Tue, 27 Jun 2023 18:44:37 +0200
add web docs for buffer and stream copy
docs/src/features.md | file | annotate | diff | comparison | revisions |
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)