1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
|
#ifndef _H_RING_BUFFER_
#define _H_RING_BUFFER_
#include "defs.h"
#include "Func.h"
S_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>
[b|b|b|b|b|b|b|b|b|b| | | | ]
^ ^
start end
front back
[ | | | | | |b|b|b|b| | | | ]
^ ^
start end
front back
[b|b| | | | | | | |b|b|b|b|b]
^ ^
end start
back front
</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);
/**
* determine
*/
sboolean
s_ring_buffer_is_empty (SRingBuffer * self);
/**
* Add data to the front of the ringbuffer.
*
*/
void
s_ring_buffer_push (SRingBuffer * self,
sbyte data);
/**
* add an item to the back of the ringbuffer.
*/
void
s_ring_buffer_push_back (SRingBuffer * self,
sbyte data);
/**
* Pop an item from the front of the array.
*/
sbyte
s_ring_buffer_pop (SRingBuffer * self);
/**
* Pop the back of the array.
*/
sbyte
s_ring_buffer_pop_back (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);
/**
* @}
*/
S_END_DECLS
#endif /* _H_RING_BUFFER_ */
|