Mercurial > hg > ucx / changeset

--- a/docs/src/features.md	Tue Jun 27 18:24:28 2023 +0200
+++ b/docs/src/features.md	Tue Jun 27 18:44:37 2023 +0200
@@ -74,7 +74,18 @@
 
 ## Buffer
 
-*Header file:* [buffer.h](api/buffer_8h.html)  
+*Header file:* [buffer.h](api/buffer_8h.html)
+
+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 [Utilities](#utilities)) 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.
+
+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. 
 
 ## Memory Pool
 
@@ -116,6 +127,37 @@
 
 *Header file:* [utils.h](api/utils_8h.html)
 
+UCX provides some utilities for routine tasks. Most of them are simple macros, like e.g. the `cx_for_n()` macro,
+creating a `for` loop counting from zero to (n-1) which is extremely useful to traverse the indices of
+an array.
+
+But the most useful utilities are the *stream copy* functions, which provide a simple way to copy all - or a
+bounded amount of - data from one stream to another. Since the read/write functions of a UCX buffer are
+fully compatible with stream read/write functions, you can easily transfer data from file or network streams to
+a UCX buffer or vice-versa.
+
+The following example shows, how easy it is to read the contents of a file into a buffer:
+```c
+FILE *inputfile = fopen(infilename, "r");
+if (inputfile) {
+    CxBuffer fbuf;
+    cxBufferInit(&fbuf, NULL, 4096, NULL, CX_BUFFER_AUTO_EXTEND);
+    cx_stream_copy(inputfile, &fbuf,
+                   (cx_read_func) fread,
+                   (cx_write_func) cxBufferWrite);
+    fclose(inputfile);
+    
+    // ... do something meaningful with the contents ...
+    
+    cxBufferDestroy(&fbuf);
+} else {
+    perror("Error opening input file");
+    if (fout != stdout) {
+        fclose(fout);
+    }
+}
+```
+
 ### Printf Functions
 
 *Header file:* [printf.h](api/printf_8h.html)