Compare commits
36
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 nlohmann
|
264aee6773 | ||
|
nlohmann
|
cf84df303b | ||
|
nlohmann
|
40c9f42917 | ||
|
nlohmann
|
11a863958e | ||
|
nlohmann
|
b36f8a9821 | ||
|
nlohmann
|
d2e264bd84 | ||
|
nlohmann
|
41c601a7d1 | ||
|
nlohmann
|
39c2507b2a | ||
|
nlohmann
|
7130ea885a | ||
|
nlohmann
|
d9c2ec4722 | ||
|
nlohmann
|
b3d9aca8da | ||
|
nlohmann
|
73e6e76732 | ||
|
nlohmann
|
3849327381 | ||
|
nlohmann
|
90f0c9d411 | ||
|
nlohmann
|
be4d0a6f4b | ||
|
nlohmann
|
53e1ee907f | ||
|
nlohmann
|
98c9bea1d1 | ||
|
nlohmann
|
dcc7a74a18 | ||
|
nlohmann
|
e12071023d | ||
|
nlohmann
|
22fba27145 | ||
|
nlohmann
|
79119509a9 | ||
|
nlohmann
|
6d3900e253 | ||
|
nlohmann
|
60e9652b7f | ||
|
nlohmann
|
1eb9589abb | ||
|
nlohmann
|
ad947e10d0 | ||
|
nlohmann
|
56189bffb2 | ||
|
nlohmann
|
207a4df1e4 | ||
|
nlohmann
|
4e5f6962d3 | ||
|
nlohmann
|
f991906bcd | ||
|
nlohmann
|
6cba066a3f | ||
|
nlohmann
|
42b1d75fff | ||
|
nlohmann
|
149f7353a9 | ||
|
nlohmann
|
3d5002612b | ||
|
nlohmann
|
148be4b157 | ||
|
nlohmann
|
41e21ac50a | ||
|
nlohmann
|
f99a460b9b |
No files matched your search
@@ -1,64 +1,19 @@
|
||||
---
|
||||
template: home.html
|
||||
hide:
|
||||
- toc
|
||||
---
|
||||
|
||||
# JSON for Modern C++
|
||||
|
||||
|
||||
|
||||
JSON for Modern C++ is a header-only C++11 library that turns JSON into a first-class C++ data type, using the operator
|
||||
magic of modern C++ so that creating, reading, and modifying JSON values feels as natural as it does in languages like
|
||||
Python. The whole library is available as a single header, `json.hpp`, with no dependencies, no subproject, and no
|
||||
complex build system to set up; a companion header, `json_fwd.hpp`, provides forward declarations to keep compile times
|
||||
down. See [header-only integration](integration/index.md) for details. It is heavily unit-tested with 100% code
|
||||
coverage, checked with Valgrind and the Clang Sanitizers for memory leaks, and continuously fuzz-tested by Google
|
||||
OSS-Fuzz.
|
||||
|
||||
## Quick start
|
||||
|
||||
Add the single header to your project and use the library like this:
|
||||
|
||||
```cpp
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// parse a JSON string
|
||||
json j = json::parse(R"({"happy": true, "pi": 3.141})");
|
||||
|
||||
// access and modify values
|
||||
j["name"] = "Niels";
|
||||
j["list"] = {1, 0, 2};
|
||||
|
||||
// serialize with an indent of 4 spaces
|
||||
std::cout << j.dump(4) << '\n';
|
||||
}
|
||||
```
|
||||
|
||||
Get the library by copying the single header [`json.hpp`](https://github.com/nlohmann/json/releases) from the
|
||||
releases page into a directory `nlohmann` on your include path, or by installing it with a package manager:
|
||||
|
||||
```sh
|
||||
brew install nlohmann-json # Homebrew
|
||||
vcpkg install nlohmann-json # vcpkg
|
||||
```
|
||||
|
||||
```cmake
|
||||
find_package(nlohmann_json 3.12.0 REQUIRED)
|
||||
target_link_libraries(myproject PRIVATE nlohmann_json::nlohmann_json)
|
||||
```
|
||||
|
||||
See [Integration](integration/index.md) for CMake in detail, all supported package managers (Conan, Meson, Bazel,
|
||||
Conda, and more), and pkg-config.
|
||||
|
||||
## Explore the documentation
|
||||
|
||||
<div class="grid cards" markdown>
|
||||
|
||||
- :octicons-rocket-24:{ .lg .middle } __Features__
|
||||
|
||||
---
|
||||
|
||||
Creating, parsing, accessing, and serializing JSON values, JSON Pointer/Patch, binary formats, and more.
|
||||
Creating, parsing, accessing, and serializing JSON values, converting your own C++ types, JSON Pointer/Patch/Merge
|
||||
Patch, binary formats, zero-copy views, and more.
|
||||
|
||||
[:octicons-arrow-right-24: Features](features/index.md)
|
||||
|
||||
@@ -74,7 +29,8 @@ Conda, and more), and pkg-config.
|
||||
|
||||
---
|
||||
|
||||
The complete reference for `basic_json` and its member functions, types, and related classes.
|
||||
The complete reference for `basic_json` and its member functions, types, and related classes, as well as for
|
||||
`json_document` and `json_view`.
|
||||
|
||||
[:octicons-arrow-right-24: API documentation](api/basic_json/index.md)
|
||||
|
||||
@@ -92,7 +48,7 @@ Conda, and more), and pkg-config.
|
||||
|
||||
What changed in each release, with links to the relevant documentation.
|
||||
|
||||
[:octicons-arrow-right-24: Releases](home/releases.md)
|
||||
[:octicons-arrow-right-24: Releases](home/releases/index.md)
|
||||
|
||||
- :octicons-people-24:{ .lg .middle } __Community__
|
||||
|
||||
@@ -104,11 +60,5 @@ Conda, and more), and pkg-config.
|
||||
|
||||
</div>
|
||||
|
||||
!!! info "Unreleased changes"
|
||||
|
||||
This documentation is built from the `develop` branch and may describe changes that are not part of a release
|
||||
yet. Their version numbers are followed by an <span class="unreleased-version">unreleased</span> badge; see
|
||||
[Releases](home/releases.md) for what shipped in each version.
|
||||
|
||||
The library is licensed under the [MIT License](home/license.md). The source code, issue tracker, and discussions
|
||||
are on [GitHub](https://github.com/nlohmann/json).
|
||||
|
||||
|
||||
@@ -1 +1 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link rel=icon href=/assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>JSON for Modern C++</title><link rel=stylesheet href=/assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=/assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="/assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=/css/custom.css><script>__md_scope=new URL("/",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=/. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> <div class=md-search data-md-component=search role=dialog> <label class=md-search__overlay for=__search></label> <div class=md-search__inner role=search> <form class=md-search__form name=search> <input type=text class=md-search__input name=query aria-label=Search placeholder=SeaLine truncated
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link rel=icon href=/assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>JSON for Modern C++</title><link rel=stylesheet href=/assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=/assets/stylesheets/palette.ab4e12ef.min.css><link rel=stylesheet href=/css/custom.css><link rel=stylesheet href=/css/brand.css><link rel=stylesheet href=/css/fig-sax.css><link rel=stylesheet href=/css/fig-jsonview.css><link rel=stylesheet href=/css/fig-exceptions.css><link rel=stylesheet href=/css/fig-pointer.css><link rel=stylesheet href=/css/fig-charts.css><link rel=stylesheet href=/css/fig-integration.css><link rel=stylesheet href=/css/fig-macros.css><script>__md_scope=new URL("/",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=/. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=/images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> <div class=md-search data-md-component=search role=dialog> <label class=md-search__overlay for=__search></label> <div class=md-search__innerLine truncated
|
||||
@@ -30,6 +30,14 @@ struct adl_serializer {
|
||||
- [**from_json**](from_json.md) - convert a JSON value to any value type
|
||||
- [**to_json**](to_json.md) - convert any value type to a JSON value
|
||||
|
||||
## See also
|
||||
|
||||
- [Arbitrary type conversions](../../features/arbitrary_types.md) - how to make your types convertible
|
||||
- [`get`](../basic_json/get.md) - / [`get_to`](../basic_json/get_to.md) - convert a JSON value to a C++ type
|
||||
- [`basic_json`](../basic_json/basic_json.md) - construct a JSON value from a C++ value
|
||||
- [`NLOHMANN_DEFINE_TYPE_INTRUSIVE`](../macros/nlohmann_define_type_intrusive.md) - generate the conversion functions for a type
|
||||
- [Specializing enum conversion](../../features/enum_conversion.md) - serializing enums as JSON strings
|
||||
|
||||
## Version history
|
||||
|
||||
- Added in version 2.1.0.
|
||||
@@ -30,7 +30,7 @@ class (either explicitly or via the conversion operators).
|
||||
|
||||
## Return value
|
||||
|
||||
1. (none) -- the converted value is written to the output parameter `val`.
|
||||
1. (none) — the converted value is written to the output parameter `val`.
|
||||
2. the JSON value `j` converted to `TargetType`
|
||||
|
||||
## Examples
|
||||
@@ -41,13 +41,51 @@ class (either explicitly or via the conversion operators).
|
||||
called by the `adl_serializer` when `get<ns::person>()` is called.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/from_json__default_constructible.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
namespace ns
|
||||
{
|
||||
// a simple struct to model a person
|
||||
struct person
|
||||
{
|
||||
std::string name;
|
||||
std::string address;
|
||||
int age;
|
||||
};
|
||||
} // namespace ns
|
||||
|
||||
namespace ns
|
||||
{
|
||||
void from_json(const json& j, person& p)
|
||||
{
|
||||
j.at("name").get_to(p.name);
|
||||
j.at("address").get_to(p.address);
|
||||
j.at("age").get_to(p.age);
|
||||
}
|
||||
} // namespace ns
|
||||
|
||||
int main()
|
||||
{
|
||||
json j;
|
||||
j["name"] = "Ned Flanders";
|
||||
j["address"] = "744 Evergreen Terrace";
|
||||
j["age"] = 60;
|
||||
|
||||
auto p = j.get<ns::person>();
|
||||
|
||||
std::cout << p.name << " (" << p.age << ") lives in " << p.address << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/from_json__default_constructible.output"
|
||||
Ned Flanders (60) lives in 744 Evergreen Terrace
|
||||
|
||||
```
|
||||
|
||||
??? example "Example: (2) Non-default-constructible type"
|
||||
@@ -56,18 +94,74 @@ class (either explicitly or via the conversion operators).
|
||||
realize the conversion of a non-default-constructible type.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/from_json__non_default_constructible.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
namespace ns
|
||||
{
|
||||
// a simple struct to model a person (not default constructible)
|
||||
struct person
|
||||
{
|
||||
person(std::string n, std::string a, int aa)
|
||||
: name(std::move(n)), address(std::move(a)), age(aa)
|
||||
{}
|
||||
|
||||
std::string name;
|
||||
std::string address;
|
||||
int age;
|
||||
};
|
||||
} // namespace ns
|
||||
|
||||
namespace nlohmann
|
||||
{
|
||||
template <>
|
||||
struct adl_serializer<ns::person>
|
||||
{
|
||||
static ns::person from_json(const json& j)
|
||||
{
|
||||
return {j.at("name"), j.at("address"), j.at("age")};
|
||||
}
|
||||
|
||||
// Here's the catch! You must provide a to_json method! Otherwise, you
|
||||
// will not be able to convert person to json, since you fully
|
||||
// specialized adl_serializer on that type
|
||||
static void to_json(json& j, ns::person p)
|
||||
{
|
||||
j["name"] = p.name;
|
||||
j["address"] = p.address;
|
||||
j["age"] = p.age;
|
||||
}
|
||||
};
|
||||
} // namespace nlohmann
|
||||
|
||||
int main()
|
||||
{
|
||||
json j;
|
||||
j["name"] = "Ned Flanders";
|
||||
j["address"] = "744 Evergreen Terrace";
|
||||
j["age"] = 60;
|
||||
|
||||
auto p = j.get<ns::person>();
|
||||
|
||||
std::cout << p.name << " (" << p.age << ") lives in " << p.address << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/from_json__non_default_constructible.output"
|
||||
Ned Flanders (60) lives in 744 Evergreen Terrace
|
||||
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [to_json](to_json.md)
|
||||
- [`to_json`](to_json.md) - convert a C++ value to JSON
|
||||
- [Arbitrary Type Conversions](../../features/arbitrary_types.md) - write your own `from_json` and `to_json` functions
|
||||
- [Converting values](../../features/conversions.md) - overview of `get`, `get_to` and implicit conversions
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/adl_serializer/from_json/" rel="canonical"><link href=../ rel=prev><link href=../to_json/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>from_json - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../../css/custom.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannadl_serializerfrom_json class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> from_json </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></sLine truncated
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/adl_serializer/from_json/" rel="canonical"><link href=../ rel=prev><link href=../to_json/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>from_json - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel=stylesheet href=../../../css/custom.css><link rel=stylesheet href=../../../css/brand.css><link rel=stylesheet href=../../../css/fig-sax.css><link rel=stylesheet href=../../../css/fig-jsonview.css><link rel=stylesheet href=../../../css/fig-exceptions.css><link rel=stylesheet href=../../../css/fig-pointer.css><link rel=stylesheet href=../../../css/fig-charts.css><link rel=stylesheet href=../../../css/fig-integration.css><link rel=stylesheet href=../../../css/fig-macros.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannadl_serializerfrom_json class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> from_json </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5Line truncated
|
||||
<span class=k>template</span><span class=o><</span><span class=k>typename</span><span class=w> </span><span class=nc>BasicJsonType</span><span class=p>,</span><span class=w> </span><span class=k>typename</span><span class=w> </span><span class=nc>TargetType</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>ValueType</span><span class=o>></span>
|
||||
<span class=k>static</span><span class=w> </span><span class=k>auto</span><span class=w> </span><span class=n>from_json</span><span class=p>(</span><span class=n>BasicJsonType</span><span class=w> </span><span class=o>&&</span><span class=w> </span><span class=n>j</span><span class=p>,</span><span class=w> </span><span class=n>TargetType</span><span class=o>&</span><span class=w> </span><span class=n>val</span><span class=p>)</span><span class=w> </span><span class=k>noexcept</span><span class=p>(</span>
|
||||
<span class=w> </span><span class=k>noexcept</span><span class=p>(</span><span class=o>::</span><span class=n>nlohmann</span><span class=o>::</span><span class=n>from_json</span><span class=p>(</span><span class=n>std</span><span class=o>::</span><span class=n>forward</span><span class=o><</span><span class=n>BasicJsonType</span><span class=o>></span><span class=p>(</span><span class=n>j</span><span class=p>),</span><span class=w> </span><span class=n>val</span><span class=p>)))</span>
|
||||
@@ -9,10 +9,10 @@
|
||||
<span class=k>static</span><span class=w> </span><span class=k>auto</span><span class=w> </span><span class=n>from_json</span><span class=p>(</span><span class=n>BasicJsonType</span><span class=w> </span><span class=o>&&</span><span class=w> </span><span class=n>j</span><span class=p>)</span><span class=w> </span><span class=k>noexcept</span><span class=p>(</span>
|
||||
<span class=k>noexcept</span><span class=p>(</span><span class=o>::</span><span class=n>nlohmann</span><span class=o>::</span><span class=n>from_json</span><span class=p>(</span><span class=n>std</span><span class=o>::</span><span class=n>forward</span><span class=o><</span><span class=n>BasicJsonType</span><span class=o>></span><span class=p>(</span><span class=n>j</span><span class=p>),</span><span class=w> </span><span class=n>detail</span><span class=o>::</span><span class=n>identity_tag</span><span class=o><</span><span class=n>TargetType</span><span class=o>></span><span class=w> </span><span class=p>{})))</span>
|
||||
<span class=o>-></span><span class=w> </span><span class=k>decltype</span><span class=p>(</span><span class=o>::</span><span class=n>nlohmann</span><span class=o>::</span><span class=n>from_json</span><span class=p>(</span><span class=n>std</span><span class=o>::</span><span class=n>forward</span><span class=o><</span><span class=n>BasicJsonType</span><span class=o>></span><span class=p>(</span><span class=n>j</span><span class=p>),</span><span class=w> </span><span class=n>detail</span><span class=o>::</span><span class=n>identity_tag</span><span class=o><</span><span class=n>TargetType</span><span class=o>></span><span class=w> </span><span class=p>{}))</span>
|
||||
</code></pre></div> <p>This function is usually called by the <a href=../../basic_json/get/ ><code>get()</code></a> function of the <a href=../../basic_json/ >basic_json</a> class (either explicitly or via the conversion operators).</p> <ol> <li>This function is chosen for default-constructible value types.</li> <li>This function is chosen for value types which are not default-constructible.</li> </ol> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">¶</a></h2> <dl> <dt><code>j</code> (in)</dt> <dd><abbr title="JavaScript Object Notation">JSON</abbr> value to read from</dd> <dt><code>val</code> (out)</dt> <dd>value to write to</dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">¶</a></h2> <ol> <li>(none) -- the converted value is written to the output parameter <code>val</code>.</li> <li>the <abbr title="JavaScript Object Notation">JSON</abbr> value <code>j</code> converted to <code>TargetType</code></li> </ol> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example: (1) Default-constructible type</summary> <p>The example below shows how a <code>from_json</code> function can be implemented for a user-defined type. This function is called by the <code>adl_serializer</code> when <code>get<ns::person>()</code> is called.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
</code></pre></div> <p>This function is usually called by the <a href=../../basic_json/get/ ><code>get()</code></a> function of the <a href=../../basic_json/ >basic_json</a> class (either explicitly or via the conversion operators).</p> <ol> <li>This function is chosen for default-constructible value types.</li> <li>This function is chosen for value types which are not default-constructible.</li> </ol> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">¶</a></h2> <dl> <dt><code>j</code> (in)</dt> <dd><abbr title="JavaScript Object Notation">JSON</abbr> value to read from</dd> <dt><code>val</code> (out)</dt> <dd>value to write to</dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">¶</a></h2> <ol> <li>(none) — the converted value is written to the output parameter <code>val</code>.</li> <li>the <abbr title="JavaScript Object Notation">JSON</abbr> value <code>j</code> converted to <code>TargetType</code></li> </ol> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example: (1) Default-constructible type</summary> <p>The example below shows how a <code>from_json</code> function can be implemented for a user-defined type. This function is called by the <code>adl_serializer</code> when <code>get<ns::person>()</code> is called.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=k>namespace</span><span class=w> </span><span class=nn>ns</span>
|
||||
<span class=p>{</span>
|
||||
@@ -44,13 +44,13 @@
|
||||
|
||||
<span class=w> </span><span class=k>auto</span><span class=w> </span><span class=n>p</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>j</span><span class=p>.</span><span class=n>get</span><span class=o><</span><span class=n>ns</span><span class=o>::</span><span class=n>person</span><span class=o>></span><span class=p>();</span>
|
||||
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>p</span><span class=p>.</span><span class=n>name</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=s>" ("</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>p</span><span class=p>.</span><span class=n>age</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=s>") lives in "</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>p</span><span class=p>.</span><span class=n>address</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>endl</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>p</span><span class=p>.</span><span class=n>name</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=s>" ("</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>p</span><span class=p>.</span><span class=n>age</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=s>") lives in "</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>p</span><span class=p>.</span><span class=n>address</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code><span class=err>Ned</span><span class=w> </span><span class=err>Fla</span><span class=kc>n</span><span class=err>ders</span><span class=w> </span><span class=err>(</span><span class=mi>60</span><span class=err>)</span><span class=w> </span><span class=err>lives</span><span class=w> </span><span class=err>i</span><span class=kc>n</span><span class=w> </span><span class=mi>744</span><span class=w> </span><span class=err>Evergree</span><span class=kc>n</span><span class=w> </span><span class=err>Terrace</span>
|
||||
</code></pre></div> </details> <details class=example> <summary>Example: (2) Non-default-constructible type</summary> <p>The example below shows how a <code>from_json</code> is implemented as part of a specialization of the <code>adl_serializer</code> to realize the conversion of a non-default-constructible type.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=k>namespace</span><span class=w> </span><span class=nn>ns</span>
|
||||
<span class=p>{</span>
|
||||
@@ -98,7 +98,7 @@
|
||||
|
||||
<span class=w> </span><span class=k>auto</span><span class=w> </span><span class=n>p</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>j</span><span class=p>.</span><span class=n>get</span><span class=o><</span><span class=n>ns</span><span class=o>::</span><span class=n>person</span><span class=o>></span><span class=p>();</span>
|
||||
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>p</span><span class=p>.</span><span class=n>name</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=s>" ("</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>p</span><span class=p>.</span><span class=n>age</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=s>") lives in "</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>p</span><span class=p>.</span><span class=n>address</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>endl</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>p</span><span class=p>.</span><span class=n>name</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=s>" ("</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>p</span><span class=p>.</span><span class=n>age</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=s>") lives in "</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>p</span><span class=p>.</span><span class=n>address</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code><span class=err>Ned</span><span class=w> </span><span class=err>Fla</span><span class=kc>n</span><span class=err>ders</span><span class=w> </span><span class=err>(</span><span class=mi>60</span><span class=err>)</span><span class=w> </span><span class=err>lives</span><span class=w> </span><span class=err>i</span><span class=kc>n</span><span class=w> </span><span class=mi>744</span><span class=w> </span><span class=err>Evergree</span><span class=kc>n</span><span class=w> </span><span class=err>Terrace</span>
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../to_json/ >to_json</a></li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 2.1.0.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="June 29, 2026 20:15:18 UTC">June 29, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4C0 465.5 14.3 480 31.9 480H416c17.6 0 32-14.5 32-32.3V64.3c0-17.8-14.4-32.3-32-32.3M135.4 416H69V202.2h66.5V416zM102.2 96a38.5 38.5 0 1 1 0 77 38.5 38.5 0 1 1 0-77m282.1 320h-66.4V312c0-24.8-.5-56.7-34.5-56.7-34.6 0-39.9 27-39.9 54.9V416h-66.4V202.2h63.7v29.2h.9c8.9-16.8 30.6-34.5 62.9-34.5 67.2 0 79.7 44.3 79.7 101.9z"/></svg> </a> <a href="https://www.xing.com/profile/Niels_Lohmann" target="_blank" rel="noopener" title="www.xing.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 384 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--Line truncated
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../to_json/ ><code>to_json</code></a> - convert a C++ value to <abbr title="JavaScript Object Notation">JSON</abbr></li> <li><a href=../../../features/arbitrary_types/ >Arbitrary Type Conversions</a> - write your own <code>from_json</code> and <code>to_json</code> functions</li> <li><a href=../../../features/conversions/ >Converting values</a> - overview of <code>get</code>, <code>get_to</code> and implicit conversions</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 2.1.0.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../ class="md-footer__link md-footer__link--prev" aria-label="Previous: Overview"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> Overview </div> </div> </a> <a href=../to_json/ class="md-footer__link md-footer__link--next" aria-label="Next: to_json"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> to_json </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-1Line truncated
|
||||
@@ -27,7 +27,7 @@ This function is usually called by the [`get()`](https://json.nlohmann.me/api/ba
|
||||
|
||||
## Return value
|
||||
|
||||
1. (none) -- the converted value is written to the output parameter `val`.
|
||||
1. (none) — the converted value is written to the output parameter `val`.
|
||||
1. the JSON value `j` converted to `TargetType`
|
||||
|
||||
## Examples
|
||||
@@ -40,7 +40,7 @@ The example below shows how a `from_json` function can be implemented for a user
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
namespace ns
|
||||
{
|
||||
@@ -72,7 +72,7 @@ int main()
|
||||
|
||||
auto p = j.get<ns::person>();
|
||||
|
||||
std::cout << p.name << " (" << p.age << ") lives in " << p.address << std::endl;
|
||||
std::cout << p.name << " (" << p.age << ") lives in " << p.address << '\n';
|
||||
}
|
||||
```
|
||||
|
||||
@@ -90,7 +90,7 @@ The example below shows how a `from_json` is implemented as part of a specializa
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
namespace ns
|
||||
{
|
||||
@@ -138,7 +138,7 @@ int main()
|
||||
|
||||
auto p = j.get<ns::person>();
|
||||
|
||||
std::cout << p.name << " (" << p.age << ") lives in " << p.address << std::endl;
|
||||
std::cout << p.name << " (" << p.age << ") lives in " << p.address << '\n';
|
||||
}
|
||||
```
|
||||
|
||||
@@ -150,7 +150,9 @@ Ned Flanders (60) lives in 744 Evergreen Terrace
|
||||
|
||||
## See also
|
||||
|
||||
- [to_json](https://json.nlohmann.me/api/adl_serializer/to_json/index.md)
|
||||
- [`to_json`](https://json.nlohmann.me/api/adl_serializer/to_json/index.md) - convert a C++ value to JSON
|
||||
- [Arbitrary Type Conversions](https://json.nlohmann.me/features/arbitrary_types/index.md) - write your own `from_json` and `to_json` functions
|
||||
- [Converting values](https://json.nlohmann.me/features/conversions/index.md) - overview of `get`, `get_to` and implicit conversions
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/adl_serializer/" rel="canonical"><link href=../byte_container_with_subtype/subtype/ rel=prev><link href=from_json/ rel=next><link rel=icon href=../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>Overview - JSON for Modern C++</title><link rel=stylesheet href=../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../css/custom.css><script>__md_scope=new URL("../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannadl_serializer class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> Overview </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </lLine truncated
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/adl_serializer/" rel="canonical"><link href=../byte_container_with_subtype/subtype/ rel=prev><link href=from_json/ rel=next><link rel=icon href=../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>Overview - JSON for Modern C++</title><link rel=stylesheet href=../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../assets/stylesheets/palette.ab4e12ef.min.css><link rel=stylesheet href=../../css/custom.css><link rel=stylesheet href=../../css/brand.css><link rel=stylesheet href=../../css/fig-sax.css><link rel=stylesheet href=../../css/fig-jsonview.css><link rel=stylesheet href=../../css/fig-exceptions.css><link rel=stylesheet href=../../css/fig-pointer.css><link rel=stylesheet href=../../css/fig-charts.css><link rel=stylesheet href=../../css/fig-integration.css><link rel=stylesheet href=../../css/fig-macros.css><script>__md_scope=new URL("../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannadl_serializer class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> Overview </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1Line truncated
|
||||
<span class=k>struct</span><span class=w> </span><span class=nc>adl_serializer</span><span class=p>;</span>
|
||||
</code></pre></div> <p>Serializer that uses <abbr title="Argument-dependent lookup">ADL</abbr> (<a href="https://en.cppreference.com/w/cpp/language/adl">Argument-Dependent Lookup</a>) to choose <code>to_json</code>/<code>from_json</code> functions from the types' namespaces.</p> <p>It is implemented similarly to</p> <div class=highlight><pre><span></span><code><span class=k>template</span><span class=o><</span><span class=k>typename</span><span class=w> </span><span class=nc>ValueType</span><span class=o>></span>
|
||||
<span class=k>struct</span><span class=w> </span><span class=nc>adl_serializer</span><span class=w> </span><span class=p>{</span>
|
||||
@@ -12,4 +12,4 @@
|
||||
<span class=w> </span><span class=c1>// same thing, but with the "from_json" method</span>
|
||||
<span class=w> </span><span class=p>}</span>
|
||||
<span class=p>};</span>
|
||||
</code></pre></div> <h2 id=member-functions>Member functions<a class=headerlink href=#member-functions title="Permanent link">¶</a></h2> <ul> <li><a href=from_json/ ><strong>from_json</strong></a> - convert a <abbr title="JavaScript Object Notation">JSON</abbr> value to any value type</li> <li><a href=to_json/ ><strong>to_json</strong></a> - convert any value type to a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 2.1.0.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="May 4, 2025 08:28:24 UTC">May 4, 2025</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4C0 465.5 14.3 480 31.9 480H416c17.6 0 32-14.5 32-32.3V64.3c0-17.8-14.4-32.3-32-32.3M135.4 416H69V202.2h66.5V416zM102.2 96a38.5 38.5 0 1 1 0 77 38.5 38.5 0 1 1 0-77m282.1 320h-66.4V312c0-24.8-.5-56.7-34.5-56.7-34.6 0-39.9 27-39.9 54.9V416h-66.4V202.2h63.7v29.2h.9c8.9-16.8 30.6-34.5 62.9-34.5 67.2 0 79.7 44.3 79.7 101.9z"/></svg> </a> <a href="https://www.xing.com/profile/Niels_Lohmann" target="_blank" rel="noopener" title="www.xing.com" class="md-social__link"> <svg xmLine truncated
|
||||
</code></pre></div> <h2 id=member-functions>Member functions<a class=headerlink href=#member-functions title="Permanent link">¶</a></h2> <ul> <li><a href=from_json/ ><strong>from_json</strong></a> - convert a <abbr title="JavaScript Object Notation">JSON</abbr> value to any value type</li> <li><a href=to_json/ ><strong>to_json</strong></a> - convert any value type to a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> </ul> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../../features/arbitrary_types/ >Arbitrary type conversions</a> - how to make your types convertible</li> <li><a href=../basic_json/get/ ><code>get</code></a> - / <a href=../basic_json/get_to/ ><code>get_to</code></a> - convert a <abbr title="JavaScript Object Notation">JSON</abbr> value to a C++ type</li> <li><a href=../basic_json/basic_json/ ><code>basic_json</code></a> - construct a <abbr title="JavaScript Object Notation">JSON</abbr> value from a C++ value</li> <li><a href=../macros/nlohmann_define_type_intrusive/ ><code>NLOHMANN_DEFINE_TYPE_INTRUSIVE</code></a> - generate the conversion functions for a type</li> <li><a href=../../features/enum_conversion/ >Specializing enum conversion</a> - serializing enums as <abbr title="JavaScript Object Notation">JSON</abbr> strings</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 2.1.0.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../byte_container_with_subtype/subtype/ class="md-footer__link md-footer__link--prev" aria-label="Previous: subtype"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> subtype </div> </div> </a> <a href=from_json/ class="md-footer__link md-footer__link--next" aria-label="Next: from_json"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> from_json </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.Line truncated
|
||||
@@ -29,6 +29,14 @@ struct adl_serializer {
|
||||
- [**from_json**](https://json.nlohmann.me/api/adl_serializer/from_json/index.md) - convert a JSON value to any value type
|
||||
- [**to_json**](https://json.nlohmann.me/api/adl_serializer/to_json/index.md) - convert any value type to a JSON value
|
||||
|
||||
## See also
|
||||
|
||||
- [Arbitrary type conversions](https://json.nlohmann.me/features/arbitrary_types/index.md) - how to make your types convertible
|
||||
- [`get`](https://json.nlohmann.me/api/basic_json/get/index.md) - / [`get_to`](https://json.nlohmann.me/api/basic_json/get_to/index.md) - convert a JSON value to a C++ type
|
||||
- [`basic_json`](https://json.nlohmann.me/api/basic_json/basic_json/index.md) - construct a JSON value from a C++ value
|
||||
- [`NLOHMANN_DEFINE_TYPE_INTRUSIVE`](https://json.nlohmann.me/api/macros/nlohmann_define_type_intrusive/index.md) - generate the conversion functions for a type
|
||||
- [Specializing enum conversion](https://json.nlohmann.me/features/enum_conversion/index.md) - serializing enums as JSON strings
|
||||
|
||||
## Version history
|
||||
|
||||
- Added in version 2.1.0.
|
||||
@@ -25,18 +25,53 @@ This function is usually called by the constructors of the [basic_json](../basic
|
||||
by the `adl_serializer` when the constructor `basic_json(ns::person)` is called.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/to_json.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
namespace ns
|
||||
{
|
||||
// a simple struct to model a person
|
||||
struct person
|
||||
{
|
||||
std::string name;
|
||||
std::string address;
|
||||
int age;
|
||||
};
|
||||
} // namespace ns
|
||||
|
||||
namespace ns
|
||||
{
|
||||
void to_json(json& j, const person& p)
|
||||
{
|
||||
j = json{ {"name", p.name}, {"address", p.address}, {"age", p.age} };
|
||||
}
|
||||
} // namespace ns
|
||||
|
||||
int main()
|
||||
{
|
||||
ns::person p = {"Ned Flanders", "744 Evergreen Terrace", 60};
|
||||
|
||||
json j = p;
|
||||
|
||||
std::cout << j << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/to_json.output"
|
||||
{"address":"744 Evergreen Terrace","age":60,"name":"Ned Flanders"}
|
||||
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [from_json](from_json.md)
|
||||
- [`from_json`](from_json.md) - convert JSON to a C++ value
|
||||
- [Arbitrary Type Conversions](../../features/arbitrary_types.md) - write your own `from_json` and `to_json` functions
|
||||
- [Converting values](../../features/conversions.md) - overview of `get`, `get_to` and implicit conversions
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -1,11 +1,11 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/adl_serializer/to_json/" rel="canonical"><link href=../from_json/ rel=prev><link href=../../json/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>to_json - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../../css/custom.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannadl_serializerto_json class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> to_json </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/><Line truncated
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/adl_serializer/to_json/" rel="canonical"><link href=../from_json/ rel=prev><link href=../../is_json_view/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>to_json - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel=stylesheet href=../../../css/custom.css><link rel=stylesheet href=../../../css/brand.css><link rel=stylesheet href=../../../css/fig-sax.css><link rel=stylesheet href=../../../css/fig-jsonview.css><link rel=stylesheet href=../../../css/fig-exceptions.css><link rel=stylesheet href=../../../css/fig-pointer.css><link rel=stylesheet href=../../../css/fig-charts.css><link rel=stylesheet href=../../../css/fig-integration.css><link rel=stylesheet href=../../../css/fig-macros.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannadl_serializerto_json class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> to_json </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5Line truncated
|
||||
<span class=k>static</span><span class=w> </span><span class=k>auto</span><span class=w> </span><span class=n>to_json</span><span class=p>(</span><span class=n>BasicJsonType</span><span class=o>&</span><span class=w> </span><span class=n>j</span><span class=p>,</span><span class=w> </span><span class=n>TargetType</span><span class=w> </span><span class=o>&&</span><span class=w> </span><span class=n>val</span><span class=p>)</span><span class=w> </span><span class=k>noexcept</span><span class=p>(</span>
|
||||
<span class=w> </span><span class=k>noexcept</span><span class=p>(</span><span class=o>::</span><span class=n>nlohmann</span><span class=o>::</span><span class=n>to_json</span><span class=p>(</span><span class=n>j</span><span class=p>,</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>forward</span><span class=o><</span><span class=n>TargetType</span><span class=o>></span><span class=p>(</span><span class=n>val</span><span class=p>))))</span>
|
||||
<span class=o>-></span><span class=w> </span><span class=k>decltype</span><span class=p>(</span><span class=o>::</span><span class=n>nlohmann</span><span class=o>::</span><span class=n>to_json</span><span class=p>(</span><span class=n>j</span><span class=p>,</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>forward</span><span class=o><</span><span class=n>TargetType</span><span class=o>></span><span class=p>(</span><span class=n>val</span><span class=p>)),</span><span class=w> </span><span class=kt>void</span><span class=p>())</span>
|
||||
</code></pre></div> <p>This function is usually called by the constructors of the <a href=../../basic_json/ >basic_json</a> class.</p> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">¶</a></h2> <dl> <dt><code>j</code> (out)</dt> <dd><abbr title="JavaScript Object Notation">JSON</abbr> value to write to</dd> <dt><code>val</code> (in)</dt> <dd>value to read from</dd> </dl> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example</summary> <p>The example below shows how a <code>to_json</code> function can be implemented for a user-defined type. This function is called by the <code>adl_serializer</code> when the constructor <code>basic_json(ns::person)</code> is called.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=k>namespace</span><span class=w> </span><span class=nn>ns</span>
|
||||
<span class=p>{</span>
|
||||
@@ -32,7 +32,7 @@
|
||||
|
||||
<span class=w> </span><span class=n>json</span><span class=w> </span><span class=n>j</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>p</span><span class=p>;</span>
|
||||
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>j</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>endl</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>j</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code><span class=p>{</span><span class=nt>"address"</span><span class=p>:</span><span class=s2>"744 Evergreen Terrace"</span><span class=p>,</span><span class=nt>"age"</span><span class=p>:</span><span class=mi>60</span><span class=p>,</span><span class=nt>"name"</span><span class=p>:</span><span class=s2>"Ned Flanders"</span><span class=p>}</span>
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../from_json/ >from_json</a></li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 2.1.0.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="November 1, 2023 20:23:55 UTC">November 1, 2023</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4C0 465.5 14.3 480 31.9 480H416c17.6 0 32-14.5 32-32.3V64.3c0-17.8-14.4-32.3-32-32.3M135.4 416H69V202.2h66.5V416zM102.2 96a38.5 38.5 0 1 1 0 77 38.5 38.5 0 1 1 0-77m282.1 320h-66.4V312c0-24.8-.5-56.7-34.5-56.7-34.6 0-39.9 27-39.9 54.9V416h-66.4V202.2h63.7v29.2h.9c8.9-16.8 30.6-34.5 62.9-34.5 67.2 0 79.7 44.3 79.7 101.9z"/></svg> </a> <a href="https://www.xing.com/profile/Niels_Lohmann" target="_blank" rel="noopener" title="www.xing.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 384 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 FonticoLine truncated
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../from_json/ ><code>from_json</code></a> - convert <abbr title="JavaScript Object Notation">JSON</abbr> to a C++ value</li> <li><a href=../../../features/arbitrary_types/ >Arbitrary Type Conversions</a> - write your own <code>from_json</code> and <code>to_json</code> functions</li> <li><a href=../../../features/conversions/ >Converting values</a> - overview of <code>get</code>, <code>get_to</code> and implicit conversions</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 2.1.0.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../from_json/ class="md-footer__link md-footer__link--prev" aria-label="Previous: from_json"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> from_json </div> </div> </a> <a href=../../is_json_view/ class="md-footer__link md-footer__link--next" aria-label="Next: is_json_view"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> is_json_view </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.Line truncated
|
||||
@@ -25,7 +25,7 @@ The example below shows how a `to_json` function can be implemented for a user-d
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
namespace ns
|
||||
{
|
||||
@@ -52,7 +52,7 @@ int main()
|
||||
|
||||
json j = p;
|
||||
|
||||
std::cout << j << std::endl;
|
||||
std::cout << j << '\n';
|
||||
}
|
||||
```
|
||||
|
||||
@@ -64,7 +64,9 @@ Output:
|
||||
|
||||
## See also
|
||||
|
||||
- [from_json](https://json.nlohmann.me/api/adl_serializer/from_json/index.md)
|
||||
- [`from_json`](https://json.nlohmann.me/api/adl_serializer/from_json/index.md) - convert JSON to a C++ value
|
||||
- [Arbitrary Type Conversions](https://json.nlohmann.me/features/arbitrary_types/index.md) - write your own `from_json` and `to_json` functions
|
||||
- [Converting values](https://json.nlohmann.me/features/conversions/index.md) - overview of `get`, `get_to` and implicit conversions
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
+101
-6
@@ -44,6 +44,22 @@ are collected in [Template Parameter Requirements](../../features/types/template
|
||||
- [**json**](../json.md) - default specialization
|
||||
- [**ordered_json**](../ordered_json.md) - a specialization that maintains the insertion order of object keys
|
||||
|
||||
## Documents and views
|
||||
|
||||
Besides `basic_json`, the library offers a second way to hold a parsed JSON text: a
|
||||
[`basic_json_document`](../basic_json_document/index.md), which owns or borrows the text and holds a flat index of the
|
||||
values in it, and a [`basic_json_view`](../basic_json_view/index.md), a read-only handle to one value of such a document.
|
||||
Both are defined in the header `<nlohmann/json_view.hpp>`; see
|
||||
[Zero-copy JSON views](../../features/json_view.md) for the concept and the trade-offs.
|
||||
|
||||
- [**json_document**](../json_document.md) / [**ordered_json_document**](../ordered_json_document.md) - read-only
|
||||
documents of the `basic_json` specialization they belong to
|
||||
- [**json_editable_document**](../json_editable_document.md) /
|
||||
[**ordered_json_editable_document**](../ordered_json_editable_document.md) - documents that can be modified in place
|
||||
- [**json_view**](../json_view.md) / [**ordered_json_view**](../ordered_json_view.md) - views of a document
|
||||
- [**json_editable_view**](../json_editable_view.md) /
|
||||
[**ordered_json_editable_view**](../ordered_json_editable_view.md) - views of an editable document
|
||||
|
||||
## Iterator invalidation
|
||||
|
||||
All operations that add values to an **array** ([`push_back`](push_back.md) , [`operator+=`](operator+=.md),
|
||||
@@ -85,7 +101,7 @@ The class satisfies the following concept requirements:
|
||||
- [EqualityComparable](https://en.cppreference.com/w/cpp/named_req/EqualityComparable): JSON values can be compared with
|
||||
`==`, see [`operator==`](operator_eq.md).
|
||||
- [LessThanComparable](https://en.cppreference.com/w/cpp/named_req/LessThanComparable): JSON values can be compared with
|
||||
`<`, see [`operator<`](operator_le.md).
|
||||
`<`, see [`operator<`](operator_lt.md).
|
||||
- [Swappable](https://en.cppreference.com/w/cpp/named_req/Swappable): Any JSON lvalue or rvalue of can be swapped with
|
||||
any lvalue or rvalue of other compatible types, using unqualified function `swap`.
|
||||
- [NullablePointer](https://en.cppreference.com/w/cpp/named_req/NullablePointer): JSON values can be compared against
|
||||
@@ -105,10 +121,14 @@ The class satisfies the following concept requirements:
|
||||
- [**json_pointer**](../json_pointer/index.md) - JSON Pointer implementation
|
||||
- [**json_serializer**](json_serializer.md) - type of the serializer to for conversions from/to JSON
|
||||
- [**error_handler_t**](error_handler_t.md) - type to choose behavior on decoding errors
|
||||
- [**bjdata_version_t**](bjdata_version_t.md) - type to choose the BJData version to write
|
||||
- [**cbor_tag_handler_t**](cbor_tag_handler_t.md) - type to choose how to handle CBOR tags
|
||||
- **initializer_list_t** - type for initializer lists of `basic_json` values
|
||||
- [**input_format_t**](input_format_t.md) - type to choose the format to parse
|
||||
- [**json_sax_t**](../json_sax/index.md) - type for SAX events
|
||||
- [**with_object_t, with_array_t, with_string_t, with_boolean_t, with_integers_t, with_float_t, with_allocator_t,
|
||||
with_json_serializer_t, with_binary_t, with_base_class_t**](with_t.md) - types to create a `basic_json` type with
|
||||
one (or two) replaced template parameters
|
||||
|
||||
### Exceptions
|
||||
|
||||
@@ -169,7 +189,7 @@ The class satisfies the following concept requirements:
|
||||
Functions to inspect the type of a JSON value.
|
||||
|
||||
- [**type**](type.md) - return the type of the JSON value
|
||||
- [**operator value_t**](operator_value_t.md) - return the type of the JSON value
|
||||
- [`operator value_t`](operator_value_t.md) - return the type of the JSON value
|
||||
- [**type_name**](type_name.md) - return the type as string
|
||||
- [**is_primitive**](is_primitive.md) - return whether the type is primitive
|
||||
- [**is_structured**](is_structured.md) - return whether the type is structured
|
||||
@@ -198,7 +218,7 @@ Direct access to the stored value of a JSON value.
|
||||
- [**get_to**](get_to.md) - get a value and write it to a destination
|
||||
- [**get_ptr**](get_ptr.md) - get a pointer value
|
||||
- [**get_ref**](get_ref.md) - get a reference value
|
||||
- [**operator ValueType**](operator_ValueType.md) - get a value
|
||||
- [`operator ValueType`](operator_ValueType.md) - get a value
|
||||
- [**get_binary**](get_binary.md) - get a binary value
|
||||
- [**as_base_class**](as_base_class.md) - access the custom base class
|
||||
|
||||
@@ -282,6 +302,7 @@ Access to the JSON value
|
||||
### JSON Merge Patch functions
|
||||
|
||||
- [**merge_patch**](merge_patch.md) - applies a JSON Merge Patch
|
||||
- [**merge_diff**](merge_diff.md) (_static_) - creates a diff as a JSON Merge Patch
|
||||
|
||||
## Static functions
|
||||
|
||||
@@ -327,18 +348,92 @@ Access to the JSON value
|
||||
The example shows how the library is used.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/README.cpp"
|
||||
#include <iostream>
|
||||
#include <iomanip>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create a JSON object
|
||||
json j =
|
||||
{
|
||||
{"pi", 3.141},
|
||||
{"happy", true},
|
||||
{"name", "Niels"},
|
||||
{"nothing", nullptr},
|
||||
{
|
||||
"answer", {
|
||||
{"everything", 42}
|
||||
}
|
||||
},
|
||||
{"list", {1, 0, 2}},
|
||||
{
|
||||
"object", {
|
||||
{"currency", "USD"},
|
||||
{"value", 42.99}
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
// add new values
|
||||
j["new"]["key"]["value"] = {"another", "list"};
|
||||
|
||||
// count elements
|
||||
auto s = j.size();
|
||||
j["size"] = s;
|
||||
|
||||
// pretty print with indent of 4 spaces
|
||||
std::cout << std::setw(4) << j << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/README.output"
|
||||
{
|
||||
"answer": {
|
||||
"everything": 42
|
||||
},
|
||||
"happy": true,
|
||||
"list": [
|
||||
1,
|
||||
0,
|
||||
2
|
||||
],
|
||||
"name": "Niels",
|
||||
"new": {
|
||||
"key": {
|
||||
"value": [
|
||||
"another",
|
||||
"list"
|
||||
]
|
||||
}
|
||||
},
|
||||
"nothing": null,
|
||||
"object": {
|
||||
"currency": "USD",
|
||||
"value": 42.99
|
||||
},
|
||||
"pi": 3.141,
|
||||
"size": 8
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format](https://tools.ietf.org/html/rfc8259)
|
||||
- [RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format](https://tools.ietf.org/html/rfc8259) -
|
||||
specification of the JSON data interchange format
|
||||
- [`basic_json_document`](../basic_json_document/index.md) - / [`basic_json_view`](../basic_json_view/index.md) - parse a JSON
|
||||
text into a flat index and read it through a view
|
||||
- [Zero-copy JSON views](../../features/json_view.md) - when to use a document and a view instead of a `basic_json`
|
||||
- [Types](../../features/types/index.md) - how JSON values are stored and which types exist
|
||||
- [Converting values](../../features/conversions.md) - get values out of a JSON value and put values in
|
||||
- [Creating JSON values](../../features/creating_values.md) - all the ways to build a JSON value
|
||||
- [Arbitrary Type Conversions](../../features/arbitrary_types.md) - convert your own types to and from JSON
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
+107
-8
@@ -23,6 +23,9 @@ Checks whether the input is valid JSON.
|
||||
respectively as UTF-8, UTF-16, and UTF-32. If `SentinelType` differs from `IteratorType`, it must be comparable to
|
||||
the iterator type with `operator!=`.
|
||||
|
||||
Ill-formed UTF-16 and UTF-32 sequences are rejected: a lone surrogate, a high surrogate that is not followed by its
|
||||
low surrogate, and a code point above `U+10FFFF` all make this function return `false`.
|
||||
|
||||
Unlike the [`parse()`](parse.md) function, this function neither throws an exception in case of invalid JSON input
|
||||
(i.e., a parse error) nor creates diagnostic information.
|
||||
|
||||
@@ -35,9 +38,12 @@ Unlike the [`parse()`](parse.md) function, this function neither throws an excep
|
||||
- a `#!c FILE` pointer (throws if null)
|
||||
- a C-style array of characters
|
||||
- a pointer to a null-terminated string of single byte characters (throws if null)
|
||||
- a `std::string`
|
||||
- a `std::string` or a `std::string_view` (C++17)
|
||||
- a container `obj` for which `begin(obj)` and `end(obj)` produce a valid pair of iterators
|
||||
(as found via ADL or member functions, with semantics compatible to `std::begin` and `std::end`)
|
||||
- wide characters (`wchar_t`, `char16_t`, `char32_t`), which are converted to UTF-8: a wide string object
|
||||
(`std::wstring`, `std::u16string`, `std::u32string`) or an array (e.g. a wide string literal); a pointer to a
|
||||
null-terminated wide string (e.g. `std::u16string::c_str()`) is not supported
|
||||
|
||||
`IteratorType`
|
||||
: a compatible iterator type, for instance.
|
||||
@@ -101,13 +107,40 @@ outside of a string, invalid) byte; see the [FAQ entry](../../home/faq.md#nul-by
|
||||
The example below demonstrates the `accept()` function reading from a string.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/accept__string.cpp"
|
||||
#include <iostream>
|
||||
#include <iomanip>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// a valid JSON text
|
||||
const auto* valid_text = R"(
|
||||
{
|
||||
"numbers": [1, 2, 3]
|
||||
}
|
||||
)";
|
||||
|
||||
// an invalid JSON text
|
||||
const auto* invalid_text = R"(
|
||||
{
|
||||
"strings": ["extra", "comma", ]
|
||||
}
|
||||
)";
|
||||
|
||||
std::cout << std::boolalpha
|
||||
<< json::accept(valid_text) << ' '
|
||||
<< json::accept(invalid_text) << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/accept__string.output"
|
||||
true false
|
||||
|
||||
```
|
||||
|
||||
??? example "Example: (2) reading from an iterator pair"
|
||||
@@ -116,22 +149,81 @@ outside of a string, invalid) byte; see the [FAQ entry](../../home/faq.md#nul-by
|
||||
exactly the JSON text; the second one also covers the trailing bytes and is therefore rejected.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/accept__iterator_pair.cpp"
|
||||
#include <iostream>
|
||||
#include <vector>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// a buffer containing a JSON text followed by more data
|
||||
std::vector<std::uint8_t> input = {'[', '1', ',', '2', ',', '3', ']', 'o', 't', 'h', 'e', 'r'};
|
||||
|
||||
std::cout << std::boolalpha
|
||||
<< json::accept(input.begin(), input.begin() + 7) << ' '
|
||||
<< json::accept(input.begin(), input.end()) << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/accept__iterator_pair.output"
|
||||
true false
|
||||
|
||||
```
|
||||
|
||||
??? example "Example: (3) reading from UTF-16 strings"
|
||||
|
||||
The encoding is deduced from the character type of the input. String literals like `u"..."`, `U"..."`, and
|
||||
`L"..."` work as well.
|
||||
|
||||
```cpp
|
||||
#include <iostream>
|
||||
#include <string>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// a valid JSON text, given as UTF-16
|
||||
const std::u16string valid_text = u"{\"name\":\"\u00e9\"}";
|
||||
|
||||
// an invalid JSON text, given as UTF-16
|
||||
const std::u16string invalid_text = u"{\"name\":\"\u00e9\",}";
|
||||
|
||||
std::cout << std::boolalpha
|
||||
<< json::accept(valid_text) << ' '
|
||||
<< json::accept(invalid_text) << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
true false
|
||||
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [parse](parse.md) - deserialize from a compatible input
|
||||
- [sax_parse](sax_parse.md) - parse input using the SAX interface
|
||||
- [operator>>](../operator_gtgt.md) - deserialize from stream
|
||||
- [`parse`](parse.md) - deserialize from a compatible input
|
||||
- [`sax_parse`](sax_parse.md) - parse input using the SAX interface
|
||||
- [`operator>>`](../operator_gtgt.md) - deserialize from stream
|
||||
- [`JSON_STRICT_NUL_HANDLING`](../macros/json_strict_nul_handling.md) - opt in to rejecting a NUL byte in the input
|
||||
instead of treating it as end of input
|
||||
- [`JSON_DISABLE_STREAM_BULK_SCAN`](../macros/json_disable_stream_bulk_scan.md) - read a `std::istream` one character
|
||||
at a time
|
||||
- [`JSON_DISABLE_UNLOCKED_FILE_IO`](../macros/json_disable_unlocked_file_io.md) - read a `FILE*` with the locking stdio
|
||||
functions
|
||||
- [Parsing](../../features/parsing/index.md) - overview of the parsing functions
|
||||
- [Comments](../../features/comments.md) - ignore `//` and `/* */` comments while parsing
|
||||
- [Trailing Commas](../../features/trailing_commas.md) - accept trailing commas in arrays and objects
|
||||
- [Parsing and Exceptions](../../features/parsing/parse_exceptions.md) - handling parse errors and locating them in the input
|
||||
- [Parsing Untrusted Input](../../features/parsing/untrusted_input.md) - limits and checks for input you do not control
|
||||
|
||||
## Version history
|
||||
|
||||
@@ -143,6 +235,13 @@ outside of a string, invalid) byte; see the [FAQ entry](../../home/faq.md#nul-by
|
||||
- Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.
|
||||
- `JSON_STRICT_NUL_HANDLING` added in version 3.13.0 to optionally reject a NUL byte in the input instead of treating
|
||||
it as end of input; planned to become the default in version 4.0.0.
|
||||
- Parsing from an `std::istream` scans the characters in its stream buffer in bulk in version 3.13.0
|
||||
([`JSON_DISABLE_STREAM_BULK_SCAN`](../macros/json_disable_stream_bulk_scan.md)).
|
||||
- Parsing from a `FILE*` locks the file once instead of once per character in version 3.13.0
|
||||
([`JSON_DISABLE_UNLOCKED_FILE_IO`](../macros/json_disable_unlocked_file_io.md)).
|
||||
- Ill-formed UTF-16 and UTF-32 input (a lone surrogate, a high surrogate that is not followed by its low surrogate, or
|
||||
a code point above `U+10FFFF`) is rejected in version 3.13.0; before that, some such sequences were accepted or
|
||||
ended the input silently.
|
||||
|
||||
!!! warning "Deprecation"
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/accept/" rel="canonical"><link href=../~basic_json/ rel=prev><link href=../array/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>accept - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../../css/custom.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsonaccept class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> accept </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </labeLine truncated
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/accept/" rel="canonical"><link href=../~basic_json/ rel=prev><link href=../array/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>accept - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel=stylesheet href=../../../css/custom.css><link rel=stylesheet href=../../../css/brand.css><link rel=stylesheet href=../../../css/fig-sax.css><link rel=stylesheet href=../../../css/fig-jsonview.css><link rel=stylesheet href=../../../css/fig-exceptions.css><link rel=stylesheet href=../../../css/fig-pointer.css><link rel=stylesheet href=../../../css/fig-charts.css><link rel=stylesheet href=../../../css/fig-integration.css><link rel=stylesheet href=../../../css/fig-macros.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsonaccept class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> accept </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 Line truncated
|
||||
<span class=k>template</span><span class=o><</span><span class=k>typename</span><span class=w> </span><span class=nc>InputType</span><span class=o>></span>
|
||||
<span class=k>static</span><span class=w> </span><span class=kt>bool</span><span class=w> </span><span class=n>accept</span><span class=p>(</span><span class=n>InputType</span><span class=o>&&</span><span class=w> </span><span class=n>i</span><span class=p>,</span>
|
||||
<span class=w> </span><span class=k>const</span><span class=w> </span><span class=kt>bool</span><span class=w> </span><span class=n>ignore_comments</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=nb>false</span><span class=p>,</span>
|
||||
@@ -9,23 +9,23 @@
|
||||
<span class=k>static</span><span class=w> </span><span class=kt>bool</span><span class=w> </span><span class=n>accept</span><span class=p>(</span><span class=n>IteratorType</span><span class=w> </span><span class=n>first</span><span class=p>,</span><span class=w> </span><span class=n>SentinelType</span><span class=w> </span><span class=n>last</span><span class=p>,</span>
|
||||
<span class=w> </span><span class=k>const</span><span class=w> </span><span class=kt>bool</span><span class=w> </span><span class=n>ignore_comments</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=nb>false</span><span class=p>,</span>
|
||||
<span class=w> </span><span class=k>const</span><span class=w> </span><span class=kt>bool</span><span class=w> </span><span class=n>ignore_trailing_commas</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=nb>false</span><span class=p>);</span>
|
||||
</code></pre></div> <p>Checks whether the input is valid <abbr title="JavaScript Object Notation">JSON</abbr>.</p> <ol> <li>Reads from a compatible input.</li> <li> <p>Reads from a pair of character iterators, or an iterator and a sentinel of a different type (C++20 ranges support)</p> <p>The value_type of the iterator must be an integral type with a size of 1, 2, or 4 bytes, which will be interpreted respectively as <abbr title="Unicode Transformation Format">UTF</abbr>-8, <abbr title="Unicode Transformation Format">UTF</abbr>-16, and <abbr title="Unicode Transformation Format">UTF</abbr>-32. If <code>SentinelType</code> differs from <code>IteratorType</code>, it must be comparable to the iterator type with <code>operator!=</code>.</p> </li> </ol> <p>Unlike the <a href=../parse/ ><code>parse()</code></a> function, this function neither throws an exception in case of invalid <abbr title="JavaScript Object Notation">JSON</abbr> input (i.e., a parse error) nor creates diagnostic information.</p> <h2 id=template-parameters>Template parameters<a class=headerlink href=#template-parameters title="Permanent link">¶</a></h2> <dl> <dt><code>InputType</code></dt> <dd> <p>A compatible input, for instance:</p> <ul> <li>an <code>std::istream</code> object</li> <li>a <code class=highlight><span class=kt>FILE</span></code> pointer (throws if null)</li> <li>a C-style array of characters</li> <li>a pointer to a null-terminated string of single byte characters (throws if null)</li> <li>a <code>std::string</code></li> <li>a container <code>obj</code> for which <code>begin(obj)</code> and <code>end(obj)</code> produce a valid pair of iterators (as found via <abbr title="Argument-dependent lookup">ADL</abbr> or member functions, with semantics compatible to <code>std::begin</code> and <code>std::end</code>)</li> </ul> </dd> <dt><code>IteratorType</code></dt> <dd> <p>a compatible iterator type, for instance.</p> <ul> <li>a pair of <code>std::string::iterator</code> or <code>std::vector<std::uint8_t>::iterator</code></li> <li>a pair of pointers such as <code>ptr</code> and <code>ptr + len</code></li> </ul> </dd> <dt><code>SentinelType</code></dt> <dd> <p>defaults to <code>IteratorType</code>; may be a different type comparable to <code>IteratorType</code> via <code>operator!=</code>, for instance.</p> <ul> <li>a custom sentinel type for C++20 ranges</li> <li><code>std::default_sentinel_t</code>, when <code>IteratorType</code> is <code>std::counted_iterator</code></li> </ul> </dd> </dl> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">¶</a></h2> <dl> <dt><code>i</code> (in)</dt> <dd>Input to parse from.</dd> <dt><code>ignore_comments</code> (in)</dt> <dd>whether comments should be ignored and treated like whitespace (<code class=highlight><span class=nb>true</span></code>) or yield a parse error (<code class=highlight><span class=nb>false</span></code>); (optional, <code class=highlight><span class=nb>false</span></code> by default)</dd> <dt><code>ignore_trailing_commas</code> (in)</dt> <dd>whether trailing commas in arrays or objects should be ignored and treated like whitespace (<code class=highlight><span class=nb>true</span></code>) or yield a parse error (<code class=highlight><span class=nb>false</span></code>); (optional, <code class=highlight><span class=nb>false</span></code> by default)</dd> <dt><code>first</code> (in)</dt> <dd>iterator to the start of the character range</dd> <dt><code>last</code> (in)</dt> <dd>iterator to the end of the character range, or a sentinel value that compares equal to the end iterator with <code>operator!=</code></dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">¶</a></h2> <p>Whether the input is valid <abbr title="JavaScript Object Notation">JSON</abbr>.</p> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">¶</a></h2> <p>Strong guarantee: if an exception is thrown, there are no changes in the <abbr title="JavaScript Object Notation">JSON</abbr> value.</p> <h2 id=exceptions>Exceptions<a class=headerlink href=#exceptions title="Permanent link">¶</a></h2> <p>Throws <a href=../../../home/exceptions/#jsonexceptionparse_error101><code>parse_error.101</code></a> in case of an empty input like a null <code class=highlight><span class=kt>FILE</span><span class=o>*</span></code> or <code class=highlight><span class=kt>char</span><span class=o>*</span></code> pointer.</p> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">¶</a></h2> <p>Linear in the length of the input. The parser is a predictive LL(1) parser.</p> <h2 id=notes>Notes<a class=headerlink href=#notes title="Permanent link">¶</a></h2> <p>A <abbr title="Unicode Transformation Format">UTF</abbr>-8 byte order mark is silently ignored.</p> <p>By default, a <code>'\0'</code> (NUL) byte anywhere in the input is treated aLine truncated
|
||||
</code></pre></div> <p>Checks whether the input is valid <abbr title="JavaScript Object Notation">JSON</abbr>.</p> <ol> <li>Reads from a compatible input.</li> <li> <p>Reads from a pair of character iterators, or an iterator and a sentinel of a different type (C++20 ranges support)</p> <p>The value_type of the iterator must be an integral type with a size of 1, 2, or 4 bytes, which will be interpreted respectively as <abbr title="Unicode Transformation Format">UTF</abbr>-8, <abbr title="Unicode Transformation Format">UTF</abbr>-16, and <abbr title="Unicode Transformation Format">UTF</abbr>-32. If <code>SentinelType</code> differs from <code>IteratorType</code>, it must be comparable to the iterator type with <code>operator!=</code>.</p> <p>Ill-formed <abbr title="Unicode Transformation Format">UTF</abbr>-16 and <abbr title="Unicode Transformation Format">UTF</abbr>-32 sequences are rejected: a lone surrogate, a high surrogate that is not followed by its low surrogate, and a code point above <code>U+10FFFF</code> all make this function return <code>false</code>.</p> </li> </ol> <p>Unlike the <a href=../parse/ ><code>parse()</code></a> function, this function neither throws an exception in case of invalid <abbr title="JavaScript Object Notation">JSON</abbr> input (i.e., a parse error) nor creates diagnostic information.</p> <h2 id=template-parameters>Template parameters<a class=headerlink href=#template-parameters title="Permanent link">¶</a></h2> <dl> <dt><code>InputType</code></dt> <dd> <p>A compatible input, for instance:</p> <ul> <li>an <code>std::istream</code> object</li> <li>a <code class=highlight><span class=kt>FILE</span></code> pointer (throws if null)</li> <li>a C-style array of characters</li> <li>a pointer to a null-terminated string of single byte characters (throws if null)</li> <li>a <code>std::string</code> or a <code>std::string_view</code> (C++17)</li> <li>a container <code>obj</code> for which <code>begin(obj)</code> and <code>end(obj)</code> produce a valid pair of iterators (as found via <abbr title="Argument-dependent lookup">ADL</abbr> or member functions, with semantics compatible to <code>std::begin</code> and <code>std::end</code>)</li> <li>wide characters (<code>wchar_t</code>, <code>char16_t</code>, <code>char32_t</code>), which are converted to <abbr title="Unicode Transformation Format">UTF</abbr>-8: a wide string object (<code>std::wstring</code>, <code>std::u16string</code>, <code>std::u32string</code>) or an array (e.g. a wide string literal); a pointer to a null-terminated wide string (e.g. <code>std::u16string::c_str()</code>) is not supported</li> </ul> </dd> <dt><code>IteratorType</code></dt> <dd> <p>a compatible iterator type, for instance.</p> <ul> <li>a pair of <code>std::string::iterator</code> or <code>std::vector<std::uint8_t>::iterator</code></li> <li>a pair of pointers such as <code>ptr</code> and <code>ptr + len</code></li> </ul> </dd> <dt><code>SentinelType</code></dt> <dd> <p>defaults to <code>IteratorType</code>; may be a different type comparable to <code>IteratorType</code> via <code>operator!=</code>, for instance.</p> <ul> <li>a custom sentinel type for C++20 ranges</li> <li><code>std::default_sentinel_t</code>, when <code>IteratorType</code> is <code>std::counted_iterator</code></li> </ul> </dd> </dl> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">¶</a></h2> <dl> <dt><code>i</code> (in)</dt> <dd>Input to parse from.</dd> <dt><code>ignore_comments</code> (in)</dt> <dd>whether comments should be ignored and treated like whitespace (<code class=highlight><span class=nb>true</span></code>) or yield a parse error (<code class=highlight><span class=nb>false</span></code>); (optional, <code class=highlight><span class=nb>false</span></code> by default)</dd> <dt><code>ignore_trailing_commas</code> (in)</dt> <dd>whether trailing commas in arrays or objects should be ignored and treated like whitespace (<code class=highlight><span class=nb>true</span></code>) or yield a parse error (<code class=highlight><span class=nb>false</span></code>); (optional, <code class=highlight><span class=nb>false</span></code> by default)</dd> <dt><code>first</code> (in)</dt> <dd>iterator to the start of the character range</dd> <dt><code>last</code> (in)</dt> <dd>iterator to the end of the character range, or a sentinel value that compares equal to the end iterator with <code>operator!=</code></dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">¶</a></h2> <p>Whether the input is valid <abbr title="JavaScript Object Notation">JSON</abbr>.</p> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">¶</a></h2> <p>Strong guarantee: if an exception is thrown, there are no changes in the <abbr title="JavaScript Object Notation">JSON</abbr> value.</p> <h2 id=exceptions>Exceptions<a class=headerlink href=#exceptions title=Line truncated
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><iomanip></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
<span class=w> </span><span class=c1>// a valid JSON text</span>
|
||||
<span class=w> </span><span class=k>auto</span><span class=w> </span><span class=n>valid_text</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=sa>R</span><span class=s>"</span><span class=dl>(</span>
|
||||
<span class=w> </span><span class=k>const</span><span class=w> </span><span class=k>auto</span><span class=o>*</span><span class=w> </span><span class=n>valid_text</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=sa>R</span><span class=s>"</span><span class=dl>(</span>
|
||||
<span class=s> {</span>
|
||||
<span class=s> "numbers": [1, 2, 3]</span>
|
||||
<span class=s> }</span>
|
||||
<span class=s> </span><span class=dl>)</span><span class=s>"</span><span class=p>;</span>
|
||||
|
||||
<span class=w> </span><span class=c1>// an invalid JSON text</span>
|
||||
<span class=w> </span><span class=k>auto</span><span class=w> </span><span class=n>invalid_text</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=sa>R</span><span class=s>"</span><span class=dl>(</span>
|
||||
<span class=w> </span><span class=k>const</span><span class=w> </span><span class=k>auto</span><span class=o>*</span><span class=w> </span><span class=n>invalid_text</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=sa>R</span><span class=s>"</span><span class=dl>(</span>
|
||||
<span class=s> {</span>
|
||||
<span class=s> "strings": ["extra", "comma", ]</span>
|
||||
<span class=s> }</span>
|
||||
@@ -40,7 +40,7 @@
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><vector></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -52,4 +52,23 @@
|
||||
<span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>accept</span><span class=p>(</span><span class=n>input</span><span class=p>.</span><span class=n>begin</span><span class=p>(),</span><span class=w> </span><span class=n>input</span><span class=p>.</span><span class=n>end</span><span class=p>())</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code><span class=kc>true</span><span class=w> </span><span class=kc>false</span>
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../parse/ >parse</a> - deserialize from a compatible input</li> <li><a href=../sax_parse/ >sax_parse</a> - parse input using the <abbr title="Simple API for XML">SAX</abbr> interface</li> <li><a href=../../operator_gtgt/ >operator>></a> - deserialize from stream</li> <li><a href=../../macros/json_strict_nul_handling/ ><code>JSON_STRICT_NUL_HANDLING</code></a> - opt in to rejecting a NUL byte in the input instead of treating it as end of input</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 3.0.0.</li> <li>Ignoring comments via <code>ignore_comments</code> added in version 3.9.0.</li> <li>Changed <a href=../../../features/assertions/ >runtime assertion</a> in case of <code>FILE*</code> null pointers to exception in version 3.12.0.</li> <li>Added <code>ignore_trailing_commas</code> in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>.</li> <li>Extended container support (1) to include types with lvalue-only <abbr title="Argument-dependent lookup">ADL</abbr> <code>begin</code>/<code>end</code> (matching <code>std::begin</code>/<code>std::end</code> semantics) in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>.</li> <li>Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>.</li> <li><code>JSON_STRICT_NUL_HANDLING</code> added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span> to optionally reject a NUL byte in the input instead of treating it as end of input; planned to become the default in version 4.0.0.</li> </ul> <div class="admonition warning"> <p class=admonition-title>Deprecation</p> <p>Overload (2) replaces calls to <code>accept</code> with a pair of iterators as their first parameter which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like <code class=highlight><span class=n>accept</span><span class=p>({</span><span class=n>ptr</span><span class=p>,</span><span class=w> </span><span class=n>ptr</span><span class=o>+</span><span class=n>len</span><span class=p>},</span><span class=w> </span><span class=p>...);</span></code> with <code class=highlight><span class=n>accept</span><span class=p>(</span><span class=n>ptr</span><span class=p>,</span><span class=w> </span><span class=n>ptr</span><span class=o>+</span><span class=n>len</span><span class=p>,</span><span class=w> </span><span class=p>...);</span></code>.</p> <p>You should be warned by your compiler with a <code>-Wdeprecated-declarations</code> warning if you are using a deprecated function.</p> <p>See the <a href=../../../integration/migration_guide/#parsing>migration guide</a> for how to update existing code.</p> </div> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 2, 2026 09:32:15 UTC">October 2, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Line truncated
|
||||
</code></pre></div> </details> <details class=example> <summary>Example: (3) reading from <abbr title="Unicode Transformation Format">UTF</abbr>-16 strings</summary> <p>The encoding is deduced from the character type of the input. String literals like <code>u"..."</code>, <code>U"..."</code>, and <code>L"..."</code> work as well.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><string></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
<span class=w> </span><span class=c1>// a valid JSON text, given as UTF-16</span>
|
||||
<span class=w> </span><span class=k>const</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>u16string</span><span class=w> </span><span class=n>valid_text</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=sa>u</span><span class=s>"{</span><span class=se>\"</span><span class=s>name</span><span class=se>\"</span><span class=s>:</span><span class=se>\"\u00e9\"</span><span class=s>}"</span><span class=p>;</span>
|
||||
|
||||
<span class=w> </span><span class=c1>// an invalid JSON text, given as UTF-16</span>
|
||||
<span class=w> </span><span class=k>const</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>u16string</span><span class=w> </span><span class=n>invalid_text</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=sa>u</span><span class=s>"{</span><span class=se>\"</span><span class=s>name</span><span class=se>\"</span><span class=s>:</span><span class=se>\"\u00e9\"</span><span class=s>,}"</span><span class=p>;</span>
|
||||
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>boolalpha</span>
|
||||
<span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>accept</span><span class=p>(</span><span class=n>valid_text</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>' '</span>
|
||||
<span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>accept</span><span class=p>(</span><span class=n>invalid_text</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code><span class=kc>true</span><span class=w> </span><span class=kc>false</span>
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../parse/ ><code>parse</code></a> - deserialize from a compatible input</li> <li><a href=../sax_parse/ ><code>sax_parse</code></a> - parse input using the <abbr title="Simple API for XML">SAX</abbr> interface</li> <li><a href=../../operator_gtgt/ ><code>operator>></code></a> - deserialize from stream</li> <li><a href=../../macros/json_strict_nul_handling/ ><code>JSON_STRICT_NUL_HANDLING</code></a> - opt in to rejecting a <abbr title="Null character (U+0000, byte value 0)">NUL</abbr> byte in the input instead of treating it as end of input</li> <li><a href=../../macros/json_disable_stream_bulk_scan/ ><code>JSON_DISABLE_STREAM_BULK_SCAN</code></a> - read a <code>std::istream</code> one character at a time</li> <li><a href=../../macros/json_disable_unlocked_file_io/ ><code>JSON_DISABLE_UNLOCKED_FILE_IO</code></a> - read a <code>FILE*</code> with the locking stdio functions</li> <li><a href=../../../features/parsing/ >Parsing</a> - overview of the parsing functions</li> <li><a href=../../../features/comments/ >Comments</a> - ignore <code>//</code> and <code>/* */</code> comments while parsing</li> <li><a href=../../../features/trailing_commas/ >Trailing Commas</a> - accept trailing commas in arrays and objects</li> <li><a href=../../../features/parsing/parse_exceptions/ >Parsing and Exceptions</a> - handling parse errors and locating them in the input</li> <li><a href=../../../features/parsing/untrusted_input/ >Parsing Untrusted Input</a> - limits and checks for input you do not control</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 3.0.0.</li> <li>Ignoring comments via <code>ignore_comments</code> added in version 3.9.0.</li> <li>Changed <a href=../../../features/assertions/ >runtime assertion</a> in case of <code>FILE*</code> null pointers to exception in version 3.12.0.</li> <li>Added <code>ignore_trailing_commas</code> in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>.</li> <li>Extended container support (1) to include types with lvalue-only <abbr title="Argument-dependent lookup">ADL</abbr> <code>begin</code>/<code>end</code> (matching <code>std::begin</code>/<code>std::end</code> semantics) in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>.</li> <li>Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>.</li> <li><code>JSON_STRICT_NUL_HANDLING</code> added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span> to optionally reject a <abbr title="Null character (U+0000, byte value 0)">NUL</abbr> byte in the input instead of treating it as end of input; planned to become the default in version 4.0.0.</li> <li>Parsing from an <code>std::istream</code> scans the characters in its stream buffer in bulk in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span> (<a href=../../macros/json_disable_stream_bulk_scan/ ><code>JSON_DISABLE_STREAM_BULK_SCAN</code></a>).</li> <li>Parsing from a <code>FILE*</code> locks the file once instead of once per character in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span> (<a href=../../macros/json_disable_unlocked_file_io/ ><code>JSON_DISABLE_UNLOCKED_FILE_IO</code></a>).</li> <li>Ill-formed <abbr title="Unicode Transformation Format">UTF</abbr>-16 and <abbr title="Unicode Transformation Format">UTF</abbr>-32 input (a lone surrogate, a high surrogate that is not followed by its low surrogate, or a code point above <code>U+10FFFF</code>) is rejected in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>; before that, some such sequences were accepted or ended the input silently.</li> </ul> <div class="admonition warning"> <p class=admonition-title>Deprecation</p> <p>Overload (2) replaces calls to <code>accept</code> with a pair of iterators as their first parameter which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like <code class=highlight><span class=n>accept</span><span class=p>({</span><span class=n>ptr</span><span class=p>,</span><span class=w> </span><span class=n>ptr</span><span class=o>+</span><span class=n>len</span><span class=p>},</span><span class=w> </span><span class=p>...);</span></code> with <code class=highlighLine truncated
|
||||
@@ -22,6 +22,8 @@ Checks whether the input is valid JSON.
|
||||
|
||||
The value_type of the iterator must be an integral type with a size of 1, 2, or 4 bytes, which will be interpreted respectively as UTF-8, UTF-16, and UTF-32. If `SentinelType` differs from `IteratorType`, it must be comparable to the iterator type with `operator!=`.
|
||||
|
||||
Ill-formed UTF-16 and UTF-32 sequences are rejected: a lone surrogate, a high surrogate that is not followed by its low surrogate, and a code point above `U+10FFFF` all make this function return `false`.
|
||||
|
||||
Unlike the [`parse()`](https://json.nlohmann.me/api/basic_json/parse/index.md) function, this function neither throws an exception in case of invalid JSON input (i.e., a parse error) nor creates diagnostic information.
|
||||
|
||||
## Template parameters
|
||||
@@ -33,9 +35,12 @@ Unlike the [`parse()`](https://json.nlohmann.me/api/basic_json/parse/index.md) f
|
||||
- a `FILE` pointer (throws if null)
|
||||
- a C-style array of characters
|
||||
- a pointer to a null-terminated string of single byte characters (throws if null)
|
||||
- a `std::string`
|
||||
- a `std::string` or a `std::string_view` (C++17)
|
||||
- a container `obj` for which `begin(obj)` and `end(obj)` produce a valid pair of iterators
|
||||
(as found via ADL or member functions, with semantics compatible to `std::begin` and `std::end`)
|
||||
- wide characters (`wchar_t`, `char16_t`, `char32_t`), which are converted to UTF-8: a wide string object
|
||||
(`std::wstring`, `std::u16string`, `std::u32string`) or an array (e.g. a wide string literal); a pointer to a
|
||||
null-terminated wide string (e.g. `std::u16string::c_str()`) is not supported
|
||||
```
|
||||
|
||||
`IteratorType` : a compatible iterator type, for instance.
|
||||
@@ -97,19 +102,19 @@ The example below demonstrates the `accept()` function reading from a string.
|
||||
#include <iomanip>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// a valid JSON text
|
||||
auto valid_text = R"(
|
||||
const auto* valid_text = R"(
|
||||
{
|
||||
"numbers": [1, 2, 3]
|
||||
}
|
||||
)";
|
||||
|
||||
// an invalid JSON text
|
||||
auto invalid_text = R"(
|
||||
const auto* invalid_text = R"(
|
||||
{
|
||||
"strings": ["extra", "comma", ]
|
||||
}
|
||||
@@ -136,7 +141,7 @@ The example below demonstrates the `accept()` function reading from an iterator
|
||||
#include <vector>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -155,12 +160,50 @@ Output:
|
||||
true false
|
||||
```
|
||||
|
||||
Example: (3) reading from UTF-16 strings
|
||||
|
||||
The encoding is deduced from the character type of the input. String literals like `u"..."`, `U"..."`, and `L"..."` work as well.
|
||||
|
||||
```
|
||||
#include <iostream>
|
||||
#include <string>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// a valid JSON text, given as UTF-16
|
||||
const std::u16string valid_text = u"{\"name\":\"\u00e9\"}";
|
||||
|
||||
// an invalid JSON text, given as UTF-16
|
||||
const std::u16string invalid_text = u"{\"name\":\"\u00e9\",}";
|
||||
|
||||
std::cout << std::boolalpha
|
||||
<< json::accept(valid_text) << ' '
|
||||
<< json::accept(invalid_text) << '\n';
|
||||
}
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
true false
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [parse](https://json.nlohmann.me/api/basic_json/parse/index.md) - deserialize from a compatible input
|
||||
- [sax_parse](https://json.nlohmann.me/api/basic_json/sax_parse/index.md) - parse input using the SAX interface
|
||||
- [operator>>](https://json.nlohmann.me/api/operator_gtgt/index.md) - deserialize from stream
|
||||
- [`parse`](https://json.nlohmann.me/api/basic_json/parse/index.md) - deserialize from a compatible input
|
||||
- [`sax_parse`](https://json.nlohmann.me/api/basic_json/sax_parse/index.md) - parse input using the SAX interface
|
||||
- [`operator>>`](https://json.nlohmann.me/api/operator_gtgt/index.md) - deserialize from stream
|
||||
- [`JSON_STRICT_NUL_HANDLING`](https://json.nlohmann.me/api/macros/json_strict_nul_handling/index.md) - opt in to rejecting a NUL byte in the input instead of treating it as end of input
|
||||
- [`JSON_DISABLE_STREAM_BULK_SCAN`](https://json.nlohmann.me/api/macros/json_disable_stream_bulk_scan/index.md) - read a `std::istream` one character at a time
|
||||
- [`JSON_DISABLE_UNLOCKED_FILE_IO`](https://json.nlohmann.me/api/macros/json_disable_unlocked_file_io/index.md) - read a `FILE*` with the locking stdio functions
|
||||
- [Parsing](https://json.nlohmann.me/features/parsing/index.md) - overview of the parsing functions
|
||||
- [Comments](https://json.nlohmann.me/features/comments/index.md) - ignore `//` and `/* */` comments while parsing
|
||||
- [Trailing Commas](https://json.nlohmann.me/features/trailing_commas/index.md) - accept trailing commas in arrays and objects
|
||||
- [Parsing and Exceptions](https://json.nlohmann.me/features/parsing/parse_exceptions/index.md) - handling parse errors and locating them in the input
|
||||
- [Parsing Untrusted Input](https://json.nlohmann.me/features/parsing/untrusted_input/index.md) - limits and checks for input you do not control
|
||||
|
||||
## Version history
|
||||
|
||||
@@ -171,6 +214,9 @@ true false
|
||||
- Extended container support (1) to include types with lvalue-only ADL `begin`/`end` (matching `std::begin`/`std::end` semantics) in version 3.13.0 unreleased.
|
||||
- Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0 unreleased.
|
||||
- `JSON_STRICT_NUL_HANDLING` added in version 3.13.0 unreleased to optionally reject a NUL byte in the input instead of treating it as end of input; planned to become the default in version 4.0.0.
|
||||
- Parsing from an `std::istream` scans the characters in its stream buffer in bulk in version 3.13.0 unreleased ([`JSON_DISABLE_STREAM_BULK_SCAN`](https://json.nlohmann.me/api/macros/json_disable_stream_bulk_scan/index.md)).
|
||||
- Parsing from a `FILE*` locks the file once instead of once per character in version 3.13.0 unreleased ([`JSON_DISABLE_UNLOCKED_FILE_IO`](https://json.nlohmann.me/api/macros/json_disable_unlocked_file_io/index.md)).
|
||||
- Ill-formed UTF-16 and UTF-32 input (a lone surrogate, a high surrogate that is not followed by its low surrogate, or a code point above `U+10FFFF`) is rejected in version 3.13.0 unreleased; before that, some such sequences were accepted or ended the input silently.
|
||||
|
||||
Deprecation
|
||||
|
||||
|
||||
+27
-4
@@ -29,9 +29,9 @@ Linear in the size of `init`.
|
||||
This function is only needed to express two edge cases that cannot be realized with the initializer list constructor
|
||||
([`basic_json(initializer_list_t, bool, value_t)`](basic_json.md)). These cases are:
|
||||
|
||||
1. creating an array whose elements are all pairs whose first element is a string -- in this case, the initializer list
|
||||
1. creating an array whose elements are all pairs whose first element is a string — in this case, the initializer list
|
||||
constructor would create an object, taking the first elements as keys
|
||||
2. creating an empty array -- passing the empty initializer list to the initializer list constructor yields an empty
|
||||
2. creating an empty array — passing the empty initializer list to the initializer list constructor yields an empty
|
||||
object
|
||||
|
||||
## Examples
|
||||
@@ -41,13 +41,36 @@ This function is only needed to express two edge cases that cannot be realized w
|
||||
The following code shows an example for the `array` function.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/array.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create JSON arrays
|
||||
json j_no_init_list = json::array();
|
||||
json j_empty_init_list = json::array({});
|
||||
json j_nonempty_init_list = json::array({1, 2, 3, 4});
|
||||
json j_list_of_pairs = json::array({ {"one", 1}, {"two", 2} });
|
||||
|
||||
// serialize the JSON arrays
|
||||
std::cout << j_no_init_list << '\n';
|
||||
std::cout << j_empty_init_list << '\n';
|
||||
std::cout << j_nonempty_init_list << '\n';
|
||||
std::cout << j_list_of_pairs << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/array.output"
|
||||
[]
|
||||
[]
|
||||
[1,2,3,4]
|
||||
[["one",1],["two",2]]
|
||||
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/array/" rel="canonical"><link href=../accept/ rel=prev><link href=../array_t/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>array - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../../css/custom.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsonarray class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> array </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> <divLine truncated
|
||||
</code></pre></div> <p>Creates a <abbr title="JavaScript Object Notation">JSON</abbr> array value from a given initializer list. That is, given a list of values <code>a, b, c</code>, creates the <abbr title="JavaScript Object Notation">JSON</abbr> value <code class=highlight><span class=p>[</span><span class=err>a</span><span class=p>,</span><span class=w> </span><span class=err>b</span><span class=p>,</span><span class=w> </span><span class=err>c</span><span class=p>]</span></code>. If the initializer list is empty, the empty array <code class=highlight><span class=p>[]</span></code> is created.</p> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">¶</a></h2> <dl> <dt><code>init</code> (in)</dt> <dd>initializer list with <abbr title="JavaScript Object Notation">JSON</abbr> values to create an array from (optional)</dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">¶</a></h2> <p><abbr title="JavaScript Object Notation">JSON</abbr> array value</p> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">¶</a></h2> <p>Strong guarantee: if an exception is thrown, there are no changes in the <abbr title="JavaScript Object Notation">JSON</abbr> value.</p> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">¶</a></h2> <p>Linear in the size of <code>init</code>.</p> <h2 id=notes>Notes<a class=headerlink href=#notes title="Permanent link">¶</a></h2> <p>This function is only needed to express two edge cases that cannot be realized with the initializer list constructor (<a href=../basic_json/ ><code>basic_json(initializer_list_t, bool, value_t)</code></a>). These cases are:</p> <ol> <li>creating an array whose elements are all pairs whose first element is a string -- in this case, the initializer list constructor would create an object, taking the first elements as keys</li> <li>creating an empty array -- passing the empty initializer list to the initializer list constructor yields an empty object</li> </ol> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example</summary> <p>The following code shows an example for the <code>array</code> function.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/array/" rel="canonical"><link href=../accept/ rel=prev><link href=../array_t/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>array - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel=stylesheet href=../../../css/custom.css><link rel=stylesheet href=../../../css/brand.css><link rel=stylesheet href=../../../css/fig-sax.css><link rel=stylesheet href=../../../css/fig-jsonview.css><link rel=stylesheet href=../../../css/fig-exceptions.css><link rel=stylesheet href=../../../css/fig-pointer.css><link rel=stylesheet href=../../../css/fig-charts.css><link rel=stylesheet href=../../../css/fig-integration.css><link rel=stylesheet href=../../../css/fig-macros.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsonarray class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> array </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1Line truncated
|
||||
</code></pre></div> <p>Creates a <abbr title="JavaScript Object Notation">JSON</abbr> array value from a given initializer list. That is, given a list of values <code>a, b, c</code>, creates the <abbr title="JavaScript Object Notation">JSON</abbr> value <code class=highlight><span class=p>[</span><span class=err>a</span><span class=p>,</span><span class=w> </span><span class=err>b</span><span class=p>,</span><span class=w> </span><span class=err>c</span><span class=p>]</span></code>. If the initializer list is empty, the empty array <code class=highlight><span class=p>[]</span></code> is created.</p> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">¶</a></h2> <dl> <dt><code>init</code> (in)</dt> <dd>initializer list with <abbr title="JavaScript Object Notation">JSON</abbr> values to create an array from (optional)</dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">¶</a></h2> <p><abbr title="JavaScript Object Notation">JSON</abbr> array value</p> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">¶</a></h2> <p>Strong guarantee: if an exception is thrown, there are no changes in the <abbr title="JavaScript Object Notation">JSON</abbr> value.</p> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">¶</a></h2> <p>Linear in the size of <code>init</code>.</p> <h2 id=notes>Notes<a class=headerlink href=#notes title="Permanent link">¶</a></h2> <p>This function is only needed to express two edge cases that cannot be realized with the initializer list constructor (<a href=../basic_json/ ><code>basic_json(initializer_list_t, bool, value_t)</code></a>). These cases are:</p> <ol> <li>creating an array whose elements are all pairs whose first element is a string — in this case, the initializer list constructor would create an object, taking the first elements as keys</li> <li>creating an empty array — passing the empty initializer list to the initializer list constructor yields an empty object</li> </ol> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example</summary> <p>The following code shows an example for the <code>array</code> function.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -22,4 +22,4 @@
|
||||
<span class=p>[]</span>
|
||||
<span class=p>[</span><span class=mi>1</span><span class=p>,</span><span class=mi>2</span><span class=p>,</span><span class=mi>3</span><span class=p>,</span><span class=mi>4</span><span class=p>]</span>
|
||||
<span class=p>[[</span><span class=s2>"one"</span><span class=p>,</span><span class=mi>1</span><span class=p>],[</span><span class=s2>"two"</span><span class=p>,</span><span class=mi>2</span><span class=p>]]</span>
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../basic_json/ ><code>basic_json(initializer_list_t)</code></a> - create a <abbr title="JavaScript Object Notation">JSON</abbr> value from an initializer list</li> <li><a href=../object/ ><code>object</code></a> - create a <abbr title="JavaScript Object Notation">JSON</abbr> object value from an initializer list</li> <li><a href=../../../features/creating_values/ >Creating <abbr title="JavaScript Object Notation">JSON</abbr> values</a> - the article on creating <abbr title="JavaScript Object Notation">JSON</abbr> values</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 1.0.0.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="July 4, 2026 09:13:25 UTC">July 4, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4C0 465.5 14.3 480 31.9 480H416c17.6 0 32-14.5 32-32.3V64.3c0-17.8-14.4-32.3-32-32.3M135.4 416H69V202.2h66.5V416zM102.2 96a38.5 38.5 0 1 1 0 77 38.5 38.5 0 1 1 0-77m282.1 320h-66.4V312c0-24.8-.5-56.7-34.5-56.7-34.6 0-39.9 27-39.9 54.9VLine truncated
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../basic_json/ ><code>basic_json(initializer_list_t)</code></a> - create a <abbr title="JavaScript Object Notation">JSON</abbr> value from an initializer list</li> <li><a href=../object/ ><code>object</code></a> - create a <abbr title="JavaScript Object Notation">JSON</abbr> object value from an initializer list</li> <li><a href=../../../features/creating_values/ >Creating <abbr title="JavaScript Object Notation">JSON</abbr> values</a> - the article on creating <abbr title="JavaScript Object Notation">JSON</abbr> values</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 1.0.0.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../accept/ class="md-footer__link md-footer__link--prev" aria-label="Previous: accept"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> accept </div> </div> </a> <a href=../array_t/ class="md-footer__link md-footer__link--next" aria-label="Next: array_t"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> array_t </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4Line truncated
|
||||
@@ -26,8 +26,8 @@ Linear in the size of `init`.
|
||||
|
||||
This function is only needed to express two edge cases that cannot be realized with the initializer list constructor ([`basic_json(initializer_list_t, bool, value_t)`](https://json.nlohmann.me/api/basic_json/basic_json/index.md)). These cases are:
|
||||
|
||||
1. creating an array whose elements are all pairs whose first element is a string -- in this case, the initializer list constructor would create an object, taking the first elements as keys
|
||||
1. creating an empty array -- passing the empty initializer list to the initializer list constructor yields an empty object
|
||||
1. creating an array whose elements are all pairs whose first element is a string — in this case, the initializer list constructor would create an object, taking the first elements as keys
|
||||
1. creating an empty array — passing the empty initializer list to the initializer list constructor yields an empty object
|
||||
|
||||
## Examples
|
||||
|
||||
@@ -39,7 +39,7 @@ The following code shows an example for the `array` function.
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
|
||||
@@ -27,7 +27,7 @@ To store objects in C++, a type is defined by the template parameters explained
|
||||
|
||||
### Default type
|
||||
|
||||
With the default values for `ArrayType` (`std::vector`) and `AllocatorType` (`std::allocator`), the default value for
|
||||
With the default values for `ArrayType` (`std::vector`) and `AllocatorType` (`std::allocator`), the default type for
|
||||
`array_t` is:
|
||||
|
||||
```cpp
|
||||
@@ -58,21 +58,34 @@ Arrays are stored as pointers in a `basic_json` type. That is, for any access to
|
||||
The following code shows that `array_t` is by default, a typedef to `#!cpp std::vector<nlohmann::json>`.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/array_t.cpp"
|
||||
#include <iostream>
|
||||
#include <iomanip>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
std::cout << std::boolalpha << std::is_same<std::vector<json>, json::array_t>::value << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/array_t.output"
|
||||
true
|
||||
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [object_t](object_t.md) the type used to store JSON objects
|
||||
- [binary_t](binary_t.md) the type used to store binary values
|
||||
- [is_array](is_array.md) checks whether the JSON value is an array
|
||||
- [max_size](max_size.md) returns the maximum possible number of elements
|
||||
- [`object_t`](object_t.md) - the type used to store JSON objects
|
||||
- [`binary_t`](binary_t.md) - the type used to store binary values
|
||||
- [`is_array`](is_array.md) - checks whether the JSON value is an array
|
||||
- [`max_size`](max_size.md) - returns the maximum possible number of elements
|
||||
- [Types](../../features/types/index.md) - how arrays are stored
|
||||
- [Template Parameter Requirements](../../features/types/template_parameters.md) - requirements on the `ArrayType` template parameter
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/array_t/" rel="canonical"><link href=../array/ rel=prev><link href=../as_base_class/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>array_t - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../../css/custom.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsonarray_t class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> array_t </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> Line truncated
|
||||
</code></pre></div> <p>The type used to store <abbr title="JavaScript Object Notation">JSON</abbr> arrays.</p> <p><a href="https://tools.ietf.org/html/rfc8259"><abbr title="Request for Comments">RFC</abbr> 8259</a> describes <abbr title="JavaScript Object Notation">JSON</abbr> arrays as follows:</p> <blockquote> <p>An array is an ordered sequence of zero or more values.</p> </blockquote> <p>To store objects in C++, a type is defined by the template parameters explained below.</p> <h2 id=template-parameters>Template parameters<a class=headerlink href=#template-parameters title="Permanent link">¶</a></h2> <dl> <dt><code>ArrayType</code></dt> <dd>container type to store arrays. It must be a vector-like container: the library uses <code>operator[]</code>, <code>at()</code>, and <code>resize()</code>, and requires random-access iterators. <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>vector</span></code> and <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>deque</span></code> qualify; <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>list</span></code> does not. See <a href=../../../features/types/template_parameters/#arraytype>Template Parameter Requirements</a> for the full list of requirements.</dd> <dt><code>AllocatorType</code></dt> <dd>the allocator to use for objects (e.g., <code>std::allocator</code>)</dd> </dl> <h2 id=notes>Notes<a class=headerlink href=#notes title="Permanent link">¶</a></h2> <h3 id=default-type>Default type<a class=headerlink href=#default-type title="Permanent link">¶</a></h3> <p>With the default values for <code>ArrayType</code> (<code>std::vector</code>) and <code>AllocatorType</code> (<code>std::allocator</code>), the default value for <code>array_t</code> is:</p> <div class=highlight><pre><span></span><code><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=o><</span>
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/array_t/" rel="canonical"><link href=../array/ rel=prev><link href=../as_base_class/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>array_t - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel=stylesheet href=../../../css/custom.css><link rel=stylesheet href=../../../css/brand.css><link rel=stylesheet href=../../../css/fig-sax.css><link rel=stylesheet href=../../../css/fig-jsonview.css><link rel=stylesheet href=../../../css/fig-exceptions.css><link rel=stylesheet href=../../../css/fig-pointer.css><link rel=stylesheet href=../../../css/fig-charts.css><link rel=stylesheet href=../../../css/fig-integration.css><link rel=stylesheet href=../../../css/fig-macros.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsonarray_t class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> array_t </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0Line truncated
|
||||
</code></pre></div> <p>The type used to store <abbr title="JavaScript Object Notation">JSON</abbr> arrays.</p> <p><a href="https://tools.ietf.org/html/rfc8259"><abbr title="Request for Comments">RFC</abbr> 8259</a> describes <abbr title="JavaScript Object Notation">JSON</abbr> arrays as follows:</p> <blockquote> <p>An array is an ordered sequence of zero or more values.</p> </blockquote> <p>To store objects in C++, a type is defined by the template parameters explained below.</p> <h2 id=template-parameters>Template parameters<a class=headerlink href=#template-parameters title="Permanent link">¶</a></h2> <dl> <dt><code>ArrayType</code></dt> <dd>container type to store arrays. It must be a vector-like container: the library uses <code>operator[]</code>, <code>at()</code>, and <code>resize()</code>, and requires random-access iterators. <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>vector</span></code> and <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>deque</span></code> qualify; <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>list</span></code> does not. See <a href=../../../features/types/template_parameters/#arraytype>Template Parameter Requirements</a> for the full list of requirements.</dd> <dt><code>AllocatorType</code></dt> <dd>the allocator to use for objects (e.g., <code>std::allocator</code>)</dd> </dl> <h2 id=notes>Notes<a class=headerlink href=#notes title="Permanent link">¶</a></h2> <h3 id=default-type>Default type<a class=headerlink href=#default-type title="Permanent link">¶</a></h3> <p>With the default values for <code>ArrayType</code> (<code>std::vector</code>) and <code>AllocatorType</code> (<code>std::allocator</code>), the default type for <code>array_t</code> is:</p> <div class=highlight><pre><span></span><code><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=o><</span>
|
||||
<span class=w> </span><span class=n>basic_json</span><span class=p>,</span><span class=w> </span><span class=c1>// value_type</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>allocator</span><span class=o><</span><span class=n>basic_json</span><span class=o>></span><span class=w> </span><span class=c1>// allocator_type</span>
|
||||
<span class=o>></span>
|
||||
@@ -7,11 +7,11 @@
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><iomanip></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>boolalpha</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>is_same</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=o><</span><span class=n>json</span><span class=o>></span><span class=p>,</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>array_t</span><span class=o>>::</span><span class=n>value</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>endl</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>boolalpha</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>is_same</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=o><</span><span class=n>json</span><span class=o>></span><span class=p>,</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>array_t</span><span class=o>>::</span><span class=n>value</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code><span class=kc>true</span>
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../object_t/ >object_t</a> the type used to store <abbr title="JavaScript Object Notation">JSON</abbr> objects</li> <li><a href=../binary_t/ >binary_t</a> the type used to store binary values</li> <li><a href=../is_array/ >is_array</a> checks whether the <abbr title="JavaScript Object Notation">JSON</abbr> value is an array</li> <li><a href=../max_size/ >max_size</a> returns the maximum possible number of elements</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 1.0.0.</li> <li>Made <code>capacity()</code> optional, so that array types such as <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>deque</span></code> can be used, in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 2, 2026 09:32:15 UTC">October 2, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4C0 465.5 14Line truncated
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../object_t/ ><code>object_t</code></a> - the type used to store <abbr title="JavaScript Object Notation">JSON</abbr> objects</li> <li><a href=../binary_t/ ><code>binary_t</code></a> - the type used to store binary values</li> <li><a href=../is_array/ ><code>is_array</code></a> - checks whether the <abbr title="JavaScript Object Notation">JSON</abbr> value is an array</li> <li><a href=../max_size/ ><code>max_size</code></a> - returns the maximum possible number of elements</li> <li><a href=../../../features/types/ >Types</a> - how arrays are stored</li> <li><a href=../../../features/types/template_parameters/ >Template Parameter Requirements</a> - requirements on the <code>ArrayType</code> template parameter</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 1.0.0.</li> <li>Made <code>capacity()</code> optional, so that array types such as <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>deque</span></code> can be used, in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../array/ class="md-footer__link md-footer__link--prev" aria-label="Previous: array"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> array </div> </div> </a> <a href=../as_base_class/ class="md-footer__link md-footer__link--next" aria-label="Next: as_base_class"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> as_base_class </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.Line truncated
|
||||
@@ -22,7 +22,7 @@ To store objects in C++, a type is defined by the template parameters explained
|
||||
|
||||
### Default type
|
||||
|
||||
With the default values for `ArrayType` (`std::vector`) and `AllocatorType` (`std::allocator`), the default value for `array_t` is:
|
||||
With the default values for `ArrayType` (`std::vector`) and `AllocatorType` (`std::allocator`), the default type for `array_t` is:
|
||||
|
||||
```
|
||||
std::vector<
|
||||
@@ -54,11 +54,11 @@ The following code shows that `array_t` is by default, a typedef to `std::vector
|
||||
#include <iomanip>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
std::cout << std::boolalpha << std::is_same<std::vector<json>, json::array_t>::value << std::endl;
|
||||
std::cout << std::boolalpha << std::is_same<std::vector<json>, json::array_t>::value << '\n';
|
||||
}
|
||||
```
|
||||
|
||||
@@ -70,10 +70,12 @@ true
|
||||
|
||||
## See also
|
||||
|
||||
- [object_t](https://json.nlohmann.me/api/basic_json/object_t/index.md) the type used to store JSON objects
|
||||
- [binary_t](https://json.nlohmann.me/api/basic_json/binary_t/index.md) the type used to store binary values
|
||||
- [is_array](https://json.nlohmann.me/api/basic_json/is_array/index.md) checks whether the JSON value is an array
|
||||
- [max_size](https://json.nlohmann.me/api/basic_json/max_size/index.md) returns the maximum possible number of elements
|
||||
- [`object_t`](https://json.nlohmann.me/api/basic_json/object_t/index.md) - the type used to store JSON objects
|
||||
- [`binary_t`](https://json.nlohmann.me/api/basic_json/binary_t/index.md) - the type used to store binary values
|
||||
- [`is_array`](https://json.nlohmann.me/api/basic_json/is_array/index.md) - checks whether the JSON value is an array
|
||||
- [`max_size`](https://json.nlohmann.me/api/basic_json/max_size/index.md) - returns the maximum possible number of elements
|
||||
- [Types](https://json.nlohmann.me/features/types/index.md) - how arrays are stored
|
||||
- [Template Parameter Requirements](https://json.nlohmann.me/features/types/template_parameters/index.md) - requirements on the `ArrayType` template parameter
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -35,18 +35,50 @@ The function is equivalent to `static_cast<json_base_class_t&>(j)` (or `static_c
|
||||
of `basic_json`.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/as_base_class.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
class base_class_with_hidden_members
|
||||
{
|
||||
public:
|
||||
const char* type_name() const noexcept
|
||||
{
|
||||
return "my_type_name";
|
||||
}
|
||||
|
||||
std::size_t size() const noexcept
|
||||
{
|
||||
return 42;
|
||||
}
|
||||
};
|
||||
|
||||
using json = nlohmann::json::with_base_class_t<base_class_with_hidden_members>;
|
||||
|
||||
int main()
|
||||
{
|
||||
json j = {1, 2, 3};
|
||||
|
||||
// the members of basic_json hide the members of the base class
|
||||
std::cout << j.type_name() << ' ' << j.size() << '\n';
|
||||
|
||||
// access the hidden members of the base class
|
||||
std::cout << j.as_base_class().type_name() << ' ' << j.as_base_class().size() << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/as_base_class.output"
|
||||
array 3
|
||||
my_type_name 42
|
||||
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [json_base_class_t](json_base_class_t.md) - type of the custom base class
|
||||
- [`json_base_class_t`](json_base_class_t.md) - type of the custom base class
|
||||
- [Template Parameter Requirements](../../features/types/template_parameters.md) - requirements on the `CustomBaseClass` template parameter
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/as_base_class/" rel="canonical"><link href=../array_t/ rel=prev><link href=../at/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>as_base_class - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../../css/custom.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsonas_base_class class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> as_base_class </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 Line truncated
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/as_base_class/" rel="canonical"><link href=../array_t/ rel=prev><link href=../at/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>as_base_class - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel=stylesheet href=../../../css/custom.css><link rel=stylesheet href=../../../css/brand.css><link rel=stylesheet href=../../../css/fig-sax.css><link rel=stylesheet href=../../../css/fig-jsonview.css><link rel=stylesheet href=../../../css/fig-exceptions.css><link rel=stylesheet href=../../../css/fig-pointer.css><link rel=stylesheet href=../../../css/fig-charts.css><link rel=stylesheet href=../../../css/fig-integration.css><link rel=stylesheet href=../../../css/fig-macros.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsonas_base_class class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> as_base_class </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.Line truncated
|
||||
<span class=k>const</span><span class=w> </span><span class=n>json_base_class_t</span><span class=o>&</span><span class=w> </span><span class=nf>as_base_class</span><span class=p>()</span><span class=w> </span><span class=k>const</span><span class=w> </span><span class=k>noexcept</span><span class=p>;</span>
|
||||
</code></pre></div> <p>Returns a reference to this object as its custom base class <a href=../json_base_class_t/ ><code>json_base_class_t</code></a>. No copy is made.</p> <p>Since <code>basic_json</code> derives from <code>json_base_class_t</code>, a member of <code>basic_json</code> hides any member of the custom base class with the same name. This function makes such hidden members accessible again.</p> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">¶</a></h2> <p>reference to this object as <a href=../json_base_class_t/ ><code>json_base_class_t</code></a></p> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">¶</a></h2> <p>No-throw guarantee: this function never throws exceptions.</p> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">¶</a></h2> <p>Constant.</p> <h2 id=notes>Notes<a class=headerlink href=#notes title="Permanent link">¶</a></h2> <p>The function is equivalent to <code>static_cast<json_base_class_t&>(j)</code> (or <code>static_cast<const json_base_class_t&>(j)</code>).</p> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example</summary> <p>The example shows how to use <code>as_base_class</code> to access members of the custom base class that are hidden by members of <code>basic_json</code>.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
@@ -17,19 +17,7 @@
|
||||
<span class=w> </span><span class=p>}</span>
|
||||
<span class=p>};</span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>basic_json</span><span class=w> </span><span class=o><</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>map</span><span class=p>,</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=p>,</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>string</span><span class=p>,</span>
|
||||
<span class=w> </span><span class=kt>bool</span><span class=p>,</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=kt>int64_t</span><span class=p>,</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=kt>uint64_t</span><span class=p>,</span>
|
||||
<span class=w> </span><span class=kt>double</span><span class=p>,</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>allocator</span><span class=p>,</span>
|
||||
<span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>adl_serializer</span><span class=p>,</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=kt>uint8_t</span><span class=o>></span><span class=p>,</span>
|
||||
<span class=w> </span><span class=n>base_class_with_hidden_members</span>
|
||||
<span class=w> </span><span class=o>></span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=o>::</span><span class=n>with_base_class_t</span><span class=o><</span><span class=n>base_class_with_hidden_members</span><span class=o>></span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -43,4 +31,4 @@
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code><span class=err>array</span><span class=w> </span><span class=mi>3</span>
|
||||
<span class=err>my_</span><span class=kc>t</span><span class=err>ype_</span><span class=kc>na</span><span class=err>me</span><span class=w> </span><span class=mi>42</span>
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../json_base_class_t/ >json_base_class_t</a> - type of the custom base class</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 4, 2026 10:00:31 UTC">October 4, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4C0 465.5 14.3 480 31.9 480H416c17.6 0 32-14.5 32-32.3V64.3c0-17.8-14.4-32.3-32-32.3M135.4 416H69V202.2h66.5V416zM102.2 96a38.5 38.5 0 1 1 0 77 38.5 38.5 0 1 1 0-77m282.1 320h-66.4V312c0-24.8-.5-56.7-34.5-56.7-34.6 0-39.9 27-39.9 54.9V416h-66.4V202.2h63.7v29.2h.9c8.9-16.8 30.6-34.5 62.9-34.5 67.2 0 79.7 44.3 79.7 101.9z"/></svg> </a> <a href="https://www.xing.com/profile/Niels_Lohmann" target="_blank" rel="noopener" title="www.xing.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 384 512"><!-- Font Awesome Free 7.1.0 by @fontLine truncated
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../json_base_class_t/ ><code>json_base_class_t</code></a> - type of the custom base class</li> <li><a href=../../../features/types/template_parameters/ >Template Parameter Requirements</a> - requirements on the <code>CustomBaseClass</code> template parameter</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../array_t/ class="md-footer__link md-footer__link--prev" aria-label="Previous: array_t"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> array_t </div> </div> </a> <a href=../at/ class="md-footer__link md-footer__link--next" aria-label="Next: at"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> at </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-Line truncated
|
||||
@@ -49,19 +49,7 @@ class base_class_with_hidden_members
|
||||
}
|
||||
};
|
||||
|
||||
using json = nlohmann::basic_json <
|
||||
std::map,
|
||||
std::vector,
|
||||
std::string,
|
||||
bool,
|
||||
std::int64_t,
|
||||
std::uint64_t,
|
||||
double,
|
||||
std::allocator,
|
||||
nlohmann::adl_serializer,
|
||||
std::vector<std::uint8_t>,
|
||||
base_class_with_hidden_members
|
||||
>;
|
||||
using json = nlohmann::json::with_base_class_t<base_class_with_hidden_members>;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -84,7 +72,8 @@ my_type_name 42
|
||||
|
||||
## See also
|
||||
|
||||
- [json_base_class_t](https://json.nlohmann.me/api/basic_json/json_base_class_t/index.md) - type of the custom base class
|
||||
- [`json_base_class_t`](https://json.nlohmann.me/api/basic_json/json_base_class_t/index.md) - type of the custom base class
|
||||
- [Template Parameter Requirements](https://json.nlohmann.me/features/types/template_parameters/index.md) - requirements on the `CustomBaseClass` template parameter
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
+512
-24
@@ -90,7 +90,8 @@ Strong exception safety: if an exception occurs, the original value stays intact
|
||||
1. Constant.
|
||||
2. Logarithmic in the size of the container.
|
||||
3. Logarithmic in the size of the container.
|
||||
4. Logarithmic in the size of the container.
|
||||
4. Linear in the number of reference tokens of `ptr`; for each of them, logarithmic in the size of the object, or
|
||||
constant for an array.
|
||||
|
||||
## Notes
|
||||
|
||||
@@ -114,13 +115,59 @@ Strong exception safety: if an exception occurs, the original value stays intact
|
||||
exceptions that can be thrown.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/at__size_type.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create JSON array
|
||||
json array = {"first", "2nd", "third", "fourth"};
|
||||
|
||||
// output element at index 2 (third element)
|
||||
std::cout << array.at(2) << '\n';
|
||||
|
||||
// change element at index 1 (second element) to "second"
|
||||
array.at(1) = "second";
|
||||
|
||||
// output changed array
|
||||
std::cout << array << '\n';
|
||||
|
||||
// exception type_error.304
|
||||
try
|
||||
{
|
||||
// use at() on a non-array type
|
||||
json str = "I am a string";
|
||||
str.at(0) = "Another string";
|
||||
}
|
||||
catch (const json::type_error& e)
|
||||
{
|
||||
std::cout << e.what() << '\n';
|
||||
}
|
||||
|
||||
// exception out_of_range.401
|
||||
try
|
||||
{
|
||||
// try to write beyond the array limit
|
||||
array.at(5) = "sixth";
|
||||
}
|
||||
catch (const json::out_of_range& e)
|
||||
{
|
||||
std::cout << e.what() << '\n';
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/at__size_type.output"
|
||||
"third"
|
||||
["first","second","third","fourth"]
|
||||
[json.exception.type_error.304] cannot use at() with string
|
||||
[json.exception.out_of_range.401] array index 5 is out of range
|
||||
|
||||
```
|
||||
|
||||
??? example "Example: (1) access specified array element with bounds checking"
|
||||
@@ -129,13 +176,52 @@ Strong exception safety: if an exception occurs, the original value stays intact
|
||||
that can be thrown.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/at__size_type_const.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create JSON array
|
||||
const json array = {"first", "2nd", "third", "fourth"};
|
||||
|
||||
// output element at index 2 (third element)
|
||||
std::cout << array.at(2) << '\n';
|
||||
|
||||
// exception type_error.304
|
||||
try
|
||||
{
|
||||
// use at() on a non-array type
|
||||
const json str = "I am a string";
|
||||
std::cout << str.at(0) << '\n';
|
||||
}
|
||||
catch (const json::type_error& e)
|
||||
{
|
||||
std::cout << e.what() << '\n';
|
||||
}
|
||||
|
||||
// exception out_of_range.401
|
||||
try
|
||||
{
|
||||
// try to read beyond the array limit
|
||||
std::cout << array.at(5) << '\n';
|
||||
}
|
||||
catch (const json::out_of_range& e)
|
||||
{
|
||||
std::cout << e.what() << '\n';
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/at__size_type_const.output"
|
||||
"third"
|
||||
[json.exception.type_error.304] cannot use at() with string
|
||||
[json.exception.out_of_range.401] array index 5 is out of range
|
||||
|
||||
```
|
||||
|
||||
??? example "Example: (2) access specified object element with bounds checking"
|
||||
@@ -144,13 +230,64 @@ Strong exception safety: if an exception occurs, the original value stays intact
|
||||
exceptions that can be thrown.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/at__object_t_key_type.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create JSON object
|
||||
json object =
|
||||
{
|
||||
{"the good", "il buono"},
|
||||
{"the bad", "il cattivo"},
|
||||
{"the ugly", "il brutto"}
|
||||
};
|
||||
|
||||
// output element with key "the ugly"
|
||||
std::cout << object.at("the ugly") << '\n';
|
||||
|
||||
// change element with key "the bad"
|
||||
object.at("the bad") = "il cattivo";
|
||||
|
||||
// output changed array
|
||||
std::cout << object << '\n';
|
||||
|
||||
// exception type_error.304
|
||||
try
|
||||
{
|
||||
// use at() on a non-object type
|
||||
json str = "I am a string";
|
||||
str.at("the good") = "Another string";
|
||||
}
|
||||
catch (const json::type_error& e)
|
||||
{
|
||||
std::cout << e.what() << '\n';
|
||||
}
|
||||
|
||||
// exception out_of_range.401
|
||||
try
|
||||
{
|
||||
// try to write at a nonexisting key
|
||||
object.at("the fast") = "il rapido";
|
||||
}
|
||||
catch (const json::out_of_range& e)
|
||||
{
|
||||
std::cout << e.what() << '\n';
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/at__object_t_key_type.output"
|
||||
"il brutto"
|
||||
{"the bad":"il cattivo","the good":"il buono","the ugly":"il brutto"}
|
||||
[json.exception.type_error.304] cannot use at() with string
|
||||
[json.exception.out_of_range.403] key 'the fast' not found
|
||||
|
||||
```
|
||||
|
||||
??? example "Example: (2) access specified object element with bounds checking"
|
||||
@@ -159,13 +296,57 @@ Strong exception safety: if an exception occurs, the original value stays intact
|
||||
that can be thrown.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/at__object_t_key_type_const.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create JSON object
|
||||
const json object =
|
||||
{
|
||||
{"the good", "il buono"},
|
||||
{"the bad", "il cattivo"},
|
||||
{"the ugly", "il brutto"}
|
||||
};
|
||||
|
||||
// output element with key "the ugly"
|
||||
std::cout << object.at("the ugly") << '\n';
|
||||
|
||||
// exception type_error.304
|
||||
try
|
||||
{
|
||||
// use at() on a non-object type
|
||||
const json str = "I am a string";
|
||||
std::cout << str.at("the good") << '\n';
|
||||
}
|
||||
catch (const json::type_error& e)
|
||||
{
|
||||
std::cout << e.what() << '\n';
|
||||
}
|
||||
|
||||
// exception out_of_range.401
|
||||
try
|
||||
{
|
||||
// try to read from a nonexisting key
|
||||
std::cout << object.at("the fast") << '\n';
|
||||
}
|
||||
catch (const json::out_of_range)
|
||||
{
|
||||
std::cout << "out of range" << '\n';
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/at__object_t_key_type_const.output"
|
||||
"il brutto"
|
||||
[json.exception.type_error.304] cannot use at() with string
|
||||
out of range
|
||||
|
||||
```
|
||||
|
||||
??? example "Example: (3) access specified object element using string_view with bounds checking"
|
||||
@@ -174,13 +355,66 @@ Strong exception safety: if an exception occurs, the original value stays intact
|
||||
exceptions that can be thrown.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/at__keytype.c++17.cpp"
|
||||
#include <iostream>
|
||||
#include <string_view>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using namespace std::string_view_literals;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create JSON object
|
||||
json object =
|
||||
{
|
||||
{"the good", "il buono"},
|
||||
{"the bad", "il cattivo"},
|
||||
{"the ugly", "il brutto"}
|
||||
};
|
||||
|
||||
// output element with key "the ugly" using string_view
|
||||
std::cout << object.at("the ugly"sv) << '\n';
|
||||
|
||||
// change element with key "the bad" using string_view
|
||||
object.at("the bad"sv) = "il cattivo";
|
||||
|
||||
// output changed array
|
||||
std::cout << object << '\n';
|
||||
|
||||
// exception type_error.304
|
||||
try
|
||||
{
|
||||
// use at() with string_view on a non-object type
|
||||
json str = "I am a string";
|
||||
str.at("the good"sv) = "Another string";
|
||||
}
|
||||
catch (const json::type_error& e)
|
||||
{
|
||||
std::cout << e.what() << '\n';
|
||||
}
|
||||
|
||||
// exception out_of_range.401
|
||||
try
|
||||
{
|
||||
// try to write at a nonexisting key using string_view
|
||||
object.at("the fast"sv) = "il rapido";
|
||||
}
|
||||
catch (const json::out_of_range& e)
|
||||
{
|
||||
std::cout << e.what() << '\n';
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/at__keytype.c++17.output"
|
||||
"il brutto"
|
||||
{"the bad":"il cattivo","the good":"il buono","the ugly":"il brutto"}
|
||||
[json.exception.type_error.304] cannot use at() with string
|
||||
[json.exception.out_of_range.403] key 'the fast' not found
|
||||
|
||||
```
|
||||
|
||||
??? example "Example: (3) access specified object element using string_view with bounds checking"
|
||||
@@ -189,13 +423,59 @@ Strong exception safety: if an exception occurs, the original value stays intact
|
||||
that can be thrown.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/at__keytype_const.c++17.cpp"
|
||||
#include <iostream>
|
||||
#include <string_view>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using namespace std::string_view_literals;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create JSON object
|
||||
const json object =
|
||||
{
|
||||
{"the good", "il buono"},
|
||||
{"the bad", "il cattivo"},
|
||||
{"the ugly", "il brutto"}
|
||||
};
|
||||
|
||||
// output element with key "the ugly" using string_view
|
||||
std::cout << object.at("the ugly"sv) << '\n';
|
||||
|
||||
// exception type_error.304
|
||||
try
|
||||
{
|
||||
// use at() with string_view on a non-object type
|
||||
const json str = "I am a string";
|
||||
std::cout << str.at("the good"sv) << '\n';
|
||||
}
|
||||
catch (const json::type_error& e)
|
||||
{
|
||||
std::cout << e.what() << '\n';
|
||||
}
|
||||
|
||||
// exception out_of_range.401
|
||||
try
|
||||
{
|
||||
// try to read from a nonexisting key using string_view
|
||||
std::cout << object.at("the fast"sv) << '\n';
|
||||
}
|
||||
catch (const json::out_of_range& e)
|
||||
{
|
||||
std::cout << "out of range" << '\n';
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/at__keytype_const.c++17.output"
|
||||
"il brutto"
|
||||
[json.exception.type_error.304] cannot use at() with string
|
||||
out of range
|
||||
|
||||
```
|
||||
|
||||
??? example "Example: (4) access specified element via JSON Pointer"
|
||||
@@ -204,13 +484,128 @@ Strong exception safety: if an exception occurs, the original value stays intact
|
||||
exceptions that can be thrown.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/at__json_pointer.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
using namespace nlohmann::literals;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create a JSON value
|
||||
json j =
|
||||
{
|
||||
{"number", 1}, {"string", "foo"}, {"array", {1, 2}}
|
||||
};
|
||||
|
||||
// read-only access
|
||||
|
||||
// output element with JSON pointer "/number"
|
||||
std::cout << j.at("/number"_json_pointer) << '\n';
|
||||
// output element with JSON pointer "/string"
|
||||
std::cout << j.at("/string"_json_pointer) << '\n';
|
||||
// output element with JSON pointer "/array"
|
||||
std::cout << j.at("/array"_json_pointer) << '\n';
|
||||
// output element with JSON pointer "/array/1"
|
||||
std::cout << j.at("/array/1"_json_pointer) << '\n';
|
||||
|
||||
// writing access
|
||||
|
||||
// change the string
|
||||
j.at("/string"_json_pointer) = "bar";
|
||||
// output the changed string
|
||||
std::cout << j["string"] << '\n';
|
||||
|
||||
// change an array element
|
||||
j.at("/array/1"_json_pointer) = 21;
|
||||
// output the changed array
|
||||
std::cout << j["array"] << '\n';
|
||||
|
||||
// out_of_range.106
|
||||
try
|
||||
{
|
||||
// try to use an array index with leading '0'
|
||||
json::reference ref = j.at("/array/01"_json_pointer);
|
||||
}
|
||||
catch (const json::parse_error& e)
|
||||
{
|
||||
std::cout << e.what() << '\n';
|
||||
}
|
||||
|
||||
// out_of_range.109
|
||||
try
|
||||
{
|
||||
// try to use an array index that is not a number
|
||||
json::reference ref = j.at("/array/one"_json_pointer);
|
||||
}
|
||||
catch (const json::parse_error& e)
|
||||
{
|
||||
std::cout << e.what() << '\n';
|
||||
}
|
||||
|
||||
// out_of_range.401
|
||||
try
|
||||
{
|
||||
// try to use an invalid array index
|
||||
json::reference ref = j.at("/array/4"_json_pointer);
|
||||
}
|
||||
catch (const json::out_of_range& e)
|
||||
{
|
||||
std::cout << e.what() << '\n';
|
||||
}
|
||||
|
||||
// out_of_range.402
|
||||
try
|
||||
{
|
||||
// try to use the array index '-'
|
||||
json::reference ref = j.at("/array/-"_json_pointer);
|
||||
}
|
||||
catch (const json::out_of_range& e)
|
||||
{
|
||||
std::cout << e.what() << '\n';
|
||||
}
|
||||
|
||||
// out_of_range.403
|
||||
try
|
||||
{
|
||||
// try to use a JSON pointer to a nonexistent object key
|
||||
json::const_reference ref = j.at("/foo"_json_pointer);
|
||||
}
|
||||
catch (const json::out_of_range& e)
|
||||
{
|
||||
std::cout << e.what() << '\n';
|
||||
}
|
||||
|
||||
// out_of_range.404
|
||||
try
|
||||
{
|
||||
// try to use a JSON pointer that cannot be resolved
|
||||
json::reference ref = j.at("/number/foo"_json_pointer);
|
||||
}
|
||||
catch (const json::out_of_range& e)
|
||||
{
|
||||
std::cout << e.what() << '\n';
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/at__json_pointer.output"
|
||||
1
|
||||
"foo"
|
||||
[1,2]
|
||||
2
|
||||
"bar"
|
||||
[1,21]
|
||||
[json.exception.parse_error.106] parse error: array index '01' must not begin with '0'
|
||||
[json.exception.parse_error.109] parse error: array index 'one' is not a number
|
||||
[json.exception.out_of_range.401] array index 4 is out of range
|
||||
[json.exception.out_of_range.402] array index '-' (2) is out of range
|
||||
[json.exception.out_of_range.403] key 'foo' not found
|
||||
[json.exception.out_of_range.404] unresolved reference token 'foo'
|
||||
|
||||
```
|
||||
|
||||
??? example "Example: (4) access specified element via JSON Pointer"
|
||||
@@ -219,26 +614,119 @@ Strong exception safety: if an exception occurs, the original value stays intact
|
||||
that can be thrown.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/at__json_pointer_const.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
using namespace nlohmann::literals;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create a JSON value
|
||||
const json j =
|
||||
{
|
||||
{"number", 1}, {"string", "foo"}, {"array", {1, 2}}
|
||||
};
|
||||
|
||||
// read-only access
|
||||
|
||||
// output element with JSON pointer "/number"
|
||||
std::cout << j.at("/number"_json_pointer) << '\n';
|
||||
// output element with JSON pointer "/string"
|
||||
std::cout << j.at("/string"_json_pointer) << '\n';
|
||||
// output element with JSON pointer "/array"
|
||||
std::cout << j.at("/array"_json_pointer) << '\n';
|
||||
// output element with JSON pointer "/array/1"
|
||||
std::cout << j.at("/array/1"_json_pointer) << '\n';
|
||||
|
||||
// out_of_range.109
|
||||
try
|
||||
{
|
||||
// try to use an array index that is not a number
|
||||
json::const_reference ref = j.at("/array/one"_json_pointer);
|
||||
}
|
||||
catch (const json::parse_error& e)
|
||||
{
|
||||
std::cout << e.what() << '\n';
|
||||
}
|
||||
|
||||
// out_of_range.401
|
||||
try
|
||||
{
|
||||
// try to use an invalid array index
|
||||
json::const_reference ref = j.at("/array/4"_json_pointer);
|
||||
}
|
||||
catch (const json::out_of_range& e)
|
||||
{
|
||||
std::cout << e.what() << '\n';
|
||||
}
|
||||
|
||||
// out_of_range.402
|
||||
try
|
||||
{
|
||||
// try to use the array index '-'
|
||||
json::const_reference ref = j.at("/array/-"_json_pointer);
|
||||
}
|
||||
catch (const json::out_of_range& e)
|
||||
{
|
||||
std::cout << e.what() << '\n';
|
||||
}
|
||||
|
||||
// out_of_range.403
|
||||
try
|
||||
{
|
||||
// try to use a JSON pointer to a nonexistent object key
|
||||
json::const_reference ref = j.at("/foo"_json_pointer);
|
||||
}
|
||||
catch (const json::out_of_range& e)
|
||||
{
|
||||
std::cout << e.what() << '\n';
|
||||
}
|
||||
|
||||
// out_of_range.404
|
||||
try
|
||||
{
|
||||
// try to use a JSON pointer that cannot be resolved
|
||||
json::const_reference ref = j.at("/number/foo"_json_pointer);
|
||||
}
|
||||
catch (const json::out_of_range& e)
|
||||
{
|
||||
std::cout << e.what() << '\n';
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/at__json_pointer_const.output"
|
||||
1
|
||||
"foo"
|
||||
[1,2]
|
||||
2
|
||||
[json.exception.parse_error.109] parse error: array index 'one' is not a number
|
||||
[json.exception.out_of_range.401] array index 4 is out of range
|
||||
[json.exception.out_of_range.402] array index '-' (2) is out of range
|
||||
[json.exception.out_of_range.403] key 'foo' not found
|
||||
[json.exception.out_of_range.404] unresolved reference token 'foo'
|
||||
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- documentation on [checked access](../../features/element_access/checked_access.md)
|
||||
- [`operator[]`](operator%5B%5D.md) for unchecked access by reference
|
||||
- [`value`](value.md) for access with default value
|
||||
- [Checked access](../../features/element_access/checked_access.md) - element access with range checking
|
||||
- [`operator[]`](operator%5B%5D.md) - unchecked access by reference
|
||||
- [`value`](value.md) - access with default value
|
||||
- [`basic_json_view::at`](../basic_json_view/at.md) - the same access on a zero-copy view
|
||||
- [Element Access](../../features/element_access/index.md) - overview of all ways to access elements
|
||||
- [JSON Pointer](../../features/json_pointer.md) - access nested values with a pointer
|
||||
|
||||
## Version history
|
||||
|
||||
1. Added in version 1.0.0.
|
||||
2. Added in version 1.0.0.
|
||||
3. Added in version 3.11.0. Fixed in version 3.13.0 to consistently accept `std::string_view`-convertible keys, as
|
||||
already supported by [`operator[]`](operator[].md), [`value`](value.md), [`find`](find.md), and other lookup
|
||||
functions.
|
||||
4. Added in version 2.0.0.
|
||||
3. Added in version 3.11.0. Support for keys convertible to `std::string_view` added in version 3.13.0, consistently
|
||||
across the lookup functions.
|
||||
4. Added in version 2.0.0. Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) instead of
|
||||
[`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) for a one-character array index that is not
|
||||
a digit (e.g., `/x`) in version 3.13.0, as it already did for longer ones.
|
||||
@@ -1,4 +1,4 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/at/" rel="canonical"><link href=../as_base_class/ rel=prev><link href=../back/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>at - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../../css/custom.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsonat class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> at </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> <div class=mLine truncated
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/at/" rel="canonical"><link href=../as_base_class/ rel=prev><link href=../back/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>at - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel=stylesheet href=../../../css/custom.css><link rel=stylesheet href=../../../css/brand.css><link rel=stylesheet href=../../../css/fig-sax.css><link rel=stylesheet href=../../../css/fig-jsonview.css><link rel=stylesheet href=../../../css/fig-exceptions.css><link rel=stylesheet href=../../../css/fig-pointer.css><link rel=stylesheet href=../../../css/fig-charts.css><link rel=stylesheet href=../../../css/fig-integration.css><link rel=stylesheet href=../../../css/fig-macros.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsonat class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> at </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 Line truncated
|
||||
<span class=n>reference</span><span class=w> </span><span class=nf>at</span><span class=p>(</span><span class=n>size_type</span><span class=w> </span><span class=n>idx</span><span class=p>);</span>
|
||||
<span class=n>const_reference</span><span class=w> </span><span class=nf>at</span><span class=p>(</span><span class=n>size_type</span><span class=w> </span><span class=n>idx</span><span class=p>)</span><span class=w> </span><span class=k>const</span><span class=p>;</span>
|
||||
|
||||
@@ -15,10 +15,10 @@
|
||||
<span class=c1>// (4)</span>
|
||||
<span class=n>reference</span><span class=w> </span><span class=nf>at</span><span class=p>(</span><span class=k>const</span><span class=w> </span><span class=n>json_pointer</span><span class=o>&</span><span class=w> </span><span class=n>ptr</span><span class=p>);</span>
|
||||
<span class=n>const_reference</span><span class=w> </span><span class=nf>at</span><span class=p>(</span><span class=k>const</span><span class=w> </span><span class=n>json_pointer</span><span class=o>&</span><span class=w> </span><span class=n>ptr</span><span class=p>)</span><span class=w> </span><span class=k>const</span><span class=p>;</span>
|
||||
</code></pre></div> <ol> <li>Returns a reference to the array element at specified location <code>idx</code>, with bounds checking.</li> <li>Returns a reference to the object element with specified key <code>key</code>, with bounds checking.</li> <li>See 2. This overload is only available if <code>KeyType</code> is comparable with <code class=highlight><span class=k>typename</span><span class=w> </span><span class=nc>object_t</span><span class=o>::</span><span class=n>key_type</span></code> and <code class=highlight><span class=k>typename</span><span class=w> </span><span class=nc>object_comparator_t</span><span class=o>::</span><span class=n>is_transparent</span></code> denotes a type.</li> <li>Returns a reference to the element at specified <abbr title="JavaScript Object Notation">JSON</abbr> pointer <code>ptr</code>, with bounds checking.</li> </ol> <h2 id=template-parameters>Template parameters<a class=headerlink href=#template-parameters title="Permanent link">¶</a></h2> <dl> <dt><code>KeyType</code></dt> <dd>A type for an object key other than <a href=../../json_pointer/ ><code>json_pointer</code></a> that is comparable with <a href=../string_t/ ><code>string_t</code></a> using <a href=../object_comparator_t/ ><code>object_comparator_t</code></a>. This can also be a string view (C++17).</dd> </dl> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">¶</a></h2> <dl> <dt><code>idx</code> (in)</dt> <dd>index of the element to access</dd> <dt><code>key</code> (in)</dt> <dd>object key of the elements to access</dd> <dt><code>ptr</code> (in)</dt> <dd><abbr title="JavaScript Object Notation">JSON</abbr> pointer to the desired element</dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">¶</a></h2> <ol> <li>reference to the element at index <code>idx</code></li> <li>reference to the element at key <code>key</code></li> <li>reference to the element at key <code>key</code></li> <li>reference to the element pointed to by <code>ptr</code></li> </ol> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">¶</a></h2> <p>Strong exception safety: if an exception occurs, the original value stays intact.</p> <h2 id=exceptions>Exceptions<a class=headerlink href=#exceptions title="Permanent link">¶</a></h2> <ol> <li>The function can throw the following exceptions:<ul> <li>Throws <a href=../../../home/exceptions/#jsonexceptiontype_error304><code>type_error.304</code></a> if the <abbr title="JavaScript Object Notation">JSON</abbr> value is not an array; in this case, calling <code>at</code> with an index makes no sense. See the example below.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range401><code>out_of_range.401</code></a> if the index <code>idx</code> is out of range of the array; that is, <code>idx >= size()</code>. See the example below.</li> </ul> </li> <li>The function can throw the following exceptions:<ul> <li>Throws <a href=../../../home/exceptions/#jsonexceptiontype_error304><code>type_error.304</code></a> if the <abbr title="JavaScript Object Notation">JSON</abbr> value is not an object; in this case, calling <code>at</code> with a key makes no sense. See the example below.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range403><code>out_of_range.403</code></a> if the key <code>key</code> is not stored in the object; that is, <code>find(key) == end()</code>. See the example below.</li> </ul> </li> <li>See 2.</li> <li>The function can throw the following exceptions:<ul> <li>Throws <a href=../../../home/exceptions/#jsonexceptionparse_error106><code>parse_error.106</code></a> if an array index in the passed <abbr title="JavaScript Object Notation">JSON</abbr> pointer <code>ptr</code> begins with '0'. See the example below.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionparse_error109><code>parse_error.109</code></a> if an array index in the passed <abbr title="JavaScript Object Notation">JSON</abbr> pointer <code>ptr</code> is not a number. See the example below.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range401><code>out_of_range.401</code></a> if an array index in the passed <abbr title="JavaScript Object Notation">JSON</abbr> pointer <code>ptr</code> is out of range. See the example below.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range402><code>out_of_range.402</code></a> if the array index '-' is used in the passed <abbr title="JavaScript Object Notation">JSON</abbr> pointer <code>ptr</code>. As <code>at</code> provides checked access (and no elements are implicitly inserted), the index '-' is always invalid. See the example below.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range403><code>out_of_range.403</code></a> if the <abbr title="JavaScript Object Notation">JSON</abbr> pointer describes a keLine truncated
|
||||
</code></pre></div> <ol> <li>Returns a reference to the array element at specified location <code>idx</code>, with bounds checking.</li> <li>Returns a reference to the object element with specified key <code>key</code>, with bounds checking.</li> <li>See 2. This overload is only available if <code>KeyType</code> is comparable with <code class=highlight><span class=k>typename</span><span class=w> </span><span class=nc>object_t</span><span class=o>::</span><span class=n>key_type</span></code> and <code class=highlight><span class=k>typename</span><span class=w> </span><span class=nc>object_comparator_t</span><span class=o>::</span><span class=n>is_transparent</span></code> denotes a type.</li> <li>Returns a reference to the element at specified <abbr title="JavaScript Object Notation">JSON</abbr> pointer <code>ptr</code>, with bounds checking.</li> </ol> <h2 id=template-parameters>Template parameters<a class=headerlink href=#template-parameters title="Permanent link">¶</a></h2> <dl> <dt><code>KeyType</code></dt> <dd>A type for an object key other than <a href=../../json_pointer/ ><code>json_pointer</code></a> that is comparable with <a href=../string_t/ ><code>string_t</code></a> using <a href=../object_comparator_t/ ><code>object_comparator_t</code></a>. This can also be a string view (C++17).</dd> </dl> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">¶</a></h2> <dl> <dt><code>idx</code> (in)</dt> <dd>index of the element to access</dd> <dt><code>key</code> (in)</dt> <dd>object key of the elements to access</dd> <dt><code>ptr</code> (in)</dt> <dd><abbr title="JavaScript Object Notation">JSON</abbr> pointer to the desired element</dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">¶</a></h2> <ol> <li>reference to the element at index <code>idx</code></li> <li>reference to the element at key <code>key</code></li> <li>reference to the element at key <code>key</code></li> <li>reference to the element pointed to by <code>ptr</code></li> </ol> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">¶</a></h2> <p>Strong exception safety: if an exception occurs, the original value stays intact.</p> <h2 id=exceptions>Exceptions<a class=headerlink href=#exceptions title="Permanent link">¶</a></h2> <ol> <li>The function can throw the following exceptions:<ul> <li>Throws <a href=../../../home/exceptions/#jsonexceptiontype_error304><code>type_error.304</code></a> if the <abbr title="JavaScript Object Notation">JSON</abbr> value is not an array; in this case, calling <code>at</code> with an index makes no sense. See the example below.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range401><code>out_of_range.401</code></a> if the index <code>idx</code> is out of range of the array; that is, <code>idx >= size()</code>. See the example below.</li> </ul> </li> <li>The function can throw the following exceptions:<ul> <li>Throws <a href=../../../home/exceptions/#jsonexceptiontype_error304><code>type_error.304</code></a> if the <abbr title="JavaScript Object Notation">JSON</abbr> value is not an object; in this case, calling <code>at</code> with a key makes no sense. See the example below.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range403><code>out_of_range.403</code></a> if the key <code>key</code> is not stored in the object; that is, <code>find(key) == end()</code>. See the example below.</li> </ul> </li> <li>See 2.</li> <li>The function can throw the following exceptions:<ul> <li>Throws <a href=../../../home/exceptions/#jsonexceptionparse_error106><code>parse_error.106</code></a> if an array index in the passed <abbr title="JavaScript Object Notation">JSON</abbr> pointer <code>ptr</code> begins with '0'. See the example below.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionparse_error109><code>parse_error.109</code></a> if an array index in the passed <abbr title="JavaScript Object Notation">JSON</abbr> pointer <code>ptr</code> is not a number. See the example below.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range401><code>out_of_range.401</code></a> if an array index in the passed <abbr title="JavaScript Object Notation">JSON</abbr> pointer <code>ptr</code> is out of range. See the example below.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range402><code>out_of_range.402</code></a> if the array index '-' is used in the passed <abbr title="JavaScript Object Notation">JSON</abbr> pointer <code>ptr</code>. As <code>at</code> provides checked access (and no elements are implicitly inserted), the index '-' is always invalid. See the example below.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range403><code>out_of_range.403</code></a> if the <abbr title="JavaScript Object Notation">JSON</abbr> pointer describes a keLine truncated
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -64,7 +64,7 @@
|
||||
</code></pre></div> </details> <details class=example> <summary>Example: (1) access specified array element with bounds checking</summary> <p>The example below shows how array elements can be read using <code>at()</code>. It also demonstrates the different exceptions that can be thrown.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -103,7 +103,7 @@
|
||||
</code></pre></div> </details> <details class=example> <summary>Example: (2) access specified object element with bounds checking</summary> <p>The example below shows how object elements can be read and written using <code>at()</code>. It also demonstrates the different exceptions that can be thrown.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -154,7 +154,7 @@
|
||||
</code></pre></div> </details> <details class=example> <summary>Example: (2) access specified object element with bounds checking</summary> <p>The example below shows how object elements can be read using <code>at()</code>. It also demonstrates the different exceptions that can be thrown.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -200,7 +200,7 @@
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=k>namespace</span><span class=w> </span><span class=nn>std</span><span class=o>::</span><span class=nn>string_view_literals</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -253,7 +253,7 @@
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=k>namespace</span><span class=w> </span><span class=nn>std</span><span class=o>::</span><span class=nn>string_view_literals</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -297,7 +297,7 @@
|
||||
</code></pre></div> </details> <details class=example> <summary>Example: (4) access specified element via <abbr title="JavaScript Object Notation">JSON</abbr> Pointer</summary> <p>The example below shows how object elements can be read and written using <code>at()</code>. It also demonstrates the different exceptions that can be thrown.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=k>namespace</span><span class=w> </span><span class=nn>nlohmann</span><span class=o>::</span><span class=nn>literals</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
@@ -412,7 +412,7 @@
|
||||
</code></pre></div> </details> <details class=example> <summary>Example: (4) access specified element via <abbr title="JavaScript Object Notation">JSON</abbr> Pointer</summary> <p>The example below shows how object elements can be read using <code>at()</code>. It also demonstrates the different exceptions that can be thrown.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=k>namespace</span><span class=w> </span><span class=nn>nlohmann</span><span class=o>::</span><span class=nn>literals</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
@@ -498,4 +498,4 @@
|
||||
<span class=p>[</span><span class=err>jso</span><span class=kc>n</span><span class=err>.excep</span><span class=kc>t</span><span class=err>io</span><span class=kc>n</span><span class=err>.ou</span><span class=kc>t</span><span class=err>_o</span><span class=kc>f</span><span class=err>_ra</span><span class=kc>n</span><span class=err>ge.</span><span class=mi>402</span><span class=p>]</span><span class=w> </span><span class=err>array</span><span class=w> </span><span class=err>i</span><span class=kc>n</span><span class=err>dex</span><span class=w> </span><span class=err>'</span><span class=mi>-</span><span class=err>'</span><span class=w> </span><span class=err>(</span><span class=mi>2</span><span class=err>)</span><span class=w> </span><span class=err>is</span><span class=w> </span><span class=err>ou</span><span class=kc>t</span><span class=w> </span><span class=err>o</span><span class=kc>f</span><span class=w> </span><span class=err>ra</span><span class=kc>n</span><span class=err>ge</span>
|
||||
<span class=p>[</span><span class=err>jso</span><span class=kc>n</span><span class=err>.excep</span><span class=kc>t</span><span class=err>io</span><span class=kc>n</span><span class=err>.ou</span><span class=kc>t</span><span class=err>_o</span><span class=kc>f</span><span class=err>_ra</span><span class=kc>n</span><span class=err>ge.</span><span class=mi>403</span><span class=p>]</span><span class=w> </span><span class=err>key</span><span class=w> </span><span class=err>'</span><span class=kc>f</span><span class=err>oo'</span><span class=w> </span><span class=kc>n</span><span class=err>o</span><span class=kc>t</span><span class=w> </span><span class=kc>f</span><span class=err>ou</span><span class=kc>n</span><span class=err>d</span>
|
||||
<span class=p>[</span><span class=err>jso</span><span class=kc>n</span><span class=err>.excep</span><span class=kc>t</span><span class=err>io</span><span class=kc>n</span><span class=err>.ou</span><span class=kc>t</span><span class=err>_o</span><span class=kc>f</span><span class=err>_ra</span><span class=kc>n</span><span class=err>ge.</span><span class=mi>404</span><span class=p>]</span><span class=w> </span><span class=err>u</span><span class=kc>nres</span><span class=err>olved</span><span class=w> </span><span class=err>re</span><span class=kc>feren</span><span class=err>ce</span><span class=w> </span><span class=kc>t</span><span class=err>oke</span><span class=kc>n</span><span class=w> </span><span class=err>'</span><span class=kc>f</span><span class=err>oo'</span>
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li>documentation on <a href=../../../features/element_access/checked_access/ >checked access</a></li> <li><a href=../operator%5B%5D/ ><code>operator[]</code></a> for unchecked access by reference</li> <li><a href=../value/ ><code>value</code></a> for access with default value</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ol> <li>Added in version 1.0.0.</li> <li>Added in version 1.0.0.</li> <li>Added in version 3.11.0. Fixed in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span> to consistently accept <code>std::string_view</code>-convertible keys, as already supported by <a href=../operator%5B%5D/ ><code>operator[]</code></a>, <a href=../value/ ><code>value</code></a>, <a href=../find/ ><code>find</code></a>, and other lookup functions.</li> <li>Added in version 2.0.0.</li> </ol> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 4, 2026 09:46:32 UTC">October 4, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C14.3 32 0 46.Line truncated
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../../../features/element_access/checked_access/ >Checked access</a> - element access with range checking</li> <li><a href=../operator%5B%5D/ ><code>operator[]</code></a> - unchecked access by reference</li> <li><a href=../value/ ><code>value</code></a> - access with default value</li> <li><a href=../../basic_json_view/at/ ><code>basic_json_view::at</code></a> - the same access on a zero-copy view</li> <li><a href=../../../features/element_access/ >Element Access</a> - overview of all ways to access elements</li> <li><a href=../../../features/json_pointer/ ><abbr title="JavaScript Object Notation">JSON</abbr> Pointer</a> - access nested values with a pointer</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ol> <li>Added in version 1.0.0.</li> <li>Added in version 1.0.0.</li> <li>Added in version 3.11.0. Support for keys convertible to <code>std::string_view</code> added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>, consistently across the lookup functions.</li> <li>Added in version 2.0.0. Throws <a href=../../../home/exceptions/#jsonexceptionparse_error109><code>parse_error.109</code></a> instead of <a href=../../../home/exceptions/#jsonexceptionout_of_range404><code>out_of_range.404</code></a> for a one-character array index that is not a digit (e.g., <code>/x</code>) in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>, as it already did for longer ones.</li> </ol> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 16:15:55 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../as_base_class/ class="md-footer__link md-footer__link--prev" aria-label="Previous: as_base_class"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> as_base_class </div> </div> </a> <a href=../back/ class="md-footer__link md-footer__link--next" aria-label="Next: back"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> back </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2sLine truncated
|
||||
+17
-14
@@ -71,7 +71,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
|
||||
1. Constant.
|
||||
1. Logarithmic in the size of the container.
|
||||
1. Logarithmic in the size of the container.
|
||||
1. Logarithmic in the size of the container.
|
||||
1. Linear in the number of reference tokens of `ptr`; for each of them, logarithmic in the size of the object, or constant for an array.
|
||||
|
||||
## Notes
|
||||
|
||||
@@ -93,7 +93,7 @@ The example below shows how array elements can be read and written using `at()`.
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -151,7 +151,7 @@ The example below shows how array elements can be read using `at()`. It also dem
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -202,7 +202,7 @@ The example below shows how object elements can be read and written using `at()`
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -265,7 +265,7 @@ The example below shows how object elements can be read using `at()`. It also de
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -323,7 +323,7 @@ The example below shows how object elements can be read and written using `at()`
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using namespace std::string_view_literals;
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -388,7 +388,7 @@ The example below shows how object elements can be read using `at()`. It also de
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using namespace std::string_view_literals;
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -444,7 +444,7 @@ The example below shows how object elements can be read and written using `at()`
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
using namespace nlohmann::literals;
|
||||
|
||||
int main()
|
||||
@@ -571,7 +571,7 @@ The example below shows how object elements can be read using `at()`. It also de
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
using namespace nlohmann::literals;
|
||||
|
||||
int main()
|
||||
@@ -666,13 +666,16 @@ Output:
|
||||
|
||||
## See also
|
||||
|
||||
- documentation on [checked access](https://json.nlohmann.me/features/element_access/checked_access/index.md)
|
||||
- [`operator[]`](https://json.nlohmann.me/api/basic_json/operator%5B%5D/index.md) for unchecked access by reference
|
||||
- [`value`](https://json.nlohmann.me/api/basic_json/value/index.md) for access with default value
|
||||
- [Checked access](https://json.nlohmann.me/features/element_access/checked_access/index.md) - element access with range checking
|
||||
- [`operator[]`](https://json.nlohmann.me/api/basic_json/operator%5B%5D/index.md) - unchecked access by reference
|
||||
- [`value`](https://json.nlohmann.me/api/basic_json/value/index.md) - access with default value
|
||||
- [`basic_json_view::at`](https://json.nlohmann.me/api/basic_json_view/at/index.md) - the same access on a zero-copy view
|
||||
- [Element Access](https://json.nlohmann.me/features/element_access/index.md) - overview of all ways to access elements
|
||||
- [JSON Pointer](https://json.nlohmann.me/features/json_pointer/index.md) - access nested values with a pointer
|
||||
|
||||
## Version history
|
||||
|
||||
1. Added in version 1.0.0.
|
||||
1. Added in version 1.0.0.
|
||||
1. Added in version 3.11.0. Fixed in version 3.13.0 unreleased to consistently accept `std::string_view`-convertible keys, as already supported by [`operator[]`](https://json.nlohmann.me/api/basic_json/operator%5B%5D/index.md), [`value`](https://json.nlohmann.me/api/basic_json/value/index.md), [`find`](https://json.nlohmann.me/api/basic_json/find/index.md), and other lookup functions.
|
||||
1. Added in version 2.0.0.
|
||||
1. Added in version 3.11.0. Support for keys convertible to `std::string_view` added in version 3.13.0 unreleased, consistently across the lookup functions.
|
||||
1. Added in version 2.0.0. Throws [`parse_error.109`](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error109) instead of [`out_of_range.404`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range404) for a one-character array index that is not a digit (e.g., `/x`) in version 3.13.0 unreleased, as it already did for longer ones.
|
||||
+51
-4
@@ -46,20 +46,67 @@ Constant.
|
||||
The following code shows an example for `back()`.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/back.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create JSON values
|
||||
json j_boolean = true;
|
||||
json j_number_integer = 17;
|
||||
json j_number_float = 23.42;
|
||||
json j_object = {{"one", 1}, {"two", 2}};
|
||||
json j_object_empty(json::value_t::object);
|
||||
json j_array = {1, 2, 4, 8, 16};
|
||||
json j_array_empty(json::value_t::array);
|
||||
json j_string = "Hello, world";
|
||||
|
||||
// call back()
|
||||
std::cout << j_boolean.back() << '\n';
|
||||
std::cout << j_number_integer.back() << '\n';
|
||||
std::cout << j_number_float.back() << '\n';
|
||||
std::cout << j_object.back() << '\n';
|
||||
//std::cout << j_object_empty.back() << '\n'; // undefined behavior
|
||||
std::cout << j_array.back() << '\n';
|
||||
//std::cout << j_array_empty.back() << '\n'; // undefined behavior
|
||||
std::cout << j_string.back() << '\n';
|
||||
|
||||
// back() called on a null value
|
||||
try
|
||||
{
|
||||
json j_null;
|
||||
j_null.back();
|
||||
}
|
||||
catch (const json::invalid_iterator& e)
|
||||
{
|
||||
std::cout << e.what() << '\n';
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/back.output"
|
||||
true
|
||||
17
|
||||
23.42
|
||||
2
|
||||
16
|
||||
"Hello, world"
|
||||
[json.exception.invalid_iterator.214] cannot get value
|
||||
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [front](front.md) to access the first element
|
||||
- [`front`](front.md) - to access the first element
|
||||
- [`basic_json_view::back`](../basic_json_view/back.md) - the same access on a zero-copy view
|
||||
- [Element Access](../../features/element_access/index.md) - overview of all ways to access elements
|
||||
|
||||
## Version history
|
||||
|
||||
- Added in version 1.0.0.
|
||||
- Adjusted code to return reference to binary values in version 3.8.0.
|
||||
- Binary values are supported since version 3.8.0.
|
||||
@@ -1,4 +1,4 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/back/" rel="canonical"><link href=../at/ rel=prev><link href=../begin/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>back - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../../css/custom.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsonback class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> back </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> <div class=md-Line truncated
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/back/" rel="canonical"><link href=../at/ rel=prev><link href=../begin/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>back - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel=stylesheet href=../../../css/custom.css><link rel=stylesheet href=../../../css/brand.css><link rel=stylesheet href=../../../css/fig-sax.css><link rel=stylesheet href=../../../css/fig-jsonview.css><link rel=stylesheet href=../../../css/fig-exceptions.css><link rel=stylesheet href=../../../css/fig-pointer.css><link rel=stylesheet href=../../../css/fig-charts.css><link rel=stylesheet href=../../../css/fig-integration.css><link rel=stylesheet href=../../../css/fig-macros.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsonback class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> back </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.Line truncated
|
||||
|
||||
<span class=n>const_reference</span><span class=w> </span><span class=nf>back</span><span class=p>()</span><span class=w> </span><span class=k>const</span><span class=p>;</span>
|
||||
</code></pre></div> <p>Returns a reference to the last element in the container. For a <abbr title="JavaScript Object Notation">JSON</abbr> container <code>c</code>, the expression <code>c.back()</code> is equivalent to</p> <div class=highlight><pre><span></span><code><span class=k>auto</span><span class=w> </span><span class=n>tmp</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>c</span><span class=p>.</span><span class=n>end</span><span class=p>();</span>
|
||||
@@ -7,7 +7,7 @@
|
||||
</code></pre></div> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">¶</a></h2> <p>In the case of a structured type (array or object), a reference to the last element is returned. In the case of number, string, boolean, or binary values, a reference to the value is returned.</p> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">¶</a></h2> <p>Strong guarantee: if an exception is thrown, there are no changes in the <abbr title="JavaScript Object Notation">JSON</abbr> value.</p> <h2 id=exceptions>Exceptions<a class=headerlink href=#exceptions title="Permanent link">¶</a></h2> <p>If the <abbr title="JavaScript Object Notation">JSON</abbr> value is <code class=highlight><span class=kc>null</span></code>, exception <a href=../../../home/exceptions/#jsonexceptioninvalid_iterator214><code>invalid_iterator.214</code></a> is thrown.</p> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">¶</a></h2> <p>Constant.</p> <h2 id=notes>Notes<a class=headerlink href=#notes title="Permanent link">¶</a></h2> <div class="admonition info"> <p class=admonition-title>Precondition</p> <p>The array or object must not be empty. Calling <code>back</code> on an empty array or object yields undefined behavior.</p> </div> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example</summary> <p>The following code shows an example for <code>back()</code>.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -49,4 +49,4 @@
|
||||
<span class=mi>16</span>
|
||||
<span class=s2>"Hello, world"</span>
|
||||
<span class=p>[</span><span class=err>jso</span><span class=kc>n</span><span class=err>.excep</span><span class=kc>t</span><span class=err>io</span><span class=kc>n</span><span class=err>.i</span><span class=kc>n</span><span class=err>valid_i</span><span class=kc>terat</span><span class=err>or.</span><span class=mi>214</span><span class=p>]</span><span class=w> </span><span class=err>ca</span><span class=kc>nn</span><span class=err>o</span><span class=kc>t</span><span class=w> </span><span class=err>ge</span><span class=kc>t</span><span class=w> </span><span class=err>value</span>
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../front/ >front</a> to access the first element</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 1.0.0.</li> <li>Adjusted code to return reference to binary values in version 3.8.0.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="April 5, 2025 16:54:35 UTC">April 5, 2025</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4C0 465.5 14.3 480 31.9 480H416c17.6 0 32-14.5 32-32.3V64.3c0-17.8-14.4-32.3-32-32.3M135.4 416H69V202.2h66.5V416zM102.2 96a38.5 38.5 0 1 1 0 77 38.5 38.5 0 1 1 0-77m282.1 320h-66.4V312c0-24.8-.5-56.7-34.5-56.7-34.6 0-39.9 27-39.9 54.9V416h-66.4V202.2h63.7v29.2h.9c8.9-16.8 30.6-34.5 62.9-34.5 67.2 0 79.7 44.3 79.7 101.9z"/></svg> </a> <a href="https://www.xing.com/profile/Niels_Lohmann" target="_blank" rel="noopener" title="www.xing.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 384 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/lLine truncated
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../front/ ><code>front</code></a> - to access the first element</li> <li><a href=../../basic_json_view/back/ ><code>basic_json_view::back</code></a> - the same access on a zero-copy view</li> <li><a href=../../../features/element_access/ >Element Access</a> - overview of all ways to access elements</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 1.0.0.</li> <li>Binary values are supported since version 3.8.0.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../at/ class="md-footer__link md-footer__link--prev" aria-label="Previous: at"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> at </div> </div> </a> <a href=../begin/ class="md-footer__link md-footer__link--next" aria-label="Next: begin"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> begin </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.Line truncated
|
||||
@@ -46,7 +46,7 @@ The following code shows an example for `back()`.
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -97,9 +97,11 @@ true
|
||||
|
||||
## See also
|
||||
|
||||
- [front](https://json.nlohmann.me/api/basic_json/front/index.md) to access the first element
|
||||
- [`front`](https://json.nlohmann.me/api/basic_json/front/index.md) - to access the first element
|
||||
- [`basic_json_view::back`](https://json.nlohmann.me/api/basic_json_view/back/index.md) - the same access on a zero-copy view
|
||||
- [Element Access](https://json.nlohmann.me/features/element_access/index.md) - overview of all ways to access elements
|
||||
|
||||
## Version history
|
||||
|
||||
- Added in version 1.0.0.
|
||||
- Adjusted code to return reference to binary values in version 3.8.0.
|
||||
- Binary values are supported since version 3.8.0.
|
||||
+501
-38
@@ -52,7 +52,7 @@ basic_json(basic_json&& other) noexcept;
|
||||
The postcondition of this constructor can be restored by calling [`clear()`](clear.md).
|
||||
|
||||
2. Create a `#!json null` JSON value. It either takes a null pointer as parameter (explicitly creating `#!json null`)
|
||||
or no parameter (implicitly creating `#!json null`). The passed null pointer itself is not read -- it is only used to
|
||||
or no parameter (implicitly creating `#!json null`). The passed null pointer itself is not read — it is only used to
|
||||
choose the right constructor.
|
||||
|
||||
3. This is a "catch all" constructor for all compatible JSON types; that is, types for which a `to_json()` method
|
||||
@@ -68,6 +68,14 @@ basic_json(basic_json&& other) noexcept;
|
||||
`std::unordered_map`, `std::multimap`, and `std::unordered_multimap` with a `key_type` compatible to `string_t`
|
||||
and a `value_type` from which a `basic_json` value can be constructed.
|
||||
- **strings**: `string_t`, string literals, and all compatible string containers can be used.
|
||||
|
||||
!!! note "Rvalue containers are moved from"
|
||||
|
||||
If `val` is an rvalue of a compatible array-like or object-like container other than `array_t`/`object_t`
|
||||
(e.g., `json j = std::move(vec);` or `json j(std::vector<std::string>{...});`), the elements are moved into
|
||||
the JSON value instead of copied. Afterwards, the elements of the source container are in a valid but
|
||||
unspecified state (**moved-from**). Keys of associative containers are `const` and therefore still copied.
|
||||
Lvalues and `const` rvalues are copied, and the source is left unchanged.
|
||||
- **numbers**: [`number_integer_t`](number_integer_t.md), [`number_unsigned_t`](number_unsigned_t.md),
|
||||
[`number_float_t`](number_float_t.md), and all convertible number types such as `int`, `size_t`, `int64_t`, `float`
|
||||
or `double` can be used.
|
||||
@@ -105,19 +113,22 @@ basic_json(basic_json&& other) noexcept;
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A(["initializer_list init"]) --> B{"empty, or every element is a 2-element<br/>array whose first element is a string?"}
|
||||
B -->|"yes"| C{"type_deduction"}
|
||||
B -->|"no"| D{"type_deduction"}
|
||||
A(["initializer_list init"]) --> B{{"empty, or every element is a 2-element<br/>array whose first element is a string?"}}
|
||||
B -->|"yes"| C{{"type_deduction"}}
|
||||
B -->|"no"| D{{"type_deduction"}}
|
||||
C -->|"true"| OBJ["create object"]
|
||||
C -->|"false"| E{"manual_type"}
|
||||
C -->|"false"| E{{"manual_type"}}
|
||||
E -->|"object"| OBJ
|
||||
E -->|"array"| ARR["create array"]
|
||||
D -->|"true"| ARR
|
||||
D -->|"false"| F{"manual_type"}
|
||||
D -->|"false"| F{{"manual_type"}}
|
||||
F -->|"array"| ARR
|
||||
F -->|"object"| ERR["throw type_error.301"]
|
||||
```
|
||||
|
||||
<p class="nj-caption" markdown>Decision flow for an initializer list: hexagons are checks, edge labels are their
|
||||
outcomes, and rectangles are the resulting value or exception.</p>
|
||||
|
||||
The rules aim to create the best fit between a C++ initializer list and JSON values. The rationale is as follows:
|
||||
|
||||
1. The empty initializer list is written as `#!cpp {}` which is exactly an empty JSON object.
|
||||
@@ -236,7 +247,9 @@ basic_json(basic_json&& other) noexcept;
|
||||
2. No-throw guarantee: this constructor never throws exceptions.
|
||||
3. Depends on the called constructor. For types directly supported by the library (i.e., all types for which no
|
||||
`to_json()` function was provided), a strong guarantee holds: if an exception is thrown, there are no changes to any
|
||||
JSON value.
|
||||
JSON value. **Exception:** when `val` is an rvalue array-like or object-like container, its elements are moved one
|
||||
by one; if an exception is thrown in the middle of the conversion (e.g., an allocation failure), the JSON value is
|
||||
unchanged, but the source container may be left partially moved-from.
|
||||
4. Depends on the called constructor. For types directly supported by the library (i.e., all types for which no
|
||||
`to_json()` function was provided), a strong guarantee holds: if an exception is thrown, there are no changes to any
|
||||
JSON value.
|
||||
@@ -336,13 +349,45 @@ basic_json(basic_json&& other) noexcept;
|
||||
The following code shows the constructor for different `value_t` values.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/basic_json__value_t.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create the different JSON values with default values
|
||||
json j_null(json::value_t::null);
|
||||
json j_boolean(json::value_t::boolean);
|
||||
json j_number_integer(json::value_t::number_integer);
|
||||
json j_number_float(json::value_t::number_float);
|
||||
json j_object(json::value_t::object);
|
||||
json j_array(json::value_t::array);
|
||||
json j_string(json::value_t::string);
|
||||
|
||||
// serialize the JSON values
|
||||
std::cout << j_null << '\n';
|
||||
std::cout << j_boolean << '\n';
|
||||
std::cout << j_number_integer << '\n';
|
||||
std::cout << j_number_float << '\n';
|
||||
std::cout << j_object << '\n';
|
||||
std::cout << j_array << '\n';
|
||||
std::cout << j_string << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/basic_json__value_t.output"
|
||||
null
|
||||
false
|
||||
0
|
||||
0.0
|
||||
{}
|
||||
[]
|
||||
""
|
||||
|
||||
```
|
||||
|
||||
??? example "Example: (2) create a `#!json null` object"
|
||||
@@ -350,13 +395,31 @@ basic_json(basic_json&& other) noexcept;
|
||||
The following code shows the constructor with and without a null pointer parameter.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/basic_json__nullptr_t.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// implicitly create a JSON null value
|
||||
json j1;
|
||||
|
||||
// explicitly create a JSON null value
|
||||
json j2(nullptr);
|
||||
|
||||
// serialize the JSON null value
|
||||
std::cout << j1 << '\n' << j2 << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/basic_json__nullptr_t.output"
|
||||
null
|
||||
null
|
||||
|
||||
```
|
||||
|
||||
??? example "Example: (3) create a JSON value from compatible types"
|
||||
@@ -364,13 +427,266 @@ basic_json(basic_json&& other) noexcept;
|
||||
The following code shows the constructor with several compatible types.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/basic_json__CompatibleType.cpp"
|
||||
#include <iostream>
|
||||
#include <deque>
|
||||
#include <list>
|
||||
#include <forward_list>
|
||||
#include <set>
|
||||
#include <unordered_map>
|
||||
#include <unordered_set>
|
||||
#include <valarray>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// ============
|
||||
// object types
|
||||
// ============
|
||||
|
||||
// create an object from an object_t value
|
||||
json::object_t object_value = { {"one", 1}, {"two", 2} };
|
||||
json j_object_t(object_value);
|
||||
|
||||
// create an object from std::map
|
||||
std::map<std::string, int> c_map
|
||||
{
|
||||
{"one", 1}, {"two", 2}, {"three", 3}
|
||||
};
|
||||
json j_map(c_map);
|
||||
|
||||
// create an object from std::unordered_map
|
||||
std::unordered_map<const char*, double> c_umap
|
||||
{
|
||||
{"one", 1.2}, {"two", 2.3}, {"three", 3.4}
|
||||
};
|
||||
json j_umap(c_umap);
|
||||
|
||||
// create an object from std::multimap
|
||||
std::multimap<std::string, bool> c_mmap
|
||||
{
|
||||
{"one", true}, {"two", true}, {"three", false}, {"three", true}
|
||||
};
|
||||
json j_mmap(c_mmap); // only one entry for key "three" is used
|
||||
|
||||
// create an object from std::unordered_multimap
|
||||
std::unordered_multimap<std::string, bool> c_ummap
|
||||
{
|
||||
{"one", true}, {"two", true}, {"three", false}, {"three", false}
|
||||
};
|
||||
json j_ummap(c_ummap); // only one entry for key "three" is used
|
||||
|
||||
// serialize the JSON objects
|
||||
std::cout << j_object_t << '\n';
|
||||
std::cout << j_map << '\n';
|
||||
std::cout << j_umap << '\n';
|
||||
std::cout << j_mmap << '\n';
|
||||
std::cout << j_ummap << "\n\n";
|
||||
|
||||
// ===========
|
||||
// array types
|
||||
// ===========
|
||||
|
||||
// create an array from an array_t value
|
||||
json::array_t array_value = {"one", "two", 3, 4.5, false};
|
||||
json j_array_t(array_value);
|
||||
|
||||
// create an array from std::vector
|
||||
std::vector<int> c_vector {1, 2, 3, 4};
|
||||
json j_vec(c_vector);
|
||||
|
||||
// create an array from std::valarray
|
||||
std::valarray<short> c_valarray {10, 9, 8, 7};
|
||||
json j_valarray(c_valarray);
|
||||
|
||||
// create an array from std::deque
|
||||
std::deque<double> c_deque {1.2, 2.3, 3.4, 5.6};
|
||||
json j_deque(c_deque);
|
||||
|
||||
// create an array from std::list
|
||||
std::list<bool> c_list {true, true, false, true};
|
||||
json j_list(c_list);
|
||||
|
||||
// create an array from std::forward_list
|
||||
std::forward_list<std::int64_t> c_flist {12345678909876, 23456789098765, 34567890987654, 45678909876543};
|
||||
json j_flist(c_flist);
|
||||
|
||||
// create an array from std::array
|
||||
std::array<unsigned long, 4> c_array {{1, 2, 3, 4}};
|
||||
json j_array(c_array);
|
||||
|
||||
// create an array from std::set
|
||||
std::set<std::string> c_set {"one", "two", "three", "four", "one"};
|
||||
json j_set(c_set); // only one entry for "one" is used
|
||||
|
||||
// create an array from std::unordered_set
|
||||
std::unordered_set<std::string> c_uset {"one", "one"};
|
||||
json j_uset(c_uset); // only one entry for "one" is used
|
||||
|
||||
// create an array from std::multiset
|
||||
std::multiset<std::string> c_mset {"one", "two", "one", "four"};
|
||||
json j_mset(c_mset); // both entries for "one" are used
|
||||
|
||||
// create an array from std::unordered_multiset
|
||||
std::unordered_multiset<std::string> c_umset {"one", "one"};
|
||||
json j_umset(c_umset); // both entries for "one" are used
|
||||
|
||||
// serialize the JSON arrays
|
||||
std::cout << j_array_t << '\n';
|
||||
std::cout << j_vec << '\n';
|
||||
std::cout << j_valarray << '\n';
|
||||
std::cout << j_deque << '\n';
|
||||
std::cout << j_list << '\n';
|
||||
std::cout << j_flist << '\n';
|
||||
std::cout << j_array << '\n';
|
||||
std::cout << j_set << '\n';
|
||||
std::cout << j_uset << '\n';
|
||||
std::cout << j_mset << '\n';
|
||||
std::cout << j_umset << "\n\n";
|
||||
|
||||
// ============
|
||||
// string types
|
||||
// ============
|
||||
|
||||
// create string from a string_t value
|
||||
json::string_t string_value = "The quick brown fox jumps over the lazy dog.";
|
||||
json j_string_t(string_value);
|
||||
|
||||
// create a JSON string directly from a string literal
|
||||
json j_string_literal("The quick brown fox jumps over the lazy dog.");
|
||||
|
||||
// create string from std::string
|
||||
std::string s_stdstring = "The quick brown fox jumps over the lazy dog.";
|
||||
json j_stdstring(s_stdstring);
|
||||
|
||||
// serialize the JSON strings
|
||||
std::cout << j_string_t << '\n';
|
||||
std::cout << j_string_literal << '\n';
|
||||
std::cout << j_stdstring << "\n\n";
|
||||
|
||||
// ============
|
||||
// number types
|
||||
// ============
|
||||
|
||||
// create a JSON number from number_integer_t
|
||||
json::number_integer_t value_integer_t = -42;
|
||||
json j_integer_t(value_integer_t);
|
||||
|
||||
// create a JSON number from number_unsigned_t
|
||||
json::number_integer_t value_unsigned_t = 17;
|
||||
json j_unsigned_t(value_unsigned_t);
|
||||
|
||||
// create a JSON number from an anonymous enum
|
||||
enum { enum_value = 17 };
|
||||
json j_enum(enum_value);
|
||||
|
||||
// create values of different integer types
|
||||
short n_short = 42;
|
||||
int n_int = -23;
|
||||
long n_long = 1024;
|
||||
int_least32_t n_int_least32_t = -17;
|
||||
uint8_t n_uint8_t = 8;
|
||||
|
||||
// create (integer) JSON numbers
|
||||
json j_short(n_short);
|
||||
json j_int(n_int);
|
||||
json j_long(n_long);
|
||||
json j_int_least32_t(n_int_least32_t);
|
||||
json j_uint8_t(n_uint8_t);
|
||||
|
||||
// create values of different floating-point types
|
||||
json::number_float_t v_ok = 3.141592653589793;
|
||||
json::number_float_t v_nan = NAN;
|
||||
json::number_float_t v_infinity = INFINITY;
|
||||
|
||||
// create values of different floating-point types
|
||||
float n_float = 42.23;
|
||||
float n_float_nan = 1.0f / 0.0f;
|
||||
double n_double = 23.42;
|
||||
|
||||
// create (floating point) JSON numbers
|
||||
json j_ok(v_ok);
|
||||
json j_nan(v_nan);
|
||||
json j_infinity(v_infinity);
|
||||
json j_float(n_float);
|
||||
json j_float_nan(n_float_nan);
|
||||
json j_double(n_double);
|
||||
|
||||
// serialize the JSON numbers
|
||||
std::cout << j_integer_t << '\n';
|
||||
std::cout << j_unsigned_t << '\n';
|
||||
std::cout << j_enum << '\n';
|
||||
std::cout << j_short << '\n';
|
||||
std::cout << j_int << '\n';
|
||||
std::cout << j_long << '\n';
|
||||
std::cout << j_int_least32_t << '\n';
|
||||
std::cout << j_uint8_t << '\n';
|
||||
std::cout << j_ok << '\n';
|
||||
std::cout << j_nan << '\n';
|
||||
std::cout << j_infinity << '\n';
|
||||
std::cout << j_float << '\n';
|
||||
std::cout << j_float_nan << '\n';
|
||||
std::cout << j_double << "\n\n";
|
||||
|
||||
// =============
|
||||
// boolean types
|
||||
// =============
|
||||
|
||||
// create boolean values
|
||||
json j_truth = true;
|
||||
json j_falsity = false;
|
||||
|
||||
// serialize the JSON booleans
|
||||
std::cout << j_truth << '\n';
|
||||
std::cout << j_falsity << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/basic_json__CompatibleType.output"
|
||||
{"one":1,"two":2}
|
||||
{"one":1,"three":3,"two":2}
|
||||
{"one":1.2,"three":3.4,"two":2.3}
|
||||
{"one":true,"three":false,"two":true}
|
||||
{"one":true,"three":false,"two":true}
|
||||
|
||||
["one","two",3,4.5,false]
|
||||
[1,2,3,4]
|
||||
[10,9,8,7]
|
||||
[1.2,2.3,3.4,5.6]
|
||||
[true,true,false,true]
|
||||
[12345678909876,23456789098765,34567890987654,45678909876543]
|
||||
[1,2,3,4]
|
||||
["four","one","three","two"]
|
||||
["one"]
|
||||
["four","one","one","two"]
|
||||
["one","one"]
|
||||
|
||||
"The quick brown fox jumps over the lazy dog."
|
||||
"The quick brown fox jumps over the lazy dog."
|
||||
"The quick brown fox jumps over the lazy dog."
|
||||
|
||||
-42
|
||||
17
|
||||
17
|
||||
42
|
||||
-23
|
||||
1024
|
||||
-17
|
||||
8
|
||||
3.141592653589793
|
||||
null
|
||||
null
|
||||
42.22999954223633
|
||||
null
|
||||
23.42
|
||||
|
||||
true
|
||||
false
|
||||
|
||||
```
|
||||
|
||||
Note the output is platform-dependent.
|
||||
@@ -382,13 +698,38 @@ basic_json(basic_json&& other) noexcept;
|
||||
converting to `json`, whose `object_t` sorts by key.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/basic_json__BasicJsonType.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
using nlohmann::ordered_json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create an ordered_json value; insertion order is preserved
|
||||
ordered_json oj = {{"c", 3}, {"a", 1}, {"b", 2}};
|
||||
|
||||
// convert to json -- overload (4) is used; keys end up sorted
|
||||
json j(oj);
|
||||
|
||||
// convert back to ordered_json -- the original insertion order is lost,
|
||||
// because it was already given up when converting to json
|
||||
ordered_json oj2(j);
|
||||
|
||||
std::cout << oj << '\n';
|
||||
std::cout << j << '\n';
|
||||
std::cout << oj2 << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/basic_json__BasicJsonType.output"
|
||||
{"c":3,"a":1,"b":2}
|
||||
{"a":1,"b":2,"c":3}
|
||||
{"a":1,"b":2,"c":3}
|
||||
|
||||
```
|
||||
|
||||
??? example "Example: (5) create a container (array or object) from an initializer list"
|
||||
@@ -396,13 +737,39 @@ basic_json(basic_json&& other) noexcept;
|
||||
The example below shows how JSON values are created from initializer lists.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/basic_json__list_init_t.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create JSON values
|
||||
json j_empty_init_list = json({});
|
||||
json j_object = { {"one", 1}, {"two", 2} };
|
||||
json j_array = {1, 2, 3, 4};
|
||||
json j_nested_object = { {"one", {1}}, {"two", {1, 2}} };
|
||||
json j_nested_array = { {{1}, "one"}, {{1, 2}, "two"} };
|
||||
|
||||
// serialize the JSON value
|
||||
std::cout << j_empty_init_list << '\n';
|
||||
std::cout << j_object << '\n';
|
||||
std::cout << j_array << '\n';
|
||||
std::cout << j_nested_object << '\n';
|
||||
std::cout << j_nested_array << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/basic_json__list_init_t.output"
|
||||
{}
|
||||
{"one":1,"two":2}
|
||||
[1,2,3,4]
|
||||
{"one":[1],"two":[1,2]}
|
||||
[[[1],"one"],[[1,2],"two"]]
|
||||
|
||||
```
|
||||
|
||||
??? example "Example: (6) construct an array with count copies of a given value"
|
||||
@@ -410,13 +777,34 @@ basic_json(basic_json&& other) noexcept;
|
||||
The following code shows examples for creating arrays with several copies of a given value.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/basic_json__size_type_basic_json.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create an array by creating copies of a JSON value
|
||||
json value = "Hello";
|
||||
json array_0 = json(0, value);
|
||||
json array_1 = json(1, value);
|
||||
json array_5 = json(5, value);
|
||||
|
||||
// serialize the JSON arrays
|
||||
std::cout << array_0 << '\n';
|
||||
std::cout << array_1 << '\n';
|
||||
std::cout << array_5 << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/basic_json__size_type_basic_json.output"
|
||||
[]
|
||||
["Hello"]
|
||||
["Hello","Hello","Hello","Hello","Hello"]
|
||||
|
||||
```
|
||||
|
||||
??? example "Example: (7) construct a JSON container given an iterator range"
|
||||
@@ -424,13 +812,49 @@ basic_json(basic_json&& other) noexcept;
|
||||
The example below shows several ways to create JSON values by specifying a subrange with iterators.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/basic_json__InputIt_InputIt.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create JSON values
|
||||
json j_array = {"alpha", "bravo", "charly", "delta", "easy"};
|
||||
json j_number = 42;
|
||||
json j_object = {{"one", "eins"}, {"two", "zwei"}};
|
||||
|
||||
// create copies using iterators
|
||||
json j_array_range(j_array.begin() + 1, j_array.end() - 2);
|
||||
json j_number_range(j_number.begin(), j_number.end());
|
||||
json j_object_range(j_object.begin(), j_object.find("two"));
|
||||
|
||||
// serialize the values
|
||||
std::cout << j_array_range << '\n';
|
||||
std::cout << j_number_range << '\n';
|
||||
std::cout << j_object_range << '\n';
|
||||
|
||||
// example for an exception
|
||||
try
|
||||
{
|
||||
json j_invalid(j_number.begin() + 1, j_number.end());
|
||||
}
|
||||
catch (const json::invalid_iterator& e)
|
||||
{
|
||||
std::cout << e.what() << '\n';
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/basic_json__InputIt_InputIt.output"
|
||||
["bravo","charly"]
|
||||
42
|
||||
{"one":"eins"}
|
||||
[json.exception.invalid_iterator.204] iterators out of range
|
||||
|
||||
```
|
||||
|
||||
??? example "Example: (8) copy constructor"
|
||||
@@ -438,13 +862,32 @@ basic_json(basic_json&& other) noexcept;
|
||||
The following code shows an example for the copy constructor.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/basic_json__basic_json.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create a JSON array
|
||||
json j1 = {"one", "two", 3, 4.5, false};
|
||||
|
||||
// create a copy
|
||||
json j2(j1);
|
||||
|
||||
// serialize the JSON array
|
||||
std::cout << j1 << " = " << j2 << '\n';
|
||||
std::cout << std::boolalpha << (j1 == j2) << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/basic_json__basic_json.output"
|
||||
["one","two",3,4.5,false] = ["one","two",3,4.5,false]
|
||||
true
|
||||
|
||||
```
|
||||
|
||||
??? example "Example: (9) move constructor"
|
||||
@@ -452,35 +895,55 @@ basic_json(basic_json&& other) noexcept;
|
||||
The code below shows the move constructor explicitly called via `std::move`.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/basic_json__moveconstructor.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create a JSON value
|
||||
json a = 23;
|
||||
|
||||
// move contents of a to b
|
||||
json b(std::move(a));
|
||||
|
||||
// serialize the JSON arrays
|
||||
std::cout << a << '\n';
|
||||
std::cout << b << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/basic_json__moveconstructor.output"
|
||||
null
|
||||
23
|
||||
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [array](array.md) create a JSON array value, forcing array creation from an initializer list even when it looks like
|
||||
- [`array`](array.md) - create a JSON array value, forcing array creation from an initializer list even when it looks like
|
||||
an object
|
||||
- [object](object.md) create a JSON object value, forcing object creation from an initializer list
|
||||
- [binary](binary.md) create a JSON binary array value
|
||||
- [operator=](operator=.md) copy assignment operator
|
||||
- [`object`](object.md) - create a JSON object value, forcing object creation from an initializer list
|
||||
- [`binary`](binary.md) - create a JSON binary array value
|
||||
- [`operator=`](operator=.md) - copy assignment operator
|
||||
- [Creating JSON values](../../features/creating_values.md) - the article on creating JSON values
|
||||
- [Converting values](../../features/conversions.md) - which C++ types can be converted
|
||||
|
||||
## Version history
|
||||
|
||||
1. Since version 1.0.0.
|
||||
2. Since version 1.0.0.
|
||||
3. Since version 2.1.0.
|
||||
4. Since version 3.2.0. Explicit for different string types if `JSON_USE_IMPLICIT_CONVERSIONS` is `0` since
|
||||
1. Added in version 1.0.0.
|
||||
2. Added in version 1.0.0.
|
||||
3. Added in version 2.1.0.
|
||||
4. Added in version 3.1.2. Explicit for different string types if `JSON_USE_IMPLICIT_CONVERSIONS` is `0` since
|
||||
version 3.13.0.
|
||||
5. Since version 1.0.0.
|
||||
6. Since version 1.0.0.
|
||||
7. Since version 1.0.0. Fixed in version 3.13.0 to also check the iterator range for binary values; before, a range
|
||||
5. Added in version 1.0.0.
|
||||
6. Added in version 1.0.0.
|
||||
7. Added in version 1.0.0. Fixed in version 3.13.0 to also check the iterator range for binary values; before, a range
|
||||
that did not cover the whole value (such as `(end(), end())`) was accepted and the whole binary value was copied,
|
||||
unlike the other primitive types.
|
||||
8. Since version 1.0.0.
|
||||
9. Since version 1.0.0.
|
||||
8. Added in version 1.0.0.
|
||||
9. Added in version 1.0.0.
|
||||
@@ -1,4 +1,4 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/basic_json/" rel="canonical"><link href=../ rel=prev><link href=../~basic_json/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>(Constructor) - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../../css/custom.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsonbasic_json class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> (Constructor) </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5Line truncated
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/basic_json/" rel="canonical"><link href=../ rel=prev><link href=../~basic_json/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>(Constructor) - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel=stylesheet href=../../../css/custom.css><link rel=stylesheet href=../../../css/brand.css><link rel=stylesheet href=../../../css/fig-sax.css><link rel=stylesheet href=../../../css/fig-jsonview.css><link rel=stylesheet href=../../../css/fig-exceptions.css><link rel=stylesheet href=../../../css/fig-pointer.css><link rel=stylesheet href=../../../css/fig-charts.css><link rel=stylesheet href=../../../css/fig-integration.css><link rel=stylesheet href=../../../css/fig-macros.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsonbasic_json class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> (Constructor) </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6Line truncated
|
||||
<span class=n>basic_json</span><span class=p>(</span><span class=k>const</span><span class=w> </span><span class=n>value_t</span><span class=w> </span><span class=n>v</span><span class=p>);</span>
|
||||
|
||||
<span class=c1>// (2)</span>
|
||||
@@ -31,24 +31,24 @@
|
||||
|
||||
<span class=c1>// (9)</span>
|
||||
<span class=n>basic_json</span><span class=p>(</span><span class=n>basic_json</span><span class=o>&&</span><span class=w> </span><span class=n>other</span><span class=p>)</span><span class=w> </span><span class=k>noexcept</span><span class=p>;</span>
|
||||
</code></pre></div> <ol> <li> <p>Create an empty <abbr title="JavaScript Object Notation">JSON</abbr> value with a given type. The value will be default initialized with an empty value which depends on the type:</p> <table> <thead> <tr> <th>Value type</th> <th>initial value</th> </tr> </thead> <tbody> <tr> <td>null</td> <td><code class=highlight><span class=kc>null</span></code></td> </tr> <tr> <td>boolean</td> <td><code class=highlight><span class=kc>false</span></code></td> </tr> <tr> <td>string</td> <td><code class=highlight><span class=s2>""</span></code></td> </tr> <tr> <td>number</td> <td><code class=highlight><span class=mi>0</span></code></td> </tr> <tr> <td>object</td> <td><code class=highlight><span class=p>{}</span></code></td> </tr> <tr> <td>array</td> <td><code class=highlight><span class=p>[]</span></code></td> </tr> <tr> <td>binary</td> <td>empty array</td> </tr> </tbody> </table> <p>The postcondition of this constructor can be restored by calling <a href=../clear/ ><code>clear()</code></a>.</p> </li> <li> <p>Create a <code class=highlight><span class=kc>null</span></code> <abbr title="JavaScript Object Notation">JSON</abbr> value. It either takes a null pointer as parameter (explicitly creating <code class=highlight><span class=kc>null</span></code>) or no parameter (implicitly creating <code class=highlight><span class=kc>null</span></code>). The passed null pointer itself is not read -- it is only used to choose the right constructor.</p> </li> <li> <p>This is a "catch all" constructor for all compatible <abbr title="JavaScript Object Notation">JSON</abbr> types; that is, types for which a <code>to_json()</code> method exists. The constructor forwards the parameter <code>val</code> to that method (to <code>json_serializer<U>::to_json</code> method with <code>U = uncvref_t<CompatibleType></code>, to be exact).</p> <p>Template type <code>CompatibleType</code> includes, but is not limited to, the following types:</p> <ul> <li><strong>arrays</strong>: <a href=../array_t/ ><code>array_t</code></a> and all kinds of compatible containers such as <code>std::vector</code>, <code>std::deque</code>, <code>std::list</code>, <code>std::forward_list</code>, <code>std::array</code>, <code>std::valarray</code>, <code>std::set</code>, <code>std::unordered_set</code>, <code>std::multiset</code>, and <code>std::unordered_multiset</code> with a <code>value_type</code> from which a <code>basic_json</code> value can be constructed.</li> <li><strong>objects</strong>: <a href=../object_t/ ><code>object_t</code></a> and all kinds of compatible associative containers such as <code>std::map</code>, <code>std::unordered_map</code>, <code>std::multimap</code>, and <code>std::unordered_multimap</code> with a <code>key_type</code> compatible to <code>string_t</code> and a <code>value_type</code> from which a <code>basic_json</code> value can be constructed.</li> <li><strong>strings</strong>: <code>string_t</code>, string literals, and all compatible string containers can be used.</li> <li><strong>numbers</strong>: <a href=../number_integer_t/ ><code>number_integer_t</code></a>, <a href=../number_unsigned_t/ ><code>number_unsigned_t</code></a>, <a href=../number_float_t/ ><code>number_float_t</code></a>, and all convertible number types such as <code>int</code>, <code>size_t</code>, <code>int64_t</code>, <code>float</code> or <code>double</code> can be used.</li> <li><strong>boolean</strong>: <code>boolean_t</code> / <code>bool</code> can be used.</li> <li><strong>binary</strong>: <code>binary_t</code> / <code>std::vector<uint8_t></code> may be used; unfortunately because string literals cannot be distinguished from binary character arrays by the C++ type system, all types compatible with <code>const char*</code> will be directed to the string constructor instead. This is both for backwards compatibility and due to the fact that a binary type is not a standard <abbr title="JavaScript Object Notation">JSON</abbr> type.</li> </ul> <p>See the examples below.</p> </li> <li> <p>This is a constructor for existing <code>basic_json</code> types. It does not hijack copy/move constructors, since the parameter has different template arguments than the current ones.</p> <p>The constructor tries to convert the internal <code>m_value</code> of the parameter. Each member value (object, array, string, etc.) is serialized via the corresponding <code>to_json()</code> overload. For objects and strings, the conversion requires that the <em>target</em> <code>basic_json</code> type's <code>object_t::key_type</code> (or <code>string_t</code>) be directly constructible from the <em>source</em> type's corresponding member type via <code>is_constructible</code>. If this requirement is not met, the conversion does not fail to compile; instead, it silently falls back to the array-conversion path, which represents objects as arrays of <code>[key, value]</code> pairs and strings as arrays of character codes. This is a known limitatLine truncated
|
||||
A(["initializer_list init"]) --> B{"empty, or every element is a 2-element<br/>array whose first element is a string?"}
|
||||
B -->|"yes"| C{"type_deduction"}
|
||||
B -->|"no"| D{"type_deduction"}
|
||||
</code></pre></div> <ol> <li> <p>Create an empty <abbr title="JavaScript Object Notation">JSON</abbr> value with a given type. The value will be default initialized with an empty value which depends on the type:</p> <table> <thead> <tr> <th>Value type</th> <th>initial value</th> </tr> </thead> <tbody> <tr> <td>null</td> <td><code class=highlight><span class=kc>null</span></code></td> </tr> <tr> <td>boolean</td> <td><code class=highlight><span class=kc>false</span></code></td> </tr> <tr> <td>string</td> <td><code class=highlight><span class=s2>""</span></code></td> </tr> <tr> <td>number</td> <td><code class=highlight><span class=mi>0</span></code></td> </tr> <tr> <td>object</td> <td><code class=highlight><span class=p>{}</span></code></td> </tr> <tr> <td>array</td> <td><code class=highlight><span class=p>[]</span></code></td> </tr> <tr> <td>binary</td> <td>empty array</td> </tr> </tbody> </table> <p>The postcondition of this constructor can be restored by calling <a href=../clear/ ><code>clear()</code></a>.</p> </li> <li> <p>Create a <code class=highlight><span class=kc>null</span></code> <abbr title="JavaScript Object Notation">JSON</abbr> value. It either takes a null pointer as parameter (explicitly creating <code class=highlight><span class=kc>null</span></code>) or no parameter (implicitly creating <code class=highlight><span class=kc>null</span></code>). The passed null pointer itself is not read — it is only used to choose the right constructor.</p> </li> <li> <p>This is a "catch all" constructor for all compatible <abbr title="JavaScript Object Notation">JSON</abbr> types; that is, types for which a <code>to_json()</code> method exists. The constructor forwards the parameter <code>val</code> to that method (to <code>json_serializer<U>::to_json</code> method with <code>U = uncvref_t<CompatibleType></code>, to be exact).</p> <p>Template type <code>CompatibleType</code> includes, but is not limited to, the following types:</p> <ul> <li><strong>arrays</strong>: <a href=../array_t/ ><code>array_t</code></a> and all kinds of compatible containers such as <code>std::vector</code>, <code>std::deque</code>, <code>std::list</code>, <code>std::forward_list</code>, <code>std::array</code>, <code>std::valarray</code>, <code>std::set</code>, <code>std::unordered_set</code>, <code>std::multiset</code>, and <code>std::unordered_multiset</code> with a <code>value_type</code> from which a <code>basic_json</code> value can be constructed.</li> <li><strong>objects</strong>: <a href=../object_t/ ><code>object_t</code></a> and all kinds of compatible associative containers such as <code>std::map</code>, <code>std::unordered_map</code>, <code>std::multimap</code>, and <code>std::unordered_multimap</code> with a <code>key_type</code> compatible to <code>string_t</code> and a <code>value_type</code> from which a <code>basic_json</code> value can be constructed.</li> <li><strong>strings</strong>: <code>string_t</code>, string literals, and all compatible string containers can be used.</li> </ul> <div class="admonition note"> <p class=admonition-title>Rvalue containers are moved from</p> <p>If <code>val</code> is an rvalue of a compatible array-like or object-like container other than <code>array_t</code>/<code>object_t</code> (e.g., <code>json j = std::move(vec);</code> or <code>json j(std::vector<std::string>{...});</code>), the elements are moved into the <abbr title="JavaScript Object Notation">JSON</abbr> value instead of copied. Afterwards, the elements of the source container are in a valid but unspecified state (<strong>moved-from</strong>). Keys of associative containers are <code>const</code> and therefore still copied. Lvalues and <code>const</code> rvalues are copied, and the source is left unchanged.</p> </div> <ul> <li><strong>numbers</strong>: <a href=../number_integer_t/ ><code>number_integer_t</code></a>, <a href=../number_unsigned_t/ ><code>number_unsigned_t</code></a>, <a href=../number_float_t/ ><code>number_float_t</code></a>, and all convertible number types such as <code>int</code>, <code>size_t</code>, <code>int64_t</code>, <code>float</code> or <code>double</code> can be used.</li> <li><strong>boolean</strong>: <code>boolean_t</code> / <code>bool</code> can be used.</li> <li><strong>binary</strong>: <code>binary_t</code> / <code>std::vector<uint8_t></code> may be used; unfortunately because string literals cannot be distinguished from binary character arrays by the C++ type system, all types compatible with <code>const char*</code> will be directed to the string constructor instead. This is both for backwards compatibility and due to the fact that a binary type is not a standard <abbr title="JavaScript Object Notation">JSON</abbr> type.</li> </ul> <p>See the examples below.</p> </li> <li> <p>This is a constructor for existing <code>basic_json</code> types. It does not hijack copy/move constructors, since the parameter has different template arguments than the current ones.</pLine truncated
|
||||
A(["initializer_list init"]) --> B{{"empty, or every element is a 2-element<br/>array whose first element is a string?"}}
|
||||
B -->|"yes"| C{{"type_deduction"}}
|
||||
B -->|"no"| D{{"type_deduction"}}
|
||||
C -->|"true"| OBJ["create object"]
|
||||
C -->|"false"| E{"manual_type"}
|
||||
C -->|"false"| E{{"manual_type"}}
|
||||
E -->|"object"| OBJ
|
||||
E -->|"array"| ARR["create array"]
|
||||
D -->|"true"| ARR
|
||||
D -->|"false"| F{"manual_type"}
|
||||
D -->|"false"| F{{"manual_type"}}
|
||||
F -->|"array"| ARR
|
||||
F -->|"object"| ERR["throw type_error.301"]</code></pre> <p>The rules aim to create the best fit between a C++ initializer list and <abbr title="JavaScript Object Notation">JSON</abbr> values. The rationale is as follows:</p> <ol> <li>The empty initializer list is written as <code class=highlight><span class=p>{}</span></code> which is exactly an empty <abbr title="JavaScript Object Notation">JSON</abbr> object.</li> <li>C++ has no way of describing mapped types other than to list a list of pairs. As <abbr title="JavaScript Object Notation">JSON</abbr> requires that keys must be of type string, rule 2 is the weakest constraint one can pose on initializer lists to interpret them as an object.</li> <li>In all other cases, the initializer list could not be interpreted as a <abbr title="JavaScript Object Notation">JSON</abbr> object type, so interpreting it as a <abbr title="JavaScript Object Notation">JSON</abbr> array type is safe.</li> </ol> <p>With the rules described above, the following <abbr title="JavaScript Object Notation">JSON</abbr> values cannot be expressed by an initializer list:</p> <ul> <li>the empty array (<code class=highlight><span class=p>[]</span></code>): use <code>array(initializer_list_t)</code> with an empty initializer list in this case</li> <li>arrays whose elements satisfy rule 2: use <code>array(initializer_list_t)</code> with the same initializer list in this case</li> </ul> <p>Function <a href=../array/ ><code>array()</code></a> and <a href=../object/ ><code>object()</code></a> force array and object creation from initializer lists, respectively.</p> <div class="admonition warning"> <p class=admonition-title>Brace initialization yields arrays</p> <p>Because this constructor takes an <code>initializer_list_t</code>, brace-initializing a <code>json</code>/<code>ordered_json</code> from another <code>json</code> value wraps it in a single-element array rather than copying it:</p> <div class=highlight><pre><span></span><code><span class=n>json</span><span class=w> </span><span class=n>j1</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=s>"hello"</span><span class=p>;</span>
|
||||
F -->|"object"| ERR["throw type_error.301"]</code></pre> <p><p class=nj-caption markdown>Decision flow for an initializer list: hexagons are checks, edge labels are their outcomes, and rectangles are the resulting value or exception.</p></p> <p>The rules aim to create the best fit between a C++ initializer list and <abbr title="JavaScript Object Notation">JSON</abbr> values. The rationale is as follows:</p> <ol> <li>The empty initializer list is written as <code class=highlight><span class=p>{}</span></code> which is exactly an empty <abbr title="JavaScript Object Notation">JSON</abbr> object.</li> <li>C++ has no way of describing mapped types other than to list a list of pairs. As <abbr title="JavaScript Object Notation">JSON</abbr> requires that keys must be of type string, rule 2 is the weakest constraint one can pose on initializer lists to interpret them as an object.</li> <li>In all other cases, the initializer list could not be interpreted as a <abbr title="JavaScript Object Notation">JSON</abbr> object type, so interpreting it as a <abbr title="JavaScript Object Notation">JSON</abbr> array type is safe.</li> </ol> <p>With the rules described above, the following <abbr title="JavaScript Object Notation">JSON</abbr> values cannot be expressed by an initializer list:</p> <ul> <li>the empty array (<code class=highlight><span class=p>[]</span></code>): use <code>array(initializer_list_t)</code> with an empty initializer list in this case</li> <li>arrays whose elements satisfy rule 2: use <code>array(initializer_list_t)</code> with the same initializer list in this case</li> </ul> <p>Function <a href=../array/ ><code>array()</code></a> and <a href=../object/ ><code>object()</code></a> force array and object creation from initializer lists, respectively.</p> <div class="admonition warning"> <p class=admonition-title>Brace initialization yields arrays</p> <p>Because this constructor takes an <code>initializer_list_t</code>, brace-initializing a <code>json</code>/<code>ordered_json</code> from another <code>json</code> value wraps it in a single-element array rather than copying it:</p> <div class=highlight><pre><span></span><code><span class=n>json</span><span class=w> </span><span class=n>j1</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=s>"hello"</span><span class=p>;</span>
|
||||
<span class=n>json</span><span class=w> </span><span class=n>j2</span><span class=p>{</span><span class=n>j1</span><span class=p>};</span><span class=w> </span><span class=c1>// [!] j2 is ["hello"], NOT a copy of j1</span>
|
||||
<span class=n>json</span><span class=w> </span><span class=nf>j3</span><span class=p>(</span><span class=n>j1</span><span class=p>);</span><span class=w> </span><span class=c1>// j3 is "hello" -- parentheses copy as expected</span>
|
||||
</code></pre></div> <p>See the <abbr title="Frequently Asked Questions">FAQ</abbr> entry on <a href=../../../home/faq/#brace-initialization-yields-arrays>brace initialization</a> for the full explanation, an opt-in macro to change this behavior, and how to explicitly create a single-element array (<code>json::array({value})</code>) if that is what you want.</p> </div> </li> <li> <p>Constructs a <abbr title="JavaScript Object Notation">JSON</abbr> array value by creating <code>cnt</code> copies of a passed value. In case <code>cnt</code> is <code>0</code>, an empty array is created.</p> </li> <li> <p>Constructs the <abbr title="JavaScript Object Notation">JSON</abbr> value with the contents of the range <code>[first, last)</code>. The semantics depend on the different types a <abbr title="JavaScript Object Notation">JSON</abbr> value can have:</p> <ul> <li>In case of a <code class=highlight><span class=kc>null</span></code> type, <a href=../../../home/exceptions/#jsonexceptioninvalid_iterator206>invalid_iterator.206</a> is thrown.</li> <li>In case of other primitive types (number, boolean, string, or binary), <code>first</code> must be <code>begin()</code> and <code>last</code> must be <code>end()</code>. In this case, the value is copied. Otherwise, <a href=../../../home/exceptions/#jsonexceptioninvalid_iterator204><code>invalid_iterator.204</code></a> is thrown.</li> <li>In case of structured types (array, object), the constructor behaves as similar versions for <code>std::vector</code> or <code>std::map</code>; that is, a <abbr title="JavaScript Object Notation">JSON</abbr> array or object is constructed from the values in the range.</li> </ul> </li> <li> <p>Creates a copy of a given <abbr title="JavaScript Object Notation">JSON</abbr> value.</p> </li> <li> <p>Move constructor. Constructs a <abbr title="JavaScript Object Notation">JSON</abbr> value with the contents of the given value <code>other</code> using move semantics. It "steals" the resources from <code>other</code> and leaves it as <abbr title="JavaScript Object Notation">JSON</abbr> <code class=highlight><span class=kc>null</span></code> value.</p> </li> </ol> <h2 id=template-parameters>Template parameters<a class=headerlink href=#template-parameters title="Permanent link">¶</a></h2> <dl> <dt><code>CompatibleType</code></dt> <dd> <p>a type such that:</p> <ul> <li><code>CompatibleType</code> is not derived from <code>std::istream</code>,</li> <li><code>CompatibleType</code> is not <code>basic_json</code> (to avoid hijacking copy/move constructors),</li> <li><code>CompatibleType</code> is not a different <code>basic_json</code> type (i.e. with different template arguments)</li> <li><code>CompatibleType</code> is not a <code>basic_json</code> nested type (e.g., <code>json_pointer</code>, <code>iterator</code>, etc.)</li> <li>if <a href=../../macros/json_disable_tuple_reference_conversion/ ><code>JSON_DISABLE_TUPLE_REFERENCE_CONVERSION</code></a> is defined to <code>1</code>: <code>CompatibleType</code> is not a one-element <code>std::tuple</code> holding a reference to <code>basic_json</code></li> <li><code>json_serializer<U></code> (with <code>U = uncvref_t<CompatibleType></code>) has a <code>to_json(basic_json_t&, CompatibleType&&)</code> method</li> </ul> </dd> <dt><code>BasicJsonType</code>:</dt> <dd> <p>a type such that:</p> <ul> <li><code>BasicJsonType</code> is a <code>basic_json</code> type.</li> <li><code>BasicJsonType</code> has different template arguments than <code>basic_json_t</code>.</li> </ul> <p><strong>Note:</strong> For cross-<code>basic_json</code> conversions to produce correct results, the target <code>basic_json</code>'s <a href=../object_t/ ><code>object_t</code></a><code>::key_type</code> and <a href=../string_t/ ><code>string_t</code></a> must be directly constructible from the source <code>basic_json</code>'s corresponding types. See the description of overload (4) above for details on what happens when this requirement is not met.</p> </dd> <dt><code>U</code>:</dt> <dd><code>uncvref_t<CompatibleType></code></dd> </dl> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">¶</a></h2> <dl> <dt><code>v</code> (in)</dt> <dd>the type of the value to create</dd> <dt><code>val</code> (in)</dt> <dd>the value to be forwarded to the respective constructor</dd> <dt><code>init</code> (in)</dt> <dd>initializer list with <abbr title="JavaScript Object Notation">JSON</abbr> values</dd> <dt><code>type_deduction</code> (in)</dt> <dd>internal parameter; when set to <code class=highlight><span class=nb>true</span></code>, the type of the <abbr title="JavaScript Object Notation">JSON</abbr> value is deducted from the initializer list <code>init</code>; when set to <code class=highlight><span class=nb>false</span></code>, the type provided via <code>manual_type</code> is forced. This mode is used by the functions <code>array(initializer_list_t)</code> and <code>object(Line truncated
|
||||
</code></pre></div> <p>See the <abbr title="Frequently Asked Questions">FAQ</abbr> entry on <a href=../../../home/faq/#brace-initialization-yields-arrays>brace initialization</a> for the full explanation, an opt-in macro to change this behavior, and how to explicitly create a single-element array (<code>json::array({value})</code>) if that is what you want.</p> </div> </li> <li> <p>Constructs a <abbr title="JavaScript Object Notation">JSON</abbr> array value by creating <code>cnt</code> copies of a passed value. In case <code>cnt</code> is <code>0</code>, an empty array is created.</p> </li> <li> <p>Constructs the <abbr title="JavaScript Object Notation">JSON</abbr> value with the contents of the range <code>[first, last)</code>. The semantics depend on the different types a <abbr title="JavaScript Object Notation">JSON</abbr> value can have:</p> <ul> <li>In case of a <code class=highlight><span class=kc>null</span></code> type, <a href=../../../home/exceptions/#jsonexceptioninvalid_iterator206>invalid_iterator.206</a> is thrown.</li> <li>In case of other primitive types (number, boolean, string, or binary), <code>first</code> must be <code>begin()</code> and <code>last</code> must be <code>end()</code>. In this case, the value is copied. Otherwise, <a href=../../../home/exceptions/#jsonexceptioninvalid_iterator204><code>invalid_iterator.204</code></a> is thrown.</li> <li>In case of structured types (array, object), the constructor behaves as similar versions for <code>std::vector</code> or <code>std::map</code>; that is, a <abbr title="JavaScript Object Notation">JSON</abbr> array or object is constructed from the values in the range.</li> </ul> </li> <li> <p>Creates a copy of a given <abbr title="JavaScript Object Notation">JSON</abbr> value.</p> </li> <li> <p>Move constructor. Constructs a <abbr title="JavaScript Object Notation">JSON</abbr> value with the contents of the given value <code>other</code> using move semantics. It "steals" the resources from <code>other</code> and leaves it as <abbr title="JavaScript Object Notation">JSON</abbr> <code class=highlight><span class=kc>null</span></code> value.</p> </li> </ol> <h2 id=template-parameters>Template parameters<a class=headerlink href=#template-parameters title="Permanent link">¶</a></h2> <dl> <dt><code>CompatibleType</code></dt> <dd> <p>a type such that:</p> <ul> <li><code>CompatibleType</code> is not derived from <code>std::istream</code>,</li> <li><code>CompatibleType</code> is not <code>basic_json</code> (to avoid hijacking copy/move constructors),</li> <li><code>CompatibleType</code> is not a different <code>basic_json</code> type (i.e. with different template arguments)</li> <li><code>CompatibleType</code> is not a <code>basic_json</code> nested type (e.g., <code>json_pointer</code>, <code>iterator</code>, etc.)</li> <li>if <a href=../../macros/json_disable_tuple_reference_conversion/ ><code>JSON_DISABLE_TUPLE_REFERENCE_CONVERSION</code></a> is defined to <code>1</code>: <code>CompatibleType</code> is not a one-element <code>std::tuple</code> holding a reference to <code>basic_json</code></li> <li><code>json_serializer<U></code> (with <code>U = uncvref_t<CompatibleType></code>) has a <code>to_json(basic_json_t&, CompatibleType&&)</code> method</li> </ul> </dd> <dt><code>BasicJsonType</code>:</dt> <dd> <p>a type such that:</p> <ul> <li><code>BasicJsonType</code> is a <code>basic_json</code> type.</li> <li><code>BasicJsonType</code> has different template arguments than <code>basic_json_t</code>.</li> </ul> <p><strong>Note:</strong> For cross-<code>basic_json</code> conversions to produce correct results, the target <code>basic_json</code>'s <a href=../object_t/ ><code>object_t</code></a><code>::key_type</code> and <a href=../string_t/ ><code>string_t</code></a> must be directly constructible from the source <code>basic_json</code>'s corresponding types. See the description of overload (4) above for details on what happens when this requirement is not met.</p> </dd> <dt><code>U</code>:</dt> <dd><code>uncvref_t<CompatibleType></code></dd> </dl> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">¶</a></h2> <dl> <dt><code>v</code> (in)</dt> <dd>the type of the value to create</dd> <dt><code>val</code> (in)</dt> <dd>the value to be forwarded to the respective constructor</dd> <dt><code>init</code> (in)</dt> <dd>initializer list with <abbr title="JavaScript Object Notation">JSON</abbr> values</dd> <dt><code>type_deduction</code> (in)</dt> <dd>internal parameter; when set to <code class=highlight><span class=nb>true</span></code>, the type of the <abbr title="JavaScript Object Notation">JSON</abbr> value is deducted from the initializer list <code>init</code>; when set to <code class=highlight><span class=nb>false</span></code>, the type provided via <code>manual_type</code> is forced. This mode is used by the functions <code>array(initializer_list_t)</code> and <code>object(Line truncated
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -80,7 +80,7 @@
|
||||
</code></pre></div> </details> <details class=example> <summary>Example: (2) create a <code class=highlight><span class=kc>null</span></code> object</summary> <p>The following code shows the constructor with and without a null pointer parameter.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -105,7 +105,7 @@
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><valarray></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -351,8 +351,8 @@
|
||||
</code></pre></div> <p>Note the output is platform-dependent.</p> </details> <details class=example> <summary>Example: (4) create a <abbr title="JavaScript Object Notation">JSON</abbr> value from another <code>basic_json</code> specialization</summary> <p>The example below shows how a <code>json</code> value is converted to an <code>ordered_json</code> value and back using the converting constructor. Note how the original insertion order of <code>oj</code> is not restored, because it was already given up when converting to <code>json</code>, whose <code>object_t</code> sorts by key.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>ordered_json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>ordered_json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>ordered_json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -376,7 +376,7 @@
|
||||
</code></pre></div> </details> <details class=example> <summary>Example: (5) create a container (array or object) from an initializer list</summary> <p>The example below shows how <abbr title="JavaScript Object Notation">JSON</abbr> values are created from initializer lists.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -402,7 +402,7 @@
|
||||
</code></pre></div> </details> <details class=example> <summary>Example: (6) construct an array with count copies of a given value</summary> <p>The following code shows examples for creating arrays with several copies of a given value.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -423,7 +423,7 @@
|
||||
</code></pre></div> </details> <details class=example> <summary>Example: (7) construct a <abbr title="JavaScript Object Notation">JSON</abbr> container given an iterator range</summary> <p>The example below shows several ways to create <abbr title="JavaScript Object Notation">JSON</abbr> values by specifying a subrange with iterators.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -459,7 +459,7 @@
|
||||
</code></pre></div> </details> <details class=example> <summary>Example: (8) copy constructor</summary> <p>The following code shows an example for the copy constructor.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -478,7 +478,7 @@
|
||||
</code></pre></div> </details> <details class=example> <summary>Example: (9) move constructor</summary> <p>The code below shows the move constructor explicitly called via <code>std::move</code>.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -494,4 +494,4 @@
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code><span class=kc>null</span>
|
||||
<span class=mi>23</span>
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../array/ >array</a> create a <abbr title="JavaScript Object Notation">JSON</abbr> array value, forcing array creation from an initializer list even when it looks like an object</li> <li><a href=../object/ >object</a> create a <abbr title="JavaScript Object Notation">JSON</abbr> object value, forcing object creation from an initializer list</li> <li><a href=../binary/ >binary</a> create a <abbr title="JavaScript Object Notation">JSON</abbr> binary array value</li> <li><a href=../operator%3D/ >operator=</a> copy assignment operator</li> <li><a href=../../../features/creating_values/ >Creating <abbr title="JavaScript Object Notation">JSON</abbr> values</a> - the article on creating <abbr title="JavaScript Object Notation">JSON</abbr> values</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ol> <li>Since version 1.0.0.</li> <li>Since version 1.0.0.</li> <li>Since version 2.1.0.</li> <li>Since version 3.2.0. Explicit for different string types if <code>JSON_USE_IMPLICIT_CONVERSIONS</code> is <code>0</code> since version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>.</li> <li>Since version 1.0.0.</li> <li>Since version 1.0.0.</li> <li>Since version 1.0.0. Fixed in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span> to also check the iterator range for binary values; before, a range that did not cover the whole value (such as <code>(end(), end())</code>) was accepted and the whole binary value was copied, unlike the other primitive types.</li> <li>Since version 1.0.0.</li> <li>Since version 1.0.0.</li> </ol> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 4, 2026 09:46:52 UTC">October 4, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2Line truncated
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../array/ ><code>array</code></a> - create a <abbr title="JavaScript Object Notation">JSON</abbr> array value, forcing array creation from an initializer list even when it looks like an object</li> <li><a href=../object/ ><code>object</code></a> - create a <abbr title="JavaScript Object Notation">JSON</abbr> object value, forcing object creation from an initializer list</li> <li><a href=../binary/ ><code>binary</code></a> - create a <abbr title="JavaScript Object Notation">JSON</abbr> binary array value</li> <li><a href=../operator%3D/ ><code>operator=</code></a> - copy assignment operator</li> <li><a href=../../../features/creating_values/ >Creating <abbr title="JavaScript Object Notation">JSON</abbr> values</a> - the article on creating <abbr title="JavaScript Object Notation">JSON</abbr> values</li> <li><a href=../../../features/conversions/ >Converting values</a> - which C++ types can be converted</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ol> <li>Added in version 1.0.0.</li> <li>Added in version 1.0.0.</li> <li>Added in version 2.1.0.</li> <li>Added in version 3.1.2. Explicit for different string types if <code>JSON_USE_IMPLICIT_CONVERSIONS</code> is <code>0</code> since version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>.</li> <li>Added in version 1.0.0.</li> <li>Added in version 1.0.0.</li> <li>Added in version 1.0.0. Fixed in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span> to also check the iterator range for binary values; before, a range that did not cover the whole value (such as <code>(end(), end())</code>) was accepted and the whole binary value was copied, unlike the other primitive types.</li> <li>Added in version 1.0.0.</li> <li>Added in version 1.0.0.</li> </ol> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../ class="md-footer__link md-footer__link--prev" aria-label="Previous: Overview"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> Overview </div> </div> </a> <a href=../~basic_json/ class="md-footer__link md-footer__link--next" aria-label="Next: (Destructor)"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> (Destructor) </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - htLine truncated
|
||||
@@ -50,7 +50,7 @@ basic_json(basic_json&& other) noexcept;
|
||||
|
||||
The postcondition of this constructor can be restored by calling [`clear()`](https://json.nlohmann.me/api/basic_json/clear/index.md).
|
||||
|
||||
1. Create a `null` JSON value. It either takes a null pointer as parameter (explicitly creating `null`) or no parameter (implicitly creating `null`). The passed null pointer itself is not read -- it is only used to choose the right constructor.
|
||||
1. Create a `null` JSON value. It either takes a null pointer as parameter (explicitly creating `null`) or no parameter (implicitly creating `null`). The passed null pointer itself is not read — it is only used to choose the right constructor.
|
||||
|
||||
1. This is a "catch all" constructor for all compatible JSON types; that is, types for which a `to_json()` method exists. The constructor forwards the parameter `val` to that method (to `json_serializer<U>::to_json` method with `U = uncvref_t<CompatibleType>`, to be exact).
|
||||
|
||||
@@ -59,6 +59,11 @@ basic_json(basic_json&& other) noexcept;
|
||||
- **arrays**: [`array_t`](https://json.nlohmann.me/api/basic_json/array_t/index.md) and all kinds of compatible containers such as `std::vector`, `std::deque`, `std::list`, `std::forward_list`, `std::array`, `std::valarray`, `std::set`, `std::unordered_set`, `std::multiset`, and `std::unordered_multiset` with a `value_type` from which a `basic_json` value can be constructed.
|
||||
- **objects**: [`object_t`](https://json.nlohmann.me/api/basic_json/object_t/index.md) and all kinds of compatible associative containers such as `std::map`, `std::unordered_map`, `std::multimap`, and `std::unordered_multimap` with a `key_type` compatible to `string_t` and a `value_type` from which a `basic_json` value can be constructed.
|
||||
- **strings**: `string_t`, string literals, and all compatible string containers can be used.
|
||||
|
||||
Rvalue containers are moved from
|
||||
|
||||
If `val` is an rvalue of a compatible array-like or object-like container other than `array_t`/`object_t` (e.g., `json j = std::move(vec);` or `json j(std::vector<std::string>{...});`), the elements are moved into the JSON value instead of copied. Afterwards, the elements of the source container are in a valid but unspecified state (**moved-from**). Keys of associative containers are `const` and therefore still copied. Lvalues and `const` rvalues are copied, and the source is left unchanged.
|
||||
|
||||
- **numbers**: [`number_integer_t`](https://json.nlohmann.me/api/basic_json/number_integer_t/index.md), [`number_unsigned_t`](https://json.nlohmann.me/api/basic_json/number_unsigned_t/index.md), [`number_float_t`](https://json.nlohmann.me/api/basic_json/number_float_t/index.md), and all convertible number types such as `int`, `size_t`, `int64_t`, `float` or `double` can be used.
|
||||
- **boolean**: `boolean_t` / `bool` can be used.
|
||||
- **binary**: `binary_t` / `std::vector<uint8_t>` may be used; unfortunately because string literals cannot be distinguished from binary character arrays by the C++ type system, all types compatible with `const char*` will be directed to the string constructor instead. This is both for backwards compatibility and due to the fact that a binary type is not a standard JSON type.
|
||||
@@ -79,19 +84,21 @@ basic_json(basic_json&& other) noexcept;
|
||||
|
||||
```
|
||||
flowchart TD
|
||||
A(["initializer_list init"]) --> B{"empty, or every element is a 2-element<br/>array whose first element is a string?"}
|
||||
B -->|"yes"| C{"type_deduction"}
|
||||
B -->|"no"| D{"type_deduction"}
|
||||
A(["initializer_list init"]) --> B{{"empty, or every element is a 2-element<br/>array whose first element is a string?"}}
|
||||
B -->|"yes"| C{{"type_deduction"}}
|
||||
B -->|"no"| D{{"type_deduction"}}
|
||||
C -->|"true"| OBJ["create object"]
|
||||
C -->|"false"| E{"manual_type"}
|
||||
C -->|"false"| E{{"manual_type"}}
|
||||
E -->|"object"| OBJ
|
||||
E -->|"array"| ARR["create array"]
|
||||
D -->|"true"| ARR
|
||||
D -->|"false"| F{"manual_type"}
|
||||
D -->|"false"| F{{"manual_type"}}
|
||||
F -->|"array"| ARR
|
||||
F -->|"object"| ERR["throw type_error.301"]
|
||||
```
|
||||
|
||||
Decision flow for an initializer list: hexagons are checks, edge labels are their outcomes, and rectangles are the resulting value or exception.
|
||||
|
||||
The rules aim to create the best fit between a C++ initializer list and JSON values. The rationale is as follows:
|
||||
|
||||
1. The empty initializer list is written as `{}` which is exactly an empty JSON object.
|
||||
@@ -182,7 +189,7 @@ this requirement is not met.
|
||||
|
||||
1. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
|
||||
1. No-throw guarantee: this constructor never throws exceptions.
|
||||
1. Depends on the called constructor. For types directly supported by the library (i.e., all types for which no `to_json()` function was provided), a strong guarantee holds: if an exception is thrown, there are no changes to any JSON value.
|
||||
1. Depends on the called constructor. For types directly supported by the library (i.e., all types for which no `to_json()` function was provided), a strong guarantee holds: if an exception is thrown, there are no changes to any JSON value. **Exception:** when `val` is an rvalue array-like or object-like container, its elements are moved one by one; if an exception is thrown in the middle of the conversion (e.g., an allocation failure), the JSON value is unchanged, but the source container may be left partially moved-from.
|
||||
1. Depends on the called constructor. For types directly supported by the library (i.e., all types for which no `to_json()` function was provided), a strong guarantee holds: if an exception is thrown, there are no changes to any JSON value.
|
||||
1. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
|
||||
1. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
|
||||
@@ -266,7 +273,7 @@ The following code shows the constructor for different `value_t` values.
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -310,7 +317,7 @@ The following code shows the constructor with and without a null pointer paramet
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -347,7 +354,7 @@ The following code shows the constructor with several compatible types.
|
||||
#include <valarray>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -607,8 +614,8 @@ The example below shows how a `json` value is converted to an `ordered_json` val
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using ordered_json = nlohmann::ordered_json;
|
||||
using nlohmann::json;
|
||||
using nlohmann::ordered_json;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -644,7 +651,7 @@ The example below shows how JSON values are created from initializer lists.
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -682,7 +689,7 @@ The following code shows examples for creating arrays with several copies of a g
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -715,7 +722,7 @@ The example below shows several ways to create JSON values by specifying a subra
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -763,7 +770,7 @@ The following code shows an example for the copy constructor.
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -794,7 +801,7 @@ The code below shows the move constructor explicitly called via `std::move`.
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -819,20 +826,21 @@ null
|
||||
|
||||
## See also
|
||||
|
||||
- [array](https://json.nlohmann.me/api/basic_json/array/index.md) create a JSON array value, forcing array creation from an initializer list even when it looks like an object
|
||||
- [object](https://json.nlohmann.me/api/basic_json/object/index.md) create a JSON object value, forcing object creation from an initializer list
|
||||
- [binary](https://json.nlohmann.me/api/basic_json/binary/index.md) create a JSON binary array value
|
||||
- [operator=](https://json.nlohmann.me/api/basic_json/operator%3D/index.md) copy assignment operator
|
||||
- [`array`](https://json.nlohmann.me/api/basic_json/array/index.md) - create a JSON array value, forcing array creation from an initializer list even when it looks like an object
|
||||
- [`object`](https://json.nlohmann.me/api/basic_json/object/index.md) - create a JSON object value, forcing object creation from an initializer list
|
||||
- [`binary`](https://json.nlohmann.me/api/basic_json/binary/index.md) - create a JSON binary array value
|
||||
- [`operator=`](https://json.nlohmann.me/api/basic_json/operator%3D/index.md) - copy assignment operator
|
||||
- [Creating JSON values](https://json.nlohmann.me/features/creating_values/index.md) - the article on creating JSON values
|
||||
- [Converting values](https://json.nlohmann.me/features/conversions/index.md) - which C++ types can be converted
|
||||
|
||||
## Version history
|
||||
|
||||
1. Since version 1.0.0.
|
||||
1. Since version 1.0.0.
|
||||
1. Since version 2.1.0.
|
||||
1. Since version 3.2.0. Explicit for different string types if `JSON_USE_IMPLICIT_CONVERSIONS` is `0` since version 3.13.0 unreleased.
|
||||
1. Since version 1.0.0.
|
||||
1. Since version 1.0.0.
|
||||
1. Since version 1.0.0. Fixed in version 3.13.0 unreleased to also check the iterator range for binary values; before, a range that did not cover the whole value (such as `(end(), end())`) was accepted and the whole binary value was copied, unlike the other primitive types.
|
||||
1. Since version 1.0.0.
|
||||
1. Since version 1.0.0.
|
||||
1. Added in version 1.0.0.
|
||||
1. Added in version 1.0.0.
|
||||
1. Added in version 2.1.0.
|
||||
1. Added in version 3.1.2. Explicit for different string types if `JSON_USE_IMPLICIT_CONVERSIONS` is `0` since version 3.13.0 unreleased.
|
||||
1. Added in version 1.0.0.
|
||||
1. Added in version 1.0.0.
|
||||
1. Added in version 1.0.0. Fixed in version 3.13.0 unreleased to also check the iterator range for binary values; before, a range that did not cover the whole value (such as `(end(), end())`) was accepted and the whole binary value was copied, unlike the other primitive types.
|
||||
1. Added in version 1.0.0.
|
||||
1. Added in version 1.0.0.
|
||||
+59
-7
@@ -7,7 +7,40 @@ const_iterator begin() const noexcept;
|
||||
|
||||
Returns an iterator to the first element.
|
||||
|
||||
|
||||
<div class="nj-fig-wrap" markdown>
|
||||
<svg class="nj-fig nj-fig--range" viewBox="0 0 600 150" role="img" aria-labelledby="fig-be-title" xmlns="http://www.w3.org/2000/svg">
|
||||
<title id="fig-be-title">A row of fifteen elements followed by a dashed past-the-last position. begin() points to the first element and end() points to the past-the-last position.</title>
|
||||
<defs><marker id="fig-be-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path class="fg-head" d="M0 1 L10 5 L0 9 z"/></marker></defs>
|
||||
<rect class="fg-cell" x="30" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="64" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="98" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="132" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="166" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="200" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="234" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="268" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="302" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="336" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="370" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="404" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="438" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="472" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="506" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell fg-cell--end" x="540" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-pill" x="15" y="8" width="60" height="24" rx="6"/>
|
||||
<text class="fg-pilltext" x="45" y="24">begin</text>
|
||||
<line class="fg-arrow" x1="45" y1="32" x2="45" y2="60" marker-end="url(#fig-be-arrow)"/>
|
||||
<rect class="fg-pill" x="531" y="8" width="48" height="24" rx="6"/>
|
||||
<text class="fg-pilltext" x="555" y="24">end</text>
|
||||
<line class="fg-arrow" x1="555" y1="32" x2="555" y2="60" marker-end="url(#fig-be-arrow)"/>
|
||||
<text class="fg-note fg-note--r" x="537" y="132">Past-the-last element</text>
|
||||
<line class="fg-arrow" x1="555" y1="124" x2="555" y2="96" marker-end="url(#fig-be-arrow)"/>
|
||||
</svg>
|
||||
|
||||
</div>
|
||||
|
||||
<p class="nj-caption" markdown>`begin()` points to the first element and `end()` to the position after the last element;
|
||||
the dashed cell is the past-the-last position, which must not be dereferenced.</p>
|
||||
|
||||
## Return value
|
||||
|
||||
@@ -28,22 +61,41 @@ Constant.
|
||||
The following code shows an example for `begin()`.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/begin.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create an array value
|
||||
json array = {1, 2, 3, 4, 5};
|
||||
|
||||
// get an iterator to the first element
|
||||
json::iterator it = array.begin();
|
||||
|
||||
// serialize the element that the iterator points to
|
||||
std::cout << *it << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/begin.output"
|
||||
1
|
||||
|
||||
```
|
||||
|
||||
## 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
|
||||
- [`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
|
||||
- [`basic_json_view::begin`](../basic_json_view/begin.md) - the same iteration on a zero-copy view (in document order,
|
||||
not sorted by key)
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/begin/" rel="canonical"><link href=../back/ rel=prev><link href=../binary/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>begin - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../../css/custom.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsonbegin class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> begin </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> <div clLine truncated
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/begin/" rel="canonical"><link href=../back/ rel=prev><link href=../binary/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>begin - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel=stylesheet href=../../../css/custom.css><link rel=stylesheet href=../../../css/brand.css><link rel=stylesheet href=../../../css/fig-sax.css><link rel=stylesheet href=../../../css/fig-jsonview.css><link rel=stylesheet href=../../../css/fig-exceptions.css><link rel=stylesheet href=../../../css/fig-pointer.css><link rel=stylesheet href=../../../css/fig-charts.css><link rel=stylesheet href=../../../css/fig-integration.css><link rel=stylesheet href=../../../css/fig-macros.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsonbegin class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> begin </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61Line truncated
|
||||
<span class=n>const_iterator</span><span class=w> </span><span class=nf>begin</span><span class=p>()</span><span class=w> </span><span class=k>const</span><span class=w> </span><span class=k>noexcept</span><span class=p>;</span>
|
||||
</code></pre></div> <p>Returns an iterator to the first element.</p> <p><img alt="Illustration from cppreference.com" src=../../../images/range-begin-end.svg></p> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">¶</a></h2> <p>iterator to the first element</p> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">¶</a></h2> <p>No-throw guarantee: this member function never throws exceptions.</p> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">¶</a></h2> <p>Constant.</p> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example</summary> <p>The following code shows an example for <code>begin()</code>.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
</code></pre></div> <p>Returns an iterator to the first element.</p> <div class=nj-fig-wrap> <p><svg class="nj-fig nj-fig--range" viewbox="0 0 600 150" role=img aria-labelledby=fig-be-title xmlns=http://www.w3.org/2000/svg> <title id=fig-be-title>A row of fifteen elements followed by a dashed past-the-last position. begin() points to the first element and end() points to the past-the-last position.</title> <defs><marker id=fig-be-arrow viewbox="0 0 10 10" refx=9 refy=5 markerwidth=7 markerheight=7 orient=auto><path class=fg-head d="M0 1 L10 5 L0 9 z"/></marker></defs> <rect class=fg-cell x=30 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=64 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=98 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=132 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=166 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=200 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=234 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=268 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=302 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=336 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=370 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=404 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=438 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=472 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=506 y=62 width=30 height=30 rx=5 /> <rect x=540 y=62 width=30 height=30 rx=5 class="fg-cell fg-cell--end"/> <rect class=fg-pill x=15 y=8 width=60 height=24 rx=6 /> <text class=fg-pilltext x=45 y=24>begin</text> <line class=fg-arrow x1=45 y1=32 x2=45 y2=60 marker-end=url(#fig-be-arrow) /> <rect class=fg-pill x=531 y=8 width=48 height=24 rx=6 /> <text class=fg-pilltext x=555 y=24>end</text> <line class=fg-arrow x1=555 y1=32 x2=555 y2=60 marker-end=url(#fig-be-arrow) /> <text class="fg-note fg-note--r" x=537 y=132>Past-the-last element</text> <line class=fg-arrow x1=555 y1=124 x2=555 y2=96 marker-end=url(#fig-be-arrow) /> </svg></p> </div> <p class=nj-caption><code>begin()</code> points to the first element and <code>end()</code> to the position after the last element; the dashed cell is the past-the-last position, which must not be dereferenced.</p> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">¶</a></h2> <p>iterator to the first element</p> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">¶</a></h2> <p>No-throw guarantee: this member function never throws exceptions.</p> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">¶</a></h2> <p>Constant.</p> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example</summary> <p>The following code shows an example for <code>begin()</code>.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -17,4 +17,4 @@
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=o>*</span><span class=n>it</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code><span class=mi>1</span>
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../end/ >end</a> returns an iterator to one past the last element</li> <li><a href=../cbegin/ >cbegin</a> returns a const iterator to the first element</li> <li><a href=../rbegin/ >rbegin</a> returns a reverse iterator to the last element</li> <li><a href=../items/ >items</a> returns an iteration proxy to access keys and values during range-based for loops</li> <li><a href=../../../features/iterators/ >Iterators</a> - the article on iterators</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 1.0.0.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 2, 2026 09:32:15 UTC">October 2, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4C0 465.5 14.3 480 31.9 480H416c17.6 0 32-14.5 32-32.3V64.3c0-17.8-14.4-32.3-32-32.3M135.4 416H69V202.2h66.5V416zM102.2 96a38.5 38.5 0 1 1 0 77 38.5 38.5 0 1 1 0-77m282.1 320h-66.4V312c0-24.8-.5-56.7-34.5-56.7-34.6 0-39.9 27-39.9 54.9V416h-66.4V202.2h63.7v29.2h.9c8.9-16.8 30.6-34.5 62.9-34.5 67.2 0 79.7 44.Line truncated
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../end/ ><code>end</code></a> - returns an iterator to one past the last element</li> <li><a href=../cbegin/ ><code>cbegin</code></a> - returns a const iterator to the first element</li> <li><a href=../rbegin/ ><code>rbegin</code></a> - returns a reverse iterator to the last element</li> <li><a href=../items/ ><code>items</code></a> - returns an iteration proxy to access keys and values during range-based for loops</li> <li><a href=../../../features/iterators/ >Iterators</a> - the article on iterators</li> <li><a href=../../basic_json_view/begin/ ><code>basic_json_view::begin</code></a> - the same iteration on a zero-copy view (in document order, not sorted by key)</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 1.0.0.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../back/ class="md-footer__link md-footer__link--prev" aria-label="Previous: back"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> back </div> </div> </a> <a href=../binary/ class="md-footer__link md-footer__link--next" aria-label="Next: binary"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> binary </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3Line truncated
|
||||
@@ -7,6 +7,8 @@ const_iterator begin() const noexcept;
|
||||
|
||||
Returns an iterator to the first element.
|
||||
|
||||
`begin()` points to the first element and `end()` to the position after the last element; the dashed cell is the past-the-last position, which must not be dereferenced.
|
||||
|
||||
## Return value
|
||||
|
||||
iterator to the first element
|
||||
@@ -29,7 +31,7 @@ The following code shows an example for `begin()`.
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -52,11 +54,12 @@ Output:
|
||||
|
||||
## See also
|
||||
|
||||
- [end](https://json.nlohmann.me/api/basic_json/end/index.md) returns an iterator to one past the last element
|
||||
- [cbegin](https://json.nlohmann.me/api/basic_json/cbegin/index.md) returns a const iterator to the first element
|
||||
- [rbegin](https://json.nlohmann.me/api/basic_json/rbegin/index.md) returns a reverse iterator to the last element
|
||||
- [items](https://json.nlohmann.me/api/basic_json/items/index.md) returns an iteration proxy to access keys and values during range-based for loops
|
||||
- [`end`](https://json.nlohmann.me/api/basic_json/end/index.md) - returns an iterator to one past the last element
|
||||
- [`cbegin`](https://json.nlohmann.me/api/basic_json/cbegin/index.md) - returns a const iterator to the first element
|
||||
- [`rbegin`](https://json.nlohmann.me/api/basic_json/rbegin/index.md) - returns a reverse iterator to the last element
|
||||
- [`items`](https://json.nlohmann.me/api/basic_json/items/index.md) - returns an iteration proxy to access keys and values during range-based for loops
|
||||
- [Iterators](https://json.nlohmann.me/features/iterators/index.md) - the article on iterators
|
||||
- [`basic_json_view::begin`](https://json.nlohmann.me/api/basic_json_view/begin/index.md) - the same iteration on a zero-copy view (in document order, not sorted by key)
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -52,21 +52,39 @@ initialization of a binary array type, for backwards compatibility and so it doe
|
||||
The following code shows how to create a binary value.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/binary.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create a binary vector
|
||||
std::vector<std::uint8_t> vec = {0xCA, 0xFE, 0xBA, 0xBE};
|
||||
|
||||
// create a binary JSON value with subtype 42
|
||||
json j = json::binary(vec, 42);
|
||||
|
||||
// output type and subtype
|
||||
std::cout << "type: " << j.type_name() << ", subtype: " << j.get_binary().subtype() << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/binary.output"
|
||||
type: binary, subtype: 42
|
||||
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [binary_t](binary_t.md) type for binary values
|
||||
- [get_binary](get_binary.md) get a reference to the stored binary value
|
||||
- [is_binary](is_binary.md) return whether the value is binary
|
||||
- [byte_container_with_subtype](../byte_container_with_subtype/index.md) container for binary values with subtype
|
||||
- [Binary formats](../../features/binary_formats/index.md) - formats that can store binary values
|
||||
- [`binary_t`](binary_t.md) - type for binary values
|
||||
- [`get_binary`](get_binary.md) - get a reference to the stored binary value
|
||||
- [`is_binary`](is_binary.md) - return whether the value is binary
|
||||
- [`byte_container_with_subtype`](../byte_container_with_subtype/index.md) - container for binary values with subtype
|
||||
- [Binary Values](../../features/binary_values.md) - the article on binary values
|
||||
|
||||
## Version history
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/binary/" rel="canonical"><link href=../begin/ rel=prev><link href=../binary_t/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>binary - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../../css/custom.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsonbinary class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> binary </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> Line truncated
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/binary/" rel="canonical"><link href=../begin/ rel=prev><link href=../binary_t/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>binary - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel=stylesheet href=../../../css/custom.css><link rel=stylesheet href=../../../css/brand.css><link rel=stylesheet href=../../../css/fig-sax.css><link rel=stylesheet href=../../../css/fig-jsonview.css><link rel=stylesheet href=../../../css/fig-exceptions.css><link rel=stylesheet href=../../../css/fig-pointer.css><link rel=stylesheet href=../../../css/fig-charts.css><link rel=stylesheet href=../../../css/fig-integration.css><link rel=stylesheet href=../../../css/fig-macros.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsonbinary class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> binary </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5Line truncated
|
||||
<span class=k>static</span><span class=w> </span><span class=n>basic_json</span><span class=w> </span><span class=nf>binary</span><span class=p>(</span><span class=k>const</span><span class=w> </span><span class=k>typename</span><span class=w> </span><span class=nc>binary_t</span><span class=o>::</span><span class=n>container_type</span><span class=o>&</span><span class=w> </span><span class=n>init</span><span class=p>);</span>
|
||||
<span class=k>static</span><span class=w> </span><span class=n>basic_json</span><span class=w> </span><span class=nf>binary</span><span class=p>(</span><span class=k>typename</span><span class=w> </span><span class=nc>binary_t</span><span class=o>::</span><span class=n>container_type</span><span class=o>&&</span><span class=w> </span><span class=n>init</span><span class=p>);</span>
|
||||
|
||||
@@ -10,7 +10,7 @@
|
||||
</code></pre></div> <ol> <li>Creates a <abbr title="JavaScript Object Notation">JSON</abbr> binary array value from a given binary container.</li> <li>Creates a <abbr title="JavaScript Object Notation">JSON</abbr> binary array value from a given binary container with subtype.</li> </ol> <p>Binary values are part of various binary formats, such as <abbr title="Concise Binary Object Representation">CBOR</abbr>, MessagePack, and <abbr title="Binary JSON">BSON</abbr>. This constructor is used to create a value for serialization to those formats.</p> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">¶</a></h2> <dl> <dt><code>init</code> (in)</dt> <dd>container containing bytes to use as a binary type</dd> <dt><code>subtype</code> (in)</dt> <dd>subtype to use in <abbr title="Concise Binary Object Representation">CBOR</abbr>, MessagePack, and <abbr title="Binary JSON">BSON</abbr></dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">¶</a></h2> <p><abbr title="JavaScript Object Notation">JSON</abbr> binary array value</p> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">¶</a></h2> <p>Strong guarantee: if an exception is thrown, there are no changes in the <abbr title="JavaScript Object Notation">JSON</abbr> value.</p> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">¶</a></h2> <p>Linear in the size of <code>init</code>; constant for <code>typename binary_t::container_type&& init</code> versions.</p> <h2 id=notes>Notes<a class=headerlink href=#notes title="Permanent link">¶</a></h2> <p>Note, this function exists because of the difficulty in correctly specifying the correct template overload in the standard value ctor, as both <abbr title="JavaScript Object Notation">JSON</abbr> arrays and <abbr title="JavaScript Object Notation">JSON</abbr> binary arrays are backed with some form of a <code>std::vector</code>. Because <abbr title="JavaScript Object Notation">JSON</abbr> binary arrays are a non-standard extension, it was decided that it would be best to prevent automatic initialization of a binary array type, for backwards compatibility and so it does not happen on accident.</p> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example</summary> <p>The following code shows how to create a binary value.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -21,7 +21,7 @@
|
||||
<span class=w> </span><span class=n>json</span><span class=w> </span><span class=n>j</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>binary</span><span class=p>(</span><span class=n>vec</span><span class=p>,</span><span class=w> </span><span class=mi>42</span><span class=p>);</span>
|
||||
|
||||
<span class=w> </span><span class=c1>// output type and subtype</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=s>"type: "</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>j</span><span class=p>.</span><span class=n>type_name</span><span class=p>()</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=s>", subtype: "</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>j</span><span class=p>.</span><span class=n>get_binary</span><span class=p>().</span><span class=n>subtype</span><span class=p>()</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>endl</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=s>"type: "</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>j</span><span class=p>.</span><span class=n>type_name</span><span class=p>()</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=s>", subtype: "</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>j</span><span class=p>.</span><span class=n>get_binary</span><span class=p>().</span><span class=n>subtype</span><span class=p>()</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code><span class=kc>t</span><span class=err>ype</span><span class=p>:</span><span class=w> </span><span class=err>bi</span><span class=kc>nar</span><span class=err>y</span><span class=p>,</span><span class=w> </span><span class=err>sub</span><span class=kc>t</span><span class=err>ype</span><span class=p>:</span><span class=w> </span><span class=mi>42</span>
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../binary_t/ >binary_t</a> type for binary values</li> <li><a href=../get_binary/ >get_binary</a> get a reference to the stored binary value</li> <li><a href=../is_binary/ >is_binary</a> return whether the value is binary</li> <li><a href=../../byte_container_with_subtype/ >byte_container_with_subtype</a> container for binary values with subtype</li> <li><a href=../../../features/binary_values/ >Binary Values</a> - the article on binary values</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 3.8.0.</li> <li>Changed the type of <code>subtype</code> from <code>std::uint8_t</code> to <code>binary_t::subtype_type</code> (<code>std::uint64_t</code>) in version 3.10.0.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 2, 2026 09:32:15 UTC">October 2, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4C0 465.5 14.3 480 31.9 480H416c17.6 0 32-14.5 32-32.3V64.3c0-17.8-14.4-32.3-32-32.3M135.4 416H69V202.2h66.5V416zM102.2 96a38.5 38.5 0 1 1 Line truncated
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../../../features/binary_formats/ >Binary formats</a> - formats that can store binary values</li> <li><a href=../binary_t/ ><code>binary_t</code></a> - type for binary values</li> <li><a href=../get_binary/ ><code>get_binary</code></a> - get a reference to the stored binary value</li> <li><a href=../is_binary/ ><code>is_binary</code></a> - return whether the value is binary</li> <li><a href=../../byte_container_with_subtype/ ><code>byte_container_with_subtype</code></a> - container for binary values with subtype</li> <li><a href=../../../features/binary_values/ >Binary Values</a> - the article on binary values</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 3.8.0.</li> <li>Changed the type of <code>subtype</code> from <code>std::uint8_t</code> to <code>binary_t::subtype_type</code> (<code>std::uint64_t</code>) in version 3.10.0.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../begin/ class="md-footer__link md-footer__link--prev" aria-label="Previous: begin"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> begin </div> </div> </a> <a href=../binary_t/ class="md-footer__link md-footer__link--next" aria-label="Next: binary_t"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> binary_t </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 Line truncated
|
||||
@@ -49,7 +49,7 @@ The following code shows how to create a binary value.
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -60,7 +60,7 @@ int main()
|
||||
json j = json::binary(vec, 42);
|
||||
|
||||
// output type and subtype
|
||||
std::cout << "type: " << j.type_name() << ", subtype: " << j.get_binary().subtype() << std::endl;
|
||||
std::cout << "type: " << j.type_name() << ", subtype: " << j.get_binary().subtype() << '\n';
|
||||
}
|
||||
```
|
||||
|
||||
@@ -72,10 +72,11 @@ type: binary, subtype: 42
|
||||
|
||||
## See also
|
||||
|
||||
- [binary_t](https://json.nlohmann.me/api/basic_json/binary_t/index.md) type for binary values
|
||||
- [get_binary](https://json.nlohmann.me/api/basic_json/get_binary/index.md) get a reference to the stored binary value
|
||||
- [is_binary](https://json.nlohmann.me/api/basic_json/is_binary/index.md) return whether the value is binary
|
||||
- [byte_container_with_subtype](https://json.nlohmann.me/api/byte_container_with_subtype/index.md) container for binary values with subtype
|
||||
- [Binary formats](https://json.nlohmann.me/features/binary_formats/index.md) - formats that can store binary values
|
||||
- [`binary_t`](https://json.nlohmann.me/api/basic_json/binary_t/index.md) - type for binary values
|
||||
- [`get_binary`](https://json.nlohmann.me/api/basic_json/get_binary/index.md) - get a reference to the stored binary value
|
||||
- [`is_binary`](https://json.nlohmann.me/api/basic_json/is_binary/index.md) - return whether the value is binary
|
||||
- [`byte_container_with_subtype`](https://json.nlohmann.me/api/byte_container_with_subtype/index.md) - container for binary values with subtype
|
||||
- [Binary Values](https://json.nlohmann.me/features/binary_values/index.md) - the article on binary values
|
||||
|
||||
## Version history
|
||||
|
||||
+21
-18
@@ -41,7 +41,7 @@ represent a byte array in modern C++.
|
||||
[`byte_container_with_subtype`](../byte_container_with_subtype/index.md) derives directly from it. Its
|
||||
`value_type` must additionally be exactly one byte wide (e.g., `std::uint8_t`/`char`/`std::byte`): the binary
|
||||
serializers (CBOR, MessagePack, BSON, UBJSON) read and write the container's raw bytes via
|
||||
`reinterpret_cast`, which is only correct for byte-sized elements -- a container like
|
||||
`reinterpret_cast`, which is only correct for byte-sized elements — a container like
|
||||
`#!cpp std::vector<std::intptr_t>` will not work as `BinaryType`. The elements must be stored contiguously, and
|
||||
the binary readers additionally require `resize()` and `operator[]`. See
|
||||
[Template Parameter Requirements](../../features/types/template_parameters.md#binarytype) for the full list.
|
||||
@@ -64,18 +64,7 @@ values of that type directly to a `basic_json` instance, and they will automatic
|
||||
rather than 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
|
||||
>;
|
||||
using custom_json = nlohmann::ordered_json::with_binary_t<std::vector<std::byte>>;
|
||||
|
||||
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
|
||||
@@ -101,8 +90,9 @@ type `#!cpp binary_t*` must be dereferenced.
|
||||
|
||||
- MessagePack
|
||||
- If a subtype is given and the binary array contains exactly 1, 2, 4, 8, or 16 elements, the fixext family (fixext1,
|
||||
fixext2, fixext4, fixext8) is used. For other sizes, the ext family (ext8, ext16, ext32) is used. The subtype is
|
||||
then added as a signed 8-bit integer.
|
||||
fixext2, fixext4, fixext8, fixext16) is used. For other sizes, the ext family (ext8, ext16, ext32) is used. The
|
||||
subtype is then written as the signed 8-bit ext type: subtypes 128 to 255 map to the negative (reserved) ext
|
||||
types, and on reading the ext type is exposed as an unsigned subtype from 0 to 255.
|
||||
- If no subtype is given, the bin family (bin8, bin16, bin32) is used.
|
||||
|
||||
- BSON
|
||||
@@ -117,18 +107,31 @@ type `#!cpp binary_t*` must be dereferenced.
|
||||
`#!cpp nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>`.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/binary_t.cpp"
|
||||
#include <iostream>
|
||||
#include <iomanip>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
std::cout << std::boolalpha << std::is_same<nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>, json::binary_t>::value << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/binary_t.output"
|
||||
true
|
||||
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [byte_container_with_subtype](../byte_container_with_subtype/index.md)
|
||||
- [Binary values](../../features/binary_values.md) - how binary values and subtypes are handled
|
||||
- [Binary formats](../../features/binary_formats/index.md) - formats that can store binary values
|
||||
- [`byte_container_with_subtype`](../byte_container_with_subtype/index.md) - container type used by binary values
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -1,16 +1,5 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/binary_t/" rel="canonical"><link href=../binary/ rel=prev><link href=../boolean_t/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>binary_t - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../../css/custom.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsonbinary_t class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> binary_t </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg>Line truncated
|
||||
</code></pre></div> <p>This type is a type designed to carry binary data that appears in various serialized formats, such as <abbr title="Concise Binary Object Representation">CBOR</abbr>'s Major Type 2, MessagePack's bin, and <abbr title="Binary JSON">BSON</abbr>'s generic binary subtype. This type is NOT a part of standard <abbr title="JavaScript Object Notation">JSON</abbr> and exists solely for compatibility with these binary types. As such, it is simply defined as an ordered sequence of zero or more byte values.</p> <p>Additionally, as an implementation detail, the subtype of the binary data is carried around as a <code>std::uint64_t</code>, which is compatible with both of the binary data formats that use binary subtyping, (though the specific numbering is incompatible with each other, and it is up to the user to translate between them). The subtype is added to <code>BinaryType</code> via the helper type <a href=../../byte_container_with_subtype/ >byte_container_with_subtype</a>.</p> <p><a href="https://www.rfc-editor.org/rfc/rfc8949.html#section-3.1"><abbr title="Concise Binary Object Representation">CBOR</abbr>'s <abbr title="Request for Comments">RFC</abbr> 8949</a> describes this type as:</p> <blockquote> <p>Major type 2: A byte string. The number of bytes in the string is equal to the argument.</p> </blockquote> <p><a href="https://github.com/msgpack/msgpack/blob/master/spec.md#bin-format-family">MessagePack's documentation on the bin type family</a> describes this type as:</p> <blockquote> <p>Bin format family stores a byte array in 2, 3, or 5 bytes of extra bytes in addition to the size of the byte array.</p> </blockquote> <p><a href="http://bsonspec.org/spec.html"><abbr title="Binary JSON">BSON</abbr>'s specifications</a> describe several binary types; however, this type is intended to represent the generic binary type which has the description:</p> <blockquote> <p>Generic binary subtype - This is the most commonly used binary subtype and should be the 'default' for drivers and tools.</p> </blockquote> <p>None of these impose any limitations on the internal representation other than the basic unit of storage be some type of array whose parts are decomposable into bytes.</p> <p>The default representation of this binary format is a <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=kt>uint8_t</span><span class=o>></span></code>, which is a very common way to represent a byte array in modern C++.</p> <h2 id=template-parameters>Template parameters<a class=headerlink href=#template-parameters title="Permanent link">¶</a></h2> <dl> <dt><code>BinaryType</code></dt> <dd> <p>container type to store arrays</p> <p>Although not formally expressed as a C++ concept, <code>BinaryType</code> must be default-constructible, copy/move-constructible, and support <code>push_back()</code>, <code>.data()</code>, and <code>.size()</code>, because <a href=../../byte_container_with_subtype/ ><code>byte_container_with_subtype</code></a> derives directly from it. Its <code>value_type</code> must additionally be exactly one byte wide (e.g., <code>std::uint8_t</code>/<code>char</code>/<code>std::byte</code>): the binary serializers (<abbr title="Concise Binary Object Representation">CBOR</abbr>, MessagePack, <abbr title="Binary JSON">BSON</abbr>, <abbr title="Universal Binary JSON">UBJSON</abbr>) read and write the container's raw bytes via <code>reinterpret_cast</code>, which is only correct for byte-sized elements -- a container like <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=kt>intptr_t</span><span class=o>></span></code> will not work as <code>BinaryType</code>. The elements must be stored contiguously, and the binary readers additionally require <code>resize()</code> and <code>operator[]</code>. See <a href=../../../features/types/template_parameters/#binarytype>Template Parameter Requirements</a> for the full list.</p> </dd> </dl> <h2 id=notes>Notes<a class=headerlink href=#notes title="Permanent link">¶</a></h2> <h3 id=default-type>Default type<a class=headerlink href=#default-type title="Permanent link">¶</a></h3> <p>The default values for <code>BinaryType</code> is <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=kt>uint8_t</span><span class=o>></span></code>.</p> <h3 id=supported-byte-types>Supported byte types<a class=headerlink href=#supported-byte-types title="Permanent link">¶</a></h3> <p><code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=kt>uint8_t</span><span clLine truncated
|
||||
<span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>ordered_map</span><span class=p>,</span><span class=w> </span><span class=c1>// ObjectType</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=p>,</span><span class=w> </span><span class=c1>// ArrayType</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>string</span><span class=p>,</span><span class=w> </span><span class=c1>// StringType</span>
|
||||
<span class=w> </span><span class=kt>bool</span><span class=p>,</span><span class=w> </span><span class=c1>// BooleanType</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=kt>int64_t</span><span class=p>,</span><span class=w> </span><span class=c1>// NumberIntegerType</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=kt>uint64_t</span><span class=p>,</span><span class=w> </span><span class=c1>// NumberUnsignedType</span>
|
||||
<span class=w> </span><span class=kt>double</span><span class=p>,</span><span class=w> </span><span class=c1>// NumberFloatType</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>allocator</span><span class=p>,</span><span class=w> </span><span class=c1>// AllocatorType</span>
|
||||
<span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>adl_serializer</span><span class=p>,</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=kt>byte</span><span class=o>></span><span class=w> </span><span class=c1>// Custom BinaryType</span>
|
||||
<span class=o>></span><span class=p>;</span>
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/binary_t/" rel="canonical"><link href=../binary/ rel=prev><link href=../bjdata_version_t/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>binary_t - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel=stylesheet href=../../../css/custom.css><link rel=stylesheet href=../../../css/brand.css><link rel=stylesheet href=../../../css/fig-sax.css><link rel=stylesheet href=../../../css/fig-jsonview.css><link rel=stylesheet href=../../../css/fig-exceptions.css><link rel=stylesheet href=../../../css/fig-pointer.css><link rel=stylesheet href=../../../css/fig-charts.css><link rel=stylesheet href=../../../css/fig-integration.css><link rel=stylesheet href=../../../css/fig-macros.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsonbinary_t class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> binary_t </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5Line truncated
|
||||
</code></pre></div> <p>This type is a type designed to carry binary data that appears in various serialized formats, such as <abbr title="Concise Binary Object Representation">CBOR</abbr>'s Major Type 2, MessagePack's bin, and <abbr title="Binary JSON">BSON</abbr>'s generic binary subtype. This type is NOT a part of standard <abbr title="JavaScript Object Notation">JSON</abbr> and exists solely for compatibility with these binary types. As such, it is simply defined as an ordered sequence of zero or more byte values.</p> <p>Additionally, as an implementation detail, the subtype of the binary data is carried around as a <code>std::uint64_t</code>, which is compatible with both of the binary data formats that use binary subtyping, (though the specific numbering is incompatible with each other, and it is up to the user to translate between them). The subtype is added to <code>BinaryType</code> via the helper type <a href=../../byte_container_with_subtype/ >byte_container_with_subtype</a>.</p> <p><a href="https://www.rfc-editor.org/rfc/rfc8949.html#section-3.1"><abbr title="Concise Binary Object Representation">CBOR</abbr>'s <abbr title="Request for Comments">RFC</abbr> 8949</a> describes this type as:</p> <blockquote> <p>Major type 2: A byte string. The number of bytes in the string is equal to the argument.</p> </blockquote> <p><a href="https://github.com/msgpack/msgpack/blob/master/spec.md#bin-format-family">MessagePack's documentation on the bin type family</a> describes this type as:</p> <blockquote> <p>Bin format family stores a byte array in 2, 3, or 5 bytes of extra bytes in addition to the size of the byte array.</p> </blockquote> <p><a href="http://bsonspec.org/spec.html"><abbr title="Binary JSON">BSON</abbr>'s specifications</a> describe several binary types; however, this type is intended to represent the generic binary type which has the description:</p> <blockquote> <p>Generic binary subtype - This is the most commonly used binary subtype and should be the 'default' for drivers and tools.</p> </blockquote> <p>None of these impose any limitations on the internal representation other than the basic unit of storage be some type of array whose parts are decomposable into bytes.</p> <p>The default representation of this binary format is a <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=kt>uint8_t</span><span class=o>></span></code>, which is a very common way to represent a byte array in modern C++.</p> <h2 id=template-parameters>Template parameters<a class=headerlink href=#template-parameters title="Permanent link">¶</a></h2> <dl> <dt><code>BinaryType</code></dt> <dd> <p>container type to store arrays</p> <p>Although not formally expressed as a C++ concept, <code>BinaryType</code> must be default-constructible, copy/move-constructible, and support <code>push_back()</code>, <code>.data()</code>, and <code>.size()</code>, because <a href=../../byte_container_with_subtype/ ><code>byte_container_with_subtype</code></a> derives directly from it. Its <code>value_type</code> must additionally be exactly one byte wide (e.g., <code>std::uint8_t</code>/<code>char</code>/<code>std::byte</code>): the binary serializers (<abbr title="Concise Binary Object Representation">CBOR</abbr>, MessagePack, <abbr title="Binary JSON">BSON</abbr>, <abbr title="Universal Binary JSON">UBJSON</abbr>) read and write the container's raw bytes via <code>reinterpret_cast</code>, which is only correct for byte-sized elements — a container like <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=kt>intptr_t</span><span class=o>></span></code> will not work as <code>BinaryType</code>. The elements must be stored contiguously, and the binary readers additionally require <code>resize()</code> and <code>operator[]</code>. See <a href=../../../features/types/template_parameters/#binarytype>Template Parameter Requirements</a> for the full list.</p> </dd> </dl> <h2 id=notes>Notes<a class=headerlink href=#notes title="Permanent link">¶</a></h2> <h3 id=default-type>Default type<a class=headerlink href=#default-type title="Permanent link">¶</a></h3> <p>The default values for <code>BinaryType</code> is <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=kt>uint8_t</span><span class=o>></span></code>.</p> <h3 id=supported-byte-types>Supported byte types<a class=headerlink href=#supported-byte-types title="Permanent link">¶</a></h3> <p><code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=kt>uint8_t</span><span cLine truncated
|
||||
|
||||
<span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=kt>byte</span><span class=o>></span><span class=w> </span><span class=n>data</span><span class=p>{</span><span class=n>std</span><span class=o>::</span><span class=kt>byte</span><span class=p>{</span><span class=mi>1</span><span class=p>},</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=kt>byte</span><span class=p>{</span><span class=mi>2</span><span class=p>},</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=kt>byte</span><span class=p>{</span><span class=mi>3</span><span class=p>}};</span>
|
||||
<span class=n>custom_json</span><span class=w> </span><span class=n>j</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>data</span><span class=p>;</span><span class=w> </span><span class=c1>// Creates a binary value, not an array</span>
|
||||
@@ -19,15 +8,15 @@
|
||||
<span class=c1>// Round-tripping works seamlessly</span>
|
||||
<span class=k>auto</span><span class=w> </span><span class=n>extracted</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>j</span><span class=p>.</span><span class=n>get</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=kt>byte</span><span class=o>>></span><span class=p>();</span>
|
||||
<span class=n>assert</span><span class=p>(</span><span class=n>extracted</span><span class=w> </span><span class=o>==</span><span class=w> </span><span class=n>data</span><span class=p>);</span>
|
||||
</code></pre></div> <p>This automatic type detection is a convenience feature that only applies to custom (non-default) <code>BinaryType</code> configurations. The default <code>nlohmann::json</code> continues to treat <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=kt>uint8_t</span><span class=o>></span></code> as arrays for backward compatibility.</p> <h3 id=storage>Storage<a class=headerlink href=#storage title="Permanent link">¶</a></h3> <p>Binary Arrays are stored as pointers in a <code>basic_json</code> type. That is, for any access to array values, a pointer of the type <code class=highlight><span class=n>binary_t</span><span class=o>*</span></code> must be dereferenced.</p> <h3 id=notes-on-subtypes>Notes on subtypes<a class=headerlink href=#notes-on-subtypes title="Permanent link">¶</a></h3> <ul> <li> <p><abbr title="Concise Binary Object Representation">CBOR</abbr></p> <ul> <li>Binary values are represented as byte strings. Subtypes are written as tags.</li> </ul> </li> <li> <p>MessagePack</p> <ul> <li>If a subtype is given and the binary array contains exactly 1, 2, 4, 8, or 16 elements, the fixext family (fixext1, fixext2, fixext4, fixext8) is used. For other sizes, the ext family (ext8, ext16, ext32) is used. The subtype is then added as a signed 8-bit integer.</li> <li>If no subtype is given, the bin family (bin8, bin16, bin32) is used.</li> </ul> </li> <li> <p><abbr title="Binary JSON">BSON</abbr></p> <ul> <li>If a subtype is given, it is used and added as an unsigned 8-bit integer.</li> <li>If no subtype is given, the generic binary subtype 0x00 is used.</li> </ul> </li> </ul> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example</summary> <p>The following code shows that <code>binary_t</code> is by default, a typedef to <code class=highlight><span class=n>nlohmann</span><span class=o>::</span><span class=n>byte_container_with_subtype</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=kt>uint8_t</span><span class=o>>></span></code>.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
</code></pre></div> <p>This automatic type detection is a convenience feature that only applies to custom (non-default) <code>BinaryType</code> configurations. The default <code>nlohmann::json</code> continues to treat <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=kt>uint8_t</span><span class=o>></span></code> as arrays for backward compatibility.</p> <h3 id=storage>Storage<a class=headerlink href=#storage title="Permanent link">¶</a></h3> <p>Binary Arrays are stored as pointers in a <code>basic_json</code> type. That is, for any access to array values, a pointer of the type <code class=highlight><span class=n>binary_t</span><span class=o>*</span></code> must be dereferenced.</p> <h3 id=notes-on-subtypes>Notes on subtypes<a class=headerlink href=#notes-on-subtypes title="Permanent link">¶</a></h3> <ul> <li> <p><abbr title="Concise Binary Object Representation">CBOR</abbr></p> <ul> <li>Binary values are represented as byte strings. Subtypes are written as tags.</li> </ul> </li> <li> <p>MessagePack</p> <ul> <li>If a subtype is given and the binary array contains exactly 1, 2, 4, 8, or 16 elements, the fixext family (fixext1, fixext2, fixext4, fixext8, fixext16) is used. For other sizes, the ext family (ext8, ext16, ext32) is used. The subtype is then written as the signed 8-bit ext type: subtypes 128 to 255 map to the negative (reserved) ext types, and on reading the ext type is exposed as an unsigned subtype from 0 to 255.</li> <li>If no subtype is given, the bin family (bin8, bin16, bin32) is used.</li> </ul> </li> <li> <p><abbr title="Binary JSON">BSON</abbr></p> <ul> <li>If a subtype is given, it is used and added as an unsigned 8-bit integer.</li> <li>If no subtype is given, the generic binary subtype 0x00 is used.</li> </ul> </li> </ul> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example</summary> <p>The following code shows that <code>binary_t</code> is by default, a typedef to <code class=highlight><span class=n>nlohmann</span><span class=o>::</span><span class=n>byte_container_with_subtype</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=kt>uint8_t</span><span class=o>>></span></code>.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><iomanip></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>boolalpha</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>is_same</span><span class=o><</span><span class=n>nlohmann</span><span class=o>::</span><span class=n>byte_container_with_subtype</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=kt>uint8_t</span><span class=o>>></span><span class=p>,</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>binary_t</span><span class=o>>::</span><span class=n>value</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>endl</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>boolalpha</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>is_same</span><span class=o><</span><span class=n>nlohmann</span><span class=o>::</span><span class=n>byte_container_with_subtype</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=kt>uint8_t</span><span class=o>>></span><span class=p>,</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>binary_t</span><span class=o>>::</span><span class=n>value</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code><span class=kc>true</span>
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../../byte_container_with_subtype/ >byte_container_with_subtype</a></li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 3.8.0. Changed the type of subtype to <code>std::uint64_t</code> in version 3.10.0.</li> <li>Fixed <a href=../dump/ ><code>dump</code></a>, <a href=../std_hash/ ><code>std::hash</code></a>, and <a href=../to_ubjson/ ><code>to_ubjson</code></a> for byte types that are not integers (e.g., <code class=highlight><span class=n>std</span><span class=o>::</span><span class=kt>byte</span></code>) in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>. <code>dump</code> now writes the bytes of a signed byte type (e.g., <code class=highlight><span class=kt>char</span></code>) as 0..255 rather than as negative numbers.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 2, 2026 09:32:15 UTC">October 2, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4Line truncated
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../../../features/binary_values/ >Binary values</a> - how binary values and subtypes are handled</li> <li><a href=../../../features/binary_formats/ >Binary formats</a> - formats that can store binary values</li> <li><a href=../../byte_container_with_subtype/ ><code>byte_container_with_subtype</code></a> - container type used by binary values</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 3.8.0. Changed the type of subtype to <code>std::uint64_t</code> in version 3.10.0.</li> <li>Fixed <a href=../dump/ ><code>dump</code></a>, <a href=../std_hash/ ><code>std::hash</code></a>, and <a href=../to_ubjson/ ><code>to_ubjson</code></a> for byte types that are not integers (e.g., <code class=highlight><span class=n>std</span><span class=o>::</span><span class=kt>byte</span></code>) in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>. <code>dump</code> now writes the bytes of a signed byte type (e.g., <code class=highlight><span class=kt>char</span></code>) as 0..255 rather than as negative numbers.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../binary/ class="md-footer__link md-footer__link--prev" aria-label="Previous: binary"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> binary </div> </div> </a> <a href=../bjdata_version_t/ class="md-footer__link md-footer__link--next" aria-label="Next: bjdata_version_t"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> bjdata_version_t </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5Line truncated
|
||||
@@ -34,7 +34,7 @@ copy/move-constructible, and support `push_back()`, `.data()`, and `.size()`, be
|
||||
[`byte_container_with_subtype`](https://json.nlohmann.me/api/byte_container_with_subtype/index.md) derives directly from it. Its
|
||||
`value_type` must additionally be exactly one byte wide (e.g., `std::uint8_t`/`char`/`std::byte`): the binary
|
||||
serializers (CBOR, MessagePack, BSON, UBJSON) read and write the container's raw bytes via
|
||||
`reinterpret_cast`, which is only correct for byte-sized elements -- a container like
|
||||
`reinterpret_cast`, which is only correct for byte-sized elements — a container like
|
||||
`std::vector<std::intptr_t>` will not work as `BinaryType`. The elements must be stored contiguously, and
|
||||
the binary readers additionally require `resize()` and `operator[]`. See
|
||||
[Template Parameter Requirements](https://json.nlohmann.me/features/types/template_parameters/#binarytype) for the full list.
|
||||
@@ -55,18 +55,7 @@ The default values for `BinaryType` is `std::vector<std::uint8_t>`.
|
||||
When a custom `BinaryType` is configured (other than the default `std::vector<std::uint8_t>`), you can assign values of that type directly to a `basic_json` instance, and they will automatically be recognized as binary values rather than arrays:
|
||||
|
||||
```
|
||||
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
|
||||
>;
|
||||
using custom_json = nlohmann::ordered_json::with_binary_t<std::vector<std::byte>>;
|
||||
|
||||
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
|
||||
@@ -91,7 +80,7 @@ Binary Arrays are stored as pointers in a `basic_json` type. That is, for any ac
|
||||
|
||||
- MessagePack
|
||||
|
||||
- If a subtype is given and the binary array contains exactly 1, 2, 4, 8, or 16 elements, the fixext family (fixext1, fixext2, fixext4, fixext8) is used. For other sizes, the ext family (ext8, ext16, ext32) is used. The subtype is then added as a signed 8-bit integer.
|
||||
- If a subtype is given and the binary array contains exactly 1, 2, 4, 8, or 16 elements, the fixext family (fixext1, fixext2, fixext4, fixext8, fixext16) is used. For other sizes, the ext family (ext8, ext16, ext32) is used. The subtype is then written as the signed 8-bit ext type: subtypes 128 to 255 map to the negative (reserved) ext types, and on reading the ext type is exposed as an unsigned subtype from 0 to 255.
|
||||
- If no subtype is given, the bin family (bin8, bin16, bin32) is used.
|
||||
|
||||
- BSON
|
||||
@@ -110,11 +99,11 @@ The following code shows that `binary_t` is by default, a typedef to `nlohmann::
|
||||
#include <iomanip>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
std::cout << std::boolalpha << std::is_same<nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>, json::binary_t>::value << std::endl;
|
||||
std::cout << std::boolalpha << std::is_same<nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>, json::binary_t>::value << '\n';
|
||||
}
|
||||
```
|
||||
|
||||
@@ -126,7 +115,9 @@ true
|
||||
|
||||
## See also
|
||||
|
||||
- [byte_container_with_subtype](https://json.nlohmann.me/api/byte_container_with_subtype/index.md)
|
||||
- [Binary values](https://json.nlohmann.me/features/binary_values/index.md) - how binary values and subtypes are handled
|
||||
- [Binary formats](https://json.nlohmann.me/features/binary_formats/index.md) - formats that can store binary values
|
||||
- [`byte_container_with_subtype`](https://json.nlohmann.me/api/byte_container_with_subtype/index.md) - container type used by binary values
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -0,0 +1,85 @@
|
||||
# <small>nlohmann::basic_json::</small>bjdata_version_t
|
||||
|
||||
```cpp
|
||||
enum class bjdata_version_t
|
||||
{
|
||||
draft2,
|
||||
draft3
|
||||
};
|
||||
```
|
||||
|
||||
This enumeration is used in [`to_bjdata`](to_bjdata.md) to choose the version of the BJData specification to write:
|
||||
|
||||
draft2
|
||||
: BJData Draft 2 (the default). Binary values are written as arrays of `U` integers, and ND-arrays with
|
||||
`"_ArrayType_": "byte"` are written as regular objects, since the `B` marker is not part of Draft 2.
|
||||
|
||||
draft3
|
||||
: BJData Draft 3. Binary values are written as `B` elements: as an optimized binary array (`[$B#`) if both `use_size`
|
||||
and `use_type` are set, and as an array of `B`-prefixed elements otherwise. ND-arrays with
|
||||
`"_ArrayType_": "byte"` are written as packed arrays (`[$B#[...]`).
|
||||
|
||||
Only the writer is affected by the version. [`from_bjdata`](from_bjdata.md) reads the markers of both drafts.
|
||||
|
||||
## Examples
|
||||
|
||||
??? example
|
||||
|
||||
The example below shows how the different values of the `bjdata_version_t` influence the serialization of a binary
|
||||
value with [`to_bjdata`](to_bjdata.md).
|
||||
|
||||
```cpp
|
||||
#include <iomanip>
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
|
||||
void print_hex(const char* label, const std::vector<std::uint8_t>& v)
|
||||
{
|
||||
std::cout << label << ':';
|
||||
for (auto b : v)
|
||||
{
|
||||
std::cout << ' ' << std::hex << std::setw(2) << std::setfill('0') << static_cast<int>(b);
|
||||
}
|
||||
std::cout << std::dec << std::setfill(' ') << '\n';
|
||||
}
|
||||
|
||||
int main()
|
||||
{
|
||||
// a binary value
|
||||
json j = json::binary({0xCA, 0xFE, 0xBA, 0xBE});
|
||||
|
||||
// Draft 2 (the default) writes an array of integers
|
||||
auto v2 = json::to_bjdata(j, true, true, json::bjdata_version_t::draft2);
|
||||
print_hex("draft2", v2);
|
||||
|
||||
// Draft 3 writes an optimized binary array
|
||||
auto v3 = json::to_bjdata(j, true, true, json::bjdata_version_t::draft3);
|
||||
print_hex("draft3", v3);
|
||||
|
||||
// reading yields an array for Draft 2 and a binary value for Draft 3
|
||||
std::cout << json::from_bjdata(v2) << '\n';
|
||||
std::cout << json::from_bjdata(v3) << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
draft2: 5b 24 55 23 69 04 ca fe ba be
|
||||
draft3: 5b 24 42 23 69 04 ca fe ba be
|
||||
[202,254,186,190]
|
||||
{"bytes":[202,254,186,190],"subtype":null}
|
||||
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [to_bjdata](to_bjdata.md) serializes a JSON value to BJData
|
||||
- [BJData](../../features/binary_formats/bjdata.md) - the article on the BJData format
|
||||
|
||||
## Version history
|
||||
|
||||
- Added in version 3.12.0.
|
||||
@@ -0,0 +1,43 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/bjdata_version_t/" rel="canonical"><link href=../binary_t/ rel=prev><link href=../boolean_t/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>bjdata_version_t - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel=stylesheet href=../../../css/custom.css><link rel=stylesheet href=../../../css/brand.css><link rel=stylesheet href=../../../css/fig-sax.css><link rel=stylesheet href=../../../css/fig-jsonview.css><link rel=stylesheet href=../../../css/fig-exceptions.css><link rel=stylesheet href=../../../css/fig-pointer.css><link rel=stylesheet href=../../../css/fig-charts.css><link rel=stylesheet href=../../../css/fig-integration.css><link rel=stylesheet href=../../../css/fig-macros.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsonbjdata_version_t class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> bjdata_version_t </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0Line truncated
|
||||
<span class=p>{</span>
|
||||
<span class=w> </span><span class=n>draft2</span><span class=p>,</span>
|
||||
<span class=w> </span><span class=n>draft3</span>
|
||||
<span class=p>};</span>
|
||||
</code></pre></div> <p>This enumeration is used in <a href=../to_bjdata/ ><code>to_bjdata</code></a> to choose the version of the <abbr title="Binary JData">BJData</abbr> specification to write:</p> <dl> <dt>draft2</dt> <dd><abbr title="Binary JData">BJData</abbr> Draft 2 (the default). Binary values are written as arrays of <code>U</code> integers, and ND-arrays with <code>"_ArrayType_": "byte"</code> are written as regular objects, since the <code>B</code> marker is not part of Draft 2.</dd> <dt>draft3</dt> <dd><abbr title="Binary JData">BJData</abbr> Draft 3. Binary values are written as <code>B</code> elements: as an optimized binary array (<code>[$B#</code>) if both <code>use_size</code> and <code>use_type</code> are set, and as an array of <code>B</code>-prefixed elements otherwise. ND-arrays with <code>"_ArrayType_": "byte"</code> are written as packed arrays (<code>[$B#[...]</code>).</dd> </dl> <p>Only the writer is affected by the version. <a href=../from_bjdata/ ><code>from_bjdata</code></a> reads the markers of both drafts.</p> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example</summary> <p>The example below shows how the different values of the <code>bjdata_version_t</code> influence the serialization of a binary value with <a href=../to_bjdata/ ><code>to_bjdata</code></a>.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iomanip></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>void</span><span class=w> </span><span class=nf>print_hex</span><span class=p>(</span><span class=k>const</span><span class=w> </span><span class=kt>char</span><span class=o>*</span><span class=w> </span><span class=n>label</span><span class=p>,</span><span class=w> </span><span class=k>const</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=kt>uint8_t</span><span class=o>>&</span><span class=w> </span><span class=n>v</span><span class=p>)</span>
|
||||
<span class=p>{</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>label</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>':'</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=k>for</span><span class=w> </span><span class=p>(</span><span class=k>auto</span><span class=w> </span><span class=n>b</span><span class=w> </span><span class=o>:</span><span class=w> </span><span class=n>v</span><span class=p>)</span>
|
||||
<span class=w> </span><span class=p>{</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>' '</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>hex</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>setw</span><span class=p>(</span><span class=mi>2</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>setfill</span><span class=p>(</span><span class=sc>'0'</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=k>static_cast</span><span class=o><</span><span class=kt>int</span><span class=o>></span><span class=p>(</span><span class=n>b</span><span class=p>);</span>
|
||||
<span class=w> </span><span class=p>}</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>dec</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>setfill</span><span class=p>(</span><span class=sc>' '</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
<span class=p>}</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
<span class=w> </span><span class=c1>// a binary value</span>
|
||||
<span class=w> </span><span class=n>json</span><span class=w> </span><span class=n>j</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>binary</span><span class=p>({</span><span class=mh>0xCA</span><span class=p>,</span><span class=w> </span><span class=mh>0xFE</span><span class=p>,</span><span class=w> </span><span class=mh>0xBA</span><span class=p>,</span><span class=w> </span><span class=mh>0xBE</span><span class=p>});</span>
|
||||
|
||||
<span class=w> </span><span class=c1>// Draft 2 (the default) writes an array of integers</span>
|
||||
<span class=w> </span><span class=k>auto</span><span class=w> </span><span class=n>v2</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>to_bjdata</span><span class=p>(</span><span class=n>j</span><span class=p>,</span><span class=w> </span><span class=nb>true</span><span class=p>,</span><span class=w> </span><span class=nb>true</span><span class=p>,</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>bjdata_version_t</span><span class=o>::</span><span class=n>draft2</span><span class=p>);</span>
|
||||
<span class=w> </span><span class=n>print_hex</span><span class=p>(</span><span class=s>"draft2"</span><span class=p>,</span><span class=w> </span><span class=n>v2</span><span class=p>);</span>
|
||||
|
||||
<span class=w> </span><span class=c1>// Draft 3 writes an optimized binary array</span>
|
||||
<span class=w> </span><span class=k>auto</span><span class=w> </span><span class=n>v3</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>to_bjdata</span><span class=p>(</span><span class=n>j</span><span class=p>,</span><span class=w> </span><span class=nb>true</span><span class=p>,</span><span class=w> </span><span class=nb>true</span><span class=p>,</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>bjdata_version_t</span><span class=o>::</span><span class=n>draft3</span><span class=p>);</span>
|
||||
<span class=w> </span><span class=n>print_hex</span><span class=p>(</span><span class=s>"draft3"</span><span class=p>,</span><span class=w> </span><span class=n>v3</span><span class=p>);</span>
|
||||
|
||||
<span class=w> </span><span class=c1>// reading yields an array for Draft 2 and a binary value for Draft 3</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>from_bjdata</span><span class=p>(</span><span class=n>v2</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>from_bjdata</span><span class=p>(</span><span class=n>v3</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code><span class=err>dra</span><span class=kc>ft</span><span class=mi>2</span><span class=p>:</span><span class=w> </span><span class=mi>5</span><span class=err>b</span><span class=w> </span><span class=mi>24</span><span class=w> </span><span class=mi>55</span><span class=w> </span><span class=mi>23</span><span class=w> </span><span class=mi>69</span><span class=w> </span><span class=mi>04</span><span class=w> </span><span class=err>ca</span><span class=w> </span><span class=kc>fe</span><span class=w> </span><span class=err>ba</span><span class=w> </span><span class=err>be</span>
|
||||
<span class=err>dra</span><span class=kc>ft</span><span class=mi>3</span><span class=p>:</span><span class=w> </span><span class=mi>5</span><span class=err>b</span><span class=w> </span><span class=mi>24</span><span class=w> </span><span class=mi>42</span><span class=w> </span><span class=mi>23</span><span class=w> </span><span class=mi>69</span><span class=w> </span><span class=mi>04</span><span class=w> </span><span class=err>ca</span><span class=w> </span><span class=kc>fe</span><span class=w> </span><span class=err>ba</span><span class=w> </span><span class=err>be</span>
|
||||
<span class=p>[</span><span class=mi>202</span><span class=p>,</span><span class=mi>254</span><span class=p>,</span><span class=mi>186</span><span class=p>,</span><span class=mi>190</span><span class=p>]</span>
|
||||
<span class=p>{</span><span class=nt>"bytes"</span><span class=p>:[</span><span class=mi>202</span><span class=p>,</span><span class=mi>254</span><span class=p>,</span><span class=mi>186</span><span class=p>,</span><span class=mi>190</span><span class=p>],</span><span class=nt>"subtype"</span><span class=p>:</span><span class=kc>null</span><span class=p>}</span>
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../to_bjdata/ >to_bjdata</a> serializes a <abbr title="JavaScript Object Notation">JSON</abbr> value to <abbr title="Binary JData">BJData</abbr></li> <li><a href=../../../features/binary_formats/bjdata/ ><abbr title="Binary JData">BJData</abbr></a> - the article on the <abbr title="Binary JData">BJData</abbr> format</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 3.12.0.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 26, 2026 17:25:46 UTC">October 26, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../binary_t/ class="md-footer__link md-footer__link--prev" aria-label="Previous: binary_t"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> binary_t </div> </div> </a> <a href=../boolean_t/ class="md-footer__link md-footer__link--next" aria-label="Next: boolean_t"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> boolean_t </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/Line truncated
|
||||
@@ -0,0 +1,77 @@
|
||||
# nlohmann::basic_json::bjdata_version_t
|
||||
|
||||
```
|
||||
enum class bjdata_version_t
|
||||
{
|
||||
draft2,
|
||||
draft3
|
||||
};
|
||||
```
|
||||
|
||||
This enumeration is used in [`to_bjdata`](https://json.nlohmann.me/api/basic_json/to_bjdata/index.md) to choose the version of the BJData specification to write:
|
||||
|
||||
draft2 : BJData Draft 2 (the default). Binary values are written as arrays of `U` integers, and ND-arrays with `"_ArrayType_": "byte"` are written as regular objects, since the `B` marker is not part of Draft 2.
|
||||
|
||||
draft3 : BJData Draft 3. Binary values are written as `B` elements: as an optimized binary array (`[$B#`) if both `use_size` and `use_type` are set, and as an array of `B`-prefixed elements otherwise. ND-arrays with `"_ArrayType_": "byte"` are written as packed arrays (`[$B#[...]`).
|
||||
|
||||
Only the writer is affected by the version. [`from_bjdata`](https://json.nlohmann.me/api/basic_json/from_bjdata/index.md) reads the markers of both drafts.
|
||||
|
||||
## Examples
|
||||
|
||||
Example
|
||||
|
||||
The example below shows how the different values of the `bjdata_version_t` influence the serialization of a binary value with [`to_bjdata`](https://json.nlohmann.me/api/basic_json/to_bjdata/index.md).
|
||||
|
||||
```
|
||||
#include <iomanip>
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
|
||||
void print_hex(const char* label, const std::vector<std::uint8_t>& v)
|
||||
{
|
||||
std::cout << label << ':';
|
||||
for (auto b : v)
|
||||
{
|
||||
std::cout << ' ' << std::hex << std::setw(2) << std::setfill('0') << static_cast<int>(b);
|
||||
}
|
||||
std::cout << std::dec << std::setfill(' ') << '\n';
|
||||
}
|
||||
|
||||
int main()
|
||||
{
|
||||
// a binary value
|
||||
json j = json::binary({0xCA, 0xFE, 0xBA, 0xBE});
|
||||
|
||||
// Draft 2 (the default) writes an array of integers
|
||||
auto v2 = json::to_bjdata(j, true, true, json::bjdata_version_t::draft2);
|
||||
print_hex("draft2", v2);
|
||||
|
||||
// Draft 3 writes an optimized binary array
|
||||
auto v3 = json::to_bjdata(j, true, true, json::bjdata_version_t::draft3);
|
||||
print_hex("draft3", v3);
|
||||
|
||||
// reading yields an array for Draft 2 and a binary value for Draft 3
|
||||
std::cout << json::from_bjdata(v2) << '\n';
|
||||
std::cout << json::from_bjdata(v3) << '\n';
|
||||
}
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
draft2: 5b 24 55 23 69 04 ca fe ba be
|
||||
draft3: 5b 24 42 23 69 04 ca fe ba be
|
||||
[202,254,186,190]
|
||||
{"bytes":[202,254,186,190],"subtype":null}
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [to_bjdata](https://json.nlohmann.me/api/basic_json/to_bjdata/index.md) serializes a JSON value to BJData
|
||||
- [BJData](https://json.nlohmann.me/features/binary_formats/bjdata/index.md) - the article on the BJData format
|
||||
|
||||
## Version history
|
||||
|
||||
- Added in version 3.12.0.
|
||||
@@ -23,7 +23,7 @@ To store boolean values in C++, a type is defined by the template parameter `Bo
|
||||
|
||||
### Default type
|
||||
|
||||
With the default values for `BooleanType` (`#!cpp bool`), the default value for `boolean_t` is `#!cpp bool`.
|
||||
With the default values for `BooleanType` (`#!cpp bool`), the default type for `boolean_t` is `#!cpp bool`.
|
||||
|
||||
### Storage
|
||||
|
||||
@@ -36,18 +36,31 @@ Boolean values are stored directly inside a `basic_json` type.
|
||||
The following code shows that `boolean_t` is by default, a typedef to `#!cpp bool`.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/boolean_t.cpp"
|
||||
#include <iostream>
|
||||
#include <iomanip>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
std::cout << std::boolalpha << std::is_same<bool, json::boolean_t>::value << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/boolean_t.output"
|
||||
true
|
||||
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [is_boolean](is_boolean.md) checks whether the JSON value is a boolean
|
||||
- [`is_boolean`](is_boolean.md) - checks whether the JSON value is a boolean
|
||||
- [Types](../../features/types/index.md) - how booleans are stored
|
||||
- [Template Parameter Requirements](../../features/types/template_parameters.md) - requirements on the `BooleanType` template parameter
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -1,13 +1,13 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/boolean_t/" rel="canonical"><link href=../binary_t/ rel=prev><link href=../cbegin/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>boolean_t - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../../css/custom.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsonboolean_t class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> boolean_t </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></sLine truncated
|
||||
</code></pre></div> <p>The type used to store <abbr title="JavaScript Object Notation">JSON</abbr> booleans.</p> <p><a href="https://tools.ietf.org/html/rfc8259"><abbr title="Request for Comments">RFC</abbr> 8259</a> implicitly describes a boolean as a type which differentiates the two literals <code class=highlight><span class=kc>true</span></code> and <code class=highlight><span class=kc>false</span></code>.</p> <p>To store boolean values in C++, a type is defined by the template parameter <code>BooleanType</code> which chooses the type to use.</p> <h2 id=template-parameters>Template parameters<a class=headerlink href=#template-parameters title="Permanent link">¶</a></h2> <dl> <dt><code>BooleanType</code></dt> <dd>the type to store booleans. As it is stored directly inside a <code>basic_json</code> value (in a union), it must be a trivially default-constructible, trivially copyable, and trivially destructible type that is convertible to and from <code class=highlight><span class=kt>bool</span></code>. See <a href=../../../features/types/template_parameters/#booleantype>Template Parameter Requirements</a>.</dd> </dl> <h2 id=notes>Notes<a class=headerlink href=#notes title="Permanent link">¶</a></h2> <h3 id=default-type>Default type<a class=headerlink href=#default-type title="Permanent link">¶</a></h3> <p>With the default values for <code>BooleanType</code> (<code class=highlight><span class=kt>bool</span></code>), the default value for <code>boolean_t</code> is <code class=highlight><span class=kt>bool</span></code>.</p> <h3 id=storage>Storage<a class=headerlink href=#storage title="Permanent link">¶</a></h3> <p>Boolean values are stored directly inside a <code>basic_json</code> type.</p> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example</summary> <p>The following code shows that <code>boolean_t</code> is by default, a typedef to <code class=highlight><span class=kt>bool</span></code>.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/boolean_t/" rel="canonical"><link href=../bjdata_version_t/ rel=prev><link href=../cbegin/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>boolean_t - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel=stylesheet href=../../../css/custom.css><link rel=stylesheet href=../../../css/brand.css><link rel=stylesheet href=../../../css/fig-sax.css><link rel=stylesheet href=../../../css/fig-jsonview.css><link rel=stylesheet href=../../../css/fig-exceptions.css><link rel=stylesheet href=../../../css/fig-pointer.css><link rel=stylesheet href=../../../css/fig-charts.css><link rel=stylesheet href=../../../css/fig-integration.css><link rel=stylesheet href=../../../css/fig-macros.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsonboolean_t class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> boolean_t </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3Line truncated
|
||||
</code></pre></div> <p>The type used to store <abbr title="JavaScript Object Notation">JSON</abbr> booleans.</p> <p><a href="https://tools.ietf.org/html/rfc8259"><abbr title="Request for Comments">RFC</abbr> 8259</a> implicitly describes a boolean as a type which differentiates the two literals <code class=highlight><span class=kc>true</span></code> and <code class=highlight><span class=kc>false</span></code>.</p> <p>To store boolean values in C++, a type is defined by the template parameter <code>BooleanType</code> which chooses the type to use.</p> <h2 id=template-parameters>Template parameters<a class=headerlink href=#template-parameters title="Permanent link">¶</a></h2> <dl> <dt><code>BooleanType</code></dt> <dd>the type to store booleans. As it is stored directly inside a <code>basic_json</code> value (in a union), it must be a trivially default-constructible, trivially copyable, and trivially destructible type that is convertible to and from <code class=highlight><span class=kt>bool</span></code>. See <a href=../../../features/types/template_parameters/#booleantype>Template Parameter Requirements</a>.</dd> </dl> <h2 id=notes>Notes<a class=headerlink href=#notes title="Permanent link">¶</a></h2> <h3 id=default-type>Default type<a class=headerlink href=#default-type title="Permanent link">¶</a></h3> <p>With the default values for <code>BooleanType</code> (<code class=highlight><span class=kt>bool</span></code>), the default type for <code>boolean_t</code> is <code class=highlight><span class=kt>bool</span></code>.</p> <h3 id=storage>Storage<a class=headerlink href=#storage title="Permanent link">¶</a></h3> <p>Boolean values are stored directly inside a <code>basic_json</code> type.</p> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example</summary> <p>The following code shows that <code>boolean_t</code> is by default, a typedef to <code class=highlight><span class=kt>bool</span></code>.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><iomanip></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>boolalpha</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>is_same</span><span class=o><</span><span class=kt>bool</span><span class=p>,</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>boolean_t</span><span class=o>>::</span><span class=n>value</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>endl</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>boolalpha</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>is_same</span><span class=o><</span><span class=kt>bool</span><span class=p>,</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>boolean_t</span><span class=o>>::</span><span class=n>value</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code><span class=kc>true</span>
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../is_boolean/ >is_boolean</a> checks whether the <abbr title="JavaScript Object Notation">JSON</abbr> value is a boolean</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 1.0.0.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 2, 2026 09:32:15 UTC">October 2, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4C0 465.5 14.3 480 31.9 480H416c17.6 0 32-14.5 32-32.3V64.3c0-17.8-14.4-32.3-32-32.3M135.4 416H69V202.2h66.5V416zM102.2 96a38.5 38.5 0 1 1 0 77 38.5 38.5 0 1 1 0-77m282.1 320h-66.4V312c0-24.8-.5-56.7-34.5-56.7-34.6 0-39.9 27-39.9 54.9V416h-66.4V202.2h63.7v29.2h.9c8.9-16.8 30.6-34.5 62.9-34.5 67.2 0 79.7 44.3 79.7 101.9z"/></svg> </a> <a href="https://www.xing.com/profile/Niels_Lohmann" target="_blank" rel="noopener" title="www.xing.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 384 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/liLine truncated
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../is_boolean/ ><code>is_boolean</code></a> - checks whether the <abbr title="JavaScript Object Notation">JSON</abbr> value is a boolean</li> <li><a href=../../../features/types/ >Types</a> - how booleans are stored</li> <li><a href=../../../features/types/template_parameters/ >Template Parameter Requirements</a> - requirements on the <code>BooleanType</code> template parameter</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 1.0.0.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../bjdata_version_t/ class="md-footer__link md-footer__link--prev" aria-label="Previous: bjdata_version_t"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> bjdata_version_t </div> </div> </a> <a href=../cbegin/ class="md-footer__link md-footer__link--next" aria-label="Next: cbegin"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> cbegin </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.Line truncated
|
||||
@@ -18,7 +18,7 @@ To store boolean values in C++, a type is defined by the template parameter `Boo
|
||||
|
||||
### Default type
|
||||
|
||||
With the default values for `BooleanType` (`bool`), the default value for `boolean_t` is `bool`.
|
||||
With the default values for `BooleanType` (`bool`), the default type for `boolean_t` is `bool`.
|
||||
|
||||
### Storage
|
||||
|
||||
@@ -35,11 +35,11 @@ The following code shows that `boolean_t` is by default, a typedef to `bool`.
|
||||
#include <iomanip>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
std::cout << std::boolalpha << std::is_same<bool, json::boolean_t>::value << std::endl;
|
||||
std::cout << std::boolalpha << std::is_same<bool, json::boolean_t>::value << '\n';
|
||||
}
|
||||
```
|
||||
|
||||
@@ -51,7 +51,9 @@ true
|
||||
|
||||
## See also
|
||||
|
||||
- [is_boolean](https://json.nlohmann.me/api/basic_json/is_boolean/index.md) checks whether the JSON value is a boolean
|
||||
- [`is_boolean`](https://json.nlohmann.me/api/basic_json/is_boolean/index.md) - checks whether the JSON value is a boolean
|
||||
- [Types](https://json.nlohmann.me/features/types/index.md) - how booleans are stored
|
||||
- [Template Parameter Requirements](https://json.nlohmann.me/features/types/template_parameters/index.md) - requirements on the `BooleanType` template parameter
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -6,7 +6,40 @@ const_iterator cbegin() const noexcept;
|
||||
|
||||
Returns an iterator to the first element.
|
||||
|
||||
|
||||
<div class="nj-fig-wrap" markdown>
|
||||
<svg class="nj-fig nj-fig--range" viewBox="0 0 600 150" role="img" aria-labelledby="fig-be-title" xmlns="http://www.w3.org/2000/svg">
|
||||
<title id="fig-be-title">A row of fifteen elements followed by a dashed past-the-last position. begin() points to the first element and end() points to the past-the-last position.</title>
|
||||
<defs><marker id="fig-be-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path class="fg-head" d="M0 1 L10 5 L0 9 z"/></marker></defs>
|
||||
<rect class="fg-cell" x="30" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="64" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="98" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="132" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="166" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="200" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="234" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="268" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="302" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="336" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="370" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="404" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="438" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="472" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="506" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell fg-cell--end" x="540" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-pill" x="15" y="8" width="60" height="24" rx="6"/>
|
||||
<text class="fg-pilltext" x="45" y="24">begin</text>
|
||||
<line class="fg-arrow" x1="45" y1="32" x2="45" y2="60" marker-end="url(#fig-be-arrow)"/>
|
||||
<rect class="fg-pill" x="531" y="8" width="48" height="24" rx="6"/>
|
||||
<text class="fg-pilltext" x="555" y="24">end</text>
|
||||
<line class="fg-arrow" x1="555" y1="32" x2="555" y2="60" marker-end="url(#fig-be-arrow)"/>
|
||||
<text class="fg-note fg-note--r" x="537" y="132">Past-the-last element</text>
|
||||
<line class="fg-arrow" x1="555" y1="124" x2="555" y2="96" marker-end="url(#fig-be-arrow)"/>
|
||||
</svg>
|
||||
|
||||
</div>
|
||||
|
||||
<p class="nj-caption" markdown>`cbegin()` points to the first element, like `begin()`, and `end()` to the position after
|
||||
the last element; the dashed cell is the past-the-last position, which must not be dereferenced.</p>
|
||||
|
||||
## Return value
|
||||
|
||||
@@ -27,21 +60,39 @@ Constant.
|
||||
The following code shows an example for `cbegin()`.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/cbegin.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create an array value
|
||||
const json array = {1, 2, 3, 4, 5};
|
||||
|
||||
// get an iterator to the first element
|
||||
json::const_iterator it = array.cbegin();
|
||||
|
||||
// serialize the element that the iterator points to
|
||||
std::cout << *it << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/cbegin.output"
|
||||
1
|
||||
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [begin](begin.md) returns an iterator to the first element
|
||||
- [cend](cend.md) returns a const iterator to one past the last element
|
||||
- [crbegin](crbegin.md) returns a const reverse iterator to the last element
|
||||
- [`begin`](begin.md) - returns an iterator to the first element
|
||||
- [`cend`](cend.md) - returns a const iterator to one past the last element
|
||||
- [`crbegin`](crbegin.md) - returns a const reverse iterator to the last element
|
||||
- [Iterators](../../features/iterators.md) - the article on iterators
|
||||
- [`basic_json_view::cbegin`](../basic_json_view/cbegin.md) - the same iteration on a zero-copy view
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/cbegin/" rel="canonical"><link href=../boolean_t/ rel=prev><link href=../cbor_tag_handler_t/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>cbegin - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../../css/custom.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsoncbegin class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> cbegin </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></Line truncated
|
||||
</code></pre></div> <p>Returns an iterator to the first element.</p> <p><img alt="Illustration from cppreference.com" src=../../../images/range-begin-end.svg></p> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">¶</a></h2> <p>iterator to the first element</p> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">¶</a></h2> <p>No-throw guarantee: this member function never throws exceptions.</p> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">¶</a></h2> <p>Constant.</p> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example</summary> <p>The following code shows an example for <code>cbegin()</code>.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/cbegin/" rel="canonical"><link href=../boolean_t/ rel=prev><link href=../cbor_tag_handler_t/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>cbegin - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel=stylesheet href=../../../css/custom.css><link rel=stylesheet href=../../../css/brand.css><link rel=stylesheet href=../../../css/fig-sax.css><link rel=stylesheet href=../../../css/fig-jsonview.css><link rel=stylesheet href=../../../css/fig-exceptions.css><link rel=stylesheet href=../../../css/fig-pointer.css><link rel=stylesheet href=../../../css/fig-charts.css><link rel=stylesheet href=../../../css/fig-integration.css><link rel=stylesheet href=../../../css/fig-macros.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsoncbegin class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> cbegin </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.Line truncated
|
||||
</code></pre></div> <p>Returns an iterator to the first element.</p> <div class=nj-fig-wrap> <p><svg class="nj-fig nj-fig--range" viewbox="0 0 600 150" role=img aria-labelledby=fig-be-title xmlns=http://www.w3.org/2000/svg> <title id=fig-be-title>A row of fifteen elements followed by a dashed past-the-last position. begin() points to the first element and end() points to the past-the-last position.</title> <defs><marker id=fig-be-arrow viewbox="0 0 10 10" refx=9 refy=5 markerwidth=7 markerheight=7 orient=auto><path class=fg-head d="M0 1 L10 5 L0 9 z"/></marker></defs> <rect class=fg-cell x=30 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=64 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=98 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=132 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=166 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=200 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=234 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=268 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=302 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=336 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=370 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=404 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=438 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=472 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=506 y=62 width=30 height=30 rx=5 /> <rect x=540 y=62 width=30 height=30 rx=5 class="fg-cell fg-cell--end"/> <rect class=fg-pill x=15 y=8 width=60 height=24 rx=6 /> <text class=fg-pilltext x=45 y=24>begin</text> <line class=fg-arrow x1=45 y1=32 x2=45 y2=60 marker-end=url(#fig-be-arrow) /> <rect class=fg-pill x=531 y=8 width=48 height=24 rx=6 /> <text class=fg-pilltext x=555 y=24>end</text> <line class=fg-arrow x1=555 y1=32 x2=555 y2=60 marker-end=url(#fig-be-arrow) /> <text class="fg-note fg-note--r" x=537 y=132>Past-the-last element</text> <line class=fg-arrow x1=555 y1=124 x2=555 y2=96 marker-end=url(#fig-be-arrow) /> </svg></p> </div> <p class=nj-caption><code>cbegin()</code> points to the first element, like <code>begin()</code>, and <code>end()</code> to the position after the last element; the dashed cell is the past-the-last position, which must not be dereferenced.</p> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">¶</a></h2> <p>iterator to the first element</p> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">¶</a></h2> <p>No-throw guarantee: this member function never throws exceptions.</p> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">¶</a></h2> <p>Constant.</p> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example</summary> <p>The following code shows an example for <code>cbegin()</code>.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -16,4 +16,4 @@
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=o>*</span><span class=n>it</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code><span class=mi>1</span>
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../begin/ >begin</a> returns an iterator to the first element</li> <li><a href=../cend/ >cend</a> returns a const iterator to one past the last element</li> <li><a href=../crbegin/ >crbegin</a> returns a const reverse iterator to the last element</li> <li><a href=../../../features/iterators/ >Iterators</a> - the article on iterators</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 1.0.0.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 2, 2026 09:32:15 UTC">October 2, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4C0 465.5 14.3 480 31.9 480H416c17.6 0 32-14.5 32-32.3V64.3c0-17.8-14.4-32.3-32-32.3M135.4 416H69V202.2h66.5V416zM102.2 96a38.5 38.5 0 1 1 0 77 38.5 38.5 0 1 1 0-77m282.1 320h-66.4V312c0-24.8-.5-56.7-34.5-56.7-34.6 0-39.9 27-39.9 54.9V416h-66.4V202.2h63.7v29.2h.9c8.9-16.8 30.6-34.5 62.9-34.5 67.2 0 79.7 44.3 79.7 101.9z"/></svg> </a> <a href="https://www.xing.com/profile/Niels_Lohmann" target="_blank" rel="noopener" Line truncated
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../begin/ ><code>begin</code></a> - returns an iterator to the first element</li> <li><a href=../cend/ ><code>cend</code></a> - returns a const iterator to one past the last element</li> <li><a href=../crbegin/ ><code>crbegin</code></a> - returns a const reverse iterator to the last element</li> <li><a href=../../../features/iterators/ >Iterators</a> - the article on iterators</li> <li><a href=../../basic_json_view/cbegin/ ><code>basic_json_view::cbegin</code></a> - the same iteration on a zero-copy view</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 1.0.0.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../boolean_t/ class="md-footer__link md-footer__link--prev" aria-label="Previous: boolean_t"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> boolean_t </div> </div> </a> <a href=../cbor_tag_handler_t/ class="md-footer__link md-footer__link--next" aria-label="Next: cbor_tag_handler_t"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> cbor_tag_handler_t </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3Line truncated
|
||||
@@ -6,6 +6,8 @@ const_iterator cbegin() const noexcept;
|
||||
|
||||
Returns an iterator to the first element.
|
||||
|
||||
`cbegin()` points to the first element, like `begin()`, and `end()` to the position after the last element; the dashed cell is the past-the-last position, which must not be dereferenced.
|
||||
|
||||
## Return value
|
||||
|
||||
iterator to the first element
|
||||
@@ -28,7 +30,7 @@ The following code shows an example for `cbegin()`.
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -51,10 +53,11 @@ Output:
|
||||
|
||||
## See also
|
||||
|
||||
- [begin](https://json.nlohmann.me/api/basic_json/begin/index.md) returns an iterator to the first element
|
||||
- [cend](https://json.nlohmann.me/api/basic_json/cend/index.md) returns a const iterator to one past the last element
|
||||
- [crbegin](https://json.nlohmann.me/api/basic_json/crbegin/index.md) returns a const reverse iterator to the last element
|
||||
- [`begin`](https://json.nlohmann.me/api/basic_json/begin/index.md) - returns an iterator to the first element
|
||||
- [`cend`](https://json.nlohmann.me/api/basic_json/cend/index.md) - returns a const iterator to one past the last element
|
||||
- [`crbegin`](https://json.nlohmann.me/api/basic_json/crbegin/index.md) - returns a const reverse iterator to the last element
|
||||
- [Iterators](https://json.nlohmann.me/features/iterators/index.md) - the article on iterators
|
||||
- [`basic_json_view::cbegin`](https://json.nlohmann.me/api/basic_json_view/cbegin/index.md) - the same iteration on a zero-copy view
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -9,17 +9,19 @@ enum class cbor_tag_handler_t
|
||||
};
|
||||
```
|
||||
|
||||
This enumeration is used in the [`from_cbor`](from_cbor.md) function to choose how to treat tags:
|
||||
This enumeration is used in [`from_cbor`](from_cbor.md) and [`sax_parse`](sax_parse.md) to choose how to treat tags:
|
||||
|
||||
error
|
||||
: throw a `parse_error` exception in case of a tag
|
||||
: report a parse error in case of a tag (the `from_cbor` overloads throw a `parse_error` exception by default)
|
||||
|
||||
ignore
|
||||
: ignore tags
|
||||
: ignore tags (also in front of a text string map key)
|
||||
|
||||
store
|
||||
: store tagged byte strings (for bytes 0xd8..0xdb) as binary values with the tag as subtype; other tagged values are
|
||||
read as if the tag were ignored. If several tags precede a byte string, only the innermost one is stored.
|
||||
read as if the tag were ignored. If several tags precede a byte string, only the tag directly in front of it is
|
||||
stored, and only when it has the form 0xd8..0xdb (a tag 0..23 written as 0xc0..0xd7 is skipped). Tags in front of a
|
||||
text string map key are skipped.
|
||||
|
||||
## Examples
|
||||
|
||||
@@ -29,19 +31,51 @@ store
|
||||
[`from_cbor`](from_cbor.md) when reading a tagged byte string.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/cbor_tag_handler_t.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// tagged byte string
|
||||
std::vector<std::uint8_t> vec = {{0xd8, 0x42, 0x44, 0xcA, 0xfe, 0xba, 0xbe}};
|
||||
|
||||
// cbor_tag_handler_t::error throws
|
||||
try
|
||||
{
|
||||
auto b_throw_on_tag = json::from_cbor(vec, true, true, json::cbor_tag_handler_t::error);
|
||||
}
|
||||
catch (const json::parse_error& e)
|
||||
{
|
||||
std::cout << e.what() << '\n';
|
||||
}
|
||||
|
||||
// cbor_tag_handler_t::ignore ignores the tag
|
||||
auto b_ignore_tag = json::from_cbor(vec, true, true, json::cbor_tag_handler_t::ignore);
|
||||
std::cout << b_ignore_tag << '\n';
|
||||
|
||||
// cbor_tag_handler_t::store stores the tag as binary subtype
|
||||
auto b_store_tag = json::from_cbor(vec, true, true, json::cbor_tag_handler_t::store);
|
||||
std::cout << b_store_tag << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/cbor_tag_handler_t.output"
|
||||
[json.exception.parse_error.112] parse error at byte 1: syntax error while parsing CBOR value: invalid byte: 0xD8
|
||||
{"bytes":[202,254,186,190],"subtype":null}
|
||||
{"bytes":[202,254,186,190],"subtype":66}
|
||||
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [from_cbor](from_cbor.md) deserializes a JSON value from CBOR
|
||||
- [input_format_t](input_format_t.md) the enumeration of supported input formats
|
||||
- [Binary values](../../features/binary_values.md) - how binary values and subtypes are handled
|
||||
- [`from_cbor`](from_cbor.md) - deserializes a JSON value from CBOR
|
||||
- [`input_format_t`](input_format_t.md) - the enumeration of supported input formats
|
||||
- [CBOR](../../features/binary_formats/cbor.md) - the article on the CBOR format
|
||||
|
||||
## Version history
|
||||
|
||||
@@ -1,13 +1,13 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/cbor_tag_handler_t/" rel="canonical"><link href=../cbegin/ rel=prev><link href=../cend/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>cbor_tag_handler_t - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../../css/custom.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsoncbor_tag_handler_t class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> cbor_tag_handler_t </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 Line truncated
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/cbor_tag_handler_t/" rel="canonical"><link href=../cbegin/ rel=prev><link href=../cend/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>cbor_tag_handler_t - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel=stylesheet href=../../../css/custom.css><link rel=stylesheet href=../../../css/brand.css><link rel=stylesheet href=../../../css/fig-sax.css><link rel=stylesheet href=../../../css/fig-jsonview.css><link rel=stylesheet href=../../../css/fig-exceptions.css><link rel=stylesheet href=../../../css/fig-pointer.css><link rel=stylesheet href=../../../css/fig-charts.css><link rel=stylesheet href=../../../css/fig-integration.css><link rel=stylesheet href=../../../css/fig-macros.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsoncbor_tag_handler_t class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> cbor_tag_handler_t </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 Line truncated
|
||||
<span class=p>{</span>
|
||||
<span class=w> </span><span class=n>error</span><span class=p>,</span>
|
||||
<span class=w> </span><span class=n>ignore</span><span class=p>,</span>
|
||||
<span class=w> </span><span class=n>store</span>
|
||||
<span class=p>};</span>
|
||||
</code></pre></div> <p>This enumeration is used in the <a href=../from_cbor/ ><code>from_cbor</code></a> function to choose how to treat tags:</p> <dl> <dt>error</dt> <dd>throw a <code>parse_error</code> exception in case of a tag</dd> <dt>ignore</dt> <dd>ignore tags</dd> <dt>store</dt> <dd>store tagged byte strings (for bytes 0xd8..0xdb) as binary values with the tag as subtype; other tagged values are read as if the tag were ignored. If several tags precede a byte string, only the innermost one is stored.</dd> </dl> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example</summary> <p>The example below shows how the different values of the <code>cbor_tag_handler_t</code> influence the behavior of <a href=../from_cbor/ ><code>from_cbor</code></a> when reading a tagged byte string.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
</code></pre></div> <p>This enumeration is used in <a href=../from_cbor/ ><code>from_cbor</code></a> and <a href=../sax_parse/ ><code>sax_parse</code></a> to choose how to treat tags:</p> <dl> <dt>error</dt> <dd>report a parse error in case of a tag (the <code>from_cbor</code> overloads throw a <code>parse_error</code> exception by default)</dd> <dt>ignore</dt> <dd>ignore tags (also in front of a text string map key)</dd> <dt>store</dt> <dd>store tagged byte strings (for bytes 0xd8..0xdb) as binary values with the tag as subtype; other tagged values are read as if the tag were ignored. If several tags precede a byte string, only the tag directly in front of it is stored, and only when it has the form 0xd8..0xdb (a tag 0..23 written as 0xc0..0xd7 is skipped). Tags in front of a text string map key are skipped.</dd> </dl> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example</summary> <p>The example below shows how the different values of the <code>cbor_tag_handler_t</code> influence the behavior of <a href=../from_cbor/ ><code>from_cbor</code></a> when reading a tagged byte string.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -21,18 +21,18 @@
|
||||
<span class=w> </span><span class=p>}</span>
|
||||
<span class=w> </span><span class=k>catch</span><span class=w> </span><span class=p>(</span><span class=k>const</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>parse_error</span><span class=o>&</span><span class=w> </span><span class=n>e</span><span class=p>)</span>
|
||||
<span class=w> </span><span class=p>{</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>e</span><span class=p>.</span><span class=n>what</span><span class=p>()</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>endl</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>e</span><span class=p>.</span><span class=n>what</span><span class=p>()</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=p>}</span>
|
||||
|
||||
<span class=w> </span><span class=c1>// cbor_tag_handler_t::ignore ignores the tag</span>
|
||||
<span class=w> </span><span class=k>auto</span><span class=w> </span><span class=n>b_ignore_tag</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>from_cbor</span><span class=p>(</span><span class=n>vec</span><span class=p>,</span><span class=w> </span><span class=nb>true</span><span class=p>,</span><span class=w> </span><span class=nb>true</span><span class=p>,</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>cbor_tag_handler_t</span><span class=o>::</span><span class=n>ignore</span><span class=p>);</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>b_ignore_tag</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>endl</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>b_ignore_tag</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
|
||||
<span class=w> </span><span class=c1>// cbor_tag_handler_t::store stores the tag as binary subtype</span>
|
||||
<span class=w> </span><span class=k>auto</span><span class=w> </span><span class=n>b_store_tag</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>from_cbor</span><span class=p>(</span><span class=n>vec</span><span class=p>,</span><span class=w> </span><span class=nb>true</span><span class=p>,</span><span class=w> </span><span class=nb>true</span><span class=p>,</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>cbor_tag_handler_t</span><span class=o>::</span><span class=n>store</span><span class=p>);</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>b_store_tag</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>endl</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>b_store_tag</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code><span class=p>[</span><span class=err>jso</span><span class=kc>n</span><span class=err>.excep</span><span class=kc>t</span><span class=err>io</span><span class=kc>n</span><span class=err>.parse_error.</span><span class=mi>112</span><span class=p>]</span><span class=w> </span><span class=err>parse</span><span class=w> </span><span class=err>error</span><span class=w> </span><span class=err>a</span><span class=kc>t</span><span class=w> </span><span class=err>by</span><span class=kc>te</span><span class=w> </span><span class=mi>1</span><span class=p>:</span><span class=w> </span><span class=err>sy</span><span class=kc>nta</span><span class=err>x</span><span class=w> </span><span class=err>error</span><span class=w> </span><span class=err>while</span><span class=w> </span><span class=err>parsi</span><span class=kc>n</span><span class=err>g</span><span class=w> </span><span class=err>CBOR</span><span class=w> </span><span class=err>value</span><span class=p>:</span><span class=w> </span><span class=err>i</span><span class=kc>n</span><span class=err>valid</span><span class=w> </span><span class=err>by</span><span class=kc>te</span><span class=p>:</span><span class=w> </span><span class=mi>0</span><span class=err>xD</span><span class=mi>8</span>
|
||||
<span class=p>{</span><span class=nt>"bytes"</span><span class=p>:[</span><span class=mi>202</span><span class=p>,</span><span class=mi>254</span><span class=p>,</span><span class=mi>186</span><span class=p>,</span><span class=mi>190</span><span class=p>],</span><span class=nt>"subtype"</span><span class=p>:</span><span class=kc>null</span><span class=p>}</span>
|
||||
<span class=p>{</span><span class=nt>"bytes"</span><span class=p>:[</span><span class=mi>202</span><span class=p>,</span><span class=mi>254</span><span class=p>,</span><span class=mi>186</span><span class=p>,</span><span class=mi>190</span><span class=p>],</span><span class=nt>"subtype"</span><span class=p>:</span><span class=mi>66</span><span class=p>}</span>
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../from_cbor/ >from_cbor</a> deserializes a <abbr title="JavaScript Object Notation">JSON</abbr> value from <abbr title="Concise Binary Object Representation">CBOR</abbr></li> <li><a href=../input_format_t/ >input_format_t</a> the enumeration of supported input formats</li> <li><a href=../../../features/binary_formats/cbor/ ><abbr title="Concise Binary Object Representation">CBOR</abbr></a> - the article on the <abbr title="Concise Binary Object Representation">CBOR</abbr> format</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 3.9.0. Added value <code>store</code> in 3.10.0.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 2, 2026 09:32:15 UTC">October 2, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4C0 465.5 14.3 480 31.9 480H416c17.6 0 32-14.5 32-32.3V64.3c0-17.8-14.4-32.3-32-32.3M135.4 416H69V202.2h66.5V416zM102.2 96a38.5 38.5 0 1 1 0 77 38.5 38.5 0 1 1 0-77m282.1 320h-66.4V312c0-24.8-.5-56.7-34.5-56.7-34.6 0-39.9 27-39.Line truncated
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../../../features/binary_values/ >Binary values</a> - how binary values and subtypes are handled</li> <li><a href=../from_cbor/ ><code>from_cbor</code></a> - deserializes a <abbr title="JavaScript Object Notation">JSON</abbr> value from <abbr title="Concise Binary Object Representation">CBOR</abbr></li> <li><a href=../input_format_t/ ><code>input_format_t</code></a> - the enumeration of supported input formats</li> <li><a href=../../../features/binary_formats/cbor/ ><abbr title="Concise Binary Object Representation">CBOR</abbr></a> - the article on the <abbr title="Concise Binary Object Representation">CBOR</abbr> format</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 3.9.0. Added value <code>store</code> in 3.10.0.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../cbegin/ class="md-footer__link md-footer__link--prev" aria-label="Previous: cbegin"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> cbegin </div> </div> </a> <a href=../cend/ class="md-footer__link md-footer__link--next" aria-label="Next: cend"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> cend </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 Line truncated
|
||||
@@ -9,13 +9,13 @@ enum class cbor_tag_handler_t
|
||||
};
|
||||
```
|
||||
|
||||
This enumeration is used in the [`from_cbor`](https://json.nlohmann.me/api/basic_json/from_cbor/index.md) function to choose how to treat tags:
|
||||
This enumeration is used in [`from_cbor`](https://json.nlohmann.me/api/basic_json/from_cbor/index.md) and [`sax_parse`](https://json.nlohmann.me/api/basic_json/sax_parse/index.md) to choose how to treat tags:
|
||||
|
||||
error : throw a `parse_error` exception in case of a tag
|
||||
error : report a parse error in case of a tag (the `from_cbor` overloads throw a `parse_error` exception by default)
|
||||
|
||||
ignore : ignore tags
|
||||
ignore : ignore tags (also in front of a text string map key)
|
||||
|
||||
store : store tagged byte strings (for bytes 0xd8..0xdb) as binary values with the tag as subtype; other tagged values are read as if the tag were ignored. If several tags precede a byte string, only the innermost one is stored.
|
||||
store : store tagged byte strings (for bytes 0xd8..0xdb) as binary values with the tag as subtype; other tagged values are read as if the tag were ignored. If several tags precede a byte string, only the tag directly in front of it is stored, and only when it has the form 0xd8..0xdb (a tag 0..23 written as 0xc0..0xd7 is skipped). Tags in front of a text string map key are skipped.
|
||||
|
||||
## Examples
|
||||
|
||||
@@ -27,7 +27,7 @@ The example below shows how the different values of the `cbor_tag_handler_t` inf
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -41,16 +41,16 @@ int main()
|
||||
}
|
||||
catch (const json::parse_error& e)
|
||||
{
|
||||
std::cout << e.what() << std::endl;
|
||||
std::cout << e.what() << '\n';
|
||||
}
|
||||
|
||||
// cbor_tag_handler_t::ignore ignores the tag
|
||||
auto b_ignore_tag = json::from_cbor(vec, true, true, json::cbor_tag_handler_t::ignore);
|
||||
std::cout << b_ignore_tag << std::endl;
|
||||
std::cout << b_ignore_tag << '\n';
|
||||
|
||||
// cbor_tag_handler_t::store stores the tag as binary subtype
|
||||
auto b_store_tag = json::from_cbor(vec, true, true, json::cbor_tag_handler_t::store);
|
||||
std::cout << b_store_tag << std::endl;
|
||||
std::cout << b_store_tag << '\n';
|
||||
}
|
||||
```
|
||||
|
||||
@@ -64,8 +64,9 @@ Output:
|
||||
|
||||
## See also
|
||||
|
||||
- [from_cbor](https://json.nlohmann.me/api/basic_json/from_cbor/index.md) deserializes a JSON value from CBOR
|
||||
- [input_format_t](https://json.nlohmann.me/api/basic_json/input_format_t/index.md) the enumeration of supported input formats
|
||||
- [Binary values](https://json.nlohmann.me/features/binary_values/index.md) - how binary values and subtypes are handled
|
||||
- [`from_cbor`](https://json.nlohmann.me/api/basic_json/from_cbor/index.md) - deserializes a JSON value from CBOR
|
||||
- [`input_format_t`](https://json.nlohmann.me/api/basic_json/input_format_t/index.md) - the enumeration of supported input formats
|
||||
- [CBOR](https://json.nlohmann.me/features/binary_formats/cbor/index.md) - the article on the CBOR format
|
||||
|
||||
## Version history
|
||||
|
||||
+60
-6
@@ -6,7 +6,40 @@ const_iterator cend() const noexcept;
|
||||
|
||||
Returns an iterator to one past the last element.
|
||||
|
||||
|
||||
<div class="nj-fig-wrap" markdown>
|
||||
<svg class="nj-fig nj-fig--range" viewBox="0 0 600 150" role="img" aria-labelledby="fig-be-title" xmlns="http://www.w3.org/2000/svg">
|
||||
<title id="fig-be-title">A row of fifteen elements followed by a dashed past-the-last position. begin() points to the first element and end() points to the past-the-last position.</title>
|
||||
<defs><marker id="fig-be-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path class="fg-head" d="M0 1 L10 5 L0 9 z"/></marker></defs>
|
||||
<rect class="fg-cell" x="30" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="64" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="98" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="132" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="166" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="200" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="234" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="268" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="302" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="336" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="370" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="404" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="438" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="472" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="506" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell fg-cell--end" x="540" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-pill" x="15" y="8" width="60" height="24" rx="6"/>
|
||||
<text class="fg-pilltext" x="45" y="24">begin</text>
|
||||
<line class="fg-arrow" x1="45" y1="32" x2="45" y2="60" marker-end="url(#fig-be-arrow)"/>
|
||||
<rect class="fg-pill" x="531" y="8" width="48" height="24" rx="6"/>
|
||||
<text class="fg-pilltext" x="555" y="24">end</text>
|
||||
<line class="fg-arrow" x1="555" y1="32" x2="555" y2="60" marker-end="url(#fig-be-arrow)"/>
|
||||
<text class="fg-note fg-note--r" x="537" y="132">Past-the-last element</text>
|
||||
<line class="fg-arrow" x1="555" y1="124" x2="555" y2="96" marker-end="url(#fig-be-arrow)"/>
|
||||
</svg>
|
||||
|
||||
</div>
|
||||
|
||||
<p class="nj-caption" markdown>`cend()` points to the position after the last element, like `end()`, and `begin()` to
|
||||
the first element; the dashed cell is the past-the-last position, which must not be dereferenced.</p>
|
||||
|
||||
## Return value
|
||||
|
||||
@@ -27,21 +60,42 @@ Constant.
|
||||
The following code shows an example for `cend()`.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/cend.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create an array value
|
||||
json array = {1, 2, 3, 4, 5};
|
||||
|
||||
// get an iterator to one past the last element
|
||||
json::const_iterator it = array.cend();
|
||||
|
||||
// decrement the iterator to point to the last element
|
||||
--it;
|
||||
|
||||
// serialize the element that the iterator points to
|
||||
std::cout << *it << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/cend.output"
|
||||
5
|
||||
|
||||
```
|
||||
|
||||
## 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
|
||||
- [crend](crend.md) returns a const reverse iterator to one before the first element
|
||||
- [`end`](end.md) - returns an iterator to one past the last element
|
||||
- [`cbegin`](cbegin.md) - returns a const iterator to the first element
|
||||
- [`crend`](crend.md) - returns a const reverse iterator to one before the first element
|
||||
- [Iterators](../../features/iterators.md) - the article on iterators
|
||||
- [`basic_json_view::cend`](../basic_json_view/cend.md) - the same iteration on a zero-copy view
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/cend/" rel="canonical"><link href=../cbor_tag_handler_t/ rel=prev><link href=../clear/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>cend - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../../css/custom.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsoncend class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> cend </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </labelLine truncated
|
||||
</code></pre></div> <p>Returns an iterator to one past the last element.</p> <p><img alt="Illustration from cppreference.com" src=../../../images/range-begin-end.svg></p> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">¶</a></h2> <p>iterator one past the last element</p> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">¶</a></h2> <p>No-throw guarantee: this member function never throws exceptions.</p> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">¶</a></h2> <p>Constant.</p> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example</summary> <p>The following code shows an example for <code>cend()</code>.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/cend/" rel="canonical"><link href=../cbor_tag_handler_t/ rel=prev><link href=../clear/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>cend - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel=stylesheet href=../../../css/custom.css><link rel=stylesheet href=../../../css/brand.css><link rel=stylesheet href=../../../css/fig-sax.css><link rel=stylesheet href=../../../css/fig-jsonview.css><link rel=stylesheet href=../../../css/fig-exceptions.css><link rel=stylesheet href=../../../css/fig-pointer.css><link rel=stylesheet href=../../../css/fig-charts.css><link rel=stylesheet href=../../../css/fig-integration.css><link rel=stylesheet href=../../../css/fig-macros.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsoncend class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> cend </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9Line truncated
|
||||
</code></pre></div> <p>Returns an iterator to one past the last element.</p> <div class=nj-fig-wrap> <p><svg class="nj-fig nj-fig--range" viewbox="0 0 600 150" role=img aria-labelledby=fig-be-title xmlns=http://www.w3.org/2000/svg> <title id=fig-be-title>A row of fifteen elements followed by a dashed past-the-last position. begin() points to the first element and end() points to the past-the-last position.</title> <defs><marker id=fig-be-arrow viewbox="0 0 10 10" refx=9 refy=5 markerwidth=7 markerheight=7 orient=auto><path class=fg-head d="M0 1 L10 5 L0 9 z"/></marker></defs> <rect class=fg-cell x=30 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=64 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=98 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=132 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=166 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=200 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=234 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=268 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=302 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=336 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=370 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=404 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=438 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=472 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=506 y=62 width=30 height=30 rx=5 /> <rect x=540 y=62 width=30 height=30 rx=5 class="fg-cell fg-cell--end"/> <rect class=fg-pill x=15 y=8 width=60 height=24 rx=6 /> <text class=fg-pilltext x=45 y=24>begin</text> <line class=fg-arrow x1=45 y1=32 x2=45 y2=60 marker-end=url(#fig-be-arrow) /> <rect class=fg-pill x=531 y=8 width=48 height=24 rx=6 /> <text class=fg-pilltext x=555 y=24>end</text> <line class=fg-arrow x1=555 y1=32 x2=555 y2=60 marker-end=url(#fig-be-arrow) /> <text class="fg-note fg-note--r" x=537 y=132>Past-the-last element</text> <line class=fg-arrow x1=555 y1=124 x2=555 y2=96 marker-end=url(#fig-be-arrow) /> </svg></p> </div> <p class=nj-caption><code>cend()</code> points to the position after the last element, like <code>end()</code>, and <code>begin()</code> to the first element; the dashed cell is the past-the-last position, which must not be dereferenced.</p> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">¶</a></h2> <p>iterator one past the last element</p> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">¶</a></h2> <p>No-throw guarantee: this member function never throws exceptions.</p> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">¶</a></h2> <p>Constant.</p> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example</summary> <p>The following code shows an example for <code>cend()</code>.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -19,4 +19,4 @@
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=o>*</span><span class=n>it</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code><span class=mi>5</span>
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../end/ >end</a> returns an iterator to one past the last element</li> <li><a href=../cbegin/ >cbegin</a> returns a const iterator to the first element</li> <li><a href=../crend/ >crend</a> returns a const reverse iterator to one before the first element</li> <li><a href=../../../features/iterators/ >Iterators</a> - the article on iterators</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 1.0.0.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 2, 2026 09:32:15 UTC">October 2, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4C0 465.5 14.3 480 31.9 480H416c17.6 0 32-14.5 32-32.3V64.3c0-17.8-14.4-32.3-32-32.3M135.4 416H69V202.2h66.5V416zM102.2 96a38.5 38.5 0 1 1 0 77 38.5 38.5 0 1 1 0-77m282.1 320h-66.4V312c0-24.8-.5-56.7-34.5-56.7-34.6 0-39.9 27-39.9 54.9V416h-66.4V202.2h63.7v29.2h.9c8.9-16.8 30.6-34.5 62.9-34.5 67.2 0 79.7 44.3 79.7 101.9z"/></svg> </a> <a href="https://www.xing.com/profile/Niels_Lohmann" target="_blank" rel="noLine truncated
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../end/ ><code>end</code></a> - returns an iterator to one past the last element</li> <li><a href=../cbegin/ ><code>cbegin</code></a> - returns a const iterator to the first element</li> <li><a href=../crend/ ><code>crend</code></a> - returns a const reverse iterator to one before the first element</li> <li><a href=../../../features/iterators/ >Iterators</a> - the article on iterators</li> <li><a href=../../basic_json_view/cend/ ><code>basic_json_view::cend</code></a> - the same iteration on a zero-copy view</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 1.0.0.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../cbor_tag_handler_t/ class="md-footer__link md-footer__link--prev" aria-label="Previous: cbor_tag_handler_t"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> cbor_tag_handler_t </div> </div> </a> <a href=../clear/ class="md-footer__link md-footer__link--next" aria-label="Next: clear"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> clear </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3Line truncated
|
||||
@@ -6,6 +6,8 @@ const_iterator cend() const noexcept;
|
||||
|
||||
Returns an iterator to one past the last element.
|
||||
|
||||
`cend()` points to the position after the last element, like `end()`, and `begin()` to the first element; the dashed cell is the past-the-last position, which must not be dereferenced.
|
||||
|
||||
## Return value
|
||||
|
||||
iterator one past the last element
|
||||
@@ -28,7 +30,7 @@ The following code shows an example for `cend()`.
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -54,10 +56,11 @@ Output:
|
||||
|
||||
## See also
|
||||
|
||||
- [end](https://json.nlohmann.me/api/basic_json/end/index.md) returns an iterator to one past the last element
|
||||
- [cbegin](https://json.nlohmann.me/api/basic_json/cbegin/index.md) returns a const iterator to the first element
|
||||
- [crend](https://json.nlohmann.me/api/basic_json/crend/index.md) returns a const reverse iterator to one before the first element
|
||||
- [`end`](https://json.nlohmann.me/api/basic_json/end/index.md) - returns an iterator to one past the last element
|
||||
- [`cbegin`](https://json.nlohmann.me/api/basic_json/cbegin/index.md) - returns a const iterator to the first element
|
||||
- [`crend`](https://json.nlohmann.me/api/basic_json/crend/index.md) - returns a const reverse iterator to one before the first element
|
||||
- [Iterators](https://json.nlohmann.me/features/iterators/index.md) - the article on iterators
|
||||
- [`basic_json_view::cend`](https://json.nlohmann.me/api/basic_json_view/cend/index.md) - the same iteration on a zero-copy view
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
+46
-4
@@ -43,19 +43,61 @@ All iterators, pointers, and references related to this container are invalidate
|
||||
JSON types.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/clear.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create JSON values
|
||||
json j_null;
|
||||
json j_boolean = true;
|
||||
json j_number_integer = 17;
|
||||
json j_number_float = 23.42;
|
||||
json j_object = {{"one", 1}, {"two", 2}};
|
||||
json j_array = {1, 2, 4, 8, 16};
|
||||
json j_string = "Hello, world";
|
||||
|
||||
// call clear()
|
||||
j_null.clear();
|
||||
j_boolean.clear();
|
||||
j_number_integer.clear();
|
||||
j_number_float.clear();
|
||||
j_object.clear();
|
||||
j_array.clear();
|
||||
j_string.clear();
|
||||
|
||||
// serialize the cleared values()
|
||||
std::cout << j_null << '\n';
|
||||
std::cout << j_boolean << '\n';
|
||||
std::cout << j_number_integer << '\n';
|
||||
std::cout << j_number_float << '\n';
|
||||
std::cout << j_object << '\n';
|
||||
std::cout << j_array << '\n';
|
||||
std::cout << j_string << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/clear.output"
|
||||
null
|
||||
false
|
||||
0
|
||||
0.0
|
||||
{}
|
||||
[]
|
||||
""
|
||||
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [erase](erase.md) removes elements from a JSON value
|
||||
- [empty](empty.md) checks whether the JSON value has no elements
|
||||
- [`erase`](erase.md) - removes elements from a JSON value
|
||||
- [`empty`](empty.md) - checks whether the JSON value has no elements
|
||||
- [Modifying values](../../features/modifying_values.md) - the article on modifying values
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/clear/" rel="canonical"><link href=../cend/ rel=prev><link href=../contains/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>clear - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../../css/custom.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsonclear class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> clear </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> <div Line truncated
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/clear/" rel="canonical"><link href=../cend/ rel=prev><link href=../contains/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>clear - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel=stylesheet href=../../../css/custom.css><link rel=stylesheet href=../../../css/brand.css><link rel=stylesheet href=../../../css/fig-sax.css><link rel=stylesheet href=../../../css/fig-jsonview.css><link rel=stylesheet href=../../../css/fig-exceptions.css><link rel=stylesheet href=../../../css/fig-pointer.css><link rel=stylesheet href=../../../css/fig-charts.css><link rel=stylesheet href=../../../css/fig-integration.css><link rel=stylesheet href=../../../css/fig-macros.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsonclear class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> clear </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.Line truncated
|
||||
</code></pre></div> <p>Clears the content of a <abbr title="JavaScript Object Notation">JSON</abbr> value and resets it to the default value as if <a href=../basic_json/ ><code>basic_json(value_t)</code></a> would have been called with the current value type from <a href=../type/ ><code>type()</code></a>:</p> <table> <thead> <tr> <th>Value type</th> <th>initial value</th> </tr> </thead> <tbody> <tr> <td>null</td> <td><code>null</code></td> </tr> <tr> <td>boolean</td> <td><code>false</code></td> </tr> <tr> <td>string</td> <td><code>""</code></td> </tr> <tr> <td>number</td> <td><code>0</code></td> </tr> <tr> <td>binary</td> <td>An empty byte vector with no subtype</td> </tr> <tr> <td>object</td> <td><code>{}</code></td> </tr> <tr> <td>array</td> <td><code>[]</code></td> </tr> </tbody> </table> <p>Has the same effect as calling</p> <div class=highlight><pre><span></span><code><span class=o>*</span><span class=k>this</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>basic_json</span><span class=p>(</span><span class=n>type</span><span class=p>());</span>
|
||||
</code></pre></div> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">¶</a></h2> <p>No-throw guarantee: this function never throws exceptions.</p> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">¶</a></h2> <p>Linear in the size of the <abbr title="JavaScript Object Notation">JSON</abbr> value.</p> <h2 id=notes>Notes<a class=headerlink href=#notes title="Permanent link">¶</a></h2> <p>All iterators, pointers, and references related to this container are invalidated.</p> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example</summary> <p>The example below shows the effect of <code>clear()</code> to different <abbr title="JavaScript Object Notation">JSON</abbr> types.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -41,4 +41,4 @@
|
||||
<span class=p>{}</span>
|
||||
<span class=p>[]</span>
|
||||
<span class=s2>""</span>
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../erase/ >erase</a> removes elements from a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../empty/ >empty</a> checks whether the <abbr title="JavaScript Object Notation">JSON</abbr> value has no elements</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 1.0.0.</li> <li>Added support for binary types in version 3.8.0.</li> <li>Fixed in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span> to also clear the subtype of a binary value; before, the subtype was left unchanged.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 2, 2026 09:32:15 UTC">October 2, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4C0 465.5 14.3 480 31.9 480H416c17.6 0 32-14.5 32-32.3V64.3c0-17.8-14.4-32.3-32-32.3M135.4 416H69V202.2h66.5V416zM102.2 96a38.5 38.5 0 1 1 0 77 38.5 38.5 0 1 1 0-77m282.1 320h-66.4V312c0-24.8-.5-56.7-34.5-56.7-34.6 0-39.9 27-39.9Line truncated
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../erase/ ><code>erase</code></a> - removes elements from a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../empty/ ><code>empty</code></a> - checks whether the <abbr title="JavaScript Object Notation">JSON</abbr> value has no elements</li> <li><a href=../../../features/modifying_values/ >Modifying values</a> - the article on modifying values</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 1.0.0.</li> <li>Added support for binary types in version 3.8.0.</li> <li>Fixed in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span> to also clear the subtype of a binary value; before, the subtype was left unchanged.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../cend/ class="md-footer__link md-footer__link--prev" aria-label="Previous: cend"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> cend </div> </div> </a> <a href=../contains/ class="md-footer__link md-footer__link--next" aria-label="Next: contains"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> contains </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 Line truncated
|
||||
@@ -44,7 +44,7 @@ The example below shows the effect of `clear()` to different JSON types.
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -91,8 +91,9 @@ false
|
||||
|
||||
## See also
|
||||
|
||||
- [erase](https://json.nlohmann.me/api/basic_json/erase/index.md) removes elements from a JSON value
|
||||
- [empty](https://json.nlohmann.me/api/basic_json/empty/index.md) checks whether the JSON value has no elements
|
||||
- [`erase`](https://json.nlohmann.me/api/basic_json/erase/index.md) - removes elements from a JSON value
|
||||
- [`empty`](https://json.nlohmann.me/api/basic_json/empty/index.md) - checks whether the JSON value has no elements
|
||||
- [Modifying values](https://json.nlohmann.me/features/modifying_values/index.md) - the article on modifying values
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
+110
-13
@@ -10,6 +10,10 @@ bool contains(KeyType&& key) const;
|
||||
|
||||
// (3)
|
||||
bool contains(const json_pointer& ptr) const;
|
||||
|
||||
// (4)
|
||||
template<typename T>
|
||||
bool contains(T) const = delete;
|
||||
```
|
||||
|
||||
1. Check whether an element exists in a JSON object with a key equivalent to `key`. If the element is not found or the
|
||||
@@ -17,6 +21,9 @@ bool contains(const json_pointer& ptr) const;
|
||||
2. See 1. This overload is only available if `KeyType` is comparable with `#!cpp typename object_t::key_type` and
|
||||
`#!cpp typename object_comparator_t::is_transparent` denotes a type.
|
||||
3. Check whether the given JSON pointer `ptr` can be resolved in the current JSON value.
|
||||
4. Deleted: this overload is only available if `T` is an integral type and is declared as deleted, so that a call with
|
||||
an integer `key` (for example, `#!cpp j.contains(0)`) fails to compile. Otherwise, the integer literal `0` would convert to
|
||||
a null `#!cpp const char*` and, from there, to the key type, causing undefined behavior at runtime.
|
||||
|
||||
## Template parameters
|
||||
|
||||
@@ -39,6 +46,7 @@ bool contains(const json_pointer& ptr) const;
|
||||
is not an object, `#!cpp false` is returned.
|
||||
2. See 1.
|
||||
3. `#!cpp true` if the JSON pointer can be resolved to a stored value, `#!cpp false` otherwise.
|
||||
4. Deleted; a call with an integral argument does not compile.
|
||||
|
||||
## Exception safety
|
||||
|
||||
@@ -49,14 +57,22 @@ Strong exception safety: if an exception occurs, the original value stays intact
|
||||
1. The function does not throw exceptions.
|
||||
2. The function does not throw exceptions.
|
||||
3. The function does not throw exceptions.
|
||||
4. Deleted; a call with an integral argument does not compile.
|
||||
|
||||
## Complexity
|
||||
|
||||
Logarithmic in the size of the JSON object.
|
||||
1. Logarithmic in the size of the JSON object.
|
||||
2. Logarithmic in the size of the JSON object.
|
||||
3. At most one lookup per reference token of `ptr`, each logarithmic in the size of the container at that level:
|
||||
O(*n* log *m*) for *n* reference tokens and containers of size at most *m*.
|
||||
4. Deleted; a call with an integral argument does not compile.
|
||||
|
||||
## Notes
|
||||
|
||||
- This method always returns `#!cpp false` when executed on a JSON type that is not an object.
|
||||
- Overloads (1) and (2) always return `#!cpp false` when executed on a JSON type that is not an object. Overload (3)
|
||||
also works on arrays and on primitive values: the empty JSON pointer resolves in every JSON value (so
|
||||
`#!cpp json(1).contains(""_json_pointer)` returns `#!cpp true`), and `#!cpp json({1, 2}).contains("/1"_json_pointer)`
|
||||
returns `#!cpp true`.
|
||||
- This method can be executed on any JSON value type.
|
||||
- Calling this function with an integer argument (for example, `#!cpp contains(0)`) does not compile: such an argument
|
||||
would otherwise implicitly convert to a null `#!cpp const char*` and, from there, cause undefined behavior when
|
||||
@@ -86,13 +102,34 @@ Logarithmic in the size of the JSON object.
|
||||
The example shows how `contains()` is used.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/contains__object_t_key_type.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
using namespace nlohmann::literals;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create some JSON values
|
||||
json j_object = R"( {"key": "value"} )"_json;
|
||||
json j_array = R"( [1, 2, 3] )"_json;
|
||||
|
||||
// call contains
|
||||
std::cout << std::boolalpha <<
|
||||
"j_object contains 'key': " << j_object.contains("key") << '\n' <<
|
||||
"j_object contains 'another': " << j_object.contains("another") << '\n' <<
|
||||
"j_array contains 'key': " << j_array.contains("key") << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/contains__object_t_key_type.output"
|
||||
j_object contains 'key': true
|
||||
j_object contains 'another': false
|
||||
j_array contains 'key': false
|
||||
|
||||
```
|
||||
|
||||
??? example "Example: (2) check with key using string_view"
|
||||
@@ -100,13 +137,36 @@ Logarithmic in the size of the JSON object.
|
||||
The example shows how `contains()` is used.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/contains__keytype.c++17.cpp"
|
||||
#include <iostream>
|
||||
#include <string_view>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using namespace std::string_view_literals;
|
||||
using nlohmann::json;
|
||||
using namespace nlohmann::literals;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create some JSON values
|
||||
json j_object = R"( {"key": "value"} )"_json;
|
||||
json j_array = R"( [1, 2, 3] )"_json;
|
||||
|
||||
// call contains
|
||||
std::cout << std::boolalpha <<
|
||||
"j_object contains 'key': " << j_object.contains("key"sv) << '\n' <<
|
||||
"j_object contains 'another': " << j_object.contains("another"sv) << '\n' <<
|
||||
"j_array contains 'key': " << j_array.contains("key"sv) << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/contains__keytype.c++17.output"
|
||||
j_object contains 'key': true
|
||||
j_object contains 'another': false
|
||||
j_array contains 'key': false
|
||||
|
||||
```
|
||||
|
||||
??? example "Example: (3) check with JSON pointer"
|
||||
@@ -114,26 +174,63 @@ Logarithmic in the size of the JSON object.
|
||||
The example shows how `contains()` is used.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/contains__json_pointer.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
using namespace nlohmann::literals;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create a JSON value
|
||||
json j =
|
||||
{
|
||||
{"number", 1}, {"string", "foo"}, {"array", {1, 2}}
|
||||
};
|
||||
|
||||
std::cout << std::boolalpha
|
||||
<< j.contains("/number"_json_pointer) << '\n'
|
||||
<< j.contains("/string"_json_pointer) << '\n'
|
||||
<< j.contains("/array"_json_pointer) << '\n'
|
||||
<< j.contains("/array/1"_json_pointer) << '\n'
|
||||
<< j.contains("/array/-"_json_pointer) << '\n'
|
||||
<< j.contains("/array/4"_json_pointer) << '\n'
|
||||
<< j.contains("/baz"_json_pointer) << '\n'
|
||||
// an array index with a leading '0' is not found
|
||||
<< j.contains("/array/01"_json_pointer) << '\n'
|
||||
// an array index that is not a number is not found
|
||||
<< j.contains("/array/one"_json_pointer) << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/contains__json_pointer.output"
|
||||
true
|
||||
true
|
||||
true
|
||||
true
|
||||
false
|
||||
false
|
||||
false
|
||||
false
|
||||
false
|
||||
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [find](find.md) find a value in an object
|
||||
- [count](count.md) returns the number of occurrences of a key
|
||||
- [`find`](find.md) - find a value in an object
|
||||
- [`count`](count.md) - returns the number of occurrences of a key
|
||||
- [`basic_json_view::contains`](../basic_json_view/contains.md) - the same check on a zero-copy view
|
||||
- [Element Access](../../features/element_access/index.md#does-this-key-exist) - how to test whether a key exists
|
||||
|
||||
## Version history
|
||||
|
||||
1. Added in version 3.11.0.
|
||||
2. Added in version 3.6.0. Extended template `KeyType` to support comparable types in version 3.11.0. Fixed in
|
||||
version 3.13.0 to consistently accept `std::string_view`-convertible keys, as already supported by
|
||||
[`operator[]`](operator[].md), [`at`](at.md), [`value`](value.md), and other lookup functions.
|
||||
2. Added in version 3.6.0. Extended template `KeyType` to support comparable types in version 3.11.0. Support for keys
|
||||
convertible to `std::string_view` added in version 3.13.0, consistently across the lookup functions.
|
||||
3. Added in version 3.7.0.
|
||||
4. Deleted overloads for integral key types added in version 3.13.0 to reject such calls at compile time instead of
|
||||
causing undefined behavior at runtime.
|
||||
@@ -1,4 +1,4 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/contains/" rel="canonical"><link href=../clear/ rel=prev><link href=../count/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>contains - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../../css/custom.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsoncontains class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> contains </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </laLine truncated
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/contains/" rel="canonical"><link href=../clear/ rel=prev><link href=../count/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>contains - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel=stylesheet href=../../../css/custom.css><link rel=stylesheet href=../../../css/brand.css><link rel=stylesheet href=../../../css/fig-sax.css><link rel=stylesheet href=../../../css/fig-jsonview.css><link rel=stylesheet href=../../../css/fig-exceptions.css><link rel=stylesheet href=../../../css/fig-pointer.css><link rel=stylesheet href=../../../css/fig-charts.css><link rel=stylesheet href=../../../css/fig-integration.css><link rel=stylesheet href=../../../css/fig-macros.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsoncontains class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> contains </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 1Line truncated
|
||||
<span class=kt>bool</span><span class=w> </span><span class=nf>contains</span><span class=p>(</span><span class=k>const</span><span class=w> </span><span class=k>typename</span><span class=w> </span><span class=nc>object_t</span><span class=o>::</span><span class=n>key_type</span><span class=o>&</span><span class=w> </span><span class=n>key</span><span class=p>)</span><span class=w> </span><span class=k>const</span><span class=p>;</span>
|
||||
|
||||
<span class=c1>// (2)</span>
|
||||
@@ -7,10 +7,14 @@
|
||||
|
||||
<span class=c1>// (3)</span>
|
||||
<span class=kt>bool</span><span class=w> </span><span class=nf>contains</span><span class=p>(</span><span class=k>const</span><span class=w> </span><span class=n>json_pointer</span><span class=o>&</span><span class=w> </span><span class=n>ptr</span><span class=p>)</span><span class=w> </span><span class=k>const</span><span class=p>;</span>
|
||||
</code></pre></div> <ol> <li>Check whether an element exists in a <abbr title="JavaScript Object Notation">JSON</abbr> object with a key equivalent to <code>key</code>. If the element is not found or the <abbr title="JavaScript Object Notation">JSON</abbr> value is not an object, <code class=highlight><span class=nb>false</span></code> is returned.</li> <li>See 1. This overload is only available if <code>KeyType</code> is comparable with <code class=highlight><span class=k>typename</span><span class=w> </span><span class=nc>object_t</span><span class=o>::</span><span class=n>key_type</span></code> and <code class=highlight><span class=k>typename</span><span class=w> </span><span class=nc>object_comparator_t</span><span class=o>::</span><span class=n>is_transparent</span></code> denotes a type.</li> <li>Check whether the given <abbr title="JavaScript Object Notation">JSON</abbr> pointer <code>ptr</code> can be resolved in the current <abbr title="JavaScript Object Notation">JSON</abbr> value.</li> </ol> <h2 id=template-parameters>Template parameters<a class=headerlink href=#template-parameters title="Permanent link">¶</a></h2> <dl> <dt><code>KeyType</code></dt> <dd>A type for an object key other than <a href=../../json_pointer/ ><code>json_pointer</code></a> that is comparable with <a href=../string_t/ ><code>string_t</code></a> using <a href=../object_comparator_t/ ><code>object_comparator_t</code></a>. This can also be a string view (C++17).</dd> </dl> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">¶</a></h2> <dl> <dt><code>key</code> (in)</dt> <dd>key value to check its existence.</dd> <dt><code>ptr</code> (in)</dt> <dd><abbr title="JavaScript Object Notation">JSON</abbr> pointer to check its existence.</dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">¶</a></h2> <ol> <li><code class=highlight><span class=nb>true</span></code> if an element with specified <code>key</code> exists. If no such element with such a key is found or the <abbr title="JavaScript Object Notation">JSON</abbr> value is not an object, <code class=highlight><span class=nb>false</span></code> is returned.</li> <li>See 1.</li> <li><code class=highlight><span class=nb>true</span></code> if the <abbr title="JavaScript Object Notation">JSON</abbr> pointer can be resolved to a stored value, <code class=highlight><span class=nb>false</span></code> otherwise.</li> </ol> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">¶</a></h2> <p>Strong exception safety: if an exception occurs, the original value stays intact.</p> <h2 id=exceptions>Exceptions<a class=headerlink href=#exceptions title="Permanent link">¶</a></h2> <ol> <li>The function does not throw exceptions.</li> <li>The function does not throw exceptions.</li> <li>The function does not throw exceptions.</li> </ol> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">¶</a></h2> <p>Logarithmic in the size of the <abbr title="JavaScript Object Notation">JSON</abbr> object.</p> <h2 id=notes>Notes<a class=headerlink href=#notes title="Permanent link">¶</a></h2> <ul> <li>This method always returns <code class=highlight><span class=nb>false</span></code> when executed on a <abbr title="JavaScript Object Notation">JSON</abbr> type that is not an object.</li> <li>This method can be executed on any <abbr title="JavaScript Object Notation">JSON</abbr> value type.</li> <li>Calling this function with an integer argument (for example, <code class=highlight><span class=n>contains</span><span class=p>(</span><span class=mi>0</span><span class=p>)</span></code>) does not compile: such an argument would otherwise implicitly convert to a null <code class=highlight><span class=k>const</span><span class=w> </span><span class=kt>char</span><span class=o>*</span></code> and, from there, cause undefined behavior when constructing a <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>string</span></code> for the object key. To check for an array element instead, use <a href=../at/ ><code>at</code></a>, <a href=../operator%5B%5D/ ><code>operator[]</code></a>, or compare against <a href=../size/ ><code>size</code></a>.</li> </ul> <div class="admonition info"> <p class=admonition-title>Postconditions</p> <p>If <code class=highlight><span class=n>j</span><span class=p>.</span><span class=n>contains</span><span class=p>(</span><span class=n>x</span><span class=p>)</span></code> returns <code class=highlight><span class=nb>true</span></code> for a key or <abbr title="JavaScript Object Notation">JSON</abbr> pointer <code>x</code>, then it is safe to call <code>j[x]</code>.</p> </div> <div class="admonition warning"> <p class=admonition-title>Deprecation</p> <p>Overload (3) also accepts a <a href=../../json_pointer/ ><code>json_pointer</code></a> whose template argument iLine truncated
|
||||
|
||||
<span class=c1>// (4)</span>
|
||||
<span class=k>template</span><span class=o><</span><span class=k>typename</span><span class=w> </span><span class=nc>T</span><span class=o>></span>
|
||||
<span class=kt>bool</span><span class=w> </span><span class=n>contains</span><span class=p>(</span><span class=n>T</span><span class=p>)</span><span class=w> </span><span class=k>const</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=k>delete</span><span class=p>;</span>
|
||||
</code></pre></div> <ol> <li>Check whether an element exists in a <abbr title="JavaScript Object Notation">JSON</abbr> object with a key equivalent to <code>key</code>. If the element is not found or the <abbr title="JavaScript Object Notation">JSON</abbr> value is not an object, <code class=highlight><span class=nb>false</span></code> is returned.</li> <li>See 1. This overload is only available if <code>KeyType</code> is comparable with <code class=highlight><span class=k>typename</span><span class=w> </span><span class=nc>object_t</span><span class=o>::</span><span class=n>key_type</span></code> and <code class=highlight><span class=k>typename</span><span class=w> </span><span class=nc>object_comparator_t</span><span class=o>::</span><span class=n>is_transparent</span></code> denotes a type.</li> <li>Check whether the given <abbr title="JavaScript Object Notation">JSON</abbr> pointer <code>ptr</code> can be resolved in the current <abbr title="JavaScript Object Notation">JSON</abbr> value.</li> <li>Deleted: this overload is only available if <code>T</code> is an integral type and is declared as deleted, so that a call with an integer <code>key</code> (for example, <code class=highlight><span class=n>j</span><span class=p>.</span><span class=n>contains</span><span class=p>(</span><span class=mi>0</span><span class=p>)</span></code>) fails to compile. Otherwise, the integer literal <code>0</code> would convert to a null <code class=highlight><span class=k>const</span><span class=w> </span><span class=kt>char</span><span class=o>*</span></code> and, from there, to the key type, causing undefined behavior at runtime.</li> </ol> <h2 id=template-parameters>Template parameters<a class=headerlink href=#template-parameters title="Permanent link">¶</a></h2> <dl> <dt><code>KeyType</code></dt> <dd>A type for an object key other than <a href=../../json_pointer/ ><code>json_pointer</code></a> that is comparable with <a href=../string_t/ ><code>string_t</code></a> using <a href=../object_comparator_t/ ><code>object_comparator_t</code></a>. This can also be a string view (C++17).</dd> </dl> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">¶</a></h2> <dl> <dt><code>key</code> (in)</dt> <dd>key value to check its existence.</dd> <dt><code>ptr</code> (in)</dt> <dd><abbr title="JavaScript Object Notation">JSON</abbr> pointer to check its existence.</dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">¶</a></h2> <ol> <li><code class=highlight><span class=nb>true</span></code> if an element with specified <code>key</code> exists. If no such element with such a key is found or the <abbr title="JavaScript Object Notation">JSON</abbr> value is not an object, <code class=highlight><span class=nb>false</span></code> is returned.</li> <li>See 1.</li> <li><code class=highlight><span class=nb>true</span></code> if the <abbr title="JavaScript Object Notation">JSON</abbr> pointer can be resolved to a stored value, <code class=highlight><span class=nb>false</span></code> otherwise.</li> <li>Deleted; a call with an integral argument does not compile.</li> </ol> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">¶</a></h2> <p>Strong exception safety: if an exception occurs, the original value stays intact.</p> <h2 id=exceptions>Exceptions<a class=headerlink href=#exceptions title="Permanent link">¶</a></h2> <ol> <li>The function does not throw exceptions.</li> <li>The function does not throw exceptions.</li> <li>The function does not throw exceptions.</li> <li>Deleted; a call with an integral argument does not compile.</li> </ol> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">¶</a></h2> <ol> <li>Logarithmic in the size of the <abbr title="JavaScript Object Notation">JSON</abbr> object.</li> <li>Logarithmic in the size of the <abbr title="JavaScript Object Notation">JSON</abbr> object.</li> <li>At most one lookup per reference token of <code>ptr</code>, each logarithmic in the size of the container at that level: O(<em>n</em> log <em>m</em>) for <em>n</em> reference tokens and containers of size at most <em>m</em>.</li> <li>Deleted; a call with an integral argument does not compile.</li> </ol> <h2 id=notes>Notes<a class=headerlink href=#notes title="Permanent link">¶</a></h2> <ul> <li>Overloads (1) and (2) always return <code class=highlight><span class=nb>false</span></code> when executed on a <abbr title="JavaScript Object Notation">JSON</abbr> type that is not an object. Overload (3) also works on arrays and on primitive values: the empty <abbr title="JavaScript Object Notation">JSON</abbr> pointer resolves in every <abbr title="JavaScript Object Notation">JSON</abbr> value (so <code class=highlight><span class=n>json</span><span class=p>(</span><span class=mi>1</span><span class=p>).</span><span class=n>contains</spanLine truncated
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=k>namespace</span><span class=w> </span><span class=nn>nlohmann</span><span class=o>::</span><span class=nn>literals</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
@@ -23,7 +27,7 @@
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>boolalpha</span><span class=w> </span><span class=o><<</span>
|
||||
<span class=w> </span><span class=s>"j_object contains 'key': "</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>j_object</span><span class=p>.</span><span class=n>contains</span><span class=p>(</span><span class=s>"key"</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=w> </span><span class=o><<</span>
|
||||
<span class=w> </span><span class=s>"j_object contains 'another': "</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>j_object</span><span class=p>.</span><span class=n>contains</span><span class=p>(</span><span class=s>"another"</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=w> </span><span class=o><<</span>
|
||||
<span class=w> </span><span class=s>"j_array contains 'key': "</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>j_array</span><span class=p>.</span><span class=n>contains</span><span class=p>(</span><span class=s>"key"</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>endl</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=s>"j_array contains 'key': "</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>j_array</span><span class=p>.</span><span class=n>contains</span><span class=p>(</span><span class=s>"key"</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code><span class=err>j_objec</span><span class=kc>t</span><span class=w> </span><span class=err>co</span><span class=kc>nta</span><span class=err>i</span><span class=kc>ns</span><span class=w> </span><span class=err>'key'</span><span class=p>:</span><span class=w> </span><span class=kc>true</span>
|
||||
<span class=err>j_objec</span><span class=kc>t</span><span class=w> </span><span class=err>co</span><span class=kc>nta</span><span class=err>i</span><span class=kc>ns</span><span class=w> </span><span class=err>'a</span><span class=kc>n</span><span class=err>o</span><span class=kc>t</span><span class=err>her'</span><span class=p>:</span><span class=w> </span><span class=kc>false</span>
|
||||
@@ -33,7 +37,7 @@
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=k>namespace</span><span class=w> </span><span class=nn>std</span><span class=o>::</span><span class=nn>string_view_literals</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=k>namespace</span><span class=w> </span><span class=nn>nlohmann</span><span class=o>::</span><span class=nn>literals</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
@@ -46,7 +50,7 @@
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>boolalpha</span><span class=w> </span><span class=o><<</span>
|
||||
<span class=w> </span><span class=s>"j_object contains 'key': "</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>j_object</span><span class=p>.</span><span class=n>contains</span><span class=p>(</span><span class=s>"key"</span><span class=n>sv</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=w> </span><span class=o><<</span>
|
||||
<span class=w> </span><span class=s>"j_object contains 'another': "</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>j_object</span><span class=p>.</span><span class=n>contains</span><span class=p>(</span><span class=s>"another"</span><span class=n>sv</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=w> </span><span class=o><<</span>
|
||||
<span class=w> </span><span class=s>"j_array contains 'key': "</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>j_array</span><span class=p>.</span><span class=n>contains</span><span class=p>(</span><span class=s>"key"</span><span class=n>sv</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>endl</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=s>"j_array contains 'key': "</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>j_array</span><span class=p>.</span><span class=n>contains</span><span class=p>(</span><span class=s>"key"</span><span class=n>sv</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code><span class=err>j_objec</span><span class=kc>t</span><span class=w> </span><span class=err>co</span><span class=kc>nta</span><span class=err>i</span><span class=kc>ns</span><span class=w> </span><span class=err>'key'</span><span class=p>:</span><span class=w> </span><span class=kc>true</span>
|
||||
<span class=err>j_objec</span><span class=kc>t</span><span class=w> </span><span class=err>co</span><span class=kc>nta</span><span class=err>i</span><span class=kc>ns</span><span class=w> </span><span class=err>'a</span><span class=kc>n</span><span class=err>o</span><span class=kc>t</span><span class=err>her'</span><span class=p>:</span><span class=w> </span><span class=kc>false</span>
|
||||
@@ -54,7 +58,7 @@
|
||||
</code></pre></div> </details> <details class=example> <summary>Example: (3) check with <abbr title="JavaScript Object Notation">JSON</abbr> pointer</summary> <p>The example shows how <code>contains()</code> is used.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=k>namespace</span><span class=w> </span><span class=nn>nlohmann</span><span class=o>::</span><span class=nn>literals</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
@@ -72,27 +76,11 @@
|
||||
<span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>j</span><span class=p>.</span><span class=n>contains</span><span class=p>(</span><span class=s>"/array/1"</span><span class=n>_json_pointer</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span>
|
||||
<span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>j</span><span class=p>.</span><span class=n>contains</span><span class=p>(</span><span class=s>"/array/-"</span><span class=n>_json_pointer</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span>
|
||||
<span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>j</span><span class=p>.</span><span class=n>contains</span><span class=p>(</span><span class=s>"/array/4"</span><span class=n>_json_pointer</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span>
|
||||
<span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>j</span><span class=p>.</span><span class=n>contains</span><span class=p>(</span><span class=s>"/baz"</span><span class=n>_json_pointer</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>endl</span><span class=p>;</span>
|
||||
|
||||
<span class=w> </span><span class=k>try</span>
|
||||
<span class=w> </span><span class=p>{</span>
|
||||
<span class=w> </span><span class=c1>// try to use an array index with leading '0'</span>
|
||||
<span class=w> </span><span class=n>j</span><span class=p>.</span><span class=n>contains</span><span class=p>(</span><span class=s>"/array/01"</span><span class=n>_json_pointer</span><span class=p>);</span>
|
||||
<span class=w> </span><span class=p>}</span>
|
||||
<span class=w> </span><span class=k>catch</span><span class=w> </span><span class=p>(</span><span class=k>const</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>parse_error</span><span class=o>&</span><span class=w> </span><span class=n>e</span><span class=p>)</span>
|
||||
<span class=w> </span><span class=p>{</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>e</span><span class=p>.</span><span class=n>what</span><span class=p>()</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=p>}</span>
|
||||
|
||||
<span class=w> </span><span class=k>try</span>
|
||||
<span class=w> </span><span class=p>{</span>
|
||||
<span class=w> </span><span class=c1>// try to use an array index that is not a number</span>
|
||||
<span class=w> </span><span class=n>j</span><span class=p>.</span><span class=n>contains</span><span class=p>(</span><span class=s>"/array/one"</span><span class=n>_json_pointer</span><span class=p>);</span>
|
||||
<span class=w> </span><span class=p>}</span>
|
||||
<span class=w> </span><span class=k>catch</span><span class=w> </span><span class=p>(</span><span class=k>const</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>parse_error</span><span class=o>&</span><span class=w> </span><span class=n>e</span><span class=p>)</span>
|
||||
<span class=w> </span><span class=p>{</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>e</span><span class=p>.</span><span class=n>what</span><span class=p>()</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=p>}</span>
|
||||
<span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>j</span><span class=p>.</span><span class=n>contains</span><span class=p>(</span><span class=s>"/baz"</span><span class=n>_json_pointer</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span>
|
||||
<span class=w> </span><span class=c1>// an array index with a leading '0' is not found</span>
|
||||
<span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>j</span><span class=p>.</span><span class=n>contains</span><span class=p>(</span><span class=s>"/array/01"</span><span class=n>_json_pointer</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span>
|
||||
<span class=w> </span><span class=c1>// an array index that is not a number is not found</span>
|
||||
<span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>j</span><span class=p>.</span><span class=n>contains</span><span class=p>(</span><span class=s>"/array/one"</span><span class=n>_json_pointer</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code><span class=kc>true</span>
|
||||
<span class=kc>true</span>
|
||||
@@ -101,4 +89,6 @@
|
||||
<span class=kc>false</span>
|
||||
<span class=kc>false</span>
|
||||
<span class=kc>false</span>
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../find/ >find</a> find a value in an object</li> <li><a href=../count/ >count</a> returns the number of occurrences of a key</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ol> <li>Added in version 3.11.0.</li> <li>Added in version 3.6.0. Extended template <code>KeyType</code> to support comparable types in version 3.11.0. Fixed in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span> to consistently accept <code>std::string_view</code>-convertible keys, as already supported by <a href=../operator%5B%5D/ ><code>operator[]</code></a>, <a href=../at/ ><code>at</code></a>, <a href=../value/ ><code>value</code></a>, and other lookup functions.</li> <li>Added in version 3.7.0.</li> <li>Deleted overloads for integral key types added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span> to reject such calls at compile time instead of causing undefined behavior at runtime.</li> </ol> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 4, 2026 09:46:32 UTC">October 4, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontaLine truncated
|
||||
<span class=kc>false</span>
|
||||
<span class=kc>false</span>
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../find/ ><code>find</code></a> - find a value in an object</li> <li><a href=../count/ ><code>count</code></a> - returns the number of occurrences of a key</li> <li><a href=../../basic_json_view/contains/ ><code>basic_json_view::contains</code></a> - the same check on a zero-copy view</li> <li><a href=../../../features/element_access/#does-this-key-exist>Element Access</a> - how to test whether a key exists</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ol> <li>Added in version 3.11.0.</li> <li>Added in version 3.6.0. Extended template <code>KeyType</code> to support comparable types in version 3.11.0. Support for keys convertible to <code>std::string_view</code> added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>, consistently across the lookup functions.</li> <li>Added in version 3.7.0.</li> <li>Deleted overloads for integral key types added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span> to reject such calls at compile time instead of causing undefined behavior at runtime.</li> </ol> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../clear/ class="md-footer__link md-footer__link--prev" aria-label="Previous: clear"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> clear </div> </div> </a> <a href=../count/ class="md-footer__link md-footer__link--next" aria-label="Next: count"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> count </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-Line truncated
|
||||
@@ -10,11 +10,16 @@ bool contains(KeyType&& key) const;
|
||||
|
||||
// (3)
|
||||
bool contains(const json_pointer& ptr) const;
|
||||
|
||||
// (4)
|
||||
template<typename T>
|
||||
bool contains(T) const = delete;
|
||||
```
|
||||
|
||||
1. Check whether an element exists in a JSON object with a key equivalent to `key`. If the element is not found or the JSON value is not an object, `false` is returned.
|
||||
1. See 1. This overload is only available if `KeyType` is comparable with `typename object_t::key_type` and `typename object_comparator_t::is_transparent` denotes a type.
|
||||
1. Check whether the given JSON pointer `ptr` can be resolved in the current JSON value.
|
||||
1. Deleted: this overload is only available if `T` is an integral type and is declared as deleted, so that a call with an integer `key` (for example, `j.contains(0)`) fails to compile. Otherwise, the integer literal `0` would convert to a null `const char*` and, from there, to the key type, causing undefined behavior at runtime.
|
||||
|
||||
## Template parameters
|
||||
|
||||
@@ -31,6 +36,7 @@ bool contains(const json_pointer& ptr) const;
|
||||
1. `true` if an element with specified `key` exists. If no such element with such a key is found or the JSON value is not an object, `false` is returned.
|
||||
1. See 1.
|
||||
1. `true` if the JSON pointer can be resolved to a stored value, `false` otherwise.
|
||||
1. Deleted; a call with an integral argument does not compile.
|
||||
|
||||
## Exception safety
|
||||
|
||||
@@ -41,14 +47,18 @@ Strong exception safety: if an exception occurs, the original value stays intact
|
||||
1. The function does not throw exceptions.
|
||||
1. The function does not throw exceptions.
|
||||
1. The function does not throw exceptions.
|
||||
1. Deleted; a call with an integral argument does not compile.
|
||||
|
||||
## Complexity
|
||||
|
||||
Logarithmic in the size of the JSON object.
|
||||
1. Logarithmic in the size of the JSON object.
|
||||
1. Logarithmic in the size of the JSON object.
|
||||
1. At most one lookup per reference token of `ptr`, each logarithmic in the size of the container at that level: O(*n* log *m*) for *n* reference tokens and containers of size at most *m*.
|
||||
1. Deleted; a call with an integral argument does not compile.
|
||||
|
||||
## Notes
|
||||
|
||||
- This method always returns `false` when executed on a JSON type that is not an object.
|
||||
- Overloads (1) and (2) always return `false` when executed on a JSON type that is not an object. Overload (3) also works on arrays and on primitive values: the empty JSON pointer resolves in every JSON value (so `json(1).contains(""_json_pointer)` returns `true`), and `json({1, 2}).contains("/1"_json_pointer)` returns `true`.
|
||||
- This method can be executed on any JSON value type.
|
||||
- Calling this function with an integer argument (for example, `contains(0)`) does not compile: such an argument would otherwise implicitly convert to a null `const char*` and, from there, cause undefined behavior when constructing a `std::string` for the object key. To check for an array element instead, use [`at`](https://json.nlohmann.me/api/basic_json/at/index.md), [`operator[]`](https://json.nlohmann.me/api/basic_json/operator%5B%5D/index.md), or compare against [`size`](https://json.nlohmann.me/api/basic_json/size/index.md).
|
||||
|
||||
@@ -74,7 +84,7 @@ The example shows how `contains()` is used.
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
using namespace nlohmann::literals;
|
||||
|
||||
int main()
|
||||
@@ -87,7 +97,7 @@ int main()
|
||||
std::cout << std::boolalpha <<
|
||||
"j_object contains 'key': " << j_object.contains("key") << '\n' <<
|
||||
"j_object contains 'another': " << j_object.contains("another") << '\n' <<
|
||||
"j_array contains 'key': " << j_array.contains("key") << std::endl;
|
||||
"j_array contains 'key': " << j_array.contains("key") << '\n';
|
||||
}
|
||||
```
|
||||
|
||||
@@ -109,7 +119,7 @@ The example shows how `contains()` is used.
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using namespace std::string_view_literals;
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
using namespace nlohmann::literals;
|
||||
|
||||
int main()
|
||||
@@ -122,7 +132,7 @@ int main()
|
||||
std::cout << std::boolalpha <<
|
||||
"j_object contains 'key': " << j_object.contains("key"sv) << '\n' <<
|
||||
"j_object contains 'another': " << j_object.contains("another"sv) << '\n' <<
|
||||
"j_array contains 'key': " << j_array.contains("key"sv) << std::endl;
|
||||
"j_array contains 'key': " << j_array.contains("key"sv) << '\n';
|
||||
}
|
||||
```
|
||||
|
||||
@@ -142,7 +152,7 @@ The example shows how `contains()` is used.
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
using namespace nlohmann::literals;
|
||||
|
||||
int main()
|
||||
@@ -160,27 +170,11 @@ int main()
|
||||
<< j.contains("/array/1"_json_pointer) << '\n'
|
||||
<< j.contains("/array/-"_json_pointer) << '\n'
|
||||
<< j.contains("/array/4"_json_pointer) << '\n'
|
||||
<< j.contains("/baz"_json_pointer) << std::endl;
|
||||
|
||||
try
|
||||
{
|
||||
// try to use an array index with leading '0'
|
||||
j.contains("/array/01"_json_pointer);
|
||||
}
|
||||
catch (const json::parse_error& e)
|
||||
{
|
||||
std::cout << e.what() << '\n';
|
||||
}
|
||||
|
||||
try
|
||||
{
|
||||
// try to use an array index that is not a number
|
||||
j.contains("/array/one"_json_pointer);
|
||||
}
|
||||
catch (const json::parse_error& e)
|
||||
{
|
||||
std::cout << e.what() << '\n';
|
||||
}
|
||||
<< j.contains("/baz"_json_pointer) << '\n'
|
||||
// an array index with a leading '0' is not found
|
||||
<< j.contains("/array/01"_json_pointer) << '\n'
|
||||
// an array index that is not a number is not found
|
||||
<< j.contains("/array/one"_json_pointer) << '\n';
|
||||
}
|
||||
```
|
||||
|
||||
@@ -194,16 +188,20 @@ true
|
||||
false
|
||||
false
|
||||
false
|
||||
false
|
||||
false
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [find](https://json.nlohmann.me/api/basic_json/find/index.md) find a value in an object
|
||||
- [count](https://json.nlohmann.me/api/basic_json/count/index.md) returns the number of occurrences of a key
|
||||
- [`find`](https://json.nlohmann.me/api/basic_json/find/index.md) - find a value in an object
|
||||
- [`count`](https://json.nlohmann.me/api/basic_json/count/index.md) - returns the number of occurrences of a key
|
||||
- [`basic_json_view::contains`](https://json.nlohmann.me/api/basic_json_view/contains/index.md) - the same check on a zero-copy view
|
||||
- [Element Access](https://json.nlohmann.me/features/element_access/#does-this-key-exist) - how to test whether a key exists
|
||||
|
||||
## Version history
|
||||
|
||||
1. Added in version 3.11.0.
|
||||
1. Added in version 3.6.0. Extended template `KeyType` to support comparable types in version 3.11.0. Fixed in version 3.13.0 unreleased to consistently accept `std::string_view`-convertible keys, as already supported by [`operator[]`](https://json.nlohmann.me/api/basic_json/operator%5B%5D/index.md), [`at`](https://json.nlohmann.me/api/basic_json/at/index.md), [`value`](https://json.nlohmann.me/api/basic_json/value/index.md), and other lookup functions.
|
||||
1. Added in version 3.6.0. Extended template `KeyType` to support comparable types in version 3.11.0. Support for keys convertible to `std::string_view` added in version 3.13.0 unreleased, consistently across the lookup functions.
|
||||
1. Added in version 3.7.0.
|
||||
1. Deleted overloads for integral key types added in version 3.13.0 unreleased to reject such calls at compile time instead of causing undefined behavior at runtime.
|
||||
+59
-9
@@ -7,12 +7,19 @@ size_type count(const typename object_t::key_type& key) const;
|
||||
// (2)
|
||||
template<typename KeyType>
|
||||
size_type count(KeyType&& key) const;
|
||||
|
||||
// (3)
|
||||
template<typename T>
|
||||
size_type count(T) const = delete;
|
||||
```
|
||||
|
||||
1. Returns the number of elements with key `key`. If `ObjectType` is the default `std::map` type, the return value will
|
||||
always be `0` (`key` was not found) or `1` (`key` was found).
|
||||
2. See 1. This overload is only available if `KeyType` is comparable with `#!cpp typename object_t::key_type` and
|
||||
`#!cpp typename object_comparator_t::is_transparent` denotes a type.
|
||||
3. Deleted: this overload is only available if `T` is an integral type and is declared as deleted, so that a call with
|
||||
an integer `key` (for example, `#!cpp j.count(0)`) fails to compile. Otherwise, the integer literal `0` would convert to
|
||||
a null `#!cpp const char*` and, from there, to the key type, causing undefined behavior at runtime.
|
||||
|
||||
## Template parameters
|
||||
|
||||
@@ -53,13 +60,33 @@ Logarithmic in the size of the JSON object.
|
||||
The example shows how `count()` is used.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/count__object_t_key_type.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create a JSON object
|
||||
json j_object = {{"one", 1}, {"two", 2}};
|
||||
|
||||
// call count()
|
||||
auto count_two = j_object.count("two");
|
||||
auto count_three = j_object.count("three");
|
||||
|
||||
// print values
|
||||
std::cout << "number of elements with key \"two\": " << count_two << '\n';
|
||||
std::cout << "number of elements with key \"three\": " << count_three << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/count__object_t_key_type.output"
|
||||
number of elements with key "two": 1
|
||||
number of elements with key "three": 0
|
||||
|
||||
```
|
||||
|
||||
??? example "Example: (2) count number of elements using string_view"
|
||||
@@ -67,25 +94,48 @@ Logarithmic in the size of the JSON object.
|
||||
The example shows how `count()` is used.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/count__keytype.c++17.cpp"
|
||||
#include <iostream>
|
||||
#include <string_view>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using namespace std::string_view_literals;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create a JSON object
|
||||
json j_object = {{"one", 1}, {"two", 2}};
|
||||
|
||||
// call count()
|
||||
auto count_two = j_object.count("two"sv);
|
||||
auto count_three = j_object.count("three"sv);
|
||||
|
||||
// print values
|
||||
std::cout << "number of elements with key \"two\": " << count_two << '\n';
|
||||
std::cout << "number of elements with key \"three\": " << count_three << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/count__keytype.c++17.output"
|
||||
number of elements with key "two": 1
|
||||
number of elements with key "three": 0
|
||||
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [find](find.md) find a value in an object
|
||||
- [contains](contains.md) checks whether a key exists
|
||||
- [`find`](find.md) - find a value in an object
|
||||
- [`contains`](contains.md) - checks whether a key exists
|
||||
- [`basic_json_view::count`](../basic_json_view/count.md) - the same check on a zero-copy view
|
||||
- [Element Access](../../features/element_access/index.md#does-this-key-exist) - how to test whether a key exists
|
||||
|
||||
## Version history
|
||||
|
||||
1. Added in version 3.11.0.
|
||||
2. Added in version 1.0.0. Changed parameter `key` type to `KeyType&&` in version 3.11.0. Fixed in version 3.13.0 to
|
||||
consistently accept `std::string_view`-convertible keys, as already supported by [`operator[]`](operator[].md),
|
||||
[`at`](at.md), [`value`](value.md), and other lookup functions.
|
||||
2. Added in version 1.0.0. Changed to support comparable key types in version 3.11.0. Support for keys convertible to
|
||||
`std::string_view` added in version 3.13.0, consistently across the lookup functions.
|
||||
3. Deleted overload for integral key types added in version 3.13.0 to reject such calls at compile time instead of
|
||||
causing undefined behavior at runtime.
|
||||
@@ -1,13 +1,17 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/count/" rel="canonical"><link href=../contains/ rel=prev><link href=../crbegin/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>count - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../../css/custom.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsoncount class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> count </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> <dLine truncated
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/count/" rel="canonical"><link href=../contains/ rel=prev><link href=../crbegin/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>count - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel=stylesheet href=../../../css/custom.css><link rel=stylesheet href=../../../css/brand.css><link rel=stylesheet href=../../../css/fig-sax.css><link rel=stylesheet href=../../../css/fig-jsonview.css><link rel=stylesheet href=../../../css/fig-exceptions.css><link rel=stylesheet href=../../../css/fig-pointer.css><link rel=stylesheet href=../../../css/fig-charts.css><link rel=stylesheet href=../../../css/fig-integration.css><link rel=stylesheet href=../../../css/fig-macros.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsoncount class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> count </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0Line truncated
|
||||
<span class=n>size_type</span><span class=w> </span><span class=nf>count</span><span class=p>(</span><span class=k>const</span><span class=w> </span><span class=k>typename</span><span class=w> </span><span class=nc>object_t</span><span class=o>::</span><span class=n>key_type</span><span class=o>&</span><span class=w> </span><span class=n>key</span><span class=p>)</span><span class=w> </span><span class=k>const</span><span class=p>;</span>
|
||||
|
||||
<span class=c1>// (2)</span>
|
||||
<span class=k>template</span><span class=o><</span><span class=k>typename</span><span class=w> </span><span class=nc>KeyType</span><span class=o>></span>
|
||||
<span class=n>size_type</span><span class=w> </span><span class=n>count</span><span class=p>(</span><span class=n>KeyType</span><span class=o>&&</span><span class=w> </span><span class=n>key</span><span class=p>)</span><span class=w> </span><span class=k>const</span><span class=p>;</span>
|
||||
</code></pre></div> <ol> <li>Returns the number of elements with key <code>key</code>. If <code>ObjectType</code> is the default <code>std::map</code> type, the return value will always be <code>0</code> (<code>key</code> was not found) or <code>1</code> (<code>key</code> was found).</li> <li>See 1. This overload is only available if <code>KeyType</code> is comparable with <code class=highlight><span class=k>typename</span><span class=w> </span><span class=nc>object_t</span><span class=o>::</span><span class=n>key_type</span></code> and <code class=highlight><span class=k>typename</span><span class=w> </span><span class=nc>object_comparator_t</span><span class=o>::</span><span class=n>is_transparent</span></code> denotes a type.</li> </ol> <h2 id=template-parameters>Template parameters<a class=headerlink href=#template-parameters title="Permanent link">¶</a></h2> <dl> <dt><code>KeyType</code></dt> <dd>A type for an object key other than <a href=../../json_pointer/ ><code>json_pointer</code></a> that is comparable with <a href=../string_t/ ><code>string_t</code></a> using <a href=../object_comparator_t/ ><code>object_comparator_t</code></a>. This can also be a string view (C++17).</dd> </dl> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">¶</a></h2> <dl> <dt><code>key</code> (in)</dt> <dd>key value of the element to count.</dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">¶</a></h2> <p>Number of elements with key <code>key</code>. If the <abbr title="JavaScript Object Notation">JSON</abbr> value is not an object, the return value will be <code>0</code>.</p> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">¶</a></h2> <p>Strong exception safety: if an exception occurs, the original value stays intact.</p> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">¶</a></h2> <p>Logarithmic in the size of the <abbr title="JavaScript Object Notation">JSON</abbr> object.</p> <h2 id=notes>Notes<a class=headerlink href=#notes title="Permanent link">¶</a></h2> <ul> <li>This method always returns <code>0</code> when executed on a <abbr title="JavaScript Object Notation">JSON</abbr> type that is not an object.</li> <li>Calling this function with an integer argument (for example, <code class=highlight><span class=n>count</span><span class=p>(</span><span class=mi>0</span><span class=p>)</span></code>) does not compile: such an argument would otherwise implicitly convert to a null <code class=highlight><span class=k>const</span><span class=w> </span><span class=kt>char</span><span class=o>*</span></code> and, from there, cause undefined behavior when constructing a <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>string</span></code> for the object key. To check for an array element instead, use <a href=../at/ ><code>at</code></a>, <a href=../operator%5B%5D/ ><code>operator[]</code></a>, or compare against <a href=../size/ ><code>size</code></a>.</li> </ul> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example: (1) count number of elements</summary> <p>The example shows how <code>count()</code> is used.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
|
||||
<span class=c1>// (3)</span>
|
||||
<span class=k>template</span><span class=o><</span><span class=k>typename</span><span class=w> </span><span class=nc>T</span><span class=o>></span>
|
||||
<span class=n>size_type</span><span class=w> </span><span class=n>count</span><span class=p>(</span><span class=n>T</span><span class=p>)</span><span class=w> </span><span class=k>const</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=k>delete</span><span class=p>;</span>
|
||||
</code></pre></div> <ol> <li>Returns the number of elements with key <code>key</code>. If <code>ObjectType</code> is the default <code>std::map</code> type, the return value will always be <code>0</code> (<code>key</code> was not found) or <code>1</code> (<code>key</code> was found).</li> <li>See 1. This overload is only available if <code>KeyType</code> is comparable with <code class=highlight><span class=k>typename</span><span class=w> </span><span class=nc>object_t</span><span class=o>::</span><span class=n>key_type</span></code> and <code class=highlight><span class=k>typename</span><span class=w> </span><span class=nc>object_comparator_t</span><span class=o>::</span><span class=n>is_transparent</span></code> denotes a type.</li> <li>Deleted: this overload is only available if <code>T</code> is an integral type and is declared as deleted, so that a call with an integer <code>key</code> (for example, <code class=highlight><span class=n>j</span><span class=p>.</span><span class=n>count</span><span class=p>(</span><span class=mi>0</span><span class=p>)</span></code>) fails to compile. Otherwise, the integer literal <code>0</code> would convert to a null <code class=highlight><span class=k>const</span><span class=w> </span><span class=kt>char</span><span class=o>*</span></code> and, from there, to the key type, causing undefined behavior at runtime.</li> </ol> <h2 id=template-parameters>Template parameters<a class=headerlink href=#template-parameters title="Permanent link">¶</a></h2> <dl> <dt><code>KeyType</code></dt> <dd>A type for an object key other than <a href=../../json_pointer/ ><code>json_pointer</code></a> that is comparable with <a href=../string_t/ ><code>string_t</code></a> using <a href=../object_comparator_t/ ><code>object_comparator_t</code></a>. This can also be a string view (C++17).</dd> </dl> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">¶</a></h2> <dl> <dt><code>key</code> (in)</dt> <dd>key value of the element to count.</dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">¶</a></h2> <p>Number of elements with key <code>key</code>. If the <abbr title="JavaScript Object Notation">JSON</abbr> value is not an object, the return value will be <code>0</code>.</p> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">¶</a></h2> <p>Strong exception safety: if an exception occurs, the original value stays intact.</p> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">¶</a></h2> <p>Logarithmic in the size of the <abbr title="JavaScript Object Notation">JSON</abbr> object.</p> <h2 id=notes>Notes<a class=headerlink href=#notes title="Permanent link">¶</a></h2> <ul> <li>This method always returns <code>0</code> when executed on a <abbr title="JavaScript Object Notation">JSON</abbr> type that is not an object.</li> <li>Calling this function with an integer argument (for example, <code class=highlight><span class=n>count</span><span class=p>(</span><span class=mi>0</span><span class=p>)</span></code>) does not compile: such an argument would otherwise implicitly convert to a null <code class=highlight><span class=k>const</span><span class=w> </span><span class=kt>char</span><span class=o>*</span></code> and, from there, cause undefined behavior when constructing a <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>string</span></code> for the object key. To check for an array element instead, use <a href=../at/ ><code>at</code></a>, <a href=../operator%5B%5D/ ><code>operator[]</code></a>, or compare against <a href=../size/ ><code>size</code></a>.</li> </ul> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example: (1) count number of elements</summary> <p>The example shows how <code>count()</code> is used.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -29,7 +33,7 @@
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=k>namespace</span><span class=w> </span><span class=nn>std</span><span class=o>::</span><span class=nn>string_view_literals</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -46,4 +50,4 @@
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code><span class=kc>nu</span><span class=err>mber</span><span class=w> </span><span class=err>o</span><span class=kc>f</span><span class=w> </span><span class=err>eleme</span><span class=kc>nts</span><span class=w> </span><span class=err>wi</span><span class=kc>t</span><span class=err>h</span><span class=w> </span><span class=err>key</span><span class=w> </span><span class=nt>"two"</span><span class=p>:</span><span class=w> </span><span class=mi>1</span>
|
||||
<span class=kc>nu</span><span class=err>mber</span><span class=w> </span><span class=err>o</span><span class=kc>f</span><span class=w> </span><span class=err>eleme</span><span class=kc>nts</span><span class=w> </span><span class=err>wi</span><span class=kc>t</span><span class=err>h</span><span class=w> </span><span class=err>key</span><span class=w> </span><span class=nt>"three"</span><span class=p>:</span><span class=w> </span><span class=mi>0</span>
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../find/ >find</a> find a value in an object</li> <li><a href=../contains/ >contains</a> checks whether a key exists</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ol> <li>Added in version 3.11.0.</li> <li>Added in version 1.0.0. Changed parameter <code>key</code> type to <code>KeyType&&</code> in version 3.11.0. Fixed in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span> to consistently accept <code>std::string_view</code>-convertible keys, as already supported by <a href=../operator%5B%5D/ ><code>operator[]</code></a>, <a href=../at/ ><code>at</code></a>, <a href=../value/ ><code>value</code></a>, and other lookup functions.</li> <li>Deleted overload for integral key types added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span> to reject such calls at compile time instead of causing undefined behavior at runtime.</li> </ol> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 4, 2026 09:46:32 UTC">October 4, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontaweLine truncated
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../find/ ><code>find</code></a> - find a value in an object</li> <li><a href=../contains/ ><code>contains</code></a> - checks whether a key exists</li> <li><a href=../../basic_json_view/count/ ><code>basic_json_view::count</code></a> - the same check on a zero-copy view</li> <li><a href=../../../features/element_access/#does-this-key-exist>Element Access</a> - how to test whether a key exists</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ol> <li>Added in version 3.11.0.</li> <li>Added in version 1.0.0. Changed to support comparable key types in version 3.11.0. Support for keys convertible to <code>std::string_view</code> added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>, consistently across the lookup functions.</li> <li>Deleted overload for integral key types added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span> to reject such calls at compile time instead of causing undefined behavior at runtime.</li> </ol> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../contains/ class="md-footer__link md-footer__link--prev" aria-label="Previous: contains"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> contains </div> </div> </a> <a href=../crbegin/ class="md-footer__link md-footer__link--next" aria-label="Next: crbegin"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> crbegin </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 Line truncated
|
||||
@@ -7,10 +7,15 @@ size_type count(const typename object_t::key_type& key) const;
|
||||
// (2)
|
||||
template<typename KeyType>
|
||||
size_type count(KeyType&& key) const;
|
||||
|
||||
// (3)
|
||||
template<typename T>
|
||||
size_type count(T) const = delete;
|
||||
```
|
||||
|
||||
1. Returns the number of elements with key `key`. If `ObjectType` is the default `std::map` type, the return value will always be `0` (`key` was not found) or `1` (`key` was found).
|
||||
1. See 1. This overload is only available if `KeyType` is comparable with `typename object_t::key_type` and `typename object_comparator_t::is_transparent` denotes a type.
|
||||
1. Deleted: this overload is only available if `T` is an integral type and is declared as deleted, so that a call with an integer `key` (for example, `j.count(0)`) fails to compile. Otherwise, the integer literal `0` would convert to a null `const char*` and, from there, to the key type, causing undefined behavior at runtime.
|
||||
|
||||
## Template parameters
|
||||
|
||||
@@ -47,7 +52,7 @@ The example shows how `count()` is used.
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -81,7 +86,7 @@ The example shows how `count()` is used.
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using namespace std::string_view_literals;
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -107,11 +112,13 @@ number of elements with key "three": 0
|
||||
|
||||
## See also
|
||||
|
||||
- [find](https://json.nlohmann.me/api/basic_json/find/index.md) find a value in an object
|
||||
- [contains](https://json.nlohmann.me/api/basic_json/contains/index.md) checks whether a key exists
|
||||
- [`find`](https://json.nlohmann.me/api/basic_json/find/index.md) - find a value in an object
|
||||
- [`contains`](https://json.nlohmann.me/api/basic_json/contains/index.md) - checks whether a key exists
|
||||
- [`basic_json_view::count`](https://json.nlohmann.me/api/basic_json_view/count/index.md) - the same check on a zero-copy view
|
||||
- [Element Access](https://json.nlohmann.me/features/element_access/#does-this-key-exist) - how to test whether a key exists
|
||||
|
||||
## Version history
|
||||
|
||||
1. Added in version 3.11.0.
|
||||
1. Added in version 1.0.0. Changed parameter `key` type to `KeyType&&` in version 3.11.0. Fixed in version 3.13.0 unreleased to consistently accept `std::string_view`-convertible keys, as already supported by [`operator[]`](https://json.nlohmann.me/api/basic_json/operator%5B%5D/index.md), [`at`](https://json.nlohmann.me/api/basic_json/at/index.md), [`value`](https://json.nlohmann.me/api/basic_json/value/index.md), and other lookup functions.
|
||||
1. Added in version 1.0.0. Changed to support comparable key types in version 3.11.0. Support for keys convertible to `std::string_view` added in version 3.13.0 unreleased, consistently across the lookup functions.
|
||||
1. Deleted overload for integral key types added in version 3.13.0 unreleased to reject such calls at compile time instead of causing undefined behavior at runtime.
|
||||
@@ -6,7 +6,67 @@ const_reverse_iterator crbegin() const noexcept;
|
||||
|
||||
Returns an iterator to the reverse-beginning; that is, the last element.
|
||||
|
||||
|
||||
<div class="nj-fig-wrap" markdown>
|
||||
<svg class="nj-fig nj-fig--range" viewBox="0 0 600 236" role="img" aria-labelledby="fig-rbe-title" xmlns="http://www.w3.org/2000/svg">
|
||||
<title id="fig-rbe-title">Two rows of sixteen cells. The upper row shows the reversed sequence: rend() points to a dashed position before the first element and rbegin() to the last element. The lower row shows the forward sequence: begin() points to the first element and end() to a dashed position after the last element. A reverse iterator stores an iterator to the next element, so rend() corresponds to begin() and rbegin() to end().</title>
|
||||
<defs><marker id="fig-rbe-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path class="fg-head" d="M0 1 L10 5 L0 9 z"/></marker></defs>
|
||||
<rect class="fg-cell fg-cell--end" x="30" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="64" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="98" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="132" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="166" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="200" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="234" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="268" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="302" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="336" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="370" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="404" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="438" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="472" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="506" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="540" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="30" y="144" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="64" y="144" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="98" y="144" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="132" y="144" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="166" y="144" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="200" y="144" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="234" y="144" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="268" y="144" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="302" y="144" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="336" y="144" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="370" y="144" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="404" y="144" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="438" y="144" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="472" y="144" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="506" y="144" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell fg-cell--end" x="540" y="144" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-pill" x="19" y="8" width="52" height="24" rx="6"/>
|
||||
<text class="fg-pilltext" x="45" y="24">rend</text>
|
||||
<line class="fg-arrow" x1="45" y1="32" x2="45" y2="60" marker-end="url(#fig-rbe-arrow)"/>
|
||||
<rect class="fg-pill" x="521" y="8" width="68" height="24" rx="6"/>
|
||||
<text class="fg-pilltext" x="555" y="24">rbegin</text>
|
||||
<line class="fg-arrow" x1="555" y1="32" x2="555" y2="60" marker-end="url(#fig-rbe-arrow)"/>
|
||||
<text class="fg-note fg-note--l" x="81" y="24">Reverse past-the-last element</text>
|
||||
<line class="fg-arrow fg-arrow--dash" x1="45" y1="94" x2="45" y2="142"/>
|
||||
<line class="fg-arrow fg-arrow--dash" x1="555" y1="94" x2="555" y2="142"/>
|
||||
<text class="fg-note" x="300" y="123">A reverse iterator stores an iterator to the next element</text>
|
||||
<text class="fg-note" x="300" y="141" dy="0" style="display:none"></text>
|
||||
<rect class="fg-pill" x="15" y="204" width="60" height="24" rx="6"/>
|
||||
<text class="fg-pilltext" x="45" y="220">begin</text>
|
||||
<line class="fg-arrow" x1="45" y1="202" x2="45" y2="178" marker-end="url(#fig-rbe-arrow)"/>
|
||||
<rect class="fg-pill" x="531" y="204" width="48" height="24" rx="6"/>
|
||||
<text class="fg-pilltext" x="555" y="220">end</text>
|
||||
<line class="fg-arrow" x1="555" y1="202" x2="555" y2="178" marker-end="url(#fig-rbe-arrow)"/>
|
||||
<text class="fg-note fg-note--r" x="515" y="221">Past-the-last element</text>
|
||||
</svg>
|
||||
|
||||
</div>
|
||||
|
||||
<p class="nj-caption" markdown>`crbegin()` points to the last element, like `rbegin()`, and `rend()` to the position
|
||||
before the first element. The upper row is the reversed sequence and the lower row the forward sequence; dashed arrows
|
||||
link each reverse iterator to the forward iterator it stores, and dashed cells are past-the-last positions.</p>
|
||||
|
||||
## Return value
|
||||
|
||||
@@ -27,20 +87,37 @@ Constant.
|
||||
The following code shows an example for `crbegin()`.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/crbegin.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create an array value
|
||||
json array = {1, 2, 3, 4, 5};
|
||||
|
||||
// get an iterator to the reverse-beginning
|
||||
json::const_reverse_iterator it = array.crbegin();
|
||||
|
||||
// serialize the element that the iterator points to
|
||||
std::cout << *it << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/crbegin.output"
|
||||
5
|
||||
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [crend](crend.md) returns a const reverse iterator to one before the first element
|
||||
- [rbegin](rbegin.md) returns a reverse iterator to the last element
|
||||
- [cbegin](cbegin.md) returns a const iterator to the first element
|
||||
- [`crend`](crend.md) - returns a const reverse iterator to one before the first element
|
||||
- [`rbegin`](rbegin.md) - returns a reverse iterator to the last element
|
||||
- [`cbegin`](cbegin.md) - returns a const iterator to the first element
|
||||
- [Iterators](../../features/iterators.md) - the article on iterators
|
||||
|
||||
## Version history
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/crbegin/" rel="canonical"><link href=../count/ rel=prev><link href=../crend/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>crbegin - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../../css/custom.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsoncrbegin class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> crbegin </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label>Line truncated
|
||||
</code></pre></div> <p>Returns an iterator to the reverse-beginning; that is, the last element.</p> <p><img alt="Illustration from cppreference.com" src=../../../images/range-rbegin-rend.svg></p> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">¶</a></h2> <p>reverse iterator to the last element</p> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">¶</a></h2> <p>No-throw guarantee: this member function never throws exceptions.</p> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">¶</a></h2> <p>Constant.</p> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example</summary> <p>The following code shows an example for <code>crbegin()</code>.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/crbegin/" rel="canonical"><link href=../count/ rel=prev><link href=../crend/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>crbegin - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel=stylesheet href=../../../css/custom.css><link rel=stylesheet href=../../../css/brand.css><link rel=stylesheet href=../../../css/fig-sax.css><link rel=stylesheet href=../../../css/fig-jsonview.css><link rel=stylesheet href=../../../css/fig-exceptions.css><link rel=stylesheet href=../../../css/fig-pointer.css><link rel=stylesheet href=../../../css/fig-charts.css><link rel=stylesheet href=../../../css/fig-integration.css><link rel=stylesheet href=../../../css/fig-macros.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsoncrbegin class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> crbegin </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.Line truncated
|
||||
</code></pre></div> <p>Returns an iterator to the reverse-beginning; that is, the last element.</p> <div class=nj-fig-wrap> <p><svg class="nj-fig nj-fig--range" viewbox="0 0 600 236" role=img aria-labelledby=fig-rbe-title xmlns=http://www.w3.org/2000/svg> <title id=fig-rbe-title>Two rows of sixteen cells. The upper row shows the reversed sequence: rend() points to a dashed position before the first element and rbegin() to the last element. The lower row shows the forward sequence: begin() points to the first element and end() to a dashed position after the last element. A reverse iterator stores an iterator to the next element, so rend() corresponds to begin() and rbegin() to end().</title> <defs><marker id=fig-rbe-arrow viewbox="0 0 10 10" refx=9 refy=5 markerwidth=7 markerheight=7 orient=auto><path class=fg-head d="M0 1 L10 5 L0 9 z"/></marker></defs> <rect x=30 y=62 width=30 height=30 rx=5 class="fg-cell fg-cell--end"/> <rect class=fg-cell x=64 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=98 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=132 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=166 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=200 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=234 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=268 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=302 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=336 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=370 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=404 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=438 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=472 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=506 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=540 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=30 y=144 width=30 height=30 rx=5 /> <rect class=fg-cell x=64 y=144 width=30 height=30 rx=5 /> <rect class=fg-cell x=98 y=144 width=30 height=30 rx=5 /> <rect class=fg-cell x=132 y=144 width=30 height=30 rx=5 /> <rect class=fg-cell x=166 y=144 width=30 height=30 rx=5 /> <rect class=fg-cell x=200 y=144 width=30 height=30 rx=5 /> <rect class=fg-cell x=234 y=144 width=30 height=30 rx=5 /> <rect class=fg-cell x=268 y=144 width=30 height=30 rx=5 /> <rect class=fg-cell x=302 y=144 width=30 height=30 rx=5 /> <rect class=fg-cell x=336 y=144 width=30 height=30 rx=5 /> <rect class=fg-cell x=370 y=144 width=30 height=30 rx=5 /> <rect class=fg-cell x=404 y=144 width=30 height=30 rx=5 /> <rect class=fg-cell x=438 y=144 width=30 height=30 rx=5 /> <rect class=fg-cell x=472 y=144 width=30 height=30 rx=5 /> <rect class=fg-cell x=506 y=144 width=30 height=30 rx=5 /> <rect x=540 y=144 width=30 height=30 rx=5 class="fg-cell fg-cell--end"/> <rect class=fg-pill x=19 y=8 width=52 height=24 rx=6 /> <text class=fg-pilltext x=45 y=24>rend</text> <line class=fg-arrow x1=45 y1=32 x2=45 y2=60 marker-end=url(#fig-rbe-arrow) /> <rect class=fg-pill x=521 y=8 width=68 height=24 rx=6 /> <text class=fg-pilltext x=555 y=24>rbegin</text> <line class=fg-arrow x1=555 y1=32 x2=555 y2=60 marker-end=url(#fig-rbe-arrow) /> <text class="fg-note fg-note--l" x=81 y=24>Reverse past-the-last element</text> <line x1=45 y1=94 x2=45 y2=142 class="fg-arrow fg-arrow--dash"/> <line x1=555 y1=94 x2=555 y2=142 class="fg-arrow fg-arrow--dash"/> <text class=fg-note x=300 y=123>A reverse iterator stores an iterator to the next element</text> <text class=fg-note x=300 y=141 dy=0 style=display:none></text> <rect class=fg-pill x=15 y=204 width=60 height=24 rx=6 /> <text class=fg-pilltext x=45 y=220>begin</text> <line class=fg-arrow x1=45 y1=202 x2=45 y2=178 marker-end=url(#fig-rbe-arrow) /> <rect class=fg-pill x=531 y=204 width=48 height=24 rx=6 /> <text class=fg-pilltext x=555 y=220>end</text> <line class=fg-arrow x1=555 y1=202 x2=555 y2=178 marker-end=url(#fig-rbe-arrow) /> <text class="fg-note fg-note--r" x=515 y=221>Past-the-last element</text> </svg></p> </div> <p class=nj-caption><code>crbegin()</code> points to the last element, like <code>rbegin()</code>, and <code>rend()</code> to the position before the first element. The upper row is the reversed sequence and the lower row the forward sequence; dashed arrows link each reverse iterator to the forward iterator it stores, and dashed cells are past-the-last positions.</p> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">¶</a></h2> <p>reverse iterator to the last element</p> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">¶</a></h2> <p>No-throw guarantee: this member function never throws exceptions.</p> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">¶</a></h2> <p>Constant.</p> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example</summary> <p>The following code shows an example foLine truncated
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -16,4 +16,4 @@
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=o>*</span><span class=n>it</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code><span class=mi>5</span>
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../crend/ >crend</a> returns a const reverse iterator to one before the first element</li> <li><a href=../rbegin/ >rbegin</a> returns a reverse iterator to the last element</li> <li><a href=../cbegin/ >cbegin</a> returns a const iterator to the first element</li> <li><a href=../../../features/iterators/ >Iterators</a> - the article on iterators</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 1.0.0.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 2, 2026 09:32:15 UTC">October 2, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4C0 465.5 14.3 480 31.9 480H416c17.6 0 32-14.5 32-32.3V64.3c0-17.8-14.4-32.3-32-32.3M135.4 416H69V202.2h66.5V416zM102.2 96a38.5 38.5 0 1 1 0 77 38.5 38.5 0 1 1 0-77m282.1 320h-66.4V312c0-24.8-.5-56.7-34.5-56.7-34.6 0-39.9 27-39.9 54.9V416h-66.4V202.2h63.7v29.2h.9c8.9-16.8 30.6-34.5 62.9-34.5 67.2 0 79.7 44.3 79.7 101.9z"/></svg> </a> <a href="https://www.xing.com/profile/Niels_Lohmann" target="_blank" relLine truncated
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../crend/ ><code>crend</code></a> - returns a const reverse iterator to one before the first element</li> <li><a href=../rbegin/ ><code>rbegin</code></a> - returns a reverse iterator to the last element</li> <li><a href=../cbegin/ ><code>cbegin</code></a> - returns a const iterator to the first element</li> <li><a href=../../../features/iterators/ >Iterators</a> - the article on iterators</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 1.0.0.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../count/ class="md-footer__link md-footer__link--prev" aria-label="Previous: count"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> count </div> </div> </a> <a href=../crend/ class="md-footer__link md-footer__link--next" aria-label="Next: crend"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> crend </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3Line truncated
|
||||
@@ -6,6 +6,8 @@ const_reverse_iterator crbegin() const noexcept;
|
||||
|
||||
Returns an iterator to the reverse-beginning; that is, the last element.
|
||||
|
||||
`crbegin()` points to the last element, like `rbegin()`, and `rend()` to the position before the first element. The upper row is the reversed sequence and the lower row the forward sequence; dashed arrows link each reverse iterator to the forward iterator it stores, and dashed cells are past-the-last positions.
|
||||
|
||||
## Return value
|
||||
|
||||
reverse iterator to the last element
|
||||
@@ -28,7 +30,7 @@ The following code shows an example for `crbegin()`.
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -51,9 +53,9 @@ Output:
|
||||
|
||||
## See also
|
||||
|
||||
- [crend](https://json.nlohmann.me/api/basic_json/crend/index.md) returns a const reverse iterator to one before the first element
|
||||
- [rbegin](https://json.nlohmann.me/api/basic_json/rbegin/index.md) returns a reverse iterator to the last element
|
||||
- [cbegin](https://json.nlohmann.me/api/basic_json/cbegin/index.md) returns a const iterator to the first element
|
||||
- [`crend`](https://json.nlohmann.me/api/basic_json/crend/index.md) - returns a const reverse iterator to one before the first element
|
||||
- [`rbegin`](https://json.nlohmann.me/api/basic_json/rbegin/index.md) - returns a reverse iterator to the last element
|
||||
- [`cbegin`](https://json.nlohmann.me/api/basic_json/cbegin/index.md) - returns a const iterator to the first element
|
||||
- [Iterators](https://json.nlohmann.me/features/iterators/index.md) - the article on iterators
|
||||
|
||||
## Version history
|
||||
|
||||
+86
-6
@@ -7,7 +7,67 @@ const_reverse_iterator crend() const noexcept;
|
||||
Returns an iterator to the reverse-end; that is, one before the first element. This element acts as a placeholder,
|
||||
attempting to access it results in undefined behavior.
|
||||
|
||||
|
||||
<div class="nj-fig-wrap" markdown>
|
||||
<svg class="nj-fig nj-fig--range" viewBox="0 0 600 236" role="img" aria-labelledby="fig-rbe-title" xmlns="http://www.w3.org/2000/svg">
|
||||
<title id="fig-rbe-title">Two rows of sixteen cells. The upper row shows the reversed sequence: rend() points to a dashed position before the first element and rbegin() to the last element. The lower row shows the forward sequence: begin() points to the first element and end() to a dashed position after the last element. A reverse iterator stores an iterator to the next element, so rend() corresponds to begin() and rbegin() to end().</title>
|
||||
<defs><marker id="fig-rbe-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path class="fg-head" d="M0 1 L10 5 L0 9 z"/></marker></defs>
|
||||
<rect class="fg-cell fg-cell--end" x="30" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="64" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="98" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="132" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="166" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="200" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="234" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="268" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="302" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="336" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="370" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="404" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="438" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="472" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="506" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="540" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="30" y="144" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="64" y="144" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="98" y="144" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="132" y="144" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="166" y="144" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="200" y="144" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="234" y="144" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="268" y="144" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="302" y="144" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="336" y="144" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="370" y="144" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="404" y="144" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="438" y="144" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="472" y="144" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="506" y="144" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell fg-cell--end" x="540" y="144" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-pill" x="19" y="8" width="52" height="24" rx="6"/>
|
||||
<text class="fg-pilltext" x="45" y="24">rend</text>
|
||||
<line class="fg-arrow" x1="45" y1="32" x2="45" y2="60" marker-end="url(#fig-rbe-arrow)"/>
|
||||
<rect class="fg-pill" x="521" y="8" width="68" height="24" rx="6"/>
|
||||
<text class="fg-pilltext" x="555" y="24">rbegin</text>
|
||||
<line class="fg-arrow" x1="555" y1="32" x2="555" y2="60" marker-end="url(#fig-rbe-arrow)"/>
|
||||
<text class="fg-note fg-note--l" x="81" y="24">Reverse past-the-last element</text>
|
||||
<line class="fg-arrow fg-arrow--dash" x1="45" y1="94" x2="45" y2="142"/>
|
||||
<line class="fg-arrow fg-arrow--dash" x1="555" y1="94" x2="555" y2="142"/>
|
||||
<text class="fg-note" x="300" y="123">A reverse iterator stores an iterator to the next element</text>
|
||||
<text class="fg-note" x="300" y="141" dy="0" style="display:none"></text>
|
||||
<rect class="fg-pill" x="15" y="204" width="60" height="24" rx="6"/>
|
||||
<text class="fg-pilltext" x="45" y="220">begin</text>
|
||||
<line class="fg-arrow" x1="45" y1="202" x2="45" y2="178" marker-end="url(#fig-rbe-arrow)"/>
|
||||
<rect class="fg-pill" x="531" y="204" width="48" height="24" rx="6"/>
|
||||
<text class="fg-pilltext" x="555" y="220">end</text>
|
||||
<line class="fg-arrow" x1="555" y1="202" x2="555" y2="178" marker-end="url(#fig-rbe-arrow)"/>
|
||||
<text class="fg-note fg-note--r" x="515" y="221">Past-the-last element</text>
|
||||
</svg>
|
||||
|
||||
</div>
|
||||
|
||||
<p class="nj-caption" markdown>`crend()` points to the position before the first element, like `rend()`, and `rbegin()`
|
||||
to the last element. The upper row is the reversed sequence and the lower row the forward sequence; dashed arrows link
|
||||
each reverse iterator to the forward iterator it stores, and dashed cells are past-the-last positions.</p>
|
||||
|
||||
## Return value
|
||||
|
||||
@@ -28,20 +88,40 @@ Constant.
|
||||
The following code shows an example for `crend()`.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/crend.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create an array value
|
||||
json array = {1, 2, 3, 4, 5};
|
||||
|
||||
// get an iterator to the reverse-end
|
||||
json::const_reverse_iterator it = array.crend();
|
||||
|
||||
// increment the iterator to point to the first element
|
||||
--it;
|
||||
|
||||
// serialize the element that the iterator points to
|
||||
std::cout << *it << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/crend.output"
|
||||
1
|
||||
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [crbegin](crbegin.md) returns a const reverse iterator to the last element
|
||||
- [rend](rend.md) returns a reverse iterator to one before the first element
|
||||
- [cend](cend.md) returns a const iterator to one past the last element
|
||||
- [`crbegin`](crbegin.md) - returns a const reverse iterator to the last element
|
||||
- [`rend`](rend.md) - returns a reverse iterator to one before the first element
|
||||
- [`cend`](cend.md) - returns a const iterator to one past the last element
|
||||
- [Iterators](../../features/iterators.md) - the article on iterators
|
||||
|
||||
## Version history
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/crend/" rel="canonical"><link href=../crbegin/ rel=prev><link href=../default_object_comparator_t/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>crend - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../../css/custom.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsoncrend class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> crend </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/Line truncated
|
||||
</code></pre></div> <p>Returns an iterator to the reverse-end; that is, one before the first element. This element acts as a placeholder, attempting to access it results in undefined behavior.</p> <p><img alt="Illustration from cppreference.com" src=../../../images/range-rbegin-rend.svg></p> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">¶</a></h2> <p>reverse iterator to the element following the last element</p> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">¶</a></h2> <p>No-throw guarantee: this member function never throws exceptions.</p> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">¶</a></h2> <p>Constant.</p> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example</summary> <p>The following code shows an example for <code>crend()</code>.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/crend/" rel="canonical"><link href=../crbegin/ rel=prev><link href=../default_object_comparator_t/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>crend - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel=stylesheet href=../../../css/custom.css><link rel=stylesheet href=../../../css/brand.css><link rel=stylesheet href=../../../css/fig-sax.css><link rel=stylesheet href=../../../css/fig-jsonview.css><link rel=stylesheet href=../../../css/fig-exceptions.css><link rel=stylesheet href=../../../css/fig-pointer.css><link rel=stylesheet href=../../../css/fig-charts.css><link rel=stylesheet href=../../../css/fig-integration.css><link rel=stylesheet href=../../../css/fig-macros.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsoncrend class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> crend </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5Line truncated
|
||||
</code></pre></div> <p>Returns an iterator to the reverse-end; that is, one before the first element. This element acts as a placeholder, attempting to access it results in undefined behavior.</p> <div class=nj-fig-wrap> <p><svg class="nj-fig nj-fig--range" viewbox="0 0 600 236" role=img aria-labelledby=fig-rbe-title xmlns=http://www.w3.org/2000/svg> <title id=fig-rbe-title>Two rows of sixteen cells. The upper row shows the reversed sequence: rend() points to a dashed position before the first element and rbegin() to the last element. The lower row shows the forward sequence: begin() points to the first element and end() to a dashed position after the last element. A reverse iterator stores an iterator to the next element, so rend() corresponds to begin() and rbegin() to end().</title> <defs><marker id=fig-rbe-arrow viewbox="0 0 10 10" refx=9 refy=5 markerwidth=7 markerheight=7 orient=auto><path class=fg-head d="M0 1 L10 5 L0 9 z"/></marker></defs> <rect x=30 y=62 width=30 height=30 rx=5 class="fg-cell fg-cell--end"/> <rect class=fg-cell x=64 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=98 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=132 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=166 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=200 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=234 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=268 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=302 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=336 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=370 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=404 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=438 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=472 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=506 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=540 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=30 y=144 width=30 height=30 rx=5 /> <rect class=fg-cell x=64 y=144 width=30 height=30 rx=5 /> <rect class=fg-cell x=98 y=144 width=30 height=30 rx=5 /> <rect class=fg-cell x=132 y=144 width=30 height=30 rx=5 /> <rect class=fg-cell x=166 y=144 width=30 height=30 rx=5 /> <rect class=fg-cell x=200 y=144 width=30 height=30 rx=5 /> <rect class=fg-cell x=234 y=144 width=30 height=30 rx=5 /> <rect class=fg-cell x=268 y=144 width=30 height=30 rx=5 /> <rect class=fg-cell x=302 y=144 width=30 height=30 rx=5 /> <rect class=fg-cell x=336 y=144 width=30 height=30 rx=5 /> <rect class=fg-cell x=370 y=144 width=30 height=30 rx=5 /> <rect class=fg-cell x=404 y=144 width=30 height=30 rx=5 /> <rect class=fg-cell x=438 y=144 width=30 height=30 rx=5 /> <rect class=fg-cell x=472 y=144 width=30 height=30 rx=5 /> <rect class=fg-cell x=506 y=144 width=30 height=30 rx=5 /> <rect x=540 y=144 width=30 height=30 rx=5 class="fg-cell fg-cell--end"/> <rect class=fg-pill x=19 y=8 width=52 height=24 rx=6 /> <text class=fg-pilltext x=45 y=24>rend</text> <line class=fg-arrow x1=45 y1=32 x2=45 y2=60 marker-end=url(#fig-rbe-arrow) /> <rect class=fg-pill x=521 y=8 width=68 height=24 rx=6 /> <text class=fg-pilltext x=555 y=24>rbegin</text> <line class=fg-arrow x1=555 y1=32 x2=555 y2=60 marker-end=url(#fig-rbe-arrow) /> <text class="fg-note fg-note--l" x=81 y=24>Reverse past-the-last element</text> <line x1=45 y1=94 x2=45 y2=142 class="fg-arrow fg-arrow--dash"/> <line x1=555 y1=94 x2=555 y2=142 class="fg-arrow fg-arrow--dash"/> <text class=fg-note x=300 y=123>A reverse iterator stores an iterator to the next element</text> <text class=fg-note x=300 y=141 dy=0 style=display:none></text> <rect class=fg-pill x=15 y=204 width=60 height=24 rx=6 /> <text class=fg-pilltext x=45 y=220>begin</text> <line class=fg-arrow x1=45 y1=202 x2=45 y2=178 marker-end=url(#fig-rbe-arrow) /> <rect class=fg-pill x=531 y=204 width=48 height=24 rx=6 /> <text class=fg-pilltext x=555 y=220>end</text> <line class=fg-arrow x1=555 y1=202 x2=555 y2=178 marker-end=url(#fig-rbe-arrow) /> <text class="fg-note fg-note--r" x=515 y=221>Past-the-last element</text> </svg></p> </div> <p class=nj-caption><code>crend()</code> points to the position before the first element, like <code>rend()</code>, and <code>rbegin()</code> to the last element. The upper row is the reversed sequence and the lower row the forward sequence; dashed arrows link each reverse iterator to the forward iterator it stores, and dashed cells are past-the-last positions.</p> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">¶</a></h2> <p>reverse iterator to the element following the last element</p> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">¶</a></h2> <p>No-throw guarantee: this member function never throws exceptions.</p> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">¶</a></h2> <p>Constant.</p> <h2 id=examples>Examples<a class=headerlink href=#examples title="PermaneLine truncated
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -19,4 +19,4 @@
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=o>*</span><span class=n>it</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code><span class=mi>1</span>
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../crbegin/ >crbegin</a> returns a const reverse iterator to the last element</li> <li><a href=../rend/ >rend</a> returns a reverse iterator to one before the first element</li> <li><a href=../cend/ >cend</a> returns a const iterator to one past the last element</li> <li><a href=../../../features/iterators/ >Iterators</a> - the article on iterators</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 1.0.0.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 2, 2026 09:32:15 UTC">October 2, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4C0 465.5 14.3 480 31.9 480H416c17.6 0 32-14.5 32-32.3V64.3c0-17.8-14.4-32.3-32-32.3M135.4 416H69V202.2h66.5V416zM102.2 96a38.5 38.5 0 1 1 0 77 38.5 38.5 0 1 1 0-77m282.1 320h-66.4V312c0-24.8-.5-56.7-34.5-56.7-34.6 0-39.9 27-39.9 54.9V416h-66.4V202.2h63.7v29.2h.9c8.9-16.8 30.6-34.5 62.9-34.5 67.2 0 79.7 44.3 79.7 101.9z"/></svg> </a> <a href="https://www.xing.com/profile/Niels_Lohmann" target="_blank"Line truncated
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../crbegin/ ><code>crbegin</code></a> - returns a const reverse iterator to the last element</li> <li><a href=../rend/ ><code>rend</code></a> - returns a reverse iterator to one before the first element</li> <li><a href=../cend/ ><code>cend</code></a> - returns a const iterator to one past the last element</li> <li><a href=../../../features/iterators/ >Iterators</a> - the article on iterators</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 1.0.0.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../crbegin/ class="md-footer__link md-footer__link--prev" aria-label="Previous: crbegin"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> crbegin </div> </div> </a> <a href=../default_object_comparator_t/ class="md-footer__link md-footer__link--next" aria-label="Next: default_object_comparator_t"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> default_object_comparator_t </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3Line truncated
|
||||
@@ -6,6 +6,8 @@ const_reverse_iterator crend() const noexcept;
|
||||
|
||||
Returns an iterator to the reverse-end; that is, one before the first element. This element acts as a placeholder, attempting to access it results in undefined behavior.
|
||||
|
||||
`crend()` points to the position before the first element, like `rend()`, and `rbegin()` to the last element. The upper row is the reversed sequence and the lower row the forward sequence; dashed arrows link each reverse iterator to the forward iterator it stores, and dashed cells are past-the-last positions.
|
||||
|
||||
## Return value
|
||||
|
||||
reverse iterator to the element following the last element
|
||||
@@ -28,7 +30,7 @@ The following code shows an example for `crend()`.
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -54,9 +56,9 @@ Output:
|
||||
|
||||
## See also
|
||||
|
||||
- [crbegin](https://json.nlohmann.me/api/basic_json/crbegin/index.md) returns a const reverse iterator to the last element
|
||||
- [rend](https://json.nlohmann.me/api/basic_json/rend/index.md) returns a reverse iterator to one before the first element
|
||||
- [cend](https://json.nlohmann.me/api/basic_json/cend/index.md) returns a const iterator to one past the last element
|
||||
- [`crbegin`](https://json.nlohmann.me/api/basic_json/crbegin/index.md) - returns a const reverse iterator to the last element
|
||||
- [`rend`](https://json.nlohmann.me/api/basic_json/rend/index.md) - returns a reverse iterator to one before the first element
|
||||
- [`cend`](https://json.nlohmann.me/api/basic_json/cend/index.md) - returns a const iterator to one past the last element
|
||||
- [Iterators](https://json.nlohmann.me/features/iterators/index.md) - the article on iterators
|
||||
|
||||
## Version history
|
||||
|
||||
@@ -21,19 +21,34 @@ The actual comparator used depends on [`object_t`](object_t.md) and can be obtai
|
||||
The example below demonstrates the default comparator.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/default_object_comparator_t.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
std::cout << std::boolalpha
|
||||
<< "one < two : " << json::default_object_comparator_t{}("one", "two") << "\n"
|
||||
<< "three < four : " << json::default_object_comparator_t{}("three", "four") << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/default_object_comparator_t.output"
|
||||
one < two : true
|
||||
three < four : false
|
||||
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [object_comparator_t](object_comparator_t.md) the comparator actually used by `object_t`
|
||||
- [object_t](object_t.md) the type used to store JSON objects
|
||||
- [`object_comparator_t`](object_comparator_t.md) - the comparator actually used by `object_t`
|
||||
- [`object_t`](object_t.md) - the type used to store JSON objects
|
||||
- [Template Parameter Requirements](../../features/types/template_parameters.md) - requirements on the `ObjectType` template parameter
|
||||
- [Object order](../../features/object_order.md) - preserve the insertion order of keys
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -1,17 +1,17 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/default_object_comparator_t/" rel="canonical"><link href=../crend/ rel=prev><link href=../diff/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>default_object_comparator_t - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../../css/custom.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsondefault_object_comparator_t class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> default_object_comparator_t </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 Line truncated
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/default_object_comparator_t/" rel="canonical"><link href=../crend/ rel=prev><link href=../diff/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>default_object_comparator_t - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel=stylesheet href=../../../css/custom.css><link rel=stylesheet href=../../../css/brand.css><link rel=stylesheet href=../../../css/fig-sax.css><link rel=stylesheet href=../../../css/fig-jsonview.css><link rel=stylesheet href=../../../css/fig-exceptions.css><link rel=stylesheet href=../../../css/fig-pointer.css><link rel=stylesheet href=../../../css/fig-charts.css><link rel=stylesheet href=../../../css/fig-integration.css><link rel=stylesheet href=../../../css/fig-macros.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsondefault_object_comparator_t class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> default_object_comparator_t </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=httLine truncated
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>default_object_comparator_t</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>less</span><span class=o><></span><span class=p>;</span><span class=w> </span><span class=c1>// since C++14</span>
|
||||
</code></pre></div> <p>The default comparator used by <a href=../object_t/ ><code>object_t</code></a>.</p> <p>Since C++14 a transparent comparator is used which prevents unnecessary string construction when looking up a key in an object.</p> <p>The actual comparator used depends on <a href=../object_t/ ><code>object_t</code></a> and can be obtained via <a href=../object_comparator_t/ ><code>object_comparator_t</code></a>.</p> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example</summary> <p>The example below demonstrates the default comparator.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>boolalpha</span>
|
||||
<span class=w> </span><span class=o><<</span><span class=w> </span><span class=s>"one < two : "</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>default_object_comparator_t</span><span class=p>{}(</span><span class=s>"one"</span><span class=p>,</span><span class=w> </span><span class=s>"two"</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=s>"</span><span class=se>\n</span><span class=s>"</span>
|
||||
<span class=w> </span><span class=o><<</span><span class=w> </span><span class=s>"three < four : "</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>default_object_comparator_t</span><span class=p>{}(</span><span class=s>"three"</span><span class=p>,</span><span class=w> </span><span class=s>"four"</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>endl</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=o><<</span><span class=w> </span><span class=s>"three < four : "</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>default_object_comparator_t</span><span class=p>{}(</span><span class=s>"three"</span><span class=p>,</span><span class=w> </span><span class=s>"four"</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code><span class=err>o</span><span class=kc>ne</span><span class=w> </span><span class=err><</span><span class=w> </span><span class=kc>t</span><span class=err>wo</span><span class=w> </span><span class=p>:</span><span class=w> </span><span class=kc>true</span>
|
||||
<span class=kc>t</span><span class=err>hree</span><span class=w> </span><span class=err><</span><span class=w> </span><span class=kc>f</span><span class=err>our</span><span class=w> </span><span class=p>:</span><span class=w> </span><span class=kc>false</span>
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../object_comparator_t/ >object_comparator_t</a> the comparator actually used by <code>object_t</code></li> <li><a href=../object_t/ >object_t</a> the type used to store <abbr title="JavaScript Object Notation">JSON</abbr> objects</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 3.11.0.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 2, 2026 09:32:15 UTC">October 2, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4C0 465.5 14.3 480 31.9 480H416c17.6 0 32-14.5 32-32.3V64.3c0-17.8-14.4-32.3-32-32.3M135.4 416H69V202.2h66.5V416zM102.2 96a38.5 38.5 0 1 1 0 77 38.5 38.5 0 1 1 0-77m282.1 320h-66.4V312c0-24.8-.5-56.7-34.5-56.7-34.6 0-39.9 27-39.9 54.9V416h-66.4V202.2h63.7v29.2h.9c8.9-16.8 30.6-34.5 62.9-34.5 67.2 0 79.7 44.3 79.7 101.9z"/></svg> </a> <a href="https://www.xing.com/profile/Niels_Lohmann" target="_blank" rel="noopener" title="www.xing.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 384 51Line truncated
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../object_comparator_t/ ><code>object_comparator_t</code></a> - the comparator actually used by <code>object_t</code></li> <li><a href=../object_t/ ><code>object_t</code></a> - the type used to store <abbr title="JavaScript Object Notation">JSON</abbr> objects</li> <li><a href=../../../features/types/template_parameters/ >Template Parameter Requirements</a> - requirements on the <code>ObjectType</code> template parameter</li> <li><a href=../../../features/object_order/ >Object order</a> - preserve the insertion order of keys</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 3.11.0.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../crend/ class="md-footer__link md-footer__link--prev" aria-label="Previous: crend"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> crend </div> </div> </a> <a href=../diff/ class="md-footer__link md-footer__link--next" aria-label="Next: diff"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> diff </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m3Line truncated
|
||||
@@ -22,13 +22,13 @@ The example below demonstrates the default comparator.
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
std::cout << std::boolalpha
|
||||
<< "one < two : " << json::default_object_comparator_t{}("one", "two") << "\n"
|
||||
<< "three < four : " << json::default_object_comparator_t{}("three", "four") << std::endl;
|
||||
<< "three < four : " << json::default_object_comparator_t{}("three", "four") << '\n';
|
||||
}
|
||||
```
|
||||
|
||||
@@ -41,8 +41,10 @@ three < four : false
|
||||
|
||||
## See also
|
||||
|
||||
- [object_comparator_t](https://json.nlohmann.me/api/basic_json/object_comparator_t/index.md) the comparator actually used by `object_t`
|
||||
- [object_t](https://json.nlohmann.me/api/basic_json/object_t/index.md) the type used to store JSON objects
|
||||
- [`object_comparator_t`](https://json.nlohmann.me/api/basic_json/object_comparator_t/index.md) - the comparator actually used by `object_t`
|
||||
- [`object_t`](https://json.nlohmann.me/api/basic_json/object_t/index.md) - the type used to store JSON objects
|
||||
- [Template Parameter Requirements](https://json.nlohmann.me/features/types/template_parameters/index.md) - requirements on the `ObjectType` template parameter
|
||||
- [Object order](https://json.nlohmann.me/features/object_order/index.md) - preserve the insertion order of keys
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
+113
-11
@@ -2,17 +2,28 @@
|
||||
|
||||
```cpp
|
||||
static basic_json diff(const basic_json& source,
|
||||
const basic_json& target);
|
||||
const basic_json& target,
|
||||
const string_t& path = "");
|
||||
```
|
||||
|
||||
Creates a [JSON Patch](http://jsonpatch.com) so that value `source` can be changed into the value `target` by calling
|
||||
[`patch`](patch.md) function.
|
||||
|
||||
For two JSON values `source` and `target`, the following code yields always `#!cpp true`:
|
||||
For two JSON values `source` and `target`, the following code yields `#!cpp true`:
|
||||
```cpp
|
||||
source.patch(diff(source, target)) == target;
|
||||
```
|
||||
|
||||
The equality holds up to [`operator==`](operator_eq.md), so it has the following exceptions:
|
||||
|
||||
- A value that is not equal to itself cannot round-trip. This applies to `NaN` (also nested in an array or object) and
|
||||
to [discarded](is_discarded.md) values: `diff` emits a `replace` operation for them. A `NaN` in the patch is
|
||||
serialized as `#!json null`, so a patch that was dumped and parsed again would set `#!json null`.
|
||||
- Numbers that compare equal produce no operation, even if their types differ or if one is zero and the other is
|
||||
negative zero: `diff(1, 1.0)` (integer and floating-point), `diff(1u, 1)` (unsigned and signed integer) and
|
||||
`diff(0.0, -0.0)` (positive and negative zero) all return `#!json []`. The patched value is then the `source` and
|
||||
keeps its number type and sign.
|
||||
|
||||
## Parameters
|
||||
|
||||
`source` (in)
|
||||
@@ -21,21 +32,48 @@ source.patch(diff(source, target)) == target;
|
||||
`target` (in)
|
||||
: JSON value to compare against
|
||||
|
||||
`path` (in)
|
||||
: a prefix that is put verbatim in front of the `path` member of every operation (default: `""`, which addresses the
|
||||
root of the value). The prefix is neither escaped nor validated: `#!cpp diff(1, 2, "abc")` yields an operation with
|
||||
the `path` `abc`, which is not a valid JSON Pointer. Use it with a valid JSON Pointer such as `/root` and escape
|
||||
`~` and `/` in its reference tokens (see [JSON Pointer](../../features/json_pointer.md)).
|
||||
|
||||
## Return value
|
||||
|
||||
a JSON patch to convert the `source` to `target`
|
||||
|
||||
## Exception safety
|
||||
|
||||
Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
|
||||
Strong guarantee: `source` and `target` are never modified.
|
||||
|
||||
## Complexity
|
||||
|
||||
Linear in the lengths of `source` and `target`.
|
||||
Linear in the total number of values (including nested ones) in `source` and `target`, times the cost of a key-based
|
||||
object operation (looking up a key in an object): logarithmic for [`json`](../json.md), and linear for
|
||||
[`ordered_json`](../ordered_json.md) (see [`ordered_map` complexity](../ordered_map.md#complexity)). For
|
||||
`ordered_json`, diffing two objects with `n` and `m` members therefore takes O((n+m)²) when their keys do not line up
|
||||
(e.g., a key was added or the keys are in a different order). The size of the patch is proportional to the number of
|
||||
operations times the length of their paths, so a small change deep inside a value yields a long `path`.
|
||||
|
||||
## Notes
|
||||
|
||||
Currently, only `remove`, `add`, and `replace` operations are generated.
|
||||
- Currently, only `remove`, `add`, and `replace` operations are generated.
|
||||
- The patch is correct, but not guaranteed to be minimal. For instance, `diff([1,2,3], [0,1,2,3])` yields three
|
||||
`replace` operations and one `add` operation instead of a single insertion.
|
||||
- Differences between two arrays are reported index by index. Elements that were added at the end of the array are added
|
||||
with `add` operations on the path `/-` (appended in order), and elements that were removed are removed with `remove`
|
||||
operations from the highest index down to the lowest, so that the remaining indices stay valid.
|
||||
- For objects, the operations for the members of `source` come first (`replace`, `remove`, or the operations for nested
|
||||
values, in the iteration order of `source`), followed by `add` operations for the members that only `target` has.
|
||||
- For [`ordered_json`](../ordered_json.md), objects with the same keys in a different order are different. As a patch
|
||||
cannot reorder members, `diff` removes all keys of the `source` object and adds them again in the order of the
|
||||
`target`.
|
||||
- If `source` and `target` differ as a whole (e.g., different types), the patch consists of a single `replace`
|
||||
operation for the root of the value, i.e., with the `path` `""` (or the given `path` prefix).
|
||||
- The `value` members of the patch hold copies of values of `target`. A [binary](../../features/binary_values.md) value
|
||||
has no JSON representation: when a patch that contains one is serialized, it becomes an object such as
|
||||
`#!json {"bytes":[1,3],"subtype":null}`, so a parsed patch no longer holds a binary value (and would set that object
|
||||
instead).
|
||||
|
||||
## Examples
|
||||
|
||||
@@ -44,21 +82,85 @@ Currently, only `remove`, `add`, and `replace` operations are generated.
|
||||
The following code shows how a JSON patch is created as a diff for two JSON values.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/diff.cpp"
|
||||
#include <iostream>
|
||||
#include <iomanip>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
using namespace nlohmann::literals;
|
||||
|
||||
int main()
|
||||
{
|
||||
// the source document
|
||||
json source = R"(
|
||||
{
|
||||
"baz": "qux",
|
||||
"foo": "bar"
|
||||
}
|
||||
)"_json;
|
||||
|
||||
// the target document
|
||||
json target = R"(
|
||||
{
|
||||
"baz": "boo",
|
||||
"hello": [
|
||||
"world"
|
||||
]
|
||||
}
|
||||
)"_json;
|
||||
|
||||
// create the patch
|
||||
json patch = json::diff(source, target);
|
||||
|
||||
// roundtrip
|
||||
json patched_source = source.patch(patch);
|
||||
|
||||
// output patch and roundtrip result
|
||||
std::cout << std::setw(4) << patch << "\n\n"
|
||||
<< std::setw(4) << patched_source << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/diff.output"
|
||||
[
|
||||
{
|
||||
"op": "replace",
|
||||
"path": "/baz",
|
||||
"value": "boo"
|
||||
},
|
||||
{
|
||||
"op": "remove",
|
||||
"path": "/foo"
|
||||
},
|
||||
{
|
||||
"op": "add",
|
||||
"path": "/hello",
|
||||
"value": [
|
||||
"world"
|
||||
]
|
||||
}
|
||||
]
|
||||
|
||||
{
|
||||
"baz": "boo",
|
||||
"hello": [
|
||||
"world"
|
||||
]
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [RFC 6902 (JSON Patch)](https://tools.ietf.org/html/rfc6902)
|
||||
- [patch](patch.md) applies a JSON Patch
|
||||
- [patch_inplace](patch_inplace.md) applies a JSON Patch in place
|
||||
- [merge_patch](merge_patch.md) applies a JSON Merge Patch
|
||||
- [RFC 6902 (JSON Patch)](https://tools.ietf.org/html/rfc6902) - specification of JSON Patch
|
||||
- [`patch`](patch.md) - applies a JSON Patch
|
||||
- [`patch_inplace`](patch_inplace.md) - applies a JSON Patch in place
|
||||
- [`merge_patch`](merge_patch.md) - applies a JSON Merge Patch
|
||||
- [`merge_diff`](merge_diff.md) - creates a diff as a JSON Merge Patch
|
||||
- [JSON Patch and Diff](../../features/json_patch.md) - the article on JSON Patch
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -1,11 +1,12 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/diff/" rel="canonical"><link href=../default_object_comparator_t/ rel=prev><link href=../dump/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>diff - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../../css/custom.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsondiff class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> diff </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg>Line truncated
|
||||
<span class=w> </span><span class=k>const</span><span class=w> </span><span class=n>basic_json</span><span class=o>&</span><span class=w> </span><span class=n>target</span><span class=p>);</span>
|
||||
</code></pre></div> <p>Creates a <a href="http://jsonpatch.com"><abbr title="JavaScript Object Notation">JSON</abbr> Patch</a> so that value <code>source</code> can be changed into the value <code>target</code> by calling <a href=../patch/ ><code>patch</code></a> function.</p> <p>For two <abbr title="JavaScript Object Notation">JSON</abbr> values <code>source</code> and <code>target</code>, the following code yields always <code class=highlight><span class=nb>true</span></code>: <div class=highlight><pre><span></span><code><span class=n>source</span><span class=p>.</span><span class=n>patch</span><span class=p>(</span><span class=n>diff</span><span class=p>(</span><span class=n>source</span><span class=p>,</span><span class=w> </span><span class=n>target</span><span class=p>))</span><span class=w> </span><span class=o>==</span><span class=w> </span><span class=n>target</span><span class=p>;</span>
|
||||
</code></pre></div></p> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">¶</a></h2> <dl> <dt><code>source</code> (in)</dt> <dd><abbr title="JavaScript Object Notation">JSON</abbr> value to compare from</dd> <dt><code>target</code> (in)</dt> <dd><abbr title="JavaScript Object Notation">JSON</abbr> value to compare against</dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">¶</a></h2> <p>a <abbr title="JavaScript Object Notation">JSON</abbr> patch to convert the <code>source</code> to <code>target</code></p> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">¶</a></h2> <p>Strong guarantee: if an exception is thrown, there are no changes in the <abbr title="JavaScript Object Notation">JSON</abbr> value.</p> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">¶</a></h2> <p>Linear in the lengths of <code>source</code> and <code>target</code>.</p> <h2 id=notes>Notes<a class=headerlink href=#notes title="Permanent link">¶</a></h2> <p>Currently, only <code>remove</code>, <code>add</code>, and <code>replace</code> operations are generated.</p> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example</summary> <p>The following code shows how a <abbr title="JavaScript Object Notation">JSON</abbr> patch is created as a diff for two <abbr title="JavaScript Object Notation">JSON</abbr> values.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/diff/" rel="canonical"><link href=../default_object_comparator_t/ rel=prev><link href=../dump/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>diff - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel=stylesheet href=../../../css/custom.css><link rel=stylesheet href=../../../css/brand.css><link rel=stylesheet href=../../../css/fig-sax.css><link rel=stylesheet href=../../../css/fig-jsonview.css><link rel=stylesheet href=../../../css/fig-exceptions.css><link rel=stylesheet href=../../../css/fig-pointer.css><link rel=stylesheet href=../../../css/fig-charts.css><link rel=stylesheet href=../../../css/fig-integration.css><link rel=stylesheet href=../../../css/fig-macros.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsondiff class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> diff </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 Line truncated
|
||||
<span class=w> </span><span class=k>const</span><span class=w> </span><span class=n>basic_json</span><span class=o>&</span><span class=w> </span><span class=n>target</span><span class=p>,</span>
|
||||
<span class=w> </span><span class=k>const</span><span class=w> </span><span class=n>string_t</span><span class=o>&</span><span class=w> </span><span class=n>path</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=s>""</span><span class=p>);</span>
|
||||
</code></pre></div> <p>Creates a <a href="http://jsonpatch.com"><abbr title="JavaScript Object Notation">JSON</abbr> Patch</a> so that value <code>source</code> can be changed into the value <code>target</code> by calling <a href=../patch/ ><code>patch</code></a> function.</p> <p>For two <abbr title="JavaScript Object Notation">JSON</abbr> values <code>source</code> and <code>target</code>, the following code yields <code class=highlight><span class=nb>true</span></code>: <div class=highlight><pre><span></span><code><span class=n>source</span><span class=p>.</span><span class=n>patch</span><span class=p>(</span><span class=n>diff</span><span class=p>(</span><span class=n>source</span><span class=p>,</span><span class=w> </span><span class=n>target</span><span class=p>))</span><span class=w> </span><span class=o>==</span><span class=w> </span><span class=n>target</span><span class=p>;</span>
|
||||
</code></pre></div></p> <p>The equality holds up to <a href=../operator_eq/ ><code>operator==</code></a>, so it has the following exceptions:</p> <ul> <li>A value that is not equal to itself cannot round-trip. This applies to <code>NaN</code> (also nested in an array or object) and to <a href=../is_discarded/ >discarded</a> values: <code>diff</code> emits a <code>replace</code> operation for them. A <code>NaN</code> in the patch is serialized as <code class=highlight><span class=kc>null</span></code>, so a patch that was dumped and parsed again would set <code class=highlight><span class=kc>null</span></code>.</li> <li>Numbers that compare equal produce no operation, even if their types differ or if one is zero and the other is negative zero: <code>diff(1, 1.0)</code> (integer and floating-point), <code>diff(1u, 1)</code> (unsigned and signed integer) and <code>diff(0.0, -0.0)</code> (positive and negative zero) all return <code class=highlight><span class=p>[]</span></code>. The patched value is then the <code>source</code> and keeps its number type and sign.</li> </ul> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">¶</a></h2> <dl> <dt><code>source</code> (in)</dt> <dd><abbr title="JavaScript Object Notation">JSON</abbr> value to compare from</dd> <dt><code>target</code> (in)</dt> <dd><abbr title="JavaScript Object Notation">JSON</abbr> value to compare against</dd> <dt><code>path</code> (in)</dt> <dd>a prefix that is put verbatim in front of the <code>path</code> member of every operation (default: <code>""</code>, which addresses the root of the value). The prefix is neither escaped nor validated: <code class=highlight><span class=n>diff</span><span class=p>(</span><span class=mi>1</span><span class=p>,</span><span class=w> </span><span class=mi>2</span><span class=p>,</span><span class=w> </span><span class=s>"abc"</span><span class=p>)</span></code> yields an operation with the <code>path</code> <code>abc</code>, which is not a valid <abbr title="JavaScript Object Notation">JSON</abbr> Pointer. Use it with a valid <abbr title="JavaScript Object Notation">JSON</abbr> Pointer such as <code>/root</code> and escape <code>~</code> and <code>/</code> in its reference tokens (see <a href=../../../features/json_pointer/ ><abbr title="JavaScript Object Notation">JSON</abbr> Pointer</a>).</dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">¶</a></h2> <p>a <abbr title="JavaScript Object Notation">JSON</abbr> patch to convert the <code>source</code> to <code>target</code></p> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">¶</a></h2> <p>Strong guarantee: <code>source</code> and <code>target</code> are never modified.</p> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">¶</a></h2> <p>Linear in the total number of values (including nested ones) in <code>source</code> and <code>target</code>, times the cost of a key-based object operation (looking up a key in an object): logarithmic for <a href=../../json/ ><code>json</code></a>, and linear for <a href=../../ordered_json/ ><code>ordered_json</code></a> (see <a href=../../ordered_map/#complexity><code>ordered_map</code> complexity</a>). For <code>ordered_json</code>, diffing two objects with <code>n</code> and <code>m</code> members therefore takes O((n+m)²) when their keys do not line up (e.g., a key was added or the keys are in a different order). The size of the patch is proportional to the number of operations times the length of their paths, so a small change deep inside a value yields a long <code>path</code>.</p> <h2 id=notes>Notes<a class=headerlink href=#notes title="Permanent link">¶</a></h2> <ul> <li>Currently, only <code>remove</code>, <code>add</code>, and <code>replace</code> operations are generated.</li> <li>The patch is correct, but not guaranteed to be minimal. For instance, <code>diff([1,2,3], [0,1,2,3])</code> yields three <code>replace</code> operations and one <code>add</code> operation instead of a single insertion.</li> <li>Differences between two arrays are reported index by index. Elements that were added at the end of the array are added with <code>add</code> operations on the path <code>/-</code> (appended in order), and elements that were removed are removed with <code>remove</code> operations from the highest index down to the lowest, so that the remaining indices stay valid.</li> <li>For objects, the operations for the members of <code>source</code> come first (<code>replace</code>, <code>remove</code>, or the operations for nested values, in the iteration order of <code>source</code>), followed by <code>add</code> operations for the members that only <code>target</code> has.</li> <li>For <a href=../../ordered_json/ ><code>ordered_json</code></a>, objects with the same keys in a different order are different. As a patch canLine truncated
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><iomanip></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=k>namespace</span><span class=w> </span><span class=nn>nlohmann</span><span class=o>::</span><span class=nn>literals</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
@@ -36,7 +37,7 @@
|
||||
|
||||
<span class=w> </span><span class=c1>// output patch and roundtrip result</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>setw</span><span class=p>(</span><span class=mi>4</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>patch</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=s>"</span><span class=se>\n\n</span><span class=s>"</span>
|
||||
<span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>setw</span><span class=p>(</span><span class=mi>4</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>patched_source</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>endl</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>setw</span><span class=p>(</span><span class=mi>4</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>patched_source</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code><span class=p>[</span>
|
||||
<span class=w> </span><span class=p>{</span>
|
||||
@@ -63,4 +64,4 @@
|
||||
<span class=w> </span><span class=s2>"world"</span>
|
||||
<span class=w> </span><span class=p>]</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href="https://tools.ietf.org/html/rfc6902"><abbr title="Request for Comments">RFC</abbr> 6902 (<abbr title="JavaScript Object Notation">JSON</abbr> Patch)</a></li> <li><a href=../patch/ >patch</a> applies a <abbr title="JavaScript Object Notation">JSON</abbr> Patch</li> <li><a href=../patch_inplace/ >patch_inplace</a> applies a <abbr title="JavaScript Object Notation">JSON</abbr> Patch in place</li> <li><a href=../merge_patch/ >merge_patch</a> applies a <abbr title="JavaScript Object Notation">JSON</abbr> Merge Patch</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 2.0.0.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="June 29, 2026 20:15:18 UTC">June 29, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4C0 465.5 14.3 480 31.9 480H416c17.6 0 32-14.5 32-32.3V64.3c0-17.8-14.4-32.3-32-32.3M135.4 416H69V202.2h66.5V416zM102.2 96a38.5 38.5 0 1 1 0 77 38.5 38.5 0 1 1 0-77m282.1 320h-66.4V312c0-24.8-.5-56.7-34.5-56.7-34.6 0-39.9 27-39.9 54.9V416h-6Line truncated
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href="https://tools.ietf.org/html/rfc6902"><abbr title="Request for Comments">RFC</abbr> 6902 (<abbr title="JavaScript Object Notation">JSON</abbr> Patch)</a> - specification of <abbr title="JavaScript Object Notation">JSON</abbr> Patch</li> <li><a href=../patch/ ><code>patch</code></a> - applies a <abbr title="JavaScript Object Notation">JSON</abbr> Patch</li> <li><a href=../patch_inplace/ ><code>patch_inplace</code></a> - applies a <abbr title="JavaScript Object Notation">JSON</abbr> Patch in place</li> <li><a href=../merge_patch/ ><code>merge_patch</code></a> - applies a <abbr title="JavaScript Object Notation">JSON</abbr> Merge Patch</li> <li><a href=../merge_diff/ ><code>merge_diff</code></a> - creates a diff as a <abbr title="JavaScript Object Notation">JSON</abbr> Merge Patch</li> <li><a href=../../../features/json_patch/ ><abbr title="JavaScript Object Notation">JSON</abbr> Patch and Diff</a> - the article on <abbr title="JavaScript Object Notation">JSON</abbr> Patch</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 2.0.0.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 16:16:08 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../default_object_comparator_t/ class="md-footer__link md-footer__link--prev" aria-label="Previous: default_object_comparator_t"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> default_object_comparator_t </div> </div> </a> <a href=../dump/ class="md-footer__link md-footer__link--next" aria-label="Next: dump"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> dump </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 2Line truncated
|
||||
@@ -2,38 +2,52 @@
|
||||
|
||||
```
|
||||
static basic_json diff(const basic_json& source,
|
||||
const basic_json& target);
|
||||
const basic_json& target,
|
||||
const string_t& path = "");
|
||||
```
|
||||
|
||||
Creates a [JSON Patch](http://jsonpatch.com) so that value `source` can be changed into the value `target` by calling [`patch`](https://json.nlohmann.me/api/basic_json/patch/index.md) function.
|
||||
|
||||
For two JSON values `source` and `target`, the following code yields always `true`:
|
||||
For two JSON values `source` and `target`, the following code yields `true`:
|
||||
|
||||
```
|
||||
source.patch(diff(source, target)) == target;
|
||||
```
|
||||
|
||||
The equality holds up to [`operator==`](https://json.nlohmann.me/api/basic_json/operator_eq/index.md), so it has the following exceptions:
|
||||
|
||||
- A value that is not equal to itself cannot round-trip. This applies to `NaN` (also nested in an array or object) and to [discarded](https://json.nlohmann.me/api/basic_json/is_discarded/index.md) values: `diff` emits a `replace` operation for them. A `NaN` in the patch is serialized as `null`, so a patch that was dumped and parsed again would set `null`.
|
||||
- Numbers that compare equal produce no operation, even if their types differ or if one is zero and the other is negative zero: `diff(1, 1.0)` (integer and floating-point), `diff(1u, 1)` (unsigned and signed integer) and `diff(0.0, -0.0)` (positive and negative zero) all return `[]`. The patched value is then the `source` and keeps its number type and sign.
|
||||
|
||||
## Parameters
|
||||
|
||||
`source` (in) : JSON value to compare from
|
||||
|
||||
`target` (in) : JSON value to compare against
|
||||
|
||||
`path` (in) : a prefix that is put verbatim in front of the `path` member of every operation (default: `""`, which addresses the root of the value). The prefix is neither escaped nor validated: `diff(1, 2, "abc")` yields an operation with the `path` `abc`, which is not a valid JSON Pointer. Use it with a valid JSON Pointer such as `/root` and escape `~` and `/` in its reference tokens (see [JSON Pointer](https://json.nlohmann.me/features/json_pointer/index.md)).
|
||||
|
||||
## Return value
|
||||
|
||||
a JSON patch to convert the `source` to `target`
|
||||
|
||||
## Exception safety
|
||||
|
||||
Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
|
||||
Strong guarantee: `source` and `target` are never modified.
|
||||
|
||||
## Complexity
|
||||
|
||||
Linear in the lengths of `source` and `target`.
|
||||
Linear in the total number of values (including nested ones) in `source` and `target`, times the cost of a key-based object operation (looking up a key in an object): logarithmic for [`json`](https://json.nlohmann.me/api/json/index.md), and linear for [`ordered_json`](https://json.nlohmann.me/api/ordered_json/index.md) (see [`ordered_map` complexity](https://json.nlohmann.me/api/ordered_map/#complexity)). For `ordered_json`, diffing two objects with `n` and `m` members therefore takes O((n+m)²) when their keys do not line up (e.g., a key was added or the keys are in a different order). The size of the patch is proportional to the number of operations times the length of their paths, so a small change deep inside a value yields a long `path`.
|
||||
|
||||
## Notes
|
||||
|
||||
Currently, only `remove`, `add`, and `replace` operations are generated.
|
||||
- Currently, only `remove`, `add`, and `replace` operations are generated.
|
||||
- The patch is correct, but not guaranteed to be minimal. For instance, `diff([1,2,3], [0,1,2,3])` yields three `replace` operations and one `add` operation instead of a single insertion.
|
||||
- Differences between two arrays are reported index by index. Elements that were added at the end of the array are added with `add` operations on the path `/-` (appended in order), and elements that were removed are removed with `remove` operations from the highest index down to the lowest, so that the remaining indices stay valid.
|
||||
- For objects, the operations for the members of `source` come first (`replace`, `remove`, or the operations for nested values, in the iteration order of `source`), followed by `add` operations for the members that only `target` has.
|
||||
- For [`ordered_json`](https://json.nlohmann.me/api/ordered_json/index.md), objects with the same keys in a different order are different. As a patch cannot reorder members, `diff` removes all keys of the `source` object and adds them again in the order of the `target`.
|
||||
- If `source` and `target` differ as a whole (e.g., different types), the patch consists of a single `replace` operation for the root of the value, i.e., with the `path` `""` (or the given `path` prefix).
|
||||
- The `value` members of the patch hold copies of values of `target`. A [binary](https://json.nlohmann.me/features/binary_values/index.md) value has no JSON representation: when a patch that contains one is serialized, it becomes an object such as `{"bytes":[1,3],"subtype":null}`, so a parsed patch no longer holds a binary value (and would set that object instead).
|
||||
|
||||
## Examples
|
||||
|
||||
@@ -46,7 +60,7 @@ The following code shows how a JSON patch is created as a diff for two JSON valu
|
||||
#include <iomanip>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
using namespace nlohmann::literals;
|
||||
|
||||
int main()
|
||||
@@ -77,7 +91,7 @@ int main()
|
||||
|
||||
// output patch and roundtrip result
|
||||
std::cout << std::setw(4) << patch << "\n\n"
|
||||
<< std::setw(4) << patched_source << std::endl;
|
||||
<< std::setw(4) << patched_source << '\n';
|
||||
}
|
||||
```
|
||||
|
||||
@@ -113,10 +127,12 @@ Output:
|
||||
|
||||
## See also
|
||||
|
||||
- [RFC 6902 (JSON Patch)](https://tools.ietf.org/html/rfc6902)
|
||||
- [patch](https://json.nlohmann.me/api/basic_json/patch/index.md) applies a JSON Patch
|
||||
- [patch_inplace](https://json.nlohmann.me/api/basic_json/patch_inplace/index.md) applies a JSON Patch in place
|
||||
- [merge_patch](https://json.nlohmann.me/api/basic_json/merge_patch/index.md) applies a JSON Merge Patch
|
||||
- [RFC 6902 (JSON Patch)](https://tools.ietf.org/html/rfc6902) - specification of JSON Patch
|
||||
- [`patch`](https://json.nlohmann.me/api/basic_json/patch/index.md) - applies a JSON Patch
|
||||
- [`patch_inplace`](https://json.nlohmann.me/api/basic_json/patch_inplace/index.md) - applies a JSON Patch in place
|
||||
- [`merge_patch`](https://json.nlohmann.me/api/basic_json/merge_patch/index.md) - applies a JSON Merge Patch
|
||||
- [`merge_diff`](https://json.nlohmann.me/api/basic_json/merge_diff/index.md) - creates a diff as a JSON Merge Patch
|
||||
- [JSON Patch and Diff](https://json.nlohmann.me/features/json_patch/index.md) - the article on JSON Patch
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
+114
-4
@@ -62,6 +62,9 @@ Linear.
|
||||
|
||||
## Notes
|
||||
|
||||
Floating-point numbers are written with the fewest digits that read back as the same value (for `#!cpp double`; see
|
||||
[number handling](../../features/types/number_handling.md#number-serialization)).
|
||||
|
||||
Binary values are serialized as an object containing two keys:
|
||||
|
||||
- "bytes": an array of bytes as integers
|
||||
@@ -75,19 +78,124 @@ Binary values are serialized as an object containing two keys:
|
||||
result of the serialization.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/dump.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create JSON values
|
||||
json j_object = {{"one", 1}, {"two", 2}};
|
||||
json j_array = {1, 2, 4, 8, 16};
|
||||
json j_string = "Hellö 😀!";
|
||||
|
||||
// call dump()
|
||||
std::cout << "objects:" << '\n'
|
||||
<< j_object.dump() << "\n\n"
|
||||
<< j_object.dump(-1) << "\n\n"
|
||||
<< j_object.dump(0) << "\n\n"
|
||||
<< j_object.dump(4) << "\n\n"
|
||||
<< j_object.dump(1, '\t') << "\n\n";
|
||||
|
||||
std::cout << "arrays:" << '\n'
|
||||
<< j_array.dump() << "\n\n"
|
||||
<< j_array.dump(-1) << "\n\n"
|
||||
<< j_array.dump(0) << "\n\n"
|
||||
<< j_array.dump(4) << "\n\n"
|
||||
<< j_array.dump(1, '\t') << "\n\n";
|
||||
|
||||
std::cout << "strings:" << '\n'
|
||||
<< j_string.dump() << '\n'
|
||||
<< j_string.dump(-1, ' ', true) << '\n';
|
||||
|
||||
// create JSON value with invalid UTF-8 byte sequence
|
||||
json j_invalid = "ä\xA9ü";
|
||||
try
|
||||
{
|
||||
std::cout << j_invalid.dump() << '\n';
|
||||
}
|
||||
catch (const json::type_error& e)
|
||||
{
|
||||
std::cout << e.what() << '\n';
|
||||
}
|
||||
|
||||
std::cout << "string with replaced invalid characters: "
|
||||
<< j_invalid.dump(-1, ' ', false, json::error_handler_t::replace)
|
||||
<< "\nstring with ignored invalid characters: "
|
||||
<< j_invalid.dump(-1, ' ', false, json::error_handler_t::ignore)
|
||||
<< '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/dump.output"
|
||||
objects:
|
||||
{"one":1,"two":2}
|
||||
|
||||
{"one":1,"two":2}
|
||||
|
||||
{
|
||||
"one": 1,
|
||||
"two": 2
|
||||
}
|
||||
|
||||
{
|
||||
"one": 1,
|
||||
"two": 2
|
||||
}
|
||||
|
||||
{
|
||||
"one": 1,
|
||||
"two": 2
|
||||
}
|
||||
|
||||
arrays:
|
||||
[1,2,4,8,16]
|
||||
|
||||
[1,2,4,8,16]
|
||||
|
||||
[
|
||||
1,
|
||||
2,
|
||||
4,
|
||||
8,
|
||||
16
|
||||
]
|
||||
|
||||
[
|
||||
1,
|
||||
2,
|
||||
4,
|
||||
8,
|
||||
16
|
||||
]
|
||||
|
||||
[
|
||||
1,
|
||||
2,
|
||||
4,
|
||||
8,
|
||||
16
|
||||
]
|
||||
|
||||
strings:
|
||||
"Hellö 😀!"
|
||||
"Hell\u00f6 \ud83d\ude00!"
|
||||
[json.exception.type_error.316] invalid UTF-8 byte at index 2: 0xA9
|
||||
string with replaced invalid characters: "ä�ü"
|
||||
string with ignored invalid characters: "äü"
|
||||
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [to_string](to_string.md) returns a string representation of a JSON value
|
||||
- [operator<<](../operator_ltlt.md) serialize to stream
|
||||
- [`to_string`](to_string.md) - returns a string representation of a JSON value
|
||||
- [`operator<<`](../operator_ltlt.md) - serialize to stream
|
||||
- [`basic_json_view::dump`](../basic_json_view/dump.md) - the corresponding function of `basic_json_view`, serializing
|
||||
directly from a flat index without building a `basic_json` value
|
||||
- [Serialization](../../features/serialization.md) - the serialization article
|
||||
|
||||
## Version history
|
||||
@@ -97,3 +205,5 @@ Binary values are serialized as an object containing two keys:
|
||||
- Error handlers added in version 3.4.0.
|
||||
- Serialization of binary values added in version 3.8.0.
|
||||
- Error handler `keep` added in version 3.13.0.
|
||||
- Doubles are written with the shortest digits (Żmij instead of Grisu2) since version 3.13.0; about 0.1% of doubles are
|
||||
written differently, most of them with fewer digits.
|
||||
@@ -1,11 +1,11 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/dump/" rel="canonical"><link href=../diff/ rel=prev><link href=../emplace/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>dump - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../../css/custom.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsondump class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> dump </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> <div classLine truncated
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/dump/" rel="canonical"><link href=../diff/ rel=prev><link href=../emplace/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>dump - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel=stylesheet href=../../../css/custom.css><link rel=stylesheet href=../../../css/brand.css><link rel=stylesheet href=../../../css/fig-sax.css><link rel=stylesheet href=../../../css/fig-jsonview.css><link rel=stylesheet href=../../../css/fig-exceptions.css><link rel=stylesheet href=../../../css/fig-pointer.css><link rel=stylesheet href=../../../css/fig-charts.css><link rel=stylesheet href=../../../css/fig-integration.css><link rel=stylesheet href=../../../css/fig-macros.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsondump class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> dump </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.5Line truncated
|
||||
<span class=w> </span><span class=k>const</span><span class=w> </span><span class=kt>char</span><span class=w> </span><span class=n>indent_char</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=sc>' '</span><span class=p>,</span>
|
||||
<span class=w> </span><span class=k>const</span><span class=w> </span><span class=kt>bool</span><span class=w> </span><span class=n>ensure_ascii</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=nb>false</span><span class=p>,</span>
|
||||
<span class=w> </span><span class=k>const</span><span class=w> </span><span class=n>error_handler_t</span><span class=w> </span><span class=n>error_handler</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>error_handler_t</span><span class=o>::</span><span class=n>strict</span><span class=p>)</span><span class=w> </span><span class=k>const</span><span class=p>;</span>
|
||||
</code></pre></div> <p>Serialization function for <abbr title="JavaScript Object Notation">JSON</abbr> values. The function tries to mimic Python's <a href="https://docs.python.org/2/library/json.html#json.dump"><code>json.dumps()</code> function</a>, and currently supports its <code>indent</code> and <code>ensure_ascii</code> parameters.</p> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">¶</a></h2> <dl> <dt><code>indent</code> (in)</dt> <dd>If <code>indent</code> is nonnegative, then array elements and object members will be pretty-printed with that indent level. An indent level of <code>0</code> will only insert newlines. <code>-1</code> (the default) selects the most compact representation.</dd> <dt><code>indent_char</code> (in)</dt> <dd>The character to use for indentation if <code>indent</code> is greater than <code>0</code>. The default is <code></code> (space).</dd> <dt><code>ensure_ascii</code> (in)</dt> <dd>If <code>ensure_ascii</code> is true, all non-<abbr title="American Standard Code for Information Interchange">ASCII</abbr> characters in the output are escaped with <code>\uXXXX</code> sequences, and the result consists of <abbr title="American Standard Code for Information Interchange">ASCII</abbr> characters only.</dd> <dt><code>error_handler</code> (in)</dt> <dd>how to react on decoding errors; there are four possible values (see <a href=../error_handler_t/ ><code>error_handler_t</code></a>: <code>strict</code> (throws an exception in case a decoding error occurs; default), <code>replace</code> (replace invalid <abbr title="Unicode Transformation Format">UTF</abbr>-8 sequences with U+FFFD), <code>ignore</code> (ignore invalid <abbr title="Unicode Transformation Format">UTF</abbr>-8 sequences during serialization; all valid bytes are copied to the output unchanged, and invalid bytes are dropped), and <code>keep</code> (write the ill-formed bytes to the output as is, without escaping them, even if <code>ensure_ascii</code> is <code class=highlight><span class=nb>true</span></code>; the result is then not valid <abbr title="Unicode Transformation Format">UTF</abbr>-8, but equals the input bytes exactly, and well-formed characters around the ill-formed bytes are still escaped as usual)).</dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">¶</a></h2> <p>string containing the serialization of the <abbr title="JavaScript Object Notation">JSON</abbr> value</p> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">¶</a></h2> <p>Strong guarantee: if an exception is thrown, there are no changes to any <abbr title="JavaScript Object Notation">JSON</abbr> value.</p> <h2 id=exceptions>Exceptions<a class=headerlink href=#exceptions title="Permanent link">¶</a></h2> <p>Throws <a href=../../../home/exceptions/#jsonexceptiontype_error316><code>type_error.316</code></a> if a string stored inside the <abbr title="JavaScript Object Notation">JSON</abbr> value is not <abbr title="Unicode Transformation Format">UTF</abbr>-8 encoded and <code>error_handler</code> is set to <code>strict</code></p> <div class="admonition warning"> <p class=admonition-title>Serializing untrusted input</p> <p>When serializing values that may contain invalid or untrusted <abbr title="Unicode Transformation Format">UTF</abbr>-8 (e.g., bytes taken directly from network input), <code>dump()</code> throws <a href=../../../home/exceptions/#jsonexceptiontype_error316><code>type_error.316</code></a> in the default <code>strict</code> mode. To serialize such data without throwing, pass <a href=../error_handler_t/ ><code>error_handler_t::replace</code></a> (substitutes U+FFFD) or <a href=../error_handler_t/ ><code>error_handler_t::ignore</code></a>. Callers that serialize untrusted input on a crash-sensitive path should either choose a non-strict error handler or wrap <code>dump()</code> in a <code class=highlight><span class=k>try</span></code>/<code class=highlight><span class=k>catch</span></code>.</p> <p>See the <a href=../../../home/faq/#serializing-untrusted-or-invalid-utf-8><abbr title="Frequently Asked Questions">FAQ</abbr></a> for details.</p> </div> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">¶</a></h2> <p>Linear.</p> <h2 id=notes>Notes<a class=headerlink href=#notes title="Permanent link">¶</a></h2> <p>Binary values are serialized as an object containing two keys:</p> <ul> <li>"bytes": an array of bytes as integers</li> <li>"subtype": the subtype as integer or <code class=highlight><span class=kc>null</span></code> if the binary has no subtype</li> </ul> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example</summary> <p>The following example shows the effect of different <code>indent</code>, <code>indent_char</code>, and <code>ensure_Line truncated
|
||||
</code></pre></div> <p>Serialization function for <abbr title="JavaScript Object Notation">JSON</abbr> values. The function tries to mimic Python's <a href="https://docs.python.org/2/library/json.html#json.dump"><code>json.dumps()</code> function</a>, and currently supports its <code>indent</code> and <code>ensure_ascii</code> parameters.</p> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">¶</a></h2> <dl> <dt><code>indent</code> (in)</dt> <dd>If <code>indent</code> is nonnegative, then array elements and object members will be pretty-printed with that indent level. An indent level of <code>0</code> will only insert newlines. <code>-1</code> (the default) selects the most compact representation.</dd> <dt><code>indent_char</code> (in)</dt> <dd>The character to use for indentation if <code>indent</code> is greater than <code>0</code>. The default is <code></code> (space).</dd> <dt><code>ensure_ascii</code> (in)</dt> <dd>If <code>ensure_ascii</code> is true, all non-<abbr title="American Standard Code for Information Interchange">ASCII</abbr> characters in the output are escaped with <code>\uXXXX</code> sequences, and the result consists of <abbr title="American Standard Code for Information Interchange">ASCII</abbr> characters only.</dd> <dt><code>error_handler</code> (in)</dt> <dd>how to react on decoding errors; there are four possible values (see <a href=../error_handler_t/ ><code>error_handler_t</code></a>: <code>strict</code> (throws an exception in case a decoding error occurs; default), <code>replace</code> (replace invalid <abbr title="Unicode Transformation Format">UTF</abbr>-8 sequences with U+FFFD), <code>ignore</code> (ignore invalid <abbr title="Unicode Transformation Format">UTF</abbr>-8 sequences during serialization; all valid bytes are copied to the output unchanged, and invalid bytes are dropped), and <code>keep</code> (write the ill-formed bytes to the output as is, without escaping them, even if <code>ensure_ascii</code> is <code class=highlight><span class=nb>true</span></code>; the result is then not valid <abbr title="Unicode Transformation Format">UTF</abbr>-8, but equals the input bytes exactly, and well-formed characters around the ill-formed bytes are still escaped as usual)).</dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">¶</a></h2> <p>string containing the serialization of the <abbr title="JavaScript Object Notation">JSON</abbr> value</p> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">¶</a></h2> <p>Strong guarantee: if an exception is thrown, there are no changes to any <abbr title="JavaScript Object Notation">JSON</abbr> value.</p> <h2 id=exceptions>Exceptions<a class=headerlink href=#exceptions title="Permanent link">¶</a></h2> <p>Throws <a href=../../../home/exceptions/#jsonexceptiontype_error316><code>type_error.316</code></a> if a string stored inside the <abbr title="JavaScript Object Notation">JSON</abbr> value is not <abbr title="Unicode Transformation Format">UTF</abbr>-8 encoded and <code>error_handler</code> is set to <code>strict</code></p> <div class="admonition warning"> <p class=admonition-title>Serializing untrusted input</p> <p>When serializing values that may contain invalid or untrusted <abbr title="Unicode Transformation Format">UTF</abbr>-8 (e.g., bytes taken directly from network input), <code>dump()</code> throws <a href=../../../home/exceptions/#jsonexceptiontype_error316><code>type_error.316</code></a> in the default <code>strict</code> mode. To serialize such data without throwing, pass <a href=../error_handler_t/ ><code>error_handler_t::replace</code></a> (substitutes U+FFFD) or <a href=../error_handler_t/ ><code>error_handler_t::ignore</code></a>. Callers that serialize untrusted input on a crash-sensitive path should either choose a non-strict error handler or wrap <code>dump()</code> in a <code class=highlight><span class=k>try</span></code>/<code class=highlight><span class=k>catch</span></code>.</p> <p>See the <a href=../../../home/faq/#serializing-untrusted-or-invalid-utf-8><abbr title="Frequently Asked Questions">FAQ</abbr></a> for details.</p> </div> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">¶</a></h2> <p>Linear.</p> <h2 id=notes>Notes<a class=headerlink href=#notes title="Permanent link">¶</a></h2> <p>Floating-point numbers are written with the fewest digits that read back as the same value (for <code class=highlight><span class=kt>double</span></code>; see <a href=../../../features/types/number_handling/#number-serialization>number handling</a>).</p> <p>Binary values are serialized as an object containing two keys:</p> <ul> <li>"bytes": an array of bytes as integers</li> <li>"subtype": the subtype as integer or <code class=highlight><span class=kc>null</span></code> if the binary has no subtype</li> </ul> <h2 id=exaLine truncated
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -37,11 +37,11 @@
|
||||
<span class=w> </span><span class=n>json</span><span class=w> </span><span class=n>j_invalid</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=s>"ä</span><span class=se>\xA9</span><span class=s>ü"</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=k>try</span>
|
||||
<span class=w> </span><span class=p>{</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>j_invalid</span><span class=p>.</span><span class=n>dump</span><span class=p>()</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>endl</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>j_invalid</span><span class=p>.</span><span class=n>dump</span><span class=p>()</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=p>}</span>
|
||||
<span class=w> </span><span class=k>catch</span><span class=w> </span><span class=p>(</span><span class=k>const</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>type_error</span><span class=o>&</span><span class=w> </span><span class=n>e</span><span class=p>)</span>
|
||||
<span class=w> </span><span class=p>{</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>e</span><span class=p>.</span><span class=n>what</span><span class=p>()</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>endl</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>e</span><span class=p>.</span><span class=n>what</span><span class=p>()</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=p>}</span>
|
||||
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=s>"string with replaced invalid characters: "</span>
|
||||
@@ -105,4 +105,4 @@
|
||||
<span class=p>[</span><span class=err>jso</span><span class=kc>n</span><span class=err>.excep</span><span class=kc>t</span><span class=err>io</span><span class=kc>n</span><span class=err>.</span><span class=kc>t</span><span class=err>ype_error.</span><span class=mi>316</span><span class=p>]</span><span class=w> </span><span class=err>i</span><span class=kc>n</span><span class=err>valid</span><span class=w> </span><span class=err>UTF</span><span class=mi>-8</span><span class=w> </span><span class=err>by</span><span class=kc>te</span><span class=w> </span><span class=err>a</span><span class=kc>t</span><span class=w> </span><span class=err>i</span><span class=kc>n</span><span class=err>dex</span><span class=w> </span><span class=mi>2</span><span class=p>:</span><span class=w> </span><span class=mi>0</span><span class=err>xA</span><span class=mi>9</span>
|
||||
<span class=err>s</span><span class=kc>tr</span><span class=err>i</span><span class=kc>n</span><span class=err>g</span><span class=w> </span><span class=err>wi</span><span class=kc>t</span><span class=err>h</span><span class=w> </span><span class=err>replaced</span><span class=w> </span><span class=err>i</span><span class=kc>n</span><span class=err>valid</span><span class=w> </span><span class=err>charac</span><span class=kc>ters</span><span class=p>:</span><span class=w> </span><span class=s2>"ä�ü"</span>
|
||||
<span class=err>s</span><span class=kc>tr</span><span class=err>i</span><span class=kc>n</span><span class=err>g</span><span class=w> </span><span class=err>wi</span><span class=kc>t</span><span class=err>h</span><span class=w> </span><span class=err>ig</span><span class=kc>n</span><span class=err>ored</span><span class=w> </span><span class=err>i</span><span class=kc>n</span><span class=err>valid</span><span class=w> </span><span class=err>charac</span><span class=kc>ters</span><span class=p>:</span><span class=w> </span><span class=s2>"äü"</span>
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../to_string/ >to_string</a> returns a string representation of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../../operator_ltlt/ >operator<<</a> serialize to stream</li> <li><a href=../../../features/serialization/ >Serialization</a> - the serialization article</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 1.0.0.</li> <li>Indentation character <code>indent_char</code>, option <code>ensure_ascii</code> and exceptions added in version 3.0.0.</li> <li>Error handlers added in version 3.4.0.</li> <li>Serialization of binary values added in version 3.8.0.</li> <li>Error handler <code>keep</code> added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 4, 2026 10:13:49 UTC">October 4, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4C0 465.5 14.3 480 31.9 480H416cLine truncated
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../to_string/ ><code>to_string</code></a> - returns a string representation of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../../operator_ltlt/ ><code>operator<<</code></a> - serialize to stream</li> <li><a href=../../basic_json_view/dump/ ><code>basic_json_view::dump</code></a> - the corresponding function of <code>basic_json_view</code>, serializing directly from a flat index without building a <code>basic_json</code> value</li> <li><a href=../../../features/serialization/ >Serialization</a> - the serialization article</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 1.0.0.</li> <li>Indentation character <code>indent_char</code>, option <code>ensure_ascii</code> and exceptions added in version 3.0.0.</li> <li>Error handlers added in version 3.4.0.</li> <li>Serialization of binary values added in version 3.8.0.</li> <li>Error handler <code>keep</code> added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>.</li> <li>Doubles are written with the shortest digits (Żmij instead of Grisu2) since version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>; about 0.1% of doubles are written differently, most of them with fewer digits.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../diff/ class="md-footer__link md-footer__link--prev" aria-label="Previous: diff"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> diff </div> </div> </a> <a href=../emplace/ class="md-footer__link md-footer__link--next" aria-label="Next: emplace"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> emplace </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.Line truncated
|
||||
@@ -43,6 +43,8 @@ Linear.
|
||||
|
||||
## Notes
|
||||
|
||||
Floating-point numbers are written with the fewest digits that read back as the same value (for `double`; see [number handling](https://json.nlohmann.me/features/types/number_handling/#number-serialization)).
|
||||
|
||||
Binary values are serialized as an object containing two keys:
|
||||
|
||||
- "bytes": an array of bytes as integers
|
||||
@@ -58,7 +60,7 @@ The following example shows the effect of different `indent`, `indent_char`, and
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -90,11 +92,11 @@ int main()
|
||||
json j_invalid = "ä\xA9ü";
|
||||
try
|
||||
{
|
||||
std::cout << j_invalid.dump() << std::endl;
|
||||
std::cout << j_invalid.dump() << '\n';
|
||||
}
|
||||
catch (const json::type_error& e)
|
||||
{
|
||||
std::cout << e.what() << std::endl;
|
||||
std::cout << e.what() << '\n';
|
||||
}
|
||||
|
||||
std::cout << "string with replaced invalid characters: "
|
||||
@@ -167,8 +169,9 @@ string with ignored invalid characters: "äü"
|
||||
|
||||
## See also
|
||||
|
||||
- [to_string](https://json.nlohmann.me/api/basic_json/to_string/index.md) returns a string representation of a JSON value
|
||||
- [operator\<<](https://json.nlohmann.me/api/operator_ltlt/index.md) serialize to stream
|
||||
- [`to_string`](https://json.nlohmann.me/api/basic_json/to_string/index.md) - returns a string representation of a JSON value
|
||||
- [`operator<<`](https://json.nlohmann.me/api/operator_ltlt/index.md) - serialize to stream
|
||||
- [`basic_json_view::dump`](https://json.nlohmann.me/api/basic_json_view/dump/index.md) - the corresponding function of `basic_json_view`, serializing directly from a flat index without building a `basic_json` value
|
||||
- [Serialization](https://json.nlohmann.me/features/serialization/index.md) - the serialization article
|
||||
|
||||
## Version history
|
||||
@@ -178,3 +181,4 @@ string with ignored invalid characters: "äü"
|
||||
- Error handlers added in version 3.4.0.
|
||||
- Serialization of binary values added in version 3.8.0.
|
||||
- Error handler `keep` added in version 3.13.0 unreleased.
|
||||
- Doubles are written with the shortest digits (Żmij instead of Grisu2) since version 3.13.0 unreleased; about 0.1% of doubles are written differently, most of them with fewer digits.
|
||||
@@ -52,23 +52,60 @@ Logarithmic in the size of the container, O(log(`size()`)).
|
||||
the same key.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/emplace.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create JSON values
|
||||
json object = {{"one", 1}, {"two", 2}};
|
||||
json null;
|
||||
|
||||
// print values
|
||||
std::cout << object << '\n';
|
||||
std::cout << null << '\n';
|
||||
|
||||
// add values
|
||||
auto res1 = object.emplace("three", 3);
|
||||
null.emplace("A", "a");
|
||||
null.emplace("B", "b");
|
||||
|
||||
// the following call will not add an object, because there is already
|
||||
// a value stored at key "B"
|
||||
auto res2 = null.emplace("B", "c");
|
||||
|
||||
// print values
|
||||
std::cout << object << '\n';
|
||||
std::cout << *res1.first << " " << std::boolalpha << res1.second << '\n';
|
||||
|
||||
std::cout << null << '\n';
|
||||
std::cout << *res2.first << " " << std::boolalpha << res2.second << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/emplace.output"
|
||||
{"one":1,"two":2}
|
||||
null
|
||||
{"one":1,"three":3,"two":2}
|
||||
3 true
|
||||
{"A":"a","B":"b"}
|
||||
"b" false
|
||||
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [emplace_back](emplace_back.md) add a value to an array
|
||||
- [insert](insert.md) add values to an array/object
|
||||
- [`emplace_back`](emplace_back.md) - add a value to an array
|
||||
- [`insert`](insert.md) - add values to an array/object
|
||||
- [Modifying values](../../features/modifying_values.md) - the article on modifying values
|
||||
|
||||
## Version history
|
||||
|
||||
- Since version 2.0.8.
|
||||
- Added in version 2.0.8.
|
||||
- Fixed in version 3.13.0: for [`ordered_json`](../ordered_json.md), the value could previously only be passed as an
|
||||
rvalue; it can now also be passed as an lvalue or a `#!cpp const` lvalue, matching the behavior of `json`.
|
||||
@@ -1,9 +1,9 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/emplace/" rel="canonical"><link href=../dump/ rel=prev><link href=../emplace_back/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>emplace - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../../css/custom.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsonemplace class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> emplace </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </Line truncated
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/emplace/" rel="canonical"><link href=../dump/ rel=prev><link href=../emplace_back/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>emplace - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel=stylesheet href=../../../css/custom.css><link rel=stylesheet href=../../../css/brand.css><link rel=stylesheet href=../../../css/fig-sax.css><link rel=stylesheet href=../../../css/fig-jsonview.css><link rel=stylesheet href=../../../css/fig-exceptions.css><link rel=stylesheet href=../../../css/fig-pointer.css><link rel=stylesheet href=../../../css/fig-charts.css><link rel=stylesheet href=../../../css/fig-integration.css><link rel=stylesheet href=../../../css/fig-macros.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsonemplace class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> emplace </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1Line truncated
|
||||
<span class=n>std</span><span class=o>::</span><span class=n>pair</span><span class=o><</span><span class=n>iterator</span><span class=p>,</span><span class=w> </span><span class=kt>bool</span><span class=o>></span><span class=w> </span><span class=n>emplace</span><span class=p>(</span><span class=n>Args</span><span class=o>&&</span><span class=w> </span><span class=p>...</span><span class=w> </span><span class=n>args</span><span class=p>);</span>
|
||||
</code></pre></div> <p>Inserts a new element into a <abbr title="JavaScript Object Notation">JSON</abbr> object constructed in-place with the given <code>args</code> if there is no element with the key in the container. If the function is called on a <abbr title="JavaScript Object Notation">JSON</abbr> null value, an empty object is created before appending the value created from <code>args</code>.</p> <h2 id=template-parameters>Template parameters<a class=headerlink href=#template-parameters title="Permanent link">¶</a></h2> <dl> <dt><code>Args</code></dt> <dd>compatible types to create a <code>basic_json</code> object</dd> </dl> <h2 id=iterator-invalidation>Iterator invalidation<a class=headerlink href=#iterator-invalidation title="Permanent link">¶</a></h2> <p>For <a href=../../ordered_json/ ><code>ordered_json</code></a>, adding a value to an object can yield a reallocation, in which case all iterators (including the <code>end()</code> iterator) and all references to the elements are invalidated.</p> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">¶</a></h2> <dl> <dt><code>args</code> (in)</dt> <dd>arguments to forward to a constructor of <code>basic_json</code></dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">¶</a></h2> <p>a pair consisting of an iterator to the inserted element, or the already-existing element if no insertion happened, and a <code class=highlight><span class=kt>bool</span></code> denoting whether the insertion took place.</p> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">¶</a></h2> <p>Strong guarantee: if an exception is thrown, there are no changes to any <abbr title="JavaScript Object Notation">JSON</abbr> value. As an exception, a <code class=highlight><span class=kc>null</span></code> value is converted to an empty object before the element is added and keeps that type if adding the element throws.</p> <h2 id=exceptions>Exceptions<a class=headerlink href=#exceptions title="Permanent link">¶</a></h2> <p>Throws <a href=../../../home/exceptions/#jsonexceptiontype_error311><code>type_error.311</code></a> when called on a type other than <abbr title="JavaScript Object Notation">JSON</abbr> object or <code class=highlight><span class=kc>null</span></code>; example: <code>"cannot use emplace() with number"</code></p> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">¶</a></h2> <p>Logarithmic in the size of the container, O(log(<code>size()</code>)).</p> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example</summary> <p>The example shows how <code>emplace()</code> can be used to add elements to a <abbr title="JavaScript Object Notation">JSON</abbr> object. Note how the <code class=highlight><span class=kc>null</span></code> value was silently converted to a <abbr title="JavaScript Object Notation">JSON</abbr> object. Further note how no value is added if there was already one value stored with the same key.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -37,4 +37,4 @@
|
||||
<span class=mi>3</span><span class=w> </span><span class=kc>true</span>
|
||||
<span class=p>{</span><span class=nt>"A"</span><span class=p>:</span><span class=s2>"a"</span><span class=p>,</span><span class=nt>"B"</span><span class=p>:</span><span class=s2>"b"</span><span class=p>}</span>
|
||||
<span class=s2>"b"</span><span class=w> </span><span class=kc>false</span>
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../emplace_back/ >emplace_back</a> add a value to an array</li> <li><a href=../insert/ >insert</a> add values to an array/object</li> <li><a href=../../../features/modifying_values/ >Modifying values</a> - the article on modifying values</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Since version 2.0.8.</li> <li>Fixed in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>: for <a href=../../ordered_json/ ><code>ordered_json</code></a>, the value could previously only be passed as an rvalue; it can now also be passed as an lvalue or a <code class=highlight><span class=k>const</span></code> lvalue, matching the behavior of <code>json</code>.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 4, 2026 09:46:25 UTC">October 4, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4C0 465.5 14.3 480 31.9 480H416c17.6 0 32-14.5 32-32.3V64.3c0-17.8-14.4-32.3-32-32.3M135.4 416H69V20Line truncated
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../emplace_back/ ><code>emplace_back</code></a> - add a value to an array</li> <li><a href=../insert/ ><code>insert</code></a> - add values to an array/object</li> <li><a href=../../../features/modifying_values/ >Modifying values</a> - the article on modifying values</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 2.0.8.</li> <li>Fixed in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>: for <a href=../../ordered_json/ ><code>ordered_json</code></a>, the value could previously only be passed as an rvalue; it can now also be passed as an lvalue or a <code class=highlight><span class=k>const</span></code> lvalue, matching the behavior of <code>json</code>.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../dump/ class="md-footer__link md-footer__link--prev" aria-label="Previous: dump"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> dump </div> </div> </a> <a href=../emplace_back/ class="md-footer__link md-footer__link--next" aria-label="Next: emplace_back"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> emplace_back </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 35Line truncated
|
||||
@@ -45,7 +45,7 @@ The example shows how `emplace()` can be used to add elements to a JSON object.
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -88,11 +88,11 @@ null
|
||||
|
||||
## See also
|
||||
|
||||
- [emplace_back](https://json.nlohmann.me/api/basic_json/emplace_back/index.md) add a value to an array
|
||||
- [insert](https://json.nlohmann.me/api/basic_json/insert/index.md) add values to an array/object
|
||||
- [`emplace_back`](https://json.nlohmann.me/api/basic_json/emplace_back/index.md) - add a value to an array
|
||||
- [`insert`](https://json.nlohmann.me/api/basic_json/insert/index.md) - add values to an array/object
|
||||
- [Modifying values](https://json.nlohmann.me/features/modifying_values/index.md) - the article on modifying values
|
||||
|
||||
## Version history
|
||||
|
||||
- Since version 2.0.8.
|
||||
- Added in version 2.0.8.
|
||||
- Fixed in version 3.13.0 unreleased: for [`ordered_json`](https://json.nlohmann.me/api/ordered_json/index.md), the value could previously only be passed as an rvalue; it can now also be passed as an lvalue or a `const` lvalue, matching the behavior of `json`.
|
||||
@@ -50,22 +50,50 @@ Amortized constant.
|
||||
silently converted to a JSON array.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/emplace_back.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create JSON values
|
||||
json array = {1, 2, 3, 4, 5};
|
||||
json null;
|
||||
|
||||
// print values
|
||||
std::cout << array << '\n';
|
||||
std::cout << null << '\n';
|
||||
|
||||
// add values
|
||||
array.emplace_back(6);
|
||||
null.emplace_back("first");
|
||||
null.emplace_back(3, "second");
|
||||
|
||||
// print values
|
||||
std::cout << array << '\n';
|
||||
std::cout << null << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/emplace_back.output"
|
||||
[1,2,3,4,5]
|
||||
null
|
||||
[1,2,3,4,5,6]
|
||||
["first",["second","second","second"]]
|
||||
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [operator+=](operator+=.md) add a value to an array/object
|
||||
- [push_back](push_back.md) add a value to an array/object
|
||||
- [`operator+=`](operator+=.md) - add a value to an array/object
|
||||
- [`push_back`](push_back.md) - add a value to an array/object
|
||||
- [Modifying values](../../features/modifying_values.md) - the article on modifying values
|
||||
|
||||
## Version history
|
||||
|
||||
- Since version 2.0.8.
|
||||
- Added in version 2.0.8.
|
||||
- Returns reference since 3.7.0.
|
||||
@@ -1,9 +1,9 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/emplace_back/" rel="canonical"><link href=../emplace/ rel=prev><link href=../empty/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>emplace_back - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../../css/custom.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsonemplace_back class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> emplace_back </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9Line truncated
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/emplace_back/" rel="canonical"><link href=../emplace/ rel=prev><link href=../empty/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>emplace_back - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel=stylesheet href=../../../css/custom.css><link rel=stylesheet href=../../../css/brand.css><link rel=stylesheet href=../../../css/fig-sax.css><link rel=stylesheet href=../../../css/fig-jsonview.css><link rel=stylesheet href=../../../css/fig-exceptions.css><link rel=stylesheet href=../../../css/fig-pointer.css><link rel=stylesheet href=../../../css/fig-charts.css><link rel=stylesheet href=../../../css/fig-integration.css><link rel=stylesheet href=../../../css/fig-macros.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsonemplace_back class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> emplace_back </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5Line truncated
|
||||
<span class=n>reference</span><span class=w> </span><span class=n>emplace_back</span><span class=p>(</span><span class=n>Args</span><span class=o>&&</span><span class=w> </span><span class=p>...</span><span class=w> </span><span class=n>args</span><span class=p>);</span>
|
||||
</code></pre></div> <p>Creates a <abbr title="JavaScript Object Notation">JSON</abbr> value from the passed parameters <code>args</code> to the end of the <abbr title="JavaScript Object Notation">JSON</abbr> value. If the function is called on a <abbr title="JavaScript Object Notation">JSON</abbr> <code class=highlight><span class=kc>null</span></code> value, an empty array is created before appending the value created from <code>args</code>.</p> <h2 id=template-parameters>Template parameters<a class=headerlink href=#template-parameters title="Permanent link">¶</a></h2> <dl> <dt><code>Args</code></dt> <dd>compatible types to create a <code>basic_json</code> object</dd> </dl> <h2 id=iterator-invalidation>Iterator invalidation<a class=headerlink href=#iterator-invalidation title="Permanent link">¶</a></h2> <p>By adding an element to the end of the array, a reallocation can happen, in which case all iterators (including the <a href=../end/ ><code>end()</code></a> iterator) and all references to the elements are invalidated. Otherwise, only the <a href=../end/ ><code>end()</code></a> iterator is invalidated.</p> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">¶</a></h2> <dl> <dt><code>args</code> (in)</dt> <dd>arguments to forward to a constructor of <code>basic_json</code></dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">¶</a></h2> <p>reference to the inserted element</p> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">¶</a></h2> <p>Strong guarantee: if an exception is thrown, there are no changes to any <abbr title="JavaScript Object Notation">JSON</abbr> value. As an exception, a <code class=highlight><span class=kc>null</span></code> value is converted to an empty array before the element is added and keeps that type if adding the element throws.</p> <h2 id=exceptions>Exceptions<a class=headerlink href=#exceptions title="Permanent link">¶</a></h2> <p>Throws <a href=../../../home/exceptions/#jsonexceptiontype_error311><code>type_error.311</code></a> when called on a type other than <abbr title="JavaScript Object Notation">JSON</abbr> array or <code class=highlight><span class=kc>null</span></code>; example: <code>"cannot use emplace_back() with number"</code></p> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">¶</a></h2> <p>Amortized constant.</p> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example</summary> <p>The example shows how <code>emplace_back()</code> can be used to add elements to a <abbr title="JavaScript Object Notation">JSON</abbr> array. Note how the <code>null</code> value was silently converted to a <abbr title="JavaScript Object Notation">JSON</abbr> array.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -28,4 +28,4 @@
|
||||
<span class=kc>null</span>
|
||||
<span class=p>[</span><span class=mi>1</span><span class=p>,</span><span class=mi>2</span><span class=p>,</span><span class=mi>3</span><span class=p>,</span><span class=mi>4</span><span class=p>,</span><span class=mi>5</span><span class=p>,</span><span class=mi>6</span><span class=p>]</span>
|
||||
<span class=p>[</span><span class=s2>"first"</span><span class=p>,[</span><span class=s2>"second"</span><span class=p>,</span><span class=s2>"second"</span><span class=p>,</span><span class=s2>"second"</span><span class=p>]]</span>
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../operator%2B%3D/ >operator+=</a> add a value to an array/object</li> <li><a href=../push_back/ >push_back</a> add a value to an array/object</li> <li><a href=../../../features/modifying_values/ >Modifying values</a> - the article on modifying values</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Since version 2.0.8.</li> <li>Returns reference since 3.7.0.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 2, 2026 09:32:15 UTC">October 2, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4C0 465.5 14.3 480 31.9 480H416c17.6 0 32-14.5 32-32.3V64.3c0-17.8-14.4-32.3-32-32.3M135.4 416H69V202.2h66.5V416zM102.2 96a38.5 38.5 0 1 1 0 77 38.5 38.5 0 1 1 0-77m282.1 320h-66.4V312c0-24.8-.5-56.7-34.5-56.7-34.6 0-39.9 27-39.9 54.9V416h-66.4V202.2h63.7v29.2h.9c8.9-16.8 30.6-34.5 62.9-34.5 67.2 0 79.7 44.3 79.7 101.9z"/></svg> </a> <a href="https://www.xing.com/profile/Niels_Lohmann" target="_blank" rel="noopener" title="www.xing.com" class="md-social__link"> Line truncated
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../operator%2B%3D/ ><code>operator+=</code></a> - add a value to an array/object</li> <li><a href=../push_back/ ><code>push_back</code></a> - add a value to an array/object</li> <li><a href=../../../features/modifying_values/ >Modifying values</a> - the article on modifying values</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 2.0.8.</li> <li>Returns reference since 3.7.0.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../emplace/ class="md-footer__link md-footer__link--prev" aria-label="Previous: emplace"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> emplace </div> </div> </a> <a href=../empty/ class="md-footer__link md-footer__link--next" aria-label="Next: empty"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> empty </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a>Line truncated
|
||||
@@ -45,7 +45,7 @@ The example shows how `emplace_back()` can be used to add elements to a JSON arr
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -79,11 +79,11 @@ null
|
||||
|
||||
## See also
|
||||
|
||||
- [operator+=](https://json.nlohmann.me/api/basic_json/operator%2B%3D/index.md) add a value to an array/object
|
||||
- [push_back](https://json.nlohmann.me/api/basic_json/push_back/index.md) add a value to an array/object
|
||||
- [`operator+=`](https://json.nlohmann.me/api/basic_json/operator%2B%3D/index.md) - add a value to an array/object
|
||||
- [`push_back`](https://json.nlohmann.me/api/basic_json/push_back/index.md) - add a value to an array/object
|
||||
- [Modifying values](https://json.nlohmann.me/features/modifying_values/index.md) - the article on modifying values
|
||||
|
||||
## Version history
|
||||
|
||||
- Since version 2.0.8.
|
||||
- Added in version 2.0.8.
|
||||
- Returns reference since 3.7.0.
|
||||
+45
-5
@@ -41,7 +41,7 @@ bool empty() const noexcept
|
||||
|
||||
## Notes
|
||||
|
||||
This function does not return whether a string stored as JSON value is empty -- it returns whether the JSON container
|
||||
This function does not return whether a string stored as JSON value is empty — it returns whether the JSON container
|
||||
itself is empty which is `#!cpp false` in the case of a string.
|
||||
|
||||
## Examples
|
||||
@@ -51,19 +51,59 @@ itself is empty which is `#!cpp false` in the case of a string.
|
||||
The following code uses `empty()` to check if a JSON object contains any elements.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/empty.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create JSON values
|
||||
json j_null;
|
||||
json j_boolean = true;
|
||||
json j_number_integer = 17;
|
||||
json j_number_float = 23.42;
|
||||
json j_object = {{"one", 1}, {"two", 2}};
|
||||
json j_object_empty(json::value_t::object);
|
||||
json j_array = {1, 2, 4, 8, 16};
|
||||
json j_array_empty(json::value_t::array);
|
||||
json j_string = "Hello, world";
|
||||
|
||||
// call empty()
|
||||
std::cout << std::boolalpha;
|
||||
std::cout << j_null.empty() << '\n';
|
||||
std::cout << j_boolean.empty() << '\n';
|
||||
std::cout << j_number_integer.empty() << '\n';
|
||||
std::cout << j_number_float.empty() << '\n';
|
||||
std::cout << j_object.empty() << '\n';
|
||||
std::cout << j_object_empty.empty() << '\n';
|
||||
std::cout << j_array.empty() << '\n';
|
||||
std::cout << j_array_empty.empty() << '\n';
|
||||
std::cout << j_string.empty() << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/empty.output"
|
||||
true
|
||||
false
|
||||
false
|
||||
false
|
||||
false
|
||||
true
|
||||
false
|
||||
true
|
||||
false
|
||||
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [size](size.md) returns the number of elements
|
||||
- [clear](clear.md) clears the content and resets the value to the default value
|
||||
- [`size`](size.md) - returns the number of elements
|
||||
- [`clear`](clear.md) - clears the content and resets the value to the default value
|
||||
- [`basic_json_view::empty`](../basic_json_view/empty.md) - the same check on a zero-copy view
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/empty/" rel="canonical"><link href=../emplace_back/ rel=prev><link href=../end/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>empty - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../../css/custom.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsonempty class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> empty </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> <dLine truncated
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/empty/" rel="canonical"><link href=../emplace_back/ rel=prev><link href=../end/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>empty - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel=stylesheet href=../../../css/custom.css><link rel=stylesheet href=../../../css/brand.css><link rel=stylesheet href=../../../css/fig-sax.css><link rel=stylesheet href=../../../css/fig-jsonview.css><link rel=stylesheet href=../../../css/fig-exceptions.css><link rel=stylesheet href=../../../css/fig-pointer.css><link rel=stylesheet href=../../../css/fig-charts.css><link rel=stylesheet href=../../../css/fig-integration.css><link rel=stylesheet href=../../../css/fig-macros.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsonempty class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> empty </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0Line truncated
|
||||
</code></pre></div> <p>Checks if a <abbr title="JavaScript Object Notation">JSON</abbr> value has no elements (i.e., whether its <a href=../size/ ><code>size()</code></a> is <code>0</code>).</p> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">¶</a></h2> <p>The return value depends on the different types and is defined as follows:</p> <table> <thead> <tr> <th>Value type</th> <th>return value</th> </tr> </thead> <tbody> <tr> <td>null</td> <td><code class=highlight><span class=nb>true</span></code></td> </tr> <tr> <td>boolean</td> <td><code class=highlight><span class=nb>false</span></code></td> </tr> <tr> <td>string</td> <td><code class=highlight><span class=nb>false</span></code></td> </tr> <tr> <td>number</td> <td><code class=highlight><span class=nb>false</span></code></td> </tr> <tr> <td>binary</td> <td><code class=highlight><span class=nb>false</span></code></td> </tr> <tr> <td>object</td> <td>result of function <code>object_t::empty()</code></td> </tr> <tr> <td>array</td> <td>result of function <code>array_t::empty()</code></td> </tr> </tbody> </table> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">¶</a></h2> <p>No-throw guarantee: this function never throws exceptions.</p> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">¶</a></h2> <p>Constant, as long as <a href=../array_t/ ><code>array_t</code></a> and <a href=../object_t/ ><code>object_t</code></a> satisfy the <a href="https://en.cppreference.com/w/cpp/named_req/Container">Container</a> concept; that is, their <code>empty()</code> functions have constant complexity.</p> <h2 id=possible-implementation>Possible implementation<a class=headerlink href=#possible-implementation title="Permanent link">¶</a></h2> <div class=highlight><pre><span></span><code><span class=kt>bool</span><span class=w> </span><span class=nf>empty</span><span class=p>()</span><span class=w> </span><span class=k>const</span><span class=w> </span><span class=k>noexcept</span>
|
||||
<span class=p>{</span>
|
||||
<span class=w> </span><span class=k>return</span><span class=w> </span><span class=n>size</span><span class=p>()</span><span class=w> </span><span class=o>==</span><span class=w> </span><span class=mi>0</span><span class=p>;</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> <h2 id=notes>Notes<a class=headerlink href=#notes title="Permanent link">¶</a></h2> <p>This function does not return whether a string stored as <abbr title="JavaScript Object Notation">JSON</abbr> value is empty -- it returns whether the <abbr title="JavaScript Object Notation">JSON</abbr> container itself is empty which is <code class=highlight><span class=nb>false</span></code> in the case of a string.</p> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example</summary> <p>The following code uses <code>empty()</code> to check if a <abbr title="JavaScript Object Notation">JSON</abbr> object contains any elements.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
</code></pre></div> <h2 id=notes>Notes<a class=headerlink href=#notes title="Permanent link">¶</a></h2> <p>This function does not return whether a string stored as <abbr title="JavaScript Object Notation">JSON</abbr> value is empty — it returns whether the <abbr title="JavaScript Object Notation">JSON</abbr> container itself is empty which is <code class=highlight><span class=nb>false</span></code> in the case of a string.</p> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example</summary> <p>The following code uses <code>empty()</code> to check if a <abbr title="JavaScript Object Notation">JSON</abbr> object contains any elements.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -42,4 +42,4 @@
|
||||
<span class=kc>false</span>
|
||||
<span class=kc>true</span>
|
||||
<span class=kc>false</span>
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../size/ >size</a> returns the number of elements</li> <li><a href=../clear/ >clear</a> clears the content and resets the value to the default value</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 1.0.0.</li> <li>Extended to return <code class=highlight><span class=nb>false</span></code> for binary types in version 3.8.0.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 2, 2026 09:32:15 UTC">October 2, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4C0 465.5 14.3 480 31.9 480H416c17.6 0 32-14.5 32-32.3V64.3c0-17.8-14.4-32.3-32-32.3M135.4 416H69V202.2h66.5V416zM102.2 96a38.5 38.5 0 1 1 0 77 38.5 38.5 0 1 1 0-77m282.1 320h-66.4V312c0-24.8-.5-56.7-34.5-56.7-34.6 0-39.9 27-39.9 54.9V416h-66.4V202.2h63.7v29.2h.9c8.9-16.8 30.6-34.5 62.9-34.5 67.2 0 79.7 44.3 79.7 101.9z"/></svg> </a> <a href="https://www.xing.com/profile/Niels_Lohmann" target="_blank" rel="noopener" title="www.xing.com" class="md-social__link"> <svg xmlns=http://wwLine truncated
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../size/ ><code>size</code></a> - returns the number of elements</li> <li><a href=../clear/ ><code>clear</code></a> - clears the content and resets the value to the default value</li> <li><a href=../../basic_json_view/empty/ ><code>basic_json_view::empty</code></a> - the same check on a zero-copy view</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 1.0.0.</li> <li>Extended to return <code class=highlight><span class=nb>false</span></code> for binary types in version 3.8.0.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../emplace_back/ class="md-footer__link md-footer__link--prev" aria-label="Previous: emplace_back"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> emplace_back </div> </div> </a> <a href=../end/ class="md-footer__link md-footer__link--next" aria-label="Next: end"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> end </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6Line truncated
|
||||
@@ -39,7 +39,7 @@ bool empty() const noexcept
|
||||
|
||||
## Notes
|
||||
|
||||
This function does not return whether a string stored as JSON value is empty -- it returns whether the JSON container itself is empty which is `false` in the case of a string.
|
||||
This function does not return whether a string stored as JSON value is empty — it returns whether the JSON container itself is empty which is `false` in the case of a string.
|
||||
|
||||
## Examples
|
||||
|
||||
@@ -51,7 +51,7 @@ The following code uses `empty()` to check if a JSON object contains any element
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -96,8 +96,9 @@ false
|
||||
|
||||
## See also
|
||||
|
||||
- [size](https://json.nlohmann.me/api/basic_json/size/index.md) returns the number of elements
|
||||
- [clear](https://json.nlohmann.me/api/basic_json/clear/index.md) clears the content and resets the value to the default value
|
||||
- [`size`](https://json.nlohmann.me/api/basic_json/size/index.md) - returns the number of elements
|
||||
- [`clear`](https://json.nlohmann.me/api/basic_json/clear/index.md) - clears the content and resets the value to the default value
|
||||
- [`basic_json_view::empty`](https://json.nlohmann.me/api/basic_json_view/empty/index.md) - the same check on a zero-copy view
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
+60
-6
@@ -7,7 +7,40 @@ const_iterator end() const noexcept;
|
||||
|
||||
Returns an iterator to one past the last element.
|
||||
|
||||
|
||||
<div class="nj-fig-wrap" markdown>
|
||||
<svg class="nj-fig nj-fig--range" viewBox="0 0 600 150" role="img" aria-labelledby="fig-be-title" xmlns="http://www.w3.org/2000/svg">
|
||||
<title id="fig-be-title">A row of fifteen elements followed by a dashed past-the-last position. begin() points to the first element and end() points to the past-the-last position.</title>
|
||||
<defs><marker id="fig-be-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path class="fg-head" d="M0 1 L10 5 L0 9 z"/></marker></defs>
|
||||
<rect class="fg-cell" x="30" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="64" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="98" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="132" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="166" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="200" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="234" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="268" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="302" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="336" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="370" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="404" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="438" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="472" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell" x="506" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-cell fg-cell--end" x="540" y="62" width="30" height="30" rx="5"/>
|
||||
<rect class="fg-pill" x="15" y="8" width="60" height="24" rx="6"/>
|
||||
<text class="fg-pilltext" x="45" y="24">begin</text>
|
||||
<line class="fg-arrow" x1="45" y1="32" x2="45" y2="60" marker-end="url(#fig-be-arrow)"/>
|
||||
<rect class="fg-pill" x="531" y="8" width="48" height="24" rx="6"/>
|
||||
<text class="fg-pilltext" x="555" y="24">end</text>
|
||||
<line class="fg-arrow" x1="555" y1="32" x2="555" y2="60" marker-end="url(#fig-be-arrow)"/>
|
||||
<text class="fg-note fg-note--r" x="537" y="132">Past-the-last element</text>
|
||||
<line class="fg-arrow" x1="555" y1="124" x2="555" y2="96" marker-end="url(#fig-be-arrow)"/>
|
||||
</svg>
|
||||
|
||||
</div>
|
||||
|
||||
<p class="nj-caption" markdown>`end()` points to the position after the last element and `begin()` to the first element;
|
||||
the dashed cell is the past-the-last position, which must not be dereferenced.</p>
|
||||
|
||||
## Return value
|
||||
|
||||
@@ -28,21 +61,42 @@ Constant.
|
||||
The following code shows an example for `end()`.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/end.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create an array value
|
||||
json array = {1, 2, 3, 4, 5};
|
||||
|
||||
// get an iterator to one past the last element
|
||||
json::iterator it = array.end();
|
||||
|
||||
// decrement the iterator to point to the last element
|
||||
--it;
|
||||
|
||||
// serialize the element that the iterator points to
|
||||
std::cout << *it << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/end.output"
|
||||
5
|
||||
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [begin](begin.md) returns an iterator to the first element
|
||||
- [cend](cend.md) returns a const iterator to one past the last element
|
||||
- [rend](rend.md) returns a reverse iterator to one before the first element
|
||||
- [`begin`](begin.md) - returns an iterator to the first element
|
||||
- [`cend`](cend.md) - returns a const iterator to one past the last element
|
||||
- [`rend`](rend.md) - returns a reverse iterator to one before the first element
|
||||
- [Iterators](../../features/iterators.md) - the article on iterators
|
||||
- [`basic_json_view::end`](../basic_json_view/end.md) - the same iteration on a zero-copy view
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/end/" rel="canonical"><link href=../empty/ rel=prev><link href=../end_pos/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>end - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../../css/custom.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsonend class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> end </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> <div class=mdLine truncated
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/end/" rel="canonical"><link href=../empty/ rel=prev><link href=../end_pos/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>end - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel=stylesheet href=../../../css/custom.css><link rel=stylesheet href=../../../css/brand.css><link rel=stylesheet href=../../../css/fig-sax.css><link rel=stylesheet href=../../../css/fig-jsonview.css><link rel=stylesheet href=../../../css/fig-exceptions.css><link rel=stylesheet href=../../../css/fig-pointer.css><link rel=stylesheet href=../../../css/fig-charts.css><link rel=stylesheet href=../../../css/fig-integration.css><link rel=stylesheet href=../../../css/fig-macros.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsonend class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> end </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3Line truncated
|
||||
<span class=n>const_iterator</span><span class=w> </span><span class=nf>end</span><span class=p>()</span><span class=w> </span><span class=k>const</span><span class=w> </span><span class=k>noexcept</span><span class=p>;</span>
|
||||
</code></pre></div> <p>Returns an iterator to one past the last element.</p> <p><img alt="Illustration from cppreference.com" src=../../../images/range-begin-end.svg></p> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">¶</a></h2> <p>iterator one past the last element</p> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">¶</a></h2> <p>No-throw guarantee: this member function never throws exceptions.</p> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">¶</a></h2> <p>Constant.</p> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example</summary> <p>The following code shows an example for <code>end()</code>.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
</code></pre></div> <p>Returns an iterator to one past the last element.</p> <div class=nj-fig-wrap> <p><svg class="nj-fig nj-fig--range" viewbox="0 0 600 150" role=img aria-labelledby=fig-be-title xmlns=http://www.w3.org/2000/svg> <title id=fig-be-title>A row of fifteen elements followed by a dashed past-the-last position. begin() points to the first element and end() points to the past-the-last position.</title> <defs><marker id=fig-be-arrow viewbox="0 0 10 10" refx=9 refy=5 markerwidth=7 markerheight=7 orient=auto><path class=fg-head d="M0 1 L10 5 L0 9 z"/></marker></defs> <rect class=fg-cell x=30 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=64 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=98 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=132 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=166 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=200 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=234 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=268 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=302 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=336 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=370 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=404 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=438 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=472 y=62 width=30 height=30 rx=5 /> <rect class=fg-cell x=506 y=62 width=30 height=30 rx=5 /> <rect x=540 y=62 width=30 height=30 rx=5 class="fg-cell fg-cell--end"/> <rect class=fg-pill x=15 y=8 width=60 height=24 rx=6 /> <text class=fg-pilltext x=45 y=24>begin</text> <line class=fg-arrow x1=45 y1=32 x2=45 y2=60 marker-end=url(#fig-be-arrow) /> <rect class=fg-pill x=531 y=8 width=48 height=24 rx=6 /> <text class=fg-pilltext x=555 y=24>end</text> <line class=fg-arrow x1=555 y1=32 x2=555 y2=60 marker-end=url(#fig-be-arrow) /> <text class="fg-note fg-note--r" x=537 y=132>Past-the-last element</text> <line class=fg-arrow x1=555 y1=124 x2=555 y2=96 marker-end=url(#fig-be-arrow) /> </svg></p> </div> <p class=nj-caption><code>end()</code> points to the position after the last element and <code>begin()</code> to the first element; the dashed cell is the past-the-last position, which must not be dereferenced.</p> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">¶</a></h2> <p>iterator one past the last element</p> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">¶</a></h2> <p>No-throw guarantee: this member function never throws exceptions.</p> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">¶</a></h2> <p>Constant.</p> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example</summary> <p>The following code shows an example for <code>end()</code>.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -20,4 +20,4 @@
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=o>*</span><span class=n>it</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code><span class=mi>5</span>
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../begin/ >begin</a> returns an iterator to the first element</li> <li><a href=../cend/ >cend</a> returns a const iterator to one past the last element</li> <li><a href=../rend/ >rend</a> returns a reverse iterator to one before the first element</li> <li><a href=../../../features/iterators/ >Iterators</a> - the article on iterators</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 1.0.0.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 2, 2026 09:32:15 UTC">October 2, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4C0 465.5 14.3 480 31.9 480H416c17.6 0 32-14.5 32-32.3V64.3c0-17.8-14.4-32.3-32-32.3M135.4 416H69V202.2h66.5V416zM102.2 96a38.5 38.5 0 1 1 0 77 38.5 38.5 0 1 1 0-77m282.1 320h-66.4V312c0-24.8-.5-56.7-34.5-56.7-34.6 0-39.9 27-39.9 54.9V416h-66.4V202.2h63.7v29.2h.9c8.9-16.8 30.6-34.5 62.9-34.5 67.2 0 79.7 44.3 79.7 101.9z"/></svg> </a> <a href="https://www.xing.com/profile/Niels_Lohmann" target="_blank" rel="noopener" Line truncated
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../begin/ ><code>begin</code></a> - returns an iterator to the first element</li> <li><a href=../cend/ ><code>cend</code></a> - returns a const iterator to one past the last element</li> <li><a href=../rend/ ><code>rend</code></a> - returns a reverse iterator to one before the first element</li> <li><a href=../../../features/iterators/ >Iterators</a> - the article on iterators</li> <li><a href=../../basic_json_view/end/ ><code>basic_json_view::end</code></a> - the same iteration on a zero-copy view</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 1.0.0.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../empty/ class="md-footer__link md-footer__link--prev" aria-label="Previous: empty"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> empty </div> </div> </a> <a href=../end_pos/ class="md-footer__link md-footer__link--next" aria-label="Next: end_pos"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> end_pos </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1Line truncated
|
||||
@@ -7,6 +7,8 @@ const_iterator end() const noexcept;
|
||||
|
||||
Returns an iterator to one past the last element.
|
||||
|
||||
`end()` points to the position after the last element and `begin()` to the first element; the dashed cell is the past-the-last position, which must not be dereferenced.
|
||||
|
||||
## Return value
|
||||
|
||||
iterator one past the last element
|
||||
@@ -29,7 +31,7 @@ The following code shows an example for `end()`.
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -55,10 +57,11 @@ Output:
|
||||
|
||||
## See also
|
||||
|
||||
- [begin](https://json.nlohmann.me/api/basic_json/begin/index.md) returns an iterator to the first element
|
||||
- [cend](https://json.nlohmann.me/api/basic_json/cend/index.md) returns a const iterator to one past the last element
|
||||
- [rend](https://json.nlohmann.me/api/basic_json/rend/index.md) returns a reverse iterator to one before the first element
|
||||
- [`begin`](https://json.nlohmann.me/api/basic_json/begin/index.md) - returns an iterator to the first element
|
||||
- [`cend`](https://json.nlohmann.me/api/basic_json/cend/index.md) - returns a const iterator to one past the last element
|
||||
- [`rend`](https://json.nlohmann.me/api/basic_json/rend/index.md) - returns a reverse iterator to one before the first element
|
||||
- [Iterators](https://json.nlohmann.me/features/iterators/index.md) - the article on iterators
|
||||
- [`basic_json_view::end`](https://json.nlohmann.me/api/basic_json_view/end/index.md) - the same iteration on a zero-copy view
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
+106
-4
@@ -47,21 +47,123 @@ Constant.
|
||||
??? example "Example"
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/diagnostic_positions.cpp"
|
||||
#include <iostream>
|
||||
|
||||
#define JSON_DIAGNOSTIC_POSITIONS 1
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
std::string json_string = R"(
|
||||
{
|
||||
"address": {
|
||||
"street": "Fake Street",
|
||||
"housenumber": 1
|
||||
}
|
||||
}
|
||||
)";
|
||||
json j = json::parse(json_string);
|
||||
|
||||
std::cout << "Root diagnostic positions: \n";
|
||||
std::cout << "\tstart_pos: " << j.start_pos() << '\n';
|
||||
std::cout << "\tend_pos:" << j.end_pos() << "\n";
|
||||
std::cout << "Original string: \n";
|
||||
std::cout << "{\n \"address\": {\n \"street\": \"Fake Street\",\n \"housenumber\": 1\n }\n }" << "\n";
|
||||
std::cout << "Parsed string: \n";
|
||||
std::cout << json_string.substr(j.start_pos(), j.end_pos() - j.start_pos()) << "\n\n";
|
||||
|
||||
std::cout << "address diagnostic positions: \n";
|
||||
std::cout << "\tstart_pos:" << j["address"].start_pos() << '\n';
|
||||
std::cout << "\tend_pos:" << j["address"].end_pos() << "\n\n";
|
||||
std::cout << "Original string: \n";
|
||||
std::cout << "{ \"street\": \"Fake Street\",\n \"housenumber\": 1\n }" << "\n";
|
||||
std::cout << "Parsed string: \n";
|
||||
std::cout << json_string.substr(j["address"].start_pos(), j["address"].end_pos() - j["address"].start_pos()) << "\n\n";
|
||||
|
||||
std::cout << "street diagnostic positions: \n";
|
||||
std::cout << "\tstart_pos:" << j["address"]["street"].start_pos() << '\n';
|
||||
std::cout << "\tend_pos:" << j["address"]["street"].end_pos() << "\n\n";
|
||||
std::cout << "Original string: \n";
|
||||
std::cout << "\"Fake Street\"" << "\n";
|
||||
std::cout << "Parsed string: \n";
|
||||
std::cout << json_string.substr(j["address"]["street"].start_pos(), j["address"]["street"].end_pos() - j["address"]["street"].start_pos()) << "\n\n";
|
||||
|
||||
std::cout << "housenumber diagnostic positions: \n";
|
||||
std::cout << "\tstart_pos:" << j["address"]["housenumber"].start_pos() << '\n';
|
||||
std::cout << "\tend_pos:" << j["address"]["housenumber"].end_pos() << "\n\n";
|
||||
std::cout << "Original string: \n";
|
||||
std::cout << "1" << "\n";
|
||||
std::cout << "Parsed string: \n";
|
||||
std::cout << json_string.substr(j["address"]["housenumber"].start_pos(), j["address"]["housenumber"].end_pos() - j["address"]["housenumber"].start_pos()) << "\n\n";
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
--8<-- "examples/diagnostic_positions.output"
|
||||
Root diagnostic positions:
|
||||
start_pos: 5
|
||||
end_pos:109
|
||||
Original string:
|
||||
{
|
||||
"address": {
|
||||
"street": "Fake Street",
|
||||
"housenumber": 1
|
||||
}
|
||||
}
|
||||
Parsed string:
|
||||
{
|
||||
"address": {
|
||||
"street": "Fake Street",
|
||||
"housenumber": 1
|
||||
}
|
||||
}
|
||||
|
||||
address diagnostic positions:
|
||||
start_pos:26
|
||||
end_pos:103
|
||||
|
||||
Original string:
|
||||
{ "street": "Fake Street",
|
||||
"housenumber": 1
|
||||
}
|
||||
Parsed string:
|
||||
{
|
||||
"street": "Fake Street",
|
||||
"housenumber": 1
|
||||
}
|
||||
|
||||
street diagnostic positions:
|
||||
start_pos:50
|
||||
end_pos:63
|
||||
|
||||
Original string:
|
||||
"Fake Street"
|
||||
Parsed string:
|
||||
"Fake Street"
|
||||
|
||||
housenumber diagnostic positions:
|
||||
start_pos:92
|
||||
end_pos:93
|
||||
|
||||
Original string:
|
||||
1
|
||||
Parsed string:
|
||||
1
|
||||
|
||||
|
||||
```
|
||||
|
||||
The output shows the start/end positions of all the objects and fields in the JSON string.
|
||||
|
||||
## See also
|
||||
|
||||
- [start_pos](start_pos.md) to access the start position
|
||||
- [JSON_DIAGNOSTIC_POSITIONS](../macros/json_diagnostic_positions.md) for an overview of the diagnostic positions
|
||||
- [`start_pos`](start_pos.md) - to access the start position
|
||||
- [`JSON_DIAGNOSTIC_POSITIONS`](../macros/json_diagnostic_positions.md) - overview of the supported conversions
|
||||
- [Parsing and Exceptions](../../features/parsing/parse_exceptions.md) - handling parse errors and locating them in the input
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/end_pos/" rel="canonical"><link href=../end/ rel=prev><link href=../erase/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>end_pos - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../../css/custom.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsonend_pos class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> end_pos </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> <Line truncated
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/end_pos/" rel="canonical"><link href=../end/ rel=prev><link href=../erase/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>end_pos - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel=stylesheet href=../../../css/custom.css><link rel=stylesheet href=../../../css/brand.css><link rel=stylesheet href=../../../css/fig-sax.css><link rel=stylesheet href=../../../css/fig-jsonview.css><link rel=stylesheet href=../../../css/fig-exceptions.css><link rel=stylesheet href=../../../css/fig-pointer.css><link rel=stylesheet href=../../../css/fig-charts.css><link rel=stylesheet href=../../../css/fig-integration.css><link rel=stylesheet href=../../../css/fig-macros.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsonend_pos class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> end_pos </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5cLine truncated
|
||||
<span class=k>constexpr</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=kt>size_t</span><span class=w> </span><span class=nf>end_pos</span><span class=p>()</span><span class=w> </span><span class=k>const</span><span class=w> </span><span class=k>noexcept</span><span class=p>;</span>
|
||||
<span class=cp>#endif</span>
|
||||
</code></pre></div> <p>Returns the position immediately following the last character of the <abbr title="JavaScript Object Notation">JSON</abbr> string from which the value was parsed from.</p> <table> <thead> <tr> <th><abbr title="JavaScript Object Notation">JSON</abbr> type</th> <th>return value</th> </tr> </thead> <tbody> <tr> <td>object</td> <td>position after the closing <code>}</code></td> </tr> <tr> <td>array</td> <td>position after the closing <code>]</code></td> </tr> <tr> <td>string</td> <td>position after the closing <code>"</code></td> </tr> <tr> <td>number</td> <td>position after the last character</td> </tr> <tr> <td>boolean</td> <td>position after <code>e</code></td> </tr> <tr> <td>null</td> <td>position after <code>l</code></td> </tr> </tbody> </table> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">¶</a></h2> <p>the position of the character <em>following</em> the last character of the given value in the parsed <abbr title="JavaScript Object Notation">JSON</abbr> string, if the value was created by the <a href=../parse/ ><code>parse</code></a> function, or <code>std::string::npos</code> if the value was constructed otherwise</p> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">¶</a></h2> <p>No-throw guarantee: this member function never throws exceptions.</p> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">¶</a></h2> <p>Constant.</p> <h2 id=notes>Notes<a class=headerlink href=#notes title="Permanent link">¶</a></h2> <div class="admonition note"> <p class=admonition-title>Note</p> <p>The function is only available if macro <a href=../../macros/json_diagnostic_positions/ ><code>JSON_DIAGNOSTIC_POSITIONS</code></a> has been defined to <code class=highlight><span class=mi>1</span></code> before including the library header.</p> </div> <div class="admonition warning"> <p class=admonition-title>Invalidation</p> <p>The returned positions are only valid as long as the <abbr title="JavaScript Object Notation">JSON</abbr> value is not changed. The positions are <em>not</em> updated when the <abbr title="JavaScript Object Notation">JSON</abbr> value is changed.</p> </div> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example</summary> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
@@ -6,7 +6,7 @@
|
||||
<span class=cp>#define JSON_DIAGNOSTIC_POSITIONS 1</span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -101,4 +101,4 @@ Original string:
|
||||
1
|
||||
Parsed string:
|
||||
1
|
||||
</code></pre></div> <p>The output shows the start/end positions of all the objects and fields in the <abbr title="JavaScript Object Notation">JSON</abbr> string.</p> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../start_pos/ >start_pos</a> to access the start position</li> <li><a href=../../macros/json_diagnostic_positions/ >JSON_DIAGNOSTIC_POSITIONS</a> for an overview of the diagnostic positions</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 3.12.0.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="January 17, 2025 05:53:35 UTC">January 17, 2025</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4C0 465.5 14.3 480 31.9 480H416c17.6 0 32-14.5 32-32.3V64.3c0-17.8-14.4-32.3-32-32.3M135.4 416H69V202.2h66.5V416zM102.2 96a38.5 38.5 0 1 1 0 77 38.5 38.5 0 1 1 0-77m282.1 320h-66.4V312c0-24.8-.5-56.7-34.5-56.7-34.6 0-39.9 27-39.9 54.9V416h-66.4V202.2h63.7v29.2h.9c8.9-16.8 30.6-34.5 62.9-34.5 67.2 0 79.7 44.3 79.7 101.9z"/></svg> </a> <a href="https://www.xing.com/profile/Niels_Lohmann" target="_blank" rel="noopenLine truncated
|
||||
</code></pre></div> <p>The output shows the start/end positions of all the objects and fields in the <abbr title="JavaScript Object Notation">JSON</abbr> string.</p> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../start_pos/ ><code>start_pos</code></a> - to access the start position</li> <li><a href=../../macros/json_diagnostic_positions/ ><code>JSON_DIAGNOSTIC_POSITIONS</code></a> - overview of the supported conversions</li> <li><a href=../../../features/parsing/parse_exceptions/ >Parsing and Exceptions</a> - handling parse errors and locating them in the input</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 3.12.0.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../end/ class="md-footer__link md-footer__link--prev" aria-label="Previous: end"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> end </div> </div> </a> <a href=../erase/ class="md-footer__link md-footer__link--next" aria-label="Next: erase"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> erase </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.Line truncated
|
||||
@@ -49,7 +49,7 @@ Example
|
||||
#define JSON_DIAGNOSTIC_POSITIONS 1
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -155,8 +155,9 @@ The output shows the start/end positions of all the objects and fields in the JS
|
||||
|
||||
## See also
|
||||
|
||||
- [start_pos](https://json.nlohmann.me/api/basic_json/start_pos/index.md) to access the start position
|
||||
- [JSON_DIAGNOSTIC_POSITIONS](https://json.nlohmann.me/api/macros/json_diagnostic_positions/index.md) for an overview of the diagnostic positions
|
||||
- [`start_pos`](https://json.nlohmann.me/api/basic_json/start_pos/index.md) - to access the start position
|
||||
- [`JSON_DIAGNOSTIC_POSITIONS`](https://json.nlohmann.me/api/macros/json_diagnostic_positions/index.md) - overview of the supported conversions
|
||||
- [Parsing and Exceptions](https://json.nlohmann.me/features/parsing/parse_exceptions/index.md) - handling parse errors and locating them in the input
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
+147
-15
@@ -137,13 +137,50 @@ Strong exception safety: if an exception occurs, the original value stays intact
|
||||
The example shows the effect of `erase()` for different JSON types using an iterator.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/erase__IteratorType.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create JSON values
|
||||
json j_boolean = true;
|
||||
json j_number_integer = 17;
|
||||
json j_number_float = 23.42;
|
||||
json j_object = {{"one", 1}, {"two", 2}};
|
||||
json j_array = {1, 2, 4, 8, 16};
|
||||
json j_string = "Hello, world";
|
||||
|
||||
// call erase()
|
||||
j_boolean.erase(j_boolean.begin());
|
||||
j_number_integer.erase(j_number_integer.begin());
|
||||
j_number_float.erase(j_number_float.begin());
|
||||
j_object.erase(j_object.find("two"));
|
||||
j_array.erase(j_array.begin() + 2);
|
||||
j_string.erase(j_string.begin());
|
||||
|
||||
// print values
|
||||
std::cout << j_boolean << '\n';
|
||||
std::cout << j_number_integer << '\n';
|
||||
std::cout << j_number_float << '\n';
|
||||
std::cout << j_object << '\n';
|
||||
std::cout << j_array << '\n';
|
||||
std::cout << j_string << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/erase__IteratorType.output"
|
||||
null
|
||||
null
|
||||
null
|
||||
{"one":1}
|
||||
[1,2,8,16]
|
||||
null
|
||||
|
||||
```
|
||||
|
||||
??? example "Example: (2) remove elements given an iterator range"
|
||||
@@ -151,13 +188,50 @@ Strong exception safety: if an exception occurs, the original value stays intact
|
||||
The example shows the effect of `erase()` for different JSON types using an iterator range.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/erase__IteratorType_IteratorType.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create JSON values
|
||||
json j_boolean = true;
|
||||
json j_number_integer = 17;
|
||||
json j_number_float = 23.42;
|
||||
json j_object = {{"one", 1}, {"two", 2}};
|
||||
json j_array = {1, 2, 4, 8, 16};
|
||||
json j_string = "Hello, world";
|
||||
|
||||
// call erase()
|
||||
j_boolean.erase(j_boolean.begin(), j_boolean.end());
|
||||
j_number_integer.erase(j_number_integer.begin(), j_number_integer.end());
|
||||
j_number_float.erase(j_number_float.begin(), j_number_float.end());
|
||||
j_object.erase(j_object.find("two"), j_object.end());
|
||||
j_array.erase(j_array.begin() + 1, j_array.begin() + 3);
|
||||
j_string.erase(j_string.begin(), j_string.end());
|
||||
|
||||
// print values
|
||||
std::cout << j_boolean << '\n';
|
||||
std::cout << j_number_integer << '\n';
|
||||
std::cout << j_number_float << '\n';
|
||||
std::cout << j_object << '\n';
|
||||
std::cout << j_array << '\n';
|
||||
std::cout << j_string << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/erase__IteratorType_IteratorType.output"
|
||||
null
|
||||
null
|
||||
null
|
||||
{"one":1}
|
||||
[1,8,16]
|
||||
null
|
||||
|
||||
```
|
||||
|
||||
??? example "Example: (3) remove element from a JSON object given a key"
|
||||
@@ -165,13 +239,33 @@ Strong exception safety: if an exception occurs, the original value stays intact
|
||||
The example shows the effect of `erase()` for different JSON types using an object key.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/erase__object_t_key_type.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create a JSON object
|
||||
json j_object = {{"one", 1}, {"two", 2}};
|
||||
|
||||
// call erase()
|
||||
auto count_one = j_object.erase("one");
|
||||
auto count_three = j_object.erase("three");
|
||||
|
||||
// print values
|
||||
std::cout << j_object << '\n';
|
||||
std::cout << count_one << " " << count_three << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/erase__object_t_key_type.output"
|
||||
{"two":2}
|
||||
1 0
|
||||
|
||||
```
|
||||
|
||||
??? example "Example: (4) remove element from a JSON object given a key using string_view"
|
||||
@@ -179,13 +273,35 @@ Strong exception safety: if an exception occurs, the original value stays intact
|
||||
The example shows the effect of `erase()` for different JSON types using an object key.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/erase__keytype.c++17.cpp"
|
||||
#include <iostream>
|
||||
#include <string_view>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using namespace std::string_view_literals;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create a JSON object
|
||||
json j_object = {{"one", 1}, {"two", 2}};
|
||||
|
||||
// call erase()
|
||||
auto count_one = j_object.erase("one"sv);
|
||||
auto count_three = j_object.erase("three"sv);
|
||||
|
||||
// print values
|
||||
std::cout << j_object << '\n';
|
||||
std::cout << count_one << " " << count_three << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/erase__keytype.c++17.output"
|
||||
{"two":2}
|
||||
1 0
|
||||
|
||||
```
|
||||
|
||||
??? example "Example: (5) remove element from a JSON array given an index"
|
||||
@@ -193,19 +309,36 @@ Strong exception safety: if an exception occurs, the original value stays intact
|
||||
The example shows the effect of `erase()` using an array index.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/erase__size_type.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create a JSON array
|
||||
json j_array = {0, 1, 2, 3, 4, 5};
|
||||
|
||||
// call erase()
|
||||
j_array.erase(2);
|
||||
|
||||
// print values
|
||||
std::cout << j_array << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/erase__size_type.output"
|
||||
[0,1,3,4,5]
|
||||
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [clear](clear.md) clears the contents
|
||||
- [insert](insert.md) add values to an array/object
|
||||
- [`clear`](clear.md) - clears the contents
|
||||
- [`insert`](insert.md) - add values to an array/object
|
||||
- [Modifying values](../../features/modifying_values.md) - the article on modifying values
|
||||
|
||||
## Version history
|
||||
@@ -213,7 +346,6 @@ Strong exception safety: if an exception occurs, the original value stays intact
|
||||
1. Added in version 1.0.0. Added support for binary types in version 3.8.0.
|
||||
2. Added in version 1.0.0. Added support for binary types in version 3.8.0.
|
||||
3. Added in version 1.0.0.
|
||||
4. Added in version 3.11.0. Fixed in version 3.13.0 to consistently accept `std::string_view`-convertible keys, as
|
||||
already supported by [`operator[]`](operator[].md), [`at`](at.md), [`value`](value.md), and other lookup
|
||||
functions.
|
||||
4. Added in version 3.11.0. Support for keys convertible to `std::string_view` added in version 3.13.0, consistently
|
||||
across the lookup functions.
|
||||
5. Added in version 1.0.0.
|
||||
@@ -1,4 +1,4 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/erase/" rel="canonical"><link href=../end_pos/ rel=prev><link href=../error_handler_t/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>erase - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../../css/custom.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsonerase class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> erase </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </laLine truncated
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/erase/" rel="canonical"><link href=../end_pos/ rel=prev><link href=../error_handler_t/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>erase - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel=stylesheet href=../../../css/custom.css><link rel=stylesheet href=../../../css/brand.css><link rel=stylesheet href=../../../css/fig-sax.css><link rel=stylesheet href=../../../css/fig-jsonview.css><link rel=stylesheet href=../../../css/fig-exceptions.css><link rel=stylesheet href=../../../css/fig-pointer.css><link rel=stylesheet href=../../../css/fig-charts.css><link rel=stylesheet href=../../../css/fig-integration.css><link rel=stylesheet href=../../../css/fig-macros.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsonerase class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> erase </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 1Line truncated
|
||||
<span class=n>iterator</span><span class=w> </span><span class=nf>erase</span><span class=p>(</span><span class=n>iterator</span><span class=w> </span><span class=n>pos</span><span class=p>);</span>
|
||||
<span class=n>const_iterator</span><span class=w> </span><span class=nf>erase</span><span class=p>(</span><span class=n>const_iterator</span><span class=w> </span><span class=n>pos</span><span class=p>);</span>
|
||||
|
||||
@@ -18,7 +18,7 @@
|
||||
</code></pre></div> <ol> <li> <p>Removes an element from a <abbr title="JavaScript Object Notation">JSON</abbr> value specified by iterator <code>pos</code>. The iterator <code>pos</code> must be valid and dereferenceable. Thus, the <code>end()</code> iterator (which is valid, but is not dereferenceable) cannot be used as a value for <code>pos</code>.</p> <p>If called on a primitive type other than <code class=highlight><span class=kc>null</span></code>, the resulting <abbr title="JavaScript Object Notation">JSON</abbr> value will be <code class=highlight><span class=kc>null</span></code>.</p> </li> <li> <p>Remove an element range specified by <code>[first; last)</code> from a <abbr title="JavaScript Object Notation">JSON</abbr> value. The iterator <code>first</code> does not need to be dereferenceable if <code>first == last</code>: erasing an empty range is a no-op.</p> <p>If called on a primitive type other than <code class=highlight><span class=kc>null</span></code>, the resulting <abbr title="JavaScript Object Notation">JSON</abbr> value will be <code class=highlight><span class=kc>null</span></code>.</p> </li> <li> <p>Removes an element from a <abbr title="JavaScript Object Notation">JSON</abbr> object by key.</p> </li> <li> <p>See 3. This overload is only available if <code>KeyType</code> is comparable with <code class=highlight><span class=k>typename</span><span class=w> </span><span class=nc>object_t</span><span class=o>::</span><span class=n>key_type</span></code> and <code class=highlight><span class=k>typename</span><span class=w> </span><span class=nc>object_comparator_t</span><span class=o>::</span><span class=n>is_transparent</span></code> denotes a type.</p> </li> <li> <p>Removes an element from a <abbr title="JavaScript Object Notation">JSON</abbr> array by index.</p> </li> </ol> <h2 id=template-parameters>Template parameters<a class=headerlink href=#template-parameters title="Permanent link">¶</a></h2> <dl> <dt><code>KeyType</code></dt> <dd>A type for an object key other than <a href=../../json_pointer/ ><code>json_pointer</code></a> that is comparable with <a href=../string_t/ ><code>string_t</code></a> using <a href=../object_comparator_t/ ><code>object_comparator_t</code></a>. This can also be a string view (C++17).</dd> </dl> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">¶</a></h2> <dl> <dt><code>pos</code> (in)</dt> <dd>iterator to the element to remove</dd> <dt><code>first</code> (in)</dt> <dd>iterator to the beginning of the range to remove</dd> <dt><code>last</code> (in)</dt> <dd>iterator past the end of the range to remove</dd> <dt><code>key</code> (in)</dt> <dd>object key of the elements to remove</dd> <dt><code>idx</code> (in)</dt> <dd>array index of the element to remove</dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">¶</a></h2> <ol> <li>Iterator following the last removed element. If the iterator <code>pos</code> refers to the last element, the <code>end()</code> iterator is returned.</li> <li>Iterator following the last removed element. If the iterator <code>last</code> refers to the last element, the <code>end()</code> iterator is returned.</li> <li>Number of elements removed. If <code>ObjectType</code> is the default <code>std::map</code> type, the return value will always be <code>0</code> (<code>key</code> was not found) or <code>1</code> (<code>key</code> was found).</li> <li>See 3.</li> <li>(none)</li> </ol> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">¶</a></h2> <p>Strong exception safety: if an exception occurs, the original value stays intact.</p> <h2 id=exceptions>Exceptions<a class=headerlink href=#exceptions title="Permanent link">¶</a></h2> <ol> <li>The function can throw the following exceptions:<ul> <li>Throws <a href=../../../home/exceptions/#jsonexceptiontype_error307><code>type_error.307</code></a> if called on a <code>null</code> value; example: <code>"cannot use erase() with null"</code></li> <li>Throws <a href=../../../home/exceptions/#jsonexceptioninvalid_iterator202><code>invalid_iterator.202</code></a> if called on an iterator which does not belong to the current <abbr title="JavaScript Object Notation">JSON</abbr> value; example: <code>"iterator does not fit current value"</code></li> <li>Throws <a href=../../../home/exceptions/#jsonexceptioninvalid_iterator205><code>invalid_iterator.205</code></a> if called on a primitive type with invalid iterator (i.e., any iterator which is not <code>begin()</code>); example: <code>"iterator out of range"</code></li> </ul> </li> <li>The function can throw the following exceptions:<ul> <li>Throws <a href=../../../home/exceptions/#jsonexceptiontype_error307><code>type_error.307</code></a> if called on a <code>null</code> value; example: <code>"cannot use erase() with null"</code></li> <li>Throws <a href=../../../home/exceptions/#jsoneLine truncated
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -55,7 +55,7 @@
|
||||
</code></pre></div> </details> <details class=example> <summary>Example: (2) remove elements given an iterator range</summary> <p>The example shows the effect of <code>erase()</code> for different <abbr title="JavaScript Object Notation">JSON</abbr> types using an iterator range.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -92,7 +92,7 @@
|
||||
</code></pre></div> </details> <details class=example> <summary>Example: (3) remove element from a <abbr title="JavaScript Object Notation">JSON</abbr> object given a key</summary> <p>The example shows the effect of <code>erase()</code> for different <abbr title="JavaScript Object Notation">JSON</abbr> types using an object key.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -114,7 +114,7 @@
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=k>namespace</span><span class=w> </span><span class=nn>std</span><span class=o>::</span><span class=nn>string_view_literals</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -134,7 +134,7 @@
|
||||
</code></pre></div> </details> <details class=example> <summary>Example: (5) remove element from a <abbr title="JavaScript Object Notation">JSON</abbr> array given an index</summary> <p>The example shows the effect of <code>erase()</code> using an array index.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -148,4 +148,4 @@
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>j_array</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code><span class=p>[</span><span class=mi>0</span><span class=p>,</span><span class=mi>1</span><span class=p>,</span><span class=mi>3</span><span class=p>,</span><span class=mi>4</span><span class=p>,</span><span class=mi>5</span><span class=p>]</span>
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../clear/ >clear</a> clears the contents</li> <li><a href=../insert/ >insert</a> add values to an array/object</li> <li><a href=../../../features/modifying_values/ >Modifying values</a> - the article on modifying values</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ol> <li>Added in version 1.0.0. Added support for binary types in version 3.8.0.</li> <li>Added in version 1.0.0. Added support for binary types in version 3.8.0.</li> <li>Added in version 1.0.0.</li> <li>Added in version 3.11.0. Fixed in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span> to consistently accept <code>std::string_view</code>-convertible keys, as already supported by <a href=../operator%5B%5D/ ><code>operator[]</code></a>, <a href=../at/ ><code>at</code></a>, <a href=../value/ ><code>value</code></a>, and other lookup functions.</li> <li>Added in version 1.0.0.</li> </ol> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 4, 2026 09:46:32 UTC">October 4, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: Line truncated
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../clear/ ><code>clear</code></a> - clears the contents</li> <li><a href=../insert/ ><code>insert</code></a> - add values to an array/object</li> <li><a href=../../../features/modifying_values/ >Modifying values</a> - the article on modifying values</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ol> <li>Added in version 1.0.0. Added support for binary types in version 3.8.0.</li> <li>Added in version 1.0.0. Added support for binary types in version 3.8.0.</li> <li>Added in version 1.0.0.</li> <li>Added in version 3.11.0. Support for keys convertible to <code>std::string_view</code> added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>, consistently across the lookup functions.</li> <li>Added in version 1.0.0.</li> </ol> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../end_pos/ class="md-footer__link md-footer__link--prev" aria-label="Previous: end_pos"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> end_pos </div> </div> </a> <a href=../error_handler_t/ class="md-footer__link md-footer__link--next" aria-label="Next: error_handler_t"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> error_handler_t </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.Line truncated
|
||||
@@ -113,7 +113,7 @@ The example shows the effect of `erase()` for different JSON types using an iter
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -162,7 +162,7 @@ The example shows the effect of `erase()` for different JSON types using an iter
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -211,7 +211,7 @@ The example shows the effect of `erase()` for different JSON types using an obje
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -245,7 +245,7 @@ The example shows the effect of `erase()` for different JSON types using an obje
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using namespace std::string_view_literals;
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -277,7 +277,7 @@ The example shows the effect of `erase()` using an array index.
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -300,8 +300,8 @@ Output:
|
||||
|
||||
## See also
|
||||
|
||||
- [clear](https://json.nlohmann.me/api/basic_json/clear/index.md) clears the contents
|
||||
- [insert](https://json.nlohmann.me/api/basic_json/insert/index.md) add values to an array/object
|
||||
- [`clear`](https://json.nlohmann.me/api/basic_json/clear/index.md) - clears the contents
|
||||
- [`insert`](https://json.nlohmann.me/api/basic_json/insert/index.md) - add values to an array/object
|
||||
- [Modifying values](https://json.nlohmann.me/features/modifying_values/index.md) - the article on modifying values
|
||||
|
||||
## Version history
|
||||
@@ -309,5 +309,5 @@ Output:
|
||||
1. Added in version 1.0.0. Added support for binary types in version 3.8.0.
|
||||
1. Added in version 1.0.0. Added support for binary types in version 3.8.0.
|
||||
1. Added in version 1.0.0.
|
||||
1. Added in version 3.11.0. Fixed in version 3.13.0 unreleased to consistently accept `std::string_view`-convertible keys, as already supported by [`operator[]`](https://json.nlohmann.me/api/basic_json/operator%5B%5D/index.md), [`at`](https://json.nlohmann.me/api/basic_json/at/index.md), [`value`](https://json.nlohmann.me/api/basic_json/value/index.md), and other lookup functions.
|
||||
1. Added in version 3.11.0. Support for keys convertible to `std::string_view` added in version 3.13.0 unreleased, consistently across the lookup functions.
|
||||
1. Added in version 1.0.0.
|
||||
@@ -37,8 +37,8 @@ ignore
|
||||
: ignore invalid UTF-8 sequences; all valid bytes are copied to the output unchanged, and invalid bytes are dropped
|
||||
|
||||
keep
|
||||
: keep invalid UTF-8 sequences unchanged; only meaningful for the binary formats mentioned above, since [`dump`]
|
||||
(dump.md) itself must produce text, and `keep` there writes the ill-formed bytes to the output as is, so the
|
||||
: keep invalid UTF-8 sequences unchanged; only meaningful for the binary formats mentioned above, since
|
||||
[`dump`](dump.md) itself must produce text, and `keep` there writes the ill-formed bytes to the output as is, so the
|
||||
result is then not valid UTF-8 (but still equals the input bytes exactly, including around any well-formed
|
||||
characters, which are still escaped as usual)
|
||||
|
||||
@@ -50,18 +50,47 @@ keep
|
||||
[`dump`](dump.md) when reading serializing an invalid UTF-8 sequence.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/error_handler_t.cpp"
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create JSON value with invalid UTF-8 byte sequence
|
||||
json j_invalid = "ä\xA9ü";
|
||||
try
|
||||
{
|
||||
std::cout << j_invalid.dump() << '\n';
|
||||
}
|
||||
catch (const json::type_error& e)
|
||||
{
|
||||
std::cout << e.what() << '\n';
|
||||
}
|
||||
|
||||
std::cout << "string with replaced invalid characters: "
|
||||
<< j_invalid.dump(-1, ' ', false, json::error_handler_t::replace)
|
||||
<< "\nstring with ignored invalid characters: "
|
||||
<< j_invalid.dump(-1, ' ', false, json::error_handler_t::ignore)
|
||||
<< "\nstring with the invalid byte kept as is (" << j_invalid.dump(-1, ' ', false, json::error_handler_t::keep).size()
|
||||
<< " bytes, not valid UTF-8 itself)\n";
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
--8<-- "examples/error_handler_t.output"
|
||||
[json.exception.type_error.316] invalid UTF-8 byte at index 2: 0xA9
|
||||
string with replaced invalid characters: "ä�ü"
|
||||
string with ignored invalid characters: "äü"
|
||||
string with the invalid byte kept as is (7 bytes, not valid UTF-8 itself)
|
||||
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [dump](dump.md) serializes a JSON value, with an `error_handler_t` parameter to configure invalid UTF-8 handling
|
||||
- [`dump`](dump.md) - serializes a JSON value, with an `error_handler_t` parameter to configure invalid UTF-8 handling
|
||||
- [Handling invalid UTF-8](../../features/serialization.md#handling-invalid-utf-8) - the article on handling invalid UTF-8
|
||||
|
||||
## Version history
|
||||
|
||||
Loaded 100 of 1730 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user