diff --git a/docs/mkdocs/docs/features/binary_formats/bjdata.md b/docs/mkdocs/docs/features/binary_formats/bjdata.md index 986176c8a..a89a22885 100644 --- a/docs/mkdocs/docs/features/binary_formats/bjdata.md +++ b/docs/mkdocs/docs/features/binary_formats/bjdata.md @@ -15,7 +15,7 @@ simple processing. !!! abstract "References" - - [BJData Specification](https://neurojson.org/bjdata/draft2) + - [BJData Specification](https://neurojson.org/bjdata/draft2) ## Serialization @@ -52,38 +52,38 @@ The library uses the following mapping from JSON values types to BJData types ac !!! success "Complete mapping" - The mapping is **complete** in the sense that any JSON value type can be converted to a BJData value. + The mapping is **complete** in the sense that any JSON value type can be converted to a BJData value. - Any BJData output created by `to_bjdata` can be successfully parsed by `from_bjdata`. + Any BJData output created by `to_bjdata` can be successfully parsed by `from_bjdata`. !!! warning "Size constraints" - The following values can **not** be converted to a BJData value: + The following values can **not** be converted to a BJData value: - strings with more than 18446744073709551615 bytes, i.e., $2^{64}-1$ bytes (theoretical) !!! info "Unused BJData markers" - The following markers are not used in the conversion: + The following markers are not used in the conversion: - `Z`: no-op values are not created. - `C`: single-byte strings are serialized with `S` markers. !!! info "NaN/infinity handling" - If NaN or Infinity are stored inside a JSON number, they are serialized properly. This behavior differs from the + If NaN or Infinity are stored inside a JSON number, they are serialized properly. This behavior differs from the `dump()` function which serializes NaN or Infinity to `#!json null`. !!! info "Endianness" - A breaking difference between BJData and UBJSON is the endianness of numerical values. In BJData, all numerical data + A breaking difference between BJData and UBJSON is the endianness of numerical values. In BJData, all numerical data types (integers `UiuImlML` and floating-point values `hdD`) are stored in the little-endian (LE) byte order as opposed to big-endian as used by UBJSON. Adopting LE to store numeric records avoids unnecessary byte swapping on most modern computers where LE is used as the default byte order. !!! info "Optimized formats" - Optimized formats for containers are supported via two parameters of + Optimized formats for containers are supported via two parameters of [`to_bjdata`](../../api/basic_json/to_bjdata.md): - Parameter `use_size` adds size information to the beginning of a container and removes the closing marker. @@ -96,7 +96,7 @@ The library uses the following mapping from JSON values types to BJData types ac !!! info "ND-array optimized format" - BJData extends UBJSON's optimized array **size** marker to support ND-arrays of uniform numerical data types + BJData extends UBJSON's optimized array **size** marker to support ND-arrays of uniform numerical data types (referred to as *packed arrays*). For example, the 2-D `uint8` integer array `[[1,2],[3,4],[5,6]]`, stored as nested optimized array in UBJSON `[ [$U#i2 1 2 [$U#i2 3 4 [$U#i2 5 6 ]`, can be further compressed in BJData to `[$U#[$i#i2 2 3 1 2 3 4 5 6` or `[$U#[i2 i3] 1 2 3 4 5 6`. @@ -126,7 +126,7 @@ The library uses the following mapping from JSON values types to BJData types ac !!! info "Restrictions in optimized data types for arrays and objects" - Due to diminished space saving, hampered readability, and increased security risks, in BJData, the allowed data + Due to diminished space saving, hampered readability, and increased security risks, in BJData, the allowed data types following the `$` marker in an optimized array and object container are restricted to **non-zero-fixed-length** data types. Therefore, the valid optimized type markers can only be one of `UiuImlMLhdDC`. This also means other variable (`[{SH`) or zero-length types (`TFN`) can not be used in an optimized array or object @@ -134,7 +134,7 @@ The library uses the following mapping from JSON values types to BJData types ac !!! info "Binary values" - If the JSON data contains the binary type, the value stored is a list of integers, as suggested by the BJData + If the JSON data contains the binary type, the value stored is a list of integers, as suggested by the BJData documentation. In particular, this means that the serialization and the deserialization of JSON containing binary values into BJData and back will result in a different JSON object. @@ -179,7 +179,7 @@ The library maps BJData types to JSON value types as follows: !!! success "Complete mapping" - The mapping is **complete** in the sense that any BJData value can be converted to a JSON value. + The mapping is **complete** in the sense that any BJData value can be converted to a JSON value. ??? example diff --git a/docs/mkdocs/docs/features/binary_formats/bson.md b/docs/mkdocs/docs/features/binary_formats/bson.md index 8c7716d9b..f3b8cf18d 100644 --- a/docs/mkdocs/docs/features/binary_formats/bson.md +++ b/docs/mkdocs/docs/features/binary_formats/bson.md @@ -6,8 +6,8 @@ representation of data types that are not part of the JSON spec. For example, BS !!! abstract "References" - - [BSON Website](http://bsonspec.org) - the main source on BSON - - [BSON Specification](http://bsonspec.org/spec.html) - the specification + - [BSON Website](http://bsonspec.org) - the main source on BSON + - [BSON Specification](http://bsonspec.org/spec.html) - the specification ## Serialization diff --git a/docs/mkdocs/docs/features/binary_formats/cbor.md b/docs/mkdocs/docs/features/binary_formats/cbor.md index 3db25e2fb..2d0a1dae1 100644 --- a/docs/mkdocs/docs/features/binary_formats/cbor.md +++ b/docs/mkdocs/docs/features/binary_formats/cbor.md @@ -5,7 +5,7 @@ small code size, fairly small message size, and extensibility without the need f !!! abstract "References" - - [CBOR Website](http://cbor.io) - the main source on CBOR + - [CBOR Website](http://cbor.io) - the main source on CBOR - [CBOR Playground](http://cbor.me) - an interactive webpage to translate between JSON and CBOR - [RFC 7049](https://tools.ietf.org/html/rfc7049) - the CBOR specification @@ -62,15 +62,15 @@ see "binary" cells in the table above. !!! success "Complete mapping" - The mapping is **complete** in the sense that any JSON value type can be converted to a CBOR value. + The mapping is **complete** in the sense that any JSON value type can be converted to a CBOR value. !!! info "NaN/infinity handling" - If NaN or Infinity are stored inside a JSON number, they are serialized properly. This behavior differs from the normal JSON serialization which serializes NaN or Infinity to `null`. + If NaN or Infinity are stored inside a JSON number, they are serialized properly. This behavior differs from the normal JSON serialization which serializes NaN or Infinity to `null`. !!! info "Unused CBOR types" - The following CBOR types are not used in the conversion: + The following CBOR types are not used in the conversion: - UTF-8 strings terminated by "break" (0x7F) - arrays terminated by "break" (0x9F) @@ -150,7 +150,7 @@ The library maps CBOR types to JSON value types as follows: !!! warning "Incomplete mapping" - The mapping is **incomplete** in the sense that not all CBOR types can be converted to a JSON value. The following CBOR types are not supported and will yield parse errors: + The mapping is **incomplete** in the sense that not all CBOR types can be converted to a JSON value. The following CBOR types are not supported and will yield parse errors: - date/time (0xC0..0xC1) - bignum (0xC2..0xC3) @@ -162,7 +162,7 @@ The library maps CBOR types to JSON value types as follows: !!! warning "Object keys" - CBOR allows map keys of any type, whereas JSON only allows strings as keys in object values. Therefore, CBOR maps with keys other than UTF-8 strings are rejected. + CBOR allows map keys of any type, whereas JSON only allows strings as keys in object values. Therefore, CBOR maps with keys other than UTF-8 strings are rejected. !!! warning "Tagged items" diff --git a/docs/mkdocs/docs/features/binary_formats/messagepack.md b/docs/mkdocs/docs/features/binary_formats/messagepack.md index bbb716e7e..b2f69f174 100644 --- a/docs/mkdocs/docs/features/binary_formats/messagepack.md +++ b/docs/mkdocs/docs/features/binary_formats/messagepack.md @@ -6,8 +6,8 @@ extra byte in addition to the strings themselves. !!! abstract "References" - - [MessagePack website](https://msgpack.org) - - [MessagePack specification](https://github.com/msgpack/msgpack/blob/master/spec.md) + - [MessagePack website](https://msgpack.org) + - [MessagePack specification](https://github.com/msgpack/msgpack/blob/master/spec.md) ## Serialization @@ -52,18 +52,18 @@ specification: !!! success "Complete mapping" - The mapping is **complete** in the sense that any JSON value type can be converted to a MessagePack value. + The mapping is **complete** in the sense that any JSON value type can be converted to a MessagePack value. - Any MessagePack output created by `to_msgpack` can be successfully parsed by `from_msgpack`. + Any MessagePack output created by `to_msgpack` can be successfully parsed by `from_msgpack`. !!! warning "Size constraints" - The following values can **not** be converted to a MessagePack value: + The following values can **not** be converted to a MessagePack value: - - strings with more than 4294967295 bytes - - byte strings with more than 4294967295 bytes - - arrays with more than 4294967295 elements - - objects with more than 4294967295 elements + - strings with more than 4294967295 bytes + - byte strings with more than 4294967295 bytes + - arrays with more than 4294967295 elements + - objects with more than 4294967295 elements !!! info "NaN/infinity handling" @@ -127,7 +127,7 @@ The library maps MessagePack types to JSON value types as follows: !!! info - Any MessagePack output created by `to_msgpack` can be successfully parsed by `from_msgpack`. + Any MessagePack output created by `to_msgpack` can be successfully parsed by `from_msgpack`. ??? example diff --git a/docs/mkdocs/docs/features/binary_formats/ubjson.md b/docs/mkdocs/docs/features/binary_formats/ubjson.md index a12c2b19a..76956d60a 100644 --- a/docs/mkdocs/docs/features/binary_formats/ubjson.md +++ b/docs/mkdocs/docs/features/binary_formats/ubjson.md @@ -5,7 +5,7 @@ achieve the generality of JSON, combined with being much easier to process than !!! abstract "References" - - [UBJSON Website](http://ubjson.org) + - [UBJSON Website](http://ubjson.org) ## Serialization @@ -37,19 +37,19 @@ The library uses the following mapping from JSON values types to UBJSON types ac !!! success "Complete mapping" - The mapping is **complete** in the sense that any JSON value type can be converted to a UBJSON value. + The mapping is **complete** in the sense that any JSON value type can be converted to a UBJSON value. - Any UBJSON output created by `to_ubjson` can be successfully parsed by `from_ubjson`. + Any UBJSON output created by `to_ubjson` can be successfully parsed by `from_ubjson`. !!! warning "Size constraints" - The following values can **not** be converted to a UBJSON value: + The following values can **not** be converted to a UBJSON value: - strings with more than 9223372036854775807 bytes (theoretical) !!! info "Unused UBJSON markers" - The following markers are not used in the conversion: + The following markers are not used in the conversion: - `Z`: no-op values are not created. - `C`: single-byte strings are serialized with `S` markers. @@ -111,7 +111,7 @@ The library maps UBJSON types to JSON value types as follows: !!! success "Complete mapping" - The mapping is **complete** in the sense that any UBJSON value can be converted to a JSON value. + The mapping is **complete** in the sense that any UBJSON value can be converted to a JSON value. ??? example diff --git a/docs/mkdocs/docs/features/comments.md b/docs/mkdocs/docs/features/comments.md index c5874c9f1..61266d9ca 100644 --- a/docs/mkdocs/docs/features/comments.md +++ b/docs/mkdocs/docs/features/comments.md @@ -5,9 +5,9 @@ This library does not support comments *by default*. It does so for three reason 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. + > 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. + > 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. diff --git a/docs/mkdocs/docs/home/faq.md b/docs/mkdocs/docs/home/faq.md index 878b8a64e..dd426e073 100644 --- a/docs/mkdocs/docs/home/faq.md +++ b/docs/mkdocs/docs/home/faq.md @@ -44,7 +44,7 @@ for objects. !!! question - Can you add an option to ignore trailing commas? + Can you add an option to ignore trailing commas? This library does not support any feature which would jeopardize interoperability. @@ -53,9 +53,9 @@ This library does not support any feature which would jeopardize interoperabilit !!! 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é$')"` + - 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: @@ -124,7 +124,7 @@ Yes, see [Parsing and exceptions](../features/parsing/parse_exceptions.md). !!! question - Can I get the key of the object item that caused an exception? + Can I get the key of the object item that caused an exception? Yes, you can. Please define the symbol [`JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md) to get [extended diagnostics messages](exceptions.md#extended-diagnostic-messages). @@ -136,18 +136,18 @@ Yes, you can. Please define the symbol [`JSON_DIAGNOSTICS`](../api/macros/json_d !!! question - - It seems that precision is lost when serializing a double. - - Can I change the precision for floating-point serialization? + - 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::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::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. + The value of `std::numeric_limits::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. + The website https://float.exposed gives a good insight into the internal storage of floating-point numbers. See [this section](../features/types/number_handling.md#number-serialization) on the library's number handling for more information. @@ -157,7 +157,7 @@ See [this section](../features/types/number_handling.md#number-serialization) on !!! question - Why does the code not compile with Android SDK? + 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. @@ -174,7 +174,7 @@ The code compiles successfully with [Android NDK](https://developer.android.com/ !!! 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? + - 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). diff --git a/docs/mkdocs/docs/home/releases.md b/docs/mkdocs/docs/home/releases.md index 2cf5b3c66..5237c4259 100644 --- a/docs/mkdocs/docs/home/releases.md +++ b/docs/mkdocs/docs/home/releases.md @@ -252,18 +252,18 @@ http://nlohmann.github.io/json/doxygen/classnlohmann_1_1basic__json_a0a45fc74063 - Fixed documentation of parse function. #1473 - Suppressed warning that cannot be fixed inside the library. #1401 #1468 - Imroved package manager suppert: - - Updated Buckaroo instructions. #1495 - - Improved Meson support. #1463 - - Added Conda package manager documentation. #1430 - - Added NuGet package manager documentation. #1132 + - Updated Buckaroo instructions. #1495 + - Improved Meson support. #1463 + - Added Conda package manager documentation. #1430 + - Added NuGet package manager documentation. #1132 - Continuous Integration - - Removed unstable or deprecated Travis builders (Xcode 6.4 - 8.2) and added Xcode 10.1 builder. - - Added Clang 7 to Travis CI. - - Fixed AppVeyor x64 builds. #1374 #1414 + - Removed unstable or deprecated Travis builders (Xcode 6.4 - 8.2) and added Xcode 10.1 builder. + - Added Clang 7 to Travis CI. + - Fixed AppVeyor x64 builds. #1374 #1414 - Updated thirdparty libraries: - - Catch 1.12.0 -> 1.12.2 - - Google Benchmark 1.3.0 -> 1.4.1 - - Doxygen 1.8.15 -> 1.8.16 + - Catch 1.12.0 -> 1.12.2 + - Google Benchmark 1.3.0 -> 1.4.1 + - Doxygen 1.8.15 -> 1.8.16 ### :fire: Deprecated functions diff --git a/docs/mkdocs/docs/integration/cmake.md b/docs/mkdocs/docs/integration/cmake.md index 831e35ab9..b470319ba 100644 --- a/docs/mkdocs/docs/integration/cmake.md +++ b/docs/mkdocs/docs/integration/cmake.md @@ -119,7 +119,7 @@ automatically download a release as a dependency at configure type. ) ``` - However, the repository download size is quite large. You might want to depend on + However, the repository download size is quite large. You might want to depend on a smaller repository. For instance, you might want to replace the URL in the example by . diff --git a/docs/mkdocs/docs/integration/package_managers.md b/docs/mkdocs/docs/integration/package_managers.md index c2fb1a7f4..b9ebf075f 100644 --- a/docs/mkdocs/docs/integration/package_managers.md +++ b/docs/mkdocs/docs/integration/package_managers.md @@ -30,29 +30,29 @@ instead. See [nlohmann-json](https://formulae.brew.sh/formula/nlohmann-json) for ??? example - 1. Create the following file: + 1. Create the following file: ```cpp title="example.cpp" --8<-- "integration/example.cpp" ``` - 2. Install the package + 2. Install the package - ```sh - brew install nlohmann-json - ``` + ```sh + brew install nlohmann-json + ``` - 3. Determine the include path, which defaults to `/usr/local/Cellar/nlohmann-json/$version/include`, where `$version` is the version of the library, e.g. `3.7.3`. The path of the library can be determined with + 3. Determine the include path, which defaults to `/usr/local/Cellar/nlohmann-json/$version/include`, where `$version` is the version of the library, e.g. `3.7.3`. The path of the library can be determined with - ```sh - brew list nlohmann-json - ``` + ```sh + brew list nlohmann-json + ``` - 4. Compile the code. For instance, the code can be compiled using Clang with + 4. Compile the code. For instance, the code can be compiled using Clang with - ```sh - clang++ example.cpp -I/usr/local/Cellar/nlohmann-json/3.7.3/include -std=c++11 -o example - ``` + ```sh + clang++ example.cpp -I/usr/local/Cellar/nlohmann-json/3.7.3/include -std=c++11 -o example + ``` :material-update: The [formula](https://formulae.brew.sh/formula/nlohmann-json) is updated automatically. @@ -68,7 +68,7 @@ If you are using [Conan](https://www.conan.io/) to manage your dependencies, mer ??? example - 1. Create the following files: + 1. Create the following files: ```ini title="Conanfile.txt" --8<-- "integration/conan/Conanfile.txt" @@ -82,15 +82,15 @@ If you are using [Conan](https://www.conan.io/) to manage your dependencies, mer --8<-- "integration/conan/example.cpp" ``` - 2. Build: + 2. Build: - ```sh - mkdir build - cd build - conan install .. - cmake .. - cmake --build . - ``` + ```sh + mkdir build + cd build + conan install .. + cmake .. + cmake --build . + ``` :material-update: The [package](https://conan.io/center/nlohmann_json) is updated automatically. @@ -112,7 +112,7 @@ If you are using [vcpkg](https://github.com/Microsoft/vcpkg/) on your project fo ??? example - 1. Create the following files: + 1. Create the following files: ```cmake title="CMakeLists.txt" --8<-- "integration/vcpkg/CMakeLists.txt" @@ -128,14 +128,14 @@ If you are using [vcpkg](https://github.com/Microsoft/vcpkg/) on your project fo vcpkg install nlohmann-json ``` - 3. Build: + 3. Build: - ```sh - mkdir build - cd build - cmake .. -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake - cmake --build . - ``` + ```sh + mkdir build + cd build + cmake .. -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake + cmake --build . + ``` Note you need to adjust `/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake` to your system.