deploy: 7c9208bfb3

api/ordered_map/index.md

@@ -0,0 +1,129 @@
+# nlohmann::ordered_map
+
+```
+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`](https://json.nlohmann.me/api/ordered_json/index.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 `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.
+
+## Member types
+
+- **key_type** - key type (`Key`)
+
+- **mapped_type** - mapped type (`T`)
+
+- **Container** - base container type (`std::vector<std::pair<const Key, T>, Allocator>`)
+
+- **iterator**
+
+- **const_iterator**
+
+- **size_type**
+
+- **value_type**
+
+- **key_compare** - key comparison function
+
+  ```
+  std::equal_to<Key>  // until C++14
+
+  std::equal_to<>     // since C++14
+  ```
+
+## Member functions
+
+- (constructor)
+- (destructor)
+- **emplace**
+- **operator[]**
+- **at**
+- **erase**
+- **count**
+- **find**
+- **insert**
+
+## Examples
+
+Example
+
+The example shows the different behavior of `std::map` and `nlohmann::ordered_map`.
+
+```
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+// simple output function
+template<typename Map>
+void output(const char* prefix, const Map& m)
+{
+    std::cout << prefix << " = { ";
+    for (auto& element : m)
+    {
+        std::cout << element.first << ":" << element.second << ' ';
+    }
+    std::cout << "}" << std::endl;
+}
+
+int main()
+{
+    // create and fill two maps
+    nlohmann::ordered_map<std::string, std::string> m_ordered;
+    m_ordered["one"] = "eins";
+    m_ordered["two"] = "zwei";
+    m_ordered["three"] = "drei";
+
+    std::map<std::string, std::string> m_std;
+    m_std["one"] = "eins";
+    m_std["two"] = "zwei";
+    m_std["three"] = "drei";
+
+    // output: m_ordered is ordered by insertion order, m_std is ordered by key
+    output("m_ordered", m_ordered);
+    output("m_std", m_std);
+
+    // erase and re-add "one" key
+    m_ordered.erase("one");
+    m_ordered["one"] = "eins";
+
+    m_std.erase("one");
+    m_std["one"] = "eins";
+
+    // output: m_ordered shows newly added key at the end; m_std is again ordered by key
+    output("m_ordered", m_ordered);
+    output("m_std", m_std);
+}
+```
+
+Output:
+
+```
+m_ordered = { one:eins two:zwei three:drei }
+m_std = { one:eins three:drei two:zwei }
+m_ordered = { two:zwei three:drei one:eins }
+m_std = { one:eins three:drei two:zwei }
+```
+
+## See also
+
+- [ordered_json](https://json.nlohmann.me/api/ordered_json/index.md)
+
+## Version history
+
+- 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.