diff options
Diffstat (limited to 'libparc/parc/algol/parc_ReadOnlyBuffer.h')
| -rw-r--r-- | libparc/parc/algol/parc_ReadOnlyBuffer.h | 834 |
1 files changed, 0 insertions, 834 deletions
diff --git a/libparc/parc/algol/parc_ReadOnlyBuffer.h b/libparc/parc/algol/parc_ReadOnlyBuffer.h deleted file mode 100644 index 39dd6aa8..00000000 --- a/libparc/parc/algol/parc_ReadOnlyBuffer.h +++ /dev/null @@ -1,834 +0,0 @@ -/* - * 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 |