comparison: docs/Writerside/topics/buffer.h.md
docs/Writerside/topics/buffer.h.md
- changeset 1262
- 7cc81244b28a
- parent 1261
- 6bbc308b7a20
- child 1263
- f993745c60f0
equal
deleted
inserted
replaced
| 1261:6bbc308b7a20 | 1262:7cc81244b28a |
|---|---|
| 1 # Buffer | 1 # Buffer |
| 2 | 2 |
| 3 <warning> | 3 This buffer implementation can be used to read from or write to memory like you would do with a stream. |
| 4 Outdated Section - will be updated soon! | 4 |
| 5 </warning> | |
| 6 | |
| 7 Instances of this buffer implementation can be used to read from or write to memory like you would do with a stream. | |
| 8 This allows the use of `cx_stream_copy()` (see [](streams.h.md)) to copy contents from one buffer to another, | 5 This allows the use of `cx_stream_copy()` (see [](streams.h.md)) to copy contents from one buffer to another, |
| 9 or from a file or network streams to the buffer and vice versa. | 6 or from a file or network streams to the buffer and vice versa. |
| 10 | 7 |
| 11 More features for convenient use of the buffer can be enabled, like automatic memory management and automatic | 8 More features for convenient use of the buffer can be enabled, like automatic memory management, |
| 12 resizing of the buffer space. | 9 automatic resizing of the buffer space, or automatic flushing of contents. |
| 13 | 10 |
| 14 Since UCX 3.0, the buffer also supports automatic flushing of contents to another stream (or buffer) as an alternative | 11 The functions `cxBufferRead()` and `cxBufferWrite()` are `cx_read_func` and `cx_write_func` compatible, |
| 15 to automatically resizing the buffer space. | 12 which in turn have a compatible signature to `fread()` and `fwrite()`. |
| 16 Please refer to the API doc for the fields prefixed with `flush_` to learn more. | 13 However, due to the different pointer type, the function pointers do not type check out of the box. |
| 14 For convenience, the macros `cxBufferReadFunc` and `cxBufferWriteFunc` are defined, which perform the necessary cast. | |
| 17 | 15 |
| 18 ## Example | 16 ## Example |
| 19 | 17 |
| 20 <warning> | 18 <warning> |
| 21 TODO: add example | 19 TODO: add example |
| 95 int cxBufferGet(CxBuffer *buffer); | 93 int cxBufferGet(CxBuffer *buffer); |
| 96 | 94 |
| 97 bool cxBufferEof(const CxBuffer *buffer); | 95 bool cxBufferEof(const CxBuffer *buffer); |
| 98 ``` | 96 ``` |
| 99 | 97 |
| 100 <warning> | 98 The function `cxBufferRead()` reads `nitems` number of items of `size` bytes each from the `buffer` |
| 101 TODO: document | 99 and stores them into the memory pointed to by `ptr`, which must be sufficiently large to hold the contents. |
| 102 </warning> | 100 The function returns the actual bytes read, which might be lower, if the desired number of items is not available. |
| 101 | |
| 102 The function `cxBufferGet()` is a `fgetc()`-like function which returns the next byte in the buffer converted to an `int`. | |
| 103 Similar to `fgetc()` it returns `EOF` when there are no more bytes in the buffer. | |
| 104 | |
| 105 When all bytes from the buffer have been read, the function `cxBufferEof()` returns true. | |
| 106 | |
| 107 All read functions advance the position in the buffer by the number of read bytes. | |
| 108 | |
| 109 > When you want to read from a buffer that you previously used for writing, do not forget to set the position | |
| 110 > in the buffer to zero, e.g. by calling `cxBufferSeek()`. | |
| 103 | 111 |
| 104 ## Reset and Clear | 112 ## Reset and Clear |
| 105 | 113 |
| 106 ```C | 114 ```C |
| 107 #include <cx/buffer.h> | 115 #include <cx/buffer.h> |
