diff options
Diffstat (limited to 'longbow/src/LongBow/private/longBow_ArrayList.h')
| -rw-r--r-- | longbow/src/LongBow/private/longBow_ArrayList.h | 225 |
1 files changed, 225 insertions, 0 deletions
diff --git a/longbow/src/LongBow/private/longBow_ArrayList.h b/longbow/src/LongBow/private/longBow_ArrayList.h new file mode 100644 index 00000000..71eeb2b9 --- /dev/null +++ b/longbow/src/LongBow/private/longBow_ArrayList.h @@ -0,0 +1,225 @@ +/* + * 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 longBow_ArrayList.h + * @ingroup internals + * @brief A simple, list implementation using a dynamic array. + * + */ +#ifndef LongBow_ARRAYLIST_H +#define LongBow_ARRAYLIST_H + +#include <stdlib.h> +#include <stdint.h> +#include <stdbool.h> + +/** + * @struct longbow_array_list + * @brief A LongBow_ArrayList is a (dynamic) array of <code>void *</code> pointers; + */ +struct longbow_array_list; + +/** + * @typedef LongBowArrayList + * @brief The struct longbow_array_list + */ +typedef struct longbow_array_list LongBowArrayList; + +/** + * Assert that a LongBowArrayList instance is valid. + * + * @param [in] array A pointer to a valid LongBowArrayList instance. + * + */ +void longBowArrayList_AssertValid(const LongBowArrayList *array); +/** + * Add a pointer to an element to the given LongBowArrayList. + * + * If the list was constructed with a destroyer, + * the pointer will be destroyed when element is removed or the list is destroyed. + * + * @param [in] array A pointer to a LongBowArrayList instance. + * @param [in] pointer An arbitrary value to store. + * + * @return The input array pointer. + */ +LongBowArrayList *longBowArrayList_Add(LongBowArrayList *array, const void *pointer); + +/** + * Remove an element at a specific index from an Array List. + * + * The element is destroyed via the function provided when calling <code>longBowArrayList_Create</code>. + * + * @param [in] array A pointer to a LongBowArrayList instance. + * @param [in] index The index of the element to remove. + * + * @return A pointer to the modified LongBowArrayList. + */ +LongBowArrayList *longBowArrayList_RemoveAtIndex(LongBowArrayList *array, size_t index); + +/** + * Add an element at the index location. Elements will be moved up if required. + * If the index is higher than the current Length the Array will be grown to that size + * + * @param [in] array A pointer to a LongBowArrayList instance. + * @param [in] pointer An arbitrary value to store. + * @param [in] index The position that the value will be stored after. + * @return A pointer to the modified LongBowArrayList. + */ +LongBowArrayList *longBowArrayList_Add_AtIndex(LongBowArrayList *array, const void *pointer, size_t index); + +/** + * Create an instance of an empty LongBowArrayList. + * + * @param [in] destroyElement + * A pointer to a function that will destroy (or equivalent) the element pointed to by <code>element</code> + * @return A pointer to a LongBowArrayList instance, or NULL if no memory could be allocated. + */ +LongBowArrayList *longBowArrayList_Create(void (*destroyElement)(void **elementAddress)); + +/** + * Create an instance of a LongBowArrayList pre-provisioned to contain the specified number of elements. + * + * @param [in] size + * The number of initial elements to provision for. + * @param [in] destroyElement + * A pointer to a function that will destroy (or equivalent) the element pointed to by <code>element</code> + * @return A pointer to a LongBowArrayList instance, or NULL if no memory could be allocated. + */ +LongBowArrayList *longBowArrayList_Create_Capacity(void (*destroyElement)(void **elementAddress), size_t size); + +/** + * Get an array of void * pointers. + * Return a pointer to an array of void * pointers contained in this Array List. + * The returned value may be the actual backing array for the Array List. + * + * @param [in] array The LongBow_ArrayList + * @return A pointer to an array of void * pointers contained in this Array List. + * + */ +void **longBowArrayList_GetArray(const LongBowArrayList *array); + +/** + * Copy a LongBowArrayList instance. + * Create a new LongBowArrayList instance with the same structure and content as the original. + * + * @param [in] array A pointer to a LongBowArrayList instance to copy. + * @return A pointer to a LongBowArrayList instance with a copy of the original, or NULL if no memory could be allocated. + */ +LongBowArrayList *longBowArrayList_Copy(const LongBowArrayList *array); + +/** + * Destroy a LongBowArrayList instance. + * + * Destroy the given LongBowArrayList by freeing all memory used by it. + * + * @param [in,out] arrayPtr A pointer to a LongBowArrayList pointer. + */ +void longBowArrayList_Destroy(LongBowArrayList **arrayPtr); + +/** + * Get an element from the given list at a specified index. + * The index must be 0 <= index < length. + * + * @return A pointer (void *) to the element in the list. + * + * @param [in] array A pointer to a LongBowArrayList instance. + * @param [in] index The index of the required element. + */ +void *longBowArrayList_Get(const LongBowArrayList *array, size_t index); + +/** + * Return the number of elements in the given LongBowArrayList. + * + * @param [in] array A pointer to a LongBowArrayList instance. + * @return A size_t of the number of elements in the given LongBowArrayList. + */ +size_t longBowArrayList_Length(const LongBowArrayList *array); + + +/** + * Determine if two LongBowArrayList instances are equal. + * + * Two LongBowArrayList instances are equal if, and only if, they both contain the same pointers in the same order. + * + * The following equivalence relations on non-null `LongBowArrayList` instances are maintained: + * + * * It is reflexive: for any non-null reference value x, `LongBowArrayList_Equals(x, x)` + * must return true. + * + * * It is symmetric: for any non-null reference values x and y, + * `longBowArrayList_Equals(x, y)` must return true if and only if + * `longBowArrayList_Equals(y, x)` returns true. + * + * * It is transitive: for any non-null reference values x, y, and z, if + * `longBowArrayList_Equals(x, y)` returns true and + * `longBowArrayList_Equals(y, z)` returns true, + * then `longBowArrayList_Equals(x, z)` must return true. + * + * * It is consistent: for any non-null reference values x and y, multiple + * invocations of `longBowArrayList_Equals(x, y)` consistently return true or + * consistently return false. + * + * * For any non-null reference value x, `longBowArrayList_Equals(x, NULL)` must + * return false. + * + * @param a A pointer to a `LongBowArrayList` instance. + * @param b A pointer to a `LongBowArrayList` instance. + * @return true if the two `LongBowArrayList` instances are equal. + * + * Example: + * @code + * { + * LongBowArrayList *a = longBowArrayList_Create(); + * LongBowArrayList *b = longBowArrayList_Create(); + * + * if (longBowArrayList_Equals(a, b)) { + * // true + * } else { + * // false + * } + * } + * @endcode + */ + +bool longBowArrayList_Equals(const LongBowArrayList *a, const LongBowArrayList *b); + +/** + * Standard library free(3) wrapper for use as a destructor function for elements of a LongBowArrayList. + * + * The create functions for LongBowArrayList have an input parameter that is a pointer to a function that + * will be called for each element when the Array List is destroyed, and when an element is removed via longBowArrayList_RemoveAtIndex. + * This destroy function has a different calling signature than the standard library's free(3) function. + * This function is a wrapper providing the correct facade for the standard library free(3) function. + * + * @param [in,out] element A pointer to the pointer to an element to be destroyed. + */ +void longBowArrayList_StdlibFreeFunction(void **element); + +/** + * Replace the first occurance of an existing element in the given LongBowArrayList. + * + * Paragraphs Of Explanation + * + * @param [in] array A pointer to a LongBowArrayList instance. + * @param [in] old A pointer to an element in the list to replace. + * @param [in] new A pointer to an element that will replace old. + * + * @return true If the element was found and replaced. + * @return false If the element was not found. + */ +bool longBowArrayList_Replace(LongBowArrayList *array, const void *old, void *new); +#endif // LongBow_ARRAYLIST_H |