Compare commits

...
18 Commits
Author SHA1 Message Date
Niels Lohmann 1cafc6bfbb Merge origin/develop into docs/cross-reference-json-view-3-13-0
Resolve the See also conflicts in basic_json_document and basic_json_view
in favour of develop (#5906).

Signed-off-by: Niels Lohmann <mail@nlohmann.me>
2026-10-24 18:50:36 +02:00
Niels Lohmann 52b72b5684 Improve documentation: byte layouts, release pages, See also, dark-mode images (#5906)
- Make the iterator range illustrations legible in dark mode (prefers-color-scheme
  rules inside the SVGs).
- Add a "Byte layout" section with a color-coded byte table to each binary format
  page (BJData, BON8, BSON, CBOR, MessagePack, UBJSON), and highlight the smallest
  size per file in the comparison table.
- Add "See also" sections to the overview pages that lacked one.
- Split the release notes into one page per release, grouped by minor version on
  the overview page, with an "API changes" section per release generated from the
  API pages' version histories (hooks/api_changes.py).
- Fact-check the release notes and version histories against the release tags and
  correct wrong or misleading entries (e.g., json_serializer 2.1.0, merge_patch
  3.1.0, items, count, operator[], to_bjdata, std::string_view key support).

Signed-off-by: Niels Lohmann <mail@nlohmann.me>
2026-10-24 17:57:44 +02:00
Niels Lohmann 01139dc192 Silence an Infer false positive in json_view materialize (#5905)
Signed-off-by: Niels Lohmann <mail@nlohmann.me>
2026-10-24 17:10:31 +02:00
Niels Lohmann 9c50bdd140 Make the DOM parser cheaper per container and per member (#5882)
* Reserve the parser's nesting stack once

The stack of open arrays and objects was a std::vector<std::uint8_t> that
allocated at the first push_back and then reallocated at 1, 2, 4, 8 bytes,
so a document nested four levels deep made four allocations before it
parsed a value. A document that starts with a container now reserves 32
levels in one allocation; deeper documents grow as before. The loop that
reads the tokens is the code it was, so large documents are not affected
(a stack object with its own storage, and a reserve at every container,
both cost the token loop instructions or cycles).

Fixed cost of parsing a 124-byte object (macOS instructions): accept
-7.6 %, DOM -2.5 %; no change for a single number.

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

* Build arrays of the DOM parser in one exact-size allocation

Reading an array of unknown length appended its elements to a std::vector
one at a time, so a small array reallocated (and moved its elements) at
sizes 1, 2, 4, ... The DOM SAX parser now collects the elements of arrays
whose length is unknown on one stack shared by all open arrays and moves
them into an array of exactly the right size when the closing bracket
arrives. An array that grows past 16 elements switches to appending to its
own vector, so large arrays pay no second copy. Binary formats, which
announce the length, and builds with JSON_DIAGNOSTICS or
JSON_DIAGNOSTIC_POSITIONS (whose values need their final place from the
start) keep storing into the array directly.

The stacks of open containers are reserved on first use instead of growing
from one element.

The binary readers get a DOM parser of their own, json_sax_dom_binary_parser:
it is the plain parser that stores every value directly in its container
(the code the readers used before). Their containers announce their size, so
the bookkeeping of the collecting parser (frame entries, the destination of a
finished container) was pure overhead for them: with the collecting parser
FromBinaryShape nested was 3-12 % and containers up to 5 % more instructions
(GCC) than before. With the plain parser Linux Ir of FromBinaryShape and
FromBinaryBuffer is within 0.8 % of develop (Clang: identical).

canada.json has 56 000 two-element arrays that took three allocations each
and now take two. DOM parse Ir on Linux against develop (GCC / Clang): canada
-7.0 % / -7.7 %, citm -0.8 % / -1.6 %, 124-byte object -5.4 % / -5.5 %;
accept and SAX are untouched.

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

* Reuse one value for the key events of the callback parser

parse() with a callback built a new string value for every key it passed to
the callback (a heap allocation and release per key), and copied the key a
second time into the object. The callback parser now keeps one string value
for key events, which it assigns, and moves the key into the object.

Callback parse, Linux Ir (GCC / Clang): twitter -13.3 % / -11.7 %, citm
-9.5 % / -7.6 %. (Earlier macOS measurement: twitter -19.5 % instructions.)

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

* Remember where the DOM parser stores the next value

The DOM SAX parser looked up the innermost open container for every value:
the end of its frame stack, then the object or array pointer in the frame.
Compilers have to reload all of that after each value is stored, since a
store of a value may alias the frame. The parser now keeps the innermost
container's kind and, for an array that stores directly, the array itself
in members, updated when a container opens or closes.

Flat arrays of numbers are the case that mattered: parsing floats.json
(1 000 000 doubles) into a DOM took 2 % more cycles than before the
previous commit on macOS and now takes 0.4 % fewer than the code before it
(signed_ints.json -0.8 %). Linux Ir is unchanged (canada -6.1 % GCC /
-6.9 % Clang, citm -0.3 % / -0.8 %, twitter +0.2 % / 0.0 %).

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

* Look up the keys of big ordered_json objects in a hash table

ordered_map keeps its elements in a vector and searches it linearly for
every key it adds, so parsing an object with n keys into ordered_json took
O(n^2) key comparisons: 33 billion instructions for one object with 30 000
keys, where json needs 245 million. From 64 keys on, the DOM parser now
keeps a hash table of the keys of the open object (hashes and positions
only; the elements stay in the vector) and finds duplicate keys there. The
result is the same, including the position of a key that occurs twice.
Smaller objects, std::map based objects and key types without std::hash
are untouched.

ordered_json parse, macOS instructions: object with 1 000 keys 64.8 M ->
14.6 M, 10 000 keys 5 104 M -> 38.7 M, 30 000 keys 33 358 M -> 89 M.
Linux Ir of an object with 2 000 keys: 43.0 M -> 1.9 M (GCC), 37.9 M ->
1.8 M (Clang).

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

* Trim the work the DOM parser does per container and per member

Opening and closing an array or object cost the DOM parser more than before
the exact-size array change, which showed on documents of many small
objects (jeopardy.json: +1.4 % Ir with GCC). This takes it back:

- the stack of open containers keeps its first eight entries in the parser
  object instead of in a vector, so it needs no capacity check beyond the
  push itself and no allocation for typical documents;
- a container is created in the place it ends up in, instead of as a
  temporary that is then moved there;
- a new object member, which is null, is constructed over the null instead
  of being swapped with it (only with the default base class of basic_json);
- the key index that big ordered_json objects use is only a part of the
  stack entries of objects that can have one;
- an array that outgrows the stack reserves twice what it has so far, as a
  vector that grew by itself would have.

DOM parse Ir of the series up to here against develop, Linux GCC / Clang:
canada -6.6 % / -7.3 %, citm +1.2 % / +0.2 %, jeopardy +0.4 % / -0.1 %,
124-byte object -6.5 % / -6.2 %. (twitter measures +6.8 % / +6.6 % at this
point in steady state, almost all of it in glibc's malloc/consolidate for the
new allocation sizes; with the last commit of the series it is -0.1 % / 0.0 %.)

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

* Test parsing containers of the sizes where the DOM parser changes storage

The DOM parser collects the elements of an array on a stack (up to 16) and
the members of an ordered_json object (up to 32) before it moves them into
the container, and uses a hash table for keys from 64 members on. Parse
arrays and objects of the sizes around these limits, nested into each other,
with repeated keys, and as random trees that are built next to their text,
and compare json and ordered_json against the value built through the API.

The tests pass on the code from before these changes as well. The random
trees are what finds the mistakes that are easy to make here: while the
collecting change was being written, a collected array that outgrew the
stack at the moment its parent had just reached the limit left its elements
in the parent, and only these tests (142 failed assertions) showed it.

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

* Do not convert floats that cannot overflow in accept()

accept() only has to find out whether a float token is finite: json_sax_acceptor
ignores the value, and the parser rejects only a float that overflows. A
float whose digits fit into 19 digits and whose decimal exponent is at most
max_exponent10 - 19 is below 10^max_exponent10 and cannot overflow, so the
lexer, told by accept() that the value is not needed, skips the conversion
for those. A token that may overflow, with more digits, or in another float
format is converted as before, so 1e309 and its neighbours are rejected as
they were (the new test compares accept() with parse() on tokens around the
limit).

json::accept(): canada.json Ir -8.6 % (GCC) / -10.9 % (Clang), 124-byte
object -3.2 %; cycles on the M1 (release benchmarks, LTO): canada -7.8 %,
floats.json -9.0 %. The check tests the accept() flag first, so the parser
that needs the value pays one load and branch: SaxParse canada +0.35 % Ir
(GCC and Clang), DOM canada +0.4 %.

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

* Collect the members of ordered_json objects on a stack until they are known

An ordered_json object keeps its members in a vector and appends every new
member to it, so reading an object of unknown size reallocated the vector at
1, 2, 4, 8, ... members, and ordered_map copies all keys on every
reallocation. The DOM SAX parser now collects the members of such objects on
one stack shared by all open objects, as it does the elements of arrays, and
moves them into a vector of exactly the right size when the closing brace
arrives. An object that gets past 32 members switches to appending to its
own vector (and, from 64, to the key index of the earlier commit). The
members are the same, in the same order, and a key that occurs twice keeps
the place of its first occurrence. std::map based objects, objects whose
size the input announces (binary formats), and builds with JSON_DIAGNOSTICS
or JSON_DIAGNOSTIC_POSITIONS are untouched.

What only ordered objects need (the collected members, the key indexes) is
a member of the parser only for them, and the code that stores a value tries
the array that takes its elements directly first. An array that outgrows
the stack now reserves 32 elements, the capacity a vector that grew by
itself has at that point; with the larger reserve before, parsing
floats.json (1 000 000 numbers) was 2 % slower on Apple M1 than before this
series.

ordered_json parse, Linux Ir against develop (GCC / Clang): citm -11.6 % /
-11.7 %, twitter -8.4 % / -8.4 %, jeopardy (12 000 objects of 7 keys)
-10.5 % / -8.0 %, canada -3.9 % / -5.2 %, 124-byte object -20.9 % / -16.5 %.
macOS time (M1, earlier base): citm -19 %, twitter -13 %, jeopardy -13 %,
canada -14 %, 124-byte object -26 %. json parse: steady-state twitter -0.1 %
(see the previous commits), citm -1.2 %.

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

* Rename the key index's match callback so Flawfinder doesn't read it as std::equal

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

* Bind the parser test's strings by reference in the range-for loop

GCC and Clang 14 (-Wrange-loop-construct) reported the copy.

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

* Collect container values only in basic_json's own parse functions

A json_sax_dom_parser that a user constructs (as in the sax_no_exception
example) must hold the values read before a parse error, as on develop:
its value is used after the error. The values of containers of unknown
size are now collected on a stack only with the new template parameter
Collect (default false), which json::parse() and the json_view
materialization set; without it, every value is stored in place as it
arrives. A test checks the values kept after an error for json and
ordered_json.

Also fixes the clang-tidy, cpplint and Infer findings: the frame stack
keeps its first frames in a std::array (left uninitialized) and the
others in a std::unique_ptr, auto for create<>(), NOLINT for member
initializers -Weffc++ needs, and an @infer-ignore for the nullptr that
place_container() does not use.

json::parse() and ordered_json::parse() instructions are unchanged
(Apple clang; twitter, citm, canada, jeopardy: -0.03 % to +0.25 %).

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

* Clarify the DOM parser's collection stacks and rename reenter_enclosing_container()

Address review comments: explain why a closed container erases only the top
of the shared stack, set the payload before the type, rename the helper that
makes the enclosing container current again, and declare the parser's state
stack right before reserving it.

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

* Export json_sax_dom_parser from the C++20 module for MSVC

MSVC needs the detail classes that basic_json befriends to be visible in
the module (#3970, as json_sax_dom_callback_parser); with its new
template parameter, json_sax_dom_parser failed in ci_module_cpp20
(C2039, not a member of nlohmann::detail).

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

* Keep the overflow-limit numbers of the parser test in a std::vector

clang-tidy (cppcoreguidelines-avoid-c-arrays) rejected the C array.

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

* Fix the clang-tidy findings of the ordered_json parser tests

The container sizes are a std::array, the expected text uses raw string
literals, the generator's arithmetic is in parentheses, auto for the
result of make<>(), and single characters are appended as characters.
clang-tidy now reports nothing on the lines the branch adds to
unit-ordered_json.cpp and unit-class_parser.cpp (apart from checks CI's
clang-tidy does not have).

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

---------

Signed-off-by: Niels Lohmann <mail@nlohmann.me>
2026-10-24 07:41:21 +02:00
Niels Lohmann dd7686a269 json_view: faster reading, indexing and C-stream parsing (#5888)
* Read C streams into a json_document in blocks

json_document::parse(FILE*) (and read(), accept(), parse_copy()) went through the
library's file input adapter and appended the text character by character
with fgetc. Read it with fread in blocks instead, like the std::istream
overload already does.

Parsing citm_catalog.json (1.7 MB) from a FILE*:
  Apple M1: 80.6 M -> 8.4 M instructions, 4.8 ms -> 0.55 ms (parse of the same text from a std::string: 8.7 M)
  Linux x86-64 Ir (whole run), GCC 13 / Clang 18: 47.0 M -> 13.7 M / 45.8 M -> 14.2 M
The parsed documents and the error cases are identical (checked over the test corpus
and 30 mutants of each file). A null FILE* is handled as before (by the library's adapter).

Belongs to the PR "json_view: read-side speedups".

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

* Index arrays without subtrees directly

operator[](idx), at(idx) and back() skipped the elements of an array one
after the other, whatever they were. In an array none of whose elements is
an array or object (numbers, strings, booleans, null) the elements are
adjacent nodes, which the array node's own sizes tell: its subtree has
exactly one node more than it has elements. Such an element is now the
node idx after the array node; any other array is walked as before.

Reading r[i] for every i of an array of 3000 integers:
  Apple M1: 28.8 M instructions, 3.1 ms -> 0.1 M instructions, 4 us
  Linux x86-64 Ir (whole run), GCC 13 / Clang 18: 84.1 M -> 3.1 M / 75.0 M -> 3.0 M
Arrays that contain arrays are unchanged.

Belongs to the PR "json_view: read-side speedups".

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

* Skip the bounds checks of number and string tokens in NUL-terminated input

For a NUL-terminated input (std::string, C string, string literal), the
parser reads the terminator instead of comparing p with the end, via
cursor::cur(). Number and string scanning still tested `p != e` before each
look at the next byte (after the integer digits for '.', for 'e', after
the exponent sign and digits, and after a string for its closing quote),
although the terminator can never be one of those characters. They now use
cur(), which is the plain load for NUL-terminated input and the bounds check
for ptr+len input, as before.

Parsing, Apple M1 instructions per parse: twitter 3.126 M -> 3.089 M (-1.2 %),
citm_catalog 8.70 M -> 8.58 M (-1.3 %), jeopardy 306.1 M -> 302.5 M (-1.2 %), signed
integers 281 M -> 266 M (-5.4 %), canada and floats -0.1 % / -0.9 %.
Linux x86-64 Ir, GCC 13 / Clang 18: twitter -0.5 % / -0.0 %, signed integers +0.2 % / -0.7 %.

Belongs to the PR "json_view: read-side speedups".

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

* Make the index text of items() on arrays lazy

basic_json_view::items() on an array formatted every element's index with
std::to_string when the item was made, whether or not the loop asks for the
key. The item now keeps the position and makes the text on the first key()
call. Objects are not affected.

Iterating over the items of an array of 3000 numbers and reading only the values:
  Apple M1: 25.5 us -> 4.6 us (0.45 M -> ~0 net instructions)
  Linux x86-64 Ir (whole run), GCC 13 / Clang 18: 14.9 M -> 4.1 M / 15.3 M -> 4.6 M
Reading key() costs what it did (24.5 us).

Belongs to the PR "json_view: read-side speedups".

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

* Make the default of value() with a C string only if the member is missing

basic_json_view::value(key, "text") and value(pointer, "text") built a
std::string from the default first and passed it on, so a call allocated
for the default even when the member exists, and copied it again when it
does not. They now look the member up and make the result directly: from the
member if there is one, else from the C string. Behavior, including the
exceptions, is the same.

Two calls (member found, member missing) with a 40 character default, Apple M1:
  1.6 K -> 0.7 K instructions
  Linux x86-64 Ir (500 rounds), GCC 13 / Clang 18: 2.46 M -> 2.22 M / 2.40 M -> 2.15 M

Belongs to the PR "json_view: read-side speedups".

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

* Materialize scalars directly and keep the stack of small subtrees local

basic_json_view::materialize() (and get<BasicJsonType>()) always set up the
SAX handler that parse() uses and a std::vector for the open containers,
sized from the document's deepest nesting. For a scalar, which is most of what
is materialized one value at a time, neither is needed: the value is made
directly (the same constructors the handler ends up calling). For arrays and
objects the stack of open containers is now a local array for the first 16
levels, and the vector is only used for deeper documents.

Materializing five scalars of a small document, Apple M1: 3.6 K -> 0.9 K instructions
  Linux x86-64 Ir (500 rounds), GCC 13 / Clang 18: 2.96 M -> 2.37 M / 2.90 M -> 2.29 M

Belongs to the PR "json_view: read-side speedups".

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

* Copy the text between escapes while scanning it

A string that contains an escape is decoded by builder::slow_string(). After
each escape it scanned the next run of plain bytes (8 or 16 byte-by-byte
steps, then a vector loop), and then copied that run to the decode arena in a
second pass. The run is now copied 16 bytes at a time while it is scanned
(one vector load, a store of the same 16 bytes, and the mask of the bytes
that end the run), and the write position lives in a local variable, not in
the builder, since a store of a character may alias the builder's members and
made the compiler reload it after every escape. A run that ends at a quote
needs no scan, and non-ASCII text goes through the UTF-8 check as before;
the portable code is unchanged.

Parsing, Apple M1 instructions: jeopardy.json 304.0 M -> 293.8 M (-3.4 %), 3000 strings with
escapes 1.72 M -> 1.54 M (-10 %), twitter -0.6 %.
Linux x86-64 Ir, GCC 13 / Clang 18: escaped strings -7.6 % / -11.4 %, twitter 0.0 % / 0.0 %.
Documents and error messages are identical on 900 k random strings of escapes, UTF-8 and control
characters (also under ASan), and on mutants of the test corpus.

Belongs to the PR "json_view: read-side speedups".

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

* Hash the last bytes of a key of a large object without a loop

key_hash() mixed a key eight bytes at a time and then packed the remaining
0-7 bytes one by one, in a loop. The last word of a key of eight or more
bytes is now read as the last eight bytes of the key (overlapping the word
before), and a key of 2-7 bytes as two overlapping words of four or two
bytes. A product only moves bits upwards, and the slot is taken from the low
bits: the high bits of the last word are folded down before the
multiplication, since keys that differ only in their last characters ("user_17",
"user_18") would otherwise share slots. The hash is not stored, so its values
may change.

Looking up every key of an object of 1000 random keys, Apple M1 instructions per 1000 lookups:
  keys of 5 bytes 175 K -> 93 K, hex strings of 8 bytes 177 K -> 168 K, keys of 12 bytes 196 K -> 186 K
Linux x86-64 Ir (whole run), GCC 13 / Clang 18: 5-byte keys -4.7 % / -8.8 %, 12-byte keys -3.3 % / -7.4 %.
Building the tables while parsing such objects is cheaper as well (5-byte keys: 13.3 us -> 10.1 us).

Belongs to the PR "json_view: read-side speedups".

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

* Compare short keys of a large object without a call of memcmp

find_indexed() compared the key of a member the table points to with
memcmp, a library call for any length. Up to 16 bytes, the bytes are now
compared as two overlapping words (the first and the last 8, 4, or 2 bytes),
as find_member() already does for the objects without a table; longer keys
still use memcmp.

Looking up every key of an object of 1000 random keys, Apple M1 instructions per 1000 lookups
(with the previous commit): keys of 5 bytes 93 K -> 72 K, hex strings of 8 bytes 168 K -> 148 K,
keys of 12 bytes 186 K -> 170 K, keys of 24 bytes 198 K -> 193 K (unchanged, memcmp).
Linux x86-64 Ir (whole run), GCC 13 / Clang 18: 5-byte keys -7.2 % / -7.3 %, 12-byte keys -5.9 % / -6.6 %.

Belongs to the PR "json_view: read-side speedups".

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

* Read an unedited editable document like a read-only one

Views of a json_editable_document followed edits at every step: the
lookup, the element access, back(), dump() and materialize() were built
for nodes that can be moved or linked, though no edit changes the index until
the first one (every edit creates the edit state before it touches a node).
Until then these now take the read-only code: one check of the document's
edit state per call, not per member or per node. After the first edit
nothing changes. Views that were made earlier keep working, as the check is
made when they are used.

Unedited editable document, Apple M1: dump() of twitter.json 1.40 M -> 1.22 M instructions (-12.6 %);
lookups unchanged. Linux x86-64 Ir, GCC 13 / Clang 18: dump -1.7 % / -1.0 %, lookups -0.1 % / 0.0 %.
Walking with iterators is unchanged, and so is dump() after an edit.

Belongs to the PR "json_view: read-side speedups".

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

* Format the numbered test keys of json_view's index with a stream

The keys were made with snprintf() and a format from a list, which
Flawfinder reports as an error (CWE-134, a format string that is not a
literal). A stream now formats them; the 30000 keys of the test are the
same as before.

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

* Put the key number of the json_view index test in parentheses

astyle formatted i * step after << as a pointer declaration (i* step),
which failed the amalgamation check.

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

* Fix the compiler and lint findings of json_view's read side and tests

- find() and contains() dispatch on Editable for the member lookup; for
  documents that cannot be edited both branches were the same call
  (GCC -Wduplicated-branches)
- json_view.hpp includes <cstdio> for the FILE overload (cpplint)
- the arena check macro of the builder is on one line (cpplint read it
  as an if body without braces)
- tests: no nested conditional (also MSVC C4018), no useless cast,
  parentheses around mixed operators, raw string literals, += instead
  of temporary concatenations, and NOLINT for the fixed seeds and a
  find() != npos, as elsewhere in the tests

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

* Grow the decode arena through a function and store its position back on every return

slow_string() kept its write position in locals and grew the arena through
the macro NLOHMANN_VIEW_ENSURE. The macro is now the always-inline member
arena_ensure() (a lambda is not inlined at every call site by clang, which
then keeps the position in memory: +11 % instructions on escape-heavy
strings), and a guard stores the position back into m_arena_write on every
return instead of by hand on the successful one. Instruction counts are
unchanged (clang) or 1 % lower (GCC).

Also word the complexity of back() as that of at().

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

---------

Signed-off-by: Niels Lohmann <mail@nlohmann.me>
2026-10-24 07:41:06 +02:00
Niels Lohmann e9c4fe3cdf json_view: indented and ensure_ascii dumps through the fast writer (#5889)
* Write the indented output of json_view's dump() with the fast writer

The compact writer of dump() (cursor in a register, fixed-size copies of
tokens) served dump(-1) only; every dump(indent), and everything with
ensure_ascii that was indented, went through a generic walk that calls put()
for each token and put_repeated() (a memset call) for each line break. The
fast writer now writes indented output, too, with or without ensure_ascii, and
the generic walk is gone. A line break is a copy of a 64-byte ruler (a line
break and 63 indentation characters) when the line is at most 64 bytes, and a
store plus memset beyond that. The depth is counted only in the indented
instantiations (counting it in the compact one cost an editable document 5 %
with Clang). The indented walks are out of line (dump_pretty()): inlined
into dump() next to the compact ones, they made compact dumps of integer
arrays 7 % slower.

A decoded string (one with escape sequences) of a damaged image loaded with
image_check::bounds can contain invalid UTF-8. As before, the compact dump
writes such bytes unchanged, and the indented dump throws type_error.316; its
runs are found by the lexer's validating scan (a scalar validation of every
sequence made dump(2) of decoded CJK text twice as slow as before).

dump(2) instructions per call, macOS arm64 (before -> after):

               twitter         citm            canada          jeopardy(4k)
  json         3.75M -> 1.85M  8.28M -> 3.93M  67.1M -> 56.0M  9.56M -> 4.81M
  editable     3.82M -> 1.84M  8.48M -> 4.02M  68.1M -> 56.2M  9.66M -> 4.75M

Linux instructions (GCC 13 / Clang 18), dump(2) and dump(2, ' ', true):

  twitter      -25 % / -30 %      -11 % / -11 %
  citm         -29 % / -28 %      -24 % / -24 %
  jeopardy(4k) -25 % / -32 %      -20 % / -24 %
  CJK text with \u escapes  -6 % / -11 %   -2 % / -2 %

The compact dump is unchanged (within +0.4 % on Linux, within noise on the Mac).

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

* Scan the strings of json_view's dump() with ensure_ascii 16 bytes at a time

With ensure_ascii, a string of the source that has a byte >= 0x7F was written
by a generic path: put() per piece and a validate-and-decode step for every
character beyond ASCII. It now goes through a writer with the cursor in a
local variable. The part of the string that has nothing to escape is found
16 bytes at a time (SSE2 or NEON; the existing 8-byte scan without vector
support) and copied; strings that are ASCII throughout are still decided by
the 8-byte check of dump() with ensure_ascii (a 16-byte scan for them was
2-5 % slower for short strings). The two-byte sequences (lead C2..DF) and
the three-byte sequences whose continuation bytes may have any value (lead
E1..EF except ED) are decoded with a few compares; E0, ED, four-byte
sequences, and damaged input go through validate_one_utf8() as before, so
damaged images still throw type_error.316.

dump(-1, ' ', true) instructions per call, macOS arm64 (develop -> now);
the compact dump without ensure_ascii and dumps of ASCII text are unchanged:

  twitter 5.42M -> 3.57M    citm 3.28M -> 3.24M     jeopardy(4k) 5.78M -> 5.65M
  CJK text, raw 66.5M -> 35.3M    escaped \u 32.7M -> 17.0M
  Latin text with accents 11.5M -> 9.4M    ASCII text 4.40M -> 4.40M

Linux instructions (GCC 13 / Clang 18), dump(-1, ' ', true):

  twitter -9 % / -33 %    CJK text -14 % / -47 %    Latin text -8 % / -18 %
  citm -0.2 % / -0.4 %    ASCII text -0.1 % / -0.3 %

The compact dump without ensure_ascii is unchanged (canada 0.0 %).

The unit test covers every character of the Basic Multilingual Plane, and a
character that needs an escape at each position of strings of 0..40 bytes.

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

* Find the end of the plain run of a decoded string 16 bytes at a time with SSE2

The strings of a document that had escape sequences are written in runs
without a quote, backslash, or control character; the compact dump found the
end of a run 8 bytes at a time with a SWAR test. With SSE2 (x86-64) it now
compares 16 bytes per step. NEON keeps the SWAR code: there the mask of a
step costs more than it saves on the short runs that are typical here.

Instructions of dump(), Linux (GCC 13 / Clang 18):

  twitter.json                  1.99M -> 1.88M (-5.2 %) / 1.97M -> 1.92M (-3.0 %)
  CJK text with \u escapes      5.98M -> 4.52M (-24.5 %) / 5.30M -> 4.25M (-19.9 %)
  ASCII text with a few escapes 4.28M -> 4.09M (-4.4 %) / 4.24M -> 4.11M (-3.2 %)
  jeopardy (4,000 questions)    5.08M -> 4.78M (-5.8 %) / 4.97M -> 4.80M (-3.4 %)

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

* Rename depth_counter's open() and close() to enter() and leave()

Flawfinder took them for the file functions open() and close().

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

* Fix the clang-tidy findings in json_view's dump and its tests

- the SSE2 loop of the string scan is within NOLINTBEGIN/END
  (portability-simd-intrinsics), as in to_chars.hpp
- depth_counter<false>'s leave() and get() keep the interface of
  depth_counter<true> instead of being static
- write_ascii() compares the room left as a size_t variable
- the test's texts are a std::array, and a JSON fragment with escapes
  is a raw string literal

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

* Move dump_ascii() and dump_pretty() next to dump()

Address a review comment: the two dispatchers that dump() calls now follow
it directly.

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

---------

Signed-off-by: Niels Lohmann <mail@nlohmann.me>
2026-10-24 07:38:17 +02:00
dependabot[bot] 1e9222f955 Bump dompurify from 3.4.16 to 3.4.17 in /docs/mkdocs/scripts/mermaid (#5904)
Bumps [dompurify](https://github.com/cure53/DOMPurify) from 3.4.16 to 3.4.17.
- [Release notes](https://github.com/cure53/DOMPurify/releases)
- [Commits](https://github.com/cure53/DOMPurify/compare/3.4.16...3.4.17)

---
updated-dependencies:
- dependency-name: dompurify
  dependency-version: 3.4.17
  dependency-type: indirect
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
2026-10-24 07:37:42 +02:00
Niels Lohmann ffcd392be0 Fix Semgrep findings in Python tooling (#5899)
- generate_docset.py: use SHA-256 instead of SHA-1 for the cache file
  name digest of downloaded images.
- generate_docset.py: suppress dynamic-urllib-use-detected; the URL
  scheme is restricted to http(s) right before the call.
- generate_natvis.py: suppress direct-use-of-jinja2; the template
  renders a local XML file with autoescape enabled.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>
2026-10-23 07:11:17 +02:00
dependabot[bot] e28506dd86 Bump jsdom from 30.1.2 to 30.1.3 in /docs/mkdocs/scripts/mermaid (#5898)
Signed-off-by: Niels Lohmann <mail@nlohmann.me>
2026-10-23 06:54:23 +02:00
dependabot[bot] 03a0595c1e Bump actions/upload-artifact from 7.0.1 to 7.0.2 (#5897)
Signed-off-by: Niels Lohmann <mail@nlohmann.me>
2026-10-23 06:54:07 +02:00
dependabot[bot] 4e72af9d54 Bump step-security/harden-runner from 2.21.1 to 2.22.1 (#5896)
Signed-off-by: Niels Lohmann <mail@nlohmann.me>
2026-10-23 06:53:50 +02:00
dependabot[bot] 0f5d07310c Bump the codeql-action group with 4 updates (#5895)
Signed-off-by: Niels Lohmann <mail@nlohmann.me>
2026-10-23 06:53:32 +02:00
Niels Lohmann 0b924f5375 Split and print JSON pointers in one pass (#5887)
Signed-off-by: Niels Lohmann <mail@nlohmann.me>
2026-10-23 06:53:15 +02:00
Niels Lohmann 6fa14d8f95 Write binary formats through reserved sink space and number runs (#5885)
Signed-off-by: Niels Lohmann <mail@nlohmann.me>
2026-10-23 06:52:58 +02:00
Niels Lohmann dec0e9b749 Write strings, scalars and indentation in dump() with fewer calls (#5883)
Signed-off-by: Niels Lohmann <mail@nlohmann.me>
2026-10-23 06:52:41 +02:00
Niels Lohmann 86d5c56c54 Speed up flatten(), unflatten(), diff() and patch() further (#5886)
Signed-off-by: Niels Lohmann <mail@nlohmann.me>
2026-10-23 06:48:12 +02:00
Niels Lohmann aa0b371f7c Faster std::istream input: inline get-area path, binary reads, unbuffered streambufs (#5884)
Signed-off-by: Niels Lohmann <mail@nlohmann.me>
2026-10-23 06:48:00 +02:00
Niels Lohmann ace1030107 Fix develop CI: bit_cast ADL ambiguity and artifact-less comment runs (#5894)
- unit-stl_helpers.cpp: with a std::array argument, an unqualified
  bit_cast<...>(bytes) also finds std::bit_cast via ADL in C++20 and
  MSVC 2019 rejects the call as ambiguous (AppVeyor). Qualify the call.
- comment_check_amalgamation.yml: skip, rather than crash, when the
  triggering run has no "pr" artifact (stale queued runs that complete
  as failed without ever running a job).

Signed-off-by: Niels Lohmann <mail@nlohmann.me>
2026-10-22 20:22:53 +02:00
163 changed files with 13344 additions and 2500 deletions

No files matched your search

+3 -3
View File
@@ -38,14 +38,14 @@ jobs:
# Initializes the CodeQL tools for scanning.
- name: Initialize CodeQL
uses: github/codeql-action/init@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3
uses: github/codeql-action/init@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
with:
languages: c-cpp
# Autobuild attempts to build any compiled languages (C/C++, C#, or Java).
# If this step fails, then you should remove it and run the build manually (see below)
- name: Autobuild
uses: github/codeql-action/autobuild@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3
uses: github/codeql-action/autobuild@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
- name: Perform CodeQL Analysis
uses: github/codeql-action/analyze@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3
uses: github/codeql-action/analyze@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
@@ -37,6 +37,14 @@ jobs:
var matchArtifact = artifacts.data.artifacts.filter((artifact) => {
return artifact.name == "pr"
})[0];
// a run that failed before its jobs started (e.g. a stale queued
// run cancelled long after its push) has no artifact to report on
if (!matchArtifact) {
core.notice('Run ${{ github.event.workflow_run.id }} has no "pr" artifact; nothing to comment on.');
core.setOutput('found', 'false');
return;
}
core.setOutput('found', 'true');
var download = await github.rest.actions.downloadArtifact({
owner: context.repo.owner,
repo: context.repo.repo,
@@ -51,9 +59,11 @@ jobs:
# Extract the untrusted PR artifact into a dedicated empty directory and
# read only the two expected files by fixed path afterwards. This avoids a
# malicious archive overwriting workspace files or escaping via ../ paths.
- run: unzip -o pr.zip -d ./pr_artifact
- if: steps.download.outputs.found == 'true'
run: unzip -o pr.zip -d ./pr_artifact
- name: 'Comment on PR'
if: steps.download.outputs.found == 'true'
uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
+1 -1
View File
@@ -47,6 +47,6 @@ jobs:
output: 'flawfinder_results.sarif'
- name: Upload analysis results to GitHub Security tab
uses: github/codeql-action/upload-sarif@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3
uses: github/codeql-action/upload-sarif@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
with:
sarif_file: ${{github.workspace}}/flawfinder_results.sarif
+2 -2
View File
@@ -54,7 +54,7 @@ jobs:
timeout-minutes: 60
steps:
- name: Harden Runner
uses: step-security/harden-runner@e14015d583714f6e62063499dc959a02595150a1 # v2.21.1
uses: step-security/harden-runner@ccd8616d44fd3846e67624a50d5aad6d37bf2d25 # v2.22.1
with:
egress-policy: audit
@@ -78,7 +78,7 @@ jobs:
- name: Summary
run: cat tests/benchmarks/json_view/results/*.md >> "$GITHUB_STEP_SUMMARY"
- uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
- uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: json_view-benchmarks-${{ matrix.runner }}-${{ inputs.compiler || 'g++' }}
path: tests/benchmarks/json_view/results/
+1 -1
View File
@@ -80,6 +80,6 @@ jobs:
# Upload the results to GitHub's code scanning dashboard.
- name: "Upload to code-scanning"
uses: github/codeql-action/upload-sarif@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3
uses: github/codeql-action/upload-sarif@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
with:
sarif_file: results.sarif
+1 -1
View File
@@ -65,7 +65,7 @@ jobs:
# Upload SARIF file generated in previous step
- name: Upload SARIF file
uses: github/codeql-action/upload-sarif@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3
uses: github/codeql-action/upload-sarif@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
with:
sarif_file: semgrep.sarif
if: always()
+2 -1
View File
@@ -341,13 +341,14 @@ def download(url, docs) -> str:
raise ValueError(f'not an http(s) URL: {url}')
req = urllib.request.Request(u.geturl(), headers={'User-Agent': USER_AGENT})
# (the scheme is checked above)
# nosemgrep: python.lang.security.audit.dynamic-urllib-use-detected.dynamic-urllib-use-detected
with urllib.request.urlopen(req, timeout=20) as r: # nosec B310
data = r.read()
ctype = r.headers.get_content_type()
path = urllib.parse.unquote(u.path).lstrip('/')
ext = os.path.splitext(path)[1]
if u.query or not ext or path.endswith('/'):
digest = hashlib.sha1(url.encode(), usedforsecurity=False).hexdigest()[:12]
digest = hashlib.sha256(url.encode()).hexdigest()[:12]
path = os.path.join(os.path.dirname(path), digest + CONTENT_TYPE_EXT.get(ctype, ext or '.bin'))
rel = os.path.normpath(os.path.join('assets', 'external', u.hostname, path))
out = os.path.join(docs, rel)
@@ -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)
## Version history
- Added in version 2.1.0.
+2 -3
View File
@@ -239,9 +239,8 @@ Strong exception safety: if an exception occurs, the original value stays intact
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.
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 -1
View File
@@ -63,4 +63,4 @@ Constant.
## 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.
@@ -482,15 +482,15 @@ basic_json(basic_json&& other) noexcept;
## 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.
+2 -3
View File
@@ -141,9 +141,8 @@ Logarithmic in the size of the JSON object.
## 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.
+2 -3
View File
@@ -92,8 +92,7 @@ Logarithmic in the size of the JSON object.
## 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 -1
View File
@@ -69,6 +69,6 @@ Logarithmic in the size of the container, O(log(`size()`)).
## 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`.
@@ -67,5 +67,5 @@ Amortized constant.
## Version history
- Since version 2.0.8.
- Added in version 2.0.8.
- Returns reference since 3.7.0.
+2 -3
View File
@@ -213,7 +213,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 -1
View File
@@ -84,4 +84,4 @@ constructor.
## Version history
- Since version 3.0.0.
- Added in version 3.0.0.
+2 -3
View File
@@ -99,8 +99,7 @@ Logarithmic in the size of the JSON object.
## Version history
1. Added in version 3.11.0.
2. Added in version 1.0.0. Changed 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 1.0.0. Changed 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. 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 -1
View File
@@ -57,4 +57,4 @@ Constant.
## 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.
+3 -3
View File
@@ -188,6 +188,6 @@ overload (3).
## Version history
1. Since version 2.1.0.
2. Since version 2.1.0. Extended to work with other specializations of `basic_json` in version 3.2.0.
3. Since version 1.0.0.
1. Added in version 2.1.0.
2. Added in version 2.1.0. Extended to work with other specializations of `basic_json` in version 3.1.2.
3. Added in version 1.0.0.
+1 -1
View File
@@ -76,5 +76,5 @@ Depends on the `json_serializer<ValueType>::from_json()` implementation.
## Version history
- Since version 3.3.0.
- Added in version 3.3.0.
- Added a `static_assert` with a clear message for `const` arguments in version 3.13.0.
@@ -75,4 +75,4 @@ classDiagram
## Version history
- Since version 3.0.0.
- Added in version 3.0.0.
+2 -2
View File
@@ -104,8 +104,8 @@ When iterating over an array, `key()` will return the index of the element as st
## Version history
- Added `iterator_wrapper` in version 3.0.0.
- Added `items` and deprecated `iterator_wrapper` in version 3.1.0.
- Added in version 3.1.0 as the replacement of the static function `iterator_wrapper`, which was available since
version 1.0.0 and is deprecated since version 3.1.0.
- Added structured binding support in version 3.5.0.
!!! warning "Deprecation"
@@ -51,4 +51,4 @@ deserializes. See [Template Parameter Requirements](../../features/types/templat
## Version history
- Since version 2.0.0.
- Added in version 2.1.0.
@@ -71,6 +71,6 @@ returned by `#!cpp (*this)[key]`); it is read as it was when `merge_patch()` was
## Version history
- Added in version 3.0.0.
- Added in version 3.1.0.
- Fixed use of freed or relocated memory when `apply_patch` is `#!cpp *this` or refers to a value contained in
`#!cpp *this`, in version 3.13.0.
@@ -128,6 +128,6 @@ interpreted as `object_t::value_type` or `std::initializer_list<basic_json>`, se
## Version history
1. Since version 1.0.0.
2. Since version 1.0.0.
3. Since version 2.0.0.
1. Added in version 1.0.0.
2. Added in version 1.0.0.
3. Added in version 2.0.0.
@@ -284,10 +284,10 @@ Strong exception safety: if an exception occurs, the original value stays intact
1. Added in version 1.0.0. Fixed in version 3.13.0 to throw `#!cpp std::length_error` instead of emptying the array and
accessing it out of bounds when `idx` equals the maximum value of `size_type`. A missing index in the const version
is guarded by a runtime assertion since version 3.13.0.
2. Added in version 1.0.0. Added overloads for `T* key` in version 1.1.0. Removed overloads for `T* key` (replaced by 3)
in version 3.11.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 [`at`](at.md), [`value`](value.md), [`find`](find.md), and other lookup functions.
2. Added in version 1.0.0. Added overloads for `T* key` in version 1.1.0. The `T* key` overloads forward to
overload 3 since version 3.11.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. A missing array index in the const version is guarded by a runtime assertion since
version 3.13.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
@@ -89,6 +89,6 @@ Linear in the size of the JSON value.
## Version history
- Since version 1.0.0.
- Added in version 1.0.0.
- Macros `JSON_EXPLICIT`/[`JSON_USE_IMPLICIT_CONVERSIONS`](../macros/json_use_implicit_conversions.md) added
in version 3.9.0.
@@ -75,4 +75,4 @@ classDiagram
## Version history
- Since version 3.0.0.
- Added in version 3.0.0.
@@ -76,4 +76,4 @@ classDiagram
## Version history
- Since version 3.0.0.
- Added in version 3.0.0.
@@ -84,4 +84,4 @@ or the end of file. This also holds true when reading a byte vector for binary f
## Version history
- Since version 3.0.0.
- Added in version 3.0.0.
+3 -3
View File
@@ -125,6 +125,6 @@ throws.
## Version history
1. Since version 1.0.0.
2. Since version 1.0.0.
3. Since version 2.0.0.
1. Added in version 1.0.0.
2. Added in version 1.0.0.
3. Added in version 2.0.0.
+7 -7
View File
@@ -182,10 +182,10 @@ Constant.
## Version history
1. Since version 1.0.0. Exchanges the `json_base_class_t` subobject along with the value since version 3.13.0.
2. Since version 1.0.0. Exchanges the `json_base_class_t` subobject along with the value since version 3.13.0.
3. Since version 1.0.0.
4. Since version 1.0.0.
5. Since version 1.0.0.
6. Since version 3.8.0.
7. Since version 3.8.0.
1. Added in version 1.0.0. Exchanges the `json_base_class_t` subobject along with the value since version 3.13.0.
2. Added in version 1.0.0. Exchanges the `json_base_class_t` subobject along with the value since version 3.13.0.
3. Added in version 1.0.0.
4. Added in version 1.0.0.
5. Added in version 1.0.0.
6. Added in version 3.8.0.
7. Added in version 3.8.0.
@@ -124,5 +124,3 @@ Linear in the size of the JSON value `j`.
[`JSON_STRICT_BINARY_UTF8`](../macros/json_strict_binary_utf8.md) is enabled) throws `type_error.316`.
- Throws `type_error.321` for a discarded value since version 3.13.0; previously, a discarded value nested in an
array or object was silently skipped, producing invalid BJData.
- Writes unsigned integers wider than 64 bits as high-precision numbers since version 3.13.0; previously, they were
silently truncated to 64 bits.
@@ -76,4 +76,4 @@ classDiagram
## Version history
- Since version 3.0.0.
- Added in version 3.0.0.
+3 -6
View File
@@ -231,11 +231,8 @@ changes to any JSON value.
1. Added in version 1.0.0. Changed parameter `default_value` type from `const ValueType&` to `ValueType&&` in version
3.11.0. 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.
2. Added in version 3.11.0. Made `ValueType` the first template parameter in version 3.11.2. Fixed in version 3.13.0
to consistently accept `std::string_view`-convertible keys, as already supported by
[`operator[]`](operator[].md), [`at`](at.md), [`find`](find.md), and other lookup functions.
3. Added in version 2.0.2. Extended to work with arrays in version 3.13.0, including fixing an issue where resolving
`ptr` through an array unexpectedly threw `out_of_range` instead of returning the resolved element (or
`default_value`, as documented). Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109)
2. Added in version 3.11.0. Made `ValueType` the first template parameter in version 3.11.2. Support for keys
convertible to `std::string_view` added in version 3.13.0, consistently across the lookup functions.
3. Added in version 2.0.2. Extended to work with arrays in version 3.13.0. Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109)
instead of returning `default_value` 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.
@@ -117,9 +117,10 @@ points apply to every edit:
## See also
- [basic_json_view](../basic_json_view/index.md) - the read-only handle to a value of a document
- [json_document](../json_document.md) - this template for the default specialization `nlohmann::json`
- [Zero-copy JSON views](../../features/json_view.md) - the concept behind documents and views
- [Zero-copy JSON views](../../features/json_view.md) - guide to documents and views
- [**basic_json_view**](../basic_json_view/index.md) - the non-owning handle to a value in a document
- [**json_document**](../json_document.md) and [**json_editable_document**](../json_editable_document.md) - the default specializations
- [**materialize**](../basic_json_view/materialize.md) - build a `basic_json` value from a view
## Version history
+2 -1
View File
@@ -80,7 +80,8 @@ None of these exceptions carry a [`JSON_DIAGNOSTICS`](../macros/json_diagnostics
Objects with 128 or more members get a hash index of their keys while parsing, so that a lookup in them takes
constant time on average.
2. Linear in `idx`: elements are skipped one at a time from the first one, since they are not a fixed size in the
index (unlike `BasicJsonType`'s array, which is random-access).
index (unlike `BasicJsonType`'s array, which is random-access). Constant if no element of the array is an array
or object, since the elements are then adjacent in the index.
3. Linear in the number of reference tokens of `ptr` and, for each token, in the number of members of the object at
that level (as 1.) or the index into the array (as 2.).
+2 -1
View File
@@ -28,7 +28,8 @@ This exception does not carry a [`JSON_DIAGNOSTICS`](../macros/json_diagnostics.
Linear in the size of the array or object: unlike [`front()`](front.md), which only ever looks at the first
element, `back()` has to walk every element to find where they end, since elements are not a fixed size in the
index.
index. Constant if no element of the array is an array or object, since the elements are then adjacent
in the index.
## Notes
@@ -145,9 +145,10 @@ still refers to it -- including ones taken before the change -- reads the new va
## See also
- [basic_json_document](../basic_json_document/index.md) - the document a view refers into
- [materialize](materialize.md) - build the `BasicJsonType` value of a subtree
- [Zero-copy JSON views](../../features/json_view.md) - the concept behind documents and views
- [Zero-copy JSON views](../../features/json_view.md) - guide to documents and views
- [**basic_json_document**](../basic_json_document/index.md) - the document that owns the parsed data
- [**json_view**](../json_view.md) and [**json_editable_view**](../json_editable_view.md) - the default specializations
- [**materialize**](materialize.md) - build a `basic_json` value from a view
## Version history
@@ -86,7 +86,8 @@ None of these exceptions carry a [`JSON_DIAGNOSTICS`](../macros/json_diagnostics
Objects with 128 or more members get a hash index of their keys while parsing, so that a lookup in them takes
constant time on average.
2. Linear in `idx`: elements are skipped one at a time from the first one, since they are not a fixed size in the
index (unlike `BasicJsonType`'s array, which is random-access).
index (unlike `BasicJsonType`'s array, which is random-access). Constant if no element of the array is an array
or object, since the elements are then adjacent in the index.
3. Linear in the number of reference tokens of `ptr` and, for each token, in the number of members of the object at
that level (as 1.) or the index into the array (as 2.).
@@ -51,4 +51,4 @@ byte_container_with_subtype(container_type&& container, subtype_type subtype);
## Version history
Since version 3.8.0.
Added in version 3.8.0.
@@ -39,4 +39,4 @@ Constant.
## Version history
Since version 3.8.0.
Added in version 3.8.0.
@@ -42,4 +42,4 @@ Constant.
## Version history
Since version 3.8.0.
Added in version 3.8.0.
@@ -29,6 +29,14 @@ specific naming scheme in order to override the binary type.
- [**has_subtype**](has_subtype.md) - return whether the value has a subtype
- [**clear_subtype**](clear_subtype.md) - clears the binary subtype
## See also
- [Binary values](../../features/binary_values.md) - how binary values and subtypes are handled
- [**binary**](../basic_json/binary.md) - create a binary array value
- [**get_binary**](../basic_json/get_binary.md) - get a reference to the stored binary value
- [**binary_t**](../basic_json/binary_t.md) - type for binary arrays
- [Binary formats](../../features/binary_formats/index.md) - formats that can store binary values
## Version history
- Added in version 3.8.0.
@@ -44,4 +44,4 @@ Constant.
## Version history
Since version 3.8.0.
Added in version 3.8.0.
+1 -1
View File
@@ -30,4 +30,4 @@ types.
## Version history
Since version 1.0.0.
Added in version 1.0.0.
+1 -1
View File
@@ -32,4 +32,4 @@ specialization.
## Version history
Since version 3.13.0.
Added in version 3.13.0.
@@ -40,4 +40,4 @@ parsing, without ever rewriting the source text -- see [Edits](basic_json_docume
## Version history
Since version 3.13.0.
Added in version 3.13.0.
+1 -1
View File
@@ -38,4 +38,4 @@ still referring to it seeing the change, see [Edits](basic_json_document/index.m
## Version history
Since version 3.13.0.
Added in version 3.13.0.
@@ -51,5 +51,5 @@ operator string_t() const
## Version history
- Since version 2.0.0.
- Added in version 2.0.0.
- Changed type to `string_t` and deprecated in version 3.11.0.
@@ -49,5 +49,5 @@ ptr == json_pointer(ptr.to_string());
## Version history
- Since version 2.0.0.
- Added in version 2.0.0.
- Changed return type to `string_t` in version 3.11.0.
+7
View File
@@ -59,6 +59,13 @@ leading `-` sign.
- [**start_object**](start_object.md) (_virtual_) - the beginning of an object was read
- [**string**](string.md) (_virtual_) - a string value was read
## See also
- [SAX interface](../../features/parsing/sax_interface.md) - guide to event-based parsing
- [**sax_parse**](../basic_json/sax_parse.md) - generate SAX events from an input
- [**parse**](../basic_json/parse.md) - DOM parsing, with optional [parser callbacks](../../features/parsing/parser_callbacks.md)
- [Parse exceptions](../../features/parsing/parse_exceptions.md)
## Version history
- Added in version 3.2.0.
+1 -1
View File
@@ -31,4 +31,4 @@ This type is a [`basic_json_view`](basic_json_view/index.md) of a value of a [`j
## Version history
Since version 3.13.0.
Added in version 3.13.0.
+10 -1
View File
@@ -137,4 +137,13 @@ header. See also the [macro overview page](../../features/macros.md).
- [**NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_WITH_DEFAULT_WITH_NAMES**](nlohmann_define_type_with_names.md) - serialize/deserialize
a derived class; uses default values; uses custom names
- [**NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE_WITH_NAMES**](nlohmann_define_type_with_names.md) - serialize a derived
class; uses custom names
class; uses custom names
## See also
- [Macros](../../features/macros.md) - guide to the supported macros
- [Runtime assertions](../../features/assertions.md)
- [Arbitrary type conversions](../../features/arbitrary_types.md) - using the `NLOHMANN_DEFINE_TYPE_*` macros
- [Enum conversion](../../features/enum_conversion.md) - using `NLOHMANN_JSON_SERIALIZE_ENUM`
- [The `nlohmann` namespace](../../features/namespace.md)
- [CMake integration](../../integration/cmake.md) - setting macros from the build system
+1 -1
View File
@@ -42,4 +42,4 @@ parsing an object of `n` keys costs O(n²) rather than O(n log n). See
## Version history
Since version 3.9.0.
Added in version 3.9.0.
@@ -35,4 +35,4 @@ of object keys, instead of sorting them like [`json_document`](json_document.md)
## Version history
Since version 3.13.0.
Added in version 3.13.0.
@@ -44,4 +44,4 @@ members [`set`](basic_json_document/set.md) added -- instead of sorting them lik
## Version history
Since version 3.13.0.
Added in version 3.13.0.
@@ -37,4 +37,4 @@ This type is a [`basic_json_view`](basic_json_view/index.md) of a value of an
## Version history
Since version 3.13.0.
Added in version 3.13.0.
+1 -1
View File
@@ -32,4 +32,4 @@ This type is a [`basic_json_view`](basic_json_view/index.md) of a value of an
## Version history
Since version 3.13.0.
Added in version 3.13.0.
+1 -1
View File
@@ -58,7 +58,7 @@ particular, a 3.x release does not:
- remove or rename a documented macro, CMake option, CMake target, or header, or change what a documented macro does.
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).
documented in the [release notes](../home/releases/index.md).
The following are **not** part of the public API and may change in any release, including patch releases:
+29
View File
@@ -18,3 +18,32 @@
white-space: nowrap;
cursor: help;
}
/* byte layout tables of the binary formats */
.md-typeset .byte-layout td code {
white-space: pre-wrap;
}
.md-typeset .bl {
display: inline-block;
padding: 0 .25em;
border-radius: .2em;
font-family: var(--md-code-font-family);
font-size: .85em;
white-space: nowrap;
}
.md-typeset .bl-t {
background-color: rgba(66, 133, 244, .25);
box-shadow: inset 0 -.12em 0 rgba(66, 133, 244, .8);
}
.md-typeset .bl-l {
background-color: rgba(251, 140, 0, .25);
box-shadow: inset 0 -.12em 0 rgba(251, 140, 0, .8);
}
.md-typeset .bl-d {
background-color: rgba(67, 160, 71, .25);
box-shadow: inset 0 -.12em 0 rgba(67, 160, 71, .8);
}
@@ -190,6 +190,41 @@ The library uses the following mapping from JSON values types to BJData types ac
--8<-- "examples/to_bjdata.output"
```
### Byte layout
Consider the following JSON value (shown formatted for readability):
```json
{
"id": 300,
"name": "json",
"pi": 3.14,
"tags": [
"a",
"b"
]
}
```
`to_bjdata` encodes it to 51 bytes (shown in hexadecimal; the encoding contains no whitespace). The colors mark the role of each byte: <span class="bl bl-t">type/marker</span> <span class="bl bl-l">length/count/size</span> <span class="bl bl-d">data</span>.
<div class="byte-layout" markdown="0"><table>
<thead><tr><th>JSON</th><th>Bytes</th><th>Meaning</th></tr></thead><tbody>
<tr><td><code>{</code></td><td><span class="bl bl-t">7B</span></td><td>object start (<code>{</code>)</td></tr>
<tr><td><code>&quot;id&quot;: 300,</code></td><td><span class="bl bl-l">69 02</span> <span class="bl bl-d">69 64</span> <span class="bl bl-t">49</span> <span class="bl bl-d">2C 01</span></td><td>key: length 2 as int8 (<code>i</code>), then UTF-8 bytes; value: int16 (<code>I</code>), little-endian</td></tr>
<tr><td><code>&quot;name&quot;: &quot;json&quot;,</code></td><td><span class="bl bl-l">69 04</span> <span class="bl bl-d">6E 61 6D 65</span> <span class="bl bl-t">53</span> <span class="bl bl-l">69 04</span> <span class="bl bl-d">6A 73 6F 6E</span></td><td>key: length 4; value: string (<code>S</code>), length 4 as int8, UTF-8 bytes</td></tr>
<tr><td><code>&quot;pi&quot;: 3.14,</code></td><td><span class="bl bl-l">69 02</span> <span class="bl bl-d">70 69</span> <span class="bl bl-t">44</span> <span class="bl bl-d">1F 85 EB 51 B8 1E 09 40</span></td><td>key: length 2; value: float64 (<code>D</code>), little-endian</td></tr>
<tr><td><code>&quot;tags&quot;: [</code></td><td><span class="bl bl-l">69 04</span> <span class="bl bl-d">74 61 67 73</span> <span class="bl bl-t">5B</span></td><td>key: length 4; value: array start (<code>[</code>)</td></tr>
<tr><td><code>&quot;a&quot;,</code></td><td><span class="bl bl-t">53</span> <span class="bl bl-l">69 01</span> <span class="bl bl-d">61</span></td><td>string, length 1</td></tr>
<tr><td><code>&quot;b&quot;</code></td><td><span class="bl bl-t">53</span> <span class="bl bl-l">69 01</span> <span class="bl bl-d">62</span></td><td>string, length 1</td></tr>
<tr><td><code>]</code></td><td><span class="bl bl-t">5D</span></td><td>array end (<code>]</code>)</td></tr>
<tr><td><code>}</code></td><td><span class="bl bl-t">7D</span></td><td>object end (<code>}</code>)</td></tr>
</tbody></table></div>
## Deserialization
The library maps BJData types to JSON value types as follows:
@@ -105,6 +105,41 @@ serialized as 0x81 0x65 0xFF, but `[1,2,3,4,"e"]` as 0x85 0x91 0x92 0x93 0x94 0x
--8<-- "examples/to_bon8.output"
```
### Byte layout
Consider the following JSON value (shown formatted for readability):
```json
{
"id": 300,
"name": "json",
"pi": 3.14,
"tags": [
"a",
"b"
]
}
```
`to_bon8` encodes it to 35 bytes (shown in hexadecimal; the encoding contains no whitespace). The colors mark the role of each byte: <span class="bl bl-t">type/marker</span> <span class="bl bl-l">length/count/size</span> <span class="bl bl-d">data</span>.
<div class="byte-layout" markdown="0"><table>
<thead><tr><th>JSON</th><th>Bytes</th><th>Meaning</th></tr></thead><tbody>
<tr><td><code>{</code></td><td><span class="bl bl-t">8A</span></td><td>object with 4 members</td></tr>
<tr><td><code>&quot;id&quot;: 300,</code></td><td><span class="bl bl-d">69 64</span> <span class="bl bl-t">C4</span> <span class="bl bl-d">04</span></td><td>key: UTF-8 bytes; the string ends at the next byte, which cannot continue a UTF-8 character; value: 2-byte positive integer (lead byte, then a byte below 0x80)</td></tr>
<tr><td><code>&quot;name&quot;: &quot;json&quot;,</code></td><td><span class="bl bl-d">6E 61 6D 65</span> <span class="bl bl-l">FF</span> <span class="bl bl-d">6A 73 6F 6E</span> <span class="bl bl-l">FF</span></td><td>key: UTF-8 bytes; 0xFF terminates the string as another string follows; value: UTF-8 bytes; terminated as a string key follows</td></tr>
<tr><td><code>&quot;pi&quot;: 3.14,</code></td><td><span class="bl bl-d">70 69</span> <span class="bl bl-t">8F</span> <span class="bl bl-d">40 09 1E B8 51 EB 85 1F</span></td><td>key: UTF-8 bytes; value: binary64 (IEEE 754, big-endian); its marker also ends <code>&quot;pi&quot;</code></td></tr>
<tr><td><code>&quot;tags&quot;: [</code></td><td><span class="bl bl-d">74 61 67 73</span> <span class="bl bl-t">82</span></td><td>key: UTF-8 bytes; value: array with 2 elements; its marker also ends <code>&quot;tags&quot;</code></td></tr>
<tr><td><code>&quot;a&quot;,</code></td><td><span class="bl bl-d">61</span> <span class="bl bl-l">FF</span></td><td>UTF-8 bytes; terminated as a string follows</td></tr>
<tr><td><code>&quot;b&quot;</code></td><td><span class="bl bl-d">62</span> <span class="bl bl-l">FF</span></td><td>UTF-8 bytes; terminated as nothing follows</td></tr>
<tr><td><code>]</code></td><td></td><td>no end marker: the element count was given up front</td></tr>
<tr><td><code>}</code></td><td></td><td>no end marker: the member count was given up front</td></tr>
</tbody></table></div>
## Deserialization
The library maps BON8 types to JSON value types as follows:
@@ -61,6 +61,41 @@ The library uses the following mapping from JSON values types to BSON types:
```
### Byte layout
Consider the following JSON value (shown formatted for readability):
```json
{
"id": 300,
"name": "json",
"pi": 3.14,
"tags": [
"a",
"b"
]
}
```
`to_bson` encodes it to 69 bytes (shown in hexadecimal; the encoding contains no whitespace). The colors mark the role of each byte: <span class="bl bl-t">type/marker</span> <span class="bl bl-l">length/count/size</span> <span class="bl bl-d">data</span>.
<div class="byte-layout" markdown="0"><table>
<thead><tr><th>JSON</th><th>Bytes</th><th>Meaning</th></tr></thead><tbody>
<tr><td><code>{</code></td><td><span class="bl bl-l">45 00 00 00</span></td><td>document size: 69 bytes (int32, little-endian)</td></tr>
<tr><td><code>&quot;id&quot;: 300,</code></td><td><span class="bl bl-t">10</span> <span class="bl bl-d">69 64 00</span> <span class="bl bl-d">2C 01 00 00</span></td><td>int32 element; key as NUL-terminated string; value (little-endian)</td></tr>
<tr><td><code>&quot;name&quot;: &quot;json&quot;,</code></td><td><span class="bl bl-t">02</span> <span class="bl bl-d">6E 61 6D 65 00</span> <span class="bl bl-l">05 00 00 00</span> <span class="bl bl-d">6A 73 6F 6E 00</span></td><td>string element; key; length incl. NUL (int32); NUL-terminated UTF-8 bytes</td></tr>
<tr><td><code>&quot;pi&quot;: 3.14,</code></td><td><span class="bl bl-t">01</span> <span class="bl bl-d">70 69 00</span> <span class="bl bl-d">1F 85 EB 51 B8 1E 09 40</span></td><td>double element; key; value (little-endian)</td></tr>
<tr><td><code>&quot;tags&quot;: [</code></td><td><span class="bl bl-t">04</span> <span class="bl bl-d">74 61 67 73 00</span> <span class="bl bl-l">17 00 00 00</span></td><td>array element; key; embedded document of 23 bytes (keys are the indices)</td></tr>
<tr><td><code>&quot;a&quot;,</code></td><td><span class="bl bl-t">02</span> <span class="bl bl-d">30 00</span> <span class="bl bl-l">02 00 00 00</span> <span class="bl bl-d">61 00</span></td><td>string element; key <code>&quot;0&quot;</code>; length 2; <code>a</code> + NUL</td></tr>
<tr><td><code>&quot;b&quot;</code></td><td><span class="bl bl-t">02</span> <span class="bl bl-d">31 00</span> <span class="bl bl-l">02 00 00 00</span> <span class="bl bl-d">62 00</span></td><td>string element; key <code>&quot;1&quot;</code>; length 2; <code>b</code> + NUL</td></tr>
<tr><td><code>]</code></td><td><span class="bl bl-t">00</span></td><td>end of the array document</td></tr>
<tr><td><code>}</code></td><td><span class="bl bl-t">00</span></td><td>end of the document</td></tr>
</tbody></table></div>
## Deserialization
The library maps BSON record types to JSON value types as follows:
@@ -110,6 +110,41 @@ see "binary" cells in the table above.
--8<-- "examples/to_cbor.output"
```
### Byte layout
Consider the following JSON value (shown formatted for readability):
```json
{
"id": 300,
"name": "json",
"pi": 3.14,
"tags": [
"a",
"b"
]
}
```
`to_cbor` encodes it to 39 bytes (shown in hexadecimal; the encoding contains no whitespace). The colors mark the role of each byte: <span class="bl bl-t">type/marker</span> <span class="bl bl-l">length/count/size</span> <span class="bl bl-d">data</span>.
<div class="byte-layout" markdown="0"><table>
<thead><tr><th>JSON</th><th>Bytes</th><th>Meaning</th></tr></thead><tbody>
<tr><td><code>{</code></td><td><span class="bl bl-t">A4</span></td><td>map with 4 key/value pairs</td></tr>
<tr><td><code>&quot;id&quot;: 300,</code></td><td><span class="bl bl-t">62</span> <span class="bl bl-d">69 64</span> <span class="bl bl-t">19</span> <span class="bl bl-d">01 2C</span></td><td>key: text string of length 2, then its UTF-8 bytes; value: unsigned integer, 2 bytes follow (big-endian)</td></tr>
<tr><td><code>&quot;name&quot;: &quot;json&quot;,</code></td><td><span class="bl bl-t">64</span> <span class="bl bl-d">6E 61 6D 65</span> <span class="bl bl-t">64</span> <span class="bl bl-d">6A 73 6F 6E</span></td><td>key: text string of length 4; value: text string of length 4</td></tr>
<tr><td><code>&quot;pi&quot;: 3.14,</code></td><td><span class="bl bl-t">62</span> <span class="bl bl-d">70 69</span> <span class="bl bl-t">FB</span> <span class="bl bl-d">40 09 1E B8 51 EB 85 1F</span></td><td>key: text string of length 2; value: double-precision float (IEEE 754, big-endian)</td></tr>
<tr><td><code>&quot;tags&quot;: [</code></td><td><span class="bl bl-t">64</span> <span class="bl bl-d">74 61 67 73</span> <span class="bl bl-t">82</span></td><td>key: text string of length 4; value: array with 2 elements</td></tr>
<tr><td><code>&quot;a&quot;,</code></td><td><span class="bl bl-t">61</span> <span class="bl bl-d">61</span></td><td>text string of length 1</td></tr>
<tr><td><code>&quot;b&quot;</code></td><td><span class="bl bl-t">61</span> <span class="bl bl-d">62</span></td><td>text string of length 1</td></tr>
<tr><td><code>]</code></td><td></td><td>no end marker: the element count was given up front</td></tr>
<tr><td><code>}</code></td><td></td><td>no end marker: the member count was given up front</td></tr>
</tbody></table></div>
## Deserialization
The library maps CBOR types to JSON value types as follows:
@@ -45,12 +45,19 @@ See [binary values](../binary_values.md) for more information.
| BJData | 53.2 % | 91.1 % | 78.1 % | 96.6 % |
| BJData (size) | 58.6 % | 92.1 % | 86.7 % | 97.4 % |
| BJData (size+type) | 58.6 % | 92.1 % | 86.5 % | 97.4 % |
| BON8 | 50.5 % | 83.8 % | 63.5 % | 87.5 % |
| BON8 | **50.5 %** | **83.8 %** | **63.5 %** | **87.5 %** |
| BSON | 85.8 % | 95.2 % | 95.8 % | 106.7 % |
| CBOR | 50.5 % | 86.3 % | 68.4 % | 88.0 % |
| MessagePack | 50.5 % | 86.0 % | 68.5 % | 87.9 % |
| CBOR | **50.5 %** | 86.3 % | 68.4 % | 88.0 % |
| MessagePack | **50.5 %** | 86.0 % | 68.5 % | 87.9 % |
| UBJSON | 53.2 % | 91.3 % | 78.2 % | 96.6 % |
| UBJSON (size) | 58.6 % | 92.3 % | 86.8 % | 97.4 % |
| UBJSON (size+type) | 55.9 % | 92.3 % | 85.0 % | 95.0 % |
Sizes compared to minified JSON value.
Sizes compared to minified JSON value; the smallest size per file is printed in bold.
## See also
- [Binary values](../binary_values.md) - binary values and subtypes
- [**to_cbor**](../../api/basic_json/to_cbor.md) / [**from_cbor**](../../api/basic_json/from_cbor.md), [**to_msgpack**](../../api/basic_json/to_msgpack.md) / [**from_msgpack**](../../api/basic_json/from_msgpack.md), [**to_bson**](../../api/basic_json/to_bson.md) / [**from_bson**](../../api/basic_json/from_bson.md), [**to_ubjson**](../../api/basic_json/to_ubjson.md) / [**from_ubjson**](../../api/basic_json/from_ubjson.md), [**to_bjdata**](../../api/basic_json/to_bjdata.md) / [**from_bjdata**](../../api/basic_json/from_bjdata.md), [**to_bon8**](../../api/basic_json/to_bon8.md) / [**from_bon8**](../../api/basic_json/from_bon8.md) - the conversion functions
- [Parsing untrusted input](../parsing/untrusted_input.md)
- [SAX interface](../parsing/sax_interface.md) - decode binary formats without building a value
@@ -91,6 +91,41 @@ specification:
--8<-- "examples/to_msgpack.output"
```
### Byte layout
Consider the following JSON value (shown formatted for readability):
```json
{
"id": 300,
"name": "json",
"pi": 3.14,
"tags": [
"a",
"b"
]
}
```
`to_msgpack` encodes it to 39 bytes (shown in hexadecimal; the encoding contains no whitespace). The colors mark the role of each byte: <span class="bl bl-t">type/marker</span> <span class="bl bl-l">length/count/size</span> <span class="bl bl-d">data</span>.
<div class="byte-layout" markdown="0"><table>
<thead><tr><th>JSON</th><th>Bytes</th><th>Meaning</th></tr></thead><tbody>
<tr><td><code>{</code></td><td><span class="bl bl-t">84</span></td><td>map with 4 key/value pairs</td></tr>
<tr><td><code>&quot;id&quot;: 300,</code></td><td><span class="bl bl-t">A2</span> <span class="bl bl-d">69 64</span> <span class="bl bl-t">CD</span> <span class="bl bl-d">01 2C</span></td><td>key: fixstr of length 2, then its UTF-8 bytes; value: uint 16 (big-endian)</td></tr>
<tr><td><code>&quot;name&quot;: &quot;json&quot;,</code></td><td><span class="bl bl-t">A4</span> <span class="bl bl-d">6E 61 6D 65</span> <span class="bl bl-t">A4</span> <span class="bl bl-d">6A 73 6F 6E</span></td><td>key: fixstr of length 4; value: fixstr of length 4</td></tr>
<tr><td><code>&quot;pi&quot;: 3.14,</code></td><td><span class="bl bl-t">A2</span> <span class="bl bl-d">70 69</span> <span class="bl bl-t">CB</span> <span class="bl bl-d">40 09 1E B8 51 EB 85 1F</span></td><td>key: fixstr of length 2; value: float 64 (IEEE 754, big-endian)</td></tr>
<tr><td><code>&quot;tags&quot;: [</code></td><td><span class="bl bl-t">A4</span> <span class="bl bl-d">74 61 67 73</span> <span class="bl bl-t">92</span></td><td>key: fixstr of length 4; value: fixarray with 2 elements</td></tr>
<tr><td><code>&quot;a&quot;,</code></td><td><span class="bl bl-t">A1</span> <span class="bl bl-d">61</span></td><td>fixstr of length 1</td></tr>
<tr><td><code>&quot;b&quot;</code></td><td><span class="bl bl-t">A1</span> <span class="bl bl-d">62</span></td><td>fixstr of length 1</td></tr>
<tr><td><code>]</code></td><td></td><td>no end marker: the element count was given up front</td></tr>
<tr><td><code>}</code></td><td></td><td>no end marker: the member count was given up front</td></tr>
</tbody></table></div>
## Deserialization
The library maps MessagePack types to JSON value types as follows:
@@ -103,6 +103,41 @@ The library uses the following mapping from JSON values types to UBJSON types ac
--8<-- "examples/to_ubjson.output"
```
### Byte layout
Consider the following JSON value (shown formatted for readability):
```json
{
"id": 300,
"name": "json",
"pi": 3.14,
"tags": [
"a",
"b"
]
}
```
`to_ubjson` encodes it to 51 bytes (shown in hexadecimal; the encoding contains no whitespace). The colors mark the role of each byte: <span class="bl bl-t">type/marker</span> <span class="bl bl-l">length/count/size</span> <span class="bl bl-d">data</span>.
<div class="byte-layout" markdown="0"><table>
<thead><tr><th>JSON</th><th>Bytes</th><th>Meaning</th></tr></thead><tbody>
<tr><td><code>{</code></td><td><span class="bl bl-t">7B</span></td><td>object start (<code>{</code>)</td></tr>
<tr><td><code>&quot;id&quot;: 300,</code></td><td><span class="bl bl-l">69 02</span> <span class="bl bl-d">69 64</span> <span class="bl bl-t">49</span> <span class="bl bl-d">01 2C</span></td><td>key: length 2 as int8 (<code>i</code>), then UTF-8 bytes; value: int16 (<code>I</code>), big-endian</td></tr>
<tr><td><code>&quot;name&quot;: &quot;json&quot;,</code></td><td><span class="bl bl-l">69 04</span> <span class="bl bl-d">6E 61 6D 65</span> <span class="bl bl-t">53</span> <span class="bl bl-l">69 04</span> <span class="bl bl-d">6A 73 6F 6E</span></td><td>key: length 4; value: string (<code>S</code>), length 4 as int8, UTF-8 bytes</td></tr>
<tr><td><code>&quot;pi&quot;: 3.14,</code></td><td><span class="bl bl-l">69 02</span> <span class="bl bl-d">70 69</span> <span class="bl bl-t">44</span> <span class="bl bl-d">40 09 1E B8 51 EB 85 1F</span></td><td>key: length 2; value: float64 (<code>D</code>), big-endian</td></tr>
<tr><td><code>&quot;tags&quot;: [</code></td><td><span class="bl bl-l">69 04</span> <span class="bl bl-d">74 61 67 73</span> <span class="bl bl-t">5B</span></td><td>key: length 4; value: array start (<code>[</code>)</td></tr>
<tr><td><code>&quot;a&quot;,</code></td><td><span class="bl bl-t">53</span> <span class="bl bl-l">69 01</span> <span class="bl bl-d">61</span></td><td>string, length 1</td></tr>
<tr><td><code>&quot;b&quot;</code></td><td><span class="bl bl-t">53</span> <span class="bl bl-l">69 01</span> <span class="bl bl-d">62</span></td><td>string, length 1</td></tr>
<tr><td><code>]</code></td><td><span class="bl bl-t">5D</span></td><td>array end (<code>]</code>)</td></tr>
<tr><td><code>}</code></td><td><span class="bl bl-t">7D</span></td><td>object end (<code>}</code>)</td></tr>
</tbody></table></div>
## Deserialization
The library maps UBJSON types to JSON value types as follows:
@@ -21,3 +21,12 @@ flowchart TD
A --> F{"just testing first?"}
F -->|"yes"| G["contains() / find()"]
```
## See also
- [**operator[]**](../../api/basic_json/operator%5B%5D.md) - unchecked access
- [**at**](../../api/basic_json/at.md) - checked access
- [**value**](../../api/basic_json/value.md) - access with default value
- [**contains**](../../api/basic_json/contains.md) and [**find**](../../api/basic_json/find.md) - test for existence
- [**front**](../../api/basic_json/front.md) and [**back**](../../api/basic_json/back.md) - first and last element
- [**items**](../../api/basic_json/items.md) - iterate over keys and values
+8
View File
@@ -59,3 +59,11 @@ C++ types, and finally serialize it again.
This section gives conceptual overviews. For the precise signature, parameters, and return value of a function, see
the [API Documentation](../api/basic_json/index.md).
## See also
- [API documentation](../api/basic_json/index.md) - reference of all classes and functions
- [FAQ](../home/faq.md) - answers to common questions
- [Exceptions](../home/exceptions.md) - all exceptions and their error codes
- [Design goals](../home/design_goals.md)
- [Integration](../integration/index.md) - how to add the library to a project
+9
View File
@@ -286,3 +286,12 @@ This implementation does exactly follow this approach, as it uses double precisi
### Storage
Integer number values, unsigned integer number values, and floating-point number values are stored directly inside a `basic_json` type.
## See also
- [Number handling](number_handling.md) - how numbers are stored and converted
- [Template parameter requirements](template_parameters.md)
- [**basic_json**](../../api/basic_json/index.md) - the class template and its member types
- [**type**](../../api/basic_json/type.md) and [**value_t**](../../api/basic_json/value_t.md) - query the type of a value
- [**object_t**](../../api/basic_json/object_t.md), [**array_t**](../../api/basic_json/array_t.md), [**string_t**](../../api/basic_json/string_t.md), [**number_integer_t**](../../api/basic_json/number_integer_t.md), [**number_float_t**](../../api/basic_json/number_float_t.md) - the underlying types
- [Object order](../object_order.md)
+5
View File
@@ -339,6 +339,11 @@ The `serializer` (used by [`dump`](../api/basic_json/dump.md) and [`operator<<`]
- `output_stream_adapter` writes to a `std::ostream`.
- `output_string_adapter` appends to a string.
The `binary_writer` does not call an adapter for every byte. The `to_*` functions that return a `std::vector` write
into the vector through a sink (`output_vector_sink`) that is not virtual. The functions that take an output adapter
write through a sink (`output_adapter_sink`) that collects the output in a buffer of one kibibyte and passes it to the
adapter in blocks, so that the adapter is called (and a stream locked) once per block instead of once per value.
## Value conversion
Values are converted from and to other types with the `JSONSerializer` template parameter. The default,
-453
View File
@@ -1,453 +0,0 @@
# Releases
This page summarizes the notable changes of every release and links to the relevant documentation.
The **complete release notes** — including all changes, the download files, and their checksums — are
published on the [GitHub releases page](https://github.com/nlohmann/json/releases).
!!! 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.
## Unreleased
- Converting an rvalue container to JSON (`json j = std::move(vec);`, `json j = std::map<std::string, std::string>{...};`)
now **moves** the elements instead of copying them (e.g., `std::vector<std::string>` with 100,000 strings: 4.7 ms to
2.3 ms). Two consequences: the source container is left in a valid but unspecified (moved-from) state, and if an
exception is thrown during the conversion, the source may be partially moved-from, so the strong exception guarantee
no longer holds for the source of an rvalue conversion (the JSON value itself is unaffected). Lvalues and `const`
objects are still copied. See [`basic_json`](../api/basic_json/basic_json.md).
## v3.12.0 (2025-04-11)
Fixes bugs found in 3.11.3 and adds several features. All changes are backward-compatible.
- Adds diagnostic byte positions via [`JSON_DIAGNOSTIC_POSITIONS`](../api/macros/json_diagnostic_positions.md),
exposed through the new [`start_pos`](../api/basic_json/start_pos.md) and
[`end_pos`](../api/basic_json/end_pos.md) member functions.
- Makes the [conversion macros](../features/arbitrary_types.md#simplify-your-life-with-macros)
templated (so they also work with [`ordered_json`](../api/ordered_json.md)) and adds
[`NLOHMANN_DEFINE_DERIVED_TYPE`](../api/macros/nlohmann_define_derived_type.md) for derived classes.
- Adds `std::optional` support (C++17) and lets [`patch`](../api/basic_json/patch.md),
[`diff`](../api/basic_json/diff.md), and [`flatten`](../api/basic_json/flatten.md) work with
arbitrary string types.
- Extends the [binary formats](../features/binary_formats/index.md):
[BJData](../features/binary_formats/bjdata.md) draft 3 and unsigned 64-bit integers for
[BSON](../features/binary_formats/bson.md).
- Adds multidimensional C-array conversion and UTF-8 encoded `std::filesystem::path` conversions, and
raises the minimum [CMake](../integration/cmake.md) version to 3.5 and supports CMake 4.0.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.12.0).
## v3.11.3 (2023-11-28)
Adds features and fixes bugs found in 3.11.2. All changes are backward-compatible.
- Adds a [custom base class](../api/basic_json/json_base_class_t.md) as a node customization point.
- Adds serialization-only [conversion macros](../features/macros.md)
(`NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE` and `NLOHMANN_DEFINE_TYPE_INTRUSIVE_ONLY_SERIALIZE`)
and a clearer parse error for empty input.
- Adds [Bazel](../integration/package_managers.md#bazel) and
[Swift Package Manager](../integration/package_managers.md#swift-package-manager) build support.
- Fixes custom allocators, a memory leak in [`adl_serializer`](../api/adl_serializer/to_json.md)'s
`to_json`, initializer-list construction when `size_type` is not `int`, and many compiler warnings.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.11.3).
## v3.11.2 (2022-08-12)
Fixes bugs found in 3.11.1 and restructures the namespace. All changes are backward-compatible.
- Fixes the [`value`](../api/basic_json/value.md) function (broken for strings, size types, and
`nullptr` in 3.11.0) and makes `json_fwd.hpp` self-contained.
- Restores using [`json_pointer`](../api/json_pointer/index.md) as a key in associative containers and
comparing it with strings.
- Restructures the inline [namespace](../features/namespace.md) and allows disabling the version
component, and avoids heap allocations in the [BJData](../features/binary_formats/bjdata.md) parser.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.11.2).
## v3.11.1 (2022-08-01)
Fixes a regression from 3.11.0. All changes are backward-compatible.
- Restores the global [user-defined string literals](../api/macros/json_use_global_udls.md)
[`operator""_json`](../api/operator_literal_json.md) and
[`operator""_json_pointer`](../api/operator_literal_json_pointer.md), which 3.11.0 had moved into a
namespace by default.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.11.1).
## v3.11.0 (2022-08-01)
One of the largest releases ever. All changes are backward-compatible.
- Allows `std::string_view` as object keys in [`at`](../api/basic_json/at.md),
[`operator[]`](../api/basic_json/operator%5B%5D.md), [`value`](../api/basic_json/value.md),
[`erase`](../api/basic_json/erase.md), [`find`](../api/basic_json/find.md),
[`contains`](../api/basic_json/contains.md), and [`count`](../api/basic_json/count.md).
- Adds the [BJData](../features/binary_formats/bjdata.md) binary format (the fifth supported format).
- Improves C++20 support, including [`operator<=>`](../api/basic_json/operator_spaceship.md) and
`<ranges>`-compatible iterators.
- Adds a versioned, ABI-tagged inline [namespace](../features/namespace.md)
([`NLOHMANN_JSON_NAMESPACE`](../api/macros/nlohmann_json_namespace.md)) and the option to move the
UDLs out of the global namespace ([`JSON_USE_GLOBAL_UDLS`](../api/macros/json_use_global_udls.md)).
- Adds [`patch_inplace`](../api/basic_json/patch_inplace.md), default values for the
[conversion macros](../features/arbitrary_types.md#simplify-your-life-with-macros), and an option to
disable enum serialization ([`JSON_DISABLE_ENUM_SERIALIZATION`](../api/macros/json_disable_enum_serialization.md)).
This release introduced a UDL regression that was fixed in
[3.11.1](https://github.com/nlohmann/json/releases/tag/v3.11.1).
[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.11.0).
## v3.10.5 (2022-01-03)
Bug-fix release. All changes are backward-compatible.
- Guards the `std::filesystem` conversions behind compiler-support checks
([`JSON_HAS_FILESYSTEM`](../api/macros/json_has_filesystem.md)), which can be set to `0` to disable
them altogether.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.10.5).
## v3.10.4 (2021-10-16)
Fixes regressions introduced in 3.10.0. All changes are backward-compatible.
- Fixes the `std::filesystem::path` conversion (which could trigger a stack overflow and broke
compilation on Windows).
- Fixes compilation for types with an explicit defaulted constructor and for code relying on the
return values of `std::find` and `std::remove`.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.10.4).
## v3.10.3 (2021-10-08)
Fixes more regressions from 3.10.0. All changes are backward-compatible.
- Fixes [extended-diagnostics](../api/macros/json_diagnostics.md) assertions triggered by
[`update`](../api/basic_json/update.md) and by inserting into arrays.
- Supports custom allocators when writing binary formats into a `std::vector`, and allows conversion
from types that only provide `begin()`/`end()`.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.10.3).
## v3.10.2 (2021-08-26)
Re-release of 3.10.1, whose Git tag pointed at the wrong commit due to a bug in the release script.
All changes are backward-compatible.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.10.2).
## v3.10.1 (2021-08-24)
Fixes a regression from 3.10.0. All changes are backward-compatible.
- Fixes an [extended-diagnostics](../api/macros/json_diagnostics.md) assertion triggered when used
with [`ordered_json`](../api/ordered_json.md), and hardens the GDB pretty-printer.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.10.1).
## v3.10.0 (2021-08-17)
Feature release. All changes are backward-compatible.
- Adds [extended diagnostic messages](../api/macros/json_diagnostics.md)
([`JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md)) that prepend a JSON pointer to exception
messages to pinpoint the offending value.
- Adds a GDB pretty-printer and a [`cbor_tag_handler_t`](../api/basic_json/cbor_tag_handler_t.md)
`store` option to keep CBOR tags as binary subtypes.
- Supports containers with non-default-constructible types and parsing from `std::byte`.
- Adds [`JSON_NO_IO`](../api/macros/json_no_io.md) to exclude the I/O headers and the
[`JSON_HAS_CPP_*`](../api/macros/json_has_cpp_11.md) macros to override the detected C++ standard.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.10.0).
## v3.9.1 (2020-08-06)
Fixes two regressions from 3.9.0. All changes are backward-compatible.
- Accepts consecutive [comments](../features/comments.md) and completes the
[`ordered_json`](../api/ordered_json.md) interface (e.g. `ordered_json::parse`).
[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.9.1).
## v3.9.0 (2020-07-27)
Feature release adding four long-requested features. All changes are backward-compatible.
- Optional [comment](../features/comments.md) parsing in [`parse`](../api/basic_json/parse.md) via the
`ignore_comments` parameter.
- [`ordered_json`](../api/ordered_json.md) to preserve the [insertion order](../features/object_order.md)
of object keys.
- An option to switch off [implicit conversions](../api/macros/json_use_implicit_conversions.md).
- The [`NLOHMANN_DEFINE_TYPE_*`](../features/arbitrary_types.md#simplify-your-life-with-macros)
convenience macros, plus high-precision-number support for
[UBJSON](../features/binary_formats/ubjson.md) and CBOR tag handling.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.9.0).
## v3.8.0 (2020-06-14)
Feature release. All changes are backward-compatible.
- Introduces a [binary value](../features/binary_values.md) type that is read from and written to
[CBOR](../features/binary_formats/cbor.md), [BSON](../features/binary_formats/bson.md), and
[MessagePack](../features/binary_formats/messagepack.md), and can be shared between formats.
- Generalizes the input adapters to read from any `LegacyInputIterator` container (3–10 % faster
parsing).
- Fixes [`contains`](../api/basic_json/contains.md) for JSON pointers and makes the binary
[`from_cbor`](../api/basic_json/from_cbor.md)/[`from_msgpack`](../api/basic_json/from_msgpack.md)/etc.
functions respect `allow_exceptions`.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.8.0).
## v3.7.3 (2019-11-17)
Fixes a regression from 3.7.2 that could yield quadratic complexity in destructor calls. All changes
are backward-compatible. [Full release notes](https://github.com/nlohmann/json/releases/tag/v3.7.3).
## v3.7.2 (2019-11-10)
Fixes a stack overflow for deeply nested input by making the destructor iterative; parsing is now
bounded only by available memory. All changes are backward-compatible.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.7.2).
## v3.7.1 (2019-11-06)
Bug-fix release. All changes are backward-compatible.
- Fixes a segmentation fault when serializing the `std::int64_t` minimum value and fixes
[`contains`](../api/basic_json/contains.md) for JSON pointers.
- Allows [`items`](../api/basic_json/items.md) with a custom string type and makes `json_pointer::back`
`const`.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.7.1).
## v3.7.0 (2019-07-28)
Convenience features and house-keeping. All changes are backward-compatible.
- Adds a [`contains`](../api/basic_json/contains.md) overload that checks a JSON pointer without
throwing, a generic `to_string`, and a return value for
[`emplace_back`](../api/basic_json/emplace_back.md).
[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.7.0).
## v3.6.1 (2019-03-20)
Fixes a regression (GCC 7/8 compilation) and a `<Windows.h>` build error introduced in 3.6.0. All
changes are backward-compatible. [Full release notes](https://github.com/nlohmann/json/releases/tag/v3.6.1).
## v3.6.0 (2019-03-20)
Feature release. All changes are backward-compatible.
- Reworks the [JSON pointer](../features/json_pointer.md) interface (`operator/`, `push_back`,
`parent_pointer`, …).
- Adds a [`contains`](../api/basic_json/contains.md) function to test for an object key and greatly
improves the performance of integer serialization.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.6.0).
## v3.5.0 (2018-12-22)
Feature release. All changes are backward-compatible.
- Adds structured-binding support via the [`items`](../api/basic_json/items.md) function and reading
from `FILE*` in the [`parse`](../api/basic_json/parse.md) function.
- Fixes the `eofbit` handling on input streams and a bug in the BSON SAX parser.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.5.0).
## v3.4.0 (2018-10-30)
Feature release. All changes are backward-compatible.
- Adds [BSON](../features/binary_formats/bson.md) read/write support.
- Adds configurable Unicode error handlers to [`dump`](../api/basic_json/dump.md) (throw, replace with
U+FFFD, or ignore) and the
[`NLOHMANN_JSON_SERIALIZE_ENUM`](../api/macros/nlohmann_json_serialize_enum.md) macro for
[enum conversion](../features/enum_conversion.md).
- Improves parse-error messages with line/column positions and context.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.4.0).
## v3.3.0 (2018-10-05)
Feature release. All changes are backward-compatible.
- Adds GCC 4.8 support, the [`get_to`](../api/basic_json/get_to.md) function, and an overhauled and
documented [CMake](../integration/cmake.md) integration.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.3.0).
## v3.2.0 (2018-08-20)
Feature release. All changes are backward-compatible.
- Adds a [SAX interface](../features/parsing/sax_interface.md) and a non-recursive parser.
- Adds parsing from wide-string types (`std::wstring`, `std::u16string`, `std::u32string`) and
`std::string_view` (C++17), and round-tripping of `std::map`/`std::unordered_map` with non-string
keys.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.2.0).
## v3.1.2 (2018-03-14)
Bug-fix release. All changes are backward-compatible.
- Fixes a memory leak in the parser callback and adds user-defined string-type support to the parser
and serializer.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.1.2).
## v3.1.1 (2018-02-13)
Bug-fix release. All changes are backward-compatible.
- Fixes parsing of indefinite-length CBOR strings, a user-defined conversion to vector types, and
overflow detection for UBJSON containers.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.1.1).
## v3.1.0 (2018-02-01)
Feature release. All changes are backward-compatible.
- Adds [UBJSON](../features/binary_formats/ubjson.md) read/write support and
[JSON Merge Patch](../features/merge_patch.md) via [`merge_patch`](../api/basic_json/merge_patch.md).
- Switches to the Grisu2 algorithm for short, round-trippable floating-point output, and splits the
header into [multiple files](../integration/index.md) with a forward-declaration header.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.1.0).
## v3.0.1 (2017-12-29)
Fixes small issues in the [JSON Pointer](../features/json_pointer.md) and
[JSON Patch](../features/json_patch.md) implementations (invalid "copy" targets and non-integer array
indices). All changes are backward-compatible.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.0.1).
## v3.0.0 (2017-12-17)
First 3.x release — a major release with breaking changes (see the
[migration guide](../integration/migration_guide.md)).
- Introduces user-defined [exceptions](exceptions.md) (`json::exception` and subtypes, each with an
identifier).
- Adds a non-throwing [`accept`](../api/basic_json/accept.md) function and an `allow_exceptions` flag
for [`parse`](../api/basic_json/parse.md), and an [`update`](../api/basic_json/update.md) function to
merge objects.
- Adds streaming for CBOR and MessagePack and allows storing NaN/infinity.
- Non-UTF-8 strings now throw on serialization, and the iterator category changed to bidirectional.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.0.0).
## v2.1.1 (2017-02-25)
Bug-fix release. All changes are backward-compatible.
- Makes number parsing and serialization locale-independent with correct floating-point
round-tripping; released files are now GPG-signed.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.1.1).
## v2.1.0 (2017-01-28)
Feature release. All changes are backward-compatible.
- Adds conversions from and to [arbitrary user-defined types](../features/arbitrary_types.md) via
`to_json`/`from_json`, the [`meta`](../api/basic_json/meta.md) function, and the option to switch off
exceptions ([`JSON_NOEXCEPTION`](../api/macros/json_noexception.md)).
[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.1.0).
## v2.0.10 (2017-01-02)
Fixes several security-relevant bugs in the CBOR and MessagePack parsers found by OSS-Fuzz. All
changes are backward-compatible. [Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.10).
## v2.0.9 (2016-12-16)
Adds the [CBOR](../features/binary_formats/cbor.md) and
[MessagePack](../features/binary_formats/messagepack.md) binary formats. All changes are
backward-compatible. [Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.9).
## v2.0.8 (2016-12-02)
Adds the [`emplace`](../api/basic_json/emplace.md) and
[`emplace_back`](../api/basic_json/emplace_back.md) functions and improves parsing and serialization
performance. All changes are backward-compatible.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.8).
## v2.0.7 (2016-11-02)
Fixes several parser bugs found through the "Parsing JSON is a Minefield" study (short files, encoding
detection, surrogate pairs). All changes are backward-compatible.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.7).
## v2.0.6 (2016-10-15)
Fixes [`operator[]`](../api/basic_json/operator%5B%5D.md) for [JSON pointers](../features/json_pointer.md)
so that it creates missing values like the other overloads. All changes are backward-compatible.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.6).
## v2.0.5 (2016-09-14)
Fixes a remaining stream end-of-file detection bug in the parser. All changes are backward-compatible.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.5).
## v2.0.4 (2016-09-11)
Fixes stream end-of-file detection in the parser. All changes are backward-compatible.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.4).
## v2.0.3 (2016-08-31)
Generalizes the parser to accept any contiguous sequence of one-byte elements and deprecates the
input-stream constructor in favor of the [`parse`](../api/basic_json/parse.md) function. All changes
are backward-compatible. [Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.3).
## v2.0.2 (2016-07-31)
Overhauls the parser (now rejecting unescaped control characters), tightens the class invariants, and
cleans up the code. All changes are backward-compatible.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.2).
## v2.0.1 (2016-06-28)
Fixes a performance regression in the [`dump`](../api/basic_json/dump.md) function by adjusting the
stream locale once per serialization. All changes are backward-compatible.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.1).
## v2.0.0 (2016-06-24)
Feature release with a minor (potentially non-backward-compatible) API change from added `noexcept`
and `constexpr` specifiers.
- Adds [JSON Pointer](../features/json_pointer.md) support in [`at`](../api/basic_json/at.md) and
[`operator[]`](../api/basic_json/operator%5B%5D.md), plus [`flatten`](../api/basic_json/flatten.md)
and [`unflatten`](../api/basic_json/unflatten.md).
- Adds [JSON Patch](../features/json_patch.md) via [`diff`](../api/basic_json/diff.md) and
[`patch`](../api/basic_json/patch.md), unsigned 64-bit integer support, and locale-independent
serialization.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.0).
## v1.1.0 (2016-01-24)
Bug-fix and feature release. All changes are backward-compatible.
- Improves floating-point round-tripping, adds a `get_ref` accessor for stored values, and introduces
runtime [assertions](../features/assertions.md).
[Full release notes](https://github.com/nlohmann/json/releases/tag/v1.1.0).
## v1.0.0 (2015-12-28)
First official release. [Full release notes](https://github.com/nlohmann/json/releases/tag/v1.0.0).
## See also
- [Migration Guide](../integration/migration_guide.md) — how to future-proof your code for the next
major version and replace deprecated functions.
+155
View File
@@ -0,0 +1,155 @@
# Releases
This section summarizes the notable changes of every release and links to the relevant documentation.
The **complete release notes** — including all changes, the download files, and their checksums — are
published on the [GitHub releases page](https://github.com/nlohmann/json/releases).
!!! 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.
Every release has its own page with a summary of its notable changes and an overview of the API that was added or
changed in it. The API overview is generated from the "Version history" section of the
[API pages](../../api/basic_json/index.md); it is not a change log, but helps to see whether a feature is available in
the version you use.
## Unreleased
| Release | Date | Summary |
|---------|------|---------|
| [Unreleased](unreleased.md) | | Changes on the `develop` branch that are not part of a release yet. |
## Version 3.12.x
| Release | Date | Summary |
|---------|------|---------|
| [v3.12.0](v3.12.0.md) | 2025-04-11 | Fixes bugs found in 3.11.3 and adds several features. No public API was removed or renamed. |
## Version 3.11.x
| Release | Date | Summary |
|---------|------|---------|
| [v3.11.3](v3.11.3.md) | 2023-11-28 | Adds features and fixes bugs found in 3.11.2. All changes are backward-compatible. |
| [v3.11.2](v3.11.2.md) | 2022-08-12 | Fixes bugs found in 3.11.1 and restructures the namespace. All changes are backward-compatible. |
| [v3.11.1](v3.11.1.md) | 2022-08-01 | Fixes a regression from 3.11.0. All changes are backward-compatible. |
| [v3.11.0](v3.11.0.md) | 2022-08-01 | One of the largest releases ever. All changes are backward-compatible. |
## Version 3.10.x
| Release | Date | Summary |
|---------|------|---------|
| [v3.10.5](v3.10.5.md) | 2022-01-03 | Bug-fix release. All changes are backward-compatible. |
| [v3.10.4](v3.10.4.md) | 2021-10-16 | Fixes regressions introduced in 3.10.0. All changes are backward-compatible. |
| [v3.10.3](v3.10.3.md) | 2021-10-08 | Fixes more regressions from 3.10.0. All changes are backward-compatible. |
| [v3.10.2](v3.10.2.md) | 2021-08-26 | Re-release of 3.10.1, whose Git tag pointed at the wrong commit due to a bug in the release script. All changes are backward-compatible. |
| [v3.10.1](v3.10.1.md) | 2021-08-24 | Fixes a regression from 3.10.0. All changes are backward-compatible. |
| [v3.10.0](v3.10.0.md) | 2021-08-17 | Feature release. All changes are backward-compatible. |
## Version 3.9.x
| Release | Date | Summary |
|---------|------|---------|
| [v3.9.1](v3.9.1.md) | 2020-08-06 | Fixes two regressions from 3.9.0. All changes are backward-compatible. |
| [v3.9.0](v3.9.0.md) | 2020-07-27 | Feature release adding four long-requested features. All changes are backward-compatible. |
## Version 3.8.x
| Release | Date | Summary |
|---------|------|---------|
| [v3.8.0](v3.8.0.md) | 2020-06-14 | Feature release. All changes are backward-compatible. |
## Version 3.7.x
| Release | Date | Summary |
|---------|------|---------|
| [v3.7.3](v3.7.3.md) | 2019-11-17 | Fixes a regression from 3.7.2 that could yield quadratic complexity in destructor calls. All changes are backward-compatible. |
| [v3.7.2](v3.7.2.md) | 2019-11-10 | Fixes a stack overflow for deeply nested input by making the destructor iterative; parsing of JSON text is now bounded only by available memory (the binary-format parsers still recurse). All changes are backward-compatible. |
| [v3.7.1](v3.7.1.md) | 2019-11-06 | Bug-fix release. All changes are backward-compatible. |
| [v3.7.0](v3.7.0.md) | 2019-07-28 | Convenience features and house-keeping. All changes are backward-compatible. |
## Version 3.6.x
| Release | Date | Summary |
|---------|------|---------|
| [v3.6.1](v3.6.1.md) | 2019-03-20 | Fixes a regression (GCC 7/8 compilation) and a `<Windows.h>` build error introduced in 3.6.0. All changes are backward-compatible. |
| [v3.6.0](v3.6.0.md) | 2019-03-20 | Feature release. All changes are backward-compatible. |
## Version 3.5.x
| Release | Date | Summary |
|---------|------|---------|
| [v3.5.0](v3.5.0.md) | 2018-12-22 | Feature release. All changes are backward-compatible. |
## Version 3.4.x
| Release | Date | Summary |
|---------|------|---------|
| [v3.4.0](v3.4.0.md) | 2018-10-30 | Feature release. All changes are backward-compatible. |
## Version 3.3.x
| Release | Date | Summary |
|---------|------|---------|
| [v3.3.0](v3.3.0.md) | 2018-10-05 | Feature release. All changes are backward-compatible. |
## Version 3.2.x
| Release | Date | Summary |
|---------|------|---------|
| [v3.2.0](v3.2.0.md) | 2018-08-20 | Feature release. All changes are backward-compatible. |
## Version 3.1.x
| Release | Date | Summary |
|---------|------|---------|
| [v3.1.2](v3.1.2.md) | 2018-03-14 | Bug-fix release. All changes are backward-compatible. |
| [v3.1.1](v3.1.1.md) | 2018-02-13 | Bug-fix release. All changes are backward-compatible. |
| [v3.1.0](v3.1.0.md) | 2018-02-01 | Feature release. All changes are backward-compatible. |
## Version 3.0.x
| Release | Date | Summary |
|---------|------|---------|
| [v3.0.1](v3.0.1.md) | 2017-12-29 | Fixes small issues in the [JSON Pointer](../../features/json_pointer.md) and [JSON Patch](../../features/json_patch.md) implementations (invalid "copy" targets and non-integer array indices). All changes are backward-compatible. |
| [v3.0.0](v3.0.0.md) | 2017-12-17 | First 3.x release — a major release with breaking changes (see the [migration guide](../../integration/migration_guide.md)). |
## Version 2.1.x
| Release | Date | Summary |
|---------|------|---------|
| [v2.1.1](v2.1.1.md) | 2017-02-25 | Bug-fix release. All changes are backward-compatible. |
| [v2.1.0](v2.1.0.md) | 2017-01-28 | Feature release. All changes are backward-compatible. |
## Version 2.0.x
| Release | Date | Summary |
|---------|------|---------|
| [v2.0.10](v2.0.10.md) | 2017-01-02 | Fixes several security-relevant bugs in the CBOR and MessagePack parsers found by OSS-Fuzz. All changes are backward-compatible. |
| [v2.0.9](v2.0.9.md) | 2016-12-16 | Adds the [CBOR](../../features/binary_formats/cbor.md) and [MessagePack](../../features/binary_formats/messagepack.md) binary formats. All changes are backward-compatible. |
| [v2.0.8](v2.0.8.md) | 2016-12-02 | Adds the [`emplace`](../../api/basic_json/emplace.md) and [`emplace_back`](../../api/basic_json/emplace_back.md) functions and improves parsing and serialization performance. All changes are backward-compatible. |
| [v2.0.7](v2.0.7.md) | 2016-11-02 | Fixes several parser bugs found through the "Parsing JSON is a Minefield" study (short files, encoding detection, surrogate pairs). All changes are backward-compatible. |
| [v2.0.6](v2.0.6.md) | 2016-10-15 | Fixes [`operator[]`](../../api/basic_json/operator%5B%5D.md) for [JSON pointers](../../features/json_pointer.md) so that it creates missing values like the other overloads. All changes are backward-compatible. |
| [v2.0.5](v2.0.5.md) | 2016-09-14 | Fixes a remaining stream end-of-file detection bug in the parser. All changes are backward-compatible. |
| [v2.0.4](v2.0.4.md) | 2016-09-11 | Fixes stream end-of-file detection in the parser. All changes are backward-compatible. |
| [v2.0.3](v2.0.3.md) | 2016-08-31 | Generalizes the parser to accept any contiguous sequence of one-byte elements and deprecates the input-stream constructor in favor of the [`parse`](../../api/basic_json/parse.md) function. All changes are backward-compatible. |
| [v2.0.2](v2.0.2.md) | 2016-07-31 | Overhauls the parser (now rejecting unescaped control characters), tightens the class invariants, and cleans up the code. All changes are backward-compatible. |
| [v2.0.1](v2.0.1.md) | 2016-06-28 | Fixes a performance regression in the [`dump`](../../api/basic_json/dump.md) function by adjusting the stream locale once per serialization. All changes are backward-compatible. |
| [v2.0.0](v2.0.0.md) | 2016-06-24 | Feature release with a minor (potentially non-backward-compatible) API change from added `noexcept` and `constexpr` specifiers. |
## Version 1.1.x
| Release | Date | Summary |
|---------|------|---------|
| [v1.1.0](v1.1.0.md) | 2016-01-24 | Bug-fix and feature release. All changes are backward-compatible. |
## Version 1.0.x
| Release | Date | Summary |
|---------|------|---------|
| [v1.0.0](v1.0.0.md) | 2015-12-28 | First official release. |
## See also
- [Migration Guide](../../integration/migration_guide.md) — how to future-proof your code for the next
major version and replace deprecated functions.
@@ -0,0 +1,14 @@
# Unreleased
These changes are part of the `develop` branch, but not of a release yet.
- Converting an rvalue container to JSON (`json j = std::move(vec);`, `json j = std::map<std::string, std::string>{...};`)
now **moves** the elements instead of copying them (e.g., `std::vector<std::string>` with 100,000 strings: 4.7 ms to
2.3 ms). Two consequences: the source container is left in a valid but unspecified (moved-from) state, and if an
exception is thrown during the conversion, the source may be partially moved-from, so the strong exception guarantee
no longer holds for the source of an rvalue conversion (the JSON value itself is unaffected). Lvalues and `const`
objects are still copied. See [`basic_json`](../../api/basic_json/basic_json.md).
## API changes
<!-- api-changes -->
+9
View File
@@ -0,0 +1,9 @@
# v1.0.0
Released on 2015-12-28.
First official release. [Full release notes](https://github.com/nlohmann/json/releases/tag/v1.0.0).
## API changes
<!-- api-changes -->
+14
View File
@@ -0,0 +1,14 @@
# v1.1.0
Released on 2016-01-24.
Bug-fix and feature release. All changes are backward-compatible.
- Improves floating-point round-tripping, adds a `get_ref` accessor for stored values, and introduces
runtime [assertions](../../features/assertions.md).
[Full release notes](https://github.com/nlohmann/json/releases/tag/v1.1.0).
## API changes
<!-- api-changes -->
+19
View File
@@ -0,0 +1,19 @@
# v2.0.0
Released on 2016-06-24.
Feature release with a minor (potentially non-backward-compatible) API change from added `noexcept`
and `constexpr` specifiers.
- Adds [JSON Pointer](../../features/json_pointer.md) support in [`at`](../../api/basic_json/at.md) and
[`operator[]`](../../api/basic_json/operator%5B%5D.md), plus [`flatten`](../../api/basic_json/flatten.md)
and [`unflatten`](../../api/basic_json/unflatten.md).
- Adds [JSON Patch](../../features/json_patch.md) via [`diff`](../../api/basic_json/diff.md) and
[`patch`](../../api/basic_json/patch.md), unsigned 64-bit integer support, and locale-independent
serialization.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.0).
## API changes
<!-- api-changes -->
+11
View File
@@ -0,0 +1,11 @@
# v2.0.1
Released on 2016-06-28.
Fixes a performance regression in the [`dump`](../../api/basic_json/dump.md) function by adjusting the
stream locale once per serialization. All changes are backward-compatible.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.1).
## API changes
<!-- api-changes -->
+10
View File
@@ -0,0 +1,10 @@
# v2.0.10
Released on 2017-01-02.
Fixes several security-relevant bugs in the CBOR and MessagePack parsers found by OSS-Fuzz. All
changes are backward-compatible. [Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.10).
## API changes
<!-- api-changes -->
+11
View File
@@ -0,0 +1,11 @@
# v2.0.2
Released on 2016-07-31.
Overhauls the parser (now rejecting unescaped control characters), tightens the class invariants, and
cleans up the code. All changes are backward-compatible.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.2).
## API changes
<!-- api-changes -->
+11
View File
@@ -0,0 +1,11 @@
# v2.0.3
Released on 2016-08-31.
Generalizes the parser to accept any contiguous sequence of one-byte elements and deprecates the
input-stream constructor in favor of the [`parse`](../../api/basic_json/parse.md) function. All changes
are backward-compatible. [Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.3).
## API changes
<!-- api-changes -->
+10
View File
@@ -0,0 +1,10 @@
# v2.0.4
Released on 2016-09-11.
Fixes stream end-of-file detection in the parser. All changes are backward-compatible.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.4).
## API changes
<!-- api-changes -->
+10
View File
@@ -0,0 +1,10 @@
# v2.0.5
Released on 2016-09-14.
Fixes a remaining stream end-of-file detection bug in the parser. All changes are backward-compatible.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.5).
## API changes
<!-- api-changes -->
+11
View File
@@ -0,0 +1,11 @@
# v2.0.6
Released on 2016-10-15.
Fixes [`operator[]`](../../api/basic_json/operator%5B%5D.md) for [JSON pointers](../../features/json_pointer.md)
so that it creates missing values like the other overloads. All changes are backward-compatible.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.6).
## API changes
<!-- api-changes -->
+11
View File
@@ -0,0 +1,11 @@
# v2.0.7
Released on 2016-11-02.
Fixes several parser bugs found through the "Parsing JSON is a Minefield" study (short files, encoding
detection, surrogate pairs). All changes are backward-compatible.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.7).
## API changes
<!-- api-changes -->
+12
View File
@@ -0,0 +1,12 @@
# v2.0.8
Released on 2016-12-02.
Adds the [`emplace`](../../api/basic_json/emplace.md) and
[`emplace_back`](../../api/basic_json/emplace_back.md) functions and improves parsing and serialization
performance. All changes are backward-compatible.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.8).
## API changes
<!-- api-changes -->
+11
View File
@@ -0,0 +1,11 @@
# v2.0.9
Released on 2016-12-16.
Adds the [CBOR](../../features/binary_formats/cbor.md) and
[MessagePack](../../features/binary_formats/messagepack.md) binary formats. All changes are
backward-compatible. [Full release notes](https://github.com/nlohmann/json/releases/tag/v2.0.9).
## API changes
<!-- api-changes -->
+15
View File
@@ -0,0 +1,15 @@
# v2.1.0
Released on 2017-01-28.
Feature release. All changes are backward-compatible.
- Adds conversions from and to [arbitrary user-defined types](../../features/arbitrary_types.md) via
`to_json`/`from_json`, the [`meta`](../../api/basic_json/meta.md) function, and the option to switch off
exceptions ([`JSON_NOEXCEPTION`](../../api/macros/json_noexception.md)).
[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.1.0).
## API changes
<!-- api-changes -->
+14
View File
@@ -0,0 +1,14 @@
# v2.1.1
Released on 2017-02-25.
Bug-fix release. All changes are backward-compatible.
- Makes number parsing and serialization locale-independent with correct floating-point
round-tripping; commits and released files are GPG-signed.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v2.1.1).
## API changes
<!-- api-changes -->
+20
View File
@@ -0,0 +1,20 @@
# v3.0.0
Released on 2017-12-17.
First 3.x release — a major release with breaking changes (see the
[migration guide](../../integration/migration_guide.md)).
- Introduces user-defined [exceptions](../exceptions.md) (`json::exception` and subtypes, each with an
identifier).
- Adds a non-throwing [`accept`](../../api/basic_json/accept.md) function and an `allow_exceptions` flag
for [`parse`](../../api/basic_json/parse.md), and an [`update`](../../api/basic_json/update.md) function to
merge objects.
- Adds streaming for CBOR and MessagePack and allows storing NaN/infinity.
- Non-UTF-8 strings now throw on serialization, and the iterator category changed to bidirectional.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.0.0).
## API changes
<!-- api-changes -->
+12
View File
@@ -0,0 +1,12 @@
# v3.0.1
Released on 2017-12-29.
Fixes small issues in the [JSON Pointer](../../features/json_pointer.md) and
[JSON Patch](../../features/json_patch.md) implementations (invalid "copy" targets and non-integer array
indices). All changes are backward-compatible.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.0.1).
## API changes
<!-- api-changes -->
+16
View File
@@ -0,0 +1,16 @@
# v3.1.0
Released on 2018-02-01.
Feature release. All changes are backward-compatible.
- Adds [UBJSON](../../features/binary_formats/ubjson.md) read/write support and
[JSON Merge Patch](../../features/merge_patch.md) via [`merge_patch`](../../api/basic_json/merge_patch.md).
- Switches to the Grisu2 algorithm for short, round-trippable floating-point output, and splits the
header into [multiple files](../../integration/index.md) with a forward-declaration header.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.1.0).
## API changes
<!-- api-changes -->
+14
View File
@@ -0,0 +1,14 @@
# v3.1.1
Released on 2018-02-13.
Bug-fix release. All changes are backward-compatible.
- Fixes parsing of indefinite-length CBOR strings, a user-defined conversion to vector types, and
overflow detection for UBJSON containers.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.1.1).
## API changes
<!-- api-changes -->
+14
View File
@@ -0,0 +1,14 @@
# v3.1.2
Released on 2018-03-14.
Bug-fix release. All changes are backward-compatible.
- Fixes a memory leak in the parser callback and adds user-defined string-type support to the parser
and serializer.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.1.2).
## API changes
<!-- api-changes -->
+20
View File
@@ -0,0 +1,20 @@
# v3.10.0
Released on 2021-08-17.
Feature release. All changes are backward-compatible.
- Adds [extended diagnostic messages](../../api/macros/json_diagnostics.md)
([`JSON_DIAGNOSTICS`](../../api/macros/json_diagnostics.md)) that prepend a JSON pointer to exception
messages to pinpoint the offending value.
- Adds a GDB pretty-printer and a [`cbor_tag_handler_t`](../../api/basic_json/cbor_tag_handler_t.md)
`store` option to keep CBOR tags as binary subtypes.
- Supports containers with non-default-constructible types and parsing from `std::byte`.
- Adds [`JSON_NO_IO`](../../api/macros/json_no_io.md) to exclude the I/O headers and the
[`JSON_HAS_CPP_*`](../../api/macros/json_has_cpp_11.md) macros to override the detected C++ standard.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.10.0).
## API changes
<!-- api-changes -->
+14
View File
@@ -0,0 +1,14 @@
# v3.10.1
Released on 2021-08-24.
Fixes a regression from 3.10.0. All changes are backward-compatible.
- Fixes an [extended-diagnostics](../../api/macros/json_diagnostics.md) assertion triggered when used
with [`ordered_json`](../../api/ordered_json.md), and hardens the GDB pretty-printer.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.10.1).
## API changes
<!-- api-changes -->
+11
View File
@@ -0,0 +1,11 @@
# v3.10.2
Released on 2021-08-26.
Re-release of 3.10.1, whose Git tag pointed at the wrong commit due to a bug in the release script.
All changes are backward-compatible.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.10.2).
## API changes
<!-- api-changes -->
+16
View File
@@ -0,0 +1,16 @@
# v3.10.3
Released on 2021-10-08.
Fixes more regressions from 3.10.0. All changes are backward-compatible.
- Fixes [extended-diagnostics](../../api/macros/json_diagnostics.md) assertions triggered by
[`update`](../../api/basic_json/update.md) and by inserting into arrays.
- Supports custom allocators when writing binary formats into a `std::vector`, and allows conversion
from types that only provide `begin()`/`end()`.
[Full release notes](https://github.com/nlohmann/json/releases/tag/v3.10.3).
## API changes
<!-- api-changes -->
Loaded 100 of 163 files, more files were not shown because too many files have changed in this diff. Show more