External/json
8
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

📝 add documentation

Browse Source
This commit is contained in:
Niels Lohmann 2021-09-11 14:59:21 +02:00
parent 5221115ff1
commit 7c55a91004
No known key found for this signature in database
GPG Key ID: 7F3CEA63AE251B69
10 changed files with 192 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
doc/examples/to_bon8.cpp Normal file
View File

@ -0,0 +1,21 @@
#include <iostream>
#include <iomanip>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create a JSON value
json j = R"({"compact": true, "schema": 0})"_json;
// serialize it to BON8
std::vector<uint8_t> v = json::to_bon8(j);
// print the vector content
for (auto& byte : v)
{
std::cout << "0x" << std::hex << std::setw(2) << std::setfill('0') << (int)byte << " ";
}
std::cout << std::endl;
}

1
doc/examples/to_bon8.output Normal file
View File

@ -0,0 +1 @@
0x88 0x63 0x6f 0x6d 0x70 0x61 0x63 0x74 0xf9 0x73 0x63 0x68 0x65 0x6d 0x61 0x90

1
doc/mkdocs/docs/api/basic_json/index.md
View File

@ -230,6 +230,7 @@ Access to the JSON value
- [**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_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

2
doc/mkdocs/docs/api/basic_json/input_format_t.md
View File

@ -25,7 +25,7 @@ ubjson
: UBJSON (Universal Binary JSON)
bson
: BSON (Bin­ary JSON)
: BSON (Binary JSON)
## Version history

57
doc/mkdocs/docs/api/basic_json/to_bon8.md Normal file
View File

@ -0,0 +1,57 @@
# basic_json::to_bon8
```cpp
// (1)
static std::vector<std::uint8_t> to_bon8(const basic_json& j);
// (2)
static void to_bon8(const basic_json& j, detail::output_adapter<std::uint8_t> o);
static void to_bon8(const basic_json& j, detail::output_adapter<char> o);
```
Serializes a given JSON value `j` to a byte vector using the BON8 serialization format. BON8 is a binary serialization
format which aims to be more compact than JSON itself, yet more efficient to parse.
1. Returns a byte vector containing the BON8 serialization.
2. Writes the BON8 serialization to an output adapter.
## Parameters
`j` (in)
: JSON value to serialize
`o` (in)
: output adapter to write serialization to
## Return value
1. BON8 serialization as byte vector
2. /
## Exception safety
Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
## Complexity
Linear in the size of the JSON value `j`.
## Example
??? example
The example shows the serialization of a JSON value to a byte vector in BON8 format.
```cpp
--8<-- "examples/to_bon8.cpp"
```
Output:
```json
--8<-- "examples/to_bon8.output"
```
## Version history
- Added in version 3.11.0.

2
doc/mkdocs/docs/features/binary_formats/bson.md
View File

@ -1,6 +1,6 @@
# BSON
BSON, short for Bin­ary JSON, is a bin­ary-en­coded seri­al­iz­a­tion of JSON-like doc­u­ments. Like JSON, BSON sup­ports the em­bed­ding of doc­u­ments and ar­rays with­in oth­er doc­u­ments and ar­rays. BSON also con­tains ex­ten­sions that al­low rep­res­ent­a­tion of data types that are not part of the JSON spec. For ex­ample, BSON has a Date type and a BinData type.
BSON, short for Binary JSON, is a binary-encoded serialization of JSON-like documents. Like JSON, BSON supports the embedding of documents and arrays within other documents and arrays. BSON also contains extensions that allow representation of data types that are not part of the JSON spec. For example, BSON has a Date type and a BinData type.
!!! abstract "References"

3
doc/mkdocs/docs/features/binary_formats/index.md
View File

@ -6,6 +6,7 @@ Though JSON is a ubiquitous data format, it is not a very compact format suitabl
- [CBOR](cbor.md) (Concise Binary Object Representation),
- [MessagePack](messagepack.md), and
- [UBJSON](ubjson.md) (Universal Binary JSON)
- BON8
to efficiently encode JSON values to byte vectors and to decode such vectors.
@ -19,6 +20,7 @@ to efficiently encode JSON values to byte vectors and to decode such vectors.
| CBOR | complete | incomplete, but all JSON types are supported |
| MessagePack | complete | complete |
| UBJSON | complete | complete |
| BON8 | complete | not yet implemented |
### Binary values
@ -28,6 +30,7 @@ to efficiently encode JSON values to byte vectors and to decode such vectors.
| CBOR | supported | supported |
| MessagePack | supported | supported |
| UBJSON | not supported | not supported |
| BON8 | not supported | not supported |
See [binary values](../binary_values.md) for more information.

1
doc/mkdocs/mkdocs.yml
View File

@ -168,6 +168,7 @@ nav:
- api/basic_json/sax_parse.md
- api/basic_json/size.md
- api/basic_json/string_t.md
- api/basic_json/to_bon8.md
- api/basic_json/to_bson.md
- api/basic_json/to_cbor.md
- api/basic_json/to_msgpack.md

53
include/nlohmann/json.hpp
View File

@ -7303,6 +7303,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
@sa see @ref to_msgpack(const basic_json&) for the related MessagePack format
@sa see @ref to_ubjson(const basic_json&, const bool, const bool) for the
related UBJSON format
@sa see @ref to_bson(const basic_json&) for the related BSON format
@sa see @ref to_bon8(const basic_json&) for the related BON8 format
@since version 2.0.9; compact representation of floating-point numbers
since version 3.8.0
@ -7399,6 +7401,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
@sa see @ref to_cbor(const basic_json& for the related CBOR format
@sa see @ref to_ubjson(const basic_json&, const bool, const bool) for the
related UBJSON format
@sa see @ref to_bon8(const basic_json&) for the related BON8 format
@since version 2.0.9
*/
@ -7502,6 +7505,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
analogous deserialization
@sa see @ref to_cbor(const basic_json& for the related CBOR format
@sa see @ref to_msgpack(const basic_json&) for the related MessagePack format
@sa see @ref to_bon8(const basic_json&) for the related BON8 format
@since version 3.1.0
*/
@ -7582,6 +7586,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
related UBJSON format
@sa see @ref to_cbor(const basic_json&) for the related CBOR format
@sa see @ref to_msgpack(const basic_json&) for the related MessagePack format
@sa see @ref to_bon8(const basic_json&) for the related BON8 format
*/
static std::vector<std::uint8_t> to_bson(const basic_json& j)
{
@ -7611,6 +7616,44 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
binary_writer<char>(o).write_bson(j);
}
/*!
@brief Serializes the given JSON object `j` to BON8 and returns a vector
containing the corresponding BON8-representation.
BON8 is a binary format that encodes JSON values using those byte sequences
that would form invalid UTF-8 strings. As a result, strings do not need to
be re-encoded.
@note The mapping is **complete** in the sense that any JSON value type
can be converted to a BON8 value.
@note The following values can **not** be converted to a BON8 value:
- integers larger than 9223372036854775807
@throw out_of_range.407 if `j.is_number_unsigned() && j.get<std::uint64_t>() > 9223372036854775807`
@note Any BON8 output created via @ref to_bon8 can be successfully parsed
by @ref from_bon8.
@param[in] j JSON value to serialize
@return BON8 serialization as byte vector
@complexity Linear in the size of the JSON value @a j.
@liveexample{The example shows the serialization of a JSON value to a byte
vector in BON8 format.,to_bon8}
@sa https://github.com/ttauri-project/ttauri/blob/main/docs/BON8.md
@sa see @ref from_bon8(detail::input_adapter&&, const bool strict) for the
analogous deserialization
@sa see @ref to_ubjson(const basic_json&, const bool, const bool) for the
related UBJSON format
@sa see @ref to_cbor(const basic_json&) for the related CBOR format
@sa see @ref to_msgpack(const basic_json&) for the related MessagePack format
@sa see @ref to_bson(const basic_json&) for the related BSON format
@since version 3.11.0
*/
static std::vector<std::uint8_t> to_bon8(const basic_json& j)
{
std::vector<std::uint8_t> result;
@ -7618,11 +7661,21 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
return result;
}
/*!
@brief Serializes the given JSON object `j` to BON8 and forwards the
corresponding BON8-representation to the given output_adapter `o`.
@param j The JSON object to convert to BON8.
@param o The output adapter that receives the binary BON8 representation.
@sa see @ref to_bon8(const basic_json&)
*/
static void to_bon8(const basic_json& j, detail::output_adapter<std::uint8_t> o)
{
binary_writer<std::uint8_t>(o).write_bon8(j);
}
/*!
@copydoc to_bon8(const basic_json&, detail::output_adapter<std::uint8_t>)
*/
static void to_bon8(const basic_json& j, detail::output_adapter<char> o)
{
binary_writer<char>(o).write_bon8(j);

53
single_include/nlohmann/json.hpp
View File

@ -25027,6 +25027,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
@sa see @ref to_msgpack(const basic_json&) for the related MessagePack format
@sa see @ref to_ubjson(const basic_json&, const bool, const bool) for the
related UBJSON format
@sa see @ref to_bson(const basic_json&) for the related BSON format
@sa see @ref to_bon8(const basic_json&) for the related BON8 format
@since version 2.0.9; compact representation of floating-point numbers
since version 3.8.0
@ -25123,6 +25125,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
@sa see @ref to_cbor(const basic_json& for the related CBOR format
@sa see @ref to_ubjson(const basic_json&, const bool, const bool) for the
related UBJSON format
@sa see @ref to_bon8(const basic_json&) for the related BON8 format
@since version 2.0.9
*/
@ -25226,6 +25229,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
analogous deserialization
@sa see @ref to_cbor(const basic_json& for the related CBOR format
@sa see @ref to_msgpack(const basic_json&) for the related MessagePack format
@sa see @ref to_bon8(const basic_json&) for the related BON8 format
@since version 3.1.0
*/
@ -25306,6 +25310,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
related UBJSON format
@sa see @ref to_cbor(const basic_json&) for the related CBOR format
@sa see @ref to_msgpack(const basic_json&) for the related MessagePack format
@sa see @ref to_bon8(const basic_json&) for the related BON8 format
*/
static std::vector<std::uint8_t> to_bson(const basic_json& j)
{
@ -25335,6 +25340,44 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
binary_writer<char>(o).write_bson(j);
}
/*!
@brief Serializes the given JSON object `j` to BON8 and returns a vector
containing the corresponding BON8-representation.
BON8 is a binary format that encodes JSON values using those byte sequences
that would form invalid UTF-8 strings. As a result, strings do not need to
be re-encoded.
@note The mapping is **complete** in the sense that any JSON value type
can be converted to a BON8 value.
@note The following values can **not** be converted to a BON8 value:
- integers larger than 9223372036854775807
@throw out_of_range.407 if `j.is_number_unsigned() && j.get<std::uint64_t>() > 9223372036854775807`
@note Any BON8 output created via @ref to_bon8 can be successfully parsed
by @ref from_bon8.
@param[in] j JSON value to serialize
@return BON8 serialization as byte vector
@complexity Linear in the size of the JSON value @a j.
@liveexample{The example shows the serialization of a JSON value to a byte
vector in BON8 format.,to_bon8}
@sa https://github.com/ttauri-project/ttauri/blob/main/docs/BON8.md
@sa see @ref from_bon8(detail::input_adapter&&, const bool strict) for the
analogous deserialization
@sa see @ref to_ubjson(const basic_json&, const bool, const bool) for the
related UBJSON format
@sa see @ref to_cbor(const basic_json&) for the related CBOR format
@sa see @ref to_msgpack(const basic_json&) for the related MessagePack format
@sa see @ref to_bson(const basic_json&) for the related BSON format
@since version 3.11.0
*/
static std::vector<std::uint8_t> to_bon8(const basic_json& j)
{
std::vector<std::uint8_t> result;
@ -25342,11 +25385,21 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
return result;
}
/*!
@brief Serializes the given JSON object `j` to BON8 and forwards the
corresponding BON8-representation to the given output_adapter `o`.
@param j The JSON object to convert to BON8.
@param o The output adapter that receives the binary BON8 representation.
@sa see @ref to_bon8(const basic_json&)
*/
static void to_bon8(const basic_json& j, detail::output_adapter<std::uint8_t> o)
{
binary_writer<std::uint8_t>(o).write_bon8(j);
}
/*!
@copydoc to_bon8(const basic_json&, detail::output_adapter<std::uint8_t>)
*/
static void to_bon8(const basic_json& j, detail::output_adapter<char> o)
{
binary_writer<char>(o).write_bon8(j);