diff options
Diffstat (limited to 'libparc/parc/algol/parc_ReadOnlyBuffer.h')
| -rw-r--r-- | libparc/parc/algol/parc_ReadOnlyBuffer.h | 834 |
1 files changed, 834 insertions, 0 deletions
diff --git a/libparc/parc/algol/parc_ReadOnlyBuffer.h b/libparc/parc/algol/parc_ReadOnlyBuffer.h new file mode 100644 index 00000000..39dd6aa8 --- /dev/null +++ b/libparc/parc/algol/parc_ReadOnlyBuffer.h @@ -0,0 +1,834 @@ +/* + * 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_ReadOnlyBuffer.h + * @ingroup memory + * @brief An indexable, linear buffer of read-only bytes. + * + * A `PARCReadOnlyBuffer` is a {@link PARCBuffer} that cannot be modified, + * but retains a position, limit and capacity. + * + */ +#ifndef libparc_parc_ReadOnlyBuffer_h +#define libparc_parc_ReadOnlyBuffer_h + +#include <parc/algol/parc_Buffer.h> +#include <parc/algol/parc_ByteArray.h> + +struct parc_readonly_buffer; +typedef struct parc_readonly_buffer PARCReadOnlyBuffer; + +/** + * Create a new instance of `PARCBuPARCReadOnlyBuffer` referencing the content of the given {@link PARCBuffer}. + * + * A reference to the content of the given `PARCBuffer` is acquired. + * + * The new buffer's position, limit, capacity and mark will be the same as the given `PARCBuffer`. + * + * If capacity is zero, the buffer contains no underlying byte array. + * + * @param [in] buffer A pointed to a valid `PARCBuffer` instance. + * + * @return A `PARCReadOnlyBuffer` pointer. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * PARCReadOnlyBuffer *roBuffer = parcReadOnlyBuffer_Create(buffer); + * + * ... + * + * parcReadOnlyBuffer_Release(&roBuffer); + * parcBuffer_Release(&buffer); + * } + * @endcode + */ +PARCReadOnlyBuffer *parcReadOnlyBuffer_Create(PARCBuffer *buffer); + +/** + * Create a new instance of `PARCReadOnlyBuffer` using program supplied memory. + * + * The new buffer will be backed by the given byte array. + * Modifications to the array will be visible through the buffer. + * + * The new buffer's capacity will be @p arrayLength, + * its position will be @p position, + * its limit will be @p limit, + * and its mark will be undefined. + * + * Its backing array will be the given array, + * and its array offset will be zero. + * + * @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 `PARCReadOnlyBuffer` pointer. + * + * Example: + * @code + * { + * uint8_t array[10] = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 }; + * PARCReadOnlyBuffer *roBuffer = parcReadOnlyBuffer_Create(array, 10, 0, 10); + * + * ... + * + * parcReadOnlyBuffer_Release(&roBuffer); + * } + * @endcode + */ +PARCReadOnlyBuffer *parcReadOnlyBuffer_Wrap(uint8_t *array, size_t arrayLength, size_t position, size_t limit); + +/** + * Increase the number of references to a `PARCReadOnlyBuffer`. + * + * Note that new `PARCReadOnlyBuffer` is not created, + * only that the given `PARCReadOnlyBuffer` reference count is incremented. + * Discard the reference by invoking `parcBuffer_Release`. + * + * @param [in] buffer A `PARCReadOnlyBuffer` instance. + * + * @return The input `PARCReadOnlyBuffer` pointer. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * PARCReadOnlyBuffer *roBuffer = parcReadOnlyBuffer_Create(buffer); + * + * PARCReadOnlyBuffer *handle = parcReadOnlyBuffer_Acquire(roBuffer); + * + * ... + * + * parcReadOnlyBuffer_Release(&handle); + * parcReadOnlyBuffer_Release(&roBuffer); + * parcBuffer_Release(&buffer); + * } + * @endcode + */ +PARCReadOnlyBuffer *parcReadOnlyBuffer_Acquire(const PARCReadOnlyBuffer *buffer); + +/** + * Release a `PARCReadOnlyBuffer` reference. + * + * Only the last invocation where the reference count is decremented to zero, + * will actually destroy the `PARCReadOnlyBuffer`. + * + * @param [in,out] bufferPtr Pointer to the `PARCReadOnlyBuffer` instance to be released. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * PARCReadOnlyBuffer *roBuffer = parcReadOnlyBuffer_Create(buffer); + * + * ... + * + * parcReadOnlyBuffer_Release(&roBuffer); + * parcBuffer_Release(&buffer); + * } + * @endcode + */ +void parcReadOnlyBuffer_Release(PARCReadOnlyBuffer **bufferPtr); + +/** + * Returns this buffer's capacity. + * + * @param [in] buffer A pointer to a `PARCReadOnlyBuffer` instance. + * + * @return The given buffer's capacity. + * + * Example: + * @code + * { + * uint8_t array[10] = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 }; + * PARCReadOnlyBuffer *roBuffer = parcReadOnlyBuffer_Create(array, 10, 0, 10); + * + * size_t capacity = parcReadOnlyBuffer_Capacity(roBuffer); + * // capacity will be 10 + * + * ... + * + * parcReadOnlyBuffer_Release(&roBuffer); + * } + * @endcode + */ +size_t parcReadOnlyBuffer_Capacity(const PARCReadOnlyBuffer *buffer); + +/** + * Clear the given buffer: 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 `parcReadOnlyBuffer_Mark`. + * + * @param [in,out] buffer A pointer to the `PARCReadOnlyBuffer` instance to be modified. + * + * @return The value of @p buffer. + * + * Example: + * @code + * { + * parcReadOnlyBuffer_Clear(buffer); + * } + * @endcode + * + */ +PARCReadOnlyBuffer *parcReadOnlyBuffer_Clear(PARCReadOnlyBuffer *buffer); + +/** + * Determine if two `PARCReadOnlyBuffer` instances are equal. + * + * The following equivalence relations on non-null `PARCReadOnlyBuffer` instances are maintained: + * + * * It is reflexive: for any non-null reference value x, `parcReadOnlyBuffer_Equals(x, x)` must return true. + * + * * It is symmetric: for any non-null reference values x and y, `parcReadOnlyBuffer_Equals(x, y)` must return true if and only if + * `parcReadOnlyBuffer_Equals(y x)` returns true. + * + * * It is transitive: for any non-null reference values x, y, and z, if + * `parcReadOnlyBuffer_Equals(x, y)` returns true and + * `parcReadOnlyBuffer_Equals(y, z)` returns true, + * then `parcReadOnlyBuffer_Equals(x, z)` must return true. + * + * * It is consistent: for any non-null reference values x and y, multiple invocations of `parcReadOnlyBuffer_Equals(x, y)` + * consistently return true or consistently return false. + * + * * For any non-null reference value x, `parcReadOnlyBuffer_Equals(x, NULL)` must return false. + * + * + * @param [in] x A pointer to a `PARCReadOnlyBuffer` instance. + * @param [in] y A pointer to a `PARCReadOnlyBuffer` instance. + * + * @return true `PARCReadOnlyBuffer` x and y are equal. + * @return false `PARCReadOnlyBuffer` x and y are not equal. + * + * Example: + * @code + * { + * uint8_t array[10] = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 }; + * PARCReadOnlyBuffer *roBuffer1 = parcReadOnlyBuffer_Create(array, 10, 0, 10); + * PARCReadOnlyBuffer *roBuffer2 = parcReadOnlyBuffer_Create(array, 10, 0, 10); + * + * if (parcReadOnlyBuffer_Equals(roBuffer1, roBuffer2)) { + * printf("ROBuffers are equal\n"); + * } else { + * printf("ROBuffers are NOT equal\n"); + * } + * + * + * parcReadOnlyBuffer_Release(&roBuffer); + * } + * @endcode + */ +bool parcReadOnlyBuffer_Equals(const PARCReadOnlyBuffer *x, const PARCReadOnlyBuffer *y); + +/** + * Return a pointer to the {@link PARCByteArray} that backs this buffer. + * + * If this `PARCReadOnlyBuffer` has a capacity of zero, + * there is no array of bytes and this function returns NULL. + * + * Modifications to the `PARCByteArray` will cause the returned array's content to be modified, and vice versa. + * + * The caller must obtain its own reference to the `PARCByteArray` if it intends to store it elsewhere. + * + * @param [in] buffer A `PARCReadOnlyBuffer` pointer. + * + * @return The pointer to the `PARCByteArray` for the given `PARCReadOnlyBuffer`. + * + * Example: + * @code + * { + * uint8_t array[10] = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 }; + * PARCReadOnlyBuffer *roBuffer = parcReadOnlyBuffer_Create(array, 10, 0, 10); + * + * PARCByteArray *byteArray = parcReadOnlyBuffer_Array(roBuffer); + * + * ... + * + * parcByteArray_Release(&byteArray); + * parcReadOnlyBuffer_Release(&roBuffer); + * } + * @endcode + */ +PARCByteArray *parcReadOnlyBuffer_Array(const PARCReadOnlyBuffer *buffer); + +/** + * Create a copy of the given `PARCReadOnlyBuffer`. + * + * A new buffer is created as a complete copy of the original. + * + * @param [in] original A `PARCReadOnlyBuffer` instance. + * + * @return A `PARCReadOnlyBuffer` instance which is an identical, independent copy of the original. + * + * Example: + * @code + * { + * uint8_t array[10] = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 }; + * PARCReadOnlyBuffer *roBuffer = parcReadOnlyBuffer_Create(array, 10, 0, 10); + * + * PARCReadOnlyBuffer *copy = parcReadOnlyBuffer_Copy(roBuffer); + * + * if (parcReadOnlyBuffer_Equals(roBuffer, copy)) { + * printf("ROBuffers are equal\n"); + * } + * + * parcReadOnlyBuffer_Release(©); + * parcReadOnlyBuffer_Release(&roBuffer); + * } + * @endcode + * + * @see parcReadOnlyBuffer_Equals + */ +PARCReadOnlyBuffer *parcReadOnlyBuffer_Copy(const PARCReadOnlyBuffer *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 `PARCReadOnlyBuffer` pointer. + * + * @return The offset within this `PARCReadOnlyBuffer`'s array of the first element of the buffer + * + * Example: + * @code + * { + * uint8_t array[10] = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 }; + * PARCReadOnlyBuffer *roBuffer = parcReadOnlyBuffer_Create(array, 10, 0, 10); + * + * size_t arrayOffset = parcReadOnlyBuffer_ArrayOffset(buffer); + * // offset will be 0 since the contents of the buffer start at the beginning + * + * parcReadOnlyBuffer_Release(&roBuffer); + * } + * @endcode + */ +size_t parcReadOnlyBuffer_ArrayOffset(const PARCReadOnlyBuffer *buffer); + +/** + * Rewinds this `PARCReadOnlyBuffer`: The position is set to zero and the mark is invalidated. + * + * The mark is made invalid and any subsequent operation on the resulting + * {@link PARCBuffer} that requires the mark will abort until the mark + * is set again via {@link parcBuffer_Mark}. + * + * @param [in,out] buffer A `PARCReadOnlyBuffer` pointer. + * + * @return The given `PARCReadOnlyBuffer` pointer. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * parcBuffer_PutUint8(buffer, (uint8_t)'A'); + * + * PARCReadOnlyBuffer *roBuffer = parcReadOnlyBuffer_Create(buffer); + * + * parcReadOnlyBuffer_Rewind(roBuffer); + * + * parcReadOnlyBuffer_Release(&roBuffer); + * parcBuffer_Release(&buffer); + * } + * @endcode + */ +PARCReadOnlyBuffer *parcReadOnlyBuffer_Rewind(PARCReadOnlyBuffer *buffer); + +/** + * Resets the given `PARCReadOnlyBuffer`'s position to the previously-marked position. + * + * Invoking this method neither changes nor invalidates the mark's value. + * + * @param [in,out] buffer A `PARCReadOnlyBuffer` pointer. + * + * @return The given `PARCReadOnlyBuffer` pointer. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * parcBuffer_PutUint8(buffer, (uint8_t)'A'); + * + * PARCReadOnlyBuffer *roBuffer = parcReadOnlyBuffer_Create(buffer); + * + * parcReadOnlyBuffer_Reset(roBuffer); + * + * parcReadOnlyBuffer_Release(&roBuffer); + * parcBuffer_Release(&buffer); + * } + * @endcode + */ +PARCReadOnlyBuffer *parcReadOnlyBuffer_Reset(PARCReadOnlyBuffer *buffer); + +/** + * Return the given `PARCReadOnlyBuffer`'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 `PARCReadOnlyBuffer` pointer. + * + * @return The given `PARCReadOnlyBuffer`'s limit. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * + * PARCReadOnlyBuffer *roBuffer = parcReadOnlyBuffer_Create(buffer); + * + * size_t limit = parcReadOnlyBuffer_Limit(roBuffer); + * // limit will be 10 + * + * parcReadOnlyBuffer_Release(&roBuffer); + * parcBuffer_Release(&buffer); + * } + * @endcode + */ +size_t parcReadOnlyBuffer_Limit(const PARCReadOnlyBuffer *buffer); + +/** + * Sets this buffer's mark at its position. + * + * @param [in,out] buffer A `PARCReadOnlyBuffer` pointer. + * + * @return The given `PARCReadOnlyBuffer` pointer. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * PARCReadOnlyBuffer *roBuffer = parcReadOnlyBuffer_Create(buffer); + * + * parcReadOnlyBuffer_Mark(roBuffer); + * // since the position was 0, the mark remains at 0 + * + * parcReadOnlyBuffer_Release(&roBuffer); + * parcBuffer_Release(&buffer); + * } + * @endcode + */ +PARCReadOnlyBuffer *parcReadOnlyBuffer_Mark(PARCReadOnlyBuffer *buffer); + +/** + * Sets this `PARCReadOnlyBuffer`'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 {@link parcReadOnlyBuffer_Mark()}. + * + * @param [in] buffer A `PARCReadOnlyBuffer` pointer. + * @param [in] newLimit The new limit value; must be no larger than this `PARCReadOnlyBuffer`'s capacity + * + * @return The given `PARCReadOnlyBuffer` pointer. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * PARCReadOnlyBuffer *roBuffer = parcReadOnlyBuffer_Create(buffer); + * + * parcReadOnlyBuffer_SetLimit(roBuffer, 8); + * // the limit is now 8, but the capacity is 10 + * + * parcReadOnlyBuffer_Release(&roBuffer); + * parcBuffer_Release(&buffer); + * } + * @endcode + */ +PARCReadOnlyBuffer *parcReadOnlyBuffer_SetLimit(PARCReadOnlyBuffer *buffer, size_t newLimit); + +/** + * Return a pointer to memory that can be cast to a specific type. + * + * This does not guarantee proper memory alignment. + * It is possible to obtain a pointer to memory that cannot be accessed + * as integer or other types because of CPU memory alignment requirements. + * + * @param [in,out] buffer A `PARCReadOnlyBuffer` pointer. + * @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); + * + * PARCReadOnlyBuffer *roBuffer = parcReadOnlyBuffer_Create(buffer); + * + * char *actual = parcReadOnlyBuffer_Overlay(roBuffer, length); + * + * struct timeval *tm = parcReadOnlyBuffer_Overlay(roBuffer, sizeof(struct timeval)); + * } + * @endcode + */ +void *parcReadOnlyBuffer_Overlay(PARCReadOnlyBuffer *buffer, size_t length); + +/** + * Return the given `PARCReadOnlyBuffer`'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 `PARCReadOnlyBuffer` pointer. + * + * @return The given `PARCReadOnlyBuffer`'s position. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * PARCReadOnlyBuffer *roBuffer = parcReadOnlyBuffer_Create(buffer); + * + * size_t position = parcReadOnlyBuffer_Position(roBuffer); + * // position is zero since the position of the underlying buffer is also 0 + * + * parcReadOnlyBuffer_Release(&roBuffer); + * parcBuffer_Release(&buffer); + * } + * @endcode + */ +size_t parcReadOnlyBuffer_Position(const PARCReadOnlyBuffer *buffer); + +/** + * Set the given `PARCReadOnlyBuffer`'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 + * `PARCReadOnlyBuffer` that requires the mark will abort until the mark + * is set again via `parcReadOnlyBuffer_Mark`. + * + * @param [in,out] buffer A `PARCReadOnlyBuffer` pointer. + * @param [in] newPosition The value of the new position which must be less than or equal to the buffer's current limit. + * + * @return The given `PARCReadOnlyBuffer`'s position. + * + * Example: + * @code + * { + * PARCReadOnlyBuffer *buffer = parcReadOnlyBuffer_Create(parcBuffer_Allocate(10)); + * parcReadOnlyBuffer_SetPosition(buffer, 5); + * parcReadOnlyBuffer_Remaining(buffer); // Returns 5. + * } + * @endcode + */ +PARCReadOnlyBuffer *parcReadOnlyBuffer_SetPosition(PARCReadOnlyBuffer *buffer, size_t newPosition); + +/** + * Returns the number of elements between the current position and the limit. + * + * @param [in] buffer A `PARCReadOnlyBuffer` pointer. + * + * @return The number of elements remaining in this `PARCReadOnlyBuffer`. + * + * Example: + * @code + * { + * parcReadOnlyBuffer_SetPosition(buffer, 5); + * parcReadOnlyBuffer_Remaining(buffer); // Returns 5. + * } + * @endcode + */ +size_t parcReadOnlyBuffer_Remaining(const PARCReadOnlyBuffer *buffer); + +/** + * Tells whether there are any elements between the current position and the limit. + * + * @param [in] buffer A `PARCReadOnlyBuffer` pointer. + * + * @return true if, and only if, there is at least one element remaining in this `PARCReadOnlyBuffer`. + * + * Example: + * @code + * { + * parcReadOnlyBuffer_SetPosition(buffer, 5); + * bool remaining = parcReadOnlyBuffer_HasRemaining(buffer); + * // remaining is true, since #remaining = 5 + * } + * @endcode + */ +bool parcReadOnlyBuffer_HasRemaining(const PARCReadOnlyBuffer *buffer); + +/** + * Set the limit to the current position, then set the position to zero. + * If the mark is defined, it is invalidated. + * + * @param [in,out] buffer The `PARCReadOnlyBuffer` pointer to be modified. + * + * @return The same value as `buffer` + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * parcBuffer_PutByte(buffer, 'X'); + * PARCReadOnlyBuffer *roBuffer = parcReadOnlyBuffer_Create(buffer); + * + * parcReadOnlyBuffer_Flip(roBuffer); + * uint8_t actual = parcReadOnlyBuffer_GetUint8(roBuffer); + * + * ... + * + * parcReadOnlyBuffer_Release(&roBuffer); + * parcBuffer_Release(&buffer); + * } + */ +PARCReadOnlyBuffer *parcReadOnlyBuffer_Flip(PARCReadOnlyBuffer *buffer); + +/** + * Get the single uint8_t at the index specified. + * + * @param [in] buffer A `PARCReadOnlyBuffer` pointer. + * @param [in] index The index from which to retrieve the single byte in the buffer. + * + * @return The uint8_t value at the specified index + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * parcBuffer_PutByte(buffer, 'X'); + * PARCReadOnlyBuffer *roBuffer = parcReadOnlyBuffer_Create(buffer); + * + * uint8_t byte = parcReadOnlyBuffer_GetAtIndex(roBuffer, 0); + * + * ... + * + * parcReadOnlyBuffer_Release(&roBuffer); + * parcBuffer_Release(&buffer); + * } + */ +uint8_t parcReadOnlyBuffer_GetAtIndex(const PARCReadOnlyBuffer *buffer, size_t index); + +/** + * Read an array of length bytes from the given PARCReadOnlyBuffer, copying them to an array. + * + * The buffer's position is incremented by @p length. + * + * @param [in] buffer The `PARCReadOnlyBuffer` containing the `uint8_t` value. + * @param [out] array The `uint8_t` array to receive @p length bytes. + * @param [in] length The number of `uint8_t` elements to get.. + * + * @return The given `PARCReadOnlyBuffer`. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(5); + * parcBuffer_PutUint8(buffer, 'A'); + * parcBuffer_PutUint8(buffer, 'B'); + * parcBuffer_PutUint8(buffer, 'C'); + * PARCReadOnlyBuffer *roBuffer = parcReadOnlyBuffer_Create(buffer); + * + * uint8_t array[3]; + * parcReadOnlyBuffer_GetArray(roBuffer, 3, array); + * // array[0] == 'A' + * // array[1] == 'B' + * // array[2] == 'C' + * } + * @endcode + * + * @see parcReadOnlyBuffer_Overlay + */ +PARCReadOnlyBuffer *parcReadOnlyBuffer_GetArray(PARCReadOnlyBuffer *buffer, uint8_t *array, size_t length); + +/** + * Get the single `uint8_t` at the current buffer position. + * + * @param [in] buffer A `PARCReadOnlyBuffer` pointer. + * + * @return The `uint8_t` value at the current position. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * parcBuffer_PutByte(buffer, 'X'); + * PARCReadOnlyBuffer *roBuffer = parcReadOnlyBuffer_Create(buffer); + * parcReadOnlyBuffer_Flip(roBuffer); + * + * uint8_t actual = parcReadOnlyBuffer_GetUint8(roBuffer); + * + * parcReadOnlyBuffer_Release(&roBuffer); + * parcBuffer_Release(&buffer); + * } + * @endcode + */ +uint8_t parcReadOnlyBuffer_GetUint8(PARCReadOnlyBuffer *buffer); + +/** + * Get the single `uint16_t` at the current buffer position. + * + * @param [in] buffer A `PARCReadOnlyBuffer` pointer. + * + * @return The `uint16_t` value at the current position. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * parcBuffer_PutUint16(buffer, 0x1234); + * PARCReadOnlyBuffer *roBuffer = parcReadOnlyBuffer_Create(buffer); + * parcReadOnlyBuffer_Flip(roBuffer); + * + * uint16_t actual = parcReadOnlyBuffer_GetUint16(roBuffer); + * + * parcReadOnlyBuffer_Release(&roBuffer); + * parcBuffer_Release(&buffer); + * } + * @endcode + */ +uint16_t parcReadOnlyBuffer_GetUint16(PARCReadOnlyBuffer *buffer); + +/** + * Get the single `uint32_t` at the current buffer position. + * + * @param [in] buffer A `PARCReadOnlyBuffer` pointer. + * + * @return The `uint32_t` value at the current position. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(10); + * parcBuffer_PutUint32(buffer, 0x12345678); + * PARCReadOnlyBuffer *roBuffer = parcReadOnlyBuffer_Create(buffer); + * parcReadOnlyBuffer_Flip(roBuffer); + * + * uint32_t actual = parcReadOnlyBuffer_GetUint32(roBuffer); + * + * parcReadOnlyBuffer_Release(&roBuffer); + * parcBuffer_Release(&buffer); + * } + * @endcode + */ +uint32_t parcReadOnlyBuffer_GetUint32(PARCReadOnlyBuffer *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 `PARCReadOnlyBuffer` containing the value. + * + * @return The `uint64_t` at the buffer's current position. + * + * Example: + * @code + * { + * PARCBuffer *buffer = parcBuffer_Allocate(sizeof(uint64_t)); + * parcBuffer_PutUint64(buffer, 0x1234567812345678); + * parcBuffer_Flip(buffer); + * + * PARCReadOnlyBuffer *readOnly = parcReadOnlyBuffer_Create(buffer); + * uint64_t actual = parcReadOnlyBuffer_GetUint64(&readOnly); + * } + * @endcode + */ +uint64_t parcReadOnlyBuffer_GetUint64(PARCReadOnlyBuffer *buffer); + +/** + * Returns a hash code value for the given instance. + * + * The general contract of `HashCode` is: + * + * Whenever it is invoked on the same instance more than once during an execution of an application, + * the {@link parcReadOnlyBuffer_HashCode} function must consistently return the same value, + * provided no information used in a corresponding {@link parcReadOnlyBuffer_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 parcReadOnlyBuffer_Equals} method, + * then calling the {@link parcReadOnlyBuffer_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 parcReadOnlyBuffer_Equals()} function, + * then calling the {@link parcReadOnlyBuffer_HashCode()} + * method on each of the two objects must produce distinct integer results. + * + * @param [in] buffer A pointer to the `PARCReadOnlyBuffer` instance. + * + * @return The hashcode for the given instance. + * + * Example: + * @code + * { + * uint32_t hashValue = parcReadOnlyBuffer_HashCode(buffer); + * } + * @endcode + * + * @see parcReadOnlyBuffer_Equals + */ +PARCHashCode parcReadOnlyBuffer_HashCode(const PARCReadOnlyBuffer *buffer); + +/** + * Create a null-terminated C string containing the bytes of the given `PARCReadOnlyBuffer`. + * + * The string consists of the bytes from the current position of the buffer to its limit. + * + * @param [in] buffer A `PARCReadOnlyBuffer` instance. + * + * @return NULL Cannot allocate memory. + * @return non-NULL A pointer to a null-terminated C string that must be deallocated via {@link parcMemory_Deallocate}. + * + * Example: + * @code + * { + * char *string = parcReadOnlyBuffer_ToString(buffer); + * + * parcMemory_Deallocate((void **)&string); + * } + * @endcode + */ +char *parcReadOnlyBuffer_ToString(const PARCReadOnlyBuffer *buffer); + +/** + * Print a human readable representation of the given `PARCReadOnlyBuffer`. + * + * Print on standard output a human readable representation of the given `PARCReadOnlyBuffer` indented by the level indicated. + * + * @param [in] buffer A pointer to the `PARCReadOnlyBuffer` instance. + * @param [in] indentation The number of tabs by which to indent the output strings. + * + * Example: + * @code + * { + * parcReadOnlyBuffer_Display(buffer, 0); + * } + * @endcode + */ +void parcReadOnlyBuffer_Display(const PARCReadOnlyBuffer *buffer, int indentation); +#endif // libparc_parc_ReadOnlyBuffer_h |