Mercurial > hg > ucx / file comparison

comparison: src/cx/buffer.h

src/cx/buffer.h

changeset 483
929016224c3c
child 484
9e6900b1cf9d
equal deleted inserted replaced
482:0d998f19d130 483:929016224c3c
1 /*
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3 *
4 * Copyright 2021 Mike Becker, Olaf Wintermann All rights reserved.
5 *
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions are met:
8 *
9 * 1. Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * 2. Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26 * POSSIBILITY OF SUCH DAMAGE.
27 */
28
29 /**
30 * \file buffer.h
31 *
32 * \brief Advanced buffer implementation.
33 *
34 * Instances of CxBuffer can be used to read from or to write to like one
35 * would do with a stream.
36 *
37 * Some features for convenient use of the buffer
38 * can be enabled. See the documentation of the macro constants for more
39 * information.
40 *
41 * \author Mike Becker
42 * \author Olaf Wintermann
43 * \version 3.0
44 * \copyright 2-Clause BSD License
45 */
46
47 #ifndef UCX_BUFFER_H
48 #define UCX_BUFFER_H
49
50 #include <sys/types.h>
51 #include <stdio.h>
52
53 #ifdef __cplusplus
54 extern "C" {
55 #endif
56
57 /**
58 * No buffer features enabled (all flags cleared).
59 */
60 #define CX_BUFFER_DEFAULT 0x00
61
62 /**
63 * If this flag is enabled, the buffer will automatically free its contents when destroyed.
64 */
65 #define CX_BUFFER_FREE_CONTENTS 0x01
66
67 /**
68 * If this flag is enabled, the buffer will automatically extends its capacity.
69 */
70 #define CX_BUFFER_AUTO_EXTEND 0x02
71
72 /** Structure for the UCX buffer data. */
73 typedef struct {
74 /** A pointer to the buffer contents. */
75 union {
76 /**
77 * Data is interpreted as text.
78 */
79 char *space;
80 /**
81 * Data is interpreted as binary.
82 */
83 unsigned char *bytes;
84 };
85 /** Current position of the buffer. */
86 size_t pos;
87 /** Current capacity (i.e. maximum size) of the buffer. */
88 size_t capacity;
89 /** Current size of the buffer content. */
90 size_t size;
91 /**
92 * Flag register for buffer features.
93 * \see #CX_BUFFER_DEFAULT
94 * \see #CX_BUFFER_FREE_CONTENTS
95 * \see #CX_BUFFER_AUTO_EXTEND
96 */
97 int flags;
98 } cx_buffer_s;
99
100 /**
101 * UCX buffer.
102 */
103 typedef cx_buffer_s *CxBuffer;
104
105 /**
106 * Creates a new buffer.
107 *
108 * \note You may provide \c NULL as argument for \p space.
109 * Then this function will allocate the space and enforce
110 * the #CX_BUFFER_FREE_CONTENTS flag.
111 *
112 * \param space pointer to the memory area, or <code>NULL</code> to allocate
113 * new memory
114 * \param capacity the capacity of the buffer
115 * \param flags buffer features (see cx_buffer_s.flags)
116 * \return the new buffer
117 */
118 CxBuffer cxBufferCreate(
119 void *space,
120 size_t capacity,
121 int flags
122 );
123
124 /**
125 * Destroys a buffer.
126 *
127 * If the #CX_BUFFER_FREE_CONTENTS feature is enabled, the contents of the buffer
128 * are also freed.
129 *
130 * \param buffer the buffer to destroy
131 */
132 void cxBufferDestroy(CxBuffer buffer);
133
134 /**
135 * Creates a new buffer and fills it with content copied from another buffer.
136 *
137 * \note The #CX_BUFFER_FREE_CONTENTS feature is enforced for the new buffer.
138 *
139 * \param src the source buffer
140 * \param start the start position of extraction
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)
143 * \return a new buffer containing the extraction
144 */
145 CxBuffer cxBufferExtract(
146 CxBuffer src,
147 size_t start,
148 size_t length,
149 int flags
150 );
151
152 /**
153 * A shorthand macro for copying an entire buffer.
154 *
155 * \param src the source buffer
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
158 */
159 #define cxBufferClone(src, flags) cxBufferExtract(src, 0, (src)->capacity, flags)
160
161
162 /**
163 * Shifts the contents of the buffer by the given offset.
164 *
165 * If the offset is positive, the contents are shifted to the right.
166 * If auto extension is enabled, the buffer grows, if necessary.
167 * In case the auto extension fails, this function returns a non-zero value and
168 * no contents are changed.
169 * If auto extension is disabled, the contents that do not fit into the buffer
170 * are discarded.
171 *
172 * If the offset is negative, the contents are shifted to the left where the
173 * first \p shift bytes are discarded.
174 * The new size of the buffer is the old size minus the absolute shift value.
175 * If this value is larger than the buffer size, the buffer is emptied (but
176 * not cleared, see the security note below).
177 *
178 * The buffer position gets shifted alongside with the content but is kept
179 * within the boundaries of the buffer.
180 *
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.
183 *
184 * \par Security Note
185 * The shifting operation does \em not erase the previously occupied memory cells.
186 * You can easily do that manually, e.g. by calling
187 * <code>memset(buffer->bytes, 0, shift)</code> for a right shift or
188 * <code>memset(buffer->size, 0, buffer->capacity - buffer->size)</code>
189 * for a left shift.
190 *
191 * \param buffer the buffer
192 * \param shift the shift offset (negative means left shift)
193 * \return 0 on success, non-zero if a required auto-extension fails
194 */
195 int cxBufferShift(
196 CxBuffer buffer,
197 off_t shift
198 );
199
200 /**
201 * Shifts the buffer to the right.
202 * See cxBufferShift() for details.
203 *
204 * \param buffer the buffer
205 * \param shift the shift offset
206 * \return 0 on success, non-zero if a required auto-extension fails
207 * \see cxBufferShift()
208 */
209 int cxBufferShiftRight(
210 CxBuffer buffer,
211 size_t shift
212 );
213
214 /**
215 * Shifts the buffer to the left.
216 * See cxBufferShift() for details.
217 *
218 * \note Since a left shift cannot fail due to memory allocation problems, this
219 * function always returns zero.
220 *
221 * \param buffer the buffer
222 * \param shift the positive shift offset
223 * \return always zero
224 * \see cxBufferShift()
225 */
226 int cxBufferShiftLeft(
227 CxBuffer buffer,
228 size_t shift
229 );
230
231
232 /**
233 * Moves the position of the buffer.
234 *
235 * The new position is relative to the \p whence argument.
236 *
237 * \li \c SEEK_SET marks the start of the buffer.
238 * \li \c SEEK_CUR marks the current position.
239 * \li \c SEEK_END marks the end of the buffer.
240 *
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
243 * unchanged (\c SEEK_CUR).
244 *
245 * \param buffer the buffer
246 * \param offset position offset relative to \p whence
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
249 *
250 */
251 int cxBufferSeek(
252 CxBuffer buffer,
253 off_t offset,
254 int whence
255 );
256
257 /**
258 * Clears the buffer by resetting the position and deleting the data.
259 *
260 * The data is deleted by zeroing it with a call to memset().
261 *
262 * \param buffer the buffer to be cleared
263 */
264 #define cxBufferClear(buffer) memset((buffer)->bytes, 0, (buffer)->size); \
265 (buffer)->size = 0; (buffer)->pos = 0;
266
267 /**
268 * Tests, if the buffer position has exceeded the buffer capacity.
269 *
270 * \param buffer the buffer to test
271 * \return non-zero, if the current buffer position has exceeded the last
272 * available byte of the buffer.
273 */
274 int cxBufferEof(CxBuffer buffer);
275
276
277 /**
278 * Ensures that the buffer has a minimum capacity.
279 *
280 * If the current capacity is not sufficient, the buffer will be extended.
281 *
282 * \param buffer the buffer
283 * \param capacity the minimum required capacity for this buffer
284 * \return 0 on success or a non-zero value on failure
285 */
286 int cxBufferMinimumCapacity(
287 CxBuffer buffer,
288 size_t capacity
289 );
290
291 /**
292 * Writes data to a CxBuffer.
293 *
294 * The position of the buffer is increased by the number of bytes written.
295 *
296 * \note The signature is compatible with the fwrite() family of functions.
297 *
298 * \param ptr a pointer to the memory area containing the bytes to be written
299 * \param size the length of one element
300 * \param nitems the element count
301 * \param buffer the CxBuffer to write to
302 * \return the total count of bytes written
303 */
304 size_t cxBufferWrite(
305 const void *ptr,
306 size_t size,
307 size_t nitems,
308 CxBuffer buffer
309 );
310
311 /**
312 * Reads data from a CxBuffer.
313 *
314 * The position of the buffer is increased by the number of bytes read.
315 *
316 * \note The signature is compatible with the fread() family of functions.
317 *
318 * \param ptr a pointer to the memory area where to store the read data
319 * \param size the length of one element
320 * \param nitems the element count
321 * \param buffer the CxBuffer to read from
322 * \return the total number of elements read
323 */
324 size_t cxBufferRead(
325 void *ptr,
326 size_t size,
327 size_t nitems,
328 CxBuffer buffer
329 );
330
331 /**
332 * Writes a character to a buffer.
333 *
334 * The least significant byte of the argument is written to the buffer. If the
335 * end of the buffer is reached and #CX_BUFFER_AUTO_EXTEND feature is enabled,
336 * the buffer capacity is extended by cxBufferMinimumCapacity(). If the feature is
337 * disabled or buffer extension fails, \c EOF is returned.
338 *
339 * On successful write, the position of the buffer is increased.
340 *
341 * \param buffer the buffer to write to
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
344 * reached and automatic extension is not enabled or not possible
345 */
346 int cxBufferPut(
347 CxBuffer buffer,
348 int c
349 );
350
351 /**
352 * Gets a character from a buffer.
353 *
354 * The current position of the buffer is increased after a successful read.
355 *
356 * \param buffer the buffer to read from
357 * \return the character or \c EOF, if the end of the buffer is reached
358 */
359 int cxBufferGet(CxBuffer buffer);
360
361 /**
362 * Writes a string to a buffer.
363 *
364 * \param buffer the buffer
365 * \param str the zero-terminated string
366 * \return the number of bytes written
367 */
368 size_t cxBufferPutString(
369 CxBuffer buffer,
370 const char *str
371 );
372
373 #ifdef __cplusplus
374 }
375 #endif
376
377 #endif /* UCX_BUFFER_H */

Mercurial Repository: ucx

mercurial