Collections

Vector

struct UVec

A type safe, generic vector.

Subclassed by UStrBuf

Type definitions

UVEC_DECL(T)

Declares a new vector type.

Parameters

• T – [symbol] Vector type.

UVEC_DECL_SPEC(T, SPEC)

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

Parameters

• T – [symbol] Vector type.

• SPEC – [specifier] Specifier.

UVEC_DECL_EQUATABLE(T)

Declares a new equatable vector type.

Parameters

• T – [symbol] Vector type.

UVEC_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.

UVEC_DECL_COMPARABLE(T)

Declares a new comparable vector type.

Parameters

• T – [symbol] Vector type.

UVEC_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.

UVEC_IMPL(T)

Implements a previously declared vector type.

Parameters

• T – [symbol] Vector type.

UVEC_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.

UVEC_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).

UVEC_IMPL_IDENTIFIABLE(T)

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

Parameters

• T – [symbol] Vector type.

UVEC_INIT(T)

Defines a new static vector type.

Parameters

• T – [symbol] Vector type.

UVEC_INIT_EQUATABLE(T, equal_func)

Defines a new static equatable vector type.

Parameters

• T – [symbol] Vector type.

• equal_func – [(T, T) -> bool] Equality function.

UVEC_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).

UVEC_INIT_IDENTIFIABLE(T)

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

Parameters

• T – [symbol] Vector type.

Declaration

UVec(T)

Declares a new vector variable.

Parameters

• T – [symbol] Vector type.

uvec_decl(T)

Vector type forward declaration.

Parameters

• T – [symbol] Vector type.

Memory management

uvec(T)

Initializes a new vector.

Parameters

• T – [symbol] Vector type.

Returns

[UVec(T)] Initialized vector instance.

uvec_deinit(T, vec)

De-initializes a vector previously initialized via uvec(T).

Parameters

• T – [symbol] Vector type.

• vec – [UVec(T)*] Vector to de-initialize.

uvec_move(T, vec)

Invalidates the vector and returns its storage.

Parameters

• T – [symbol] Vector type.

• vec – [UVec(T)*] Vector whose storage should be returned.

Returns

[UVec(T)] Vector storage.

uvec_copy(T, src, dest)

Copies the specified vector.

Parameters

• T – [symbol] Vector type.

• src – [UVec(T)*] Vector to copy.

• dest – [UVec(T)*] Vector to copy into.

Returns

[uvec_ret] UVEC_OK on success, otherwise UVEC_ERR.

uvec_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 – [UVec(T)*] Vector to copy.

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

uvec_reserve(T, vec, size)

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

Parameters

• T – [symbol] Vector type.

• vec – [UVec(T)*] Vector instance.

• size – [ulib_uint] Number of elements the vector should be able to hold.

Returns

[uvec_ret] UVEC_OK on success, otherwise UVEC_ERR.

uvec_expand(T, vec, size)

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

Parameters

• T – [symbol] Vector type.

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

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

Returns

[uvec_ret] UVEC_OK on success, otherwise UVEC_ERR.

uvec_shrink(T, vec)

Shrinks the specified vector so that its allocated size is just large enough to hold the elements it currently contains.

Parameters

• T – [symbol] Vector type.

• vec – [UVec(T)*] Vector to shrink.

Returns

[uvec_ret] UVEC_OK on success, otherwise UVEC_ERR.

Primitives

uvec_data(T, vec)

Returns the raw array backing the vector.

Parameters

• T – [symbol] Vector type.

• vec – [UVec(T)*] Vector instance.

Returns

[T*] Pointer to the first element of the raw array.

uvec_get(T, vec, idx)

Retrieves the element at the specified index.

Parameters

• T – [symbol] Vector type.

• vec – [UVec(T)*] Vector instance.

• idx – [ulib_uint] Index.

Returns

[T] Element at the specified index.

uvec_set(T, vec, idx, item)

Replaces the element at the specified index.

Parameters

• T – [symbol] Vector type.

• vec – [UVec(T)*] Vector instance.

• idx – [ulib_uint] Index.

• item – [T] Replacement element.

uvec_first(T, vec)

Returns the first element in the vector.

Parameters

• T – [symbol] Vector type.

• vec – [UVec(T)*] Vector instance.

Returns

[T] First element.

uvec_last(T, vec)

Returns the last element in the vector.

Parameters

• T – [symbol] Vector type.

• vec – [UVec(T)*] Vector instance.

Returns

[T] Last element.

uvec_count(T, vec)

Returns the number of elements in the vector.

Parameters

• T – [symbol] Vector type.

• vec – [UVec(T)*] Vector instance.

Returns

[ulib_uint] Number of elements.

uvec_size(T, vec)

Returns the maximum number of elements that can be held by the raw array backing the vector, i.e.

the vector’s capacity.

Parameters

• T – [symbol] Vector type.

• vec – [UVec(T)*] Vector instance.

Returns

[ulib_uint] Capacity.

uvec_index_is_valid(T, vec, idx)

Checks if the specified index is valid.

Parameters

• T – [symbol] Vector type.

• vec – [UVec(T)*] Vector instance.

• idx – [ulib_uint] Index.

Returns

True if the index is valid, false otherwise.

uvec_push(T, vec, item)

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

Parameters

• T – [symbol] Vector type.

• vec – [UVec(T)*] Vector instance.

• item – [T] Element to push.

Returns

[uvec_ret] UVEC_OK on success, otherwise UVEC_ERR.

uvec_pop(T, vec)

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

Parameters

• T – [symbol] Vector type.

• vec – [UVec(T)*] Vector instance.

Returns

[T] Last element.

uvec_remove_at(T, vec, idx)

Removes the element at the specified index.

Parameters

• T – [symbol] Vector type.

• vec – [UVec(T)*] Vector instance.

• idx – [ulib_uint] Index of the element to remove.

Returns

[T] Removed element.

uvec_insert_at(T, vec, idx, item)

Inserts an element at the specified index.

Parameters

• T – [symbol] Vector type.

• vec – [UVec(T)*] Vector instance.

• idx – [ulib_uint] Index at which the element should be inserted.

• item – [T] Element to insert.

Returns

[uvec_ret] UVEC_OK on success, otherwise UVEC_ERR.

uvec_remove_all(T, vec)

Removes all the elements in the vector.

Parameters

• T – [symbol] Vector type.

• vec – [UVec(T)*] Vector instance.

uvec_append(T, vec, src)

Appends a vector to another.

Parameters

• T – [symbol] Vector type.

• vec – [UVec(T)*] Vector instance.

• src – [UVec(T)*] Vector to append.

Returns

[uvec_ret] UVEC_OK on success, otherwise UVEC_ERR.

uvec_append_array(T, vec, array, n)

Appends an array to the specified vector.

Parameters

• T – [symbol] Vector type.

• vec – [UVec(T)*] Vector instance.

• array – [T*] Array to append.

• n – [ulib_uint] Number of elements to append.

Returns

[uvec_ret] UVEC_OK on success, otherwise UVEC_ERR.

uvec_get_range(T, vec, start, len)

Returns a read-only range over the specified vector.

Warning

Mutating the range object is undefined behavior.

Parameters

• T – [symbol] Vector type.

• vec – [UVec(T)*] Vector instance.

• start – [ulib_uint] Start index of the range.

• len – [ulib_uint] Length of the range.

Returns

[UVec(T)] Range.

uvec_get_range_from(T, vec, start)

Returns a read-only range over the specified vector.

Warning

Mutating the range object is undefined behavior.

Parameters

• T – [symbol] Vector type.

• vec – [UVec(T)*] Vector instance.

• start – [ulib_uint] Start index of the range.

Returns

[UVec(T)] Range.

uvec_get_range_to(T, vec, len)

Returns a read-only range over the specified vector.

Warning

Mutating the range object is undefined behavior.

Parameters

• T – [symbol] Vector type.

• vec – [UVec(T)*] Vector instance.

• len – [ulib_uint] Length of the range.

Returns

[UVec(T)] Range.

uvec_set_range(T, vec, array, start, n)

Sets items in the specified range to those contained in an array.

Parameters

• T – [symbol] Vector type.

• vec – [UVec(T)*] Vector instance.

• array – [T*] Array containing the items.

• start – [ulib_uint] Range start index.

• n – [ulib_uint] Number of elements in the array.

Returns

[uvec_ret] UVEC_OK on success, UVEC_ERR on memory error, UVEC_NO if start is greater than the vector’s capacity.

uvec_reverse(T, vec)

Reverses the vector.

Parameters

• T – [symbol] Vector type.

• vec – [UVec(T)*] Vector instance.

Iteration

uvec_foreach(T, vec, enum_name)

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

Parameters

• T – [symbol] Vector type.

• vec – [UVec(T)*] Vector instance.

• enum_name – [symbol] Name of the variable holding the current item and its index.

uvec_foreach_reverse(T, vec, enum_name)

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

Parameters

• T – [symbol] Vector type.

• vec – [UVec(T)*] Vector instance.

• enum_name – [symbol] Name of the variable holding the current item and its index.

Equatable

uvec_index_of(T, vec, item)

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

Parameters

• T – [symbol] Vector type.

• vec – [UVec(T)*] Vector instance.

• item – [T] Element to search.

Returns

[ulib_uint] Index of the found element, or an invalid index if the element cannot be found.

uvec_index_of_reverse(T, vec, item)

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

Parameters

• T – [symbol] Vector type.

• vec – [UVec(T)*] Vector instance.

• item – [T] Element to search.

Returns

[ulib_uint] Index of the found element, or an invalid index if the element cannot be found.

uvec_contains(T, vec, item)

Checks whether the vector contains the specified element.

Parameters

• T – [symbol] Vector type.

• vec – [UVec(T)*] Vector instance.

• item – [T] Element to search.

Returns

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

uvec_remove(T, vec, item)

Removes the specified element.

Parameters

• T – [symbol] Vector type.

• vec – [UVec(T)*] Vector instance.

• item – [T] Element to remove.

Returns

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

uvec_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.

Parameters

• T – [symbol] Vector type.

• vec_a – [UVec(T)*] First vector.

• vec_b – [UVec(T)*] Second vector.

Returns

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

uvec_push_unique(T, vec, item)

Pushes the specified element to the top of the vector if it does not already contain it.

Parameters

• T – [symbol] Vector type.

• vec – [UVec(T)*] Vector instance.

• item – [T] Element to push.

Returns

[uvec_ret] UVEC_OK if the element was pushed, UVEC_NO if the element was already present, otherwise UVEC_ERR.

Comparable

uvec_index_of_min(T, vec)

Returns the index of the minimum element in the vector.

Parameters

• T – [symbol] Vector type.

• vec – [UVec(T)*] Vector instance.

Returns

[ulib_uint] Index of the minimum element.

uvec_index_of_max(T, vec)

Returns the index of the maximum element in the vector.

Parameters

• T – [symbol] Vector type.

• vec – [UVec(T)*] Vector instance.

Returns

[ulib_uint] Index of the maximum element.

uvec_sort(T, vec)

Sorts the vector.

Average performance: O(n log n)

Parameters

• T – [symbol] Vector type.

• vec – [UVec(T)*] Vector instance.

uvec_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 – [UVec(T)*] Vector instance.

• start – [ulib_uint] Range start index.

• len – [ulib_uint] Range length.

uvec_insertion_index_sorted(T, vec, item)

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

Average performance: O(log n)

Parameters

• T – [symbol] Vector type.

• vec – [UVec(T)*] Vector instance.

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

Returns

[ulib_uint] Insertion index.

uvec_index_of_sorted(T, vec, item)

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

Average performance: O(log n)

Note

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

Parameters

• T – [symbol] Vector type.

• vec – [UVec(T)*] Vector instance.

• item – [T] Element to search.

Returns

[ulib_uint] Index of the found element, or an invalid index.

uvec_contains_sorted(T, vec, item)

Checks whether a sorted vector contains the specified element.

Average performance: O(log n)

Parameters

• T – [symbol] Vector type.

• vec – [UVec(T)*] Vector instance.

• item – [T] Element to search.

Returns

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

uvec_insert_sorted(T, vec, item, idx)

Inserts the specified element in a sorted vector.

Parameters

• T – [symbol] Vector type.

• vec – [UVec(T)*] Vector instance.

• item – [T] Element to insert.

• idx – [out] [ulib_uint] Index of the inserted element.

Returns

[uvec_ret] UVEC_OK on success, otherwise UVEC_ERR.

uvec_insert_sorted_unique(T, vec, item, idx)

Inserts the specified element in a sorted vector only if it does not already contain it.

Parameters

• T – [symbol] Vector type.

• vec – [UVec(T)*] Vector instance.

• item – [T] Element to insert.

• idx – [out] [ulib_uint] Index of the inserted (or that of the already present) element.

Returns

[uvec_ret] UVEC_OK if the element was inserted, UVEC_NO if the element was already present, otherwise UVEC_ERR.

uvec_remove_sorted(T, vec, item)

Removes the specified element from a sorted vector.

Parameters

• T – [symbol] Vector type.

• vec – [UVec(T)*] Vector instance.

• item – [T] Element to remove.

Returns

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

enum uvec_ret

Return codes.

Values:

enumerator UVEC_ERR

The operation failed due to an error.

As of right now, it can only happen if memory cannot be allocated.

enumerator UVEC_OK

The operation succeeded.

enumerator UVEC_NO

The operation could not be completed.

Hash table

struct UHash

A type safe, generic hash table.

Type definitions

UHASH_DECL(T, uh_key, uh_val)

Declares a new hash table type.

Parameters

• T – [symbol] Hash table name.

• uh_key – [symbol] Type of the keys.

• uh_val – [symbol] Type of the values.

UHASH_DECL_SPEC(T, uh_key, uh_val, SPEC)

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

Parameters

• T – [symbol] Hash table name.

• uh_key – [symbol] Type of the keys.

• uh_val – [symbol] Type of the values.

• SPEC – [specifier] Specifier.

UHASH_DECL_PI(T, uh_key, uh_val)

Declares a new hash table type with per-instance hash and equality functions.

Parameters

• T – [symbol] Hash table name.

• uh_key – [symbol] Type of the keys.

• uh_val – [symbol] Type of the values.

UHASH_DECL_PI_SPEC(T, uh_key, uh_val, SPEC)

Declares a new hash table type with per-instance hash and equality functions, prepending a specifier to the generated declarations.

Parameters

• T – [symbol] Hash table name.

• uh_key – [symbol] Type of the keys.

• uh_val – [symbol] Type of the values.

• SPEC – [specifier] Specifier.

UHASH_IMPL(T, hash_func, equal_func)

Implements a previously declared hash table type.

Parameters

• T – [symbol] Hash table name.

• hash_func – [(uh_key) -> ulib_uint] Hash function or expression.

• equal_func – [(uh_key, uh_key) -> bool] Equality function or expression.

UHASH_IMPL_PI(T, default_hfunc, default_efunc)

Implements a previously declared hash table type with per-instance hash and equality functions.

Parameters

• T – [symbol] Hash table name.

• default_hfunc – [(uh_key) -> ulib_uint] Default hash function (can be NULL).

• default_efunc – [(uh_key, uh_key) -> bool] Default equality function (can be NULL).

UHASH_INIT(T, uh_key, uh_val, hash_func, equal_func)

Defines a new static hash table type.

Parameters

• T – [symbol] Hash table name.

• uh_key – [symbol] Type of the keys.

• uh_val – [symbol] Type of the values.

• hash_func – [(uh_key) -> ulib_uint] Hash function or expression.

• equal_func – [(uh_key, uh_key) -> bool] Equality function or expression.

UHASH_INIT_PI(T, uh_key, uh_val, default_hfunc, default_efunc)

Defines a new static hash table type with per-instance hash and equality functions.

Parameters

• T – [symbol] Hash table name.

• uh_key – [symbol] Type of the keys.

• uh_val – [symbol] Type of the values.

• default_hfunc – [(uh_key) -> ulib_uint] Default hash function (can be NULL).

• default_efunc – [(uh_key, uh_key) -> bool] Default equality function (can be NULL).

Hash and equality functions

uhash_identical(a, b)

Identity macro.

Parameters

• a – LHS of the identity.

• b – RHS of the identity.

Returns

a == b

uhash_str_equals(a, b)

Equality function for strings.

Parameters

• a – [char const *] LHS of the equality relation (NULL terminated string).

• b – [char const *] RHS of the equality relation (NULL terminated string).

Returns

[bool] True if a is equal to b, false otherwise.

uhash_int8_hash(key)

Hash function for 8 bit integers.

Parameters

• key – [int8_t/uint8_t] The integer.

Returns

[ulib_uint] The hash value.

uhash_int16_hash(key)

Hash function for 16 bit integers.

Parameters

• key – [int16_t/uint16_t] The integer.

Returns

[ulib_uint] The hash value.

uhash_int32_hash(key)

Hash function for 32 bit integers.

Parameters

• key – [int32_t/uint32_t] The integer.

Returns

[ulib_uint] The hash value.

uhash_int64_hash(key)

Hash function for 64 bit integers.

Parameters

• key – [int64_t/uint64_t] The integer.

Returns

[ulib_uint] The hash value.

uhash_str_hash(key)

Hash function for strings.

Parameters

• key – [char const *] Pointer to a NULL-terminated string.

Returns

[ulib_uint] The hash value.

uhash_ptr_hash(key)

Hash function for pointers.

Parameters

• key – [pointer] The pointer.

Returns

[ulib_uint] The hash value.

uhash_combine_hash(hash_1, hash_2)

Combines two hashes.

Parameters

• hash_1 – [ulib_uint] First hash.

• hash_2 – [ulib_uint] Second hash.

Returns

[ulib_uint] The hash value.

Declaration

UHash(T)

Declares a new hash table variable.

Parameters

• T – [symbol] Hash table name.

uhash_decl(T)

Hash table type forward declaration.

Parameters

• T – [symbol] Hash table name.

Memory management

uhash_deinit(T, h)

Deinitializes the specified hash table.

Parameters

• T – [symbol] Hash table name.

• h – [UHash(T)*] Hash table to deinitialize.

uhash_move(T, h)

Invalidates the hash table and returns its storage.

Parameters

• T – [symbol] Hash table name.

• h – [UHash(T)*] Hash table whose storage should be returned.

Returns

[UHash(T)] Hash table storage.

uhash_copy(T, src, dest)

Copies the specified hash table.

Parameters

• T – [symbol] Hash table name.

• src – [UHash(T)*] Hash table to copy.

• dest – [UHash(T)*] Hash table to copy into.

Returns

[uhash_ret] UHASH_OK if the operation succeeded, UHASH_ERR on error.

uhash_copy_as_set(T, src, dest)

Returns a new hash set obtained by copying the keys of another hash table.

Parameters

• T – [symbol] Hash table name.

• src – [UHash(T)*] Hash table to copy.

• dest – [UHash(T)*] Hash table to copy into.

Returns

[uhash_ret] UHASH_OK if the operation succeeded, UHASH_ERR on error.

uhash_resize(T, h, s)

Resizes the specified hash table.

Parameters

• T – [symbol] Hash table name.

• h – [UHash(T)*] Hash table to resize.

• s – [ulib_uint] Hash table size.

Returns

[uhash_ret] UHASH_OK if the operation succeeded, UHASH_ERR on error.

Primitives

uhash_is_map(T, h)

Checks whether the hash table is a map.

Parameters

• T – [symbol] Hash table name.

• h – [UHash(T)*] Hash table instance.

Returns

True if the hash table is a map, false otherwise.

uhash_put(T, h, k, i)

Inserts a key into the specified hash table.

Parameters

• T – [symbol] Hash table name.

• h – [UHash(T)*] Hash table instance.

• k – [uhash_T_key] Key to insert.

• i – [out] [ulib_uint*] Index of the inserted element.

Returns

[uhash_ret] Return code (see uhash_ret).

uhash_get(T, h, k)

Retrieves the index of the bucket associated with the specified key.

Parameters

• T – [symbol] Hash table name.

• h – [UHash(T)*] Hash table instance.

• k – [uhash_T_key] Key whose index should be retrieved.

Returns

[ulib_uint] Index of the key, or UHASH_INDEX_MISSING if it is absent.

uhash_delete(T, h, k)

Deletes the bucket at the specified index.

Parameters

• T – [symbol] Hash table name.

• h – [UHash(T)*] Hash table instance.

• k – [ulib_uint] Index of the bucket to delete.

uhash_contains(T, h, k)

Checks whether the hash table contains the specified key.

Parameters

• T – [symbol] Hash table name.

• h – [UHash(T)*] Hash table instance.

• k – [uhash_T_key] Key to test.

Returns

[bool] True if the hash table contains the specified key, false otherwise.

uhash_exists(T, h, x)

Tests whether a bucket contains data.

Parameters

• T – [symbol] Hash table name.

• h – [UHash(T)*] Hash table instance.

• x – [ulib_uint] Index of the bucket to test.

Returns

[bool] True if the bucket contains data, false otherwise.

uhash_key(T, h, x)

Retrieves the key at the specified index.

Parameters

• T – [symbol] Hash table name.

• h – [UHash(T)*] Hash table instance.

• x – [ulib_uint] Index of the bucket whose key should be retrieved.

Returns

[uhash_T_key] Key.

uhash_value(T, h, x)

Retrieves the value at the specified index.

Note

Undefined behavior if used on hash sets.

Parameters

• T – [symbol] Hash table name.

• h – [UHash(T)*] Hash table instance.

• x – [ulib_uint] Index of the bucket whose value should be retrieved.

Returns

[T value type] Value.

uhash_size(T, h)

Returns the maximum number of elements that can be held by the hash table.

Parameters

• T – [symbol] Hash table name.

• h – [UHash(T)*] Hash table instance.

Returns

[ulib_uint] Maximum number of elements.

uhash_count(T, h)

Returns the number of elements in the hash table.

Parameters

• T – [symbol] Hash table name.

• h – [UHash(T)*] Hash table instance.

Returns

[ulib_uint] Number of elements.

uhash_clear(T, h)

Resets the specified hash table without deallocating it.

Parameters

• T – [symbol] Hash table name.

• h – [UHash(T)*] Hash table instance.

Map-specific API

uhmap(T)

Initializes a new hash map.

Parameters

• T – [symbol] Hash table name.

Returns

[UHash(T)] Hash table instance.

uhmap_pi(T, hash_func, equal_func)

Initializes a new hash map with per-instance hash and equality functions.

Parameters

• T – [symbol] Hash table name.

• hash_func – [(uh_key) -> ulib_uint] Hash function pointer.

• equal_func – [(uh_key, uh_key) -> bool] Equality function pointer.

Returns

[UHash(T)] Hash table instance.

uhmap_get(T, h, k, m)

Returns the value associated with the specified key.

Parameters

• T – [symbol] Hash table name.

• h – [UHash(T)*] Hash table instance.

• k – [uhash_T_key] The key.

• m – [uhash_T_val] Value to return if the key is missing.

Returns

[uhash_T_val] Value associated with the specified key.

uhmap_set(T, h, k, v, e)

Adds a key:value pair to the map, returning the replaced value (if any).

Parameters

• T – [symbol] Hash table name.

• h – [UHash(T)*] Hash table instance.

• k – [uhash_T_key] The key.

• v – [uhash_T_val] The value.

• e – [out] [uhash_T_val*] Existing value, only set if key was already in the map.

Returns

[uhash_ret] Return code (see uhash_ret).

uhmap_add(T, h, k, v, e)

Adds a key:value pair to the map, only if the key is missing.

Parameters

• T – [symbol] Hash table name.

• h – [UHash(T)*] Hash table instance.

• k – [uhash_T_key] The key.

• v – [uhash_T_val] The value.

• e – [out] [uhash_T_val*] Existing value, only set if key was already in the map.

Returns

[uhash_ret] Return code (see uhash_ret).

uhmap_replace(T, h, k, v, r)

Replaces a value in the map, only if its associated key exists.

Parameters

• T – [symbol] Hash table name.

• h – [UHash(T)*] Hash table instance.

• k – [uhash_T_key] The key.

• v – [uhash_T_val] The value.

• r – [out] [uhash_T_val*] Replaced value, only set if the return value is true.

Returns

[bool] True if the value was replaced (its key was present), false otherwise.

uhmap_remove(T, h, k)

Removes a key:value pair from the map.

Parameters

• T – [symbol] Hash table name.

• h – [UHash(T)*] Hash table instance.

• k – [uhash_T_key] The key.

Returns

[bool] True if the key was present (it was deleted), false otherwise.

uhmap_pop(T, h, k, dk, dv)

Removes a key:value pair from the map, returning the deleted key and value.

Parameters

• T – [symbol] Hash table name.

• h – [UHash(T)*] Hash table instance.

• k – [uhash_T_key] The key.

• dk – [out] [uhash_T_key*] Deleted key, only set if key was present in the map.

• dv – [out] [uhash_T_val*] Deleted value, only set if key was present in the map.

Returns

[bool] True if the key was present (it was deleted), false otherwise.

Set-specific API

uhset(T)

Initializes a new hash set.

Parameters

• T – [symbol] Hash table name.

Returns

[UHash(T)] Hash table instance.

uhset_pi(T, hash_func, equal_func)

Initializes a new hash set with per-instance hash and equality functions.

Parameters

• T – [symbol] Hash table name.

• hash_func – [(uh_key) -> ulib_uint] Hash function pointer.

• equal_func – [(uh_key, uh_key) -> bool] Equality function pointer.

Returns

[UHash(T)] Hash table instance.

uhset_insert(T, h, k)

Inserts an element in the set.

Parameters

• T – [symbol] Hash table name.

• h – [UHash(T)*] Hash table instance.

• k – [uhash_T_key] Element to insert.

Returns

[uhash_ret] Return code (see uhash_ret).

uhset_insert_get_existing(T, h, k, e)

Inserts an element in the set, returning the existing element if it was already present.

Parameters

• T – [symbol] Hash table name.

• h – [UHash(T)*] Hash table instance.

• k – [uhash_T_key] Element to insert.

• e – [out] [uhash_T_key*] Existing element, only set if it was already in the set.

Returns

[uhash_ret] Return code (see uhash_ret).

uhset_insert_all(T, h, a, n)

Populates the set with elements from an array.

Note

This function returns UHASH_INSERTED if at least one element in the array was missing from the set.

Parameters

• T – [symbol] Hash table name.

• h – [UHash(T)*] Hash table instance.

• a – [uhash_T_key*] Array of elements.

• n – [ulib_uint] Size of the array.

Returns

[uhash_ret] Return code (see uhash_ret).

uhset_replace(T, h, k, r)

Replaces an element in the set, only if it exists.

Parameters

• T – [symbol] Hash table name.

• h – [UHash(T)*] Hash table instance.

• k – [uhash_T_key] Element to replace.

• r – [out] [uhash_T_key*] Replaced element, only set if the return value is true.

Returns

[bool] True if the element was replaced (it was present), false otherwise.

uhset_remove(T, h, k)

Removes an element from the set.

Parameters

• T – [symbol] Hash table name.

• h – [UHash(T)*] Hash table instance.

• k – [uhash_T_key] Element to remove.

Returns

[bool] True if the element was removed (it was present), false otherwise.

uhset_pop(T, h, k, d)

Removes an element from the set, returning the deleted element.

Parameters

• T – [symbol] Hash table name.

• h – [UHash(T)*] Hash table instance.

• k – [uhash_T_key] Element to remove.

• d – [out] [uhash_T_key*] Deleted element, only set if element was present in the set.

Returns

[bool] True if the element was removed (it was present), false otherwise.

uhset_is_superset(T, h1, h2)

Checks whether the set is a superset of another set.

Parameters

• T – [symbol] Hash table name.

• h1 – [UHash(T)*] Superset.

• h2 – [UHash(T)*] Subset.

Returns

[bool] True if the superset relation holds, false otherwise.

uhset_union(T, h1, h2)

Performs the union between two sets, mutating the first.

Parameters

• T – [symbol] Hash table name.

• h1 – [UHash(T)*] Set to mutate.

• h2 – [UHash(T)*] Other set.

Returns

[uhash_ret] UHASH_OK if the operation succeeded, UHASH_ERR on error.

uhset_intersect(T, h1, h2)

Performs the intersection between two sets, mutating the first.

Parameters

• T – [symbol] Hash table name.

• h1 – [UHash(T)*] Set to mutate.

• h2 – [UHash(T)*] Other set.

uhset_equals(T, h1, h2)

Checks whether the set is equal to another set.

Parameters

• T – [symbol] Hash table name.

• h1 – [UHash(T)*] LHS of the equality relation.

• h2 – [UHash(T)*] RHS of the equality relation.

Returns

[bool] True if the equality relation holds, false otherwise.

uhset_hash(T, h)

Computes the hash of the set.

The computed hash does not depend on the order of the elements.

Parameters

• T – [symbol] Hash table name.

• h – [UHash(T)*] Hash table instance.

Returns

[ulib_uint] Hash of the set.

uhset_get_any(T, h, m)

Returns one of the elements in the set.

Parameters

• T – [symbol] Hash table name.

• h – [UHash(T)*] Hash table instance.

• m – [uhash_T_key] Value returned if the set is empty.

Returns

[uhash_T_key] One of the elements in the set.

Iteration

uhash_next(T, h, i)

Returns the index of the first bucket starting from (and including) i which contains data.

Parameters

• T – [symbol] Hash table name.

• h – [UHash(T)*] Hash table instance.

• i – [ulib_uint] Index of the bucket to start searching from.

Returns

Index of the first bucket containing data.

uhash_foreach(T, ht, enum_name)

Iterates over the entries in the hash table.

Parameters

• T – [symbol] Hash table name.

• ht – [UHash(T)*] Hash table instance.

• enum_name – [symbol] Name of the variable holding the current index, key and value.

enum uhash_ret

Return codes.

Values:

enumerator UHASH_ERR

The operation failed.

As of right now, it can only happen if memory cannot be allocated.

enumerator UHASH_OK

The operation succeeded.

enumerator UHASH_PRESENT

The key is already present.

enumerator UHASH_INSERTED

The key has been inserted (it was absent).