mirror of https://github.com/nlohmann/json.git synced 2026-08-29 20:47:14 +00:00

Files

T

Niels Lohmann 0e4ad2e8da docs: record the reduced string_t and array_t requirements

Drop c_str(), back(), find(str, pos), replace(), and substr() from the
StringType requirements and at(size_type) from the ArrayType ones, and
note the string assignment the JSON pointer code performs. Streaming a
json_pointer no longer needs assignability from a std::string.

Add the non-null-terminated data() to the list of violations that are not
diagnosed at compile time -- it was described in the StringType section
but missing from the summary at the top -- and correct the QString row,
which no longer fails for the c_str() it lacks.

JSON_CATCH_USER no longer wraps a catch of std::out_of_range: the last one
went away with array_t::at(). Describe what the library actually catches.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

2026-08-28 17:38:58 +00:00

2.8 KiB

Raw Blame History

JSON_CATCH_USER, JSON_THROW_USER, JSON_TRY_USER

// (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.

This macro overrides #!cpp catch calls inside the library. The argument is the type of the exception to catch. The library uses it in a single place: to swallow any exception escaping the parent-pointer check that JSON_DIAGNOSTICS adds to the class invariant. The places where the library catches its own json::out_of_range exceptions use JSON_INTERNAL_CATCH instead, which JSON_CATCH_USER also overrides unless JSON_INTERNAL_CATCH_USER is defined. The macro is always followed by a scope.
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 try calls inside the library. It has no arguments and is always followed by a scope.

Parameters

exception (in): an exception type

Default definition

By default, the macros map to their respective C++ keywords:

#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 to make reaching the #!cpp throw branch abort the process.

#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 <iostream>

#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 <nlohmann/json.hpp>
```

Version history

Added in version 3.1.0.

2.8 KiB Raw Blame History