1# Runtime Assertions 2 3The code contains numerous debug assertions to ensure class invariants are valid or to detect undefined behavior. 4Whereas the former class invariants are nothing to be concerned of, the latter checks for undefined behavior are to 5detect bugs in client code. 6 7## Switch off runtime assertions 8 9Runtime assertions can be switched off by defining the preprocessor macro `NDEBUG` (see the 10[documentation of assert](https://en.cppreference.com/w/cpp/error/assert)) which is the default for release builds. 11 12## Change assertion behavior 13 14The behavior of runtime assertions can be changes by defining macro [`JSON_ASSERT(x)`](../api/macros/json_assert.md) 15before including the `json.hpp` header. 16 17## Function with runtime assertions 18 19### Unchecked object access to a const value 20 21Function [`operator[]`](../api/basic_json/operator%5B%5D.md) implements unchecked access for objects. Whereas a missing 22key is added in case of non-const objects, accessing a const object with a missing key is undefined behavior (think of a 23dereferenced null pointer) and yields a runtime assertion. 24 25If you are not sure whether an element in an object exists, use checked access with the 26[`at` function](../api/basic_json/at.md) or call the [`contains` function](../api/basic_json/contains.md) before. 27 28See also the documentation on [element access](element_access/index.md). 29 30??? example "Example 1: Missing object key" 31 32 The following code will trigger an assertion at runtime: 33 34 ```cpp 35 #include <nlohmann/json.hpp> 36 37 using json = nlohmann::json; 38 39 int main() 40 { 41 const json j = {{"key", "value"}}; 42 auto v = j["missing"]; 43 } 44 ``` 45 46 Output: 47 48 ``` 49 Assertion failed: (m_value.object->find(key) != m_value.object->end()), function operator[], file json.hpp, line 2144. 50 ``` 51 52### Constructing from an uninitialized iterator range 53 54Constructing a JSON value from an iterator range (see [constructor](../api/basic_json/basic_json.md)) with an 55uninitialized iterator is undefined behavior and yields a runtime assertion. 56 57??? example "Example 2: Uninitialized iterator range" 58 59 The following code will trigger an assertion at runtime: 60 61 ```cpp 62 #include <nlohmann/json.hpp> 63 64 using json = nlohmann::json; 65 66 int main() 67 { 68 json::iterator it1, it2; 69 json j(it1, it2); 70 } 71 ``` 72 73 Output: 74 75 ``` 76 Assertion failed: (m_object != nullptr), function operator++, file iter_impl.hpp, line 368. 77 ``` 78 79### Operations on uninitialized iterators 80 81Any operation on uninitialized iterators (i.e., iterators that are not associated with any JSON value) is undefined 82behavior and yields a runtime assertion. 83 84??? example "Example 3: Uninitialized iterator" 85 86 The following code will trigger an assertion at runtime: 87 88 ```cpp 89 #include <nlohmann/json.hpp> 90 91 using json = nlohmann::json; 92 93 int main() 94 { 95 json::iterator it; 96 ++it; 97 } 98 ``` 99 100 Output: 101 102 ``` 103 Assertion failed: (m_object != nullptr), function operator++, file iter_impl.hpp, line 368. 104 ``` 105 106### Reading from a null `FILE` pointer 107 108Reading from a null `#!cpp FILE` pointer is undefined behavior and yields a runtime assertion. This can happen when 109calling `#!cpp std::fopen` on a nonexistent file. 110 111??? example "Example 4: Uninitialized iterator" 112 113 The following code will trigger an assertion at runtime: 114 115 ```cpp 116 #include <nlohmann/json.hpp> 117 118 using json = nlohmann::json; 119 120 int main() 121 { 122 std::FILE* f = std::fopen("nonexistent_file.json", "r"); 123 json j = json::parse(f); 124 } 125 ``` 126 127 Output: 128 129 ``` 130 Assertion failed: (m_file != nullptr), function file_input_adapter, file input_adapters.hpp, line 55. 131 ``` 132