mirror of
https://github.com/nlohmann/json.git
synced 2026-10-08 15:37:13 +00:00
deploy: e4e7d657ef
This commit is contained in:
nlohmann committed
1 parent
6cba066a3f
commit
f991906bcd
12 files changed
+70
-16
No files matched your search
@@ -8,4 +8,4 @@ make<span class=w> </span>serve<span class=w> </span>-C<span class=w> </span>doc
|
||||
make<span class=w> </span>check_mermaid<span class=w> </span>-C<span class=w> </span>docs/mkdocs<span class=w> </span><span class=c1># checks the Mermaid diagrams (requires Node.js)</span>
|
||||
</code></pre></div> <p>A new <abbr title="Application Programming Interfaces">API</abbr> page also needs an entry in <a href="https://github.com/nlohmann/json/blob/develop/docs/docset/docSet.sql"><code>docs/docset/docSet.sql</code></a>, the search index of the docset; <code>make build</code> reports missing entries.</p> <h3 id=amalgamate-the-source-code>Amalgamate the source code<a class=headerlink href=#amalgamate-the-source-code title="Permanent link">¶</a></h3> <p>The single-header files <a href="https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json.hpp"><code>single_include/nlohmann/json.hpp</code></a> and <a href="https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json_fwd.hpp"><code>single_include/nlohmann/json_fwd.hpp</code></a> are <strong>generated</strong> from the source files in the <a href="https://github.com/nlohmann/json/tree/develop/include/nlohmann"><code>include/nlohmann</code> directory</a>. <strong>Do not</strong> edit the files directly; instead, modify the include/nlohmann sources and regenerate the files by executing:</p> <div class=highlight><pre><span></span><code>make<span class=w> </span>amalgamate
|
||||
</code></pre></div> <p>Running <code>make amalgamate</code> will also apply automatic formatting to the source files using <a href="https://astyle.sourceforge.net/"><code>Artistic Style</code></a>. This formatting may modify your source files in-place. Be certain to review and commit any changes to avoid unintended formatting diffs in commits.</p> <p>If you add, rename, or remove a header in <code>include/nlohmann</code>, also regenerate the header list in <a href="https://github.com/nlohmann/json/blob/develop/BUILD.bazel"><code>BUILD.bazel</code></a> (requires CMake) by executing:</p> <div class=highlight><pre><span></span><code>make<span class=w> </span>BUILD.bazel
|
||||
</code></pre></div> <p>The amalgamation check in <abbr title="Continuous Integration">CI</abbr> fails if any of these generated files is out of date.</p> <h2 id=recommended-documentation>Recommended documentation<a class=headerlink href=#recommended-documentation title="Permanent link">¶</a></h2> <ul> <li>The library’s <a href="https://github.com/nlohmann/json/blob/master/README.md">README file</a> is an excellent starting point to understand its functionality.</li> <li>The <a href="https://json.nlohmann.me">documentation page</a> is the reference documentation of the library.</li> <li><a href="https://datatracker.ietf.org/doc/html/rfc8259"><abbr title="Request for Comments">RFC</abbr> 8259</a> is the reference for the JavaScript Object Notation (<abbr title="JavaScript Object Notation">JSON</abbr>) Data Interchange Format.</li> </ul> <h2 id=please-dont>Please don't...<a class=headerlink href=#please-dont title="Permanent link">¶</a></h2> <p>Certain contributions are not helpful.</p> <h3 id=break-the-public-api>Break the public <abbr title="Application Programming Interfaces">API</abbr><a class=headerlink href=#break-the-public-api title="Permanent link">¶</a></h3> <p>We take pride in the library being used by <a href="https://json.nlohmann.me/home/customers/">numerous customers across various industries</a>. They all rely on the guarantees provided by <a href="https://semver.org">semantic versioning</a>. Please do not change the library such that the public <abbr title="Application Programming Interfaces">API</abbr> of the 3.x.y version is broken. This includes:</p> <ul> <li>Changing function signatures (altering parameter types, return types, number of parameters) or changing the const-ness of member functions.</li> <li>Removing functions.</li> <li>Renaming functions or classes.</li> <li>Changing exception handling.</li> <li>Changing exception ids.</li> <li>Changing access specifiers.</li> <li>Changing default arguments.</li> </ul> <p>Although these guidelines may seem restrictive, they are essential for maintaining the library’s utility.</p> <p>Breaking changes may be introduced when they are guarded with a feature macro such as <a href="https://json.nlohmann.me/api/macros/json_use_implicit_conversions/"><code>JSON_USE_IMPLICIT_CONVERSIONS</code></a> which allows selectively changing the behavior of the library. In next steps, the current behavior can then be deprecated. Using feature macros then allows users to test their code against the library in the next major release.</p> <h3 id=break-c11-language-conformance>Break C++11 language conformance<a class=headerlink href=#break-c11-language-conformance title="Permanent link">¶</a></h3> <p>This library is designed to work with C++11 and later. This means that any <a href="https://github.com/nlohmann/json/blob/master/README.md#supported-compilers">supported C++11 compiler</a> should compile the library without problems. Some compilers like <abbr title="GNU Compiler Collection">GCC</abbr> 4.7 (and earlier), Clang 3.3 (and earlier), or Microsoft Visual Studio 13.0 and earlier are known not to work due to missing or incomplete C++11 support.</p> <p>Please do not add features that do not work with the mentioned supported compilers. Please guard features from C++14 and later against the respective <a href="https://json.nlohmann.me/api/macros/json_has_cpp_11/"><code>JSON_HAS_CPP_14</code></a> macros.</p> <h3 id=break-json-conformance>Break <abbr title="JavaScript Object Notation">JSON</abbr> conformance<a class=headerlink href=#break-json-conformance title="Permanent link">¶</a></h3> <p>Please refrain from proposing changes that would <strong>break <a href="https://datatracker.ietf.org/doc/html/rfc8259"><abbr title="JavaScript Object Notation">JSON</abbr></a> conformance</strong>. If you propose a conformant extension of <abbr title="JavaScript Object Notation">JSON</abbr> to be supported by the library, please motivate this extension.</p> <h2 id=wanted>Wanted<a class=headerlink href=#wanted title="Permanent link">¶</a></h2> <p>The following areas really need contribution and are always welcomed:</p> <ul> <li>Extending the <strong>continuous integration</strong> toward more exotic compilers such as Android <abbr title="Native Development Kit">NDK</abbr>, Intel's Compiler, or the bleeding-edge versions Clang.</li> <li>Improving the efficiency of the <strong><abbr title="JavaScript Object Notation">JSON</abbr> parser</strong>. The current parser is implemented as a naive recursive descent parser with hand-coded string handling. More sophisticated approaches like LALR parsers would be really appreciated. That said, parser generators like Bison or ANTLR do not play nice with single-header files -- I really would like to keep the parser inside the <code>json.hpp</code> header, and I am not aware of approaches similar to <a href="http://re2c.org"><code>re2c</code></a> for parsing.</li> <li>Extending and updating existing <strong>bencLine truncated
|
||||
</code></pre></div> <p>The amalgamation check in <abbr title="Continuous Integration">CI</abbr> fails if any of these generated files is out of date.</p> <h2 id=recommended-documentation>Recommended documentation<a class=headerlink href=#recommended-documentation title="Permanent link">¶</a></h2> <ul> <li>The library’s <a href="https://github.com/nlohmann/json/blob/master/README.md">README file</a> is an excellent starting point to understand its functionality.</li> <li>The <a href="https://json.nlohmann.me">documentation page</a> is the reference documentation of the library.</li> <li><a href="https://datatracker.ietf.org/doc/html/rfc8259"><abbr title="Request for Comments">RFC</abbr> 8259</a> is the reference for the JavaScript Object Notation (<abbr title="JavaScript Object Notation">JSON</abbr>) Data Interchange Format.</li> </ul> <h2 id=please-dont>Please don't...<a class=headerlink href=#please-dont title="Permanent link">¶</a></h2> <p>Certain contributions are not helpful.</p> <h3 id=break-the-public-api>Break the public <abbr title="Application Programming Interfaces">API</abbr><a class=headerlink href=#break-the-public-api title="Permanent link">¶</a></h3> <p>We take pride in the library being used by <a href="https://json.nlohmann.me/home/customers/">numerous customers across various industries</a>. They all rely on the guarantees provided by <a href="https://semver.org">semantic versioning</a>. Please do not change the library such that the public <abbr title="Application Programming Interfaces">API</abbr> of the 3.x.y version is broken. This includes:</p> <ul> <li>Changing function signatures (altering parameter types, return types, number of parameters) or changing the const-ness of member functions.</li> <li>Removing functions.</li> <li>Renaming functions or classes.</li> <li>Changing exception handling.</li> <li>Changing exception ids.</li> <li>Changing access specifiers.</li> <li>Changing default arguments.</li> </ul> <p>What is and is not covered by this guarantee is described in the <a href="https://json.nlohmann.me/community/roadmap/#api-stability">roadmap</a>.</p> <p>Although these guidelines may seem restrictive, they are essential for maintaining the library’s utility.</p> <p>Breaking changes may be introduced when they are guarded with a feature macro such as <a href="https://json.nlohmann.me/api/macros/json_use_implicit_conversions/"><code>JSON_USE_IMPLICIT_CONVERSIONS</code></a> which allows selectively changing the behavior of the library. In next steps, the current behavior can then be deprecated. Using feature macros then allows users to test their code against the library in the next major release.</p> <h3 id=break-c11-language-conformance>Break C++11 language conformance<a class=headerlink href=#break-c11-language-conformance title="Permanent link">¶</a></h3> <p>This library is designed to work with C++11 and later. This means that any <a href="https://github.com/nlohmann/json/blob/master/README.md#supported-compilers">supported C++11 compiler</a> should compile the library without problems. Some compilers like <abbr title="GNU Compiler Collection">GCC</abbr> 4.7 (and earlier), Clang 3.3 (and earlier), or Microsoft Visual Studio 13.0 and earlier are known not to work due to missing or incomplete C++11 support.</p> <p>Please do not add features that do not work with the mentioned supported compilers. Please guard features from C++14 and later against the respective <a href="https://json.nlohmann.me/api/macros/json_has_cpp_11/"><code>JSON_HAS_CPP_14</code></a> macros.</p> <h3 id=break-json-conformance>Break <abbr title="JavaScript Object Notation">JSON</abbr> conformance<a class=headerlink href=#break-json-conformance title="Permanent link">¶</a></h3> <p>Please refrain from proposing changes that would <strong>break <a href="https://datatracker.ietf.org/doc/html/rfc8259"><abbr title="JavaScript Object Notation">JSON</abbr></a> conformance</strong>. If you propose a conformant extension of <abbr title="JavaScript Object Notation">JSON</abbr> to be supported by the library, please motivate this extension.</p> <h2 id=wanted>Wanted<a class=headerlink href=#wanted title="Permanent link">¶</a></h2> <p>The following areas really need contribution and are always welcomed:</p> <ul> <li>Extending the <strong>continuous integration</strong> toward more exotic compilers such as Android <abbr title="Native Development Kit">NDK</abbr>, Intel's Compiler, or the bleeding-edge versions Clang.</li> <li>Improving the efficiency of the <strong><abbr title="JavaScript Object Notation">JSON</abbr> parser</strong>. The current parser is implemented as a naive recursive descent parser with hand-coded string handling. More sophisticated approaches like LALR parsers would be really appreciated. That said, parser generators like Bison or ANTLR do not play nice with single-header files -- I really would like to keep the parser inside the <code>json.hpp</code> header, and ILine truncated
|
||||
@@ -152,6 +152,8 @@ We take pride in the library being used by [numerous customers across various in
|
||||
- Changing access specifiers.
|
||||
- Changing default arguments.
|
||||
|
||||
What is and is not covered by this guarantee is described in the [roadmap](https://json.nlohmann.me/community/roadmap/#api-stability).
|
||||
|
||||
Although these guidelines may seem restrictive, they are essential for maintaining the library’s utility.
|
||||
|
||||
Breaking changes may be introduced when they are guarded with a feature macro such as [`JSON_USE_IMPLICIT_CONVERSIONS`](https://json.nlohmann.me/api/macros/json_use_implicit_conversions/) which allows selectively changing the behavior of the library. In next steps, the current behavior can then be deprecated. Using feature macros then allows users to test their code against the library in the next major release.
|
||||
|
||||
+27
-3
@@ -25,9 +25,7 @@ work items are tracked in the [GitHub milestones](https://github.com/nlohmann/js
|
||||
|
||||
## What the project will not do
|
||||
|
||||
- **Break the public API of version 3.x.** See the
|
||||
[contribution guidelines](https://github.com/nlohmann/json/blob/develop/.github/CONTRIBUTING.md#break-the-public-api)
|
||||
for what counts as a breaking change.
|
||||
- **Break the public API of version 3.x.** See [API stability](#api-stability) for what this covers.
|
||||
- **Require a newer C++ standard than C++11.**
|
||||
- **Break JSON conformance** or enable non-standard extensions by default.
|
||||
- **Add dependencies** or require a build step. The library remains header-only, and the single header
|
||||
@@ -35,6 +33,32 @@ work items are tracked in the [GitHub milestones](https://github.com/nlohmann/js
|
||||
- **Trade simplicity for speed or memory efficiency.** Performance improvements are welcome, but the library is not
|
||||
meant to compete with the fastest JSON libraries, see [Design goals](../home/design_goals.md).
|
||||
|
||||
## API stability
|
||||
|
||||
Releases follow [semantic versioning](https://semver.org): a minor or patch release of version 3.x does not break code
|
||||
that uses the public API. In particular, a 3.x release does not:
|
||||
|
||||
- change the signature of a function (its parameter types, return type, number of parameters, or the const-ness of a
|
||||
member function);
|
||||
- remove or rename a function or class;
|
||||
- change which exceptions a function throws, or the [exception ids](../home/exceptions.md);
|
||||
- change access specifiers or default arguments.
|
||||
|
||||
Exceptions to these rules, for instance when fixing a bug requires changing the exception a function throws, are
|
||||
documented in the [release notes](../home/releases.md).
|
||||
|
||||
The following are **not** part of the public API and may change in any release, including patch releases:
|
||||
|
||||
- The text of exception messages returned by `what()`. Use the [exception id](../home/exceptions.md) to tell errors
|
||||
apart.
|
||||
- The ABI, including `sizeof(basic_json)` and the memory layout of its values. Recompile your code when you upgrade the
|
||||
library. The [versioned inline namespace](../features/namespace.md) turns mixing versions into a link error.
|
||||
- Everything in namespace `nlohmann::detail`, and macros and type traits that are not documented in the
|
||||
[API reference](../api/basic_json/index.md).
|
||||
|
||||
Changes that would break the public API are only added behind a macro whose default keeps the 3.x behavior, see
|
||||
[Version 4.0](#version-40).
|
||||
|
||||
## Version 4.0
|
||||
|
||||
There is no release date for version 4.0 yet. Proposals that need a major version, for instance stricter type
|
||||
|
||||
@@ -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/community/roadmap/" rel="canonical"><link href=../governance/ rel=prev><link href=../security_policy/ rel=next><link rel=icon href=../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>Roadmap - 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=#roadmap 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> Roadmap </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-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=author content="Niels Lohmann"><link href="https://json.nlohmann.me/community/roadmap/" rel="canonical"><link href=../governance/ rel=prev><link href=../security_policy/ rel=next><link rel=icon href=../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>Roadmap - 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=#roadmap 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> Roadmap </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-mdLine truncated
|
||||
<span class=cp>#define JSON_USE_GLOBAL_UDLS 0</span>
|
||||
<span class=cp>#define JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON 0</span>
|
||||
<span class=cp>#define JSON_BRACE_INIT_COPY_SEMANTICS 1</span>
|
||||
@@ -8,4 +8,4 @@
|
||||
<span class=cp>#define JSON_DISABLE_TUPLE_REFERENCE_CONVERSION 1</span>
|
||||
<span class=cp>#define JSON_DELETE_DEPRECATED_FUNCTIONS 1</span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
</code></pre></div> <p>The macros must be defined before the library header is included; setting them once in the build system is the easiest way to achieve this.</p> <h3 id=removal-of-deprecated-functions>Removal of deprecated functions<a class=headerlink href=#removal-of-deprecated-functions title="Permanent link">¶</a></h3> <p>Version 4.0 will remove all deprecated functions. Compiling with deprecation warnings enabled shows which of them your code still uses. Defining <a href=../../api/macros/json_delete_deprecated_functions/ ><code>JSON_DELETE_DEPRECATED_FUNCTIONS</code></a> to <code>1</code> turns these warnings into errors, as the deprecated functions are then deleted. The <a href=../../integration/migration_guide/#replace-deprecated-functions>migration guide</a> shows how to replace each of them.</p> <p>The <code>from_*</code> overloads taking a pointer and a length are not removed in version 4.0, but stay deleted. Without them, a call like <code>from_cbor(ptr, len)</code> would still compile: it would read <code>ptr</code> as a NUL-terminated string and convert <code>len</code> to the <code>strict</code> parameter.</p> <table> <thead> <tr> <th>Deprecated</th> <th>Since</th> <th>Migration</th> </tr> </thead> <tbody> <tr> <td><code class=highlight><span class=k>operator</span><span class=o><<</span><span class=p>(</span><span class=n>basic_json</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>istream</span><span class=o>&</span><span class=p>)</span></code></td> <td>3.0.0</td> <td><a href=../../integration/migration_guide/#parsing>Parsing</a></td> </tr> <tr> <td><code class=highlight><span class=k>operator</span><span class=o>>></span><span class=p>(</span><span class=k>const</span><span class=w> </span><span class=n>basic_json</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>ostream</span><span class=o>&</span><span class=p>)</span></code></td> <td>3.0.0</td> <td><a href=../../integration/migration_guide/#miscellaneous-functions>Miscellaneous functions</a></td> </tr> <tr> <td><code>iterator_wrapper</code></td> <td>3.1.0</td> <td><a href=../../integration/migration_guide/#miscellaneous-functions>Miscellaneous functions</a></td> </tr> <tr> <td><a href=../../api/basic_json/parse/ ><code>parse</code></a>, <a href=../../api/basic_json/accept/ ><code>accept</code></a>, and <a href=../../api/basic_json/sax_parse/ ><code>sax_parse</code></a> with an initializer list <code>{ptr, len}</code> or <code>{first, last}</code></td> <td>3.8.0</td> <td><a href=../../integration/migration_guide/#parsing>Parsing</a></td> </tr> <tr> <td><a href=../../api/basic_json/from_bson/ ><code>from_bson</code></a>, <a href=../../api/basic_json/from_cbor/ ><code>from_cbor</code></a>, <a href=../../api/basic_json/from_msgpack/ ><code>from_msgpack</code></a>, and <a href=../../api/basic_json/from_ubjson/ ><code>from_ubjson</code></a> with <code>(ptr, len)</code> or an initializer list</td> <td>3.8.0</td> <td><a href=../../integration/migration_guide/#parsing>Parsing</a></td> </tr> <tr> <td><a href=../../api/json_pointer/operator_string_t/ ><code>json_pointer::operator string_t</code></a></td> <td>3.11.0</td> <td><a href=../../integration/migration_guide/#json-pointers><abbr title="JavaScript Object Notation">JSON</abbr> Pointers</a></td> </tr> <tr> <td><a href=../../api/json_pointer/ ><code>json_pointer</code></a> with a <code>basic_json</code> type as template argument, and the overloads of <code>value</code>, <code>contains</code>, <code>operator[]</code>, and <code>at</code> accepting such a pointer</td> <td>3.11.0</td> <td><a href=../../integration/migration_guide/#json-pointers><abbr title="JavaScript Object Notation">JSON</abbr> Pointers</a></td> </tr> <tr> <td>Comparing a <a href=../../api/json_pointer/ ><code>json_pointer</code></a> with a string via <a href=../../api/json_pointer/operator_eq/ ><code>operator==</code></a> or <a href=../../api/json_pointer/operator_ne/ ><code>operator!=</code></a></td> <td>3.11.2</td> <td><a href=../../integration/migration_guide/#json-pointers><abbr title="JavaScript Object Notation">JSON</abbr> Pointers</a></td> </tr> <tr> <td><a href=../../api/basic_json/from_bjdata/ ><code>from_bjdata</code></a> and <a href=../../api/basic_json/from_bon8/ ><code>from_bon8</code></a> with <code>(ptr, len)</code></td> <td>3.13.0</td> <td><a href=../../integration/migration_guide/#parsing>Parsing</a></td> </tr> </tbody> </table> <p>The deprecated legacy comparison of discarded values is controlled by a macro and therefore listed in the table above.</p> <p>New breaking changes will follow the same path: they are added to these tables when they land in a 3.x release.</p> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-fiLine truncated
|
||||
</code></pre></div> <p>The macros must be defined before the library header is included; setting them once in the build system is the easiest way to achieve this.</p> <h3 id=removal-of-deprecated-functions>Removal of deprecated functions<a class=headerlink href=#removal-of-deprecated-functions title="Permanent link">¶</a></h3> <p>Version 4.0 will remove all deprecated functions. Compiling with deprecation warnings enabled shows which of them your code still uses. Defining <a href=../../api/macros/json_delete_deprecated_functions/ ><code>JSON_DELETE_DEPRECATED_FUNCTIONS</code></a> to <code>1</code> turns these warnings into errors, as the deprecated functions are then deleted. The <a href=../../integration/migration_guide/#replace-deprecated-functions>migration guide</a> shows how to replace each of them.</p> <p>The <code>from_*</code> overloads taking a pointer and a length are not removed in version 4.0, but stay deleted. Without them, a call like <code>from_cbor(ptr, len)</code> would still compile: it would read <code>ptr</code> as a NUL-terminated string and convert <code>len</code> to the <code>strict</code> parameter.</p> <table> <thead> <tr> <th>Deprecated</th> <th>Since</th> <th>Migration</th> </tr> </thead> <tbody> <tr> <td><code class=highlight><span class=k>operator</span><span class=o><<</span><span class=p>(</span><span class=n>basic_json</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>istream</span><span class=o>&</span><span class=p>)</span></code></td> <td>3.0.0</td> <td><a href=../../integration/migration_guide/#parsing>Parsing</a></td> </tr> <tr> <td><code class=highlight><span class=k>operator</span><span class=o>>></span><span class=p>(</span><span class=k>const</span><span class=w> </span><span class=n>basic_json</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>ostream</span><span class=o>&</span><span class=p>)</span></code></td> <td>3.0.0</td> <td><a href=../../integration/migration_guide/#miscellaneous-functions>Miscellaneous functions</a></td> </tr> <tr> <td><code>iterator_wrapper</code></td> <td>3.1.0</td> <td><a href=../../integration/migration_guide/#miscellaneous-functions>Miscellaneous functions</a></td> </tr> <tr> <td><a href=../../api/basic_json/parse/ ><code>parse</code></a>, <a href=../../api/basic_json/accept/ ><code>accept</code></a>, and <a href=../../api/basic_json/sax_parse/ ><code>sax_parse</code></a> with an initializer list <code>{ptr, len}</code> or <code>{first, last}</code></td> <td>3.8.0</td> <td><a href=../../integration/migration_guide/#parsing>Parsing</a></td> </tr> <tr> <td><a href=../../api/basic_json/from_bson/ ><code>from_bson</code></a>, <a href=../../api/basic_json/from_cbor/ ><code>from_cbor</code></a>, <a href=../../api/basic_json/from_msgpack/ ><code>from_msgpack</code></a>, and <a href=../../api/basic_json/from_ubjson/ ><code>from_ubjson</code></a> with <code>(ptr, len)</code> or an initializer list</td> <td>3.8.0</td> <td><a href=../../integration/migration_guide/#parsing>Parsing</a></td> </tr> <tr> <td><a href=../../api/json_pointer/operator_string_t/ ><code>json_pointer::operator string_t</code></a></td> <td>3.11.0</td> <td><a href=../../integration/migration_guide/#json-pointers><abbr title="JavaScript Object Notation">JSON</abbr> Pointers</a></td> </tr> <tr> <td><a href=../../api/json_pointer/ ><code>json_pointer</code></a> with a <code>basic_json</code> type as template argument, and the overloads of <code>value</code>, <code>contains</code>, <code>operator[]</code>, and <code>at</code> accepting such a pointer</td> <td>3.11.0</td> <td><a href=../../integration/migration_guide/#json-pointers><abbr title="JavaScript Object Notation">JSON</abbr> Pointers</a></td> </tr> <tr> <td>Comparing a <a href=../../api/json_pointer/ ><code>json_pointer</code></a> with a string via <a href=../../api/json_pointer/operator_eq/ ><code>operator==</code></a> or <a href=../../api/json_pointer/operator_ne/ ><code>operator!=</code></a></td> <td>3.11.2</td> <td><a href=../../integration/migration_guide/#json-pointers><abbr title="JavaScript Object Notation">JSON</abbr> Pointers</a></td> </tr> <tr> <td><a href=../../api/basic_json/from_bjdata/ ><code>from_bjdata</code></a> and <a href=../../api/basic_json/from_bon8/ ><code>from_bon8</code></a> with <code>(ptr, len)</code></td> <td>3.13.0</td> <td><a href=../../integration/migration_guide/#parsing>Parsing</a></td> </tr> </tbody> </table> <p>The deprecated legacy comparison of discarded values is controlled by a macro and therefore listed in the table above.</p> <p>New breaking changes will follow the same path: they are added to these tables when they land in a 3.x release.</p> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-fiLine truncated
|
||||
@@ -14,12 +14,31 @@ This page describes what the project intends to do, and what it does not intend
|
||||
|
||||
## What the project will not do
|
||||
|
||||
- **Break the public API of version 3.x.** See the [contribution guidelines](https://github.com/nlohmann/json/blob/develop/.github/CONTRIBUTING.md#break-the-public-api) for what counts as a breaking change.
|
||||
- **Break the public API of version 3.x.** See [API stability](#api-stability) for what this covers.
|
||||
- **Require a newer C++ standard than C++11.**
|
||||
- **Break JSON conformance** or enable non-standard extensions by default.
|
||||
- **Add dependencies** or require a build step. The library remains header-only, and the single header `json.hpp` remains a complete distribution.
|
||||
- **Trade simplicity for speed or memory efficiency.** Performance improvements are welcome, but the library is not meant to compete with the fastest JSON libraries, see [Design goals](https://json.nlohmann.me/home/design_goals/index.md).
|
||||
|
||||
## API stability
|
||||
|
||||
Releases follow [semantic versioning](https://semver.org): a minor or patch release of version 3.x does not break code that uses the public API. In particular, a 3.x release does not:
|
||||
|
||||
- change the signature of a function (its parameter types, return type, number of parameters, or the const-ness of a member function);
|
||||
- remove or rename a function or class;
|
||||
- change which exceptions a function throws, or the [exception ids](https://json.nlohmann.me/home/exceptions/index.md);
|
||||
- change access specifiers or default arguments.
|
||||
|
||||
Exceptions to these rules, for instance when fixing a bug requires changing the exception a function throws, are documented in the [release notes](https://json.nlohmann.me/home/releases/index.md).
|
||||
|
||||
The following are **not** part of the public API and may change in any release, including patch releases:
|
||||
|
||||
- The text of exception messages returned by `what()`. Use the [exception id](https://json.nlohmann.me/home/exceptions/index.md) to tell errors apart.
|
||||
- The ABI, including `sizeof(basic_json)` and the memory layout of its values. Recompile your code when you upgrade the library. The [versioned inline namespace](https://json.nlohmann.me/features/namespace/index.md) turns mixing versions into a link error.
|
||||
- Everything in namespace `nlohmann::detail`, and macros and type traits that are not documented in the [API reference](https://json.nlohmann.me/api/basic_json/index.md).
|
||||
|
||||
Changes that would break the public API are only added behind a macro whose default keeps the 3.x behavior, see [Version 4.0](#version-40).
|
||||
|
||||
## Version 4.0
|
||||
|
||||
There is no release date for version 4.0 yet. Proposals that need a major version, for instance stricter type conversions, are collected in issue [#3453](https://github.com/nlohmann/json/issues/3453).
|
||||
|
||||
Reference in new issue
Block a user