Merge "Initial commit: cframework. Longbow and Libparc" into cframework/master

1 files changed, 580 insertions, 0 deletions

diff --git a/libparc/parc/algol/parc_ByteArray.h b/libparc/parc/algol/parc_ByteArray.h
new file mode 100644
index 00000000..98cc970a
--- /dev/null
+++ b/libparc/parc/algol/parc_ByteArray.h
@@ -0,0 +1,580 @@
+/*
+ * 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 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 `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 `trapOutOfBounds` 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