Mercurial > hg > ucx / changeset

--- a/docs/Writerside/topics/buffer.h.md	Sun Mar 23 12:26:03 2025 +0100
+++ b/docs/Writerside/topics/buffer.h.md	Mon Mar 24 20:16:36 2025 +0100
@@ -144,9 +144,21 @@
 int cxBufferShiftLeft(CxBuffer *buffer, size_t shift);
 ```
 
-<warning>
-TODO: document
-</warning>
+The function `cxBufferShift()` moves the contents within the buffer by the specified `shift` offset,
+where a negative offset means a shift to the left, and a positive offset means a shift to the right.
+It also adjusts the current position within the buffer, and in case of a right shift also the size, by the same offset.
+
+Data that is shift to the left, is always discarded when the new position of a byte would be smaller than zero.
+If the new position would be smaller than zero, it is set exactly to zero.
+
+When data is shift to the right, the behavior depends on the `CX_BUFFER_AUTO_EXTEND` flag.
+If set, the function extends the buffer's capacity before moving the data.
+Otherwise, the function discards all data that would exceed the buffer's capacity, and both the size and the position are equal to the capacity
+(which means, `cxBufferEof()` returns `true` after the operation). 
+
+The functions `cxBufferShiftRight()` and `cxBufferShiftLeft()` accept a larger (but in both cases positive) shift offset,
+which usually does not make much sense on a 64-bit platform where `off_t` is already large enough to represent any reasonable offset.
+You may, however, still use those function to express more explicitly in your code in which direction you want the contents to be shifted.
 
 ## Flushing