External/json
8
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

📝 overwork macro documentation

Browse Source
This commit is contained in:
Niels Lohmann 2022-04-16 22:33:06 +02:00
parent 10344907ff
commit 169e1da4b0
No known key found for this signature in database
GPG Key ID: 7F3CEA63AE251B69
16 changed files with 333 additions and 82 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
README.md
View File

@ -93,7 +93,7 @@ There is also a [**docset**](https://github.com/Kapeli/Dash-User-Contributions/t
## Examples
Beside the examples below, you may want to check the [documentation](https://nlohmann.github.io/json/) where each function contains a separate code example (e.g., check out [`emplace()`](https://nlohmann.github.io/json/api/basic_json/emplace/)). All [example files](https://github.com/nlohmann/json/tree/develop/doc/examples) can be compiled and executed on their own (e.g., file [emplace.cpp](https://github.com/nlohmann/json/blob/develop/doc/examples/emplace.cpp)).
Beside the examples below, you may want to check the [documentation](https://json.nlohmann.me/) where each function contains a separate code example (e.g., check out [`emplace()`](https://json.nlohmann.me/api/basic_json/emplace/)). All [example files](https://github.com/nlohmann/json/tree/develop/doc/examples) can be compiled and executed on their own (e.g., file [emplace.cpp](https://github.com/nlohmann/json/blob/develop/doc/examples/emplace.cpp)).
### JSON as first-class data type
@ -162,7 +162,7 @@ json j2 = {
};
```
Note that in all these cases, you never need to "tell" the compiler which JSON value type you want to use. If you want to be explicit or express some edge cases, the functions [`json::array()`](https://nlohmann.github.io/json/api/basic_json/array/) and [`json::object()`](https://nlohmann.github.io/json/api/basic_json/object/) will help:
Note that in all these cases, you never need to "tell" the compiler which JSON value type you want to use. If you want to be explicit or express some edge cases, the functions [`json::array()`](https://json.nlohmann.me/api/basic_json/array/) and [`json::object()`](https://json.nlohmann.me/api/basic_json/object/) will help:
```cpp
// a way to express the empty array []
@ -197,7 +197,7 @@ auto j2 = R"(
Note that without appending the `_json` suffix, the passed string literal is not parsed, but just used as JSON string value. That is, `json j = "{ \"happy\": true, \"pi\": 3.141 }"` would just store the string `"{ "happy": true, "pi": 3.141 }"` rather than parsing the actual object.
The above example can also be expressed explicitly using [`json::parse()`](https://nlohmann.github.io/json/api/basic_json/parse/):
The above example can also be expressed explicitly using [`json::parse()`](https://json.nlohmann.me/api/basic_json/parse/):
```cpp
// parse explicitly
@ -240,9 +240,9 @@ std::cout << cpp_string << " == " << cpp_string2 << " == " << j_string.get<std::
std::cout << j_string << " == " << serialized_string << std::endl;
```
[`.dump()`](https://nlohmann.github.io/json/api/basic_json/dump/) returns the originally stored string value.
[`.dump()`](https://json.nlohmann.me/api/basic_json/dump/) returns the originally stored string value.
Note the library only supports UTF-8. When you store strings with different encodings in the library, calling [`dump()`](https://nlohmann.github.io/json/api/basic_json/dump/) may throw an exception unless `json::error_handler_t::replace` or `json::error_handler_t::ignore` are used as error handlers.
Note the library only supports UTF-8. When you store strings with different encodings in the library, calling [`dump()`](https://json.nlohmann.me/api/basic_json/dump/) may throw an exception unless `json::error_handler_t::replace` or `json::error_handler_t::ignore` are used as error handlers.
#### To/from streams (e.g. files, string streams)
@ -730,7 +730,7 @@ Some important things:
* Those methods **MUST** be in your type's namespace (which can be the global namespace), or the library will not be able to locate them (in this example, they are in namespace `ns`, where `person` is defined).
* Those methods **MUST** be available (e.g., proper headers must be included) everywhere you use these conversions. Look at [issue 1108](https://github.com/nlohmann/json/issues/1108) for errors that may occur otherwise.
* When using `get<your_type>()`, `your_type` **MUST** be [DefaultConstructible](https://en.cppreference.com/w/cpp/named_req/DefaultConstructible). (There is a way to bypass this requirement described later.)
* In function `from_json`, use function [`at()`](https://nlohmann.github.io/json/api/basic_json/at/) to access the object values rather than `operator[]`. In case a key does not exist, `at` throws an exception that you can handle, whereas `operator[]` exhibits undefined behavior.
* In function `from_json`, use function [`at()`](https://json.nlohmann.me/api/basic_json/at/) to access the object values rather than `operator[]`. In case a key does not exist, `at` throws an exception that you can handle, whereas `operator[]` exhibits undefined behavior.
* You do not need to add serializers or deserializers for STL types like `std::vector`: the library already implements these.
#### Simplify your life with macros
@ -1647,7 +1647,7 @@ The library supports **Unicode input** as follows:
- [Unicode noncharacters](https://www.unicode.org/faq/private_use.html#nonchar1) will not be replaced by the library.
- Invalid surrogates (e.g., incomplete pairs such as `\uDEAD`) will yield parse errors.
- The strings stored in the library are UTF-8 encoded. When using the default string type (`std::string`), note that its length/size functions return the number of stored bytes rather than the number of characters or glyphs.
- When you store strings with different encodings in the library, calling [`dump()`](https://nlohmann.github.io/json/api/basic_json/dump/) may throw an exception unless `json::error_handler_t::replace` or `json::error_handler_t::ignore` are used as error handlers.
- When you store strings with different encodings in the library, calling [`dump()`](https://json.nlohmann.me/api/basic_json/dump/) may throw an exception unless `json::error_handler_t::replace` or `json::error_handler_t::ignore` are used as error handlers.
- To store wide strings (e.g., `std::wstring`), you need to convert them to a UTF-8 encoded `std::string` before, see [an example](https://json.nlohmann.me/home/faq/#wide-string-handling).
### Comments in JSON
@ -1682,7 +1682,7 @@ Here is a related issue [#1924](https://github.com/nlohmann/json/issues/1924).
### Further notes
- The code contains numerous debug **assertions** which can be switched off by defining the preprocessor macro `NDEBUG`, see the [documentation of `assert`](https://en.cppreference.com/w/cpp/error/assert). In particular, note [`operator[]`](https://nlohmann.github.io/json/api/basic_json/operator%5B%5D/) implements **unchecked access** for const objects: If the given key is not present, the behavior is undefined (think of a dereferenced null pointer) and yields an [assertion failure](https://github.com/nlohmann/json/issues/289) if assertions are switched on. If you are not sure whether an element in an object exists, use checked access with the [`at()` function](https://nlohmann.github.io/json/api/basic_json/at/). Furthermore, you can define `JSON_ASSERT(x)` to replace calls to `assert(x)`.
- The code contains numerous debug **assertions** which can be switched off by defining the preprocessor macro `NDEBUG`, see the [documentation of `assert`](https://en.cppreference.com/w/cpp/error/assert). In particular, note [`operator[]`](https://json.nlohmann.me/api/basic_json/operator%5B%5D/) implements **unchecked access** for const objects: If the given key is not present, the behavior is undefined (think of a dereferenced null pointer) and yields an [assertion failure](https://github.com/nlohmann/json/issues/289) if assertions are switched on. If you are not sure whether an element in an object exists, use checked access with the [`at()` function](https://json.nlohmann.me/api/basic_json/at/). Furthermore, you can define `JSON_ASSERT(x)` to replace calls to `assert(x)`.
- As the exact number type is not defined in the [JSON specification](https://tools.ietf.org/html/rfc8259.html), this library tries to choose the best fitting C++ number type automatically. As a result, the type `double` may be used to store numbers which may yield [**floating-point exceptions**](https://github.com/nlohmann/json/issues/181) in certain rare situations if floating-point exceptions have been unmasked in the calling code. These exceptions are not caused by the library and need to be fixed in the calling code, such as by re-masking the exceptions prior to calling library functions.
- The code can be compiled without C++ **runtime type identification** features; that is, you can use the `-fno-rtti` compiler flag.
- **Exceptions** are used widely within the library. They can, however, be switched off with either using the compiler flag `-fno-exceptions` or by defining the symbol `JSON_NOEXCEPTION`. In this case, exceptions are replaced by `abort()` calls. You can further control this behavior by defining `JSON_THROW_USER` (overriding `throw`), `JSON_TRY_USER` (overriding `try`), and `JSON_CATCH_USER` (overriding `catch`). Note that `JSON_THROW_USER` should leave the current scope (e.g., by throwing or aborting), as continuing after it may yield undefined behavior. Note the explanatory [`what()`](https://en.cppreference.com/w/cpp/error/exception/what) string of exceptions is not available for MSVC if exceptions are disabled, see [#2824](https://github.com/nlohmann/json/discussions/2824).

6
doc/mkdocs/docs/api/basic_json/back.md
View File

@ -33,12 +33,6 @@ If the JSON value is `#!json null`, exception
Constant.
## Notes
!!! danger
Calling `back` on an empty array or object is undefined behavior and is **guarded by an assertion**!
## Examples
??? example

10
doc/mkdocs/docs/api/basic_json/basic_json.md
View File

@ -250,17 +250,15 @@ basic_json(basic_json&& other) noexcept;
!!! info "Preconditions"
- Iterators `first` and `last` must be initialized. **This precondition is enforced with an assertion (see
warning).** If assertions are switched off, a violation of this precondition yields undefined behavior.
- Iterators `first` and `last` must be initialized. **This precondition is enforced with a
[runtime assertion](../../features/assertions.md).
- Range `[first, last)` is valid. Usually, this precondition cannot be checked efficiently. Only certain edge
cases are detected; see the description of the exceptions above. A violation of this precondition yields
undefined behavior.
!!! warning
!!! danger
A precondition is enforced with a runtime assertion that will result in calling `std::abort` if this
precondition is not met. Assertions can be disabled by defining `NDEBUG` at compile time. See
<https://en.cppreference.com/w/cpp/error/assert> for more information.
A precondition is enforced with a [runtime assertion](../../features/assertions.md).
- Overload 8:

6
doc/mkdocs/docs/api/basic_json/front.md
View File

@ -26,12 +26,6 @@ If the JSON value is `#!json null`, exception
Constant.
## Notes
!!! danger
Calling `front` on an empty array or object is undefined behavior and is **guarded by an assertion**!
## Examples
??? example

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

@ -16,7 +16,7 @@ Implicit reference access to the internally stored JSON value. No copies are mad
: reference type; must be a reference to [`array_t`](array_t.md), [`object_t`](object_t.md),
[`string_t`](string_t.md), [`boolean_t`](boolean_t.md), [`number_integer_t`](number_integer_t.md), or
[`number_unsigned_t`](number_unsigned_t.md), [`number_float_t`](number_float_t.md), or [`binary_t`](binary_t.md).
Enforced by static assertion.
Enforced by a static assertion.
## Return value

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

@ -77,7 +77,8 @@ Strong exception safety: if an exception occurs, the original value stays intact
!!! danger
1. If the element with key `idx` does not exist, the behavior is undefined.
2. If the element with key `key` does not exist, the behavior is undefined and is **guarded by an assertion**!
2. If the element with key `key` does not exist, the behavior is undefined and is **guarded by a
[runtime assertion](../../features/assertions.md)**!
1. The non-const version may add values: If `idx` is beyond the range of the array (i.e., `idx >= size()`), then the
array is silently filled up with `#!json null` values to make `idx` a valid reference to the last stored element. In

7
doc/mkdocs/docs/api/macros/index.md
View File

@ -6,13 +6,14 @@
Some aspects of the library can be configured by defining preprocessor macros before including the `json.hpp` header.
- [`JSON_ASSERT(x)`](json_assert.md)
- [**JSON_ASSERT(x)**](json_assert.md) - control behavior of runtime assertions
- `JSON_CATCH_USER(exception)`
- `JSON_DIAGNOSTICS`
- [**JSON_DIAGNOSTICS**](json_diagnostics.md) - control extended diagnostics
- `JSON_HAS_CPP_11`, `JSON_HAS_CPP_14`, `JSON_HAS_CPP_17`, `JSON_HAS_CPP_20`
- [**JSON_HAS_FILESYSTEM**/**JSON_HAS_EXPERIMENTAL_FILESYSTEM**](json_has_filesystem.md) - control `std::filesystem` support
- `JSON_NOEXCEPTION`
- `JSON_NO_IO`
- `JSON_SKIP_UNSUPPORTED_COMPILER_CHECK`
- [**JSON_SKIP_UNSUPPORTED_COMPILER_CHECK**](json_skip_unsupported_compiler_check.md) - do not warn about unsupported compilers
- `JSON_THROW_USER(exception)`
- `JSON_TRY_USER`
- `JSON_USE_IMPLICIT_CONVERSIONS`

79
doc/mkdocs/docs/api/macros/json_assert.md
View File

@ -1,11 +1,84 @@
# JSON_ASSERT(x)
```cpp
JSON_ASSERT(x)
#define JSON_ASSERT(x) /* value */
```
## Default implementation
This macro controls which code is executed for [runtime assertions](../../features/assertions.md) of the libraries.
## Parameters
`x` (in)
: expression of scalar type
## Default definition
The default value is [`#!cpp assert(x)`](https://en.cppreference.com/w/cpp/error/assert).
```cpp
assert(x);
#define JSON_ASSERT(x) assert(x)
```
Therefore, assertions can be switched off by defining `NDEBUG`.
## Notes
- The library uses numerous assertions to guarantee invariants and to abort in case of otherwise undefined behavior
(e.g., when calling [operator[]](../basic_json/operator%5B%5D.md) with a missing object key on a `const` object). See
page [runtime assertions](../../features/assertions.md) for more information.
- Defining the macro to code that does not call `std::abort` may leave the library in an undefined state.
- The macro is undefined outside the library.
## Examples
??? example "Example 1: default behavior"
The following code will trigger an assertion at runtime:
```cpp
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
const json j = {{"key", "value"}};
auto v = j["missing"];
}
```
Output:
```
Assertion failed: (m_value.object->find(key) != m_value.object->end()), function operator[], file json.hpp, line 2144.
```
??? example "Example 2: user-defined behavior"
The assertion reporting can be changed by defining `JSON_ASSERT(x)` differently.
```cpp
#include <cstdio>
#include <cstdlib>
#define JSON_ASSERT(x) if(!(x)){fprintf(stderr, "assertion error in %s\n", __FUNCTION__); std::abort();}
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
const json j = {{"key", "value"}};
auto v = j["missing"];
}
```
Output:
```
assertion error in operator[]
```
## Version history
- Added in version 3.9.0.

67
doc/mkdocs/docs/api/macros/json_diagnostics.md Normal file
View File

@ -0,0 +1,67 @@
# JSON_DIAGNOSTICS
```cpp
#define JSON_DIAGNOSTICS /* value */
```
This macro enables [extended diagnostics for exception messages](../../home/exceptions.md#extended-diagnostic-messages).
Possible values are `1` to enable or `0` to disable (default).
When enabled, exception messages contain a [JSON Pointer](../json_pointer/json_pointer.md) to the JSON value that
triggered the exception. Note that enabling this macro increases the size of every JSON value by one pointer and adds
some runtime overhead.
The diagnostics messages can also be controlled with the CMake option `JSON_Diagnostics` (`OFF` by default) which sets
`JSON_DIAGNOSTICS` accordingly.
## Default definition
The default value is `0` (extended diagnostics are switched off).
```cpp
#define JSON_DIAGNOSTICS 0
```
When the macro is not defined, the library will define it to its default value.
## Notes
!!! warning
As this macro changes the definition of the `basic_json` object, it MUST be defined in the same way globally, even
across different compilation units; DO NOT link together code compiled with different definitions of
`JSON_DIAGNOSTICS` as this is a violation of the One Definition Rule and will cause undefined behaviour.
## Examples
??? example "Example 1: default behavior"
```cpp
--8<-- "examples/diagnostics_standard.cpp"
```
Output:
```
--8<-- "examples/diagnostics_standard.output"
```
This exception can be hard to debug if storing the value `#!c "12"` and accessing it is further apart.
??? example "Example 2: extended diagnostic messages"
```cpp
--8<-- "examples/diagnostics_extended.cpp"
```
Output:
```
--8<-- "examples/diagnostics_extended.output"
```
Now the exception message contains a JSON Pointer `/address/housenumber` that indicates which value has the wrong type.
## Version history
- Added in version 3.10.0.

30
doc/mkdocs/docs/api/macros/json_has_filesystem.md Normal file
View File

@ -0,0 +1,30 @@
# JSON_HAS_FILESYSTEM / JSON_HAS_EXPERIMENTAL_FILESYSTEM
```cpp
#define JSON_HAS_FILESYSTEM /* value */
#define JSON_HAS_EXPERIMENTAL_FILESYSTEM /* value */
```
When compiling with C++17, the library provides conversions from and to
[`std::filesystem::path`](https://en.cppreference.com/w/cpp/filesystem/path). As compiler support for filesystem is
limited, the library tries to detect whether
[`<filesystem>`/`std::filesystem`](https://en.cppreference.com/w/cpp/header/filesystem) (`JSON_HAS_FILESYSTEM`) or
[`<experimental/filesystem>`/`std::experimental::filesystem`](https://en.cppreference.com/w/cpp/header/experimental/filesystem)
(`JSON_HAS_EXPERIMENTAL_FILESYSTEM`) should be used. To override the built-in check, define `JSON_HAS_FILESYSTEM` or
`JSON_HAS_EXPERIMENTAL_FILESYSTEM` to `1`.
## Default definition
The default value is detected based on the preprocessor macros `#!cpp __cpp_lib_filesystem`,
`#!cpp __cpp_lib_experimental_filesystem`, `#!cpp __has_include(<filesystem>)`, or
`#!cpp __has_include(<experimental/filesystem>)`.
## Notes
- Note that older compilers or older versions of libstd++ also require the library `stdc++fs` to be linked to for
filesystem support.
- Both macros are undefined outside the library.
## Version history
- Added in version 3.10.5.

20
doc/mkdocs/docs/api/macros/json_skip_unsupported_compiler_check.md Normal file
View File

@ -0,0 +1,20 @@
# JSON_SKIP_UNSUPPORTED_COMPILER_CHECK
```cpp
#undef JSON_SKIP_UNSUPPORTED_COMPILER_CHECK
```
When defined, the library will not create a compile error when a known unsupported compiler is detected. This allows to
use the library with compilers that do not fully support C++11 and may only work if unsupported features are not used.
## Default definition
By default, the macro is not defined.
```cpp
#undef JSON_SKIP_UNSUPPORTED_COMPILER_CHECK
```
## Version history
Added in version 3.2.0.

104
doc/mkdocs/docs/features/assertions.md Normal file
View File

@ -0,0 +1,104 @@
# Runtime Assertions
The code contains numerous debug assertions to ensure class invariants are valid or to detect undefined behavior.
Whereas the former class invariants are nothing to be concerned of, the latter checks for undefined behavior are to
detect bugs in client code.
## Switch off runtime assertions
Runtime assertions can be switched off by defining the preprocessor macro `NDEBUG` (see the
[documentation of assert](https://en.cppreference.com/w/cpp/error/assert)) which is the default for release builds.
## Change assertion behavior
The behavior of runtime assertions can be changes by defining macro [`JSON_ASSERT(x)`](../api/macros/json_assert.md)
before including the `json.hpp` header.
## Function with runtime assertions
### Unchecked object access to a const value
Function [`operator[]`](../api/basic_json/operator%5B%5D.md) implements unchecked access for objects. Whereas a missing
key is added in case of non-const objects, accessing a const object with a missing key is undefined behavior (think of a
dereferenced null pointer) and yields an runtime assertion.
If you are not sure whether an element in an object exists, use checked access with the
[`at` function](../api/basic_json/at.md) or call the [`contains` function](../api/basic_json/contains.md) before.
See also the documentation on [element access](element_access/index.md).
??? example "Example 1: Missing object key"
The following code will trigger an assertion at runtime:
```cpp
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
const json j = {{"key", "value"}};
auto v = j["missing"];
}
```
Output:
```
Assertion failed: (m_value.object->find(key) != m_value.object->end()), function operator[], file json.hpp, line 2144.
```
### Constructing from an uninitialized iterator range
Constructing a JSON value from an iterator range (see [constructor](../api/basic_json/basic_json.md)) with an
uninitialized iterator is undefined behavior and yields a runtime assertion.
??? example "Example 2: Uninitialized iterator range"
The following code will trigger an assertion at runtime:
```cpp
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
json::iterator it1, it2;
json j(it1, it2);
}
```
Output:
```
Assertion failed: (m_object != nullptr), function operator++, file iter_impl.hpp, line 368.
```
### Operations on uninitialized iterators
Any operation on uninitialized iterators (i.e., iterators that are not associated with any JSON value) is undefined
behavior and yields a runtime assertion.
??? example "Example 3: Uninitialized iterator"
The following code will trigger an assertion at runtime:
```cpp
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
json::iterator it;
++it;
}
```
Output:
```
Assertion failed: (m_object != nullptr), function operator++, file iter_impl.hpp, line 368.
```

12
doc/mkdocs/docs/features/element_access/unchecked_access.md
View File

@ -94,9 +94,9 @@ When accessing an invalid index (i.e., an index greater than or equal to the arr
## Summary
| scenario | non-const value | const value |
|-----------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------|
| access to existing object key | reference to existing value is returned | const reference to existing value is returned |
| access to valid array index | reference to existing value is returned | const reference to existing value is returned |
| access to non-existing object key | reference to newly inserted `#!json null` value is returned | **undefined behavior**; assertion in debug mode |
| access to invalid array index | reference to newly inserted `#!json null` value is returned; any index between previous maximal index and passed index are filled with `#!json null` | **undefined behavior**; assertion in debug mode |
| scenario | non-const value | const value |
|-----------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| access to existing object key | reference to existing value is returned | const reference to existing value is returned |
| access to valid array index | reference to existing value is returned | const reference to existing value is returned |
| access to non-existing object key | reference to newly inserted `#!json null` value is returned | **undefined behavior**; [runtime assertion](../assertions.md) in debug mode |
| access to invalid array index | reference to newly inserted `#!json null` value is returned; any index between previous maximal index and passed index are filled with `#!json null` | **undefined behavior**; [runtime assertion](../assertions.md) in debug mode |

47
doc/mkdocs/docs/features/macros.md
View File

@ -4,17 +4,9 @@ Some aspects of the library can be configured by defining preprocessor macros be
## `JSON_ASSERT(x)`
This macro controls which code is executed for runtime assertions of the libraries.
This macro controls which code is executed for [runtime assertions](assertions.md) of the library.
!!! info "Default behavior"
The default value is [`#!cpp assert(x)`](https://en.cppreference.com/w/cpp/error/assert).
```cpp
#define JSON_ASSERT(x) assert(x)
```
The macro was introduced in version 3.9.0.
See [full documentation of `JSON_ASSERT(x)`](../api/macros/json_assert.md).
## `JSON_CATCH_USER(exception)`
@ -55,19 +47,7 @@ that enabling this macro increases the size of every JSON value by one pointer a
The diagnostics messages can also be controlled with the CMake option `JSON_Diagnostics` (`OFF` by default) which sets
`JSON_DIAGNOSTICS` accordingly.
!!! warning
As this macro changes the definition of the `basic_json` object, it MUST be defined in the same way globally, even
across different compilation units; DO NOT link together code compiled with different definitions of
`JSON_DIAGNOSTICS` as this is a violation of the One Definition Rule and will cause undefined behaviour.
!!! info "Default behavior"
```cpp
#define JSON_DIAGNOSTICS 0
```
The macro was introduced in version 3.10.0.
See [full documentation of `JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md).
## `JSON_HAS_CPP_11`, `JSON_HAS_CPP_14`, `JSON_HAS_CPP_17`, `JSON_HAS_CPP_20`
@ -91,16 +71,7 @@ for filesystem is limited, the library tries to detect whether `<filesystem>`/`s
or `<experimental/filesystem>`/`std::experimental::filesystem` (`JSON_HAS_EXPERIMENTAL_FILESYSTEM`) should be used.
To override the built-in check, define `JSON_HAS_FILESYSTEM` or `JSON_HAS_EXPERIMENTAL_FILESYSTEM` to `1`.
!!! info "Default behavior"
The default value is detected based on the preprocessor macros `#!cpp __cpp_lib_filesystem`,
`#!cpp __cpp_lib_experimental_filesystem`, `#!cpp __has_include(<filesystem>)`, or
`#!cpp __has_include(<experimental/filesystem>)`.
Note that older compilers or older versions of libstd++ also require the library `stdc++fs` to be linked to for
filesystem support.
The macros were introduced in version 3.10.5.
See [full documentation of `JSON_HAS_FILESYSTEM` and `JSON_HAS_EXPERIMENTAL_FILESYSTEM`](../api/macros/json_has_filesystem.md).
## `JSON_NOEXCEPTION`
@ -159,15 +130,7 @@ The macro was introduced in version 3.11.0.
When defined, the library will not create a compile error when a known unsupported compiler is detected. This allows to
use the library with compilers that do not fully support C++11 and may only work if unsupported features are not used.
!!! info "Default behavior"
By default, the macro is not defined.
```cpp
#undef JSON_SKIP_UNSUPPORTED_COMPILER_CHECK
```
The macro was introduced in version 3.2.0.
See [full documentation of `JSON_SKIP_UNSUPPORTED_COMPILER_CHECK`](../api/macros/json_skip_unsupported_compiler_check.md).
## `JSON_THROW_USER(exception)`

5
doc/mkdocs/mkdocs.yml
View File

@ -64,6 +64,7 @@ nav:
- features/parsing/parse_exceptions.md
- features/parsing/parser_callbacks.md
- features/parsing/sax_interface.md
- features/assertions.md
- features/enum_conversion.md
- features/macros.md
- Types:
@ -232,6 +233,10 @@ nav:
- macros:
- 'Overview': api/macros/index.md
- 'JSON_ASSERT(x)': api/macros/json_assert.md
- 'JSON_DIAGNOSTICS': api/macros/json_diagnostics.md
- 'JSON_HAS_EXPERIMENTAL_FILESYSTEM': api/macros/json_has_filesystem.md
- 'JSON_HAS_FILESYSTEM': api/macros/json_has_filesystem.md
- 'JSON_SKIP_UNSUPPORTED_COMPILER_CHECK': api/macros/json_skip_unsupported_compiler_check.md
# Extras
extra:

1
doc/mkdocs/scripts/check_structure.py Normal file → Executable file
View File

@ -23,6 +23,7 @@ def check_structure():
'Exceptions',
'Complexity',
'Possible implementation',
'Default definition',
'Notes',
'Examples',
'See also',