comparison: docs/Writerside/topics/buffer.h.md
docs/Writerside/topics/buffer.h.md
- changeset 1270
- 503f0ad94c6c
- parent 1269
- e15ca477d448
equal
deleted
inserted
replaced
| 1269:e15ca477d448 | 1270:503f0ad94c6c |
|---|---|
| 81 #include <cx/buffer.h> | 81 #include <cx/buffer.h> |
| 82 | 82 |
| 83 size_t cxBufferWrite(const void *ptr, size_t size, size_t nitems, | 83 size_t cxBufferWrite(const void *ptr, size_t size, size_t nitems, |
| 84 CxBuffer *buffer); | 84 CxBuffer *buffer); |
| 85 | 85 |
| 86 int cxBufferPut(CxBuffer *buffer, int c); | |
| 87 | |
| 88 size_t cxBufferPutString(CxBuffer *buffer, const char *str); | |
| 89 | |
| 90 int cxBufferTerminate(CxBuffer *buffer); | |
| 91 | |
| 86 size_t cxBufferAppend(const void *ptr, size_t size, size_t nitems, | 92 size_t cxBufferAppend(const void *ptr, size_t size, size_t nitems, |
| 87 CxBuffer *buffer); | 93 CxBuffer *buffer); |
| 88 | 94 |
| 89 int cxBufferPut(CxBuffer *buffer, int c); | |
| 90 | |
| 91 size_t cxBufferPutString(CxBuffer *buffer, const char *str); | |
| 92 | |
| 93 int cxBufferTerminate(CxBuffer *buffer); | |
| 94 | |
| 95 int cxBufferMinimumCapacity(CxBuffer *buffer, size_t capacity); | 95 int cxBufferMinimumCapacity(CxBuffer *buffer, size_t capacity); |
| 96 ``` | 96 ``` |
| 97 | 97 |
| 98 <warning> | 98 The primary function for writing to a buffer is `cxBufferWrite()` |
| 99 TODO: document | 99 which writes up to `nitems` with `size` bytes each from the memory pointed to by `ptr` to the buffer. |
| 100 </warning> | 100 |
| 101 When the capacity of the buffer is not sufficient and the `CX_BUFFER_AUTO_EXTEND` is not set in the buffer, | |
| 102 items that do not fit into the buffer are discarded. | |
| 103 The function always returns the actual number of items successfully written. | |
| 104 This equals the number of bytes if and only if `size=1`. | |
| 105 | |
| 106 The function `cxBufferPut()` is a `putc()`-like wrapper for `cxBufferWrite()` which writes the character `c`, | |
| 107 converted to an `unsigned char` to the buffer. | |
| 108 Just like `putc()` this function returns the written character on success, and `EOF` on failure, | |
| 109 but it does _not_ set `errno` on failure. | |
| 110 | |
| 111 The function `cxBufferPutString()` is a convenience function, | |
| 112 that uses stdlib `strlen()` to compute the length of `str` and then invokes `cxBufferWrite()`. | |
| 113 | |
| 114 All of the above functions advance the buffers position by the number of bytes written, | |
| 115 and cause the _size_ of the buffer to grow, if necessary, to contain all written bytes. | |
| 116 On the other hand, `cxBufferTerminate()` writes a zero-byte at the current position, | |
| 117 effectively creating a zero-terminated string whose size equals the buffer size. | |
| 118 | |
| 119 The function `cxBufferAppend()` writes the data to end of the buffer (given by its size) regardless of the current position, | |
| 120 and it also does _not_ advance the position. | |
| 121 If the write operation triggered a [flush](#flushing), however, the position will be shifted left alongside the shifted buffer contents. | |
| 122 In case the data at which the current position points gets flushed, the new position will be zero. | |
| 123 | |
| 124 If you already (roughly) know how many bytes you will be writing to a buffer, | |
| 125 you can save some allocations during auto-extension when you invoke `cxBufferMinimumCapacity()` before writing the data. | |
| 126 Usually you do not need to do this, unless you have many subsequence writes which impose the risk of multiple unnecessary reallocations. | |
| 101 | 127 |
| 102 ## Read | 128 ## Read |
| 103 | 129 |
| 104 ```C | 130 ```C |
| 105 #include <cx/buffer.h> | 131 #include <cx/buffer.h> |
