deploy: 56ddcb65f0

2026-09-28 02:30:32 +00:00 · 2026-09-27 21:37:45 +00:00
parent 0cd46537bb
commit be6bcd470b
322 changed files with 1586 additions and 534 deletions
@@ -290,11 +290,13 @@ Access to the JSON value
 ### Binary formats

 - [**from_bjdata**](from_bjdata.md) (_static_) - create a JSON value from an input in BJData format
+- [**from_bon8**](from_bon8.md) (_static_) - create a JSON value from an input in BON8 format
 - [**from_bson**](from_bson.md) (_static_) - create a JSON value from an input in BSON format
 - [**from_cbor**](from_cbor.md) (_static_) - create a JSON value from an input in CBOR format
 - [**from_msgpack**](from_msgpack.md) (_static_) - create a JSON value from an input in MessagePack format
 - [**from_ubjson**](from_ubjson.md) (_static_) - create a JSON value from an input in UBJSON format
 - [**to_bjdata**](to_bjdata.md) (_static_) - create a BJData serialization of a given JSON value
+- [**to_bon8**](to_bon8.md) (_static_) - create a BON8 serialization of a given JSON value
 - [**to_bson**](to_bson.md) (_static_) - create a BSON serialization of a given JSON value
 - [**to_cbor**](to_cbor.md) (_static_) - create a CBOR serialization of a given JSON value
 - [**to_msgpack**](to_msgpack.md) (_static_) - create a MessagePack serialization of a given JSON value
@@ -18,7 +18,8 @@ ignore
 :   ignore tags

 store
-:   store tagged values as binary container with subtype (for bytes 0xd8..0xdb)
+:   store tagged byte strings (for bytes 0xd8..0xdb) as binary values with the tag as subtype; other tagged values are
+    read as if the tag were ignored. If several tags precede a byte string, only the innermost one is stored.

 ## Examples

@@ -15,7 +15,7 @@ error : throw a `parse_error` exception in case of a tag

 ignore : ignore tags

-store : store tagged values as binary container with subtype (for bytes 0xd8..0xdb)
+store : store tagged byte strings (for bytes 0xd8..0xdb) as binary values with the tag as subtype; other tagged values are read as if the tag were ignored. If several tags precede a byte string, only the innermost one is stored.

 ## Examples

@@ -104,6 +104,7 @@ Linear in the size of the input.
 - [from_msgpack](from_msgpack.md) create a JSON value from an input in MessagePack format
 - [from_bson](from_bson.md) create a JSON value from an input in BSON format
 - [from_ubjson](from_ubjson.md) create a JSON value from an input in UBJSON format
+- [from_bon8](from_bon8.md) create a JSON value from an input in BON8 format

 ## Version history

@@ -118,6 +118,7 @@ Output:
 - [from_msgpack](https://json.nlohmann.me/api/basic_json/from_msgpack/index.md) create a JSON value from an input in MessagePack format
 - [from_bson](https://json.nlohmann.me/api/basic_json/from_bson/index.md) create a JSON value from an input in BSON format
 - [from_ubjson](https://json.nlohmann.me/api/basic_json/from_ubjson/index.md) create a JSON value from an input in UBJSON format
+- [from_bon8](https://json.nlohmann.me/api/basic_json/from_bon8/index.md) create a JSON value from an input in BON8 format

 ## Version history

@@ -0,0 +1,108 @@
+# <small>nlohmann::basic_json::</small>from_bon8
+
+```cpp
+// (1)
+template<typename InputType>
+static basic_json from_bon8(InputType&& i,
+                            const bool strict = true,
+                            const bool allow_exceptions = true);
+// (2)
+template<typename IteratorType, typename SentinelType = IteratorType>
+static basic_json from_bon8(IteratorType first, SentinelType last,
+                            const bool strict = true,
+                            const bool allow_exceptions = true);
+```
+
+Deserializes a given input to a JSON value using the BON8 (Binary Object Notation 8) serialization format.
+
+1. Reads from a compatible input.
+2. Reads from an iterator range, or an iterator and a sentinel of a different type (C++20 ranges support).
+
+The exact mapping and its limitations are described on a [dedicated page](../../features/binary_formats/bon8.md).
+
+## Template parameters
+
+`InputType`
+:   A compatible input, for instance:
+
+    - an `std::istream` object
+    - a `FILE` pointer
+    - a C-style array of characters
+    - a pointer to a null-terminated string of single byte characters
+    - a container `obj` for which `begin(obj)` and `end(obj)` produce a valid pair of iterators
+      (as found via ADL or member functions, with semantics compatible to `std::begin` and `std::end`)
+
+`IteratorType`
+:   a compatible iterator type
+
+`SentinelType`
+:   defaults to `IteratorType`; may be a different type comparable to `IteratorType` via `operator!=`, for instance.
+
+    - a custom sentinel type for C++20 ranges
+    - `std::default_sentinel_t`, when `IteratorType` is `std::counted_iterator`
+
+## Parameters
+
+`i` (in)
+:   an input in BON8 format convertible to an input adapter
+
+`first` (in)
+:   iterator to the start of the input
+
+`last` (in)
+:   iterator to the end of the input, or a sentinel value that compares equal to the end iterator with `operator!=`
+
+`strict` (in)
+:   whether to expect the input to be consumed until EOF (`#!cpp true` by default)
+
+`allow_exceptions` (in)
+:   whether to throw exceptions in case of a parse error (optional, `#!cpp true` by default)
+
+## Return value
+
+deserialized JSON value; in case of a parse error and `allow_exceptions` set to `#!cpp false`, the return value will be
+`value_t::discarded`. The latter can be checked with [`is_discarded`](is_discarded.md).
+
+## Exception safety
+
+Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
+
+## Exceptions
+
+- Throws [parse_error.110](../../home/exceptions.md#jsonexceptionparse_error110) if the given input ends prematurely or
+  the end of the file was not reached when `strict` was set to true
+- Throws [parse_error.112](../../home/exceptions.md#jsonexceptionparse_error112) if a parse error occurs, for instance
+  an invalid byte, a string that is not valid UTF-8, or an object key that is not a string
+
+## Complexity
+
+Linear in the size of the input.
+
+## Examples
+
+??? example
+
+    The example shows the deserialization of a byte vector in BON8 format to a JSON value.
+     
+    ```cpp
+    --8<-- "examples/from_bon8.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/from_bon8.output"
+    ```
+
+## See also
+
+- [to_bon8](to_bon8.md) create a BON8 serialization of a JSON value
+- [from_cbor](from_cbor.md) create a JSON value from an input in CBOR format
+- [from_msgpack](from_msgpack.md) create a JSON value from an input in MessagePack format
+- [from_bson](from_bson.md) create a JSON value from an input in BSON format
+- [from_ubjson](from_ubjson.md) create a JSON value from an input in UBJSON format
+- [from_bjdata](from_bjdata.md) create a JSON value from an input in BJData format
+
+## Version history
+
+- Added in version 3.13.0.
@@ -0,0 +1,125 @@
+# nlohmann::basic_json::from_bon8
+
+```
+// (1)
+template<typename InputType>
+static basic_json from_bon8(InputType&& i,
+                            const bool strict = true,
+                            const bool allow_exceptions = true);
+// (2)
+template<typename IteratorType, typename SentinelType = IteratorType>
+static basic_json from_bon8(IteratorType first, SentinelType last,
+                            const bool strict = true,
+                            const bool allow_exceptions = true);
+```
+
+Deserializes a given input to a JSON value using the BON8 (Binary Object Notation 8) serialization format.
+
+1. Reads from a compatible input.
+1. Reads from an iterator range, or an iterator and a sentinel of a different type (C++20 ranges support).
+
+The exact mapping and its limitations are described on a [dedicated page](https://json.nlohmann.me/features/binary_formats/bon8/index.md).
+
+## Template parameters
+
+`InputType` : A compatible input, for instance:
+
+```
+- an `std::istream` object
+- a `FILE` pointer
+- a C-style array of characters
+- a pointer to a null-terminated string of single byte characters
+- a container `obj` for which `begin(obj)` and `end(obj)` produce a valid pair of iterators
+  (as found via ADL or member functions, with semantics compatible to `std::begin` and `std::end`)
+```
+
+`IteratorType` : a compatible iterator type
+
+`SentinelType` : defaults to `IteratorType`; may be a different type comparable to `IteratorType` via `operator!=`, for instance.
+
+```
+- a custom sentinel type for C++20 ranges
+- `std::default_sentinel_t`, when `IteratorType` is `std::counted_iterator`
+```
+
+## Parameters
+
+`i` (in) : an input in BON8 format convertible to an input adapter
+
+`first` (in) : iterator to the start of the input
+
+`last` (in) : iterator to the end of the input, or a sentinel value that compares equal to the end iterator with `operator!=`
+
+`strict` (in) : whether to expect the input to be consumed until EOF (`true` by default)
+
+`allow_exceptions` (in) : whether to throw exceptions in case of a parse error (optional, `true` by default)
+
+## Return value
+
+deserialized JSON value; in case of a parse error and `allow_exceptions` set to `false`, the return value will be `value_t::discarded`. The latter can be checked with [`is_discarded`](https://json.nlohmann.me/api/basic_json/is_discarded/index.md).
+
+## Exception safety
+
+Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
+
+## Exceptions
+
+- Throws [parse_error.110](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error110) if the given input ends prematurely or the end of the file was not reached when `strict` was set to true
+- Throws [parse_error.112](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error112) if a parse error occurs, for instance an invalid byte, a string that is not valid UTF-8, or an object key that is not a string
+
+## Complexity
+
+Linear in the size of the input.
+
+## Examples
+
+Example
+
+The example shows the deserialization of a byte vector in BON8 format to a JSON value.
+
+```
+#include <iostream>
+#include <iomanip>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    // create byte vector
+    std::vector<std::uint8_t> v = {0x89, 0x63, 0x6f, 0x6d, 0x70, 0x61, 0x63, 0x74,
+                                   0xf9, 0x66, 0x6f, 0x72, 0x6d, 0x61, 0x74, 0xff,
+                                   0x42, 0x4f, 0x4e, 0x38, 0xff, 0x73, 0x63, 0x68,
+                                   0x65, 0x6d, 0x61, 0x90
+                                  };
+
+    // deserialize it with BON8
+    json j = json::from_bon8(v);
+
+    // print the deserialized JSON value
+    std::cout << std::setw(2) << j << std::endl;
+}
+```
+
+Output:
+
+```
+{
+  "compact": true,
+  "format": "BON8",
+  "schema": 0
+}
+```
+
+## See also
+
+- [to_bon8](https://json.nlohmann.me/api/basic_json/to_bon8/index.md) create a BON8 serialization of a JSON value
+- [from_cbor](https://json.nlohmann.me/api/basic_json/from_cbor/index.md) create a JSON value from an input in CBOR format
+- [from_msgpack](https://json.nlohmann.me/api/basic_json/from_msgpack/index.md) create a JSON value from an input in MessagePack format
+- [from_bson](https://json.nlohmann.me/api/basic_json/from_bson/index.md) create a JSON value from an input in BSON format
+- [from_ubjson](https://json.nlohmann.me/api/basic_json/from_ubjson/index.md) create a JSON value from an input in UBJSON format
+- [from_bjdata](https://json.nlohmann.me/api/basic_json/from_bjdata/index.md) create a JSON value from an input in BJData format
+
+## Version history
+
+- Added in version 3.13.0.
@@ -104,6 +104,7 @@ Linear in the size of the input.
 - [from_msgpack](from_msgpack.md) for the related MessagePack format
 - [from_ubjson](from_ubjson.md) for the related UBJSON format
 - [from_bjdata](from_bjdata.md) for the related BJData format
+- [from_bon8](from_bon8.md) for the related BON8 format

 ## Version history

@@ -119,6 +119,7 @@ Output:
 - [from_msgpack](https://json.nlohmann.me/api/basic_json/from_msgpack/index.md) for the related MessagePack format
 - [from_ubjson](https://json.nlohmann.me/api/basic_json/from_ubjson/index.md) for the related UBJSON format
 - [from_bjdata](https://json.nlohmann.me/api/basic_json/from_bjdata/index.md) for the related BJData format
+- [from_bon8](https://json.nlohmann.me/api/basic_json/from_bon8/index.md) for the related BON8 format

 ## Version history

@@ -110,6 +110,7 @@ Linear in the size of the input.
 - [from_bson](from_bson.md) create a JSON value from an input in BSON format
 - [from_ubjson](from_ubjson.md) create a JSON value from an input in UBJSON format
 - [from_bjdata](from_bjdata.md) create a JSON value from an input in BJData format
+- [from_bon8](from_bon8.md) create a JSON value from an input in BON8 format

 ## Version history

@@ -122,6 +122,7 @@ Output:
 - [from_bson](https://json.nlohmann.me/api/basic_json/from_bson/index.md) create a JSON value from an input in BSON format
 - [from_ubjson](https://json.nlohmann.me/api/basic_json/from_ubjson/index.md) create a JSON value from an input in UBJSON format
 - [from_bjdata](https://json.nlohmann.me/api/basic_json/from_bjdata/index.md) create a JSON value from an input in BJData format
+- [from_bon8](https://json.nlohmann.me/api/basic_json/from_bon8/index.md) create a JSON value from an input in BON8 format

 ## Version history

@@ -103,6 +103,7 @@ Linear in the size of the input.
 - [from_bson](from_bson.md) create a JSON value from an input in BSON format
 - [from_ubjson](from_ubjson.md) create a JSON value from an input in UBJSON format
 - [from_bjdata](from_bjdata.md) create a JSON value from an input in BJData format
+- [from_bon8](from_bon8.md) create a JSON value from an input in BON8 format

 ## Version history

@@ -117,6 +117,7 @@ Output:
 - [from_bson](https://json.nlohmann.me/api/basic_json/from_bson/index.md) create a JSON value from an input in BSON format
 - [from_ubjson](https://json.nlohmann.me/api/basic_json/from_ubjson/index.md) create a JSON value from an input in UBJSON format
 - [from_bjdata](https://json.nlohmann.me/api/basic_json/from_bjdata/index.md) create a JSON value from an input in BJData format
+- [from_bon8](https://json.nlohmann.me/api/basic_json/from_bon8/index.md) create a JSON value from an input in BON8 format

 ## Version history

@@ -104,6 +104,7 @@ Linear in the size of the input.
 - [from_msgpack](from_msgpack.md) create a JSON value from an input in MessagePack format
 - [from_bson](from_bson.md) create a JSON value from an input in BSON format
 - [from_bjdata](from_bjdata.md) create a JSON value from an input in BJData format
+- [from_bon8](from_bon8.md) create a JSON value from an input in BON8 format

 ## Version history

@@ -118,6 +118,7 @@ Output:
 - [from_msgpack](https://json.nlohmann.me/api/basic_json/from_msgpack/index.md) create a JSON value from an input in MessagePack format
 - [from_bson](https://json.nlohmann.me/api/basic_json/from_bson/index.md) create a JSON value from an input in BSON format
 - [from_bjdata](https://json.nlohmann.me/api/basic_json/from_bjdata/index.md) create a JSON value from an input in BJData format
+- [from_bon8](https://json.nlohmann.me/api/basic_json/from_bon8/index.md) create a JSON value from an input in BON8 format

 ## Version history

@@ -269,11 +269,13 @@ Access to the JSON value
 ### Binary formats

 - [**from_bjdata**](https://json.nlohmann.me/api/basic_json/from_bjdata/index.md) (*static*) - create a JSON value from an input in BJData format
+- [**from_bon8**](https://json.nlohmann.me/api/basic_json/from_bon8/index.md) (*static*) - create a JSON value from an input in BON8 format
 - [**from_bson**](https://json.nlohmann.me/api/basic_json/from_bson/index.md) (*static*) - create a JSON value from an input in BSON format
 - [**from_cbor**](https://json.nlohmann.me/api/basic_json/from_cbor/index.md) (*static*) - create a JSON value from an input in CBOR format
 - [**from_msgpack**](https://json.nlohmann.me/api/basic_json/from_msgpack/index.md) (*static*) - create a JSON value from an input in MessagePack format
 - [**from_ubjson**](https://json.nlohmann.me/api/basic_json/from_ubjson/index.md) (*static*) - create a JSON value from an input in UBJSON format
 - [**to_bjdata**](https://json.nlohmann.me/api/basic_json/to_bjdata/index.md) (*static*) - create a BJData serialization of a given JSON value
+- [**to_bon8**](https://json.nlohmann.me/api/basic_json/to_bon8/index.md) (*static*) - create a BON8 serialization of a given JSON value
 - [**to_bson**](https://json.nlohmann.me/api/basic_json/to_bson/index.md) (*static*) - create a BSON serialization of a given JSON value
 - [**to_cbor**](https://json.nlohmann.me/api/basic_json/to_cbor/index.md) (*static*) - create a CBOR serialization of a given JSON value
 - [**to_msgpack**](https://json.nlohmann.me/api/basic_json/to_msgpack/index.md) (*static*) - create a MessagePack serialization of a given JSON value
@@ -7,7 +7,8 @@ enum class input_format_t {
    msgpack,
    ubjson,
    bson,
-    bjdata
+    bjdata,
+    bon8
 };
 ```

@@ -31,6 +32,9 @@ bson
 bjdata
 :   BJData (Binary JData)

+bon8
+:   BON8 (Binary Object Notation 8)
+
 ## Examples

 ??? example
@@ -7,7 +7,8 @@ enum class input_format_t {
    msgpack,
    ubjson,
    bson,
-    bjdata
+    bjdata,
+    bon8
 };
 ```

@@ -25,6 +26,8 @@ bson : BSON (Binary JSON)

 bjdata : BJData (Binary JData)

+bon8 : BON8 (Binary Object Notation 8)
+
 ## Examples

 Example
--- a/Show More
+++ b/Show More