Mercurial > hg > ucx / changeset

--- a/docs/Writerside/topics/buffer.h.md	Tue Mar 25 22:11:06 2025 +0100
+++ b/docs/Writerside/topics/buffer.h.md	Wed Mar 26 12:26:20 2025 +0100
@@ -1,19 +1,17 @@
 # Buffer
 
-<warning>
-Outdated Section - will be updated soon!
-</warning>
+This buffer implementation can be used to read from or write to memory like you would do with a stream.
 
-Instances of 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.
 
-More features for convenient use of the buffer can be enabled, like automatic memory management and automatic
-resizing of the buffer space.
+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.
 
-Since UCX 3.0, the buffer also supports automatic flushing of contents to another stream (or buffer) as an alternative
-to automatically resizing the buffer space.
-Please refer to the API doc for the fields prefixed with `flush_` to learn more. 
+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.
+For convenience, the macros `cxBufferReadFunc` and `cxBufferWriteFunc` are defined, which perform the necessary cast.
 
 ## Example
 
@@ -97,9 +95,19 @@
 bool cxBufferEof(const CxBuffer *buffer);
 ```
 
-<warning>
-TODO: document
-</warning>
+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.
+
+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.
+
+When all bytes from the buffer have been read, the function `cxBufferEof()` returns true. 
+
+All read functions advance the position in the buffer by the number of read bytes.
+
+> When you want to read from a buffer that you previously used for writing, do not forget to set the position
+> in the buffer to zero, e.g. by calling `cxBufferSeek()`.
 
 ## Reset and Clear