deploy: e9c3985f0a

api/basic_json/basic_json.md

@@ -115,7 +115,22 @@ basic_json(basic_json&& other) noexcept;
    
     Function [`array()`](array.md) and [`object()`](object.md) force array and object creation from initializer lists,
     respectively.
-        
+
+    !!! warning "Brace initialization yields arrays"
+
+        Because this constructor takes an `initializer_list_t`, brace-initializing a `json`/`ordered_json` from
+        another `json` value wraps it in a single-element array rather than copying it:
+
+        ```cpp
+        json j1 = "hello";
+        json j2{j1};   // [!] j2 is ["hello"], NOT a copy of j1
+        json j3(j1);   // j3 is "hello" -- parentheses copy as expected
+        ```
+
+        See the FAQ entry on [brace initialization](../../home/faq.md#brace-initialization-yields-arrays) for the
+        full explanation, an opt-in macro to change this behavior, and how to explicitly create a single-element
+        array (`json::array({value})`) if that is what you want.
+
 6. Constructs a JSON array value by creating `cnt` copies of a passed value. In case `cnt` is `0`, an empty array is
    created.
 

api/basic_json/basic_json/index.md

@@ -88,6 +88,18 @@ basic_json(basic_json&& other) noexcept;
 
    Function [`array()`](https://json.nlohmann.me/api/basic_json/array/index.md) and [`object()`](https://json.nlohmann.me/api/basic_json/object/index.md) force array and object creation from initializer lists, respectively.
 
+   Brace initialization yields arrays
+
+   Because this constructor takes an `initializer_list_t`, brace-initializing a `json`/`ordered_json` from another `json` value wraps it in a single-element array rather than copying it:
+
+   ```
+   json j1 = "hello";
+   json j2{j1};   // [!] j2 is ["hello"], NOT a copy of j1
+   json j3(j1);   // j3 is "hello" -- parentheses copy as expected
+   ```
+
+   See the FAQ entry on [brace initialization](https://json.nlohmann.me/home/faq/#brace-initialization-yields-arrays) for the full explanation, an opt-in macro to change this behavior, and how to explicitly create a single-element array (`json::array({value})`) if that is what you want.
+
 1. Constructs a JSON array value by creating `cnt` copies of a passed value. In case `cnt` is `0`, an empty array is created.
 
 1. Constructs the JSON value with the contents of the range `[first, last)`. The semantics depend on the different types a JSON value can have:

api/basic_json/binary_t.md

@@ -37,6 +37,14 @@ represent a byte array in modern C++.
 `BinaryType`
 :   container type to store arrays
 
+    Although not formally expressed as a C++ concept, `BinaryType` must be default-constructible,
+    copy/move-constructible, and support `push_back()`, `.data()`, and `.size()`, because
+    [`byte_container_with_subtype`](../byte_container_with_subtype/index.md) derives directly from it. Its
+    `value_type` must additionally be exactly one byte wide (e.g., `std::uint8_t`/`char`/`std::byte`): the binary
+    serializers (CBOR, MessagePack, BSON, UBJSON) read and write the container's raw bytes via
+    `reinterpret_cast`, which is only correct for byte-sized elements -- a container like
+    `#!cpp std::vector<std::intptr_t>` will not work as `BinaryType`.
+
 ## Notes
 
 #### Default type

api/basic_json/binary_t/index.md

@@ -28,6 +28,16 @@ The default representation of this binary format is a `std::vector<std::uint8_t>
 
 `BinaryType` : container type to store arrays
 
+```
+Although not formally expressed as a C++ concept, `BinaryType` must be default-constructible,
+copy/move-constructible, and support `push_back()`, `.data()`, and `.size()`, because
+[`byte_container_with_subtype`](https://json.nlohmann.me/api/byte_container_with_subtype/index.md) derives directly from it. Its
+`value_type` must additionally be exactly one byte wide (e.g., `std::uint8_t`/`char`/`std::byte`): the binary
+serializers (CBOR, MessagePack, BSON, UBJSON) read and write the container's raw bytes via
+`reinterpret_cast`, which is only correct for byte-sized elements -- a container like
+`std::vector<std::intptr_t>` will not work as `BinaryType`.
+```
+
 ## Notes
 
 #### Default type

api/basic_json/items.md

@@ -46,6 +46,17 @@ for (auto& [key, val] : j_object.items())
 }
 ```
 
+If you need to name the type of the dereferenced element explicitly (e.g., to write a standalone function that
+takes it as a parameter, or to use `items()` with `std::for_each`), use `decltype`:
+
+```cpp
+using element_type = decltype(*j_object.items().begin());
+```
+
+The per-element type (`iteration_proxy_value`) lives in the library's internal `detail` namespace and is
+intentionally unspecified as a stable, named type -- `decltype` is the supported way to obtain it, but its exact
+name/definition may change between versions.
+
 ## Return value
 
 iteration proxy object wrapping the current value with an interface to use in range-based for loops

api/basic_json/items/index.md

@@ -44,6 +44,14 @@ for (auto& [key, val] : j_object.items())
 }
 ```
 
+If you need to name the type of the dereferenced element explicitly (e.g., to write a standalone function that takes it as a parameter, or to use `items()` with `std::for_each`), use `decltype`:
+
+```
+using element_type = decltype(*j_object.items().begin());
+```
+
+The per-element type (`iteration_proxy_value`) lives in the library's internal `detail` namespace and is intentionally unspecified as a stable, named type -- `decltype` is the supported way to obtain it, but its exact name/definition may change between versions.
+
 ## Return value
 
 iteration proxy object wrapping the current value with an interface to use in range-based for loops

api/basic_json/operator%5B%5D.md

@@ -124,6 +124,15 @@ Strong exception safety: if an exception occurs, the original value stays intact
       filled with `#!json null`.
     - The special value `-` is treated as a synonym for the index past the end.
 
+    !!! note "Creating intermediate levels that don't exist yet"
+
+        When the JSON pointer traverses intermediate levels that don't exist at all yet (not just a missing
+        leaf), each missing level is created as an array or an object depending on whether the corresponding
+        pointer token parses as a non-negative integer: a numeric token creates an array, a non-numeric token
+        creates an object. For example, on an initially `#!json null` value, `/foo/0/0/0` creates nested arrays,
+        while `/foo/one/one/one` creates nested objects. This is not specified by the JSON Pointer RFC; it is
+        this library's own, intentional disambiguation rule. See also [JSON Pointer](../../features/json_pointer.md).
+
 ## Examples
 
 ??? example "Example: (1) access specified array element"

api/basic_json/operator[]/index.md

@@ -99,6 +99,10 @@ The following cases apply to the **const** overloads; the non-const overloads in
    - If the JSON pointer points to an array index that does not exist, it is created and filled with a `null` value before a reference to it is returned. All indices between the current maximum and the given index are also filled with `null`.
    - The special value `-` is treated as a synonym for the index past the end.
 
+   Creating intermediate levels that don't exist yet
+
+   When the JSON pointer traverses intermediate levels that don't exist at all yet (not just a missing leaf), each missing level is created as an array or an object depending on whether the corresponding pointer token parses as a non-negative integer: a numeric token creates an array, a non-numeric token creates an object. For example, on an initially `null` value, `/foo/0/0/0` creates nested arrays, while `/foo/one/one/one` creates nested objects. This is not specified by the JSON Pointer RFC; it is this library's own, intentional disambiguation rule. See also [JSON Pointer](https://json.nlohmann.me/features/json_pointer/index.md).
+
 ## Examples
 
 Example: (1) access specified array element