]>
Commit | Line | Data |
---|---|---|
1e59de90 TL |
1 | # Supported Macros |
2 | ||
3 | Some aspects of the library can be configured by defining preprocessor macros before including the `json.hpp` header. | |
4 | ||
5 | ## `JSON_ASSERT(x)` | |
6 | ||
7 | The default value is `#!cpp assert(x)`. | |
8 | ||
9 | ## `JSON_CATCH_USER(exception)` | |
10 | ||
11 | This macro overrides `#!cpp catch` calls inside the library. The argument is the type of the exception to catch. As of | |
12 | version 3.8.0, the library only catches `std::out_of_range` exceptions internally to rethrow them as | |
13 | [`json::out_of_range`](../home/exceptions.md#out-of-range) exceptions. The macro is always followed by a scope. | |
14 | ||
15 | See [Switch off exceptions](../home/exceptions.md#switch-off-exceptions) for an example. | |
16 | ||
17 | ## `JSON_DIAGNOSTICS` | |
18 | ||
19 | This macro enables extended diagnostics for exception messages. Possible values are `1` to enable or `0` to disable | |
20 | (default). | |
21 | ||
22 | When enabled, exception messages contain a [JSON Pointer](json_pointer.md) to the JSON value that triggered the | |
23 | exception, see [Extended diagnostic messages](../home/exceptions.md#extended-diagnostic-messages) for an example. Note | |
24 | that enabling this macro increases the size of every JSON value by one pointer and adds some runtime overhead. | |
25 | ||
26 | The diagnostics messages can also be controlled with the CMake option `JSON_Diagnostics` (`OFF` by default) which sets | |
27 | `JSON_DIAGNOSTICS` accordingly. | |
28 | ||
29 | ## `JSON_HAS_CPP_11`, `JSON_HAS_CPP_14`, `JSON_HAS_CPP_17`, `JSON_HAS_CPP_20` | |
30 | ||
31 | The library targets C++11, but also supports some features introduced in later C++ versions (e.g., `std::string_view` | |
32 | support for C++17). For these new features, the library implements some preprocessor checks to determine the C++ | |
33 | standard. By defining any of these symbols, the internal check is overridden and the provided C++ version is | |
34 | unconditionally assumed. This can be helpful for compilers that only implement parts of the standard and would be | |
35 | detected incorrectly. | |
36 | ||
37 | ## `JSON_HAS_FILESYSTEM`, `JSON_HAS_EXPERIMENTAL_FILESYSTEM` | |
38 | ||
39 | When compiling with C++17, the library provides conversions from and to `std::filesystem::path`. As compiler support | |
40 | for filesystem is limited, the library tries to detect whether `<filesystem>`/`std::filesystem` (`JSON_HAS_FILESYSTEM`) | |
41 | or `<experimental/filesystem>`/`std::experimental::filesystem` (`JSON_HAS_EXPERIMENTAL_FILESYSTEM`) should be used. | |
42 | To override the built-in check, define `JSON_HAS_FILESYSTEM` or `JSON_HAS_EXPERIMENTAL_FILESYSTEM` to `1`. | |
43 | ||
44 | ## `JSON_NOEXCEPTION` | |
45 | ||
46 | Exceptions can be switched off by defining the symbol `JSON_NOEXCEPTION`. When defining `JSON_NOEXCEPTION`, `#!cpp try` | |
47 | is replaced by `#!cpp if (true)`, `#!cpp catch` is replaced by `#!cpp if (false)`, and `#!cpp throw` is replaced by | |
48 | `#!cpp std::abort()`. | |
49 | ||
50 | The same effect is achieved by setting the compiler flag `-fno-exceptions`. | |
51 | ||
52 | Note the explanatory [`what()`](https://en.cppreference.com/w/cpp/error/exception/what) string of exceptions is not | |
53 | available for MSVC if exceptions are disabled, see [#2824](https://github.com/nlohmann/json/discussions/2824). | |
54 | ||
55 | ## `JSON_NO_IO` | |
56 | ||
57 | When defined, headers `<cstdio>`, `<ios>`, `<iosfwd>`, `<istream>`, and `<ostream>` are not included and parse functions | |
58 | relying on these headers are excluded. This is relevant for environment where these I/O functions are disallowed for | |
59 | security reasons (e.g., Intel Software Guard Extensions (SGX)). | |
60 | ||
61 | ## `JSON_SKIP_UNSUPPORTED_COMPILER_CHECK` | |
62 | ||
63 | When defined, the library will not create a compile error when a known unsupported compiler is detected. This allows to | |
64 | use the library with compilers that do not fully support C++11 and may only work if unsupported features are not used. | |
65 | ||
66 | ## `JSON_THROW_USER(exception)` | |
67 | ||
68 | This macro overrides `#!cpp throw` calls inside the library. The argument is the exception to be thrown. Note that | |
69 | `JSON_THROW_USER` should leave the current scope (e.g., by throwing or aborting), as continuing after it may yield | |
70 | undefined behavior. | |
71 | ||
72 | See [Switch off exceptions](../home/exceptions.md#switch-off-exceptions) for an example. | |
73 | ||
74 | ## `JSON_TRY_USER` | |
75 | ||
76 | This macro overrides `#!cpp try` calls inside the library. It has no arguments and is always followed by a scope. | |
77 | ||
78 | See [Switch off exceptions](../home/exceptions.md#switch-off-exceptions) for an example. | |
79 | ||
80 | ## `JSON_USE_IMPLICIT_CONVERSIONS` | |
81 | ||
82 | When defined to `0`, implicit conversions are switched off. By default, implicit conversions are switched on. | |
83 | ||
84 | ??? example | |
85 | ||
86 | This is an example for an implicit conversion: | |
87 | ||
88 | ```cpp | |
89 | json j = "Hello, world!"; | |
90 | std::string s = j; | |
91 | ``` | |
92 | ||
93 | When `JSON_USE_IMPLICIT_CONVERSIONS` is defined to `0`, the code above does no longer compile. Instead, it must be | |
94 | written like this: | |
95 | ||
96 | ```cpp | |
97 | json j = "Hello, world!"; | |
98 | auto s = j.get<std::string>(); | |
99 | ``` | |
100 | ||
101 | Implicit conversions can also be controlled with the CMake option `JSON_ImplicitConversions` (`ON` by default) which | |
102 | sets `JSON_USE_IMPLICIT_CONVERSIONS` accordingly. | |
103 | ||
104 | ## `NLOHMANN_DEFINE_TYPE_INTRUSIVE(type, member...)` | |
105 | ||
106 | This macro can be used to simplify the serialization/deserialization of types if (1) want to use a JSON object as | |
107 | serialization and (2) want to use the member variable names as object keys in that object. | |
108 | ||
109 | The macro is to be defined inside the class/struct to create code for. Unlike | |
110 | [`NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE`](#nlohmann_define_type_non_intrusivetype-member), it can access private members. | |
111 | The first parameter is the name of the class/struct, and all remaining parameters name the members. | |
112 | ||
113 | See [Simplify your life with macros](arbitrary_types.md#simplify-your-life-with-macros) for an example. | |
114 | ||
115 | ## `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(type, member...)` | |
116 | ||
117 | This macro can be used to simplify the serialization/deserialization of types if (1) want to use a JSON object as | |
118 | serialization and (2) want to use the member variable names as object keys in that object. | |
119 | ||
120 | The macro is to be defined inside the namespace of the class/struct to create code for. Private members cannot be | |
121 | accessed. Use [`NLOHMANN_DEFINE_TYPE_INTRUSIVE`](#nlohmann_define_type_intrusivetype-member) in these scenarios. The | |
122 | first parameter is the name of the class/struct, and all remaining parameters name the members. | |
123 | ||
124 | See [Simplify your life with macros](arbitrary_types.md#simplify-your-life-with-macros) for an example. | |
125 | ||
126 | ## `NLOHMANN_JSON_SERIALIZE_ENUM(type, ...)` | |
127 | ||
128 | This macro simplifies the serialization/deserialization of enum types. See | |
129 | [Specializing enum conversion](enum_conversion.md) for more information. | |
130 | ||
131 | ## `NLOHMANN_JSON_VERSION_MAJOR`, `NLOHMANN_JSON_VERSION_MINOR`, `NLOHMANN_JSON_VERSION_PATCH` | |
132 | ||
133 | These macros are defined by the library and contain the version numbers according to | |
134 | [Semantic Versioning 2.0.0](https://semver.org). |