Scarfski/json
1
0
Fork 0
mirror of https://github.com/nlohmann/json.git synced 2026-10-28 19:45:22 +00:00
Code Issues Packages Projects Releases Wiki Activity

deploy: 94fe31eb9b

Browse Source
This commit is contained in:
nlohmann
2026-10-26 21:24:35 +00:00
parent 41c601a7d1
commit d2e264bd84
1400 changed files with 11859 additions and 5440 deletions
Download Patch File Download Diff File Expand all files Collapse all files
api/adl_serializer/from_json.md
+4 -4
View File
@@ -44,7 +44,7 @@ class (either explicitly or via the conversion operators).
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
namespace ns
{
@@ -76,7 +76,7 @@ class (either explicitly or via the conversion operators).
auto p = j.get<ns::person>();
std::cout << p.name << " (" << p.age << ") lives in " << p.address << std::endl;
std::cout << p.name << " (" << p.age << ") lives in " << p.address << '\n';
}
```
@@ -97,7 +97,7 @@ class (either explicitly or via the conversion operators).
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
namespace ns
{
@@ -145,7 +145,7 @@ class (either explicitly or via the conversion operators).
auto p = j.get<ns::person>();
std::cout << p.name << " (" << p.age << ") lives in " << p.address << std::endl;
std::cout << p.name << " (" << p.age << ") lives in " << p.address << '\n';
}
```
api/adl_serializer/from_json/index.html
+5 -5
View File
File diff suppressed because one or more lines are too long
api/adl_serializer/from_json/index.md
+4 -4
View File
@@ -40,7 +40,7 @@ The example below shows how a `from_json` function can be implemented for a user
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
namespace ns
{
@@ -72,7 +72,7 @@ int main()
auto p = j.get<ns::person>();
std::cout << p.name << " (" << p.age << ") lives in " << p.address << std::endl;
std::cout << p.name << " (" << p.age << ") lives in " << p.address << '\n';
}
```
@@ -90,7 +90,7 @@ The example below shows how a `from_json` is implemented as part of a specializa
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
namespace ns
{
@@ -138,7 +138,7 @@ int main()
auto p = j.get<ns::person>();
std::cout << p.name << " (" << p.age << ") lives in " << p.address << std::endl;
std::cout << p.name << " (" << p.age << ") lives in " << p.address << '\n';
}
```
api/adl_serializer/index.html
+1 -1
View File
File diff suppressed because one or more lines are too long
api/adl_serializer/to_json.md
+2 -2
View File
@@ -28,7 +28,7 @@ This function is usually called by the constructors of the [basic_json](../basic
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
namespace ns
{
@@ -55,7 +55,7 @@ This function is usually called by the constructors of the [basic_json](../basic
json j = p;
std::cout << j << std::endl;
std::cout << j << '\n';
}
```
api/adl_serializer/to_json/index.html
+3 -3
View File
File diff suppressed because one or more lines are too long
api/adl_serializer/to_json/index.md
+2 -2
View File
@@ -25,7 +25,7 @@ The example below shows how a `to_json` function can be implemented for a user-d
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
namespace ns
{
@@ -52,7 +52,7 @@ int main()
json j = p;
std::cout << j << std::endl;
std::cout << j << '\n';
}
```
api/basic_json.md
+2 -1
View File
@@ -121,6 +121,7 @@ The class satisfies the following concept requirements:
- [**json_pointer**](../json_pointer/index.md) - JSON Pointer implementation
- [**json_serializer**](json_serializer.md) - type of the serializer to for conversions from/to JSON
- [**error_handler_t**](error_handler_t.md) - type to choose behavior on decoding errors
- [**bjdata_version_t**](bjdata_version_t.md) - type to choose the BJData version to write
- [**cbor_tag_handler_t**](cbor_tag_handler_t.md) - type to choose how to handle CBOR tags
- **initializer_list_t** - type for initializer lists of `basic_json` values
- [**input_format_t**](input_format_t.md) - type to choose the format to parse
@@ -351,7 +352,7 @@ Access to the JSON value
#include <iomanip>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
api/basic_json/accept.md
+5 -5
View File
@@ -111,19 +111,19 @@ outside of a string, invalid) byte; see the [FAQ entry](../../home/faq.md#nul-by
#include <iomanip>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
// a valid JSON text
auto valid_text = R"(
const auto* valid_text = R"(
{
"numbers": [1, 2, 3]
}
)";
// an invalid JSON text
auto invalid_text = R"(
const auto* invalid_text = R"(
{
"strings": ["extra", "comma", ]
}
@@ -153,7 +153,7 @@ outside of a string, invalid) byte; see the [FAQ entry](../../home/faq.md#nul-by
#include <vector>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -184,7 +184,7 @@ outside of a string, invalid) byte; see the [FAQ entry](../../home/faq.md#nul-by
#include <string>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
api/basic_json/accept/index.html
+8 -8
View File
File diff suppressed because one or more lines are too long
api/basic_json/accept/index.md
+5 -5
View File
@@ -102,19 +102,19 @@ The example below demonstrates the `accept()` function reading from a string.
#include <iomanip>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
// a valid JSON text
auto valid_text = R"(
const auto* valid_text = R"(
{
"numbers": [1, 2, 3]
}
)";
// an invalid JSON text
auto invalid_text = R"(
const auto* invalid_text = R"(
{
"strings": ["extra", "comma", ]
}
@@ -141,7 +141,7 @@ The example below demonstrates the `accept()` function reading from an iterator
#include <vector>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -169,7 +169,7 @@ The encoding is deduced from the character type of the input. String literals li
#include <string>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
api/basic_json/array.md
+1 -1
View File
@@ -44,7 +44,7 @@ This function is only needed to express two edge cases that cannot be realized w
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
api/basic_json/array/index.html
+2 -2
View File
File diff suppressed because one or more lines are too long
api/basic_json/array/index.md
+1 -1
View File
@@ -39,7 +39,7 @@ The following code shows an example for the `array` function.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
api/basic_json/array_t.md
+2 -2
View File
@@ -62,11 +62,11 @@ Arrays are stored as pointers in a `basic_json` type. That is, for any access to
#include <iomanip>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
std::cout << std::boolalpha << std::is_same<std::vector<json>, json::array_t>::value << std::endl;
std::cout << std::boolalpha << std::is_same<std::vector<json>, json::array_t>::value << '\n';
}
```
api/basic_json/array_t/index.html
+3 -3
View File
File diff suppressed because one or more lines are too long
api/basic_json/array_t/index.md
+2 -2
View File
@@ -54,11 +54,11 @@ The following code shows that `array_t` is by default, a typedef to `std::vector
#include <iomanip>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
std::cout << std::boolalpha << std::is_same<std::vector<json>, json::array_t>::value << std::endl;
std::cout << std::boolalpha << std::is_same<std::vector<json>, json::array_t>::value << '\n';
}
```
api/basic_json/as_base_class/index.html
+1 -1
View File
File diff suppressed because one or more lines are too long
api/basic_json/at.md
+8 -8
View File
@@ -117,7 +117,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -178,7 +178,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -232,7 +232,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -298,7 +298,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -359,7 +359,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
#include <nlohmann/json.hpp>
using namespace std::string_view_literals;
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -427,7 +427,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
#include <nlohmann/json.hpp>
using namespace std::string_view_literals;
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -486,7 +486,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
using namespace nlohmann::literals;
int main()
@@ -616,7 +616,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
using namespace nlohmann::literals;
int main()
api/basic_json/at/index.html
+9 -9
View File
File diff suppressed because one or more lines are too long
api/basic_json/at/index.md
+8 -8
View File
@@ -93,7 +93,7 @@ The example below shows how array elements can be read and written using `at()`.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -151,7 +151,7 @@ The example below shows how array elements can be read using `at()`. It also dem
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -202,7 +202,7 @@ The example below shows how object elements can be read and written using `at()`
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -265,7 +265,7 @@ The example below shows how object elements can be read using `at()`. It also de
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -323,7 +323,7 @@ The example below shows how object elements can be read and written using `at()`
#include <nlohmann/json.hpp>
using namespace std::string_view_literals;
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -388,7 +388,7 @@ The example below shows how object elements can be read using `at()`. It also de
#include <nlohmann/json.hpp>
using namespace std::string_view_literals;
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -444,7 +444,7 @@ The example below shows how object elements can be read and written using `at()`
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
using namespace nlohmann::literals;
int main()
@@ -571,7 +571,7 @@ The example below shows how object elements can be read using `at()`. It also de
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
using namespace nlohmann::literals;
int main()
api/basic_json/back.md
+1 -1
View File
@@ -49,7 +49,7 @@ Constant.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
api/basic_json/back/index.html
+2 -2
View File
File diff suppressed because one or more lines are too long
api/basic_json/back/index.md
+1 -1
View File
@@ -46,7 +46,7 @@ The following code shows an example for `back()`.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
api/basic_json/basic_json.md
+10 -10
View File
@@ -349,7 +349,7 @@ basic_json(basic_json&& other) noexcept;
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -395,7 +395,7 @@ basic_json(basic_json&& other) noexcept;
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -434,7 +434,7 @@ basic_json(basic_json&& other) noexcept;
#include <valarray>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -698,8 +698,8 @@ basic_json(basic_json&& other) noexcept;
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using ordered_json = nlohmann::ordered_json;
using nlohmann::json;
using nlohmann::ordered_json;
int main()
{
@@ -737,7 +737,7 @@ basic_json(basic_json&& other) noexcept;
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -777,7 +777,7 @@ basic_json(basic_json&& other) noexcept;
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -812,7 +812,7 @@ basic_json(basic_json&& other) noexcept;
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -862,7 +862,7 @@ basic_json(basic_json&& other) noexcept;
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -895,7 +895,7 @@ basic_json(basic_json&& other) noexcept;
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
api/basic_json/basic_json/index.html
+11 -11
View File
File diff suppressed because one or more lines are too long
api/basic_json/basic_json/index.md
+10 -10
View File
@@ -271,7 +271,7 @@ The following code shows the constructor for different `value_t` values.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -315,7 +315,7 @@ The following code shows the constructor with and without a null pointer paramet
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -352,7 +352,7 @@ The following code shows the constructor with several compatible types.
#include <valarray>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -612,8 +612,8 @@ The example below shows how a `json` value is converted to an `ordered_json` val
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using ordered_json = nlohmann::ordered_json;
using nlohmann::json;
using nlohmann::ordered_json;
int main()
{
@@ -649,7 +649,7 @@ The example below shows how JSON values are created from initializer lists.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -687,7 +687,7 @@ The following code shows examples for creating arrays with several copies of a g
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -720,7 +720,7 @@ The example below shows several ways to create JSON values by specifying a subra
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -768,7 +768,7 @@ The following code shows an example for the copy constructor.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -799,7 +799,7 @@ The code below shows the move constructor explicitly called via `std::move`.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
api/basic_json/begin.md
+1 -1
View File
@@ -31,7 +31,7 @@ Constant.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
api/basic_json/begin/index.html
+2 -2
View File
File diff suppressed because one or more lines are too long
api/basic_json/begin/index.md
+1 -1
View File
@@ -29,7 +29,7 @@ The following code shows an example for `begin()`.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
api/basic_json/binary.md
+2 -2
View File
@@ -55,7 +55,7 @@ initialization of a binary array type, for backwards compatibility and so it doe
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -66,7 +66,7 @@ initialization of a binary array type, for backwards compatibility and so it doe
json j = json::binary(vec, 42);
// output type and subtype
std::cout << "type: " << j.type_name() << ", subtype: " << j.get_binary().subtype() << std::endl;
std::cout << "type: " << j.type_name() << ", subtype: " << j.get_binary().subtype() << '\n';
}
```
api/basic_json/binary/index.html
+3 -3
View File
File diff suppressed because one or more lines are too long
api/basic_json/binary/index.md
+2 -2
View File
@@ -49,7 +49,7 @@ The following code shows how to create a binary value.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -60,7 +60,7 @@ int main()
json j = json::binary(vec, 42);
// output type and subtype
std::cout << "type: " << j.type_name() << ", subtype: " << j.get_binary().subtype() << std::endl;
std::cout << "type: " << j.type_name() << ", subtype: " << j.get_binary().subtype() << '\n';
}
```
api/basic_json/binary_t.md
+5 -4
View File
@@ -90,8 +90,9 @@ type `#!cpp binary_t*` must be dereferenced.
- MessagePack
- If a subtype is given and the binary array contains exactly 1, 2, 4, 8, or 16 elements, the fixext family (fixext1,
fixext2, fixext4, fixext8) is used. For other sizes, the ext family (ext8, ext16, ext32) is used. The subtype is
then added as a signed 8-bit integer.
fixext2, fixext4, fixext8, fixext16) is used. For other sizes, the ext family (ext8, ext16, ext32) is used. The
subtype is then written as the signed 8-bit ext type: subtypes 128 to 255 map to the negative (reserved) ext
types, and on reading the ext type is exposed as an unsigned subtype from 0 to 255.
- If no subtype is given, the bin family (bin8, bin16, bin32) is used.
- BSON
@@ -110,11 +111,11 @@ type `#!cpp binary_t*` must be dereferenced.
#include <iomanip>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
std::cout << std::boolalpha << std::is_same<nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>, json::binary_t>::value << std::endl;
std::cout << std::boolalpha << std::is_same<nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>, json::binary_t>::value << '\n';
}
```
api/basic_json/binary_t/index.html
+5 -5
View File
File diff suppressed because one or more lines are too long
api/basic_json/binary_t/index.md
+3 -3
View File
@@ -80,7 +80,7 @@ Binary Arrays are stored as pointers in a `basic_json` type. That is, for any ac
- MessagePack
- If a subtype is given and the binary array contains exactly 1, 2, 4, 8, or 16 elements, the fixext family (fixext1, fixext2, fixext4, fixext8) is used. For other sizes, the ext family (ext8, ext16, ext32) is used. The subtype is then added as a signed 8-bit integer.
- If a subtype is given and the binary array contains exactly 1, 2, 4, 8, or 16 elements, the fixext family (fixext1, fixext2, fixext4, fixext8, fixext16) is used. For other sizes, the ext family (ext8, ext16, ext32) is used. The subtype is then written as the signed 8-bit ext type: subtypes 128 to 255 map to the negative (reserved) ext types, and on reading the ext type is exposed as an unsigned subtype from 0 to 255.
- If no subtype is given, the bin family (bin8, bin16, bin32) is used.
- BSON
@@ -99,11 +99,11 @@ The following code shows that `binary_t` is by default, a typedef to `nlohmann::
#include <iomanip>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
std::cout << std::boolalpha << std::is_same<nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>, json::binary_t>::value << std::endl;
std::cout << std::boolalpha << std::is_same<nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>, json::binary_t>::value << '\n';
}
```
api/basic_json/bjdata_version_t.md
+85
View File
@@ -0,0 +1,85 @@
# <small>nlohmann::basic_json::</small>bjdata_version_t
```cpp
enum class bjdata_version_t
{
draft2,
draft3
};
```
This enumeration is used in [`to_bjdata`](to_bjdata.md) to choose the version of the BJData specification to write:
draft2
: BJData Draft 2 (the default). Binary values are written as arrays of `U` integers, and ND-arrays with
`"_ArrayType_": "byte"` are written as regular objects, since the `B` marker is not part of Draft 2.
draft3
: BJData Draft 3. Binary values are written as `B` elements: as an optimized binary array (`[$B#`) if both `use_size`
and `use_type` are set, and as an array of `B`-prefixed elements otherwise. ND-arrays with
`"_ArrayType_": "byte"` are written as packed arrays (`[$B#[...]`).
Only the writer is affected by the version. [`from_bjdata`](from_bjdata.md) reads the markers of both drafts.
## Examples
??? example
The example below shows how the different values of the `bjdata_version_t` influence the serialization of a binary
value with [`to_bjdata`](to_bjdata.md).
```cpp
#include <iomanip>
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
void print_hex(const char* label, const std::vector<std::uint8_t>& v)
{
std::cout << label << ':';
for (auto b : v)
{
std::cout << ' ' << std::hex << std::setw(2) << std::setfill('0') << static_cast<int>(b);
}
std::cout << std::dec << std::setfill(' ') << '\n';
}
int main()
{
// a binary value
json j = json::binary({0xCA, 0xFE, 0xBA, 0xBE});
// Draft 2 (the default) writes an array of integers
auto v2 = json::to_bjdata(j, true, true, json::bjdata_version_t::draft2);
print_hex("draft2", v2);
// Draft 3 writes an optimized binary array
auto v3 = json::to_bjdata(j, true, true, json::bjdata_version_t::draft3);
print_hex("draft3", v3);
// reading yields an array for Draft 2 and a binary value for Draft 3
std::cout << json::from_bjdata(v2) << '\n';
std::cout << json::from_bjdata(v3) << '\n';
}
```
Output:
```json
draft2: 5b 24 55 23 69 04 ca fe ba be
draft3: 5b 24 42 23 69 04 ca fe ba be
[202,254,186,190]
{"bytes":[202,254,186,190],"subtype":null}
```
## See also
- [to_bjdata](to_bjdata.md) serializes a JSON value to BJData
- [BJData](../../features/binary_formats/bjdata.md) - the article on the BJData format
## Version history
- Added in version 3.12.0.
api/basic_json/bjdata_version_t/index.html
+43
View File
File diff suppressed because one or more lines are too long
api/basic_json/bjdata_version_t/index.md
+77
View File
@@ -0,0 +1,77 @@
# nlohmann::basic_json::bjdata_version_t
```
enum class bjdata_version_t
{
draft2,
draft3
};
```
This enumeration is used in [`to_bjdata`](https://json.nlohmann.me/api/basic_json/to_bjdata/index.md) to choose the version of the BJData specification to write:
draft2 : BJData Draft 2 (the default). Binary values are written as arrays of `U` integers, and ND-arrays with `"_ArrayType_": "byte"` are written as regular objects, since the `B` marker is not part of Draft 2.
draft3 : BJData Draft 3. Binary values are written as `B` elements: as an optimized binary array (`[$B#`) if both `use_size` and `use_type` are set, and as an array of `B`-prefixed elements otherwise. ND-arrays with `"_ArrayType_": "byte"` are written as packed arrays (`[$B#[...]`).
Only the writer is affected by the version. [`from_bjdata`](https://json.nlohmann.me/api/basic_json/from_bjdata/index.md) reads the markers of both drafts.
## Examples
Example
The example below shows how the different values of the `bjdata_version_t` influence the serialization of a binary value with [`to_bjdata`](https://json.nlohmann.me/api/basic_json/to_bjdata/index.md).
```
#include <iomanip>
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
void print_hex(const char* label, const std::vector<std::uint8_t>& v)
{
std::cout << label << ':';
for (auto b : v)
{
std::cout << ' ' << std::hex << std::setw(2) << std::setfill('0') << static_cast<int>(b);
}
std::cout << std::dec << std::setfill(' ') << '\n';
}
int main()
{
// a binary value
json j = json::binary({0xCA, 0xFE, 0xBA, 0xBE});
// Draft 2 (the default) writes an array of integers
auto v2 = json::to_bjdata(j, true, true, json::bjdata_version_t::draft2);
print_hex("draft2", v2);
// Draft 3 writes an optimized binary array
auto v3 = json::to_bjdata(j, true, true, json::bjdata_version_t::draft3);
print_hex("draft3", v3);
// reading yields an array for Draft 2 and a binary value for Draft 3
std::cout << json::from_bjdata(v2) << '\n';
std::cout << json::from_bjdata(v3) << '\n';
}
```
Output:
```
draft2: 5b 24 55 23 69 04 ca fe ba be
draft3: 5b 24 42 23 69 04 ca fe ba be
[202,254,186,190]
{"bytes":[202,254,186,190],"subtype":null}
```
## See also
- [to_bjdata](https://json.nlohmann.me/api/basic_json/to_bjdata/index.md) serializes a JSON value to BJData
- [BJData](https://json.nlohmann.me/features/binary_formats/bjdata/index.md) - the article on the BJData format
## Version history
- Added in version 3.12.0.
api/basic_json/boolean_t.md
+2 -2
View File
@@ -40,11 +40,11 @@ Boolean values are stored directly inside a `basic_json` type.
#include <iomanip>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
std::cout << std::boolalpha << std::is_same<bool, json::boolean_t>::value << std::endl;
std::cout << std::boolalpha << std::is_same<bool, json::boolean_t>::value << '\n';
}
```
api/basic_json/boolean_t/index.html
+3 -3
View File
File diff suppressed because one or more lines are too long
api/basic_json/boolean_t/index.md
+2 -2
View File
@@ -35,11 +35,11 @@ The following code shows that `boolean_t` is by default, a typedef to `bool`.
#include <iomanip>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
std::cout << std::boolalpha << std::is_same<bool, json::boolean_t>::value << std::endl;
std::cout << std::boolalpha << std::is_same<bool, json::boolean_t>::value << '\n';
}
```
api/basic_json/cbegin.md
+1 -1
View File
@@ -30,7 +30,7 @@ Constant.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
api/basic_json/cbegin/index.html
+2 -2
View File
File diff suppressed because one or more lines are too long
api/basic_json/cbegin/index.md
+1 -1
View File
@@ -28,7 +28,7 @@ The following code shows an example for `cbegin()`.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
api/basic_json/cbor_tag_handler_t.md
+8 -6
View File
@@ -15,11 +15,13 @@ error
: report a parse error in case of a tag (the `from_cbor` overloads throw a `parse_error` exception by default)
ignore
: ignore tags
: ignore tags (also in front of a text string map key)
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.
read as if the tag were ignored. If several tags precede a byte string, only the tag directly in front of it is
stored, and only when it has the form 0xd8..0xdb (a tag 0..23 written as 0xc0..0xd7 is skipped). Tags in front of a
text string map key are skipped.
## Examples
@@ -32,7 +34,7 @@ store
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -46,16 +48,16 @@ store
}
catch (const json::parse_error& e)
{
std::cout << e.what() << std::endl;
std::cout << e.what() << '\n';
}
// cbor_tag_handler_t::ignore ignores the tag
auto b_ignore_tag = json::from_cbor(vec, true, true, json::cbor_tag_handler_t::ignore);
std::cout << b_ignore_tag << std::endl;
std::cout << b_ignore_tag << '\n';
// cbor_tag_handler_t::store stores the tag as binary subtype
auto b_store_tag = json::from_cbor(vec, true, true, json::cbor_tag_handler_t::store);
std::cout << b_store_tag << std::endl;
std::cout << b_store_tag << '\n';
}
```
api/basic_json/cbor_tag_handler_t/index.html
+7 -7
View File
File diff suppressed because one or more lines are too long
api/basic_json/cbor_tag_handler_t/index.md
+6 -6
View File
@@ -13,9 +13,9 @@ This enumeration is used in [`from_cbor`](https://json.nlohmann.me/api/basic_jso
error : report a parse error in case of a tag (the `from_cbor` overloads throw a `parse_error` exception by default)
ignore : ignore tags
ignore : ignore tags (also in front of a text string map key)
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.
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 tag directly in front of it is stored, and only when it has the form 0xd8..0xdb (a tag 0..23 written as 0xc0..0xd7 is skipped). Tags in front of a text string map key are skipped.
## Examples
@@ -27,7 +27,7 @@ The example below shows how the different values of the `cbor_tag_handler_t` inf
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -41,16 +41,16 @@ int main()
}
catch (const json::parse_error& e)
{
std::cout << e.what() << std::endl;
std::cout << e.what() << '\n';
}
// cbor_tag_handler_t::ignore ignores the tag
auto b_ignore_tag = json::from_cbor(vec, true, true, json::cbor_tag_handler_t::ignore);
std::cout << b_ignore_tag << std::endl;
std::cout << b_ignore_tag << '\n';
// cbor_tag_handler_t::store stores the tag as binary subtype
auto b_store_tag = json::from_cbor(vec, true, true, json::cbor_tag_handler_t::store);
std::cout << b_store_tag << std::endl;
std::cout << b_store_tag << '\n';
}
```
api/basic_json/cend.md
+1 -1
View File
@@ -30,7 +30,7 @@ Constant.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
api/basic_json/cend/index.html
+2 -2
View File
File diff suppressed because one or more lines are too long
api/basic_json/cend/index.md
+1 -1
View File
@@ -28,7 +28,7 @@ The following code shows an example for `cend()`.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
api/basic_json/clear.md
+1 -1
View File
@@ -46,7 +46,7 @@ All iterators, pointers, and references related to this container are invalidate
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
api/basic_json/clear/index.html
+2 -2
View File
File diff suppressed because one or more lines are too long
api/basic_json/clear/index.md
+1 -1
View File
@@ -44,7 +44,7 @@ The example below shows the effect of `clear()` to different JSON types.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
api/basic_json/contains.md
+15 -8
View File
@@ -61,11 +61,18 @@ Strong exception safety: if an exception occurs, the original value stays intact
## Complexity
Logarithmic in the size of the JSON object.
1. Logarithmic in the size of the JSON object.
2. Logarithmic in the size of the JSON object.
3. At most one lookup per reference token of `ptr`, each logarithmic in the size of the container at that level:
O(*n* log *m*) for *n* reference tokens and containers of size at most *m*.
4. Deleted; a call with an integral argument does not compile.
## Notes
- This method always returns `#!cpp false` when executed on a JSON type that is not an object.
- Overloads (1) and (2) always return `#!cpp false` when executed on a JSON type that is not an object. Overload (3)
also works on arrays and on primitive values: the empty JSON pointer resolves in every JSON value (so
`#!cpp json(1).contains(""_json_pointer)` returns `#!cpp true`), and `#!cpp json({1, 2}).contains("/1"_json_pointer)`
returns `#!cpp true`.
- This method can be executed on any JSON value type.
- Calling this function with an integer argument (for example, `#!cpp contains(0)`) does not compile: such an argument
would otherwise implicitly convert to a null `#!cpp const char*` and, from there, cause undefined behavior when
@@ -98,7 +105,7 @@ Logarithmic in the size of the JSON object.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
using namespace nlohmann::literals;
int main()
@@ -111,7 +118,7 @@ Logarithmic in the size of the JSON object.
std::cout << std::boolalpha <<
"j_object contains 'key': " << j_object.contains("key") << '\n' <<
"j_object contains 'another': " << j_object.contains("another") << '\n' <<
"j_array contains 'key': " << j_array.contains("key") << std::endl;
"j_array contains 'key': " << j_array.contains("key") << '\n';
}
```
@@ -135,7 +142,7 @@ Logarithmic in the size of the JSON object.
#include <nlohmann/json.hpp>
using namespace std::string_view_literals;
using json = nlohmann::json;
using nlohmann::json;
using namespace nlohmann::literals;
int main()
@@ -148,7 +155,7 @@ Logarithmic in the size of the JSON object.
std::cout << std::boolalpha <<
"j_object contains 'key': " << j_object.contains("key"sv) << '\n' <<
"j_object contains 'another': " << j_object.contains("another"sv) << '\n' <<
"j_array contains 'key': " << j_array.contains("key"sv) << std::endl;
"j_array contains 'key': " << j_array.contains("key"sv) << '\n';
}
```
@@ -170,7 +177,7 @@ Logarithmic in the size of the JSON object.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
using namespace nlohmann::literals;
int main()
@@ -192,7 +199,7 @@ Logarithmic in the size of the JSON object.
// an array index with a leading '0' is not found
<< j.contains("/array/01"_json_pointer) << '\n'
// an array index that is not a number is not found
<< j.contains("/array/one"_json_pointer) << std::endl;
<< j.contains("/array/one"_json_pointer) << '\n';
}
```
api/basic_json/contains/index.html
+9 -9
View File
File diff suppressed because one or more lines are too long
api/basic_json/contains/index.md
+11 -8
View File
@@ -51,11 +51,14 @@ Strong exception safety: if an exception occurs, the original value stays intact
## Complexity
Logarithmic in the size of the JSON object.
1. Logarithmic in the size of the JSON object.
1. Logarithmic in the size of the JSON object.
1. At most one lookup per reference token of `ptr`, each logarithmic in the size of the container at that level: O(*n* log *m*) for *n* reference tokens and containers of size at most *m*.
1. Deleted; a call with an integral argument does not compile.
## Notes
- This method always returns `false` when executed on a JSON type that is not an object.
- Overloads (1) and (2) always return `false` when executed on a JSON type that is not an object. Overload (3) also works on arrays and on primitive values: the empty JSON pointer resolves in every JSON value (so `json(1).contains(""_json_pointer)` returns `true`), and `json({1, 2}).contains("/1"_json_pointer)` returns `true`.
- This method can be executed on any JSON value type.
- Calling this function with an integer argument (for example, `contains(0)`) does not compile: such an argument would otherwise implicitly convert to a null `const char*` and, from there, cause undefined behavior when constructing a `std::string` for the object key. To check for an array element instead, use [`at`](https://json.nlohmann.me/api/basic_json/at/index.md), [`operator[]`](https://json.nlohmann.me/api/basic_json/operator%5B%5D/index.md), or compare against [`size`](https://json.nlohmann.me/api/basic_json/size/index.md).
@@ -81,7 +84,7 @@ The example shows how `contains()` is used.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
using namespace nlohmann::literals;
int main()
@@ -94,7 +97,7 @@ int main()
std::cout << std::boolalpha <<
"j_object contains 'key': " << j_object.contains("key") << '\n' <<
"j_object contains 'another': " << j_object.contains("another") << '\n' <<
"j_array contains 'key': " << j_array.contains("key") << std::endl;
"j_array contains 'key': " << j_array.contains("key") << '\n';
}
```
@@ -116,7 +119,7 @@ The example shows how `contains()` is used.
#include <nlohmann/json.hpp>
using namespace std::string_view_literals;
using json = nlohmann::json;
using nlohmann::json;
using namespace nlohmann::literals;
int main()
@@ -129,7 +132,7 @@ int main()
std::cout << std::boolalpha <<
"j_object contains 'key': " << j_object.contains("key"sv) << '\n' <<
"j_object contains 'another': " << j_object.contains("another"sv) << '\n' <<
"j_array contains 'key': " << j_array.contains("key"sv) << std::endl;
"j_array contains 'key': " << j_array.contains("key"sv) << '\n';
}
```
@@ -149,7 +152,7 @@ The example shows how `contains()` is used.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
using namespace nlohmann::literals;
int main()
@@ -171,7 +174,7 @@ int main()
// an array index with a leading '0' is not found
<< j.contains("/array/01"_json_pointer) << '\n'
// an array index that is not a number is not found
<< j.contains("/array/one"_json_pointer) << std::endl;
<< j.contains("/array/one"_json_pointer) << '\n';
}
```
api/basic_json/count.md
+2 -2
View File
@@ -63,7 +63,7 @@ Logarithmic in the size of the JSON object.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -99,7 +99,7 @@ Logarithmic in the size of the JSON object.
#include <nlohmann/json.hpp>
using namespace std::string_view_literals;
using json = nlohmann::json;
using nlohmann::json;
int main()
{
api/basic_json/count/index.html
+3 -3
View File
File diff suppressed because one or more lines are too long
api/basic_json/count/index.md
+2 -2
View File
@@ -52,7 +52,7 @@ The example shows how `count()` is used.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -86,7 +86,7 @@ The example shows how `count()` is used.
#include <nlohmann/json.hpp>
using namespace std::string_view_literals;
using json = nlohmann::json;
using nlohmann::json;
int main()
{
api/basic_json/crbegin.md
+1 -1
View File
@@ -30,7 +30,7 @@ Constant.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
api/basic_json/crbegin/index.html
+2 -2
View File
File diff suppressed because one or more lines are too long
api/basic_json/crbegin/index.md
+1 -1
View File
@@ -28,7 +28,7 @@ The following code shows an example for `crbegin()`.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
api/basic_json/crend.md
+1 -1
View File
@@ -31,7 +31,7 @@ Constant.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
api/basic_json/crend/index.html
+2 -2
View File
File diff suppressed because one or more lines are too long
api/basic_json/crend/index.md
+1 -1
View File
@@ -28,7 +28,7 @@ The following code shows an example for `crend()`.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
api/basic_json/default_object_comparator_t.md
+2 -2
View File
@@ -24,13 +24,13 @@ The actual comparator used depends on [`object_t`](object_t.md) and can be obtai
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
std::cout << std::boolalpha
<< "one < two : " << json::default_object_comparator_t{}("one", "two") << "\n"
<< "three < four : " << json::default_object_comparator_t{}("three", "four") << std::endl;
<< "three < four : " << json::default_object_comparator_t{}("three", "four") << '\n';
}
```
api/basic_json/default_object_comparator_t/index.html
+3 -3
View File
File diff suppressed because one or more lines are too long
api/basic_json/default_object_comparator_t/index.md
+2 -2
View File
@@ -22,13 +22,13 @@ The example below demonstrates the default comparator.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
std::cout << std::boolalpha
<< "one < two : " << json::default_object_comparator_t{}("one", "two") << "\n"
<< "three < four : " << json::default_object_comparator_t{}("three", "four") << std::endl;
<< "three < four : " << json::default_object_comparator_t{}("three", "four") << '\n';
}
```
api/basic_json/diff.md
+43 -6
View File
@@ -2,17 +2,27 @@
```cpp
static basic_json diff(const basic_json& source,
const basic_json& target);
const basic_json& target,
const string_t& path = "");
```
Creates a [JSON Patch](http://jsonpatch.com) so that value `source` can be changed into the value `target` by calling
[`patch`](patch.md) function.
For two JSON values `source` and `target`, the following code always yields `#!cpp true`:
For two JSON values `source` and `target`, the following code yields `#!cpp true`:
```cpp
source.patch(diff(source, target)) == target;
```
The equality holds up to [`operator==`](operator_eq.md), so it has the following exceptions:
- A value that is not equal to itself cannot round-trip. This applies to `NaN` (also nested in an array or object) and
to [discarded](is_discarded.md) values: `diff` emits a `replace` operation for them. A `NaN` in the patch is
serialized as `#!json null`, so a patch that was dumped and parsed again would set `#!json null`.
- Numbers that compare equal produce no operation, even if their types or signs differ: `diff(1, 1.0)`,
`diff(1u, 1)` (unsigned and signed integer) and `diff(0.0, -0.0)` all return `#!json []`. The patched value is then
the `source` and keeps its number type.
## Parameters
`source` (in)
@@ -21,6 +31,12 @@ source.patch(diff(source, target)) == target;
`target` (in)
: JSON value to compare against
`path` (in)
: a prefix that is put verbatim in front of the `path` member of every operation (default: `""`, which addresses the
root of the value). The prefix is neither escaped nor validated: `#!cpp diff(1, 2, "abc")` yields an operation with
the `path` `abc`, which is not a valid JSON Pointer. Use it with a valid JSON Pointer such as `/root` and escape
`~` and `/` in its reference tokens (see [JSON Pointer](../../features/json_pointer.md)).
## Return value
a JSON patch to convert the `source` to `target`
@@ -31,11 +47,32 @@ Strong guarantee: `source` and `target` are never modified.
## Complexity
Linear in the lengths of `source` and `target`.
Linear in the total number of values (including nested ones) in `source` and `target`, times the cost of a key-based
object operation (looking up a key in an object): logarithmic for [`json`](../json.md), and linear for
[`ordered_json`](../ordered_json.md) (see [`ordered_map` complexity](../ordered_map.md#complexity)). For
`ordered_json`, diffing two objects with `n` and `m` members therefore takes O((n+m)²) when their keys do not line up
(e.g., a key was added or the keys are in a different order). The size of the patch is proportional to the number of
operations times the length of their paths, so a small change deep inside a value yields a long `path`.
## Notes
Currently, only `remove`, `add`, and `replace` operations are generated.
- Currently, only `remove`, `add`, and `replace` operations are generated.
- The patch is correct, but not guaranteed to be minimal. For instance, `diff([1,2,3], [0,1,2,3])` yields three
`replace` operations and one `add` operation instead of a single insertion.
- Differences between two arrays are reported index by index. Elements that were added at the end of the array are added
with `add` operations on the path `/-` (appended in order), and elements that were removed are removed with `remove`
operations from the highest index down to the lowest, so that the remaining indices stay valid.
- For objects, the operations for the members of `source` come first (`replace`, `remove`, or the operations for nested
values, in the iteration order of `source`), followed by `add` operations for the members that only `target` has.
- For [`ordered_json`](../ordered_json.md), objects with the same keys in a different order are different. As a patch
cannot reorder members, `diff` removes all keys of the `source` object and adds them again in the order of the
`target`.
- If `source` and `target` differ as a whole (e.g., different types), the patch consists of a single `replace`
operation for the root of the value, i.e., with the `path` `""` (or the given `path` prefix).
- The `value` members of the patch hold copies of values of `target`. A [binary](../../features/binary_values.md) value
has no JSON representation: when a patch that contains one is serialized, it becomes an object such as
`#!json {"bytes":[1,3],"subtype":null}`, so a parsed patch no longer holds a binary value (and would set that object
instead).
## Examples
@@ -48,7 +85,7 @@ Currently, only `remove`, `add`, and `replace` operations are generated.
#include <iomanip>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
using namespace nlohmann::literals;
int main()
@@ -79,7 +116,7 @@ Currently, only `remove`, `add`, and `replace` operations are generated.
// output patch and roundtrip result
std::cout << std::setw(4) << patch << "\n\n"
<< std::setw(4) << patched_source << std::endl;
<< std::setw(4) << patched_source << '\n';
}
```
api/basic_json/diff/index.html
+8 -7
View File
File diff suppressed because one or more lines are too long
api/basic_json/diff/index.md
+20 -6
View File
@@ -2,23 +2,31 @@
```
static basic_json diff(const basic_json& source,
const basic_json& target);
const basic_json& target,
const string_t& path = "");
```
Creates a [JSON Patch](http://jsonpatch.com) so that value `source` can be changed into the value `target` by calling [`patch`](https://json.nlohmann.me/api/basic_json/patch/index.md) function.
For two JSON values `source` and `target`, the following code always yields `true`:
For two JSON values `source` and `target`, the following code yields `true`:
```
source.patch(diff(source, target)) == target;
```
The equality holds up to [`operator==`](https://json.nlohmann.me/api/basic_json/operator_eq/index.md), so it has the following exceptions:
- A value that is not equal to itself cannot round-trip. This applies to `NaN` (also nested in an array or object) and to [discarded](https://json.nlohmann.me/api/basic_json/is_discarded/index.md) values: `diff` emits a `replace` operation for them. A `NaN` in the patch is serialized as `null`, so a patch that was dumped and parsed again would set `null`.
- Numbers that compare equal produce no operation, even if their types or signs differ: `diff(1, 1.0)`, `diff(1u, 1)` (unsigned and signed integer) and `diff(0.0, -0.0)` all return `[]`. The patched value is then the `source` and keeps its number type.
## Parameters
`source` (in) : JSON value to compare from
`target` (in) : JSON value to compare against
`path` (in) : a prefix that is put verbatim in front of the `path` member of every operation (default: `""`, which addresses the root of the value). The prefix is neither escaped nor validated: `diff(1, 2, "abc")` yields an operation with the `path` `abc`, which is not a valid JSON Pointer. Use it with a valid JSON Pointer such as `/root` and escape `~` and `/` in its reference tokens (see [JSON Pointer](https://json.nlohmann.me/features/json_pointer/index.md)).
## Return value
a JSON patch to convert the `source` to `target`
@@ -29,11 +37,17 @@ Strong guarantee: `source` and `target` are never modified.
## Complexity
Linear in the lengths of `source` and `target`.
Linear in the total number of values (including nested ones) in `source` and `target`, times the cost of a key-based object operation (looking up a key in an object): logarithmic for [`json`](https://json.nlohmann.me/api/json/index.md), and linear for [`ordered_json`](https://json.nlohmann.me/api/ordered_json/index.md) (see [`ordered_map` complexity](https://json.nlohmann.me/api/ordered_map/#complexity)). For `ordered_json`, diffing two objects with `n` and `m` members therefore takes O((n+m)²) when their keys do not line up (e.g., a key was added or the keys are in a different order). The size of the patch is proportional to the number of operations times the length of their paths, so a small change deep inside a value yields a long `path`.
## Notes
Currently, only `remove`, `add`, and `replace` operations are generated.
- Currently, only `remove`, `add`, and `replace` operations are generated.
- The patch is correct, but not guaranteed to be minimal. For instance, `diff([1,2,3], [0,1,2,3])` yields three `replace` operations and one `add` operation instead of a single insertion.
- Differences between two arrays are reported index by index. Elements that were added at the end of the array are added with `add` operations on the path `/-` (appended in order), and elements that were removed are removed with `remove` operations from the highest index down to the lowest, so that the remaining indices stay valid.
- For objects, the operations for the members of `source` come first (`replace`, `remove`, or the operations for nested values, in the iteration order of `source`), followed by `add` operations for the members that only `target` has.
- For [`ordered_json`](https://json.nlohmann.me/api/ordered_json/index.md), objects with the same keys in a different order are different. As a patch cannot reorder members, `diff` removes all keys of the `source` object and adds them again in the order of the `target`.
- If `source` and `target` differ as a whole (e.g., different types), the patch consists of a single `replace` operation for the root of the value, i.e., with the `path` `""` (or the given `path` prefix).
- The `value` members of the patch hold copies of values of `target`. A [binary](https://json.nlohmann.me/features/binary_values/index.md) value has no JSON representation: when a patch that contains one is serialized, it becomes an object such as `{"bytes":[1,3],"subtype":null}`, so a parsed patch no longer holds a binary value (and would set that object instead).
## Examples
@@ -46,7 +60,7 @@ The following code shows how a JSON patch is created as a diff for two JSON valu
#include <iomanip>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
using namespace nlohmann::literals;
int main()
@@ -77,7 +91,7 @@ int main()
// output patch and roundtrip result
std::cout << std::setw(4) << patch << "\n\n"
<< std::setw(4) << patched_source << std::endl;
<< std::setw(4) << patched_source << '\n';
}
```
api/basic_json/dump.md
+3 -3
View File
@@ -81,7 +81,7 @@ Binary values are serialized as an object containing two keys:
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -113,11 +113,11 @@ Binary values are serialized as an object containing two keys:
json j_invalid = "ä\xA9ü";
try
{
std::cout << j_invalid.dump() << std::endl;
std::cout << j_invalid.dump() << '\n';
}
catch (const json::type_error& e)
{
std::cout << e.what() << std::endl;
std::cout << e.what() << '\n';
}
std::cout << "string with replaced invalid characters: "
api/basic_json/dump/index.html
+4 -4
View File
File diff suppressed because one or more lines are too long
api/basic_json/dump/index.md
+3 -3
View File
@@ -60,7 +60,7 @@ The following example shows the effect of different `indent`, `indent_char`, and
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -92,11 +92,11 @@ int main()
json j_invalid = "ä\xA9ü";
try
{
std::cout << j_invalid.dump() << std::endl;
std::cout << j_invalid.dump() << '\n';
}
catch (const json::type_error& e)
{
std::cout << e.what() << std::endl;
std::cout << e.what() << '\n';
}
std::cout << "string with replaced invalid characters: "
api/basic_json/emplace.md
+1 -1
View File
@@ -55,7 +55,7 @@ Logarithmic in the size of the container, O(log(`size()`)).
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
api/basic_json/emplace/index.html
+2 -2
View File
File diff suppressed because one or more lines are too long
api/basic_json/emplace/index.md
+1 -1
View File
@@ -45,7 +45,7 @@ The example shows how `emplace()` can be used to add elements to a JSON object.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
api/basic_json/emplace_back.md
+1 -1
View File
@@ -53,7 +53,7 @@ Amortized constant.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
api/basic_json/emplace_back/index.html
+2 -2
View File
File diff suppressed because one or more lines are too long
api/basic_json/emplace_back/index.md
+1 -1
View File
@@ -45,7 +45,7 @@ The example shows how `emplace_back()` can be used to add elements to a JSON arr
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
api/basic_json/empty.md
+1 -1
View File
@@ -54,7 +54,7 @@ itself is empty which is `#!cpp false` in the case of a string.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
api/basic_json/empty/index.html
+2 -2
View File
File diff suppressed because one or more lines are too long
api/basic_json/empty/index.md
+1 -1
View File
@@ -51,7 +51,7 @@ The following code uses `empty()` to check if a JSON object contains any element
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
api/basic_json/end.md
+1 -1
View File
@@ -31,7 +31,7 @@ Constant.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
api/basic_json/end/index.html
+2 -2
View File
File diff suppressed because one or more lines are too long
api/basic_json/end/index.md
+1 -1
View File
@@ -29,7 +29,7 @@ The following code shows an example for `end()`.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
api/basic_json/end_pos.md
+1 -1
View File
@@ -52,7 +52,7 @@ Constant.
#define JSON_DIAGNOSTIC_POSITIONS 1
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
api/basic_json/end_pos/index.html
+2 -2
View File
File diff suppressed because one or more lines are too long
api/basic_json/end_pos/index.md
+1 -1
View File
@@ -49,7 +49,7 @@ Example
#define JSON_DIAGNOSTIC_POSITIONS 1
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
api/basic_json/erase.md
+5 -5
View File
@@ -140,7 +140,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -191,7 +191,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -242,7 +242,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -278,7 +278,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
#include <nlohmann/json.hpp>
using namespace std::string_view_literals;
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -312,7 +312,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
api/basic_json/erase/index.html
+6 -6
View File
File diff suppressed because one or more lines are too long
api/basic_json/erase/index.md
+5 -5
View File
@@ -113,7 +113,7 @@ The example shows the effect of `erase()` for different JSON types using an iter
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -162,7 +162,7 @@ The example shows the effect of `erase()` for different JSON types using an iter
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -211,7 +211,7 @@ The example shows the effect of `erase()` for different JSON types using an obje
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -245,7 +245,7 @@ The example shows the effect of `erase()` for different JSON types using an obje
#include <nlohmann/json.hpp>
using namespace std::string_view_literals;
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -277,7 +277,7 @@ The example shows the effect of `erase()` using an array index.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
api/basic_json/error_handler_t.md
+3 -3
View File
@@ -53,7 +53,7 @@ keep
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -61,11 +61,11 @@ keep
json j_invalid = "ä\xA9ü";
try
{
std::cout << j_invalid.dump() << std::endl;
std::cout << j_invalid.dump() << '\n';
}
catch (const json::type_error& e)
{
std::cout << e.what() << std::endl;
std::cout << e.what() << '\n';
}
std::cout << "string with replaced invalid characters: "
api/basic_json/error_handler_t/index.html
+4 -4
View File
File diff suppressed because one or more lines are too long
api/basic_json/error_handler_t/index.md
+3 -3
View File
@@ -35,7 +35,7 @@ The example below shows how the different values of the `error_handler_t` influe
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -43,11 +43,11 @@ int main()
json j_invalid = "ä\xA9ü";
try
{
std::cout << j_invalid.dump() << std::endl;
std::cout << j_invalid.dump() << '\n';
}
catch (const json::type_error& e)
{
std::cout << e.what() << std::endl;
std::cout << e.what() << '\n';
}
std::cout << "string with replaced invalid characters: "
api/basic_json/exception.md
+2 -2
View File
@@ -72,7 +72,7 @@ constructor.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -86,7 +86,7 @@ constructor.
{
// output exception information
std::cout << "message: " << e.what() << '\n'
<< "exception id: " << e.id << std::endl;
<< "exception id: " << e.id << '\n';
}
}
api/basic_json/exception/index.html
+3 -3
View File
File diff suppressed because one or more lines are too long
api/basic_json/exception/index.md
+2 -2
View File
@@ -68,7 +68,7 @@ The following code shows how arbitrary library exceptions can be caught.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -82,7 +82,7 @@ int main()
{
// output exception information
std::cout << "message: " << e.what() << '\n'
<< "exception id: " << e.id << std::endl;
<< "exception id: " << e.id << '\n';
}
}
```
api/basic_json/find.md
+2 -2
View File
@@ -69,7 +69,7 @@ Logarithmic in the size of the JSON object.
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using nlohmann::json;
int main()
{
@@ -108,7 +108,7 @@ Logarithmic in the size of the JSON object.
#include <nlohmann/json.hpp>
using namespace std::string_view_literals;
using json = nlohmann::json;
using nlohmann::json;
int main()
{

Some files were not shown because too many files have changed in this diff Show More