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

Move UDLs out of the global namespace (#3605)

Browse Source 
* Move UDLs into nlohmann::literals::json_literals namespace

* Add 'using namespace' to unit tests

* Add 'using namespace' to examples

* Add 'using namespace' to README

* Move UDL mkdocs pages out of basic_json/

* Update documentation

* Update docset index

* Add JSON_GlobalUDLs CMake option

* Add unit test

* Build examples without global UDLs

* Add CI target
This commit is contained in:
Florian Albrechtskirchinger
2022-07-31 17:38:52 +02:00
committed by GitHub
parent 8fd8b52907
commit 9aafcbe965
61 changed files with 377 additions and 94 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -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

48
docs/mkdocs/docs/api/basic_json/operator_literal_json.md
View File

@@ -1,48 +0,0 @@
# <small>nlohmann::basic_json::</small>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.
## Parameters
`s` (in)
: a string representation of a JSON object
`n` (in)
: length of string `s`
## Return value
[`json`](../json.md) value parsed from `s`
## Exceptions
The function can throw anything that [`parse(s, s+n)`](parse.md) would throw.
## Complexity
Linear.
## Examples
??? example
The following code shows how to create JSON values from string literals.
```cpp
--8<-- "examples/operator_literal_json.cpp"
```
Output:
```json
--8<-- "examples/operator_literal_json.output"
```
## Version history
- Added in version 1.0.0.

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

@@ -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

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

@@ -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

99
docs/mkdocs/docs/api/macros/json_use_global_udls.md Normal file
View File

@@ -0,0 +1,99 @@
# 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.
!!! 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.
## Examples
??? example "Example 1: Default behavior"
The code below shows the default behavior using the `_json` UDL.
```cpp
#include <nlohmann/json.hpp>
#include <iostream>
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 <nlohmann/json.hpp>
#include <iostream>
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.

59
docs/mkdocs/docs/api/operator_literal_json.md Normal file
View File

@@ -0,0 +1,59 @@
# <small>nlohmann::</small>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.
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)
: a string representation of a JSON object
`n` (in)
: length of string `s`
## Return value
[`json`](json.md) value parsed from `s`
## Exceptions
The function can throw anything that [`parse(s, s+n)`](basic_json/parse.md) would throw.
## Complexity
Linear.
## Examples
??? example
The following code shows how to create JSON values from string literals.
```cpp
--8<-- "examples/operator_literal_json.cpp"
```
Output:
```json
--8<-- "examples/operator_literal_json.output"
```
## Version history
- Added in version 1.0.0.
- Moved to namespace `nlohmann::literals::json_literals` in 3.11.0.

21
docs/mkdocs/docs/api/basic_json/operator_literal_json_pointer.md → docs/mkdocs/docs/api/operator_literal_json_pointer.md
View File

@@ -1,12 +1,22 @@
# <small>nlohmann::basic_json::</small>operator""_json_pointer
# <small>nlohmann::</small>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.