Niels Lohmann
63c10a51fc
* Review and extend the documentation, and check it in CI A review of all documentation pages found factual errors, dead links, missing cross-references, and gaps in examples. This fixes them and adds checks so the same problems are caught automatically. Fixes: - wrong signatures and version histories (operator!= C++20 member, binary() subtype type, get<PointerType>(), JSON_NO_THREAD_LOCAL, ...) - stale descriptions (number parsing since #5283, UBJSON table, SAX example that no longer compiled, tsl::ordered_map advice) - dead internal and external links; repology.org badges (the domain is suspended) replaced by badges that query the registries directly - deprecation notes link the migration guide; the guide itself fixed Additions: - "See also" sections, cross-references, 25 runnable examples, 12 Mermaid diagrams, new API pages for json_pointer::operator<=> and byte_container_with_subtype::operator==/!= - landing page, guides for untrusted input and performance - "unreleased" badge after versions newer than the latest release Checks: - strict documentation build (broken links/anchors fail it); CI and the publish workflow fetch the full history the build needs - weekly external link check, Mermaid syntax check in CI - check_structure.py: example titles, heading levels, alt texts, header links, docset index coverage; its unused-example check works again - all examples produce the same output on every platform Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Keep the customer links that could not be fixed A dead link on the customers page is still the evidence of where the use of the library was documented. Keep the original URLs of the entries without a working replacement (Marne, Cisco Webex Desk Camera, Philips Hue, CyberArk) and exclude exactly these URLs from the link check. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Correct the duplicate-key recipe's claim about SAX positions The SAX interface's key() receives no position either; only parse_error() does. Also note that the recipe does not report the path to the repeated key (see discussion #5085). Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Say the library is available as a single header and mention json_fwd.hpp Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Correct documentation errors found while hunting for bugs - patch/patch_inplace: list the JSON pointer errors parse_error.106-109 and out_of_range.402/404, and quote the actual parse_error.105 message. - unflatten: list parse_error.106/107/108 and out_of_range.404. - to_bson: list out_of_range.415 (binary subtype above 255) and note that 412 and 415 are new in 3.13.0. - to_string: state that string_t must be convertible to std::string, also in the StringType requirements table. - JSON Lines: a `while (input >> j)` loop also throws after the last value for concatenated JSON values; show a loop that works for both. - BON8: a string gets 0xFF only if nothing follows it in the message; a string at the end of an array or object is ended by 0xFE. - custom_string_type.hpp: add operator+=(char), which the "Always required" list asks for (json_pointer::to_string, flatten, unflatten, and diff did not compile), and an ADL int_to_string for diff and items. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Cache the release headers with functools.lru_cache Codacy (Pylint) flagged the mutable default argument that header() used as its cache. functools.lru_cache keeps the same memoization without it. The script's output is unchanged. Signed-off-by: Niels Lohmann <mail@nlohmann.me> --------- Signed-off-by: Niels Lohmann <mail@nlohmann.me>
136 lines
5.5 KiB
Markdown
136 lines
5.5 KiB
Markdown
# <small>nlohmann::</small>ordered_map
|
||
|
||
```cpp
|
||
template<class Key, class T, class IgnoredLess = std::less<Key>,
|
||
class Allocator = std::allocator<std::pair<const Key, T>>>
|
||
struct ordered_map : std::vector<std::pair<const Key, T>, Allocator>;
|
||
```
|
||
|
||
A minimal map-like container that preserves insertion order for use within [`nlohmann::ordered_json`](ordered_json.md)
|
||
(`nlohmann::basic_json<ordered_map>`).
|
||
|
||
## Template parameters
|
||
|
||
`Key`
|
||
: key type
|
||
|
||
`T`
|
||
: mapped type
|
||
|
||
`IgnoredLess`
|
||
: comparison function (ignored and only added to ensure compatibility with `#!cpp std::map`)
|
||
|
||
`Allocator`
|
||
: allocator type
|
||
|
||
## Iterator invalidation
|
||
|
||
The type uses a `std::vector` to store object elements. Therefore, adding elements can yield a reallocation in which
|
||
case all iterators (including the `end()` iterator) and all references to the elements are invalidated.
|
||
|
||
When the storage grows, the keys are copied and the mapped values are moved to the new storage. A plain `std::vector`
|
||
would copy the whole elements instead, because their `#!cpp const` keys make them not nothrow move constructible; for
|
||
[`ordered_json`](ordered_json.md), this would be a deep copy of every nested value. The values are only copied if
|
||
`T` is not default constructible or not nothrow move assignable.
|
||
|
||
## Member types
|
||
|
||
- **key_type** - key type (`Key`)
|
||
- **mapped_type** - mapped type (`T`)
|
||
- **Container** - base container type (`#!cpp std::vector<std::pair<const Key, T>, Allocator>`)
|
||
- **iterator**
|
||
- **const_iterator**
|
||
- **size_type**
|
||
- **value_type**
|
||
- **key_compare** - key comparison function
|
||
```cpp
|
||
std::equal_to<Key> // until C++14
|
||
|
||
std::equal_to<> // since C++14
|
||
```
|
||
|
||
## Member functions
|
||
|
||
- (constructor)
|
||
- (destructor)
|
||
- **emplace**
|
||
- **operator\[\]**
|
||
- **at**
|
||
- **erase**
|
||
- **count**
|
||
- **find**
|
||
- **insert**
|
||
|
||
## Exception safety
|
||
|
||
**emplace**, **operator\[\]**, and **insert(value)** have the strong exception guarantee: if an exception is thrown (for
|
||
instance, because copying a key or allocating memory fails), the contents of the container are unchanged.
|
||
|
||
## Complexity
|
||
|
||
Because the elements are stored in a `std::vector` in insertion order, there is no index to look a key up by. Every
|
||
key-based operation performs a **linear scan** over the stored elements. With `n` denoting the number of elements in the
|
||
container:
|
||
|
||
| Operation | Complexity | Note |
|
||
|----------------------------------------|----------------|----------------------------------------------------------|
|
||
| **emplace** | O(n) | scans for an existing key, then appends (amortized O(1)) |
|
||
| **operator\[\]** | O(n) | delegates to **emplace** (non-const) or **at** (const) |
|
||
| **at** | O(n) | throws `#!cpp std::out_of_range` if the key is not found |
|
||
| **find** | O(n) | |
|
||
| **count** | O(n) | the result is always 0 or 1 |
|
||
| **erase(key)** | O(n) | scan, then move the remaining elements one position down |
|
||
| **erase(pos)**, **erase(first, last)** | O(n) | moves all elements after the erased range |
|
||
| **insert(value)** | O(n) | equivalent to **emplace** |
|
||
| **insert(first, last)** | O((n + m) * m) | for `m` inserted elements |
|
||
|
||
This differs from `#!cpp std::map`, where the same operations are O(log n).
|
||
|
||
!!! warning "Quadratic cost of building large objects"
|
||
|
||
Because every insertion scans all elements inserted so far, building an object of `n` distinct keys costs
|
||
**O(n²)** in total. This applies to filling an [`ordered_json`](ordered_json.md) object key by key as well as to
|
||
parsing one, since the parser inserts each key as it is read.
|
||
|
||
The cost is negligible for the object sizes typically found in configuration files or API payloads, but it grows
|
||
steeply for machine-generated objects with many thousands of keys. Measured with `-O2 -DNDEBUG` for parsing a flat
|
||
object of `n` keys, relative to `#!cpp nlohmann::json` (which uses `#!cpp std::map`):
|
||
|
||
| `n` | `json` | `ordered_json` | factor |
|
||
|--------|--------|----------------|--------|
|
||
| 2000 | 0.7 ms | 3.6 ms | 5× |
|
||
| 4000 | 0.8 ms | 14.0 ms | 19× |
|
||
| 8000 | 1.6 ms | 67.8 ms | 43× |
|
||
| 16 000 | 3.3 ms | 181.6 ms | 54× |
|
||
|
||
If key order matters for objects of that size, consider a container with a lookup index, such as
|
||
[`nlohmann::fifo_map`](https://github.com/nlohmann/fifo_map)
|
||
([integration](https://github.com/nlohmann/json/issues/485#issuecomment-333652309)), as the object type -- see
|
||
[object order](../features/object_order.md).
|
||
|
||
## Examples
|
||
|
||
??? example
|
||
|
||
The example shows the different behavior of `std::map` and `nlohmann::ordered_map`.
|
||
|
||
```cpp
|
||
--8<-- "examples/ordered_map.cpp"
|
||
```
|
||
|
||
Output:
|
||
|
||
```json
|
||
--8<-- "examples/ordered_map.output"
|
||
```
|
||
|
||
## See also
|
||
|
||
- [ordered_json](ordered_json.md)
|
||
|
||
## Version history
|
||
|
||
- Added in version 3.9.0 to implement [`nlohmann::ordered_json`](ordered_json.md).
|
||
- Added **key_compare** member in version 3.11.0.
|
||
- Changed in version 3.13.0: growing the storage moves the mapped values instead of copying them.
|