225 * (if @c NULL, the cxDefaultAllocator will be used) |
225 * (if @c NULL, the cxDefaultAllocator will be used) |
226 * @param flags buffer features (see cx_buffer_s.flags) |
226 * @param flags buffer features (see cx_buffer_s.flags) |
227 * @return zero on success, non-zero if a required allocation failed |
227 * @return zero on success, non-zero if a required allocation failed |
228 */ |
228 */ |
229 cx_attr_nonnull_arg(1) |
229 cx_attr_nonnull_arg(1) |
230 cx_attr_export |
230 CX_EXPORT int cxBufferInit(CxBuffer *buffer, void *space, size_t capacity, |
231 int cxBufferInit( |
231 const CxAllocator *allocator, int flags); |
232 CxBuffer *buffer, |
|
233 void *space, |
|
234 size_t capacity, |
|
235 const CxAllocator *allocator, |
|
236 int flags |
|
237 ); |
|
238 |
232 |
239 /** |
233 /** |
240 * Configures the buffer for flushing. |
234 * Configures the buffer for flushing. |
241 * |
235 * |
242 * Flushing can happen automatically when data is written |
236 * Flushing can happen automatically when data is written |
249 * @retval non-zero failure |
243 * @retval non-zero failure |
250 * @see cxBufferFlush() |
244 * @see cxBufferFlush() |
251 * @see cxBufferWrite() |
245 * @see cxBufferWrite() |
252 */ |
246 */ |
253 cx_attr_nonnull |
247 cx_attr_nonnull |
254 cx_attr_export |
248 CX_EXPORT int cxBufferEnableFlushing(CxBuffer *buffer, CxBufferFlushConfig config); |
255 int cxBufferEnableFlushing( |
|
256 CxBuffer *buffer, |
|
257 CxBufferFlushConfig config |
|
258 ); |
|
259 |
249 |
260 /** |
250 /** |
261 * Destroys the buffer contents. |
251 * Destroys the buffer contents. |
262 * |
252 * |
263 * Has no effect if the #CX_BUFFER_FREE_CONTENTS feature is not enabled. |
253 * Has no effect if the #CX_BUFFER_FREE_CONTENTS feature is not enabled. |
265 * |
255 * |
266 * @param buffer the buffer which contents shall be destroyed |
256 * @param buffer the buffer which contents shall be destroyed |
267 * @see cxBufferInit() |
257 * @see cxBufferInit() |
268 */ |
258 */ |
269 cx_attr_nonnull |
259 cx_attr_nonnull |
270 cx_attr_export |
260 CX_EXPORT void cxBufferDestroy(CxBuffer *buffer); |
271 void cxBufferDestroy(CxBuffer *buffer); |
|
272 |
261 |
273 /** |
262 /** |
274 * Deallocates the buffer. |
263 * Deallocates the buffer. |
275 * |
264 * |
276 * If the #CX_BUFFER_FREE_CONTENTS feature is enabled, this function also destroys |
265 * If the #CX_BUFFER_FREE_CONTENTS feature is enabled, this function also destroys |
277 * the contents. If you @em only want to destroy the contents, use cxBufferDestroy(). |
266 * the contents. If you @em only want to destroy the contents, use cxBufferDestroy(). |
278 * |
267 * |
279 * @param buffer the buffer to deallocate |
268 * @param buffer the buffer to deallocate |
280 * @see cxBufferCreate() |
269 * @see cxBufferCreate() |
281 */ |
270 */ |
282 cx_attr_export |
271 CX_EXPORT void cxBufferFree(CxBuffer *buffer); |
283 void cxBufferFree(CxBuffer *buffer); |
|
284 |
272 |
285 /** |
273 /** |
286 * Allocates and initializes a fresh buffer. |
274 * Allocates and initializes a fresh buffer. |
287 * |
275 * |
288 * You may also provide a read-only @p space, in which case |
276 * You may also provide a read-only @p space, in which case |
304 * memory management within the buffer |
292 * memory management within the buffer |
305 * (if @c NULL, the cxDefaultAllocator will be used) |
293 * (if @c NULL, the cxDefaultAllocator will be used) |
306 * @param flags buffer features (see cx_buffer_s.flags) |
294 * @param flags buffer features (see cx_buffer_s.flags) |
307 * @return a pointer to the buffer on success, @c NULL if a required allocation failed |
295 * @return a pointer to the buffer on success, @c NULL if a required allocation failed |
308 */ |
296 */ |
309 cx_attr_malloc |
297 cx_attr_malloc cx_attr_dealloc(cxBufferFree, 1) cx_attr_nodiscard |
310 cx_attr_dealloc(cxBufferFree, 1) |
298 CX_EXPORT CxBuffer *cxBufferCreate(void *space, size_t capacity, |
311 cx_attr_nodiscard |
299 const CxAllocator *allocator, int flags); |
312 cx_attr_export |
|
313 CxBuffer *cxBufferCreate( |
|
314 void *space, |
|
315 size_t capacity, |
|
316 const CxAllocator *allocator, |
|
317 int flags |
|
318 ); |
|
319 |
300 |
320 /** |
301 /** |
321 * Shifts the contents of the buffer by the given offset. |
302 * Shifts the contents of the buffer by the given offset. |
322 * |
303 * |
323 * If the offset is positive, the contents are shifted to the right. |
304 * If the offset is positive, the contents are shifted to the right. |
352 * @retval non-zero if a required auto-extension or copy-on-write fails |
333 * @retval non-zero if a required auto-extension or copy-on-write fails |
353 * @see cxBufferShiftLeft() |
334 * @see cxBufferShiftLeft() |
354 * @see cxBufferShiftRight() |
335 * @see cxBufferShiftRight() |
355 */ |
336 */ |
356 cx_attr_nonnull |
337 cx_attr_nonnull |
357 cx_attr_export |
338 CX_EXPORT int cxBufferShift(CxBuffer *buffer, off_t shift); |
358 int cxBufferShift( |
|
359 CxBuffer *buffer, |
|
360 off_t shift |
|
361 ); |
|
362 |
339 |
363 /** |
340 /** |
364 * Shifts the buffer to the right. |
341 * Shifts the buffer to the right. |
365 * See cxBufferShift() for details. |
342 * See cxBufferShift() for details. |
366 * |
343 * |
369 * @retval zero success |
346 * @retval zero success |
370 * @retval non-zero if a required auto-extension or copy-on-write fails |
347 * @retval non-zero if a required auto-extension or copy-on-write fails |
371 * @see cxBufferShift() |
348 * @see cxBufferShift() |
372 */ |
349 */ |
373 cx_attr_nonnull |
350 cx_attr_nonnull |
374 cx_attr_export |
351 CX_EXPORT int cxBufferShiftRight(CxBuffer *buffer, size_t shift); |
375 int cxBufferShiftRight( |
|
376 CxBuffer *buffer, |
|
377 size_t shift |
|
378 ); |
|
379 |
352 |
380 /** |
353 /** |
381 * Shifts the buffer to the left. |
354 * Shifts the buffer to the left. |
382 * See cxBufferShift() for details. |
355 * See cxBufferShift() for details. |
383 * |
356 * |
386 * @retval zero success |
359 * @retval zero success |
387 * @retval non-zero if the buffer uses copy-on-write and the allocation fails |
360 * @retval non-zero if the buffer uses copy-on-write and the allocation fails |
388 * @see cxBufferShift() |
361 * @see cxBufferShift() |
389 */ |
362 */ |
390 cx_attr_nonnull |
363 cx_attr_nonnull |
391 cx_attr_export |
364 CX_EXPORT int cxBufferShiftLeft(CxBuffer *buffer, size_t shift); |
392 int cxBufferShiftLeft( |
|
393 CxBuffer *buffer, |
|
394 size_t shift |
|
395 ); |
|
396 |
365 |
397 |
366 |
398 /** |
367 /** |
399 * Moves the position of the buffer. |
368 * Moves the position of the buffer. |
400 * |
369 * |
414 * @retval zero success |
383 * @retval zero success |
415 * @retval non-zero if the position is invalid |
384 * @retval non-zero if the position is invalid |
416 * |
385 * |
417 */ |
386 */ |
418 cx_attr_nonnull |
387 cx_attr_nonnull |
419 cx_attr_export |
388 CX_EXPORT int cxBufferSeek(CxBuffer *buffer, off_t offset, int whence); |
420 int cxBufferSeek( |
|
421 CxBuffer *buffer, |
|
422 off_t offset, |
|
423 int whence |
|
424 ); |
|
425 |
389 |
426 /** |
390 /** |
427 * Clears the buffer by resetting the position and deleting the data. |
391 * Clears the buffer by resetting the position and deleting the data. |
428 * |
392 * |
429 * The data is deleted by zeroing it with a call to memset(). |
393 * The data is deleted by zeroing it with a call to memset(). |
434 * |
398 * |
435 * @param buffer the buffer to be cleared |
399 * @param buffer the buffer to be cleared |
436 * @see cxBufferReset() |
400 * @see cxBufferReset() |
437 */ |
401 */ |
438 cx_attr_nonnull |
402 cx_attr_nonnull |
439 cx_attr_export |
403 CX_EXPORT void cxBufferClear(CxBuffer *buffer); |
440 void cxBufferClear(CxBuffer *buffer); |
|
441 |
404 |
442 /** |
405 /** |
443 * Resets the buffer by resetting the position and size to zero. |
406 * Resets the buffer by resetting the position and size to zero. |
444 * |
407 * |
445 * The data in the buffer is not deleted. If you need a safe |
408 * The data in the buffer is not deleted. If you need a safe |
447 * |
410 * |
448 * @param buffer the buffer to be cleared |
411 * @param buffer the buffer to be cleared |
449 * @see cxBufferClear() |
412 * @see cxBufferClear() |
450 */ |
413 */ |
451 cx_attr_nonnull |
414 cx_attr_nonnull |
452 cx_attr_export |
415 CX_EXPORT void cxBufferReset(CxBuffer *buffer); |
453 void cxBufferReset(CxBuffer *buffer); |
|
454 |
416 |
455 /** |
417 /** |
456 * Tests, if the buffer position has exceeded the buffer size. |
418 * Tests, if the buffer position has exceeded the buffer size. |
457 * |
419 * |
458 * @param buffer the buffer to test |
420 * @param buffer the buffer to test |
459 * @retval true if the current buffer position has exceeded the last |
421 * @retval true if the current buffer position has exceeded the last |
460 * byte of the buffer's contents |
422 * byte of the buffer's contents |
461 * @retval false otherwise |
423 * @retval false otherwise |
462 */ |
424 */ |
463 cx_attr_nonnull |
425 cx_attr_nonnull cx_attr_nodiscard |
464 cx_attr_nodiscard |
426 CX_EXPORT bool cxBufferEof(const CxBuffer *buffer); |
465 cx_attr_export |
|
466 bool cxBufferEof(const CxBuffer *buffer); |
|
467 |
427 |
468 |
428 |
469 /** |
429 /** |
470 * Ensures that the buffer has a minimum capacity. |
430 * Ensures that the buffer has a minimum capacity. |
471 * |
431 * |
479 * @retval zero the capacity was already sufficient or successfully increased |
439 * @retval zero the capacity was already sufficient or successfully increased |
480 * @retval non-zero on allocation failure |
440 * @retval non-zero on allocation failure |
481 * @see cxBufferShrink() |
441 * @see cxBufferShrink() |
482 */ |
442 */ |
483 cx_attr_nonnull |
443 cx_attr_nonnull |
484 cx_attr_export |
444 CX_EXPORT int cxBufferMinimumCapacity(CxBuffer *buffer, size_t capacity); |
485 int cxBufferMinimumCapacity( |
|
486 CxBuffer *buffer, |
|
487 size_t capacity |
|
488 ); |
|
489 |
445 |
490 /** |
446 /** |
491 * Shrinks the capacity of the buffer to fit its current size. |
447 * Shrinks the capacity of the buffer to fit its current size. |
492 * |
448 * |
493 * If @p reserve is larger than zero, the buffer is shrunk to its size plus |
449 * If @p reserve is larger than zero, the buffer is shrunk to its size plus |
502 * @param buffer the buffer |
458 * @param buffer the buffer |
503 * @param reserve the number of bytes that shall remain reserved |
459 * @param reserve the number of bytes that shall remain reserved |
504 * @see cxBufferMinimumCapacity() |
460 * @see cxBufferMinimumCapacity() |
505 */ |
461 */ |
506 cx_attr_nonnull |
462 cx_attr_nonnull |
507 cx_attr_export |
463 CX_EXPORT void cxBufferShrink(CxBuffer *buffer, size_t reserve); |
508 void cxBufferShrink( |
|
509 CxBuffer *buffer, |
|
510 size_t reserve |
|
511 ); |
|
512 |
464 |
513 /** |
465 /** |
514 * Writes data to a CxBuffer. |
466 * Writes data to a CxBuffer. |
515 * |
467 * |
516 * If automatic flushing is not enabled, the data is simply written into the |
468 * If automatic flushing is not enabled, the data is simply written into the |
550 * @return the total count of elements written |
502 * @return the total count of elements written |
551 * @see cxBufferAppend() |
503 * @see cxBufferAppend() |
552 * @see cxBufferRead() |
504 * @see cxBufferRead() |
553 */ |
505 */ |
554 cx_attr_nonnull |
506 cx_attr_nonnull |
555 cx_attr_export |
507 CX_EXPORT size_t cxBufferWrite(const void *ptr, size_t size, |
556 size_t cxBufferWrite( |
508 size_t nitems, CxBuffer *buffer); |
557 const void *ptr, |
|
558 size_t size, |
|
559 size_t nitems, |
|
560 CxBuffer *buffer |
|
561 ); |
|
562 |
509 |
563 /** |
510 /** |
564 * Appends data to a CxBuffer. |
511 * Appends data to a CxBuffer. |
565 * |
512 * |
566 * The data is always appended to current data within the buffer, |
513 * The data is always appended to current data within the buffer, |
578 * @return the total count of elements written |
525 * @return the total count of elements written |
579 * @see cxBufferWrite() |
526 * @see cxBufferWrite() |
580 * @see cxBufferRead() |
527 * @see cxBufferRead() |
581 */ |
528 */ |
582 cx_attr_nonnull |
529 cx_attr_nonnull |
583 cx_attr_export |
530 CX_EXPORT size_t cxBufferAppend(const void *ptr, size_t size, |
584 size_t cxBufferAppend( |
531 size_t nitems, CxBuffer *buffer); |
585 const void *ptr, |
|
586 size_t size, |
|
587 size_t nitems, |
|
588 CxBuffer *buffer |
|
589 ); |
|
590 |
532 |
591 /** |
533 /** |
592 * Performs a single flush-run on the specified buffer. |
534 * Performs a single flush-run on the specified buffer. |
593 * |
535 * |
594 * Does nothing when the position in the buffer is zero. |
536 * Does nothing when the position in the buffer is zero. |
640 * @param buffer the buffer |
582 * @param buffer the buffer |
641 * @return the number of successfully flushed bytes |
583 * @return the number of successfully flushed bytes |
642 * @see cxBufferEnableFlushing() |
584 * @see cxBufferEnableFlushing() |
643 */ |
585 */ |
644 cx_attr_nonnull |
586 cx_attr_nonnull |
645 cx_attr_export |
587 CX_EXPORT size_t cxBufferFlush(CxBuffer *buffer); |
646 size_t cxBufferFlush(CxBuffer *buffer); |
|
647 |
588 |
648 /** |
589 /** |
649 * Reads data from a CxBuffer. |
590 * Reads data from a CxBuffer. |
650 * |
591 * |
651 * The position of the buffer is increased by the number of bytes read. |
592 * The position of the buffer is increased by the number of bytes read. |
659 * @return the total number of elements read |
600 * @return the total number of elements read |
660 * @see cxBufferWrite() |
601 * @see cxBufferWrite() |
661 * @see cxBufferAppend() |
602 * @see cxBufferAppend() |
662 */ |
603 */ |
663 cx_attr_nonnull |
604 cx_attr_nonnull |
664 cx_attr_export |
605 CX_EXPORT size_t cxBufferRead(void *ptr, size_t size, |
665 size_t cxBufferRead( |
606 size_t nitems, CxBuffer *buffer); |
666 void *ptr, |
|
667 size_t size, |
|
668 size_t nitems, |
|
669 CxBuffer *buffer |
|
670 ); |
|
671 |
607 |
672 /** |
608 /** |
673 * Writes a character to a buffer. |
609 * Writes a character to a buffer. |
674 * |
610 * |
675 * The least significant byte of the argument is written to the buffer. If the |
611 * The least significant byte of the argument is written to the buffer. If the |
687 * @return the byte that has been written or @c EOF when the end of the stream is |
623 * @return the byte that has been written or @c EOF when the end of the stream is |
688 * reached, and automatic extension is not enabled or not possible |
624 * reached, and automatic extension is not enabled or not possible |
689 * @see cxBufferTerminate() |
625 * @see cxBufferTerminate() |
690 */ |
626 */ |
691 cx_attr_nonnull |
627 cx_attr_nonnull |
692 cx_attr_export |
628 CX_EXPORT int cxBufferPut(CxBuffer *buffer, int c); |
693 int cxBufferPut( |
|
694 CxBuffer *buffer, |
|
695 int c |
|
696 ); |
|
697 |
629 |
698 /** |
630 /** |
699 * Writes a terminating zero to a buffer at the current position. |
631 * Writes a terminating zero to a buffer at the current position. |
700 * |
632 * |
701 * If successful, sets the size to the current position and advances the position by one. |
633 * If successful, sets the size to the current position and advances the position by one. |
705 * |
637 * |
706 * @param buffer the buffer to write to |
638 * @param buffer the buffer to write to |
707 * @return zero, if the terminator could be written, non-zero otherwise |
639 * @return zero, if the terminator could be written, non-zero otherwise |
708 */ |
640 */ |
709 cx_attr_nonnull |
641 cx_attr_nonnull |
710 cx_attr_export |
642 CX_EXPORT int cxBufferTerminate(CxBuffer *buffer); |
711 int cxBufferTerminate(CxBuffer *buffer); |
|
712 |
643 |
713 /** |
644 /** |
714 * Writes a string to a buffer. |
645 * Writes a string to a buffer. |
715 * |
646 * |
716 * This is a convenience function for <code>cxBufferWrite(str, 1, strlen(str), buffer)</code>. |
647 * This is a convenience function for <code>cxBufferWrite(str, 1, strlen(str), buffer)</code>. |
717 * |
648 * |
718 * @param buffer the buffer |
649 * @param buffer the buffer |
719 * @param str the zero-terminated string |
650 * @param str the zero-terminated string |
720 * @return the number of bytes written |
651 * @return the number of bytes written |
721 */ |
652 */ |
722 cx_attr_nonnull |
653 cx_attr_nonnull cx_attr_cstr_arg(2) |
723 cx_attr_cstr_arg(2) |
654 CX_EXPORT size_t cxBufferPutString(CxBuffer *buffer, const char *str); |
724 cx_attr_export |
|
725 size_t cxBufferPutString( |
|
726 CxBuffer *buffer, |
|
727 const char *str |
|
728 ); |
|
729 |
655 |
730 /** |
656 /** |
731 * Gets a character from a buffer. |
657 * Gets a character from a buffer. |
732 * |
658 * |
733 * The current position of the buffer is increased after a successful read. |
659 * The current position of the buffer is increased after a successful read. |
734 * |
660 * |
735 * @param buffer the buffer to read from |
661 * @param buffer the buffer to read from |
736 * @return the character or @c EOF, if the end of the buffer is reached |
662 * @return the character or @c EOF, if the end of the buffer is reached |
737 */ |
663 */ |
738 cx_attr_nonnull |
664 cx_attr_nonnull |
739 cx_attr_export |
665 CX_EXPORT int cxBufferGet(CxBuffer *buffer); |
740 int cxBufferGet(CxBuffer *buffer); |
|
741 |
666 |
742 #ifdef __cplusplus |
667 #ifdef __cplusplus |
743 } |
668 } |
744 #endif |
669 #endif |
745 |
670 |