DOCUMENTATION.md

Macros

TYPE

The macro TYPE defines the type of each element in a vector. Defining TYPE is required and will result in an error if it is not defined.

#define TYPE int
#include "vec.h"
#undef TYPE

NAME

The macro NAME is required only if TYPE is defined as something that could not be an identifier.

For example, if TYPE is char *, one must define NAME as well.

#define TYPE char *
#define NAME str
#include "vec.h"
#undef TYPE
#undef NAME

IS_EQUAL

#define IS_EQUAL(a, b) ...

The macro IS_EQUAL should return true if a is the same as b. This macro is built-in for anything that can be compared using the == operator, as well char *s using strcmp.

To change the definition, define a macro that takes two arguments and returns true or false. The following is an example:

struct pair {
	int first;
	int second;
};

#define IS_EQUAL(a, b) ((a).first == (b).first && (a).second == (b).second)

Functions

Note, all the documentation below assumes TYPE as been defined as foo.

#define TYPE foo

new

vec_foo_t *vec_foo_new(void);

The function vec_foo_new() dynamically creates and returns a pointer to a vec_foo_t. The caller is reponsible for freeing memory using vec_foo_delete(). If memory cannot be allocated, NULL is returned.

delete

void vec_int_delete(vec_int_t *v);

The function vec_foo_delete() frees all memory associated with the vector v.

from

vec_foo_t *vec_foo_from(foo *a, size_t n);

The function vec_foo_from() dynamically creates and returns a pointer to a vec_foo_t, filling the slots of the new vector with the first n elements of the array a. The caller is reponsible for freeing memory using vec_foo_delete().

with_capacity

vec_foo_t *vec_foo_with_capacity(size_t n);

The function vec_foo_with_capacity() dynamically creates and returns a pointer to a vec_foo_t with the capacity to hold n. This allows you to use knowledge you may have about the future size of a vector to minimize memory allocations. The caller is reponsible for freeing memory using vec_foo_delete(). If memory cannot be allocated, NULL is returned.

push

void vec_foo_push(vec_foo_t *v, foo x);

The function vec_foo_push() appends x to v.

pop

foo vec_foo_pop(vec_foo_t *v);

The function vec_foo_pop() removes and returns the last element in v. It is the caller's responsibility to ensure the vector is not empty when vec_foo_pop() is called.

get

foo vec_foo_get(vec_foo_t *v, size_t i);

The function vec_foo_get returns the element at index i of v. It is the caller's responsibility to ensure i is in-bounds.

set

void vec_foo_set(vec_foo_t *v, size_t i, foo x);

The function vec_foo_get sets the element at index i of v to x. It is the caller's responsibility to ensure i is in-bounds.

size

size_t vec_foo_size(vec_foo_t *v);

The function vec_foo_size returns the number of elements in v.

is_empty

bool vec_foo_is_empty(vec_foo_t *v);

The function vec_foo_is_empty returns true if v is empty, false otherwise.

resize

void vec_foo_resize(vec_foo_t *v, size_t s, foo x);

The function vec_foo_resize changes the size of v to s. If the new size is greater than the current size, each new slot is filled with x. If the new size if less than the current size, the vector is truncated and x is not used.

clear

void vec_foo_clear(vec_foo_t *v);

The function vec_foo_clear removes every element in v. This is done in constant time.

contains

void vec_foo_contains(vec_foo_t *v, foo x);

The function vec_foo_contains returns true if v contains x, false otherwise.

This relies on IS_EQUAL, and thus is built-in for anything that can be compared using the == operator, as well char *s using strcmp.

copy

void vec_foo_copy(vec_foo_t *v);

The function vec_foo_copy returns a shallow copy of v.