comparison: docs/Writerside/topics/buffer.h.md
docs/Writerside/topics/buffer.h.md
- changeset 1542
- 197450c2b0b3
- parent 1515
- f024313c08f1
equal
deleted
inserted
replaced
| 1541:d06aa9db0408 | 1542:197450c2b0b3 |
|---|---|
| 127 int cxBufferMinimumCapacity(CxBuffer *buffer, size_t capacity); | 127 int cxBufferMinimumCapacity(CxBuffer *buffer, size_t capacity); |
| 128 | 128 |
| 129 void cxBufferShrink(CxBuffer *buffer, size_t reserve); | 129 void cxBufferShrink(CxBuffer *buffer, size_t reserve); |
| 130 ``` | 130 ``` |
| 131 | 131 |
| 132 The functions `cxBufferReserve()` and `cxBufferMinimumCapacity()` guarantee a buffer capacity of _at least_ `capacity`. | 132 The function `cxBufferMinimumCapacity()` guarantees a buffer capacity of _at least_ `capacity`. |
| 133 The difference is, that `cxBufferReserve()` will not increase the capacity beyond the specified `capacity`, | 133 It will grow the capacity in powers of two until the system's page size is reached. |
| 134 while `cxBufferMinimumCapacity()` will grow the capacity in powers of two until the system's page size is reached. | |
| 135 Then, the new capacity will be a multiple of the page size. | 134 Then, the new capacity will be a multiple of the page size. |
| 136 The function returns non-zero if increasing the capacity was attempted unsuccessfully. | 135 The function returns non-zero if increasing the capacity was attempted unsuccessfully. |
| 136 | |
| 137 The function `cxBufferReserve()`, on the other hand, will reallocate the buffer's space to match exactly the requested `capacity` | |
| 138 and the contents are truncated if required. | |
| 137 | 139 |
| 138 You should use `cxBufferReserve()` when you know precisely the required capacity beforehand | 140 You should use `cxBufferReserve()` when you know precisely the required capacity beforehand |
| 139 and `cxBufferMinimumCapacity()` when it is likely that the buffer needs to regrow soon. | 141 and `cxBufferMinimumCapacity()` when it is likely that the buffer needs to regrow soon. |
| 140 | 142 |
| 141 The function `cxBufferShrink()` can be used to shrink the capacity of the buffer to its current size | 143 The function `cxBufferShrink()` can be used to shrink the capacity of the buffer to its current size |
