API

group array

Common definitions for arrays.

Defines

y_ARRAY_TYPE(T)

A define allowing users to define arrays for any type, a replacement for generic types.

The result is a struct with two fields: len (the length) as a size_t, and a, the actual array.

This is meant to be used in a typedef.

Parameters:
  • T – The type to turn into an array.

Returns:

An array type with the given type.

Pre:

T must be a valid type.

y_ARRAY_CONST_TYPE(T)

A define allowing users to define const arrays for any type, a replacement for generic types.

The result is a struct with two fields: len (the length) as a size_t, and a, the actual array.

This is meant to be used in a typedef.

Parameters:
  • T – The type to turn into an array.

Returns:

An array type with the given type.

Pre:

T must be a valid type.

y_ARRAY_INIT(arr, p, l)

A define to initialize a variable with an array type created by y_ARRAY_TYPE meant for a non-pointer.

arr must not be a pointer.

Parameters:
  • arr – The array struct to initialize.

  • p – The pointer to the actual array.

  • l – The length of the valid memory at p.

Pre:

arr must be an identifier.

Pre:

arr must not be a pointer.

Pre:

arr must have a type that was created by y_ARRAY_TYPE.

Pre:

p must not be NULL.

Pre:

l must be greater than zero.

y_ARRAY_INITP(arr, p, l)

A define to initialize a variable with an array type created by y_ARRAY_TYPE meant for a pointer.

arr must be a pointer.

Parameters:
  • arr – The array struct to initialize.

  • p – The pointer to the actual array.

  • l – The length of the valid memory at p.

Pre:

arr must be an identifier.

Pre:

arr must be a pointer.

Pre:

arr must have a type that was created by y_ARRAY_TYPE.

Pre:

p must not be NULL.

Pre:

l must be greater than zero.

y_i(p, i)

A define that will index an array type made by y_ARRAY_TYPE and do bounds checking.

The first argument must not be a pointer; see y_ip for an equivalent that takes a pointer. The index is cast to an unsigned type. Currently, it will abort on failure.

Both arguments must be non-side-effecting expressions. To ensure this, y_i is defined to take the address of the first argument in debug mode and dereference the pointer. This should cause compile errors unless the argument is an lvalues, which are non-side-effect expressions.

Parameters:
  • p – The array struct to index into.

  • i – The index.

Returns:

The element at index i if it is in range; aborts otherwise.

Pre:

p must have a type that was created by y_ARRAY_TYPE.

Pre:

p must not be an expression with side effects. Usually, it should just be an array identifier.

Pre:

i must not be an expression with side effects.

y_ip(p, i)

A define that will index an array type made by y_ARRAY_TYPE and do bounds checking.

The first argument must be a pointer; see y_ip for an equivalent that does not takes a pointer. The index is cast to an unsigned type. Currently, it will abort on failure.

Both arguments must be non-side-effecting expressions. To ensure this, y_ip is defined to take the address of the first argument in debug mode and dereference the pointer. This should cause compile errors unless the argument is an lvalues, which are non-side-effect expressions.

Parameters:
  • p – The array struct to index into.

  • i – The index.

Returns:

The element at index i if it is in range; aborts otherwise.

Pre:

p must have a type that was created by y_ARRAY_TYPE.

Pre:

p must not be a pointer.

Pre:

p must not be an expression with side effects. Usually, it should just be an array identifier.

Pre:

i must not be an expression with side effects.

group vector

Definitions and types for Yc’s vector (resizable array).

Defines

y_VEC_INVALID_IDX

A marker for an invalid index.

Typedefs

typedef struct y_vec *y_Vector

This is the actual vector type.

It is necessary to hide its inner workings from the user, so this is just a void pointer.

typedef struct y_tree *y_Tree

Public definition of Yc’s binary tree.

It is not good to expose the internals to the user, so they are hidden behind a void pointer type. It’s here because of C99 errors with Clang.

Functions

y_Vector y_vec_create(size_t cap, size_t esize, y_Destructor dtor, y_Copier copy)

Creates a vector with the specified capacity, using esize to figure out how much to allocate.

Parameters:
  • cap – The initial capacity that the vector should be created at. If it is 0, or less than 0, then the vector is allocated with a default size.

  • esize – The size of each element in the vector. This is best passed in using sizeof.

  • dtor – The destructor for vector elements. Can be NULL if no destructor is required.

  • copy – The copy function for elements. Can be NULL if special copying is not required (i.e., memcpy works).

Returns:

NULL on malloc error, a valid y_Vector otherwise.

Pre:

esize must not be 0.

y_Vector y_vec_createStringVec(size_t cap)

Creates a vector of y_Strings.

Parameters:

cap – The initial capacity of the vector.

Returns:

NULL on malloc error, a valid y_Vector otherwise.

y_Vector y_vec_createTreeVec(size_t cap, size_t esize, y_Destructor dtor, y_Copier copy)

Creates a vector of y_Trees, where the trees’ elements are esize large and use dtor as their destructor.

Parameters:
  • cap – The initial capacity of the vector.

  • esize – The size for the trees’ elements.

  • dtor – The destructor for the trees’ elements. Can be NULL if no destructor is required.

  • copy – The copy function for elements. Can be NULL if special copying is not required (ie, memcpy).

Returns:

NULL on malloc error, a valid y_Vector otherwise.

Pre:

esize must not be 0.

y_Status y_vec_copy(y_Vector d, const struct y_vec *s)

Copies one y_Vector into another.

If the destination’s capacity is enough to fit the data, the capacity is not changed, even if it is not the same as the source’s capacity. Otherwise, it is expanded to the source’s capacity.

Parameters:
  • d – The destination vector.

  • s – The source vector.

Returns:

y_STATUS_SUCCESS if the copy succeeded, a descriptive status value otherwise.

Pre:

d must not be NULL.

Pre:

s must not be NULL.

Pre:

d and s must not be the same vector.

Pre:

The element size of d must match the element size of s.

Pre:

d and s must have the same copy function.

size_t y_vec_len(const y_Vector v)

Returns the length of the vector.

This value is expected to change if any other y_vec function (excluding y_vec_get and y_vec_at) is called!

Parameters:

v – The vector whose length will be returned.

Returns:

The length (not capacity) of the vector.

Pre:

v must not be NULL.

size_t y_vec_cap(const y_Vector v)

Returns the capacity of the vector, which is the number of elements it can hold without expanding.

Parameters:

v – The vector whose capacity will be returned.

Returns:

The capacity of v.

Pre:

v must not be NULL.

size_t y_vec_esize(const y_Vector v)

Returns the element size of the vector, which is the size of elements.

This is mostly for users to check assumptions using assert().

Parameters:

v – The vector whose element size will be returned.

Returns:

The element size of v.

Pre:

v must not be NULL.

void *y_vec_get(const y_Vector v, size_t idx)

Returns a pointer to an index in the vector.

This value is expected to change if any other y_vec function (excluding y_vec_len and y_vec_at) is called!

This function only does an assert for bounds checks. Thus, when compiling a release, this function does no bounds checking at all. Only use if you know that your index is within bounds. However, using this function removes a branch.

Parameters:
  • v – The vector whose data will be returned.

  • idx – The index in the vector to get a pointer to.

Returns:

A pointer to the data at the index in the vector or null if there are no items in the vector or if the index is out of range.

Pre:

v must not be NULL.

Pre:

idx must be within the bounds of v.

void *y_vec_at(const y_Vector v, size_t idx)

Returns a pointer to an index in the vector.

This value is expected to change if any other y_vec function (excluding y_vec_len and y_vec_get) is called!

This will panic if idx is out of range.

Parameters:
  • v – The vector whose data will be returned.

  • idx – The index in the vector to get a pointer to.

Returns:

A pointer to the data at the index in the vector or null if there are no items in the vector or if the index is out of range.

Pre:

v must not be NULL.

void *y_vec_get_r(const y_Vector v, size_t idx)

Returns a pointer to an index in the vector in reverse order.

This value is expected to change if any other y_vec function (excluding y_vec_len and y_vec_at) is called!

This function only does an assert for bounds checks. Thus, when compiling a release, this function does no bounds checking at all. Only use if you know that your index is within bounds. However, using this function removes a branch.

Parameters:
  • v – The vector whose data will be returned.

  • idx – The index from the back the vector to get a pointer to.

Returns:

A pointer to the data at the index in the vector or null if there are no items in the vector or if the index is out of range.

Pre:

v must not be NULL.

Pre:

idx must be within the bounds of v.

void *y_vec_at_r(const y_Vector v, size_t idx)

Returns a pointer to an index in the vector in reverse order.

This value is expected to change if any other y_vec function (excluding y_vec_len and y_vec_get) is called!

This will panic if idx is out of range.

Parameters:
  • v – The vector whose data will be returned.

  • idx – The index in the vector to get a pointer to.

Returns:

A pointer to the data at the index in the vector or null if there are no items in the vector or if the index is out of range.

Pre:

v must not be NULL.

void *y_vec_last(const y_Vector v)

Returns a pointer to the last element in the vector.

This panics if there are no elements.

Parameters:

v – The vector.

Returns:

A pointer to the last element in the vector.

Pre:

v must not be NULL.

Pre:

v must have at least one element.

y_Status y_vec_expand(y_Vector v, size_t ncap)

Expands the provided vector to have a capacity of at least n elements.

It may end up with a larger capacity; it uses the growth factor to grow the vector.

Parameters:
  • v – The vector that will be expanded.

  • ncap – The number of elements that the vector should have capacity for.

Returns:

y_STATUS_SUCCESS if the vector was successfully expanded, or a status describing the error.

Pre:

v must not be NULL.

y_Status y_vec_setCapacity(y_Vector v, size_t ncap)

Sets the vector’s capacity to ncap (new capacity).

If ncap is less than the current length of the vector, those existing elements will be erased.

Parameters:
  • v – The vector to resize.

  • ncap – The new capacity for the vector.

Returns:

y_STATUS_SUCCESS if the vector was successfully expanded or contracted, or a status describing the error.

Pre:

v must not be NULL.

Pre:

ncap must not be 0.

y_Status y_vec_setLength(y_Vector v, size_t nlen)

Sets the vector’s length to nlen (new len).

If nlen is less than the current length of the vector, those existing elements will be erased. If nlen is greater than the current length, the new contents are set to all zeroes.

Parameters:
  • v – The vector to resize.

  • nlen – The new length for the vector.

Returns:

y_STATUS_SUCCESS if the vector was successfully expanded, or a status describing the error.

Pre:

v must not be NULL.

y_Status y_vec_add(y_Vector v, size_t idx, const void *ptr)

Copies the specified data into the vector at the index.

Whatever is at that index is moved to the last index. Thus, this procedure does not maintain the order of the elements. This panics if the index is greater than the length of the vector.

Parameters:
  • v – The vector that the data will be added to.

  • idx – The index of the vector that the data will be added to.

  • ptr – Pointer to the data that will be added to the vector.

Returns:

y_STATUS_SUCCESS if the data was added, or a status describing the error.

Pre:

v must not be NULL.

Pre:

idx must be within the bounds of v + 1.

Pre:

ptr must not be NULL.

Pre:

ptr must point to data that is at least as as large as the element size of v.

y_Status y_vec_nadd(y_Vector v, size_t idx, size_t n, const void *ptr)

Copies n elements of the specified data into the vector at the index.

Whatever is at that index and n - 1 elements after is moved to the last index. Thus, this procedure does not maintain the order of the elements. This panics if the index is greater than the length of the vector.

Parameters:
  • v – The vector that the data will be added to.

  • idx – The index of the vector that the data will be added to.

  • n – The number of elements to copy in.

  • ptr – Pointer to the data that will be added to the vector.

Returns:

y_STATUS_SUCCESS if the data was added, or a status describing the error.

Pre:

v must not be NULL.

Pre:

idx must be within the bounds of v + 1.

Pre:

n must be greater than 0.

Pre:

ptr must not be NULL.

Pre:

ptr must point to at least to n elements of a size that is at least as large as the element size of v.

y_Status y_vec_addString(y_Vector v, size_t idx, const char *str)

Add a string onto a vector at the specified index.Whatever is at that index and n - 1 elements after is moved to the last index.

Thus, this procedure does not maintain the order of the elements. This panics if the index is greater than the length of the vector.

Parameters:
  • v – The vector to add to.

  • str – The string to add. The data will be copied.

  • idx – The index to add the string at.

Returns:

y_STATUS_SUCCESS on success, an error code otherwise.

Pre:

v must not be NULL.

Pre:

v must be a string vector (created with y_vec_createStringVec()).

Pre:

idx must be within the bounds of v + 1.

Pre:

str must not be NULL.

y_Tree y_vec_addTree(y_Vector v, size_t idx)

Builds and adds a tree onto a vector at the specified index.

Whatever is at that index is moved to the last index. Thus, this procedure does not maintain the order of the elements. This panics if the index is greater than the length of the vector.

Parameters:
  • v – The vector to add to.

  • idx – The index to add the tree at.

Returns:

The newly-created tree, or NULL on failure.

Pre:

v must not be NULL.

Pre:

v must be a tree vector (created with y_vec_createTreeVec()).

Pre:

idx must be within the bounds of v + 1.

y_Status y_vec_push(y_Vector v, const void *ptr)

Push the specified data at the back of the vector and maintain the order of the elements.

Parameters:
  • v – The vector that the data will be added to.

  • ptr – Pointer to the data that will be added to the vector.

Returns:

y_STATUS_SUCCESS if the data was added, or a status describing the error.

Pre:

v must not be NULL.

Pre:

ptr must not be NULL.

Pre:

ptr must point to data that is at least as large as the element size of v.

y_Status y_vec_pushEmpty(y_Vector v, void *res)

Push empty data at the back of the vector and maintain the order of the elements, and returns the element in res.

Parameters:
  • v – The vector that the data will be added to.

  • res – Pointer to a pointer to return the data that was added.

Returns:

y_STATUS_SUCCESS if the data was added, or a status describing the error.

Pre:

v must not be NULL.

Pre:

res must not be NULL.

Pre:

res must point to data that is at least as large as the element size of v.

y_Status y_vec_npush(y_Vector v, size_t n, const void *ptr)

Push n elements of the specified data at the back of the vector and maintain the order of the elements.

Parameters:
  • v – The vector that the data will be added to.

  • n – The number of elements to copy in.

  • ptr – Pointer to the data that will be added to the vector.

Returns:

y_STATUS_SUCCESS if the data was added, or a status describing the error.

Pre:

v must not be NULL.

Pre:

n must be greater than 0.

Pre:

ptr must not be NULL.

Pre:

ptr must point to at least to n elements of a size that is at least as large as the element size of v.

y_Status y_vec_pushString(y_Vector v, const char *str)

Push a string onto a vector.

This function maintains the order of the elements.

Parameters:
  • v – The vector to push onto.

  • str – The string to push. The data will be copied.

Returns:

y_STATUS_SUCCESS on success, an error code otherwise.

Pre:

v must not be NULL.

Pre:

v must be a string vector (created with y_vec_createStringVec()).

Pre:

str must not be NULL.

y_Tree y_vec_pushTree(y_Vector v)

Push a tree onto a vector.

This function maintains the order of the elements.

Parameters:

v – The vector to push onto.

Returns:

The newly-created tree, or NULL on failure.

Pre:

v must not be NULL.

Pre:

v must be a tree vector (created with y_vec_createTreeVec()).

y_Status y_vec_pushAt(y_Vector v, size_t idx, const void *ptr)

Push the specified data at the specified index of the vector and maintain the order of the elements.

Parameters:
  • v – The vector that the data will be added to.

  • idx – The index of the vector where the data will be put.

  • ptr – Pointer to the data that will be added to the vector.

Returns:

y_STATUS_SUCCESS if the data was added, or a status describing the error.

Pre:

v must not be NULL.

Pre:

idx must be within the bounds of v + 1.

Pre:

ptr must not be NULL.

Pre:

ptr must point to data that is at least as large as the element size of v.

y_Status y_vec_npushAt(y_Vector v, size_t idx, size_t n, const void *ptr)

Push n elements of the specified data at the specified index of the vector and maintain the order of the elements.

Parameters:
  • v – The vector that the data will be added to.

  • idx – The index of the vector where the data will be put.

  • n – The number of elements to copy in.

  • ptr – Pointer to the data that will be added to the vector.

Returns:

y_STATUS_SUCCESS if the data was added, or a status describing the error.

Pre:

v must not be NULL.

Pre:

idx must be within the bounds of v + 1.

Pre:

n must be greater than 0.

Pre:

ptr must not be NULL.

Pre:

ptr must point to at least to n elements of a size that are at least as large as the element size of v.

y_Status y_vec_pushStringAt(y_Vector v, size_t idx, const char *str)

Pushes a string at the specified index onto the vector.

This function maintains the order of the elements.

Parameters:
  • v – The vector that the string will be added to.

  • idx – The index to push at.

  • str – The string to push.

Returns:

y_STATUS_SUCCESS on success, an error code otherwise.

Pre:

v must not be NULL.

Pre:

v must be a string vector (created with y_vec_createStringVec()).

Pre:

idx must be within the bounds of v + 1.

Pre:

str must not be NULL.

y_Tree y_vec_pushTreeAt(y_Vector v, size_t idx)

Creates and pushes a tree at the specified index onto the vector.

This function maintains the order of the elements.

Parameters:
  • v – The vector that the vector will be added to.

  • idx – The index to push at.

Returns:

The newly-created tree, or NULL on failure.

Pre:

v must not be NULL.

Pre:

v must be a tree vector (created with y_vec_createTreeVec()).

Pre:

idx must be within the bounds of v + 1.

void y_vec_remove(y_Vector v, size_t idx)

Deletes the data at the specified index and copies the data at the last index into the specified index.

This procedure does not maintain the order of the elements.

Parameters:
  • v – The vector that the data will be deleted from.

  • idx – The index of the vector where the data will be removed.

Pre:

v must not be NULL.

Pre:

idx must be within the bounds of v.

Pre:

v must have at least 1 element.

void y_vec_nremove(y_Vector v, size_t n, size_t idx)

Deletes n elements of the data at the specified index and copies the data at the last n indices into the specified index and following n - 1 indices.

This procedure does not maintain the order of the elements.

Parameters:
  • v – The vector that the data will be deleted from.

  • n – The number of elements to delete.

  • idx – The index of the vector where the data will be removed.

Pre:

v must not be NULL.

Pre:

idx must be within the bounds of v.

Pre:

n must be greater than 0.

Pre:

idx + n must be within the bounds of v.

Pre:

v must have at least n elements.

void y_vec_removeAll(y_Vector v)

Remove all elements.

Parameters:

v – The vector that the data will be deleted from.

Pre:

v must not be NULL.

void y_vec_pop(y_Vector v)

Pop the data at the back, maintaining the order of the elements.

Parameters:

v – The vector that the data will be deleted from.

Pre:

v must not be NULL.

Pre:

v must have at least 1 element.

void y_vec_popEmpty(y_Vector v)

Removes an empty element.

This is meant to be used when an error happens when trying to initialize the empty element.

Parameters:

v – The vector.

Pre:

v must not be NULL.

void y_vec_npop(y_Vector v, size_t n)

Pop n elements of the data at the back, maintaining the order of the elements.

Parameters:
  • v – The vector that the data will be deleted from.

  • n – The number of elements to delete.

Pre:

v must not be NULL.

Pre:

n must be greater than 0.

Pre:

v must have at least n elements.

void y_vec_popAt(y_Vector v, size_t idx)

Pop the data at the specified index, maintaining the order of the elements.

Parameters:
  • v – The vector that the data will be deleted from.

  • idx – The index of the vector where the data will be removed.

Pre:

v must not be NULL.

Pre:

idx must be within bounds of v.

Pre:

v must have at least 1 element.

void y_vec_npopAt(y_Vector v, size_t idx, size_t n)

Pop n elements of the data at the specified index, maintaining the order of the elements.

Parameters:
  • v – The vector that the data will be deleted from.

  • idx – The index of the vector where the data will be removed.

  • n – The number of elements to delete.

Pre:

v must not be NULL.

Pre:

idx must be within bounds of v.

Pre:

idx + n must be within bounds of v.

Pre:

n must be greater than 0.

Pre:

n must be less than the length of v.

y_Iterator y_vec_begin(const y_Vector v)

Creates and returns an iterator for v.

The iterator can be used as though it is a pointer to the current element (because it is); thus, it can just be dereferenced to get the data. Also, it will be NULL when there are no more elements, so that can be used as a loop condition.

Note: The returned iterator is invalidated if v changes at all. After that, it cannot be used.

Parameters:

v – The vector that will generate an iterator.

Returns:

An iterator for v.

Pre:

v must not be NULL.

y_Iterator y_vec_rbegin(const y_Vector v)

Creates and returns a reverse iterator for v.

The iterator can be used as though it is a pointer to the current element (because it is); thus, it can just be dereferenced to get the data. Also, it will be NULL when there are no more elements, so that can be used as a loop condition.

Note: The returned iterator is invalidated if v changes at all. After that, it cannot be used.

Parameters:

v – The vector that will generate an iterator.

Returns:

An iterator for v.

Pre:

v must not be NULL.

y_Iterator y_vec_next(const y_Vector v, const y_Iterator it)

Returns the next iterator (or rather, the next position for the iterator) for v and it.

Parameters:
  • v – The vector that will generate an iterator.

  • it – The current iterator.

Returns:

The next position of the iterator for v.

Pre:

v must not be NULL.

Pre:

it must not be NULL.

Pre:

it must be an iterator for v.

Pre:

it must be valid. This means that v has not been changed since it was initially created.

y_Iterator y_vec_rnext(const y_Vector v, const y_Iterator it)

Returns the next iterator (or rather, the next position for the iterator) for v and it going in reverse.

Parameters:
  • v – The vector that will generate an iterator.

  • it – The current iterator.

Returns:

The next position of the iterator for v.

Pre:

v must not be NULL.

Pre:

it must not be NULL.

Pre:

it must be an iterator for v.

Pre:

it must be valid. This means that v has not been changed since it was initially created.

size_t y_vec_bsearch(const y_Vector v, const void *item, const y_Comparator cmp)

Returns the index that item is at or y_VEC_INVALID_INDEX if item does not exist in the vector.

Parameters:
  • v – The vector that will generate an iterator.

  • item – The item to search for.

  • cmp – The comparator for items in the vector.

Returns:

The index the item is at or y_VEC_INVALID_INDEX if it does not exist.

Pre:

v must not be NULL.

Pre:

item must not be NULL.

Pre:

cmp must not be NULL.

Pre:

v must be sorted.

size_t y_vec_bsearch_add(const y_Vector v, const void *item, const y_Comparator cmp)

Returns the index that item is at or the index it should be inserted at to keep the array sorted.

Parameters:
  • v – The vector.

  • item – The item to search for.

  • cmp – The comparator for items in the vector.

Returns:

The index the item is at or at which to insert the item.

Pre:

v must not be NULL.

Pre:

item must not be NULL.

Pre:

cmp must not be NULL.

Pre:

v must be sorted.

bool y_vec_sorted(const y_Vector v, const y_Comparator cmp)

Returns true if v is sorted, according to cmp, false otherwise.

Parameters:
  • v – The vector to be tested.

  • cmp – The comparator for items in the vector.

Returns:

True if v is sorted, false otherwise.

Pre:

v must not be NULL.

Pre:

cmp must not be NULL.

void y_vec_free(y_Vector v)

Frees all of the data from the vector and the vector itself.

Parameters:

v – The vector that will be freed.

Pre:

v must not be NULL.

group svector

Definitions and types for Yc’s svector (resizable array that segments allocations such that no elements have to be moved).

Typedefs

typedef struct y_svec *y_SVector

This is the actual svector type.

It is necessary to hide its inner workings from the user, so this is just a void pointer.

Functions

y_SVector y_svec_create(size_t esize, y_Destructor dtor, y_Copier copy)

Creates an svector with the specified capacity, using esize to figure out how much to allocate.

Parameters:
  • esize – The size of each element in the vector. This is best passed in using sizeof.

  • dtor – The destructor for vector elements. Can be NULL if no destructor is required.

  • copy – The copy function for elements. Can be NULL if special copying is not required (ie, memcpy works).

Returns:

NULL on malloc error, a valid y_SVector otherwise.

Pre:

esize must not be 0.

y_Status y_svec_copy(y_SVector d, const y_SVector s)

Copies one y_SVector into another.

If the destination’s capacity is enough to fit the data, the capacity is not changed, even if it is not the same as the source’s capacity. Otherwise, it is expanded to the source’s capacity.

Parameters:
  • d – The destination vector.

  • s – The source vector.

Returns:

y_STATUS_SUCCESS if the copy succeeded, a descriptive status value otherwise.

Pre:

d must not be NULL.

Pre:

s must not be NULL.

Pre:

d and s must not be the same vector.

Pre:

The element size of d must match the element size of s.

Pre:

d and s must have the same copy function.

size_t y_svec_len(const y_SVector v)

Returns the length of the svector.

This value is expected to change if any other y_svec function (excluding y_svec_get() and y_svec_at()) is called!

Parameters:

v – The vector whose length will be returned.

Returns:

The length (not capacity) of the vector.

Pre:

v must not be NULL.

size_t y_svec_cap(const y_SVector v)

Returns the capacity of the vector, which is the number of elements it can hold without expanding.

Parameters:

v – The vector whose capacity will be returned.

Returns:

The capacity of v.

Pre:

v must not be NULL.

size_t y_svec_esize(const y_SVector v)

Returns the element size of the vector, which is the size of elements.

This is mostly for users to check assumptions using assert().

Parameters:

v – The vector whose element size will be returned.

Returns:

The element size of v.

Pre:

v must not be NULL.

void *y_svec_get(const y_SVector v, size_t idx)

Returns a pointer to an index in the svector.

This value is expected to change if any other y_svec function (excluding y_svec_len() and y_svec_at()) is called!

This function only does an assert for bounds checks. Thus, when compiling a release, this function does no bounds checking at all. Only use if you know that your index is within bounds. However, using this function removes a branch.

Parameters:
  • v – The vector whose data will be returned.

  • idx – The index in the vector to get a pointer to.

Returns:

A pointer to the data at the index in the vector.

Pre:

v must not be NULL.

Pre:

idx must be within the bounds of v.

void *y_svec_at(const y_SVector v, size_t idx)

Returns a pointer to an index in the svector.

This value is expected to change if any other y_svec function (excluding y_svec_len() and y_svec_get()) is called! Will panic if idx is out of range.

Parameters:
  • v – The vector whose data will be returned.

  • idx – The index in the vector to get a pointer to.

Returns:

A pointer to the data at the index in the vector.

Pre:

v must not be NULL.

void *y_svec_get_r(const y_SVector v, size_t idx)

Returns a pointer to an index in the svector.

This value is expected to change if any other y_svec function (excluding y_svec_len() and y_svec_at()) is called!

This function only does an assert for bounds checks. Thus, when compiling a release, this function does no bounds checking at all. Only use if you know that your index is within bounds. However, using this function removes a branch.

Parameters:
  • v – The vector whose data will be returned.

  • idx – The index from the back of the vector to get a pointer to.

Returns:

A pointer to the data at the index in the vector.

Pre:

v must not be NULL.

Pre:

idx must be within the bounds of v.

void *y_svec_at_r(const y_SVector v, size_t idx)

Returns a pointer to an index in the svector.

This value is expected to change if any other y_svec function (excluding y_svec_len() and y_svec_get()) is called! Will panic if idx is out of range.

Parameters:
  • v – The vector whose data will be returned.

  • idx – The index from the back of the vector to get a pointer to.

Returns:

A pointer to the data at the index in the vector.

Pre:

v must not be NULL.

void *y_svec_last(const y_SVector v)

Returns the last item in the vector, as though the last item is the top of a stack.

Parameters:

v – The vector whose data will be returned.

Returns:

A pointer to the data at the last index in the vector

Pre:

v must not be NULL.

y_Status y_svec_push(y_SVector v, const void *ptr)

Push the specified data at the back of the svector and maintain the order of the elements.

Parameters:
  • v – The vector that the data will be added to.

  • ptr – Pointer to the data that will be added to the vector.

Returns:

y_STATUS_SUCCESS if the data was added, or a status describing the error.

Pre:

v must not be NULL.

Pre:

ptr must not be NULL.

Pre:

ptr must point to data that is at least as large as the element size of v.

y_Status y_svec_npush(y_SVector v, size_t n, const void *ptr)

Push n elements of the specified data at the back of the svector and maintain the order of the elements.

Parameters:
  • v – The vector that the data will be added to.

  • n – The number of elements to copy in.

  • ptr – Pointer to the data that will be added to the vector.

Returns:

y_STATUS_SUCCESS if the data was added, or a status describing the error.

Pre:

v must not be NULL.

Pre:

n must be greater than 0.

Pre:

ptr must not be NULL.

Pre:

ptr must point to at least to n elements of a size that is at least as large as the element size of v.

y_Status y_svec_pushEmpty(y_SVector v, void *res)

Pushes an empty element and returns it.

Parameters:
  • v – The vector to push onto.

  • res – A pointer to a pointer to return a pointer to the new element.

Returns:

An error code, if any.

Pre:

v must not be NULL.

Pre:

res must not be NULL.

void y_svec_popEmpty(y_SVector v)

Removes an empty element.

This is meant to be used when an error happens when trying to initialize the empty element.

Parameters:

v – The vector.

Pre:

v must not be NULL.

void y_svec_pop(y_SVector v)

Pop the data at the back, maintaining the order of the elements.

Parameters:

v – The vector that the data will be deleted from.

Pre:

v must not be NULL.

Pre:

v must have at least 1 element.

void y_svec_npop(y_SVector v, size_t n)

Pop n elements of the data at the back, maintaining the order of the elements.

Parameters:
  • v – The vector that the data will be deleted from.

  • n – The number of elements to delete.

Pre:

v must not be NULL.

Pre:

n must be greater than 0.

Pre:

v must have at least n elements.

void y_svec_removeAll(y_SVector v)

Removes all items from the vector.

Parameters:

v – The vector to remove all items from.

Pre:

v must not be NULL.

void y_svec_free(y_SVector v)

Frees all of the data from the svector and the svector itself.

Parameters:

v – The vector that will be freed.

Pre:

v must not be NULL.

group nvector

Definitions and types for Yc’s nvector (resizable array that allows struct of arrays type construction for data-oriented programming).

Typedefs

typedef struct y_nvec *y_NVector

This is the actual nvector type.

It is necessary to hide its inner workings from the user, so this is just a void pointer.

Functions

y_NVector y_nvec_vcreate(size_t narrays, size_t cap, y_NDestructor dtor, y_NCopier copy, ...)

Creates an nvector with the specified capacity and destructor.

For variadic arguments, this function only accepts parameters of types size_t.

Parameters:
  • narrays – The number of arrays to allocate. There must be narrays variadic size_t arguments.

  • cap – The initial capacity that the nvector should be created at. If it is 0, or less than 0, then the vector is allocated with a default size.

  • dtor – The element destructor, or NULL if unnecessary.

  • copy – The copy function for elements. Can be NULL if special copying is not required (ie, memcpy works).

  • ... – The sizes of each element type. There must be narrays sizes. Must be size_t args only.

Returns:

The newly-created y_NVector or NULL on error.

Pre:

narrays must be greater than or equal to 2.

Pre:

All variadic arguments should be size_t.

Pre:

There must be narrays variadic arguments.

y_NVector y_nvec_lcreate(size_t narrays, size_t cap, y_NDestructor dtor, y_NCopier copy, va_list esizes)

Creates an nvector with the specified capacity and destructor.

The element sizes are passed in as a va_list.

The param esizes must only contain size_t arguments.

Parameters:
  • narrays – The number of arrays to allocate. There must be narrays va_list size_t arguments.

  • cap – The initial capacity that the nvector should be created at. If it is 0, or less than 0, then the vector is allocated with a default size.

  • dtor – The element destructor, or NULL if unnecessary.

  • copy – The copy function for elements. Can be NULL if special copying is not required (ie, memcpy works).

  • esizes – The sizes of each element type. There must be narrays sizes. Must be size_t args only.

Returns:

The newly-created y_NVector or NULL on error.

Pre:

narrays must be greater than or equal to 2.

Pre:

All variadic arguments should be size_t.

Pre:

There must be narrays variadic arguments.

y_NVector y_nvec_create(size_t narrays, size_t cap, y_NDestructor dtor, y_NCopier copy, size_t esizes[])

Creates an nvector with the specified capacity, destructor, and element sizes.

Parameters:
  • narrays – The number of arrays to allocate. There must be narrays va_list size_t arguments.

  • cap – The initial capacity that the nvector should be created at. If it is 0, or less than 0, then the vector is allocated with a default size.

  • dtor – The element destructor, or NULL if unnecessary.

  • copy – The copy function for elements. Can be NULL if special copying is not required (ie, memcpy works).

  • esizes – The sizes of each element type. There must be narrays sizes. Must be size_t args only.

Returns:

The newly-created y_NVector or NULL on error.

Pre:

narrays must be greater than or equal to 2.

Pre:

All variadic arguments should be size_t.

Pre:

There must be narrays variadic arguments.

y_Status y_nvec_copy(y_NVector d, const y_NVector s)

Copies one y_NVector into another.

If the destination’s capacity is enough to fit the data, the capacity is not changed, even if it is not the same as the source’s capacity. Otherwise, it is expanded to the source’s capacity.

Parameters:
  • d – The destination nvector.

  • s – The source nvector.

Returns:

y_STATUS_SUCCESS if the copy succeeded, a descriptive status value otherwise.

Pre:

d must not be NULL.

Pre:

s must not be NULL.

Pre:

d and s must have the same number of arrays.

Pre:

The element sizes of all corresponding arrays must match.

Pre:

d and s must have the same copy function.

size_t y_nvec_len(const y_NVector v)

Returns the length of the nvector.

This value is expected to change if any y_nvec function that changes the vector is called!

Parameters:

v – The nvector whose length will be returned.

Returns:

The length (not capacity) of the nvector.

Pre:

v must not be NULL.

size_t y_nvec_cap(const y_NVector v)

Returns the current capacity of the vector.

Parameters:

v – The nvector whose length will be returned.

Returns:

The capacity of v.

Pre:

v must not be NULL.

size_t y_nvec_esize(const y_NVector v, size_t arrayIdx)

Returns the element size of the vector at arrayIdx.

Parameters:
  • v – The vector whose element size will be returned.

  • arrayIdx – The index of the array to query.

Returns:

The element size of array arrayIdx in v.

Pre:

v must not be NULL.

Pre:

arrayIdx must be less than the number of arrays in v.

void *y_nvec_get(const y_NVector v, size_t arrayIdx, size_t idx)

Returns a pointer to an index in the array specified by arrayIdx.

This value is expected to change if any y_nvec function that changes the vector is called!

This function only does an assert for bounds checks. Thus, when compiling a release, this function does no bounds checking at all. Only use if you know that your index is within bounds.

Parameters:
  • v – The nvector whose data will be returned.

  • arrayIdx – The index of the array to retrieve data from.

  • idx – The index in the nvector to get a pointer to.

Returns:

A pointer to the data at the index in the nvector. This panics in debug mode if the index is out of range.

Pre:

v must not be NULL.

Pre:

arrayIdx must be less than the number of arrays in v.

Pre:

idx must be within the bounds of v.

void *y_nvec_at(const y_NVector v, size_t arrayIdx, size_t idx)

Returns a pointer to an index in the array.

This value is expected to change if any y_nvec function that changes the vector is called!

Parameters:
  • v – The nvector whose data will be returned.

  • arrayIdx – The index of the array to retrieve data from.

  • idx – The index in the nvector to get a pointer to.

Returns:

A pointer to the data at the index in the nvector. This panics if the index is out of range.

Pre:

v must not be NULL.

Pre:

arrayIdx must be less than the number of arrays in v.

y_Status y_nvec_expand(y_NVector v, size_t ncap)

Expands the provided nvector to have a capacity of at least n elements.

It may end up with a larger capacity; it uses the growth factor to grow v.

Parameters:
  • v – The nvector that will be expanded.

  • ncap – The number of elements that the nvector should have capacity for.

Returns:

y_STATUS_SUCCESS if the nvector was successfully expanded, or a status describing the error.

Pre:

v must not be NULL.

y_Status y_nvec_setCapacity(y_NVector v, size_t ncap)

Sets the nvector’s capacity to ncap (new capacity).

If ncap is less than the current length of the nvector, those existing elements will be erased.

Parameters:
  • v – The nvector to resize.

  • ncap – The new capacity for the nvector.

Returns:

y_STATUS_SUCCESS if the nvector was successfully expanded, or a status describing the error.

Pre:

v must not be NULL.

Pre:

ncap must be greater than 0.

y_Status y_nvec_setLength(y_NVector v, size_t nlen)

Sets the nvector’s length to nlen (new len).

If ncap is less than the current length of the nvector, those existing elements will be erased.

Parameters:
  • v – The nvector to resize.

  • nlen – The new length for the nvector.

Returns:

y_STATUS_SUCCESS if the nvector was successfully expanded, or a status describing the error.

Pre:

v must not be NULL.

y_Status y_nvec_vadd(y_NVector v, size_t idx, ...)

Copies the specified data into the nvector at the index.

Whatever is at that index is moved to the last index. Thus, this procedure does not maintain the order of the elements.

For variadic arguments, this function only accepts void pointers (void*).

Parameters:
  • v – The nvector that the data will be added to.

  • idx – The index of the nvector that the data will be added to.

  • ... – Pointers to the data that will be added to the nvector. There must be as many pointers as arrays in the nvector. Must be void pointers.

Returns:

y_STATUS_SUCCESS if the data was added, or a status describing the error.

Pre:

v must not be NULL.

Pre:

idx must be within the bounds of v + 1.

Pre:

All variadic arguments should be void*.

Pre:

All variadic arguments must not be NULL.

Pre:

All variadic arguments must point to data that is at least as large as the element size of the corresponding array.

Pre:

There must be exactly as many variadic arguments as there are arrays in v.

y_Status y_nvec_ladd(y_NVector v, size_t idx, va_list ptrs)

Copies the specified data into the nvector at the index.

Whatever is at that index is moved to the last index. Thus, this procedure does not maintain the order of the elements.

This function only accepts void pointers (void*) in ptrs.

Parameters:
  • v – The nvector that the data will be added to.

  • idx – The index of the nvector that the data will be added to.

  • ptrs – Pointers to the data that will be added to the nvector. There must be as many pointers as arrays in the nvector. Must be void pointers.

Returns:

y_STATUS_SUCCESS if the data was added, or a status describing the error.

Pre:

v must not be NULL.

Pre:

idx must be within the bounds of v + 1.

Pre:

All variadic arguments should be void*.

Pre:

All variadic arguments must not be NULL.

Pre:

All variadic arguments must point to data that is at least as large as the element size of the corresponding array.

Pre:

There must be exactly as many variadic arguments as there are arrays in v.

y_Status y_nvec_add(y_NVector v, size_t idx, void *ptrs)

Copies the specified data into the nvector at the index.

Whatever is at that index is moved to the last index. Thus, this procedure does not maintain the order of the elements.

Parameters:
  • v – The nvector that the data will be added to.

  • idx – The index of the nvector that the data will be added to.

  • ptrs – Pointers to the data that will be added to the nvector. There must be as many elements as arrays in the nvector.

Returns:

y_STATUS_SUCCESS if the data was added, or a status describing the error.

Pre:

v must not be NULL.

Pre:

idx must be within the bounds of v + 1.

Pre:

All variadic arguments should be void*.

Pre:

All variadic arguments must not be NULL.

Pre:

All variadic arguments must point to data that is at least as large as the element size of the corresponding array.

Pre:

There must be exactly as many variadic arguments as there are arrays in v.

y_Status y_nvec_vnadd(y_NVector v, size_t idx, size_t n, ...)

Copies n elements of the specified data into the nvector at the index.

Whatever is at that index and n - 1 elements after is moved to the last index. Thus, this procedure does not maintain the order of the elements.

For variadic arguments, this function only accepts void pointers (void*).

Parameters:
  • v – The nvector that the data will be added to.

  • idx – The index of the nvector that the data will be added to.

  • n – The number of elements to copy in.

  • ... – Pointers to the data that will be added to the nvector. There must be as many pointers as arrays in the nvector. Must be void pointers.

Returns:

y_STATUS_SUCCESS if the data was added, or a status describing the error.

Pre:

v must not be NULL.

Pre:

idx must be within the bounds of v + 1.

Pre:

n must be greater than 0.

Pre:

All variadic arguments should be void*.

Pre:

All variadic arguments must not be NULL.

Pre:

All variadic arguments must point to at least n elements of data that is at least as large as the element size of the corresponding array.

Pre:

There must be exactly as many variadic arguments as there are arrays in v.

y_Status y_nvec_lnadd(y_NVector v, size_t idx, size_t n, va_list ptrs)

Copies n elements of the specified data into the nvector at the index.

Whatever is at that index and n - 1 elements after is moved to the last index. Thus, this procedure does not maintain the order of the elements.

This function only accepts void pointers (void*) in ptrs.

Parameters:
  • v – The nvector that the data will be added to.

  • idx – The index of the nvector that the data will be added to.

  • n – The number of elements to copy in.

  • ptrs – Pointers to the data that will be added to the nvector. There must be as many pointers as arrays in the nvector. Must be void pointers.

Returns:

y_STATUS_SUCCESS if the data was added, or a status describing the error.

Pre:

v must not be NULL.

Pre:

idx must be within the bounds of v + 1.

Pre:

n must be greater than 0.

Pre:

All variadic arguments should be void*.

Pre:

All variadic arguments must not be NULL.

Pre:

All variadic arguments must point to at least n elements of data that is at least as large as the element size of the corresponding array.

Pre:

There must be exactly as many variadic arguments as there are arrays in v.

y_Status y_nvec_nadd(y_NVector v, size_t idx, size_t n, void *ptrs)

Copies n elements of the specified data into the nvector at the index.

Whatever is at that index and n - 1 elements after is moved to the last index. Thus, this procedure does not maintain the order of the elements.

Parameters:
  • v – The nvector that the data will be added to.

  • idx – The index of the nvector that the data will be added to.

  • n – The number of elements to copy in.

  • ptrs – Pointers to the data that will be added to the nvector. There must be as many pointers as arrays in the nvector. Must be void pointers.

Returns:

y_STATUS_SUCCESS if the data was added, or a status describing the error.

Pre:

v must not be NULL.

Pre:

idx must be within the bounds of v + 1.

Pre:

n must be greater than 0.

Pre:

All variadic arguments should be void*.

Pre:

All variadic arguments must not be NULL.

Pre:

All variadic arguments must point to at least n elements of data that is at least as large as the element size of the corresponding array.

Pre:

There must be exactly as many variadic arguments as there are arrays in v.

y_Status y_nvec_vpush(y_NVector v, ...)

Pushes the specified data at the back of the nvector, maintaining the order of the elements.

For variadic arguments, this function only accepts void pointers (void*).

Parameters:
  • v – The nvector that the data will be added to.

  • ... – Pointers to the data that will be added to the nvector. There must be as many pointers as arrays in the nvector. Must be void pointers.

Returns:

y_STATUS_SUCCESS if the data was added, or a status describing the error.

Pre:

v must not be NULL.

Pre:

All variadic arguments should be void*.

Pre:

All variadic arguments must not be NULL.

Pre:

All variadic arguments must point to data that is at least as large as the element size of the corresponding array.

Pre:

There must be exactly as many variadic arguments as there are arrays in v.

y_Status y_nvec_lpush(y_NVector v, va_list ptrs)

Pushes the specified data at the back of the nvector, maintaining the order of the elements.

This function only accepts void pointers (void*) in ptrs.

Parameters:
  • v – The nvector that the data will be added to.

  • ptrs – Pointers to the data that will be added to the nvector. There must be as many pointers as arrays in the nvector. Must be void pointers.

Returns:

y_STATUS_SUCCESS if the data was added, or a status describing the error.

Pre:

v must not be NULL.

Pre:

All variadic arguments should be void*.

Pre:

All elements in ptrs must not be NULL.

Pre:

All variadic arguments must point to data that is at least as large as the element size of the corresponding array.

Pre:

There must be exactly as many variadic arguments as there are arrays in v.

y_Status y_nvec_push(y_NVector v, void *ptrs)

Pushes the specified data at the back of the nvector, maintaining the order of the elements.

Parameters:
  • v – The nvector that the data will be added to.

  • ptrs – Pointers to the data that will be added to the nvector. There must be as many pointers as arrays in the nvector. Must be void pointers.

Returns:

y_STATUS_SUCCESS if the data was added, or a status describing the error.

Pre:

v must not be NULL.

Pre:

All variadic arguments should be void*.

Pre:

All elements in ptrs must not be NULL.

Pre:

All variadic arguments must point to data that is at least as large as the element size of the corresponding array.

Pre:

There must be exactly as many variadic arguments as there are arrays in v.

y_Status y_nvec_vnpush(y_NVector v, size_t n, ...)

Pushes n elements of the specified data at the back of the nvector, maintaining the order of the elements.

For variadic arguments, this function only accepts void pointers (void*).

Parameters:
  • v – The nvector that the data will be added to.

  • n – The number of elements to copy in.

  • ... – Pointers to the data that will be added to the nvector. There must be as many pointers as arrays in the nvector. Must be void pointers.

Returns:

y_STATUS_SUCCESS if the data was added, or a status describing the error.

Pre:

v must not be NULL.

Pre:

n must be greater than 0.

Pre:

All variadic arguments should be void*.

Pre:

All variadic arguments must not be NULL.

Pre:

All variadic arguments must point to at least n elements of data that is at least as large as the element size of the corresponding array.

Pre:

There must be exactly as many variadic arguments as there are arrays in v.

y_Status y_nvec_lnpush(y_NVector v, size_t n, va_list ptrs)

Pushes n elements of the specified data at the back of the nvector, maintaining the order of the elements.

This function only accepts void pointers (void*) in ptrs.

Parameters:
  • v – The nvector that the data will be added to.

  • n – The number of elements to copy in.

  • ptrs – Pointers to the data that will be added to the nvector. There must be as many pointers as arrays in the nvector. Must be void pointers.

Returns:

y_STATUS_SUCCESS if the data was added, or a status describing the error.

Pre:

v must not be NULL.

Pre:

n must be greater than 0.

Pre:

All variadic arguments should be void*.

Pre:

All elements in ptrs must not be NULL.

Pre:

All variadic arguments must point to data that is at least as large as the element size of the corresponding array.

Pre:

There must be exactly as many variadic arguments as there are arrays in v.

y_Status y_nvec_npush(y_NVector v, size_t n, void *ptrs)

Pushes n elements of the specified data at the back of the nvector, maintaining the order of the elements.

Parameters:
  • v – The nvector that the data will be added to.

  • n – The number of elements to copy in.

  • ptrs – Pointers to the data that will be added to the nvector. There must be as many pointers as arrays in the nvector. Must be void pointers.

Returns:

y_STATUS_SUCCESS if the data was added, or a status describing the error.

Pre:

v must not be NULL.

Pre:

n must be greater than 0.

Pre:

All variadic arguments should be void*.

Pre:

All elements in ptrs must not be NULL.

Pre:

All variadic arguments must point to data that is at least as large as the element size of the corresponding array.

Pre:

There must be exactly as many variadic arguments as there are arrays in v.

y_Status y_nvec_vpushAt(y_NVector v, size_t idx, ...)

Pushes the specified data at the specified index of the nvector, maintaining the order of the elements.

For variadic arguments, this function only accepts void pointers (void*).

Parameters:
  • v – The nvector that the data will be added to.

  • idx – The index of the nvector where the data will be put.

  • ... – Pointers to the data that will be added to the nvector. There must be as many pointers as arrays in the nvector. Must be void pointers.

Returns:

y_STATUS_SUCCESS if the data was added, or a status describing the error.

Pre:

v must not be NULL.

Pre:

idx must be within the bounds of v + 1.

Pre:

All variadic arguments should be void*.

Pre:

All variadic arguments must not be NULL.

Pre:

All variadic arguments must point to at least n elements of data that is at least as large as the element size of the corresponding array.

Pre:

There must be exactly as many variadic arguments as there are arrays in v.

y_Status y_nvec_lpushAt(y_NVector v, size_t idx, va_list ptrs)

Pushes the specified data at the specified index of the nvector, maintaining the order of the elements.

This function only accepts void pointers (void*) in ptrs.

Parameters:
  • v – The nvector that the data will be added to.

  • idx – The index of the nvector where the data will be put.

  • ptrs – Pointers to the data that will be added to the nvector. There must be as many pointers as arrays in the nvector. Must be void pointers.

Returns:

y_STATUS_SUCCESS if the data was added, or a status describing the error.

Pre:

v must not be NULL.

Pre:

idx must be within the bounds of v + 1.

Pre:

All variadic arguments should be void*.

Pre:

All variadic arguments must not be NULL.

Pre:

All variadic arguments must point to data that is at least as large as the element size of the corresponding array.

Pre:

There must be exactly as many variadic arguments as there are arrays in v.

y_Status y_nvec_pushAt(y_NVector v, size_t idx, void *ptrs)

Pushes the specified data at the specified index of the nvector, maintaining the order of the elements.

Parameters:
  • v – The nvector that the data will be added to.

  • idx – The index of the nvector where the data will be put.

  • ptrs – Pointers to the data that will be added to the nvector. There must be as many pointers as arrays in the nvector. Must be void pointers.

Returns:

y_STATUS_SUCCESS if the data was added, or a status describing the error.

Pre:

v must not be NULL.

Pre:

idx must be within the bounds of v + 1.

Pre:

ptrs must not be NULL.

Pre:

All elements in ptrs must not be NULL.

Pre:

All elements in ptrs must point to data that is at least as large as the element size of the corresponding array.

Pre:

There must be at least as many elements in ptrs as there are arrays in v.

y_Status y_nvec_vnpushAt(y_NVector v, size_t idx, size_t n, ...)

Pushes n elements of the specified data at the specified index of the nvector, maintaining the order of the elements.

For variadic arguments, this function only accepts void pointers (void*).

Parameters:
  • v – The nvector that the data will be added to.

  • idx – The index of the nvector where the data will be put.

  • n – The number of elements to copy in.

  • ... – Pointers to the data that will be added to the nvector. There must be as many pointers as arrays in the nvector. Must be void pointers.

Returns:

y_STATUS_SUCCESS if the data was added, or a status describing the error.

Pre:

v must not be NULL.

Pre:

idx must be within the bounds of v + 1.

Pre:

n must be greater than 0.

Pre:

All variadic arguments should be void*.

Pre:

All variadic arguments must not be NULL.

Pre:

All variadic arguments must point to at least n elements of data that is at least as large as the element size of the corresponding array.

Pre:

There must be exactly as many variadic arguments as there are arrays in v.

y_Status y_nvec_lnpushAt(y_NVector v, size_t idx, size_t n, va_list ptrs)

Pushes n elements of the specified data at the specified index of the nvector, maintaining the order of the elements.

This function only accepts void pointers (void*) in ptrs.

Parameters:
  • v – The nvector that the data will be added to.

  • idx – The index of the nvector where the data will be put.

  • n – The number of elements to copy in.

  • ptrs – Pointers to the data that will be added to the nvector. There must be as many pointers as arrays in the nvector. Must be void pointers.

Returns:

y_STATUS_SUCCESS if the data was added, or a status describing the error.

Pre:

v must not be NULL.

Pre:

idx must be within the bounds of v + 1.

Pre:

n must be greater than 0.

Pre:

All variadic arguments should be void*.

Pre:

All variadic arguments must not be NULL.

Pre:

All variadic arguments must point to at least n elements of data that is at least as large as the element size of the corresponding array.

Pre:

There must be exactly as many variadic arguments as there are arrays in v.

y_Status y_nvec_npushAt(y_NVector v, size_t idx, size_t n, void *ptrs)

Pushes n elements of the specified data at the specified index of the nvector, maintaining the order of the elements.

Parameters:
  • v – The nvector that the data will be added to.

  • idx – The index of the nvector where the data will be put.

  • n – The number of elements to copy in.

  • ptrs – Pointers to the data that will be added to the nvector. There must be as many pointers as arrays in the nvector. Must be void pointers.

Returns:

y_STATUS_SUCCESS if the data was added, or a status describing the error.

Pre:

v must not be NULL.

Pre:

idx must be within the bounds of v + 1.

Pre:

n must be greater than 0.

Pre:

ptrs must not be NULL.

Pre:

All elements in ptrs must not be NULL.

Pre:

All elements in ptrs must point to at least n elements of data that is at least as large as the element size of the corresponding array.

Pre:

There must be at least as many elements in ptrs as there are arrays in v.

void y_nvec_remove(y_NVector v, size_t idx)

Deletes the data from all arrays at the specified index and copies the data at the last index in all arrays into the specified index.

This procedure does not maintain the order of the elements.

Parameters:
  • v – The nvector that the data will be deleted from.

  • idx – The index of the nvector where the data will be removed.

Pre:

v must not be NULL.

Pre:

idx must be within the bounds of v.

Pre:

v must have at least 1 element.

void y_nvec_nremove(y_NVector v, size_t idx, size_t n)

Deletes n elements of the data in all arrays at the specified index and copies the data at the last index in all arrays into the specified index.

This procedure does not maintain the order of the elements.

Parameters:
  • v – The nvector that the data will be deleted from.

  • idx – The index of the nvector where the data will be removed.

  • n – The number of elements to delete.

Pre:

v must not be NULL.

Pre:

idx must be within the bounds of v.

Pre:

n must be greater than 0.

Pre:

idx + n must be within the bounds of v.

Pre:

v must have at least n elements.

void y_nvec_pop(y_NVector v)

Pops the data in all arrays at the back, maintaining the order of the elements.

Parameters:

v – The nvector that the data will be deleted from.

Pre:

v must not be NULL.

Pre:

v must not be NULL.

Pre:

v must have at least 1 element.

void y_nvec_npop(y_NVector v, size_t n)

Pops n elements of the data in all arrays at the back, maintaining the order of the elements.

Parameters:
  • v – The nvector that the data will be deleted from.

  • n – The number of elements to delete.

Pre:

v must not be NULL.

Pre:

n must be greater than 0.

Pre:

v must have at least n elements.

void y_nvec_popAt(y_NVector v, size_t idx)

Pops the data in all arrays at the specified index, maintaining the order of the elements.

Parameters:
  • v – The nvector that the data will be deleted from.

  • idx – The index of the nvector where the data will be removed.

Pre:

v must not be NULL.

Pre:

idx must be within bounds of v.

void y_nvec_npopAt(y_NVector v, size_t idx, size_t n)

Pops n elements of the data in all arrays at the specified index, maintaining the order of the elements.

Parameters:
  • v – The nvector that the data will be deleted from.

  • idx – The index of the nvector where the data will be removed.

  • n – The number of elements to delete.

Pre:

v must not be NULL.

Pre:

idx must be within bounds of v.

Pre:

idx + n must be within bounds of v.

Pre:

n must be greater than 0.

Pre:

n must be less than the length of v.

y_Iterator y_nvec_begin(const y_NVector v)

Creates and returns an iterator for v.

The iterator cannot be used as though it is a pointer to the current element; use y_nvec_item(). Also, it will be NULL when there are no more elements, so that can be used as a loop condition.

Note: The returned iterator is invalidated if v changes at all. After that, it cannot be used.

Parameters:

v – The vector that will generate an iterator.

Returns:

An iterator for v.

Pre:

v must not be NULL.

y_Iterator y_nvec_rbegin(const y_NVector v)

Creates and returns a reverse iterator for v.

The iterator cannot be used as though it is a pointer to the current element; use y_nvec_item(). Also, it will be NULL when there are no more elements, so that can be used as a loop condition.

Note: The returned iterator is invalidated if v changes at all. After that, it cannot be used.

Parameters:

v – The vector that will generate an iterator.

Returns:

An iterator for v.

Pre:

v must not be NULL.

y_Iterator y_nvec_next(const y_NVector v, const y_Iterator it)

Returns the next iterator (or rather, the next position for the iterator).

Parameters:
  • v – The vector that will generate an iterator.

  • it – The current iterator.

Returns:

The next position of the iterator for v.

Pre:

v must not be NULL.

Pre:

it must not be NULL.

Pre:

it must be an iterator for v.

Pre:

it must be valid. This means that v has not been changed since it was initially created.

y_Iterator y_nvec_rnext(const y_NVector v, const y_Iterator it)

Returns the next iterator (or rather, the next position for the iterator), going in reverse.

Parameters:
  • v – The vector that will generate an iterator.

  • it – The current iterator.

Returns:

The next position of the iterator for v.

Pre:

v must not be NULL.

Pre:

it must not be NULL.

Pre:

it must be an iterator for v.

Pre:

it must be valid. This means that v has not been changed since it was initially created.

void *y_nvec_item(const y_NVector v, const y_Iterator it, size_t arrayIdx)

Returns the item in the array at arrayIdx that corresponds to it’s position.

Parameters:
  • v – The vector to query.

  • it – The current iterator.

  • arrayIdx – The index of the array to query.

Returns:

A pointer to the element corresponding to the array and iterator.

void y_nvec_free(y_NVector v)

Frees all of the data from the nvector and the nvector itself.

Parameters:

v – The nvector that will be freed.

Pre:

v must not be NULL.

group stack

Definitions and types for Yc’s stack (resizable array, top at end).

Typedefs

typedef struct y_vec *y_Stack

This is the actual stack type.

It is necessary to hide its inner workings from the user, so this is just a void pointer.

Functions

y_Stack y_stack_create(size_t cap, size_t esize, y_Destructor dtor, y_Copier copy)

Creates a stack with the specified capacity, using esize to figure out how much to allocate.

Parameters:
  • cap – The initial capacity that the stack should be created at. If it is 0, then the stack is allocated with a default size.

  • esize – The size of each element in the vector. This is best passed in using sizeof.

  • dtor – The destructor for stack elements. Can be NULL if no destructor is required.

  • copy – The copy function for elements. Can be NULL if special copying is not required (ie, memcpy works).

Returns:

NULL on malloc error, a valid y_Stack otherwise.

Pre:

esize must not be 0.

size_t y_stack_len(const y_Stack s)

Returns the length of the stack.

This value is expected to change if any other y_stack function (excluding y_stack_top() and y_stack_item()) is called!

Parameters:

s – The stack whose length will be returned.

Returns:

The length (not capacity) of the stack.

Pre:

s must not be NULL.

size_t y_stack_cap(const y_Stack s)

Returns the capacity of the stack, which is the number of elements it can hold without expanding.

Parameters:

s – The stack whose capacity will be returned.

Returns:

The capacity of s.

Pre:

s must not be NULL.

size_t y_stack_esize(const y_Stack s)

Returns the element size of the stack, which is the size of elements.

Parameters:

s – The stack whose element size will be returned.

Returns:

The element size of s.

Pre:

s must not be NULL.

void *y_stack_top(const y_Stack s)

Returns a pointer to the top item on s and panics if there are no elements in s.

Parameters:

s – The stack to query.

Returns:

A pointer to the top item of s.

Pre:

s must not be NULL.

void *y_stack_item(const y_Stack s, size_t idx)

Returns a pointer to the item idx away from the top.

Panics if there are no elements in s, or if idx is out of range.

Parameters:
  • s – The stack to query.

  • idx – The index of the item to return.

Returns:

A pointer to the item idx away from the top of stack.

Pre:

s must not be NULL.

Pre:

idx must be within the bounds of s.

y_Status y_stack_setCapacity(y_Stack s, size_t ncap)

Sets the stack’s capacity to ncap (new capacity).

If ncap is less than the current length of the stack, those existing elements will be erased.

Parameters:
  • s – The stack to resize.

  • ncap – The new capacity for the stack.

Returns:

y_STATUS_SUCCESS if the stack was successfully expanded or shrunk, or a status describing the error.

Pre:

s must not be NULL.

Pre:

ncap must not be 0.

y_Status y_stack_push(y_Stack s, void *ptr)

Pushes the data at ptr onto the top of s.

Parameters:
  • s – The stack to push onto.

  • ptr – A pointer to the data to push.

Returns:

y_STATUS_SUCCESS on success, or a descriptive error code.

Pre:

s must not be NULL.

Pre:

ptr must not be NULL.

Pre:

ptr must point to data that is at least as large as the element size of v.

y_Status y_stack_npush(y_Stack s, size_t n, const void *ptr)

Pushes n items at ptr onto the top of s.

Parameters:
  • s – The stack to push onto.

  • n – The number of items to push.

  • ptr – A pointer to the data to push.

Pre:

s must not be NULL.

Pre:

n must be greater than 0.

Pre:

ptr must not be NULL.

Pre:

ptr must point to at least to n elements of a size that is at least as large as the element size of v.

void y_stack_pop(y_Stack s)

Pops the top item off of s.

Parameters:

s – The stack to pop off of.

Pre:

s must not be NULL.

Pre:

s must have at least 1 element.

void y_stack_npop(y_Stack s, size_t n)

Pops the n top items off of s.

Parameters:
  • s – The stack to pop off of.

  • n – The number of items to pop off.

Pre:

s must not be NULL.

Pre:

s must have at least n elements.

void y_stack_free(void *stack)

Frees stack and its data.

Parameters:

stack – The stack to free.

Pre:

stack must not be NULL.

group list

Definitions and types for Yc’s linked list.

Defines

y_LIST_INVALID_ID

A handle to an invalid ID.

Typedefs

typedef uint32_t y_ListID

This is the type of the ID of elements.

typedef struct y_list *y_List

This is the actual list type.

It is necessary to hide its inner workings from the user, so this is just a void pointer.

Functions

y_List y_list_create(size_t esize, y_Destructor dtor, y_Copier copy)

Creates a list using esize to figure out how much to allocate.

Parameters:
  • esize – The size of each element in the list. This is best passed in using sizeof.

  • dtor – The destructor for list elements. Can be NULL if no destructor is required.

  • copy – The copy function for elements. Can be NULL if special copying is not required (ie, memcpy works).

Returns:

NULL on malloc error, a valid y_List otherwise.

Pre:

esize must not be 0.

size_t y_list_len(const y_List l)

Returns the length of the list.

This value is expected to change if any other y_list function (excluding y_list_get) is called!

Parameters:

l – The list whose length will be returned.

Returns:

The length (not capacity) of the list.

Pre:

l must not be NULL.

size_t y_list_cap(const y_List l)

Returns the capacity of the list, which is the number of elements it can hold without expanding.

Parameters:

l – The list whose capacity will be returned.

Returns:

The capacity of l.

Pre:

l must not be NULL.

size_t y_list_esize(const y_List l)

Returns the element size of the list, which is the size of elements.

This is mostly for users to check assumptions using assert().

Parameters:

l – The list whose element size will be returned.

Returns:

The element size of l.

Pre:

l must not be NULL.

y_ListElem y_list_head(const y_List l)

Returns the head of the list.

This panics if there are no items in the list.

Parameters:

l – The list whose head will be returned.

Returns:

The head of l.

Pre:

l must not be NULL.

y_ListID y_list_head_id(const y_List l)

Returns the ID of the head of the list.

This returns y_LIST_INVALID_ID if there are no items in the list.

Parameters:

l – The list whose head’s ID will be returned.

Returns:

The head of l.

Pre:

l must not be NULL.

y_ListElem y_list_tail(const y_List l)

Returns the tail of the list.

This panics if there are no items in the list.

Parameters:

l – The list whose tail will be returned.

Returns:

The tail of l.

Pre:

l must not be NULL.

y_ListID y_list_tail_id(const y_List l)

Returns the ID of the tail of the list.

This returns y_LIST_INVALID_ID if there are no items in the list.

Parameters:

l – The list whose tail’s ID will be returned.

Returns:

The tail of l.

Pre:

l must not be NULL.

void *y_list_item(const y_List l, y_ListID id)

Returns a pointer to the item with ID id.

Parameters:
  • l – The list that will be queried.

  • id – The item of the item to return.

Returns:

The item with the specified ID.

Pre:

l must not be NULL.

Pre:

id must be valid.

bool y_list_hasPrev(const y_List l, y_ListID id)

Returns true if there is a previous item relative to the item at id.

This panics if there are no items in the list.

Parameters:
  • l – The list to query.

  • id – The ID of the item to query. This is the id field of a y_ListElem.

Returns:

True if there is an item previous to the item at id, false otherwise.

Pre:

l must not be NULL.

Pre:

id must be valid.

y_ListElem y_list_prev(const y_List l, y_ListID id)

Returns the previous item in the list relative to the at id.

This panics if there are no items in the list or there is no previous item.

Parameters:
  • l – The list to query.

  • id – The index of the item to query. This is the id field of a y_ListElem.

Returns:

The item previous to the item at id.

Pre:

l must not be NULL.

Pre:

id must be valid.

y_ListID y_list_prev_id(const y_List l, y_ListID id)

Returns the ID of the previous item in the list relative to the at id.

This panics if there are no items in the list.

Parameters:
  • l – The list to query.

  • id – The index of the item to query. This is the id field of a y_ListElem.

Returns:

The item previous to the item at id, or y_LIST_INVALID_ID if none.

Pre:

l must not be NULL.

Pre:

id must be valid.

bool y_list_hasNext(const y_List l, y_ListID id)

Returns true if there is a next item relative to the item at id.

This panics if there are no items in the list.

Parameters:
  • l – The list to query.

  • id – The index of the item to query. This is the id field of a y_ListElem.

Returns:

True if there is an item next to the item at id, false otherwise.

Pre:

l must not be NULL.

Pre:

id must be valid.

y_ListElem y_list_next(const y_List l, y_ListID id)

Returns the next item in the list relative to the at id.

This panics if there are no items in the list or there is no next item.

Parameters:
  • l – The list to query.

  • id – The index of the item to query. This is the id field of a y_ListElem.

Returns:

The item next to the item at id.

Pre:

l must not be NULL.

Pre:

id must be valid.

y_ListID y_list_next_id(const y_List l, y_ListID id)

Returns the ID of next item in the list relative to the at id.

This panics if there are no items in the list.

Parameters:
  • l – The list to query.

  • id – The index of the item to query. This is the id field of a y_ListElem.

Returns:

The item next to the item at id, or y_LIST_INVALID_ID if none.

Pre:

l must not be NULL.

Pre:

id must be valid.

y_Status y_list_prepend(y_List l, const void *data)

Prepends the data pointed to by data to the list.

This makes the data the new head of the list.

Parameters:
  • l – The list to prepend to.

  • data – A pointer to the data to prepend.

Returns:

A status code indicating success or failure.

Pre:

l must not be NULL.

Pre:

data must not be NULL.

Pre:

data must point to data of the same size as the elements of the list.

y_Status y_list_append(y_List l, const void *data)

Appends the data pointed to by data to the list.

This makes the data the new tail of the list.

Parameters:
  • l – The list to append to.

  • data – A pointer to the data to append.

Returns:

A status code indicating success or failure.

Pre:

l must not be NULL.

Pre:

data must not be NULL.

Pre:

data must point to data of the same size as the elements of the list.

y_Status y_list_addBefore(y_List l, y_ListID id, const void *data)

Adds the data pointed to by data before the item with ID id.

Parameters:
  • l – The list to add to.

  • id – The ID of the item to add before.

  • data – A pointer to the data to add.

Returns:

A status code indicating success or failure.

Pre:

l must not be NULL.

Pre:

data must not be NULL.

Pre:

data must point to data of the same size as the elements of the list.

y_Status y_list_naddBefore(y_List l, size_t n, y_ListID id, const void *data)

Adds n elements of the data pointed to by data before the item with ID id.

Parameters:
  • l – The list to add to.

  • n – The number of elements to add.

  • id – The ID of the item to add before.

  • data – A pointer to the data to add.

Returns:

A status code indicating success or failure.

Pre:

l must not be NULL.

Pre:

n must be at least 1.

Pre:

data must not be NULL.

Pre:

data must point to n elements of data of the same size as the elements of the list.

y_Status y_list_addAfter(y_List l, y_ListID id, const void *data)

Adds the data pointed to by data after the item with ID id.

Parameters:
  • l – The list to add to.

  • id – The ID of the item to add after.

  • data – A pointer to the data to add.

Returns:

A status code indicating success or failure.

Pre:

l must not be NULL.

Pre:

id must be the ID of a valid item in the list.

Pre:

data must not be NULL.

Pre:

data must point to data of the same size as the elements of the list.

y_Status y_list_naddAfter(y_List l, size_t n, y_ListID id, const void *data)

Adds n elements of the data pointed to by data after the item with ID id.

Parameters:
  • l – The list to add to.

  • n – The number of elements to add.

  • id – The ID of the item to add after.

  • data – A pointer to the data to add.

Returns:

A status code indicating success or failure.

Pre:

l must not be NULL.

Pre:

n must be at least 1.

Pre:

id must be the ID of a valid item in the list.

Pre:

data must not be NULL.

Pre:

data must point to data of the same size as the elements of the list.

void y_list_moveBefore(y_List l, y_ListID itemId, y_ListID id)

Moves the item with ID itemID to just before the item with ID id.

Parameters:
  • l – The list to edit.

  • itemId – The item to move.

  • id – The ID of the item to move to.

Pre:

l must not be NULL.

Pre:

id must be the ID of a valid item in the list.

Pre:

itemId must be the ID of a valid item in the list.

void y_list_nmoveBefore(y_List l, size_t n, y_ListID itemId, y_ListID id)

Moves n items, beginning with the item with ID itemID, to just before the item with ID id.

Panics if there are not at least n items between the items or before the end of the list.

Parameters:
  • l – The list to edit.

  • n – The number of elements to move.

  • itemId – The item to move.

  • id – The ID of the item to move to.

Pre:

l must not be NULL.

Pre:

n must be at least 1.

Pre:

id must be the ID of a valid item in the list.

Pre:

itemId must be the ID of a valid item in the list.

Pre:

There must be at least n items between the items or before the end of the list.

void y_list_moveAfter(y_List l, y_ListID itemId, y_ListID id)

Moves the item with ID itemID to just after the item with ID id.

Parameters:
  • l – The list to edit.

  • itemId – The item to move.

  • id – The ID of the item to move to.

Pre:

l must not be NULL.

Pre:

id must be the ID of a valid item in the list.

Pre:

itemId must be the ID of a valid item in the list.

void y_list_nmoveAfter(y_List l, size_t n, y_ListID itemId, y_ListID id)

Moves n items, beginning with the item with ID itemID, to just after the item with ID id.

Panics if there are not at least n items between the items or before the end of the list.

Parameters:
  • l – The list to edit.

  • n – The number of elements to move.

  • itemId – The item to move.

  • id – The ID of the item to move to.

Pre:

l must not be NULL.

Pre:

n must be at least 1.

Pre:

id must be the ID of a valid item in the list.

Pre:

itemId must be the ID of a valid item in the list.

Pre:

There must be at least n items between the items or before the end of the list.

void y_list_remove(y_List l, y_ListID id)

Removes the item from the list with ID id.

Parameters:
  • l – The list to add to.

  • id – The ID of the item to remove.

Pre:

l must not be NULL.

void y_list_nremove(y_List l, size_t n, y_ListID id)

Removes the n items from the list that start with the item of ID id.

Panics if there are not at least n items after the item.

Parameters:
  • l – The list to add to.

  • n – The number of items to remove.

  • id – The ID of the first item to remove.

Pre:

l must not be NULL.

Pre:

n must be at least 1.

Pre:

There must be at least n items after the item.

void y_list_free(y_List l)

Frees all of the data from the list and the list itself.

Parameters:

l – The list that will be freed.

Pre:

l must not be NULL.

struct y_ListElem
#include <list.h>

A type that describes elements of the list.

group tree

Definitions and types for Yc’s tree (binary tree).

Defines

y_TREE_NO_PARENT

Marker for node with no parent (the root node).

Typedefs

typedef size_t y_Node

A handle to a node.

This is the public definition of nodes in Y’s binary tree type. These are handles and are not to be used as anything but parameters to the functions defined below.

I do not want to expose the internals to the user, so they are hidden behind this typedef. Nodes are a little different, so that’s why this is not defined as a void pointer type.

Functions

y_Tree y_tree_create(size_t cap, size_t esize, y_Destructor dtor, y_Copier copy)

Creates a y_Tree with the specified node capacity and size, returning the handle to the tree.

Parameters:
  • cap – The node capacity of the tree.

  • esize – The node size of the tree. This is best passed in with sizeof.

  • dtor – Function to destruct elements, or NULL if unnecessary.

  • copy – The copy function for elements, or NULL if memcpy is sufficient.

Returns:

NULL if there was a malloc error, or a valid y_Tree if there were no errors.

Pre:

esize must not be 0.

y_Status y_tree_copy(y_Tree d, const struct y_tree *s)

Copies one y_Tree into another.

If the destination’s capacity is enough to fit the data, the capacity is not changed, even if it is not the same as the source’s capacity. Otherwise, it is expanded to the source’s capacity.

Parameters:
  • d – The destination tree.

  • s – The source tree.

Returns:

y_STATUS_SUCCESS if the copy succeeded, a descriptive status value otherwise.

Pre:

d must not be NULL.

Pre:

s must not be NULL.

Pre:

d and s must not be the same tree.

Pre:

The element size of d must match the element size of s.

Pre:

d and s must have the same copy function.

size_t y_tree_nodes(const y_Tree t)

Returns the number of nodes in the tree.

Parameters:

t – The tree that will be queried for the number of nodes.

Returns:

The number of nodes in the tree.

Pre:

t must not be NULL.

size_t y_tree_cap(const y_Tree t)

Returns the node capacity of t.

Parameters:

t – The tree whose capacity will be returned.

Returns:

The capacity of t.

Pre:

t must not be NULL.

size_t y_tree_esize(const y_Tree t)

Returns the node size of t.

Parameters:

t – The tree whose node size will be returned.

Returns:

The node size of t.

Pre:

t must not be NULL.

y_Node y_tree_root(void)

Returns a handle to the root node.

Returns:

a handle to the root node.

y_Node y_tree_parent(y_Node node)

Returns the parent of the given node.

Parameters:

node – The node whose parent will be returned.

Returns:

A handle to the parent of node, or y_TREE_NO_PARENT if the user passed in the root node.

y_Node y_tree_left(y_Node p)

Returns a handle to the left child of the parent.

This procedure returns a handle the child node exists. This is because that handle can then be used as a parameter to add the node.

Parameters:

p – The node whose left child will be returned.

Returns:

A handle to the left child of the given node.

y_Node y_tree_right(y_Node p)

Returns a handle to the right child of the parent.

This procedure returns a handle the child node exists. This is because that handle can then be used as a parameter to add the node.

Parameters:

p – The node whose right child will be returned.

Returns:

A handle to the right child of the given node.

bool y_tree_exists(const y_Tree t, y_Node node)

Returns true if the node exists, false otherwise.

Parameters:
  • t – The tree that the node may be in.

  • node – The node to test for.

Returns:

True if the node exists, false otherwise.

Pre:

t must not be NULL.

bool y_tree_hasLeft(const y_Tree t, y_Node p)

Tells the caller whether the specified node has a left child or not.

Parameters:
  • t – The tree that the node may be in.

  • p – The parent of the left node to test for.

Returns:

True if the left child exists, false otherwise.

Pre:

t must not be NULL.

bool y_tree_hasRight(const y_Tree t, y_Node p)

Tells the caller whether the specified node has a right child or not.

Parameters:
  • t – The tree that the node may be in.

  • p – The parent of the right node to test for.

Returns:

True if the right child exists, false otherwise.

Pre:

t must not be NULL.

void *y_tree_node(const y_Tree t, y_Node node)

Returns a pointer to the data in the node or NULL if the node does not exist.

Parameters:
  • t – The tree that the node exists in.

  • node – The node to get the data for.

Returns:

A pointer to the data if the node exists, NULL otherwise.

Pre:

t must not be NULL.

y_Status y_tree_empty(y_Tree t)

Empties tree and destroys all of its elements.

Parameters:

t – The y_Tree to empty.

Returns:

y_STATUS_SUCCESS on success, an error code otherwise.

Pre:

t must not be NULL.

y_Status y_tree_add(y_Tree t, y_Node node, const void *ptr)

Adds the data to the tree in the node.

This will overwrite the current data in the node, if it exists.

Parameters:
  • t – The tree to add the data to.

  • node – The node where the data will be added.

  • ptr – Pointer to the data to add.

Returns:

y_STATUS_SUCCESS if the data was successfully added, or an appropriate error code.

Pre:

t must not be NULL.

Pre:

node’s parent must exist.

Pre:

ptr must not be NULL.

Pre:

ptr must point to data that is at least as large as the element size of t.

y_Status y_tree_remove(y_Tree t, y_Node node)

Removes the node from the tree.

Parameters:
  • t – The tree to remove the node from.

  • node – The node to remove.

Returns:

y_STATUS_SUCCESS if the node was successfully removed, or an appropriate error code.

Pre:

t must not be NULL.

Pre:

node must not have children.

y_Status y_tree_removeAll(y_Tree t, y_Node node)

Removes the node from the tree.

The difference between this and y_tree_remove() is that y_tree_remove() will error if there are existing children, where this one will remove them all.

Parameters:
  • t – The tree to remove the node from.

  • node – The node to remove.

Returns:

y_STATUS_SUCCESS if the node was successfully removed, or an appropriate error code.

Pre:

t must not be NULL.

y_Iterator y_tree_begin(const y_Tree t)

Creates and returns an iterator for t, to be used in either y_tree_next_breadth() or y_tree_next_preorder().

The iterator can be used as though it is a pointer to the current element (because it is); thus, it can just be dereferenced to get the data. Also, it will be NULL when there are no more elements, so that can be used as a loop condition.

Note: The returned iterator is invalidated if v changes at all. After that, it cannot be used.

Parameters:

t – The tree that will generate an iterator.

Returns:

A breadth-first or preorder iterator for t.

Pre:

t must not be NULL.

y_Iterator y_tree_begin_inorder(const y_Tree t)

Creates and returns an iterator for t, to be used in y_tree_next_inorder().

The iterator can be used as though it is a pointer to the current element (because it is); thus, it can just be dereferenced to get the data. Also, it will be NULL when there are no more elements, so that can be used as a loop condition.

Note: The returned iterator is invalidated if v changes at all. After that, it cannot be used.

Parameters:

t – The tree that will generate an iterator.

Returns:

A preorder iterator for t.

Pre:

t must not be NULL.

y_Iterator y_tree_begin_postorder(const y_Tree t)

Creates and returns an iterator for t, to be used in y_tree_next_postorder().

The iterator can be used as though it is a pointer to the current element (because it is); thus, it can just be dereferenced to get the data. Also, it will be NULL when there are no more elements, so that can be used as a loop condition.

Note: The returned iterator is invalidated if v changes at all. After that, it cannot be used.

Parameters:

t – The tree that will generate an iterator.

Returns:

A postorder iterator for t.

Pre:

t must not be NULL.

y_Iterator y_tree_next_breadth(const y_Tree t, const y_Iterator it)

Returns the next iterator (or rather, the next position for the iterator) in a breadth-first search for t.

Note: to get a starting iterator for this procedure, use y_tree_begin().

Parameters:
  • t – The vector that will generate an iterator.

  • it – The current iterator.

Returns:

The next position of the iterator for t.

Pre:

t must not be NULL.

Pre:

it must not be NULL.

Pre:

it must be an iterator for t.

Pre:

it must be valid. This means that t has not been changed since it was initially created.

y_Iterator y_tree_next_preorder(const y_Tree t, const y_Iterator it)

Returns the next iterator (or rather, the next position for the iterator) in a preorder-traversal (equivalent to a depth-first search) for t.

Note: to get a starting iterator for this procedure, use y_tree_begin().

Parameters:
  • t – The vector that will generate an iterator.

  • it – The current iterator.

Returns:

The next position of the iterator for t.

Pre:

t must not be NULL.

Pre:

it must not be NULL.

Pre:

it must be an iterator for t.

Pre:

it must be valid. This means that t has not been changed since it was initially created.

y_Iterator y_tree_next_inorder(const y_Tree t, const y_Iterator it)

Returns the next iterator (or rather, the next position for the iterator) in a inorder-traversal for t.

Note: to get a starting iterator for this procedure, use y_tree_begin_inorder().

Parameters:
  • t – The vector that will generate an iterator.

  • it – The current iterator.

Returns:

The next position of the iterator for t.

Pre:

t must not be NULL.

Pre:

it must not be NULL.

Pre:

it must be an iterator for t.

Pre:

it must be valid. This means that t has not been changed since it was initially created.

y_Iterator y_tree_next_postorder(const y_Tree t, const y_Iterator it)

Returns the next iterator (or rather, the next position for the iterator) in a postorder-traversal for t.

Note: to get a starting iterator for this procedure, use y_tree_begin_postorder().

Parameters:
  • t – The vector that will generate an iterator.

  • it – The current iterator.

Returns:

The next position of the iterator for t.

Pre:

t must not be NULL.

Pre:

it must not be NULL.

Pre:

it must be an iterator for t.

Pre:

it must be valid. This means that t has not been changed since it was initially created.

void y_tree_free(y_Tree t)

Releases the memory allocated in the y_Tree.

Parameters:

t – The tree’s whose memory will be freed.

Pre:

t must not be NULL.

group ntree

Definitions and types for Yc’s ntree (tree that supports n children per node).

Defines

y_NTREE_INVALID_CHILD

A marker for an invalid child index.

Typedefs

typedef struct y_ntree *y_NTree

This is the public definition of Yc’s ntree.

It is not good to expose the internals to the user, so they are hidden behind a void pointer type.

typedef size_t y_Child

This is the public definition of children position indices.

Functions

y_NTree y_ntree_create(size_t children, size_t cap, size_t esize, y_Destructor dtor, y_Copier copy)

Creates a y_NTree with the specified node capacity and size, returning the handle to the tree.

Parameters:
  • children – The number of children each node should have.

  • cap – The node capacity of the tree.

  • esize – The node size of the tree.

  • dtor – A destructor for the values in the tree, or NULL.

  • copy – The copy function for elements. Can be NULL if special copying is not required (ie, memcpy works).

Returns:

NULL on malloc error, a valid y_NTree otherwise.

Pre:

esize must not be 0.

Pre:

children must be in the range [3, UINT32_t_MAX].

y_Status y_ntree_copy(y_NTree d, const y_NTree s)

Copies one y_NTree into another.

If the destination’s capacity is enough to fit the data, the capacity is not changed, even if it is not the same as the source’s capacity. Otherwise, it is expanded to the source’s capacity.

Parameters:
  • d – The destination tree.

  • s – The source tree.

Returns:

y_STATUS_SUCCESS if the copy succeeded, a descriptive status value otherwise.

Pre:

d must not be NULL.

Pre:

s must not be NULL.

Pre:

d and s must not be the same tree.

Pre:

The element size of d must match the element size of s.

Pre:

d and s must have the same copy function.

size_t y_ntree_nodes(const y_NTree t)

Returns the number of nodes in the tree.

Parameters:

t – The tree that will be queried for the number of nodes.

Returns:

The number of nodes in the tree.

Pre:

t must not be NULL.

size_t y_ntree_cap(const y_NTree t)

Returns the capacity (in nodes) of t.

Parameters:

t – The tree whose capacity will be returned.

Returns:

The capacity of t.

Pre:

t must not be NULL.

size_t y_ntree_esize(const y_NTree t)

Returns the node size of t.

Parameters:

t – The tree whose node size will be returned.

Returns:

The node size of t.

Pre:

t must not be NULL.

y_Child y_ntree_children(const y_NTree t)

Returns how many children each node have in the tree.

Parameters:

t – The tree to query for the number of children.

Returns:

The number of children that each node has.

Pre:

t must not be NULL.

y_Node y_ntree_root(void)

Returns a handle to the root node.

Returns:

A handle to the root node.

y_Node y_ntree_parent(const y_NTree t, y_Node node)

Returns the parent of the given node.

Parameters:
  • t – The tree to search for the parent.

  • node – The node whose parent will be returned.

Returns:

A handle to the parent of node, or y_TREE_NO_PARENT if the user passed in the root node, or if the node is invalid.

Pre:

t must not be NULL.

y_Node y_ntree_child(const y_NTree t, y_Node p, y_Child c)

Returns a handle to the child of the parent.

If c is greater than the number of children, this returns y_TREE_NO_PARENT.

Note: This procedure returns a handle the child or parent nodes exists. This is because those handles can then be used as a parameter to add the nodes. To check if they do exist, use the procedure y_ntree_exists().

Parameters:
  • t – The tree to search for the child.

  • p – The node whose left child will be returned.

  • c – The child whose handle will be returned.

Returns:

A handle to the child of the given node.

Pre:

t must not be NULL.

y_Child y_ntree_childPos(const y_NTree t, y_Node c)

Returns c’s position (which child of its parent it is).

If c is the root node, this returns y_NTREE_INVALID_CHILD.

Note: This procedure returns a handle the child or parent nodes exists. This is because those handles can then be used as a parameter to add the nodes. To check if they do exist, use the procedure y_ntree_exists().

Parameters:
  • t – The tree to query.

  • c – The child to query.

Returns:

The position of c in its parent.

Pre:

t must not be NULL.

bool y_ntree_exists(const y_NTree t, y_Node node)

Returns true if the node exists, false otherwise.

Parameters:
  • t – The tree that the node may be in.

  • node – The node to test for.

Returns:

True if the node exists, false otherwise.

Pre:

t must not be NULL.

bool y_ntree_hasChild(const y_NTree t, y_Node p, y_Child child)

Tells the caller whether the specified node has the specified child or not.

Parameters:
  • t – The tree that the node may be in.

  • p – The parent of the left node to test for.

  • child – The child to query for.

Returns:

True if the child exists, false otherwise.

Pre:

t must not be NULL.

void *y_ntree_node(const y_NTree t, y_Node node)

Returns a pointer to the data in the node or NULL if the node does not exist.

Parameters:
  • t – The tree that the node exists in.

  • node – The node to get the data for.

Returns:

A pointer to the data if the node exists, NULL otherwise.

Pre:

t must not be NULL.

y_Status y_ntree_empty(y_NTree t)

Empties tree and destroys all of its elements.

Parameters:

t – The y_NTree to empty.

Returns:

y_STATUS_SUCCESS on success, an error code otherwise.

Pre:

t must not be NULL.

y_Status y_ntree_add(y_NTree t, y_Node node, void *ptr)

Adds the data to the tree in the node.

This will overwrite the current data in the node, if it exists.

Parameters:
  • t – The tree to add the data to.

  • node – The node where the data will be added.

  • ptr – Pointer to the data to add.

Returns:

y_STATUS_SUCCESS if the data was successfully added, or an appropriate error code.

Pre:

t must not be NULL.

Pre:

node’s parent must exist.

Pre:

ptr must not be NULL.

Pre:

ptr must point to data that is at least as large as the element size of t.

y_Status y_ntree_remove(y_NTree t, y_Node node)

Removes the node from the tree.

Parameters:
  • t – The tree to remove the node from.

  • node – The node to remove.

Returns:

y_STATUS_SUCCESS if the node was successfully removed, or an appropriate error code.

Pre:

t must not be NULL.

Pre:

node must not have children.

y_Iterator y_ntree_begin(const y_NTree t)

Creates and returns an iterator for t, to be used in either y_ntree_next_breadth() or y_ntree_next_preorder().

The iterator can be used as though it is a pointer to the current element (because it is); thus, it can just be dereferenced to get the data. Also, it will be NULL when there are no more elements, so that can be used as a loop condition.

Note: The returned iterator is invalidated if v changes at all. After that, it cannot be used.

Parameters:

t – The tree that will generate an iterator.

Returns:

An iterator for t.

Pre:

t must not be NULL.

y_Iterator y_ntree_begin_postorder(const y_NTree t)

Creates and returns an iterator for t, to be used in y_ntree_next_postorder().

The iterator can be used as though it is a pointer to the current element (because it is); thus, it can just be dereferenced to get the data. Also, it will be NULL when there are no more elements, so that can be used as a loop condition.

Note: The returned iterator is invalidated if v changes at all. After that, it cannot be used.

Parameters:

t – The tree that will generate an iterator.

Returns:

A postorder iterator for t.

Pre:

t must not be NULL.

y_Iterator y_ntree_next_breadth(const y_NTree t, const y_Iterator it)

Returns the next iterator (or rather, the next position for the iterator) in a breadth-first search for t.

Note: to get a starting iterator for this procedure, use y_ntree_begin().

Parameters:
  • t – The vector that will generate an iterator.

  • it – The current iterator.

Returns:

The next position of the iterator for t.

Pre:

t must not be NULL.

Pre:

it must not be NULL.

Pre:

it must be an iterator for t.

Pre:

it must be valid. This means that t has not been changed since it was initially created.

y_Iterator y_ntree_next_preorder(const y_NTree t, const y_Iterator it)

Returns the next iterator (or rather, the next position for the iterator) in a preorder traversal (equivalent to depth-first search) for t.

Note: to get a starting iterator for this procedure, use y_ntree_begin().

Parameters:
  • t – The vector that will generate an iterator.

  • it – The current iterator.

Returns:

The next position of the iterator for t.

Pre:

t must not be NULL.

Pre:

it must not be NULL.

Pre:

it must be an iterator for t.

Pre:

it must be valid. This means that t has not been changed since it was initially created.

y_Iterator y_ntree_next_postorder(const y_NTree t, const y_Iterator it)

Returns the next iterator (or rather, the next position for the iterator) in a postorder-traversal for t.

Note: to get a starting iterator for this procedure, use y_ntree_begin_postorder().

Parameters:
  • t – The vector that will generate an iterator.

  • it – The current iterator.

Returns:

The next position of the iterator for t.

Pre:

t must not be NULL.

Pre:

it must not be NULL.

Pre:

it must be an iterator for t.

Pre:

it must be valid. This means that t has not been changed since it was initially created.

void y_ntree_free(y_NTree t)

Releases the memory allocated in the Y tree.

Parameters:

t – The tree’s whose memory will be freed.

Pre:

t must not be NULL.

group map

Public function definitions and types for Yc’s map type.

Typedefs

typedef struct y_map *y_Map

Public-facing type of private map.

typedef uint64_t (*y_Hasher)(const void *ptr)

Function type for hashing elements.

Param ptr:

A pointer to the element to hash.

Return:

A 64-bit hash for the element.

typedef bool (*y_Equal)(const void *key1, const void *key2)

Function type for comparing keys.

Param key1:

A pointer to the first key to compare.

Param key2:

A pointer to the second key to compare.

Return:

true if the keys are equal, false otherwise.

Functions

y_Map y_map_create(const float load, const size_t ksize, const size_t esize, const y_Hasher hash, const y_Equal eq, const y_Destructor kdtor, const y_Destructor vdtor)

Creates a new y_Map and returns it.

If the hash function is NULL, keys are required to be the same size as sizeof(uint64_t), and they will be used as the hash instead. The same goes for the compare function: if NULL, keys must be uint64_t because they will just be compared instead.

Parameters:
  • load – The max load factor for the map.

  • ksize – The size of the key type (best passed in with sizeof).

  • esize – The size of the value type (best passed in with sizeof).

  • hash – The hash function that will be used for the map.

  • eq – The equality function that will be used to compare keys.

  • kdtor – The destructor function for the key type, if necessary.

  • vdtor – The destructor function for the value type, if necessary.

Returns:

NULL on malloc error, a valid y_Map otherwise.

Pre:

ksize must be greater than 0.

Pre:

esize must be greater than 0.

Pre:

If cmp is NULL, ksize must be sizeof(uint64_t).

Pre:

If hash is NULL, ksize must be sizeof(uint64_t).

Pre:

load must be between (0, 1].

y_Map y_map_createStringKeyMap(const float load, const size_t esize, const y_Destructor vdtor)

Creates a y_Map that uses y_strs as the keys.

Parameters:
  • load – The max load factor for the map.

  • esize – The size of the value type.

  • vdtor – The destructor function for the value type, if necessary.

Returns:

NULL on malloc error, a valid y_Map otherwise.

Pre:

load must be between (0, 1].

Pre:

esize must be greater than 0.

y_Map y_map_createStringMap(const float load)

Creates a y_Map that uses y_strs as values and keys.

Parameters:

load – The max load factor for the map.

Returns:

NULL on malloc error, a valid y_Map otherwise.

Pre:

load must be between (0, 1].

bool y_map_exists(const y_Map m, const void *key)

Returns true if the map has the key, false otherwise.

Parameters:
  • m – The map to query.

  • key – The key to query for.

Returns:

true if the key exists in the map, false otherwise.

Pre:

m must not be NULL.

Pre:

key must not be NULL.

Pre:

m must not have been created with y_map_createStringMap().

bool y_map_existsStringKey(const y_Map m, const char *key)

Returns true if the map has the key, false otherwise.

Parameters:
  • m – The map to query.

  • key – The key to query for.

Returns:

true if the key exists in the map, false otherwise.

Pre:

m must not be NULL.

Pre:

key must not be NULL.

Pre:

m must have been created with y_map_createStringKeyMap().

bool y_map_existsStrings(const y_Map m, const char *key)

Returns true if the map has the key, false otherwise.

Parameters:
  • m – The map to query.

  • key – The key to query for.

Returns:

true if the key exists in the map, false otherwise.

Pre:

m must not be NULL.

Pre:

key must not be NULL.

Pre:

m must have been created with y_map_createStringMap().

bool y_map_exists_k(const y_Map m, const void *key, void *key_ptr)

Returns true if the map has the key, false otherwise.

If the item exists, key_ptr is assumed to be a pointer to a pointer to the key type and will be initialized with the pointer to the key.

Parameters:
  • m – The map to query.

  • key – The key to query for.

  • key_ptr – The key pointer to a pointer to fill in if the item exists.

Returns:

true if the key exists in the map, false otherwise.

Pre:

m must not be NULL.

Pre:

key must not be NULL.

Pre:

key_ptr must not be NULL.

Pre:

m must not have been created with y_map_createStringMap().

bool y_map_existsStringKey_k(const y_Map m, const char *key, y_str **key_ptr)

Returns true if the map has the key, false otherwise.

If the item exists, key_ptr is assumed to be a pointer to a pointer to the key type and will be initialized with the pointer to the key.

Parameters:
  • m – The map to query.

  • key – The key to query for.

  • key_ptr – The key pointer to a pointer to fill in if the item exists.

Returns:

true if the key exists in the map, false otherwise.

Pre:

m must not be NULL.

Pre:

key must not be NULL.

Pre:

key_ptr must not be NULL.

Pre:

m must have been created with y_map_createStringKeyMap().

bool y_map_existsStrings_k(const y_Map m, const char *key, y_str **key_ptr)

Returns true if the map has the key, false otherwise.

If the item exists, key_ptr is assumed to be a pointer to a pointer to the key type and will be initialized with the pointer to the key.

Parameters:
  • m – The map to query.

  • key – The key to query for.

  • key_ptr – The key pointer to a pointer to fill in if the item exists.

Returns:

true if the key exists in the map, false otherwise.

Pre:

m must not be NULL.

Pre:

key must not be NULL.

Pre:

key_ptr must not be NULL.

Pre:

m must have been created with y_map_createStringMap().

bool y_map_exists_v(const y_Map m, const void *key, void *val_ptr)

Returns true if the map has the key, false otherwise.

If the item exists, then val_ptr is assumed to be a pointer to a pointer to the value type and will be initialized with the pointer to the value.

Parameters:
  • m – The map to query.

  • key – The key to query for.

  • val_ptr – The value pointer to a pointer to fill in if the item exists.

Returns:

true if the key exists in the map, false otherwise.

Pre:

m must not be NULL.

Pre:

key must not be NULL.

Pre:

val_ptr must not be NULL.

Pre:

m must not have been created with y_map_createStringMap().

bool y_map_existsStringKey_v(const y_Map m, const char *key, void *val_ptr)

Returns true if the map has the key, false otherwise.

If the item exists, then val_ptr is assumed to be a pointer to a pointer to the value type and will be initialized with the pointer to the value.

Parameters:
  • m – The map to query.

  • key – The key to query for.

  • val_ptr – The value pointer to a pointer to fill in if the item exists.

Returns:

true if the key exists in the map, false otherwise.

Pre:

m must not be NULL.

Pre:

key must not be NULL.

Pre:

val_ptr must not be NULL.

Pre:

m must have been created with y_map_createStringKeyMap().

bool y_map_existsStrings_v(const y_Map m, const char *key, y_str **val_ptr)

Returns true if the map has the key, false otherwise.

If the item exists, then val_ptr is assumed to be a pointer to a pointer to the value type and will be initialized with the pointer to the value.

Parameters:
  • m – The map to query.

  • key – The key to query for.

  • val_ptr – The value pointer to a pointer to fill in if the item exists.

Returns:

true if the key exists in the map, false otherwise.

Pre:

m must not be NULL.

Pre:

key must not be NULL.

Pre:

val_ptr must not be NULL.

Pre:

m must have been created with y_map_createStringMap().

bool y_map_exists_kv(const y_Map m, const void *key, void *key_ptr, void *val_ptr)

Returns true if the map has the key, false otherwise.

If the item exists, key_ptr is assumed to be a pointer to a pointer to the key type and will be initialized with the pointer to the key. If the item exists, then val_ptr is assumed to be a pointer to a pointer to the value type and will be initialized with the pointer to the value.

Parameters:
  • m – The map to query.

  • key – The key to query for.

  • key_ptr – The key pointer to a pointer to fill in if the item exists.

  • val_ptr – The value pointer to a pointer to fill in if the item exists.

Returns:

true if the key exists in the map, false otherwise.

Pre:

m must not be NULL.

Pre:

key must not be NULL.

Pre:

key_ptr must not be NULL.

Pre:

val_ptr must not be NULL.

Pre:

m must not have been created with y_map_createStringMap().

bool y_map_existsStringKey_kv(const y_Map m, const char *key, y_str **key_ptr, void *val_ptr)

Returns true if the map has the key, false otherwise.

If the item exists, key_ptr is assumed to be a pointer to a pointer to the key type and will be initialized with the pointer to the key. If the item exists, then val_ptr is assumed to be a pointer to a pointer to the value type and will be initialized with the pointer to the value.

Parameters:
  • m – The map to query.

  • key – The key to query for.

  • key_ptr – The key pointer to a pointer to fill in if the item exists.

  • val_ptr – The value pointer to a pointer to fill in if the item exists.

Returns:

true if the key exists in the map, false otherwise.

Pre:

m must not be NULL.

Pre:

key must not be NULL.

Pre:

key_ptr must not be NULL.

Pre:

val_ptr must not be NULL.

Pre:

m must have been created with y_map_createStringKeyMap().

bool y_map_existsStrings_kv(const y_Map m, const char *key, y_str **key_ptr, y_str **val_ptr)

Returns true if the map has the key, false otherwise.

If the item exists, key_ptr is assumed to be a pointer to a pointer to the key type and will be initialized with the pointer to the key. If the item exists, then val_ptr is assumed to be a pointer to a pointer to the value type and will be initialized with the pointer to the value.

Parameters:
  • m – The map to query.

  • key – The key to query for.

  • key_ptr – The key pointer to a pointer to fill in if the item exists.

  • val_ptr – The value pointer to a pointer to fill in if the item exists.

Returns:

true if the key exists in the map, false otherwise.

Pre:

m must not be NULL.

Pre:

key must not be NULL.

Pre:

key_ptr must not be NULL.

Pre:

val_ptr must not be NULL.

Pre:

m must have been created with y_map_createStringMap().

void *y_map_at(const y_Map m, const void *key)

Returns a pointer to the value in the map that has the specified key.

If there is no value with key, this panics.

Parameters:
  • m – The map to search for the value.

  • key – The key for the value.

Returns:

A pointer to the value.

Pre:

m must not be NULL.

Pre:

key must not be NULL.

Pre:

key must point to data that is at least as large as the key size of m.

Pre:

m must not have been created with y_map_createStringMap().

void *y_map_atStringKey(const y_Map m, const char *key)

Returns a pointer to the value in the map that has the specified key.

If there is no value with key, this panics.

Parameters:
  • m – The map to search for the value.

  • key – The key for the value.

Returns:

A pointer to the value.

Pre:

m must not be NULL.

Pre:

key must not be NULL.

Pre:

key must point to data that is at least as large as the key size of m.

Pre:

m must have been created with y_map_createStringKeyMap().

void *y_map_atStrings(const y_Map m, const char *key)

Returns a pointer to the value in the map that has the specified key.

If there is no value with key, this panics.

Parameters:
  • m – The map to search for the value.

  • key – The key for the value.

Returns:

A pointer to the value.

Pre:

m must not be NULL.

Pre:

key must not be NULL.

Pre:

key must point to data that is at least as large as the key size of m.

Pre:

m must have been created with y_map_createStringMap().

size_t y_map_size(const y_Map m)

Returns the number of elements in the provided map.

Parameters:

m – The map whose size will be returned.

Returns:

The number of elements in the map.

Pre:

m must not be NULL.

size_t y_map_cap(const y_Map m)

Returns the maximum number of elements the provided map can hold (the capacity).

If the load of the map is less than 1, the map will never reach this capacity before expanding.

Parameters:

m – The map whose capacity will be returned.

Returns:

m’s capacity.

Pre:

m must not be NULL.

size_t y_map_ksize(const y_Map m)

Returns the key size of m.

Parameters:

m – The map whose key size will be returned.

Returns:

m’s key size.

Pre:

m must not be NULL.

size_t y_map_vsize(const y_Map m)

Returns the element size of m.

Parameters:

m – The map whose element size will be returned.

Returns:

m’s element size.

Pre:

m must not be NULL.

size_t y_map_max(const y_Map m)

Returns the maximum number of element m can hold without allocating more memory.

Parameters:

m – The map whose max size will be returned.

Returns:

m’s max size without allocating more memory.

Pre:

m must not be NULL.

float y_map_load(const y_Map m)

Returns the load factor that was set for the map.

Parameters:

m – The map whose load factor will be returned.

Returns:

m’s load factor.

Pre:

m must not be NULL.

y_Status y_map_insert(y_Map m, const void *key, const void *val)

Inserts the data pointed to by val at the key in the provided map.

If the value already exists, it is overwritten. If the y_Map was created with either y_map_createStringKeyMap() or y_map_createStringMap(), this will assert.

Parameters:
  • m – The map to insert into.

  • key – Pointer to the key to insert at.

  • val – Pointer to the value to insert.

Returns:

y_STATUS_SUCCESS if the value was successfully inserted, or a descriptive error code otherwise.

Pre:

m must not be NULL.

Pre:

m must not have been created with either y_map_createStringKeyMap() or y_map_createStringMap().

Pre:

key must not be NULL.

Pre:

key must point to data that is at least as large as the key size of m.

Pre:

val must not be NULL.

Pre:

val must point to data that is at least as large as the element size of m.

y_Status y_map_insertStringKey(y_Map m, const char *key, const void *val)

Inserts a value using the string as the key.

If the y_Map was not created using y_map_createStringKeyMap(), this will assert.

Parameters:
  • m – The map to insert into.

  • key – The string key.

  • val – Pointer to the value to insert.

Returns:

y_STATUS_SUCCESS if the value was successfully inserted, or a descriptive error code otherwise.

Pre:

m must not be NULL.

Pre:

m must have been created with y_map_createStringKeyMap().

Pre:

key must not be NULL.

Pre:

val must not be NULL.

Pre:

val must point to data that is at least as large as the element size of m.

y_Status y_map_insertStrings(y_Map m, const char *key, const char *val)

Inserts a string value using the string as the key.

If the y_Map was not created using y_map_createStringMap(), this will return y_STATUS_INVALID_STATE.

Parameters:
  • m – The map to insert into.

  • key – The string key.

  • val – The string value

Returns:

y_STATUS_SUCCESS if the value was successfully inserted, or a descriptive error code otherwise.

Pre:

m must not be NULL.

Pre:

m must have been created with y_map_createStringMap().

Pre:

key must not be NULL.

Pre:

val must not be NULL.

void y_map_remove(y_Map m, const void *key)

Removes the element at the specified key from the provided map.

This panics if there is no element with the specified key in the map.

Parameters:
  • m – The map whose element will be removed.

  • key – The key whose value will be removed.

Pre:

m must not be NULL.

Pre:

key must not be NULL.

Pre:

There must be data with a key of key.

Pre:

key must point to data that is at least as large as the key size of m.

Pre:

m must not have been created with y_map_createStringMap().

void y_map_removeStringKey(y_Map m, const char *key)

Removes the element at the specified key from the provided map.

This panics if there is no element with the specified key in the map.

Parameters:
  • m – The map whose element will be removed.

  • key – The key whose value will be removed.

Pre:

m must not be NULL.

Pre:

key must not be NULL.

Pre:

There must be data with a key of key.

Pre:

key must point to data that is at least as large as the key size of m.

Pre:

m must have been created with y_map_createStringMap().

void y_map_removeAll(y_Map m)

Removes all items from the map.

Parameters:

m – The map to remove all items from.

Pre:

m must not be NULL.

y_Iterator y_map_begin(const y_Map m)

Creates and returns an iterator for m.

The iterator can be used as though it is a pointer to the key of the current element (because it is); thus, it can just be dereferenced to get the key and passed to y_map_at() to get the data. Also, it will be NULL when there are no more elements, so that can be used as a loop condition.

Note: The returned iterator is invalidated if m changes at all. After that, it cannot be used.

Parameters:

m – The map that will generate an iterator.

Returns:

An iterator for m.

Pre:

m must not be NULL.

y_Iterator y_map_rbegin(const y_Map m)

Creates and returns a reverse iterator for m.

The iterator can be used as though it is a pointer to the key of the current element (because it is); thus, it can just be dereferenced to get the key and passed to y_map_at() to get the data. Also, it will be NULL when there are no more elements, so that can be used as a loop condition.

Note: The returned iterator is invalidated if m changes at all. After that, it cannot be used.

Parameters:

m – The map that will generate an iterator.

Returns:

An iterator for m.

Pre:

m must not be NULL.

y_Iterator y_map_next(const y_Map m, const y_Iterator it)

Returns the next iterator (or rather, the next position for the iterator) for m and it.

Parameters:
  • m – The map that will generate an iterator.

  • it – The current iterator.

Returns:

The next position of the iterator for m.

Pre:

m must not be NULL.

Pre:

it must not be NULL.

Pre:

it must be an iterator for m.

Pre:

it must be valid. This means that m has not been changed since it was initially created.

y_Iterator y_map_rnext(const y_Map m, const y_Iterator it)

Returns the next iterator (or rather, the next position for the iterator), going in reverse, for m and it.

Parameters:
  • m – The map that will generate an iterator.

  • it – The current iterator.

Returns:

The next position of the iterator for m.

Pre:

m must not be NULL.

Pre:

it must not be NULL.

Pre:

it must be an iterator for m.

Pre:

it must be valid. This means that m has not been changed since it was initially created.

void *y_map_key(const y_Map m, const y_Iterator it)

Returns the key for the given iterator it for map m.

Parameters:
  • m – The map to query for the key.

  • it – The iterator to get the key for.

Returns:

The key at the iterator.

Pre:

m must not be NULL.

Pre:

it must not be NULL.

Pre:

it must be an iterator for m.

Pre:

it must be valid. This means that m has not been changed since it was initially created.

void y_map_free(void *map)

Frees all allocated data associated with the map.

This function always succeeds.

Parameters:

map – The map whose data will be freed.

Pre:

map must not be NULL.

group imap

Public function definitions and types for Yc’s insertion-ordered map.

Typedefs

typedef struct y_imap *y_IMap

Public-facing type of private map.

Functions

y_IMap y_imap_create(const float load, const size_t ksize, const size_t esize, const y_Hasher hash, const y_Equal eq, const y_Destructor kdtor, const y_Destructor vdtor)

Creates a new y_IMap and returns it.

If the hash function is NULL, keys are required to be the same size as sizeof(uint64_t), and they will be used as the hash instead. The same goes for the compare function: if NULL, keys must be uint64_t because they will just be compared instead.

Parameters:
  • load – The max load factor for the map.

  • ksize – The size of the key type (best passed in with sizeof).

  • esize – The size of the value type (best passed in with sizeof).

  • hash – The hash function that will be used for the map.

  • eq – The equality function that will be used to compare keys.

  • kdtor – The destructor function for the key type, if necessary.

  • vdtor – The destructor function for the value type, if necessary.

Returns:

NULL on malloc error, a valid y_IMap otherwise.

Pre:

ksize must be greater than 0.

Pre:

esize must be greater than 0.

Pre:

If cmp is NULL, ksize must be sizeof(uint64_t).

Pre:

If hash is NULL, ksize must be sizeof(uint64_t).

Pre:

load must be between (0, 1].

y_IMap y_imap_createStringKeyMap(const float load, const size_t esize, const y_Destructor vdtor)

Creates a y_IMap that uses y_strs as the keys.

Parameters:
  • load – The max load factor for the map.

  • esize – The size of the value type.

  • vdtor – The destructor function for the value type, if necessary.

Returns:

NULL on malloc error, a valid y_IMap otherwise.

Pre:

load must be between (0, 1].

Pre:

esize must be greater than 0.

bool y_imap_exists(const y_IMap m, const void *key)

Returns true if the map has the key, false otherwise.

Parameters:
  • m – The map to query.

  • key – The key to query for.

Returns:

True if the key exists in the map, false otherwise.

Pre:

m must not be NULL.

Pre:

must have been created with y_imap_create();

Pre:

key must not be NULL.

bool y_imap_existsStringKey(const y_IMap m, const char *key)

Returns true if the map has the key, false otherwise.

Parameters:
  • m – The map to query.

  • key – The key to query for.

Returns:

True if the key exists in the map, false otherwise.

Pre:

m must not be NULL.

Pre:

must have been created with y_imap_createStringKey();

Pre:

key must not be NULL.

bool y_imap_exists_k(const y_IMap m, const void *key, void *key_ptr)

Returns true if the map has the key, false otherwise.

If the item exists, key_ptr is assumed to be a pointer to a pointer to the key type and will be initialized with the pointer to the key.

Parameters:
  • m – The map to query.

  • key – The key to query for.

  • key_ptr – The key pointer to a pointer to fill in if the item exists.

Returns:

True if the key exists in the map, false otherwise.

Pre:

m must not be NULL.

Pre:

must have been created with y_imap_create();

Pre:

key must not be NULL.

Pre:

key_ptr must not be NULL.

bool y_imap_existsStringKey_k(const y_IMap m, const char *key, void *key_ptr)

Returns true if the map has the key, false otherwise.

If the item exists, key_ptr is assumed to be a pointer to a pointer to the key type and will be initialized with the pointer to the key.

Parameters:
  • m – The map to query.

  • key – The key to query for.

  • key_ptr – The key pointer to a pointer to fill in if the item exists.

Returns:

True if the key exists in the map, false otherwise.

Pre:

m must not be NULL.

Pre:

must have been created with y_imap_createStringKey();

Pre:

key must not be NULL.

Pre:

key_ptr must not be NULL.

bool y_imap_exists_v(const y_IMap m, const void *key, void *val_ptr)

Returns true if the map has the key, false otherwise.

If the item exists, then val_ptr is assumed to be a pointer to a pointer to the value type and will be initialized with the pointer to the value.

Parameters:
  • m – The map to query.

  • key – The key to query for.

  • val_ptr – The value pointer to a pointer to fill in if the item exists.

Returns:

True if the key exists in the map, false otherwise.

Pre:

m must not be NULL.

Pre:

must have been created with y_imap_create();

Pre:

key must not be NULL.

Pre:

val_ptr must not be NULL.

bool y_imap_existsStringKey_v(const y_IMap m, const char *key, void *val_ptr)

Returns true if the map has the key, false otherwise.

If the item exists, then val_ptr is assumed to be a pointer to a pointer to the value type and will be initialized with the pointer to the value.

Parameters:
  • m – The map to query.

  • key – The key to query for.

  • val_ptr – The value pointer to a pointer to fill in if the item exists.

Returns:

True if the key exists in the map, false otherwise.

Pre:

m must not be NULL.

Pre:

must have been created with y_imap_createStringKey();

Pre:

key must not be NULL.

Pre:

val_ptr must not be NULL.

bool y_imap_exists_kv(const y_IMap m, const void *key, void *key_ptr, void *val_ptr)

Returns true if the map has the key, false otherwise.

If the item exists, key_ptr is assumed to be a pointer to a pointer to the key type and will be initialized with the pointer to the key. If the item exists, then val_ptr is assumed to be a pointer to a pointer to the value type and will be initialized with the pointer to the value.

Parameters:
  • m – The map to query.

  • key – The key to query for.

  • key_ptr – The key pointer to a pointer to fill in if the item exists.

  • val_ptr – The value pointer to a pointer to fill in if the item exists.

Returns:

True if the key exists in the map, false otherwise.

Pre:

m must not be NULL.

Pre:

must have been created with y_imap_create();

Pre:

key must not be NULL.

Pre:

key_ptr must not be NULL.

Pre:

val_ptr must not be NULL.

bool y_imap_existsStringKey_kv(const y_IMap m, const char *key, void *key_ptr, void *val_ptr)

Returns true if the map has the key, false otherwise.

If the item exists, key_ptr is assumed to be a pointer to a pointer to the key type and will be initialized with the pointer to the key. If the item exists, then val_ptr is assumed to be a pointer to a pointer to the value type and will be initialized with the pointer to the value.

Parameters:
  • m – The map to query.

  • key – The key to query for.

  • key_ptr – The key pointer to a pointer to fill in if the item exists.

  • val_ptr – The value pointer to a pointer to fill in if the item exists.

Returns:

True if the key exists in the map, false otherwise.

Pre:

m must not be NULL.

Pre:

must have been created with y_imap_createStringKey();

Pre:

key must not be NULL.

Pre:

key_ptr must not be NULL.

Pre:

val_ptr must not be NULL.

void *y_imap_at(const y_IMap m, const void *key)

Returns a pointer to the value in the map that has the specified key.

If there is no value with key, this panics.

Parameters:
  • m – The map to search for the value.

  • key – The key for the value.

Returns:

A pointer to the value.

Pre:

m must not be NULL.

Pre:

must have been created with y_imap_create();

Pre:

key must not be NULL.

Pre:

key must point to data that is at least as large as the key size of m.

void *y_imap_atStringKey(const y_IMap m, const char *key)

Returns a pointer to the value in the map that has the specified key.

If there is no value with key, this panics.

Parameters:
  • m – The map to search for the value.

  • key – The key for the value.

Returns:

A pointer to the value.

Pre:

m must not be NULL.

Pre:

must have been created with y_imap_createStringKey();

Pre:

key must not be NULL.

Pre:

key must point to data that is at least as large as the key size of m.

size_t y_imap_size(const y_IMap m)

Returns the number of elements in the provided map.

Parameters:

m – The map whose size will be returned.

Returns:

The number of elements in the map.

Pre:

m must not be NULL.

size_t y_imap_cap(const y_IMap m)

Returns the maximum number of elements the provided map can hold (the capacity).

If the load of the map is less than 1, the map will never reach this capacity before expanding.

Parameters:

m – The map whose capacity will be returned.

Returns:

m’s capacity.

Pre:

m must not be NULL.

size_t y_imap_ksize(const y_IMap m)

Returns the key size of m.

Parameters:

m – The map whose key size will be returned.

Returns:

m’s key size.

Pre:

m must not be NULL.

size_t y_imap_vsize(const y_IMap m)

Returns the element size of m.

Parameters:

m – The map whose element size will be returned.

Returns:

m’s element size.

Pre:

m must not be NULL.

size_t y_imap_max(const y_IMap m)

Returns the maximum number of element m can hold without allocating more memory.

Parameters:

m – The map whose max size will be returned.

Returns:

m’s max size without allocating more memory.

Pre:

m must not be NULL.

float y_imap_load(const y_IMap m)

Returns the load factor that was set for the map.

Parameters:

m – The map whose load factor will be returned.

Returns:

m’s load factor.

Pre:

m must not be NULL.

y_Status y_imap_insert(y_IMap m, const void *key, const void *val)

Inserts the data pointed to by val at the key in the provided map.

If the value already exists, it is overwritten. If the y_IMap was created with either y_imap_createStringKeyMap() or y_imap_createStringMap(), this will assert.

Parameters:
  • m – The map to insert into.

  • key – Pointer to the key to insert at.

  • val – Pointer to the value to insert.

Returns:

y_STATUS_SUCCESS if the value was successfully inserted, or a descriptive error code otherwise.

Pre:

m must not be NULL.

Pre:

m must not have been created with either y_imap_createStringKeyMap() or y_imap_createStringMap().

Pre:

key must not be NULL.

Pre:

key must point to data that is at least as large as the key size of m.

Pre:

val must not be NULL.

Pre:

val must point to data that is at least as large as the element size of m.

y_Status y_imap_insertStringKey(y_IMap m, const char *key, const void *val)

Inserts a value using the string as the key.

If the y_IMap was not created using y_imap_createStringKeyMap(), this will assert.

Parameters:
  • m – The map to insert into.

  • key – The string key.

  • val – Pointer to the value to insert.

Returns:

y_STATUS_SUCCESS if the value was successfully inserted, or a descriptive error code otherwise.

Pre:

m must not be NULL.

Pre:

m must have been created with y_imap_createStringKeyMap().

Pre:

key must not be NULL.

Pre:

val must not be NULL.

Pre:

val must point to data that is at least as large as the element size of m.

void y_imap_remove(y_IMap m, const void *key)

Removes the element at the specified key from the provided map.

Parameters:
  • m – The map whose element will be removed.

  • key – The key whose value will be removed.

Pre:

m must not be NULL.

Pre:

key must not be NULL.

Pre:

key must point to data that is at least as large as the key size of m.

void y_imap_removeAll(y_IMap m)

Removes all items from the map.

Parameters:

m – The map to remove all items from.

Pre:

m must not be NULL.

y_Iterator y_imap_begin(const y_IMap m)

Creates and returns an iterator for m.

The iterator can be used as though it is a pointer to the key of the current element (because it is); thus, it can just be dereferenced to get the key and passed to y_imap_at() to get the data. Also, it will be NULL when there are no more elements, so that can be used as a loop condition.

Note: The returned iterator is invalidated if m changes at all. After that, it cannot be used.

Parameters:

m – The map that will generate an iterator.

Returns:

An iterator for m.

Pre:

m must not be NULL.

y_Iterator y_imap_rbegin(const y_IMap m)

Creates and returns a reverse iterator for m.

The iterator can be used as though it is a pointer to the key of the current element (because it is); thus, it can just be dereferenced to get the key and passed to y_imap_at() to get the data. Also, it will be NULL when there are no more elements, so that can be used as a loop condition.

Note: The returned iterator is invalidated if m changes at all. After that, it cannot be used.

Parameters:

m – The map that will generate an iterator.

Returns:

An iterator for m.

Pre:

m must not be NULL.

y_Iterator y_imap_next(const y_IMap m, const y_Iterator it)

Returns the next iterator (or rather, the next position for the iterator) for m and it.

Parameters:
  • m – The map that will generate an iterator.

  • it – The current iterator.

Returns:

The next position of the iterator for m.

Pre:

m must not be NULL.

Pre:

it must not be NULL.

Pre:

it must be an iterator for m.

Pre:

it must be valid. This means that m has not been changed since it was initially created.

y_Iterator y_imap_rnext(const y_IMap m, const y_Iterator it)

Returns the next iterator (or rather, the next position for the iterator), going in reverse, for m and it.

Parameters:
  • m – The map that will generate an iterator.

  • it – The current iterator.

Returns:

The next position of the iterator for m.

Pre:

m must not be NULL.

Pre:

it must not be NULL.

Pre:

it must be an iterator for m.

Pre:

it must be valid. This means that m has not been changed since it was initially created.

void *y_imap_key(const y_IMap m, const y_Iterator it)

Returns the key for the given iterator it for map m.

Parameters:
  • m – The map to query for the key.

  • it – The iterator to get the key for.

Returns:

The key at the iterator.

Pre:

m must not be NULL.

Pre:

it must not be NULL.

Pre:

it must be an iterator for m.

Pre:

it must be valid. This means that m has not been changed since it was initially created.

void y_imap_free(void *map)

Frees all allocated data associated with the map.

This function always succeeds.

Parameters:

map – The map whose data will be freed.

Pre:

map must not be NULL.

group smap

Public function definitions and types for Yc’s segmented map.

Typedefs

typedef struct y_smap *y_SMap

Public-facing type of private map.

Functions

y_SMap y_smap_create(const float load, const size_t ksize, const size_t esize, const y_Hasher hash, const y_Equal eq, const y_Destructor kdtor, const y_Destructor vdtor)

Creates a new y_SMap and returns it.

If the hash function is NULL, keys are required to be the same size as sizeof(uint64_t), and they will be used as the hash instead. The same goes for the compare function: if NULL, keys must be uint64_t because they will just be compared instead.

Parameters:
  • load – The max load factor for the map.

  • ksize – The size of the key type (best passed in with sizeof).

  • esize – The size of the value type (best passed in with sizeof).

  • hash – The hash function that will be used for the map.

  • eq – The equality function that will be used to compare keys.

  • kdtor – The destructor function for the key type, if necessary.

  • vdtor – The destructor function for the value type, if necessary.

Returns:

NULL on malloc error, a valid y_SMap otherwise.

Pre:

ksize must be greater than 0.

Pre:

esize must be greater than 0.

Pre:

If cmp is NULL, ksize must be sizeof(uint64_t).

Pre:

If hash is NULL, ksize must be sizeof(uint64_t).

Pre:

load must be between (0, 1].

y_SMap y_smap_createStringKeyMap(const float load, const size_t esize, const y_Destructor vdtor)

Creates a y_SMap that uses y_strs as the keys.

Parameters:
  • load – The max load factor for the map.

  • esize – The size of the value type.

  • vdtor – The destructor function for the value type, if necessary.

Returns:

NULL on malloc error, a valid y_SMap otherwise.

Pre:

load must be between (0, 1].

Pre:

esize must be greater than 0.

bool y_smap_exists(const y_SMap m, const void *key)

Returns true if the map has the key, false otherwise.

Parameters:
  • m – The map to query.

  • key – The key to query for.

Returns:

true if the key exists in the map, false otherwise.

Pre:

m must not be NULL.

Pre:

key must not be NULL.

bool y_smap_exists_k(const y_SMap m, const void *key, void *key_ptr)

Returns true if the map has the key, false otherwise.

If the item exists, key_ptr is assumed to be a pointer to a pointer to the key type and will be initialized with the pointer to the key.

Parameters:
  • m – The map to query.

  • key – The key to query for.

  • key_ptr – The key pointer to a pointer to fill in if the item exists.

Returns:

true if the key exists in the map, false otherwise.

Pre:

m must not be NULL.

Pre:

key must not be NULL.

Pre:

key_ptr must not be NULL.

bool y_smap_exists_v(const y_SMap m, const void *key, void *val_ptr)

Returns true if the map has the key, false otherwise.

If the item exists, then val_ptr is assumed to be a pointer to a pointer to the value type and will be initialized with the pointer to the value.

Parameters:
  • m – The map to query.

  • key – The key to query for.

  • val_ptr – The value pointer to a pointer to fill in if the item exists.

Returns:

true if the key exists in the map, false otherwise.

Pre:

m must not be NULL.

Pre:

key must not be NULL.

Pre:

val_ptr must not be NULL.

bool y_smap_exists_kv(const y_SMap m, const void *key, void *key_ptr, void *val_ptr)

Returns true if the map has the key, false otherwise.

If the item exists, key_ptr is assumed to be a pointer to a pointer to the key type and will be initialized with the pointer to the key. If the item exists, then val_ptr is assumed to be a pointer to a pointer to the value type and will be initialized with the pointer to the value.

Parameters:
  • m – The map to query.

  • key – The key to query for.

  • key_ptr – The key pointer to a pointer to fill in if the item exists.

  • val_ptr – The value pointer to a pointer to fill in if the item exists.

Returns:

true if the key exists in the map, false otherwise.

Pre:

m must not be NULL.

Pre:

key must not be NULL.

Pre:

key_ptr must not be NULL.

Pre:

val_ptr must not be NULL.

void *y_smap_at(const y_SMap m, const void *key)

Returns a pointer to the value in the map that has the specified key.

If there is no value with key, this panics.

Parameters:
  • m – The map to search for the value.

  • key – The key for the value.

Returns:

A pointer to the value.

Pre:

m must not be NULL.

Pre:

key must not be NULL.

Pre:

key must point to data that is at least as large as the key size of m.

void *y_smap_atStringKey(const y_SMap m, const char *key)

Returns a pointer to the value in the map that has the specified key.

If there is no value with key, this panics.

Parameters:
  • m – The map to search for the value.

  • key – The key for the value.

Returns:

A pointer to the value.

Pre:

m must not be NULL.

Pre:

key must not be NULL.

Pre:

key must point to data that is at least as large as the key size of m.

void *y_smap_at_i(const y_SMap m, const void *key, size_t *idx)

Returns a pointer to the value in the map that has the specified key.

If there is no value with key, this panics. If idx is not NULL, the index of the item is stored there.

Parameters:
  • m – The map to search for the value.

  • key – The key for the value.

  • idx – A pointer to store the item’s index, if not NULL.

Returns:

A pointer to the value.

Pre:

m must not be NULL.

Pre:

key must not be NULL.

Pre:

key must point to data that is at least as large as the key size of m.

void *y_smap_atStringKey_i(const y_SMap m, const char *key, size_t *idx)

Returns a pointer to the value in the map that has the specified key.

If there is no value with key, this panics. If idx is not NULL, the index of the item is stored there.

Parameters:
  • m – The map to search for the value.

  • key – The key for the value.

  • idx – A pointer to store the item’s index, if not NULL.

Returns:

A pointer to the value.

Pre:

m must not be NULL.

Pre:

key must not be NULL.

Pre:

key must point to data that is at least as large as the key size of m.

void *y_smap_atIdx(const y_SMap m, size_t idx)

Gets the item at the index.

If there is no item at the index, this panics.

Parameters:
  • m – The map to search for the value.

  • idx – The index for the value.

Returns:

A pointer to the value.

Pre:

m must not be NULL.

size_t y_smap_idx(const y_SMap m, const void *key)

Gets the index of the item with the key.

If there is no item with the key, this panics.

Parameters:
  • m – The map to search for the value.

  • key – The key for the value.

Returns:

The index of the value, which can be used in y_smap_idx().

Pre:

m must not be NULL.

Pre:

key must not be NULL.

size_t y_smap_idxStringKey(const y_SMap m, const char *key)

Gets the index of the item with the key.

If there is no item with the key, this panics.

Parameters:
  • m – The map to search for the value.

  • key – The key for the value.

Returns:

The index of the value, which can be used in y_smap_idx().

Pre:

m must not be NULL.

Pre:

key must not be NULL.

size_t y_smap_size(const y_SMap m)

Returns the number of elements in the provided map.

Parameters:

m – The map whose size will be returned.

Returns:

The number of elements in the map.

Pre:

m must not be NULL.

size_t y_smap_cap(const y_SMap m)

Returns the maximum number of elements the provided map can hold (the capacity).

If the load of the map is less than 1, the map will never reach this capacity before expanding.

Parameters:

m – The map whose capacity will be returned.

Returns:

m’s capacity.

Pre:

m must not be NULL.

size_t y_smap_ksize(const y_SMap m)

Returns the key size of m.

Parameters:

m – The map whose key size will be returned.

Returns:

m’s key size.

Pre:

m must not be NULL.

size_t y_smap_vsize(const y_SMap m)

Returns the element size of m.

Parameters:

m – The map whose element size will be returned.

Returns:

m’s element size.

Pre:

m must not be NULL.

size_t y_smap_max(const y_SMap m)

Returns the maximum number of element m can hold without allocating more memory.

Parameters:

m – The map whose max size will be returned.

Returns:

m’s max size without allocating more memory.

Pre:

m must not be NULL.

float y_smap_load(const y_SMap m)

Returns the load factor that was set for the map.

Parameters:

m – The map whose load factor will be returned.

Returns:

m’s load factor.

Pre:

m must not be NULL.

y_Status y_smap_insert(y_SMap m, const void *key, const void *val, size_t *idx)

Inserts the data pointed to by val at the key in the provided map.

If the value already exists, it is overwritten. If the y_SMap was created with either y_smap_createStringKeyMap() or y_smap_createStringMap(), this will assert.

Parameters:
  • m – The map to insert into.

  • key – Pointer to the key to insert at.

  • val – Pointer to the value to insert.

  • idx – A pointer to fill with the resulting index. Can be NULL.

Returns:

y_STATUS_SUCCESS if the value was successfully inserted, or a descriptive error code otherwise.

Pre:

m must not be NULL.

Pre:

m must not have been created with either y_smap_createStringKeyMap() or y_smap_createStringMap().

Pre:

key must not be NULL.

Pre:

key must point to data that is at least as large as the key size of m.

Pre:

val must not be NULL.

Pre:

val must point to data that is at least as large as the element size of m.

y_Status y_smap_insertStringKey(y_SMap m, const char *key, const void *val, size_t *idx)

Inserts a value using the string as the key.

If the y_SMap was not created using y_smap_createStringKeyMap(), this will assert.

Parameters:
  • m – The map to insert into.

  • key – The string key.

  • val – Pointer to the value to insert.

  • idx – A pointer to fill with the resulting index. Can be NULL.

Returns:

y_STATUS_SUCCESS if the value was successfully inserted, or a descriptive error code otherwise.

Pre:

m must not be NULL.

Pre:

m must have been created with y_smap_createStringKeyMap().

Pre:

key must not be NULL.

Pre:

val must not be NULL.

Pre:

val must point to data that is at least as large as the element size of m.

void y_smap_removeAll(y_SMap m)

Removes all items from the map.

Parameters:

m – The map to remove all items from.

Pre:

m must not be NULL.

void y_smap_free(void *map)

Frees all allocated data associated with the map.

This function always succeeds.

Parameters:

map – The map whose data will be freed.

Pre:

map must not be NULL.