Mercurial > hg > ucx / changeset

     1.1 --- a/docs/src/features.md	Tue Jun 27 18:24:28 2023 +0200
     1.2 +++ b/docs/src/features.md	Tue Jun 27 18:44:37 2023 +0200
     1.3 @@ -74,7 +74,18 @@
     1.4  
     1.5  ## Buffer
     1.6  
     1.7 -*Header file:* [buffer.h](api/buffer_8h.html)  
     1.8 +*Header file:* [buffer.h](api/buffer_8h.html)
     1.9 +
    1.10 +Instances of this buffer implementation can be used to read from or write to memory like you would do with a stream.
    1.11 +This allows the use of `cx_stream_copy()` (see [Utilities](#utilities)) to copy contents from one buffer to another,
    1.12 +or from a file or network streams to the buffer and vice-versa.
    1.13 +
    1.14 +More features for convenient use of the buffer can be enabled, like automatic memory management and automatic
    1.15 +resizing of the buffer space.
    1.16 +
    1.17 +Since UCX 3.0, the buffer also supports automatic flushing of contents to another stream (or buffer) as an alternative
    1.18 +to automatically resizing the buffer space.
    1.19 +Please refer to the API doc for the fields prefixed with `flush_` to learn more. 
    1.20  
    1.21  ## Memory Pool
    1.22  
    1.23 @@ -116,6 +127,37 @@
    1.24  
    1.25  *Header file:* [utils.h](api/utils_8h.html)
    1.26  
    1.27 +UCX provides some utilities for routine tasks. Most of them are simple macros, like e.g. the `cx_for_n()` macro,
    1.28 +creating a `for` loop counting from zero to (n-1) which is extremely useful to traverse the indices of
    1.29 +an array.
    1.30 +
    1.31 +But the most useful utilities are the *stream copy* functions, which provide a simple way to copy all - or a
    1.32 +bounded amount of - data from one stream to another. Since the read/write functions of a UCX buffer are
    1.33 +fully compatible with stream read/write functions, you can easily transfer data from file or network streams to
    1.34 +a UCX buffer or vice-versa.
    1.35 +
    1.36 +The following example shows, how easy it is to read the contents of a file into a buffer:
    1.37 +```c
    1.38 +FILE *inputfile = fopen(infilename, "r");
    1.39 +if (inputfile) {
    1.40 +    CxBuffer fbuf;
    1.41 +    cxBufferInit(&fbuf, NULL, 4096, NULL, CX_BUFFER_AUTO_EXTEND);
    1.42 +    cx_stream_copy(inputfile, &fbuf,
    1.43 +                   (cx_read_func) fread,
    1.44 +                   (cx_write_func) cxBufferWrite);
    1.45 +    fclose(inputfile);
    1.46 +    
    1.47 +    // ... do something meaningful with the contents ...
    1.48 +    
    1.49 +    cxBufferDestroy(&fbuf);
    1.50 +} else {
    1.51 +    perror("Error opening input file");
    1.52 +    if (fout != stdout) {
    1.53 +        fclose(fout);
    1.54 +    }
    1.55 +}
    1.56 +```
    1.57 +
    1.58  ### Printf Functions
    1.59  
    1.60  *Header file:* [printf.h](api/printf_8h.html)