Unverified Commit 6a739205 authored by Niels Lohmann's avatar Niels Lohmann Committed by GitHub
Browse files

Complete documentation for 3.11.0 (#3464)

* 👥 update contributor and sponsor list

* 🚧 document BJData format

* 🚧 document BJData format

* 📝 clarified documentation of [json.exception.parse_error.112]

*  adjust titles

* 📝 add more examples

* 🚨 adjust warnings for index.md files

* 📝 add more examples

* 🔥 remove example for deprecated code

* 📝 add missing enum entry

* 📝 overwork table for binary formats

*  add test to create table for binary formats

* 📝 fix wording in example

* 📝 add more examples

* Update iterators.md (#3481)

*  add check for overloads to linter #3455

* 👥 update contributor list

* 📝 add more examples

* 📝 fix documentation

* 📝 add more examples

* 🎨 fix indentation

* 🔥 remove example for destructor

* 📝

 overwork documentation

* Updated BJData documentation, #3464 (#3493)

* update bjdata.md for #3464

* Minor edit

* Fix URL typo

* Add info on demoting ND array to a 1-D optimized array when singleton dimension
Co-authored-by: default avatarChaoqi Zhang <prncoprs@163.com>
Co-authored-by: default avatarQianqian Fang <fangqq@gmail.com>
parent a8a547d7
......@@ -54,7 +54,7 @@ There are myriads of [JSON](https://json.org) libraries out there, and each may
- **Trivial integration**. Our whole code consists of a single header file [`json.hpp`](https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json.hpp). That's it. No library, no subproject, no dependencies, no complex build system. The class is written in vanilla C++11. All in all, everything should require no adjustment of your compiler flags or project settings.
- **Serious testing**. Our class is heavily [unit-tested](https://github.com/nlohmann/json/tree/develop/tests/src) and covers [100%](https://coveralls.io/r/nlohmann/json) of the code, including all exceptional behavior. Furthermore, we checked with [Valgrind](https://valgrind.org) and the [Clang Sanitizers](https://clang.llvm.org/docs/index.html) that there are no memory leaks. [Google OSS-Fuzz](https://github.com/google/oss-fuzz/tree/master/projects/json) additionally runs fuzz tests against all parsers 24/7, effectively executing billions of tests so far. To maintain high quality, the project is following the [Core Infrastructure Initiative (CII) best practices](https://bestpractices.coreinfrastructure.org/projects/289).
- **Serious testing**. Our code is heavily [unit-tested](https://github.com/nlohmann/json/tree/develop/tests/src) and covers [100%](https://coveralls.io/r/nlohmann/json) of the code, including all exceptional behavior. Furthermore, we checked with [Valgrind](https://valgrind.org) and the [Clang Sanitizers](https://clang.llvm.org/docs/index.html) that there are no memory leaks. [Google OSS-Fuzz](https://github.com/google/oss-fuzz/tree/master/projects/json) additionally runs fuzz tests against all parsers 24/7, effectively executing billions of tests so far. To maintain high quality, the project is following the [Core Infrastructure Initiative (CII) best practices](https://bestpractices.coreinfrastructure.org/projects/289).
Other aspects were not so important to us:
......@@ -69,6 +69,10 @@ See the [contribution guidelines](https://github.com/nlohmann/json/blob/master/.
You can sponsor this library at [GitHub Sponsors](https://github.com/sponsors/nlohmann).
### :office: Corporate Sponsor
[![](https://upload.wikimedia.org/wikipedia/commons/thumb/9/9e/Codacy-logo-black.svg/320px-Codacy-logo-black.svg.png)](https://github.com/codacy)
### :label: Named Sponsors
- [Michael Hartmann](https://github.com/reFX-Mike)
......@@ -1599,6 +1603,20 @@ I deeply appreciate the help of the following people.
- [Dirk Stolle](https://github.com/striezel) fixed typos in documentation.
- [Daniel Albuschat](https://github.com/daniel-kun) corrected the parameter name in the `parse` documentation.
- [Prince Mendiratta](https://github.com/Prince-Mendiratta) fixed a link to the FAQ.
- [Florian Albrechtskirchinger](https://github.com/falbrechtskirchinger) implemented `std::string_view` support for object keys and made dozens of other improvements.
- [Qianqian Fang](https://github.com/fangq) implemented the Binary JData (BJData) format.
- [pketelsen](https://github.com/pketelsen) added macros `NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT` and `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT`.
- [DarkZeros](https://github.com/DarkZeros) adjusted to code to not clash with Arduino defines.
- [flagarde](https://github.com/flagarde) fixed the output of `meta()` for MSVC.
- [Giovanni Cerretani](https://github.com/gcerretani) fixed a check for `std::filesystem`.
- [Dimitris Apostolou](https://github.com/rex4539) fixed a typo.
- [Ferry Huberts](https://github.com/fhuberts) fixed a typo.
- [Michael Nosthoff](https://github.com/heinemml) fixed a typo.
- [JungHoon Lee](https://github.com/jhnlee) fixed a typo.
- [Faruk D.](https://github.com/fdiblen) fixed the CITATION.CFF file.
- [Andrea Cocito](https://github.com/puffetto) added a clarification on macro usage to the documentation.
- [Krzysiek Karbowiak](https://github.com/kkarbowiak) refactored the tests to use `CHECK_THROWS_WITH_AS`.
- [Chaoqi Zhang](https://github.com/prncoprs) fixed a typo.
Thanks a lot for helping out! Please [let me know](mailto:mail@nlohmann.me) if I forgot someone.
......@@ -1613,7 +1631,7 @@ The library itself consists of a single header file licensed under the MIT licen
- [**Artistic Style**](http://astyle.sourceforge.net) for automatic source code indentation
- [**Clang**](https://clang.llvm.org) for compilation with code sanitizers
- [**CMake**](https://cmake.org) for build automation
- [**Codacity**](https://www.codacy.com) for further [code analysis](https://www.codacy.com/app/nlohmann/json)
- [**Codacy**](https://www.codacy.com) for further [code analysis](https://www.codacy.com/app/nlohmann/json)
- [**Coveralls**](https://coveralls.io) to measure [code coverage](https://coveralls.io/github/nlohmann/json)
- [**Coverity Scan**](https://scan.coverity.com) for [static analysis](https://scan.coverity.com/projects/nlohmann-json)
- [**cppcheck**](http://cppcheck.sourceforge.net) for static analysis
......
#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;
}
{"bytes":[],"subtype":null}
{"bytes":[202,254,186,190],"subtype":null}
{"bytes":[202,254,186,190],"subtype":42}
#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';
}
before calling clear_subtype(): {"bytes":[202,254,186,190],"subtype":42}
after calling clear_subtype(): {"bytes":[202,254,186,190],"subtype":null}
#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;
}
c1.has_subtype() = false
c2.has_subtype() = true
#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';
}
before calling set_subtype(42): {"bytes":[202,254,186,190],"subtype":null}
after calling set_subtype(42): {"bytes":[202,254,186,190],"subtype":42}
#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));
}
c1.subtype() = 18446744073709551615
c2.subtype() = 42
#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;
}
[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}
#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;
}
one < two : true
three < four : false
#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';
}
[json.exception.type_error.316] invalid UTF-8 byte at index 2: 0xA9
string with replaced invalid characters: "ä�ü"
string with ignored invalid characters: "äü"
#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;
}
{
"compact": true,
"schema": 0
}
#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);
}
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment