deploy: ad94fb01cc

features/conversions.md

@@ -66,8 +66,14 @@ auto t = j.get<std::tuple<double, std::string, int>>();  // {1.0, "hello", 42}
     std::get<1>(refs) = "world";  // modifies j[1] in place
     ```
 
-    A referenced type must be one the library actually stores (or an arithmetic type it can convert to/from);
-    otherwise this is a compile error.
+    A referenced element must name the type the library actually *stores* — one of [`boolean_t`](../api/basic_json/boolean_t.md),
+    [`number_integer_t`](../api/basic_json/number_integer_t.md), [`number_unsigned_t`](../api/basic_json/number_unsigned_t.md),
+    [`number_float_t`](../api/basic_json/number_float_t.md), [`string_t`](../api/basic_json/string_t.md),
+    [`binary_t`](../api/basic_json/binary_t.md), [`array_t`](../api/basic_json/array_t.md), or
+    [`object_t`](../api/basic_json/object_t.md). There is nothing else to refer to, so a reference to any other type is a
+    compile error even when a conversion would exist: `#!cpp std::tuple<int&>` is rejected, because the library stores a
+    `#!cpp number_integer_t` (`#!cpp std::int64_t` by default) and not an `#!cpp int`. This restriction applies only to
+    reference elements — a plain `#!cpp std::tuple<int>` converts by value as usual.
 
 ## Implicit conversions
 
@@ -116,17 +122,34 @@ which forces the explicit `get` form and can catch unintended conversions at com
     with a custom `adl_serializer<std::optional<T>>` specialization. Prefer `get<std::optional<T>>()`/`get_to()`
     over `static_cast` for optional types.
 
-!!! warning "Converting to a fixed-size `std::array` does not check length"
+!!! warning "Converting to a fixed-size destination does not check the array size"
 
-    Converting a JSON array to `#!cpp std::array<T, N>` does not check that the JSON array's size matches `N`:
-    if the JSON array is longer, the extra elements are silently dropped; if it is shorter, the remaining
-    `std::array` elements are left default-constructed. No exception is thrown in either case.
+    Some destination types have a size that is fixed by their C++ type rather than by the JSON value:
+    `#!cpp std::pair<A, B>`, `#!cpp std::tuple<Ts...>`, `#!cpp std::array<T, N>`, C arrays `#!cpp T[N]`, and
+    `#!cpp std::map`/`#!cpp std::unordered_map` with a non-string key type (which is read from an array of
+    two-element arrays). All of them read exactly as many elements as they need via
+    [`at`](../api/basic_json/at.md) and **never compare the JSON array's size to that number**. The two
+    mismatch directions therefore behave differently:
+
+    - The JSON array has **too many** elements: the surplus is **silently discarded**, and no exception is
+      thrown.
+    - The JSON array has **too few** elements: `at` throws
+      [`out_of_range.401`](../home/exceptions.md#jsonexceptionout_of_range401) for the first missing index --
+      an out-of-range error, not a [`type_error`](../home/exceptions.md#type-errors), even though the cause
+      is a shape mismatch.
 
     ```cpp
     json j = {1, 2, 3, 4, 5};
-    auto a = j.get<std::array<int, 3>>();  // {1, 2, 3} -- elements 4 and 5 silently dropped
+
+    auto a = j.get<std::array<int, 3>>();       // {1, 2, 3} -- elements 4 and 5 silently dropped
+    auto p = j.get<std::pair<int, int>>();      // (1, 2)    -- elements 3, 4, and 5 silently dropped
+
+    json k = {1};
+    auto q = k.get<std::pair<int, int>>();      // ❌ throws out_of_range.401
     ```
 
+    If a size mismatch is an error in your application, check the size yourself before converting.
+
 ## Omitting a field when serializing `std::optional`
 
 By default, `to_json` for `std::optional<T>` writes either the value or `#!json null` -- there is no built-in way

features/conversions/index.md

@@ -124,7 +124,7 @@ auto refs = j.get<std::tuple<double&, std::string&>>();
 std::get<1>(refs) = "world";  // modifies j[1] in place
 ```
 
-A referenced type must be one the library actually stores (or an arithmetic type it can convert to/from); otherwise this is a compile error.
+A referenced element must name the type the library actually *stores* — one of [`boolean_t`](https://json.nlohmann.me/api/basic_json/boolean_t/index.md), [`number_integer_t`](https://json.nlohmann.me/api/basic_json/number_integer_t/index.md), [`number_unsigned_t`](https://json.nlohmann.me/api/basic_json/number_unsigned_t/index.md), [`number_float_t`](https://json.nlohmann.me/api/basic_json/number_float_t/index.md), [`string_t`](https://json.nlohmann.me/api/basic_json/string_t/index.md), [`binary_t`](https://json.nlohmann.me/api/basic_json/binary_t/index.md), [`array_t`](https://json.nlohmann.me/api/basic_json/array_t/index.md), or [`object_t`](https://json.nlohmann.me/api/basic_json/object_t/index.md). There is nothing else to refer to, so a reference to any other type is a compile error even when a conversion would exist: `std::tuple<int&>` is rejected, because the library stores a `number_integer_t` (`std::int64_t` by default) and not an `int`. This restriction applies only to reference elements — a plain `std::tuple<int>` converts by value as usual.
 
 ## Implicit conversions
 
@@ -161,15 +161,25 @@ j_null.get_to(opt);                                     // ✅ std::nullopt
 
 `operator ValueType()` (used by `static_cast` and implicit conversions) intentionally excludes `std::optional<T>` from delegating to `get<T>()`, to avoid a constructor ambiguity with `std::optional<T>`'s own converting constructor from `basic_json`. As a result, `static_cast<std::optional<T>>(json_value)` goes through `std::optional<T>`'s own converting constructor rather than through `get<std::optional<T>>()`, which can behave differently -- for example, with a custom `adl_serializer<std::optional<T>>` specialization. Prefer `get<std::optional<T>>()`/`get_to()` over `static_cast` for optional types.
 
-Converting to a fixed-size `std::array` does not check length
+Converting to a fixed-size destination does not check the array size
 
-Converting a JSON array to `std::array<T, N>` does not check that the JSON array's size matches `N`: if the JSON array is longer, the extra elements are silently dropped; if it is shorter, the remaining `std::array` elements are left default-constructed. No exception is thrown in either case.
+Some destination types have a size that is fixed by their C++ type rather than by the JSON value: `std::pair<A, B>`, `std::tuple<Ts...>`, `std::array<T, N>`, C arrays `T[N]`, and `std::map`/`std::unordered_map` with a non-string key type (which is read from an array of two-element arrays). All of them read exactly as many elements as they need via [`at`](https://json.nlohmann.me/api/basic_json/at/index.md) and **never compare the JSON array's size to that number**. The two mismatch directions therefore behave differently:
+
+- The JSON array has **too many** elements: the surplus is **silently discarded**, and no exception is thrown.
+- The JSON array has **too few** elements: `at` throws [`out_of_range.401`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range401) for the first missing index -- an out-of-range error, not a [`type_error`](https://json.nlohmann.me/home/exceptions/#type-errors), even though the cause is a shape mismatch.
 
 ```
 json j = {1, 2, 3, 4, 5};
-auto a = j.get<std::array<int, 3>>();  // {1, 2, 3} -- elements 4 and 5 silently dropped
+
+auto a = j.get<std::array<int, 3>>();       // {1, 2, 3} -- elements 4 and 5 silently dropped
+auto p = j.get<std::pair<int, int>>();      // (1, 2)    -- elements 3, 4, and 5 silently dropped
+
+json k = {1};
+auto q = k.get<std::pair<int, int>>();      // ❌ throws out_of_range.401
 ```
 
+If a size mismatch is an error in your application, check the size yourself before converting.
+
 ## Omitting a field when serializing `std::optional`
 
 By default, `to_json` for `std::optional<T>` writes either the value or `null` -- there is no built-in way to make a field disappear from the serialized object entirely when the `std::optional` is `std::nullopt`. Because a specialization of `adl_serializer<std::optional<T>>` only controls how the *value* is converted (it cannot prevent the containing object's `to_json` from inserting the key in the first place), omission has to be implemented in the *containing* type's `to_json`:

features/object_order.md

@@ -53,6 +53,12 @@ If you do want to preserve the **insertion order**, you can use the type [`nlohm
 
 Alternatively, you can use a more sophisticated ordered map like [`tsl::ordered_map`](https://github.com/Tessil/ordered-map) ([integration](https://github.com/nlohmann/json/issues/546#issuecomment-304447518)) or [`nlohmann::fifo_map`](https://github.com/nlohmann/fifo_map) ([integration](https://github.com/nlohmann/json/issues/485#issuecomment-333652309)).
 
+The [`ordered_map`](../api/ordered_map.md) behind `nlohmann::ordered_json` is deliberately minimal and has no lookup
+index, so every key access is a linear scan and building an object of `n` keys costs O(n²). This is unnoticeable at
+typical object sizes but becomes significant for objects with many thousands of keys; see
+[`ordered_map` complexity](../api/ordered_map.md#complexity). The alternatives above keep a lookup index and do not
+have this cost.
+
 ### Notes on parsing
 
 Note that you also need to call the right [`parse`](../api/basic_json/parse.md) function when reading from a file.

features/object_order/index.md

@@ -70,6 +70,8 @@ Output:
 
 Alternatively, you can use a more sophisticated ordered map like [`tsl::ordered_map`](https://github.com/Tessil/ordered-map) ([integration](https://github.com/nlohmann/json/issues/546#issuecomment-304447518)) or [`nlohmann::fifo_map`](https://github.com/nlohmann/fifo_map) ([integration](https://github.com/nlohmann/json/issues/485#issuecomment-333652309)).
 
+The [`ordered_map`](https://json.nlohmann.me/api/ordered_map/index.md) behind `nlohmann::ordered_json` is deliberately minimal and has no lookup index, so every key access is a linear scan and building an object of `n` keys costs O(n²). This is unnoticeable at typical object sizes but becomes significant for objects with many thousands of keys; see [`ordered_map` complexity](https://json.nlohmann.me/api/ordered_map/#complexity). The alternatives above keep a lookup index and do not have this cost.
+
 ### Notes on parsing
 
 Note that you also need to call the right [`parse`](https://json.nlohmann.me/api/basic_json/parse/index.md) function when reading from a file. Assume file `input.json` contains the JSON object above: