diff options
Diffstat (limited to 'libparc/parc/algol/parc_Buffer.h')
| -rw-r--r-- | libparc/parc/algol/parc_Buffer.h | 1665 |
1 files changed, 1665 insertions, 0 deletions
diff --git a/libparc/parc/algol/parc_Buffer.h b/libparc/parc/algol/parc_Buffer.h new file mode 100644 index 00000000..2c7f56fd --- /dev/null +++ b/libparc/parc/algol/parc_Buffer.h @@ -0,0 +1,1665 @@ +/* + * Copyright (c) 2017 Cisco and/or its affiliates. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at: + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @file parc_Buffer.h + * @ingroup memory + * @brief An indexable, linear buffer of bytes. + * + * A `PARCBuffer` is a linear, finite sequence of bytes. + * The essential properties of a buffer are its content, its capacity, limit, and position: + * + * @htmlonly + * <svg xmlns="http://www.w3.org/2000/svg" xmlns:xl="http://www.w3.org/1999/xlink" xmlns:dc="http://purl.org/dc/elements/1.1/" version="1.1" viewBox="48 143 304 126" width="304pt" height="126pt"> + * <defs> + * <font-face font-family="Helvetica Neue" font-size="10" panose-1="2 0 5 3 0 0 0 2 0 4" units-per-em="1000" underline-position="-100" underline-thickness="50" slope="0" x-height="517" cap-height="714" ascent="951.99585" descent="-212.99744" font-weight="500"> + * <font-face-src> + * <font-face-name name="HelveticaNeue"/> + * </font-face-src> + * </font-face> + * <marker orient="auto" overflow="visible" markerUnits="strokeWidth" id="FilledArrow_Marker" viewBox="-1 -4 10 8" markerWidth="10" markerHeight="8" color="black"> + * <g> + * <path d="M 8 0 L 0 -3 L 0 3 Z" fill="currentColor" stroke="currentColor" stroke-width="1"/> + * </g> + * </marker> + * </defs> + * <g stroke="none" stroke-opacity="1" stroke-dasharray="none" fill="none" fill-opacity="1"> + * <title>icon_512x512</title> + * <rect fill="white" width="512" height="512"/> + * <g> + * <title>Layer 1</title> + * <text transform="translate(73 231.5)" fill="black"> + * <tspan font-family="Helvetica Neue" font-size="10" font-weight="500" x=".055" y="10" textLength="13.37">Off</tspan> + * <tspan font-family="Helvetica Neue" font-size="10" font-weight="500" x="13.425" y="10" textLength="13.52">set</tspan> + * </text> + * <text transform="translate(178.5 231)" fill="black"> + * <tspan font-family="Helvetica Neue" font-size="10" font-weight="500" x=".445" y="10" textLength="36.11">Position</tspan> + * <tspan font-family="Helvetica Neue" font-size="10" font-weight="500" x="7.2" y="22" textLength="22.6">Mark</tspan> + * </text> + * <text transform="translate(294 231.5)" fill="black"> + * <tspan font-family="Helvetica Neue" font-size="10" font-weight="500" x=".16" y="10" textLength="21.68">Limit</tspan> + * </text> + * <text transform="translate(271 157.5)" fill="black"> + * <tspan font-family="Helvetica Neue" font-size="10" font-weight="500" x=".185" y="10" textLength="39.63">Capacity</tspan> + * </text> + * <text transform="translate(83 157.5)" fill="black"> + * <tspan font-family="Helvetica Neue" font-size="10" font-weight="500" x=".245" y="10" textLength="23.51">Array</tspan> + * </text> + * <path d="M 78 165.48333 C 73.6671 165.98884 67.757544 163.49623 65 167 C 63.49089 168.91749 62.925312 172.63153 62.52875 176.66717" marker-end="url(#FilledArrow_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/> + * <rect x="59" y="187" width="281" height="13" fill="#205469"/> + * <rect x="59" y="187" width="281" height="13" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/> + * <path d="M 316 166.11628 C 321.9994 166.74412 330.42197 164.60163 334 168 C 335.8631 169.76954 336.41326 173.04195 336.67595 176.64326" marker-end="url(#FilledArrow_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/> + * <rect x="116" y="181" width="160" height="27" fill="#f60"/> + * <rect x="116" y="181" width="160" height="27" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/> + * <path d="M 105 234.05085 C 108.6663 233.3673 114.16685 236.34137 116 232 C 117.15073 229.27477 116.856755 223.66586 116.47841 217.88884" marker-end="url(#FilledArrow_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/> + * <path d="M 289 235.56897 C 284.6671 235.04603 278.16645 238.59437 276 234 C 274.57827 230.98495 275.02256 224.46193 275.496 217.88448" marker-end="url(#FilledArrow_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/> + * <line x1="173.5" y1="232.84568" x2="125.08789" y2="211.92687" marker-end="url(#FilledArrow_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/> + * <line x1="220.5" y1="232.58861" x2="266.94855" y2="212.01014" marker-end="url(#FilledArrow_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/> + * </g> + * </g> + * </svg> + * @endhtmlonly + * + * * A buffer's capacity is the number of bytes it contains. + * The capacity of a buffer is never negative and never changes. + * + * * A buffer's limit is the index of the first byte that should not be read or written. + * A buffer's limit is never negative and is never greater than its capacity. + * + * * A buffer's position is a cursor to or index of the next byte to be read or written. + * A buffer's position is never negative and is never greater than its limit. + * + * A PARCBuffer's capacity may be larger than the extent of data manipulated by the buffer. + * The extent of the data manipulated by the buffer is manipulated via: + * * {@link parcBuffer_Position}, + * * {@link parcBuffer_SetPosition}, + * * {@link parcBuffer_Limit}, + * * {@link parcBuffer_SetLimit} and + * * {@link parcBuffer_Flip}. + * + * Strictly speaking, these relations are always true: _0 <= mark <= position <= limit <= capacity_ + * + * The general model for use is to: + * * Create a buffer using a form of {@link parcBuffer_Allocate} or {@link parcBuffer_Wrap}. + * * Optionally insert data into the buffer via put operations, + * ultimately setting the position at the end of the valid data. + * * 'Flip' the buffer using the {@link parcBuffer_Flip} function to set the position to 0 and the limit at the end + * of the valid data. + * * Optionally get data from the buffer via one of the many get operations. + * * Use {@link parcBuffer_Rewind} function to set the position to 0 again, leaving the limit at the end of the valid data. + * + * Data is placed into a `PARCBuffer` via `Put` functions, and retreived from the buffer via `Get` operations. + * Both `Put` and `Get` perform their operations at the position of the buffer and update the position to the location of the + * next element of data. + * Both `Put` and `Get` operations have a full compliment of intrinsic data types that operate on data at + * relative positions in the buffer. + * + * The function {@link parcBuffer_GetAtIndex} provides absolute index access to the buffer for bytes. + * + * * {@link parcBuffer_PutUint8}, + * * {@link parcBuffer_PutUint16}, + * * {@link parcBuffer_PutUint32}, + * * {@link parcBuffer_PutUint64}, + * * {@link parcBuffer_PutAtIndex} + * + * * {@link parcBuffer_GetUint8}, + * * {@link parcBuffer_GetUint16}, + * * {@link parcBuffer_GetUint32}, + * * {@link parcBuffer_GetUint64}, + * * {@link parcBuffer_GetAtIndex} + * + */ +#ifndef libparc_parc_Buffer_h +#define libparc_parc_Buffer_h + +typedef struct parc_buffer PARCBuffer; + +#include <parc/algol/parc_Object.h> +#include <parc/algol/parc_ByteArray.h> + +extern parcObjectDescriptor_Declaration(PARCBuffer); + +#ifdef PARCLibrary_DISABLE_VALIDATION +# define parcBuffer_OptionalAssertValid(_instance_) +#else +# define parcBuffer_OptionalAssertValid(_instance_) parcBuffer_AssertValid(_instance_) +#endif + +/** + * Assert that an instance of `PARCBuffer` is valid. + * + * If the instance is not valid, terminate via `trapIllegalValue()` + * + * Valid means the internal state of the type is consistent with its required current or future behaviour. + * This may include the validation of internal instances of types. + * + * @param [in] instance A pointer to a `PARCBuffer` instance. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(64); + * + * parcBuffer_AssertValid(array); + * } + * @endcode + * @see parcBuffer_OptionalAssertValid + */ +void parcBuffer_AssertValid(const PARCBuffer *instance); + +/** + * Determine if an instance of `PARCBuffer` is valid. + * + * + * Valid means the internal state of the type is consistent with its required current or future behaviour. + * This may include the validation of internal instances of types. + * + * @param [in] buffer A pointer to a `PARCBuffer` instance. + * + * @return true The instance is valid. + * @return false The instance is not valid. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(64); + * + * if (parcBuffer_IsValid(buffer)) { + * printf("Buffer is valid.\n"); + * } + * } + * @endcode + */ +bool parcBuffer_IsValid(const PARCBuffer *buffer); + +/** + * Create a new instance of `PARCBuffer` using dynamically allocated memory. + * + * The new buffer's position will be zero, + * its limit will be set to `length`, + * its mark will be undefined, + * and each of its elements will be initialized to zero. + * + * If capacity is zero, the buffer contains no underlying byte array. + * + * @param [in] capacity The number of bytes to allocate. + * + * @return NULL Memory could not be allocated. + * @return non-NULL A pointer to a `PARCBuffer` instance. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(64); + * + * parcBuffer_Release(&&buffer); + * } + * @endcode + */ +PARCBuffer *parcBuffer_Allocate(size_t capacity); + +/** + * Create a new instance of `PARCBuffer` using using program supplied static memory (rather than allocated). + * + * The new buffer will be backed by the given array, @p array. + * Modifications to the buffer will cause the array to be modified and vice versa. + * + * The new buffer's capacity will be @p arrayLength, + * its initial position will be @p position , + * the index of the first byte that should not be read or written will be @p limit, + * and its mark will be undefined. + * + * In all cases, _0 <= position <= limit <= capacity_ + * + * Its backing array will be the given array, starting at index 0 of that array. + * + * @param [in] array A pointer to a memory array. + * @param [in] arrayLength The length, in `uint8_t` units, of the memory array. + * @param [in] position The initial value for the buffer's position. + * @param [in] limit The initial value for the buffer's limit. + * + * @return A `PARCBuffer` pointer. + * + * Example: + * @code + * { + * uint8_t array[64]; + * + * PARCBuffer *buffer = parcBuffer_Wrap(array, sizeof(array), 0, sizeof(array)); + * + * parcBuffer_Release(&buffer); + * } + * @endcode + * + * @see parcBuffer_Allocate + * @see parcBuffer_Release + */ +PARCBuffer *parcBuffer_Wrap(void *array, size_t arrayLength, size_t position, size_t limit); + +/** + * Create a new instance of `PARCBuffer` using referencing the given {@link PARCByteArray}. + * + * A reference to the `PARCByteArray` is acquired. + * + * The new buffer will be backed by the given `PARCByteArray`. + * Modifications to the buffer will cause the array to be modified and vice versa. + * + * The new buffer's capacity will be @p arrayLength, + * its initial position will be @p position , + * the index of the first byte that should not be read or written will be @p limit, + * and its mark will be undefined. + * + * In all cases, _0 <= position <= limit <= capacity_ + * + * The new buffer's + * capacity will be the length of the `PARCByteArray`, + * its initial position will be @p position , + * the index of the first byte that should not be read or written will be @p limit, + * and its mark will be undefined. + * + * @param [in] byteArray A pointer to a `PARCByteArray` instance. + * @param [in] position The initial value for the buffer's position. + * @param [in] limit The initial value for the buffer's limit which must be less than or equal to the PARCByteArray's capacity. + * + * @return A `PARCBuffer` pointer. + * + * Example: + * @code + * { + * PARCByteArray *array = parcByteArray_Allocate(64); + * + * PARCBuffer *buffer = parcBuffer_WrapByteArray(array, 0, parcByteArray_Capacity(array)); + * + * parcBuffer_Release(&&buffer); + * } + * @endcode + * + * @see parcBuffer_Allocate + * @see parcBuffer_Wrap + */ +PARCBuffer *parcBuffer_WrapByteArray(PARCByteArray *byteArray, size_t position, size_t limit); + +/** + * Create a new instance of `PARCBuffer` wrapping the given null-terminated C string as its value. + * + * The new buffer's capacity will be the length of the string excluding the terminating nul character. + * its initial position will be 0, + * the index of the first byte that should not be read or written will be @p limit, + * and its mark will be undefined. + * + * @param [in] string A pointer to a C-string to copy and then wrap. + * + * @return A `PARCBuffer` pointer. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_WrapCString("Hello World"); + * + * parcBuffer_Release(&buffer); + * } + * @endcode + * + * @see parcBuffer_Allocate + * @see parcBuffer_Wrap + */ +PARCBuffer *parcBuffer_WrapCString(char *string); + +/** + * Create a new instance of a `PARCBuffer` copying the given null-terminated C string as its value. + * + * The new buffer's capacity will be the length of the string excluding the terminating nul character. + * its initial position will be 0, + * the index of the first byte that should not be read or written will be @p limit, + * and its mark will be undefined. + * + * @param [in] string A pointer to C-string to copy and then wrap. + * + * @return A `PARCBuffer` pointer. + * + * Example: + * @code + * { + * PARCByteArray *buffer = parcBuffer_AllocateCString("test string"); + * + * parcBUffer_Release(&buffer); + * } + * @endcode + */ +PARCBuffer *parcBuffer_AllocateCString(const char *string); + +/** + * Create a `PARCBuffer` initalised with a copy of the contents of given byte array. + * + * The length must be non-negative (> 0) and the array pointer must not be NULL. + * The contents of the given array are used to initialize the `PARCBuffer` instance, + * and the size of the new instance is equal to the specified length (just wide enough to fit the array). + * + * @param [in] bytes A pointer to an array of bytes. + * @param [in] length The number of bytes to copy to the `PARCBuffer`. + * + * @return A newly allocated `PARCBuffer` instance that must be freed via `parcBuffer_Release()`. + * + * Example: + * @code + * { + * unsigned char array[] = { 1, 2, 3, 4, 5 }; + * PARCBuffer *buffer = parcBuffer_CreateFromArray(array, sizeof(array)); + * + * parcBuffer_Release(&buffer); + * } + * @endcode + */ +PARCBuffer *parcBuffer_CreateFromArray(const void *bytes, size_t length); + +/** + * Parse a null-terminated hexadecimal string to create a new `PARCBuffer` instance. + * + * The hex string must be null-terminated so parsing is deterministic and correct. + * The hex string parameter is not modified in any way. + * The hex string must be an even length greater than zero. + * + * @param [in] hexString The hex string to parse. + * + * @return NULL The string could not be parsed + * @return A new `PARCElasticBuffer` instance. + * + * Example: + * @code + * { + * char *expected = "0123456789ABCDEF"; + * PARCBuffer *buffer = parcBuffer_Flip(parcBuffer_ParseHexString(expected)); + * printf("String: %s\n", parcBuffer_ToString(buffer)); + * + * parcBuffer_Release(buffer); + * } + * @endcode + */ +PARCBuffer *parcBuffer_ParseHexString(const char *hexString); + +/** + * Increase or decrease the capacity of an existing PARCBuffer. + * + * If the new capacity is greater than the old capacity and the limit is currently set to the old capacity, + * then set the new limit to the new capacity. + * Otherwise, if the limit is not currently set to the capacity, then leave the limit unchanged. + * + * If the new capacity is less than the old capacity and the limit is currently set to the old capacity, + * then set the new limit to the new capacity. + * Otherwise, set the limit to the the lesser of the old limit or the new capacity. + * If the limit is not currently set to the capacity, + * the set the limit to the the lesser of the old limit or the new capacity. + * + * If the original mark exceeds the new limit, the new mark is invalidated and any subsequent + * operation on the resulting `PARCBuffer` that requires the mark will abort until the mark + * is set again via `parcBuffer_Mark`. + * + * If the original position of the buffer is beyond the new limit of the buffer, the position is set to the new limit. + * + * The contents of the old buffer are preserved from the origin to the new limit. + * + * This operation may induce a memory copy. + * As a consequence, any `PARCBuffer` instances previously created via {@link parcBuffer_Slice} + * refer to memory previously used by this `PARCBuffer`. + * + * A PARCBuffer originally created via any of the `parcBuffer_Wrap` forms, + * may no longer refer to the original wrapped data. + * + * @param [in] buffer A pointer to a valid `PARCBuffer` instance. + * @param [in] capacity The new capacity of `PARCBuffer` + * + * @return PARCBuffer A new `PARCBuffer` instance initialized with the contents of the given buffer. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_WrapCString("Hello World"); + * parcBuffer_Resize(buffer, 4); + * + * parcBuffer_Release(&buffer); + * } + * @endcode + * + * @see parcBuffer_Allocate + * @see parcBuffer_Wrap + */ +PARCBuffer *parcBuffer_Resize(PARCBuffer *buffer, size_t capacity); + +/** + * Increase the number of references to a `PARCBuffer`. + * + * Note that new `PARCBuffer` is not created, + * only that the given `PARCBuffer` reference count is incremented. + * Discard the reference by invoking `parcBuffer_Release`. + * + * @param [in] buffer A pointer to a `PARCBuffer` instance. + * + * @return The input `PARCBuffer` pointer. + * + * Example: + * @code + * { + * PARCBuffer *x = parcBuffer_Allocate(10); + * + * PARCBuffer *x_2 = parcBuffer_Acquire(x); + * + * parcBuffer_Release(&x); + * parcBuffer_Release(&x_2); + * } + * @endcode + */ +PARCBuffer *parcBuffer_Acquire(const PARCBuffer *buffer); + +/** + * Release a previously acquired reference to the specified instance, + * decrementing the reference count for the instance. + * + * The pointer to the instance is set to NULL as a side-effect of this function. + * + * If the invocation causes the last reference to the instance to be released, + * the instance is deallocated and the instance's implementation will perform + * additional cleanup and release other privately held references. + * + * @param [in,out] bufferPtr A pointer to a pointer to the instance to release. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * + * parcBuffer_Release(&buffer); + * } + * @endcode + */ +void parcBuffer_Release(PARCBuffer **bufferPtr); + +/** + * Returns this buffer's capacity. + * + * @param [in] buffer A pointer to a `PARCBuffer` instance. + * + * @return The given buffer's capacity. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * + * size_t capacity = parcBuffer_Capacity(buffer); + * + * parcBuffer_Release(&capacity); + * } + * @endcode + */ +size_t parcBuffer_Capacity(const PARCBuffer *buffer); + +/** + * Clear the given buffer restoring it to its initial state: + * The position is set to zero, + * the limit is set to the capacity, + * and the mark is invalidated. + * + * The mark is made invalid and any subsequent operation on the resulting + * `PARCBuffer` that requires the mark will abort until the mark + * is set again via `parcBuffer_Mark`. + * + * @param [in,out] buffer A pointer to a `PARCBuffer` instance. + * + * @return The value of @p buffer. + * + * Example: + * @code + * { + * parcBuffer_Clear(buffer); + * } + * @endcode + */ +PARCBuffer *parcBuffer_Clear(PARCBuffer *buffer); + +/** + * Determine if two `PARCBuffer` instances are equal. + * + * The following equivalence relations on non-null `PARCBuffer` instances are maintained: * + * * It is reflexive: for any non-null reference value x, `parcBuffer_Equals(x, x)` must return true. + * + * * It is symmetric: for any non-null reference values x and y, `parcBuffer_Equals(x, y)` must return true if and only if + * `parcBuffer_Equals(y x)` returns true. + * + * * It is transitive: for any non-null reference values x, y, and z, if + * `parcBuffer_Equals(x, y)` returns true and + * `parcBuffer_Equals(y, z)` returns true, + * then `parcBuffer_Equals(x, z)` must return true. + * + * * It is consistent: for any non-null reference values x and y, multiple invocations of `parcBuffer_Equals(x, y)` + * consistently return true or consistently return false. + * + * * For any non-null reference value x, `parcBuffer_Equals(x, NULL)` must return false. + * + * + * @param [in] x A pointer to a `PARCBuffer` instance. + * @param [in] y A pointer to a `PARCBuffer` instance. + * + * @return true `PARCBuffers` x and y are equal. + * @return false `PARCBuffers` x and y are not equal. + * + * Example: + * @code + * { + * PARCBuffer *bufferA = parcBuffer_Allocate(10); + * PARCBuffer *bufferB = parcBuffer_Allocate(10); + * + * if (parcBuffer_Equals(bufferA, bufferB)) { + * printf("Buffers are equal.\n"); + * } else { + * printf("Buffers are NOT equal.\n"); + * } + * + * parcBuffer_Release(&bufferA); + * parcBuffer_Release(&bufferB); + * } + * @endcode + * + * @see parcBuffer_HashCode + */ +bool parcBuffer_Equals(const PARCBuffer *x, const PARCBuffer *y); + +/** + * Compares instance a with instance b for order. + * + * Returns a negative integer, zero, or a positive integer as instance + * a is less than, equal to, or greater than instance b. + * + * The buffer's position, limit, and mark are not modified. + * + * @param [in] a A pointer to the first instance of `PARCBuffer`. + * @param [in] b A pointer to the second instance of `PARCBuffer`. + * + * @return <0 Instance a is less than instance b. + * @return 0 Instance a and instance b compare the same. + * @return >0 Instance a is greater than instance b. + * + * Example: + * @code + * { + * PARCBuffer *bufferA = parcBuffer_Allocate(10); + * PARCBuffer *bufferB = parcBuffer_Allocate(10); + * + * if (parcBuffer_Compare(bufferA, bufferB) == 0) { + * printf("Buffers are equal.\n"); + * } + * + * parcBuffer_Release(&bufferA); + * parcBuffer_Release(&bufferB); + * } + * @endcode + * + * @see parcBuffer_Equals + */ +int parcBuffer_Compare(const PARCBuffer *a, const PARCBuffer *b); + +/** + * Return a pointer to the {@link PARCByteArray} that backs this buffer. + * + * If this `PARCBuffer` has a capacity of zero, + * there is no array of bytes and this function returns NULL. + * + * Modifications to the contents of the `PARCByteArray` will visible to the given + * `PARCBuffer` and vice-versa. + * + * The origin of the given `PARCBuffer` may not be the same as the origin of the underlying + * `PARCByteArray`. + * Use {@link parcBuffer_ArrayOffset} to obtain the origin of the given `PARCBuffer` + * relative to the origin of the underlying `PARCByteArray` + * + * The caller must obtain its own reference to the `PARCByteArray` if it intends to store it elsewhere. + * + * Note: Many hard to find bugs can be caused by using this function. + * Use the functions provided to manipulate the `PARCBuffer` and its contents. + * + * @param [in] buffer A `PARCBuffer` pointer. + * + * @return NULL There is no `PARCByteArray` backing the given `PARCBuffer` (no capacity). + * @return non-NULL The pointer to the `PARCByteArray` for the given `PARCBuffer`. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * + * PARCByteArray *array = parcBuffer_Array(buffer); + * + * parcBuffer_Release(&buffer); + * } + * @endcode + * + * @see parcByteArray_Acquire + */ +PARCByteArray *parcBuffer_Array(const PARCBuffer *buffer); + +/** + * Create an independent copy the given `PARCBuffer` + * + * A new buffer is created as a complete copy of the original. + * + * @param [in] buffer A pointer to a `PARCBuffer` instance. + * + * @return NULL Memory could not be allocated. + * @return non-NULL A pointer to a new `PARCBuffer` instance. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * parcBuffer_PutUint8(buffer, (uint8_t)'A'); + * + * PARCBuffer *copy = parcBuffer_Copy(buffer); + * + * parcBuffer_Release(©); + * parcBuffer_Release(&buffer); + * } + * @endcode + * + */ +PARCBuffer *parcBuffer_Copy(const PARCBuffer *buffer); + +/** + * Creates a new buffer that shares the original buffer's content. + * + * The content of the new buffer will be that of this buffer. + * Changes to the buffer's content will be visible in both buffers, + * however the two buffers' position, limit, and mark values will be independent. + * + * The new buffer's capacity, limit, position, and mark values will be identical to those of the original buffer. + * + * @param [in] original The orignal PARCBuffer instance that will be duplicated. + * + * @return NULL Memory could not be allocated. + * @return non-NULL A pointer to ta valid `PARCBuffer` instance. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * parcBuffer_Duplicate(buffer2); + * + * parcBuffer_Release(&buffer); + * parcBuffer_Release(&buffer2); + * } + * @endcode + */ +PARCBuffer *parcBuffer_Duplicate(const PARCBuffer *original); + +/** + * Returns the offset within this buffer's backing {@link PARCByteArray} of the first element. + * + * Buffer position <i>p</i> corresponds to array index <i>p + arrayOffset()</i>. + * + * @param [in] buffer A pointer to a `PARCBuffer` instance. + * + * @return `size_t` The offset within this `PARCBuffer`'s array of the first element of the buffer + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * parcBuffer_PutUint8(buffer, (uint8_t)'A'); + * + * size_t arrayOffset = parcBuffer_ArrayOffset(buffer); + * // offset will be 0 since the contents of the buffer start at the beginning + * + * parcBuffer_Release(&buffer); + * } + * @endcode + */ +size_t parcBuffer_ArrayOffset(const PARCBuffer *buffer); + +/** + * Rewinds this `PARCBuffer`: The position is set to zero and the mark is invalidated. + * + * The mark is made invalid and any subsequent operation on the resulting + * `PARCBuffer` that requires the mark will abort until the mark + * is set again via `parcBuffer_Mark`. + * + * @param [in,out] buffer A pointer to a `PARCBuffer` instance. + * + * @return The given `PARCBuffer` pointer. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * parcBuffer_PutUint8(buffer, (uint8_t)'A'); + * + * parcBuffer_Rewind(buffer); // bring it back to zero + * + * parcBuffer_Release(&buffer); + * } + * @endcode + */ +PARCBuffer *parcBuffer_Rewind(PARCBuffer *buffer); + +/** + * Resets the given `PARCBuffer`'s position to the previously-marked position. + * + * Invoking this method neither changes nor invalidates the mark's value. + * + * @param [in,out] buffer A pointer to a `PARCBuffer` instance. + * + * @return The given `PARCBuffer` pointer. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * parcBuffer_PutUint8(buffer, (uint8_t)'A'); + * + * buffer = parcBuffer_Reset(buffer); + * + * parcBuffer_Release(&buffer); + * } + * @endcode + */ +PARCBuffer *parcBuffer_Reset(PARCBuffer *buffer); + +/** + * Return the given `PARCBuffer`'s limit. + * + * A buffer's limit is the index of the first element that should not be read or written. + * A buffer's limit is never negative and is never greater than its capacity. + * + * @param [in] buffer A pointer to a `PARCBuffer` instance. + * + * @return The given `PARCBuffer`'s limit. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * parcBuffer_PutUint8(buffer, (uint8_t)'A'); + * + * size_t limit = parcBuffer_Limit(buffer); + * // limit will be 10 + * + * parcBuffer_Release(&buffer); + * } + * @endcode + */ +size_t parcBuffer_Limit(const PARCBuffer *buffer); + +/** + * Sets this buffer's mark at its position. + * + * @param [in,out] buffer A pointer to a `PARCBuffer` instance. + * + * @return The value of @p buffer. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * parcBuffer_PutUint8(buffer, (uint8_t)'A'); + * parcBuffer_Mark(buffer); + * // since the position was 0, the mark remains at 0 + * + * ... + * + * parcBuffer_Release(&buffer); + * } + * @endcode + */ +PARCBuffer *parcBuffer_Mark(PARCBuffer *buffer); + +/** + * Sets this `PARCBuffer`'s limit. + * + * If the position is larger than the new limit then it is set to the new limit. + * + * If the mark is defined and larger than the new limit then the mark is invalidated and + * any subsequent operation that requires the mark will abort until the mark + * is set again via `parcBuffer_Mark` + * + * @param [in,out] buffer A pointer to a `PARCBuffer` instance. + * @param newLimit The new limit value; must be no larger than this `PARCBuffer`'s capacity. + * + * @return The given `PARCBuffer` pointer. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * parcBuffer_PutUint8(buffer, (uint8_t)'A'); + * + * parcBuffer_SetLimit(buffer, 8); + * + * size_t limit = parcBuffer_Limit(buffer); + * size_t capacity = parcBuffer_Capacity(buffer); + * // capacity is 10, limit is 8 + * + * ... + * + * parcBuffer_Release(&buffer); + * } + * @endcode + */ +PARCBuffer *parcBuffer_SetLimit(PARCBuffer *buffer, size_t newLimit); + +/** + * Return a pointer to buffer memory starting the buffer's current position. + * + * The @p length parameter must be less than or equal to the remaining bytes in the buffer + * and has no effect on the return value, + * except that if the buffer's position is equal to the limit, then this traps with OutOfBounds + * + * The current position of the buffer is advanced by @p length bytes. + * It is acceptable for the @p length parameter to be zero, + * thereby causing the current position to remain unchanged. + * + * This does not guarantee any particular memory alignment. + * Therefore, it is possible to obtain a pointer to memory that cannot be accessed + * as a native type because of CPU architecture alignment requirements. + * + * The function returns a pointer to contiguous memory within a `PARCBuffer`, + * but does not acquire a reference to the `PARCBuffer` instance, + * the underlying {@link PARCByteArray}, nor the actual memory array. + * If the {@link PARCBuffer} or the underlying {@link PARCByteArray} is released finally, + * the result from a previous call to `parcBuffer_Overlay` will point to undefined values. + * + * @param [in,out] buffer A pointer to a `PARCBuffer` instance. + * @param [in] length The number of bytes to advance the buffer's position. + * + * @return non-NULL A pointer to memory. + * + * Example: + * @code + * { + * char *expected = "Hello World"; + * struct timeval theTime = { .tv_sec = 123, .tv_usec = 456}; + * + * PARCBuffer *buffer = parcBuffer_Allocate(sizeof(uint16_t) + strlen(expected) + sizeof(theTime)); + * + * parcBuffer_PutUint16(buffer, strlen(expected)); + * parcBuffer_PutUint8(buffer, expected, strlen(expected)); + * parcBuffer_PutUint8(buffer, &theTime, sizeof(theTime)); + * parcBuffer_Flip(); + * + * uint16_t length = parcBuffer_GetUint16(buffer); + * char *actual = parcBuffer_Overlay(buffer, length); + * struct timeval *tm = parcBuffer_Overlay(buffer, sizeof(struct timeval)); + * } + * @endcode + */ +void *parcBuffer_Overlay(PARCBuffer *buffer, size_t length); + +/** + * Return the given `PARCBuffer`'s position. + * + * A buffer's position is the index of the next element to be read or written. + * A buffer's position is never negative and is never greater than its limit. + * + * @param [in] buffer A pointer to a `PARCBuffer` instance. + * @return The given `PARCBuffer`'s position. + * + * Example: + * @code + * { + * size_t currentPosition = parcBuffer_Position(buffer); + * } + * @endcode + * + * @see parcBuffer_SetPosition + */ +size_t parcBuffer_Position(const PARCBuffer *buffer); + +/** + * Set the given `PARCBuffer`'s position. + * + * A buffer's position is the index of the next element to be read or written. + * A buffer's position is never negative and is never greater than its limit. + * + * If the mark is defined and larger than the new position then the mark + * is invalidated and any subsequent operation on the resulting + * `PARCBuffer` that requires the mark will abort until the mark + * is set again via `parcBuffer_Mark`. + * + * @param [in,out] buffer A pointer to a `PARCBuffer` instance. + * @param [in] newPosition The buffer's new position which must be less than or equal to the current limit. + * + * @return The given `PARCBuffer`'s position. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * parcBuffer_SetPosition(buffer, 5); + * parcBuffer_Remaining(buffer); // Returns 5. + * } + * @endcode + * + * @see parcBuffer_Limit + */ +PARCBuffer *parcBuffer_SetPosition(PARCBuffer *buffer, size_t newPosition); + +/** + * Returns the number of elements between the current position and the limit. + * + * @param [in] buffer A pointer to a `PARCBuffer` instance. + * + * @return The number of elements remaining in this `PARCBuffer`. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * parcBuffer_SetPosition(buffer, 5); + * parcBuffer_Remaining(buffer); // Returns 5. + * } + * @endcode + */ +size_t parcBuffer_Remaining(const PARCBuffer *buffer); + +/** + * Tells whether there are any elements between the current position and the limit. + * + * @param [in] buffer A pointer to a `PARCBuffer` instance. + * + * @return true The `PARCBuffer` contains at least one more element. + * @return false The `PARCBuffer` does not contain any more elements. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * parcBuffer_SetPosition(buffer, 5); + * bool hasRemaining = parcBuffer_HasRemaining(buffer); // returns true since #remaining = 5 + * } + * @endcode + */ +bool parcBuffer_HasRemaining(const PARCBuffer *buffer); + +/** + * Creates a new byte buffer whose content is a shared subsequence of this buffer's content. + * + * The content of the new buffer will start at this buffer's current position. + * Changes to this buffer's content will be visible in the new buffer, + * and vice versa; + * the two buffers' position, limit, + * and mark values will be independent. + * + * The new buffer's position will be zero, + * its capacity and its limit will be the number of bytes remaining in this buffer, + * and its mark will be undefined. + * + * @param [in] original A pointer to a `PARCBuffer` instance. + * + * @return non-NULL A pointer to a new `PARCBuffer` whose content is a shared subsequence of the original buffer's content. + * @return NULL Memory could not be allocated. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * parcBuffer_SetPosition(buffer, 5); + * parcBuffer_SetLimit(buffer, 8); + * + * PARCBuffer *slice = parcBuffer_Slice(buffer); + * // the slice will be the subset of bytes 5,6,7, and will + * // have limit and capacity of 3 (= 8 - 5) + * + * ... + * + * parcBuffer_Release(&buffer); + * parcBuffer_Release(&slice); + * } + * @endcode + */ +PARCBuffer *parcBuffer_Slice(const PARCBuffer *original); + +/** + * Set the limit to the current position, + * then set the position to zero. + * If the mark is defined, it is invalidated. + * + * Any subsequent operation that requires the mark will abort until the mark + * is set again via `parcBuffer_Mark`. + * + * @param [in,out] buffer A pointer to a `PARCBuffer` instance. + * + * @return The same value as @p buffer. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * parcBuffer_PutByte(buffer, 'X'); + * parcBuffer_Flip(buffer); + * uint8_t actual = parcBuffer_GetUint8(buffer); + * + * ... + * parcBuffer_Release(&buffer); + * } + * @endcode + */ +PARCBuffer *parcBuffer_Flip(PARCBuffer *buffer); + +/** + * Get the single `uint8_t` at the index specified. + * + * The buffer's position is not modified. + * + * @param [in] buffer A pointer to a `PARCBuffer` instance. + * @param [in] index The index into the @p buffer to find the `uint8_t`. + * + * @return The `uint8_t` value at @p index. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * parcBuffer_PutByte(buffer, 'X'); + * uint8_t actual = parcBuffer_GetAtIndex(buffer, 0); + * // actual == (uint8_t) 'X' + * + * ... + * parcBuffer_Release(&buffer); + * } + * @endcode + */ +uint8_t parcBuffer_GetAtIndex(const PARCBuffer *buffer, size_t index); + +/** + * Read the unsigned 8-bit value at the buffer's current position, + * and then increment the position by 1. + * + * @param [in] buffer The pointer to a `PARCBuffer` instance containing the `uint8_t` value. + * + * @return The `uint8_t` at the buffer's current position + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * parcBuffer_PutByte(buffer, 'X'); + * parcBuffer_Flip(buffer); + * uint8_t actual = parcBuffer_GetUint8(buffer); + * + * ... + * parcBuffer_Release(&buffer); + * } + * @endcode + * + */ +uint8_t parcBuffer_GetUint8(PARCBuffer *buffer); + +/** + * Read the unsigned 16-bit value in network order at the buffer's current position, + * and then increment the position by 2. + * + * @param [in,out] buffer The pointer to the `PARCBuffer` instance containing the value. + * + * @return The `uint16_t` at the buffer's current position. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * (buffer, 0x1234); + * parcBuffer_Flip(buffer); + * uint16_t actual = parcBuffer_GetUint16(buffer); + * } + * @endcode + * + * @see parcBuffer_Overlay + */ +uint16_t parcBuffer_GetUint16(PARCBuffer *buffer); + +/** + * Read the unsigned 32-bit value in network order at the buffer's current position, + * and then increment the position by the 4. + * + * @param [in,out] buffer The pointer to the instance of `PARCBuffer` containing the value. + * + * @return The `uint32_t` at the buffer's current position. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * parcBuffer_PutUint32(buffer, 0x12345678); + * parcBuffer_Flip(buffer); + * uint32_t actual = parcBuffer_GetUint32(buffer); + * } + * @endcode + * + * @see parcBuffer_Overlay + */ +uint32_t parcBuffer_GetUint32(PARCBuffer *buffer); + +/** + * Read the unsigned 64-bit value in network order at the buffer's current position, + * and then increment the position by 8. + * + * @param [in,out] buffer The pointer to the instance of `PARCBuffer` containing the value. + * + * @return The `uint64_t` at the buffer's current position. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * parcBuffer_PutUint64(buffer, 0x12345678); + * parcBuffer_Flip(buffer); + * uint64_t actual = parcBuffer_GetUint64(buffer); + * } + * @endcode + * + * @see parcBuffer_Overlay + */ +uint64_t parcBuffer_GetUint64(PARCBuffer *buffer); + +/** + * Read an array of length bytes from the given PARCBuffer, copying them to an array. + * + * The buffer's position is incremented by @p length. + * + * @param [in,out] buffer The pointer to the instance of `PARCBuffer` containing the `uint8_t` value. + * @param [in] length The number of `uint8_t` elements to get. + * @param [in] array The `uint8_t` array to receive @p length bytes. + * + * @return A pointer to the given `PARCBuffer` instance + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(5); + * parcBuffer_PutUint8(buffer, 'A'); + * parcBuffer_PutUint8(buffer, 'B'); + * parcBuffer_PutUint8(buffer, 'C'); + * + * uint8_t array[3]; + * parcBuffer_GetBytes(buffer, 3, array); + * // array[0] == 'A' + * // array[1] == 'B' + * // array[2] == 'C' + * } + * @endcode + * + * @see parcBuffer_Overlay + */ +PARCBuffer *parcBuffer_GetBytes(PARCBuffer *buffer, size_t length, uint8_t *array); + +/** + * Insert an unsigned 8-bit value into the given `PARCBuffer` at the current position. + * + * Advance the current position by 1. + * + * @param [in,out] buffer A pointer to the `PARCBuffer` instance. + * @param [in] value The value to be inserted into the`PARCBuffer` instance at the current position. + * @return The `PARCBuffer` + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * parcBuffer_PutByte(buffer, 'X'); + * } + * @endcode + */ +PARCBuffer *parcBuffer_PutUint8(PARCBuffer *buffer, uint8_t value); + +/** + * Insert an unsigned 16-bit value into the given `PARCBuffer` at the current position, + * in big-endian, network-byte-order. + * + * Advance the current position by 2. + * + * @param [in,out] buffer A pointer to the `PARCBuffer` instance. + * @param [in] value The value to be inserted + * @return The pointer to `PARCBuffer` + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * parcBuffer_PutUint16(buffer, 0x1234); + * } + * @endcode + */ +PARCBuffer *parcBuffer_PutUint16(PARCBuffer *buffer, uint16_t value); + +/** + * Insert an unsigned 32-bit value into the given `PARCBuffer` at the current position, + * in big-endian, network-byte-order. + * + * Advance the current position by 4. + * + * @param [in,out] buffer A pointer to the `PARCBuffer` instance. + * @param [in] value The value to be inserted + * @return The `PARCBuffer` + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * parcBuffer_PutUint32(buffer, 0x12345678); + * } + * @endcode + */ +PARCBuffer *parcBuffer_PutUint32(PARCBuffer *buffer, uint32_t value); + +/** + * Insert an unsigned 64-bit value into the given `PARCBuffer` at the current position, + * in big-endian, network-byte-order. + * + * Advance the current position by 8. + * + * @param [in,out] buffer A pointer to the `PARCBuffer` instance. + * @param [in] value The value to be inserted + * @return The `PARCBuffer` + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * parcBuffer_PutUint64(buffer, 0x1234); + * } + * @endcode + */ +PARCBuffer *parcBuffer_PutUint64(PARCBuffer *buffer, uint64_t value); + +/** + * Insert unsigned 8-bit value to the given `PARCBuffer` at given index. + * + * The buffer's position is unchanged. + * + * @param [in,out] buffer A pointer to the `PARCBuffer` instance. + * @param [in] index The index at which to insert @p value + * @param [in] value The value to be inserted + * + * @return The value of @p buffer. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * parcBuffer_PutAtIndex(buffer, 3, 'X'); + * } + * @endcode + */ +PARCBuffer *parcBuffer_PutAtIndex(PARCBuffer *buffer, size_t index, uint8_t value); + +/** + * Copy `arrayLength` bytes from the given array into the `PARCBuffer`. + * + * The position is incremented by `arrayLength` + * + * @param [in] buffer A pointer to the `PARCBuffer` instance. + * @param [in] arrayLength The number of bytes to copy into the buffer. + * @param [in] array A pointer to the array of bytes. + * + * @return The value of @p buffer. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(5); + * + * uint8_t array[3]; + * array[0] = 'A'; + * array[1] = 'B'; + * array[2] = 'C'; + * + * parcBuffer_PutArray(buffer, 3, array); + * // the buffer will now contain ['A','B','C'] at indices 0,1,2 + * } + * @endcode + */ +PARCBuffer *parcBuffer_PutArray(PARCBuffer *buffer, size_t arrayLength, const uint8_t *array); + +/** + * Copy the contents of the given nul-terminated C string into a PARCBuffer, including the terminating nul byte. + * + * The position is incremented by the length of the string plus 1. + * + * @param [in] buffer A pointer to the `PARCBuffer` instance. + * @param [in] string A pointer to nul-terminated C string. + * + * @return The value of @p buffer. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(5); + * + * char *string = "ABC"; + * + * parcBuffer_PutCString(buffer, string); + * // the buffer will now contain ['A','B','C', 0] at indices 0, 1, 2, and 3 + * } + * @endcode + */ +PARCBuffer *parcBuffer_PutCString(PARCBuffer *buffer, const char *string); + +/** + * Put the contents of a `PARCBuffer` into another. + * + * @param [in] buffer A pointer to the destination `PARCBuffer` instance. + * @param [in] source A pointer to the source `PARCBuffer` instance. + * + * @return The value of @p result. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * PARCBuffer *insertee = parcBuffer_AllocateCString("Hello"); + * parcBuffer_PutBuffer(buffer, insertee); + * // buffer will now contain "Hello" in the first 5 byte indices + * } + * @endcode + */ +PARCBuffer *parcBuffer_PutBuffer(PARCBuffer *buffer, const PARCBuffer *source); + +/** + * Returns a hash code value for the given instance. + * + * The hash code of a `PARCBuffer` depends only upon its remaining elements from the current position to the limit. + * + * Because `PARCBuffer` hash codes are content-dependent, be careful when using them as keys in `PARCHashMap` + * and other similar data structures unless it is known that their contents will not change. + * + * The general contract of `HashCode` is: + * + * Whenever it is invoked on the same instance more than once during an execution of an application, + * the `HashCode` function must consistently return the same value, + * provided no information used in a corresponding {@link parcByteArray_Equals} + * comparisons on the instance is modified. + * + * This value need not remain consistent from one execution of an application to another execution of the same application. + * If two instances are equal according to the {@link parcByteArray_Equals} method, + * then calling the {@link parcBuffer_HashCode} method on each of the two instances must produce the same integer result. + * + * It is not required that if two instances are unequal according to the {@link parcBuffer_Equals} function, + * then calling the `parcBuffer_HashCode` + * method on each of the two objects must produce distinct integer results. + * + * @param [in] buffer A pointer to the `PARCBuffer` instance. + * + * @return The hashcode for the given instance. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * uint32_t hashValue = parcBuffer_HashCode(buffer); + * parcBuffer_Release(&buffer); + * } + * @endcode + * + * @see parcByteArray_HashCode + */ +PARCHashCode parcBuffer_HashCode(const PARCBuffer *buffer); + +/** + * Return the position of the first `uint8_t` value that matches the given byte. + * + * If the value does not exist between the current position and the limit, + * return `SIZE_MAX` (<stdint.h>). + * + * @param [in] buffer A pointer to a `PARCBuffer` instance. + * @param [in] byte The byte to search for within the buffer. + * + * @return The index of the first byte equal to `byte`, or `SIZE_MAX` (<stdint.h>) + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Wrap("Hello World", 10, 0, 10); + * + * size_t ePosition = parcBuffer_FindUint8(buffer, 'e'); + * + * // ePosition is equal to 1. + * + * size_t xPosition = parcBuffer_FindUint8(buffer, 'x'); + * + * // ePosition is equal to SIZE_MAX. + * } + * @endcode + */ +size_t parcBuffer_FindUint8(const PARCBuffer *buffer, uint8_t byte); + +/** + * Produce a null-terminated string representation of the specified `PARCBuffer` + * from the current position to the limit. + * The buffer's position is not changed. + * + * The result must be freed by the caller via {@link parcMemory_Deallocate}. + * + * @param [in] buffer A pointer to the instance. + * + * @return NULL Cannot allocate memory. + * @return non-NULL A pointer to an allocated, null-terminated C string that must be deallocated via {@link parcMemory_Deallocate}. + * + * Example: + * @code + * { + * char *helloWorld = "Hello World"; + * PARCBuffer *instance = parcBuffer_Wrap(helloWorld, strlen(helloWorld), 0, strlen(helloWorld)); + * + * char *string = parcBuffer_ToString(instance); + * + * if (string != NULL) { + * printf("Hello: %s\n", string); + * parcMemory_Deallocate((void **)&string); + * } else { + * printf("Cannot allocate memory\n"); + * } + * + * parcBuffer_Release(&instance); + * } + * @endcode + * + * @see parcBuffer_Display + */ +char *parcBuffer_ToString(const PARCBuffer *buffer); + +/** + * Print a human readable representation of the given `PARCBuffer`. + * + * @param [in] indentation The level of indentation to use to pretty-print the output. + * @param [in] buffer A pointer to the instance to display. + * + * Example: + * @code + * { + * PARCBuffer *instance = parcBuffer_Create(); + * + * parcBuffer_Display(instance, 0); + * + * parcBuffer_Release(&instance); + * } + * @endcode + */ +void parcBuffer_Display(const PARCBuffer *buffer, int indentation); + +/** + * Return a null-terminated string containing the hex-byte representation of the given `PARCBuffer`. + * + * The result must be freed by the caller via `parcMemory_Deallocate()`. + * + * @param [in] buffer A pointer to a `PARCBuffer` instance. + * + * @return NULL Cannot allocate memory. + * @return non-NULL A pointer to an allocated, null-terminated C string that must be deallocated via {@link parcMemory_Deallocate}. + * + * Example: + * @code + * { + * PARCBuffer *instance = parcBuffer_Create(); + * + * char *hexString = parcBuffer_ToHexString(instance); + * parcMemory_Deallocate((void **)&hexString); + * + * parcBuffer_Release(&instance); + * } + * @endcode + * + * @see parcMemory_Deallocate + */ +char *parcBuffer_ToHexString(const PARCBuffer *buffer); + +/** + * Advance the position of the given buffer to the first byte that is not in the array @p bytesToSkipOver. + * + * The position will not exceed the PARCBuffer's limit. + * + * @param [in,out] buffer A pointer to a `PARCBuffer` instance. + * @param [in] length Length of the byte array that includes skip bytes + * @param [in] bytesToSkipOver A null-terminated array of bytes to skip. + * + * @return true The `PARCBuffer`'s position was updated. + * @return false The `PARCBuffer`'s position reached the limit. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_WrapCString("Hello World"); + * uint8_t skipOverBytes[] = { 'H', 0 }; + * + * bool actual = parcBuffer_SkipOver(buffer, 1, skipOverBytes); + * // the buffer position will now be 1, as it skipped over the 'H' byte in the array + * // actual will be true + * } + * @endcode + * + * @see parcBuffer_SkipTo + */ +bool parcBuffer_SkipOver(PARCBuffer *buffer, size_t length, const uint8_t *bytesToSkipOver); + +/** + * Advance the position of the given buffer to the first byte that is in the array @p bytesToSkipTo. + * + * The position will not exceed the PARCBuffer's limit. + * + * @param [in,out] buffer A pointer to a `PARCBuffer` instance. + * @param [in] length Length of the byte array that includes skip bytes + * @param [in] bytesToSkipTo A null-terminated array of bytes to find. + * + * @return true The PARCBuffer's position is at the first byte matched. + * @return false The PARCBuffer's position reached the limit. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_WrapCString("Hello World"); + * uint8_t skipOverBytes[] = { 'l', 0 }; + * + * bool actual = parcBuffer_SkipTo(buffer, 1, skipOverBytes); + * // the buffer position will now be set to the index of the first 'l' byte in the underlying array + * // actual will be true + * } + * @endcode + * + * @see parcBuffer_SkipOver + */ +bool parcBuffer_SkipTo(PARCBuffer *buffer, size_t length, const uint8_t *bytesToSkipTo); + +/** + * Return the byte at the given `PARCBuffers'` current position, without modifying the position. + * + * @param [in] buffer A pointer to a `PARCBuffer` instance. + * + * @return The byte at the given `PARCBuffers'` current position + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_AllocateCString("Hello"); + * uint8_t byte = parcBuffer_PeekByte(1); + * // byte == (uint8_t) 'e'; + * } + * @endcode + */ +uint8_t parcBuffer_PeekByte(const PARCBuffer *buffer); + +/** + * Parse an ASCII representation of a hexadecimal number in the given `PARCBuffer` + * + * The number may be prefixed with the characters '0', 'x'. + * The buffer's position will be left at the first non-parsable character. + * + * Overflow is not checked. + * + * @param [in] buffer A pointer to a valid `PARCBuffer` instance. + * + * @return A uint64_t of the hexadecimal number. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_WrapCString("0x10"); + * uint64_t value = parcBuffer_ParseHexNumber(buffer); + * + * parcBuffer_Release(&buffer); + * } + * @endcode + */ +uint64_t parcBuffer_ParseHexNumber(PARCBuffer *buffer); + +/** + * Parse an ASCII representation of a unsigned decimal number in the given `PARCBuffer` + * + * The buffer's position will be left at the first non-parsable character. + * + * Overflow is not checked. + * + * @param [in] buffer A pointer to a valid `PARCBuffer` instance. + * + * @return A uint64_t of the decimal number. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_WrapCString("100"); + * uint64_t value = parcBuffer_ParseDecimalNumber(buffer); + * + * parcBuffer_Release(&buffer); + * } + * @endcode + */ +uint64_t parcBuffer_ParseDecimalNumber(PARCBuffer *buffer); + +/** + * Parse an ASCII representation of a unsigned decimal number or a hexadecimal number in the given `PARCBuffer` + * + * The buffer's position will be left at the first non-parsable character. + * + * Overflow is not checked. + * + * @param [in] buffer A pointer to a valid `PARCBuffer` instance. + * + * @return A uint64_t of the number. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_WrapCString("100"); + * uint64_t value = parcBuffer_ParseNumeric(buffer); + * + * parcBuffer_Release(&buffer); + * } + * @endcode + */ +uint64_t parcBuffer_ParseNumeric(PARCBuffer *buffer); +#endif // libparc_parc_Buffer_h |