comparison: docs/Writerside/topics/buffer.h.md
docs/Writerside/topics/buffer.h.md
- changeset 1290
- 4ac889e14211
- parent 1288
- b41ad5d9bcbf
- child 1291
- 5942859fd76c
equal
deleted
inserted
replaced
| 1289:2e8edba252a0 | 1290:4ac889e14211 |
|---|---|
| 115 | 115 |
| 116 The function `cxBufferDestroy()` is to be used when the buffer was initialized with `cxBufferInit()`, | 116 The function `cxBufferDestroy()` is to be used when the buffer was initialized with `cxBufferInit()`, |
| 117 and the function `cxBufferFree()` is to be used when the buffer was created with `cxBufferCreate()`. | 117 and the function `cxBufferFree()` is to be used when the buffer was created with `cxBufferCreate()`. |
| 118 The only difference is, that `cxBufferFree()` additionally deallocates the memory of the `CxBuffer` structure. | 118 The only difference is, that `cxBufferFree()` additionally deallocates the memory of the `CxBuffer` structure. |
| 119 | 119 |
| 120 ## Capacity Management | |
| 121 | |
| 122 ```C | |
| 123 #include <cx/buffer.h> | |
| 124 | |
| 125 int cxBufferMinimumCapacity(CxBuffer *buffer, size_t capacity); | |
| 126 | |
| 127 void cxBufferShrink(CxBuffer *buffer, size_t reserve); | |
| 128 ``` | |
| 129 | |
| 130 The function `cxBufferMinimumCapacity()` guarantees a buffer capacity of _at least_ `capacity`. | |
| 131 It may allocate more space, depending on the allocation strategy. | |
| 132 The function returns non-zero if increasing the capacity was attempted unsuccessfully. | |
| 133 | |
| 134 The function `cxBufferShrink()` can be used to shrink the capacity of the buffer to its current size | |
| 135 plus a number of `reserve` bytes. | |
| 136 If the current capacity is not larger than the size plus the reserve bytes, the function will do nothing. | |
| 137 | |
| 138 > If the buffer is in a copy-on-write state, `cxBufferMinimumCapacity()` will perform the copy-on-write action | |
| 139 > before reallocating the space. | |
| 140 > The function `cxBufferShrink()` on the other hand does _nothing_ when the buffer is in a copy-on-write state, | |
| 141 > because it does not make much sense to copy the memory just to have it in a smaller memory region. | |
| 142 | |
| 120 ## Write | 143 ## Write |
| 121 | 144 |
| 122 ```C | 145 ```C |
| 123 #include <cx/buffer.h> | 146 #include <cx/buffer.h> |
| 124 | 147 |
| 131 | 154 |
| 132 int cxBufferTerminate(CxBuffer *buffer); | 155 int cxBufferTerminate(CxBuffer *buffer); |
| 133 | 156 |
| 134 size_t cxBufferAppend(const void *ptr, size_t size, size_t nitems, | 157 size_t cxBufferAppend(const void *ptr, size_t size, size_t nitems, |
| 135 CxBuffer *buffer); | 158 CxBuffer *buffer); |
| 136 | |
| 137 int cxBufferMinimumCapacity(CxBuffer *buffer, size_t capacity); | |
| 138 ``` | 159 ``` |
| 139 | 160 |
| 140 The primary function for writing to a buffer is `cxBufferWrite()` | 161 The primary function for writing to a buffer is `cxBufferWrite()` |
| 141 which writes up to `nitems` with `size` bytes each from the memory pointed to by `ptr` to the buffer. | 162 which writes up to `nitems` with `size` bytes each from the memory pointed to by `ptr` to the buffer. |
| 142 | 163 |
| 160 | 181 |
| 161 The function `cxBufferAppend()` writes the data to end of the buffer (given by its size) regardless of the current position, | 182 The function `cxBufferAppend()` writes the data to end of the buffer (given by its size) regardless of the current position, |
| 162 and it also does _not_ advance the position. | 183 and it also does _not_ advance the position. |
| 163 If the write operation triggered a [flush](#flushing), however, the position will be shifted left alongside the shifted buffer contents. | 184 If the write operation triggered a [flush](#flushing), however, the position will be shifted left alongside the shifted buffer contents. |
| 164 In case the data at which the current position points gets flushed, the new position will be zero. | 185 In case the data at which the current position points gets flushed, the new position will be zero. |
| 165 | |
| 166 If you already (roughly) know how many bytes you will be writing to a buffer, | |
| 167 you can save some allocations during auto-extension when you invoke `cxBufferMinimumCapacity()` before writing the data. | |
| 168 Usually you do not need to do this, unless you have many subsequence writes which impose the risk of multiple unnecessary reallocations. | |
| 169 | 186 |
| 170 ## Read | 187 ## Read |
| 171 | 188 |
| 172 ```C | 189 ```C |
| 173 #include <cx/buffer.h> | 190 #include <cx/buffer.h> |
