libds/include/vec.h

#ifndef LIBDS_VEC_HEADER
#define LIBDS_VEC_HEADER

#define LIBDS_VEC_CAPACITY 4

#include "libds.h"

/**
 * A vector struct.
 * The vector uses a dynamic array to accommodate all the elements.
 * Whenever the size limit is reached, the vector allocates a new array that is two times bigger.
 */
struct vec_s {
  /**
   * The data array of the vector.
   */
  void* data;
  /**
   * The maximum size of the vector.
   */
  int capacity;
  /**
   * The current number of items in the vector.
   */
  int size;
};

typedef struct vec_s vec;

/**
 * Initializes the vector. This uses malloc to get new memory for the array,
 * and therefore can fail.
 * @param vec the vector to initialize
 * @return LIBDS_SUCCESS if all goes well, LIBDS_MALLOC if an allocation fails.
 */
libds_result vec_init(vec* vec);
/**
 * Frees the vector, also freeing the dynamic array it uses for storage.
 * This leaves the data intact. Use vec_foreach to free the data if
 * it is no longer used.
 * @param vec the vector to free
 */
void vec_free(vec* vec);

/**
 * Adds an element to the vector
 * @param vec the vector to add the value to
 * @param val the value to add to the vector.
 * @return LIBDS_SUCCESS if all goes wellm LIBDS_MALLOC if an allocation fails.
 */
libds_result vec_add(vec* vec, void* val);
/**
 * Removes the given value from the vector
 * @param vec the vector to remove the value from
 * @param val the value to remove
 */
void vec_remove(vec* vec, void* val);

/**
 * Runs through every element in the vector, and compares it against the
 * given data using the given comparison function. If the comparison function returns
 * true, returns the element that was passed to it. If the comparison function returns
 * true for no element, returns NULL.
 * @param vec the vector to iterate through.
 * @param data the data to compare elements against
 * @param compare the comparison function
 * @return the first element that is matched by the comparison function, or NULL if none are matched.
 */
void* vec_find(vec* vec, void* data, compare_func compare);
/**
 * Runs through every element in the vector, and compares it against the
 * given data using the given comparison function. If the comparison function returns
 * true, calls the foreach function, passing it the element and the variable argument list.
 * Stops if any foreach function returns a nonzero code.
 * @param vec the vector to perform the operation on
 * @param data the data to pass the comparison function
 * @param compare the comparison function operating on the data and each element in the list.
 * @param foreach the function to be called on every element recognized by the comparison function
 * @param ... variable arguments to be passed on to the foreach function
 * @return 0 if all goes well, or the first nonzero code returned by foreach.
 */
int vec_foreach(vec* vec, void* data, compare_func compare, foreach_func foreach, ...);

/**
 * Gets the value at the given index of the vector.
 * @param vec the vector to get the value from
 * @param index the index to retreive a value from
 * @return pointer to the value, or, if the index is out of bounds (or there is nothing there) NULL.
 */
void* vec_index(vec* vec, int index);

#endif