API Conventions

This page covers the contract rules that repeat across modules. Read it once before you start mixing modules in one program.

Naming and Construction

Public functions use snake_case. Enum values use UPPER_SNAKE_CASE. Shared callback types live in types.h as comparator and hash_func_t.

Most constructors start with create_. Every module exposes cleanup through a free field on the public struct, called as self->free(self).

Ownership

The library owns internal storage. The caller owns stored payloads.

That rule covers lists, queues, heaps, stacks, deque, maps, sets, trees, tries, graphs, matrices, vectors, and solver objects. Destroying the container or handle frees the container state, not the user data that the container points to.

Callback Semantics

Comparators and hash functions are part of the data model, not optional decoration.

Comparators define order in SORTED_LIST, heaps, priority queues, trees, and tree-backed sets. In hash-based structures, comparators define equality and hash functions define bucket placement. Equal keys must hash to the same bucket family, or lookup and removal stop making sense.

The strict case is set algebra. union_with, intersection_with, difference_with, and is_subset_of require both sets to use the same implementation family and the same callback pointers.

Empty and Boundary Behavior

The library follows a small number of patterns.

Factory functions return NULL on allocation failure or invalid construction arguments.

Read operations on empty structures usually return NULL. That includes queue->dequeue, stack->pop, stack->top, heap->pop, heap->peek, deque->pop_front, deque->pop_back, deque->peek_front, deque->peek_back, map->get for a missing key, tree->search for a missing key, and trie->search for a missing word.

Indexed reads return NULL when the index is out of range. That includes list->get and deque->get.

Invalid mutating operations usually leave state unchanged. Array-list and linked-list inserts with an invalid index are no-ops in the shipped tests. tree->delete on a missing key is a no-op. graph->remove_edge on a missing endpoint is a no-op.

Results You Must Destroy

The following result objects belong to the caller and must be destroyed after use.

graph->get_neighbors, traversal result lists, component lists, SCC lists, MST edge lists, tree->range_query, trie->get_words_with_prefix, matrix results from arithmetic calls, vectors returned by shortest-path calls, matrices returned by Floyd-Warshall, and simplex tableaux returned through solve.

Results You Must Not Free

The following return paths hand back stored pointers, not copies.

list->get, deque->get, map->get, tree->search, tree->min, tree->max, tree->predecessor, tree->successor, set->to_list payload entries, and trie->search return stored payload pointers.

Graph traversal lists contain graph-owned int * vertex-id pointers. You free the list container, not the integers inside it.

Read Next

If the next question is module choice, move to Containers or Associative-Structures. If the next question is graph or numeric work, move to Graphs or Numerics-and-Optimization.