Mercurial > hg > ucx / file diff

--- a/docs/Writerside/topics/buffer.h.md	Wed Nov 26 23:06:12 2025 +0100
+++ b/docs/Writerside/topics/buffer.h.md	Wed Nov 26 23:22:03 2025 +0100
@@ -122,16 +122,22 @@
 ```C
 #include <cx/buffer.h>
 
+int cxBufferReserve(CxBuffer *buffer, size_t capacity);
+
 int cxBufferMinimumCapacity(CxBuffer *buffer, size_t capacity);
 
 void cxBufferShrink(CxBuffer *buffer, size_t reserve);
 ```
 
-The function `cxBufferMinimumCapacity()` guarantees a buffer capacity of _at least_ `capacity`.
-The actual capacity will be a power of two until the system's page size is reached.
+The functions `cxBufferReserve()` and `cxBufferMinimumCapacity()` guarantee a buffer capacity of _at least_ `capacity`.
+The difference is, that `cxBufferReserve()` will not increase the capacity beyond the specified `capacity`,
+while `cxBufferMinimumCapacity()` will grow the capacity in powers of two until the system's page size is reached.
 Then, the new capacity will be a multiple of the page size.
 The function returns non-zero if increasing the capacity was attempted unsuccessfully.
 
+You should use `cxBufferReserve()` when you know precisely the required capacity beforehand
+and `cxBufferMinimumCapacity()` when it is likely that the buffer needs to regrow soon.
+
 The function `cxBufferShrink()` can be used to shrink the capacity of the buffer to its current size
 plus a number of `reserve` bytes.
 If the current capacity is not larger than the size plus the reserve bytes, the function will do nothing.