insertionordered

Insertionordered refers to the property of certain associative containers that preserve the sequence in which elements were added. In such containers, iterating over the elements yields them in insertion order rather than in an arbitrary order or according to key value. The term is often used for maps and sets that guarantee a stable, insertion-based iteration sequence.

Implementation and behavior can vary by language and library. Typically, an insertion-ordered container maintains a secondary structure, such as a linked list, to record the order of insertions while using a hash table for fast lookups. In many implementations, inserting a new element appends it to the end of the order; updating an existing key’s value usually does not move its position; removing an element deletes it from the order; re-inserting a key after removal may place it at the end, depending on the API. Exact semantics depend on the specific data structure being used.

Examples by language include: Java's LinkedHashMap and LinkedHashSet, which preserve insertion order; Python's dict (since version 3.7) and collections.OrderedDict, both preserving insertion order; JavaScript's Map and Set, which maintain insertion order of keys and values; PHP arrays, which preserve insertion order. In contrast, standard C++ containers like std::map order elements by key, and std::unordered_map does not guarantee a stable order.

Use cases for insertion-ordered structures include predictable iteration for serialization, debugging, and generating deterministic output across runs, as well as certain caching and streaming scenarios. Trade-offs commonly involve higher memory overhead and potentially slower insertion compared with unordered or non-ordered containers, along with the need to understand each API’s exact order semantics.