charring.h File Reference

Simple char ring buffer for microcontrollers. More...

#include <stdint.h>

Include dependency graph for charring.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	CharRingBuf
	Holds all data for a buffer. More...
Defines
#define	CharRing_available(B)   ((B)->count)
#define	CharRing_free_space(B)   ((B)->len - (B)->count)
#define	CharRing_full(B)   ((B)->count == (B)->len)
#define	CharRing_empty(B)   ((B)->count == 0)
Functions
CharRingBuf *	CharRing_new (int16_t)
	Allocates and returns a pointer to a new CharRingBuf buffer object.
void	CharRing_free (CharRingBuf *)
	Destroys a character ring buffer.
void	CharRing_putchar (CharRingBuf *, char)
	Writes a character to buffer.
char	CharRing_getchar (CharRingBuf *)
	Reads a character from buffer.

---

Detailed Description

Simple char ring buffer for microcontrollers.

Author:

Dan Fekete <thefekete@gmail.com>

Date:

March 10, 2015

Copyright:

Copyright 2015, Dan Fekete <thefekete@gmail.com> Released under the GNU GPL version 3

CharRing is a simple character ring/circular buffer designed for microcontrollers.

Definition in file charring.h.

---

Data Structure Documentation

struct CharRingBuf

Holds all data for a buffer.

Warning:

Don't mess with this directly, use the functions and macros to manipulate the buffers!

Definition at line 37 of file charring.h.

Data Fields
char *	buf	Pointer to buffer chars.
int16_t	count	Number of chars in buffer.
int16_t	head	Write offset.
int16_t	len	Total buffer length.
int16_t	tail	Read offset.

---

Define Documentation

#define CharRing_available

(

B

)

((B)->count)

Returns the number of available chars in CharRing buffer B

Definition at line 20 of file charring.h.

#define CharRing_empty

(

B

)

((B)->count == 0)

Returns whether CharRing buffer B is empty or not

Definition at line 29 of file charring.h.

#define CharRing_free_space

(

B

)

((B)->len - (B)->count)

Returns the number of free slots in CharRing buffer B

Definition at line 23 of file charring.h.

#define CharRing_full

(

B

)

((B)->count == (B)->len)

Returns whether CharRing buffer B is full or not

Definition at line 26 of file charring.h.

---

Function Documentation

void CharRing_free

(

CharRingBuf *

b

)

Destroys a character ring buffer.

Properly frees all memory that was allocated in the creation of CharRingBuf b.

Parameters:

b	CharRingBuf buffer to be destroyed

Definition at line 43 of file charring.c.

char CharRing_getchar

(

CharRingBuf *

b

)

Reads a character from buffer.

If there are no chars available in the buffer, this will always return '\0' (null char). But thats what CharRing_available() and CharRing_empty() are for:

  if (CharRing_available(my_buf)) {
      // do stuff
  }

  if (!CharRing_empty(my_buf)) {
      // do stuff
  }

Parameters:

b	CharRingBuf buffer to read

Returns:

Next char from buffer ('\0' if buffer empty)

Definition at line 98 of file charring.c.

Here is the caller graph for this function:

CharRingBuf* CharRing_new

(

int16_t

len

)

Allocates and returns a pointer to a new CharRingBuf buffer object.

Warning:

A call to CharRing_free() is required to properly free allocated memory.

Parameters:

len	size of buffer to be created

Returns:

a new CharRingBuf buffer struct

Definition at line 26 of file charring.c.

void CharRing_putchar	(	CharRingBuf *	b,
		char	c
	)

Writes a character to buffer.

Warning:

If the buffer is full, it will discard the oldest char in the buffer to make room.

If losing data is unacceptable then you need to check on the buffer before writing to it. CharRing_free_space() will give you the free space in the buffer and you can check to see if the buffer is full with CharRing_full():

  while (CharRing_full(my_buf));  // wait for buffer to open up

Parameters:

b	CharRingBuf buffer to write
c	character to write

Definition at line 66 of file charring.c.

Here is the call graph for this function: