deploy: c72f37a40d

api/basic_json.md

@@ -35,6 +35,10 @@ class basic_json;
 | `BinaryType`         | type for binary arrays                                                    | [`binary_t`](binary_t.md)                   |
 | `CustomBaseClass`    | extension point for user code                                             | [`json_base_class_t`](json_base_class_t.md) |
 
+The library imposes a number of requirements on these types that are not expressed as C++ concepts, such as the
+container operations `object_t` and `array_t` must provide, or the fact that `StringType` must be `char`-based. They
+are collected in [Template Parameter Requirements](../../features/types/template_parameters.md).
+
 ## Specializations
 
 - [**json**](../json.md) - default specialization

api/basic_json/array_t.md

@@ -14,7 +14,11 @@ To store objects in C++, a type is defined by the template parameters explained
 ## Template parameters
 
 `ArrayType`
-:   container type to store arrays (e.g., `std::vector` or `std::list`)
+:   container type to store arrays. It must be a vector-like container: the library uses `operator[]`, `at()`, and
+    `resize()`, and requires random-access iterators. `#!cpp std::vector` and `#!cpp std::deque` qualify;
+    `#!cpp std::list` does not. See
+    [Template Parameter Requirements](../../features/types/template_parameters.md#arraytype) for the full list of
+    requirements.
 
 `AllocatorType`
 :   the allocator to use for objects (e.g., `std::allocator`)
@@ -66,3 +70,4 @@ Arrays are stored as pointers in a `basic_json` type. That is, for any access to
 ## Version history
 
 - Added in version 1.0.0.
+- Made `capacity()` optional, so that array types such as `#!cpp std::deque` can be used, in version 3.13.0.

api/basic_json/array_t/index.md

@@ -14,7 +14,7 @@ To store objects in C++, a type is defined by the template parameters explained
 
 ## Template parameters
 
-`ArrayType` : container type to store arrays (e.g., `std::vector` or `std::list`)
+`ArrayType` : container type to store arrays. It must be a vector-like container: the library uses `operator[]`, `at()`, and `resize()`, and requires random-access iterators. `std::vector` and `std::deque` qualify; `std::list` does not. See [Template Parameter Requirements](https://json.nlohmann.me/features/types/template_parameters/#arraytype) for the full list of requirements.
 
 `AllocatorType` : the allocator to use for objects (e.g., `std::allocator`)
 
@@ -71,3 +71,4 @@ true
 ## Version history
 
 - Added in version 1.0.0.
+- Made `capacity()` optional, so that array types such as `std::deque` can be used, in version 3.13.0.

api/basic_json/binary_t.md

@@ -42,7 +42,9 @@ represent a byte array in modern C++.
     `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`.
+    `#!cpp std::vector<std::intptr_t>` will not work as `BinaryType`. The elements must be stored contiguously, and
+    the binary readers additionally require `resize()` and `operator[]`. See
+    [Template Parameter Requirements](../../features/types/template_parameters.md#binarytype) for the full list.
 
 ## Notes
 
@@ -50,6 +52,11 @@ represent a byte array in modern C++.
 
 The default values for `BinaryType` is `#!cpp std::vector<std::uint8_t>`.
 
+#### Supported byte types
+
+`#!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
 
 When a custom `BinaryType` is configured (other than the default `#!cpp std::vector<std::uint8_t>`), you can assign
@@ -126,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.

api/basic_json/binary_t/index.md

@@ -35,7 +35,9 @@ copy/move-constructible, and support `push_back()`, `.data()`, and `.size()`, be
 `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`.
+`std::vector<std::intptr_t>` will not work as `BinaryType`. The elements must be stored contiguously, and
+the binary readers additionally require `resize()` and `operator[]`. See
+[Template Parameter Requirements](https://json.nlohmann.me/features/types/template_parameters/#binarytype) for the full list.
 ```
 
 ## Notes
@@ -44,6 +46,10 @@ serializers (CBOR, MessagePack, BSON, UBJSON) read and write the container's raw
 
 The default values for `BinaryType` is `std::vector<std::uint8_t>`.
 
+#### Supported byte types
+
+`std::vector<std::uint8_t>`, `std::vector<char>`, and `std::vector<std::byte>` are supported. Regardless of which of them is configured, [`dump`](https://json.nlohmann.me/api/basic_json/dump/index.md) writes the bytes as the numbers 0..255.
+
 #### Custom BinaryType behavior
 
 When a custom `BinaryType` is configured (other than the default `std::vector<std::uint8_t>`), you can assign values of that type directly to a `basic_json` instance, and they will automatically be recognized as binary values rather than arrays:
@@ -125,3 +131,4 @@ true
 ## Version history
 
 - Added in version 3.8.0. Changed the type of subtype to `std::uint64_t` in version 3.10.0.
+- Fixed [`dump`](https://json.nlohmann.me/api/basic_json/dump/index.md), [`std::hash`](https://json.nlohmann.me/api/basic_json/std_hash/index.md), and [`to_ubjson`](https://json.nlohmann.me/api/basic_json/to_ubjson/index.md) for byte types that are not integers (e.g., `std::byte`) in version 3.13.0. `dump` now writes the bytes of a signed byte type (e.g., `char`) as 0..255 rather than as negative numbers.

api/basic_json/boolean_t.md

@@ -11,6 +11,14 @@ literals `#!json true` and `#!json false`.
 
 To store boolean values in C++, a type is defined by the template parameter  `BooleanType` which chooses the type to use.
 
+## Template parameters
+
+`BooleanType`
+:   the type to store booleans. As it is stored directly inside a `basic_json` value (in a union), it must be a
+    trivially default-constructible, trivially copyable, and trivially destructible type that is convertible to and
+    from `#!cpp bool`. See
+    [Template Parameter Requirements](../../features/types/template_parameters.md#booleantype).
+
 ## Notes
 
 #### Default type

api/basic_json/boolean_t/index.md

@@ -10,6 +10,10 @@ The type used to store JSON booleans.
 
 To store boolean values in C++, a type is defined by the template parameter `BooleanType` which chooses the type to use.
 
+## Template parameters
+
+`BooleanType` : the type to store booleans. As it is stored directly inside a `basic_json` value (in a union), it must be a trivially default-constructible, trivially copyable, and trivially destructible type that is convertible to and from `bool`. See [Template Parameter Requirements](https://json.nlohmann.me/features/types/template_parameters/#booleantype).
+
 ## Notes
 
 #### Default type

api/basic_json/index.md

@@ -35,6 +35,8 @@ class basic_json;
 | `BinaryType`         | type for binary arrays                                                    | [`binary_t`](https://json.nlohmann.me/api/basic_json/binary_t/index.md)                   |
 | `CustomBaseClass`    | extension point for user code                                             | [`json_base_class_t`](https://json.nlohmann.me/api/basic_json/json_base_class_t/index.md) |
 
+The library imposes a number of requirements on these types that are not expressed as C++ concepts, such as the container operations `object_t` and `array_t` must provide, or the fact that `StringType` must be `char`-based. They are collected in [Template Parameter Requirements](https://json.nlohmann.me/features/types/template_parameters/index.md).
+
 ## Specializations
 
 - [**json**](https://json.nlohmann.me/api/json/index.md) - default specialization

api/basic_json/json_base_class_t.md

@@ -21,8 +21,11 @@ The default value for `CustomBaseClass` is `void`. In this case, an
 
 #### Limitations
 
-The type `CustomBaseClass` has to be a default-constructible class.
+The type `CustomBaseClass` has to be a default-constructible, non-`final` class.
 `basic_json` only supports copy/move construction/assignment if `CustomBaseClass` does so as well.
+A `CustomBaseClass` with non-static data members forfeits `basic_json`'s
+[standard layout](https://en.cppreference.com/w/cpp/named_req/StandardLayoutType) guarantee. See
+[Template Parameter Requirements](../../features/types/template_parameters.md#custombaseclass).
 
 ## Examples
 

api/basic_json/json_base_class_t/index.md

@@ -18,7 +18,7 @@ The default value for `CustomBaseClass` is `void`. In this case, an [empty base
 
 #### Limitations
 
-The type `CustomBaseClass` has to be a default-constructible class. `basic_json` only supports copy/move construction/assignment if `CustomBaseClass` does so as well.
+The type `CustomBaseClass` has to be a default-constructible, non-`final` class. `basic_json` only supports copy/move construction/assignment if `CustomBaseClass` does so as well. A `CustomBaseClass` with non-static data members forfeits `basic_json`'s [standard layout](https://en.cppreference.com/w/cpp/named_req/StandardLayoutType) guarantee. See [Template Parameter Requirements](https://json.nlohmann.me/features/types/template_parameters/#custombaseclass).
 
 ## Examples
 

api/basic_json/json_serializer.md

@@ -19,6 +19,12 @@ using json_serializer = JSONSerializer<T, SFINAE>;
 
 The default values for `json_serializer` is [`adl_serializer`](../adl_serializer/index.md).
 
+#### Requirements
+
+A custom serializer must provide `#!cpp static void to_json(basic_json&, T)` for every type it serializes, and either
+`#!cpp static void from_json(const basic_json&, T&)` or `#!cpp static T from_json(const basic_json&)` for every type it
+deserializes. See [Template Parameter Requirements](../../features/types/template_parameters.md#jsonserializer).
+
 ## Examples
 
 ??? example

api/basic_json/json_serializer/index.md

@@ -17,6 +17,10 @@ using json_serializer = JSONSerializer<T, SFINAE>;
 
 The default values for `json_serializer` is [`adl_serializer`](https://json.nlohmann.me/api/adl_serializer/index.md).
 
+#### Requirements
+
+A custom serializer must provide `static void to_json(basic_json&, T)` for every type it serializes, and either `static void from_json(const basic_json&, T&)` or `static T from_json(const basic_json&)` for every type it deserializes. See [Template Parameter Requirements](https://json.nlohmann.me/features/types/template_parameters/#jsonserializer).
+
 ## Examples
 
 Example

api/basic_json/number_float_t.md

@@ -20,6 +20,16 @@ used.
 To store floating-point numbers in C++, a type is defined by the template parameter `NumberFloatType` which chooses the
 type to use.
 
+## Template parameters
+
+`NumberFloatType`
+:   the type to store floating-point numbers. Parsing and serialization are implemented in terms of
+    `#!cpp std::strtof`/`#!cpp std::strtod`/`#!cpp std::strtold` and `#!cpp std::snprintf`, so the type must be
+    `#!cpp float`, `#!cpp double`, or `#!cpp long double`. The
+    [binary formats](../../features/binary_formats/index.md) additionally require `#!cpp float` or `#!cpp double`,
+    because they have no encoding for `#!cpp long double`. See
+    [Template Parameter Requirements](../../features/types/template_parameters.md#numberfloattype).
+
 ## Notes
 
 #### Default type

api/basic_json/number_float_t/index.md

@@ -14,6 +14,10 @@ This description includes both integer and floating-point numbers. However, C++
 
 To store floating-point numbers in C++, a type is defined by the template parameter `NumberFloatType` which chooses the type to use.
 
+## Template parameters
+
+`NumberFloatType` : the type to store floating-point numbers. Parsing and serialization are implemented in terms of `std::strtof`/`std::strtod`/`std::strtold` and `std::snprintf`, so the type must be `float`, `double`, or `long double`. The [binary formats](https://json.nlohmann.me/features/binary_formats/index.md) additionally require `float` or `double`, because they have no encoding for `long double`. See [Template Parameter Requirements](https://json.nlohmann.me/features/types/template_parameters/#numberfloattype).
+
 ## Notes
 
 #### Default type

api/basic_json/number_integer_t.md

@@ -20,6 +20,13 @@ used.
 To store integer numbers in C++, a type is defined by the template parameter `NumberIntegerType` which chooses the type
 to use.
 
+## Template parameters
+
+`NumberIntegerType`
+:   the type to store signed integers. It must be a **signed integral** type (`#!cpp std::is_integral`) with a
+    `#!cpp std::numeric_limits` specialization, and it is stored directly inside a `basic_json` value. See
+    [Template Parameter Requirements](../../features/types/template_parameters.md#numberintegertype-and-numberunsignedtype).
+
 ## Notes
 
 #### Default type

api/basic_json/number_integer_t/index.md

@@ -14,6 +14,10 @@ This description includes both integer and floating-point numbers. However, C++
 
 To store integer numbers in C++, a type is defined by the template parameter `NumberIntegerType` which chooses the type to use.
 
+## Template parameters
+
+`NumberIntegerType` : the type to store signed integers. It must be a **signed integral** type (`std::is_integral`) with a `std::numeric_limits` specialization, and it is stored directly inside a `basic_json` value. See [Template Parameter Requirements](https://json.nlohmann.me/features/types/template_parameters/#numberintegertype-and-numberunsignedtype).
+
 ## Notes
 
 #### Default type

api/basic_json/number_unsigned_t.md

@@ -20,6 +20,14 @@ used.
 To store unsigned integer numbers in C++, a type is defined by the template parameter `NumberUnsignedType` which chooses
 the type to use.
 
+## Template parameters
+
+`NumberUnsignedType`
+:   the type to store unsigned integers. It must be an **unsigned integral** type (`#!cpp std::is_integral`) with a
+    `#!cpp std::numeric_limits` specialization, and it must be able to represent the absolute value of every
+    [`number_integer_t`](number_integer_t.md) value. See
+    [Template Parameter Requirements](../../features/types/template_parameters.md#numberintegertype-and-numberunsignedtype).
+
 ## Notes
 
 #### Default type

api/basic_json/number_unsigned_t/index.md

@@ -14,6 +14,10 @@ This description includes both integer and floating-point numbers. However, C++
 
 To store unsigned integer numbers in C++, a type is defined by the template parameter `NumberUnsignedType` which chooses the type to use.
 
+## Template parameters
+
+`NumberUnsignedType` : the type to store unsigned integers. It must be an **unsigned integral** type (`std::is_integral`) with a `std::numeric_limits` specialization, and it must be able to represent the absolute value of every [`number_integer_t`](https://json.nlohmann.me/api/basic_json/number_integer_t/index.md) value. See [Template Parameter Requirements](https://json.nlohmann.me/features/types/template_parameters/#numberintegertype-and-numberunsignedtype).
+
 ## Notes
 
 #### Default type

api/basic_json/object_comparator_t.md

@@ -30,3 +30,5 @@ and [`default_object_comparator_t`](default_object_comparator_t.md) otherwise.
 - Added in version 3.0.0.
 - Changed to be conditionally defined as `#!cpp typename object_t::key_compare` or `default_object_comparator_t` in
   version 3.11.0.
+- Fixed the fallback to `default_object_comparator_t`, which previously failed to compile for object types without a
+  `key_compare` member type, in version 3.13.0.

api/basic_json/object_comparator_t/index.md

@@ -39,3 +39,4 @@ json::object_comparator_t("three", "four") = false
 
 - Added in version 3.0.0.
 - Changed to be conditionally defined as `typename object_t::key_compare` or `default_object_comparator_t` in version 3.11.0.
+- Fixed the fallback to `default_object_comparator_t`, which previously failed to compile for object types without a `key_compare` member type, in version 3.13.0.

api/basic_json/object_t.md

@@ -18,7 +18,11 @@ To store objects in C++, a type is defined by the template parameters described
 ## Template parameters
 
 `ObjectType`
-:   the container to store objects (e.g., `std::map` or `std::unordered_map`)
+:   the container to store objects. Its template parameters must have the same order and meaning as those of
+    `std::map`; in particular, the third parameter is a comparator. `#!cpp std::unordered_map`, whose third parameter
+    is a hash function, therefore needs an adapter -- see
+    [Template Parameter Requirements](../../features/types/template_parameters.md#objecttype) for the full list of
+    requirements, an adapter example, and the containers that are known to work.
 
 `StringType`
 :   the type of the keys or names (e.g., `std::string`). The comparison function `std::less<StringType>` is used to
@@ -122,3 +126,4 @@ the object is silently converted as an array of key-value pairs, which is incorr
 ## Version history
 
 - Added in version 1.0.0.
+- Allowed object types whose `erase(iterator)` returns `#!cpp void` in version 3.13.0.

api/basic_json/object_t/index.md

@@ -17,7 +17,7 @@ To store objects in C++, a type is defined by the template parameters described
 
 ## Template parameters
 
-`ObjectType` : the container to store objects (e.g., `std::map` or `std::unordered_map`)
+`ObjectType` : the container to store objects. Its template parameters must have the same order and meaning as those of `std::map`; in particular, the third parameter is a comparator. `std::unordered_map`, whose third parameter is a hash function, therefore needs an adapter -- see [Template Parameter Requirements](https://json.nlohmann.me/features/types/template_parameters/#objecttype) for the full list of requirements, an adapter example, and the containers that are known to work.
 
 `StringType` : the type of the keys or names (e.g., `std::string`). The comparison function `std::less<StringType>` is used to order elements inside the container.
 
@@ -106,3 +106,4 @@ true
 ## Version history
 
 - Added in version 1.0.0.
+- Allowed object types whose `erase(iterator)` returns `void` in version 3.13.0.