88 size_t capacity; |
88 size_t capacity; |
89 /** Current size of the buffer content. */ |
89 /** Current size of the buffer content. */ |
90 size_t size; |
90 size_t size; |
91 /** |
91 /** |
92 * Flag register for buffer features. |
92 * Flag register for buffer features. |
93 * \see #CX_BUFFER_DEFAULT |
93 * @see #CX_BUFFER_DEFAULT |
94 * \see #CX_BUFFER_FREE_CONTENTS |
94 * @see #CX_BUFFER_FREE_CONTENTS |
95 * \see #CX_BUFFER_AUTO_EXTEND |
95 * @see #CX_BUFFER_AUTO_EXTEND |
96 */ |
96 */ |
97 int flags; |
97 int flags; |
98 } cx_buffer_s; |
98 } cx_buffer_s; |
99 |
99 |
100 /** |
100 /** |
107 * |
107 * |
108 * \note You may provide \c NULL as argument for \p space. |
108 * \note You may provide \c NULL as argument for \p space. |
109 * Then this function will allocate the space and enforce |
109 * Then this function will allocate the space and enforce |
110 * the #CX_BUFFER_FREE_CONTENTS flag. |
110 * the #CX_BUFFER_FREE_CONTENTS flag. |
111 * |
111 * |
112 * \param space pointer to the memory area, or <code>NULL</code> to allocate |
112 * @param space pointer to the memory area, or <code>NULL</code> to allocate |
113 * new memory |
113 * new memory |
114 * \param capacity the capacity of the buffer |
114 * @param capacity the capacity of the buffer |
115 * \param flags buffer features (see cx_buffer_s.flags) |
115 * @param flags buffer features (see cx_buffer_s.flags) |
116 * \return the new buffer |
116 * @return the new buffer |
117 */ |
117 */ |
118 CxBuffer cxBufferCreate( |
118 CxBuffer cxBufferCreate( |
119 void *space, |
119 void *space, |
120 size_t capacity, |
120 size_t capacity, |
121 int flags |
121 int flags |
125 * Destroys a buffer. |
125 * Destroys a buffer. |
126 * |
126 * |
127 * If the #CX_BUFFER_FREE_CONTENTS feature is enabled, the contents of the buffer |
127 * If the #CX_BUFFER_FREE_CONTENTS feature is enabled, the contents of the buffer |
128 * are also freed. |
128 * are also freed. |
129 * |
129 * |
130 * \param buffer the buffer to destroy |
130 * @param buffer the buffer to destroy |
131 */ |
131 */ |
132 void cxBufferDestroy(CxBuffer buffer); |
132 void cxBufferDestroy(CxBuffer buffer); |
133 |
133 |
134 /** |
134 /** |
135 * Creates a new buffer and fills it with content copied from another buffer. |
135 * Creates a new buffer and fills it with content copied from another buffer. |
136 * |
136 * |
137 * \note The #CX_BUFFER_FREE_CONTENTS feature is enforced for the new buffer. |
137 * \note The #CX_BUFFER_FREE_CONTENTS feature is enforced for the new buffer. |
138 * |
138 * |
139 * \param src the source buffer |
139 * @param src the source buffer |
140 * \param start the start position of extraction |
140 * @param start the start position of extraction |
141 * \param length the count of bytes to extract (must not be zero) |
141 * @param length the count of bytes to extract (must not be zero) |
142 * \param flags features for the new buffer (#CX_BUFFER_FREE_CONTENTS will always be enabled) |
142 * @param flags features for the new buffer (#CX_BUFFER_FREE_CONTENTS will always be enabled) |
143 * \return a new buffer containing the extraction |
143 * @return a new buffer containing the extraction |
144 */ |
144 */ |
145 CxBuffer cxBufferExtract( |
145 CxBuffer cxBufferExtract( |
146 CxBuffer src, |
146 CxBuffer src, |
147 size_t start, |
147 size_t start, |
148 size_t length, |
148 size_t length, |
150 ); |
150 ); |
151 |
151 |
152 /** |
152 /** |
153 * A shorthand macro for copying an entire buffer. |
153 * A shorthand macro for copying an entire buffer. |
154 * |
154 * |
155 * \param src the source buffer |
155 * @param src the source buffer |
156 * \param flags features for the new buffer (#CX_BUFFER_FREE_CONTENTS will always be enabled) |
156 * @param flags features for the new buffer (#CX_BUFFER_FREE_CONTENTS will always be enabled) |
157 * \return a new buffer with the copied content |
157 * @return a new buffer with the copied content |
158 */ |
158 */ |
159 #define cxBufferClone(src, flags) cxBufferExtract(src, 0, (src)->capacity, flags) |
159 #define cxBufferClone(src, flags) cxBufferExtract(src, 0, (src)->capacity, flags) |
160 |
160 |
161 |
161 |
162 /** |
162 /** |
179 * within the boundaries of the buffer. |
179 * within the boundaries of the buffer. |
180 * |
180 * |
181 * \note For situations where \c off_t is not large enough, there are specialized cxBufferShiftLeft() and |
181 * \note For situations where \c off_t is not large enough, there are specialized cxBufferShiftLeft() and |
182 * cxBufferShiftRight() functions using a \c size_t as parameter type. |
182 * cxBufferShiftRight() functions using a \c size_t as parameter type. |
183 * |
183 * |
184 * \par Security Note |
184 * \attention |
185 * The shifting operation does \em not erase the previously occupied memory cells. |
185 * Security Note: The shifting operation does \em not erase the previously occupied memory cells. |
186 * You can easily do that manually, e.g. by calling |
186 * But you can easily do that manually, e.g. by calling |
187 * <code>memset(buffer->bytes, 0, shift)</code> for a right shift or |
187 * <code>memset(buffer->bytes, 0, shift)</code> for a right shift or |
188 * <code>memset(buffer->size, 0, buffer->capacity - buffer->size)</code> |
188 * <code>memset(buffer->size, 0, buffer->capacity - buffer->size)</code> |
189 * for a left shift. |
189 * for a left shift. |
190 * |
190 * |
191 * \param buffer the buffer |
191 * @param buffer the buffer |
192 * \param shift the shift offset (negative means left shift) |
192 * @param shift the shift offset (negative means left shift) |
193 * \return 0 on success, non-zero if a required auto-extension fails |
193 * @return 0 on success, non-zero if a required auto-extension fails |
194 */ |
194 */ |
195 int cxBufferShift( |
195 int cxBufferShift( |
196 CxBuffer buffer, |
196 CxBuffer buffer, |
197 off_t shift |
197 off_t shift |
198 ); |
198 ); |
199 |
199 |
200 /** |
200 /** |
201 * Shifts the buffer to the right. |
201 * Shifts the buffer to the right. |
202 * See cxBufferShift() for details. |
202 * See cxBufferShift() for details. |
203 * |
203 * |
204 * \param buffer the buffer |
204 * @param buffer the buffer |
205 * \param shift the shift offset |
205 * @param shift the shift offset |
206 * \return 0 on success, non-zero if a required auto-extension fails |
206 * @return 0 on success, non-zero if a required auto-extension fails |
207 * \see cxBufferShift() |
207 * @see cxBufferShift() |
208 */ |
208 */ |
209 int cxBufferShiftRight( |
209 int cxBufferShiftRight( |
210 CxBuffer buffer, |
210 CxBuffer buffer, |
211 size_t shift |
211 size_t shift |
212 ); |
212 ); |
216 * See cxBufferShift() for details. |
216 * See cxBufferShift() for details. |
217 * |
217 * |
218 * \note Since a left shift cannot fail due to memory allocation problems, this |
218 * \note Since a left shift cannot fail due to memory allocation problems, this |
219 * function always returns zero. |
219 * function always returns zero. |
220 * |
220 * |
221 * \param buffer the buffer |
221 * @param buffer the buffer |
222 * \param shift the positive shift offset |
222 * @param shift the positive shift offset |
223 * \return always zero |
223 * @return always zero |
224 * \see cxBufferShift() |
224 * @see cxBufferShift() |
225 */ |
225 */ |
226 int cxBufferShiftLeft( |
226 int cxBufferShiftLeft( |
227 CxBuffer buffer, |
227 CxBuffer buffer, |
228 size_t shift |
228 size_t shift |
229 ); |
229 ); |
240 * |
240 * |
241 * With an offset of zero, this function sets the buffer position to zero |
241 * With an offset of zero, this function sets the buffer position to zero |
242 * (\c SEEK_SET), the buffer size (\c SEEK_END) or leaves the buffer position |
242 * (\c SEEK_SET), the buffer size (\c SEEK_END) or leaves the buffer position |
243 * unchanged (\c SEEK_CUR). |
243 * unchanged (\c SEEK_CUR). |
244 * |
244 * |
245 * \param buffer the buffer |
245 * @param buffer the buffer |
246 * \param offset position offset relative to \p whence |
246 * @param offset position offset relative to \p whence |
247 * \param whence one of \c SEEK_SET, \c SEEK_CUR or \c SEEK_END |
247 * @param whence one of \c SEEK_SET, \c SEEK_CUR or \c SEEK_END |
248 * \return 0 on success, non-zero if the position is invalid |
248 * @return 0 on success, non-zero if the position is invalid |
249 * |
249 * |
250 */ |
250 */ |
251 int cxBufferSeek( |
251 int cxBufferSeek( |
252 CxBuffer buffer, |
252 CxBuffer buffer, |
253 off_t offset, |
253 off_t offset, |
257 /** |
257 /** |
258 * Clears the buffer by resetting the position and deleting the data. |
258 * Clears the buffer by resetting the position and deleting the data. |
259 * |
259 * |
260 * The data is deleted by zeroing it with a call to memset(). |
260 * The data is deleted by zeroing it with a call to memset(). |
261 * |
261 * |
262 * \param buffer the buffer to be cleared |
262 * @param buffer the buffer to be cleared |
263 */ |
263 */ |
264 #define cxBufferClear(buffer) memset((buffer)->bytes, 0, (buffer)->size); \ |
264 #define cxBufferClear(buffer) memset((buffer)->bytes, 0, (buffer)->size); \ |
265 (buffer)->size = 0; (buffer)->pos = 0; |
265 (buffer)->size = 0; (buffer)->pos = 0; |
266 |
266 |
267 /** |
267 /** |
268 * Tests, if the buffer position has exceeded the buffer capacity. |
268 * Tests, if the buffer position has exceeded the buffer capacity. |
269 * |
269 * |
270 * \param buffer the buffer to test |
270 * @param buffer the buffer to test |
271 * \return non-zero, if the current buffer position has exceeded the last |
271 * @return non-zero, if the current buffer position has exceeded the last |
272 * available byte of the buffer. |
272 * available byte of the buffer. |
273 */ |
273 */ |
274 int cxBufferEof(CxBuffer buffer); |
274 int cxBufferEof(CxBuffer buffer); |
275 |
275 |
276 |
276 |
277 /** |
277 /** |
278 * Ensures that the buffer has a minimum capacity. |
278 * Ensures that the buffer has a minimum capacity. |
279 * |
279 * |
280 * If the current capacity is not sufficient, the buffer will be extended. |
280 * If the current capacity is not sufficient, the buffer will be extended. |
281 * |
281 * |
282 * \param buffer the buffer |
282 * @param buffer the buffer |
283 * \param capacity the minimum required capacity for this buffer |
283 * @param capacity the minimum required capacity for this buffer |
284 * \return 0 on success or a non-zero value on failure |
284 * @return 0 on success or a non-zero value on failure |
285 */ |
285 */ |
286 int cxBufferMinimumCapacity( |
286 int cxBufferMinimumCapacity( |
287 CxBuffer buffer, |
287 CxBuffer buffer, |
288 size_t capacity |
288 size_t capacity |
289 ); |
289 ); |
293 * |
293 * |
294 * The position of the buffer is increased by the number of bytes written. |
294 * The position of the buffer is increased by the number of bytes written. |
295 * |
295 * |
296 * \note The signature is compatible with the fwrite() family of functions. |
296 * \note The signature is compatible with the fwrite() family of functions. |
297 * |
297 * |
298 * \param ptr a pointer to the memory area containing the bytes to be written |
298 * @param ptr a pointer to the memory area containing the bytes to be written |
299 * \param size the length of one element |
299 * @param size the length of one element |
300 * \param nitems the element count |
300 * @param nitems the element count |
301 * \param buffer the CxBuffer to write to |
301 * @param buffer the CxBuffer to write to |
302 * \return the total count of bytes written |
302 * @return the total count of bytes written |
303 */ |
303 */ |
304 size_t cxBufferWrite( |
304 size_t cxBufferWrite( |
305 const void *ptr, |
305 const void *ptr, |
306 size_t size, |
306 size_t size, |
307 size_t nitems, |
307 size_t nitems, |
313 * |
313 * |
314 * The position of the buffer is increased by the number of bytes read. |
314 * The position of the buffer is increased by the number of bytes read. |
315 * |
315 * |
316 * \note The signature is compatible with the fread() family of functions. |
316 * \note The signature is compatible with the fread() family of functions. |
317 * |
317 * |
318 * \param ptr a pointer to the memory area where to store the read data |
318 * @param ptr a pointer to the memory area where to store the read data |
319 * \param size the length of one element |
319 * @param size the length of one element |
320 * \param nitems the element count |
320 * @param nitems the element count |
321 * \param buffer the CxBuffer to read from |
321 * @param buffer the CxBuffer to read from |
322 * \return the total number of elements read |
322 * @return the total number of elements read |
323 */ |
323 */ |
324 size_t cxBufferRead( |
324 size_t cxBufferRead( |
325 void *ptr, |
325 void *ptr, |
326 size_t size, |
326 size_t size, |
327 size_t nitems, |
327 size_t nitems, |
336 * the buffer capacity is extended by cxBufferMinimumCapacity(). If the feature is |
336 * the buffer capacity is extended by cxBufferMinimumCapacity(). If the feature is |
337 * disabled or buffer extension fails, \c EOF is returned. |
337 * disabled or buffer extension fails, \c EOF is returned. |
338 * |
338 * |
339 * On successful write, the position of the buffer is increased. |
339 * On successful write, the position of the buffer is increased. |
340 * |
340 * |
341 * \param buffer the buffer to write to |
341 * @param buffer the buffer to write to |
342 * \param c the character to write |
342 * @param c the character to write |
343 * \return the byte that has bean written or \c EOF when the end of the stream is |
343 * @return the byte that has bean written or \c EOF when the end of the stream is |
344 * reached and automatic extension is not enabled or not possible |
344 * reached and automatic extension is not enabled or not possible |
345 */ |
345 */ |
346 int cxBufferPut( |
346 int cxBufferPut( |
347 CxBuffer buffer, |
347 CxBuffer buffer, |
348 int c |
348 int c |
351 /** |
351 /** |
352 * Gets a character from a buffer. |
352 * Gets a character from a buffer. |
353 * |
353 * |
354 * The current position of the buffer is increased after a successful read. |
354 * The current position of the buffer is increased after a successful read. |
355 * |
355 * |
356 * \param buffer the buffer to read from |
356 * @param buffer the buffer to read from |
357 * \return the character or \c EOF, if the end of the buffer is reached |
357 * @return the character or \c EOF, if the end of the buffer is reached |
358 */ |
358 */ |
359 int cxBufferGet(CxBuffer buffer); |
359 int cxBufferGet(CxBuffer buffer); |
360 |
360 |
361 /** |
361 /** |
362 * Writes a string to a buffer. |
362 * Writes a string to a buffer. |
363 * |
363 * |
364 * \param buffer the buffer |
364 * @param buffer the buffer |
365 * \param str the zero-terminated string |
365 * @param str the zero-terminated string |
366 * \return the number of bytes written |
366 * @return the number of bytes written |
367 */ |
367 */ |
368 size_t cxBufferPutString( |
368 size_t cxBufferPutString( |
369 CxBuffer buffer, |
369 CxBuffer buffer, |
370 const char *str |
370 const char *str |
371 ); |
371 ); |