Mercurial > hg > ucx / file comparison

comparison: docs/src/features.md

docs/src/features.md

changeset 724
5e7b1951dc80
parent 723
c33e0ac069dd
child 725
c9b882bef838
equal deleted inserted replaced
723:c33e0ac069dd 724:5e7b1951dc80
72 As a rule of thumb, you _should not_ pass the strings of a UCX string structure to another API without explicitly 72 As a rule of thumb, you _should not_ pass the strings of a UCX string structure to another API without explicitly
73 ensuring that the string is zero-terminated. 73 ensuring that the string is zero-terminated.
74 74
75 ## Buffer 75 ## Buffer
76 76
77 *Header file:* [buffer.h](api/buffer_8h.html) 77 *Header file:* [buffer.h](api/buffer_8h.html)
78
79 Instances of this buffer implementation can be used to read from or write to memory like you would do with a stream.
80 This allows the use of `cx_stream_copy()` (see [Utilities](#utilities)) to copy contents from one buffer to another,
81 or from a file or network streams to the buffer and vice-versa.
82
83 More features for convenient use of the buffer can be enabled, like automatic memory management and automatic
84 resizing of the buffer space.
85
86 Since UCX 3.0, the buffer also supports automatic flushing of contents to another stream (or buffer) as an alternative
87 to automatically resizing the buffer space.
88 Please refer to the API doc for the fields prefixed with `flush_` to learn more.
78 89
79 ## Memory Pool 90 ## Memory Pool
80 91
81 *Header file:* [mempool.h](api/mempool_8h.html) 92 *Header file:* [mempool.h](api/mempool_8h.html)
82 93
114 125
115 ## Utilities 126 ## Utilities
116 127
117 *Header file:* [utils.h](api/utils_8h.html) 128 *Header file:* [utils.h](api/utils_8h.html)
118 129
130 UCX provides some utilities for routine tasks. Most of them are simple macros, like e.g. the `cx_for_n()` macro,
131 creating a `for` loop counting from zero to (n-1) which is extremely useful to traverse the indices of
132 an array.
133
134 But the most useful utilities are the *stream copy* functions, which provide a simple way to copy all - or a
135 bounded amount of - data from one stream to another. Since the read/write functions of a UCX buffer are
136 fully compatible with stream read/write functions, you can easily transfer data from file or network streams to
137 a UCX buffer or vice-versa.
138
139 The following example shows, how easy it is to read the contents of a file into a buffer:
140 ```c
141 FILE *inputfile = fopen(infilename, "r");
142 if (inputfile) {
143 CxBuffer fbuf;
144 cxBufferInit(&fbuf, NULL, 4096, NULL, CX_BUFFER_AUTO_EXTEND);
145 cx_stream_copy(inputfile, &fbuf,
146 (cx_read_func) fread,
147 (cx_write_func) cxBufferWrite);
148 fclose(inputfile);
149
150 // ... do something meaningful with the contents ...
151
152 cxBufferDestroy(&fbuf);
153 } else {
154 perror("Error opening input file");
155 if (fout != stdout) {
156 fclose(fout);
157 }
158 }
159 ```
160
119 ### Printf Functions 161 ### Printf Functions
120 162
121 *Header file:* [printf.h](api/printf_8h.html) 163 *Header file:* [printf.h](api/printf_8h.html)
122 164
123 ### Compare Functions 165 ### Compare Functions

Mercurial Repository: ucx

mercurial