comparison: src/cx/buffer.h
src/cx/buffer.h
- changeset 1024
- 8f99f6c28bd3
- parent 1016
- fe177d6dabb8
equal
deleted
inserted
replaced
| 1017:b0098854071f | 1024:8f99f6c28bd3 |
|---|---|
| 58 */ | 58 */ |
| 59 #define CX_BUFFER_DEFAULT 0x00 | 59 #define CX_BUFFER_DEFAULT 0x00 |
| 60 | 60 |
| 61 /** | 61 /** |
| 62 * If this flag is enabled, the buffer will automatically free its contents when destroyed. | 62 * If this flag is enabled, the buffer will automatically free its contents when destroyed. |
| 63 * | |
| 64 * Do NOT set this flag together with #CX_BUFFER_COPY_ON_WRITE. It will be automatically | |
| 65 * set when the copy-on-write operations is performed. | |
| 63 */ | 66 */ |
| 64 #define CX_BUFFER_FREE_CONTENTS 0x01 | 67 #define CX_BUFFER_FREE_CONTENTS 0x01 |
| 65 | 68 |
| 66 /** | 69 /** |
| 67 * If this flag is enabled, the buffer will automatically extends its capacity. | 70 * If this flag is enabled, the buffer will automatically extend its capacity. |
| 68 */ | 71 */ |
| 69 #define CX_BUFFER_AUTO_EXTEND 0x02 | 72 #define CX_BUFFER_AUTO_EXTEND 0x02 |
| 73 | |
| 74 /** | |
| 75 * If this flag is enabled, the buffer will allocate new memory when written to. | |
| 76 * | |
| 77 * The current contents of the buffer will be copied to the new memory and the flag | |
| 78 * will be cleared while the #CX_BUFFER_FREE_CONTENTS flag will be set automatically. | |
| 79 */ | |
| 80 #define CX_BUFFER_COPY_ON_WRITE 0x04 | |
| 70 | 81 |
| 71 /** Structure for the UCX buffer data. */ | 82 /** Structure for the UCX buffer data. */ |
| 72 typedef struct { | 83 typedef struct { |
| 73 /** A pointer to the buffer contents. */ | 84 /** A pointer to the buffer contents. */ |
| 74 union { | 85 union { |
| 126 /** | 137 /** |
| 127 * Flag register for buffer features. | 138 * Flag register for buffer features. |
| 128 * @see #CX_BUFFER_DEFAULT | 139 * @see #CX_BUFFER_DEFAULT |
| 129 * @see #CX_BUFFER_FREE_CONTENTS | 140 * @see #CX_BUFFER_FREE_CONTENTS |
| 130 * @see #CX_BUFFER_AUTO_EXTEND | 141 * @see #CX_BUFFER_AUTO_EXTEND |
| 142 * @see #CX_BUFFER_COPY_ON_WRITE | |
| 131 */ | 143 */ |
| 132 int flags; | 144 int flags; |
| 133 } cx_buffer_s; | 145 } cx_buffer_s; |
| 134 | 146 |
| 135 /** | 147 /** |
| 138 typedef cx_buffer_s CxBuffer; | 150 typedef cx_buffer_s CxBuffer; |
| 139 | 151 |
| 140 /** | 152 /** |
| 141 * Initializes a fresh buffer. | 153 * Initializes a fresh buffer. |
| 142 * | 154 * |
| 155 * You may also provide a read-only \p space, in which case | |
| 156 * you will need to cast the pointer, and you should set the | |
| 157 * #CX_BUFFER_COPY_ON_WRITE flag. | |
| 158 * | |
| 143 * \note You may provide \c NULL as argument for \p space. | 159 * \note You may provide \c NULL as argument for \p space. |
| 144 * Then this function will allocate the space and enforce | 160 * Then this function will allocate the space and enforce |
| 145 * the #CX_BUFFER_FREE_CONTENTS flag. | 161 * the #CX_BUFFER_FREE_CONTENTS flag. In that case, specifying |
| 162 * copy-on-write should be avoided, because the allocated | |
| 163 * space will be leaking after the copy-on-write operation. | |
| 146 * | 164 * |
| 147 * @param buffer the buffer to initialize | 165 * @param buffer the buffer to initialize |
| 148 * @param space pointer to the memory area, or \c NULL to allocate | 166 * @param space pointer to the memory area, or \c NULL to allocate |
| 149 * new memory | 167 * new memory |
| 150 * @param capacity the capacity of the buffer | 168 * @param capacity the capacity of the buffer |
| 190 void cxBufferFree(CxBuffer *buffer); | 208 void cxBufferFree(CxBuffer *buffer); |
| 191 | 209 |
| 192 /** | 210 /** |
| 193 * Allocates and initializes a fresh buffer. | 211 * Allocates and initializes a fresh buffer. |
| 194 * | 212 * |
| 213 * You may also provide a read-only \p space, in which case | |
| 214 * you will need to cast the pointer, and you should set the | |
| 215 * #CX_BUFFER_COPY_ON_WRITE flag. | |
| 216 * | |
| 195 * \note You may provide \c NULL as argument for \p space. | 217 * \note You may provide \c NULL as argument for \p space. |
| 196 * Then this function will allocate the space and enforce | 218 * Then this function will allocate the space and enforce |
| 197 * the #CX_BUFFER_FREE_CONTENTS flag. | 219 * the #CX_BUFFER_FREE_CONTENTS flag. |
| 198 * | 220 * |
| 199 * @param space pointer to the memory area, or \c NULL to allocate | 221 * @param space pointer to the memory area, or \c NULL to allocate |
| 244 * <code>memset(buffer->bytes + buffer->size, 0, buffer->capacity - buffer->size)</code> | 266 * <code>memset(buffer->bytes + buffer->size, 0, buffer->capacity - buffer->size)</code> |
| 245 * for a left shift. | 267 * for a left shift. |
| 246 * | 268 * |
| 247 * @param buffer the buffer | 269 * @param buffer the buffer |
| 248 * @param shift the shift offset (negative means left shift) | 270 * @param shift the shift offset (negative means left shift) |
| 249 * @return 0 on success, non-zero if a required auto-extension fails | 271 * @return 0 on success, non-zero if a required auto-extension or copy-on-write fails |
| 250 */ | 272 */ |
| 251 cx_attr_nonnull | 273 cx_attr_nonnull |
| 252 int cxBufferShift( | 274 int cxBufferShift( |
| 253 CxBuffer *buffer, | 275 CxBuffer *buffer, |
| 254 off_t shift | 276 off_t shift |
| 258 * Shifts the buffer to the right. | 280 * Shifts the buffer to the right. |
| 259 * See cxBufferShift() for details. | 281 * See cxBufferShift() for details. |
| 260 * | 282 * |
| 261 * @param buffer the buffer | 283 * @param buffer the buffer |
| 262 * @param shift the shift offset | 284 * @param shift the shift offset |
| 263 * @return 0 on success, non-zero if a required auto-extension fails | 285 * @return 0 on success, non-zero if a required auto-extension or copy-on-write fails |
| 264 * @see cxBufferShift() | 286 * @see cxBufferShift() |
| 265 */ | 287 */ |
| 266 cx_attr_nonnull | 288 cx_attr_nonnull |
| 267 int cxBufferShiftRight( | 289 int cxBufferShiftRight( |
| 268 CxBuffer *buffer, | 290 CxBuffer *buffer, |
| 271 | 293 |
| 272 /** | 294 /** |
| 273 * Shifts the buffer to the left. | 295 * Shifts the buffer to the left. |
| 274 * See cxBufferShift() for details. | 296 * See cxBufferShift() for details. |
| 275 * | 297 * |
| 276 * \note Since a left shift cannot fail due to memory allocation problems, this | |
| 277 * function always returns zero. | |
| 278 * | |
| 279 * @param buffer the buffer | 298 * @param buffer the buffer |
| 280 * @param shift the positive shift offset | 299 * @param shift the positive shift offset |
| 281 * @return always zero | 300 * @return usually zero, except the buffer uses copy-on-write and the allocation fails |
| 282 * @see cxBufferShift() | 301 * @see cxBufferShift() |
| 283 */ | 302 */ |
| 284 cx_attr_nonnull | 303 cx_attr_nonnull |
| 285 int cxBufferShiftLeft( | 304 int cxBufferShiftLeft( |
| 286 CxBuffer *buffer, | 305 CxBuffer *buffer, |
| 317 /** | 336 /** |
| 318 * Clears the buffer by resetting the position and deleting the data. | 337 * Clears the buffer by resetting the position and deleting the data. |
| 319 * | 338 * |
| 320 * The data is deleted by zeroing it with a call to memset(). | 339 * The data is deleted by zeroing it with a call to memset(). |
| 321 * If you do not need that, you can use the faster cxBufferReset(). | 340 * If you do not need that, you can use the faster cxBufferReset(). |
| 341 * | |
| 342 * \note If the #CX_BUFFER_COPY_ON_WRITE flag is set, this function | |
| 343 * will not erase the data and behave exactly as cxBufferReset(). | |
| 322 * | 344 * |
| 323 * @param buffer the buffer to be cleared | 345 * @param buffer the buffer to be cleared |
| 324 * @see cxBufferReset() | 346 * @see cxBufferReset() |
| 325 */ | 347 */ |
| 326 cx_attr_nonnull | 348 cx_attr_nonnull |
