comparison: docs/Writerside/topics/buffer.h.md
docs/Writerside/topics/buffer.h.md
- changeset 1515
- f024313c08f1
- parent 1514
- ee5d668a71e4
equal
deleted
inserted
replaced
| 1514:ee5d668a71e4 | 1515:f024313c08f1 |
|---|---|
| 120 ## Capacity Management | 120 ## Capacity Management |
| 121 | 121 |
| 122 ```C | 122 ```C |
| 123 #include <cx/buffer.h> | 123 #include <cx/buffer.h> |
| 124 | 124 |
| 125 int cxBufferReserve(CxBuffer *buffer, size_t capacity); | |
| 126 | |
| 125 int cxBufferMinimumCapacity(CxBuffer *buffer, size_t capacity); | 127 int cxBufferMinimumCapacity(CxBuffer *buffer, size_t capacity); |
| 126 | 128 |
| 127 void cxBufferShrink(CxBuffer *buffer, size_t reserve); | 129 void cxBufferShrink(CxBuffer *buffer, size_t reserve); |
| 128 ``` | 130 ``` |
| 129 | 131 |
| 130 The function `cxBufferMinimumCapacity()` guarantees a buffer capacity of _at least_ `capacity`. | 132 The functions `cxBufferReserve()` and `cxBufferMinimumCapacity()` guarantee a buffer capacity of _at least_ `capacity`. |
| 131 The actual capacity will be a power of two until the system's page size is reached. | 133 The difference is, that `cxBufferReserve()` will not increase the capacity beyond the specified `capacity`, |
| 134 while `cxBufferMinimumCapacity()` will grow the capacity in powers of two until the system's page size is reached. | |
| 132 Then, the new capacity will be a multiple of the page size. | 135 Then, the new capacity will be a multiple of the page size. |
| 133 The function returns non-zero if increasing the capacity was attempted unsuccessfully. | 136 The function returns non-zero if increasing the capacity was attempted unsuccessfully. |
| 137 | |
| 138 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. | |
| 134 | 140 |
| 135 The function `cxBufferShrink()` can be used to shrink the capacity of the buffer to its current size | 141 The function `cxBufferShrink()` can be used to shrink the capacity of the buffer to its current size |
| 136 plus a number of `reserve` bytes. | 142 plus a number of `reserve` bytes. |
| 137 If the current capacity is not larger than the size plus the reserve bytes, the function will do nothing. | 143 If the current capacity is not larger than the size plus the reserve bytes, the function will do nothing. |
| 138 | 144 |
