Mercurial > hg > ucx / file diff

--- a/docs/Writerside/topics/buffer.h.md	Sat Oct 11 15:42:48 2025 +0200
+++ b/docs/Writerside/topics/buffer.h.md	Sun Oct 12 20:21:56 2025 +0200
@@ -3,14 +3,14 @@
 This buffer implementation can be used to read from or write to memory like you would do with a stream.
 
 This allows the use of `cx_stream_copy()` (see [](streams.h.md)) to copy contents from one buffer to another,
-or from a file or network streams to the buffer and vice versa.
+or from a file or network stream to the buffer and vice versa.
 
 More features for convenient use of the buffer can be enabled, like automatic memory management,
 automatic resizing of the buffer space, or automatic flushing of contents.
 
 The functions `cxBufferRead()` and `cxBufferWrite()` are `cx_read_func` and `cx_write_func` compatible,
 which in turn have a compatible signature to `fread()` and `fwrite()`.
-However, due to the different pointer type, the function pointers do not type check out of the box.
+However, due to the different pointer type the function pointers do not type check out of the box.
 For convenience, the macros `cxBufferReadFunc` and `cxBufferWriteFunc` are defined, which perform the necessary cast.
 
 ## Example
@@ -80,7 +80,7 @@
 #define CX_BUFFER_COPY_ON_EXTEND
 ```
 
-For creating a UCX buffer you have two options: initialize a pre-allocated structure, or allocate and initialize a new structure in one call.
+For creating a UCX buffer, you have two options: initialize a pre-allocated structure, or allocate and initialize a new structure in one call.
 
 For the first option, you can call `cxBufferInit()` with the `buffer` argument pointing to an uninitialized `CxBuffer` structure.
 You can pass a pre-allocated `space`, the desired `capacity`, and an `allocator`.
@@ -175,12 +175,12 @@
 The function `cxBufferPutString()` is a convenience function,
 that uses stdlib `strlen()` to compute the length of `str` and then invokes `cxBufferWrite()`.
 
-All of the above functions advance the buffers position by the number of bytes written,
+All the above functions advance the buffer position by the number of bytes written 
 and cause the _size_ of the buffer to grow, if necessary, to contain all written bytes.
 On the other hand, `cxBufferTerminate()` writes a zero-byte at the current position,
 effectively creating a zero-terminated string whose size equals the buffer size.
 
-The function `cxBufferAppend()` writes the data to end of the buffer (given by its size) regardless of the current position,
+The function `cxBufferAppend()` writes the data to the end of the buffer (given by its size) regardless of the current position,
 and it also does _not_ advance the position.
 If the write operation triggered a [flush](#flushing), however, the position will be shifted left alongside the shifted buffer contents.
 In case the data at which the current position points gets flushed, the new position will be zero.
@@ -199,8 +199,8 @@
 ```
 
 The function `cxBufferRead()` reads `nitems` number of items of `size` bytes each from the `buffer`
-and stores them into the memory pointed to by `ptr`, which must be sufficiently large to hold the contents.
-The function returns the actual bytes read, which might be lower, if the desired number of items is not available.
+and stores them into the memory pointed to by `ptr`, which must be large enough to hold the contents.
+The function returns the actual bytes read, which might be lower if the desired number of items is not available.
 
 The function `cxBufferGet()` is a `fgetc()`-like function which returns the next byte in the buffer converted to an `int`.
 Similar to `fgetc()` it returns `EOF` when there are no more bytes in the buffer.
@@ -225,8 +225,8 @@
 The function `cxBufferReset()` sets both size and position of the buffer to zero,
 and `cxBufferClear()` additionally uses `memset()` to set every byte in the buffer to zero.
 
-> When clearing the buffer, only the "live" data, i.e. bytes with indices `[0..size)`, are cleared.
-> If you which to clear the entire buffer's memory, you would need to set the size to the capacity, first.
+> When clearing the buffer, only the "live" data, i.e., bytes with indices `[0..size)`, are cleared.
+> If you want to clear the entire buffer's memory, you would need to set the size to the capacity, first.
 
 > If the `CX_BUFFER_COPY_ON_WRITE` flag is set, `cxBufferClear()` behaves exactly like `cxBufferReset()`,
 > because writing to the contents is disallowed.
@@ -263,9 +263,9 @@
 
 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.
+It also adjusts the current position within the buffer, and in the 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.
+Data shifted 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.
@@ -274,8 +274,8 @@
 (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.
+which usually makes little sense on a 64-bit platform where `off_t` is already large enough to represent any reasonable offset.
+You may, however, still use those functions to express more explicitly in your code in which direction you want the contents to be shifted.
 
 ## Flushing
 
@@ -310,13 +310,13 @@
 Flushing happens by invoking the `wfunc` up to `blkmax` times, writing up to `blksize` bytes from the buffer to the `target` with each call.
 The target might not accept all bytes (i.e. the `wfunc` return value indicates that fewer items have been written than requested),
 in which case the remaining data remains in the buffer.
-That means, the buffer is effectively [shifted](#shift-contents) left by the number of successfully flushed bytes.
+That means the buffer is effectively [shifted](#shift-contents) left by the number of successfully flushed bytes.
 
 > When you write large amounts of data to a buffer, multiple flush cycles might happen.
-> After the first flush operations completed, the reclaimed space in the buffer is filled first, but if that
-> is not sufficient, another flush may be triggered within the same invocation of the write operation.
+> After the first flush operations are completed, the reclaimed space in the buffer is filled first, but if that
+> is not enough, another flush may be triggered within the same invocation of the write operation.
 > 
-> That means, as much data is written to the buffer and/or flushed as possible, until neither the flush target, nor the buffer accept more data.
+> That means as much data is written to the buffer and/or flushed as possible, until neither the flush target nor the buffer accept more data.
 >{style="note"}
 
 > The function `cxBufferFlush()` simply returns zero when flushing was not enabled via `cxBufferEnableFlushing()`.