diff options
Diffstat (limited to 'libparc/parc/algol/parc_ByteArray.h')
| -rw-r--r-- | libparc/parc/algol/parc_ByteArray.h | 580 |
1 files changed, 0 insertions, 580 deletions
diff --git a/libparc/parc/algol/parc_ByteArray.h b/libparc/parc/algol/parc_ByteArray.h deleted file mode 100644 index c7a26285..00000000 --- a/libparc/parc/algol/parc_ByteArray.h +++ /dev/null @@ -1,580 +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_ByteArray.h - * @ingroup memory - * @brief A simple reference counted unsigned byte array. - * - * @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 74 304 68" width="304pt" height="68pt"> - * <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(271 88.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 88.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 96.483333 C 73.6671 96.98884 67.757544 94.49623 65 98 C 63.49089 99.917494 62.925312 103.63153 62.52875 107.66717" marker-end="url(#FilledArrow_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/> - * <rect x="59" y="118" width="281" height="13" fill="white"/> - * <rect x="59" y="118" width="281" height="13" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/> - * <path d="M 316 97.11628 C 321.9994 97.744123 330.42197 95.601626 334 99 C 335.8631 100.769544 336.41326 104.04195 336.67595 107.643264" marker-end="url(#FilledArrow_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/> - * </g> - * </g> - * </svg> - * @endhtmlonly - * - * `PARCByteArray` is a simple reference counted array of `uint8_t` values. - * Instances of `PARCByteArray` are created either by dynamically allocating the byte array, - * via `parcByteArray_Allocate()`, - * or by wrapping a static `uint8_t` array, - * via `parcByteArray_Wrap()`. - * - * New references to an existing instance of `PARCByteArray` are created via `parcByteArray_Acquire()`. - * - * A `PARCByteArray` reference is released via `parcByteArray_Release`. - * Only the last invocation will deallocated the `PARCByteArray`. - * If the `PARCByteArray` references dynamically allocated memory, - * that memory is freed with the `PARCByteArray` when the last reference is released. - * - */ -#ifndef libparc_parc_ByteArray_h -#define libparc_parc_ByteArray_h -#include <stdlib.h> -#include <stdbool.h> -#include <stdint.h> - -struct parc_byte_array; -/** - * - * @see {@link parcByteArray_Allocate} - * @see {@link parcByteArray_Wrap} - */ -typedef struct parc_byte_array PARCByteArray; - -#include <parc/algol/parc_HashCode.h> - -#ifdef PARCLibrary_DISABLE_VALIDATION -# define parcByteArray_OptionalAssertValid(_instance_) -#else -# define parcByteArray_OptionalAssertValid(_instance_) parcByteArray_AssertValid(_instance_) -#endif - -/** - * Assert that an instance of `PARCByteArray` is valid. - * - * If the instance is not valid, terminate via {@link parcTrapIllegalValue} - * - * 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 `PARCByteArray` instance. - */ -void parcByteArray_AssertValid(const PARCByteArray *instance); - -/** - * Determine if an instance of `PARCByteArray` 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] instance A pointer to a `PARCByteArray` instance. - * - * @return true The instance is valid. - * @return false The instance is not valid. - */ -bool parcByteArray_IsValid(const PARCByteArray *instance); - -/** - * Dynamically allocate a `PARCByteArray` of a specific capacity. - * - * @param [in] capacity The number of bytes in the byte array. - * - * @return A pointer to an allocated `PARCByteArray` instance which must be released via {@link parcByteArray_Release()}. - * - * Example: - * @code - * { - * PARCByteArray *byteArray = parcByteArray_Allocate(100); - * - * parcByteArray_Release(&byteArray); - * } - * @endcode - * - * @see parcByteArray_Release - */ -PARCByteArray *parcByteArray_Allocate(const size_t capacity); - -/** - * Wrap existing memory in a {@link PARCByteArray}. - * - * As in all `Wrap` functions, a copy of the memory is not made. - * Be sure to only wrap memory that is either global, - * or used within on stack-frame or functional block. - * Otherwise, corruption is likly to occur. - * - * @param [in] capacity The maximum capacity of the backing array. - * @param [in] array A pointer to the backing array. - * - * @return A pointer to an allocated `PARCByteArray` instance which must be released via {@link parcByteArray_Release()}. - * - * Example: - * @code - * { - * uint8_t array[10]; - * PARCByteArray *byteArray = parcByteArray_Wrap(array, 10); - * - * parcByteArray_Release(&byteArray); - * } - * @endcode - */ -PARCByteArray *parcByteArray_Wrap(size_t capacity, uint8_t *array); - -/** - * Returns the pointer to the `uint8_t` array that backs this `PARCByteArray`. - * - * Modifications to the given `PARCByteArray` content will cause the returned array's content to be modified, and vice versa. - * - * The reference count for the given `PARCByteArray` is not modified. - * - * <b>Use with caution.</b> - * - * @param [in] byteArray Pointer to a `PARCByteArray` instance from which the underlying array is extracted. - * - * @return The pointer to the `uint8_t` array that backs this `PARCByteArray`. - * - * Example: - * @code - * { - * uint8_t array[10]; - * PARCByteArray *byteArray = parcByteArray_Wrap(array, 10); - * - * uint8_t *raw = parcByteArray_Array(byteArray); - * // updates on the raw array (pointer) are seen in the byteArray instance - * // use with caution - * - * parcByteArray_Release(&byteArray); - * } - * @endcode - */ -uint8_t *parcByteArray_Array(const PARCByteArray *byteArray); - -/** - * Increase the number of references to a `PARCByteArray`. - * - * Note that a new `PARCByteArray` is not created, - * only that the given `PARCByteArray` reference count is incremented. - * Discard the reference by invoking {@link parcByteArray_Release}. - * - * @param [in] instance A pointer to the original `PARCByteArray` instance. - * - * @return The value of the input parameter @p instance. - * - * Example: - * @code - * { - * PARCByteArray *x = parcByteArray_Allocate(10); - * - * PARCByteArray *x_2 = parcByteArray_Acquire(x); - * - * parcByteArray_Release(&x); - * parcByteArray_Release(&x_2); - * } - * @endcode - * - * @see parcByteArray_Release - */ -PARCByteArray *parcByteArray_Acquire(const PARCByteArray *instance); - -/** - * 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] byteArrayPtr A pointer to a pointer to the instance of `PARCByteArray` to release. - * - * Example: - * @code - * { - * PARCByteArray *x = parcByteArray_Acquire(...); - * - * parcByteArray_Release(&x); - * } - * @endcode - */ -void parcByteArray_Release(PARCByteArray **byteArrayPtr); - -/** - * Put an `uint8_t` value into the byte array at the given index. - * - * The value of @p index must be greater than or equal to 0, and less than the capacity. - * - * @param [in,out] result A pointer to the instance of `PARCByteArray` that will receive the data. - * @param [in] index The index at which the byte will be inserted. - * @param [in] byte The byte to be inserted into the array. - * - * @return The `PARCByteArray` that receive the data. - * - * Example: - * @code - * { - * uint8_t array[10]; - * PARCByteArray *byteArray = parcByteArray_Wrap(array, 10); - * - * parcByteArray_PutByte(byteArray, 5, 123); - * - * parcByteArray_Release(&byteArray); - * } - * @endcode - */ -PARCByteArray *parcByteArray_PutByte(PARCByteArray *result, size_t index, uint8_t byte); - -/** - * Get the value at a specific index from the given `PARCByteArray`. - * - * @param [in] result The instance of `PARCByteArray` that will produce the data. - * @param [in] index The index from which the byte will be retrieved. - * - * @return The value at a specific index from the given `PARCByteArray`. - * - * Example: - * @code - * { - * uint8_t array[10]; - * PARCByteArray *byteArray = parcByteArray_Wrap(array, 10); - * - * parcByteArray_PutByte(byteArray, 5, 123); - * - * parcByteArray_GetByte(byteArray, 5); - * - * parcByteArray_Release(&byteArray); - * } - * @endcode - */ -uint8_t parcByteArray_GetByte(const PARCByteArray *result, size_t index); - -/** - * 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. - * - * @param [in] a A pointer to a `PARCByteArray` instance 'a'. - * @param [in] b A pointer to another `PARCByteArray` instance 'b'. - * - * @return <0 Instance a is less then instance b. - * @return 0 Instance a and instance b compare the same. - * @return >0 Instance a is greater than instance b. - * - * Example: - * @code - * { - * uint8_t array[10]; - * PARCByteArray *byteArray1 = parcByteArray_Wrap(array, 10); - * PARCByteArray *byteArray2 = parcByteArray_Wrap(array, 10); - * - * if (parcByteArray_Compare(byteArray1, byteArray2) == 0) { - * printf("Equal\n"); - * } - * - * parcByteArray_Release(&byteArray1); - * parcByteArray_Release(&byteArray2); - * } - * @endcode - * - * @see parcByteArray_Equal - */ -int parcByteArray_Compare(const PARCByteArray *a, const PARCByteArray *b); - -/** - * Copy data from an external array into a `PARCByteArray`. - * - * Provided that the underlying `PARCByteArray` is large enough, - * copy the bytes from the given `array` for `length` bytes. - * - * @param [in,out] result The `PARCByteArray` that will receive the data. - * @param [in] offset The offset into the `PARCByteArray` that will receive the data. - * @param [in] length The number of bytes to copy in. - * @param [in] source The uint8_t array containing the original data. - * - * @return The given `PARCByteArray` pointer - * - * @throws SIGABRT `parcTrapOutOfBounds` if the underlying `PARCByteArray` is not large enough - * - * Example: - * @code - * { - * uint8_t array[10]; - * PARCByteArray *byteArray = parcByteArray_Wrap(array, 10); - * uint8_t inner[3]; - * inner[0] = 0xFF; - * inner[1] = 0xFF; - * inner[2] = 0xFF; - * - * parcByteArray_PutBytes(byteArray, 1, 3, inner); - * // Bytes 1,2,3 of byteArray will be 0xFF (offset was 1, not 0) - * - * parcByteArray_Release(&byteArray); - * } - * @endcode - */ -PARCByteArray *parcByteArray_PutBytes(PARCByteArray *result, size_t offset, size_t length, const uint8_t *source); - -/** - * Copy data from a `PARCByteArray` into an external array. - * - * Provided that the underlying `PARCByteArray` has at least `length` bytes - * copy the bytes from the `PARCByteArray` into the given `array`. - * - * @param [in] source The `PARCByteArray` that will produce the data. - * @param [in] offset The offset into the `PARCByteArray` from which the data will be copied. - * @param [in] length The number of bytes to copy from the <code>PARCByteArray</code> into @p destination. - * @param [in] destination The `uint8_t` array That will contain the data. - * - * @return The given `PARCByteArray` @p source pointer. - * - * Example: - * @code - * { - * uint8_t array[10]; - * PARCByteArray *byteArray = parcByteArray_Wrap(array, 10); - * - * uint8_t inner[3]; - * parcByteArray_GetBytes(byteArray, 0, 3, inner); - * // inner will contain a copy of bytes 0,1,2 from the byteArray - * - * parcByteArray_Release(&byteArray); - * } - * @endcode - */ -PARCByteArray *parcByteArray_GetBytes(const PARCByteArray *source, size_t offset, size_t length, uint8_t *destination); - - -/** - * Copy a portion of one `PARCByteArray` into another. - * - * The sum of (destination/source) offset and length must be within the bounds of the - * respective (destination/source) `PARCByteArray` instances. - * - * @param [in,out] destination Pointer to the destination `PARCByteArray` instance. - * @param [in] destOffset Offset within the destination `PARCByteArray` instance. - * @param [in] source Pointer to the source `PARCByteArray` instance. - * @param [in] srcOffset Offset within the source `PARCByteArray` instance. - * @param [in] length Number of bytes to copy from the source to the destination. - * - * @return PARCByteArray* A pointer to the destination. - * - * Example: - * @code - * { - * uint8_t array1[10]; - * PARCByteArray *byteArray1 = parcByteArray_Wrap(array1, 10); - * uint8_t array2[3]; - * array2[0] = 0xAA; - * array2[1] = 0xBB; - * array2[2] = 0xCC; - * PARCByteArray *byteArray2 = parcByteArray_Wrap(array2, 3); - * - * parcByteArray_ArrayCopy(byteArray1, 0, byteArray2, 0, 3); - * // the first three bytes of byteArray1 will now be 0xAA,0xBB,0xCC - * } - * @endcode - */ -PARCByteArray *parcByteArray_ArrayCopy(PARCByteArray *destination, size_t destOffset, const PARCByteArray *source, size_t srcOffset, size_t length); - -/** - * Get the capacity of a `PARCByteArray`. - * - * The `PARCByteArray`'s capacity is the number of bytes stored in the backing store of a `PARCByteArray`. - * - * @param [in] byteArray Pointer to the `PARCByteArray` instance being examined. - * - * @return The capacity of a `PARCByteArray`. - * - * Example: - * @code - * { - * uint8_t array[10]; - * PARCByteArray *byteArray = parcByteArray_Wrap(array, 10); - * - * size_t capacity = parcByteArray_Capacity(byteArray); - * } - * @endcode - */ -size_t parcByteArray_Capacity(const PARCByteArray *byteArray); - -/** - * Create a copy of an existing `PARCByteArray`. - * - * The copy is equal to, but shares nothing in common with, the original `PARCByteArray` - * - * @param [in] original A non-null pointer to the `PARCByteArray` to copy. - * - * @return NULL Memory could not be allocated. - * @return non-NULL A pointer to the new `PARCByteArray` instance. - * - * Example: - * @code - * { - * uint8_t array[10]; - * PARCByteArray *byteArray = parcByteArray_Wrap(array, 10); - * PARCByteArray *copy = parcByteArray_Copy(byteArray); - * } - * @endcode - * - * @see parcByteArray_Allocate - * @see parcByteArray_Wrap - */ -PARCByteArray *parcByteArray_Copy(const PARCByteArray *original); - -/** - * Determine if two `PARCByteArray` instances are equal. - * - * Two `PARCByteArray` instances are equal if, and only if, - * * They have the same number of elements, and - * * The two sequences of remaining elements are pointwise equal. - * - * The following equivalence relations on non-null `PARCByteArray` instances are maintained: - * - * * It is reflexive: for any non-null reference value x, `parcByteArray_Equals(x, x)` must return true. - * - * * It is symmetric: for any non-null reference values x and y, `parcByteArray_Equals(x, y)` must return true if and only if - * `parcByteArray_Equals(y, x)` returns true. - * - * * It is transitive: for any non-null reference values x, y, and z, if - * `parcByteArray_Equals(x, y)` returns true and - * `parcByteArray_Equals(y, z)` returns true, - * then `parcByteArray_Equals(x, z)` must return true. - * - * * It is consistent: for any non-null reference values x and y, multiple invocations of `parcByteArray_Equals(x, y)` - * consistently return true or consistently return false. - * - * * For any non-null reference value x, `parcByteArray_Equals(x, NULL)` must return false. - * - * @param [in] a A pointer to a `PARCByteArray` instance. - * @param [in] b A pointer to a `PARCByteArray` instance. - * - * @return true if the two `PARCByteArray` instances are equal. - * - * Example: - * @code - * { - * uint8_t array[10]; - * PARCByteArray *byteArray1 = parcByteArray_Wrap(array, 10); - * PARCByteArray *byteArray2 = parcByteArray_Wrap(array, 10); - * - * if (parcByteArray_Equals(byteArray1, byteArray2)) { - * printf("Equal\n"); - * } else { - * printf("NOT Equal\n"); - * } - * - * parcByteArray_Release(&byteArray1); - * parcByteArray_Release(&byteArray2); - * } - * @endcode - */ -bool parcByteArray_Equals(const PARCByteArray *a, const PARCByteArray *b); - -/** - * 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 parcByteArray_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 parcByteArray_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 parcByteArray_Equals} function, - * then calling the {@link parcByteArray_HashCode} - * method on each of the two objects must produce distinct integer results. - * - * @param [in] array A pointer to the `PARCByteArray` instance. - * - * @return The hashcode for the given instance. - * - * Example: - * @code - * { - * PARCByteArray *array = parcByteArray_Allocate(10); - * uint32_t hashValue = parcByteArray_HashCode(array); - * parcByteArray_Release(&buffer); - * } - * @endcode - * - * @see parcByteArray_HashCode - */ -PARCHashCode parcByteArray_HashCode(const PARCByteArray *array); - -/** - * Return the memory address as a `uint8_t *` to the location specified by `index`. - * - * @param [in] array A pointer to the `PARCByteArray` instance. - * @param [in] index The index of the address. - * - * @return A pointer to the location offset by index bytes within the array. - * - * Example: - * @code - * { - * PARCByteArray *byteArray = parcByteArray_Allocate(10); - * uint8_t *offsetAddress = parcByteArray_AddressOfIndex(byteArray, 4); - * // offsetAddress now points to the array at offset 4 within byteArray - * } - * @endcode - */ -uint8_t *parcByteArray_AddressOfIndex(const PARCByteArray *array, size_t index); - -/** - * Pretty print the given `PARCByteArray` instance. - * - * @param [in] indentation The amount of indentation to prefix each line of output - * @param [in] array The `PARCByteArray` instance to be printed. - * - * Example: - * @code - * { - * PARCByteArray *byteArray = parcByteArray_Allocate(10); - * parcByteArray_Display(byteArray, 0); - * } - * @endcode - */ -void parcByteArray_Display(const PARCByteArray *array, int indentation); -#endif // libparc_parc_ByteArray_h |