comparison: src/ucx/cx/buffer.h
src/ucx/cx/buffer.h
- changeset 582
- 82b60a8dd55c
- parent 579
- e10457d74fe1
- child 621
- 956c03c25edd
equal
deleted
inserted
replaced
| 581:4a049e416021 | 582:82b60a8dd55c |
|---|---|
| 220 * @param space pointer to the memory area, or @c NULL to allocate | 220 * @param space pointer to the memory area, or @c NULL to allocate |
| 221 * new memory | 221 * new memory |
| 222 * @param capacity the capacity of the buffer | 222 * @param capacity the capacity of the buffer |
| 223 * @param allocator the allocator this buffer shall use for automatic | 223 * @param allocator the allocator this buffer shall use for automatic |
| 224 * memory management | 224 * memory management |
| 225 * (if @c NULL, a default stdlib allocator 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_attr_export |
| 303 * @param space pointer to the memory area, or @c NULL to allocate | 303 * @param space pointer to the memory area, or @c NULL to allocate |
| 304 * new memory | 304 * new memory |
| 305 * @param capacity the capacity of the buffer | 305 * @param capacity the capacity of the buffer |
| 306 * @param allocator the allocator to use for allocating the structure and the automatic | 306 * @param allocator the allocator to use for allocating the structure and the automatic |
| 307 * memory management within the buffer | 307 * memory management within the buffer |
| 308 * (if @c NULL, a default stdlib allocator will be used) | 308 * (if @c NULL, the cxDefaultAllocator will be used) |
| 309 * @param flags buffer features (see cx_buffer_s.flags) | 309 * @param flags buffer features (see cx_buffer_s.flags) |
| 310 * @return a pointer to the buffer on success, @c NULL if a required allocation failed | 310 * @return a pointer to the buffer on success, @c NULL if a required allocation failed |
| 311 */ | 311 */ |
| 312 cx_attr_malloc | 312 cx_attr_malloc |
| 313 cx_attr_dealloc(cxBufferFree, 1) | 313 cx_attr_dealloc(cxBufferFree, 1) |
| 472 /** | 472 /** |
| 473 * Ensures that the buffer has a minimum capacity. | 473 * Ensures that the buffer has a minimum capacity. |
| 474 * | 474 * |
| 475 * If the current capacity is not sufficient, the buffer will be extended. | 475 * If the current capacity is not sufficient, the buffer will be extended. |
| 476 * | 476 * |
| 477 * The new capacity will be a power of two until the system's page size is reached. | |
| 478 * Then, the new capacity will be a multiple of the page size. | |
| 479 * | |
| 477 * @param buffer the buffer | 480 * @param buffer the buffer |
| 478 * @param capacity the minimum required capacity for this buffer | 481 * @param capacity the minimum required capacity for this buffer |
| 479 * @retval zero the capacity was already sufficient or successfully increased | 482 * @retval zero the capacity was already sufficient or successfully increased |
| 480 * @retval non-zero on allocation failure | 483 * @retval non-zero on allocation failure |
| 484 * @see cxBufferShrink() | |
| 481 */ | 485 */ |
| 482 cx_attr_nonnull | 486 cx_attr_nonnull |
| 483 cx_attr_export | 487 cx_attr_export |
| 484 int cxBufferMinimumCapacity( | 488 int cxBufferMinimumCapacity( |
| 485 CxBuffer *buffer, | 489 CxBuffer *buffer, |
| 486 size_t capacity | 490 size_t capacity |
| 491 ); | |
| 492 | |
| 493 /** | |
| 494 * Shrinks the capacity of the buffer to fit its current size. | |
| 495 * | |
| 496 * If @p reserve is larger than zero, the buffer is shrunk to its size plus | |
| 497 * the number of reserved bytes. | |
| 498 * | |
| 499 * If the current capacity is not larger than the size plus the reserved bytes, | |
| 500 * nothing happens. | |
| 501 * | |
| 502 * If the #CX_BUFFER_COPY_ON_WRITE or #CX_BUFFER_COPY_ON_EXTEND flag is set, | |
| 503 * this function does nothing. | |
| 504 * | |
| 505 * @param buffer the buffer | |
| 506 * @param reserve the number of bytes that shall remain reserved | |
| 507 * @see cxBufferMinimumCapacity() | |
| 508 */ | |
| 509 cx_attr_nonnull | |
| 510 cx_attr_export | |
| 511 void cxBufferShrink( | |
| 512 CxBuffer *buffer, | |
| 513 size_t reserve | |
| 487 ); | 514 ); |
| 488 | 515 |
| 489 /** | 516 /** |
| 490 * Writes data to a CxBuffer. | 517 * Writes data to a CxBuffer. |
| 491 * | 518 * |
| 672 ); | 699 ); |
| 673 | 700 |
| 674 /** | 701 /** |
| 675 * Writes a terminating zero to a buffer at the current position. | 702 * Writes a terminating zero to a buffer at the current position. |
| 676 * | 703 * |
| 677 * On successful write, @em neither the position @em nor the size of the buffer is | 704 * If successful, sets the size to the current position and advances the position by one. |
| 678 * increased. | |
| 679 * | 705 * |
| 680 * The purpose of this function is to have the written data ready to be used as | 706 * The purpose of this function is to have the written data ready to be used as |
| 681 * a C string. | 707 * a C string with the buffer's size being the length of that string. |
| 682 * | 708 * |
| 683 * @param buffer the buffer to write to | 709 * @param buffer the buffer to write to |
| 684 * @return zero, if the terminator could be written, non-zero otherwise | 710 * @return zero, if the terminator could be written, non-zero otherwise |
| 685 */ | 711 */ |
| 686 cx_attr_nonnull | 712 cx_attr_nonnull |
