Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 549c79b

Browse files
nlohmannnlohmann
authored
Overwork documentation (#4516)
1 parent 9f60e85 commit 549c79b

68 files changed

Lines changed: 1110 additions & 360 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/publish_documentation.yml‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -25,9 +25,6 @@ jobs:
2525
steps:
2626
- uses: actions/checkout@v4
2727

28-
- name: Install and update PlantUML
29-
run: sudo apt-get update ; sudo apt-get install -y plantuml
30-
3128
- name: Install virtual environment
3229
run: make install_venv -C docs/mkdocs
3330

‎CMakeLists.txt‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -81,23 +81,23 @@ else()
8181
endif()
8282

8383
if (NOT JSON_ImplicitConversions)
84-
message(STATUS "Implicit conversions are disabled")
84+
message(STATUS "Implicit conversions are disabled (JSON_USE_IMPLICIT_CONVERSIONS=0)")
8585
endif()
8686

8787
if (JSON_DisableEnumSerialization)
88-
message(STATUS "Enum integer serialization is disabled")
88+
message(STATUS "Enum integer serialization is disabled (JSON_DISABLE_ENUM_SERIALIZATION=0)")
8989
endif()
9090

9191
if (JSON_LegacyDiscardedValueComparison)
92-
message(STATUS "Legacy discarded value comparison enabled")
92+
message(STATUS "Legacy discarded value comparison enabled (JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON=1)")
9393
endif()
9494

9595
if (JSON_Diagnostics)
96-
message(STATUS "Diagnostics enabled")
96+
message(STATUS "Diagnostics enabled (JSON_DIAGNOSTICS=1)")
9797
endif()
9898

9999
if (NOT JSON_GlobalUDLs)
100-
message(STATUS "User-defined string literals are not put in the global namespace")
100+
message(STATUS "User-defined string literals are not put in the global namespace (JSON_USE_GLOBAL_UDLS=0)")
101101
endif()
102102

103103
if (JSON_SystemInclude)

‎README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@
3939
- [Conversions to/from arbitrary types](#arbitrary-types-conversions)
4040
- [Specializing enum conversion](#specializing-enum-conversion)
4141
- [Binary formats (BSON, CBOR, MessagePack, UBJSON, and BJData)](#binary-formats-bson-cbor-messagepack-ubjson-and-bjdata)
42+
- [Customers](#customers)
4243
- [Supported compilers](#supported-compilers)
4344
- [Integration](#integration)
4445
- [CMake](#cmake)
@@ -1112,6 +1113,11 @@ binary.set_subtype(0x10);
11121113
auto cbor = json::to_msgpack(j); // 0xD5 (fixext2), 0x10, 0xCA, 0xFE
11131114
```
11141115
1116+
## Customers
1117+
1118+
The library is used in multiple projects, applications, operating systems, etc. The list below is not exhaustive, but the result of an internet search. If you know further customers of the library, please let me know, see [contact](#contact).
1119+
1120+
[![](docs/mkdocs/docs/images/customers.png)](https://json.nlohmann.me/home/customers/)
11151121
11161122
## Supported compilers
11171123

‎cmake/ci.cmake‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1024,8 +1024,8 @@ add_custom_target(ci_test_examples
10241024
)
10251025

10261026
add_custom_target(ci_test_api_documentation
1027-
COMMAND ${Python3_EXECUTABLE} scripts/check_structure.py
1028-
WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}/docs/mkdocs
1027+
COMMAND ${Python3_EXECUTABLE} ../scripts/check_structure.py
1028+
WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}/docs/mkdocs/docs
10291029
COMMENT "Lint the API documentation"
10301030
)
10311031

‎docs/mkdocs/Makefile‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,3 +35,11 @@ install_venv: requirements.txt
3535
# uninstall the virtual environment
3636
uninstall_venv: clean
3737
rm -fr venv
38+
39+
update_requirements:
40+
rm -fr venv_small
41+
python3 -mvenv venv_small
42+
venv_small/bin/pip3 install pur
43+
venv_small/bin/pur -r requirements.txt
44+
rm -fr venv_small venv
45+
make install_venv

‎docs/mkdocs/docs/api/basic_json/accept.md‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -29,9 +29,9 @@ Unlike the [`parse`](parse.md) function, this function neither throws an excepti
2929
: A compatible input, for instance:
3030
3131
- an `std::istream` object
32-
- a `FILE` pointer (must not be null)
32+
- a `FILE` pointer (throws if null)
3333
- a C-style array of characters
34-
- a pointer to a null-terminated string of single byte characters
34+
- a pointer to a null-terminated string of single byte characters (throws if null)
3535
- a `std::string`
3636
- an object `obj` for which `begin(obj)` and `end(obj)` produces a valid pair of iterators.
3737
@@ -64,18 +64,17 @@ Whether the input is valid JSON.
6464
6565
Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
6666
67+
## Exceptions
68+
69+
Throws [`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101) in case of an empty input like a null `FILE*` or `char*` pointer.
70+
6771
## Complexity
6872
6973
Linear in the length of the input. The parser is a predictive LL(1) parser.
7074
7175
## Notes
7276
73-
(1) A UTF-8 byte order mark is silently ignored.
74-
75-
!!! danger "Runtime assertion"
76-
77-
The precondition that a passed `#!cpp FILE` pointer must not be null is enforced with a
78-
[runtime assertion](../../features/assertions.md).
77+
A UTF-8 byte order mark is silently ignored.
7978
8079
## Examples
8180
@@ -102,6 +101,7 @@ Linear in the length of the input. The parser is a predictive LL(1) parser.
102101
103102
- Added in version 3.0.0.
104103
- Ignoring comments via `ignore_comments` added in version 3.9.0.
104+
- Changed [runtime assertion](../../features/assertions.md) in case of `FILE*` null pointers to exception in version 3.11.4.
105105
106106
!!! warning "Deprecation"
107107

‎docs/mkdocs/docs/api/basic_json/emplace.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,11 @@ created from `args`.
1414
`Args`
1515
: compatible types to create a `basic_json` object
1616
17+
## Iterator invalidation
18+
19+
For [`ordered_json`](../ordered_json.md), adding a value to an object can yield a reallocation, in which case all
20+
iterators (including the `end()` iterator) and all references to the elements are invalidated.
21+
1722
## Parameters
1823
1924
`args` (in)

‎docs/mkdocs/docs/api/basic_json/emplace_back.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,12 @@ Creates a JSON value from the passed parameters `args` to the end of the JSON va
1313
`Args`
1414
: compatible types to create a `basic_json` object
1515
16+
## Iterator invalidation
17+
18+
By adding an element to the end of the array, a reallocation can happen, in which case all iterators (including the
19+
[`end()`](end.md) iterator) and all references to the elements are invalidated. Otherwise, only the [`end()`](end.md)
20+
iterator is invalidated.
21+
1622
## Parameters
1723
1824
`args` (in)
@@ -48,6 +54,11 @@ Amortized constant.
4854
--8<-- "examples/emplace_back.output"
4955
```
5056
57+
## See also
58+
59+
- [operator+=](operator+=.md) add a value to an array/object
60+
- [push_back](push_back.md) add a value to an array/object
61+
5162
## Version history
5263
5364
- Since version 2.0.8.

‎docs/mkdocs/docs/api/basic_json/exception.md‎

Lines changed: 30 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -8,24 +8,36 @@ This class is an extension of [`std::exception`](https://en.cppreference.com/w/c
88
member `id` for exception ids. It is used as the base class for all exceptions thrown by the `basic_json` class. This
99
class can hence be used as "wildcard" to catch exceptions, see example below.
1010
11-
```plantuml
12-
std::exception <|-- basic_json::exception
13-
basic_json::exception <|-- basic_json::parse_error
14-
basic_json::exception <|-- basic_json::invalid_iterator
15-
basic_json::exception <|-- basic_json::type_error
16-
basic_json::exception <|-- basic_json::out_of_range
17-
basic_json::exception <|-- basic_json::other_error
18-
19-
interface std::exception {}
20-
21-
class basic_json::exception #FFFF00 {
22-
+ const int id
23-
+ const char* what() const
24-
}
25-
26-
class basic_json::parse_error {
27-
+ const std::size_t byte
28-
}
11+
```mermaid
12+
classDiagram
13+
direction LR
14+
15+
class std_exception ["std::exception"] {
16+
<<interface>>
17+
}
18+
19+
class json_exception ["basic_json::exception"] {
20+
+const int id
21+
+const char* what() const
22+
}
23+
24+
class json_parse_error ["basic_json::parse_error"] {
25+
+const std::size_t byte
26+
}
27+
28+
class json_invalid_iterator ["basic_json::invalid_iterator"]
29+
class json_type_error ["basic_json::type_error"]
30+
class json_out_of_range ["basic_json::out_of_range"]
31+
class json_other_error ["basic_json::other_error"]
32+
33+
std_exception <|-- json_exception
34+
json_exception <|-- json_parse_error
35+
json_exception <|-- json_invalid_iterator
36+
json_exception <|-- json_type_error
37+
json_exception <|-- json_out_of_range
38+
json_exception <|-- json_other_error
39+
40+
style json_exception fill:#CCCCFF
2941
```
3042

3143
Subclasses:

‎docs/mkdocs/docs/api/basic_json/get_ptr.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,9 @@ Constant.
3737

3838
The pointer becomes invalid if the underlying JSON object changes.
3939

40-
Consider the following example code where the pointer `ptr` changes after the array is resized. As a result, reading or writing to `ptr` after the array change would be undefined behavior. The address of the first array element changes, because the underlying `std::vector` is resized after adding a fifth element.
40+
Consider the following example code where the pointer `ptr` changes after the array is resized. As a result,
41+
reading or writing to `ptr` after the array change would be undefined behavior. The address of the first array
42+
element changes, because the underlying `std::vector` is resized after adding a fifth element.
4143

4244
```cpp
4345
#include <iostream>

0 commit comments

Comments
 (0)