libds/include/vec.h

100 lines
3.3 KiB
C

#ifndef LIBDS_VEC_HEADER
#define LIBDS_VEC_HEADER
#define LIBDS_VEC_CAPACITY 4
#include <stddef.h>
#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.
*/
size_t capacity;
/**
* The current number of items in the vector.
*/
size_t 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, size_t index);
/**
* Clears the vector, removing all elements from it
* but not resizing it down.
* @param vec the vector to clear.
*/
void vec_clear(vec* vec);
#endif