mirror of
https://github.com/nlohmann/json.git
synced 2026-10-29 09:05:42 +00:00
deploy: 7c9208bfb3
This commit is contained in:
nlohmann committed
1 parent
9a231845c2
commit
279d757031
758 files changed
+56489
-503
No files matched your search
@@ -138,4 +138,4 @@
|
||||
</code></pre></div> </details> <div class="admonition tip"> <p class=admonition-title>Avoiding invalid <abbr title="Unicode Transformation Format">UTF</abbr>-8</p> <p>The best fix is to ensure that all strings are <abbr title="Unicode Transformation Format">UTF</abbr>-8 encoded before storing them. See the <a href=../../home/faq/#parse-errors-reading-non-ascii-characters><abbr title="Frequently Asked Questions">FAQ</abbr> on non-<abbr title="American Standard Code for Information Interchange">ASCII</abbr> characters</a> for how to convert wide or Latin-1 strings.</p> </div> <h2 id=numbers-nan-and-binary-values>Numbers, <abbr title="Not a Number">NaN</abbr>, and binary values<a class=headerlink href=#numbers-nan-and-binary-values title="Permanent link">¶</a></h2> <ul> <li><strong>Numbers</strong> are serialized with enough precision to round-trip; see <a href=../types/number_handling/#number-serialization>number serialization</a>.</li> <li><strong><abbr title="Not a Number">NaN</abbr> and infinity</strong> cannot be represented in <abbr title="JavaScript Object Notation">JSON</abbr> and are serialized as <code class=highlight><span class=kc>null</span></code>; see <a href=../types/number_handling/#nan-handling><abbr title="Not a Number">NaN</abbr> handling</a>. The <a href=../binary_formats/ >binary formats</a> can preserve them.</li> <li><strong>Binary values</strong> have no <abbr title="JavaScript Object Notation">JSON</abbr> representation and are serialized as a helper object for debugging only; see <a href=../binary_values/#serialization>binary values</a>.</li> </ul> <h2 id=using-stdformat-stdprint-and-fmt>Using <code>std::format</code>, <code>std::print</code>, and <code>fmt</code><a class=headerlink href=#using-stdformat-stdprint-and-fmt title="Permanent link">¶</a></h2> <p>Since version 3.12.0, <abbr title="JavaScript Object Notation">JSON</abbr> values can be formatted directly with C++20's <a href="https://en.cppreference.com/w/cpp/utility/format/format"><code>std::format</code></a> whenever the standard library provides the <code><format></code> header (controlled by <a href=../../api/macros/json_has_std_format/ ><code>JSON_HAS_STD_FORMAT</code></a>). This is enabled by the <a href=../../api/basic_json/std_formatter/ ><code>std::formatter<basic_json></code></a> specialization, which also makes <abbr title="JavaScript Object Notation">JSON</abbr> values work with <code>std::format_to</code> and with C++23's <code>std::print</code>/<code>std::println</code>:</p> <div class=highlight><pre><span></span><code><span class=n>std</span><span class=o>::</span><span class=n>print</span><span class=p>(</span><span class=s>"{}"</span><span class=p>,</span><span class=w> </span><span class=n>j</span><span class=p>);</span><span class=w> </span><span class=c1>// compact, like j.dump()</span>
|
||||
<span class=n>std</span><span class=o>::</span><span class=n>print</span><span class=p>(</span><span class=s>"{:2}"</span><span class=p>,</span><span class=w> </span><span class=n>j</span><span class=p>);</span><span class=w> </span><span class=c1>// pretty-printed with indent 2 (like j.dump(2))</span>
|
||||
<span class=n>std</span><span class=o>::</span><span class=n>println</span><span class=p>(</span><span class=s>"{:#}"</span><span class=p>,</span><span class=w> </span><span class=n>j</span><span class=p>);</span><span class=w> </span><span class=c1>// pretty-printed with the default indent</span>
|
||||
</code></pre></div> <p>The format spec mirrors the <code>dump</code> parameters: <code class=highlight><span class=s>"{:#}"</span></code> pretty-prints, a width such as <code class=highlight><span class=s>"{:2}"</span></code> sets the indent, and a fill-and-align prefix such as <code class=highlight><span class=s>"{:.>#}"</span></code> sets the indent character.</p> <p>For the <a href="https://github.com/fmtlib/fmt">{fmt}</a> library, the library ships a <a href=../../api/basic_json/format_as/ ><code>format_as</code></a> helper. Note its behavior depends on the <code>fmt</code> version; see the <a href=../../home/faq/#using-json-values-with-stdformat-or-fmt><abbr title="Frequently Asked Questions">FAQ</abbr> entry</a> for the details and a recipe for a full <code>fmt::formatter</code> specialization.</p> <h2 id=serializing-to-other-formats>Serializing to other formats<a class=headerlink href=#serializing-to-other-formats title="Permanent link">¶</a></h2> <p>Besides <abbr title="JavaScript Object Notation">JSON</abbr> text, a value can also be serialized to the more compact <a href=../binary_formats/ >binary formats</a> (<abbr title="Binary JData">BJData</abbr>, <abbr title="Binary JSON">BSON</abbr>, <abbr title="Concise Binary Object Representation">CBOR</abbr>, MessagePack, <abbr title="Universal Binary JSON">UBJSON</abbr>).</p> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../../api/basic_json/dump/ ><code>dump</code></a> - serialize to a <abbr title="JavaScript Object Notation">JSON</abbr>-formatted string</li> <li><a href=../../api/operator_ltlt/ ><code>operator<<</code></a> - serialize to a stream</li> <li><a href=../../api/basic_json/to_string/ ><code>to_string</code></a> - user-defined-conversion helper</li> <li><a href=../../api/basic_json/std_formatter/ ><code>std::formatter<basic_json></code></a> - use <abbr title="JavaScript Object Notation">JSON</abbr> values with <code>std::format</code> and <code>std::print</code></li> <li><a href=../../api/basic_json/format_as/ ><code>format_as</code></a> - use <abbr title="JavaScript Object Notation">JSON</abbr> values with the {fmt} library</li> <li><a href=../parsing/ >Parsing</a> - the reverse operation</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 2Line truncated
|
||||
</code></pre></div> <p>The format spec mirrors the <code>dump</code> parameters: <code class=highlight><span class=s>"{:#}"</span></code> pretty-prints, a width such as <code class=highlight><span class=s>"{:2}"</span></code> sets the indent, and a fill-and-align prefix such as <code class=highlight><span class=s>"{:.>#}"</span></code> sets the indent character.</p> <p>For the <a href="https://github.com/fmtlib/fmt">{fmt}</a> library, the library ships a <a href=../../api/basic_json/format_as/ ><code>format_as</code></a> helper. Note its behavior depends on the <code>fmt</code> version; see the <a href=../../home/faq/#using-json-values-with-stdformat-or-fmt><abbr title="Frequently Asked Questions">FAQ</abbr> entry</a> for the details and a recipe for a full <code>fmt::formatter</code> specialization.</p> <h2 id=serializing-to-other-formats>Serializing to other formats<a class=headerlink href=#serializing-to-other-formats title="Permanent link">¶</a></h2> <p>Besides <abbr title="JavaScript Object Notation">JSON</abbr> text, a value can also be serialized to the more compact <a href=../binary_formats/ >binary formats</a> (<abbr title="Binary JData">BJData</abbr>, <abbr title="Binary JSON">BSON</abbr>, <abbr title="Concise Binary Object Representation">CBOR</abbr>, MessagePack, <abbr title="Universal Binary JSON">UBJSON</abbr>).</p> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../../api/basic_json/dump/ ><code>dump</code></a> - serialize to a <abbr title="JavaScript Object Notation">JSON</abbr>-formatted string</li> <li><a href=../../api/operator_ltlt/ ><code>operator<<</code></a> - serialize to a stream</li> <li><a href=../../api/basic_json/to_string/ ><code>to_string</code></a> - user-defined-conversion helper</li> <li><a href=../../api/basic_json/std_formatter/ ><code>std::formatter<basic_json></code></a> - use <abbr title="JavaScript Object Notation">JSON</abbr> values with <code>std::format</code> and <code>std::print</code></li> <li><a href=../../api/basic_json/format_as/ ><code>format_as</code></a> - use <abbr title="JavaScript Object Notation">JSON</abbr> values with the {fmt} library</li> <li><a href=../parsing/ >Parsing</a> - the reverse operation</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 8, 2026 18:18:24 UTC">July 8, 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 2Line truncated
|
||||
@@ -0,0 +1,230 @@
|
||||
# Serialization
|
||||
|
||||
Serialization is the process of turning a JSON value back into JSON text. It is the counterpart to [parsing](https://json.nlohmann.me/features/parsing/index.md). The central function is [`dump`](https://json.nlohmann.me/api/basic_json/dump/index.md), which returns the JSON text as a string.
|
||||
|
||||
```
|
||||
json j = {{"pi", 3.141}, {"happy", true}};
|
||||
|
||||
std::string s = j.dump(); // {"happy":true,"pi":3.141}
|
||||
```
|
||||
|
||||
To write a value directly to a stream (for example, a file or `std::cout`), the [`operator<<`](https://json.nlohmann.me/api/operator_ltlt/index.md) is provided:
|
||||
|
||||
```
|
||||
std::cout << j << std::endl;
|
||||
```
|
||||
|
||||
String, not raw value
|
||||
|
||||
`dump` always returns a **JSON text**. Serializing a JSON string therefore includes the surrounding quotes and escapes special characters. To obtain the *contained* string value without quotes, use [`get<std::string>()`](https://json.nlohmann.me/features/conversions/index.md) instead of `dump`. See the [converting values](https://json.nlohmann.me/features/conversions/index.md) page.
|
||||
|
||||
## Pretty-printing
|
||||
|
||||
By default, `dump` produces the most compact representation without any superfluous whitespace. Passing a non-negative `indent` argument pretty-prints the output with the given number of spaces per level:
|
||||
|
||||
Example
|
||||
|
||||
```
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = 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() << std::endl;
|
||||
}
|
||||
catch (const json::type_error& e)
|
||||
{
|
||||
std::cout << e.what() << std::endl;
|
||||
}
|
||||
|
||||
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:
|
||||
|
||||
```
|
||||
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: "äü"
|
||||
```
|
||||
|
||||
The indentation character can be changed with the second argument (e.g., a tab `'\t'`). An `indent` of `0` inserts newlines but no leading spaces, and the default of `-1` selects the compact single-line form.
|
||||
|
||||
## Non-ASCII characters
|
||||
|
||||
Strings are stored and serialized as UTF-8 (see [types](https://json.nlohmann.me/features/types/#strings)). By default, `dump` copies valid non-ASCII characters as-is. Setting the third argument `ensure_ascii` to `true` escapes all non-ASCII characters with `\uXXXX` sequences, so that the output contains only ASCII characters:
|
||||
|
||||
```
|
||||
json j = "苹果";
|
||||
j.dump(); // "苹果"
|
||||
j.dump(-1, ' ', true); // "苹果"
|
||||
```
|
||||
|
||||
## Handling invalid UTF-8
|
||||
|
||||
If a string contains invalid UTF-8 sequences (for example, because it holds data in another encoding such as Latin-1), serialization fails by default. The fourth argument of `dump` selects an [`error_handler`](https://json.nlohmann.me/api/basic_json/error_handler_t/index.md):
|
||||
|
||||
- `strict` (default) — throw a [`type_error.316`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error316) exception.
|
||||
- `replace` — replace invalid bytes with the Unicode replacement character U+FFFD (`�`).
|
||||
- `ignore` — silently drop invalid bytes.
|
||||
|
||||
Example
|
||||
|
||||
```
|
||||
#include <iostream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// create JSON value with invalid UTF-8 byte sequence
|
||||
json j_invalid = "ä\xA9ü";
|
||||
try
|
||||
{
|
||||
std::cout << j_invalid.dump() << std::endl;
|
||||
}
|
||||
catch (const json::type_error& e)
|
||||
{
|
||||
std::cout << e.what() << std::endl;
|
||||
}
|
||||
|
||||
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.exception.type_error.316] invalid UTF-8 byte at index 2: 0xA9
|
||||
string with replaced invalid characters: "ä�ü"
|
||||
string with ignored invalid characters: "äü"
|
||||
```
|
||||
|
||||
Avoiding invalid UTF-8
|
||||
|
||||
The best fix is to ensure that all strings are UTF-8 encoded before storing them. See the [FAQ on non-ASCII characters](https://json.nlohmann.me/home/faq/#parse-errors-reading-non-ascii-characters) for how to convert wide or Latin-1 strings.
|
||||
|
||||
## Numbers, NaN, and binary values
|
||||
|
||||
- **Numbers** are serialized with enough precision to round-trip; see [number serialization](https://json.nlohmann.me/features/types/number_handling/#number-serialization).
|
||||
- **NaN and infinity** cannot be represented in JSON and are serialized as `null`; see [NaN handling](https://json.nlohmann.me/features/types/number_handling/#nan-handling). The [binary formats](https://json.nlohmann.me/features/binary_formats/index.md) can preserve them.
|
||||
- **Binary values** have no JSON representation and are serialized as a helper object for debugging only; see [binary values](https://json.nlohmann.me/features/binary_values/#serialization).
|
||||
|
||||
## Using `std::format`, `std::print`, and `fmt`
|
||||
|
||||
Since version 3.12.0, JSON values can be formatted directly with C++20's [`std::format`](https://en.cppreference.com/w/cpp/utility/format/format) whenever the standard library provides the `<format>` header (controlled by [`JSON_HAS_STD_FORMAT`](https://json.nlohmann.me/api/macros/json_has_std_format/index.md)). This is enabled by the [`std::formatter<basic_json>`](https://json.nlohmann.me/api/basic_json/std_formatter/index.md) specialization, which also makes JSON values work with `std::format_to` and with C++23's `std::print`/`std::println`:
|
||||
|
||||
```
|
||||
std::print("{}", j); // compact, like j.dump()
|
||||
std::print("{:2}", j); // pretty-printed with indent 2 (like j.dump(2))
|
||||
std::println("{:#}", j); // pretty-printed with the default indent
|
||||
```
|
||||
|
||||
The format spec mirrors the `dump` parameters: `"{:#}"` pretty-prints, a width such as `"{:2}"` sets the indent, and a fill-and-align prefix such as `"{:.>#}"` sets the indent character.
|
||||
|
||||
For the [{fmt}](https://github.com/fmtlib/fmt) library, the library ships a [`format_as`](https://json.nlohmann.me/api/basic_json/format_as/index.md) helper. Note its behavior depends on the `fmt` version; see the [FAQ entry](https://json.nlohmann.me/home/faq/#using-json-values-with-stdformat-or-fmt) for the details and a recipe for a full `fmt::formatter` specialization.
|
||||
|
||||
## Serializing to other formats
|
||||
|
||||
Besides JSON text, a value can also be serialized to the more compact [binary formats](https://json.nlohmann.me/features/binary_formats/index.md) (BJData, BSON, CBOR, MessagePack, UBJSON).
|
||||
|
||||
## See also
|
||||
|
||||
- [`dump`](https://json.nlohmann.me/api/basic_json/dump/index.md) - serialize to a JSON-formatted string
|
||||
- [`operator<<`](https://json.nlohmann.me/api/operator_ltlt/index.md) - serialize to a stream
|
||||
- [`to_string`](https://json.nlohmann.me/api/basic_json/to_string/index.md) - user-defined-conversion helper
|
||||
- [`std::formatter<basic_json>`](https://json.nlohmann.me/api/basic_json/std_formatter/index.md) - use JSON values with `std::format` and `std::print`
|
||||
- [`format_as`](https://json.nlohmann.me/api/basic_json/format_as/index.md) - use JSON values with the {fmt} library
|
||||
- [Parsing](https://json.nlohmann.me/features/parsing/index.md) - the reverse operation
|
||||
Reference in new issue
Block a user