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
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
|
#pragma once
#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.
*
* This is not a represent for a queue, this is only for byte sized data
* elements, like text and such.
*
* @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 size The number of items to allocate space for.
* @param free_func The function that is used to free the data.
*
* @note It is recomended to have a big size of the buffer to make room for
* each item that should be stored plus a bit extra. (if you expect to
* have \f$n\f$ items allocate \f$n + \frac{n}{2}\f$ slots.)
*/
S_EXPORTED
SRingBuffer *
s_ring_buffer_new (size_t size);
/**
* Free an SRingBuffer.
*
* @param self The SRingBuffer to free.
* @param free_data Set to @c TRUE to free the data.
*/
S_EXPORTED
void
s_ring_buffer_free (SRingBuffer * self);
/**
* determine if buffer is empty.
*/
S_EXPORTED
sboolean
s_ring_buffer_is_empty (SRingBuffer * self);
/**
* Add data to the front of the ringbuffer.
*
* @param err Set to TRUE on error, FALSE otherwise.
*/
S_EXPORTED
void
s_ring_buffer_push (SRingBuffer * self,
sbyte data,
sboolean * err);
/**
* add an item to the front of the ringbuffer.
* @param err Set to TRUE on error, FALSE otherwise.
*/
S_EXPORTED
void
s_ring_buffer_push_front (SRingBuffer * self,
subyte data,
sboolean * err);
/**
* Pop an item from the front of the array.
* @param err Set to TRUE on error, FALSE otherwise.
*/
S_EXPORTED
spointer
s_ring_buffer_pop (SRingBuffer * self,
sboolean * err);
/**
* Pop the front of the array.
* @param err Set to TRUE on error, FALSE otherwise.
*/
S_EXPORTED
spointer
s_ring_buffer_pop_front (SRingBuffer * self,
sboolean * err);
/**
* Peek at the byte at the end of the buffer.
* @param err Set to TRUE on error, FALSE otherwise.
*/
S_EXPORTED
sbyte
s_ring_buffer_peek (SRingBuffer * self,
sboolean * err);
/**
* Peek at the byte at the front of the buffer.
*
* @param err Set to TRUE on error, FALSE otherwise.
*/
S_EXPORTED
sbyte
s_ring_buffer_peek_front (SRingBuffer * self,
sboolean * err);
/**
* Reallocate an SRingBuffer to a new size for the internal array.
*
* @param self The SRingBuffer to reallocate.
* @param len The new length.
* @param err Set to TRUE on error, FALSE otherwise.
*/
S_EXPORTED
void
s_ring_buffer_realloc (SRingBuffer * self,
size_t len
sboolean * err);
/**
* Get the current length of the ring buffer.
*/
S_EXPORTED
size_t
s_ring_buffer_len (SRingBuffer * self);
/**
* Get the total size of the internal array.
*/
S_EXPORTED
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.
* @param err Set to TRUE on error, FALSE otherwise.
*
*
* @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.
*/
S_EXPORTED
void
s_ring_buffer_for_each (SRingBuffer * self,
ForEachFunc func,
spointer user_data,
sboolean * err);
/**
* @}
*/
S_END_DECLS
|