amorfo77/json
1
0
Fork 0
mirror of https://github.com/nlohmann/json.git synced 2026-02-26 13:26:28 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'develop' of https://github.com/nlohmann/json into bon8

Browse Source 
 Conflicts:
	docs/mkdocs/docs/api/basic_json/index.md
	docs/mkdocs/docs/features/binary_formats/index.md
	docs/mkdocs/mkdocs.yml
	tests/src/unit-binary_formats.cpp
This commit is contained in:
Niels Lohmann
2022-06-18 21:19:48 +02:00
parent ad662d15bc 87cda1d664
commit dfdbbc71bb
146 changed files with 5201 additions and 1259 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/docset/docSet.sql
View File

@@ -140,6 +140,7 @@ INSERT INTO searchIndex(name, type, path) VALUES ('SAX Interface', 'Guide', 'fea
INSERT INTO searchIndex(name, type, path) VALUES ('JSON_ASSERT', 'Macro', 'features/macros/index.html#json_assertx');
INSERT INTO searchIndex(name, type, path) VALUES ('JSON_CATCH_USER', 'Macro', 'features/macros/index.html#json_catch_userexception');
INSERT INTO searchIndex(name, type, path) VALUES ('JSON_DIAGNOSTICS', 'Macro', 'features/macros/index.html#json_diagnostics');
INSERT INTO searchIndex(name, type, path) VALUES ('JSON_DISABLE_ENUM_SERIALIZATION', 'Macro', 'features/macros/index.html#json_disable_enum_serialization');
INSERT INTO searchIndex(name, type, path) VALUES ('JSON_HAS_CPP_11', 'Macro', 'features/macros/index.html#json_has_cpp_11-json_has_cpp_14-json_has_cpp_17-json_has_cpp_20');
INSERT INTO searchIndex(name, type, path) VALUES ('JSON_HAS_CPP_14', 'Macro', 'features/macros/index.html#json_has_cpp_11-json_has_cpp_14-json_has_cpp_17-json_has_cpp_20');
INSERT INTO searchIndex(name, type, path) VALUES ('JSON_HAS_CPP_17', 'Macro', 'features/macros/index.html#json_has_cpp_11-json_has_cpp_14-json_has_cpp_17-json_has_cpp_20');

23
docs/examples/byte_container_with_subtype__byte_container_with_subtype.cpp Normal file
View File

@@ -0,0 +1,23 @@
#include <iostream>
#include <nlohmann/json.hpp>
// define a byte container based on std::vector
using byte_container_with_subtype = nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>;
using json = nlohmann::json;
int main()
{
// (1) create empty container
auto c1 = byte_container_with_subtype();
std::vector<std::uint8_t> bytes = {{0xca, 0xfe, 0xba, 0xbe}};
// (2) create container
auto c2 = byte_container_with_subtype(bytes);
// (3) create container with subtype
auto c3 = byte_container_with_subtype(bytes, 42);
std::cout << json(c1) << "\n" << json(c2) << "\n" << json(c3) << std::endl;
}

3
docs/examples/byte_container_with_subtype__byte_container_with_subtype.output Normal file
View File

@@ -0,0 +1,3 @@
{"bytes":[],"subtype":null}
{"bytes":[202,254,186,190],"subtype":null}
{"bytes":[202,254,186,190],"subtype":42}

21
docs/examples/byte_container_with_subtype__clear_subtype.cpp Normal file
View File

@@ -0,0 +1,21 @@
#include <iostream>
#include <nlohmann/json.hpp>
// define a byte container based on std::vector
using byte_container_with_subtype = nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>;
using json = nlohmann::json;
int main()
{
std::vector<std::uint8_t> bytes = {{0xca, 0xfe, 0xba, 0xbe}};
// create container with subtype
auto c1 = byte_container_with_subtype(bytes, 42);
std::cout << "before calling clear_subtype(): " << json(c1) << '\n';
c1.clear_subtype();
std::cout << "after calling clear_subtype(): " << json(c1) << '\n';
}

2
docs/examples/byte_container_with_subtype__clear_subtype.output Normal file
View File

@@ -0,0 +1,2 @@
before calling clear_subtype(): {"bytes":[202,254,186,190],"subtype":42}
after calling clear_subtype(): {"bytes":[202,254,186,190],"subtype":null}

19
docs/examples/byte_container_with_subtype__has_subtype.cpp Normal file
View File

@@ -0,0 +1,19 @@
#include <iostream>
#include <nlohmann/json.hpp>
// define a byte container based on std::vector
using byte_container_with_subtype = nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>;
int main()
{
std::vector<std::uint8_t> bytes = {{0xca, 0xfe, 0xba, 0xbe}};
// create container
auto c1 = byte_container_with_subtype(bytes);
// create container with subtype
auto c2 = byte_container_with_subtype(bytes, 42);
std::cout << std::boolalpha << "c1.has_subtype() = " << c1.has_subtype()
<< "\nc2.has_subtype() = " << c2.has_subtype() << std::endl;
}

2
docs/examples/byte_container_with_subtype__has_subtype.output Normal file
View File

@@ -0,0 +1,2 @@
c1.has_subtype() = false
c2.has_subtype() = true

22
docs/examples/byte_container_with_subtype__set_subtype.cpp Normal file
View File

@@ -0,0 +1,22 @@
#include <iostream>
#include <nlohmann/json.hpp>
// define a byte container based on std::vector
using byte_container_with_subtype = nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>;
using json = nlohmann::json;
int main()
{
std::vector<std::uint8_t> bytes = {{0xca, 0xfe, 0xba, 0xbe}};
// create container without subtype
auto c = byte_container_with_subtype(bytes);
std::cout << "before calling set_subtype(42): " << json(c) << '\n';
// set the subtype
c.set_subtype(42);
std::cout << "after calling set_subtype(42): " << json(c) << '\n';
}

2
docs/examples/byte_container_with_subtype__set_subtype.output Normal file
View File

@@ -0,0 +1,2 @@
before calling set_subtype(42): {"bytes":[202,254,186,190],"subtype":null}
after calling set_subtype(42): {"bytes":[202,254,186,190],"subtype":42}

22
docs/examples/byte_container_with_subtype__subtype.cpp Normal file
View File

@@ -0,0 +1,22 @@
#include <iostream>
#include <nlohmann/json.hpp>
// define a byte container based on std::vector
using byte_container_with_subtype = nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>;
int main()
{
std::vector<std::uint8_t> bytes = {{0xca, 0xfe, 0xba, 0xbe}};
// create container
auto c1 = byte_container_with_subtype(bytes);
// create container with subtype
auto c2 = byte_container_with_subtype(bytes, 42);
std::cout << "c1.subtype() = " << c1.subtype()
<< "\nc2.subtype() = " << c2.subtype() << std::endl;
// in case no subtype is set, return special value
assert(c1.subtype() == static_cast<byte_container_with_subtype::subtype_type>(-1));
}

2
docs/examples/byte_container_with_subtype__subtype.output Normal file
View File

@@ -0,0 +1,2 @@
c1.subtype() = 18446744073709551615
c2.subtype() = 42

28
docs/examples/cbor_tag_handler_t.cpp Normal file
View File

@@ -0,0 +1,28 @@
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// tagged byte string
std::vector<std::uint8_t> vec = {{0xd8, 0x42, 0x44, 0xcA, 0xfe, 0xba, 0xbe}};
// cbor_tag_handler_t::error throws
try
{
auto b_throw_on_tag = json::from_cbor(vec, true, true, json::cbor_tag_handler_t::error);
}
catch (json::parse_error& e)
{
std::cout << e.what() << std::endl;
}
// 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;
// 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;
}

3
docs/examples/cbor_tag_handler_t.output Normal file
View File

@@ -0,0 +1,3 @@
[json.exception.parse_error.112] parse error at byte 1: syntax error while parsing CBOR value: invalid byte: 0xD8
{"bytes":[202,254,186,190],"subtype":null}
{"bytes":[202,254,186,190],"subtype":66}

11
docs/examples/default_object_comparator_t.cpp Normal file
View File

@@ -0,0 +1,11 @@
#include <iostream>
#include <nlohmann/json.hpp>
using json = 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;
}

2
docs/examples/default_object_comparator_t.output Normal file
View File

@@ -0,0 +1,2 @@
one < two : true
three < four : false

24
docs/examples/error_handler_t.cpp Normal file
View File

@@ -0,0 +1,24 @@
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create JSON value with invalid UTF-8 byte sequence
json j_invalid = "ä\xA9ü";
try
{
std::cout << j_invalid.dump() << std::endl;
}
catch (json::type_error& e)
{
std::cout << e.what() << std::endl;
}
std::cout << "string with replaced invalid characters: "
<< j_invalid.dump(-1, ' ', false, json::error_handler_t::replace)
<< "\nstring with ignored invalid characters: "
<< j_invalid.dump(-1, ' ', false, json::error_handler_t::ignore)
<< '\n';
}

3
docs/examples/error_handler_t.output Normal file
View File

@@ -0,0 +1,3 @@
[json.exception.type_error.316] invalid UTF-8 byte at index 2: 0xA9
string with replaced invalid characters: "ä<>ü"
string with ignored invalid characters: "äü"

20
docs/examples/from_bjdata.cpp Normal file
View File

@@ -0,0 +1,20 @@
#include <iostream>
#include <iomanip>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create byte vector
std::vector<std::uint8_t> v = {0x7B, 0x69, 0x07, 0x63, 0x6F, 0x6D, 0x70, 0x61,
0x63, 0x74, 0x54, 0x69, 0x06, 0x73, 0x63, 0x68,
0x65, 0x6D, 0x61, 0x69, 0x00, 0x7D
};
// deserialize it with BJData
json j = json::from_bjdata(v);
// print the deserialized JSON value
std::cout << std::setw(2) << j << std::endl;
}

4
docs/examples/from_bjdata.output Normal file
View File

@@ -0,0 +1,4 @@
{
"compact": true,
"schema": 0
}

18
docs/examples/get_allocator.cpp Normal file
View File

@@ -0,0 +1,18 @@
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
auto alloc = json::get_allocator();
using traits_t = std::allocator_traits<decltype(alloc)>;
json* j = traits_t::allocate(alloc, 1);
traits_t::construct(alloc, j, "Hello, world!");
std::cout << *j << std::endl;
traits_t::destroy(alloc, j);
traits_t::deallocate(alloc, j, 1);
}

1
docs/examples/get_allocator.output Normal file
View File

@@ -0,0 +1 @@
"Hello, world!"

29
docs/examples/iterator_wrapper.cpp
View File

@@ -1,29 +0,0 @@
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create JSON values
json j_object = {{"one", 1}, {"two", 2}};
json j_array = {1, 2, 4, 8, 16};
//////////////////////////////////////////////////////////////////////////
// The static function iterator_wrapper was deprecated in version 3.1.0
// and will be removed in version 4.0.0. Please replace all occurrences
// of iterator_wrapper(j) with j.items().
//////////////////////////////////////////////////////////////////////////
// example for an object
for (auto& x : json::iterator_wrapper(j_object))
{
std::cout << "key: " << x.key() << ", value: " << x.value() << '\n';
}
// example for an array
for (auto& x : json::iterator_wrapper(j_array))
{
std::cout << "key: " << x.key() << ", value: " << x.value() << '\n';
}
}

7
docs/examples/iterator_wrapper.output
View File

@@ -1,7 +0,0 @@
key: one, value: 1
key: two, value: 2
key: 0, value: 1
key: 1, value: 2
key: 2, value: 4
key: 3, value: 8
key: 4, value: 16

19
docs/examples/json_pointer__operator_string.cpp Normal file
View File

@@ -0,0 +1,19 @@
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// different JSON Pointers
json::json_pointer ptr1("/foo/0");
json::json_pointer ptr2("/a~1b");
// implicit conversion to string
std::string s;
s += ptr1;
s += "\n";
s += ptr2;
std::cout << s << std::endl;
}

2
docs/examples/json_pointer__operator_string.output Normal file
View File

@@ -0,0 +1,2 @@
/foo/0
/a~1b

13
docs/examples/json_pointer__string_t.cpp Normal file
View File

@@ -0,0 +1,13 @@
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
json::json_pointer::string_t s = "This is a string.";
std::cout << s << std::endl;
std::cout << std::boolalpha << std::is_same<json::json_pointer::string_t, json::string_t>::value << std::endl;
}

2
docs/examples/json_pointer__string_t.output Normal file
View File

@@ -0,0 +1,2 @@
This is a string.
true

1
docs/examples/json_pointer__to_string.cpp
View File

@@ -19,7 +19,6 @@ int main()
json::json_pointer ptr11("/ ");
json::json_pointer ptr12("/m~0n");
std::cout << ptr1.to_string() << '\n'
<< ptr2.to_string() << '\n'
<< ptr3.to_string() << '\n'

12
docs/examples/nlohmann_json_version.cpp Normal file
View File

@@ -0,0 +1,12 @@
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
std::cout << "JSON for Modern C++ version "
<< NLOHMANN_JSON_VERSION_MAJOR << "."
<< NLOHMANN_JSON_VERSION_MINOR << "."
<< NLOHMANN_JSON_VERSION_PATCH << std::endl;
}

1
docs/examples/nlohmann_json_version.output Normal file
View File

@@ -0,0 +1 @@
JSON for Modern C++ version 3.10.5

11
docs/examples/object_comparator_t.cpp Normal file
View File

@@ -0,0 +1,11 @@
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
std::cout << std::boolalpha
<< "json::object_comparator_t(\"one\", \"two\") = " << json::object_comparator_t{}("one", "two") << "\n"
<< "json::object_comparator_t(\"three\", \"four\") = " << json::object_comparator_t{}("three", "four") << std::endl;
}

2
docs/examples/object_comparator_t.output Normal file
View File

@@ -0,0 +1,2 @@
json::object_comparator_t("one", "two") = true
json::object_comparator_t("three", "four") = false

14
docs/examples/ordered_json.cpp Normal file
View File

@@ -0,0 +1,14 @@
#include <iostream>
#include <nlohmann/json.hpp>
using ordered_json = nlohmann::ordered_json;
int main()
{
ordered_json j;
j["one"] = 1;
j["two"] = 2;
j["three"] = 3;
std::cout << j.dump(2) << '\n';
}

5
docs/examples/ordered_json.output Normal file
View File

@@ -0,0 +1,5 @@
{
"one": 1,
"two": 2,
"three": 3
}

37
docs/examples/sax_parse.cpp
View File

@@ -6,7 +6,7 @@
using json = nlohmann::json;
// a simple event consumer that collects string representations of the passed
// values; not inheriting from json::json_sax_t is not required, but can
// values; note inheriting from json::json_sax_t is not required, but can
// help not to forget a required function
class sax_event_consumer : public json::json_sax_t
{
@@ -15,79 +15,79 @@ class sax_event_consumer : public json::json_sax_t
bool null() override
{
events.push_back("value: null");
events.push_back("null()");
return true;
}
bool boolean(bool val) override
{
events.push_back("value: " + std::string(val ? "true" : "false"));
events.push_back("boolean(val=" + std::string(val ? "true" : "false") + ")");
return true;
}
bool number_integer(number_integer_t val) override
{
events.push_back("value: " + std::to_string(val));
events.push_back("number_integer(val=" + std::to_string(val) + ")");
return true;
}
bool number_unsigned(number_unsigned_t val) override
{
events.push_back("value: " + std::to_string(val));
events.push_back("number_unsigned(val=" + std::to_string(val) + ")");
return true;
}
bool number_float(number_float_t val, const string_t& s) override
{
events.push_back("value: " + s);
events.push_back("number_float(val=" + std::to_string(val) + ", s=" + s + ")");
return true;
}
bool string(string_t& val) override
{
events.push_back("value: " + val);
events.push_back("string(val=" + val + ")");
return true;
}
bool start_object(std::size_t elements) override
{
events.push_back("start: object");
events.push_back("start_object(elements=" + std::to_string(elements) + ")");
return true;
}
bool end_object() override
{
events.push_back("end: object");
events.push_back("end_object()");
return true;
}
bool start_array(std::size_t elements) override
{
events.push_back("start: array");
events.push_back("start_array(elements=" + std::to_string(elements) + ")");
return true;
}
bool end_array() override
{
events.push_back("end: array");
events.push_back("end_array()");
return true;
}
bool key(string_t& val) override
{
events.push_back("key: " + val);
events.push_back("key(val=" + val + ")");
return true;
}
bool binary(json::binary_t& val) override
{
events.push_back("binary");
events.push_back("binary(val=[...])");
return true;
}
bool parse_error(std::size_t position, const std::string& last_token, const json::exception& ex) override
{
events.push_back("error: " + std::string(ex.what()));
events.push_back("parse_error(position=" + std::to_string(position) + ", last_token=" + last_token + ",\n ex=" + std::string(ex.what()) + ")");
return false;
}
};
@@ -107,22 +107,23 @@ int main()
"Width": 100
},
"Animated" : false,
"IDs": [116, 943, 234, 38793],
"IDs": [116, 943, 234, -38793],
"DeletionDate": null,
"Distance": 12.723374634
}
}
}]
)";
// create a SAX event consumer object
sax_event_consumer sec;
// parse and serialize JSON
// parse JSON
bool result = json::sax_parse(text, &sec);
// output the recorded events
for (auto& event : sec.events)
{
std::cout << "(" << event << ") ";
std::cout << event << "\n";
}
// output the result of sax_parse

39
docs/examples/sax_parse.output
View File

@@ -1,2 +1,37 @@
(start: object) (key: Image) (start: object) (key: Width) (value: 800) (key: Height) (value: 600) (key: Title) (value: View from 15th Floor) (key: Thumbnail) (start: object) (key: Url) (value: http://www.example.com/image/481989943) (key: Height) (value: 125) (key: Width) (value: 100) (end: object) (key: Animated) (value: false) (key: IDs) (start: array) (value: 116) (value: 943) (value: 234) (value: 38793) (end: array) (key: Distance) (value: 12.723374634) (end: object) (end: object)
result: true
start_object(elements=18446744073709551615)
key(val=Image)
start_object(elements=18446744073709551615)
key(val=Width)
number_unsigned(val=800)
key(val=Height)
number_unsigned(val=600)
key(val=Title)
string(val=View from 15th Floor)
key(val=Thumbnail)
start_object(elements=18446744073709551615)
key(val=Url)
string(val=http://www.example.com/image/481989943)
key(val=Height)
number_unsigned(val=125)
key(val=Width)
number_unsigned(val=100)
end_object()
key(val=Animated)
boolean(val=false)
key(val=IDs)
start_array(elements=18446744073709551615)
number_unsigned(val=116)
number_unsigned(val=943)
number_unsigned(val=234)
number_integer(val=-38793)
end_array()
key(val=DeletionDate)
null()
key(val=Distance)
number_float(val=12.723375, s=12.723374634)
end_object()
end_object()
parse_error(position=460, last_token=12.723374634<U+000A> }<U+000A> }],
ex=[json.exception.parse_error.101] parse error at line 17, column 6: syntax error while parsing value - unexpected ']'; expected end of input)
result: false

114
docs/examples/sax_parse__binary.cpp Normal file
View File

@@ -0,0 +1,114 @@
#include <iostream>
#include <iomanip>
#include <sstream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
// a simple event consumer that collects string representations of the passed
// values; note inheriting from json::json_sax_t is not required, but can
// help not to forget a required function
class sax_event_consumer : public json::json_sax_t
{
public:
std::vector<std::string> events;
bool null() override
{
events.push_back("null()");
return true;
}
bool boolean(bool val) override
{
events.push_back("boolean(val=" + std::string(val ? "true" : "false") + ")");
return true;
}
bool number_integer(number_integer_t val) override
{
events.push_back("number_integer(val=" + std::to_string(val) + ")");
return true;
}
bool number_unsigned(number_unsigned_t val) override
{
events.push_back("number_unsigned(val=" + std::to_string(val) + ")");
return true;
}
bool number_float(number_float_t val, const string_t& s) override
{
events.push_back("number_float(val=" + std::to_string(val) + ", s=" + s + ")");
return true;
}
bool string(string_t& val) override
{
events.push_back("string(val=" + val + ")");
return true;
}
bool start_object(std::size_t elements) override
{
events.push_back("start_object(elements=" + std::to_string(elements) + ")");
return true;
}
bool end_object() override
{
events.push_back("end_object()");
return true;
}
bool start_array(std::size_t elements) override
{
events.push_back("start_array(elements=" + std::to_string(elements) + ")");
return true;
}
bool end_array() override
{
events.push_back("end_array()");
return true;
}
bool key(string_t& val) override
{
events.push_back("key(val=" + val + ")");
return true;
}
bool binary(json::binary_t& val) override
{
events.push_back("binary(val=[...])");
return true;
}
bool parse_error(std::size_t position, const std::string& last_token, const json::exception& ex) override
{
events.push_back("parse_error(position=" + std::to_string(position) + ", last_token=" + last_token + ",\n ex=" + std::string(ex.what()) + ")");
return false;
}
};
int main()
{
// CBOR byte string
std::vector<std::uint8_t> vec = {{0x44, 0xcA, 0xfe, 0xba, 0xbe}};
// create a SAX event consumer object
sax_event_consumer sec;
// parse CBOR
bool result = json::sax_parse(vec, &sec, json::input_format_t::cbor);
// output the recorded events
for (auto& event : sec.events)
{
std::cout << event << "\n";
}
// output the result of sax_parse
std::cout << "\nresult: " << std::boolalpha << result << std::endl;
}

3
docs/examples/sax_parse__binary.output Normal file
View File

@@ -0,0 +1,3 @@
binary(val=[...])
result: true

63
docs/examples/to_bjdata.cpp Normal file
View File

@@ -0,0 +1,63 @@
#include <iostream>
#include <iomanip>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
// function to print BJData's diagnostic format
void print_byte(uint8_t byte)
{
if (32 < byte and byte < 128)
{
std::cout << (char)byte;
}
else
{
std::cout << (int)byte;
}
}
int main()
{
// create a JSON value
json j = R"({"compact": true, "schema": false})"_json;
// serialize it to BJData
std::vector<std::uint8_t> v = json::to_bjdata(j);
// print the vector content
for (auto& byte : v)
{
print_byte(byte);
}
std::cout << std::endl;
// create an array of numbers
json array = {1, 2, 3, 4, 5, 6, 7, 8};
// serialize it to BJData using default representation
std::vector<std::uint8_t> v_array = json::to_bjdata(array);
// serialize it to BJData using size optimization
std::vector<std::uint8_t> v_array_size = json::to_bjdata(array, true);
// serialize it to BJData using type optimization
std::vector<std::uint8_t> v_array_size_and_type = json::to_bjdata(array, true, true);
// print the vector contents
for (auto& byte : v_array)
{
print_byte(byte);
}
std::cout << std::endl;
for (auto& byte : v_array_size)
{
print_byte(byte);
}
std::cout << std::endl;
for (auto& byte : v_array_size_and_type)
{
print_byte(byte);
}
std::cout << std::endl;
}

4
docs/examples/to_bjdata.output Normal file
View File

@@ -0,0 +1,4 @@
{i7compactTi6schemaF}
[i1i2i3i4i5i6i7i8]
[#i8i1i2i3i4i5i6i7i8
[$i#i812345678

1
docs/mkdocs/docs/api/basic_json/at.md
View File

@@ -184,6 +184,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
## See also
- documentation on [checked access](../../features/element_access/checked_access.md)
- see [`operator[]`](operator%5B%5D.md) for unchecked access by reference
- see [`value`](value.md) for access with default value

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

@@ -241,7 +241,7 @@ basic_json(basic_json&& other) noexcept;
- Overload 5:
!!! note
!!! note "Empty initializer list"
When used without parentheses around an empty initializer list, `basic_json()` is called instead of this
function, yielding the JSON `#!json null` value.

17
docs/mkdocs/docs/api/basic_json/cbor_tag_handler_t.md
View File

@@ -20,6 +20,23 @@ ignore
store
: store tagged values as binary container with subtype (for bytes 0xd8..0xdb)
## Examples
??? example
The example below shows how the different values of the `cbor_tag_handler_t` influence the behavior of
[`from_cbor`](from_cbor.md) when reading a tagged byte string.
```cpp
--8<-- "examples/cbor_tag_handler_t.cpp"
```
Output:
```json
--8<-- "examples/cbor_tag_handler_t.output"
```
## Version history
- Added in version 3.9.0. Added value `store` in 3.10.0.

4
docs/mkdocs/docs/api/basic_json/contains.md
View File

@@ -60,8 +60,8 @@ Logarithmic in the size of the JSON object.
## Notes
1. This method always returns `#!cpp false` when executed on a JSON type that is not an object.
2. This method can be executed on any JSON value type.
- This method always returns `#!cpp false` when executed on a JSON type that is not an object.
- This method can be executed on any JSON value type.
!!! info "Postconditions"

16
docs/mkdocs/docs/api/basic_json/default_object_comparator_t.md
View File

@@ -14,6 +14,22 @@ when looking up a key in an object.
The actual comparator used depends on [`object_t`](object_t.md) and can be obtained via
[`object_comparator_t`](object_comparator_t.md).
## Examples
??? example
The example below demonstrates the default comparator.
```cpp
--8<-- "examples/default_object_comparator_t.cpp"
```
Output:
```json
--8<-- "examples/default_object_comparator_t.output"
```
## Version history
- Added in version 3.11.0.

17
docs/mkdocs/docs/api/basic_json/error_handler_t.md
View File

@@ -20,6 +20,23 @@ replace
ignore
: ignore invalid UTF-8 sequences; all bytes are copied to the output unchanged
## Examples
??? example
The example below shows how the different values of the `error_handler_t` influence the behavior of
[`dump`](dump.md) when reading serializing an invalid UTF-8 sequence.
```cpp
--8<-- "examples/error_handler_t.cpp"
```
Output:
```json
--8<-- "examples/error_handler_t.output"
```
## Version history
- Added in version 3.4.0.

93
docs/mkdocs/docs/api/basic_json/from_bjdata.md Normal file
View File

@@ -0,0 +1,93 @@
# <small>nlohmann::basic_json::</small>from_bjdata
```cpp
// (1)
template<typename InputType>
static basic_json from_bjdata(InputType&& i,
const bool strict = true,
const bool allow_exceptions = true);
// (2)
template<typename IteratorType>
static basic_json from_bjdata(IteratorType first, IteratorType last,
const bool strict = true,
const bool allow_exceptions = true);
```
Deserializes a given input to a JSON value using the BJData (Binary JData) serialization format.
1. Reads from a compatible input.
2. Reads from an iterator range.
The exact mapping and its limitations is described on a [dedicated page](../../features/binary_formats/bjdata.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
- an object `obj` for which `begin(obj)` and `end(obj)` produces a valid pair of iterators.
`IteratorType`
: a compatible iterator type
## Parameters
`i` (in)
: an input in BJData format convertible to an input adapter
`first` (in)
: iterator to start of the input
`last` (in)
: iterator to end of the input
`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 file was not reached when `strict` was set to true
- Throws [parse_error.112](../../home/exceptions.md#jsonexceptionparse_error112) if a parse error occurs
- Throws [parse_error.113](../../home/exceptions.md#jsonexceptionparse_error113) if a string could not be parsed
successfully
## Complexity
Linear in the size of the input.
## Examples
??? example
The example shows the deserialization of a byte vector in BJData format to a JSON value.
```cpp
--8<-- "examples/from_bjdata.cpp"
```
Output:
```json
--8<-- "examples/from_bjdata.output"
```
## Version history
- Added in version 3.11.0.

22
docs/mkdocs/docs/api/basic_json/get_allocator.md
View File

@@ -10,10 +10,22 @@ Returns the allocator associated with the container.
associated allocator
## Examples
??? example
The example shows how `get_allocator()` is used to created `json` values.
```cpp
--8<-- "examples/get_allocator.cpp"
```
Output:
```json
--8<-- "examples/get_allocator.output"
```
## Version history
- Unknown.
!!! note
This documentation page is a stub.
- Added in version 1.0.0.

5
docs/mkdocs/docs/api/basic_json/index.md
View File

@@ -233,9 +233,10 @@ Access to the JSON value
- [**operator==**](operator_eq.md) - comparison: equal
- [**operator!=**](operator_ne.md) - comparison: not equal
- [**operator<**](operator_lt.md) - comparison: less than
- [**operator<=**](operator_le.md) - comparison: less than or equal
- [**operator>**](operator_gt.md) - comparison: greater than
- [**operator<=**](operator_le.md) - comparison: less than or equal
- [**operator>=**](operator_ge.md) - comparison: greater than or equal
- [**operator<=>**](operator_spaceship.md) - comparison: 3-way
### Serialization / Dumping
@@ -268,11 +269,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_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_bon8**](to_bon8.md) (static) - create a BON8 serialization of a given JSON value
- [**to_bjdata**](to_bjdata.md) (_static_) - create a BJData 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

22
docs/mkdocs/docs/api/basic_json/input_format_t.md
View File

@@ -6,7 +6,8 @@ enum class input_format_t {
cbor,
msgpack,
ubjson,
bson
bson,
bjdata
};
```
@@ -27,6 +28,25 @@ ubjson
bson
: BSON (Binary JSON)
bjdata
: BJData (Binary JData)
## Examples
??? example
The example below shows how an `input_format_t` enum value is passed to `sax_parse` to set the input format to CBOR.
```cpp
--8<-- "examples/sax_parse__binary.cpp"
```
Output:
```json
--8<-- "examples/sax_parse__binary.output"
```
## Version history
- Added in version 3.2.0.

17
docs/mkdocs/docs/api/basic_json/object_comparator_t.md
View File

@@ -1,6 +1,5 @@
# <small>nlohmann::basic_json::</small>object_comparator_t
```cpp
using object_comparator_t = typename object_t::key_compare;
// or
@@ -10,6 +9,22 @@ using object_comparator_t = default_object_comparator_t;
The comparator used by [`object_t`](object_t.md). Defined as `#!cpp typename object_t::key_compare` if available,
and [`default_object_comparator_t`](default_object_comparator_t.md) otherwise.
## Examples
??? example
The example below demonstrates the used object comparator.
```cpp
--8<-- "examples/object_comparator_t.cpp"
```
Output:
```json
--8<-- "examples/object_comparator_t.output"
```
## Version history
- Added in version 3.0.0.

9
docs/mkdocs/docs/api/basic_json/operator+=.md
View File

@@ -41,12 +41,9 @@ reference operator+=(initializer_list_t init);
## Exceptions
1. The function can throw the following exceptions:
- Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than
JSON array or null; example: `"cannot use operator+=() with number"`
2. The function can throw the following exceptions:
- Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than
JSON object or null; example: `"cannot use operator+=() with number"`
All functions can throw the following exception:
- Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than
JSON array or null; example: `"cannot use operator+=() with number"`
## Complexity

2
docs/mkdocs/docs/api/basic_json/operator[].md
View File

@@ -198,6 +198,8 @@ Strong exception safety: if an exception occurs, the original value stays intact
## See also
- documentation on [unchecked access](../../features/element_access/unchecked_access.md)
- documentation on [runtime assertions](../../features/assertions.md)
- see [`at`](at.md) for access by reference with range checking
- see [`value`](value.md) for access with default value

1
docs/mkdocs/docs/api/basic_json/operator_ValueType.md
View File

@@ -56,7 +56,6 @@ Linear in the size of the JSON value.
[`JSON_USE_IMPLICIT_CONVERSIONS`](../macros/json_use_implicit_conversions.md) to `0` and replace any implicit
conversions with calls to [`get`](../basic_json/get.md).
## Examples
??? example

41
docs/mkdocs/docs/api/basic_json/operator_eq.md
View File

@@ -1,21 +1,31 @@
# <small>nlohmann::basic_json::</small>operator==
```cpp
bool operator==(const_reference lhs, const_reference rhs) noexcept;
// until C++20
bool operator==(const_reference lhs, const_reference rhs) noexcept; // (1)
template<typename ScalarType>
bool operator==(const_reference lhs, const ScalarType rhs) noexcept;
bool operator==(const_reference lhs, const ScalarType rhs) noexcept; // (2)
template<typename ScalarType>
bool operator==(ScalarType lhs, const const_reference rhs) noexcept;
bool operator==(ScalarType lhs, const const_reference rhs) noexcept; // (2)
// since C++20
class basic_json {
bool operator==(const_reference rhs) const noexcept; // (1)
template<typename ScalarType>
bool operator==(ScalarType rhs) const noexcept; // (2)
};
```
Compares two JSON values for equality according to the following rules:
1. Compares two JSON values for equality according to the following rules:
- Two JSON values are equal if (1) neither value is discarded, or (2) they are of the same
type and their stored values are the same according to their respective `operator==`.
- Integer and floating-point numbers are automatically converted before comparison.
- Two JSON values are equal if (1) they are not discarded, (2) they are from the same type, and (3) their stored values
are the same according to their respective `operator==`.
- Integer and floating-point numbers are automatically converted before comparison. Note that two NaN values are always
treated as unequal.
2. Compares a JSON value and a scalar or a scalar and a JSON value for equality by converting the
scalar to a JSON value and comparing both JSON values according to 1.
## Template parameters
@@ -32,7 +42,7 @@ Compares two JSON values for equality according to the following rules:
## Return value
whether the values `lhs` and `rhs` are equal
whether the values `lhs`/`*this` and `rhs` are equal
## Exception safety
@@ -44,13 +54,17 @@ Linear.
## Notes
!!! note
!!! note "Comparing special values"
- NaN values never compare equal to themselves or to other NaN values.
- `NaN` values are unordered within the domain of numbers.
The following comparisons all yield `#!cpp false`:
1. Comparing a `NaN` with itself.
2. Comparing a `NaN` with another `NaN`.
3. Comparing a `NaN` and any other number.
- JSON `#!cpp null` values are all equal.
- Discarded values never compare equal to themselves.
!!! note
!!! note "Comparing floating-point numbers"
Floating-point numbers inside JSON values numbers are compared with `json::number_float_t::operator==` which is
`double::operator==` by default. To compare floating-point while respecting an epsilon, an alternative
@@ -117,4 +131,5 @@ Linear.
## Version history
- Added in version 1.0.0.
1. Added in version 1.0.0. Added C++20 member functions in version 3.11.0.
2. Added in version 1.0.0. Added C++20 member functions in version 3.11.0.

40
docs/mkdocs/docs/api/basic_json/operator_ge.md
View File

@@ -1,17 +1,25 @@
# <small>nlohmann::basic_json::</small>operator>=
```cpp
bool operator>=(const_reference lhs, const_reference rhs) noexcept,
// until C++20
bool operator>=(const_reference lhs, const_reference rhs) noexcept; // (1)
template<typename ScalarType>
bool operator>=(const_reference lhs, const ScalarType rhs) noexcept;
bool operator>=(const_reference lhs, const ScalarType rhs) noexcept; // (2)
template<typename ScalarType>
bool operator>=(ScalarType lhs, const const_reference rhs) noexcept;
bool operator>=(ScalarType lhs, const const_reference rhs) noexcept; // (2)
```
Compares whether one JSON value `lhs` is greater than or equal to another JSON value `rhs` by calculating
`#!cpp !(lhs < rhs)`.
1. Compares whether one JSON value `lhs` is greater than or equal to another JSON value `rhs`
according to the following rules:
- The comparison always yields `#!cpp false` if (1) either operand is discarded, or (2) either
operand is `NaN` and the other operand is either `NaN` or any other number.
- Otherwise, returns the result of `#!cpp !(lhs < rhs)`.
2. Compares wether a JSON value is greater than or equal to a scalar or a scalar is greater than or
equal to a JSON value by converting the scalar to a JSON value and comparing both JSON values
according to 1.
## Template parameters
@@ -38,6 +46,21 @@ No-throw guarantee: this function never throws exceptions.
Linear.
## Notes
!!! note "Comparing `NaN`"
`NaN` values are unordered within the domain of numbers.
The following comparisons all yield `#!cpp false`:
1. Comparing a `NaN` with itself.
2. Comparing a `NaN` with another `NaN`.
3. Comparing a `NaN` and any other number.
!!! note "Operator overload resolution"
Since C++20 overload resolution will consider the _rewritten candidate_ generated from
[`operator<=>`](operator_spaceship.md).
## Examples
??? example
@@ -54,6 +77,11 @@ Linear.
--8<-- "examples/operator__greaterequal.output"
```
## See also
- [**operator<=>**](operator_spaceship.md) comparison: 3-way
## Version history
- Added in version 1.0.0.
1. Added in version 1.0.0. Conditionally removed since C++20 in version 3.11.0.
2. Added in version 1.0.0. Conditionally removed since C++20 in version 3.11.0.

38
docs/mkdocs/docs/api/basic_json/operator_gt.md
View File

@@ -1,16 +1,24 @@
# <small>nlohmann::basic_json::</small>operator>
```cpp
bool operator>(const_reference lhs, const_reference rhs) noexcept,
// until C++20
bool operator>(const_reference lhs, const_reference rhs) noexcept; // (1)
template<typename ScalarType>
bool operator>(const_reference lhs, const ScalarType rhs) noexcept;
bool operator>(const_reference lhs, const ScalarType rhs) noexcept; // (2)
template<typename ScalarType>
bool operator>(ScalarType lhs, const const_reference rhs) noexcept;
bool operator>(ScalarType lhs, const const_reference rhs) noexcept; // (2)
```
Compares whether one JSON value `lhs` is greater than another JSON value `rhs` by calculating `#!cpp !(lhs <= rhs)`.
1. Compares whether one JSON value `lhs` is greater than another JSON value `rhs` according to the
following rules:
- The comparison always yields `#!cpp false` if (1) either operand is discarded, or (2) either
operand is `NaN` and the other operand is either `NaN` or any other number.
- Otherwise, returns the result of `#!cpp !(lhs <= rhs)`.
2. Compares wether a JSON value is greater than a scalar or a scalar is greater than a JSON value by
converting the scalar to a JSON value and comparing both JSON values according to 1.
## Template parameters
@@ -37,6 +45,21 @@ No-throw guarantee: this function never throws exceptions.
Linear.
## Notes
!!! note "Comparing `NaN`"
`NaN` values are unordered within the domain of numbers.
The following comparisons all yield `#!cpp false`:
1. Comparing a `NaN` with itself.
2. Comparing a `NaN` with another `NaN`.
3. Comparing a `NaN` and any other number.
!!! note "Operator overload resolution"
Since C++20 overload resolution will consider the _rewritten candidate_ generated from
[`operator<=>`](operator_spaceship.md).
## Examples
??? example
@@ -53,6 +76,11 @@ Linear.
--8<-- "examples/operator__greater.output"
```
## See also
- [**operator<=>**](operator_spaceship.md) comparison: 3-way
## Version history
- Added in version 1.0.0.
1. Added in version 1.0.0. Conditionally removed since C++20 in version 3.11.0.
2. Added in version 1.0.0. Conditionally removed since C++20 in version 3.11.0.

40
docs/mkdocs/docs/api/basic_json/operator_le.md
View File

@@ -1,17 +1,25 @@
# <small>nlohmann::basic_json::</small>operator<=
```cpp
bool operator<=(const_reference lhs, const_reference rhs) noexcept,
// until C++20
bool operator<=(const_reference lhs, const_reference rhs) noexcept; // (1)
template<typename ScalarType>
bool operator<=(const_reference lhs, const ScalarType rhs) noexcept;
bool operator<=(const_reference lhs, const ScalarType rhs) noexcept; // (2)
template<typename ScalarType>
bool operator<=(ScalarType lhs, const const_reference rhs) noexcept;
bool operator<=(ScalarType lhs, const const_reference rhs) noexcept; // (2)
```
Compares whether one JSON value `lhs` is less than or equal to another JSON value `rhs` by calculating
`#cpp !(rhs < lhs)`.
1. Compares whether one JSON value `lhs` is less than or equal to another JSON value `rhs`
according to the following rules:
- The comparison always yields `#!cpp false` if (1) either operand is discarded, or (2) either
operand is `NaN` and the other operand is either `NaN` or any other number.
- Otherwise, returns the result of `#!cpp !(rhs < lhs)`.
1. Compares wether a JSON value is less than or equal to a scalar or a scalar is less than or equal
to a JSON value by converting the scalar to a JSON value and comparing both JSON values according
to 1.
## Template parameters
@@ -38,6 +46,21 @@ No-throw guarantee: this function never throws exceptions.
Linear.
## Notes
!!! note "Comparing `NaN`"
`NaN` values are unordered within the domain of numbers.
The following comparisons all yield `#!cpp false`:
1. Comparing a `NaN` with itself.
2. Comparing a `NaN` with another `NaN`.
3. Comparing a `NaN` and any other number.
!!! note "Operator overload resolution"
Since C++20 overload resolution will consider the _rewritten candidate_ generated from
[`operator<=>`](operator_spaceship.md).
## Examples
??? example
@@ -54,6 +77,11 @@ Linear.
--8<-- "examples/operator__lessequal.output"
```
## See also
- [**operator<=>**](operator_spaceship.md) comparison: 3-way
## Version history
- Added in version 1.0.0.
1. Added in version 1.0.0. Conditionally removed since C++20 in version 3.11.0.
2. Added in version 1.0.0. Conditionally removed since C++20 in version 3.11.0.

61
docs/mkdocs/docs/api/basic_json/operator_lt.md
View File

@@ -1,31 +1,34 @@
# <small>nlohmann::basic_json::</small>operator<
```cpp
bool operator<(const_reference lhs, const_reference rhs) noexcept;
// until C++20
bool operator<(const_reference lhs, const_reference rhs) noexcept; // (1)
template<typename ScalarType>
bool operator<(const_reference lhs, const ScalarType rhs) noexcept;
bool operator<(const_reference lhs, const ScalarType rhs) noexcept; // (2)
template<typename ScalarType>
bool operator<(ScalarType lhs, const const_reference rhs) noexcept;
bool operator<(ScalarType lhs, const const_reference rhs) noexcept; // (2)
```
Compares whether one JSON value `lhs` is less than another JSON value `rhs` according to the following rules:
1. Compares whether one JSON value `lhs` is less than another JSON value `rhs` according to the
following rules:
- If either operand is discarded, the comparison yields `#!cpp false`.
- If both operands have the same type, the values are compared using their respective `operator<`.
- Integer and floating-point numbers are automatically converted before comparison.
- In case `lhs` and `rhs` have different types, the values are ignored and the order of the types
is considered, which is:
1. null
2. boolean
3. number (all types)
4. object
5. array
6. string
7. binary
For instance, any boolean value is considered less than any string.
- If `lhs` and `rhs` have the same type, the values are compared using the default `<` operator.
- Integer and floating-point numbers are automatically converted before comparison
- Discarded values a
- In case `lhs` and `rhs` have different types, the values are ignored and the order of the types is considered, which
is:
1. null
2. boolean
3. number (all types)
4. object
5. array
6. string
7. binary
For instance, any boolean value is considered less than any string.
2. Compares wether a JSON value is less than a scalar or a scalar is less than a JSON value by converting
the scalar to a JSON value and comparing both JSON values according to 1.
## Template parameters
@@ -52,6 +55,21 @@ No-throw guarantee: this function never throws exceptions.
Linear.
## Notes
!!! note "Comparing `NaN`"
`NaN` values are unordered within the domain of numbers.
The following comparisons all yield `#!cpp false`:
1. Comparing a `NaN` with itself.
2. Comparing a `NaN` with another `NaN`.
3. Comparing a `NaN` and any other number.
!!! note "Operator overload resolution"
Since C++20 overload resolution will consider the _rewritten candidate_ generated from
[`operator<=>`](operator_spaceship.md).
## Examples
??? example
@@ -68,6 +86,11 @@ Linear.
--8<-- "examples/operator__less.output"
```
## See also
- [**operator<=>**](operator_spaceship.md) comparison: 3-way
## Version history
- Added in version 1.0.0.
1. Added in version 1.0.0. Conditionally removed since C++20 in version 3.11.0.
2. Added in version 1.0.0. Conditionally removed since C++20 in version 3.11.0.

39
docs/mkdocs/docs/api/basic_json/operator_ne.md
View File

@@ -1,16 +1,32 @@
# <small>nlohmann::basic_json::</small>operator!=
```cpp
bool operator!=(const_reference lhs, const_reference rhs) noexcept;
// until C++20
bool operator!=(const_reference lhs, const_reference rhs) noexcept; // (1)
template<typename ScalarType>
bool operator!=(const_reference lhs, const ScalarType rhs) noexcept;
bool operator!=(const_reference lhs, const ScalarType rhs) noexcept; // (2)
template<typename ScalarType>
bool operator!=(ScalarType lhs, const const_reference rhs) noexcept;
bool operator!=(ScalarType lhs, const const_reference rhs) noexcept; // (2)
// since C++20
class basic_json {
bool operator!=(const_reference rhs) const noexcept; // (1)
template<typename ScalarType>
bool operator!=(ScalarType rhs) const noexcept; // (2)
};
```
Compares two JSON values for inequality by calculating `#!cpp !(lhs == rhs)`.
1. Compares two JSON values for inequality according to the following rules:
- The comparison always yields `#!cpp false` if (1) either operand is discarded, or (2) either
operand is `NaN` and the other operand is either `NaN` or any other number.
- Otherwise, returns the result of `#!cpp !(lhs == rhs)` (until C++20) or
`#!cpp !(*this == rhs)` (since C++20).
2. Compares a JSON value and a scalar or a scalar and a JSON value for inequality by converting the
scalar to a JSON value and comparing both JSON values according to 1.
## Template parameters
@@ -27,7 +43,7 @@ Compares two JSON values for inequality by calculating `#!cpp !(lhs == rhs)`.
## Return value
whether the values `lhs` and `rhs` are not equal
whether the values `lhs`/`*this` and `rhs` are not equal
## Exception safety
@@ -37,6 +53,16 @@ No-throw guarantee: this function never throws exceptions.
Linear.
## Notes
!!! note "Comparing `NaN`"
`NaN` values are unordered within the domain of numbers.
The following comparisons all yield `#!cpp false`:
1. Comparing a `NaN` with itself.
2. Comparing a `NaN` with another `NaN`.
3. Comparing a `NaN` and any other number.
## Examples
??? example
@@ -69,4 +95,5 @@ Linear.
## Version history
- Added in version 1.0.0.
1. Added in version 1.0.0. Added C++20 member functions in version 3.11.0.
2. Added in version 1.0.0. Added C++20 member functions in version 3.11.0.

70
docs/mkdocs/docs/api/basic_json/operator_spaceship.md Normal file
View File

@@ -0,0 +1,70 @@
# <small>nlohmann::basic_json::</small>operator<=>
```cpp
// since C++20
class basic_json {
std::partial_ordering operator<=>(const_reference rhs) const noexcept; // (1)
template<typename ScalarType>
std::partial_ordering operator<=>(const ScalarType rhs) const noexcept; // (2)
};
```
1. 3-way compares two JSON values producing a result of type `std::partial_ordering` according to the following rules:
- Two JSON values compare with a result of `std::partial_ordering::unordered` if either value is discarded.
- If both JSON values are of the same type, the result is produced by 3-way comparing their stored values using their
respective `operator<=>`.
- Integer and floating-point numbers are converted to their common type and then 3-way compared using their respective
`operator<=>`.
For instance, comparing an integer and a floating-point value will 3-way compare the first value convertered to
floating-point with the second value.
- Otherwise, yields a result by comparing the type (see [`value_t`](value_t.md)).
2. 3-way compares a JSON value and a scalar or a scalar and a JSON value by converting the scalar to a JSON value and 3-way
comparing both JSON values (see 1).
## Template parameters
`ScalarType`
: a scalar type according to `std::is_scalar<ScalarType>::value`
## Parameters
`rhs` (in)
: second value to consider
## Return value
the `std::partial_ordering` of the 3-way comparison of `*this` and `rhs`
## Exception safety
No-throw guarantee: this function never throws exceptions.
## Complexity
Linear.
## Notes
!!! note "Comparing `NaN`"
- `NaN` values are unordered within the domain of numbers.
The following comparisons all yield `std::partial_ordering::unordered`:
1. Comparing a `NaN` with itself.
2. Comparing a `NaN` with another `NaN`.
3. Comparing a `NaN` and any other number.
## See also
- [**operator==**](operator_eq.md) - comparison: equal
- [**operator!=**](operator_ne.md) - comparison: not equal
- [**operator<**](operator_lt.md) - comparison: less than
- [**operator<=**](operator_le.md) - comparison: less than or equal
- [**operator>**](operator_gt.md) - comparison: greater than
- [**operator>=**](operator_ge.md) - comparison: greater than or equal
## Version history
1. Added in version 3.11.0.
2. Added in version 3.11.0.

9
docs/mkdocs/docs/api/basic_json/push_back.md
View File

@@ -37,12 +37,9 @@ void push_back(initializer_list_t init);
## Exceptions
1. The function can throw the following exceptions:
- Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than
JSON array or null; example: `"cannot use push_back() with number"`
2. The function can throw the following exceptions:
- Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than
JSON object or null; example: `"cannot use push_back() with number"`
All functions can throw the following exception:
- Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than
JSON array or null; example: `"cannot use push_back() with number"`
## Complexity

70
docs/mkdocs/docs/api/basic_json/to_bjdata.md Normal file
View File

@@ -0,0 +1,70 @@
# <small>nlohmann::basic_json::</small>to_bjdata
```cpp
// (1)
static std::vector<std::uint8_t> to_bjdata(const basic_json& j,
const bool use_size = false,
const bool use_type = false);
// (2)
static void to_bjdata(const basic_json& j, detail::output_adapter<std::uint8_t> o,
const bool use_size = false, const bool use_type = false);
static void to_bjdata(const basic_json& j, detail::output_adapter<char> o,
const bool use_size = false, const bool use_type = false);
```
Serializes a given JSON value `j` to a byte vector using the BJData (Binary JData) serialization format. BJData
aims to be more compact than JSON itself, yet more efficient to parse.
1. Returns a byte vector containing the BJData serialization.
2. Writes the BJData serialization to an output adapter.
The exact mapping and its limitations is described on a [dedicated page](../../features/binary_formats/bjdata.md).
## Parameters
`j` (in)
: JSON value to serialize
`o` (in)
: output adapter to write serialization to
`use_size` (in)
: whether to add size annotations to container types; optional, `#!cpp false` by default.
`use_type` (in)
: whether to add type annotations to container types (must be combined with `#!cpp use_size = true`); optional,
`#!cpp false` by default.
## Return value
1. BJData serialization as byte vector
2. (none)
## 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`.
## Examples
??? example
The example shows the serialization of a JSON value to a byte vector in BJData format.
```cpp
--8<-- "examples/to_bjdata.cpp"
```
Output:
```json
--8<-- "examples/to_bjdata.output"
```
## Version history
- Added in version 3.11.0.

55
docs/mkdocs/docs/api/basic_json/value_t.md
View File

@@ -24,10 +24,57 @@ functions [`is_null`](is_null.md), [`is_object`](is_object.md), [`is_array`](is_
## Notes
There are three enumeration entries (number_integer, number_unsigned, and number_float), because the library
distinguishes these three types for numbers: [`number_unsigned_t`](number_unsigned_t.md) is used for unsigned integers,
[`number_integer_t`](number_integer_t.md) is used for signed integers, and [`number_float_t`](number_float_t.md) is used
for floating-point numbers or to approximate integers which do not fit in the limits of their respective type.
!!! note "Ordering"
The order of types is as follows:
1. `null`
2. `boolean`
3. `number_integer`, `number_unsigned`, `number_float`
4. `object`
5. `array`
6. `string`
7. `binary`
`discarded` is unordered.
!!! note "Types of numbers"
There are three enumerators for numbers (`number_integer`, `number_unsigned`, and `number_float`) to distinguish
between different types of numbers:
- [`number_unsigned_t`](number_unsigned_t.md) for unsigned integers
- [`number_integer_t`](number_integer_t.md) for signed integers
- [`number_float_t`](number_float_t.md) for floating-point numbers or to approximate integers which do not fit
into the limits of their respective type
!!! warning "Comparison operators"
`operator<` and `operator<=>` (since C++20) are overloaded and compare according to the ordering described above.
Until C++20 all other relational and equality operators yield results according to the integer value of each
enumerator.
Since C++20 some compilers consider the _rewritten candidates_ generated from `operator<=>` during overload
resolution, while others do not.
For predictable and portable behavior use:
- `operator<` or `operator<=>` when wanting to compare according to the order described above
- `operator==` or `operator!=` when wanting to compare according to each enumerators integer value
## Examples
??? example
The following code how `type()` queries the `value_t` for all JSON types.
```cpp
--8<-- "examples/type.cpp"
```
Output:
```json
--8<-- "examples/type.output"
```
## Version history

16
docs/mkdocs/docs/api/byte_container_with_subtype/byte_container_with_subtype.md
View File

@@ -25,6 +25,22 @@ byte_container_with_subtype(container_type&& container, subtype_type subtype);
`subtype` (in)
: subtype
## Examples
??? example
The example below demonstrates how byte containers can be created.
```cpp
--8<-- "examples/byte_container_with_subtype__byte_container_with_subtype.cpp"
```
Output:
```json
--8<-- "examples/byte_container_with_subtype__byte_container_with_subtype.output"
```
## Version history
Since version 3.8.0.

16
docs/mkdocs/docs/api/byte_container_with_subtype/clear_subtype.md
View File

@@ -15,6 +15,22 @@ No-throw guarantee: this function never throws exceptions.
Constant.
## Examples
??? example
The example below demonstrates how `clear_subtype` can remove subtypes.
```cpp
--8<-- "examples/byte_container_with_subtype__clear_subtype.cpp"
```
Output:
```json
--8<-- "examples/byte_container_with_subtype__clear_subtype.output"
```
## Version history
Since version 3.8.0.

16
docs/mkdocs/docs/api/byte_container_with_subtype/has_subtype.md
View File

@@ -18,6 +18,22 @@ No-throw guarantee: this function never throws exceptions.
Constant.
## Examples
??? example
The example below demonstrates how `has_subtype` can check whether a subtype was set.
```cpp
--8<-- "examples/byte_container_with_subtype__has_subtype.cpp"
```
Output:
```json
--8<-- "examples/byte_container_with_subtype__has_subtype.output"
```
## Version history
Since version 3.8.0.

16
docs/mkdocs/docs/api/byte_container_with_subtype/set_subtype.md
View File

@@ -20,6 +20,22 @@ No-throw guarantee: this function never throws exceptions.
Constant.
## Examples
??? example
The example below demonstrates how a subtype can be set with `set_subtype`.
```cpp
--8<-- "examples/byte_container_with_subtype__set_subtype.cpp"
```
Output:
```json
--8<-- "examples/byte_container_with_subtype__set_subtype.output"
```
## Version history
Since version 3.8.0.

17
docs/mkdocs/docs/api/byte_container_with_subtype/subtype.md
View File

@@ -19,6 +19,23 @@ No-throw guarantee: this function never throws exceptions.
Constant.
## Examples
??? example
The example below demonstrates how the subtype can be retrieved with `subtype`. Note how `subtype_type(-1)` is
returned for container `c1`.
```cpp
--8<-- "examples/byte_container_with_subtype__subtype.cpp"
```
Output:
```json
--8<-- "examples/byte_container_with_subtype__subtype.output"
```
## Version history
- Added in version 3.8.0

16
docs/mkdocs/docs/api/json.md
View File

@@ -7,6 +7,22 @@ using json = basic_json<>;
This type is the default specialization of the [basic_json](basic_json/index.md) class which uses the standard template
types.
## Examples
??? example
The example below demonstrates how to use the type `nlohmann::json`.
```cpp
--8<-- "examples/README.cpp"
```
Output:
```json
--8<-- "examples/README.output"
```
## Version history
Since version 1.0.0.

8
docs/mkdocs/docs/api/json_pointer/index.md
View File

@@ -14,11 +14,11 @@ are the base for JSON patches.
`RefStringType`
: the string type used for the reference tokens making up the JSON pointer
## Notes
!!! warning "Deprecation"
For backwards compatibility `RefStringType` may also be a specialization of [`basic_json`](../basic_json/index.md) in
which case `string_t` will be deduced as [`basic_json::string_t`](../basic_json/string_t.md). This feature is deprecated
and may be removed in a future major version.
For backwards compatibility `RefStringType` may also be a specialization of [`basic_json`](../basic_json/index.md)
in which case `string_t` will be deduced as [`basic_json::string_t`](../basic_json/string_t.md). This feature is
deprecated and may be removed in a future major version.
## Member types

16
docs/mkdocs/docs/api/json_pointer/operator_string.md
View File

@@ -19,6 +19,22 @@ operator string_t() const
}
```
## Examples
??? example
The example shows how JSON Pointers can be implicitly converted to strings.
```cpp
--8<-- "examples/json_pointer__operator_string.cpp"
```
Output:
```json
--8<-- "examples/json_pointer__operator_string.output"
```
## Version history
- Since version 2.0.0.

16
docs/mkdocs/docs/api/json_pointer/string_t.md
View File

@@ -7,6 +7,22 @@ The string type used for the reference tokens making up the JSON pointer.
See [`basic_json::string_t`](../basic_json/string_t.md) for more information.
## Examples
??? example
The example shows the type `string_t` and its relation to `basic_json::string_t`.
```cpp
--8<-- "examples/json_pointer__string_t.cpp"
```
Output:
```json
--8<-- "examples/json_pointer__string_t.output"
```
## Version history
- Added in version 3.11.0.

16
docs/mkdocs/docs/api/json_sax/binary.md
View File

@@ -19,6 +19,22 @@ Whether parsing should proceed.
It is safe to move the passed binary value.
## Examples
??? example
.The example below shows how the SAX interface is used.
```cpp
--8<-- "examples/sax_parse__binary.cpp"
```
Output:
```json
--8<-- "examples/sax_parse__binary.output"
```
## Version history
- Added in version 3.8.0.

16
docs/mkdocs/docs/api/json_sax/boolean.md
View File

@@ -15,6 +15,22 @@ A boolean value was read.
Whether parsing should proceed.
## Examples
??? example
.The example below shows how the SAX interface is used.
```cpp
--8<-- "examples/sax_parse.cpp"
```
Output:
```json
--8<-- "examples/sax_parse.output"
```
## Version history
- Added in version 3.2.0.

16
docs/mkdocs/docs/api/json_sax/end_array.md
View File

@@ -10,6 +10,22 @@ The end of an array was read.
Whether parsing should proceed.
## Examples
??? example
.The example below shows how the SAX interface is used.
```cpp
--8<-- "examples/sax_parse.cpp"
```
Output:
```json
--8<-- "examples/sax_parse.output"
```
## Version history
- Added in version 3.2.0.

16
docs/mkdocs/docs/api/json_sax/end_object.md
View File

@@ -10,6 +10,22 @@ The end of an object was read.
Whether parsing should proceed.
## Examples
??? example
.The example below shows how the SAX interface is used.
```cpp
--8<-- "examples/sax_parse.cpp"
```
Output:
```json
--8<-- "examples/sax_parse.output"
```
## Version history
- Added in version 3.2.0.

16
docs/mkdocs/docs/api/json_sax/key.md
View File

@@ -19,6 +19,22 @@ Whether parsing should proceed.
It is safe to move the passed object key value.
## Examples
??? example
.The example below shows how the SAX interface is used.
```cpp
--8<-- "examples/sax_parse.cpp"
```
Output:
```json
--8<-- "examples/sax_parse.output"
```
## Version history
- Added in version 3.2.0.

16
docs/mkdocs/docs/api/json_sax/null.md
View File

@@ -10,6 +10,22 @@ A null value was read.
Whether parsing should proceed.
## Examples
??? example
.The example below shows how the SAX interface is used.
```cpp
--8<-- "examples/sax_parse.cpp"
```
Output:
```json
--8<-- "examples/sax_parse.output"
```
## Version history
- Added in version 3.2.0.

16
docs/mkdocs/docs/api/json_sax/number_float.md
View File

@@ -18,6 +18,22 @@ A floating-point number was read.
Whether parsing should proceed.
## Examples
??? example
.The example below shows how the SAX interface is used.
```cpp
--8<-- "examples/sax_parse.cpp"
```
Output:
```json
--8<-- "examples/sax_parse.output"
```
## Version history
- Added in version 3.2.0.

16
docs/mkdocs/docs/api/json_sax/number_integer.md
View File

@@ -15,6 +15,22 @@ An integer number was read.
Whether parsing should proceed.
## Examples
??? example
.The example below shows how the SAX interface is used.
```cpp
--8<-- "examples/sax_parse.cpp"
```
Output:
```json
--8<-- "examples/sax_parse.output"
```
## Version history
- Added in version 3.2.0.

16
docs/mkdocs/docs/api/json_sax/number_unsigned.md
View File

@@ -15,6 +15,22 @@ An unsigned integer number was read.
Whether parsing should proceed.
## Examples
??? example
.The example below shows how the SAX interface is used.
```cpp
--8<-- "examples/sax_parse.cpp"
```
Output:
```json
--8<-- "examples/sax_parse.output"
```
## Version history
- Added in version 3.2.0.

16
docs/mkdocs/docs/api/json_sax/parse_error.md
View File

@@ -23,6 +23,22 @@ A parse error occurred.
Whether parsing should proceed (**must return `#!cpp false`**).
## Examples
??? example
.The example below shows how the SAX interface is used.
```cpp
--8<-- "examples/sax_parse.cpp"
```
Output:
```json
--8<-- "examples/sax_parse.output"
```
## Version history
- Added in version 3.2.0.

16
docs/mkdocs/docs/api/json_sax/start_array.md
View File

@@ -19,6 +19,22 @@ Whether parsing should proceed.
Binary formats may report the number of elements.
## Examples
??? example
.The example below shows how the SAX interface is used.
```cpp
--8<-- "examples/sax_parse.cpp"
```
Output:
```json
--8<-- "examples/sax_parse.output"
```
## Version history
- Added in version 3.2.0.

16
docs/mkdocs/docs/api/json_sax/start_object.md
View File

@@ -19,6 +19,22 @@ Whether parsing should proceed.
Binary formats may report the number of elements.
## Examples
??? example
.The example below shows how the SAX interface is used.
```cpp
--8<-- "examples/sax_parse.cpp"
```
Output:
```json
--8<-- "examples/sax_parse.output"
```
## Version history
- Added in version 3.2.0.

16
docs/mkdocs/docs/api/json_sax/string.md
View File

@@ -19,6 +19,22 @@ Whether parsing should proceed.
It is safe to move the passed string value.
## Examples
??? example
.The example below shows how the SAX interface is used.
```cpp
--8<-- "examples/sax_parse.cpp"
```
Output:
```json
--8<-- "examples/sax_parse.output"
```
## Version history
- Added in version 3.2.0.

9
docs/mkdocs/docs/api/macros/index.md
View File

@@ -17,6 +17,8 @@ header. See also the [macro overview page](../../features/macros.md).
- [**JSON_HAS_CPP_11**<br>**JSON_HAS_CPP_14**<br>**JSON_HAS_CPP_17**<br>**JSON_HAS_CPP_20**](json_has_cpp_11.md) - set supported C++ standard
- [**JSON_HAS_FILESYSTEM**<br>**JSON_HAS_EXPERIMENTAL_FILESYSTEM**](json_has_filesystem.md) - control `std::filesystem` support
- [**JSON_HAS_RANGES**](json_has_ranges.md) - control `std::ranges` support
- [**JSON_HAS_THREE_WAY_COMPARISON**](json_has_three_way_comparison.md) - control 3-way comparison support
- [**JSON_NO_IO**](json_no_io.md) - switch off functions relying on certain C++ I/O headers
- [**JSON_SKIP_UNSUPPORTED_COMPILER_CHECK**](json_skip_unsupported_compiler_check.md) - do not warn about unsupported compilers
@@ -27,8 +29,15 @@ header. See also the [macro overview page](../../features/macros.md).
## Type conversions
- [**JSON_DISABLE_ENUM_SERIALIZATION**](json_disable_enum_serialization.md) - switch off default serialization/deserialization functions for enums
- [**JSON_USE_IMPLICIT_CONVERSIONS**](json_use_implicit_conversions.md) - control implicit conversions
<!-- comment-->
## Comparison behavior
- [**JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON**](json_use_legacy_discarded_value_comparison.md) -
control comparison of discarded values
## Serialization/deserialization macros
- [**NLOHMANN_DEFINE_TYPE_INTRUSIVE(type, member...)**<br>**NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT(type, member...)**](nlohmann_define_type_intrusive.md) - serialization/deserialization of types _with_ access to private variables

135
docs/mkdocs/docs/api/macros/json_disable_enum_serialization.md Normal file
View File

@@ -0,0 +1,135 @@
# JSON_DISABLE_ENUM_SERIALIZATION
```cpp
#define JSON_DISABLE_ENUM_SERIALIZATION
```
When defined, default serialization and deserialization functions for enums are excluded and have to be provided by the user, for example, using [`NLOHMANN_JSON_SERIALIZE_ENUM`](nlohmann_json_serialize_enum.md) (see [arbitrary type conversions](../../features/arbitrary_types.md) for more details).
Parsing or serializing an enum will result in a compiler error.
This works for both unscoped and scoped enums.
## Default definition
By default, `#!cpp JSON_DISABLE_ENUM_SERIALIZATION` is not defined.
```cpp
#undef JSON_DISABLE_ENUM_SERIALIZATION
```
## Examples
??? example "Example 1: Disabled behavior"
The code below forces the library **not** to create default serialization/deserialization functions `from_json` and `to_json`, meaning the code below **does not** compile.
```cpp
#define JSON_DISABLE_ENUM_SERIALIZATION 1
#include <nlohmann/json.hpp>
using json = nlohmann::json;
enum class Choice
{
first,
second,
};
int main()
{
// normally invokes to_json serialization function but with JSON_DISABLE_ENUM_SERIALIZATION defined, it does not
const json j = Choice::first;
// normally invokes from_json parse function but with JSON_DISABLE_ENUM_SERIALIZATION defined, it does not
Choice ch = j.get<Choice>();
}
```
??? example "Example 2: Serialize enum macro"
The code below forces the library **not** to create default serialization/deserialization functions `from_json` and `to_json`, but uses [`NLOHMANN_JSON_SERIALIZE_ENUM`](nlohmann_json_serialize_enum.md) to parse and serialize the enum.
```cpp
#define JSON_DISABLE_ENUM_SERIALIZATION 1
#include <nlohmann/json.hpp>
using json = nlohmann::json;
enum class Choice
{
first,
second,
};
NLOHMANN_JSON_SERIALIZE_ENUM(Choice,
{
{ Choice::first, "first" },
{ Choice::second, "second" },
})
int main()
{
// uses user-defined to_json function defined by macro
const json j = Choice::first;
// uses user-defined from_json function defined by macro
Choice ch = j.get<Choice>();
}
```
??? example "Example 3: User-defined serialization/deserialization functions"
The code below forces the library **not** to create default serialization/deserialization functions `from_json` and `to_json`, but uses user-defined functions to parse and serialize the enum.
```cpp
#define JSON_DISABLE_ENUM_SERIALIZATION 1
#include <nlohmann/json.hpp>
using json = nlohmann::json;
enum class Choice
{
first,
second,
};
void from_json(const json& j, Choice& ch)
{
auto value = j.get<std::string>();
if (value == "first")
{
ch = Choice::first;
}
else if (value == "second")
{
ch = Choice::second;
}
}
void to_json(json& j, const Choice& ch)
{
auto value = j.get<std::string>();
if (value == "first")
{
ch = Choice::first;
}
else if (value == "second")
{
ch = Choice::second;
}
}
int main()
{
// uses user-defined to_json function
const json j = Choice::first;
// uses user-defined from_json function
Choice ch = j.get<Choice>();
}
```
## See also
- [`NLOHMANN_JSON_SERIALIZE_ENUM`](nlohmann_json_serialize_enum.md)

13
docs/mkdocs/docs/api/macros/json_has_cpp_11.md
View File

@@ -23,6 +23,19 @@ The default value is detected based on preprocessor macros such as `#!cpp __cplu
- `#!cpp JSON_HAS_CPP_11` is always defined.
- All macros are undefined outside the library.
## Examples
??? example
The code below forces the library to use the C++14 standard:
```cpp
#define JSON_HAS_CPP_14 1
#include <nlohmann/json.hpp>
...
```
## Version history
- Added in version 3.10.5.

13
docs/mkdocs/docs/api/macros/json_has_filesystem.md
View File

@@ -25,6 +25,19 @@ The default value is detected based on the preprocessor macros `#!cpp __cpp_lib_
filesystem support.
- Both macros are undefined outside the library.
## Examples
??? example
The code below forces the library to use the header `<experimental/filesystem>`.
```cpp
#define JSON_HAS_EXPERIMENTAL_FILESYSTEM 1
#include <nlohmann/json.hpp>
...
```
## Version history
- Added in version 3.10.5.

18
docs/mkdocs/docs/api/macros/json_has_ranges.md Normal file
View File

@@ -0,0 +1,18 @@
# JSON_HAS_RANGES
```cpp
#define JSON_HAS_RANGES /* value */
```
This macro indicates whether the standard library has any support for ranges. Implies support for concepts.
Possible values are `1` when supported or `0` when unsupported.
## Default definition
The default value is detected based on the preprocessor macro `#!cpp __cpp_lib_ranges`.
When the macro is not defined, the library will define it to its default value.
## Version history
- Added in version 3.11.0.

19
docs/mkdocs/docs/api/macros/json_has_three_way_comparison.md Normal file
View File

@@ -0,0 +1,19 @@
# JSON_HAS_THREE_WAY_COMPARISON
```cpp
#define JSON_HAS_THREE_WAY_COMPARISON /* value */
```
This macro indicates whether the compiler and standard library support 3-way comparison.
Possible values are `1` when supported or `0` when unsupported.
## Default definition
The default value is detected based on the preprocessor macros `#!cpp __cpp_impl_three_way_comparison`
and `#!cpp __cpp_lib_three_way_comparison`.
When the macro is not defined, the library will define it to its default value.
## Version history
- Added in version 3.11.0.

14
docs/mkdocs/docs/api/macros/json_no_io.md
View File

@@ -16,6 +16,20 @@ By default, `#!cpp JSON_NO_IO` is not defined.
#undef JSON_NO_IO
```
## Examples
??? example
The code below forces the library not to use the headers `<cstdio>`, `<ios>`, `<iosfwd>`, `<istream>`, and
`<ostream>`.
```cpp
#define JSON_NO_IO 1
#include <nlohmann/json.hpp>
...
```
## Version history
- Added in version 3.10.0.

13
docs/mkdocs/docs/api/macros/json_noexception.md
View File

@@ -23,6 +23,19 @@ By default, the macro is not defined.
The explanatory [`what()`](https://en.cppreference.com/w/cpp/error/exception/what) string of exceptions is not
available for MSVC if exceptions are disabled, see [#2824](https://github.com/nlohmann/json/discussions/2824).
## Examples
??? example
The code below switches off exceptions in the library.
```cpp
#define JSON_NOEXCEPTION 1
#include <nlohmann/json.hpp>
...
```
## See also
- [Switch off exceptions](../../home/exceptions.md#switch-off-exceptions) for more information how to switch off exceptions

13
docs/mkdocs/docs/api/macros/json_skip_unsupported_compiler_check.md
View File

@@ -15,6 +15,19 @@ By default, the macro is not defined.
#undef JSON_SKIP_UNSUPPORTED_COMPILER_CHECK
```
## Examples
??? example
The code below switches off the check whether the compiler is supported.
```cpp
#define JSON_SKIP_UNSUPPORTED_COMPILER_CHECK 1
#include <nlohmann/json.hpp>
...
```
## Version history
Added in version 3.2.0.

61
docs/mkdocs/docs/api/macros/json_use_legacy_discarded_value_comparison.md Normal file
View File

@@ -0,0 +1,61 @@
# JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON
```cpp
#define JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON /* value */
```
This macro enables the (incorrect) legacy comparison behavior of discarded JSON values.
Possible values are `1` to enable or `0` to disable (default).
When enabled, comparisons involving at least one discarded JSON value yield results as follows:
| **Operator** | **Result** |
|--------------|---------------|
| `==` | `#!cpp false` |
| `!=` | `#!cpp true` |
| `<` | `#!cpp false` |
| `<=` | `#!cpp true` |
| `>=` | `#!cpp true` |
| `>` | `#!cpp false` |
Otherwise, comparisons involving at least one discarded JSON value always yield `#!cpp false`.
## Default definition
The default value is `0`.
```cpp
#define JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON 0
```
When the macro is not defined, the library will define it to its default value.
## Notes
!!! warning "Inconsistent behavior in C++20 and beyond"
When targeting C++20 or above, enabling the legacy comparison behavior is _strongly_
discouraged.
- The 3-way comparison operator (`<=>`) will always give the correct result
(`#!cpp std::partial_ordering::unordered`) regardless of the value of
`JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON`.
- Overloads for the equality and relational operators emulate the legacy behavior.
Code outside your control may use either 3-way comparison or the equality and
relational operators, resulting in inconsistent and unpredictable behavior.
See [`operator<=>`](../basic_json/operator_spaceship.md) for more information on 3-way
comparison.
!!! warning "Deprecation"
The legacy comparison behavior is deprecated and may be removed in a future major
version release.
New code should not depend on it and existing code should try to remove or rewrite
expressions relying on it.
## Version history
- Added in version 3.11.0.

1
docs/mkdocs/docs/api/macros/nlohmann_json_serialize_enum.md
View File

@@ -78,6 +78,7 @@ inline void from_json(const BasicJsonType& j, type& e);
## See also
- [Specializing enum conversion](../../features/enum_conversion.md)
- [`JSON_DISABLE_ENUM_SERIALIZATION`](json_disable_enum_serialization.md)
## Version history

17
docs/mkdocs/docs/api/macros/nlohmann_json_version_major.md
View File

@@ -13,6 +13,23 @@ These macros are defined by the library and contain the version numbers accordin
The macros are defined according to the current library version.
## Examples
??? example
The example below shows how `NLOHMANN_JSON_VERSION_MAJOR`, `NLOHMANN_JSON_VERSION_MINOR`, and
`NLOHMANN_JSON_VERSION_PATCH` are defined by the library.
```cpp
--8<-- "examples/nlohmann_json_version.cpp"
```
Output:
```json
--8<-- "examples/nlohmann_json_version.output"
```
## See also
- [meta](../basic_json/meta.md) - returns version information on the library

17
docs/mkdocs/docs/api/ordered_json.md
View File

@@ -6,9 +6,26 @@ using ordered_json = basic_json<ordered_map>;
This type preserves the insertion order of object keys.
## Examples
??? example
The example below demonstrates how `ordered_json` preserves the insertion order of object keys.
```cpp
--8<-- "examples/ordered_json.cpp"
```
Output:
```json
--8<-- "examples/ordered_json.output"
```
## See also
- [ordered_map](ordered_map.md)
- [Object Order](../features/object_order.md)
## Version history

4
docs/mkdocs/docs/css/custom.css Normal file
View File

@@ -0,0 +1,4 @@
/* disable ligatures in code and preformatted blocks */
code, pre {
font-variant-ligatures: none;
}

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