diff --git a/doc/mkdocs/docs/api/macros/index.md b/doc/mkdocs/docs/api/macros/index.md index 585a88164..0552bdca2 100644 --- a/doc/mkdocs/docs/api/macros/index.md +++ b/doc/mkdocs/docs/api/macros/index.md @@ -13,11 +13,9 @@ header. ## Exceptions -- `JSON_CATCH_USER(exception)` +- [**JSON_CATCH_USER(exception)**
**JSON_THROW_USER(exception)**
**JSON_TRY_USER**](json_throw_user.md) - control exceptions - [**JSON_DIAGNOSTICS**](json_diagnostics.md) - control extended diagnostics -- `JSON_NOEXCEPTION` -- `JSON_THROW_USER(exception)` -- `JSON_TRY_USER` +- [**JSON_NOEXCEPTION**](json_noexception.md) - switch off exceptions ## Language support diff --git a/doc/mkdocs/docs/api/macros/json_noexception.md b/doc/mkdocs/docs/api/macros/json_noexception.md new file mode 100644 index 000000000..0f32b63e9 --- /dev/null +++ b/doc/mkdocs/docs/api/macros/json_noexception.md @@ -0,0 +1,32 @@ +# JSON_NOEXCEPTION + +```cpp +#define JSON_NOEXCEPTION +``` + +Exceptions can be switched off by defining the symbol `JSON_NOEXCEPTION`. When defining `JSON_NOEXCEPTION`, `#!cpp try` +is replaced by `#!cpp if (true)`, `#!cpp catch` is replaced by `#!cpp if (false)`, and `#!cpp throw` is replaced by +`#!cpp std::abort()`. + +The same effect is achieved by setting the compiler flag `-fno-exceptions`. + +## Default definition + +By default, the macro is not defined. + +```cpp +#undef JSON_NOEXCEPTION +``` + +## Notes + +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). + +## See also + +- [Switch off exceptions](../../home/exceptions.md#switch-off-exceptions) for more information how to switch off exceptions + +## Version history + +Added in version 2.1.0. diff --git a/doc/mkdocs/docs/api/macros/json_skip_library_version_check.md b/doc/mkdocs/docs/api/macros/json_skip_library_version_check.md index e2b3a0097..4dd9f04b0 100644 --- a/doc/mkdocs/docs/api/macros/json_skip_library_version_check.md +++ b/doc/mkdocs/docs/api/macros/json_skip_library_version_check.md @@ -15,6 +15,23 @@ By default, the macro is not defined. #undef JSON_SKIP_LIBRARY_VERSION_CHECK ``` +## Notes + +!!! warning + + Mixing different library versions in the same code can be a problem as the different versions may not be ABI + compatible. + +## Examples + +!!! example + + The following warning will be shown in case a different version of the library was already included: + + ``` + Already included a different version of the library! + ``` + ## Version history Added in version 3.11.0. diff --git a/doc/mkdocs/docs/api/macros/json_throw_user.md b/doc/mkdocs/docs/api/macros/json_throw_user.md new file mode 100644 index 000000000..a4d99a205 --- /dev/null +++ b/doc/mkdocs/docs/api/macros/json_throw_user.md @@ -0,0 +1,70 @@ +# JSON_CATCH_USER(exception), JSON_THROW_USER(exception), JSON_TRY_USER + +```cpp +// (1) +#define JSON_CATCH_USER(exception) /* value */ +// (2) +#define JSON_THROW_USER(exception) /* value */ +// (3) +#define JSON_TRY_USER /* value */ +``` + +Controls how exceptions are handled by the library. + +1. This macro overrides [`#!cpp catch`](https://en.cppreference.com/w/cpp/language/try_catch) calls inside the library. + The argument is the type of the exception to catch. As of version 3.8.0, the library only catches `std::out_of_range` + exceptions internally to rethrow them as [`json::out_of_range`](../../home/exceptions.md#out-of-range) exceptions. + The macro is always followed by a scope. +2. This macro overrides `#!cpp throw` calls inside the library. The argument is the exception to be thrown. Note that + `JSON_THROW_USER` should leave the current scope (e.g., by throwing or aborting), as continuing after it may yield + undefined behavior. +3. This macro overrides `#!cpp try` calls inside the library. It has no arguments and is always followed by a scope. + +## Default definition + +By default, the macros map to their respective C++ keywords: + +```cpp +#define JSON_CATCH_USER(exception) catch(exception) +#define JSON_THROW_USER(exception) throw exception +#define JSON_TRY_USER try +``` + +When exceptions are switched off, the `#!cpp try` block is executed unconditionally, and throwing exceptions is +replaced by calling [`std::abort`](https://en.cppreference.com/w/cpp/utility/program/abort) to make reaching the +`cpp throw` branch abort the process. + +```cpp +#define JSON_THROW_USER(exception) std::abort() +#define JSON_TRY_USER if (true) +#define JSON_CATCH_USER(exception) if (false) +``` + +## Examples + +??? example + + The code below switches off exceptions and creates a log entry with a detailed error message in case of errors. + + ```cpp + #include + + #define JSON_TRY_USER if(true) + #define JSON_CATCH_USER(exception) if(false) + #define JSON_THROW_USER(exception) \ + {std::clog << "Error in " << __FILE__ << ":" << __LINE__ \ + << " (function " << __FUNCTION__ << ") - " \ + << (exception).what() << std::endl; \ + std::abort();} + + #include + ``` + +## See also + +- [Switch off exceptions](../../home/exceptions.md#switch-off-exceptions) for more information how to switch off exceptions +- [JSON_NOEXCEPTION](JSON_NOEXCEPTION) - switch off exceptions + +## Version history + +- Added in version 3.1.0. diff --git a/doc/mkdocs/docs/features/macros.md b/doc/mkdocs/docs/features/macros.md index 0fcae96d9..25411d8f9 100644 --- a/doc/mkdocs/docs/features/macros.md +++ b/doc/mkdocs/docs/features/macros.md @@ -11,29 +11,8 @@ See [full documentation of `JSON_ASSERT(x)`](../api/macros/json_assert.md). ## `JSON_CATCH_USER(exception)` This macro overrides [`#!cpp catch`](https://en.cppreference.com/w/cpp/language/try_catch) calls inside the library. -The argument is the type of the exception to catch. As of version 3.8.0, the library only catches `std::out_of_range` -exceptions internally to rethrow them as [`json::out_of_range`](../home/exceptions.md#out-of-range) exceptions. The -macro is always followed by a scope. -See [Switch off exceptions](../home/exceptions.md#switch-off-exceptions) for an example. - -!!! info "Default behavior" - - When exceptions are enabled, the default value is - [`#!cpp catch(exception)`](https://en.cppreference.com/w/cpp/language/try_catch). - - ```cpp - #define JSON_CATCH_USER(exception) catch(exception) - ``` - - When exceptions are switched off by the compiler, the default value is `#!cpp if (false)` to make the catch block - unreachable. - - ```cpp - #define JSON_CATCH_USER(exception) if (false) - ``` - -The macro was introduced in version 3.1.0. +See [full documentation of `JSON_CATCH_USER(exception)`](../api/macros/json_throw_user.md). ## `JSON_DIAGNOSTICS` @@ -70,24 +49,9 @@ See [full documentation of `JSON_HAS_FILESYSTEM` and `JSON_HAS_EXPERIMENTAL_FILE ## `JSON_NOEXCEPTION` -Exceptions can be switched off by defining the symbol `JSON_NOEXCEPTION`. When defining `JSON_NOEXCEPTION`, `#!cpp try` -is replaced by `#!cpp if (true)`, `#!cpp catch` is replaced by `#!cpp if (false)`, and `#!cpp throw` is replaced by -`#!cpp std::abort()`. +Exceptions can be switched off by defining the symbol `JSON_NOEXCEPTION`. -!!! info "Default behavior" - - By default, the macro is not defined. - - ```cpp - #undef JSON_NOEXCEPTION - ``` - -The same effect is achieved by setting the compiler flag `-fno-exceptions`. - -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). - -The macro was introduced in version 2.1.0. +See [full documentation of `JSON_NOEXCEPTION`](../api/macros/json_noexception.md). ## `JSON_NO_IO` @@ -113,54 +77,15 @@ See [full documentation of `JSON_SKIP_UNSUPPORTED_COMPILER_CHECK`](../api/macros ## `JSON_THROW_USER(exception)` -This macro overrides `#!cpp throw` calls inside the library. The argument is the exception to be thrown. Note that -`JSON_THROW_USER` should leave the current scope (e.g., by throwing or aborting), as continuing after it may yield -undefined behavior. +This macro overrides `#!cpp throw` calls inside the library. The argument is the exception to be thrown. -!!! info "Default behavior" - - When exceptions are enabled, the default value is - [`#!cpp throw exception`](https://en.cppreference.com/w/cpp/language/throw). - - ```cpp - #define JSON_THROW_USER(exception) throw exception - ``` - - When exceptions are switched off by the compiler, the default value is - [`#!cpp std::abort()`](https://en.cppreference.com/w/cpp/utility/program/abort) to make reaching the throw branch - abort the process. - - ```cpp - #define JSON_THROW_USER(exception) std::abort() - ``` - -See [Switch off exceptions](../home/exceptions.md#switch-off-exceptions) for an example. - -The macro was introduced in version 3.1.0. +See [full documentation of `JSON_THROW_USER(exception)`](../api/macros/json_throw_user.md). ## `JSON_TRY_USER` -This macro overrides `#!cpp try` calls inside the library. It has no arguments and is always followed by a scope. +This macro overrides `#!cpp try` calls inside the library. -!!! info "Default behavior" - - When exceptions are enabled, the default value is - [`#!cpp try`](https://en.cppreference.com/w/cpp/language/try_catch). - - ```cpp - #define JSON_TRY_USER try - ``` - - When exceptions are switched off by the compiler, the default value is `#!cpp if (true)` to unconditionally execute - the following code block. - - ```cpp - #define JSON_TRY_USER if (true) - ``` - -See [Switch off exceptions](../home/exceptions.md#switch-off-exceptions) for an example. - -The macro was introduced in version 3.1.0. +See [full documentation of `JSON_TRY_USER`](../api/macros/json_throw_user.md). ## `JSON_USE_IMPLICIT_CONVERSIONS` diff --git a/doc/mkdocs/docs/home/exceptions.md b/doc/mkdocs/docs/home/exceptions.md index 1241926cf..666d225bd 100644 --- a/doc/mkdocs/docs/home/exceptions.md +++ b/doc/mkdocs/docs/home/exceptions.md @@ -28,9 +28,9 @@ class json::parse_error { ### Switch off exceptions -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 `#!cpp throw`), `JSON_TRY_USER` (overriding `#!cpp try`), and `JSON_CATCH_USER` (overriding `#!cpp catch`). +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`](../api/macros/json_noexception.md). In this case, exceptions are replaced by `abort()` calls. You can further control this behavior by defining `JSON_THROW_USER` (overriding `#!cpp throw`), `JSON_TRY_USER` (overriding `#!cpp try`), and `JSON_CATCH_USER` (overriding `#!cpp 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 that [`JSON_THROW_USER`](../api/macros/json_throw_user.md) should leave the current scope (e.g., by throwing or aborting), as continuing after it may yield undefined behavior. ??? example @@ -52,6 +52,8 @@ Note that `JSON_THROW_USER` should leave the current scope (e.g., by throwing or 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). +See [documentation of `JSON_TRY_USER`, `JSON_CATCH_USER` and `JSON_THROW_USER`](../api/macros/json_throw_user.md) for more information. + ### Extended diagnostic messages Exceptions in the library are thrown in the local context of the JSON value they are detected. This makes detailed diagnostics messages, and hence debugging, difficult. @@ -88,6 +90,7 @@ As this global context comes at the price of storing one additional pointer per Now the exception message contains a JSON Pointer `/address/housenumber` that indicates which value has the wrong type. +See [documentation of `JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md) for more information. ## Parse errors diff --git a/doc/mkdocs/mkdocs.yml b/doc/mkdocs/mkdocs.yml index cc8dd5e85..a6563aafd 100644 --- a/doc/mkdocs/mkdocs.yml +++ b/doc/mkdocs/mkdocs.yml @@ -234,17 +234,21 @@ nav: - macros: - 'Overview': api/macros/index.md - 'JSON_ASSERT(x)': api/macros/json_assert.md + - 'JSON_CATCH_USER': api/macros/json_throw_user.md - 'JSON_DIAGNOSTICS': api/macros/json_diagnostics.md - - 'JSON_HAS_EXPERIMENTAL_FILESYSTEM': api/macros/json_has_filesystem.md - 'JSON_HAS_CPP_11': api/macros/json_has_cpp_11.md - 'JSON_HAS_CPP_14': api/macros/json_has_cpp_11.md - 'JSON_HAS_CPP_17': api/macros/json_has_cpp_11.md - 'JSON_HAS_CPP_20': api/macros/json_has_cpp_11.md + - 'JSON_HAS_EXPERIMENTAL_FILESYSTEM': api/macros/json_has_filesystem.md - 'JSON_HAS_FILESYSTEM': api/macros/json_has_filesystem.md - - 'JSON_USE_IMPLICIT_CONVERSIONS': api/macros/json_use_implicit_conversions.md + - 'JSON_NOEXCEPTION': api/macros/json_noexception.md - 'JSON_NO_IO': api/macros/json_no_io.md - 'JSON_SKIP_LIBRARY_VERSION_CHECK': api/macros/json_skip_library_version_check.md - '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_IMPLICIT_CONVERSIONS': api/macros/json_use_implicit_conversions.md - 'NLOHMANN_JSON_VERSION_MAJOR': api/macros/nlohmann_json_version_major.md - 'NLOHMANN_JSON_VERSION_MINOR': api/macros/nlohmann_json_version_major.md - 'NLOHMANN_JSON_VERSION_PATCH': api/macros/nlohmann_json_version_major.md