wt/json
1
0 Fork 0
mirror of https://github.com/nlohmann/json.git synced 2026-11-02 13:20:40 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: new design for the documentation site (#5934)

Browse Source 
* docs: new design for the documentation site

Apply the brand to the Material for MkDocs site: Inter and JetBrains Mono
served by the site (upright and real italic), brand colours, blue header band
with the syntax pattern, wordmark in the header, new home page (hero, cards,
animated feature tour), 404 page, polish for tabs, search, footer, focus
rings, tables and code blocks, and theme features (code copy, previous/next
footer, TOC follow, search suggestions).

Draw the number railroad diagram, the parser callback events and the iterator
illustrations as inline SVGs that follow the light and dark scheme. The
generator scripts are in docs/mkdocs/scripts/figures; the feature slideshow
(json-light.svg, json-dark.svg, replacing json.gif on the home page) is built
by docs/mkdocs/scripts/slideshow. Decision nodes in five flowcharts become
hexagons, which need far less room.

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

* docs: add figures, table captions and a macro chooser

- Figures with numbered captions: SAX stepper, json_view layout and edit
  stepper, exception map, JSON pointer and patch walkers, QA pipeline,
  scaling and binary size charts, roadmap lanes, release timeline,
  integration decision tree and namespace builder
- Table captions (nj-table-caption) on 9 pages
- Compile times: modules and PCH charts, filesystem section, re-measured
  Figure 1, links between features/modules.md and compile_times.md
- Interactive macro chooser for features/arbitrary_types.md
- Link check: exclude URLs that answer the plugin with 400/401/419 or are
  dead (customers.md)

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

* docs: macro chooser generates adl_serializer for non-default-constructible types

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

* docs: cross-link concept pages and API pages in See also sections

Add See also links in both directions between the concept pages (features,
home, integration) and the API pages, write API links in code font, give every
entry a comment after a dash, and show the callback event figure on the parser
callbacks page.

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

* docs: address review comments on the new design

- Home: add a "Latest release" button
- Sponsors: update the list and group it by tier
- Features: list all feature pages on the index page
- Releases: add highlights per release, link the 4.0 roadmap, add the first commit to the timeline
- Exceptions: prefix all example messages with the exception name
- API: no code font for format names in the See also links of the to_/from_ pages
- Merge Patch: show the document before, the patch, and the result
- Replace "--" with typographic dashes, mark external links with an icon, center Mermaid diagrams

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

---------

Signed-off-by: Niels Lohmann <mail@nlohmann.me>
This commit is contained in:
Niels Lohmann authored and GitHub committed 2026-10-27 07:41:42 +01:00
1 parent 2bb2feeef4
commit a47170346a
417 files changed
+11100 -3041
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/mkdocs/docs/home/architecture.md
+89 -2
View File
@@ -32,6 +32,8 @@ flowchart LR
oa --> output
```
<p class="nj-caption" markdown>Data flow through the library: input runs left to right through an input adapter and the lexer and parser (JSON text) or the `binary_reader` (binary formats) into SAX events, which build the value tree; the `serializer` or the `binary_writer` writes the tree to an output adapter.</p>
- **JSON text** is read by an [input adapter](#input-adapters), tokenized by the lexer, and turned into SAX events by
the parser.
- **Binary formats** (BJData, BON8, BSON, CBOR, MessagePack, UBJSON) are read by an input adapter and turned into the same SAX
@@ -192,6 +194,8 @@ packet-beta
96-127: "next"
```
<p class="nj-caption" markdown>Layout of one 16-byte node of a JSON view index. Each row is 32 bits wide, and the numbers are the bit offsets of the fields `kind`, `flags`, `extra`, `off`, `len`, and `next`.</p>
| Bytes | Field | Type | Contents |
|-------|---------|------------|-------------------------------------------------------------------------------------------------------------------------------|
| 0 | `kind` | `uint8_t` | the type, numbered as [`value_t`](../api/basic_json/value_t.md): 0 null, 1 object, 2 array, 3 string, 4 boolean, 5 signed integer, 6 unsigned integer, 7 float; 10 for a link (see below). There is no node for a discarded value: a [discarded](../api/basic_json_view/is_discarded.md) view has none |
@@ -201,6 +205,8 @@ packet-beta
| 8-11 | `len` | `uint32_t` | strings: the length after decoding; floats and literals: the length of the token; arrays and objects: the number of elements |
| 12-15 | `next` | `uint32_t` | arrays and objects: the number of nodes of the subtree, including the node itself |
<p class="nj-table-caption" markdown>Fields of a node, by their byte offset within the 16-byte node. Integers use bytes 8-15 differently, see below.</p>
- **Integers** keep their converted value in bytes 8-15 instead of `len` and `next`; the length of their token follows
from the number of digits in `extra` (and the sign). Non-negative integers are unsigned integers, as with
[`parse`](../api/basic_json/parse.md).
@@ -234,6 +240,8 @@ flowchart LR
n2 -. next .-> e
```
<p class="nj-caption" markdown>The five nodes of `#!json {"a": [1, 2.5]}` in document order. Solid arrows lead from each node to the one after it; dotted arrows show where `next` leads from the object and the array, past their subtrees.</p>
| Node | `kind` | `extra` | `off` | `len` | `next` |
|------|----------------------|---------|-------|-------|--------|
| 0 | 1 (object) | 0 | 0 | 1 | 5 |
@@ -242,6 +250,8 @@ flowchart LR
| 3 | 6 (unsigned integer) | 0x0001 | 7 | - | - |
| 4 | 7 (float) | 0x0101 | 10 | 3 | 0 |
<p class="nj-table-caption" markdown>Fields of the five nodes of `#!json {"a": [1, 2.5]}`. `off` is the byte offset in the text, and - marks the bytes 8-15 that hold the integer's value instead of `len` and `next`.</p>
All `flags` are 0. The integer's bytes 8-15 hold its value, 1; its `extra` says it has one digit. The float's `extra`
says it has one integer and one fraction digit, and its `len` is that of the token `2.5`.
@@ -287,8 +297,9 @@ template<class T>
std::size_t get_elements(T* dest, std::size_t count = 1);
```
The lexer detects two optional extensions at compile time. Only `iterator_input_adapter` provides them, and only for
random-access input of single-byte characters:
The lexer detects two optional extensions at compile time. `iterator_input_adapter` provides both, and only for
random-access input of single-byte characters. `input_stream_adapter` provides the second one (as a window onto the
streambuf's buffer) unless `JSON_DISABLE_STREAM_BULK_SCAN` is defined:
- `supports_seek`, `get_consumed_count()`, and `copy_consumed_range()` let the lexer reconstruct already consumed input
for error messages instead of copying every character it reads. With `get_read_count()` and
@@ -306,6 +317,40 @@ The function `input_adapter` picks the right adapter for the argument passed to
- `input_stream_adapter` reads from a `std::istream`.
- `file_input_adapter` reads from a `std::FILE*`.
The adapters have no common base class: the lexer and the parser are templates on the adapter type, and
`wide_string_input_adapter` wraps an `iterator_input_adapter`:
```mermaid
classDiagram
class input_adapter ["input adapter"] {
<<concept>>
+char_type
+get_character() int_type
+get_elements(T* dest, size_t count) size_t
}
class iterator_input_adapter {
-IteratorType current
-SentinelType end
}
class wide_string_input_adapter {
-BaseInputAdapter base_adapter
}
class input_stream_adapter {
-std::istream* is
-std::streambuf* sb
}
class file_input_adapter {
-std::FILE* m_file
}
input_adapter <|.. iterator_input_adapter
input_adapter <|.. wide_string_input_adapter
input_adapter <|.. input_stream_adapter
input_adapter <|.. file_input_adapter
wide_string_input_adapter o-- iterator_input_adapter : converts to UTF-8
```
<p class="nj-caption" markdown>The input adapters as a class diagram. The dotted arrows mean that each adapter implements the input adapter concept; the diamond shows that `wide_string_input_adapter` holds an `iterator_input_adapter`.</p>
## SAX interface
The parser does not build values itself. It reports what it reads as events to a [SAX](../features/parsing/sax_interface.md)
@@ -321,6 +366,7 @@ The library comes with two consumers in `detail/input/json_sax.hpp`:
The `binary_reader` emits the same events for binary formats, so [`sax_parse`](../api/basic_json/sax_parse.md) works
with a user-defined consumer for JSON and for all binary formats alike.
The [SAX event stepper](../features/parsing/sax_interface.md#sax-event-stepper) shows the events for a small input.
## Output adapters
@@ -339,6 +385,36 @@ 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.
They implement the abstract class `output_adapter_protocol`. The class `output_adapter` creates the one that matches
its argument and holds it in a `std::shared_ptr` (`output_adapter_t`):
```mermaid
classDiagram
class output_adapter_protocol~CharType~ {
<<interface>>
+write_character(CharType c)*
+write_characters(const CharType* s, size_t length)*
}
class output_vector_adapter {
-std::vector& v
}
class output_stream_adapter {
-std::basic_ostream& stream
}
class output_string_adapter {
-StringType& str
}
class output_adapter {
-output_adapter_t oa
}
output_adapter_protocol <|-- output_vector_adapter
output_adapter_protocol <|-- output_stream_adapter
output_adapter_protocol <|-- output_string_adapter
output_adapter o-- output_adapter_protocol : shared_ptr
```
<p class="nj-caption" markdown>The output adapters as a class diagram. The three adapters derive from `output_adapter_protocol` (solid arrows), and `output_adapter` holds one of them through a `shared_ptr` (diamond).</p>
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
@@ -377,3 +453,14 @@ release. Besides the components above, it contains:
- type traits to detect the capabilities of user-defined types (`detail/meta/type_traits.hpp`),
- backports of C++14/17 features to C++11 (`detail/meta/cpp_future.hpp`), and
- helpers such as `string_concat` and `string_escape`.
## See also
- [`basic_json`](../api/basic_json/index.md) - the main class and all its member functions
- [`adl_serializer`](../api/adl_serializer/index.md) - customization point for type conversions
- [`json_sax`](../api/json_sax/index.md) - interface of the SAX parser events
- [SAX Interface](../features/parsing/sax_interface.md) - how to consume parser events without building a DOM
- [Zero-copy JSON views](../features/json_view.md) - the flat node index that backs views and documents
- [Template Parameter Requirements](../features/types/template_parameters.md) - the template parameters of basic_json
- [Serialization](../features/serialization.md) - the output side of the library
- [`nlohmann` Namespace](../features/namespace.md) - how the library namespace is structured
docs/mkdocs/docs/home/debugging.md
+8 -1
View File
@@ -50,5 +50,12 @@ Defining [`JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md) before includin
`type_error`/`out_of_range`-style exceptions with a JSON Pointer to the offending value, which can help pinpoint
where in a large document a runtime error occurred. This only applies to exceptions thrown *after* a value
exists (e.g. during element access); parse errors, which happen before any value exists to point at, are not
covered by this mechanism -- see [Parsing and exceptions](../features/parsing/parse_exceptions.md) for how parse
covered by this mechanism — see [Parsing and exceptions](../features/parsing/parse_exceptions.md) for how parse
errors report their own location instead.
## See also
- [`JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md) - extended exception messages with the path of the failing value
- [`JSON_DIAGNOSTIC_POSITIONS`](../api/macros/json_diagnostic_positions.md) - record byte positions of values for error messages
- [Exceptions](exceptions.md) - all exceptions and their error codes
- [`exception`](../api/basic_json/exception.md) - base class of all exceptions thrown by the library
docs/mkdocs/docs/home/design_goals.md
+7
View File
@@ -15,3 +15,10 @@ Other aspects were not so important to us:
- **Speed**. There are certainly [faster JSON libraries](https://github.com/miloyip/nativejson-benchmark#parsing-time) out there. However, if your goal is to speed up your development by adding JSON support with a single header, then this library is the way to go. If you know how to use a `std::vector` or `std::map`, you are already set.
See the [contribution guidelines](https://github.com/nlohmann/json/blob/develop/.github/CONTRIBUTING.md#please-dont) for more information.
## See also
- [`basic_json`](../api/basic_json/index.md) - the main class and all its member functions
- [Macros](../api/macros/index.md) - reference of all macros
- [Performance](../features/performance.md) - how the library performs and what is not optimized
- [Architecture](architecture.md) - how the library is put together
docs/mkdocs/docs/home/exceptions.md
+54 -42
View File
@@ -6,35 +6,35 @@
All exceptions inherit from class `json::exception` (which in turn inherits from `std::exception`). It is used as the base class for all exceptions thrown by the `basic_json` class. This class can hence be used as "wildcard" to catch exceptions.
``` mermaid
classDiagram
direction LR
class `std::exception` {
<<interface>>
}
The map shows the class tree and every exception id documented on this page; click an id to jump to its section.
class `json::exception` {
+const int id
+const char* what() const
}
<div class="nj-fig-wrap" markdown>
--8<-- "images/exception_map.svg"
</div>
class `json::parse_error` {
+const std::size_t byte
}
<p class="nj-caption" markdown>The exception classes from `std::exception` down to the five families, each with the ids it can throw. Every id chip links to the section that describes it.</p>
class `json::invalid_iterator`
class `json::type_error`
class `json::out_of_range`
class `json::other_error`
Which exception an element access throws depends on the function and on the type of the value:
`std::exception` <|-- `json::exception`
`json::exception` <|-- `json::parse_error`
`json::exception` <|-- `json::invalid_iterator`
`json::exception` <|-- `json::type_error`
`json::exception` <|-- `json::out_of_range`
`json::exception` <|-- `json::other_error`
```mermaid
flowchart LR
S{{"which call?"}} -->|"at(key)"| A{{"j is"}}
A -->|"object, key missing"| A1["out_of_range.403"]
A -->|"array or null"| A2["type_error.304"]
S -->|"at(index)"| B{{"j is"}}
B -->|"array, index >= size()"| B1["out_of_range.401"]
B -->|"object or null"| B2["type_error.304"]
S -->|"non-const operator[](key)"| C{{"j is"}}
C -->|"object or null"| C1["no exception: a missing key is inserted as null"]
C -->|"array"| C2["type_error.305"]
S -->|"value(key, default)"| D{{"j is"}}
D -->|"object, key missing"| D1["no exception: returns the default"]
D -->|"object, incompatible value type"| D2["type_error.302"]
D -->|"array or null"| D3["type_error.306"]
```
<p class="nj-caption" markdown>Exceptions thrown by element access. Start at the call on the left, follow the edge that matches the type of `j`, and read the exception id (or "no exception") in the box at the end.</p>
### Switch off exceptions
Exceptions are used widely within the library. They can, however, be switched off with either using the compiler flag `-fno-exceptions` or by defining the symbol [`JSON_NOEXCEPTION`](../api/macros/json_noexception.md). In this case, exceptions are replaced by `abort()` calls. You can further control this behavior by defining `JSON_THROW_USER` (overriding `#!cpp throw`), `JSON_TRY_USER` (overriding `#!cpp try`), and `JSON_CATCH_USER` (overriding `#!cpp catch`).
@@ -230,7 +230,7 @@ JSON uses the `\uxxxx` format to describe Unicode characters. Code points above
!!! failure "Example message"
```
parse error at 14: missing or wrong low surrogate
[json.exception.parse_error.102] parse error at 14: missing or wrong low surrogate
```
!!! note
@@ -244,7 +244,7 @@ Unicode supports code points up to 0x10FFFF. Code points above 0x10FFFF are inva
!!! failure "Example message"
```
parse error: code points above 0x10FFFF are invalid
[json.exception.parse_error.103] parse error: code points above 0x10FFFF are invalid
```
!!! note
@@ -947,7 +947,7 @@ The provided array index `i` is larger than `size-1`.
!!! failure "Example message"
```
array index 3 is out of range
[json.exception.out_of_range.401] array index 3 is out of range
```
### json.exception.out_of_range.402
@@ -957,7 +957,7 @@ The special array index `-` in a JSON Pointer never describes a valid element of
!!! failure "Example message"
```
array index '-' (3) is out of range
[json.exception.out_of_range.402] array index '-' (3) is out of range
```
### json.exception.out_of_range.403
@@ -967,7 +967,7 @@ The provided key was not found in the JSON object.
!!! failure "Example message"
```
key 'foo' not found
[json.exception.out_of_range.403] key 'foo' not found
```
### json.exception.out_of_range.404
@@ -978,7 +978,7 @@ contains other characters (e.g., `1a`), or `-` where it cannot be used.
!!! failure "Example message"
```
unresolved reference token 'foo'
[json.exception.out_of_range.404] unresolved reference token 'foo'
```
### json.exception.out_of_range.405
@@ -990,7 +990,7 @@ also thrown when the parent or a reference token of an empty JSON Pointer is req
!!! failure "Example message"
```
JSON pointer has no parent
[json.exception.out_of_range.405] JSON pointer has no parent
```
### json.exception.out_of_range.406
@@ -1002,7 +1002,7 @@ double-precision number when `number_float_t` is `#!cpp float`.
!!! failure "Example messages"
```
number overflow parsing '10E1000'
[json.exception.out_of_range.406] number overflow parsing '10E1000'
```
```
[json.exception.out_of_range.406] syntax error while parsing CBOR value: number overflow
@@ -1038,10 +1038,10 @@ exception, because they serialize integers beyond 64 bits as high-precision numb
!!! failure "Example messages"
```
integer number 18446744073709551615 cannot be represented by BON8 as it does not fit int64
[json.exception.out_of_range.407] integer number 18446744073709551615 cannot be represented by BON8 as it does not fit int64
```
```
integer number 1267650600228229401496703205376 cannot be represented by CBOR as it does not fit [-2^64, 2^64-1]
[json.exception.out_of_range.407] integer number 1267650600228229401496703205376 cannot be represented by CBOR as it does not fit [-2^64, 2^64-1]
```
### json.exception.out_of_range.408
@@ -1059,7 +1059,7 @@ count and one marker per element are kept), so any value it produces can still b
!!! failure "Example messages"
```
excessive array size: 8658170730974374167
[json.exception.out_of_range.408] excessive array size: 8658170730974374167
```
```
[json.exception.out_of_range.408] syntax error while parsing CBOR size: excessive array size
@@ -1078,7 +1078,7 @@ Key identifiers to be serialized to BSON cannot contain code point U+0000, since
!!! failure "Example message"
```
BSON key cannot contain code point U+0000 (at byte 2)
[json.exception.out_of_range.409] BSON key cannot contain code point U+0000 (at byte 2)
```
### json.exception.out_of_range.410
@@ -1090,8 +1090,8 @@ a JSON pointer exceeds the range of `size_type` (e.g., on 32-bit platforms).
!!! failure "Example message"
```
enum value out of range
array index 18446744073709551615 exceeds size_type
[json.exception.out_of_range.410] enum value out of range
[json.exception.out_of_range.410] array index 18446744073709551615 exceeds size_type
```
The second message is thrown, for instance, by `#!cpp json::parse("[1, 2]").at("/18446744073709551615"_json_pointer)`
@@ -1106,7 +1106,7 @@ A JSON Patch `add` operation cannot be applied because the target location's par
!!! failure "Example message"
```
cannot add value: the JSON Patch 'add' target's parent is of type string, but must be an object or array
[json.exception.out_of_range.411] cannot add value: the JSON Patch 'add' target's parent is of type string, but must be an object or array
```
!!! note
@@ -1124,10 +1124,10 @@ is thrown when a value is too large to be described by such a length field.
!!! failure "Example messages"
```
BSON length 2147483661 exceeds maximum of 2147483647
[json.exception.out_of_range.412] BSON length 2147483661 exceeds maximum of 2147483647
```
```
MessagePack length 4294967296 exceeds maximum of 4294967295
[json.exception.out_of_range.412] MessagePack length 4294967296 exceeds maximum of 4294967295
```
!!! note
@@ -1144,7 +1144,7 @@ A JSON Patch `remove` operation cannot be applied because the target location's
!!! failure "Example message"
```
cannot remove value: the JSON Patch 'remove' target's parent is of type number, but must be an object or array
[json.exception.out_of_range.413] cannot remove value: the JSON Patch 'remove' target's parent is of type number, but must be an object or array
```
!!! note
@@ -1158,7 +1158,7 @@ A JSON Patch `move` operation's `"from"` location is a proper prefix of its `"pa
!!! failure "Example message"
```
cannot move value: 'from' path '/0' is a proper prefix of 'path' '/0/0'
[json.exception.out_of_range.414] cannot move value: 'from' path '/0' is a proper prefix of 'path' '/0/0'
```
!!! note
@@ -1262,3 +1262,15 @@ do not throw.
This exception was added in version 3.13.0. Before that, debug builds aborted on an assertion and release builds
wrote a `$` marker without `#`, which [`from_ubjson`](../api/basic_json/from_ubjson.md) then rejected.
## See also
- [`exception`](../api/basic_json/exception.md) - base class of all exceptions thrown by the library
- [`parse_error`](../api/basic_json/parse_error.md) - exceptions indicating a parse error
- [`invalid_iterator`](../api/basic_json/invalid_iterator.md) - exceptions indicating errors with iterators
- [`type_error`](../api/basic_json/type_error.md) - exceptions indicating a wrong type
- [`out_of_range`](../api/basic_json/out_of_range.md) - exceptions indicating access out of range
- [`other_error`](../api/basic_json/other_error.md) - exceptions indicating other library errors
- [`JSON_NOEXCEPTION`](../api/macros/json_noexception.md) - switch off exceptions
- [`JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md) - extended exception messages with the path of the failing value
- [Working Without Exceptions](../features/no_exceptions.md) - use the library without exceptions
docs/mkdocs/docs/home/faq.md
+12 -3
View File
@@ -20,7 +20,7 @@
yield different results (`#!json [true]` vs. `#!json true`)?
This is a known issue, and -- even worse -- the behavior differs between GCC and Clang. The "culprit" for this is the library's constructor overloads for initializer lists to allow syntax like
This is a known issue, and — even worse — the behavior differs between GCC and Clang. The "culprit" for this is the library's constructor overloads for initializer lists to allow syntax like
```cpp
json array = {1, 2, 3, 4};
@@ -192,6 +192,8 @@ The value is a `json`, and printing it produces JSON text. Convert it first: `#!
Use `contains` or `find`. Do not test with the non-const `operator[]`: like `std::map::operator[]`, it inserts a `null`
value for a missing key. See [Does this key exist?](../features/element_access/index.md#does-this-key-exist).
For choosing between `value`, `contains`/`find`, `at`, `operator[]`, and JSON Pointer, see the decision flow in
[Element access](../features/element_access/index.md).
### Reading a value with a fallback
@@ -392,8 +394,8 @@ As described [above](#parse-errors-reading-non-ascii-characters), the library st
No. `basic_json` provides no built-in synchronization, the same as `std::map` or `std::vector`. Concurrent reads of
the same value from multiple threads are safe, as are concurrent (non-overlapping) accesses to independent `json`
objects. However, any concurrent write to a `json` object -- or a concurrent read while another thread writes to the
same object -- is a data race and requires external synchronization (e.g., a `std::mutex`) by the caller.
objects. However, any concurrent write to a `json` object — or a concurrent read while another thread writes to the
same object — is a data race and requires external synchronization (e.g., a `std::mutex`) by the caller.
### Schema validation
@@ -596,3 +598,10 @@ well. See [#3669](https://github.com/nlohmann/json/issues/3669) for details.
This is not an issue with the code, but rather with the compiler itself. On Android, use a current NDK (see above).
For MinGW, please refer to [this site](http://tehsausage.com/mingw-to-string) and
[this discussion](https://github.com/nlohmann/json/issues/136) for information on how to fix this bug.
## See also
- [`basic_json`](../api/basic_json/index.md) - the main class and all its member functions
- [Macros](../api/macros/index.md) - reference of all macros
- [Exceptions](exceptions.md) - all exceptions and their error codes
- [Features](../features/index.md) - overview of all features
docs/mkdocs/docs/home/releases/index.md
+53 -43
View File
@@ -14,6 +14,14 @@ changed in it. The API overview is generated from the "Version history" section
[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.
All releases at a glance (hover a marker for its version and date):
<div class="nj-fig-wrap" markdown>
--8<-- "images/release_timeline.svg"
</div>
<p class="nj-caption" markdown>From the first commit (diamond) in 2013 to the latest release, on a time axis by year. Filled dots with a version label are minor or major releases, rings are patch releases.</p>
## Unreleased
| Release | Date | Summary |
@@ -24,124 +32,124 @@ the version you use.
| 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. |
| [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. **Highlights:** diagnostic byte positions (`start_pos`/`end_pos`); templated conversion macros and `NLOHMANN_DEFINE_DERIVED_TYPE`; `std::optional` support. |
## 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. |
| [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. **Highlights:** custom base class for `basic_json`; serialization-only conversion macros; Bazel and Swift Package Manager support. |
| [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. **Highlights:** fixes `value` for strings and size types; restores `json_pointer` as associative-container key; restructured inline namespace. |
| [v3.11.1](v3.11.1.md) | 2022-08-01 | Fixes a regression from 3.11.0. All changes are backward-compatible. **Highlights:** restores the global `_json` and `_json_pointer` literals. |
| [v3.11.0](v3.11.0.md) | 2022-08-01 | One of the largest releases ever. All changes are backward-compatible. **Highlights:** `std::string_view` keys; BJData binary format; C++20 support including `operator<=>`. |
## 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. |
| [v3.10.5](v3.10.5.md) | 2022-01-03 | Bug-fix release. All changes are backward-compatible. **Highlights:** guards the `std::filesystem` conversions with `JSON_HAS_FILESYSTEM`. |
| [v3.10.4](v3.10.4.md) | 2021-10-16 | Fixes regressions introduced in 3.10.0. All changes are backward-compatible. **Highlights:** fixes the `std::filesystem::path` conversion; fixes types with explicit defaulted constructors; fixes `std::find`/`std::remove` return values. |
| [v3.10.3](v3.10.3.md) | 2021-10-08 | Fixes more regressions from 3.10.0. All changes are backward-compatible. **Highlights:** fixes extended-diagnostics assertions in `update` and array insertion; custom allocators for binary output; conversion from `begin()`/`end()`-only types. |
| [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. **Highlights:** re-release of 3.10.1 with the correct Git tag. |
| [v3.10.1](v3.10.1.md) | 2021-08-24 | Fixes a regression from 3.10.0. All changes are backward-compatible. **Highlights:** fixes an extended-diagnostics assertion with `ordered_json`; hardens the GDB pretty-printer. |
| [v3.10.0](v3.10.0.md) | 2021-08-17 | Feature release. All changes are backward-compatible. **Highlights:** extended diagnostic messages (`JSON_DIAGNOSTICS`); GDB pretty-printer; CBOR tag storage. |
## 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. |
| [v3.9.1](v3.9.1.md) | 2020-08-06 | Fixes two regressions from 3.9.0. All changes are backward-compatible. **Highlights:** accepts consecutive comments; completes the `ordered_json` interface. |
| [v3.9.0](v3.9.0.md) | 2020-07-27 | Feature release adding four long-requested features. All changes are backward-compatible. **Highlights:** comment parsing; `ordered_json`; switch to disable implicit conversions. |
## Version 3.8.x
| Release | Date | Summary |
|---------|------|---------|
| [v3.8.0](v3.8.0.md) | 2020-06-14 | Feature release. All changes are backward-compatible. |
| [v3.8.0](v3.8.0.md) | 2020-06-14 | Feature release. All changes are backward-compatible. **Highlights:** binary value type for CBOR, BSON, and MessagePack; input adapters for any `LegacyInputIterator` container; fixes `contains` for JSON pointers. |
## 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. |
| [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. **Highlights:** fixes quadratic complexity in destructor calls. |
| [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. **Highlights:** iterative destructor fixes a stack overflow on deeply nested input. |
| [v3.7.1](v3.7.1.md) | 2019-11-06 | Bug-fix release. All changes are backward-compatible. **Highlights:** fixes a crash when serializing the minimum `std::int64_t`; fixes `contains` for JSON pointers; `items` with custom string types. |
| [v3.7.0](v3.7.0.md) | 2019-07-28 | Convenience features and house-keeping. All changes are backward-compatible. **Highlights:** `contains` overload for JSON pointers; generic `to_string`; return value for `emplace_back`. |
## 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. |
| [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. **Highlights:** fixes a GCC 7/8 compilation regression; fixes a `<Windows.h>` build error. |
| [v3.6.0](v3.6.0.md) | 2019-03-20 | Feature release. All changes are backward-compatible. **Highlights:** reworked JSON pointer interface; `contains` function; faster integer serialization. |
## Version 3.5.x
| Release | Date | Summary |
|---------|------|---------|
| [v3.5.0](v3.5.0.md) | 2018-12-22 | Feature release. All changes are backward-compatible. |
| [v3.5.0](v3.5.0.md) | 2018-12-22 | Feature release. All changes are backward-compatible. **Highlights:** structured bindings via `items`; reading from `FILE*`; fixes `eofbit` handling on streams. |
## Version 3.4.x
| Release | Date | Summary |
|---------|------|---------|
| [v3.4.0](v3.4.0.md) | 2018-10-30 | Feature release. All changes are backward-compatible. |
| [v3.4.0](v3.4.0.md) | 2018-10-30 | Feature release. All changes are backward-compatible. **Highlights:** BSON support; Unicode error handlers for `dump`; `NLOHMANN_JSON_SERIALIZE_ENUM`. |
## Version 3.3.x
| Release | Date | Summary |
|---------|------|---------|
| [v3.3.0](v3.3.0.md) | 2018-10-05 | Feature release. All changes are backward-compatible. |
| [v3.3.0](v3.3.0.md) | 2018-10-05 | Feature release. All changes are backward-compatible. **Highlights:** GCC 4.8 support; `get_to`; overhauled CMake integration. |
## Version 3.2.x
| Release | Date | Summary |
|---------|------|---------|
| [v3.2.0](v3.2.0.md) | 2018-08-20 | Feature release. All changes are backward-compatible. |
| [v3.2.0](v3.2.0.md) | 2018-08-20 | Feature release. All changes are backward-compatible. **Highlights:** SAX interface and non-recursive parser; parsing from wide strings; conversion to `std::string_view`. |
## 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. |
| [v3.1.2](v3.1.2.md) | 2018-03-14 | Bug-fix release. All changes are backward-compatible. **Highlights:** fixes a memory leak in the parser callback; user-defined string types in parser and serializer. |
| [v3.1.1](v3.1.1.md) | 2018-02-13 | Bug-fix release. All changes are backward-compatible. **Highlights:** fixes parsing of indefinite-length CBOR strings; fixes a user-defined conversion to vector types; fixes UBJSON overflow detection. |
| [v3.1.0](v3.1.0.md) | 2018-02-01 | Feature release. All changes are backward-compatible. **Highlights:** UBJSON support; JSON Merge Patch; Grisu2 floating-point output. |
## 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)). |
| [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. **Highlights:** fixes invalid JSON Patch "copy" targets; fixes non-integer array indices in JSON Pointer. |
| [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)). **Highlights:** user-defined exceptions with identifiers; non-throwing `accept` and `allow_exceptions`; `update` to merge objects. |
## 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. |
| [v2.1.1](v2.1.1.md) | 2017-02-25 | Bug-fix release. All changes are backward-compatible. **Highlights:** locale-independent number parsing and serialization; correct floating-point round-tripping; GPG-signed commits and files. |
| [v2.1.0](v2.1.0.md) | 2017-01-28 | Feature release. All changes are backward-compatible. **Highlights:** conversions from and to arbitrary user-defined types; `meta` function; `JSON_NOEXCEPTION`. |
## 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. |
| [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. **Highlights:** fixes security-relevant bugs in the CBOR parser; fixes security-relevant bugs in the MessagePack parser. |
| [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. **Highlights:** CBOR support; MessagePack support. |
| [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. **Highlights:** `emplace` and `emplace_back`; faster parsing; faster serialization. |
| [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. **Highlights:** fixes short-file handling; fixes encoding detection; fixes surrogate pairs. |
| [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. **Highlights:** `operator[]` creates missing values for JSON pointers. |
| [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. **Highlights:** fixes a remaining stream end-of-file bug. |
| [v2.0.4](v2.0.4.md) | 2016-09-11 | Fixes stream end-of-file detection in the parser. All changes are backward-compatible. **Highlights:** fixes stream end-of-file detection. |
| [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. **Highlights:** parser accepts any contiguous sequence of one-byte elements; deprecates the input-stream constructor in favor of `parse`. |
| [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. **Highlights:** overhauled parser rejecting unescaped control characters; tighter class invariants; code cleanup. |
| [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. **Highlights:** fixes a performance regression in `dump`. |
| [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. **Highlights:** JSON Pointer support in `at` and `operator[]`, plus `flatten` and `unflatten`; JSON Patch via `diff` and `patch`; unsigned 64-bit integers. |
## 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. |
| [v1.1.0](v1.1.0.md) | 2016-01-24 | Bug-fix and feature release. All changes are backward-compatible. **Highlights:** improved floating-point round-tripping; `get_ref`; runtime assertions. |
## Version 1.0.x
@@ -153,3 +161,5 @@ the version you use.
- [Migration Guide](../../integration/migration_guide.md) — how to future-proof your code for the next
major version and replace deprecated functions.
- [Roadmap: Version 4.0](../../community/roadmap.md#version-40) — what the next major version will change and how to
try it today.
docs/mkdocs/docs/home/sponsors.md
+20 -7
View File
@@ -1,18 +1,31 @@
# Sponsors
You can sponsor this library at [GitHub Sponsors](https://github.com/sponsors/nlohmann).
You can sponsor this library at [GitHub Sponsors](https://github.com/sponsors/nlohmann). Thanks to everyone who
supports the project!
## Priority Sponsor
## Priority Sponsors
- [Martti Laine](https://github.com/codeclown)
- [Paul Harrington](https://github.com/phrrngtn)
- [Mercedes-Benz](https://github.com/mercedes-benz)
- [FastNetMon](https://github.com/FastNetMon)
## Named Sponsors
- [Paul Harrington](https://github.com/phrrngtn)
- [Steve Wagner](https://github.com/ciroque)
- [mccaffers](https://github.com/mccaffers)
- [jambolo](https://github.com/jambolo)
## Further Sponsors
- [Grisha Kirilin](https://github.com/GrishaKirilin)
- [zimmerman-dev](https://github.com/zimmerman-dev)
- [WAAutoMaton](https://github.com/WAAutoMaton)
- [F3D](https://github.com/f3d-app)
- [David Alvarez Rosa](https://github.com/david-alvarez-rosa)
- [Alex Kong](https://github.com/alex-lt-kong)
- [Mark Oates](https://github.com/MarkOates)
- [Martti Laine](https://github.com/codeclown)
- Michael Hartmann
- [Stefan Hagen](https://github.com/sthagen)
- [Steve Sperandeo](https://github.com/homer6)
- [Robert Jefe Lindstädt](https://github.com/eljefedelrodeodeljefe)
- [Steve Wagner](https://github.com/ciroque)
Thanks everyone!