diff --git a/.github/workflows/publish_documentation.yml b/.github/workflows/publish_documentation.yml index 1d1973d777..d4fd60907b 100644 --- a/.github/workflows/publish_documentation.yml +++ b/.github/workflows/publish_documentation.yml @@ -25,9 +25,6 @@ jobs: steps: - uses: actions/checkout@v4 - - name: Install and update PlantUML - run: sudo apt-get update ; sudo apt-get install -y plantuml - - name: Install virtual environment run: make install_venv -C docs/mkdocs diff --git a/CMakeLists.txt b/CMakeLists.txt index 27440a5d9c..bcfa907293 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -81,23 +81,23 @@ else() endif() if (NOT JSON_ImplicitConversions) - message(STATUS "Implicit conversions are disabled") + message(STATUS "Implicit conversions are disabled (JSON_USE_IMPLICIT_CONVERSIONS=0)") endif() if (JSON_DisableEnumSerialization) - message(STATUS "Enum integer serialization is disabled") + message(STATUS "Enum integer serialization is disabled (JSON_DISABLE_ENUM_SERIALIZATION=0)") endif() if (JSON_LegacyDiscardedValueComparison) - message(STATUS "Legacy discarded value comparison enabled") + message(STATUS "Legacy discarded value comparison enabled (JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON=1)") endif() if (JSON_Diagnostics) - message(STATUS "Diagnostics enabled") + message(STATUS "Diagnostics enabled (JSON_DIAGNOSTICS=1)") endif() if (NOT JSON_GlobalUDLs) - message(STATUS "User-defined string literals are not put in the global namespace") + message(STATUS "User-defined string literals are not put in the global namespace (JSON_USE_GLOBAL_UDLS=0)") endif() if (JSON_SystemInclude) diff --git a/README.md b/README.md index 94d00880f1..8e14e0eaa9 100644 --- a/README.md +++ b/README.md @@ -39,6 +39,7 @@ - [Conversions to/from arbitrary types](#arbitrary-types-conversions) - [Specializing enum conversion](#specializing-enum-conversion) - [Binary formats (BSON, CBOR, MessagePack, UBJSON, and BJData)](#binary-formats-bson-cbor-messagepack-ubjson-and-bjdata) +- [Customers](#customers) - [Supported compilers](#supported-compilers) - [Integration](#integration) - [CMake](#cmake) @@ -1112,6 +1113,11 @@ binary.set_subtype(0x10); auto cbor = json::to_msgpack(j); // 0xD5 (fixext2), 0x10, 0xCA, 0xFE ``` +## Customers + +The library is used in multiple projects, applications, operating systems, etc. The list below is not exhaustive, but the result of an internet search. If you know further customers of the library, please let me know, see [contact](#contact). + +[![](docs/mkdocs/docs/images/customers.png)](https://json.nlohmann.me/home/customers/) ## Supported compilers diff --git a/cmake/ci.cmake b/cmake/ci.cmake index a4af5e0d1a..9d545485a3 100644 --- a/cmake/ci.cmake +++ b/cmake/ci.cmake @@ -1024,8 +1024,8 @@ add_custom_target(ci_test_examples ) add_custom_target(ci_test_api_documentation - COMMAND ${Python3_EXECUTABLE} scripts/check_structure.py - WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}/docs/mkdocs + COMMAND ${Python3_EXECUTABLE} ../scripts/check_structure.py + WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}/docs/mkdocs/docs COMMENT "Lint the API documentation" ) diff --git a/docs/mkdocs/Makefile b/docs/mkdocs/Makefile index d3356b8202..fa525a5fa7 100644 --- a/docs/mkdocs/Makefile +++ b/docs/mkdocs/Makefile @@ -35,3 +35,11 @@ install_venv: requirements.txt # uninstall the virtual environment uninstall_venv: clean rm -fr venv + +update_requirements: + rm -fr venv_small + python3 -mvenv venv_small + venv_small/bin/pip3 install pur + venv_small/bin/pur -r requirements.txt + rm -fr venv_small venv + make install_venv diff --git a/docs/mkdocs/docs/api/basic_json/accept.md b/docs/mkdocs/docs/api/basic_json/accept.md index 1c806e82f4..b12d6223b9 100644 --- a/docs/mkdocs/docs/api/basic_json/accept.md +++ b/docs/mkdocs/docs/api/basic_json/accept.md @@ -29,9 +29,9 @@ Unlike the [`parse`](parse.md) function, this function neither throws an excepti : A compatible input, for instance: - an `std::istream` object - - a `FILE` pointer (must not be null) + - a `FILE` pointer (throws if null) - a C-style array of characters - - a pointer to a null-terminated string of single byte characters + - a pointer to a null-terminated string of single byte characters (throws if null) - a `std::string` - an object `obj` for which `begin(obj)` and `end(obj)` produces a valid pair of iterators. @@ -64,18 +64,17 @@ Whether the input is valid JSON. Strong guarantee: if an exception is thrown, there are no changes in the JSON value. +## Exceptions + +Throws [`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101) in case of an empty input like a null `FILE*` or `char*` pointer. + ## Complexity Linear in the length of the input. The parser is a predictive LL(1) parser. ## Notes -(1) A UTF-8 byte order mark is silently ignored. - -!!! danger "Runtime assertion" - - The precondition that a passed `#!cpp FILE` pointer must not be null is enforced with a - [runtime assertion](../../features/assertions.md). +A UTF-8 byte order mark is silently ignored. ## Examples @@ -102,6 +101,7 @@ Linear in the length of the input. The parser is a predictive LL(1) parser. - Added in version 3.0.0. - Ignoring comments via `ignore_comments` added in version 3.9.0. +- Changed [runtime assertion](../../features/assertions.md) in case of `FILE*` null pointers to exception in version 3.11.4. !!! warning "Deprecation" diff --git a/docs/mkdocs/docs/api/basic_json/emplace.md b/docs/mkdocs/docs/api/basic_json/emplace.md index 6cc2c98d75..cf637d628f 100644 --- a/docs/mkdocs/docs/api/basic_json/emplace.md +++ b/docs/mkdocs/docs/api/basic_json/emplace.md @@ -14,6 +14,11 @@ created from `args`. `Args` : compatible types to create a `basic_json` object +## Iterator invalidation + +For [`ordered_json`](../ordered_json.md), adding a value to an object can yield a reallocation, in which case all +iterators (including the `end()` iterator) and all references to the elements are invalidated. + ## Parameters `args` (in) diff --git a/docs/mkdocs/docs/api/basic_json/emplace_back.md b/docs/mkdocs/docs/api/basic_json/emplace_back.md index 597ad41e45..21829c216b 100644 --- a/docs/mkdocs/docs/api/basic_json/emplace_back.md +++ b/docs/mkdocs/docs/api/basic_json/emplace_back.md @@ -13,6 +13,12 @@ Creates a JSON value from the passed parameters `args` to the end of the JSON va `Args` : compatible types to create a `basic_json` object +## Iterator invalidation + +By adding an element to the end of the array, a reallocation can happen, in which case all iterators (including the +[`end()`](end.md) iterator) and all references to the elements are invalidated. Otherwise, only the [`end()`](end.md) +iterator is invalidated. + ## Parameters `args` (in) @@ -48,6 +54,11 @@ Amortized constant. --8<-- "examples/emplace_back.output" ``` +## See also + +- [operator+=](operator+=.md) add a value to an array/object +- [push_back](push_back.md) add a value to an array/object + ## Version history - Since version 2.0.8. diff --git a/docs/mkdocs/docs/api/basic_json/exception.md b/docs/mkdocs/docs/api/basic_json/exception.md index 794b7d1e2e..b592d62eec 100644 --- a/docs/mkdocs/docs/api/basic_json/exception.md +++ b/docs/mkdocs/docs/api/basic_json/exception.md @@ -8,24 +8,36 @@ This class is an extension of [`std::exception`](https://en.cppreference.com/w/c member `id` for exception ids. It is used as the base class for all exceptions thrown by the `basic_json` class. This class can hence be used as "wildcard" to catch exceptions, see example below. -```plantuml -std::exception <|-- basic_json::exception -basic_json::exception <|-- basic_json::parse_error -basic_json::exception <|-- basic_json::invalid_iterator -basic_json::exception <|-- basic_json::type_error -basic_json::exception <|-- basic_json::out_of_range -basic_json::exception <|-- basic_json::other_error - -interface std::exception {} - -class basic_json::exception #FFFF00 { - + const int id - + const char* what() const -} - -class basic_json::parse_error { - + const std::size_t byte -} +```mermaid +classDiagram + direction LR + + class std_exception ["std::exception"] { + <> + } + + class json_exception ["basic_json::exception"] { + +const int id + +const char* what() const + } + + class json_parse_error ["basic_json::parse_error"] { + +const std::size_t byte + } + + class json_invalid_iterator ["basic_json::invalid_iterator"] + class json_type_error ["basic_json::type_error"] + class json_out_of_range ["basic_json::out_of_range"] + class json_other_error ["basic_json::other_error"] + + std_exception <|-- json_exception + json_exception <|-- json_parse_error + json_exception <|-- json_invalid_iterator + json_exception <|-- json_type_error + json_exception <|-- json_out_of_range + json_exception <|-- json_other_error + + style json_exception fill:#CCCCFF ``` Subclasses: diff --git a/docs/mkdocs/docs/api/basic_json/get_ptr.md b/docs/mkdocs/docs/api/basic_json/get_ptr.md index b1ecf44d82..7c000f1ac6 100644 --- a/docs/mkdocs/docs/api/basic_json/get_ptr.md +++ b/docs/mkdocs/docs/api/basic_json/get_ptr.md @@ -37,7 +37,9 @@ Constant. The pointer becomes invalid if the underlying JSON object changes. - Consider the following example code where the pointer `ptr` changes after the array is resized. As a result, reading or writing to `ptr` after the array change would be undefined behavior. The address of the first array element changes, because the underlying `std::vector` is resized after adding a fifth element. + Consider the following example code where the pointer `ptr` changes after the array is resized. As a result, + reading or writing to `ptr` after the array change would be undefined behavior. The address of the first array + element changes, because the underlying `std::vector` is resized after adding a fifth element. ```cpp #include diff --git a/docs/mkdocs/docs/api/basic_json/index.md b/docs/mkdocs/docs/api/basic_json/index.md index 648670144e..e90091b532 100644 --- a/docs/mkdocs/docs/api/basic_json/index.md +++ b/docs/mkdocs/docs/api/basic_json/index.md @@ -42,7 +42,15 @@ class basic_json; ## Iterator invalidation -Todo +All operations that add values to an **array** ([`push_back`](push_back.md) , [`operator+=`](operator+=.md), +[`emplace_back`](emplace_back.md), [`insert`](insert.md), and [`operator[]`](operator%5B%5D.md) for a non-existing +index) can yield a reallocation, in which case all iterators (including the [`end()`](end.md) iterator) and all +references to the elements are invalidated. + +For [`ordered_json`](../ordered_json.md), also all operations that add a value to an **object** +([`push_back`](push_back.md), [`operator+=`](operator+=.md), [`emplace`](emplace.md), [`insert`](insert.md), +[`update`](update.md), and [`operator[]`](operator%5B%5D.md) for a non-existing key) can yield a reallocation, in +which case all iterators (including the [`end()`](end.md) iterator) and all references to the elements are invalidated. ## Requirements diff --git a/docs/mkdocs/docs/api/basic_json/insert.md b/docs/mkdocs/docs/api/basic_json/insert.md index 2e6b29301e..b92604887c 100644 --- a/docs/mkdocs/docs/api/basic_json/insert.md +++ b/docs/mkdocs/docs/api/basic_json/insert.md @@ -24,6 +24,17 @@ void insert(const_iterator first, const_iterator last); 4. Inserts elements from initializer list `ilist` into array before iterator `pos`. 5. Inserts elements from range `[first, last)` into object. +## Iterator invalidation + +For all cases where an element is added to an **array**, a reallocation can happen, in which case all iterators +(including the [`end()`](end.md) iterator) and all references to the elements are invalidated. Otherwise, only the +[`end()`](end.md) iterator is invalidated. Also, any iterator or reference after the insertion point will point to the +same index which is now a different value. + +For [`ordered_json`](../ordered_json.md), also adding an element to an **object** can yield a reallocation which again +invalidates all iterators and all references. Also, any iterator or reference after the insertion point will point to +the same index which is now a different value. + ## Parameters `pos` (in) diff --git a/docs/mkdocs/docs/api/basic_json/invalid_iterator.md b/docs/mkdocs/docs/api/basic_json/invalid_iterator.md index f9fdce5b41..3f0f75356a 100644 --- a/docs/mkdocs/docs/api/basic_json/invalid_iterator.md +++ b/docs/mkdocs/docs/api/basic_json/invalid_iterator.md @@ -8,26 +8,36 @@ This exception is thrown if iterators passed to a library function do not match Exceptions have ids 2xx (see [list of iterator errors](../../home/exceptions.md#iterator-errors)). -```plantuml -std::exception <|-- basic_json::exception -basic_json::exception <|-- basic_json::parse_error -basic_json::exception <|-- basic_json::invalid_iterator -basic_json::exception <|-- basic_json::type_error -basic_json::exception <|-- basic_json::out_of_range -basic_json::exception <|-- basic_json::other_error - -interface std::exception {} - -class basic_json::exception { - + const int id - + const char* what() const -} - -class basic_json::parse_error { - + const std::size_t byte -} - -class basic_json::invalid_iterator #FFFF00 {} +```mermaid +classDiagram + direction LR + + class std_exception ["std::exception"] { + <> + } + + class json_exception ["basic_json::exception"] { + +const int id + +const char* what() const + } + + class json_parse_error ["basic_json::parse_error"] { + +const std::size_t byte + } + + class json_invalid_iterator ["basic_json::invalid_iterator"] + class json_type_error ["basic_json::type_error"] + class json_out_of_range ["basic_json::out_of_range"] + class json_other_error ["basic_json::other_error"] + + std_exception <|-- json_exception + json_exception <|-- json_parse_error + json_exception <|-- json_invalid_iterator + json_exception <|-- json_type_error + json_exception <|-- json_out_of_range + json_exception <|-- json_other_error + + style json_invalid_iterator fill:#CCCCFF ``` ## Member functions diff --git a/docs/mkdocs/docs/api/basic_json/items.md b/docs/mkdocs/docs/api/basic_json/items.md index 0b34ddcba3..be32bbfd9f 100644 --- a/docs/mkdocs/docs/api/basic_json/items.md +++ b/docs/mkdocs/docs/api/basic_json/items.md @@ -66,7 +66,7 @@ When iterating over an array, `key()` will return the index of the element as st !!! danger "Lifetime issues" Using `items()` on temporary objects is dangerous. Make sure the object's lifetime exceeds the iteration. See - for more information. + [#2040](https://github.com/nlohmann/json/issues/2040) for more information. ## Examples diff --git a/docs/mkdocs/docs/api/basic_json/operator+=.md b/docs/mkdocs/docs/api/basic_json/operator+=.md index dc5f2ecc44..1591007f63 100644 --- a/docs/mkdocs/docs/api/basic_json/operator+=.md +++ b/docs/mkdocs/docs/api/basic_json/operator+=.md @@ -27,6 +27,15 @@ reference operator+=(initializer_list_t init); `init` is converted into an object element and added using `operator+=(const typename object_t::value_type&)`. Otherwise, `init` is converted to a JSON value and added using `operator+=(basic_json&&)`. +## Iterator invalidation + +For all cases where an element is added to an **array**, a reallocation can happen, in which case all iterators (including +the [`end()`](end.md) iterator) and all references to the elements are invalidated. Otherwise, only the +[`end()`](end.md) iterator is invalidated. + +For [`ordered_json`](../ordered_json.md), also adding an element to an **object** can yield a reallocation which again +invalidates all iterators and all references. + ## Parameters `val` (in) @@ -103,6 +112,11 @@ interpreted as `object_t::value_type` or `std::initializer_list`, se --8<-- "examples/push_back__initializer_list.output" ``` +## See also + +- [emplace_back](emplace_back.md) add a value to an array +- [push_back](push_back.md) add a value to an array/object + ## Version history 1. Since version 1.0.0. diff --git a/docs/mkdocs/docs/api/basic_json/operator[].md b/docs/mkdocs/docs/api/basic_json/operator[].md index 51dd8588cb..3eebd562a7 100644 --- a/docs/mkdocs/docs/api/basic_json/operator[].md +++ b/docs/mkdocs/docs/api/basic_json/operator[].md @@ -34,6 +34,15 @@ const_reference operator[](const json_pointer& ptr) const; [`string_t`](string_t.md) using [`object_comparator_t`](object_comparator_t.md). This can also be a string view (C++17). +## Iterator invalidation + +For the non-const versions 1. and 4., when passing an **array** index that does not exist, it is created and filled with +a `#!json null` value before a reference to it is returned. For this, a reallocation can happen, in which case all +iterators (including the [`end()`](end.md) iterator) and all references to the elements are invalidated. + +For [`ordered_json`](../ordered_json.md), also passing an **object key** to the non-const versions 2., 3., and 4., a +reallocation can happen which again invalidates all iterators and all references. + ## Parameters `idx` (in) diff --git a/docs/mkdocs/docs/api/basic_json/other_error.md b/docs/mkdocs/docs/api/basic_json/other_error.md index 9a83340a04..251c0f3d44 100644 --- a/docs/mkdocs/docs/api/basic_json/other_error.md +++ b/docs/mkdocs/docs/api/basic_json/other_error.md @@ -8,26 +8,36 @@ This exception is thrown in case of errors that cannot be classified with the ot Exceptions have ids 5xx (see [list of other errors](../../home/exceptions.md#further-exceptions)). -```plantuml -std::exception <|-- basic_json::exception -basic_json::exception <|-- basic_json::parse_error -basic_json::exception <|-- basic_json::invalid_iterator -basic_json::exception <|-- basic_json::type_error -basic_json::exception <|-- basic_json::out_of_range -basic_json::exception <|-- basic_json::other_error - -interface std::exception {} - -class basic_json::exception { - + const int id - + const char* what() const -} - -class basic_json::parse_error { - + const std::size_t byte -} - -class basic_json::other_error #FFFF00 {} +```mermaid +classDiagram + direction LR + + class std_exception ["std::exception"] { + <> + } + + class json_exception ["basic_json::exception"] { + +const int id + +const char* what() const + } + + class json_parse_error ["basic_json::parse_error"] { + +const std::size_t byte + } + + class json_invalid_iterator ["basic_json::invalid_iterator"] + class json_type_error ["basic_json::type_error"] + class json_out_of_range ["basic_json::out_of_range"] + class json_other_error ["basic_json::other_error"] + + std_exception <|-- json_exception + json_exception <|-- json_parse_error + json_exception <|-- json_invalid_iterator + json_exception <|-- json_type_error + json_exception <|-- json_out_of_range + json_exception <|-- json_other_error + + style json_other_error fill:#CCCCFF ``` ## Member functions diff --git a/docs/mkdocs/docs/api/basic_json/out_of_range.md b/docs/mkdocs/docs/api/basic_json/out_of_range.md index 6c1f0dfbab..0c21641168 100644 --- a/docs/mkdocs/docs/api/basic_json/out_of_range.md +++ b/docs/mkdocs/docs/api/basic_json/out_of_range.md @@ -9,26 +9,36 @@ instance in case of array indices or nonexisting object keys. Exceptions have ids 4xx (see [list of out-of-range errors](../../home/exceptions.md#out-of-range)). -```plantuml -std::exception <|-- basic_json::exception -basic_json::exception <|-- basic_json::parse_error -basic_json::exception <|-- basic_json::invalid_iterator -basic_json::exception <|-- basic_json::type_error -basic_json::exception <|-- basic_json::out_of_range -basic_json::exception <|-- basic_json::other_error - -interface std::exception {} - -class basic_json::exception { - + const int id - + const char* what() const -} - -class basic_json::parse_error { - + const std::size_t byte -} - -class basic_json::out_of_range #FFFF00 {} +```mermaid +classDiagram + direction LR + + class std_exception ["std::exception"] { + <> + } + + class json_exception ["basic_json::exception"] { + +const int id + +const char* what() const + } + + class json_parse_error ["basic_json::parse_error"] { + +const std::size_t byte + } + + class json_invalid_iterator ["basic_json::invalid_iterator"] + class json_type_error ["basic_json::type_error"] + class json_out_of_range ["basic_json::out_of_range"] + class json_other_error ["basic_json::other_error"] + + std_exception <|-- json_exception + json_exception <|-- json_parse_error + json_exception <|-- json_invalid_iterator + json_exception <|-- json_type_error + json_exception <|-- json_out_of_range + json_exception <|-- json_other_error + + style json_out_of_range fill:#CCCCFF ``` ## Member functions diff --git a/docs/mkdocs/docs/api/basic_json/parse.md b/docs/mkdocs/docs/api/basic_json/parse.md index 49838ad1d4..69d412f977 100644 --- a/docs/mkdocs/docs/api/basic_json/parse.md +++ b/docs/mkdocs/docs/api/basic_json/parse.md @@ -28,9 +28,9 @@ static basic_json parse(IteratorType first, IteratorType last, : A compatible input, for instance: - an `std::istream` object - - a `FILE` pointer (must not be null) + - a `FILE` pointer (throws if null) - a C-style array of characters - - a pointer to a null-terminated string of single byte characters + - a pointer to a null-terminated string of single byte characters (throws if null) - a `std::string` - an object `obj` for which `begin(obj)` and `end(obj)` produces a valid pair of iterators. @@ -73,10 +73,11 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va ## Exceptions -- Throws [`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101) in case of an unexpected token. -- Throws [`parse_error.102`](../../home/exceptions.md#jsonexceptionparse_error102) if to_unicode fails or surrogate +- Throws [`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101) in case of an unexpected token, or + empty input like a null `FILE*` or `char*` pointer. +- Throws [`parse_error.102`](../../home/exceptions.md#jsonexceptionparse_error102) if `to_unicode` fails or surrogate error. -- Throws [`parse_error.103`](../../home/exceptions.md#jsonexceptionparse_error103) if to_unicode fails. +- Throws [`parse_error.103`](../../home/exceptions.md#jsonexceptionparse_error103) if `to_unicode` fails. ## Complexity @@ -86,12 +87,7 @@ super-linear complexity. ## Notes -(1) A UTF-8 byte order mark is silently ignored. - -!!! danger "Runtime assertion" - - The precondition that a passed `#!cpp FILE` pointer must not be null is enforced with a - [runtime assertion](../../features/assertions.md). +A UTF-8 byte order mark is silently ignored. ## Examples @@ -203,6 +199,7 @@ super-linear complexity. - Added in version 1.0.0. - Overload for contiguous containers (1) added in version 2.0.3. - Ignoring comments via `ignore_comments` added in version 3.9.0. +- Changed [runtime assertion](../../features/assertions.md) in case of `FILE*` null pointers to exception in version 3.11.4. !!! warning "Deprecation" diff --git a/docs/mkdocs/docs/api/basic_json/parse_error.md b/docs/mkdocs/docs/api/basic_json/parse_error.md index af3e1f0b36..87b54b4c16 100644 --- a/docs/mkdocs/docs/api/basic_json/parse_error.md +++ b/docs/mkdocs/docs/api/basic_json/parse_error.md @@ -11,24 +11,36 @@ Member `byte` holds the byte index of the last read character in the input file Exceptions have ids 1xx (see [list of parse errors](../../home/exceptions.md#parse-errors)). -```plantuml -std::exception <|-- basic_json::exception -basic_json::exception <|-- basic_json::parse_error -basic_json::exception <|-- basic_json::invalid_iterator -basic_json::exception <|-- basic_json::type_error -basic_json::exception <|-- basic_json::out_of_range -basic_json::exception <|-- basic_json::other_error - -interface std::exception {} - -class basic_json::exception { - + const int id - + const char* what() const -} - -class basic_json::parse_error #FFFF00 { - + const std::size_t byte -} +```mermaid +classDiagram + direction LR + + class std_exception ["std::exception"] { + <> + } + + class json_exception ["basic_json::exception"] { + +const int id + +const char* what() const + } + + class json_parse_error ["basic_json::parse_error"] { + +const std::size_t byte + } + + class json_invalid_iterator ["basic_json::invalid_iterator"] + class json_type_error ["basic_json::type_error"] + class json_out_of_range ["basic_json::out_of_range"] + class json_other_error ["basic_json::other_error"] + + std_exception <|-- json_exception + json_exception <|-- json_parse_error + json_exception <|-- json_invalid_iterator + json_exception <|-- json_type_error + json_exception <|-- json_out_of_range + json_exception <|-- json_other_error + + style json_parse_error fill:#CCCCFF ``` ## Member functions diff --git a/docs/mkdocs/docs/api/basic_json/push_back.md b/docs/mkdocs/docs/api/basic_json/push_back.md index 5c7d20dd6a..e061039300 100644 --- a/docs/mkdocs/docs/api/basic_json/push_back.md +++ b/docs/mkdocs/docs/api/basic_json/push_back.md @@ -27,6 +27,15 @@ void push_back(initializer_list_t init); `init` is converted into an object element and added using `push_back(const typename object_t::value_type&)`. Otherwise, `init` is converted to a JSON value and added using `push_back(basic_json&&)`. +## Iterator invalidation + +For all cases where an element is added to an **array**, a reallocation can happen, in which case all iterators (including +the [`end()`](end.md) iterator) and all references to the elements are invalidated. Otherwise, only the +[`end()`](end.md) iterator is invalidated. + +For [`ordered_json`](../ordered_json.md), also adding an element to an **object** can yield a reallocation which again +invalidates all iterators and all references. + ## Parameters `val` (in) @@ -99,6 +108,11 @@ All functions can throw the following exception: --8<-- "examples/push_back__initializer_list.output" ``` +## See also + +- [emplace_back](emplace_back.md) add a value to an array +- [operator+=](operator+=.md) add a value to an array/object + ## Version history 1. Since version 1.0.0. diff --git a/docs/mkdocs/docs/api/basic_json/type_error.md b/docs/mkdocs/docs/api/basic_json/type_error.md index cda54c089c..4d590556f4 100644 --- a/docs/mkdocs/docs/api/basic_json/type_error.md +++ b/docs/mkdocs/docs/api/basic_json/type_error.md @@ -9,26 +9,36 @@ does not match the expected semantics. Exceptions have ids 3xx (see [list of type errors](../../home/exceptions.md#type-errors)). -```plantuml -std::exception <|-- basic_json::exception -basic_json::exception <|-- basic_json::parse_error -basic_json::exception <|-- basic_json::invalid_iterator -basic_json::exception <|-- basic_json::type_error -basic_json::exception <|-- basic_json::out_of_range -basic_json::exception <|-- basic_json::other_error - -interface std::exception {} - -class basic_json::exception { - + const int id - + const char* what() const -} - -class basic_json::parse_error { - + const std::size_t byte -} - -class basic_json::type_error #FFFF00 {} +```mermaid +classDiagram + direction LR + + class std_exception ["std::exception"] { + <> + } + + class json_exception ["basic_json::exception"] { + +const int id + +const char* what() const + } + + class json_parse_error ["basic_json::parse_error"] { + +const std::size_t byte + } + + class json_invalid_iterator ["basic_json::invalid_iterator"] + class json_type_error ["basic_json::type_error"] + class json_out_of_range ["basic_json::out_of_range"] + class json_other_error ["basic_json::other_error"] + + std_exception <|-- json_exception + json_exception <|-- json_parse_error + json_exception <|-- json_invalid_iterator + json_exception <|-- json_type_error + json_exception <|-- json_out_of_range + json_exception <|-- json_other_error + + style json_type_error fill:#CCCCFF ``` ## Member functions diff --git a/docs/mkdocs/docs/api/basic_json/update.md b/docs/mkdocs/docs/api/basic_json/update.md index f3546157a7..bfe785d743 100644 --- a/docs/mkdocs/docs/api/basic_json/update.md +++ b/docs/mkdocs/docs/api/basic_json/update.md @@ -17,6 +17,11 @@ recursively merges objects with common keys. The function is motivated by Python's [dict.update](https://docs.python.org/3.6/library/stdtypes.html#dict.update) function. +## Iterator invalidation + +For [`ordered_json`](../ordered_json.md), adding a value to an object can yield a reallocation, in which case all +iterators (including the `end()` iterator) and all references to the elements are invalidated. + ## Parameters `j` (in) diff --git a/docs/mkdocs/docs/api/macros/index.md b/docs/mkdocs/docs/api/macros/index.md index ae9eb20443..d37df592b5 100644 --- a/docs/mkdocs/docs/api/macros/index.md +++ b/docs/mkdocs/docs/api/macros/index.md @@ -42,7 +42,6 @@ header. See also the [macro overview page](../../features/macros.md). - [**JSON_DISABLE_ENUM_SERIALIZATION**](json_disable_enum_serialization.md) - switch off default serialization/deserialization functions for enums - [**JSON_USE_IMPLICIT_CONVERSIONS**](json_use_implicit_conversions.md) - control implicit conversions - ## Comparison behavior - [**JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON**](json_use_legacy_discarded_value_comparison.md) - @@ -50,6 +49,20 @@ header. See also the [macro overview page](../../features/macros.md). ## Serialization/deserialization macros +- Enum: [**NLOHMANN_JSON_SERIALIZE_ENUM**](nlohmann_json_serialize_enum.md) +- Class/struct: + - Do you need to serialize private variables? + - Yes? Do you only need serialization? + - Yes? `NLOHMANN_DEFINE_TYPE_INTRUSIVE_ONLY_SERIALIZE` + - No? Allow deserialization of JSON values with missing values? + - Yes? `NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT` + - No? `NLOHMANN_DEFINE_TYPE_INTRUSIVE` + - No? Do you only need serialization? + - Yes? `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE` + - No? Allow deserialization of JSON values with missing values? + - Yes? `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT` + - No? `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE` + - [**NLOHMANN_DEFINE_TYPE_INTRUSIVE(type, member...)**
**NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT(type, member...)**
**NLOHMANN_DEFINE_TYPE_INTRUSIVE_ONLY_SERIALIZE(type, member...)**][DefInt] \- serialization/deserialization of types _with_ access to private variables diff --git a/docs/mkdocs/docs/api/macros/json_use_implicit_conversions.md b/docs/mkdocs/docs/api/macros/json_use_implicit_conversions.md index 557dfa299e..4d962c2ee8 100644 --- a/docs/mkdocs/docs/api/macros/json_use_implicit_conversions.md +++ b/docs/mkdocs/docs/api/macros/json_use_implicit_conversions.md @@ -27,7 +27,7 @@ By default, implicit conversions are enabled. !!! hint "CMake option" Implicit conversions can also be controlled with the CMake option - [`JSON_ImplicitConversions`](../../integration/cmake.md#json_legacydiscardedvaluecomparison) + [`JSON_ImplicitConversions`](../../integration/cmake.md#json_implicitconversions) (`ON` by default) which defines `JSON_USE_IMPLICIT_CONVERSIONS` accordingly. ## Examples diff --git a/docs/mkdocs/docs/api/macros/json_use_legacy_discarded_value_comparison.md b/docs/mkdocs/docs/api/macros/json_use_legacy_discarded_value_comparison.md index bc1d1434a7..65f3f1767d 100644 --- a/docs/mkdocs/docs/api/macros/json_use_legacy_discarded_value_comparison.md +++ b/docs/mkdocs/docs/api/macros/json_use_legacy_discarded_value_comparison.md @@ -56,7 +56,7 @@ When the macro is not defined, the library will define it to its default value. !!! hint "CMake option" Legacy comparison can also be controlled with the CMake option - [`JSON_LegacyDiscardedValueComparison`](../../integration/cmake.md#json_legacydiscardedvaluecomparison) + [`JSON_LegacyDiscardedValueComparison`](../../integration/cmake.md#json_implicitconversions) (`OFF` by default) which defines `JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON` accordingly. ## Examples diff --git a/docs/mkdocs/docs/api/macros/nlohmann_define_derived_type.md b/docs/mkdocs/docs/api/macros/nlohmann_define_derived_type.md index e7c92ada2a..b12280f058 100644 --- a/docs/mkdocs/docs/api/macros/nlohmann_define_derived_type.md +++ b/docs/mkdocs/docs/api/macros/nlohmann_define_derived_type.md @@ -1,6 +1,5 @@ -# NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE, NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_WITH_DEFAULT - -# NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE, NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_WITH_DEFAULT +

NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE, NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_WITH_DEFAULT, + NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE, NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_WITH_DEFAULT

```cpp #define NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE(type, base_type, member...) // (1) @@ -19,7 +18,6 @@ Like [`NLOHMANN_DEFINE_TYPE_INTRUSIVE`](nlohmann_define_type_intrusive.md), they Like [`NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE`](nlohmann_define_type_non_intrusive.md), they **cannot** access private members. - The first parameter is the name of the derived class/struct, the second parameter is the name of the base class/struct and all remaining parameters name the members. The base type **must** be already serializable/deserializable. diff --git a/docs/mkdocs/docs/api/operator_literal_json.md b/docs/mkdocs/docs/api/operator_literal_json.md index bc2b2cfc5d..a3a4bd28b5 100644 --- a/docs/mkdocs/docs/api/operator_literal_json.md +++ b/docs/mkdocs/docs/api/operator_literal_json.md @@ -17,7 +17,7 @@ using namespace nlohmann; ``` This is suggested to ease migration to the next major version release of the library. See -['JSON_USE_GLOBAL_UDLS`](macros/json_use_global_udls.md#notes) for details. +[`JSON_USE_GLOBAL_UDLS`](macros/json_use_global_udls.md#notes) for details. ## Parameters diff --git a/docs/mkdocs/docs/api/operator_literal_json_pointer.md b/docs/mkdocs/docs/api/operator_literal_json_pointer.md index 0e12440e19..423678c77b 100644 --- a/docs/mkdocs/docs/api/operator_literal_json_pointer.md +++ b/docs/mkdocs/docs/api/operator_literal_json_pointer.md @@ -16,7 +16,7 @@ using namespace nlohmann::literals::json_literals; using namespace nlohmann; ``` This is suggested to ease migration to the next major version release of the library. See -['JSON_USE_GLOBAL_UDLS`](macros/json_use_global_udls.md#notes) for details. +[`JSON_USE_GLOBAL_UDLS`](macros/json_use_global_udls.md#notes) for details. ## Parameters diff --git a/docs/mkdocs/docs/api/ordered_json.md b/docs/mkdocs/docs/api/ordered_json.md index 7cfd9f4dde..f4062d13da 100644 --- a/docs/mkdocs/docs/api/ordered_json.md +++ b/docs/mkdocs/docs/api/ordered_json.md @@ -6,6 +6,13 @@ using ordered_json = basic_json; This type preserves the insertion order of object keys. +## Iterator invalidation + +The type is based on [`ordered_map`](ordered_map.md) which in turn uses a `std::vector` to store object elements. +Therefore, adding object elements can yield a reallocation in which case all iterators (including the +[`end()`](basic_json/end.md) iterator) and all references to the elements are invalidated. Also, any iterator or +reference after the insertion point will point to the same index which is now a different value. + ## Examples ??? example diff --git a/docs/mkdocs/docs/api/ordered_map.md b/docs/mkdocs/docs/api/ordered_map.md index 160b85c28b..ca4934161c 100644 --- a/docs/mkdocs/docs/api/ordered_map.md +++ b/docs/mkdocs/docs/api/ordered_map.md @@ -23,6 +23,11 @@ A minimal map-like container that preserves insertion order for use within [`nlo `Allocator` : allocator type +## Iterator invalidation + +The type uses a `std::vector` to store object elements. Therefore, adding elements can yield a reallocation in which +case all iterators (including the `end()` iterator) and all references to the elements are invalidated. + ## Member types - **key_type** - key type (`Key`) diff --git a/docs/mkdocs/docs/features/arbitrary_types.md b/docs/mkdocs/docs/features/arbitrary_types.md index e2e7893381..449671c93c 100644 --- a/docs/mkdocs/docs/features/arbitrary_types.md +++ b/docs/mkdocs/docs/features/arbitrary_types.md @@ -75,7 +75,7 @@ Likewise, when calling `template get()` or `get_to(your_type&)`, the 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. +* Those methods **MUST** be available (e.g., proper headers must be included) everywhere you use these conversions. Look at [#1108](https://github.com/nlohmann/json/issues/1108) for errors that may occur otherwise. * When using `template get()`, `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()`](../api/basic_json/at.md) 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. diff --git a/docs/mkdocs/docs/features/assertions.md b/docs/mkdocs/docs/features/assertions.md index 2bad62e81d..32b4e019b1 100644 --- a/docs/mkdocs/docs/features/assertions.md +++ b/docs/mkdocs/docs/features/assertions.md @@ -103,29 +103,38 @@ behavior and yields a runtime assertion. Assertion failed: (m_object != nullptr), function operator++, file iter_impl.hpp, line 368. ``` -### Reading from a null `FILE` pointer +## Changes -Reading from a null `#!cpp FILE` pointer is undefined behavior and yields a runtime assertion. This can happen when -calling `#!cpp std::fopen` on a nonexistent file. +### Reading from a null `FILE` or `char` pointer -??? example "Example 4: Uninitialized iterator" +Reading from a null `#!cpp FILE` or `#!cpp char` pointer in C++ is undefined behavior. Until version 3.11.4, this +library asserted that the pointer was not `nullptr` using a runtime assertion. If assertions were disabled, this would +result in undefined behavior. Since version 3.11.4, this library checks for `nullptr` and throws a +[`parse_error.101`](../home/exceptions.md#jsonexceptionparse_error101) to prevent the undefined behavior. + +??? example "Example 4: Reading from null pointer" The following code will trigger an assertion at runtime: ```cpp + #include #include using json = nlohmann::json; int main() { - std::FILE* f = std::fopen("nonexistent_file.json", "r"); - json j = json::parse(f); + std::FILE* f = std::fopen("nonexistent_file.json", "r"); + try { + json j = json::parse(f); + } catch (std::exception& e) { + std::cerr << e.what() << std::endl; + } } ``` Output: ``` - Assertion failed: (m_file != nullptr), function file_input_adapter, file input_adapters.hpp, line 55. + [json.exception.parse_error.101] parse error: attempting to parse an empty input; check that your input string or stream contains the expected JSON ``` diff --git a/docs/mkdocs/docs/features/binary_values.md b/docs/mkdocs/docs/features/binary_values.md index 5ad6433cff..4a15a2ee46 100644 --- a/docs/mkdocs/docs/features/binary_values.md +++ b/docs/mkdocs/docs/features/binary_values.md @@ -10,17 +10,19 @@ serialized JSON text if they have been created manually or via a binary format. ## API for binary values -```plantuml -class json::binary_t { - -- setters -- +```mermaid +classDiagram + +class binary_t ["json::binary_t"] { +void set_subtype(std::uint64_t subtype) +void clear_subtype() - -- getters -- +std::uint64_t subtype() const +bool has_subtype() const } -"std::vector" <|-- json::binary_t +class vector ["std::vector"] + +vector <|-- binary_t ``` By default, binary values are stored as `std::vector`. This type can be changed by providing a template diff --git a/docs/mkdocs/docs/features/comments.md b/docs/mkdocs/docs/features/comments.md index 61266d9caf..e99cceb49d 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/features/iterators.md b/docs/mkdocs/docs/features/iterators.md index ce627e0126..ca303cb4a2 100644 --- a/docs/mkdocs/docs/features/iterators.md +++ b/docs/mkdocs/docs/features/iterators.md @@ -100,7 +100,7 @@ for (auto& [key, val] : j_object.items()) !!! warning - Using `items()` on temporary objects is dangerous. Make sure the object's lifetime exceeds the iteration. See for more information. + Using `items()` on temporary objects is dangerous. Make sure the object's lifetime exceeds the iteration. See [#2040](https://github.com/nlohmann/json/issues/2040) for more information. ### Reverse iteration order diff --git a/docs/mkdocs/docs/features/macros.md b/docs/mkdocs/docs/features/macros.md index 926741b091..63457290f1 100644 --- a/docs/mkdocs/docs/features/macros.md +++ b/docs/mkdocs/docs/features/macros.md @@ -100,6 +100,11 @@ When defined to `0`, implicit conversions are switched off. By default, implicit See [full documentation of `JSON_USE_IMPLICIT_CONVERSIONS`](../api/macros/json_use_implicit_conversions.md). +## `NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE(type, base_type, member...)` +## `NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_WITH_DEFAULT(type, base_type, member...)` +## `NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE(type, base_type, member...)` +## `NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_WITH_DEFAULT(type, base_type, member...)` + ## `NLOHMANN_DEFINE_TYPE_INTRUSIVE(type, member...)` This macro can be used to simplify the serialization/deserialization of types if (1) want to use a JSON object as diff --git a/docs/mkdocs/docs/features/namespace.md b/docs/mkdocs/docs/features/namespace.md index 8cee2ccfe7..460cb3be5c 100644 --- a/docs/mkdocs/docs/features/namespace.md +++ b/docs/mkdocs/docs/features/namespace.md @@ -30,15 +30,16 @@ nlohmann::json_abi_diag_v3_11_2 Several incompatibilities have been observed. Amongst the most common ones is linking code compiled with different definitions of [`JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md). This is illustrated in the diagram below. -```plantuml -[**nlohmann_json (v3.10.5)**\nJSON_DIAGNOSTICS=0] as [json] -[**nlohmann_json (v3.10.5)**\nJSON_DIAGNOSTICS=1] as [json_diag] -[**some_library**] as [library] -[**application**] as [app] - -[library] ..|> [json] -[app] ..|> [json_diag] -[app] ..|>[library] +```mermaid +graph + json["nlohmann_json (v3.10.5)
JSON_DIAGNOSTICS=0"] + json_diag["nlohmann_json (v3.10.5)
JSON_DIAGNOSTICS=1"] + library["some library"] + app["application"] + + library --> json + app --> json_diag + app --> library ``` In releases prior to 3.11.0, mixing any version of the JSON library with different `JSON_DIAGNOSTICS` settings would diff --git a/docs/mkdocs/docs/features/parsing/sax_interface.md b/docs/mkdocs/docs/features/parsing/sax_interface.md index 0796a55f52..5a9c83a7b3 100644 --- a/docs/mkdocs/docs/features/parsing/sax_interface.md +++ b/docs/mkdocs/docs/features/parsing/sax_interface.md @@ -2,27 +2,30 @@ The library uses a SAX-like interface with the following functions: -```plantuml -interface json::sax_t { - + {abstract} bool null() - - + {abstract} bool boolean(bool val) - - + {abstract} bool number_integer(number_integer_t val) - + {abstract} bool number_unsigned(number_unsigned_t val) - - + {abstract} bool number_float(number_float_t val, const string_t& s) - - + {abstract} bool string(string_t& val) - + {abstract} bool binary(binary_t& val) - - + {abstract} bool start_object(std::size_t elements) - + {abstract} bool end_object() - + {abstract} bool start_array(std::size_t elements) - + {abstract} bool end_array() - + {abstract} bool key(string_t& val) - - + {abstract} bool parse_error(std::size_t position, const std::string& last_token, const json::exception& ex) +```mermaid +classDiagram + +class sax_t ["json::sax_t"] { + <> + +bool null()* + + +bool boolean(bool val)* + + +bool number_integer(number_integer_t val)* + +bool number_unsigned(number_unsigned_t val)* + + +bool number_float(number_float_t val, const string_t& s)* + + +bool string(string_t& val)* + +bool binary(binary_t& val)* + + +bool start_object(std::size_t elements)* + +bool end_object()* + +bool start_array(std::size_t elements)* + +bool end_array()* + +bool key(string_t& val)* + + +bool parse_error(std::size_t position, const std::string& last_token, const json::exception& ex)* } ``` diff --git a/docs/mkdocs/docs/features/types/index.md b/docs/mkdocs/docs/features/types/index.md index d9dfcc29a0..1a2a811955 100644 --- a/docs/mkdocs/docs/features/types/index.md +++ b/docs/mkdocs/docs/features/types/index.md @@ -19,8 +19,11 @@ Note there are three different types for numbers - when parsing JSON text, the b ## Storage -```plantuml -enum value_t { +```mermaid +classDiagram + +class value_t { + <> null object array @@ -33,7 +36,8 @@ enum value_t { discarded } -class json_value << (U,orchid) >> { +class json_value { + <> object_t* object array_t* array string_t* string @@ -45,17 +49,15 @@ class json_value << (U,orchid) >> { } class basic_json { - -- type and value -- - value_t m_type - json_value m_value - -- derived types -- - + typedef object_t - + typedef array_t - + typedef binary_t - + typedef boolean_t - + typedef number_integer_t - + typedef number_unsigned_t - + typedef number_float_t + -value_t m_type + -json_value m_value + +typedef object_t + +typedef array_t + +typedef binary_t + +typedef boolean_t + +typedef number_integer_t + +typedef number_unsigned_t + +typedef number_float_t } basic_json .. json_value diff --git a/docs/mkdocs/docs/home/customers.md b/docs/mkdocs/docs/home/customers.md new file mode 100644 index 0000000000..5b43f2dbf2 --- /dev/null +++ b/docs/mkdocs/docs/home/customers.md @@ -0,0 +1,157 @@ +# Customers + +The library is used in multiple projects, applications, operating systems, etc. The list below is not exhaustive, but +the result of an internet search. If you know further customers of the library, [please let me know](mailto:mail@nlohmann.me). + +![](../images/customers.png) + +## Space Exploration + +- [**Peregrine Lunar Lander Flight 01**](https://en.wikipedia.org/wiki/Peregrine_Mission_One) - The library was utilized for payload management in the **Peregrine Moon Lander**, developed by **Astrobotic Technology** and launched as part of NASA's **Commercial Lunar Payload Services (CLPS)** program. After six days in orbit, the spacecraft was intentionally redirected into Earth's atmosphere, where it burned up over the Pacific Ocean on **January 18, 2024**. + +## Automotive + +- [**Alexa Auto SDK**](https://github.com/alexa/alexa-auto-sdk), a software development kit enabling the integration of Alexa into automotive systems +- [**Apollo**](https://github.com/ApolloAuto/apollo), a framework for building autonomous driving systems +- [**Automotive Grade Linux (AGL)**](https://download.automotivelinux.org/AGL/release/jellyfish/latest/qemux86-64/deploy/licenses/nlohmann-json/): a collaborative open-source platform for automotive software development +- [**Genesis Motor** (infotainment)](http://webmanual.genesis.com/ccIC/AVNT/JW/KOR/English/reference010.html), a luxury automotive brand +- [**Hyundai** (infotainment)](https://www.hyundai.com/wsvc/ww/download.file.do?id=/content/hyundai/ww/data/opensource/data/GN7-2022/licenseCode/info), a global automotive brand +- [**Kia** (infotainment)](http://webmanual.kia.com/PREM_GEN6/AVNT/RJPE/KOR/Korean/reference010.html), a global automotive brand +- [**Mercedes-Benz Operating System (MB.OS)**](https://group.mercedes-benz.com/careers/about-us/mercedes-benz-operating-system/), a core component of the vehicle software ecosystem from Mercedes-Benz +- [**Rivian** (infotainment)](https://assets.ctfassets.net/2md5qhoeajym/3cwyo4eoufk4yingUwusFt/ded2c47da620fdfc99c88c7156d2c1d8/In-Vehicle_OSS_Attribution_2024__11-24_.pdf), an electric vehicle manufacturer +- [**Suzuki** (infotainment)](https://www.globalsuzuki.com/motorcycle/ipc/oss/oss_48KA_00.pdf), a global automotive and motorcycle manufacturer + +## Gaming and Entertainment + +- [**Assassin's Creed: Mirage**](https://www.mobygames.com/person/1195889/niels-lohmann/credits/): a stealth-action game set in the Middle East, focusing on the journey of a young assassin with classic parkour and stealth mechanics +- [**Chasm: The Rift**](https://www.mobygames.com/person/1195889/niels-lohmann/credits/): a first-person shooter blending horror and adventure, where players navigate dark realms and battle monsters +- [**College Football 25**](https://www.mobygames.com/person/1195889/niels-lohmann/credits/): a college football simulation game featuring gameplay that mimics real-life college teams and competitions +- [**Concepts**](https://concepts.app/en/licenses): a digital sketching app designed for creative professionals, offering flexible drawing tools for illustration, design, and brainstorming +- [**Depthkit**](https://www.depthkit.tv/third-party-licenses): a tool for creating and capturing volumetric video, enabling immersive 3D experiences and interactive content +- [**immersivetech**](https://immersitech.io/open-source-third-party-software/): a technology company focused on immersive experiences, providing tools and solutions for virtual and augmented reality applications +- [**LOOT**](https://loot.readthedocs.io/_/downloads/en/0.13.0/pdf/), a tool for optimizing the load order of game plugins, commonly used in The Elder Scrolls and Fallout series +- [**Madden NFL 25**](https://www.mobygames.com/person/1195889/niels-lohmann/credits/): a sports simulation game capturing the excitement of American football with realistic gameplay and team management features +- [**Marne**](https://marne.io/licenses), an unofficial private server platform for hosting custom Battlefield 1 game experiences +- [**Minecraft**](https://www.minecraft.net/zh-hant/attribution), a popular sandbox video game +- [**NHL 22**](https://www.mobygames.com/person/1195889/niels-lohmann/credits/): a hockey simulation game offering realistic gameplay, team management, and various modes to enhance the hockey experience +- [**Pixelpart**](https://pixelpart.net/documentation/book/third-party.html): a 2D animation and video compositing software that allows users to create animated graphics and visual effects with a focus on simplicity and ease of use +- [**Red Dead Redemption II**](https://www.mobygames.com/person/1195889/niels-lohmann/credits/): an open-world action-adventure game following an outlaw's story in the late 1800s, emphasizing deep storytelling and immersive gameplay +- [**Tactics Ogre: Reborn**](https://www.square-enix-games.com/en_US/documents/tactics-ogre-reborn-pc-installer-software-and-associated-plug-ins-disclosure), a tactical role-playing game featuring strategic battles and deep storytelling elements +- [**Throne and Liberty**](https://www.amazon.com/gp/help/customer/display.html?nodeId=T7fLNw5oAevCMtJFPj&pop-up=1), an MMORPG that offers an expansive fantasy world with dynamic gameplay and immersive storytelling +- [**Unity Vivox**](https://docs.unity3d.com/Packages/com.unity.services.vivox@15.1/license/Third%20Party%20Notices.html), a communication service that enables voice and text chat functionality in multiplayer games developed with Unity +- [**Zool: Redimensioned**](https://www.mobygames.com/person/1195889/niels-lohmann/credits/): a modern reimagining of the classic platformer featuring fast-paced gameplay and vibrant environments + +## Consumer Electronics + +- [**Audinate**](https://www.audinate.com/legal/software-licensing/dante-av-h-open-source-licenses/): a provider of networked audio solutions specializing in Dante technology, which facilitates high-quality digital audio transport over IP networks +- [**Cisco Webex Desk Camera**](https://www.cisco.com/c/dam/en_us/about/doing_business/open_source/docs/CiscoWebexDeskCamera-23-1622100417.pdf), a video camera designed for professional-quality video conferencing and remote collaboration +- [**Philips Hue Personal Wireless Lighting**](http://2ak5ape.257.cz/): a smart lighting system for customizable and wireless home illumination +- [**Ray-Ban Meta Smart glasses**](https://www.meta.com/de/en/legal/smart-glasses/third-party-notices-android/03/), a pair of smart glasses designed for capturing photos and videos with integrated connectivity and social features +- [**Siemens SINEMA Remote Connect**](https://cache.industry.siemens.com/dl/files/790/109793790/att_1054961/v2/OSS_SINEMA-RC_86.pdf), a remote connectivity solution for monitoring and managing industrial networks and devices securely +- [**Sony PlayStation 4**](https://doc.dl.playstation.net/doc/ps4-oss/index.html), a gaming console developed by Sony that offers a wide range of games and multimedia entertainment features +- [**Sony Virtual Webcam Driver for Remote Camera**](https://helpguide.sony.net/rc/vwd/v1/zh-cn/print.pdf), a software driver that enables the use of Sony cameras as virtual webcams for video conferencing and streaming + +## Operating Systems + +- [**Apple iOS and macOS**](https://www.apple.com/macos), a family of operating systems developed by Apple, including iOS for mobile devices and macOS for desktop computers +- [**Google Fuchsia**](https://fuchsia.googlesource.com/third_party/json/), an open-source operating system developed by Google, designed to be secure, updatable, and adaptable across various devices +- [**SerenityOS**](https://github.com/SerenityOS/serenity), an open-source operating system that aims to provide a simple and beautiful user experience with a focus on simplicity and elegance +- [**Yocto**](http://ftp.emacinc.com/openembedded-sw/kirkstone-icop-5.15-kirkstone-6.0/archive-2024-10/pn8m-090t-ppc/licenses/nlohmann-json/): a Linux-based build system for creating custom operating systems and software distributions, tailored for embedded devices and IoT applications + +## Development Tools and IDEs + +- [**Accentize SpectralBalance**](https://www.accentize.com/products/SpectralBalanceManual.pdf), an adaptive speech analysis tool designed to enhance audio quality by optimizing frequency balance in recordings +- [**Arm Compiler for Linux**](https://documentation-service.arm.com/static/66558e9d876c8d213b7843e4), a software development toolchain for compiling and optimizing applications on Arm-based Linux systems +- [**BBEdit**](https://s3.amazonaws.com/BBSW-download/BBEdit_15.1.2_User_Manual.pdf), a professional text and code editor for macOS +- [**CoderPad**](https://coderpad.io), a collaborative coding platform that enables real-time code interviews and assessments for developers; the library is included in every CoderPad instance and can be accessed with a simple `#include "json.hpp"` +- [**Compiler Explorer**](https://godbolt.org), a web-based tool that allows users to write, compile, and visualize the assembly output of code in various programming languages; the library is readily available and accessible with the directive `#include `. +- [**GitHub CodeQL**](https://github.com/github/codeql), a code analysis tool used for identifying security vulnerabilities and bugs in software through semantic queries +- [**Hex-Rays**](https://docs.hex-rays.com/user-guide/user-interface/licenses): a reverse engineering toolset for analyzing and decompiling binaries, primarily used for security research and vulnerability analysis +- [**ImHex**](https://github.com/WerWolv/ImHex), a hex editor designed for reverse engineering, providing advanced features for data analysis and manipulation +- [**Intel GPA Framework**](https://intel.github.io/gpasdk-doc/src/licenses.html), a suite of cross-platform tools for capturing, analyzing, and optimizing graphics applications across different APIs +- [**Meta Yoga**](https://github.com/facebook/yoga), a layout engine that facilitates flexible and efficient user interface design across multiple platforms +- [**NVIDIA Nsight Compute**](https://docs.nvidia.com/nsight-compute/2022.2/pdf/CopyrightAndLicenses.pdf), a performance analysis tool for CUDA applications that provides detailed insights into GPU performance metrics +- [**Notepad++**](https://github.com/notepad-plus-plus/notepad-plus-plus), a free source code editor that supports various programming languages +- [**OpenRGB**](https://gitlab.com/CalcProgrammer1/OpenRGB), an open source RGB lighting control that doesn't depend on manufacturer software +- [**OpenTelemetry C++**](https://github.com/open-telemetry/opentelemetry-cpp): a library for collecting and exporting observability data in C++, enabling developers to implement distributed tracing and metrics in their application +- [**Qt Creator**](https://doc.qt.io/qtcreator/qtcreator-attribution-json-nlohmann.html), an IDE for developing applications using the Qt application framework +- [**Scanbot SDK**](https://docs.scanbot.io/barcode-scanner-sdk/web/third-party-libraries/): a software development kit (SDK) that provides tools for integrating advanced document scanning and barcode scanning capabilities into applications + +## Machine Learning and AI + +- [**Apple Core ML Tools**](https://github.com/apple/coremltools), a set of tools for converting and configuring machine learning models for deployment in Apple's Core ML framework +- [**Avular Mobile Robotics**](https://www.avular.com/licenses/nlohmann-json-3.9.1.txt): a platform for developing and deploying mobile robotics solutions +- [**Google gemma.cpp**](https://github.com/google/gemma.cpp), a lightweight C++ inference engine designed for running AI models from the Gemma family +- [**llama.cpp**](https://github.com/ggerganov/llama.cpp), a C++ library designed for efficient inference of large language models (LLMs), enabling streamlined integration into applications +- [**Mozilla llamafile**](https://github.com/Mozilla-Ocho/llamafile), a tool designed for distributing and executing large language models (LLMs) efficiently using a single file format +- [**NVIDIA ACE**](https://docs.nvidia.com/ace/latest/index.html), a suite of real-time AI solutions designed for the development of interactive avatars and digital human applications, enabling scalable and sophisticated user interactions +- [**Peer**](https://support.peer.inc/hc/en-us/articles/17261335054235-Licenses): a platform offering personalized AI assistants for interactive learning and creative collaboration +- [**stable-diffusion.cpp**](https://github.com/leejet/stable-diffusion.cpp): a C++ implementation of the Stable Diffusion image generation model +- [**TanvasTouch**](https://tanvas.co/tanvastouch-sdk-third-party-acknowledgments): a software development kit (SDK) that enables developers to create tactile experiences on touchscreens, allowing users to feel textures and physical sensations in a digital environment +- [**TensorFlow**](https://github.com/tensorflow/tensorflow), a machine learning framework that facilitates the development and training of models, supporting data serialization and efficient data exchange between components + +## Scientific Research and Analysis + +- [**BLACK**](https://www.black-sat.org/en/stable/installation/linux.html), a bounded linear temporal logic (LTL) satisfiability checker +- [**CERN Atlas Athena**](https://gitlab.cern.ch/atlas/athena/-/blob/main/Control/PerformanceMonitoring/PerfMonComps/src/PerfMonMTSvc.h), a software framework used in the ATLAS experiment at the Large Hadron Collider (LHC) for performance monitoring +- [**KAMERA**](https://github.com/Kitware/kamera): a platform for synchronized data collection and real-time deep learning to map marine species like polar bears and seals, aiding Arctic ecosystem research +- [**KiCad**](https://gitlab.com/kicad/code/kicad/-/tree/master/thirdparty/nlohmann_json): a free and open-source software suite for electronic design automation +- [**MeVisLab**](https://mevislabdownloads.mevis.de/docs/current/MeVis/ThirdParty/Documentation/Publish/ThirdPartyReference/index.html): a software framework for medical image processing and visualization. +- [**OpenPMD API**](https://openpmd-api.readthedocs.io/en/0.8.0-alpha/backends/json.html): a versatile programming interface for accessing and managing scientific data, designed to facilitate the efficient storage, retrieval, and sharing of simulation data across various applications and platforms +- [**ParaView**](https://github.com/Kitware/ParaView): an open-source tool for large-scale data visualization and analysis across various scientific domains +- [**QGIS**](https://gitlab.b-data.ch/qgis/qgis/-/blob/backport-57658-to-release-3_34/external/nlohmann/json.hpp): a free and open-source geographic information system (GIS) application that allows users to create, edit, visualize, and analyze geospatial data across a variety of formats +- [**VTK**](https://github.com/Kitware/VTK): a software library for 3D computer graphics, image processing, and visualization +- [**VolView**](https://github.com/Kitware/VolView): a lightweight application for interactive visualization and analysis of 3D medical imaging data. + +## Business and Productivity Software + +- [**ArcGIS PRO**](https://www.esri.com/content/dam/esrisites/en-us/media/legal/open-source-acknowledgements/arcgis-pro-2-8-attribution-report.html), a desktop geographic information system (GIS) application developed by Esri for mapping and spatial analysis +- [**Autodesk Desktop**](https://damassets.autodesk.net/content/dam/autodesk/www/Company/legal-notices-trademarks/autodesk-desktop-platform-components/internal-autodesk-components-web-page-2023.pdf), a software platform developed by Autodesk for creating and managing desktop applications and services +- [**Check Point**](https://www.checkpoint.com/about-us/copyright-and-trademarks/): a cybersecurity company specializing in threat prevention and network security solutions, offering a range of products designed to protect enterprises from cyber threats and ensure data integrity +- [**Microsoft Office for Mac**](https://officecdnmac.microsoft.com/pr/legal/mac/OfficeforMacAttributions.html), a suite of productivity applications developed by Microsoft for macOS, including tools for word processing, spreadsheets, and presentations +- [**Nexthink Infinity**](https://docs.nexthink.com/legal/services-terms/experience-open-source-software-licenses/infinity-2022.8-software-licenses): a digital employee experience management platform for monitoring and improving IT performance +- [**Sophos Connect Client**](https://docs.sophos.com/nsg/licenses/SophosConnect/SophosConnectAttribution.html): a secure VPN client from Sophos that allows remote users to connect to their corporate network, ensuring secure access to resources and data +- [**Stonebranch**](https://stonebranchdocs.atlassian.net/wiki/spaces/UA77/pages/799545647/Licenses+for+Third-Party+Libraries): a cloud-based cybersecurity solution that integrates backup, disaster recovery, and cybersecurity features to protect data and ensure business continuity for organizations +- [**Tablecruncher**](https://tablecruncher.com/): a data analysis tool that allows users to import, analyze, and visualize spreadsheet data, offering interactive features for better insights and decision-making +- [**magicplan**](https://help.magicplan.app/acknowledgments), a mobile application for creating floor plans and interior designs using augmented reality + +## Databases and Big Data + +- [**ADIOS2**](https://code.ornl.gov/ecpcitest/adios2/-/tree/pr4285_FFSUpstream/thirdparty/nlohmann_json?ref_type=heads): a data management framework designed for high-performance input and output operations +- [**Cribl Stream**](https://docs.cribl.io/stream/third-party-current-list/): a real-time data processing platform that enables organizations to collect, route, and transform observability data, enhancing visibility and insights into their systems +- [**DB Browser for SQLite**](https://github.com/sqlitebrowser/sqlitebrowser), a visual open-source tool for creating, designing, and editing SQLite database files +- [**MySQL Connector/C++**](https://docs.oracle.com/cd/E17952_01/connector-cpp-9.1-license-com-en/license-opentelemetry-cpp-com.html), a C++ library for connecting and interacting with MySQL databases +- [**MySQL NDB Cluster**](https://downloads.mysql.com/docs/licenses/cluster-9.0-com-en.pdf), a distributed database system that provides high availability and scalability for MySQL databases +- [**PrestoDB**](https://github.com/prestodb/presto), a distributed SQL query engine designed for large-scale data analytics, originally developed by Facebook +- [**ROOT Data Analysis Framework**](https://root.cern/doc/v614/classnlohmann_1_1basic__json.html), an open-source data analysis framework widely used in high-energy physics and other fields for data processing and visualization + +## Simulation and Modeling + +- [**Arcturus HoloSuite**](https://www.datocms-assets.com/104353/1698904597-holosuite-third-party-software-credits-and-attributions-2.pdf), a software toolset for capturing, editing, and streaming volumetric video, featuring advanced compression technologies for high-quality 3D content creation +- [**azul**](https://pure.tudelft.nl/ws/files/85338589/tgis.12673.pdf), a fast and efficient 3D city model viewer designed for visualizing urban environments and spatial data +- [**cpplot**](https://cpplot.readthedocs.io/en/latest/library_api/function_eigen_8h_1ac080eac0541014c5892a55e41bf785e6.html), a library for creating interactive graphs and charts in C++, which can be viewed in web browsers +- [**NVIDIA Omniverse**](https://docs.omniverse.nvidia.com/composer/latest/common/product-licenses/usd-explorer/usd-explorer-2023.2.0-licenses-manifest.html), a platform for 3D content creation and collaboration that enables real-time simulations and interactive experiences across various industries +- [**Pixar Renderman**](https://rmanwiki-26.pixar.com/space/REN26/19662083/Legal+Notice), a photorealistic 3D rendering software developed by Pixar, widely used in the film industry for creating high-quality visual effects and animations +- [**ROS - Robot Operating System**](http://docs.ros.org/en/noetic/api/behaviortree_cpp/html/json_8hpp_source.html), a set of software libraries and tools that assist in developing robot applications +- [**UBS**](https://www.ubs.com/), a multinational financial services and banking company +- [**GAMS**](https://www.gams.com/47/docs/THIRDPARTY.html): a high-performance mathematical modeling system for optimization and decision support +- [**M-Star**](https://docs.mstarcfd.com/3_Licensing/thirdparty-licenses.html): a computational fluid dynamics software for simulating and analyzing fluid flow +- [**MapleSim CAD Toolbox**](https://www.maplesoft.com/support/help/MapleSim/view.aspx?path=CADToolbox/copyright): a software extension for MapleSim that integrates CAD models, allowing users to import, manipulate, and analyze 3D CAD data within the MapleSim environment for enhanced modeling and simulation +- [**Kitware SMTK**](https://github.com/Kitware/SMTK): a software toolkit for managing simulation models and workflows in scientific and engineering applications + +## Enterprise and Cloud Applications + +- [**Acronis Cyber Protect Cloud**](https://care.acronis.com/s/article/59533-Third-party-software-used-in-Acronis-Cyber-Protect-Cloud?language=en_US): an all-in-one data protection solution that combines backup, disaster recovery, and cybersecurity to safeguard business data from threats like ransomware +- [**Baereos**](https://gitlab.tiger-computing.co.uk/packages/bareos/-/blob/tiger/bullseye/third-party/CLI11/examples/json.cpp): a backup solution that provides data protection and recovery options for various environments, including physical and virtual systems +- [**Bitdefender Home Scanner**](https://www.bitdefender.de/site/Main/view/home-scanner-open-source.html), a tool from Bitdefender that scans devices for malware and security threats, providing a safeguard against potential online dangers +- [**Citrix Provisioning**](https://docs.citrix.com/en-us/provisioning/2203-ltsr/downloads/pvs-third-party-notices-2203.pdf): a solution that streamlines the delivery of virtual desktops and applications by allowing administrators to manage and provision resources efficiently across multiple environments +- [**Citrix Virtual Apps and Desktops**](https://docs.citrix.com/en-us/citrix-virtual-apps-desktops/2305/downloads/third-party-notices-apps-and-desktops.pdf), a solution from Citrix that delivers virtual apps and desktops +- [**Cyberarc**](https://docs.cyberark.com/Downloads/Legal/Privileged%20Session%20Manager%20for%20SSH%20Third-Party%20Notices.pdf): a security solution that specializes in privileged access management, enabling organizations to control and monitor access to critical systems and data, thereby enhancing overall cybersecurity posture +- [**Egnyte Desktop**](https://helpdesk.egnyte.com/hc/en-us/articles/360007071732-Third-Party-Software-Acknowledgements): a secure cloud storage solution designed for businesses, enabling file sharing, collaboration, and data management across teams while ensuring compliance and data protection +- [**Ethereum Solidity**](https://github.com/ethereum/solidity), a high-level, object-oriented programming language designed for implementing smart contracts on the Ethereum platform +- [**Inciga**](https://fossies.org/linux/icinga2/third-party/nlohmann_json/json.hpp): a monitoring tool for IT infrastructure, designed to provide insights into system performance and availability through customizable dashboards and alerts +- [**Intel Accelerator Management Daemon for VMware ESXi**](https://downloadmirror.intel.com/772507/THIRD-PARTY.txt): a management tool designed for monitoring and controlling Intel hardware accelerators within VMware ESXi environments, optimizing performance and resource allocation +- [**Juniper Identity Management Service**](https://www.juniper.net/documentation/us/en/software/jims/jims-guide/jims-guide.pdf) +- [**Microsoft Azure IoT SDK**](https://library.e.abb.com/public/2779c5f85f30484192eb3cb3f666a201/IP%20Gateway%20Open%20License%20Declaration_9AKK108467A4095_Rev_C.pdf), a collection of tools and libraries to help developers connect, build, and deploy Internet of Things (IoT) solutions on the Azure cloud platform +- [**Microsoft WinGet**](https://github.com/microsoft/winget-cli), a command-line utility included in the Windows Package Manager +- [**Pointr**](https://docs-dev.pointr.tech/docs/8.x/Developer%20Portal/Open%20Source%20Licenses/): a platform for indoor positioning and navigation solutions, offering tools and SDKs for developers to create location-based applications diff --git a/docs/mkdocs/docs/home/design_goals.md b/docs/mkdocs/docs/home/design_goals.md index b80551fe97..b3a0b2b9e3 100644 --- a/docs/mkdocs/docs/home/design_goals.md +++ b/docs/mkdocs/docs/home/design_goals.md @@ -2,7 +2,7 @@ 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. +- **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. - **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. diff --git a/docs/mkdocs/docs/home/exceptions.md b/docs/mkdocs/docs/home/exceptions.md index a0fee9e333..f6e586c624 100644 --- a/docs/mkdocs/docs/home/exceptions.md +++ b/docs/mkdocs/docs/home/exceptions.md @@ -6,24 +6,33 @@ All exceptions inherit from class `json::exception` (which in turn inherits from `std::exception`). It is used as the base class for all exceptions thrown by the `basic_json` class. This class can hence be used as "wildcard" to catch exceptions. -```plantuml -std::exception <|-- json::exception -json::exception <|-- json::parse_error -json::exception <|-- json::invalid_iterator -json::exception <|-- json::type_error -json::exception <|-- json::out_of_range -json::exception <|-- json::other_error - -interface std::exception {} - -class json::exception { - + const int id - + const char* what() const -} - -class json::parse_error { - + const std::size_t byte -} +``` mermaid +classDiagram + direction LR + class `std::exception` { + <> + } + + class `json::exception` { + +const int id + +const char* what() const + } + + class `json::parse_error` { + +const std::size_t byte + } + + class `json::invalid_iterator` + class `json::type_error` + class `json::out_of_range` + class `json::other_error` + + `std::exception` <|-- `json::exception` + `json::exception` <|-- `json::parse_error` + `json::exception` <|-- `json::invalid_iterator` + `json::exception` <|-- `json::type_error` + `json::exception` <|-- `json::out_of_range` + `json::exception` <|-- `json::other_error` ``` ### Switch off exceptions diff --git a/docs/mkdocs/docs/images/customers.png b/docs/mkdocs/docs/images/customers.png new file mode 100644 index 0000000000..f324cb2722 Binary files /dev/null and b/docs/mkdocs/docs/images/customers.png differ diff --git a/docs/mkdocs/docs/integration/bazel/BUILD b/docs/mkdocs/docs/integration/bazel/BUILD new file mode 100644 index 0000000000..ec223f14d6 --- /dev/null +++ b/docs/mkdocs/docs/integration/bazel/BUILD @@ -0,0 +1,5 @@ +cc_binary( + name = "main", + srcs = ["example.cpp"], + deps = ["@nlohmann_json//:json"], +) diff --git a/docs/mkdocs/docs/integration/bazel/WORKSPACE b/docs/mkdocs/docs/integration/bazel/WORKSPACE new file mode 100644 index 0000000000..57ef2e10c3 --- /dev/null +++ b/docs/mkdocs/docs/integration/bazel/WORKSPACE @@ -0,0 +1,7 @@ +load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") + +http_archive( + name = "nlohmann_json", + urls = ["https://github.com/nlohmann/json/archive/refs/tags/v3.11.3.tar.gz"], + strip_prefix = "json-3.11.3", +) diff --git a/docs/mkdocs/docs/integration/bazel/example.cpp b/docs/mkdocs/docs/integration/bazel/example.cpp new file mode 100644 index 0000000000..1a7ac4de2e --- /dev/null +++ b/docs/mkdocs/docs/integration/bazel/example.cpp @@ -0,0 +1,10 @@ +#include +#include +#include + +using json = nlohmann::json; + +int main() +{ + std::cout << std::setw(4) << json::meta() << std::endl; +} diff --git a/docs/mkdocs/docs/integration/cget/CMakeLists.txt b/docs/mkdocs/docs/integration/cget/CMakeLists.txt new file mode 100644 index 0000000000..e3fda5b9ad --- /dev/null +++ b/docs/mkdocs/docs/integration/cget/CMakeLists.txt @@ -0,0 +1,7 @@ +cmake_minimum_required(VERSION 3.15) +project(json_example) + +find_package(nlohmann_json REQUIRED) + +add_executable(json_example example.cpp) +target_link_libraries(json_example PRIVATE nlohmann_json::nlohmann_json) diff --git a/docs/mkdocs/docs/integration/cget/example.cpp b/docs/mkdocs/docs/integration/cget/example.cpp new file mode 100644 index 0000000000..1a7ac4de2e --- /dev/null +++ b/docs/mkdocs/docs/integration/cget/example.cpp @@ -0,0 +1,10 @@ +#include +#include +#include + +using json = nlohmann::json; + +int main() +{ + std::cout << std::setw(4) << json::meta() << std::endl; +} diff --git a/docs/mkdocs/docs/integration/cmake.md b/docs/mkdocs/docs/integration/cmake.md index 545f53f303..2f68f09ceb 100644 --- a/docs/mkdocs/docs/integration/cmake.md +++ b/docs/mkdocs/docs/integration/cmake.md @@ -119,9 +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 - a smaller repository. For instance, you might want to replace the URL in the example by - . + However, the repository download size is quite large. ## CMake Options diff --git a/docs/mkdocs/docs/integration/conan/CMakeLists.txt b/docs/mkdocs/docs/integration/conan/CMakeLists.txt index fd3e9ca716..e3fda5b9ad 100644 --- a/docs/mkdocs/docs/integration/conan/CMakeLists.txt +++ b/docs/mkdocs/docs/integration/conan/CMakeLists.txt @@ -1,9 +1,7 @@ +cmake_minimum_required(VERSION 3.15) project(json_example) -cmake_minimum_required(VERSION 2.8.12) -add_definitions("-std=c++11") -include(${CMAKE_BINARY_DIR}/conanbuildinfo.cmake) -conan_basic_setup() +find_package(nlohmann_json REQUIRED) add_executable(json_example example.cpp) -target_link_libraries(json_example ${CONAN_LIBS}) +target_link_libraries(json_example PRIVATE nlohmann_json::nlohmann_json) diff --git a/docs/mkdocs/docs/integration/conan/Conanfile.txt b/docs/mkdocs/docs/integration/conan/Conanfile.txt index a8a3e70378..6dcd6141cc 100644 --- a/docs/mkdocs/docs/integration/conan/Conanfile.txt +++ b/docs/mkdocs/docs/integration/conan/Conanfile.txt @@ -1,5 +1,6 @@ [requires] -nlohmann_json/3.7.3 +nlohmann_json/3.11.3 [generators] -cmake +CMakeToolchain +CMakeDeps diff --git a/docs/mkdocs/docs/integration/conan/example.cpp b/docs/mkdocs/docs/integration/conan/example.cpp index e5a31be4bd..1a7ac4de2e 100644 --- a/docs/mkdocs/docs/integration/conan/example.cpp +++ b/docs/mkdocs/docs/integration/conan/example.cpp @@ -1,9 +1,10 @@ #include #include +#include using json = nlohmann::json; int main() { - std::cout << json::meta() << std::endl; + std::cout << std::setw(4) << json::meta() << std::endl; } diff --git a/docs/mkdocs/docs/integration/cpm/CMakeLists.txt b/docs/mkdocs/docs/integration/cpm/CMakeLists.txt new file mode 100644 index 0000000000..c4f6340145 --- /dev/null +++ b/docs/mkdocs/docs/integration/cpm/CMakeLists.txt @@ -0,0 +1,9 @@ +cmake_minimum_required(VERSION 3.15) +project(json_example) + +include(${CMAKE_SOURCE_DIR}/cmake/CPM.cmake) + +CPMAddPackage("gh:nlohmann/json@3.11.3") + +add_executable(json_example example.cpp) +target_link_libraries(json_example PRIVATE nlohmann_json::nlohmann_json) diff --git a/docs/mkdocs/docs/integration/cpm/example.cpp b/docs/mkdocs/docs/integration/cpm/example.cpp new file mode 100644 index 0000000000..1a7ac4de2e --- /dev/null +++ b/docs/mkdocs/docs/integration/cpm/example.cpp @@ -0,0 +1,10 @@ +#include +#include +#include + +using json = nlohmann::json; + +int main() +{ + std::cout << std::setw(4) << json::meta() << std::endl; +} diff --git a/docs/mkdocs/docs/integration/homebrew/CMakeLists.txt b/docs/mkdocs/docs/integration/homebrew/CMakeLists.txt new file mode 100644 index 0000000000..12f4ae1f2b --- /dev/null +++ b/docs/mkdocs/docs/integration/homebrew/CMakeLists.txt @@ -0,0 +1,7 @@ +cmake_minimum_required(VERSION 3.15) +project(json_example) + +find_package(nlohmann_json CONFIG REQUIRED) + +add_executable(json_example example.cpp) +target_link_libraries(json_example PRIVATE nlohmann_json::nlohmann_json) diff --git a/docs/mkdocs/docs/integration/homebrew/example.cpp b/docs/mkdocs/docs/integration/homebrew/example.cpp new file mode 100644 index 0000000000..1a7ac4de2e --- /dev/null +++ b/docs/mkdocs/docs/integration/homebrew/example.cpp @@ -0,0 +1,10 @@ +#include +#include +#include + +using json = nlohmann::json; + +int main() +{ + std::cout << std::setw(4) << json::meta() << std::endl; +} diff --git a/docs/mkdocs/docs/integration/hunter/CMakeLists.txt b/docs/mkdocs/docs/integration/hunter/CMakeLists.txt new file mode 100644 index 0000000000..4acc325860 --- /dev/null +++ b/docs/mkdocs/docs/integration/hunter/CMakeLists.txt @@ -0,0 +1,15 @@ +cmake_minimum_required(VERSION 3.15) + +include("cmake/HunterGate.cmake") +HunterGate( + URL "https://github.com/cpp-pm/hunter/archive/v0.23.297.tar.gz" + SHA1 "3319fe6a3b08090df7df98dee75134d68e2ef5a3" +) + +project(json_example) + +hunter_add_package(nlohmann_json) +find_package(nlohmann_json CONFIG REQUIRED) + +add_executable(json_example example.cpp) +target_link_libraries(json_example PRIVATE nlohmann_json::nlohmann_json) diff --git a/docs/mkdocs/docs/integration/hunter/example.cpp b/docs/mkdocs/docs/integration/hunter/example.cpp new file mode 100644 index 0000000000..1a7ac4de2e --- /dev/null +++ b/docs/mkdocs/docs/integration/hunter/example.cpp @@ -0,0 +1,10 @@ +#include +#include +#include + +using json = nlohmann::json; + +int main() +{ + std::cout << std::setw(4) << json::meta() << std::endl; +} diff --git a/docs/mkdocs/docs/integration/meson/example.cpp b/docs/mkdocs/docs/integration/meson/example.cpp new file mode 100644 index 0000000000..1a7ac4de2e --- /dev/null +++ b/docs/mkdocs/docs/integration/meson/example.cpp @@ -0,0 +1,10 @@ +#include +#include +#include + +using json = nlohmann::json; + +int main() +{ + std::cout << std::setw(4) << json::meta() << std::endl; +} diff --git a/docs/mkdocs/docs/integration/meson/meson.build b/docs/mkdocs/docs/integration/meson/meson.build new file mode 100644 index 0000000000..ec6d2343b1 --- /dev/null +++ b/docs/mkdocs/docs/integration/meson/meson.build @@ -0,0 +1,12 @@ +project('json_example', 'cpp', + version: '1.0', + default_options: ['cpp_std=c++11'] +) + +dependency_json = dependency('nlohmann_json', required: true) + +executable('json_example', + sources: ['example.cpp'], + dependencies: [dependency_json], + install: true +) diff --git a/docs/mkdocs/docs/integration/package_managers.md b/docs/mkdocs/docs/integration/package_managers.md index c9a273a500..5efe83b87d 100644 --- a/docs/mkdocs/docs/integration/package_managers.md +++ b/docs/mkdocs/docs/integration/package_managers.md @@ -14,61 +14,178 @@ When executed, this program should create output similar to ## Homebrew -If you are using OS X and [Homebrew](http://brew.sh), just type +!!! abstract "Summary" -```sh -brew install nlohmann-json -``` + formula: [**`nlohmann-json`**](https://formulae.brew.sh/formula/nlohmann-json) -and you're set. If you want the bleeding edge rather than the latest release, use + - :octicons-tag-24: Availalbe versions: current version and development version (with `--HEAD` parameter) + - :octicons-rocket-24: The formula is updated with every release. + - :octicons-person-24: Maintainer: Niels Lohmann + - :octicons-file-24: File issues at the [Homebrew issue tracker](https://github.com/Homebrew/homebrew-core/issues) + - :octicons-question-24: [Homebrew website](https://brew.sh) + +If you are using OS X and [Homebrew](http://brew.sh), you can install the library with ```sh -brew install nlohmann-json --HEAD +brew install nlohmann-json ``` -instead. See [nlohmann-json](https://formulae.brew.sh/formula/nlohmann-json) for more information. +The header can be used directly in your code or via CMake. -??? example +??? example "Example: Raw compilation" 1. Create the following file: ```cpp title="example.cpp" - --8<-- "integration/example.cpp" + --8<-- "integration/homebrew/example.cpp" ``` - 2. Install the package + 2. Install the package: ```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. Compile the code and pass the Homebrew prefix to the include path such that the library can be found: ```sh - brew list nlohmann-json + c++ example.cpp -I$(brew --prefix nlohmann-json)/include -std=c++11 -o example + ``` + +??? example "Example: CMake" + + 1. Create the following files: + + ```cpp title="example.cpp" + --8<-- "integration/homebrew/example.cpp" + ``` + + ```cmake title="CMakeLists.txt" + --8<-- "integration/homebrew/CMakeLists.txt" ``` - 4. Compile the code. For instance, the code can be compiled using Clang with + 2. Install the package: ```sh - clang++ example.cpp -I/usr/local/Cellar/nlohmann-json/3.7.3/include -std=c++11 -o example + brew install nlohmann-json ``` -:material-update: The [formula](https://formulae.brew.sh/formula/nlohmann-json) is updated automatically. + 3. Compile the code and pass the Homebrew prefix to CMake to find installed packages via `#!cmake find_package`: + + ```sh + CMAKE_PREFIX_PATH=$(brew --prefix) cmake -S . -B build + cmake --build build + ``` ## 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. +!!! abstract "Summary" + + wrap: **`nlohmann_json`** + + - :octicons-tag-24: Availalbe versions: current version and select older versions (see + [WrapDB](https://mesonbuild.com/Wrapdb-projects.html)) + - :octicons-rocket-24: The package is update automatically from file + [`meson.build`](https://github.com/nlohmann/json/blob/develop/meson.build). + - :octicons-file-24: File issues at the [library issue tracker](https://github.com/nlohmann/json/issues) + - :octicons-question-24: [Meson website](https://mesonbuild.com/index.html) + +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://mesonbuild.com/Wrapdb-projects.html), or simply +use + +```shell +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. + +??? example "Example: Wrap" + + 1. Create the following files: + + ```ini title="meson.build" + --8<-- "integration/meson/meson.build" + ``` + + ```cpp title="example.cpp" + --8<-- "integration/meson/example.cpp" + ``` + + 2. Use the Meson WrapDB to fetch the nlohmann/json wrap: + + ```shell + mkdir subprojects + meson wrap install nlohmann_json + ``` + + 3. Build: -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. + ```shell + meson setup build + meson compile -C build + ``` ## Bazel -This repository provides a [Bazel](https://bazel.build/) `WORKSPACE.bazel` and a corresponding `BUILD.bazel` file. Therefore, this repository can be referenced by workspace rules such as `http_archive`, `git_repository`, or `local_repository` from other Bazel workspaces. To use the library you only need to depend on the target `@nlohmann_json//:json` (e.g. via `deps` attribute). +!!! abstract "Summary" + + use `http_archive`, `git_repository`, or `local_repository` + + - :octicons-tag-24: Any version, as version is specified in `WORKSPACE` file + - :octicons-file-24: File issues at the [library issue tracker](https://github.com/nlohmann/json/issues) + - :octicons-question-24: [Bazel website](https://bazel.build) + +This repository provides a [Bazel](https://bazel.build/) `WORKSPACE.bazel` and a corresponding `BUILD.bazel` file. Therefore, this +repository can be referenced by workspace rules such as `http_archive`, `git_repository`, or `local_repository` from +other Bazel workspaces. To use the library you only need to depend on the target `@nlohmann_json//:json` (e.g., via +`deps` attribute). + +??? example + + 1. Create the following files: + + ```ini title="BUILD" + --8<-- "integration/bazel/BUILD" + ``` + + ```ini title="WORKSPACE" + --8<-- "integration/bazel/WORKSPACE" + ``` + + ```cpp title="example.cpp" + --8<-- "integration/bazel/example.cpp" + ``` + + 2. Build and run: + + ```shell + bazel build //:main + bazel run //:main + ``` ## 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. +!!! abstract "Summary" + + recipe: [**`nlohmann_json`**](https://conan.io/center/recipes/nlohmann_json) + + - :octicons-tag-24: Availalbe versions: current version and older versions (see + [Conan Center](https://conan.io/center/recipes/nlohmann_json)) + - :octicons-rocket-24: The package is update automatically via + [this recipe](https://github.com/conan-io/conan-center-index/tree/master/recipes/nlohmann_json). + - :octicons-file-24: File issues at the [Conan Center issue tracker](https://github.com/conan-io/conan-center-index/issues) + - :octicons-question-24: [Conan website](https://conan.io) + +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. ??? example @@ -86,33 +203,147 @@ If you are using [Conan](https://www.conan.io/) to manage your dependencies, mer --8<-- "integration/conan/example.cpp" ``` - 2. Build: + 2. Call Conan: ```sh - mkdir build - cd build - conan install .. - cmake .. - cmake --build . + conan install . --output-folder=build --build=missing ``` -:material-update: The [package](https://conan.io/center/nlohmann_json) is updated automatically. + 3. Build: + + ```sh + cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE="conan_toolchain.cmake" -DCMAKE_BUILD_TYPE=Release + cmake --build 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. +!!! abstract "Summary" + + package: [**`nlohmann-json`**](https://packages.spack.io/package.html?name=nlohmann-json) + + - :octicons-tag-24: Availalbe versions: current version and older versions (see + [Spack package](https://packages.spack.io/package.html?name=nlohmann-json)) + - :octicons-rocket-24: The formula is updated with every release. + - :octicons-person-24: Maintainer: [Axel Huebl](https://github.com/ax3l) + - :octicons-file-24: File issues at the [Spack issue tracker](https://github.com/spack/spack/issues) + - :octicons-question-24: [Spack website](https://spack.io) + +If you are using [Spack](https://www.spack.io/) to manage your dependencies, you can use the +[`nlohmann-json` package](https://packages.spack.io/package.html?name=nlohmann-json) via + +```shell +spack install nlohmann-json +``` + +Please see the [Spack project](https://github.com/spack/spack) for any issues regarding the packaging. + +??? example + + 1. Create the following files: + + ```cmake title="CMakeLists.txt" + --8<-- "integration/spack/CMakeLists.txt" + ``` + + ```cpp title="example.cpp" + --8<-- "integration/spack/example.cpp" + ``` + + 2. Install the library: + + ```sh + spack install nlohmann-json + ``` + + 3. Load the environment for your Spack-installed packages: + + ```sh + spack load nlohmann-json + ``` + + 4. Build the project with CMake: + + ```sh + cmake -S . -B build -DCMAKE_PREFIX_PATH=$(spack location -i nlohmann-json) + cmake --build build + ``` ## 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. +!!! abstract "Summary" + + package: [**`nlohmann_json`**](https://hunter.readthedocs.io/en/latest/packages/pkg/nlohmann_json.html) + + - :octicons-tag-24: Availalbe versions: current version and older versions (see + [Hunter package](https://hunter.readthedocs.io/en/latest/packages/pkg/nlohmann_json.html)) + - :octicons-rocket-24: The formula is updated with every release. + - :octicons-file-24: File issues at the [Hunter issue tracker](https://github.com/cpp-pm/hunter/issues) + - :octicons-question-24: [Hunter website](https://hunter.readthedocs.io/en/latest/) + +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) via + +```cmake +hunter_add_package(nlohmann_json) +``` + +Please see the Hunter project for any issues regarding the packaging. + +??? example + + 1. Create the following files: + + ```cmake title="CMakeLists.txt" + --8<-- "integration/hunter/CMakeLists.txt" + ``` + + ```cpp title="example.cpp" + --8<-- "integration/hunter/example.cpp" + ``` + + 2. Download required files + + ```shell + mkdir cmake + wget https://raw.githubusercontent.com/cpp-pm/gate/master/cmake/HunterGate.cmake -O cmake/HunterGate.cmake + ``` + + 3. Build the project with CMake: + + ```shell + cmake -S . -B build + cmake --build build + ``` ## 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). +If you are using [Buckaroo](https://buckaroo.pm), you can install this library's module with `buckaroo add github.com/buckaroo-pm/nlohmann-json`. There is a demo repo [here](https://github.com/njlr/buckaroo-nholmann-json-example). + +!!! warning + + The module is outdated as the respective [repository](https://github.com/buckaroo-pm/nlohmann-json) has not been + updated in years. ## vcpkg -If you are using [vcpkg](https://github.com/Microsoft/vcpkg/) on your project for external dependencies, then you can install the [nlohmann-json package](https://github.com/Microsoft/vcpkg/tree/master/ports/nlohmann-json) with `vcpkg install nlohmann-json` and follow the then displayed descriptions. Please see the vcpkg project for any issues regarding the packaging. +!!! abstract "Summary" + + package: [**`nlohmann-json`**](https://github.com/Microsoft/vcpkg/tree/master/ports/nlohmann-json) + + - :octicons-tag-24: Availalbe versions: current version + - :octicons-rocket-24: The formula is updated with every release. + - :octicons-file-24: File issues at the [vcpkg issue tracker](https://github.com/microsoft/vcpkg/issues) + - :octicons-question-24: [vcpkg website](https://vcpkg.io/) + +If you are using [vcpkg](https://github.com/Microsoft/vcpkg/) on your project for external dependencies, then you can +install the [nlohmann-json package](https://github.com/Microsoft/vcpkg/tree/master/ports/nlohmann-json) with + +```shell +vcpkg install nlohmann-json +``` + +and follow the then displayed descriptions. Please see the vcpkg project for any issues regarding the packaging. ??? example @@ -135,19 +366,60 @@ If you are using [vcpkg](https://github.com/Microsoft/vcpkg/) on your project fo 3. Build: ```sh - mkdir build - cd build - cmake .. -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake - cmake --build . + cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake + cmake --build build ``` - Note you need to adjust `/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake` to your system. - ## 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`). +!!! abstract "Summary" + + package: [**`nlohmann/json`**](https://github.com/pfultz2/cget-recipes/blob/master/recipes/nlohmann/json/package.txt) + + - :octicons-tag-24: Availalbe versions: current version and older versions + - :octicons-rocket-24: The formula is updated with every release. + - :octicons-file-24: File issues at the [cget issue tracker](https://github.com/pfultz2/cget-recipes/issues) + - :octicons-question-24: [cget website](https://cget.readthedocs.io/) + +If you are using [cget](http://cget.readthedocs.io/en/latest/), you can install the latest `master` version with + +```shell +cget install nlohmann/json +``` + +A specific version can be installed with `cget install nlohmann/json@v3.11.3`. Also, the multiple header version can be +installed by adding the `-DJSON_MultipleHeaders=ON` flag (i.e., `cget install nlohmann/json -DJSON_MultipleHeaders=ON`). + +??? example + + 1. Create the following files: + + ```cmake title="CMakeLists.txt" + --8<-- "integration/vcpkg/CMakeLists.txt" + ``` + + ```cpp title="example.cpp" + --8<-- "integration/vcpkg/example.cpp" + ``` + + 2. Initialize cget -:material-update: cget reads directly from the [GitHub repository](https://github.com/nlohmann/json) and is always up-to-date. + ```shell + cget init + ``` + + 3. Install the library + + ```shell + cget install nlohmann/json + ``` + + 4. Build + + ```shell + cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=cget/cget/cget.cmake + cmake --build build + ``` ## CocoaPods @@ -191,8 +463,21 @@ If you are using [`wsjcpp`](http://wsjcpp.org), you can use the command `wsjcpp If you are using [`CPM.cmake`](https://github.com/TheLartians/CPM.cmake), you can check this [`example`](https://github.com/TheLartians/CPM.cmake/tree/master/examples/json). After [adding CPM script](https://github.com/TheLartians/CPM.cmake#adding-cpm) to your project, implement the following snippet to your CMake: ```cmake -CPMAddPackage( - NAME nlohmann_json - GITHUB_REPOSITORY nlohmann/json - VERSION 3.9.1) +CPMAddPackage("gh:nlohmann/json@3.11.3") ``` + +??? example + + 1. Download CPM.cmake + + ```shell + mkdir -p cmake + wget -O cmake/CPM.cmake https://github.com/cpm-cmake/CPM.cmake/releases/latest/download/get_cpm.cmake + ``` + + 2. Build + + ```shell + cmake -S . -B build + cmake --build build + ``` diff --git a/docs/mkdocs/docs/integration/spack/CMakeLists.txt b/docs/mkdocs/docs/integration/spack/CMakeLists.txt new file mode 100644 index 0000000000..e3fda5b9ad --- /dev/null +++ b/docs/mkdocs/docs/integration/spack/CMakeLists.txt @@ -0,0 +1,7 @@ +cmake_minimum_required(VERSION 3.15) +project(json_example) + +find_package(nlohmann_json REQUIRED) + +add_executable(json_example example.cpp) +target_link_libraries(json_example PRIVATE nlohmann_json::nlohmann_json) diff --git a/docs/mkdocs/docs/integration/spack/example.cpp b/docs/mkdocs/docs/integration/spack/example.cpp new file mode 100644 index 0000000000..1a7ac4de2e --- /dev/null +++ b/docs/mkdocs/docs/integration/spack/example.cpp @@ -0,0 +1,10 @@ +#include +#include +#include + +using json = nlohmann::json; + +int main() +{ + std::cout << std::setw(4) << json::meta() << std::endl; +} diff --git a/docs/mkdocs/docs/integration/vcpkg/CMakeLists.txt b/docs/mkdocs/docs/integration/vcpkg/CMakeLists.txt index d31f4e8359..12f4ae1f2b 100644 --- a/docs/mkdocs/docs/integration/vcpkg/CMakeLists.txt +++ b/docs/mkdocs/docs/integration/vcpkg/CMakeLists.txt @@ -1,5 +1,5 @@ +cmake_minimum_required(VERSION 3.15) project(json_example) -cmake_minimum_required(VERSION 2.8.12) find_package(nlohmann_json CONFIG REQUIRED) diff --git a/docs/mkdocs/docs/integration/vcpkg/example.cpp b/docs/mkdocs/docs/integration/vcpkg/example.cpp index e5a31be4bd..1a7ac4de2e 100644 --- a/docs/mkdocs/docs/integration/vcpkg/example.cpp +++ b/docs/mkdocs/docs/integration/vcpkg/example.cpp @@ -1,9 +1,10 @@ #include #include +#include using json = nlohmann::json; int main() { - std::cout << json::meta() << std::endl; + std::cout << std::setw(4) << json::meta() << std::endl; } diff --git a/docs/mkdocs/mkdocs.yml b/docs/mkdocs/mkdocs.yml index 5e66db596f..286f161e0c 100644 --- a/docs/mkdocs/mkdocs.yml +++ b/docs/mkdocs/mkdocs.yml @@ -9,7 +9,7 @@ repo_url: https://github.com/nlohmann/json edit_uri: edit/develop/docs/mkdocs/docs # Copyright -copyright: Copyright © 2013 - 2023 Niels Lohmann +copyright: Copyright © 2013 - 2024 Niels Lohmann # Configuration theme: @@ -30,7 +30,8 @@ theme: toggle: icon: material/brightness-4 name: Switch to light mode - + icon: + repo: fontawesome/brands/github font: text: Roboto code: JetBrains Mono @@ -41,6 +42,8 @@ theme: - navigation.indexes - navigation.top - content.tabs.link + - content.action.edit + - content.action.view nav: - Home: @@ -51,6 +54,7 @@ nav: - home/exceptions.md - home/releases.md - home/design_goals.md + - home/customers.md - home/sponsors.md - Features: - features/arbitrary_types.md @@ -281,6 +285,10 @@ nav: - 'JSON_USE_GLOBAL_UDLS': api/macros/json_use_global_udls.md - 'JSON_USE_IMPLICIT_CONVERSIONS': api/macros/json_use_implicit_conversions.md - 'JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON': api/macros/json_use_legacy_discarded_value_comparison.md + - 'NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE': api/macros/nlohmann_define_derived_type.md + - 'NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_WITH_DEFAULT': api/macros/nlohmann_define_derived_type.md + - 'NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE': api/macros/nlohmann_define_derived_type.md + - 'NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_WITH_DEFAULT': api/macros/nlohmann_define_derived_type.md - 'NLOHMANN_DEFINE_TYPE_INTRUSIVE': api/macros/nlohmann_define_type_intrusive.md - 'NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT': api/macros/nlohmann_define_type_intrusive.md - 'NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE': api/macros/nlohmann_define_type_non_intrusive.md @@ -299,8 +307,6 @@ 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 @@ -332,7 +338,11 @@ markdown_extensions: - pymdownx.magiclink - pymdownx.mark #- pymdownx.smartsymbols - - pymdownx.superfences + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format - pymdownx.tasklist: custom_checkbox: true - pymdownx.tabbed: @@ -341,23 +351,21 @@ markdown_extensions: - pymdownx.snippets: base_path: docs check_paths: true - - plantuml_markdown: - format: svg plugins: - - search: - separator: '[\s\-\.]' - lang: en - - minify: - minify_html: true - - git-revision-date-localized - - redirects: - redirect_maps: - 'api/basic_json/operator_gtgt.md': api/operator_gtgt.md - 'api/basic_json/operator_ltlt.md': api/operator_ltlt.md - 'api/basic_json/operator_literal_json.md': api/operator_literal_json.md - 'api/basic_json/operator_literal_json_pointer.md': api/operator_literal_json_pointer.md - 'api/json_pointer/operator_string.md': api/json_pointer/operator_string_t.md + - search: + separator: '[\s\-\.]' + lang: en + - minify: + minify_html: true + - git-revision-date-localized + - redirects: + redirect_maps: + 'api/basic_json/operator_gtgt.md': api/operator_gtgt.md + 'api/basic_json/operator_ltlt.md': api/operator_ltlt.md + 'api/basic_json/operator_literal_json.md': api/operator_literal_json.md + 'api/basic_json/operator_literal_json_pointer.md': api/operator_literal_json_pointer.md + 'api/json_pointer/operator_string.md': api/json_pointer/operator_string_t.md extra_css: - css/custom.css diff --git a/docs/mkdocs/requirements.txt b/docs/mkdocs/requirements.txt index b397d545d0..8bb7ef75b9 100644 --- a/docs/mkdocs/requirements.txt +++ b/docs/mkdocs/requirements.txt @@ -1,49 +1,6 @@ -Babel==2.13.1 -certifi==2023.7.22 -charset-normalizer==3.3.1 -click==8.1.7 -csscompressor==0.9.5 -future==0.18.3 -ghp-import==2.1.0 -gitdb==4.0.11 -GitPython==3.1.40 -htmlmin==0.1.12 -httplib2==0.22.0 -idna==3.4 -importlib-metadata==6.8.0 -Jinja2==3.1.2 -joblib==1.3.2 -jsmin==3.0.1 -livereload==2.6.3 -lunr==0.7.0.post1 -Markdown==3.5 -markdown-include==0.8.1 -MarkupSafe==2.1.3 -mergedeep==1.3.4 -mkdocs==1.5.3 -mkdocs-git-revision-date-localized-plugin==1.2.1 -mkdocs-material==9.4.7 -mkdocs-material-extensions==1.3 -mkdocs-minify-plugin==0.7.1 -mkdocs-redirects==1.2.1 -mkdocs-simple-hooks==0.1.5 -nltk==3.8.1 -packaging==23.2 -plantuml==0.3.0 -plantuml-markdown==3.9.2 -Pygments==2.16.1 -pymdown-extensions==10.3.1 -pyparsing==3.1.1 -python-dateutil==2.8.2 -pytz==2023.3.post1 -PyYAML==6.0.1 -pyyaml_env_tag==0.1 -regex==2023.10.3 -requests==2.31.0 -six==1.16.0 -smmap==5.0.1 -tornado==6.3.3 -tqdm==4.66.1 -urllib3==2.0.7 -watchdog==3.0.0 -zipp==3.17.0 +mkdocs==1.6.1 # documentation framework +mkdocs-git-revision-date-localized-plugin==1.3.0 # plugin "git-revision-date-localized" +mkdocs-material==9.5.48 # theme for mkdocs +mkdocs-material-extensions==1.3.1 # extensions +mkdocs-minify-plugin==0.8.0 # plugin "minify" +mkdocs-redirects==1.2.2 # plugin "redirects"