comparison: docs/Writerside/topics/buffer.h.md
docs/Writerside/topics/buffer.h.md
- changeset 1430
- 5917ed4e5a79
- parent 1424
- 563033aa998c
equal
deleted
inserted
replaced
| 1429:6e0c3a8a914a | 1430:5917ed4e5a79 |
|---|---|
| 264 The function `cxBufferShift()` moves the contents within the buffer by the specified `shift` offset, | 264 The function `cxBufferShift()` moves the contents within the buffer by the specified `shift` offset, |
| 265 where a negative offset means a shift to the left, and a positive offset means a shift to the right. | 265 where a negative offset means a shift to the left, and a positive offset means a shift to the right. |
| 266 It also adjusts the current position within the buffer, and in the case of a right shift also the size, by the same offset. | 266 It also adjusts the current position within the buffer, and in the case of a right shift also the size, by the same offset. |
| 267 | 267 |
| 268 Data shifted to the left is always discarded when the new position of a byte would be smaller than zero. | 268 Data shifted to the left is always discarded when the new position of a byte would be smaller than zero. |
| 269 If the new position would be smaller than zero, it is set exactly to zero. | 269 When bytes are discarded, the new position of the buffer is set to zero. |
| 270 | 270 |
| 271 When data is shift to the right, the behavior depends on the `CX_BUFFER_AUTO_EXTEND` flag. | 271 When data is shift to the right, the behavior depends on the `CX_BUFFER_AUTO_EXTEND` flag. |
| 272 If set, the function extends the buffer's capacity before moving the data. | 272 If set, the function extends the buffer's capacity before moving the data. |
| 273 Otherwise, the function discards all data that would exceed the buffer's capacity, and both the size and the position are equal to the capacity | 273 Otherwise, the function discards all data that would exceed the buffer's capacity, and both the size and the position are equal to the capacity |
| 274 (which means, `cxBufferEof()` returns `true` after the operation). | 274 (which means, `cxBufferEof()` returns `true` after the operation). |
| 306 > By combining the `CX_BUFFER_AUTO_EXTEND` flag and the `threshold` setting, | 306 > By combining the `CX_BUFFER_AUTO_EXTEND` flag and the `threshold` setting, |
| 307 > you can create a buffer that initially starts with a small capacity, grows up to a certain threshold, | 307 > you can create a buffer that initially starts with a small capacity, grows up to a certain threshold, |
| 308 > and starts flushing only when that threshold is exceeded. | 308 > and starts flushing only when that threshold is exceeded. |
| 309 | 309 |
| 310 Flushing happens by invoking the `wfunc` up to `blkmax` times, writing up to `blksize` bytes from the buffer to the `target` with each call. | 310 Flushing happens by invoking the `wfunc` up to `blkmax` times, writing up to `blksize` bytes from the buffer to the `target` with each call. |
| 311 The target might not accept all bytes (i.e. the `wfunc` return value indicates that fewer items have been written than requested), | 311 The target might not accept all bytes (i.e., the `wfunc` return value indicates that fewer items have been written than requested), |
| 312 in which case the remaining data remains in the buffer. | 312 in which case the remaining data remains in the buffer. |
| 313 That means the buffer is effectively [shifted](#shift-contents) left by the number of successfully flushed bytes. | 313 That means the buffer is effectively [shifted](#shift-contents) left by the number of successfully flushed bytes. |
| 314 | 314 |
| 315 > When you write large amounts of data to a buffer, multiple flush cycles might happen. | 315 > When you write large amounts of data to a buffer, multiple flush cycles might happen. |
| 316 > After the first flush operations are completed, the reclaimed space in the buffer is filled first, but if that | 316 > After the first flush operations are completed, the reclaimed space in the buffer is filled first, but if that |
| 317 > is not enough, another flush may be triggered within the same invocation of the write operation. | 317 > is not enough, another flush may be triggered within the same invocation of the write operation. |
| 318 > | 318 > |
| 319 > That means as much data is written to the buffer and/or flushed as possible, until neither the flush target nor the buffer accept more data. | 319 > That means as much data is written to the buffer and/or flushed as possible, until neither the flush target nor the buffer accept more data. |
| 320 >{style="note"} | 320 > {style="note"} |
| 321 | 321 |
| 322 > The function `cxBufferFlush()` simply returns zero when flushing was not enabled via `cxBufferEnableFlushing()`. | 322 > The function `cxBufferFlush()` simply returns zero when flushing was not enabled via `cxBufferEnableFlushing()`. |
| 323 | 323 |
| 324 <seealso> | 324 <seealso> |
| 325 <category ref="apidoc"> | 325 <category ref="apidoc"> |
