lib/json
1
0
Fork 0
mirror of https://github.com/nlohmann/json.git synced 2025-07-28 12:02:00 +03:00
Code Activity

📝 add mkdocs

Browse Source
This commit is contained in:
Niels Lohmann
2020-05-24 13:03:04 +02:00
parent c92a696852
commit a8f0cd15df
36 changed files with 2656 additions and 261 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
doc/mkdocs/docs/home/code_of_conduct.md Normal file
View File

@ -0,0 +1,46 @@
# Contributor Covenant Code of Conduct
## Our Pledge
In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
## Our Standards
Examples of behavior that contributes to creating a positive environment include:
* Using welcoming and inclusive language
* Being respectful of differing viewpoints and experiences
* Gracefully accepting constructive criticism
* Focusing on what is best for the community
* Showing empathy towards other community members
Examples of unacceptable behavior by participants include:
* The use of sexualized language or imagery and unwelcome sexual attention or advances
* Trolling, insulting/derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or electronic address, without explicit permission
* Other conduct which could reasonably be considered inappropriate in a professional setting
## Our Responsibilities
Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
## Scope
This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at mail@nlohmann.me. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
[homepage]: http://contributor-covenant.org
[version]: http://contributor-covenant.org/version/1/4/

17
doc/mkdocs/docs/home/design_goals.md Normal file
View File

@ -0,0 +1,17 @@
# Design goals
There are myriads of [JSON](https://json.org) libraries out there, and each may even have its reason to exist. Our class had these design goals:
- **Intuitive syntax**. In languages such as Python, JSON feels like a first class data type. We used all the operator magic of modern C++ to achieve the same feeling in your code. Check out the [examples below](#examples) and you'll know what I mean.
- **Trivial integration**. Our whole code consists of a single header file [`json.hpp`](https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json.hpp). That's it. No library, no subproject, no dependencies, no complex build system. The class is written in vanilla C++11. All in all, everything should require no adjustment of your compiler flags or project settings.
- **Serious testing**. Our class is heavily [unit-tested](https://github.com/nlohmann/json/tree/develop/test/src) and covers [100%](https://coveralls.io/r/nlohmann/json) of the code, including all exceptional behavior. Furthermore, we checked with [Valgrind](http://valgrind.org) and the [Clang Sanitizers](https://clang.llvm.org/docs/index.html) that there are no memory leaks. [Google OSS-Fuzz](https://github.com/google/oss-fuzz/tree/master/projects/json) additionally runs fuzz tests against all parsers 24/7, effectively executing billions of tests so far. To maintain high quality, the project is following the [Core Infrastructure Initiative (CII) best practices](https://bestpractices.coreinfrastructure.org/projects/289).
Other aspects were not so important to us:
- **Memory efficiency**. Each JSON object has an overhead of one pointer (the maximal size of a union) and one enumeration element (1 byte). The default generalization uses the following C++ data types: `std::string` for strings, `int64_t`, `uint64_t` or `double` for numbers, `std::map` for objects, `std::vector` for arrays, and `bool` for Booleans. However, you can template the generalized class `basic_json` to your needs.
- **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/master/.github/CONTRIBUTING.md#please-dont) for more information.

713
doc/mkdocs/docs/home/exceptions.md Normal file
View File

@ -0,0 +1,713 @@
# Exceptions
## Overview
### Base type
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.
### 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`. 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`).
Note that `JSON_THROW_USER` should leave the current scope (e.g., by throwing or aborting), as continuing after it may yield undefined behavior.
## Parse errors
This exception is thrown by the library when a parse error occurs. Parse errors
can occur during the deserialization of JSON text, CBOR, MessagePack, as well
as when using JSON Patch.
Exceptions have ids 1xx.
!!! info "Byte index"
Member `byte` holds the byte index of the last read character in the input
file.
For an input with n bytes, 1 is the index of the first character and n+1
is the index of the terminating null byte or the end of file. This also
holds true when reading a byte vector (CBOR or MessagePack).
### json.exception.parse_error.101
This error indicates a syntax error while deserializing a JSON text. The error message describes that an unexpected token (character) was encountered, and the member `byte` indicates the error position.
!!! example
Input ended prematurely:
```
[json.exception.parse_error.101] parse error at 2: unexpected end of input; expected string literal
```
No input:
```
[json.exception.parse_error.101] parse error at line 1, column 1: syntax error while parsing value - unexpected end of input; expected '[', '{', or a literal
```
Control character was not escaped:
```
[json.exception.parse_error.101] parse error at line 1, column 2: syntax error while parsing value - invalid string: control character U+0009 (HT) must be escaped to \u0009 or \\; last read: '"<U+0009>'"
```
String was not closed:
```
[json.exception.parse_error.101] parse error at line 1, column 2: syntax error while parsing value - invalid string: missing closing quote; last read: '"'
```
Invalid number format:
```
[json.exception.parse_error.101] parse error at line 1, column 3: syntax error while parsing value - invalid number; expected '+', '-', or digit after exponent; last read: '1E'
```
`\u` was not be followed by four hex digits:
```
[json.exception.parse_error.101] parse error at line 1, column 6: syntax error while parsing value - invalid string: '\u' must be followed by 4 hex digits; last read: '"\u01"'
```
Invalid UTF-8 surrogate pair:
```
[json.exception.parse_error.101] parse error at line 1, column 13: syntax error while parsing value - invalid string: surrogate U+DC00..U+DFFF must follow U+D800..U+DBFF; last read: '"\uD7FF\uDC00'"
```
Invalid UTF-8 byte:
```
[json.exception.parse_error.101] parse error at line 3, column 24: syntax error while parsing value - invalid string: ill-formed UTF-8 byte; last read: '"vous \352t'
```
!!! tip
- Make sure the input is correctly read. Try to write the input to standard output to check if, for instance, the input file was successfully openened.
- Paste the input to a JSON validator like <http://jsonlint.com> or a tool like [jq](https://stedolan.github.io/jq/).
### json.exception.parse_error.102
JSON uses the `\uxxxx` format to describe Unicode characters. Code points above above 0xFFFF are split into two `\uxxxx` entries ("surrogate pairs"). This error indicates that the surrogate pair is incomplete or contains an invalid code point.
!!! example
```
parse error at 14: missing or wrong low surrogate
```
### json.exception.parse_error.103
Unicode supports code points up to 0x10FFFF. Code points above 0x10FFFF are invalid.
!!! example
```
parse error: code points above 0x10FFFF are invalid
```
### json.exception.parse_error.104
[RFC 6902](https://tools.ietf.org/html/rfc6902) requires a JSON Patch document to be a JSON document that represents an array of objects.
!!! example
```
[json.exception.parse_error.104] parse error: JSON patch must be an array of objects
```
### json.exception.parse_error.105
An operation of a JSON Patch document must contain exactly one "op" member, whose value indicates the operation to perform. Its value must be one of "add", "remove", "replace", "move", "copy", or "test"; other values are errors.
!!! example
```
[json.exception.parse_error.105] parse error: operation 'add' must have member 'value'
```
```
[json.exception.parse_error.105] parse error: operation 'copy' must have string member 'from'
```
```
[json.exception.parse_error.105] parse error: operation value 'foo' is invalid
```
### json.exception.parse_error.106
An array index in a JSON Pointer ([RFC 6901](https://tools.ietf.org/html/rfc6901)) may be `0` or any number without a leading `0`.
!!! example
```
[json.exception.parse_error.106] parse error: array index '01' must not begin with '0'
```
### json.exception.parse_error.107
A JSON Pointer must be a Unicode string containing a sequence of zero or more reference tokens, each prefixed by a `/` character.
!!! example
```
[json.exception.parse_error.107] parse error at byte 1: JSON pointer must be empty or begin with '/' - was: 'foo'
```
### json.exception.parse_error.108
In a JSON Pointer, only `~0` and `~1` are valid escape sequences.
!!! example
```
[json.exception.parse_error.108] parse error: escape character '~' must be followed with '0' or '1'
```
### json.exception.parse_error.109
A JSON Pointer array index must be a number.
!!! example
```
[json.exception.parse_error.109] parse error: array index 'one' is not a number
```
```
[json.exception.parse_error.109] parse error: array index '+1' is not a number
```
### json.exception.parse_error.110
When parsing CBOR or MessagePack, the byte vector ends before the complete value has been read.
!!! example
```
[json.exception.parse_error.110] parse error at byte 5: syntax error while parsing CBOR string: unexpected end of input
```
```
[json.exception.parse_error.110] parse error at byte 2: syntax error while parsing UBJSON value: expected end of input; last byte: 0x5A
```
### json.exception.parse_error.112
Not all types of CBOR or MessagePack are supported. This exception occurs if an unsupported byte was read.
!!! example
```
[json.exception.parse_error.112] parse error at byte 1: syntax error while parsing CBOR value: invalid byte: 0x1C
```
### json.exception.parse_error.113
While parsing a map key, a value that is not a string has been read.
!!! example
```
[json.exception.parse_error.113] parse error at byte 2: syntax error while parsing CBOR string: expected length specification (0x60-0x7B) or indefinite string type (0x7F); last byte: 0xFF
```
```
[json.exception.parse_error.113] parse error at byte 2: syntax error while parsing MessagePack string: expected length specification (0xA0-0xBF, 0xD9-0xDB); last byte: 0xFF
```
```
[json.exception.parse_error.113] parse error at byte 2: syntax error while parsing UBJSON char: byte after 'C' must be in range 0x00..0x7F; last byte: 0x82
```
### json.exception.parse_error.114
The parsing of the corresponding BSON record type is not implemented (yet).
!!! example
```
[json.exception.parse_error.114] parse error at byte 5: Unsupported BSON record type 0xFF
```
## Iterator errors
This exception is thrown if iterators passed to a library function do not match
the expected semantics.
Exceptions have ids 2xx.
### json.exception.invalid_iterator.201
The iterators passed to constructor `basic_json(InputIT first, InputIT last)` are not compatible, meaning they do not belong to the same container. Therefore, the range (`first`, `last`) is invalid.
!!! example
```
[json.exception.invalid_iterator.201] iterators are not compatible
```
### json.exception.invalid_iterator.202
In an erase or insert function, the passed iterator @a pos does not belong to the JSON value for which the function was called. It hence does not define a valid position for the deletion/insertion.
!!! example
```
[json.exception.invalid_iterator.202] iterator does not fit current value
```
```
[json.exception.invalid_iterator.202] iterators first and last must point to objects
```
### json.exception.invalid_iterator.203
Either iterator passed to function `erase(IteratorType` first, IteratorType last) does not belong to the JSON value from which values shall be erased. It hence does not define a valid range to delete values from.
!!! example
```
[json.exception.invalid_iterator.203] iterators do not fit current value
```
### json.exception.invalid_iterator.204
When an iterator range for a primitive type (number, boolean, or string) is passed to a constructor or an erase function, this range has to be exactly (`begin(),` `end()),` because this is the only way the single stored value is expressed. All other ranges are invalid.
!!! example
```
[json.exception.invalid_iterator.204] iterators out of range
```
### json.exception.invalid_iterator.205
When an iterator for a primitive type (number, boolean, or string) is passed to an erase function, the iterator has to be the `begin()` iterator, because it is the only way to address the stored value. All other iterators are invalid.
!!! example
```
[json.exception.invalid_iterator.205] iterator out of range
```
### json.exception.invalid_iterator.206
The iterators passed to constructor `basic_json(InputIT first, InputIT last)` belong to a JSON null value and hence to not define a valid range.
!!! example
```
[json.exception.invalid_iterator.206] cannot construct with iterators from null
```
### json.exception.invalid_iterator.207
The `key()` member function can only be used on iterators belonging to a JSON object, because other types do not have a concept of a key.
!!! example
```
[json.exception.invalid_iterator.207] cannot use key() for non-object iterators
```
### json.exception.invalid_iterator.208
The `operator[]` to specify a concrete offset cannot be used on iterators belonging to a JSON object, because JSON objects are unordered.
!!! example
```
[json.exception.invalid_iterator.208] cannot use operator[] for object iterators
```
### json.exception.invalid_iterator.209
The offset operators (`+`, `-`, `+=`, `-=`) cannot be used on iterators belonging to a JSON object, because JSON objects are unordered.
!!! example
```
[json.exception.invalid_iterator.209] cannot use offsets with object iterators
```
### json.exception.invalid_iterator.210
The iterator range passed to the insert function are not compatible, meaning they do not belong to the same container. Therefore, the range (`first`, `last`) is invalid.
!!! example
```
[json.exception.invalid_iterator.210] iterators do not fit
```
### json.exception.invalid_iterator.211
The iterator range passed to the insert function must not be a subrange of the container to insert to.
!!! example
```
[json.exception.invalid_iterator.211] passed iterators may not belong to container
```
### json.exception.invalid_iterator.212
When two iterators are compared, they must belong to the same container.
!!! example
```
[json.exception.invalid_iterator.212] cannot compare iterators of different containers
```
### json.exception.invalid_iterator.213
The order of object iterators cannot be compared, because JSON objects are unordered.
!!! example
```
[json.exception.invalid_iterator.213] cannot compare order of object iterators
```
### json.exception.invalid_iterator.214
Cannot get value for iterator: Either the iterator belongs to a null value or it is an iterator to a primitive type (number, boolean, or string), but the iterator is different to `begin()`.
!!! example
```
[json.exception.invalid_iterator.214] cannot get value
```
## Type errors
This exception is thrown in case of a type error; that is, a library function is executed on a JSON value whose type does not match the expected semantics.
Exceptions have ids 3xx.
### json.exception.type_error.301
To create an object from an initializer list, the initializer list must consist only of a list of pairs whose first element is a string. When this constraint is violated, an array is created instead.
!!! example
```
[json.exception.type_error.301] cannot create object from initializer list
```
### json.exception.type_error.302
During implicit or explicit value conversion, the JSON type must be compatible to the target type. For instance, a JSON string can only be converted into string types, but not into numbers or boolean types.
!!! example
```
[json.exception.type_error.302] type must be object, but is null
```
```
[json.exception.type_error.302] type must be string, but is object
```
### json.exception.type_error.303
To retrieve a reference to a value stored in a `basic_json` object with `get_ref`, the type of the reference must match the value type. For instance, for a JSON array, the `ReferenceType` must be `array_t &`.
!!! example
```
[json.exception.type_error.303] incompatible ReferenceType for get_ref, actual type is object
```
```
[json.exception.type_error.303] incompatible ReferenceType for get_ref, actual type is number"
```
### json.exception.type_error.304
The `at()` member functions can only be executed for certain JSON types.
!!! example
```
[json.exception.type_error.304] cannot use at() with string
```
```
[json.exception.type_error.304] cannot use at() with number
```
### json.exception.type_error.305
The `operator[]` member functions can only be executed for certain JSON types.
!!! example
```
[json.exception.type_error.305] cannot use operator[] with a string argument with array
```
```
[json.exception.type_error.305] cannot use operator[] with a numeric argument with object
```
### json.exception.type_error.306
The `value()` member functions can only be executed for certain JSON types.
!!! example
```
[json.exception.type_error.306] cannot use value() with number
```
### json.exception.type_error.307
The `erase()` member functions can only be executed for certain JSON types.
!!! example
```
[json.exception.type_error.307] cannot use erase() with string
```
### json.exception.type_error.308
The `push_back()` and `operator+=` member functions can only be executed for certain JSON types.
!!! example
```
[json.exception.type_error.308] cannot use push_back() with string
```
### json.exception.type_error.309
The `insert()` member functions can only be executed for certain JSON types.
!!! example
```
[json.exception.type_error.309] cannot use insert() with array
```
```
[json.exception.type_error.309] cannot use insert() with number
```
### json.exception.type_error.310
The `swap()` member functions can only be executed for certain JSON types.
!!! example
```
[json.exception.type_error.310] cannot use swap() with number
```
### json.exception.type_error.311
The `emplace()` and `emplace_back()` member functions can only be executed for certain JSON types.
!!! example
```
[json.exception.type_error.311] cannot use emplace() with number
```
```
[json.exception.type_error.311] cannot use emplace_back() with number
```
### json.exception.type_error.312
The `update()` member functions can only be executed for certain JSON types.
!!! example
```
[json.exception.type_error.312] cannot use update() with array
```
### json.exception.type_error.313
The `unflatten` function converts an object whose keys are JSON Pointers back into an arbitrary nested JSON value. The JSON Pointers must not overlap, because then the resulting value would not be well defined.
!!! example
```
[json.exception.type_error.313] invalid value to unflatten
```
### json.exception.type_error.314
The `unflatten` function only works for an object whose keys are JSON Pointers.
!!! example
Calling `unflatten()` on an array `#!json [1,2,3]`:
```
[json.exception.type_error.314] only objects can be unflattened
```
### json.exception.type_error.315
The `unflatten()` function only works for an object whose keys are JSON Pointers and whose values are primitive.
!!! example
Calling `unflatten()` on an object `#!json {"/1", [1,2,3]}`:
```
[json.exception.type_error.315] values in object must be primitive
```
### json.exception.type_error.316
The `dump()` function only works with UTF-8 encoded strings; that is, if you assign a `std::string` to a JSON value, make sure it is UTF-8 encoded.
!!! example
Calling `dump()` on a JSON value containing an ISO 8859-1 encoded string:
```
[json.exception.type_error.316] invalid UTF-8 byte at index 15: 0x6F
```
!!! tip
- Store the source file with UTF-8 encoding.
- Pass an error handler as last parameter to the `dump()` function to avoid this exception:
- `json::error_handler_t::replace` will replace invalid bytes sequences with `U+FFFD`
- `json::error_handler_t::ignore` will silently ignore invalid byte sequences
### json.exception.type_error.317
The dynamic type of the object cannot be represented in the requested serialization format (e.g. a raw `true` or `null` JSON object cannot be serialized to BSON)
!!! example
Serializing `#!json null` to BSON:
```
[json.exception.type_error.317] to serialize to BSON, top-level type must be object, but is null
```
Serializing `#!json [1,2,3]` to BSON:
```
[json.exception.type_error.317] to serialize to BSON, top-level type must be object, but is array
```
!!! tip
Encapsulate the JSON value in an object. That is, instead of serializing `#!json true`, serialize `#!json {"value": true}`
## Out of range
This exception is thrown in case a library function is called on an input parameter that exceeds the expected range, for instance in case of array indices or nonexisting object keys.
Exceptions have ids 4xx.
### json.exception.out_of_range.401
The provided array index `i` is larger than `size-1`.
!!! example
```
array index 3 is out of range
```
### json.exception.out_of_range.402
The special array index `-` in a JSON Pointer never describes a valid element of the array, but the index past the end. That is, it can only be used to add elements at this position, but not to read it.
!!! example
```
array index '-' (3) is out of range
```
### json.exception.out_of_range.403
The provided key was not found in the JSON object.
!!! example
```
key 'foo' not found
```
### json.exception.out_of_range.404
A reference token in a JSON Pointer could not be resolved.
!!! example
```
unresolved reference token 'foo'
```
### json.exception.out_of_range.405
The JSON Patch operations 'remove' and 'add' can not be applied to the root element of the JSON value.
!!! example
```
JSON pointer has no parent
```
### json.exception.out_of_range.406
A parsed number could not be stored as without changing it to NaN or INF.
!!! example
```
number overflow parsing '10E1000'
```
### json.exception.out_of_range.407
UBJSON and BSON only support integer numbers up to 9223372036854775807.
!!! example
```
number overflow serializing '9223372036854775808'
```
### json.exception.out_of_range.408
The size (following `#`) of an UBJSON array or object exceeds the maximal capacity.
!!! example
```
excessive array size: 8658170730974374167
```
### json.exception.out_of_range.409
Key identifiers to be serialized to BSON cannot contain code point U+0000, since the key is stored as zero-terminated c-string.
!!! example
```
BSON key cannot contain code point U+0000 (at byte 2)
```
## Further exceptions
This exception is thrown in case of errors that cannot be classified with the
other exception types.
Exceptions have ids 5xx.
### json.exception.other_error.501
A JSON Patch operation 'test' failed. The unsuccessful operation is also printed.
!!! example
Executing `#!json {"op":"test", "path":"/baz", "value":"bar"}` on `#!json {"baz": "qux"}`:
```
[json.exception.other_error.501] unsuccessful: {"op":"test","path":"/baz","value":"bar"}
```

128
doc/mkdocs/docs/home/faq.md Normal file
View File

@ -0,0 +1,128 @@
# Frequently Asked Questions (FAQ)
## Limitations
### Comments
!!! question "Questions"
- Why does the library not support comments?
- Can you add support for JSON5/JSONC/HOCON so that comments are supported?
This library does not support comments. It does so for three reasons:
1. Comments are not part of the [JSON specification](https://tools.ietf.org/html/rfc8259). You may argue that `//` or `/* */` are allowed in JavaScript, but JSON is not JavaScript.
2. This was not an oversight: Douglas Crockford [wrote on this](https://plus.google.com/118095276221607585885/posts/RK8qyGVaGSr) in May 2012:
> I removed comments from JSON because I saw people were using them to hold parsing directives, a practice which would have destroyed interoperability. I know that the lack of comments makes some people sad, but it shouldn't.
> Suppose you are using JSON to keep configuration files, which you would like to annotate. Go ahead and insert all the comments you like. Then pipe it through JSMin before handing it to your JSON parser.
3. It is dangerous for interoperability if some libraries would add comment support while others don't. Please check [The Harmful Consequences of the Robustness Principle](https://tools.ietf.org/html/draft-iab-protocol-maintenance-01) on this.
This library will not support comments in the future. If you wish to use comments, I see three options:
1. Strip comments before using this library.
2. Use a different JSON library with comment support.
3. Use a format that natively supports comments (e.g., YAML or JSON5).
### Relaxed parsing
!!! question
- Can you add an option to ignore trailing commas?
For the same reason this library does not support [comments](#comments), this library also does not support any feature which would jeopardize interoperability.
### Parse errors reading non-ASCII characters
!!! question "Questions"
- Why is the parser complaining about a Chinese character?
- Does the library support Unicode?
- I get an exception `[json.exception.parse_error.101] parse error at line 1, column 53: syntax error while parsing value - invalid string: ill-formed UTF-8 byte; last read: '"Testé$')"`
The library supports **Unicode input** as follows:
- Only **UTF-8** encoded input is supported which is the default encoding for JSON according to [RFC 8259](https://tools.ietf.org/html/rfc8259.html#section-8.1).
- `std::u16string` and `std::u32string` can be parsed, assuming UTF-16 and UTF-32 encoding, respectively. These encodings are not supported when reading from files or other input containers.
- Other encodings such as Latin-1 or ISO 8859-1 are **not** supported and will yield parse or serialization errors.
- [Unicode noncharacters](http://www.unicode.org/faq/private_use.html#nonchar1) will not be replaced by the library.
- Invalid surrogates (e.g., incomplete pairs such as `\uDEAD`) will yield parse errors.
- The strings stored in the library are UTF-8 encoded. When using the default string type (`std::string`), note that its length/size functions return the number of stored bytes rather than the number of characters or glyphs.
- When you store strings with different encodings in the library, calling [`dump()`](https://nlohmann.github.io/json/classnlohmann_1_1basic__json_a50ec80b02d0f3f51130d4abb5d1cfdc5.html#a50ec80b02d0f3f51130d4abb5d1cfdc5) may throw an exception unless `json::error_handler_t::replace` or `json::error_handler_t::ignore` are used as error handlers.
In most cases, the parser is right to complain, because the input is not UTF-8 encoded. This is especially true for Microsoft Windows where Latin-1 or ISO 8859-1 is often the standard encoding.
### Key name in exceptions
!!! question
Can I get the key of the object item that caused an exception?
No, this is not possible. See <https://github.com/nlohmann/json/issues/932> for a longer discussion.
## Serialization issues
### Order of object keys
!!! question "Questions"
- Why are object keys sorted?
- Why is the insertion order of object keys not preserved?
By default, the library does not preserve the **insertion order of object elements**. This is standards-compliant, as the [JSON standard](https://tools.ietf.org/html/rfc8259.html) defines objects as "an unordered collection of zero or more name/value pairs".
If you do want to preserve the insertion order, you can specialize the object type with containers like [`tsl::ordered_map`](https://github.com/Tessil/ordered-map) ([integration](https://github.com/nlohmann/json/issues/546#issuecomment-304447518)) or [`nlohmann::fifo_map`](https://github.com/nlohmann/fifo_map) ([integration](https://github.com/nlohmann/json/issues/485#issuecomment-333652309)).
### Number precision
!!! question
- It seems that precision is lost when serializing a double.
- Can I change the precision for floating-point serialization?
The library uses `std::numeric_limits<number_float_t>::digits10` (15 for IEEE `double`s) digits for serialization. This value is sufficient to guarantee roundtripping. If one uses more than this number of digits of precision, then string -> value -> string is not guaranteed to round-trip.
!!! quote "[cppreference.com](https://en.cppreference.com/w/cpp/types/numeric_limits/digits10)"
The value of `std::numeric_limits<T>::digits10` is the number of base-10 digits that can be represented by the type T without change, that is, any number with this many significant decimal digits can be converted to a value of type T and back to decimal form, without change due to rounding or overflow.
!!! tip
The website https://float.exposed gives a good insight into the internal storage of floating-point numbers.
## Compilation issues
### Android SDK
!!! question
Why does the code not compile with Android SDK?
Android defaults to using very old compilers and C++ libraries. To fix this, add the following to your `Application.mk`. This will switch to the LLVM C++ library, the Clang compiler, and enable C++11 and other features disabled by default.
```ini
APP_STL := c++_shared
NDK_TOOLCHAIN_VERSION := clang3.6
APP_CPPFLAGS += -frtti -fexceptions
```
The code compiles successfully with [Android NDK](https://developer.android.com/ndk/index.html?hl=ml), Revision 9 - 11 (and possibly later) and [CrystaX's Android NDK](https://www.crystax.net/en/android/ndk) version 10.
### Missing STL function
!!! question "Questions"
- Why do I get a compilation error `'to_string' is not a member of 'std'` (or similarly, for `strtod` or `strtof`)?
- Why does the code not compile with MinGW or Android SDK?
This is not an issue with the code, but rather with the compiler itself. On Android, see above to build with a newer environment. 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. For Android NDK using `APP_STL := gnustl_static`, please refer to [this discussion](https://github.com/nlohmann/json/issues/219).

21
doc/mkdocs/docs/home/license.md Normal file
View File

@ -0,0 +1,21 @@
# License
<img align="right" src="http://opensource.org/trademarks/opensource/OSI-Approved-License-100x137.png">
The class is licensed under the [MIT License](http://opensource.org/licenses/MIT):
Copyright &copy; 2013-2019 [Niels Lohmann](http://nlohmann.me)
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
* * *
The class contains the UTF-8 Decoder from Bjoern Hoehrmann which is licensed under the [MIT License](http://opensource.org/licenses/MIT) (see above). Copyright &copy; 2008-2009 [Björn Hoehrmann](http://bjoern.hoehrmann.de/) <bjoern@hoehrmann.de>
The class contains a slightly modified version of the Grisu2 algorithm from Florian Loitsch which is licensed under the [MIT License](http://opensource.org/licenses/MIT) (see above). Copyright &copy; 2009 [Florian Loitsch](http://florian.loitsch.com/)
The class contains a copy of [Hedley](https://nemequ.github.io/hedley/) from Evan Nemerson which is licensed as [CC0-1.0](http://creativecommons.org/publicdomain/zero/1.0/).

11
doc/mkdocs/docs/home/sponsors.md Normal file
View File

@ -0,0 +1,11 @@
# Sponsors
You can sponsor this library at [GitHub Sponsors](https://github.com/sponsors/nlohmann).
## Named Sponsors
- [Michael Hartmann](https://github.com/reFX-Mike)
- [Stefan Hagen](https://github.com/sthagen)
- [Steve Sperandeo](https://github.com/homer6)
Thanks everyone!