Vector

struct Vector

A type safe, generic vector.

Type definitions

VECTOR_DECL(T)

Declares a new vector type.

Parameters

VECTOR_DECL_SPEC(T, SPEC)

Declares a new vector type, prepending a specifier to the generated declarations.

Parameters

  • T: [symbol] Vector type.

  • SPEC: [specifier] Specifier.

VECTOR_DECL_EQUATABLE(T)

Declares a new equatable vector type.

Parameters

VECTOR_DECL_EQUATABLE_SPEC(T, SPEC)

Declares a new equatable vector type, prepending a specifier to the generated declarations.

Parameters

  • T: [symbol] Vector type.

  • SPEC: [specifier] Specifier.

VECTOR_DECL_COMPARABLE(T)

Declares a new comparable vector type.

Parameters

VECTOR_DECL_COMPARABLE_SPEC(T, SPEC)

Declares a new comparable vector type, prepending a specifier to the generated declarations.

Parameters

  • T: [symbol] Vector type.

  • SPEC: [specifier] Specifier.

VECTOR_IMPL(T)

Implements a previously declared vector type.

Parameters

VECTOR_IMPL_EQUATABLE(T, __equal_func)

Implements a previously declared equatable vector type.

Elements of an equatable vector can be checked for equality via __equal_func.

Parameters

  • T: [symbol] Vector type.

  • __equal_func: [(T, T) -> bool] Equality function.

VECTOR_IMPL_COMPARABLE(T, __equal_func, __compare_func)

Implements a previously declared comparable vector type.

Elements of a comparable vector can be checked for equality via __equal_func and ordered via __compare_func.

Parameters

  • T: [symbol] Vector type.

  • __equal_func: [(T, T) -> bool] Equality function.

  • __compare_func: [(T, T) -> bool] Comparison function (True if LHS is smaller than RHS).

VECTOR_IMPL_IDENTIFIABLE(T)

Implements a previously declared comparable vector type whose elements can be checked for equality via == and compared via <.

Parameters

VECTOR_INIT(T)

Defines a new static vector type.

Parameters

VECTOR_INIT_EQUATABLE(T, __equal_func)

Defines a new static equatable vector type.

Parameters

  • T: [symbol] Vector type.

  • __equal_func: [(T, T) -> bool] Equality function.

VECTOR_INIT_COMPARABLE(T, __equal_func, __compare_func)

Defines a new static comparable vector type.

Parameters

  • T: [symbol] Vector type.

  • __equal_func: [(T, T) -> bool] Equality function.

  • __compare_func: [(T, T) -> bool] Comparison function (True if LHS is smaller than RHS).

VECTOR_INIT_IDENTIFIABLE(T)

Defines a new static equatable vector type whose elements can be checked for equality via == and compared via <.

Parameters

Declaration

Vector(T)

Declares a new vector variable.

Parameters

vector_struct(T)

Expands to ‘struct Vector_T’, useful for forward-declarations.

Parameters

Memory management

vector_alloc(T)

Allocates a new vector.

Return

[Vector(T)*] Vector instance, or NULL on error.

Parameters

vector_free(T, vec)

Deallocates the specified vector.

Parameters

vector_copy(T, vec)

Copies the specified vector.

Return

[Vector(T)*] Copied vector instance, or NULL on error.

Parameters

vector_deep_copy(T, vec, __copy_func)

Performs a deep copy of the specified vector.

Return

[Vector(T)*] Copied vector instance, or NULL on error.

Parameters

  • T: [symbol] Vector type.

  • vec: [Vector(T)*] Vector to copy.

  • __copy_func: [(T) -> T] Copy function, invoked for each element.

vector_copy_to_array(T, vec, array)

Copies the elements of the specified vector into the given array.

Note

The array must be sufficiently large to hold all the elements.

Parameters

  • T: [symbol] Vector type.

  • vec: [Vector(T)*] Vector to copy.

  • array: [T*] Array to copy the elements into.

vector_init(T)

Initializes a new vector on the stack.

Return

[Vector(T)] Initialized vector instance.

Parameters

vector_deinit(vec)

De-initializes a vector previously initialized via VECTOR_INIT.

Parameters

vector_reserve_capacity(T, vec, size)

Ensures the specified vector can hold at least as many elements as ‘size’.

Return

[vector_ret_t] VECTOR_OK on success, otherwise VECTOR_ERR.

Parameters

  • T: [symbol] Vector type.

  • vec: [Vector(T)*] Vector instance.

  • size: [vector_uint_t] Number of elements the vector should be able to hold.

vector_expand(T, vec, size)

Expands the specified vector so that it can contain additional ‘size’ elements.

Return

[vector_ret_t] VECTOR_OK on success, otherwise VECTOR_ERR.

Parameters

  • T: [symbol] Vector type.

  • vec: [Vector(T)*] Vector to expand.

  • size: [vector_uint_t] Number of additional elements the vector should be able to hold.

vector_shrink(T, vec)

Shrinks the specified vector so that its allocated size exactly matches the number of elements it contains.

Return

[vector_ret_t] VECTOR_OK on success, otherwise VECTOR_ERR.

Parameters

Primitives

vector_get(vec, idx)

Retrieves the element at the specified index.

Return

[T] Element at the specified index.

Parameters

vector_set(vec, idx, item)

Replaces the element at the specified index.

Parameters

  • vec: [Vector(T)*] Vector instance.

  • idx: [vector_uint_t] Index.

  • item: [T] Replacement element.

vector_first(vec)

Returns the first element in the vector.

Return

[T] First element.

Parameters

vector_last(vec)

Returns the last element in the vector.

Return

[T] Last element.

Parameters

vector_is_empty(vec)

Checks whether the specified vector is empty.

Return

[bool] True if the vector is empty, false otherwise.

Note

For convenience, this macro returns ‘true’ for NULL vectors.

Parameters

vector_count(vec)

Returns the number of elements in the vector.

Return

[vector_uint_t] Number of elements.

Note

For convenience, this macro returns ‘0’ for NULL vectors.

Parameters

vector_push(T, vec, item)

Pushes the specified element to the top of the vector (last element).

Return

[vector_ret_t] VECTOR_OK on success, otherwise VECTOR_ERR.

Parameters

vector_pop(T, vec)

Removes and returns the element at the top of the vector (last element).

Return

[T] Last element.

Parameters

vector_remove_at(T, vec, idx)

Removes the element at the specified index.

Return

[T] Removed element.

Parameters

  • T: [symbol] Vector type.

  • vec: [Vector(T)*] Vector instance.

  • idx: [vector_uint_t] Index of the element to remove.

vector_insert_at(T, vec, idx, item)

Inserts an element at the specified index.

Return

[vector_ret_t] VECTOR_OK on success, otherwise VECTOR_ERR.

Parameters

  • T: [symbol] Vector type.

  • vec: [Vector(T)*] Vector instance.

  • idx: [vector_uint_t] Index at which the element should be inserted.

  • item: [T] Element to insert.

vector_remove_all(T, vec)

Removes all the elements in the vector.

Parameters

vector_append(T, vec, vec_to_append)

Appends a vector to another.

Return

[vector_ret_t] VECTOR_OK on success, otherwise VECTOR_ERR.

Parameters

vector_append_array(T, vec, array, n)

Appends an array to the specified vector.

Return

[vector_ret_t] VECTOR_OK on success, otherwise VECTOR_ERR.

Parameters

  • T: [symbol] Vector type.

  • vec: [Vector(T)*] Vector instance.

  • array: [T*] Array to append.

  • n: [vector_uint_t] Number of elements to append.

vector_append_items(T, vec, ...)

Appends multiple items to the specified vector.

Return

[vector_ret_t] VECTOR_OK on success, otherwise VECTOR_ERR.

Parameters

vector_reverse(T, vec)

Reverses the vector.

Parameters

Iteration

vector_iterate(T, vec, item_name, idx_name, code)

Iterates over the vector, executing the specified code block for each element.

Parameters

  • T: [symbol] Vector type.

  • vec: [Vector(T)*] Vector instance.

  • item_name: [symbol] Name of the element variable.

  • idx_name: [symbol] Name of the index variable.

  • code: [code] Code block to execute.

vector_iterate_reverse(T, vec, item_name, idx_name, code)

Iterates over the vector in reverse order, executing the specified code block for each element.

Parameters

  • T: [symbol] Vector type.

  • vec: [Vector(T)*] Vector instance.

  • item_name: [symbol] Name of the element variable.

  • idx_name: [symbol] Name of the index variable.

  • code: [code] Code block to execute.

vector_foreach(T, vec, item_name, code)

Iterates over the vector, executing the specified code block for each element.

Parameters

  • T: [symbol] Vector type.

  • vec: [Vector(T)*] Vector instance.

  • item_name: [symbol] Name of the element variable.

  • code: [code] Code block to execute.

vector_foreach_reverse(T, vec, item_name, code)

Iterates over the vector in reverse order, executing the specified code block for each element.

Parameters

  • T: [symbol] Vector type.

  • vec: [Vector(T)*] Vector instance.

  • item_name: [symbol] Name of the element variable.

  • code: [code] Code block to execute.

Equatable

vector_index_of(T, vec, item)

Returns the index of the first occurrence of the specified element.

Return

[vector_uint_t] Index of the found element, or VECTOR_INDEX_NOT_FOUND.

Parameters

vector_index_of_reverse(T, vec, item)

Returns the index of the last occurrence of the specified element.

Return

[vector_uint_t] Index of the found element, or VECTOR_INDEX_NOT_FOUND.

Parameters

vector_contains(T, vec, item)

Checks whether the vector contains the specified element.

Return

[bool] True if the vector contains the specified element, false otherwise.

Parameters

vector_contains_all(T, vec, other_vec)

Checks whether the vector contains all the elements present in another vector.

Return

[bool] True if the vector contains all the specified elements, false otherwise.

Parameters

vector_contains_any(T, vec, other_vec)

Checks whether the vector contains any of the elements contained in another vector.

Return

[bool] True if the vector contains any of the specified elements, false otherwise.

Parameters

vector_remove(T, vec, item)

Removes the specified element.

Return

[bool] True if the element was found and removed, false otherwise.

Parameters

vector_equals(T, vec_a, vec_b)

Checks whether the two vectors are equal.

Two vectors are considered equal if they contain the same elements in the same order.

Return

[bool] True if the vectors are equal, false otherwise.

Parameters

vector_remove_all_from(T, vec, vec_to_remove)

Removes all the elements present in ‘vec_to_remove’ from ‘vec’.

Parameters

Comparable

vector_index_of_min(T, vec)

Returns the index of the minimum element in the vector.

Return

[vector_uint_t] Index of the minimum element.

Parameters

vector_index_of_max(T, vec)

Returns the index of the maximum element in the vector.

Return

[vector_uint_t] Index of the maximum element.

Parameters

vector_sort(T, vec)

Sorts the vector.

Average performance: O(n log n)

Parameters

vector_sort_range(T, vec, start, len)

Sorts the elements in the specified range.

Average performance: O(n log n)

Parameters

  • T: [symbol] Vector type.

  • vec: [Vector(T)*] Vector instance.

  • start: [vector_uint_t] Range start index.

  • len: [vector_uint_t] Range length.

vector_insertion_index_sorted(T, vec, item)

Finds the insertion index for the specified item in a sorted vector.

Average performance: O(log n)

Return

[vector_uint_t] Insertion index.

Parameters

  • T: [symbol] Vector type.

  • vec: [Vector(T)*] Vector instance.

  • item: [T] Element whose insertion index should be found.

vector_index_of_sorted(T, vec, item)

Returns the index of the specified element in a sorted vector.

Average performance: O(log n)

Return

[vector_uint_t] Index of the found element, or VECTOR_INDEX_NOT_FOUND.

Note

The returned index is not necessarily the first occurrence of the item.

Parameters

vector_contains_sorted(T, vec, item)

Checks whether a sorted vector contains the specified element.

Average performance: O(log n)

Return

[bool] True if the vector contains the specified element, false otherwise.

Parameters

Higher order

vector_first_index_where(T, vec, idx_var, bool_exp)

Returns the index of the first element that matches the specified boolean expression.

Parameters

  • T: [symbol] Vector type.

  • vec: [Vector(T)*] Vector instance.

  • [out] idx_var: [vector_uint_t] Out variable (must be declared in outer scope).

  • bool_exp: [expression] Boolean expression.

vector_qsort(T, vec, __comp_func)

Sorts the vector via qsort.

See

qsort

Parameters

  • T: [symbol] Vector type.

  • vec: [Vector(T)*] Vector instance.

  • __comp_func: [(const void *, const void *) -> int] qsort-compatible sorting function.

vector_qsort_range(T, vec, start, len, __comp_func)

Sorts the elements in the specified range via qsort.

See

qsort

Parameters

  • T: [symbol] Vector type.

  • vec: [Vector(T)*] Vector instance.

  • start: [vector_uint_t] Range start index.

  • len: [vector_uint_t] Range length.

  • __comp_func: [(const void *, const void *) -> int] qsort-compatible sorting function.

Public Types

enum vector_ret_t

Return codes.

Values:

typedef uint32_t vector_uint_t

Unsigned integer type.