Containers

Read this page when the main question is how values enter, leave, and stay ordered in memory. The right structure is decided by 3 facts: how you address elements, which end you remove from, and whether order is caller-driven or comparator-driven.

Choose by Access Pattern

For indexed sequence access, read Lists. Constructor family: create_list(...).

For FIFO or LIFO flow, read Queues and Stacks. Constructor families: create_queue(...), create_stack(...).

For priority order or key updates inside the heap, read Heaps and Priority Queues. Constructor families: create_heap(...), create_queue(QUEUE_TYPE_PRIORITY, ...).

For push and pop at both ends with random access, read Deque. Constructor family: create_deque(...).

For in-place operations on a public list, read Sorting. Constructor family: create_sorter(...).

Selection Diagram

flowchart TD
    A[Need a linear structure] --> B{Need both ends?}
    B -->|yes| DQ[Deque]
    B -->|no| C{Need priority order?}
    C -->|yes| HPQ[Heaps and Priority Queues]
    C -->|no| D{Need FIFO or LIFO?}
    D -->|yes| QS[Queues and Stacks]
    D -->|no| E{Need indexed position?}
    E -->|yes| L[Lists]
    E -->|already have a list| S[Sorting]

Decision Rules

Use a list when position matters and the caller chooses the insertion index.

Use a queue when removal must happen from one end and insertion from the other.

Use a stack when the next element out must be the last element in.

Use a heap when order comes from a comparator and you only care about the current top element, not indexed traversal.

Use a deque when you need both ends and still want indexed reads.

Use the sorting helper when you already have a list and want sorting, reversing, shuffling, binary search, or min/max without changing to another container family.

What All Container Pages Cover

Each module page below answers five caller questions: the constructor contract, the operation set, the ownership rule, the empty-case behavior, and the places where one implementation behaves differently from another.

Move next to Lists, Queues-and-Stacks, Heaps-and-Priority-Queues, Deque, or Sorting.