ucx: comparison docs/Writerside/topics/buffer.h.md

-:c2d05cf1a062
+:a2757c6427cc
 The above functions destroy the buffer and deallocate the buffer's memory when the `CX_BUFFER_FREE_CONTENTS` flag is set.
 The function `cxBufferDestroy()` is to be used when the buffer was initialized with `cxBufferInit()`,
 and the function `cxBufferFree()` is to be used when the buffer was created with `cxBufferCreate()`.
-The only difference is, that `cxBufferFree()` additionally deallocates the memory of the `CxBuffer` structure.
+The only difference is that `cxBufferFree()` additionally deallocates the memory of the `CxBuffer` structure.
 ## Capacity Management
 ```C
 #include <cx/buffer.h>
 plus a number of `reserve` bytes.
 If the current capacity is not larger than the size plus the reserve bytes, the function will do nothing.
 > If the buffer is in a copy-on-write state, `cxBufferMinimumCapacity()` will perform the copy-on-write action
 > before reallocating the space.
-> The function `cxBufferShrink()` on the other hand does _nothing_ when the buffer is in a copy-on-write state,
+> The function `cxBufferShrink()` on the other hand, does _nothing_ when the buffer is in a copy-on-write state,
 > because it makes little sense to copy the memory just to have it in a smaller memory region.
 ## Write
 ```C
 When the capacity of the buffer is not sufficient and the `CX_BUFFER_AUTO_EXTEND` is not set in the buffer,
 items that do not fit into the buffer are discarded.
 The function then returns the actual number of items successfully written.
 This equals the number of bytes if and only if `size=1`.
-If `CX_BUFFER_AUTO_EXTEND` is set, the buffer is grown to it's maximum capacity
+If `CX_BUFFER_AUTO_EXTEND` is set, the buffer is grown to its maximum capacity
 (see `cxBufferMaximumCapacity()` in [](#capacity-management)).
 In case the allocation for auto-extension fails, the function immediately returns zero and does not write any data.
 The function `cxBufferPut()` is a `putc()`-like wrapper for `cxBufferWrite()` which writes the character `c`,
 converted to an `unsigned char` to the buffer.
 and cause the _size_ of the buffer to grow, if necessary, to contain all written bytes.
 On the other hand, `cxBufferTerminate()` writes a zero-byte at the current position and shrinks the buffer,
 effectively creating a zero-terminated string whose size equals the buffer size.
 > If you use cxBufferTerminate() on a buffer with the `CX_BUFFER_COPY_ON_EXTEND` flag set, the shrink operation is skipped.
-> Using `cxBufferTerminate()` on a buffer with the `CX_BUFFER_COPY_ON_WRITE` flag set, will copy the entire memory just to add the zero-terminator.
+> Using `cxBufferTerminate()` on a buffer with the `CX_BUFFER_COPY_ON_WRITE` flag set will copy the entire memory just to add the zero-terminator.
 The function `cxBufferAppend()` writes the data to the end of the buffer (given by its size) regardless of the current position,
 and it also does _not_ advance the position.
 ## Read
 The function `cxBufferRead()` reads `nitems` number of items of `size` bytes each from the `buffer`
 and stores them into the memory pointed to by `ptr`, which must be large enough to hold the contents.
 The function returns the actual bytes read, which might be lower if the desired number of items is not available.
-The function `cxBufferGet()` is a `fgetc()`-like function which returns the next byte in the buffer converted to an `int`.
+The function `cxBufferGet()` is an `fgetc()`-like function which returns the next byte in the buffer converted to an `int`.
 Similar to `fgetc()` it returns `EOF` when there are no more bytes in the buffer.
 When all bytes from the buffer have been read, the function `cxBufferEof()` returns true.
 All read functions advance the position in the buffer by the number of read bytes.
-> When you want to read from a buffer that you previously used for writing, do not forget to set the position
+> When you want to read from a buffer that you previously used for writing, remember to set the position
-> in the buffer to zero, e.g. by calling `cxBufferSeek()`.
+> in the buffer to zero, e.g., by calling `cxBufferSeek()`.
 ## Reset and Clear
 ```C
 #include <cx/buffer.h>
 size_t cxBufferPop(CxBuffer *buffer,
 size_t size, size_t nitems);
 ```
-The function `cxBufferReset()` sets both size and position of the buffer to zero,
+The function `cxBufferReset()` sets both the size and position of the buffer to zero,
 and `cxBufferClear()` additionally uses `memset()` to set every byte in the buffer to zero.
 > When clearing the buffer, only the "live" data, i.e., bytes with indices `[0..size)`, are cleared.
 > If you want to clear the entire buffer's memory, you would need to set the size to the capacity, first.
 The function `cxBufferSeek()` is a `fseek()`-like function that sets the current position in the buffer
 relative to the start (when `whence` is `SEEK_SET`), the current position (when `whence` is `SEEK_CUR`),
 or end (when `whence` is `SEEK_END`) of the buffer.
-If the resulting position is negative, or larger than the size (i.e. the first unused byte),
+If the resulting position is negative, or larger than the size (i.e., the first unused byte),
 this function returns non-zero and sets `errno` to `EINVAL`.
 > Note that the behavior of `cxBufferSeek()` when seeking beyond the end of the buffer is not exactly the same as for POSIX `fseek()`.
 ## Shift Contents
 It also adjusts the current position within the buffer, and in the case of a right shift also the size, by the same offset.
 Data shifted to the left is always discarded when the new position of a byte would be smaller than zero.
 When bytes are discarded, the new position of the buffer is set to zero.
-When data is shift to the right, the behavior depends on the `CX_BUFFER_AUTO_EXTEND` flag.
+When data is shifted to the right, the behavior depends on the `CX_BUFFER_AUTO_EXTEND` flag.
 If set, the function extends the buffer's capacity before moving the data.
 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
 (which means, `cxBufferEof()` returns `true` after the operation).
 The functions `cxBufferShiftRight()` and `cxBufferShiftLeft()` accept a larger (but in both cases positive) shift offset,

Mercurial > hg > ucx / file comparison

comparison: docs/Writerside/topics/buffer.h.md

docs/Writerside/topics/buffer.h.md