/*------------------------------------------------------------------*/
/* dynarray.h                                                       */
/*------------------------------------------------------------------*/

#ifndef DYNARRAY_INCLUDED
#define DYNARRAY_INCLUDED

typedef struct DynArray *DynArray_T;
/* A DynArray_T is an array whose length can expand dynamically. */

DynArray_T DynArray_new(int iLength);
/* Return a new DynArray_T whose length is iLength.
   It is a checked runtime error for iLength to be negative. */

void DynArray_free(DynArray_T oDynArray);
/* Free oDynArray. */

int DynArray_getLength(DynArray_T oDynArray);
/* Return the length of oDynArray.
   It is a checked runtime error for oDynArray to be NULL. */

void *DynArray_get(DynArray_T oDynArray, int iIndex);
/* Return the iIndex'th element of oDynArray.
   It is a checked runtime error for oDynArray to be NULL or empty. 
   It is a checked runtime error for iIndex to be less than 0 or
   greater than or equal to the length of oDynArray. */

void DynArray_put(DynArray_T oDynArray, int iIndex, const void *pvItem);
/* Assign pvItem to the iIndex'th element of oDynArray.
   It is a checked runtime error for oDynArray to be NULL or empty. 
   It is a checked runtime error for iIndex to be less than 0 or
   greater than or equal to the length of oDynArray. */

void DynArray_add(DynArray_T oDynArray, const void *pvItem);
/* Add pvItem to the end of oDynArray, thus incrementing its length.
   It is a checked runtime error for oDynArray to be NULL. */

void DynArray_toArray(DynArray_T oDynArray, void **ppvArray);
/* Fill ppvArray with the elements of oDynArray.
   It is a checked runtime error for oDynArray or ppvArray to be NULL.
   It is an unchecked runtime error for ppvArray to be too small
   to hold all elements of oDynArray.  */

void DynArray_map(DynArray_T oDynArray, 
   void (*pfApply)(void *pvItem, void *pvExtra),
   const void *pvExtra);
/* Apply function *pfApply to each element of oDynArray, passing pvExtra
   as an extra argument.  That is, for each element pvItem of oDynArray, 
   call (*pfApply)(pvItem, pvExtra).
   It is a checked runtime error for oDynArray or pfApply to be NULL. */

void DynArray_sort(DynArray_T oDynArray,
   int (*pfCompare)(const void *pvItem1, const void *pvItem2));
/* Sort oDynArray in the order determined by *pfCompare.  
   *pfCompare should return -<0, 0, or >0 depending upon whether *pvItem1 
   is less than, equal to, or greater than *pvItem2, respectively.
   It is a checked runtime error for oDynArray or pfCompare to be NULL. */

int DynArray_search(DynArray_T oDynArray, void *pvSoughtItem,
   int (*pfCompare)(const void *pvItem1, const void *pvItem2));

/* Linear search oDynArray for *pvSoughtItem using *pfCompare to 
   determine equality.  Return the index at which *pvSoughtItem
   is found, or -1 if there is no such index.
   *pfCompare should return 0 if *pvItem1 is equal to pvItem2, 
   and non-0 otherwise.
   It is a checked runtime error for oDynArray or pfCompare to be 
   NULL. */

int DynArray_bsearch(DynArray_T oDynArray, void *pvSoughtItem,
   int (*pfCompare)(const void *pvItem1, const void *pvItem2));
/* Binary search oDynArray for *pvSoughtItem using *pfCompare to 
   determine equality.  Return the index at which *pvSoughtItem
   is found, or -1 if there is no such index.
   *pfCompare should return <0, 0, or >0 depending upon whether *pvItem1 
   is less than, equal to, or greater than *pvItem2, respectively.
   It is a checked runtime error for oDynArray or pfCompare to be 
   NULL. 
   It is an unchecked runtime error for oDynArray not to be sorted
   as determined by *pfCompare. */

#endif