deploy: 4d46bce4e1

api/ordered_map/index.md

@@ -22,6 +22,8 @@ A minimal map-like container that preserves insertion order for use within [`nlo
 
 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 `const` keys make them not nothrow move constructible; for [`ordered_json`](https://json.nlohmann.me/api/ordered_json/index.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`)
@@ -58,6 +60,10 @@ The type uses a `std::vector` to store object elements. Therefore, adding elemen
 - **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:
@@ -160,3 +166,4 @@ m_std = { one:eins three:drei two:zwei }
 
 - Added in version 3.9.0 to implement [`nlohmann::ordered_json`](https://json.nlohmann.me/api/ordered_json/index.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.