From 7b6cf5918bc9a4b85d1e3fb9ff65348d6dce5d10 Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Fri, 5 Aug 2022 19:51:39 +0200 Subject: [PATCH] Documentation change (#3672) Co-authored-by: Florian Albrechtskirchinger --- .github/workflows/ubuntu.yml | 5 +- cmake/ci.cmake | 8 +- .../from_json__default_constructible.cpp | 37 ++++++ .../from_json__default_constructible.output | 1 + .../from_json__non_default_constructible.cpp | 53 ++++++++ ...rom_json__non_default_constructible.output | 1 + docs/examples/nlohmann_json_namespace.cpp | 14 +++ docs/examples/nlohmann_json_namespace.output | 1 + .../nlohmann_json_namespace_begin.c++17.cpp | 33 +++++ ...nlohmann_json_namespace_begin.c++17.output | 1 + docs/examples/to_json.cpp | 32 +++++ docs/examples/to_json.output | 1 + .../docs/api/adl_serializer/from_json.md | 40 +++++- .../mkdocs/docs/api/adl_serializer/to_json.md | 23 +++- docs/mkdocs/docs/api/basic_json/boolean_t.md | 4 +- .../docs/api/basic_json/json_serializer.md | 17 +++ .../api/basic_json/object_comparator_t.md | 3 +- docs/mkdocs/docs/api/basic_json/object_t.md | 3 +- docs/mkdocs/docs/api/basic_json/operator[].md | 6 +- .../mkdocs/docs/api/basic_json/operator_eq.md | 4 +- .../mkdocs/docs/api/basic_json/operator_ge.md | 13 +- .../mkdocs/docs/api/basic_json/operator_ne.md | 11 +- .../docs/api/basic_json/operator_spaceship.md | 12 +- docs/mkdocs/docs/api/basic_json/to_bjdata.md | 4 +- docs/mkdocs/docs/api/basic_json/value_t.md | 6 +- .../mkdocs/docs/api/basic_json/~basic_json.md | 2 + docs/mkdocs/docs/api/json_sax/binary.md | 2 +- docs/mkdocs/docs/api/json_sax/boolean.md | 2 +- docs/mkdocs/docs/api/json_sax/end_array.md | 2 +- docs/mkdocs/docs/api/json_sax/end_object.md | 2 +- docs/mkdocs/docs/api/json_sax/key.md | 2 +- docs/mkdocs/docs/api/json_sax/null.md | 2 +- docs/mkdocs/docs/api/json_sax/number_float.md | 2 +- .../docs/api/json_sax/number_integer.md | 2 +- .../docs/api/json_sax/number_unsigned.md | 2 +- docs/mkdocs/docs/api/json_sax/parse_error.md | 2 +- docs/mkdocs/docs/api/json_sax/start_array.md | 2 +- docs/mkdocs/docs/api/json_sax/start_object.md | 2 +- docs/mkdocs/docs/api/json_sax/string.md | 2 +- .../docs/api/macros/json_use_global_udls.md | 7 +- ...n_use_legacy_discarded_value_comparison.md | 17 ++- .../macros/nlohmann_define_type_intrusive.md | 10 +- .../nlohmann_define_type_non_intrusive.md | 9 +- .../api/macros/nlohmann_json_namespace.md | 27 +++- .../macros/nlohmann_json_namespace_begin.md | 28 +++-- docs/mkdocs/docs/api/operator_gtgt.md | 3 +- docs/mkdocs/docs/api/operator_literal_json.md | 5 +- .../docs/api/operator_literal_json_pointer.md | 4 +- docs/mkdocs/docs/api/operator_ltlt.md | 3 +- docs/mkdocs/docs/features/arbitrary_types.md | 2 +- .../docs/features/binary_formats/bjdata.md | 116 ++++++++---------- .../docs/features/binary_formats/bson.md | 4 +- .../docs/features/binary_formats/cbor.md | 15 +-- .../features/binary_formats/messagepack.md | 30 +++-- .../docs/features/binary_formats/ubjson.md | 45 +++---- docs/mkdocs/docs/features/comments.md | 4 +- .../element_access/unchecked_access.md | 3 +- .../docs/features/parsing/parse_exceptions.md | 13 +- .../docs/features/parsing/parser_callbacks.md | 20 +-- docs/mkdocs/docs/home/faq.md | 24 ++-- docs/mkdocs/docs/home/releases.md | 20 +-- docs/mkdocs/docs/integration/cmake.md | 2 +- .../docs/integration/package_managers.md | 60 ++++----- docs/mkdocs/requirements.txt | 44 +++---- docs/mkdocs/scripts/check_structure.py | 10 ++ 65 files changed, 583 insertions(+), 303 deletions(-) create mode 100644 docs/examples/from_json__default_constructible.cpp create mode 100644 docs/examples/from_json__default_constructible.output create mode 100644 docs/examples/from_json__non_default_constructible.cpp create mode 100644 docs/examples/from_json__non_default_constructible.output create mode 100644 docs/examples/nlohmann_json_namespace.cpp create mode 100644 docs/examples/nlohmann_json_namespace.output create mode 100644 docs/examples/nlohmann_json_namespace_begin.c++17.cpp create mode 100644 docs/examples/nlohmann_json_namespace_begin.c++17.output create mode 100644 docs/examples/to_json.cpp create mode 100644 docs/examples/to_json.output diff --git a/.github/workflows/ubuntu.yml b/.github/workflows/ubuntu.yml index c3e225873f..eff653cc40 100644 --- a/.github/workflows/ubuntu.yml +++ b/.github/workflows/ubuntu.yml @@ -151,9 +151,12 @@ jobs: ci_test_documentation: runs-on: ubuntu-latest + strategy: + matrix: + target: [ci_test_examples, ci_test_api_documentation] steps: - uses: actions/checkout@v3 - name: Run CMake run: cmake -S . -B build -DJSON_CI=On - name: Build - run: cmake --build build --target ci_test_documentation + run: cmake --build build --target ${{ matrix.target }} diff --git a/cmake/ci.cmake b/cmake/ci.cmake index 22cf090935..ee8d64af9f 100644 --- a/cmake/ci.cmake +++ b/cmake/ci.cmake @@ -953,12 +953,18 @@ add_custom_target(ci_icpc # test documentation ############################################################################### -add_custom_target(ci_test_documentation +add_custom_target(ci_test_examples COMMAND make CXX="${GCC_TOOL}" check_output_portable -j8 WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}/docs COMMENT "Check that all examples compile and create the desired output" ) +add_custom_target(ci_test_api_documentation + COMMAND ${Python3_EXECUTABLE} scripts/check_structure.py + WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}/docs/mkdocs + COMMENT "Lint the API documentation" +) + ############################################################################### # Clean up all generated files. ############################################################################### diff --git a/docs/examples/from_json__default_constructible.cpp b/docs/examples/from_json__default_constructible.cpp new file mode 100644 index 0000000000..17c0551c8c --- /dev/null +++ b/docs/examples/from_json__default_constructible.cpp @@ -0,0 +1,37 @@ +#include +#include + +using json = nlohmann::json; + +namespace ns +{ +// a simple struct to model a person +struct person +{ + std::string name; + std::string address; + int age; +}; +} // namespace ns + +namespace ns +{ +void from_json(const json& j, person& p) +{ + j.at("name").get_to(p.name); + j.at("address").get_to(p.address); + j.at("age").get_to(p.age); +} +} // namespace ns + +int main() +{ + json j; + j["name"] = "Ned Flanders"; + j["address"] = "744 Evergreen Terrace"; + j["age"] = 60; + + auto p = j.get(); + + std::cout << p.name << " (" << p.age << ") lives in " << p.address << std::endl; +} diff --git a/docs/examples/from_json__default_constructible.output b/docs/examples/from_json__default_constructible.output new file mode 100644 index 0000000000..b92452326d --- /dev/null +++ b/docs/examples/from_json__default_constructible.output @@ -0,0 +1 @@ +Ned Flanders (60) lives in 744 Evergreen Terrace diff --git a/docs/examples/from_json__non_default_constructible.cpp b/docs/examples/from_json__non_default_constructible.cpp new file mode 100644 index 0000000000..6cb86153cc --- /dev/null +++ b/docs/examples/from_json__non_default_constructible.cpp @@ -0,0 +1,53 @@ +#include +#include + +using json = nlohmann::json; + +namespace ns +{ +// a simple struct to model a person (not default constructible) +struct person +{ + person(std::string n, std::string a, int aa) + : name(std::move(n)), address(std::move(a)), age(aa) + {} + + std::string name; + std::string address; + int age; +}; +} // namespace ns + +namespace nlohmann +{ +template <> +struct adl_serializer +{ + static ns::person from_json(const json& j) + { + return {j.at("name"), j.at("address"), j.at("age")}; + } + + // Here's the catch! You must provide a to_json method! Otherwise, you + // will not be able to convert person to json, since you fully + // specialized adl_serializer on that type + static void to_json(json& j, ns::person p) + { + j["name"] = p.name; + j["address"] = p.address; + j["age"] = p.age; + } +}; +} // namespace nlohmann + +int main() +{ + json j; + j["name"] = "Ned Flanders"; + j["address"] = "744 Evergreen Terrace"; + j["age"] = 60; + + auto p = j.get(); + + std::cout << p.name << " (" << p.age << ") lives in " << p.address << std::endl; +} diff --git a/docs/examples/from_json__non_default_constructible.output b/docs/examples/from_json__non_default_constructible.output new file mode 100644 index 0000000000..b92452326d --- /dev/null +++ b/docs/examples/from_json__non_default_constructible.output @@ -0,0 +1 @@ +Ned Flanders (60) lives in 744 Evergreen Terrace diff --git a/docs/examples/nlohmann_json_namespace.cpp b/docs/examples/nlohmann_json_namespace.cpp new file mode 100644 index 0000000000..4bad91f4be --- /dev/null +++ b/docs/examples/nlohmann_json_namespace.cpp @@ -0,0 +1,14 @@ +#include +#include + +// possible use case: use NLOHMANN_JSON_NAMESPACE instead of nlohmann +using json = NLOHMANN_JSON_NAMESPACE::json; + +// macro needed to output the NLOHMANN_JSON_NAMESPACE as string literal +#define Q(x) #x +#define QUOTE(x) Q(x) + +int main() +{ + std::cout << QUOTE(NLOHMANN_JSON_NAMESPACE) << std::endl; +} diff --git a/docs/examples/nlohmann_json_namespace.output b/docs/examples/nlohmann_json_namespace.output new file mode 100644 index 0000000000..d5a8b59d62 --- /dev/null +++ b/docs/examples/nlohmann_json_namespace.output @@ -0,0 +1 @@ +nlohmann::json_v3_11_1 diff --git a/docs/examples/nlohmann_json_namespace_begin.c++17.cpp b/docs/examples/nlohmann_json_namespace_begin.c++17.cpp new file mode 100644 index 0000000000..9385d593d5 --- /dev/null +++ b/docs/examples/nlohmann_json_namespace_begin.c++17.cpp @@ -0,0 +1,33 @@ +#include +#include +#include + +// partial specialization (see https://json.nlohmann.me/features/arbitrary_types/) +NLOHMANN_JSON_NAMESPACE_BEGIN +template +struct adl_serializer> +{ + static void to_json(json& j, const std::optional& opt) + { + if (opt == std::nullopt) + { + j = nullptr; + } + else + { + j = *opt; + } + } +}; +NLOHMANN_JSON_NAMESPACE_END + +int main() +{ + std::optional o1 = 1; + std::optional o2 = std::nullopt; + + NLOHMANN_JSON_NAMESPACE::json j; + j.push_back(o1); + j.push_back(o2); + std::cout << j << std::endl; +} diff --git a/docs/examples/nlohmann_json_namespace_begin.c++17.output b/docs/examples/nlohmann_json_namespace_begin.c++17.output new file mode 100644 index 0000000000..b29d3b93ca --- /dev/null +++ b/docs/examples/nlohmann_json_namespace_begin.c++17.output @@ -0,0 +1 @@ +[1,null] diff --git a/docs/examples/to_json.cpp b/docs/examples/to_json.cpp new file mode 100644 index 0000000000..1f82a4de4e --- /dev/null +++ b/docs/examples/to_json.cpp @@ -0,0 +1,32 @@ +#include +#include + +using json = nlohmann::json; + +namespace ns +{ +// a simple struct to model a person +struct person +{ + std::string name; + std::string address; + int age; +}; +} // namespace ns + +namespace ns +{ +void to_json(json& j, const person& p) +{ + j = json{ {"name", p.name}, {"address", p.address}, {"age", p.age} }; +} +} // namespace ns + +int main() +{ + ns::person p = {"Ned Flanders", "744 Evergreen Terrace", 60}; + + json j = p; + + std::cout << j << std::endl; +} diff --git a/docs/examples/to_json.output b/docs/examples/to_json.output new file mode 100644 index 0000000000..e9c5bf381d --- /dev/null +++ b/docs/examples/to_json.output @@ -0,0 +1 @@ +{"address":"744 Evergreen Terrace","age":60,"name":"Ned Flanders"} diff --git a/docs/mkdocs/docs/api/adl_serializer/from_json.md b/docs/mkdocs/docs/api/adl_serializer/from_json.md index 7657855a36..ba932e9e77 100644 --- a/docs/mkdocs/docs/api/adl_serializer/from_json.md +++ b/docs/mkdocs/docs/api/adl_serializer/from_json.md @@ -14,8 +14,8 @@ noexcept(::nlohmann::from_json(std::forward(j), detail::identity_ -> decltype(::nlohmann::from_json(std::forward(j), detail::identity_tag {})) ``` -This function is usually called by the [`get()`](../basic_json/get.md) function of the -[basic_json](../basic_json) class (either explicit or via conversion operators). +This function is usually called by the [`get()`](../basic_json/get.md) function of the [basic_json](../basic_json) +class (either explicitly or via the conversion operators). 1. This function is chosen for default-constructible value types. 2. This function is chosen for value types which are not default-constructible. @@ -32,9 +32,41 @@ This function is usually called by the [`get()`](../basic_json/get.md) function Copy of the JSON value, converted to `ValueType` -!!! note +## Examples - This documentation page is a stub. +??? example "Example: (1) Default-constructible type" + + The example below shows how a `from_json` function can be implemented for a user-defined type. This function is + called by the `adl_serializer` when `get()` is called. + + ```cpp + --8<-- "examples/from_json__default_constructible.cpp" + ``` + + Output: + + ```json + --8<-- "examples/from_json__default_constructible.output" + ``` + +??? example "Example: (2) Non-default-constructible type" + + The example below shows how a `from_json` is implemented as part of a specialization of the `adl_serializer` to + realize the conversion of a non-default-constructible type. + + ```cpp + --8<-- "examples/from_json__non_default_constructible.cpp" + ``` + + Output: + + ```json + --8<-- "examples/from_json__non_default_constructible.output" + ``` + +## See also + +- [to_json](to_json.md) ## Version history diff --git a/docs/mkdocs/docs/api/adl_serializer/to_json.md b/docs/mkdocs/docs/api/adl_serializer/to_json.md index d39f72525a..f8419bd81f 100644 --- a/docs/mkdocs/docs/api/adl_serializer/to_json.md +++ b/docs/mkdocs/docs/api/adl_serializer/to_json.md @@ -17,9 +17,26 @@ This function is usually called by the constructors of the [basic_json](../basic `val` (in) : value to read from -!!! note - - This documentation page is a stub. +## Examples + +??? example + + The example below shows how a `to_json` function can be implemented for a user-defined type. This function is called + by the `adl_serializer` when the constructor `basic_json(ns::person)` is called. + + ```cpp + --8<-- "examples/to_json.cpp" + ``` + + Output: + + ```json + --8<-- "examples/to_json.output" + ``` + +## See also + +- [from_json](from_json.md) ## Version history diff --git a/docs/mkdocs/docs/api/basic_json/boolean_t.md b/docs/mkdocs/docs/api/basic_json/boolean_t.md index 3ca613148d..e3a7830270 100644 --- a/docs/mkdocs/docs/api/basic_json/boolean_t.md +++ b/docs/mkdocs/docs/api/basic_json/boolean_t.md @@ -6,8 +6,8 @@ using boolean_t = BooleanType; The type used to store JSON booleans. -[RFC 8259](https://tools.ietf.org/html/rfc8259) implicitly describes a boolean as a type which differentiates the two literals -`#!json true` and `#!json false`. +[RFC 8259](https://tools.ietf.org/html/rfc8259) implicitly describes a boolean as a type which differentiates the two +literals `#!json true` and `#!json false`. To store objects in C++, a type is defined by the template parameter `BooleanType` which chooses the type to use. diff --git a/docs/mkdocs/docs/api/basic_json/json_serializer.md b/docs/mkdocs/docs/api/basic_json/json_serializer.md index f091155671..b8b67c5cc7 100644 --- a/docs/mkdocs/docs/api/basic_json/json_serializer.md +++ b/docs/mkdocs/docs/api/basic_json/json_serializer.md @@ -19,6 +19,23 @@ using json_serializer = JSONSerializer; The default values for `json_serializer` is [`adl_serializer`](../adl_serializer). +## Examples + +??? example + + The example below shows how a conversion of a non-default-constructible type is implemented via a specialization of + the `adl_serializer`. + + ```cpp + --8<-- "examples/from_json__non_default_constructible.cpp" + ``` + + Output: + + ```json + --8<-- "examples/from_json__non_default_constructible.output" + ``` + ## Version history - Since version 2.0.0. diff --git a/docs/mkdocs/docs/api/basic_json/object_comparator_t.md b/docs/mkdocs/docs/api/basic_json/object_comparator_t.md index 496a56267e..d41b982297 100644 --- a/docs/mkdocs/docs/api/basic_json/object_comparator_t.md +++ b/docs/mkdocs/docs/api/basic_json/object_comparator_t.md @@ -28,4 +28,5 @@ and [`default_object_comparator_t`](default_object_comparator_t.md) otherwise. ## Version history - Added in version 3.0.0. -- Changed to be conditionally defined as `#!cpp typename object_t::key_compare` or `default_object_comparator_t` in version 3.11.0. +- Changed to be conditionally defined as `#!cpp typename object_t::key_compare` or `default_object_comparator_t` in + version 3.11.0. diff --git a/docs/mkdocs/docs/api/basic_json/object_t.md b/docs/mkdocs/docs/api/basic_json/object_t.md index 67b3bb78c8..39f68b0891 100644 --- a/docs/mkdocs/docs/api/basic_json/object_t.md +++ b/docs/mkdocs/docs/api/basic_json/object_t.md @@ -90,7 +90,8 @@ Objects are stored as pointers in a `basic_json` type. That is, for any access t The order name/value pairs are added to the object is *not* preserved by the library. Therefore, iterating an object may return name/value pairs in a different order than they were originally stored. In fact, keys will be traversed in alphabetical order as `std::map` with `std::less` is used by default. Please note this behavior conforms to -[RFC 8259](https://tools.ietf.org/html/rfc8259), because any order implements the specified "unordered" nature of JSON objects. +[RFC 8259](https://tools.ietf.org/html/rfc8259), because any order implements the specified "unordered" nature of JSON +objects. ## Examples diff --git a/docs/mkdocs/docs/api/basic_json/operator[].md b/docs/mkdocs/docs/api/basic_json/operator[].md index ebc737e4bc..51dd8588cb 100644 --- a/docs/mkdocs/docs/api/basic_json/operator[].md +++ b/docs/mkdocs/docs/api/basic_json/operator[].md @@ -21,7 +21,8 @@ const_reference operator[](const json_pointer& ptr) const; ``` 1. Returns a reference to the array element at specified location `idx`. -2. Returns a reference to the object element with specified key `key`. The non-const qualified overload takes the key by value. +2. Returns a reference to the object element with specified key `key`. The non-const qualified overload takes the key by + value. 3. See 2. This overload is only available if `KeyType` is comparable with `#!cpp typename object_t::key_type` and `#!cpp typename object_comparator_t::is_transparent` denotes a type. 4. Returns a reference to the element with specified JSON pointer `ptr`. @@ -234,6 +235,7 @@ Strong exception safety: if an exception occurs, the original value stays intact ## Version history 1. Added in version 1.0.0. -2. Added in version 1.0.0. Added overloads for `T* key` in version 1.1.0. Removed overloads for `T* key` (replaced by 3) in version 3.11.0. +2. Added in version 1.0.0. Added overloads for `T* key` in version 1.1.0. Removed overloads for `T* key` (replaced by 3) + in version 3.11.0. 3. Added in version 3.11.0. 4. Added in version 2.0.0. diff --git a/docs/mkdocs/docs/api/basic_json/operator_eq.md b/docs/mkdocs/docs/api/basic_json/operator_eq.md index b4d61b6371..a2ce6155c3 100644 --- a/docs/mkdocs/docs/api/basic_json/operator_eq.md +++ b/docs/mkdocs/docs/api/basic_json/operator_eq.md @@ -20,8 +20,8 @@ class basic_json { ``` 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==`. + - 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. 2. Compares a JSON value and a scalar or a scalar and a JSON value for equality by converting the diff --git a/docs/mkdocs/docs/api/basic_json/operator_ge.md b/docs/mkdocs/docs/api/basic_json/operator_ge.md index 847f6ca656..d4e2fb4a50 100644 --- a/docs/mkdocs/docs/api/basic_json/operator_ge.md +++ b/docs/mkdocs/docs/api/basic_json/operator_ge.md @@ -11,15 +11,14 @@ template bool operator>=(ScalarType lhs, const const_reference rhs) noexcept; // (2) ``` -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. +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)` (see [**operator<**](operator_lt.md)). -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. +2. Compares whether 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 diff --git a/docs/mkdocs/docs/api/basic_json/operator_ne.md b/docs/mkdocs/docs/api/basic_json/operator_ne.md index f5d989b506..982a06764d 100644 --- a/docs/mkdocs/docs/api/basic_json/operator_ne.md +++ b/docs/mkdocs/docs/api/basic_json/operator_ne.md @@ -20,13 +20,12 @@ class basic_json { ``` 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). + - 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. +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 diff --git a/docs/mkdocs/docs/api/basic_json/operator_spaceship.md b/docs/mkdocs/docs/api/basic_json/operator_spaceship.md index f5bf1cf358..9e91d0d2da 100644 --- a/docs/mkdocs/docs/api/basic_json/operator_spaceship.md +++ b/docs/mkdocs/docs/api/basic_json/operator_spaceship.md @@ -12,16 +12,16 @@ class basic_json { 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 + - 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<=>`. - - 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 + For instance, comparing an integer and a floating-point value will 3-way compare the first value converted 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). +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 diff --git a/docs/mkdocs/docs/api/basic_json/to_bjdata.md b/docs/mkdocs/docs/api/basic_json/to_bjdata.md index 1ea8505239..48598a5e61 100644 --- a/docs/mkdocs/docs/api/basic_json/to_bjdata.md +++ b/docs/mkdocs/docs/api/basic_json/to_bjdata.md @@ -13,8 +13,8 @@ static void to_bjdata(const basic_json& j, detail::output_adapter 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. +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. diff --git a/docs/mkdocs/docs/api/basic_json/value_t.md b/docs/mkdocs/docs/api/basic_json/value_t.md index f835740830..1505e02d08 100644 --- a/docs/mkdocs/docs/api/basic_json/value_t.md +++ b/docs/mkdocs/docs/api/basic_json/value_t.md @@ -52,10 +52,8 @@ functions [`is_null`](is_null.md), [`is_object`](is_object.md), [`is_array`](is_ `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: + 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 diff --git a/docs/mkdocs/docs/api/basic_json/~basic_json.md b/docs/mkdocs/docs/api/basic_json/~basic_json.md index c5c74a5257..64e9440063 100644 --- a/docs/mkdocs/docs/api/basic_json/~basic_json.md +++ b/docs/mkdocs/docs/api/basic_json/~basic_json.md @@ -14,6 +14,8 @@ No-throw guarantee: this member function never throws exceptions. Linear. + + ## Version history - Added in version 1.0.0. diff --git a/docs/mkdocs/docs/api/json_sax/binary.md b/docs/mkdocs/docs/api/json_sax/binary.md index 753e99c00c..fc0980e20b 100644 --- a/docs/mkdocs/docs/api/json_sax/binary.md +++ b/docs/mkdocs/docs/api/json_sax/binary.md @@ -23,7 +23,7 @@ It is safe to move the passed binary value. ??? example - .The example below shows how the SAX interface is used. + The example below shows how the SAX interface is used. ```cpp --8<-- "examples/sax_parse__binary.cpp" diff --git a/docs/mkdocs/docs/api/json_sax/boolean.md b/docs/mkdocs/docs/api/json_sax/boolean.md index 78163b331a..fdf2945622 100644 --- a/docs/mkdocs/docs/api/json_sax/boolean.md +++ b/docs/mkdocs/docs/api/json_sax/boolean.md @@ -19,7 +19,7 @@ Whether parsing should proceed. ??? example - .The example below shows how the SAX interface is used. + The example below shows how the SAX interface is used. ```cpp --8<-- "examples/sax_parse.cpp" diff --git a/docs/mkdocs/docs/api/json_sax/end_array.md b/docs/mkdocs/docs/api/json_sax/end_array.md index 46b4c7a4bb..9c12e40a5e 100644 --- a/docs/mkdocs/docs/api/json_sax/end_array.md +++ b/docs/mkdocs/docs/api/json_sax/end_array.md @@ -14,7 +14,7 @@ Whether parsing should proceed. ??? example - .The example below shows how the SAX interface is used. + The example below shows how the SAX interface is used. ```cpp --8<-- "examples/sax_parse.cpp" diff --git a/docs/mkdocs/docs/api/json_sax/end_object.md b/docs/mkdocs/docs/api/json_sax/end_object.md index 8df0ab4e1a..601c94a4ab 100644 --- a/docs/mkdocs/docs/api/json_sax/end_object.md +++ b/docs/mkdocs/docs/api/json_sax/end_object.md @@ -14,7 +14,7 @@ Whether parsing should proceed. ??? example - .The example below shows how the SAX interface is used. + The example below shows how the SAX interface is used. ```cpp --8<-- "examples/sax_parse.cpp" diff --git a/docs/mkdocs/docs/api/json_sax/key.md b/docs/mkdocs/docs/api/json_sax/key.md index ebd3ae2b23..31fd6c1d12 100644 --- a/docs/mkdocs/docs/api/json_sax/key.md +++ b/docs/mkdocs/docs/api/json_sax/key.md @@ -23,7 +23,7 @@ It is safe to move the passed object key value. ??? example - .The example below shows how the SAX interface is used. + The example below shows how the SAX interface is used. ```cpp --8<-- "examples/sax_parse.cpp" diff --git a/docs/mkdocs/docs/api/json_sax/null.md b/docs/mkdocs/docs/api/json_sax/null.md index 71b2a458a1..9354ede6ca 100644 --- a/docs/mkdocs/docs/api/json_sax/null.md +++ b/docs/mkdocs/docs/api/json_sax/null.md @@ -14,7 +14,7 @@ Whether parsing should proceed. ??? example - .The example below shows how the SAX interface is used. + The example below shows how the SAX interface is used. ```cpp --8<-- "examples/sax_parse.cpp" diff --git a/docs/mkdocs/docs/api/json_sax/number_float.md b/docs/mkdocs/docs/api/json_sax/number_float.md index e1b3fb60f2..17799401ee 100644 --- a/docs/mkdocs/docs/api/json_sax/number_float.md +++ b/docs/mkdocs/docs/api/json_sax/number_float.md @@ -22,7 +22,7 @@ Whether parsing should proceed. ??? example - .The example below shows how the SAX interface is used. + The example below shows how the SAX interface is used. ```cpp --8<-- "examples/sax_parse.cpp" diff --git a/docs/mkdocs/docs/api/json_sax/number_integer.md b/docs/mkdocs/docs/api/json_sax/number_integer.md index 8628a655c6..5c3cb4f316 100644 --- a/docs/mkdocs/docs/api/json_sax/number_integer.md +++ b/docs/mkdocs/docs/api/json_sax/number_integer.md @@ -19,7 +19,7 @@ Whether parsing should proceed. ??? example - .The example below shows how the SAX interface is used. + The example below shows how the SAX interface is used. ```cpp --8<-- "examples/sax_parse.cpp" diff --git a/docs/mkdocs/docs/api/json_sax/number_unsigned.md b/docs/mkdocs/docs/api/json_sax/number_unsigned.md index 7b59748238..0ac2500373 100644 --- a/docs/mkdocs/docs/api/json_sax/number_unsigned.md +++ b/docs/mkdocs/docs/api/json_sax/number_unsigned.md @@ -19,7 +19,7 @@ Whether parsing should proceed. ??? example - .The example below shows how the SAX interface is used. + The example below shows how the SAX interface is used. ```cpp --8<-- "examples/sax_parse.cpp" diff --git a/docs/mkdocs/docs/api/json_sax/parse_error.md b/docs/mkdocs/docs/api/json_sax/parse_error.md index d4405d09e5..e41cb67ff2 100644 --- a/docs/mkdocs/docs/api/json_sax/parse_error.md +++ b/docs/mkdocs/docs/api/json_sax/parse_error.md @@ -27,7 +27,7 @@ Whether parsing should proceed (**must return `#!cpp false`**). ??? example - .The example below shows how the SAX interface is used. + The example below shows how the SAX interface is used. ```cpp --8<-- "examples/sax_parse.cpp" diff --git a/docs/mkdocs/docs/api/json_sax/start_array.md b/docs/mkdocs/docs/api/json_sax/start_array.md index 8ef10a4ab7..cf2b8cf565 100644 --- a/docs/mkdocs/docs/api/json_sax/start_array.md +++ b/docs/mkdocs/docs/api/json_sax/start_array.md @@ -23,7 +23,7 @@ Binary formats may report the number of elements. ??? example - .The example below shows how the SAX interface is used. + The example below shows how the SAX interface is used. ```cpp --8<-- "examples/sax_parse.cpp" diff --git a/docs/mkdocs/docs/api/json_sax/start_object.md b/docs/mkdocs/docs/api/json_sax/start_object.md index 24fedffc3e..491815deb3 100644 --- a/docs/mkdocs/docs/api/json_sax/start_object.md +++ b/docs/mkdocs/docs/api/json_sax/start_object.md @@ -23,7 +23,7 @@ Binary formats may report the number of elements. ??? example - .The example below shows how the SAX interface is used. + The example below shows how the SAX interface is used. ```cpp --8<-- "examples/sax_parse.cpp" diff --git a/docs/mkdocs/docs/api/json_sax/string.md b/docs/mkdocs/docs/api/json_sax/string.md index 1cb6014ac0..dcffb5f612 100644 --- a/docs/mkdocs/docs/api/json_sax/string.md +++ b/docs/mkdocs/docs/api/json_sax/string.md @@ -23,7 +23,7 @@ It is safe to move the passed string value. ??? example - .The example below shows how the SAX interface is used. + The example below shows how the SAX interface is used. ```cpp --8<-- "examples/sax_parse.cpp" diff --git a/docs/mkdocs/docs/api/macros/json_use_global_udls.md b/docs/mkdocs/docs/api/macros/json_use_global_udls.md index dc9b55f624..69db9e77c3 100644 --- a/docs/mkdocs/docs/api/macros/json_use_global_udls.md +++ b/docs/mkdocs/docs/api/macros/json_use_global_udls.md @@ -21,8 +21,7 @@ When the macro is not defined, the library will define it to its default value. !!! info "Future behavior change" - The user-defined string literals will be removed from the global namespace in the next major release of the - library. + The user-defined string literals will be removed from the global namespace in the next major release of the library. To prepare existing code, define `JSON_USE_GLOBAL_UDLS` to `0` and bring the string literals into scope where needed. Refer to any of the [string literals](#see-also) for details. @@ -30,8 +29,8 @@ When the macro is not defined, the library will define it to its default value. !!! hint "CMake option" The placement of user-defined string literals can also be controlled with the CMake option - [`JSON_GlobalUDLs`](../../integration/cmake.md#json_globaludls) (`OFF` by default) - which defines `JSON_USE_GLOBAL_UDLS` accordingly. + [`JSON_GlobalUDLs`](../../integration/cmake.md#json_globaludls) (`ON` by default) which defines + `JSON_USE_GLOBAL_UDLS` accordingly. ## Examples diff --git a/docs/mkdocs/docs/api/macros/json_use_legacy_discarded_value_comparison.md b/docs/mkdocs/docs/api/macros/json_use_legacy_discarded_value_comparison.md index bdb0a4607b..bc1d1434a7 100644 --- a/docs/mkdocs/docs/api/macros/json_use_legacy_discarded_value_comparison.md +++ b/docs/mkdocs/docs/api/macros/json_use_legacy_discarded_value_comparison.md @@ -4,8 +4,8 @@ #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). +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: @@ -42,19 +42,16 @@ When the macro is not defined, the library will define it to its default value. `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. + 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. + 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. + 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. + New code should not depend on it and existing code should try to remove or rewrite expressions relying on it. !!! hint "CMake option" diff --git a/docs/mkdocs/docs/api/macros/nlohmann_define_type_intrusive.md b/docs/mkdocs/docs/api/macros/nlohmann_define_type_intrusive.md index 9a14ad7231..afd09c6db3 100644 --- a/docs/mkdocs/docs/api/macros/nlohmann_define_type_intrusive.md +++ b/docs/mkdocs/docs/api/macros/nlohmann_define_type_intrusive.md @@ -7,9 +7,9 @@ These macros can be used to simplify the serialization/deserialization of types if you want to use a JSON object as serialization and want to use the member variable names as object keys in that object. The macro is to be defined -**inside** the class/struct to create code for. -Unlike [`NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE`](nlohmann_define_type_non_intrusive.md), it can access private members. -The first parameter is the name of the class/struct, and all remaining parameters name the members. +**inside** the class/struct to create code for. Unlike +[`NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE`](nlohmann_define_type_non_intrusive.md), it can access private members. The first +parameter is the name of the class/struct, and all remaining parameters name the members. 1. Will use [`at`](../basic_json/at.md) during deserialization and will throw [`out_of_range.403`](../../home/exceptions.md#jsonexceptionout_of_range403) if a key is missing in the JSON object. @@ -40,8 +40,8 @@ See examples below for the concrete generated code. !!! info "Prerequisites" - 1. The type `type` must be default constructible. See [How can I use `get()` for non-default constructible/non-copyable types?][GetNonDefNonCopy] - for how to overcome this limitation. + 1. The type `type` must be default constructible. See [How can I use `get()` for non-default + constructible/non-copyable types?][GetNonDefNonCopy] for how to overcome this limitation. 2. The macro must be used inside the type (class/struct). [GetNonDefNonCopy]: ../../features/arbitrary_types.md#how-can-i-use-get-for-non-default-constructiblenon-copyable-types diff --git a/docs/mkdocs/docs/api/macros/nlohmann_define_type_non_intrusive.md b/docs/mkdocs/docs/api/macros/nlohmann_define_type_non_intrusive.md index 28b3589525..70cf934fcc 100644 --- a/docs/mkdocs/docs/api/macros/nlohmann_define_type_non_intrusive.md +++ b/docs/mkdocs/docs/api/macros/nlohmann_define_type_non_intrusive.md @@ -7,9 +7,9 @@ These macros can be used to simplify the serialization/deserialization of types if you want to use a JSON object as serialization and want to use the member variable names as object keys in that object. The macro is to be defined -**outside** the class/struct to create code for, but **inside** its namespace. -Unlike [`NLOHMANN_DEFINE_TYPE_INTRUSIVE`](nlohmann_define_type_intrusive.md), it **cannot** access private members. -The first parameter is the name of the class/struct, and all remaining parameters name the members. +**outside** the class/struct to create code for, but **inside** its namespace. Unlike +[`NLOHMANN_DEFINE_TYPE_INTRUSIVE`](nlohmann_define_type_intrusive.md), it **cannot** access private members. The first +parameter is the name of the class/struct, and all remaining parameters name the members. 1. Will use [`at`](../basic_json/at.md) during deserialization and will throw [`out_of_range.403`](../../home/exceptions.md#jsonexceptionout_of_range403) if a key is missing in the JSON object. @@ -103,7 +103,8 @@ See examples below for the concrete generated code. - `ns::person` is default-constructible. This is a requirement for using the macro. - `ns::person` has only public member variables. This makes `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT` applicable. - - The macro `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT` is used _outside_ the class, but _inside_ its namespace `ns`. + - The macro `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT` is used _outside_ the class, but _inside_ its + namespace `ns`. - A missing key "age" in the deserialization does not yield an exception. Instead, the default value `-1` is used. The macro is equivalent to: diff --git a/docs/mkdocs/docs/api/macros/nlohmann_json_namespace.md b/docs/mkdocs/docs/api/macros/nlohmann_json_namespace.md index d76bffb812..b44538e181 100644 --- a/docs/mkdocs/docs/api/macros/nlohmann_json_namespace.md +++ b/docs/mkdocs/docs/api/macros/nlohmann_json_namespace.md @@ -4,19 +4,34 @@ #define NLOHMANN_JSON_NAMESPACE ``` -This macro evaluates to the full name of the `nlohmann` namespace, including -the name of a versioned and ABI-tagged inline namespace. Use this macro to -unambiguously refer to the `nlohmann` namespace. +This macro evaluates to the full name of the `nlohmann` namespace, including the name of a versioned and ABI-tagged +inline namespace. Use this macro to unambiguously refer to the `nlohmann` namespace. ## Default definition -The default value consists of a prefix, a version string, and optional ABI tags -depending on whether ABI-affecting macros are defined (e.g., -[`JSON_DIAGNOSTICS`](json_diagnostics.md), and +The default value consists of a prefix, a version string, and optional ABI tags depending on whether ABI-affecting +macros are defined (e.g., [`JSON_DIAGNOSTICS`](json_diagnostics.md), and [`JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON`](json_use_legacy_discarded_value_comparison.md)). When the macro is not defined, the library will define it to its default value. +## Examples + +??? example + + The example shows how to use `NLOHMANN_JSON_NAMESPACE` instead of just `nlohmann`, as well as how to output the value + of `NLOHMANN_JSON_NAMESPACE`. + + ```cpp + --8<-- "examples/nlohmann_json_namespace.cpp" + ``` + + Output: + + ```json + --8<-- "examples/nlohmann_json_namespace.output" + ``` + ## See also - [`NLOHMANN_JSON_NAMESPACE_BEGIN, NLOHMANN_JSON_NAMESPACE_END`](nlohmann_json_namespace_begin.md) diff --git a/docs/mkdocs/docs/api/macros/nlohmann_json_namespace_begin.md b/docs/mkdocs/docs/api/macros/nlohmann_json_namespace_begin.md index 83844b502c..5fd8fba2d4 100644 --- a/docs/mkdocs/docs/api/macros/nlohmann_json_namespace_begin.md +++ b/docs/mkdocs/docs/api/macros/nlohmann_json_namespace_begin.md @@ -5,9 +5,8 @@ #define NLOHMANN_JSON_NAMESPACE_END // (2) ``` -These macros can be used to open and close the `nlohmann` namespace. They -include an inline namespace used to differentiate symbols when linking multiple -versions (including different ABI-affecting macros) of this library. +These macros can be used to open and close the `nlohmann` namespace. They include an inline namespace used to +differentiate symbols when linking multiple versions (including different ABI-affecting macros) of this library. 1. Opens the namespace. ```cpp @@ -25,11 +24,26 @@ versions (including different ABI-affecting macros) of this library. ## Default definition -The default definitions open and close the `nlohmann` as well as an inline -namespace. +The default definitions open and close the `nlohmann` as well as an inline namespace. -When these macros are not defined, the library will define them to their -default definitions. +When these macros are not defined, the library will define them to their default definitions. + +## Examples + +??? example + + The example shows an example how to use `NLOHMANN_JSON_NAMESPACE_BEGIN`/`NLOHMANN_JSON_NAMESPACE_END` from the + [How do I convert third-party types?](../../features/arbitrary_types.md#how-do-i-convert-third-party-types) page. + + ```cpp + --8<-- "examples/nlohmann_json_namespace_begin.c++17.cpp" + ``` + + Output: + + ```json + --8<-- "examples/nlohmann_json_namespace_begin.c++17.output" + ``` ## See also diff --git a/docs/mkdocs/docs/api/operator_gtgt.md b/docs/mkdocs/docs/api/operator_gtgt.md index 98d575add4..e76cc0db7f 100644 --- a/docs/mkdocs/docs/api/operator_gtgt.md +++ b/docs/mkdocs/docs/api/operator_gtgt.md @@ -21,8 +21,7 @@ the stream `i` ## Exceptions - Throws [`parse_error.101`](../home/exceptions.md#jsonexceptionparse_error101) in case of an unexpected token. -- Throws [`parse_error.102`](../home/exceptions.md#jsonexceptionparse_error102) if to_unicode fails or surrogate - error. +- Throws [`parse_error.102`](../home/exceptions.md#jsonexceptionparse_error102) if to_unicode fails or surrogate error. - Throws [`parse_error.103`](../home/exceptions.md#jsonexceptionparse_error103) if to_unicode fails. ## Complexity diff --git a/docs/mkdocs/docs/api/operator_literal_json.md b/docs/mkdocs/docs/api/operator_literal_json.md index 6775a3e1bc..cda00215c5 100644 --- a/docs/mkdocs/docs/api/operator_literal_json.md +++ b/docs/mkdocs/docs/api/operator_literal_json.md @@ -15,8 +15,9 @@ using namespace nlohmann::json_literals; using namespace nlohmann::literals::json_literals; using namespace nlohmann; ``` -This is suggested to ease migration to the next major version release of the library. -See ['JSON_USE_GLOBAL_UDLS`](macros/json_use_global_udls.md#notes) for details. + +This is suggested to ease migration to the next major version release of the library. See +['JSON_USE_GLOBAL_UDLS`](macros/json_use_global_udls.md#notes) for details. ## Parameters diff --git a/docs/mkdocs/docs/api/operator_literal_json_pointer.md b/docs/mkdocs/docs/api/operator_literal_json_pointer.md index 9b79697dc1..14d5378bcb 100644 --- a/docs/mkdocs/docs/api/operator_literal_json_pointer.md +++ b/docs/mkdocs/docs/api/operator_literal_json_pointer.md @@ -15,8 +15,8 @@ using namespace nlohmann::json_literals; using namespace nlohmann::literals::json_literals; using namespace nlohmann; ``` -This is suggested to ease migration to the next major version release of the library. -See ['JSON_USE_GLOBAL_UDLS`](macros/json_use_global_udls.md#notes) for details. +This is suggested to ease migration to the next major version release of the library. See +['JSON_USE_GLOBAL_UDLS`](macros/json_use_global_udls.md#notes) for details. ## Parameters diff --git a/docs/mkdocs/docs/api/operator_ltlt.md b/docs/mkdocs/docs/api/operator_ltlt.md index ea857718b7..1718b3c9e8 100644 --- a/docs/mkdocs/docs/api/operator_ltlt.md +++ b/docs/mkdocs/docs/api/operator_ltlt.md @@ -35,7 +35,8 @@ the stream `o` ## Exceptions 1. Throws [`type_error.316`](../home/exceptions.md#jsonexceptiontype_error316) if a string stored inside the JSON - value is not UTF-8 encoded. Note that unlike the [`dump`](basic_json/dump.md) member functions, no `error_handler` can be set. + value is not UTF-8 encoded. Note that unlike the [`dump`](basic_json/dump.md) member functions, no `error_handler` + can be set. 2. None. ## Complexity diff --git a/docs/mkdocs/docs/features/arbitrary_types.md b/docs/mkdocs/docs/features/arbitrary_types.md index 2d2e6f28bc..046a597a31 100644 --- a/docs/mkdocs/docs/features/arbitrary_types.md +++ b/docs/mkdocs/docs/features/arbitrary_types.md @@ -10,7 +10,7 @@ namespace ns { std::string address; int age; }; -} +} // namespace ns ns::person p = {"Ned Flanders", "744 Evergreen Terrace", 60}; diff --git a/docs/mkdocs/docs/features/binary_formats/bjdata.md b/docs/mkdocs/docs/features/binary_formats/bjdata.md index 74b4499e98..a89a228858 100644 --- a/docs/mkdocs/docs/features/binary_formats/bjdata.md +++ b/docs/mkdocs/docs/features/binary_formats/bjdata.md @@ -1,24 +1,21 @@ # BJData The [BJData format](https://neurojson.org) was derived from and improved upon -[Universal Binary JSON(UBJSON)](https://ubjson.org) specification (Draft 12). -Specifically, it introduces an optimized array container for efficient storage -of N-dimensional packed arrays (**ND-arrays**); it also adds 4 new type markers - -`[u] - uint16`, `[m] - uint32`, `[M] - uint64` and `[h] - float16` - to -unambigiously map common binary numeric types; furthermore, it uses little-endian -(LE) to store all numerics instead of big-endian (BE) as in UBJSON to avoid +[Universal Binary JSON(UBJSON)](https://ubjson.org) specification (Draft 12). Specifically, it introduces an optimized +array container for efficient storage of N-dimensional packed arrays (**ND-arrays**); it also adds 4 new type markers - +`[u] - uint16`, `[m] - uint32`, `[M] - uint64` and `[h] - float16` - to unambiguously map common binary numeric types; +furthermore, it uses little-endian (LE) to store all numerics instead of big-endian (BE) as in UBJSON to avoid unnecessary conversions on commonly available platforms. -Compared to other binary JSON-like formats such as MessagePack and CBOR, both BJData and -UBJSON demonstrate a rare combination of being both binary and **quasi-human-readable**. This -is because all semantic elements in BJData and UBJSON, including the data-type markers -and name/string types are directly human-readable. Data stored in the BJData/UBJSON format -are not only compact in size, fast to read/write, but also can be directly searched -or read using simple processing. +Compared to other binary JSON-like formats such as MessagePack and CBOR, both BJData and UBJSON demonstrate a rare +combination of being both binary and **quasi-human-readable**. This is because all semantic elements in BJData and +UBJSON, including the data-type markers and name/string types are directly human-readable. Data stored in the +BJData/UBJSON format are not only compact in size, fast to read/write, but also can be directly searched or read using +simple processing. !!! abstract "References" - - [BJData Specification](https://neurojson.org/bjdata/draft2) + - [BJData Specification](https://neurojson.org/bjdata/draft2) ## Serialization @@ -55,67 +52,59 @@ The library uses the following mapping from JSON values types to BJData types ac !!! success "Complete mapping" - The mapping is **complete** in the sense that any JSON value type can be converted to a BJData value. + The mapping is **complete** in the sense that any JSON value type can be converted to a BJData value. - Any BJData output created by `to_bjdata` can be successfully parsed by `from_bjdata`. + Any BJData output created by `to_bjdata` can be successfully parsed by `from_bjdata`. !!! warning "Size constraints" - The following values can **not** be converted to a BJData value: + The following values can **not** be converted to a BJData value: - strings with more than 18446744073709551615 bytes, i.e., $2^{64}-1$ bytes (theoretical) !!! info "Unused BJData markers" - The following markers are not used in the conversion: + The following markers are not used in the conversion: - `Z`: no-op values are not created. - `C`: single-byte strings are serialized with `S` markers. !!! info "NaN/infinity handling" - If NaN or Infinity are stored inside a JSON number, they are - serialized properly. This behavior differs from the `dump()` - function which serializes NaN or Infinity to `null`. - + If NaN or Infinity are stored inside a JSON number, they are serialized properly. This behavior differs from the + `dump()` function which serializes NaN or Infinity to `#!json null`. !!! info "Endianness" - A breaking difference between BJData and UBJSON is the endianness - of numerical values. In BJData, all numerical data types (integers - `UiuImlML` and floating-point values `hdD`) are stored in the little-endian (LE) - byte order as opposed to big-endian as used by UBJSON. Adopting LE - to store numeric records avoids unnecessary byte swapping on most modern - computers where LE is used as the default byte order. + A breaking difference between BJData and UBJSON is the endianness of numerical values. In BJData, all numerical data + types (integers `UiuImlML` and floating-point values `hdD`) are stored in the little-endian (LE) byte order as + opposed to big-endian as used by UBJSON. Adopting LE to store numeric records avoids unnecessary byte swapping on + most modern computers where LE is used as the default byte order. !!! info "Optimized formats" - Optimized formats for containers are supported via two parameters of + Optimized formats for containers are supported via two parameters of [`to_bjdata`](../../api/basic_json/to_bjdata.md): - - Parameter `use_size` adds size information to the beginning of a container and - removes the closing marker. - - Parameter `use_type` further checks whether all elements of a container have the - same type and adds the type marker to the beginning of the container. - The `use_type` parameter must only be used together with `use_size = true`. + - Parameter `use_size` adds size information to the beginning of a container and removes the closing marker. + - Parameter `use_type` further checks whether all elements of a container have the same type and adds the type + marker to the beginning of the container. The `use_type` parameter must only be used together with + `use_size = true`. - Note that `use_size = true` alone may result in larger representations - - the benefit of this parameter is that the receiving side is - immediately informed of the number of elements in the container. + Note that `use_size = true` alone may result in larger representations - the benefit of this parameter is that the + receiving side is immediately informed of the number of elements in the container. !!! info "ND-array optimized format" - BJData extends UBJSON's optimized array **size** marker to support ND-arrays of - uniform numerical data types (referred to as *packed arrays*). - For example, the 2-D `uint8` integer array `[[1,2],[3,4],[5,6]]`, stored - as nested optimized array in UBJSON `[ [$U#i2 1 2 [$U#i2 3 4 [$U#i2 5 6 ]`, - can be further compressed in BJData to `[$U#[$i#i2 2 3 1 2 3 4 5 6` - or `[$U#[i2 i3] 1 2 3 4 5 6`. + BJData extends UBJSON's optimized array **size** marker to support ND-arrays of uniform numerical data types + (referred to as *packed arrays*). For example, the 2-D `uint8` integer array `[[1,2],[3,4],[5,6]]`, stored as nested + optimized array in UBJSON `[ [$U#i2 1 2 [$U#i2 3 4 [$U#i2 5 6 ]`, can be further compressed in BJData to + `[$U#[$i#i2 2 3 1 2 3 4 5 6` or `[$U#[i2 i3] 1 2 3 4 5 6`. - To maintina type and size information, ND-arrays are converted to JSON objects following the - **annotated array format** (defined in the [JData specification (Draft 3)][JDataAAFmt]), - when parsed using [`from_bjdata`](../../api/basic_json/from_bjdata.md). - For example, the above 2-D `uint8` array can be parsed and accessed as + To maintain type and size information, ND-arrays are converted to JSON objects following the **annotated array + format** (defined in the [JData specification (Draft 3)][JDataAAFmt]), when parsed using + [`from_bjdata`](../../api/basic_json/from_bjdata.md). For example, the above 2-D `uint8` array can be parsed and + accessed as ```json { @@ -126,34 +115,28 @@ The library uses the following mapping from JSON values types to BJData types ac ``` Likewise, when a JSON object in the above form is serialzed using - [`to_bjdata`](../../api/basic_json/to_bjdata.md), it is automatically converted - into a compact BJData ND-array. The only exception is, that when the 1-dimensional - vector stored in `"_ArraySize_"` contains a single integer or two integers with one - being 1, a regular 1-D optimized array is generated. + [`to_bjdata`](../../api/basic_json/to_bjdata.md), it is automatically converted into a compact BJData ND-array. The + only exception is, that when the 1-dimensional vector stored in `"_ArraySize_"` contains a single integer or two + integers with one being 1, a regular 1-D optimized array is generated. - The current version of this library does not yet support automatic detection of and - conversion from a nested JSON array input to a BJData ND-array. + The current version of this library does not yet support automatic detection of and conversion from a nested JSON + array input to a BJData ND-array. [JDataAAFmt]: https://github.com/NeuroJSON/jdata/blob/master/JData_specification.md#annotated-storage-of-n-d-arrays) !!! info "Restrictions in optimized data types for arrays and objects" - Due to diminished space saving, hampered readability, and increased - security risks, in BJData, the allowed data types following the `$` marker - in an optimized array and object container are restricted to - **non-zero-fixed-length** data types. Therefore, the valid optimized - type markers can only be one of `UiuImlMLhdDC`. This also means other - variable (`[{SH`) or zero-length types (`TFN`) can not be used in an - optimized array or object in BJData. + Due to diminished space saving, hampered readability, and increased security risks, in BJData, the allowed data + types following the `$` marker in an optimized array and object container are restricted to + **non-zero-fixed-length** data types. Therefore, the valid optimized type markers can only be one of `UiuImlMLhdDC`. + This also means other variable (`[{SH`) or zero-length types (`TFN`) can not be used in an optimized array or object + in BJData. !!! info "Binary values" - If the JSON data contains the binary type, the value stored is a list - of integers, as suggested by the BJData documentation. In particular, - this means that the serialization and the deserialization of JSON - containing binary values into BJData and back will result in a - different JSON object. - + If the JSON data contains the binary type, the value stored is a list of integers, as suggested by the BJData + documentation. In particular, this means that the serialization and the deserialization of JSON containing binary + values into BJData and back will result in a different JSON object. ??? example @@ -196,8 +179,7 @@ The library maps BJData types to JSON value types as follows: !!! success "Complete mapping" - The mapping is **complete** in the sense that any BJData value can be converted to a JSON value. - + The mapping is **complete** in the sense that any BJData value can be converted to a JSON value. ??? example diff --git a/docs/mkdocs/docs/features/binary_formats/bson.md b/docs/mkdocs/docs/features/binary_formats/bson.md index 8c7716d9b6..f3b8cf18d0 100644 --- a/docs/mkdocs/docs/features/binary_formats/bson.md +++ b/docs/mkdocs/docs/features/binary_formats/bson.md @@ -6,8 +6,8 @@ representation of data types that are not part of the JSON spec. For example, BS !!! abstract "References" - - [BSON Website](http://bsonspec.org) - the main source on BSON - - [BSON Specification](http://bsonspec.org/spec.html) - the specification + - [BSON Website](http://bsonspec.org) - the main source on BSON + - [BSON Specification](http://bsonspec.org/spec.html) - the specification ## Serialization diff --git a/docs/mkdocs/docs/features/binary_formats/cbor.md b/docs/mkdocs/docs/features/binary_formats/cbor.md index 280bf577f4..2d0a1dae10 100644 --- a/docs/mkdocs/docs/features/binary_formats/cbor.md +++ b/docs/mkdocs/docs/features/binary_formats/cbor.md @@ -5,13 +5,14 @@ small code size, fairly small message size, and extensibility without the need f !!! abstract "References" - - [CBOR Website](http://cbor.io) - the main source on CBOR + - [CBOR Website](http://cbor.io) - the main source on CBOR - [CBOR Playground](http://cbor.me) - an interactive webpage to translate between JSON and CBOR - [RFC 7049](https://tools.ietf.org/html/rfc7049) - the CBOR specification ## Serialization -The library uses the following mapping from JSON values types to CBOR types according to the CBOR specification (RFC 7049): +The library uses the following mapping from JSON values types to CBOR types according to the CBOR specification +([RFC 7049](https://www.rfc-editor.org/rfc/rfc7049.html)): | JSON value type | value/range | CBOR type | first byte | |-----------------|--------------------------------------------|-----------------------------------|------------| @@ -61,15 +62,15 @@ see "binary" cells in the table above. !!! success "Complete mapping" - The mapping is **complete** in the sense that any JSON value type can be converted to a CBOR value. + The mapping is **complete** in the sense that any JSON value type can be converted to a CBOR value. !!! info "NaN/infinity handling" - If NaN or Infinity are stored inside a JSON number, they are serialized properly. This behavior differs from the normal JSON serialization which serializes NaN or Infinity to `null`. + If NaN or Infinity are stored inside a JSON number, they are serialized properly. This behavior differs from the normal JSON serialization which serializes NaN or Infinity to `null`. !!! info "Unused CBOR types" - The following CBOR types are not used in the conversion: + The following CBOR types are not used in the conversion: - UTF-8 strings terminated by "break" (0x7F) - arrays terminated by "break" (0x9F) @@ -149,7 +150,7 @@ The library maps CBOR types to JSON value types as follows: !!! warning "Incomplete mapping" - The mapping is **incomplete** in the sense that not all CBOR types can be converted to a JSON value. The following CBOR types are not supported and will yield parse errors: + The mapping is **incomplete** in the sense that not all CBOR types can be converted to a JSON value. The following CBOR types are not supported and will yield parse errors: - date/time (0xC0..0xC1) - bignum (0xC2..0xC3) @@ -161,7 +162,7 @@ The library maps CBOR types to JSON value types as follows: !!! warning "Object keys" - CBOR allows map keys of any type, whereas JSON only allows strings as keys in object values. Therefore, CBOR maps with keys other than UTF-8 strings are rejected. + CBOR allows map keys of any type, whereas JSON only allows strings as keys in object values. Therefore, CBOR maps with keys other than UTF-8 strings are rejected. !!! warning "Tagged items" diff --git a/docs/mkdocs/docs/features/binary_formats/messagepack.md b/docs/mkdocs/docs/features/binary_formats/messagepack.md index b0139b40c9..b2f69f174d 100644 --- a/docs/mkdocs/docs/features/binary_formats/messagepack.md +++ b/docs/mkdocs/docs/features/binary_formats/messagepack.md @@ -1,15 +1,18 @@ # MessagePack -MessagePack is an efficient binary serialization format. It lets you exchange data among multiple languages like JSON. But it's faster and smaller. Small integers are encoded into a single byte, and typical short strings require only one extra byte in addition to the strings themselves. +MessagePack is an efficient binary serialization format. It lets you exchange data among multiple languages like JSON. +But it's faster and smaller. Small integers are encoded into a single byte, and typical short strings require only one +extra byte in addition to the strings themselves. !!! abstract "References" - - [MessagePack website](https://msgpack.org) - - [MessagePack specification](https://github.com/msgpack/msgpack/blob/master/spec.md) + - [MessagePack website](https://msgpack.org) + - [MessagePack specification](https://github.com/msgpack/msgpack/blob/master/spec.md) ## Serialization -The library uses the following mapping from JSON values types to MessagePack types according to the MessagePack specification: +The library uses the following mapping from JSON values types to MessagePack types according to the MessagePack +specification: | JSON value type | value/range | MessagePack type | first byte | |-----------------|------------------------------------------|------------------|------------| @@ -49,22 +52,23 @@ The library uses the following mapping from JSON values types to MessagePack typ !!! success "Complete mapping" - The mapping is **complete** in the sense that any JSON value type can be converted to a MessagePack value. + The mapping is **complete** in the sense that any JSON value type can be converted to a MessagePack value. - Any MessagePack output created by `to_msgpack` can be successfully parsed by `from_msgpack`. + Any MessagePack output created by `to_msgpack` can be successfully parsed by `from_msgpack`. !!! warning "Size constraints" - The following values can **not** be converted to a MessagePack value: + The following values can **not** be converted to a MessagePack value: - - strings with more than 4294967295 bytes - - byte strings with more than 4294967295 bytes - - arrays with more than 4294967295 elements - - objects with more than 4294967295 elements + - strings with more than 4294967295 bytes + - byte strings with more than 4294967295 bytes + - arrays with more than 4294967295 elements + - objects with more than 4294967295 elements !!! info "NaN/infinity handling" - If NaN or Infinity are stored inside a JSON number, they are serialized properly. function which serializes NaN or Infinity to `null`. + If NaN or Infinity are stored inside a JSON number, they are serialized properly in contrast to the + [dump](../../api/basic_json/dump.md) function which serializes NaN or Infinity to `null`. ??? example @@ -123,7 +127,7 @@ The library maps MessagePack types to JSON value types as follows: !!! info - Any MessagePack output created by `to_msgpack` can be successfully parsed by `from_msgpack`. + Any MessagePack output created by `to_msgpack` can be successfully parsed by `from_msgpack`. ??? example diff --git a/docs/mkdocs/docs/features/binary_formats/ubjson.md b/docs/mkdocs/docs/features/binary_formats/ubjson.md index 509d9f577b..76956d60a7 100644 --- a/docs/mkdocs/docs/features/binary_formats/ubjson.md +++ b/docs/mkdocs/docs/features/binary_formats/ubjson.md @@ -1,10 +1,11 @@ # UBJSON -Universal Binary JSON (UBJSON) is a binary form directly imitating JSON, but requiring fewer bytes of data. It aims to achieve the generality of JSON, combined with being much easier to process than JSON. +Universal Binary JSON (UBJSON) is a binary form directly imitating JSON, but requiring fewer bytes of data. It aims to +achieve the generality of JSON, combined with being much easier to process than JSON. !!! abstract "References" - - [UBJSON Website](http://ubjson.org) + - [UBJSON Website](http://ubjson.org) ## Serialization @@ -36,50 +37,43 @@ The library uses the following mapping from JSON values types to UBJSON types ac !!! success "Complete mapping" - The mapping is **complete** in the sense that any JSON value type can be converted to a UBJSON value. + The mapping is **complete** in the sense that any JSON value type can be converted to a UBJSON value. - Any UBJSON output created by `to_ubjson` can be successfully parsed by `from_ubjson`. + Any UBJSON output created by `to_ubjson` can be successfully parsed by `from_ubjson`. !!! warning "Size constraints" - The following values can **not** be converted to a UBJSON value: + The following values can **not** be converted to a UBJSON value: - strings with more than 9223372036854775807 bytes (theoretical) !!! info "Unused UBJSON markers" - The following markers are not used in the conversion: + The following markers are not used in the conversion: - `Z`: no-op values are not created. - `C`: single-byte strings are serialized with `S` markers. !!! info "NaN/infinity handling" - If NaN or Infinity are stored inside a JSON number, they are - serialized properly. This behavior differs from the `dump()` - function which serializes NaN or Infinity to `null`. + If NaN or Infinity are stored inside a JSON number, they are serialized properly. This behavior differs from the + `dump()` function which serializes NaN or Infinity to `null`. !!! info "Optimized formats" - The optimized formats for containers are supported: Parameter - `use_size` adds size information to the beginning of a container and - removes the closing marker. Parameter `use_type` further checks - whether all elements of a container have the same type and adds the - type marker to the beginning of the container. The `use_type` - parameter must only be used together with `use_size = true`. + The optimized formats for containers are supported: Parameter `use_size` adds size information to the beginning of a + container and removes the closing marker. Parameter `use_type` further checks whether all elements of a container + have the same type and adds the type marker to the beginning of the container. The `use_type` parameter must only be + used together with `use_size = true`. - Note that `use_size = true` alone may result in larger representations - - the benefit of this parameter is that the receiving side is - immediately informed on the number of elements of the container. + Note that `use_size = true` alone may result in larger representations - the benefit of this parameter is that the + receiving side is immediately informed on the number of elements of the container. !!! info "Binary values" - If the JSON data contains the binary type, the value stored is a list - of integers, as suggested by the UBJSON documentation. In particular, - this means that serialization and the deserialization of a JSON - containing binary values into UBJSON and back will result in a - different JSON object. - + If the JSON data contains the binary type, the value stored is a list of integers, as suggested by the UBJSON + documentation. In particular, this means that serialization and the deserialization of a JSON containing binary + values into UBJSON and back will result in a different JSON object. ??? example @@ -117,8 +111,7 @@ The library maps UBJSON types to JSON value types as follows: !!! success "Complete mapping" - The mapping is **complete** in the sense that any UBJSON value can be converted to a JSON value. - + The mapping is **complete** in the sense that any UBJSON value can be converted to a JSON value. ??? example diff --git a/docs/mkdocs/docs/features/comments.md b/docs/mkdocs/docs/features/comments.md index c5874c9f18..61266d9caf 100644 --- a/docs/mkdocs/docs/features/comments.md +++ b/docs/mkdocs/docs/features/comments.md @@ -5,9 +5,9 @@ This library does not support comments *by default*. It does so for three reason 1. Comments are not part of the [JSON specification](https://tools.ietf.org/html/rfc8259). You may argue that `//` or `/* */` are allowed in JavaScript, but JSON is not JavaScript. 2. This was not an oversight: Douglas Crockford [wrote on this](https://plus.google.com/118095276221607585885/posts/RK8qyGVaGSr) in May 2012: - > I removed comments from JSON because I saw people were using them to hold parsing directives, a practice which would have destroyed interoperability. I know that the lack of comments makes some people sad, but it shouldn't. + > I removed comments from JSON because I saw people were using them to hold parsing directives, a practice which would have destroyed interoperability. I know that the lack of comments makes some people sad, but it shouldn't. - > Suppose you are using JSON to keep configuration files, which you would like to annotate. Go ahead and insert all the comments you like. Then pipe it through JSMin before handing it to your JSON parser. + > Suppose you are using JSON to keep configuration files, which you would like to annotate. Go ahead and insert all the comments you like. Then pipe it through JSMin before handing it to your JSON parser. 3. It is dangerous for interoperability if some libraries would add comment support while others don't. Please check [The Harmful Consequences of the Robustness Principle](https://tools.ietf.org/html/draft-iab-protocol-maintenance-01) on this. diff --git a/docs/mkdocs/docs/features/element_access/unchecked_access.md b/docs/mkdocs/docs/features/element_access/unchecked_access.md index 1bdea94e70..39f06dc9f2 100644 --- a/docs/mkdocs/docs/features/element_access/unchecked_access.md +++ b/docs/mkdocs/docs/features/element_access/unchecked_access.md @@ -99,7 +99,8 @@ that the passed index is the new maximal index. Intermediate values are filled w !!! failure "Exceptions" - `operator[]` can only be used with objects (with a string argument) or with arrays (with a numeric argument). For other types, a [`basic_json::type_error`](../../home/exceptions.md#jsonexceptiontype_error305) is thrown. + `operator[]` can only be used with objects (with a string argument) or with arrays (with a numeric argument). For + other types, a [`basic_json::type_error`](../../home/exceptions.md#jsonexceptiontype_error305) is thrown. ## Summary diff --git a/docs/mkdocs/docs/features/parsing/parse_exceptions.md b/docs/mkdocs/docs/features/parsing/parse_exceptions.md index 879dab0d32..61c0ff2902 100644 --- a/docs/mkdocs/docs/features/parsing/parse_exceptions.md +++ b/docs/mkdocs/docs/features/parsing/parse_exceptions.md @@ -1,6 +1,10 @@ # Parsing and Exceptions -When the input is not valid JSON, an exception of type [`parse_error`](../../home/exceptions.md#parse-errors) is thrown. This exception contains the position in the input where the error occurred, together with a diagnostic message and the last read input token. The exceptions page contains a [list of examples for parse error exceptions](../../home/exceptions.md#parse-errors). In case you process untrusted input, always enclose your code with a `#!cpp try`/`#!cpp catch` block, like +When the input is not valid JSON, an exception of type [`parse_error`](../../home/exceptions.md#parse-errors) is thrown. +This exception contains the position in the input where the error occurred, together with a diagnostic message and the +last read input token. The exceptions page contains a +[list of examples for parse error exceptions](../../home/exceptions.md#parse-errors). In case you process untrusted +input, always enclose your code with a `#!cpp try`/`#!cpp catch` block, like ```cpp json j; @@ -19,7 +23,9 @@ In case exceptions are undesired or not supported by the environment, there are ## Switch off exceptions -The `parse()` function accepts as last parameter a `#!cpp bool` variable `allow_exceptions` which controls whether an exception is thrown when a parse error occurs (`#!cpp true`, default) or whether a discarded value should be returned (`#!cpp false`). +The `parse()` function accepts a `#!cpp bool` parameter `allow_exceptions` which controls whether an exception is +thrown when a parse error occurs (`#!cpp true`, default) or whether a discarded value should be returned +(`#!cpp false`). ```cpp json j = json::parse(my_input, nullptr, false); @@ -33,7 +39,8 @@ Note there is no diagnostic information available in this scenario. ## Use accept() function -Alternatively, function `accept()` can be used which does not return a `json` value, but a `#!cpp bool` indicating whether the input is valid JSON. +Alternatively, function `accept()` can be used which does not return a `json` value, but a `#!cpp bool` indicating +whether the input is valid JSON. ```cpp if (!json::accept(my_input)) diff --git a/docs/mkdocs/docs/features/parsing/parser_callbacks.md b/docs/mkdocs/docs/features/parsing/parser_callbacks.md index 12136f57c7..ef076d126c 100644 --- a/docs/mkdocs/docs/features/parsing/parser_callbacks.md +++ b/docs/mkdocs/docs/features/parsing/parser_callbacks.md @@ -2,9 +2,10 @@ ## Overview -With a parser callback function, the result of parsing a JSON text can be influenced. When passed to `parse`, it is called on certain events -(passed as `parse_event_t` via parameter `event`) with a set recursion depth `depth` and context JSON value `parsed`. The return value of the -callback function is a boolean indicating whether the element that emitted the callback shall be kept or not. +With a parser callback function, the result of parsing a JSON text can be influenced. When passed to `parse`, it is +called on certain events (passed as `parse_event_t` via parameter `event`) with a set recursion depth `depth` and +context JSON value `parsed`. The return value of the callback function is a boolean indicating whether the element that +emitted the callback shall be kept or not. The type of the callback function is: @@ -17,8 +18,8 @@ using parser_callback_t = ## Callback event types -We distinguish six scenarios (determined by the event type) in which the callback function can be called. The following table describes the values -of the parameters `depth`, `event`, and `parsed`. +We distinguish six scenarios (determined by the event type) in which the callback function can be called. The following +table describes the values of the parameters `depth`, `event`, and `parsed`. | parameter `event` | description | parameter `depth` | parameter `parsed` | |-------------------------------|-----------------------------------------------------------|-------------------------------------------|----------------------------------| @@ -59,10 +60,13 @@ of the parameters `depth`, `event`, and `parsed`. ## Return value -Discarding a value (i.e., returning `#!c false`) has different effects depending on the context in which function was called: +Discarding a value (i.e., returning `#!c false`) has different effects depending on the context in which the function +was called: -- Discarded values in structured types are skipped. That is, the parser will behave as if the discarded value was never read. -- In case a value outside a structured type is skipped, it is replaced with `#!json null`. This case happens if the top-level element is skipped. +- Discarded values in structured types are skipped. That is, the parser will behave as if the discarded value was never + read. +- In case a value outside a structured type is skipped, it is replaced with `#!json null`. This case happens if the + top-level element is skipped. ??? example diff --git a/docs/mkdocs/docs/home/faq.md b/docs/mkdocs/docs/home/faq.md index 878b8a64e3..dd426e073f 100644 --- a/docs/mkdocs/docs/home/faq.md +++ b/docs/mkdocs/docs/home/faq.md @@ -44,7 +44,7 @@ for objects. !!! question - Can you add an option to ignore trailing commas? + Can you add an option to ignore trailing commas? This library does not support any feature which would jeopardize interoperability. @@ -53,9 +53,9 @@ This library does not support any feature which would jeopardize interoperabilit !!! question "Questions" - - Why is the parser complaining about a Chinese character? - - Does the library support Unicode? - - I get an exception `[json.exception.parse_error.101] parse error at line 1, column 53: syntax error while parsing value - invalid string: ill-formed UTF-8 byte; last read: '"Testé$')"` + - Why is the parser complaining about a Chinese character? + - Does the library support Unicode? + - I get an exception `[json.exception.parse_error.101] parse error at line 1, column 53: syntax error while parsing value - invalid string: ill-formed UTF-8 byte; last read: '"Testé$')"` The library supports **Unicode input** as follows: @@ -124,7 +124,7 @@ Yes, see [Parsing and exceptions](../features/parsing/parse_exceptions.md). !!! question - Can I get the key of the object item that caused an exception? + Can I get the key of the object item that caused an exception? Yes, you can. Please define the symbol [`JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md) to get [extended diagnostics messages](exceptions.md#extended-diagnostic-messages). @@ -136,18 +136,18 @@ Yes, you can. Please define the symbol [`JSON_DIAGNOSTICS`](../api/macros/json_d !!! question - - It seems that precision is lost when serializing a double. - - Can I change the precision for floating-point serialization? + - It seems that precision is lost when serializing a double. + - Can I change the precision for floating-point serialization? The library uses `std::numeric_limits::digits10` (15 for IEEE `double`s) digits for serialization. This value is sufficient to guarantee roundtripping. If one uses more than this number of digits of precision, then string -> value -> string is not guaranteed to round-trip. !!! quote "[cppreference.com](https://en.cppreference.com/w/cpp/types/numeric_limits/digits10)" - The value of `std::numeric_limits::digits10` is the number of base-10 digits that can be represented by the type T without change, that is, any number with this many significant decimal digits can be converted to a value of type T and back to decimal form, without change due to rounding or overflow. + The value of `std::numeric_limits::digits10` is the number of base-10 digits that can be represented by the type T without change, that is, any number with this many significant decimal digits can be converted to a value of type T and back to decimal form, without change due to rounding or overflow. !!! tip - The website https://float.exposed gives a good insight into the internal storage of floating-point numbers. + The website https://float.exposed gives a good insight into the internal storage of floating-point numbers. See [this section](../features/types/number_handling.md#number-serialization) on the library's number handling for more information. @@ -157,7 +157,7 @@ See [this section](../features/types/number_handling.md#number-serialization) on !!! question - Why does the code not compile with Android SDK? + Why does the code not compile with Android SDK? Android defaults to using very old compilers and C++ libraries. To fix this, add the following to your `Application.mk`. This will switch to the LLVM C++ library, the Clang compiler, and enable C++11 and other features disabled by default. @@ -174,7 +174,7 @@ The code compiles successfully with [Android NDK](https://developer.android.com/ !!! question "Questions" - - Why do I get a compilation error `'to_string' is not a member of 'std'` (or similarly, for `strtod` or `strtof`)? - - Why does the code not compile with MinGW or Android SDK? + - Why do I get a compilation error `'to_string' is not a member of 'std'` (or similarly, for `strtod` or `strtof`)? + - Why does the code not compile with MinGW or Android SDK? This is not an issue with the code, but rather with the compiler itself. On Android, see above to build with a newer environment. For MinGW, please refer to [this site](http://tehsausage.com/mingw-to-string) and [this discussion](https://github.com/nlohmann/json/issues/136) for information on how to fix this bug. For Android NDK using `APP_STL := gnustl_static`, please refer to [this discussion](https://github.com/nlohmann/json/issues/219). diff --git a/docs/mkdocs/docs/home/releases.md b/docs/mkdocs/docs/home/releases.md index 2cf5b3c66c..5237c42592 100644 --- a/docs/mkdocs/docs/home/releases.md +++ b/docs/mkdocs/docs/home/releases.md @@ -252,18 +252,18 @@ http://nlohmann.github.io/json/doxygen/classnlohmann_1_1basic__json_a0a45fc74063 - Fixed documentation of parse function. #1473 - Suppressed warning that cannot be fixed inside the library. #1401 #1468 - Imroved package manager suppert: - - Updated Buckaroo instructions. #1495 - - Improved Meson support. #1463 - - Added Conda package manager documentation. #1430 - - Added NuGet package manager documentation. #1132 + - Updated Buckaroo instructions. #1495 + - Improved Meson support. #1463 + - Added Conda package manager documentation. #1430 + - Added NuGet package manager documentation. #1132 - Continuous Integration - - Removed unstable or deprecated Travis builders (Xcode 6.4 - 8.2) and added Xcode 10.1 builder. - - Added Clang 7 to Travis CI. - - Fixed AppVeyor x64 builds. #1374 #1414 + - Removed unstable or deprecated Travis builders (Xcode 6.4 - 8.2) and added Xcode 10.1 builder. + - Added Clang 7 to Travis CI. + - Fixed AppVeyor x64 builds. #1374 #1414 - Updated thirdparty libraries: - - Catch 1.12.0 -> 1.12.2 - - Google Benchmark 1.3.0 -> 1.4.1 - - Doxygen 1.8.15 -> 1.8.16 + - Catch 1.12.0 -> 1.12.2 + - Google Benchmark 1.3.0 -> 1.4.1 + - Doxygen 1.8.15 -> 1.8.16 ### :fire: Deprecated functions diff --git a/docs/mkdocs/docs/integration/cmake.md b/docs/mkdocs/docs/integration/cmake.md index 831e35ab93..b470319ba1 100644 --- a/docs/mkdocs/docs/integration/cmake.md +++ b/docs/mkdocs/docs/integration/cmake.md @@ -119,7 +119,7 @@ automatically download a release as a dependency at configure type. ) ``` - However, the repository download size is quite large. You might want to depend on + However, the repository download size is quite large. You might want to depend on a smaller repository. For instance, you might want to replace the URL in the example by . diff --git a/docs/mkdocs/docs/integration/package_managers.md b/docs/mkdocs/docs/integration/package_managers.md index c2fb1a7f40..b9ebf075f1 100644 --- a/docs/mkdocs/docs/integration/package_managers.md +++ b/docs/mkdocs/docs/integration/package_managers.md @@ -30,29 +30,29 @@ instead. See [nlohmann-json](https://formulae.brew.sh/formula/nlohmann-json) for ??? example - 1. Create the following file: + 1. Create the following file: ```cpp title="example.cpp" --8<-- "integration/example.cpp" ``` - 2. Install the package + 2. Install the package - ```sh - brew install nlohmann-json - ``` + ```sh + brew install nlohmann-json + ``` - 3. Determine the include path, which defaults to `/usr/local/Cellar/nlohmann-json/$version/include`, where `$version` is the version of the library, e.g. `3.7.3`. The path of the library can be determined with + 3. Determine the include path, which defaults to `/usr/local/Cellar/nlohmann-json/$version/include`, where `$version` is the version of the library, e.g. `3.7.3`. The path of the library can be determined with - ```sh - brew list nlohmann-json - ``` + ```sh + brew list nlohmann-json + ``` - 4. Compile the code. For instance, the code can be compiled using Clang with + 4. Compile the code. For instance, the code can be compiled using Clang with - ```sh - clang++ example.cpp -I/usr/local/Cellar/nlohmann-json/3.7.3/include -std=c++11 -o example - ``` + ```sh + clang++ example.cpp -I/usr/local/Cellar/nlohmann-json/3.7.3/include -std=c++11 -o example + ``` :material-update: The [formula](https://formulae.brew.sh/formula/nlohmann-json) is updated automatically. @@ -68,7 +68,7 @@ If you are using [Conan](https://www.conan.io/) to manage your dependencies, mer ??? example - 1. Create the following files: + 1. Create the following files: ```ini title="Conanfile.txt" --8<-- "integration/conan/Conanfile.txt" @@ -82,15 +82,15 @@ If you are using [Conan](https://www.conan.io/) to manage your dependencies, mer --8<-- "integration/conan/example.cpp" ``` - 2. Build: + 2. Build: - ```sh - mkdir build - cd build - conan install .. - cmake .. - cmake --build . - ``` + ```sh + mkdir build + cd build + conan install .. + cmake .. + cmake --build . + ``` :material-update: The [package](https://conan.io/center/nlohmann_json) is updated automatically. @@ -112,7 +112,7 @@ If you are using [vcpkg](https://github.com/Microsoft/vcpkg/) on your project fo ??? example - 1. Create the following files: + 1. Create the following files: ```cmake title="CMakeLists.txt" --8<-- "integration/vcpkg/CMakeLists.txt" @@ -128,14 +128,14 @@ If you are using [vcpkg](https://github.com/Microsoft/vcpkg/) on your project fo vcpkg install nlohmann-json ``` - 3. Build: + 3. Build: - ```sh - mkdir build - cd build - cmake .. -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake - cmake --build . - ``` + ```sh + mkdir build + cd build + cmake .. -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake + cmake --build . + ``` Note you need to adjust `/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake` to your system. diff --git a/docs/mkdocs/requirements.txt b/docs/mkdocs/requirements.txt index d51a6242c8..6ab84bb591 100644 --- a/docs/mkdocs/requirements.txt +++ b/docs/mkdocs/requirements.txt @@ -1,49 +1,49 @@ -Babel==2.10.1 -certifi==2021.10.8 -charset-normalizer==2.0.12 -click==8.1.2 +Babel==2.10.3 +certifi==2022.6.15 +charset-normalizer==2.1.0 +click==8.1.3 csscompressor==0.9.5 future==0.18.2 -ghp-import==2.0.2 +ghp-import==2.1.0 gitdb==4.0.9 GitPython==3.1.27 htmlmin==0.1.12 httplib2==0.20.4 idna==3.3 -importlib-metadata==4.11.3 -Jinja2==3.1.1 +importlib-metadata==4.12.0 +Jinja2==3.1.2 joblib==1.1.0 jsmin==3.0.1 livereload==2.6.3 lunr==0.6.2 -Markdown==3.3.6 -markdown-include==0.6.0 +Markdown==3.4.1 +markdown-include==0.7.0 MarkupSafe==2.1.1 mergedeep==1.3.4 -mkdocs==1.3.0 -mkdocs-git-revision-date-localized-plugin==1.0.1 -mkdocs-material==8.2.10 +mkdocs==1.3.1 +mkdocs-git-revision-date-localized-plugin==1.1.0 +mkdocs-material==8.3.9 mkdocs-material-extensions==1.0.3 mkdocs-minify-plugin==0.5.0 -mkdocs-redirects==1.0.4 +mkdocs-redirects==1.0.5 mkdocs-simple-hooks==0.1.5 nltk==3.7 packaging==21.3 plantuml==0.3.0 plantuml-markdown==3.6.3 -Pygments==2.11.0 -pymdown-extensions==9.3 -pyparsing==3.0.8 +Pygments==2.12.0 +pymdown-extensions==9.5 +pyparsing==3.0.9 python-dateutil==2.8.2 pytz==2022.1 PyYAML==6.0 pyyaml_env_tag==0.1 -regex==2022.4.24 -requests==2.27.1 +regex==2022.7.25 +requests==2.28.1 six==1.16.0 smmap==5.0.0 -tornado==6.1 +tornado==6.2 tqdm==4.64.0 -urllib3==1.26.9 -watchdog==2.1.7 -zipp==3.8.0 +urllib3==1.26.11 +watchdog==2.1.9 +zipp==3.8.1 diff --git a/docs/mkdocs/scripts/check_structure.py b/docs/mkdocs/scripts/check_structure.py index 37c4ce3567..643482af24 100755 --- a/docs/mkdocs/scripts/check_structure.py +++ b/docs/mkdocs/scripts/check_structure.py @@ -3,6 +3,7 @@ import glob import os.path import re +import sys warnings = 0 @@ -75,6 +76,12 @@ def check_structure(): if len(line) > 160 and '|' not in line: report('whitespace/line_length', f'{file}:{lineno+1} ({current_section})', f'line is too long ({len(line)} vs. 160 chars)') + # sections in `` comments are treated as present + if line.startswith('') + existing_sections.append(current_section) + # check if sections are correct if line.startswith('## '): # before starting a new section, check if the previous one documented all overloads @@ -167,3 +174,6 @@ def check_examples(): check_structure() check_examples() print(120 * '-') + + if warnings > 0: + sys.exit(1)