/simpletypesystem/trunk : contents of libssts/RingBuffer.h at revision 98

: (revision 98)

To get this branch, use:

bzr branch
http://gegoxaren.bato24.eu/bzr/simpletypesystem/trunk

#ifndef _H_RING_BUFFER_
#define _H_RING_BUFFER_

#include "defs.h"
#include "Func.h"

BEGIN_DECLS


/**
 * @file
 * @defgroup SRingBuffer SRingBuffer
 * @addtogroup SRingBuffer
 * @{
 * An SRingBuffer is a special data structure that is circular in nature.
 * It only holds bytes and as such is useful when dealing with strings and
 * other eight-bit data.
 *
 * If you are looking for a circular array, this is not
 * such a structure.
 *
 * @section Theory
 * The theory behind a circular structure is simple: Never have to deal with
 * empty slots in an array, only permit indirect, non-indexed access.
 *
 <pre>
    [_|_|_|_|_|_|_|_|_|_| | | | ]
     ^                 ^
     start             end
 </pre>
 
 <pre>
    [ | | | | | |_|_|_|_| | | | ]
                 ^     ^
             start     end
 </pre>
 
 <pre>
    [_|_| | | | | | | |_|_|_|_|_]
       ^               ^
     end             start
 </pre>
 */

/**
 * The SRingBuffer is an opaque data structure that represent an array that
 * is circular in nature.
 */
typedef struct SRingBuffer SRingBuffer;

/**
 * Create a new SRingBuffer objects.
 *
 * @param len The number of items to 
 */
SRingBuffer *
s_ring_buffer_new (size_t len);

/**
 * Free an SRingBuffer.
 *
 * @param self The SRingBuffer to free.
 */
void
s_ring_buffer_free (SRingBuffer * self);

/**
 * Add data to the SRingBuffer.
 * 
 */
void
s_ring_buffer_push (SRingBuffer * self, sbyte data);

/**
 * 
 */
void
s_ring_buffer_push_front (SRingBuffer * self, sbyte);

sbyte
s_ring_buffer_pop (SRingBuffer * self);

/**
 * 
 */
sbyte
s_ring_buffer_pop_front (SRingBuffer * self);

/**
 * Reallocate an SRingBuffer to a now size for the internal array.
 *
 * @param self The SRingBuffer to reallocate.
 * @param len The new length.
 */
void
s_ring_buffer_realloc (SRingBuffer * self, size_t len);

/**
 * Get the current length of the ring buffer.
 */
size_t
s_ring_buffer_len (SRingBuffer * self);

/**
 * Get the total size of the internal array.
 */
size_t
s_ring_buffer_size (SRingBuffer * self);

/**
 * Iterate over the bytes in the SRingBuffer.
 *
 * This is the only valid way to iterate over the bytes in an SRingBuffer.
 *
 * @param self The SRingBuffer to iterate over.
 * @param func Pointer to a function that is run on each byte.
 * @param user_data Data that is provided to the function when doing the
 *                  iteration.
 *
 * @note
 * This does not use pop or push operations, and is thus the only way to keep
 * the data and still be able to iterate over it.
 *
 * The signature of the function provided should be as follows
 @code{C}
void
my_for_each_func (SRingBuffer * buffer,
                  sbyte item,
                  spointer user_data) {
  // code here
}
 @endcode
 *
 * To prevent warnings cast the function using the @c FOREACHFUNC() macro.
 */
void
s_ring_buffer_for_each (SRingBuffer * self,
                        ForEachFunc func,
                        spointer user_data);

/**
 * @}
 */

END_DECLS

#endif /* _H_RING_BUFFER_ */

98 by Gustav Hartvigsson * Started work on SRingBuffer to be used in SStream.	1	#ifndef _H_RING_BUFFER_
	2	#define _H_RING_BUFFER_
	3
	4	#include "defs.h"
	5	#include "Func.h"
	6
	7	BEGIN_DECLS
	8
	9
	10	/**
	11	* @file
	12	* @defgroup SRingBuffer SRingBuffer
	13	* @addtogroup SRingBuffer
	14	* @{
	15	* An SRingBuffer is a special data structure that is circular in nature.
	16	* It only holds bytes and as such is useful when dealing with strings and
	17	* other eight-bit data.
	18	*
	19	* If you are looking for a circular array, this is not
	20	* such a structure.
	21	*
	22	* @section Theory
	23	* The theory behind a circular structure is simple: Never have to deal with
	24	* empty slots in an array, only permit indirect, non-indexed access.
	25	*
	26	<pre>
	27	[_\|_\|_\|_\|_\|_\|_\|_\|_\|_\| \| \| \| ]
	28	^ ^
	29	start end
	30	</pre>
	31
	32	<pre>
	33	[ \| \| \| \| \| \|_\|_\|_\|_\| \| \| \| ]
	34	^ ^
	35	start end
	36	</pre>
	37
	38	<pre>
	39	[_\|_\| \| \| \| \| \| \| \|_\|_\|_\|_\|_]
	40	^ ^
	41	end start
	42	</pre>
	43	*/
	44
	45	/**
	46	* The SRingBuffer is an opaque data structure that represent an array that
	47	* is circular in nature.
	48	*/
	49	typedef struct SRingBuffer SRingBuffer;
	50
	51	/**
	52	* Create a new SRingBuffer objects.
	53	*
	54	* @param len The number of items to
	55	*/
	56	SRingBuffer *
	57	s_ring_buffer_new (size_t len);
	58
	59	/**
	60	* Free an SRingBuffer.
	61	*
	62	* @param self The SRingBuffer to free.
	63	*/
	64	void
65	s_ring_buffer_free (SRingBuffer * self);
66
67	/**
68	* Add data to the SRingBuffer.
69	*
70	*/
71	void
72	s_ring_buffer_push (SRingBuffer * self, sbyte data);
73
74	/**
75	*
76	*/
77	void
78	s_ring_buffer_push_front (SRingBuffer * self, sbyte);
79
80	sbyte
81	s_ring_buffer_pop (SRingBuffer * self);
82
83	/**
84	*
85	*/
86	sbyte
87	s_ring_buffer_pop_front (SRingBuffer * self);
88
89	/**
90	* Reallocate an SRingBuffer to a now size for the internal array.
91	*
92	* @param self The SRingBuffer to reallocate.
93	* @param len The new length.
94	*/
95	void
96	s_ring_buffer_realloc (SRingBuffer * self, size_t len);
97
98	/**
99	* Get the current length of the ring buffer.
100	*/
101	size_t
102	s_ring_buffer_len (SRingBuffer * self);
103
104	/**
105	* Get the total size of the internal array.
106	*/
107	size_t
108	s_ring_buffer_size (SRingBuffer * self);
109
110	/**
111	* Iterate over the bytes in the SRingBuffer.
112	*
113	* This is the only valid way to iterate over the bytes in an SRingBuffer.
114	*
115	* @param self The SRingBuffer to iterate over.
116	* @param func Pointer to a function that is run on each byte.
117	* @param user_data Data that is provided to the function when doing the
118	* iteration.
119	*
120	* @note
121	* This does not use pop or push operations, and is thus the only way to keep
122	* the data and still be able to iterate over it.
123	*
124	* The signature of the function provided should be as follows
125	@code{C}
126	void
127	my_for_each_func (SRingBuffer * buffer,
128	sbyte item,
129	spointer user_data) {
130	// code here
131	}
132	@endcode
133	*
134	* To prevent warnings cast the function using the @c FOREACHFUNC() macro.
135	*/
136	void
137	s_ring_buffer_for_each (SRingBuffer * self,
138	ForEachFunc func,
139	spointer user_data);
140
141	/**
142	* @}
143	*/
144
145	END_DECLS
146
147	#endif /* _H_RING_BUFFER_ */