From 0dba7874251a5107ff9c276cb54074d6dd743475 Mon Sep 17 00:00:00 2001 From: Florian Albrechtskirchinger Date: Mon, 25 Jul 2022 16:05:17 +0200 Subject: [PATCH] Update documentation --- README.md | 2 +- docs/mkdocs/docs/api/basic_json/index.md | 3 +- docs/mkdocs/docs/api/json_pointer/index.md | 4 +- docs/mkdocs/docs/api/macros/index.md | 1 + .../docs/api/macros/json_use_global_udls.md | 93 +++++++++++++++++++ docs/mkdocs/docs/api/operator_literal_json.md | 19 +++- .../docs/api/operator_literal_json_pointer.md | 21 ++++- docs/mkdocs/mkdocs.yml | 7 +- 8 files changed, 135 insertions(+), 15 deletions(-) create mode 100644 docs/mkdocs/docs/api/macros/json_use_global_udls.md diff --git a/README.md b/README.md index 72d2081de..e888d55d4 100644 --- a/README.md +++ b/README.md @@ -268,7 +268,7 @@ value. That is, `json j = "{ \"happy\": true, \"pi\": 3.141 }"` would just store `"{ "happy": true, "pi": 3.141 }"` rather than parsing the actual object. The string literal should be brought into scope with with `using namespace nlohmann::literals;` -(see [`json::parse()`](https://json.nlohmann.me/api/basic_json/operator_literal_json/)). +(see [`json::parse()`](https://json.nlohmann.me/api/operator_literal_json/)). The above example can also be expressed explicitly using [`json::parse()`](https://json.nlohmann.me/api/basic_json/parse/): diff --git a/docs/mkdocs/docs/api/basic_json/index.md b/docs/mkdocs/docs/api/basic_json/index.md index 35ce63c3e..e474b662e 100644 --- a/docs/mkdocs/docs/api/basic_json/index.md +++ b/docs/mkdocs/docs/api/basic_json/index.md @@ -289,8 +289,7 @@ Access to the JSON value ## Literals -- [**operator""_json**](operator_literal_json.md) - user-defined string literal for JSON values -- [**operator""_json_pointer**](operator_literal_json_pointer.md) - user-defined string literal for JSON pointers +- [**operator""_json**](../operator_literal_json.md) - user-defined string literal for JSON values ## Helper classes diff --git a/docs/mkdocs/docs/api/json_pointer/index.md b/docs/mkdocs/docs/api/json_pointer/index.md index aee845cde..75b536c1c 100644 --- a/docs/mkdocs/docs/api/json_pointer/index.md +++ b/docs/mkdocs/docs/api/json_pointer/index.md @@ -37,9 +37,11 @@ are the base for JSON patches. - [**push_back**](push_back.md) - append an unescaped token at the end of the pointer - [**empty**](empty.md) - return whether pointer points to the root document +## Literals + +- [**operator""_json_pointer**](../operator_literal_json_pointer.md) - user-defined string literal for JSON pointers ## See also -- [operator""_json_pointer](../basic_json/operator_literal_json_pointer.md) - user-defined string literal for JSON pointers - [RFC 6901](https://datatracker.ietf.org/doc/html/rfc6901) ## Version history diff --git a/docs/mkdocs/docs/api/macros/index.md b/docs/mkdocs/docs/api/macros/index.md index 13accd797..8e118b03f 100644 --- a/docs/mkdocs/docs/api/macros/index.md +++ b/docs/mkdocs/docs/api/macros/index.md @@ -21,6 +21,7 @@ header. See also the [macro overview page](../../features/macros.md). - [**JSON_HAS_THREE_WAY_COMPARISON**](json_has_three_way_comparison.md) - control 3-way comparison support - [**JSON_NO_IO**](json_no_io.md) - switch off functions relying on certain C++ I/O headers - [**JSON_SKIP_UNSUPPORTED_COMPILER_CHECK**](json_skip_unsupported_compiler_check.md) - do not warn about unsupported compilers +- [**JSON_USE_GLOBAL_UDLS**](json_use_global_udls.md) - place user-defined string literals (UDLs) into the global namespace ## Library version diff --git a/docs/mkdocs/docs/api/macros/json_use_global_udls.md b/docs/mkdocs/docs/api/macros/json_use_global_udls.md new file mode 100644 index 000000000..856c508c5 --- /dev/null +++ b/docs/mkdocs/docs/api/macros/json_use_global_udls.md @@ -0,0 +1,93 @@ +# JSON_USE_GLOBAL_UDLS + +```cpp +#define JSON_USE_GLOBAL_UDLS /* value */ +``` + +When defined to `1`, the user-defined string literals (UDLs) are placed into the global namespace instead of +`nlohmann::literals::json_literals`. + +## Default definition + +The default value is `1`. + +```cpp +#define JSON_USE_GLOBAL_UDLS 1 +``` + +When the macro is not defined, the library will define it to its default value. + +## Notes + +!!! info "Future behavior change" + + 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. + +## Examples + +??? example "Example 1: Default behavior" + + The code below shows the default behavior using the `_json` UDL. + + ```cpp + #include + + #include + + int main() + { + auto j = "42"_json; + + std::cout << j << std::endl; + } + ``` + + Output: + + ```json + 42 + ``` + +??? example "Example 2: Namespaced UDLs" + + The code below shows how UDLs need to be brought into scope before using `_json` when `JSON_USE_GLOBAL_UDLS` is + defined to `0`. + + ```cpp + #define JSON_USE_GLOBAL_UDLS 0 + #include + + #include + + int main() + { + // auto j = "42"_json; // This line would fail to compile, + // because the UDLs are not in the global namespace + + // Bring the UDLs into scope + using namespace nlohmann::json_literals; + + auto j = "42"_json; + + std::cout << j << std::endl; + } + ``` + + Output: + + ```json + 42 + ``` + +## See also + +- [`operator""_json`](../operator_literal_json.md) +- [`operator""_json_pointer`](../operator_literal_json_pointer.md) + +## Version history + +- Added in version 3.11.0. diff --git a/docs/mkdocs/docs/api/operator_literal_json.md b/docs/mkdocs/docs/api/operator_literal_json.md index 8e0c65df0..330729de0 100644 --- a/docs/mkdocs/docs/api/operator_literal_json.md +++ b/docs/mkdocs/docs/api/operator_literal_json.md @@ -1,12 +1,22 @@ -# nlohmann::basic_json::operator""_json +# nlohmann::operator""_json ```cpp json operator "" _json(const char* s, std::size_t n); ``` This operator implements a user-defined string literal for JSON objects. It can be used by adding `#!cpp _json` to a -string literal and returns a [`json`](../json.md) object if no parse error occurred. +string literal and returns a [`json`](json.md) object if no parse error occurred. +Use any of the following lines to bring the operator into scope: +```cpp +using namespace nlohmann::literals; +using namespace nlohmann::json_literals; +using namespace nlohmann::literals::json_literals; +using namespace nlohmann; +``` + +Alternatively, define [`JSON_USE_GLOBAL_UDLS`](macros/json_use_global_udls.md) to make them available in the global +namespace. ## Parameters `s` (in) @@ -17,11 +27,11 @@ string literal and returns a [`json`](../json.md) object if no parse error occur ## Return value -[`json`](../json.md) value parsed from `s` +[`json`](json.md) value parsed from `s` ## Exceptions -The function can throw anything that [`parse(s, s+n)`](parse.md) would throw. +The function can throw anything that [`parse(s, s+n)`](basic_json/parse.md) would throw. ## Complexity @@ -46,3 +56,4 @@ Linear. ## Version history - Added in version 1.0.0. +- Moved to namespace `nlohmann::literals::json_literals` in 3.11.0. diff --git a/docs/mkdocs/docs/api/operator_literal_json_pointer.md b/docs/mkdocs/docs/api/operator_literal_json_pointer.md index 897ac07cd..7c788db2c 100644 --- a/docs/mkdocs/docs/api/operator_literal_json_pointer.md +++ b/docs/mkdocs/docs/api/operator_literal_json_pointer.md @@ -1,12 +1,22 @@ -# nlohmann::basic_json::operator""_json_pointer +# nlohmann::operator""_json_pointer ```cpp json_pointer operator "" _json_pointer(const char* s, std::size_t n); ``` This operator implements a user-defined string literal for JSON Pointers. It can be used by adding `#!cpp _json_pointer` -to a string literal and returns a [`json_pointer`](../json_pointer/index.md) object if no parse error occurred. +to a string literal and returns a [`json_pointer`](json_pointer/index.md) object if no parse error occurred. +Use any of the following lines to bring the operator into scope: +```cpp +using namespace nlohmann::literals; +using namespace nlohmann::json_literals; +using namespace nlohmann::literals::json_literals; +using namespace nlohmann; +``` + +Alternatively, define [`JSON_USE_GLOBAL_UDLS`](macros/json_use_global_udls.md) to make them available in the global +namespace. ## Parameters `s` (in) @@ -17,11 +27,11 @@ to a string literal and returns a [`json_pointer`](../json_pointer/index.md) obj ## Return value -[`json_pointer`](../json_pointer/index.md) value parsed from `s` +[`json_pointer`](json_pointer/index.md) value parsed from `s` ## Exceptions -The function can throw anything that [`json_pointer::json_pointer`](../json_pointer/index.md) would throw. +The function can throw anything that [`json_pointer::json_pointer`](json_pointer/index.md) would throw. ## Complexity @@ -45,8 +55,9 @@ Linear. ## See also -- [json_pointer](../json_pointer/index.md) - type to represent JSON Pointers +- [json_pointer](json_pointer/index.md) - type to represent JSON Pointers ## Version history - Added in version 2.0.0. +- Moved to namespace `nlohmann::literals::json_literals` in 3.11.0. diff --git a/docs/mkdocs/mkdocs.yml b/docs/mkdocs/mkdocs.yml index 6d2889c84..65182adbf 100644 --- a/docs/mkdocs/mkdocs.yml +++ b/docs/mkdocs/mkdocs.yml @@ -162,8 +162,6 @@ nav: - 'operator<=': api/basic_json/operator_le.md - 'operator>=': api/basic_json/operator_ge.md - 'operator<=>': api/basic_json/operator_spaceship.md - - 'operator""_json': api/basic_json/operator_literal_json.md - - 'operator""_json_pointer': api/basic_json/operator_literal_json_pointer.md - 'out_of_range': api/basic_json/out_of_range.md - 'other_error': api/basic_json/other_error.md - 'parse': api/basic_json/parse.md @@ -236,6 +234,8 @@ nav: - 'operator<<(basic_json)': api/operator_ltlt.md - 'operator<<(json_pointer)': api/operator_ltlt.md - 'operator>>(basic_json)': api/operator_gtgt.md + - 'operator""_json': api/operator_literal_json.md + - 'operator""_json_pointer': api/operator_literal_json_pointer.md - 'ordered_json': api/ordered_json.md - 'ordered_map': api/ordered_map.md - macros: @@ -258,6 +258,7 @@ nav: - 'JSON_SKIP_UNSUPPORTED_COMPILER_CHECK': api/macros/json_skip_unsupported_compiler_check.md - 'JSON_THROW_USER': api/macros/json_throw_user.md - 'JSON_TRY_USER': api/macros/json_throw_user.md + - 'JSON_USE_GLOBAL_UDLS': api/macros/json_use_global_udls.md - 'JSON_USE_IMPLICIT_CONVERSIONS': api/macros/json_use_implicit_conversions.md - 'JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON': api/macros/json_use_legacy_discarded_value_comparison.md - 'NLOHMANN_DEFINE_TYPE_INTRUSIVE': api/macros/nlohmann_define_type_intrusive.md @@ -332,6 +333,8 @@ plugins: redirect_maps: 'api/basic_json/operator_gtgt.md': api/operator_gtgt.md 'api/basic_json/operator_ltlt.md': api/operator_ltlt.md + 'api/basic_json/operator_literal_json.md': api/operator_literal_json.md + 'api/basic_json/operator_literal_json_pointer.md': api/operator_literal_json_pointer.md 'api/json_pointer/operator_string.md': api/json_pointer/operator_string_t.md extra_css: