Niels Lohmann
330fbead59
* Document clang-tidy exclusions and drop unneeded ones Re-enable every excluded check in a run of clang-tidy 22 over all tests and remove the seven that never fire (cert-err58-cpp, clang-analyzer-webkit.NoUncountedMemberChecker, cppcoreguidelines-virtual-class-destructor, google-readability-function-size, hicpp-function-size, hicpp-no-assembler, readability-function-size). Document the reason for every remaining exclusion at the top of the file. Exclude in advance the checks that only exist in clang-tidy 23 and are noise here (bugprone-signed-bitwise, *-explicit-constructor, readability-trailing-comma, modernize-use-string-view), plus modernize-use-integer-sign-comparison, which needs C++20 std::cmp_less and flags deliberate casts. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Fix clang-tidy findings in documentation examples and replace redundant aliases Apply clang-tidy fixes to the documentation examples: - performance-avoid-endl: std::endl -> '\n' - readability-qualified-auto: auto -> auto* / const auto* - performance-for-range-copy: copy -> const reference - google-readability-casting: C-style cast -> static_cast Replace redundant aliases (readability-redundant-qualified-alias) such as "using json = nlohmann::json;" with "using nlohmann::json;" in the documentation, README, examples, tests, and benchmarks. Aliases at class scope and aliases of other types (with_base_class_t etc.) are kept. No changes to the library or its public API. All changed examples were compiled and run; their output matches the stored .output files (except max_size and meta, which depend on the platform and compiler). Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Format doc examples with the pinned astyle Signed-off-by: Niels Lohmann <mail@nlohmann.me> --------- Signed-off-by: Niels Lohmann <mail@nlohmann.me>
5.1 KiB
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 with, 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) which is the default for release builds. Without NDEBUG, the assertions are compiled in and contain the name of the source
file (__FILE__); see notes for builds and distribution
if that path must not end up in your binaries.
Change assertion behavior
The behavior of runtime assertions can be changed by defining macro JSON_ASSERT(x)
before including the json.hpp header.
Function with runtime assertions
Unchecked access to a const value
Function operator[] implements unchecked access for arrays and objects. Whereas
a missing element is added in the case of non-const values, accessing a const value with a missing object key or an
invalid array index is undefined behavior (think of a dereferenced null pointer) and yields a runtime assertion. This
also applies to a JSON pointer that refers to a missing key or an invalid index.
If you are not sure whether an element exists, use checked access with the at function
or call the contains function before.
See also the documentation on element access.
??? example "Example: missing object key"
The following code will trigger an assertion at runtime:
```cpp
#include <nlohmann/json.hpp>
using nlohmann::json;
int main()
{
const json j = {{"key", "value"}};
auto v = j["missing"];
}
```
Output:
```
Assertion failed: (it != m_data.m_value.object->end()), function operator[], file json.hpp, line 28795.
```
??? example "Example 2: Invalid array index in a JSON pointer"
The following code will trigger an assertion at runtime:
```cpp
#include <nlohmann/json.hpp>
using nlohmann::json;
using namespace nlohmann::literals;
int main()
{
const json j = {{"array", {1, 2, 3}}};
auto v = j["/array/5"_json_pointer];
}
```
Output:
```
Assertion failed: (idx < m_data.m_value.array->size()), function operator[], file json.hpp, line 28758.
```
Constructing from an uninitialized iterator range
Constructing a JSON value from an iterator range (see constructor) with an uninitialized iterator is undefined behavior and yields a runtime assertion.
??? example "Example: uninitialized iterator range"
The following code will trigger an assertion at runtime:
```cpp
#include <nlohmann/json.hpp>
using 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: uninitialized iterator"
The following code will trigger an assertion at runtime:
```cpp
#include <nlohmann/json.hpp>
using nlohmann::json;
int main()
{
json::iterator it;
++it;
}
```
Output:
```
Assertion failed: (m_object != nullptr), function operator++, file iter_impl.hpp, line 368.
```
Changes
Reading from a null FILE or char pointer
Reading from a null #!cpp FILE or #!cpp char pointer in C++ is undefined behavior. Until version 3.12.0, this
library asserted that the pointer was not nullptr using a runtime assertion. If assertions were disabled, this would
result in undefined behavior. Since version 3.12.0, this library checks for nullptr and throws a
parse_error.101 to prevent the undefined behavior.
??? example "Example: reading from null pointer"
The following code will trigger an assertion at runtime:
```cpp
#include <iostream>
#include <nlohmann/json.hpp>
using nlohmann::json;
int main()
{
std::FILE* f = std::fopen("nonexistent_file.json", "r");
try {
json j = json::parse(f);
} catch (std::exception& e) {
std::cerr << e.what() << std::endl;
}
}
```
Output:
```
[json.exception.parse_error.101] parse error: attempting to parse an empty input; check that your input string or stream contains the expected JSON
```
See also
- JSON_ASSERT - control behavior of runtime assertions