Dynamic Arrays
==============

Dynamically resizing arrays (a C equivalent to std::vector).

.. code:: cpp

   #include <util/darray.h>

.. struct:: darray

   The base dynamic array structure.

.. :c:macro:: DARRAY(type)

   Macro for a dynamic array based upon an actual type.  Use this with
   da_* macros.

.. member:: void *darray.array

   The array pointer.

.. member:: size_t darray.num

   The number of items within the array.

.. member:: size_t darray.capacity

   The capacity of the array.


Dynamic Array Macros
--------------------

These macro functions are used with variables created with the
**DARRAY** type macro.  When using these functions, do not use the
dynamic array value with a reference (&) operator.  For example:

.. code:: cpp

   /* creates an array of integers: 0..9 */
   DARRAY(int) array_of_integers;
   da_init(array_of_integers);

   for (size_t i = 0; i < 10; i++)
           da_push_back(array_of_integers, &i);

   [...]

   /* free when complete */
   da_free(array_of_integers);

.. function:: void da_init(da)

   Initializes a dynamic array.

   :param da: The dynamic array

---------------------

.. function:: void da_free(da)

   Frees a dynamic array.

   :param da: The dynamic array

---------------------

.. function:: void *da_end(da)

   Gets a pointer to the last value.

   :param da: The dynamic array
   :return:   The last value of a dynamic array, or *NULL* if empty.

---------------------

.. function:: void da_reserve(da, size_t capacity)

   Reserves a specific amount of buffer space for the dynamic array.

   :param da:       The dynamic array
   :param capacity: New capacity of the dynamic array

---------------------

.. function:: void da_resize(da, size_t new_size)

   Resizes the dynamic array with zeroed values.

   :param da:   The dynamic array
   :param size: New size of the dynamic array

---------------------

.. function:: void da_copy(da_dst, da_src)

   Makes a copy of a dynamic array.

   :param da_dst: The dynamic array to copy to
   :param da_src: The dynamic array to copy from

---------------------

.. function:: void da_copy_array(da, const void *src_array, size_t size)

   Makes a copy of an array pointer.

   :param da:        The dynamic array
   :param src_array: The array pointer to make a copy from
   :param size:      New size of the dynamic array

---------------------

.. function:: void da_move(da_dst, da_src)

   Moves one dynamic array variable to another without allocating new
   data.  *da_dst* is freed before moving, *da_dst* is set to *da_src*,
   then *da_src* is then zeroed.

   :param da_dst: Destination variable
   :param da_src: Source variable

---------------------

.. function:: size_t da_find(da, const void *item_data, size_t starting_idx)

   Finds a value based upon its data.  If the value cannot be found, the
   return value will be DARRAY_INVALID (-1).

   :param da:           The dynamic array
   :param item_data:    The item data to find
   :param starting_idx: The index to start from or 0 to search the
                        entire array

---------------------

.. function:: void da_push_back(da, const void *data)

   Pushes data to the back of the array.

   :param da:   The dynamic array
   :param data: Pointer to the new data to push

---------------------

.. function:: void *da_push_back_new(da)

   Pushes a zeroed value to the back of the array, and returns a pointer
   to it.

   :param da: The dynamic array
   :return:   Pointer to the new value

---------------------

.. function:: void da_push_back_array(da, const void *src_array, size_t item_count)

   Pushes an array of values to the back of the array.

   :param da:         The dynamic array
   :param src_array:  Pointer of the array of values
   :param item_count: Number of items to push back

---------------------

.. function:: void da_insert(da, size_t idx, const void *data)

   Inserts a value at a given index.

   :param da:   The dynamic array:
   :param idx:  Index where the new item will be inserted
   :param data: Pointer to the item data to insert

---------------------

.. function:: void *da_insert_new(da, size_t idx)

   Inserts a new zeroed value at a specific index, and returns a pointer
   to it.

   :param da:  The dynamic array
   :param idx: Index to insert at
   :return:    Pointer to the new value

---------------------

.. function:: void da_insert_da(da_dst, size_t idx, da_src)

   Inserts a dynamic array in to another dynamic array at a specific
   index.

   :param da_dst: Destination dynamic array being inserted in to
   :param idx:    Index to insert the data at
   :param da_src: The dynamic array to insert

---------------------

.. function:: void da_erase(da, size_t idx)

   Erases an item at a specific index.

   :param da:  The dynamic array
   :param idx: The index of the value to remove

---------------------

.. function:: void da_erase_item(da, const void *item_data)

   Erases an item that matches the value specified

   :param da:        The dynamic array
   :param item_data: Pointer to the data to remove

---------------------

.. function:: void da_erase_range(da, size_t start_idx, size_t end_idx)

   Erases a range of values.

   :param da:        The dynamic array
   :param start_idx: The starting index
   :param end_idx:   The ending index

---------------------

.. function:: void da_pop_back(da)

   Removes one item from the end of a dynamic array.

   :param da: The dynamic array

---------------------

.. function:: void da_join(da_dst, da_src)

   Pushes *da_src* to the end of *da_dst* and frees *da_src*.

   :param da_dst: The destination dynamic array
   :param da_src: The source dynamic array

---------------------

.. function:: void da_split(da_dst1, da_dst2, da_src, size_t split_idx)

   Creates two dynamic arrays by splitting another dynamic array at a
   specific index.  If the destination arrays are not freed, they will
   be freed before getting their new values.  The array being split will
   not be freed.

   :param da_dst1:   Dynamic array that will get the lower half
   :param da_dst2:   Dynamic array that will get the upper half
   :param da_src:    Dynamic array to split
   :param split_idx: Index to split *da_src* at

---------------------

.. function:: void da_move_item(da, size_t src_idx, size_t dst_idx)

   Moves an item from one index to another, moving data between if
   necessary.

   :param da:      The dynamic array
   :param src_idx: The index of the item to move
   :param dst_idx: The new index of where the item will be moved to

---------------------

.. function:: void da_swap(da, size_t idx1, size_t idx2)

   Swaps two values at the given indices.

   :param da: The dynamic array
   :param idx1: Index of the first item to swap
   :param idx2: Index of the second item to swap