Fix unflatten and binary dumping for non-default configurations

unflatten() decided between array and object by looking at the first reference
token it happened to see for a node: it started an array only when that token
was 0. With a sorted object type the token 0 always arrives first, so the
result was correct by accident; with an object type whose iteration order is
unspecified, {"/c/2":3,"/c/1":2,"/c/0":1} unflattened to an object with the
keys "0", "1", and "2" instead of an array.

Collect the pointer prefixes that have a reference token 0 among their children
before building the result, and let get_and_create() consult that set. The
outcome is now independent of the iteration order and matches, for every input,
what a sorted object type produced before: a value is restored as an array if
and only if one of its keys is 0. Iterating the flattened object in a different
order would have been simpler, but it would have changed the key order of the
result for insertion-ordered object types.

The serializer, std::hash, and the UBJSON writer converted the elements of a
binary value to an integer implicitly, which does not compile for a BinaryType
whose value type is std::byte, and which made dump() write the bytes of a
signed value type as negative numbers. Convert to std::uint8_t explicitly in
all three places, so every byte type dumps as 0..255. The default
std::vector<std::uint8_t> configuration is unaffected.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018hxZxz8svM54c6ATEvXp5E
Signed-off-by: Niels Lohmann <mail@nlohmann.me>

docs/mkdocs/docs/api/basic_json/binary_t.md

@@ -54,10 +54,8 @@ The default values for `BinaryType` is `#!cpp std::vector<std::uint8_t>`.
 
 #### Supported byte types
 
-`#!cpp std::vector<std::uint8_t>` and `#!cpp std::vector<char>` are fully supported. With
-`#!cpp std::vector<std::byte>`, assignment, [`get`](get.md), and the [binary formats](../../features/binary_formats/index.md)
-work, but [`dump`](dump.md) and [`std::hash<basic_json>`](std_hash.md) do not compile, because `#!cpp std::byte` neither
-converts to an integer nor is hashable as one.
+`#!cpp std::vector<std::uint8_t>`, `#!cpp std::vector<char>`, and `#!cpp std::vector<std::byte>` are supported.
+Regardless of which of them is configured, [`dump`](dump.md) writes the bytes as the numbers 0..255.
 
 #### Custom BinaryType behavior
 
@@ -135,3 +133,6 @@ type `#!cpp binary_t*` must be dereferenced.
 ## Version history
 
 - Added in version 3.8.0. Changed the type of subtype to `std::uint64_t` in version 3.10.0.
+- Fixed [`dump`](dump.md), [`std::hash`](std_hash.md), and [`to_ubjson`](to_ubjson.md) for byte types that are not
+  integers (e.g., `#!cpp std::byte`) in version 3.13.0. `dump` now writes the bytes of a signed byte type (e.g.,
+  `#!cpp char`) as 0..255 rather than as negative numbers.

docs/mkdocs/docs/api/basic_json/unflatten.md

@@ -37,7 +37,14 @@ Linear in the size of the JSON value.
 ## Notes
 
 Empty objects and arrays are flattened by [`flatten()`](flatten.md) to `#!json null` values and cannot unflattened to
-their original type. Apart from this example, for a JSON value `j`, the following is always true:
+their original type.
+
+A flattened array and a flattened object whose keys are array indices are indistinguishable, because both are
+described by the same JSON pointers. A value is therefore restored as an array if and only if one of its keys is the
+reference token `0`, and as an object otherwise: `#!json {"2": 1}` is restored unchanged, whereas `#!json {"0": 1}` is
+restored as `#!json [1]`. This decision does not depend on the order in which the flattened object is iterated.
+
+Apart from these two cases, for a JSON value `j`, the following is always true:
 `#!cpp j == j.flatten().unflatten()`.
 
 ## Examples
@@ -63,3 +70,4 @@ their original type. Apart from this example, for a JSON value `j`, the followin
 ## Version history
 
 - Added in version 2.0.0.
+- Made the array/object decision independent of the object's iteration order in version 3.13.0.

docs/mkdocs/docs/features/types/template_parameters.md

@@ -112,13 +112,11 @@ using unordered_json = nlohmann::basic_json<unordered_map_object>;
 The same pattern (ignoring the third argument) is how [`tsl::ordered_map`](https://github.com/Tessil/ordered-map) and
 similar containers are integrated; see [Object Order](../object_order.md).
 
-#### Hash-ordered containers and `unflatten`
+#### Iteration order
 
-[`unflatten`](../../api/basic_json/unflatten.md) rebuilds an array only if it encounters the reference token `0`
-before the other indices of that array. Sorted containers (`#!cpp std::map`) and insertion-ordered containers
-(`nlohmann::ordered_map`) both iterate the flattened object in an order that satisfies this. A container with an
-unspecified iteration order does not, and `#!cpp j.flatten().unflatten()` may then return objects with the keys
-`#!json "0"`, `#!json "1"`, ... where the original had arrays.
+The library never relies on the container's iteration order for correctness; it does determine the order in which
+object keys are serialized by [`dump`](../../api/basic_json/dump.md) and visited by
+[`items`](../../api/basic_json/items.md). See [Object Order](../object_order.md).
 
 #### `capacity()` marks a container as insertion-ordered
 
@@ -138,7 +136,7 @@ The library does not sort or de-duplicate keys itself; the behavior described in
 |--------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------|
 | `#!cpp std::map` (default)                                                                                               | full                                                                          |
 | [`nlohmann::ordered_map`](../../api/ordered_map.md)                                                                      | full; used by [`ordered_json`](../../api/ordered_json.md)                      |
-| `#!cpp std::unordered_map`, through the adapter shown above                                                              | full except [`unflatten`](../../api/basic_json/unflatten.md)                   |
+| `#!cpp std::unordered_map`, through the adapter shown above                                                              | full                                                                          |
 | [`tsl::ordered_map`](https://github.com/Tessil/ordered-map), [`nlohmann::fifo_map`](https://github.com/nlohmann/fifo_map) | through the same adapter pattern; see [Object Order](../object_order.md)       |
 | `#!cpp std::multimap`, `#!cpp std::unordered_multimap`                                                                   | not usable; `emplace` does not return `#!cpp std::pair<iterator, bool>`        |
 
@@ -437,7 +435,7 @@ such a container to a `basic_json` value.
 |------------------------------------------|-----------------------------------------------------------------------------------------------|
 | `#!cpp std::vector<std::uint8_t>` (default) | full                                                                                       |
 | `#!cpp std::vector<char>`                | full                                                                                          |
-| `#!cpp std::vector<std::byte>`           | assignment, [`get`](../../api/basic_json/get.md), and the binary formats work, but [`dump`](../../api/basic_json/dump.md) and [`std::hash<basic_json>`](../../api/basic_json/std_hash.md) do not compile |
+| `#!cpp std::vector<std::byte>`           | full                                                                                          |
 | `#!cpp std::string`                      | not usable; `binary_t::container_type` and `string_t` would be the same type, which makes the [`swap`](../../api/basic_json/swap.md) overloads ambiguous |
 | containers whose `value_type` is wider than one byte | not usable                                                                        |