Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update documentation #2312

Merged
merged 10 commits into from
Jul 26, 2020
Prev Previous commit
Next Next commit
📝 add more documentation
  • Loading branch information
nlohmann committed Jul 25, 2020
commit 6e5be17b624f2ef4054dcdd057110882990ad3a6
72 changes: 72 additions & 0 deletions doc/mkdocs/docs/api/basic_json/dump.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
# basic_json::dump

```cpp
string_t dump(const int indent = -1,
const char indent_char = ' ',
const bool ensure_ascii = false,
const error_handler_t error_handler = error_handler_t::strict) const
```

Serialization function for JSON values. The function tries to mimic
Python's `json.dumps()` function, and currently supports its `indent`
and `ensure_ascii` parameters.

## Parameters

`indent` (in)
: If indent is nonnegative, then array elements and object
members will be pretty-printed with that indent level. An indent level of
`0` will only insert newlines. `-1` (the default) selects the most compact
representation.

`indent_char` (in)
: The character to use for indentation if `indent` is
greater than `0`. The default is ` ` (space).

`ensure_ascii` (in)
: If `ensure_ascii` is true, all non-ASCII characters
in the output are escaped with `\uXXXX` sequences, and the result consists
of ASCII characters only.

`error_handler` (in)
: how to react on decoding errors; there are three
possible values: `strict` (throws and exception in case a decoding error
occurs; default), `replace` (replace invalid UTF-8 sequences with U+FFFD),
and `ignore` (ignore invalid UTF-8 sequences during serialization; all
bytes are copied to the output unchanged).

## Return value

string containing the serialization of the JSON value

## Exception safety

Strong guarantee: if an exception is thrown, there are no
changes to any JSON value.

## Complexity

Linear.

## Notes

Binary values are serialized as object containing two keys:

- "bytes": an array of bytes as integers
- "subtype": the subtype as integer or `#!json null` if the binary has no subtype

## Example

The following example shows the effect of different `indent`,
`indent_char`, and `ensure_ascii` parameters to the result of the
serialization.

```cpp
--8<-- "examples/dump.cpp"
```

Output:

```json
--8<-- "examples/dump.output"
```
11 changes: 11 additions & 0 deletions doc/mkdocs/docs/api/basic_json/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Overview

## Member functions

### Object inspection

- [dump](dump.md) - serialization

## Static functions

- [meta](meta.md) - returns version information on the library
45 changes: 45 additions & 0 deletions doc/mkdocs/docs/api/basic_json/meta.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
# basic_json::meta

```cpp
static basic_json meta();
```

This function returns a JSON object with information about the library,
including the version number and information on the platform and compiler.

## Return value

JSON object holding version information

key | description
----------- | ---------------
`compiler` | Information on the used compiler. It is an object with the following keys: `c++` (the used C++ standard), `family` (the compiler family; possible values are `clang`, `icc`, `gcc`, `ilecpp`, `msvc`, `pgcpp`, `sunpro`, and `unknown`), and `version` (the compiler version).
`copyright` | The copyright line for the library as string.
`name` | The name of the library as string.
`platform` | The used platform as string. Possible values are `win32`, `linux`, `apple`, `unix`, and `unknown`.
`url` | The URL of the project as string.
`version` | The version of the library. It is an object with the following keys: `major`, `minor`, and `patch` as defined by [Semantic Versioning](http://semver.org), and `string` (the version string).

## Exception safety

Strong guarantee: if an exception is thrown, there are no
changes to any JSON value.

## Complexity

Constant.

## Example

The following code shows an example output of the `meta()`
function.

```cpp
--8<-- "examples/meta.cpp"
```

Output:

```json
--8<-- "examples/meta.output"
```
77 changes: 77 additions & 0 deletions doc/mkdocs/docs/features/element_access/checked_access.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
# Checked access: at

## Overview

The `#!cpp at()` member function performs checked access; that is, it returns a reference to the desired value if it exists and throws a [`basic_json::out_of_range` exception](../../home/exceptions.md#out-of-range) otherwise.

??? example

Consider the following JSON value:

```json
{
"name": "Mary Smith",
"age": 42,
"hobbies": ["hiking", "reading"]
}
```

Assume the value is parsed to a `json` variable `j`.

| expression | value |
| ---------- | ----- |
| `#!cpp j` | `#!json {"name": "Mary Smith", "age": 42, "hobbies": ["hiking", "reading"]}` |
| `#!cpp j.at("name")` | `#!json "Mary Smith"` |
| `#!cpp j.at("age")` | `#!json 42` |
| `#!cpp j.at("hobbies")` | `#!json ["hiking", "reading"]` |
| `#!cpp j.at("hobbies").at(0)` | `#!json "hiking"` |
| `#!cpp j.at("hobbies").at(1)` | `#!json "reading"` |

The return value is a reference, so it can be modify the original value.

??? example

```cpp
j.at("name") = "John Smith";
```

This code produces the following JSON value:

```json
{
"name": "John Smith",
"age": 42,
"hobbies": ["hiking", "reading"]
}
```

When accessing an invalid index (i.e., and index greater than or equal to the array size) or the passed object key is non-existing, an exception is thrown.

??? example

```cpp
j.at("hobbies").at(3) = "cooking";
```

This code produces the following exception:

```
[json.exception.out_of_range.401] array index 3 is out of range
```

## Notes


!!! failure "Exceptions"

- `at` can only be used with objects (with a string argument) or with arrays (with a numeric argument). For other types, a [`basic_json::type_error`](../../home/exceptions.md#jsonexceptiontype_error304) is thrown.
- [`basic_json::out_of_range` exception](../../home/exceptions.md#out-of-range) exceptions are thrown if the provided key is not found in an object or the provided index is invalid.

## Summary

| scenario | non-const value | const value |
| -------- | ------------- | ----------- |
| access to existing object key | reference to existing value is returned | const reference to existing value is returned |
| access to valid array index | reference to existing value is returned | const reference to existing value is returned |
| access to non-existing object key | `basic_json::out_of_range` exception is thrown | `basic_json::out_of_range` exception is thrown |
| access to invalid array index | `basic_json::out_of_range` exception is thrown | `basic_json::out_of_range` exception is thrown |
32 changes: 32 additions & 0 deletions doc/mkdocs/docs/features/element_access/default_value.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
# Access with default value: value

## Overview

In many situations such as configuration files, missing values are not exceptional, but may be treated as if a default value was present.

??? example

Consider the following JSON value:

```json
{
"logOutput": "result.log",
"append": true
}
```

Assume the value is parsed to a `json` variable `j`.

| expression | value |
| ---------- | ----- |
| `#!cpp j` | `#!json {"logOutput": "result.log", "append": true}` |
| `#!cpp j.value("logOutput", "logfile.log")` | `#!json "result.log"` |
| `#!cpp j.value("append", true)` | `#!json true` |
| `#!cpp j.value("append", false)` | `#!json true` |
| `#!cpp j.value("logLevel", "verbose")` | `#!json "verbose"` |

## Note

!!! failure "Exceptions"

- `value` can only be used with objects. For other types, a [`basic_json::type_error`](../../home/exceptions.md#jsonexceptiontype_error306) is thrown.
9 changes: 9 additions & 0 deletions doc/mkdocs/docs/features/element_access/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# Overview

There are many ways elements in a JSON value can be accessed:

- unchecked access via [`operator[]`](unchecked_access.md)
- checked access via [`at`](checked_access.md)
- access with default value via [`value`](default_value.md)
- iterators
- JSON pointers
Original file line number Diff line number Diff line change
@@ -1,16 +1,6 @@
# Element Access
# Unchecked access: operator[]

There are many ways elements in a JSON value can be accessed:

- unchecked access via `operator[]`
- checked access via `at`
- checked access with default value via `value`
- iterators
- JSON pointers

## Unchecked access via `operator[]`

### Overview
## Overview

Elements in a JSON object and a JSON array can be accessed via `#!cpp operator[]` similar to a `#!cpp std::map` and a `#!cpp std::vector`, respectively.

@@ -77,7 +67,7 @@ When accessing an invalid index (i.e., and index greater than or equal to the ar
}
```

### Notes
## Notes

!!! info "Design rationale"

@@ -96,9 +86,13 @@ When accessing an invalid index (i.e., and index greater than or equal to the ar

- It is **undefined behavior** to access a const object with a non-existing key.
- It is **undefined behavior** to access a const array with an invalid index.
- In debug mode, an **assertion** will fire in both cases. You can disable assertions by defining the preprocessor symbol `#!cpp NDEBUG` or redefine the macro [`JSON_ASSERT(x)`](macros.md#json_assertx).
- In debug mode, an **assertion** will fire in both cases. You can disable assertions by defining the preprocessor symbol `#!cpp NDEBUG` or redefine the macro [`JSON_ASSERT(x)`](../macros.md#json_assertx).

!!! failure "Exceptions"

`operator[]` can only be used with objects (with a string argument) or with arrays (with a numeric argument). For other types, a [`basic_json::type_error`](../../home/exceptions.md#jsonexceptiontype_error305) is thrown.

### Summary
## Summary

| scenario | non-const value | const value |
| -------- | ------------- | ----------- |
22 changes: 16 additions & 6 deletions doc/mkdocs/mkdocs.yml
Original file line number Diff line number Diff line change
@@ -45,26 +45,35 @@ nav:
- features/binary_formats/ubjson.md
- features/binary_values.md
- features/comments.md
- features/element_access.md
- Element Access:
- features/element_access/index.md
- features/element_access/unchecked_access.md
- features/element_access/checked_access.md
- features/element_access/default_value.md
- features/iterators.md
- features/json_pointer.md
- features/json_patch.md
- features/merge_patch.md
- features/object_order.md
- Parsing:
- features/parsing/index.md
- features/parsing/parse_exceptions.md
- features/parsing/parser_callbacks.md
- features/parsing/sax_interface.md
- features/enum_conversion.md
- features/macros.md
- Parsing:
- features/parsing/index.md
- features/parsing/parse_exceptions.md
- features/parsing/parser_callbacks.md
- features/parsing/sax_interface.md
- features/types.md
- Integration:
- integration/index.md
- integration/cmake.md
- integration/package_managers.md
- Doxygen:
- doxygen/index.html
- API:
- basic_json:
- api/basic_json/index.md
- api/basic_json/dump.md
- api/basic_json/meta.md

# Extras
extra:
@@ -83,6 +92,7 @@ extra:
# Extensions
markdown_extensions:
- admonition
- def_list
- codehilite:
guess_lang: false
- toc: