From 6e5be17b624f2ef4054dcdd057110882990ad3a6 Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Sat, 25 Jul 2020 14:40:50 +0200 Subject: [PATCH] :memo: add more documentation --- doc/mkdocs/docs/api/basic_json/dump.md | 72 +++++++++++++++++ doc/mkdocs/docs/api/basic_json/index.md | 11 +++ doc/mkdocs/docs/api/basic_json/meta.md | 45 +++++++++++ .../features/element_access/checked_access.md | 77 +++++++++++++++++++ .../features/element_access/default_value.md | 32 ++++++++ .../docs/features/element_access/index.md | 9 +++ .../unchecked_access.md} | 24 +++--- doc/mkdocs/mkdocs.yml | 22 ++++-- 8 files changed, 271 insertions(+), 21 deletions(-) create mode 100644 doc/mkdocs/docs/api/basic_json/dump.md create mode 100644 doc/mkdocs/docs/api/basic_json/index.md create mode 100644 doc/mkdocs/docs/api/basic_json/meta.md create mode 100644 doc/mkdocs/docs/features/element_access/checked_access.md create mode 100644 doc/mkdocs/docs/features/element_access/default_value.md create mode 100644 doc/mkdocs/docs/features/element_access/index.md rename doc/mkdocs/docs/features/{element_access.md => element_access/unchecked_access.md} (90%) diff --git a/doc/mkdocs/docs/api/basic_json/dump.md b/doc/mkdocs/docs/api/basic_json/dump.md new file mode 100644 index 00000000..73d6b428 --- /dev/null +++ b/doc/mkdocs/docs/api/basic_json/dump.md @@ -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" +``` diff --git a/doc/mkdocs/docs/api/basic_json/index.md b/doc/mkdocs/docs/api/basic_json/index.md new file mode 100644 index 00000000..f34c20f9 --- /dev/null +++ b/doc/mkdocs/docs/api/basic_json/index.md @@ -0,0 +1,11 @@ +# Overview + +## Member functions + +### Object inspection + +- [dump](dump.md) - serialization + +## Static functions + +- [meta](meta.md) - returns version information on the library diff --git a/doc/mkdocs/docs/api/basic_json/meta.md b/doc/mkdocs/docs/api/basic_json/meta.md new file mode 100644 index 00000000..fd577545 --- /dev/null +++ b/doc/mkdocs/docs/api/basic_json/meta.md @@ -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" +``` diff --git a/doc/mkdocs/docs/features/element_access/checked_access.md b/doc/mkdocs/docs/features/element_access/checked_access.md new file mode 100644 index 00000000..095dff2d --- /dev/null +++ b/doc/mkdocs/docs/features/element_access/checked_access.md @@ -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 | diff --git a/doc/mkdocs/docs/features/element_access/default_value.md b/doc/mkdocs/docs/features/element_access/default_value.md new file mode 100644 index 00000000..02b4fea3 --- /dev/null +++ b/doc/mkdocs/docs/features/element_access/default_value.md @@ -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. diff --git a/doc/mkdocs/docs/features/element_access/index.md b/doc/mkdocs/docs/features/element_access/index.md new file mode 100644 index 00000000..1755fe8c --- /dev/null +++ b/doc/mkdocs/docs/features/element_access/index.md @@ -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 diff --git a/doc/mkdocs/docs/features/element_access.md b/doc/mkdocs/docs/features/element_access/unchecked_access.md similarity index 90% rename from doc/mkdocs/docs/features/element_access.md rename to doc/mkdocs/docs/features/element_access/unchecked_access.md index b6976970..f8667c81 100644 --- a/doc/mkdocs/docs/features/element_access.md +++ b/doc/mkdocs/docs/features/element_access/unchecked_access.md @@ -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). -### Summary +!!! 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 | scenario | non-const value | const value | | -------- | ------------- | ----------- | diff --git a/doc/mkdocs/mkdocs.yml b/doc/mkdocs/mkdocs.yml index 962f5fd5..d3799bdc 100644 --- a/doc/mkdocs/mkdocs.yml +++ b/doc/mkdocs/mkdocs.yml @@ -45,19 +45,23 @@ 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 @@ -65,6 +69,11 @@ nav: - 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: