Nlohmann Json

https://json.nlohmann.me/api/
Admin
The nlohmann::json library provides a default specialization of the basic_json class for C++ with...
Tokens:200,401
Snippets:1,769
Trust Score:8.6
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Output of example usage

Source: https://json.nlohmann.me/api/macros/nlohmann_json_namespace_begin

Output of the example, also included via a file reference.

```json
--8<-- "examples/nlohmann_json_namespace_begin.c++17.output"
```

--------------------------------

### Example: Switch off exceptions

Source: https://json.nlohmann.me/api/macros/json_noexception

Example showing how to switch off exceptions in the library by defining JSON_NOEXCEPTION before including the header.

```cpp
#define JSON_NOEXCEPTION 1
#include <nlohmann/json.hpp>

...

```

--------------------------------

### Example: switch off the version check

Source: https://json.nlohmann.me/api/macros/json_skip_library_version_check

Example usage that defines the macro before including the library to disable the version mismatch warning.

```cpp
#define JSON_SKIP_LIBRARY_VERSION_CHECK 1
#include <nlohmann/json.hpp>

...

```

--------------------------------

### Example: Multiple conversions output

Source: https://json.nlohmann.me/api/macros/nlohmann_json_serialize_enum

Output of the multiple conversions example, included via an external file.

```json
--8<-- "examples/nlohmann_json_serialize_enum_2.output"
```

--------------------------------

### Example usage of NLOHMANN_JSON_NAMESPACE_BEGIN and NLOHMANN_JSON_NAMESPACE_END

Source: https://json.nlohmann.me/api/macros/nlohmann_json_namespace_begin

Example from the 'How do I convert third-party types?' page showing how to use the macros. The code is included via a file reference and is not displayed inline.

```cpp
--8<-- "examples/nlohmann_json_namespace_begin.c++17.cpp"
```

--------------------------------

### Example: Basic usage

Source: https://json.nlohmann.me/api/macros/nlohmann_json_serialize_enum

Example showing how to use NLOHMANN_JSON_SERIALIZE_ENUM for both classical enums and enum classes. The code is included via an external file.

```cpp
--8<-- "examples/nlohmann_json_serialize_enum.cpp"
```

--------------------------------

### Example: Multiple conversions for one enumerator

Source: https://json.nlohmann.me/api/macros/nlohmann_json_serialize_enum

Example showing multiple conversions for a single enumerator. The code is included via an external file.

```cpp
--8<-- "examples/nlohmann_json_serialize_enum_2.cpp"
```

--------------------------------

### Implicit conversion example

Source: https://json.nlohmann.me/api/macros/json_use_implicit_conversions

Example of an implicit conversion. This code compiles when JSON_USE_IMPLICIT_CONVERSIONS is not defined to 0.

```cpp
json j = "Hello, world!";
std::string s = j;
```

--------------------------------

### Example usage of NLOHMANN_JSON_NAMESPACE_NO_VERSION

Source: https://json.nlohmann.me/api/macros/nlohmann_json_namespace_no_version

Example showing how to use the macro to disable the version component of the inline namespace. The output is shown as JSON.

```cpp
--8<-- "examples/nlohmann_json_namespace_no_version.cpp"
```

```json
--8<-- "examples/nlohmann_json_namespace_no_version.output"
```

--------------------------------

### Copy Assignment Example Output

Source: https://json.nlohmann.me/api/basic_json/operator%3D

Output of the copy assignment example. Both values print as 23 after the assignment.

```text
23
23
```

--------------------------------

### Example: Force no thread_local storage

Source: https://json.nlohmann.me/api/macros/json_no_thread_local

Example code that defines JSON_NO_THREAD_LOCAL and includes the nlohmann/json header. The ellipsis indicates where user code would go.

```cpp
#define JSON_NO_THREAD_LOCAL 1
#include <nlohmann/json.hpp>

...

```

--------------------------------

### Example: default behavior - code and output

Source: https://json.nlohmann.me/api/macros/json_assert

This example triggers a runtime assertion when accessing a missing key on a const json object. The output shows the assertion failure message.

```cpp
#include <nlohmann/json.hpp>

using json = nlohmann::json;

int main()
{
    const json j = {{"key", "value"}};
    auto v = j["missing"];
}
```

```text
Assertion failed: (m_value.object->find(key) != m_value.object->end()), function operator[], file json.hpp, line 2144.
```

--------------------------------

### Example: user-defined behavior - code and output

Source: https://json.nlohmann.me/api/macros/json_assert

This example shows how to redefine JSON_ASSERT to print a custom error message and abort. The output shows the custom error message.

```cpp
#include <cstdio>
#include <cstdlib>
#define JSON_ASSERT(x) if(!(x)){fprintf(stderr, "assertion error in %s\n", __FUNCTION__); std::abort();}

#include <nlohmann/json.hpp>

using json = nlohmann::json;

int main()
{
    const json j = {{"key", "value"}};
    auto v = j["missing"];
}
```

```text
assertion error in operator[]
```

--------------------------------

### Example: warning about a different library version

Source: https://json.nlohmann.me/api/macros/json_skip_library_version_check

Shows the warning message that appears when a different version of the library is already included and the macro is not defined.

```text
Already included a different version of the library!

```

--------------------------------

### Example: implicit conversion of JSON pointers to strings

Source: https://json.nlohmann.me/api/json_pointer/operator_string_t

Shows how JSON pointers can be implicitly converted to strings. The output is shown as JSON.

```cpp
--8<-- "examples/json_pointer__operator_string_t.cpp"
```

```json
--8<-- "examples/json_pointer__operator_string_t.output"
```

--------------------------------

### Second get() overload equivalent

Source: https://json.nlohmann.me/api/basic_json/get

Equivalent implementation for the second get() overload for basic_json specializations. Simply returns the current object.

```cpp
return *this;
```

--------------------------------

### Example: opt-in precise stream position (macro defined to 1)

Source: https://json.nlohmann.me/api/macros/json_precise_stream_position

With the macro defined to 1, the stream is positioned right after the number. This example reads '1true' and the second read succeeds with j2 == true.

```cpp
#define JSON_PRECISE_STREAM_POSITION 1
#include <iostream>
#include <sstream>
#include <nlohmann/json.hpp>

using json = nlohmann::json;

int main()
{
    std::istringstream input("1true");
    json j1, j2;
    input >> j1;  // j1 == 1
    input >> j2;  // j2 == true
}
```

--------------------------------

### Empty member list example

Source: https://json.nlohmann.me/api/macros/nlohmann_define_type_non_intrusive

Example of using the macro with an empty member list. The macro generates a to_json that produces an empty JSON object and a from_json that reads no members. The WITH_NAMES variants do not support this.

```cpp
struct marker {};
NLOHMANN_DEFINE_TYPE_NON_INTROSIVE(marker)
```

--------------------------------

### Example: default behavior (macro not defined)

Source: https://json.nlohmann.me/api/macros/json_precise_stream_position

Without the macro, the character after a number is consumed. This example reads '1true' and the second read throws parse_error.101 because the stream starts at 'rue'.

```cpp
#include <iostream>
#include <sstream>
#include <nlohmann/json.hpp>

using json = nlohmann::json;

int main()
{
    std::istringstream input("1true");
    json j1, j2;
    input >> j1;  // j1 == 1
    input >> j2;  // throws parse_error.101: the stream now starts at "rue"
}
```

--------------------------------

### adl_serializer implementation example

Source: https://json.nlohmann.me/api/adl_serializer

Example implementation of adl_serializer showing how it calls to_json and from_json in the type's namespace. Note that the code uses T instead of ValueType in the function signatures, which is a simplification.

```cpp
template<typename ValueType>
struct adl_serializer {
    template<typename BasicJsonType>
    static void to_json(BasicJsonType& j, const T& value) {
        // calls the "to_json" method in T's namespace
    }

    template<typename BasicJsonType>
    static void from_json(const BasicJsonType& j, T& value) {
        // same thing, but with the "from_json" method
    }
};
```

--------------------------------

### Example: Define macro before including json.hpp

Source: https://json.nlohmann.me/api/macros/json_skip_unsupported_compiler_check

Example usage that switches off the compiler support check by defining the macro before including the library header. The ellipsis represents the rest of the user's code.

```cpp
#define JSON_SKIP_UNSUPPORTED_COMPILER_CHECK 1
#include <nlohmann/json.hpp>

...

```

--------------------------------

### Example: Default behavior using _json UDL

Source: https://json.nlohmann.me/api/macros/json_use_global_udls

Demonstrates the default behavior where the _json UDL is available in the global namespace. The program parses the string "42" into a JSON value and outputs it.

```cpp
#include <nlohmann/json.hpp>

#include <iostream>

int main()
{
    auto j = "42"_json;

    std::cout << j << std::endl;
}
```

```json
42
```

--------------------------------

### Example: Include literals explicitly with JSON_NO_AUTOMATIC_UDLS

Source: https://json.nlohmann.me/api/macros/json_no_automatic_udls

This example shows how to compile a project with -DJSON_NO_AUTOMATIC_UDLS and then explicitly include <nlohmann/json_literals.hpp> in a translation unit that uses the literals. Without the explicit include, the code would fail to compile.

```cpp
// compiled with -DJSON_NO_AUTOMATIC_UDLS for the whole project
#include <nlohmann/json.hpp>

// this file uses the literals, so it includes them explicitly
#include <nlohmann/json_literals.hpp>

int main()
{
    auto j = R"({"foo": 42})"_json;
    return j.at("/foo"_json_pointer) == 42 ? 0 : 1;
}
```

--------------------------------

### Example: Define JSON_NO_IO and include header

Source: https://json.nlohmann.me/api/macros/json_no_io

Forces the library not to use the headers <cstdio>, <ios>, <iosfwd>, <istream>, and <ostream> by defining JSON_NO_IO before including the nlohmann/json.hpp header.

```cpp
#define JSON_NO_IO 1
#include <nlohmann/json.hpp>

...
```

--------------------------------

### Example: default behavior (macro not defined)

Source: https://json.nlohmann.me/api/macros/json_brace_init_copy_semantics

Without the macro, single-element brace initialization wraps the value in an array. The comment shows the resulting value.

```cpp
#include <nlohmann/json.hpp>

using json = nlohmann::json;

int main()
{
    json obj = {{"key", "value"}};

    json j{obj};
    // j is [{"key":"value"}]  -- single-element array, NOT a copy of obj
}
```

--------------------------------

### Example: opt-in copy semantics (macro defined to 1)

Source: https://json.nlohmann.me/api/macros/json_brace_init_copy_semantics

With the macro defined to 1, single-element brace initialization copies/moves the value. The comment shows the resulting value.

```cpp
#define JSON_BRACE_INIT_COPY_SEMANTICS 1
#include <nlohmann/json.hpp>

using json = nlohmann::json;

int main()
{
    json obj = {{"key", "value"}};

    json j{obj};
    // j is {"key":"value"}  -- copy of obj
}
```

--------------------------------

### push_front

Source: https://json.nlohmann.me/api/json_pointer/push_front

Documentation for the push_front method of nlohmann::json_pointer, which appends an unescaped token at the start of the reference pointer.

```APIDOC
## push_front

### Description
Appends an unescaped token at the start of the reference pointer.

### Method
push_front

### Signature
```cpp
void push_front(const string_t& token);
void push_front(string_t&& token);
```

### Parameters
- **token** (string_t) - Required - Token to add

### Exception Safety
Basic guarantee: if an exception is thrown (for instance, if copying the reference token fails), the JSON pointer is left in a valid state, but its reference tokens may have changed.

### Complexity
Linear in the number of reference tokens in the `json_pointer`.

### Example
```cpp
// Example usage
json_pointer ptr("/foo/bar");
ptr.push_front("baz");
```

### See Also
- [front](front.md) - return first reference token
- [pop_front](pop_front.md) - remove the first reference token

### Version History
- Added in version 3.13.0.
```

--------------------------------

### to_string(basic_json)

Source: https://json.nlohmann.me/api/basic_json/to_string

Documentation for the to_string function, including its signature, template parameters, return value, exception safety, exceptions, complexity, possible implementation, examples, and version history.

```APIDOC
## to_string(basic_json)

### Description
This function implements a user-defined to_string for JSON objects. It returns a string containing the serialization of the JSON value.

### Signature
```cpp
template <typename BasicJsonType>
std::string to_string(const BasicJsonType& j);
```

### Template Parameters
- **BasicJsonType** - A specialization of `basic_json` whose `string_t` is convertible to `std::string`; for other string types, use `dump`, which returns a `string_t`.

### Return Value
String containing the serialization of the JSON value.

### Exception Safety
Strong guarantee: if an exception is thrown, there are no changes to any JSON value.

### Exceptions
Throws `type_error.316` if a string stored inside the JSON value is not UTF-8 encoded.

### Complexity
Linear.

### Possible Implementation
```cpp
template <typename BasicJsonType>
std::string to_string(const BasicJsonType& j)
{
    return j.dump();
}
```

### Examples
The following code shows how the library's `to_string()` function integrates with others, allowing argument-dependent lookup.

```cpp
--8<-- "examples/to_string.cpp"
```

Output:

```json
--8<-- "examples/to_string.output"
```

### See Also
- [dump](dump.md)
- [Serialization](../../features/serialization.md) - the serialization article

### Version History
Added in version 3.7.0.
```

--------------------------------

### get()

Source: https://json.nlohmann.me/api/basic_json/get

Documentation for the get() member function of the nlohmann::json library, which converts the JSON value to a specified type or returns a pointer to the internal value.

```APIDOC
## get()

### Description
Returns a copy of the JSON value converted to a specified type, or a pointer to the internally stored JSON value if the requested pointer type fits.

### Method
Member function of `basic_json`

### Signature
```cpp
template<typename ValueType>
ValueType get() const;

template<typename BasicJsonType>
BasicJsonType get() const;

template<typename PointerType>
PointerType get() const;
```

### Template Parameters
- **ValueType** - The value type to return.
- **BasicJsonType** - A specialization of `basic_json`.
- **PointerType** - Pointer type; must be a pointer to `array_t`, `object_t`, `string_t`, `boolean_t`, `number_integer_t`, `number_unsigned_t`, `number_float_t`, or `binary_t`. Other types will not compile.

### Return Value
1. Copy of the JSON value, converted to `ValueType`.
2. A copy of `*this`, converted into `BasicJsonType`.
3. Pointer to the internally stored JSON value if the requested pointer type fits to the JSON value; `nullptr` otherwise.

### Exception Safety
Depends on what `json_serializer<ValueType>::from_json()` throws for overloads (1) and (2); the JSON value itself is never modified, since `get()` is a `const` member function. No-throw guarantee for overload (3): this function never throws exceptions.

### Exceptions
Depends on what `json_serializer<ValueType>::from_json()` throws.

### Complexity
Depends on the `json_serializer<ValueType>::from_json()` implementation for overloads (1) and (2); constant for overload (3).

### Notes
- **Undefined behavior for pointers**: Writing data to the pointee (overload 3) of the result yields an undefined state.
- **Undefined behavior for numeric conversions**: Conversions between numeric types are performed by the corresponding `from_json()` implementation using the target C++ type. When converting between numeric types, the library does not check whether the source value is representable by the target type. If the source value is outside the range of the target type, the behavior is the same as the corresponding C++ conversion. In particular, converting a floating-point value to an integer type that cannot represent the value results in undefined behavior.
- **`std::optional` conversions**: Prior to version 3.13.0, `get<std::optional<T>>()` (and other conversions to `std::optional<T>`) failed to compile in every configuration, due to an internal implementation bug that made the `from_json` overload for `std::optional` unreachable regardless of the `JSON_USE_IMPLICIT_CONVERSIONS` setting. This has been fixed.
```

--------------------------------

### First get() overload equivalent

Source: https://json.nlohmann.me/api/basic_json/get

Equivalent implementation for the first get() overload when ValueType is copy-constructible and default-constructible. Uses json_serializer<ValueType>::from_json() with a reference parameter. Chosen when the serializer has the void from_json(const basic_json&, ValueType&) form and lacks the ValueType from_json(const basic_json&) form.

```cpp
ValueType ret;
JSONSerializer<ValueType>::from_json(*this, ret);
return ret;
```

--------------------------------

### get() - Overload for basic_json specializations

Source: https://json.nlohmann.me/api/basic_json/get

Overload for converting to other basic_json specializations. The function simply returns *this.

```APIDOC
## get() - Overload for basic_json specializations

### Description
Overload for converting to other basic_json specializations. The function simply returns *this.

### Method
Template member function

### Signature
```cpp
template<typename BasicJsonType>
BasicJsonType get() const;
```

### Parameters
- **BasicJsonType** (template parameter) - The basic_json specialization to convert to.

### Behavior
The function is equivalent to:
```cpp
return *this;
```

### Return Value
The current JSON value as the specified BasicJsonType.
```

--------------------------------

### First get() overload fallback

Source: https://json.nlohmann.me/api/basic_json/get

Equivalent implementation for the first get() overload when ValueType is not copy-constructible and not default-constructible. Uses json_serializer<ValueType>::from_json() returning the value. This overload is chosen if the serializer has the ValueType from_json(const basic_json&) form; if both overloads exist, this one is preferred.

```cpp
return JSONSerializer<ValueTypeCV>::from_json(*this);
```

--------------------------------

### Force 3-way comparison

Source: https://json.nlohmann.me/api/macros/json_has_three_way_comparison

Example showing how to manually force the library to use 3-way comparison by defining the macro before including the header.

```cpp
#define JSON_HAS_THREE_WAY_COMPARISON 1
#include <nlohmann/json.hpp>

...
```

--------------------------------

### Example: requesting pointers to internal values

Source: https://json.nlohmann.me/api/basic_json/get_ptr

Shows how to request pointers to internal values of a JSON value. No type conversions are made, and nullptr is returned if the value and the requested pointer type do not match.

```cpp
--8<-- "examples/get_ptr.cpp"
```

```json
--8<-- "examples/get_ptr.output"
```

--------------------------------

### Enable legacy discarded value comparison

Source: https://json.nlohmann.me/api/macros/json_use_legacy_discarded_value_comparison

Example that enables the legacy discarded value comparison behavior by defining the macro to 1 before including the library header.

```cpp
#define JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON 1
#include <nlohmann/json.hpp>

...
```

--------------------------------

### Example: Namespaced UDLs with JSON_USE_GLOBAL_UDLS 0

Source: https://json.nlohmann.me/api/macros/json_use_global_udls

Shows how to bring UDLs into scope when JSON_USE_GLOBAL_UDLS is defined to 0. The commented line would fail to compile because the UDLs are not in the global namespace; using namespace nlohmann::json_literals is required.

```cpp
#define JSON_USE_GLOBAL_UDLS 0
#include <nlohmann/json.hpp>

#include <iostream>

int main()
{
    // auto j = "42"_json; // This line would fail to compile,
                           // because the UDLs are not in the global namespace

    // Bring the UDLs into scope
    using namespace nlohmann::json_literals;

    auto j = "42"_json;

    std::cout << j << std::endl;
}
```

```json
42
```

--------------------------------

### Example: default behavior (macro not defined)

Source: https://json.nlohmann.me/api/macros/json_disable_tuple_reference_conversion

Shows the default behavior when the macro is not defined: std::tuple<json> t(std::forward_as_tuple(j)) results in std::get<0>(t) being [true] because the whole tuple is converted.

```cpp
#include <nlohmann/json.hpp>

using json = nlohmann::json;

int main()
{
    json j = true;

    std::tuple<json> t(std::forward_as_tuple(j));
    // std::get<0>(t) is [true] -- the whole tuple was converted
}
```

--------------------------------

### swap()

Source: https://json.nlohmann.me/api/basic_json/swap

Swaps the contents of two JSON values. The complexity is constant. Examples demonstrate swapping JSON values, arrays, objects, strings, and binary values.

```APIDOC
## swap()

### Description
Swaps the contents of two JSON values. The complexity is constant.

### Method
swap

### Signature
void swap(basic_json& other) noexcept;

### Parameters
- **other** (basic_json&) - Required - The JSON value to swap with.

### Complexity
Constant.

### Examples

#### Example: (1, 2) swap JSON values

```cpp
--8<-- "examples/swap__reference.cpp"
```

Output:

```json
--8<-- "examples/swap__reference.output"
```

#### Example: (3) swap array

```cpp
--8<-- "examples/swap__array_t.cpp"
```

Output:

```json
--8<-- "examples/swap__array_t.output"
```

#### Example: (4) swap object

```cpp
--8<-- "examples/swap__object_t.cpp"
```

Output:

```json
--8<-- "examples/swap__object_t.output"
```

#### Example: (5) swap string

```cpp
--8<-- "examples/swap__string_t.cpp"
```

Output:

```json
--8<-- "examples/swap__string_t.output"
```

#### Example: (6) swap binary

```cpp
--8<-- "examples/swap__binary_t.cpp"
```

Output:

```json
--8<-- "examples/swap__binary_t.output"
```

### See also
- [std::swap<basic_json>](std_swap.md)
- [operator=](operator=.md) copy assignment
- [basic_json](basic_json.md) create a JSON value
```

--------------------------------

### Example: conversion disabled (macro defined to 1)

Source: https://json.nlohmann.me/api/macros/json_disable_tuple_reference_conversion

Shows the behavior when the macro is defined to 1: std::tuple<json> t(std::forward_as_tuple(j)) results in std::get<0>(t) being true (a copy of j), and std::tuple<const json&> r(std::forward_as_tuple(j)) results in std::get<0>(r) referring to j.

```cpp
#define JSON_DISABLE_TUPLE_REFERENCE_CONVERSION 1
#include <nlohmann/json.hpp>

using json = nlohmann::json;

int main()
{
    json j = true;

    std::tuple<json> t(std::forward_as_tuple(j));
    // std::get<0>(t) is true -- a copy of j

    std::tuple<const json&> r(std::forward_as_tuple(j));
    // std::get<0>(r) refers to j
}
```

--------------------------------

### Example: Serialize enum macro

Source: https://json.nlohmann.me/api/macros/json_disable_enum_serialization

Forces the library not to create default serialization/deserialization functions, but uses NLOHMANN_JSON_SERIALIZE_ENUM to provide user-defined functions for parsing and serializing the enum.

```cpp
#define JSON_DISABLE_ENUM_SERIALIZATION 1
#include <nlohmann/json.hpp>

using json = nlohmann::json;

enum class Choice
{
    first,
    second,
};

NLOHMANN_JSON_SERIALIZE_ENUM(Choice,
{
    { Choice::first, "first" },
    { Choice::second, "second" },
})

int main()
{
    // uses user-defined to_json function defined by macro
    const json j = Choice::first; 

    // uses user-defined from_json function defined by macro
    Choice ch = j.get<Choice>();
}
```

--------------------------------

### Background: default stream position after number

Source: https://json.nlohmann.me/api/macros/json_precise_stream_position

Illustrates that by default, the character after a number is consumed, leaving the stream one byte too far. This example shows that after reading '1' from '1true', the stream starts at 'rue'.

```cpp
std::istringstream input("1true");
json j;
input >> j;  // j == 1, but the stream now starts at "rue"
```

--------------------------------

### Custom BinaryType configuration and usage

Source: https://json.nlohmann.me/api/basic_json/binary_t

Shows how to configure a custom BinaryType (std::vector<std::byte>) and assign values directly to a basic_json instance, which are recognized as binary values rather than arrays. Includes round-tripping with get<std::vector<std::byte>>(). Requires a custom BinaryType; the default nlohmann::json treats std::vector<std::uint8_t> as arrays.

```cpp
using custom_json = nlohmann::basic_json<
    nlohmann::ordered_map,  // ObjectType
    std::vector,            // ArrayType
    std::string,            // StringType
    bool,                   // BooleanType
    std::int64_t,           // NumberIntegerType
    std::uint64_t,          // NumberUnsignedType
    double,                 // NumberFloatType
    std::allocator,         // AllocatorType
    nlohmann::adl_serializer,
    std::vector<std::byte>  // Custom BinaryType
>;

std::vector<std::byte> data{std::byte{1}, std::byte{2}, std::byte{3}};
custom_json j = data;  // Creates a binary value, not an array
assert(j.is_binary());

// Round-tripping works seamlessly
auto extracted = j.get<std::vector<std::byte>>();
assert(extracted == data);
```

--------------------------------

### begin()

Source: https://json.nlohmann.me/api/basic_json/begin

Documentation for the begin() member function of nlohmann::basic_json, which returns an iterator to the first element.

```APIDOC
## begin()

### Description
Returns an iterator to the first element.

### Method
begin()

### Signature
- `iterator begin() noexcept;`
- `const_iterator begin() const noexcept;`

### Return Value
iterator to the first element

### Exception Safety
No-throw guarantee: this member function never throws exceptions.

### Complexity
Constant.

### Example
```cpp
--8<-- "examples/begin.cpp"
```

Output:
```json
--8<-- "examples/begin.output"
```

### See Also
- [end](end.md) returns an iterator to one past the last element
- [cbegin](cbegin.md) returns a const iterator to the first element
- [rbegin](rbegin.md) returns a reverse iterator to the last element
- [items](items.md) returns an iteration proxy to access keys and values during range-based for loops
- [Iterators](../../features/iterators.md) - the article on iterators

### Version History
- Added in version 1.0.0.
```

--------------------------------

### Empty member list with NLOHMANN_DEFINE_TYPE_INTRUSIVE

Source: https://json.nlohmann.me/api/macros/nlohmann_define_type_intrusive

Example of using the macro with an empty member list. Generates a to_json that produces an empty JSON object and a from_json that reads no members. The WITH_NAMES variants do not support this.

```cpp
struct marker
{
    NLOHMANN_DEFINE_TYPE_INTRUSIVE(marker)
};
```

--------------------------------

### Enable simdutf backend with CMake

Source: https://json.nlohmann.me/api/macros/json_use_simdutf

Shows how to enable the simdutf backend: define JSON_USE_SIMDUTF and link against simdutf::simdutf. The project must also make simdutf.h available on the include path.

```cpp
#define JSON_USE_SIMDUTF 1
#include <nlohmann/json.hpp>

...

```

```cmake
target_compile_definitions(your_target PRIVATE JSON_USE_SIMDUTF)
target_link_libraries(your_target PRIVATE simdutf::simdutf)

```

--------------------------------

### start_object

Source: https://json.nlohmann.me/api/json_sax/start_object

Documentation for the start_object SAX callback in the nlohmann JSON library.

```APIDOC
## [C++] virtual bool start_object(std::size_t elements) = 0;

### Description
The beginning of an object was read. This is a pure virtual function in the SAX interface that is called when the parser encounters the start of an object.

### Method
C++ virtual function

### Signature
`virtual bool start_object(std::size_t elements) = 0;`

### Parameters
- **elements** (std::size_t) - Required - Number of object elements, or `std::numeric_limits<std::size_t>::max()` if unknown.

### Return Value
Whether parsing should proceed.

### Notes
Binary formats may report the number of elements.

### Version History
- Added in version 3.2.0.
```

--------------------------------

### Explicit conversion with get

Source: https://json.nlohmann.me/api/macros/json_use_implicit_conversions

Explicit conversion using get when implicit conversions are disabled. This code is required when JSON_USE_IMPLICIT_CONVERSIONS is defined to 0.

```cpp
json j = "Hello, world!";
auto s = j.get<std::string>();
```

--------------------------------

### format_as(basic_json)

Source: https://json.nlohmann.me/api/basic_json/format_as

Documentation for the format_as function template, which integrates with the {fmt} library.

```APIDOC
## format_as(basic_json)

### Description
This function implements the `format_as` customization point used by the {fmt} library (fmtlib). It has no dependency on any `fmt` header and no effect at all unless a caller's translation unit also includes `fmt` and calls `fmt::format`/`fmt::print` on a JSON value.

### Method
Function template

### Signature
```cpp
template <typename BasicJsonType>
std::string format_as(const BasicJsonType& j);
```

### Parameters
- **BasicJsonType** (template parameter) - A specialization of `basic_json`.
- **j** (const BasicJsonType&) - The JSON value to format.

### Return Value
String containing the serialization of the JSON value (same as `dump()`).

### Exceptions
Throws `type_error.316` if a string stored inside the JSON value is not UTF-8 encoded.

### Exception Safety
Strong guarantee: if an exception is thrown, there are no changes to any JSON value.

### Complexity
Linear.

### Possible Implementation
```cpp
template <typename BasicJsonType>
std::string format_as(const BasicJsonType& j)
{
    return j.dump();
}
```

### Notes
- `fmt` only picks up a `format_as` overload that returns a `std::string` in fmt **10.0.0 through 11.0.2**. Starting with fmt **11.1.0**, `fmt` restricts automatic `format_as` pickup to overloads that return an arithmetic type, so this function has no effect there (it is simply unused, not a compile error).
- If you use fmt >= 11.1.0, or want the same pretty-print spec support that `std::formatter<basic_json>` has, define your own `fmt::formatter` specialization mirroring the same logic.

### Example
```cpp
--8<-- "examples/format_as.cpp"
```

Output:
```json
--8<-- "examples/format_as.output"
```

### See Also
- [dump](dump.md)
- [std::formatter<basic_json>](std_formatter.md) - the `std::format` (C++20) equivalent
- [Serialization](../../features/serialization.md) - the serialization article

### Version History
- Added in version 3.13.0.
```

--------------------------------

### front()

Source: https://json.nlohmann.me/api/json_pointer/front

Documentation for the front() method of nlohmann::json_pointer, which returns the first reference token.

```APIDOC
## front()

### Description
Returns the first reference token of the JSON pointer.

### Method
front

### Signature
const string_t& front() const;

### Return Value
First reference token.

### Exceptions
Throws out_of_range.405 if the JSON pointer has no parent.

### Exception Safety
Strong exception safety: if an exception occurs, the original value stays intact.

### Complexity
Constant.

### Example
```cpp
--8<-- "examples/json_pointer__front.cpp"
```

Output:
```json
--8<-- "examples/json_pointer__front.output"
```

### See Also
- [back](back.md) return last reference token
- [pop_front](pop_front.md) remove the first reference token
- [push_front](push_front.md) append an unescaped token at the start of the pointer

### Version History
Added in version 3.13.0.
```

--------------------------------

### Define JSON_HAS_FILESYSTEM / JSON_HAS_EXPERIMENTAL_FILESYSTEM

Source: https://json.nlohmann.me/api/macros/json_has_filesystem

Macros to override the built-in detection of filesystem support. Define either macro to 1 to force the library to use the corresponding filesystem header.

```cpp
#define JSON_HAS_FILESYSTEM /* value */
#define JSON_HAS_EXPERIMENTAL_FILESYSTEM /* value */
```

--------------------------------

### Force experimental filesystem support

Source: https://json.nlohmann.me/api/macros/json_has_filesystem

Forces the library to use the header <experimental/filesystem> by defining JSON_HAS_EXPERIMENTAL_FILESYSTEM to 1 before including the library.

```cpp
#define JSON_HAS_EXPERIMENTAL_FILESYSTEM 1
#include <nlohmann/json.hpp>

...
```

--------------------------------

### Macro definitions for NLOHMANN_JSON_NAMESPACE_BEGIN and NLOHMANN_JSON_NAMESPACE_END

Source: https://json.nlohmann.me/api/macros/nlohmann_json_namespace_begin

Shows the macro definitions for opening and closing the nlohmann namespace. The first macro opens the namespace, the second closes it.

```cpp
#define NLOHMANN_JSON_NAMESPACE_BEGIN /* value */  // (1)
#define NLOHMANN_JSON_NAMESPACE_END   /* value */  // (2)
```

--------------------------------

### Undefined behavior example: pointer invalidation after array resize

Source: https://json.nlohmann.me/api/basic_json/get_ptr

Demonstrates that a pointer obtained via get_ptr becomes invalid if the underlying JSON object changes. The example shows that after pushing a fifth element to the array, the address of the first element changes, so using the old pointer would be undefined behavior.

```cpp
#include <iostream>
#include <nlohmann/json.hpp>

using json = nlohmann::json;

int main()
{
    json j = {1, 2, 3, 4};
    auto* ptr = j[0].get_ptr<std::int64_t*>();
    std::cout << "value at " << ptr << " is " << *ptr << std::endl;

    j.push_back(5);

    ptr = j[0].get_ptr<std::int64_t*>();
    std::cout << "value at " << ptr << " is " << *ptr << std::endl;
}
```

```text
value at 0x6000012fc1c8 is 1
value at 0x6000029fc088 is 1
```

--------------------------------

### basic_json(basic_json&& other)

Source: https://json.nlohmann.me/api/basic_json/basic_json

Move constructor for basic_json.

```APIDOC
## basic_json(basic_json&& other)

### Description
Move constructor for basic_json.

### Method
Constructor

### Signature
```cpp
basic_json(basic_json&& other) noexcept;
```

### Parameters
- **other** (basic_json&&) - Required - The basic_json value to move.
```

--------------------------------

### NLOHMANN_JSON_SERIALIZE_ENUM_STRICT

Source: https://json.nlohmann.me/api/macros/nlohmann_json_serialize_enum_strict

Documentation for the NLOHMANN_JSON_SERIALIZE_ENUM_STRICT macro, including its definition, parameters, default behavior, notes, examples, and version history.

```APIDOC
## NLOHMANN_JSON_SERIALIZE_ENUM_STRICT

### Description
Defines user-defined serialization for every enumerator of an enum type, throwing an exception on undefined input.

### Macro Definition
```cpp
#define NLOHMANN_JSON_SERIALIZE_ENUM_STRICT(type, conversion...)
```

### Parameters
- **type** (in) - Required - Name of the enum to serialize/deserialize.
- **conversion** (in) - Required - A pair of an enumerator and a JSON serialization; arbitrary pairs can be given as a comma-separated list.

### Default Definition
The macro adds two functions to the namespace which take care of the serialization and deserialization:

```cpp
template<typename BasicJsonType>
inline void to_json(BasicJsonType& j, const type& e);
template<typename BasicJsonType>
inline void from_json(const BasicJsonType& j, type& e);
```

### Notes
- The macro must be used inside the namespace of the enum.
- Undefined input throws `out_of_range.410` in both directions: when serializing an enum value not listed in the conversions, and when deserializing (e.g., via `get<ENUM_TYPE>()`) a JSON value that matches no conversion; example: `"enum value out of range for <type>"`.
- If an enum or JSON value is specified in multiple conversions, the first matching conversion from the top of the list will be returned when converting to or from JSON.

### Examples

#### Example: Basic usage

```cpp
--8<-- "examples/nlohmann_json_serialize_enum_strict.cpp"
```

Output:

```json
--8<-- "examples/nlohmann_json_serialize_enum_strict.output"
```

#### Example: Multiple conversions for one enumerator

```cpp
--8<-- "examples/nlohmann_json_serialize_enum_strict_2.cpp"
```

Output:

```json
--8<-- "examples/nlohmann_json_serialize_enum_strict_2.output"
```

#### Example: exceptions on invalid serialization

```cpp
--8<-- "examples/nlohmann_json_serialize_enum_strict_err.cpp"
```

Output:

```json
--8<-- "examples/nlohmann_json_serialize_enum_strict_err.output"
```

### See also
- [Specializing enum conversion](../../features/enum_conversion.md)
- [`NLOHMANN_JSON_SERIALIZE_ENUM`](./nlohmann_json_serialize_enum.md)
- [`JSON_DISABLE_ENUM_SERIALIZATION`](json_disable_enum_serialization.md)

### Version history
Added in version 3.13.0.
```

--------------------------------

### operator ValueType

Source: https://json.nlohmann.me/api/basic_json/operator_ValueType

Implicit type conversion operator that converts the JSON value to a compatible type by calling get().

```APIDOC
## operator ValueType

### Description
Implicit type conversion between the JSON value and a compatible value. The call is realized by calling get().

### Method
operator ValueType() const

### Signature
```cpp
template<typename ValueType>
JSON_EXPLICIT operator ValueType() const;
```

### Template Parameters
- **ValueType** - the value type to return

### Return Value
Copy of the JSON value, converted to ValueType.

### Exception Safety
Depends on what json_serializer<ValueType> from_json() method throws; the JSON value itself is never modified, since operator ValueType() is a const member function that only calls get().

### Exceptions
Depends on what json_serializer<ValueType> from_json() method throws.

### Complexity
Linear in the size of the JSON value.

### Notes
- By default JSON_EXPLICIT is defined to the empty string, so the signature is: `template<typename ValueType> operator ValueType() const;`
- If JSON_USE_IMPLICIT_CONVERSIONS is set to 0, JSON_EXPLICIT is defined to `explicit`, making the conversion explicit.
- Implicit conversions will be switched off by default in the next major release of the library.

### Example
```cpp
--8<-- "examples/operator__ValueType.cpp"
```

Output:
```json
--8<-- "examples/operator__ValueType.output"
```

### See Also
- get() - get a value (explicit conversion)
- Converting values - the type conversions article

### Version History
- Since version 1.0.0.
- Macros JSON_EXPLICIT and JSON_USE_IMPLICIT_CONVERSIONS added in version 3.9.0.
```

--------------------------------

### Example: Disabled behavior

Source: https://json.nlohmann.me/api/macros/json_disable_enum_serialization

Forces the library not to create default serialization/deserialization functions. The code does not compile because the enum serialization is disabled.

```cpp
#define JSON_DISABLE_ENUM_SERIALIZATION 1
#include <nlohmann/json.hpp>

using json = nlohmann::json;

enum class Choice
{
    first,
    second,
};

int main()
{
    // normally invokes to_json serialization function but with JSON_DISABLE_ENUM_SERIALIZATION defined, it does not
    const json j = Choice::first; 

    // normally invokes from_json parse function but with JSON_DISABLE_ENUM_SERIALIZATION defined, it does not
    Choice ch = j.get<Choice>();
}
```

--------------------------------

### get() - Pointer access to internal value

Source: https://json.nlohmann.me/api/basic_json/get

Explicit pointer access to the internally stored JSON value. No copies are made.

```APIDOC
## get() - Pointer access to internal value

### Description
Explicit pointer access to the internally stored JSON value. No copies are made.

### Method
Template member function

### Signatures
```cpp
template<typename PointerType>
PointerType get() noexcept;

template<typename PointerType>
const PointerType get() const noexcept;  // constexpr since C++14
```

### Parameters
- **PointerType** (template parameter) - The pointer type to return. Typically a pointer to the internal value type.

### Return Value
A pointer to the internally stored JSON value. The const overload returns a const pointer.
```

--------------------------------

### operator[] (JSON Pointer) - const

Source: https://json.nlohmann.me/api/basic_json/operator%5B%5D

Example demonstrating read-only access to JSON elements using JSON Pointer with the const operator[].

```APIDOC
## operator[] (JSON Pointer) - const

### Description
Accesses the specified element via a JSON Pointer for read-only access. This operator is used on const JSON values.

### Method
operator[]

### Signature
`const_reference operator[](const json_pointer& ptr) const`

### Parameters
- **ptr** (json_pointer) - Required - A JSON Pointer that specifies the element to access.

### Behavior
- Provides read-only access to the element at the given pointer.
- Does not modify the JSON value.

### Example
```cpp
#include <iostream>
#include <nlohmann/json.hpp>

using json = nlohmann::json;
using namespace nlohmann::literals;

int main()
{
    const json j = {{"number", 1}, {"string", "foo"}, {"array", {1, 2}}};

    std::cout << j["/number"_json_pointer] << '\n';
    std::cout << j["/string"_json_pointer] << '\n';
    std::cout << j["/array"_json_pointer] << '\n';
    std::cout << j["/array/1"_json_pointer] << '\n';
}
```

### Output
```
1
"foo"
[1,2]
2
```
```

--------------------------------

### Undefine JSON_SKIP_LIBRARY_VERSION_CHECK (default)

Source: https://json.nlohmann.me/api/macros/json_skip_library_version_check

Shows the default state of the macro, which is not defined. This is the default behavior.

```cpp
#undef JSON_SKIP_LIBRARY_VERSION_CHECK

```

--------------------------------

### Possible implementation of empty()

Source: https://json.nlohmann.me/api/basic_json/empty

Possible implementation of empty() that returns true if size() is 0. This is provided as an example of how the function could be implemented.

```cpp
bool empty() const noexcept
{
    return size() == 0;
}
```

--------------------------------

### push_back(initializer_list_t init)

Source: https://json.nlohmann.me/api/basic_json/push_back

Allows using push_back with an initializer list. If the current value is an object, the initializer list contains only two elements, and the first element is a string, it is converted into an object element; otherwise, it is converted to a JSON value and appended.

```APIDOC
## push_back(initializer_list_t init)

### Description
This function allows using `push_back` with an initializer list. In case (1) the current value is an object, (2) the initializer list `init` contains only two elements, and (3) the first element of `init` is a string, `init` is converted into an object element and added using `push_back(const typename object_t::value_type&)`. Otherwise, `init` is converted to a JSON value and added using `push_back(basic_json&&)`.

### Method
push_back (member function)

### Endpoint
basic_json::push_back(initializer_list_t init)

### Parameters
- **init** (initializer_list_t) - in - An initializer list.

### Exceptions
- Throws `type_error.308` when called on a type other than JSON array or null; example: `"cannot use push_back() with number"`.

### Complexity
Linear in the size of the initializer list `init`.

### Iterator Invalidation
For arrays, a reallocation can happen, in which case all iterators (including the `end()` iterator) and all references to the elements are invalidated. Otherwise, only the `end()` iterator is invalidated.

### Example
```cpp
// Example usage
basic_json j;
j.push_back({"key", "value"});
```
```

--------------------------------

### operator[] (JSON Pointer) - non-const

Source: https://json.nlohmann.me/api/basic_json/operator%5B%5D

Example demonstrating read and write access to JSON elements using JSON Pointer with the non-const operator[].

```APIDOC
## operator[] (JSON Pointer) - non-const

### Description
Accesses the specified element via a JSON Pointer and allows both reading and writing. This operator is used on non-const JSON values.

### Method
operator[]

### Signature
`reference operator[](const json_pointer& ptr)`

### Parameters
- **ptr** (json_pointer) - Required - A JSON Pointer that specifies the element to access.

### Behavior
- For read access, returns a reference to the element at the given pointer.
- For write access, assigns a new value to the element at the given pointer.
- If the pointer refers to a nonexisting object entry, a new entry is created.
- If the pointer refers to an array index beyond the current size, the array is extended with null values.
- If the pointer uses the '-' token, the value is appended to the array.

### Example
```cpp
#include <iostream>
#include <nlohmann/json.hpp>

using json = nlohmann::json;
using namespace nlohmann::literals;

int main()
{
    json j = {{"number", 1}, {"string", "foo"}, {"array", {1, 2}}};

    // read access
    std::cout << j["/number"_json_pointer] << '\n';
    std::cout << j["/string"_json_pointer] << '\n';
    std::cout << j["/array"_json_pointer] << '\n';
    std::cout << j["/array/1"_json_pointer] << '\n';

    // write access
    j["/string"_json_pointer] = "bar";
    j["/boolean"_json_pointer] = true;
    j["/array/1"_json_pointer] = 21;
    j["/array/4"_json_pointer] = 44;
    j["/array/-"_json_pointer] = 55;

    std::cout << j << '\n';
}
```

### Output
```
1
"foo"
[1,2]
2
{"array":[1,21,null,null,44],"boolean":true,"number":1,"string":"bar"}
[1,21,null,null,44]
[1,21,null,null,44,55]
```
```
Tokens:
Raw