comparison: ucx/cx/buffer.h
ucx/cx/buffer.h
- changeset 995
- 2f811eae2424
- parent 992
- f421aef8f865
equal
deleted
inserted
replaced
| 994:c9395b30e5c8 | 995:2f811eae2424 |
|---|---|
| 46 #ifndef UCX_BUFFER_H | 46 #ifndef UCX_BUFFER_H |
| 47 #define UCX_BUFFER_H | 47 #define UCX_BUFFER_H |
| 48 | 48 |
| 49 #include "common.h" | 49 #include "common.h" |
| 50 #include "allocator.h" | 50 #include "allocator.h" |
| 51 #include "string.h" | |
| 51 | 52 |
| 52 #ifdef __cplusplus | 53 #ifdef __cplusplus |
| 53 extern "C" { | 54 extern "C" { |
| 54 #endif | 55 #endif |
| 55 | 56 |
| 85 * After performing the copy, the flag is automatically cleared. | 86 * After performing the copy, the flag is automatically cleared. |
| 86 * This flag has no effect on buffers which do not have #CX_BUFFER_AUTO_EXTEND set, which is why | 87 * This flag has no effect on buffers which do not have #CX_BUFFER_AUTO_EXTEND set, which is why |
| 87 * buffers automatically admit the auto-extend flag when initialized with copy-on-extend enabled. | 88 * buffers automatically admit the auto-extend flag when initialized with copy-on-extend enabled. |
| 88 */ | 89 */ |
| 89 #define CX_BUFFER_COPY_ON_EXTEND 0x08 | 90 #define CX_BUFFER_COPY_ON_EXTEND 0x08 |
| 91 | |
| 92 /** | |
| 93 * If this flag is enabled, the buffer will never free its contents regardless of #CX_BUFFER_FREE_CONTENTS. | |
| 94 * | |
| 95 * This is useful, for example, when you want to keep a pointer to the data after destroying the buffer. | |
| 96 */ | |
| 97 #define CX_BUFFER_DO_NOT_FREE 0x10 | |
| 90 | 98 |
| 91 /** | 99 /** |
| 92 * Function pointer for cxBufferWrite that is compatible with cx_write_func. | 100 * Function pointer for cxBufferWrite that is compatible with cx_write_func. |
| 93 * @see cx_write_func | 101 * @see cx_write_func |
| 94 */ | 102 */ |
| 536 CX_EXPORT int cxBufferPut(CxBuffer *buffer, int c); | 544 CX_EXPORT int cxBufferPut(CxBuffer *buffer, int c); |
| 537 | 545 |
| 538 /** | 546 /** |
| 539 * Writes a terminating zero to a buffer at the current position. | 547 * Writes a terminating zero to a buffer at the current position. |
| 540 * | 548 * |
| 541 * If successful, sets the size to the current position and advances | 549 * If successful, also sets the size to the current position and shrinks the buffer. |
| 542 * the position by one. | |
| 543 * | 550 * |
| 544 * The purpose of this function is to have the written data ready to be used as | 551 * The purpose of this function is to have the written data ready to be used as |
| 545 * a C string with the buffer's size being the length of that string. | 552 * a C string with the buffer's size being the length of that string. |
| 546 * | 553 * |
| 547 * @param buffer the buffer to write to | 554 * @param buffer the buffer to write to |
| 548 * @return zero, if the terminator could be written, non-zero otherwise | 555 * @return zero, if the terminator could be written, non-zero otherwise |
| 556 * @see cxBufferShrink() | |
| 549 */ | 557 */ |
| 550 cx_attr_nonnull | 558 cx_attr_nonnull |
| 551 CX_EXPORT int cxBufferTerminate(CxBuffer *buffer); | 559 CX_EXPORT int cxBufferTerminate(CxBuffer *buffer); |
| 552 | 560 |
| 553 /** | 561 /** |
| 554 * Writes a string to a buffer. | 562 * Internal function - do not use. |
| 555 * | 563 * |
| 556 * This is a convenience function for <code>cxBufferWrite(str, 1, strlen(str), buffer)</code>. | 564 * @param buffer the buffer |
| 557 * | 565 * @param str the string |
| 558 * @param buffer the buffer | |
| 559 * @param str the zero-terminated string | |
| 560 * @return the number of bytes written | 566 * @return the number of bytes written |
| 561 */ | 567 * @see cxBufferPutString() |
| 562 cx_attr_nonnull cx_attr_cstr_arg(2) | 568 */ |
| 563 CX_EXPORT size_t cxBufferPutString(CxBuffer *buffer, const char *str); | 569 cx_attr_nonnull |
| 570 CX_EXPORT size_t cx_buffer_put_string(CxBuffer *buffer, cxstring str); | |
| 571 | |
| 572 /** | |
| 573 * Writes a string to a buffer with cxBufferWrite(). | |
| 574 * | |
| 575 * @param buffer (@c CxBuffer*) the buffer | |
| 576 * @param str (any string) the zero-terminated string | |
| 577 * @return (@c size_t) the number of bytes written | |
| 578 * @see cxBufferWrite() | |
| 579 * @see cx_strcast() | |
| 580 */ | |
| 581 #define cxBufferPutString(buffer, str) cx_buffer_put_string(buffer, cx_strcast(str)) | |
| 582 | |
| 583 /** | |
| 584 * Internal function - do not use. | |
| 585 * | |
| 586 * @param buffer the buffer | |
| 587 * @param str the string | |
| 588 * @return the number of bytes written | |
| 589 * @see cxBufferPutString() | |
| 590 */ | |
| 591 cx_attr_nonnull | |
| 592 CX_EXPORT size_t cx_buffer_append_string(CxBuffer *buffer, cxstring str); | |
| 593 | |
| 594 /** | |
| 595 * Appends a string to a buffer with cxBufferAppend(). | |
| 596 * | |
| 597 * @param buffer (@c CxBuffer*) the buffer | |
| 598 * @param str (any string) the zero-terminated string | |
| 599 * @return (@c size_t) the number of bytes written | |
| 600 * @see cxBufferAppend() | |
| 601 * @see cx_strcast() | |
| 602 */ | |
| 603 #define cxBufferAppendString(buffer, str) cx_buffer_append_string(buffer, cx_strcast(str)) | |
| 564 | 604 |
| 565 /** | 605 /** |
| 566 * Gets a character from a buffer. | 606 * Gets a character from a buffer. |
| 567 * | 607 * |
| 568 * The current position of the buffer is increased after a successful read. | 608 * The current position of the buffer is increased after a successful read. |
