Skip to content

J
json
Unverified Commit a8f0cd15 authored by Niels Lohmann's avatar Niels Lohmann
Browse files
Options

📝 add mkdocs

parent c92a6968
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 2656 additions and 261 deletions
.gitignore
View file @ a8f0cd15
...@@ -26,3 +26,7 @@ cmake-build-debug ...@@ -26,3 +26,7 @@ cmake-build-debug
test/test-* test/test-*
/.vs /.vs
doc/mkdocs/venv/
doc/mkdocs/docs/images
doc/mkdocs/docs/examples
doc/Doxyfile
View file @ a8f0cd15
...@@ -110,9 +110,7 @@ WARN_LOGFILE = ...@@ -110,9 +110,7 @@ WARN_LOGFILE =
# Configuration options related to the input files # Configuration options related to the input files
#--------------------------------------------------------------------------- #---------------------------------------------------------------------------
INPUT = ../single_include/nlohmann/json.hpp \ INPUT = ../single_include/nlohmann/json.hpp \
index.md \ index.md
faq.md \
binary_formats.md
INPUT_ENCODING = UTF-8 INPUT_ENCODING = UTF-8
FILE_PATTERNS = FILE_PATTERNS =
RECURSIVE = NO RECURSIVE = NO
......
doc/binary_formats.md deleted 100644 → 0
View file @ c92a6968
# Binary formats
![conversion between JSON and binary formats](images/binary.png)
Several formats exist that encode JSON values in a binary format to reduce the size of the encoded value as well as the required effort to parse encoded value. The library implements three formats, namely
- [CBOR](https://tools.ietf.org/html/rfc7049) (Concise Binary Object Representation)
- [MessagePack](https://msgpack.org)
- [UBJSON](http://ubjson.org) (Universal Binary JSON)
## Interface
### JSON to binary format
For each format, the `to_*` functions (i.e., `to_cbor`, `to_msgpack`, and `to_ubjson`) convert a JSON value into the respective binary format. Taking CBOR as example, the concrete prototypes are:
```cpp
static std::vector<uint8_t> to_cbor(const basic_json& j); // 1
static void to_cbor(const basic_json& j, detail::output_adapter<uint8_t> o); // 2
static void to_cbor(const basic_json& j, detail::output_adapter<char> o); // 3
```
The first function creates a byte vector from the given JSON value. The second and third function writes to an output adapter of `uint8_t` and `char`, respectively. Output adapters are implemented for strings, output streams, and vectors.
Given a JSON value `j`, the following calls are possible:
```cpp
std::vector<uint8_t> v;
v = json::to_cbor(j); // 1
json::to_cbor(j, v); // 2
std::string s;
json::to_cbor(j, s); // 3
std::ostringstream oss;
json::to_cbor(j, oss); // 3
```
### Binary format to JSON
Likewise, the `from_*` functions (i.e, `from_cbor`, `from_msgpack`, and `from_ubjson`) convert a binary encoded value into a JSON value. Taking CBOR as example, the concrete prototypes are:
```cpp
static basic_json from_cbor(detail::input_adapter i, const bool strict = true); // 1
static basic_json from_cbor(A1 && a1, A2 && a2, const bool strict = true); // 2
```
Both functions read from an input adapter: the first function takes it directly form argument `i`, whereas the second function creates it from the provided arguments `a1` and `a2`. If the optional parameter `strict` is true, the input must be read completely (or a parse error exception is thrown). If it is false, parsing succeeds even if the input is not completely read.
Input adapters are implemented for input streams, character buffers, string literals, and iterator ranges.
Given several inputs (which we assume to be filled with a CBOR value), the following calls are possible:
```cpp
std::string s;
json j1 = json::from_cbor(s); // 1
std::ifstream is("somefile.cbor", std::ios::binary);
json j2 = json::from_cbor(is); // 1
std::vector<uint8_t> v;
json j3 = json::from_cbor(v); // 1
const char* buff;
std::size_t buff_size;
json j4 = json::from_cbor(buff, buff_size); // 2
```
## Details
### CBOR
The mapping from CBOR to JSON 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 (parse_error.112):
- byte strings (0x40..0x5F)
- date/time (0xC0..0xC1)
- bignum (0xC2..0xC3)
- decimal fraction (0xC4)
- bigfloat (0xC5)
- tagged items (0xC6..0xD4, 0xD8..0xDB)
- expected conversions (0xD5..0xD7)
- simple values (0xE0..0xF3, 0xF8)
- undefined (0xF7)
CBOR further 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 (parse_error.113).
The mapping from JSON to CBOR is **complete** in the sense that any JSON value type can be converted to a CBOR value.
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 null.
The following CBOR types are not used in the conversion:
- byte strings (0x40..0x5F)
- UTF-8 strings terminated by "break" (0x7F)
- arrays terminated by "break" (0x9F)
- maps terminated by "break" (0xBF)
- date/time (0xC0..0xC1)
- bignum (0xC2..0xC3)
- decimal fraction (0xC4)
- bigfloat (0xC5)
- tagged items (0xC6..0xD4, 0xD8..0xDB)
- expected conversions (0xD5..0xD7)
- simple values (0xE0..0xF3, 0xF8)
- undefined (0xF7)
- half and single-precision floats (0xF9-0xFA)
- break (0xFF)
### MessagePack
The mapping from MessagePack to JSON is **incomplete** in the sense that not all MessagePack types can be converted to a JSON value. The following MessagePack types are not supported and will yield parse errors:
- bin 8 - bin 32 (0xC4..0xC6)
- ext 8 - ext 32 (0xC7..0xC9)
- fixext 1 - fixext 16 (0xD4..0xD8)
The mapping from JSON to MessagePack is **complete** in the sense that any JSON value type can be converted to a MessagePack value.
The following values can not be converted to a MessagePack value:
- strings with more than 4294967295 bytes
- arrays with more than 4294967295 elements
- objects with more than 4294967295 elements
The following MessagePack types are not used in the conversion:
- bin 8 - bin 32 (0xC4..0xC6)
- ext 8 - ext 32 (0xC7..0xC9)
- float 32 (0xCA)
- fixext 1 - fixext 16 (0xD4..0xD8)
Any MessagePack output created `to_msgpack` can be successfully parsed by `from_msgpack`.
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 `null`.
### UBJSON
The mapping from UBJSON to JSON is **complete** in the sense that any UBJSON value can be converted to a JSON value.
The mapping from JSON to UBJSON is **complete** in the sense that any JSON value type can be converted to a UBJSON value.
The following values can not be converted to a UBJSON value:
- strings with more than 9223372036854775807 bytes (theoretical)
- unsigned integer numbers above 9223372036854775807
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.
Any UBJSON output created to_ubjson can be successfully parsed by from_ubjson.
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 null.
The optimized formats for containers are supported: Parameter `use_size` adds size information to the beginning of a container and removes the closing marker. Parameter `use_type` further checks whether all elements of a container have the same type and adds the type marker to the beginning of the container. The `use_type` parameter must only be used together with `use_size = true`. Note that `use_size = true` alone may result in larger representations - the benefit of this parameter is that the receiving side is immediately informed on the number of elements of the container.
## Size comparison examples
The following table shows the size compared to the original JSON value for different files from the repository for the different formats.
| format | sample.json | all_unicode.json | floats.json | signed_ints.json | jeopardy.json | canada.json |
| ----------------------- | -----------:| ----------------:| -----------:| ----------------:| -------------:| -----------:|
| JSON | 100.00 % | 100.00 % | 100.00 % | 100.00 % | 100.00 % | 100.00 % |
| CBOR | 87.21 % | 71.18 % | 48.20 % | 44.16 % | 87.96 % | 50.53 % |
| MessagePack | 87.16 % | 71.18 % | 48.20 % | 44.16 % | 87.91 % | 50.56 % |
| UBJSON unoptimized | 88.15 % | 100.00 % | 48.20 % | 44.16 % | 96.58 % | 53.20 % |
| UBJSON size-optimized | 89.26 % | 100.00 % | 48.20 % | 44.16 % | 97.40 % | 58.56 % |
| UBJSON format-optimized | 89.45 % | 100.00 % | 42.85 % | 39.26 % | 94.96 % | 55.93 % |
The results show that there does not exist a "best" encoding. Furthermore, it is not always worthwhile to use UBJSON's optimizations.
doc/examples/swap__binary_t.link 0 → 100644
View file @ a8f0cd15
<a target="_blank" href="https://wandbox.org/permlink/nx6mKoJomD0M6JGq"><b>online</b></a>
\ No newline at end of file
doc/faq.md deleted 100644 → 0
View file @ c92a6968
# FAQ
## Parsing
### How can I parse from a string?
```cpp
json j = json::parse("[1,2,3,4]");
```
You can pass string literals (as above), `std::string`, `const char*` or byte containers such as `std::vector<uint8_t>`.
### How can I parse from a file?
```cpp
std::ifstream i("your_file.json");
json j = json::parse(i);
```
## Serialization
### How can I serialize a JSON value
```cpp
std::cout << j << std::endl;
```
This is equivalent to
```cpp
std::string s = j.dump();
std::cout << s << std::endl;
```
### How can I pretty-print a JSON value
```cpp
std::cout << std::setw(4) << j << std::endl;
```
This is equivalent to
```cpp
std::string s = j.dump(4);
std::cout << s << std::endl;
```
The number `4` denotes the number of spaces used for indentation.
## Iterating
### How can I iterate over a JSON value?
```cpp
for (json& val : j)
{
// val is a reference for the current value
}
```
This works with any JSON value, also primitive values like numbers.
### How can I access the keys when iterating over a JSON object?
```cpp
for (auto it = j.begin(); it != j.end(); ++it)
{
// the value
json &val = it.value();
// the key (for objects)
const std::string &key = it.key();
}
```
You can also use an iteration wrapper and use range for:
```cpp
for (auto it : json::iteration_wrapper(j))
{
// the value
json &val = it.value();
// the key (for objects)
const std::string &key = it.key();
}
```
doc/mkdocs/Makefile 0 → 100644
View file @ a8f0cd15
serve: prepare_files
venv/bin/mkdocs serve
prepare_files:
# build Doxygen
$(MAKE) -C ..
# clean subfolders
rm -fr docs/images docs/examples
# create subfolders
mkdir docs/images docs/examples
# copy images
cp -vr ../json.gif docs/images
# copy examples
cp -vr ../examples/*.cpp ../examples/*.output docs/examples
publish: prepare_files
venv/bin/mkdocs gh-deploy --clean --force
install_venv:
python3 -mvenv venv
venv/bin/pip install -r requirements.txt
uninstall_venv:
rm -fr venv
doc/mkdocs/docs/features/arbitrary_types.md 0 → 100644
View file @ a8f0cd15
# Arbitrary Types Conversions
Every type can be serialized in JSON, not just STL containers and scalar types. Usually, you would do something along those lines:
```cpp
namespace ns {
// a simple struct to model a person
struct person {
std::string name;
std::string address;
int age;
};
}
ns::person p = {"Ned Flanders", "744 Evergreen Terrace", 60};
// convert to JSON: copy each value into the JSON object
json j;
j["name"] = p.name;
j["address"] = p.address;
j["age"] = p.age;
// ...
// convert from JSON: copy each value from the JSON object
ns::person p {
j["name"].get<std::string>(),
j["address"].get<std::string>(),
j["age"].get<int>()
};
```
It works, but that's quite a lot of boilerplate... Fortunately, there's a better way:
```cpp
// create a person
ns::person p {"Ned Flanders", "744 Evergreen Terrace", 60};
// conversion: person -> json
json j = p;
std::cout << j << std::endl;
// {"address":"744 Evergreen Terrace","age":60,"name":"Ned Flanders"}
// conversion: json -> person
auto p2 = j.get<ns::person>();
// that's it
assert(p == p2);
```
## Basic usage
To make this work with one of your types, you only need to provide two functions:
```cpp
using nlohmann::json;
namespace ns {
void to_json(json& j, const person& p) {
j = json{ {"name", p.name}, {"address", p.address}, {"age", p.age} };
}
void from_json(const json& j, person& p) {
j.at("name").get_to(p.name);
j.at("address").get_to(p.address);
j.at("age").get_to(p.age);
}
} // namespace ns
```
That's all! When calling the `json` constructor with your type, your custom `to_json` method will be automatically called.
Likewise, when calling `get<your_type>()` or `get_to(your_type&)`, the `from_json` method will be called.
Some important things:
* Those methods **MUST** be in your type's namespace (which can be the global namespace), or the library will not be able to locate them (in this example, they are in namespace `ns`, where `person` is defined).
* Those methods **MUST** be available (e.g., proper headers must be included) everywhere you use these conversions. Look at [issue 1108](https://github.com/nlohmann/json/issues/1108) for errors that may occur otherwise.
* When using `get<your_type>()`, `your_type` **MUST** be [DefaultConstructible](https://en.cppreference.com/w/cpp/named_req/DefaultConstructible). (There is a way to bypass this requirement described later.)
* In function `from_json`, use function [`at()`](https://nlohmann.github.io/json/classnlohmann_1_1basic__json_a93403e803947b86f4da2d1fb3345cf2c.html#a93403e803947b86f4da2d1fb3345cf2c) to access the object values rather than `operator[]`. In case a key does not exist, `at` throws an exception that you can handle, whereas `operator[]` exhibits undefined behavior.
* You do not need to add serializers or deserializers for STL types like `std::vector`: the library already implements these.
## How do I convert third-party types?
This requires a bit more advanced technique. But first, let's see how this conversion mechanism works:
The library uses **JSON Serializers** to convert types to json.
The default serializer for `nlohmann::json` is `nlohmann::adl_serializer` (ADL means [Argument-Dependent Lookup](https://en.cppreference.com/w/cpp/language/adl)).
It is implemented like this (simplified):
```cpp
template <typename T>
struct adl_serializer {
static void to_json(json& j, const T& value) {
// calls the "to_json" method in T's namespace
}
static void from_json(const json& j, T& value) {
// same thing, but with the "from_json" method
}
};
```
This serializer works fine when you have control over the type's namespace. However, what about `boost::optional` or `std::filesystem::path` (C++17)? Hijacking the `boost` namespace is pretty bad, and it's illegal to add something other than template specializations to `std`...
To solve this, you need to add a specialization of `adl_serializer` to the `nlohmann` namespace, here's an example:
```cpp
// partial specialization (full specialization works too)
namespace nlohmann {
template <typename T>
struct adl_serializer<boost::optional<T>> {
static void to_json(json& j, const boost::optional<T>& opt) {
if (opt == boost::none) {
j = nullptr;
} else {
j = *opt; // this will call adl_serializer<T>::to_json which will
// find the free function to_json in T's namespace!
}
}
static void from_json(const json& j, boost::optional<T>& opt) {
if (j.is_null()) {
opt = boost::none;
} else {
opt = j.get<T>(); // same as above, but with
// adl_serializer<T>::from_json
}
}
};
}
```
## How can I use `get()` for non-default constructible/non-copyable types?
There is a way, if your type is [MoveConstructible](https://en.cppreference.com/w/cpp/named_req/MoveConstructible). You will need to specialize the `adl_serializer` as well, but with a special `from_json` overload:
```cpp
struct move_only_type {
move_only_type() = delete;
move_only_type(int ii): i(ii) {}
move_only_type(const move_only_type&) = delete;
move_only_type(move_only_type&&) = default;
int i;
};
namespace nlohmann {
template <>
struct adl_serializer<move_only_type> {
// note: the return type is no longer 'void', and the method only takes
// one argument
static move_only_type from_json(const json& j) {
return {j.get<int>()};
}
// Here's the catch! You must provide a to_json method! Otherwise you
// will not be able to convert move_only_type to json, since you fully
// specialized adl_serializer on that type
static void to_json(json& j, move_only_type t) {
j = t.i;
}
};
}
```
## Can I write my own serializer? (Advanced use)
Yes. You might want to take a look at [`unit-udt.cpp`](https://github.com/nlohmann/json/blob/develop/test/src/unit-udt.cpp) in the test suite, to see a few examples.
If you write your own serializer, you'll need to do a few things:
- use a different `basic_json` alias than `nlohmann::json` (the last template parameter of `basic_json` is the `JSONSerializer`)
- use your `basic_json` alias (or a template parameter) in all your `to_json`/`from_json` methods
- use `nlohmann::to_json` and `nlohmann::from_json` when you need ADL
Here is an example, without simplifications, that only accepts types with a size <= 32, and uses ADL.
```cpp
// You should use void as a second template argument
// if you don't need compile-time checks on T
template<typename T, typename SFINAE = typename std::enable_if<sizeof(T) <= 32>::type>
struct less_than_32_serializer {
template <typename BasicJsonType>
static void to_json(BasicJsonType& j, T value) {
// we want to use ADL, and call the correct to_json overload
using nlohmann::to_json; // this method is called by adl_serializer,
// this is where the magic happens
to_json(j, value);
}
template <typename BasicJsonType>
static void from_json(const BasicJsonType& j, T& value) {
// same thing here
using nlohmann::from_json;
from_json(j, value);
}
};
```
Be **very** careful when reimplementing your serializer, you can stack overflow if you don't pay attention:
```cpp
template <typename T, void>
struct bad_serializer
{
template <typename BasicJsonType>
static void to_json(BasicJsonType& j, const T& value) {
// this calls BasicJsonType::json_serializer<T>::to_json(j, value);
// if BasicJsonType::json_serializer == bad_serializer ... oops!
j = value;
}
template <typename BasicJsonType>
static void to_json(const BasicJsonType& j, T& value) {
// this calls BasicJsonType::json_serializer<T>::from_json(j, value);
// if BasicJsonType::json_serializer == bad_serializer ... oops!
value = j.template get<T>(); // oops!
}
};
```
doc/mkdocs/docs/features/binary_formats/bson.md 0 → 100644
View file @ a8f0cd15
# BSON
BSON, short for Bin­ary JSON, is a bin­ary-en­coded seri­al­iz­a­tion of JSON-like doc­u­ments. Like JSON, BSON sup­ports the em­bed­ding of doc­u­ments and ar­rays with­in oth­er doc­u­ments and ar­rays. BSON also con­tains ex­ten­sions that al­low rep­res­ent­a­tion of data types that are not part of the JSON spec. For ex­ample, BSON has a Date type and a BinData type.
!!! abstract "References"
- [BSON Website](http://bsonspec.org) - the main source on BSON
- [BSON Specification](http://bsonspec.org/spec.html) - the specification
## Serialization
The library uses the following mapping from JSON values types to BSON types:
JSON value type | value/range | BSON type | marker
--------------- | --------------------------------- | ----------- | ------
null | `null` | null | 0x0A
boolean | `true`, `false` | boolean | 0x08
number_integer | -9223372036854775808..-2147483649 | int64 | 0x12
number_integer | -2147483648..2147483647 | int32 | 0x10
number_integer | 2147483648..9223372036854775807 | int64 | 0x12
number_unsigned | 0..2147483647 | int32 | 0x10
number_unsigned | 2147483648..9223372036854775807 | int64 | 0x12
number_unsigned | 9223372036854775808..18446744073709551615| -- | --
number_float | *any value* | double | 0x01
string | *any value* | string | 0x02
array | *any value* | document | 0x04
object | *any value* | document | 0x03
binary | *any value* | binary | 0x05
!!! warning "Incomplete mapping"
The mapping is **incomplete**, since only JSON-objects (and things
contained therein) can be serialized to BSON.
Also, integers larger than 9223372036854775807 cannot be serialized to BSON,
and the keys may not contain U+0000, since they are serialized a
zero-terminated c-strings.
!!! example
```cpp
--8<-- "examples/to_bson.cpp"
```
Output:
```c
--8<-- "examples/to_bson.output"
```
## Deserialization
The library maps BSON record types to JSON value types as follows:
BSON type | BSON marker byte | JSON value type
--------------- | ---------------- | ---------------------------
double | 0x01 | number_float
string | 0x02 | string
document | 0x03 | object
array | 0x04 | array
binary | 0x05 | binary
undefined | 0x06 | *unsupported*
ObjectId | 0x07 | *unsupported*
boolean | 0x08 | boolean
UTC Date-Time | 0x09 | *unsupported*
null | 0x0A | null
Regular Expr. | 0x0B | *unsupported*
DB Pointer | 0x0C | *unsupported*
JavaScript Code | 0x0D | *unsupported*
Symbol | 0x0E | *unsupported*
JavaScript Code | 0x0F | *unsupported*
int32 | 0x10 | number_integer
Timestamp | 0x11 | *unsupported*
128-bit decimal float | 0x13 | *unsupported*
Max Key | 0x7F | *unsupported*
Min Key | 0xFF | *unsupported*
!!! warning "Incomplete mapping"
The mapping is **incomplete**. The unsupported mappings are indicated in the table above.
!!! example
```cpp
--8<-- "examples/from_bson.cpp"
```
Output:
```json
--8<-- "examples/from_bson.output"
```
doc/mkdocs/docs/features/binary_formats/cbor.md 0 → 100644
View file @ a8f0cd15
# CBOR
The Concise Binary Object Representation (CBOR) is a data format whose design goals include the possibility of extremely small code size, fairly small message size, and extensibility without the need for version negotiation.
!!! abstract "References"
- [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
## Serialization
The library uses the following mapping from JSON values types to CBOR types according to the CBOR specification (RFC 7049):
JSON value type | value/range | CBOR type | first byte
--------------- | ------------------------------------------ | ---------------------------------- | ---------------
null | `null` | Null | 0xF6
boolean | `true` | True | 0xF5
boolean | `false` | False | 0xF4
number_integer | -9223372036854775808..-2147483649 | Negative integer (8 bytes follow) | 0x3B
number_integer | -2147483648..-32769 | Negative integer (4 bytes follow) | 0x3A
number_integer | -32768..-129 | Negative integer (2 bytes follow) | 0x39
number_integer | -128..-25 | Negative integer (1 byte follow) | 0x38
number_integer | -24..-1 | Negative integer | 0x20..0x37
number_integer | 0..23 | Integer | 0x00..0x17
number_integer | 24..255 | Unsigned integer (1 byte follow) | 0x18
number_integer | 256..65535 | Unsigned integer (2 bytes follow) | 0x19
number_integer | 65536..4294967295 | Unsigned integer (4 bytes follow) | 0x1A
number_integer | 4294967296..18446744073709551615 | Unsigned integer (8 bytes follow) | 0x1B
number_unsigned | 0..23 | Integer | 0x00..0x17
number_unsigned | 24..255 | Unsigned integer (1 byte follow) | 0x18
number_unsigned | 256..65535 | Unsigned integer (2 bytes follow) | 0x19
number_unsigned | 65536..4294967295 | Unsigned integer (4 bytes follow) | 0x1A
number_unsigned | 4294967296..18446744073709551615 | Unsigned integer (8 bytes follow) | 0x1B
number_float | *any value representable by a float* | Single-Precision Float | 0xFA
number_float | *any value NOT representable by a float* | Double-Precision Float | 0xFB
string | *length*: 0..23 | UTF-8 string | 0x60..0x77
string | *length*: 23..255 | UTF-8 string (1 byte follow) | 0x78
string | *length*: 256..65535 | UTF-8 string (2 bytes follow) | 0x79
string | *length*: 65536..4294967295 | UTF-8 string (4 bytes follow) | 0x7A
string | *length*: 4294967296..18446744073709551615 | UTF-8 string (8 bytes follow) | 0x7B
array | *size*: 0..23 | array | 0x80..0x97
array | *size*: 23..255 | array (1 byte follow) | 0x98
array | *size*: 256..65535 | array (2 bytes follow) | 0x99
array | *size*: 65536..4294967295 | array (4 bytes follow) | 0x9A
array | *size*: 4294967296..18446744073709551615 | array (8 bytes follow) | 0x9B
object | *size*: 0..23 | map | 0xA0..0xB7
object | *size*: 23..255 | map (1 byte follow) | 0xB8
object | *size*: 256..65535 | map (2 bytes follow) | 0xB9
object | *size*: 65536..4294967295 | map (4 bytes follow) | 0xBA
object | *size*: 4294967296..18446744073709551615 | map (8 bytes follow) | 0xBB
binary | *size*: 0..23 | byte string | 0x40..0x57
binary | *size*: 23..255 | byte string (1 byte follow) | 0x58
binary | *size*: 256..65535 | byte string (2 bytes follow) | 0x59
binary | *size*: 65536..4294967295 | byte string (4 bytes follow) | 0x5A
binary | *size*: 4294967296..18446744073709551615 | byte string (8 bytes follow) | 0x5B
!!! success "Complete mapping"
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`.
!!! info "Unused CBOR types"
The following CBOR types are not used in the conversion:
- UTF-8 strings terminated by "break" (0x7F)
- arrays terminated by "break" (0x9F)
- maps terminated by "break" (0xBF)
- byte strings terminated by "break" (0x5F)
- date/time (0xC0..0xC1)
- bignum (0xC2..0xC3)
- decimal fraction (0xC4)
- bigfloat (0xC5)
- tagged items (0xC6..0xD4, 0xD8..0xDB)
- expected conversions (0xD5..0xD7)
- simple values (0xE0..0xF3, 0xF8)
- undefined (0xF7)
- half-precision floats (0xF9)
- break (0xFF)
!!! example
```cpp
--8<-- "examples/to_cbor.cpp"
```
Output:
```c
--8<-- "examples/to_cbor.output"
```
## Deserialization
The library maps CBOR types to JSON value types as follows:
CBOR type | JSON value type | first byte
---------------------- | --------------- | ----------
Integer | number_unsigned | 0x00..0x17
Unsigned integer | number_unsigned | 0x18
Unsigned integer | number_unsigned | 0x19
Unsigned integer | number_unsigned | 0x1A
Unsigned integer | number_unsigned | 0x1B
Negative integer | number_integer | 0x20..0x37
Negative integer | number_integer | 0x38
Negative integer | number_integer | 0x39
Negative integer | number_integer | 0x3A
Negative integer | number_integer | 0x3B
Byte string | binary | 0x40..0x57
Byte string | binary | 0x58
Byte string | binary | 0x59
Byte string | binary | 0x5A
Byte string | binary | 0x5B
UTF-8 string | string | 0x60..0x77
UTF-8 string | string | 0x78
UTF-8 string | string | 0x79
UTF-8 string | string | 0x7A
UTF-8 string | string | 0x7B
UTF-8 string | string | 0x7F
array | array | 0x80..0x97
array | array | 0x98
array | array | 0x99
array | array | 0x9A
array | array | 0x9B
array | array | 0x9F
map | object | 0xA0..0xB7
map | object | 0xB8
map | object | 0xB9
map | object | 0xBA
map | object | 0xBB
map | object | 0xBF
False | `false` | 0xF4
True | `true` | 0xF5
Null | `null` | 0xF6
Half-Precision Float | number_float | 0xF9
Single-Precision Float | number_float | 0xFA
Double-Precision Float | number_float | 0xFB
!!! 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:
- date/time (0xC0..0xC1)
- bignum (0xC2..0xC3)
- decimal fraction (0xC4)
- bigfloat (0xC5)
- tagged items (0xC6..0xD4, 0xD8..0xDB)
- expected conversions (0xD5..0xD7)
- simple values (0xE0..0xF3, 0xF8)
- undefined (0xF7)
!!! 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.
!!! example
```cpp
--8<-- "examples/from_cbor.cpp"
```
Output:
```json
--8<-- "examples/from_cbor.output"
```
doc/mkdocs/docs/features/binary_formats/index.md 0 → 100644
View file @ a8f0cd15
# Overview
Though JSON is a ubiquitous data format, it is not a very compact format suitable for data exchange, for instance over a network. Hence, the library supports
- [BSON](bson) (Binary JSON),
- [CBOR](cbor) (Concise Binary Object Representation),
- [MessagePack](messagepack), and
- [UBJSON](ubjson) (Universal Binary JSON Specification)
to efficiently encode JSON values to byte vectors and to decode such vectors.
## Comparison
### Completeness
| Format | Serialization | Deserialization |
| ----------- |---------------------------------------------- | -------------------------------------------- |
| BSON | incomplete: top-level value must be an object | incomplete, but all JSON types are supported |
| CBOR | complete | incomplete, but all JSON types are supported |
| MessagePack | complete | complete |
| UBJSON | complete | complete |
### Binary values
| Format | Binary values | Binary subtypes |
| ----------- | ------------- | --------------- |
| BSON | supported | supported |
| CBOR | supported | not supported |
| MessagePack | supported | supported |
| UBJSON | not supported | not supported |
### Sizes
| Format | canada.json | twitter.json | citm_catalog.json | jeopardy.json |
| ------------------ | ----------- | ------------ | ----------------- | ------------- |
| BSON | 85,8 % | 95,2 % | 95,8 % | 106,7 % |
| CBOR | 50,5 % | 86,3 % | 68,4 % | 88,0 % |
| MessagePack | 50,6 % | 86,0 % | 68,5 % | 87,9 % |
| UBJSON | 53,2 % | 91,3 % | 78,2 % | 96,6 % |
| UBJSON (size) | 58,6 % | 92,3 % | 86,8 % | 97,4 % |
| UBJSON (size+type) | 55,9 % | 92,3 % | 85,0 % | 95,0 % |
doc/mkdocs/docs/features/binary_formats/messagepack.md 0 → 100644
View file @ a8f0cd15
# MessagePack
MessagePack is an efficient binary serialization format. It lets you exchange data among multiple languages like JSON. But it's faster and smaller. Small integers are encoded into a single byte, and typical short strings require only one 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)
## Serialization
The library uses the following mapping from JSON values types to MessagePack types according to the MessagePack specification:
JSON value type | value/range | MessagePack type | first byte
--------------- | --------------------------------- | ---------------- | ----------
null | `null` | nil | 0xC0
boolean | `true` | true | 0xC3
boolean | `false` | false | 0xC2
number_integer | -9223372036854775808..-2147483649 | int64 | 0xD3
number_integer | -2147483648..-32769 | int32 | 0xD2
number_integer | -32768..-129 | int16 | 0xD1
number_integer | -128..-33 | int8 | 0xD0
number_integer | -32..-1 | negative fixint | 0xE0..0xFF
number_integer | 0..127 | positive fixint | 0x00..0x7F
number_integer | 128..255 | uint 8 | 0xCC
number_integer | 256..65535 | uint 16 | 0xCD
number_integer | 65536..4294967295 | uint 32 | 0xCE
number_integer | 4294967296..18446744073709551615 | uint 64 | 0xCF
number_unsigned | 0..127 | positive fixint | 0x00..0x7F
number_unsigned | 128..255 | uint 8 | 0xCC
number_unsigned | 256..65535 | uint 16 | 0xCD
number_unsigned | 65536..4294967295 | uint 32 | 0xCE
number_unsigned | 4294967296..18446744073709551615 | uint 64 | 0xCF
number_float | *any value* | float 64 | 0xCB
string | *length*: 0..31 | fixstr | 0xA0..0xBF
string | *length*: 32..255 | str 8 | 0xD9
string | *length*: 256..65535 | str 16 | 0xDA
string | *length*: 65536..4294967295 | str 32 | 0xDB
array | *size*: 0..15 | fixarray | 0x90..0x9F
array | *size*: 16..65535 | array 16 | 0xDC
array | *size*: 65536..4294967295 | array 32 | 0xDD
object | *size*: 0..15 | fix map | 0x80..0x8F
object | *size*: 16..65535 | map 16 | 0xDE
object | *size*: 65536..4294967295 | map 32 | 0xDF
binary | *size*: 0..255 | bin 8 | 0xC4
binary | *size*: 256..65535 | bin 16 | 0xC5
binary | *size*: 65536..4294967295 | bin 32 | 0xC6
!!! success "Complete mapping"
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`.
!!! warning "Size constraints"
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
!!! info "Unused MessagePack types"
The following MessagePack types are not used in the conversion: float 32 (0xCA)
!!! info "NaN/infinity handling"
If NaN or Infinity are stored inside a JSON number, they are serialized properly. function which serializes NaN or Infinity to `null`.
!!! example
```cpp
--8<-- "examples/to_msgpack.cpp"
```
Output:
```c
--8<-- "examples/to_msgpack.output"
```
## Deserialization
The library maps MessagePack types to JSON value types as follows:
MessagePack type | JSON value type | first byte
---------------- | --------------- | ----------
positive fixint | number_unsigned | 0x00..0x7F
fixmap | object | 0x80..0x8F
fixarray | array | 0x90..0x9F
fixstr | string | 0xA0..0xBF
nil | `null` | 0xC0
false | `false` | 0xC2
true | `true` | 0xC3
float 32 | number_float | 0xCA
float 64 | number_float | 0xCB
uint 8 | number_unsigned | 0xCC
uint 16 | number_unsigned | 0xCD
uint 32 | number_unsigned | 0xCE
uint 64 | number_unsigned | 0xCF
int 8 | number_integer | 0xD0
int 16 | number_integer | 0xD1
int 32 | number_integer | 0xD2
int 64 | number_integer | 0xD3
str 8 | string | 0xD9
str 16 | string | 0xDA
str 32 | string | 0xDB
array 16 | array | 0xDC
array 32 | array | 0xDD
map 16 | object | 0xDE
map 32 | object | 0xDF
bin 8 | binary | 0xC4
bin 16 | binary | 0xC5
bin 32 | binary | 0xC6
ext 8 | binary | 0xC7
ext 16 | binary | 0xC8
ext 32 | binary | 0xC9
fixext 1 | binary | 0xD4
fixext 2 | binary | 0xD5
fixext 4 | binary | 0xD6
fixext 8 | binary | 0xD7
fixext 16 | binary | 0xD8
negative fixint | number_integer | 0xE0-0xFF
!!! info
Any MessagePack output created by `to_msgpack` can be successfully parsed by `from_msgpack`.
!!! example
```cpp
--8<-- "examples/from_msgpack.cpp"
```
Output:
```json
--8<-- "examples/from_msgpack.output"
```
doc/mkdocs/docs/features/binary_formats/ubjson.md 0 → 100644
View file @ a8f0cd15
# UBJSON
Universal Binary JSON (UBJSON) is a binary form directly imitating JSON, but requiring fewer bytes of data. It aims to achieve the generality of JSON, combined with being much easier to process than JSON.
!!! abstract "References"
- [UBJSON Website](http://ubjson.org)
## Serialization
The library uses the following mapping from JSON values types to UBJSON types according to the UBJSON specification:
JSON value type | value/range | UBJSON type | marker
--------------- | --------------------------------- | ----------- | ------
null | `null` | null | `Z`
boolean | `true` | true | `T`
boolean | `false` | false | `F`
number_integer | -9223372036854775808..-2147483649 | int64 | `L`
number_integer | -2147483648..-32769 | int32 | `l`
number_integer | -32768..-129 | int16 | `I`
number_integer | -128..127 | int8 | `i`
number_integer | 128..255 | uint8 | `U`
number_integer | 256..32767 | int16 | `I`
number_integer | 32768..2147483647 | int32 | `l`
number_integer | 2147483648..9223372036854775807 | int64 | `L`
number_unsigned | 0..127 | int8 | `i`
number_unsigned | 128..255 | uint8 | `U`
number_unsigned | 256..32767 | int16 | `I`
number_unsigned | 32768..2147483647 | int32 | `l`
number_unsigned | 2147483648..9223372036854775807 | int64 | `L`
number_float | *any value* | float64 | `D`
string | *with shortest length indicator* | string | `S`
array | *see notes on optimized format* | array | `[`
object | *see notes on optimized format* | map | `{`
!!! success "Complete mapping"
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`.
!!! warning "Size constraints"
The following values can **not** be converted to a UBJSON value:
- strings with more than 9223372036854775807 bytes (theoretical)
- unsigned integer numbers above 9223372036854775807
!!! info "Unused UBJSON markers"
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 `dump()`
function which serializes NaN or Infinity to `null`.
!!! info "Optimized formats"
The optimized formats for containers are supported: Parameter
`use_size` adds size information to the beginning of a container and
removes the closing marker. Parameter `use_type` further checks
whether all elements of a container have the same type and adds the
type marker to the beginning of the container. The `use_type`
parameter must only be used together with `use_size = true`.
Note that `use_size = true` alone may result in larger representations -
the benefit of this parameter is that the receiving side is
immediately informed on the number of elements of the container.
!!! info "Binary values"
If the JSON data contains the binary type, the value stored is a list
of integers, as suggested by the UBJSON documentation. In particular,
this means that serialization and the deserialization of a JSON
containing binary values into UBJSON and back will result in a
different JSON object.
!!! example
```cpp
--8<-- "examples/to_ubjson.cpp"
```
Output:
```c
--8<-- "examples/to_ubjson.output"
```
## Deserialization
The library maps UBJSON types to JSON value types as follows:
UBJSON type | JSON value type | marker
----------- | --------------------------------------- | ------
no-op | *no value, next value is read* | `N`
null | `null` | `Z`
false | `false` | `F`
true | `true` | `T`
float32 | number_float | `d`
float64 | number_float | `D`
uint8 | number_unsigned | `U`
int8 | number_integer | `i`
int16 | number_integer | `I`
int32 | number_integer | `l`
int64 | number_integer | `L`
string | string | `S`
char | string | `C`
array | array (optimized values are supported) | `[`
object | object (optimized values are supported) | `{`
!!! success "Complete mapping"
The mapping is **complete** in the sense that any UBJSON value can be converted to a JSON value.
!!! example
```cpp
--8<-- "examples/from_ubjson.cpp"
```
Output:
```json
--8<-- "examples/from_ubjson.output"
```
doc/mkdocs/docs/features/binary_values.md 0 → 100644
View file @ a8f0cd15
# Binary Values
The library implements several [binary formats](binary_formats/index) that encode JSON in an efficient way. Most of these formats support binary values; that is, values that have semantics define outside the library and only define a sequence of bytes to be stored.
JSON itself does not have a binary value. As such, binary values are an extension that this library implements to store values received by a binary format. Binary values are never created by the JSON parser, and are only part of a serialized JSON text if they have been created manually or via a binary format.
## API for binary values
By default, binary values are stored as `std::vector<std::uint8_t>`. This type can be changed by providing a template parameter to the `basic_json` type. To store binary subtypes, the storage type is extended and exposed as `json::binary_t`:
```cpp
auto binary = json::binary_t({0xCA, 0xFE, 0xBA, 0xBE});
auto binary_with_subtype = json::binary_t({0xCA, 0xFE, 0xBA, 0xBE}, 42);
```
There are several convenience functions to check and set the subtype:
```cpp
binary.has_subtype(); // returns false
binary_with_subtype.has_subtype(); // returns true
binary_with_subtype.clear_subtype();
binary_with_subtype.has_subtype(); // returns true
binary_with_subtype.set_subtype(42);
binary.set_subtype(23);
binary.subtype(); // returns 23
```
As `json::binary_t` is subclassing `std::vector<std::uint8_t>`, all member functions are available:
```cpp
binary.size(); // returns 4
binary[1]; // returns 0xFE
```
JSON values can be constructed from `json::binary_t`:
```cpp
json j = binary;
```
Binary values are primitive values just like numbers or strings:
```cpp
j.is_binary(); // returns true
j.is_primitive(); // returns true
```
Given a binary JSON value, the `binary_t` can be accessed by reference as via `get_binary()`:
```cpp
j.get_binary().has_subtype(); // returns true
j.get_binary().size(); // returns 4
```
For convencience, binary JSON values can be constructed via `json::binary`:
```cpp
auto j2 = json::binary({0xCA, 0xFE, 0xBA, 0xBE}, 23);
auto j3 = json::binary({0xCA, 0xFE, 0xBA, 0xBE});
j2 == j; // returns true
j3.get_binary().has_subtype(); // returns false
```
## Serialization
Binary values are serialized differently according to the formats.
### JSON
JSON does not have a binary type, and this library does not introduce a new type as this would break conformance. Instead, binary values are serialized as an object with two keys: `bytes` holds an array of integers, and `subtype` is an integer or `null`.
!!! example
Code:
```cpp
// create a binary value of subtype 42
json j;
j["binary"] = json::binary({0xCA, 0xFE, 0xBA, 0xBE}, 42);
// serialize to standard output
std::cout << j.dump(2) << std::endl;
```
Output:
```json
{
"binary": {
"bytes": [202, 254, 186, 190],
"subtype": 42
}
}
```
!!! warning "No roundtrip for binary values"
The JSON parser will not parse the objects generated by binary values back to binary values. This is by design to remain standards compliant. Serializing binary values to JSON is only implemented for debugging purposes.
### BSON
[BSON](binary_formats/bson) supports binary values and subtypes. If a subtype is given, it is used and added as unsigned 8-bit integer. If no subtype is given, the generic binary subtype 0x00 is used.
!!! example
Code:
```cpp
// create a binary value of subtype 42
json j;
j["binary"] = json::binary({0xCA, 0xFE, 0xBA, 0xBE}, 42);
// convert to BSON
auto v = json::to_bson(j);
```
`v` is a `std::vector<std::uint8t>` with the following 22 elements:
```c
0x16 0x00 0x00 0x00 // number of bytes in the document
0x05 // binary value
0x62 0x69 0x6E 0x61 0x72 0x79 0x00 // key "binary" + null byte
0x04 0x00 0x00 0x00 // number of bytes
0x2a // subtype
0xCA 0xFE 0xBA 0xBE // content
0x00 // end of the document
```
Note that the serialization preserves the subtype, and deserializing `v` would yield the following value:
```json
{
"binary": {
"bytes": [202, 254, 186, 190],
"subtype": 42
}
}
```
### CBOR
[CBOR](binary_formats/cbor) supports binary values, but no subtypes. Any binary value will be serialized as byte strings. The library will choose the smallest representation using the length of the byte array.
!!! example
Code:
```cpp
// create a binary value of subtype 42 (will be ignored by CBOR)
json j;
j["binary"] = json::binary({0xCA, 0xFE, 0xBA, 0xBE}, 42);
// convert to CBOR
auto v = json::to_cbor(j);
```
`v` is a `std::vector<std::uint8t>` with the following 13 elements:
```c
0xA1 // map(1)
0x66 // text(6)
0x62 0x69 0x6E 0x61 0x72 0x79 // "binary"
0x44 // bytes(4)
0xCA 0xFE 0xBA 0xBE // content
```
Note the subtype (42) is **not** serialized, and deserializing `v` would yield the following value:
```json
{
"binary": {
"bytes": [202, 254, 186, 190],
"subtype": null
}
}
```
### MessagePack
[MessagePack](binary_formats/messagepack) supports binary values and subtypes. If a subtype is given, the ext family is used. The library will choose the smallest representation among fixext1, fixext2, fixext4, fixext8, ext8, ext16, and ext32. The subtype is then added as singed 8-bit integer.
If no subtype is given, the bin family (bin8, bin16, bin32) is used.
!!! example
Code:
```cpp
// create a binary value of subtype 42
json j;
j["binary"] = json::binary({0xCA, 0xFE, 0xBA, 0xBE}, 42);
// convert to MessagePack
auto v = json::to_msgpack(j);
```
`v` is a `std::vector<std::uint8t>` with the following 14 elements:
```c
0x81 // fixmap1
0xA6 // fixstr6
0x62 0x69 0x6E 0x61 0x72 0x79 // "binary"
0xD6 // fixext4
0x2A // subtype
0xCA 0xFE 0xBA 0xBE // content
```
Note that the serialization preserves the subtype, and deserializing `v` would yield the following value:
```json
{
"binary": {
"bytes": [202, 254, 186, 190],
"subtype": 42
}
}
```
### UBJSON
[UBJSON](binary_formats/ubjson) neither supports binary values nor subtypes, and proposes to serialize binary values as array of uint8 values. This translation is implemented by the library.
!!! example
Code:
```cpp
// create a binary value of subtype 42 (will be ignored in UBJSON)
json j;
j["binary"] = json::binary({0xCA, 0xFE, 0xBA, 0xBE}, 42);
// convert to UBJSON
auto v = json::to_msgpack(j);
```
`v` is a `std::vector<std::uint8t>` with the following 20 elements:
```c
0x7B // '{'
0x69 0x06 // i 6 (length of the key)
0x62 0x69 0x6E 0x61 0x72 0x79 // "binary"
0x5B // '['
0x55 0xCA 0x55 0xFE 0x55 0xBA 0x55 0xBE // content (each byte prefixed with 'U')
0x5D // ']'
0x7D // '}'
```
The following code uses the type and size optimization for UBJSON:
```cpp
// convert to UBJSON using the size and type optimization
auto v = json::to_ubjson(j, true, true);
```
The resulting vector has 23 elements; the optimization is not effective for examples with few values:
```c
0x7B // '{'
0x24 // '$' type of the object elements
0x5B // '[' array
0x23 0x69 0x01 // '#' i 1 number of object elements
0x69 0x06 // i 6 (length of the key)
0x62 0x69 0x6E 0x61 0x72 0x79 // "binary"
0x24 0x55 // '$' 'U' type of the array elements: unsinged integers
0x23 0x69 0x04 // '#' i 4 number of array elements
0xCA 0xFE 0xBA 0xBE // content
```
Note that subtype (42) is **not** serialized and that UBJSON has **no binary type**, and deserializing `v` would yield the following value:
```json
{
"binary": [202, 254, 186, 190]
}
```
doc/mkdocs/docs/features/enum_conversion.md 0 → 100644
View file @ a8f0cd15
# Specializing enum conversion
By default, enum values are serialized to JSON as integers. In some cases this could result in undesired behavior. If an enum is modified or re-ordered after data has been serialized to JSON, the later de-serialized JSON data may be undefined or a different enum value than was originally intended.
It is possible to more precisely specify how a given enum is mapped to and from JSON as shown below:
```cpp
// example enum type declaration
enum TaskState {
TS_STOPPED,
TS_RUNNING,
TS_COMPLETED,
TS_INVALID=-1,
};
// map TaskState values to JSON as strings
NLOHMANN_JSON_SERIALIZE_ENUM( TaskState, {
{TS_INVALID, nullptr},
{TS_STOPPED, "stopped"},
{TS_RUNNING, "running"},
{TS_COMPLETED, "completed"},
})
```
The `NLOHMANN_JSON_SERIALIZE_ENUM()` macro declares a set of `to_json()` / `from_json()` functions for type `TaskState` while avoiding repetition and boilerplate serialization code.
## Usage
```cpp
// enum to JSON as string
json j = TS_STOPPED;
assert(j == "stopped");
// json string to enum
json j3 = "running";
assert(j3.get<TaskState>() == TS_RUNNING);
// undefined json value to enum (where the first map entry above is the default)
json jPi = 3.14;
assert(jPi.get<TaskState>() == TS_INVALID );
```
## Notes
Just as in [Arbitrary Type Conversions](#arbitrary-types-conversions) above,
- `NLOHMANN_JSON_SERIALIZE_ENUM()` MUST be declared in your enum type's namespace (which can be the global namespace), or the library will not be able to locate it and it will default to integer serialization.
- It MUST be available (e.g., proper headers must be included) everywhere you use the conversions.
Other Important points:
- When using `get<ENUM_TYPE>()`, undefined JSON values will default to the first pair specified in your map. Select this default pair carefully.
- If an enum or JSON value is specified more than once in your map, the first matching occurrence from the top of the map will be returned when converting to or from JSON.
doc/mkdocs/docs/features/json_patch.md 0 → 100644
View file @ a8f0cd15
# JSON Patch
On top of this, **JSON Patch** ([RFC 6902](https://tools.ietf.org/html/rfc6902)) allows to describe differences between two JSON values - effectively allowing patch and diff operations known from Unix.
```cpp
// a JSON patch (RFC 6902)
json j_patch = R"([
{ "op": "replace", "path": "/baz", "value": "boo" },
{ "op": "add", "path": "/hello", "value": ["world"] },
{ "op": "remove", "path": "/foo"}
])"_json;
// apply the patch
json j_result = j_original.patch(j_patch);
// {
// "baz": "boo",
// "hello": ["world"]
// }
// calculate a JSON patch from two JSON values
json::diff(j_result, j_original);
// [
// { "op":" replace", "path": "/baz", "value": ["one", "two", "three"] },
// { "op": "remove","path": "/hello" },
// { "op": "add", "path": "/foo", "value": "bar" }
// ]
```
doc/mkdocs/docs/features/json_pointer.md 0 → 100644
View file @ a8f0cd15
# JSON Pointer
The library supports **JSON Pointer** ([RFC 6901](https://tools.ietf.org/html/rfc6901)) as alternative means to address structured values.
```cpp
// a JSON value
json j_original = R"({
"baz": ["one", "two", "three"],
"foo": "bar"
})"_json;
// access members with a JSON pointer (RFC 6901)
j_original["/baz/1"_json_pointer];
// "two"
```
doc/mkdocs/docs/features/merge_patch.md 0 → 100644
View file @ a8f0cd15
# JSON Merge Patch
The library supports **JSON Merge Patch** ([RFC 7386](https://tools.ietf.org/html/rfc7386)) as a patch format. Instead of using JSON Pointer (see above) to specify values to be manipulated, it describes the changes using a syntax that closely mimics the document being modified.
```cpp
// a JSON value
json j_document = R"({
"a": "b",
"c": {
"d": "e",
"f": "g"
}
})"_json;
// a patch
json j_patch = R"({
"a":"z",
"c": {
"f": null
}
})"_json;
// apply the patch
j_document.merge_patch(j_patch);
// {
// "a": "z",
// "c": {
// "d": "e"
// }
// }
```
doc/mkdocs/docs/features/sax_interface.md 0 → 100644
View file @ a8f0cd15
# SAX Interface
The library uses a SAX-like interface with the following functions:
```cpp
// called when null is parsed
bool null();
// called when a boolean is parsed; value is passed
bool boolean(bool val);
// called when a signed or unsigned integer number is parsed; value is passed
bool number_integer(number_integer_t val);
bool number_unsigned(number_unsigned_t val);
// called when a floating-point number is parsed; value and original string is passed
bool number_float(number_float_t val, const string_t& s);
// called when a string is parsed; value is passed and can be safely moved away
bool string(string_t& val);
// called when an object or array begins or ends, resp. The number of elements is passed (or -1 if not known)
bool start_object(std::size_t elements);
bool end_object();
bool start_array(std::size_t elements);
bool end_array();
// called when an object key is parsed; value is passed and can be safely moved away
bool key(string_t& val);
// called when a parse error occurs; byte position, the last token, and an exception is passed
bool parse_error(std::size_t position, const std::string& last_token, const detail::exception& ex);
```
The return value of each function determines whether parsing should proceed.
To implement your own SAX handler, proceed as follows:
1. Implement the SAX interface in a class. You can use class `nlohmann::json_sax<json>` as base class, but you can also use any class where the functions described above are implemented and public.
2. Create an object of your SAX interface class, e.g. `my_sax`.
3. Call `#!cpp bool json::sax_parse(input, &my_sax);` where the first parameter can be any input like a string or an input stream and the second parameter is a pointer to your SAX interface.
Note the `sax_parse` function only returns a `#!cpp bool` indicating the result of the last executed SAX event. It does not return `json` value - it is up to you to decide what to do with the SAX events. Furthermore, no exceptions are thrown in case of a parse error - it is up to you what to do with the exception object passed to your `parse_error` implementation. Internally, the SAX interface is used for the DOM parser (class `json_sax_dom_parser`) as well as the acceptor (`json_sax_acceptor`), see file `json_sax.hpp`.
doc/mkdocs/docs/home/code_of_conduct.md 0 → 100644
View file @ a8f0cd15
# 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/
doc/mkdocs/docs/home/design_goals.md 0 → 100644
View file @ a8f0cd15
# 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.
doc/mkdocs/docs/home/exceptions.md 0 → 100644
View file @ a8f0cd15
This diff is collapsed.
doc/mkdocs/docs/home/faq.md 0 → 100644
View file @ a8f0cd15
# 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).
doc/mkdocs/docs/home/license.md 0 → 100644
View file @ a8f0cd15
# 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/).
doc/mkdocs/docs/home/sponsors.md 0 → 100644
View file @ a8f0cd15
# 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!
doc/mkdocs/docs/hooks.py 0 → 100644
View file @ a8f0cd15
import shutil
import os.path
def copy_doxygen(*args, **kwargs):
shutil.copytree('../html', os.path.join(kwargs['config']['site_dir'], 'doxygen'))
print('Copy Doxygen complete')
doc/mkdocs/docs/index.md 0 → 100644
View file @ a8f0cd15
# JSON for Modern C++
!!! note
This page is under construction. You probably want to see the [Doxygen documentation](doxygen).
![](images/json.gif)
doc/mkdocs/docs/integration/cmake.md 0 → 100644
View file @ a8f0cd15
# CMake
You can also use the `nlohmann_json::nlohmann_json` interface target in CMake. This target populates the appropriate usage requirements for `INTERFACE_INCLUDE_DIRECTORIES` to point to the appropriate include directories and `INTERFACE_COMPILE_FEATURES` for the necessary C++11 flags.
## External
To use this library from a CMake project, you can locate it directly with `find_package()` and use the namespaced imported target from the generated package configuration:
```cmake
# CMakeLists.txt
find_package(nlohmann_json 3.2.0 REQUIRED)
...
add_library(foo ...)
...
target_link_libraries(foo PRIVATE nlohmann_json::nlohmann_json)
```
The package configuration file, `nlohmann_jsonConfig.cmake`, can be used either from an install tree or directly out of the build tree.
## Embedded
To embed the library directly into an existing CMake project, place the entire source tree in a subdirectory and call `add_subdirectory()` in your `CMakeLists.txt` file:
```cmake
# Typically you don't care so much for a third party library's tests to be
# run from your own project's code.
set(JSON_BuildTests OFF CACHE INTERNAL "")
# If you only include this third party in PRIVATE source files, you do not
# need to install it when your main project gets installed.
# set(JSON_Install OFF CACHE INTERNAL "")
# Don't use include(nlohmann_json/CMakeLists.txt) since that carries with it
# unintended consequences that will break the build. It's generally
# discouraged (although not necessarily well documented as such) to use
# include(...) for pulling in other CMake projects anyways.
add_subdirectory(nlohmann_json)
...
add_library(foo ...)
...
target_link_libraries(foo PRIVATE nlohmann_json::nlohmann_json)
```
## Embedded (FetchContent)
Since CMake v3.11,
[FetchContent](https://cmake.org/cmake/help/v3.11/module/FetchContent.html) can
be used to automatically download the repository as a dependency at configure type.
Example:
```cmake
include(FetchContent)
FetchContent_Declare(json
GIT_REPOSITORY https://github.com/nlohmann/json
GIT_TAG v3.7.3)
FetchContent_GetProperties(json)
if(NOT json_POPULATED)
FetchContent_Populate(json)
add_subdirectory(${json_SOURCE_DIR} ${json_BINARY_DIR} EXCLUDE_FROM_ALL)
endif()
target_link_libraries(foo PRIVATE nlohmann_json::nlohmann_json)
```
!!! Note
The repository <https://github.com/nlohmann/json> download size is huge.
It contains all the dataset used for the benchmarks. You might want to depend on
a smaller repository. For instance, you might want to replace the URL above by
<https://github.com/ArthurSonzogni/nlohmann_json_cmake_fetchcontent>.
## Supporting Both
To allow your project to support either an externally supplied or an embedded JSON library, you can use a pattern akin to the following:
``` cmake
# Top level CMakeLists.txt
project(FOO)
...
option(FOO_USE_EXTERNAL_JSON "Use an external JSON library" OFF)
...
add_subdirectory(thirdparty)
...
add_library(foo ...)
...
# Note that the namespaced target will always be available regardless of the
# import method
target_link_libraries(foo PRIVATE nlohmann_json::nlohmann_json)
```
```cmake
# thirdparty/CMakeLists.txt
...
if(FOO_USE_EXTERNAL_JSON)
find_package(nlohmann_json 3.2.0 REQUIRED)
else()
set(JSON_BuildTests OFF CACHE INTERNAL "")
add_subdirectory(nlohmann_json)
endif()
...
```
`thirdparty/nlohmann_json` is then a complete copy of this source tree.
doc/mkdocs/docs/integration/conan/CMakeLists.txt 0 → 100644
View file @ a8f0cd15
project(json_example)
cmake_minimum_required(VERSION 2.8.12)
add_definitions("-std=c++11")
include(${CMAKE_BINARY_DIR}/conanbuildinfo.cmake)
conan_basic_setup()
add_executable(json_example example.cpp)
target_link_libraries(json_example ${CONAN_LIBS})
doc/mkdocs/docs/integration/conan/Conanfile.txt 0 → 100644
View file @ a8f0cd15
[requires]
nlohmann_json/3.7.3
[generators]
cmake
doc/mkdocs/docs/integration/conan/example.cpp 0 → 100644
View file @ a8f0cd15
#include <nlohmann/json.hpp>
#include <iostream>
using json = nlohmann::json;
int main()
{
std::cout << json::meta() << std::endl;
}
doc/mkdocs/docs/integration/example.cpp 0 → 100644
View file @ a8f0cd15
#include <nlohmann/json.hpp>
#include <iostream>
using json = nlohmann::json;
int main()
{
std::cout << json::meta() << std::endl;
}
doc/mkdocs/docs/integration/index.md 0 → 100644
View file @ a8f0cd15
# Integration
[`json.hpp`](https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json.hpp) is the single required file in `single_include/nlohmann` or [released here](https://github.com/nlohmann/json/releases). You need to add
```cpp
#include <nlohmann/json.hpp>
// for convenience
using json = nlohmann::json;
```
to the files you want to process JSON and set the necessary switches to enable C++11 (e.g., `-std=c++11` for GCC and Clang).
You can further use file [`include/nlohmann/json_fwd.hpp`](https://github.com/nlohmann/json/blob/develop/include/nlohmann/json_fwd.hpp) for forward-declarations. The installation of json_fwd.hpp (as part of cmake's install step), can be achieved by setting `-DJSON_MultipleHeaders=ON`.
doc/mkdocs/docs/integration/package_managers.md 0 → 100644
View file @ a8f0cd15
# Package Managers
Throughout this page, we will describe how to compile the example file `example.cpp` below.
```cpp
--8<-- "integration/example.cpp"
```
## Homebrew
If you are using OS X and [Homebrew](http://brew.sh), just type
```sh
brew tap nlohmann/json
brew install nlohmann_json
```
and you're set. If you want the bleeding edge rather than the latest release, use
```sh
brew tap nlohmann/json
brew install nlohmann_json --HEAD
```
instead.
!!! example
1. Create the following file:
=== "example.cpp"
```cpp
--8<-- "integration/example.cpp"
```
2. Install the package
```sh
brew tap nlohmann/json
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
```sh
brew list nlohmann_json
```
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
```
## Meson
If you are using the [Meson Build System](http://mesonbuild.com), add this source tree as a [meson subproject](https://mesonbuild.com/Subprojects.html#using-a-subproject). You may also use the `include.zip` published in this project's [Releases](https://github.com/nlohmann/json/releases) to reduce the size of the vendored source tree. Alternatively, you can get a wrap file by downloading it from [Meson WrapDB](https://wrapdb.mesonbuild.com/nlohmann_json), or simply use `meson wrap install nlohmann_json`. Please see the meson project for any issues regarding the packaging.
The provided meson.build can also be used as an alternative to cmake for installing `nlohmann_json` system-wide in which case a pkg-config file is installed. To use it, simply have your build system require the `nlohmann_json` pkg-config dependency. In Meson, it is preferred to use the [`dependency()`](https://mesonbuild.com/Reference-manual.html#dependency) object with a subproject fallback, rather than using the subproject directly.
## Conan
If you are using [Conan](https://www.conan.io/) to manage your dependencies, merely add `nlohmann_json/x.y.z` to your `conanfile`'s requires, where `x.y.z` is the release version you want to use. Please file issues [here](https://github.com/conan-io/conan-center-index/issues) if you experience problems with the packages.
!!! example
1. Create the following files:
=== "Conanfile.txt"
```ini
--8<-- "integration/conan/Conanfile.txt"
```
=== "CMakeLists.txt"
```cmake
--8<-- "integration/conan/CMakeLists.txt"
```
=== "example.cpp"
```cpp
--8<-- "integration/conan/example.cpp"
```
2. Build:
```sh
mkdir build
cd build
conan install ..
cmake ..
cmake --build .
```
## Spack
If you are using [Spack](https://www.spack.io/) to manage your dependencies, you can use the [`nlohmann-json` package](https://spack.readthedocs.io/en/latest/package_list.html#nlohmann-json). Please see the [spack project](https://github.com/spack/spack) for any issues regarding the packaging.
## Hunter
If you are using [hunter](https://github.com/cpp-pm/hunter) on your project for external dependencies, then you can use the [nlohmann_json package](https://hunter.readthedocs.io/en/latest/packages/pkg/nlohmann_json.html). Please see the hunter project for any issues regarding the packaging.
## Buckaroo
If you are using [Buckaroo](https://buckaroo.pm), you can install this library's module with `buckaroo add github.com/buckaroo-pm/nlohmann-json`. Please file issues [here](https://github.com/buckaroo-pm/nlohmann-json). There is a demo repo [here](https://github.com/njlr/buckaroo-nholmann-json-example).
## vcpkg
If you are using [vcpkg](https://github.com/Microsoft/vcpkg/) on your project for external dependencies, then you can use the [nlohmann-json package](https://github.com/Microsoft/vcpkg/tree/master/ports/nlohmann-json). Please see the vcpkg project for any issues regarding the packaging.
## cget
If you are using [cget](http://cget.readthedocs.io/en/latest/), you can install the latest development version with `cget install nlohmann/json`. A specific version can be installed with `cget install nlohmann/json@v3.1.0`. Also, the multiple header version can be installed by adding the `-DJSON_MultipleHeaders=ON` flag (i.e., `cget install nlohmann/json -DJSON_MultipleHeaders=ON`).
## CocoaPods
If you are using [CocoaPods](https://cocoapods.org), you can use the library by adding pod `"nlohmann_json", '~>3.1.2'` to your podfile (see [an example](https://bitbucket.org/benman/nlohmann_json-cocoapod/src/master/)). Please file issues [here](https://bitbucket.org/benman/nlohmann_json-cocoapod/issues?status=new&status=open).
## NuGet
If you are using [NuGet](https://www.nuget.org), you can use the package [nlohmann.json](https://www.nuget.org/packages/nlohmann.json/). Please check [this extensive description](https://github.com/nlohmann/json/issues/1132#issuecomment-452250255) on how to use the package. Please files issues [here](https://github.com/hnkb/nlohmann-json-nuget/issues).
## Conda
If you are using [conda](https://conda.io/), you can use the package [nlohmann_json](https://github.com/conda-forge/nlohmann_json-feedstock) from [conda-forge](https://conda-forge.org) executing `conda install -c conda-forge nlohmann_json`. Please file issues [here](https://github.com/conda-forge/nlohmann_json-feedstock/issues).
## MSYS2
If you are using [MSYS2](http://www.msys2.org/), your can use the [mingw-w64-nlohmann-json](https://packages.msys2.org/base/mingw-w64-nlohmann-json) package, just type `pacman -S mingw-w64-i686-nlohmann-json` or `pacman -S mingw-w64-x86_64-nlohmann-json` for installation. Please file issues [here](https://github.com/msys2/MINGW-packages/issues/new?title=%5Bnlohmann-json%5D) if you experience problems with the packages.
## build2
If you are using [`build2`](https://build2.org), you can use the [`nlohmann-json`](https://cppget.org/nlohmann-json) package from the public repository http://cppget.org or directly from the [package's sources repository](https://github.com/build2-packaging/nlohmann-json). In your project's `manifest` file, just add `depends: nlohmann-json` (probably with some [version constraints](https://build2.org/build2-toolchain/doc/build2-toolchain-intro.xhtml#guide-add-remove-deps)). If you are not familiar with using dependencies in `build2`, [please read this introduction](https://build2.org/build2-toolchain/doc/build2-toolchain-intro.xhtml).
Please file issues [here](https://github.com/build2-packaging/nlohmann-json) if you experience problems with the packages.
## wsjcpp
If you are using [`wsjcpp`](http://wsjcpp.org), you can use the command `wsjcpp install "https://github.com/nlohmann/json:develop"` to get the latest version. Note you can change the branch ":develop" to an existing tag or another branch.
doc/mkdocs/mkdocs.yml 0 → 100644
View file @ a8f0cd15
# Project information
site_name: JSON for Modern C++
site_author: Niels Lohmann
site_url: https://squidfunk.github.io/mkdocs-material/
# Repository
repo_name: nlohmann/json
repo_url: https://github.com/nlohmann/json
edit_uri: edit/develop/doc/mkdocs/docs
# Copyright
copyright: Copyright &copy; 2013 - 2020 Niels Lohmann
# Configuration
theme:
name: material
language: en
palette:
primary: indigo
accent: indigo
font:
text: Roboto
code: Roboto Mono
features:
- tabs
- instant
nav:
- Home:
- index.md
- home/license.md
- "Code of Conduct": home/code_of_conduct.md
- "FAQ": home/faq.md
- home/exceptions.md
- home/design_goals.md
- home/sponsors.md
- Features:
- features/arbitrary_types.md
- Binary Formats:
- features/binary_formats/index.md
- features/binary_formats/bson.md
- features/binary_formats/cbor.md
- features/binary_formats/messagepack.md
- features/binary_formats/ubjson.md
- features/binary_values.md
- features/json_pointer.md
- features/json_patch.md
- features/merge_patch.md
- features/enum_conversion.md
- features/sax_interface.md
- Integration:
- integration/index.md
- integration/cmake.md
- integration/package_managers.md
- Doxygen:
- doxygen/index.html
# Extras
extra:
social:
- icon: fontawesome/brands/github
link: https://github.com/nlohmann
- icon: fontawesome/brands/twitter
link: https://twitter.com/nlohmann
- icon: fontawesome/brands/linkedin
link: https://www.linkedin.com/in/nielslohmann/
- icon: fontawesome/brands/xing
link: https://www.xing.com/profile/Niels_Lohmann
- icon: fontawesome/brands/paypal
link: https://www.paypal.me/nlohmann
# Extensions
markdown_extensions:
- admonition
- codehilite:
guess_lang: false
- toc:
permalink: true
- pymdownx.arithmatex
- pymdownx.betterem:
smart_enable: all
- pymdownx.caret
- pymdownx.critic
- pymdownx.details
- pymdownx.emoji:
emoji_index: !!python/name:materialx.emoji.twemoji
emoji_generator: !!python/name:materialx.emoji.to_svg
- pymdownx.inlinehilite
- pymdownx.magiclink
- pymdownx.mark
#- pymdownx.smartsymbols
- pymdownx.superfences
- pymdownx.tasklist:
custom_checkbox: true
- pymdownx.tabbed
- pymdownx.tilde
- pymdownx.snippets:
base_path: docs
check_paths: true
plugins:
- search:
separator: '[\s\-\.]+'
- mkdocs-simple-hooks:
hooks:
on_post_build: "docs.hooks:copy_doxygen"
doc/mkdocs/requirements.txt 0 → 100644
View file @ a8f0cd15
click>=7.1.2
future>=0.18.2
importlib-metadata>=1.6.0
Jinja2>=2.11.2
joblib>=0.15.1
livereload>=2.6.1
lunr>=0.5.8
Markdown>=3.2.2
markdown-include>=0.5.1
MarkupSafe>=1.1.1
mkdocs>=1.1.2
mkdocs-material>=5.2.1
mkdocs-material-extensions>=1.0
mkdocs-simple-hooks>=0.1.1
nltk>=3.5
Pygments>=2.6.1
pymdown-extensions>=7.1
PyYAML>=5.3.1
regex>=2020.5.14
six>=1.15.0
tornado>=6.0.4
tqdm>=4.46.0
zipp>=3.1.0
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment