External/json
8
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge branch 'nlohmann:develop' into iterator_input_adapter_fix

Browse Source
This commit is contained in:
Luca Passarella 2022-06-20 11:56:51 +02:00 committed by GitHub
commit d63d250af6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
957 changed files with 14814 additions and 2897 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.clang-tidy
View File

@ -43,6 +43,7 @@ Checks: '*,
-readability-identifier-length,
-readability-magic-numbers,
-readability-redundant-access-specifiers,
-readability-simplify-boolean-expr
-readability-uppercase-literal-suffix'
CheckOptions:

0
CODE_OF_CONDUCT.md → .github/CODE_OF_CONDUCT.md vendored
View File

2
.drone.yml → .github/external_ci/.drone.yml vendored
View File

@ -18,5 +18,5 @@ steps:
- cd build
- ../cmake-3.20.2/bin/cmake .. -DJSON_FastTests=ON
- make -j10
- cd test
- cd tests
- ../../cmake-3.20.2/bin/ctest -j10

0
appveyor.yml → .github/external_ci/appveyor.yml vendored
View File

21
.github/workflows/macos.yml vendored
View File

@ -10,7 +10,7 @@ on:
workflow_dispatch:
jobs:
xcode:
xcode_1:
runs-on: macos-10.15
strategy:
matrix:
@ -27,8 +27,25 @@ jobs:
- name: test
run: cd build ; ctest -j 10 --output-on-failure
xcode_2:
runs-on: macos-12
strategy:
matrix:
xcode: [13.3.1, 13.3, 13.2.1, 13.2, 13.1]
env:
DEVELOPER_DIR: /Applications/Xcode_${{ matrix.xcode }}.app/Contents/Developer
steps:
- uses: actions/checkout@v3
- name: cmake
run: cmake -S . -B build -D CMAKE_BUILD_TYPE=Debug -DJSON_BuildTests=On -DJSON_FastTests=ON
- name: build
run: cmake --build build --parallel 10
- name: test
run: cd build ; ctest -j 10 --output-on-failure
xcode_standards:
runs-on: macos-10.15
runs-on: macos-latest
strategy:
matrix:
standard: [11, 14, 17, 20]

42
.github/workflows/ubuntu.yml vendored
View File

@ -12,7 +12,7 @@ on:
jobs:
ci_test_clang:
runs-on: ubuntu-latest
container: ghcr.io/nlohmann/json-ci:v2.3.0
container: ghcr.io/nlohmann/json-ci:v2.4.0
steps:
- uses: actions/checkout@v3
- name: cmake
@ -22,7 +22,7 @@ jobs:
ci_test_gcc:
runs-on: ubuntu-latest
container: ghcr.io/nlohmann/json-ci:v2.3.0
container: ghcr.io/nlohmann/json-ci:v2.4.0
steps:
- uses: actions/checkout@v3
- name: cmake
@ -32,7 +32,7 @@ jobs:
ci_static_analysis:
runs-on: ubuntu-latest
container: ghcr.io/nlohmann/json-ci:v2.3.0
container: ghcr.io/nlohmann/json-ci:v2.4.0
strategy:
matrix:
target: [ci_clang_tidy, ci_cppcheck, ci_test_valgrind, ci_test_clang_sanitizer, ci_test_amalgamation, ci_clang_analyze, ci_cpplint, ci_cmake_flags, ci_single_binaries, ci_reproducible_tests, ci_non_git_tests, ci_offline_testdata, ci_infer]
@ -43,12 +43,22 @@ jobs:
- name: build
run: cmake --build build --target ${{ matrix.target }}
ci_test_single_header:
runs-on: ubuntu-latest
container: ghcr.io/nlohmann/json-ci:v2.4.0
steps:
- uses: actions/checkout@v3
- name: cmake
run: cmake -S . -B build -DJSON_CI=On
- name: build
run: cmake --build build --target ci_test_single_header
ci_cmake_options:
runs-on: ubuntu-latest
container: ghcr.io/nlohmann/json-ci:v2.3.0
container: ghcr.io/nlohmann/json-ci:v2.4.0
strategy:
matrix:
target: [ci_test_diagnostics, ci_test_noexceptions, ci_test_noimplicitconversions]
target: [ci_test_diagnostics, ci_test_noexceptions, ci_test_noimplicitconversions, ci_test_legacycomparison]
steps:
- uses: actions/checkout@v3
- name: cmake
@ -58,7 +68,7 @@ jobs:
ci_test_coverage:
runs-on: ubuntu-latest
container: ghcr.io/nlohmann/json-ci:v2.3.0
container: ghcr.io/nlohmann/json-ci:v2.4.0
steps:
- uses: actions/checkout@v3
- name: cmake
@ -78,10 +88,10 @@ jobs:
ci_test_compilers:
runs-on: ubuntu-latest
container: ghcr.io/nlohmann/json-ci:v2.3.0
container: ghcr.io/nlohmann/json-ci:v2.4.0
strategy:
matrix:
compiler: [g++-4.8, g++-4.9, g++-5, g++-6, g++-7, g++-8, g++-9, g++-10, clang++-3.5, clang++-3.6, clang++-3.7, clang++-3.8, clang++-3.9, clang++-4.0, clang++-5.0, clang++-6.0, clang++-7, clang++-8, clang++-9, clang++-10, clang++-11, clang++-12, clang++-13, clang++-14]
compiler: [g++-4.8, g++-4.9, g++-5, g++-6, g++-7, g++-8, g++-9, g++-10, g++-11, clang++-3.5, clang++-3.6, clang++-3.7, clang++-3.8, clang++-3.9, clang++-4.0, clang++-5.0, clang++-6.0, clang++-7, clang++-8, clang++-9, clang++-10, clang++-11, clang++-12, clang++-13, clang++-14]
steps:
- uses: actions/checkout@v3
- name: cmake
@ -91,7 +101,7 @@ jobs:
ci_test_standards:
runs-on: ubuntu-latest
container: ghcr.io/nlohmann/json-ci:v2.3.0
container: ghcr.io/nlohmann/json-ci:v2.4.0
strategy:
matrix:
standard: [11, 14, 17, 20]
@ -105,10 +115,22 @@ jobs:
ci_cuda_example:
runs-on: ubuntu-latest
container: ghcr.io/nlohmann/json-ci:v2.3.0
container: ghcr.io/nlohmann/json-ci:v2.4.0
steps:
- uses: actions/checkout@v3
- name: cmake
run: cmake -S . -B build -DJSON_CI=On
- name: build
run: cmake --build build --target ci_cuda_example
ci_icpc:
runs-on: ubuntu-latest
container: ghcr.io/nlohmann/json-ci:v2.2.0
steps:
- uses: actions/checkout@v2
- name: cmake
run: cmake -S . -B build -DJSON_CI=On
- name: build
run: |
. /opt/intel/oneapi/setvars.sh
cmake --build build --target ci_icpc

47
.gitignore vendored
View File

@ -1,32 +1,37 @@
json_unit
json_benchmarks
json_benchmarks_simple
fuzz-testing
*.dSYM
*.o
*.gcno
*.gcda
build
build_coverage
clang_analyze_build
benchmarks/files/numbers/*.json
.DS_Store
.wsjcpp-logs/*
.wsjcpp/*
.idea
/.idea
/cmake-build-*
test/test-*
/.vs
/.vs/
/.vscode/
doc/html
doc/mkdocs/venv/
doc/mkdocs/docs/examples
doc/mkdocs/site
doc/mkdocs/docs/__pycache__/
/doc/docset/JSON_for_Modern_C++.docset/
/doc/docset/JSON_for_Modern_C++.tgz
# clangd cache
/.cache/
# build directories (vscode-cmake-tools, user-defined, ...)
/build*/
# fuzzers
/tests/parse_*_fuzzer
/tests/corpus_*
/docs/mkdocs/docs/examples/
/docs/mkdocs/docs/__pycache__/
/docs/mkdocs/site/
/docs/mkdocs/venv/
/docs/docset/JSON_for_Modern_C++.docset/
/docs/docset/JSON_for_Modern_C++.tgz
/docs/mkdocs/docs/images/json.gif
# serve_header
/serve_header.yml
/localhost.pem
/localhost-key.pem

32
CMakeLists.txt
View File

@ -37,13 +37,15 @@ if(${MAIN_PROJECT} AND (${CMAKE_VERSION} VERSION_EQUAL 3.13 OR ${CMAKE_VERSION}
else()
set(JSON_BuildTests_INIT OFF)
endif()
option(JSON_BuildTests "Build the unit tests when BUILD_TESTING is enabled." ${JSON_BuildTests_INIT})
option(JSON_CI "Enable CI build targets." OFF)
option(JSON_Diagnostics "Use extended diagnostic messages." OFF)
option(JSON_ImplicitConversions "Enable implicit conversions." ON)
option(JSON_Install "Install CMake targets during install step." ${MAIN_PROJECT})
option(JSON_MultipleHeaders "Use non-amalgamated version of the library." OFF)
option(JSON_SystemInclude "Include as system headers (skip for clang-tidy)." OFF)
option(JSON_BuildTests "Build the unit tests when BUILD_TESTING is enabled." ${JSON_BuildTests_INIT})
option(JSON_CI "Enable CI build targets." OFF)
option(JSON_Diagnostics "Use extended diagnostic messages." OFF)
option(JSON_ImplicitConversions "Enable implicit conversions." ON)
option(JSON_DisableEnumSerialization "Disable default integer enum serialization." OFF)
option(JSON_LegacyDiscardedValueComparison "Enable legacy discarded value comparison." OFF)
option(JSON_Install "Install CMake targets during install step." ${MAIN_PROJECT})
option(JSON_MultipleHeaders "Use non-amalgamated version of the library." ON)
option(JSON_SystemInclude "Include as system headers (skip for clang-tidy)." OFF)
if (JSON_CI)
include(ci)
@ -77,6 +79,14 @@ if (NOT JSON_ImplicitConversions)
message(STATUS "Implicit conversions are disabled")
endif()
if (JSON_DisableEnumSerialization)
message(STATUS "Enum integer serialization is disabled")
endif()
if (JSON_LegacyDiscardedValueComparison)
message(STATUS "Legacy discarded value comparison enabled")
endif()
if (JSON_Diagnostics)
message(STATUS "Diagnostics enabled")
endif()
@ -100,8 +110,10 @@ endif()
target_compile_definitions(
${NLOHMANN_JSON_TARGET_NAME}
INTERFACE
JSON_USE_IMPLICIT_CONVERSIONS=$<BOOL:${JSON_ImplicitConversions}>
JSON_DIAGNOSTICS=$<BOOL:${JSON_Diagnostics}>
$<$<NOT:$<BOOL:${JSON_ImplicitConversions}>>:JSON_USE_IMPLICIT_CONVERSIONS=0>
$<$<BOOL:${JSON_DisableEnumSerialization}>:JSON_DISABLE_ENUM_SERIALIZATION=1>
$<$<BOOL:${JSON_Diagnostics}>:JSON_DIAGNOSTICS=1>
$<$<BOOL:${JSON_LegacyDiscardedValueComparison}>:JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON=1>
)
target_include_directories(
@ -136,7 +148,7 @@ CONFIGURE_FILE(
if (JSON_BuildTests)
include(CTest)
enable_testing()
add_subdirectory(test)
add_subdirectory(tests)
endif()
##

51
Makefile
View File

@ -45,7 +45,7 @@ all:
# compile example files and check output
doctest:
$(MAKE) check_output -C doc
$(MAKE) check_output -C docs
##########################################################################
@ -55,7 +55,7 @@ doctest:
run_benchmarks:
rm -fr cmake-build-benchmarks
mkdir cmake-build-benchmarks
cd cmake-build-benchmarks ; cmake ../benchmarks -GNinja -DCMAKE_BUILD_TYPE=Release -DJSON_BuildTests=On
cd cmake-build-benchmarks ; cmake ../tests/benchmarks -GNinja -DCMAKE_BUILD_TYPE=Release
cd cmake-build-benchmarks ; ninja
cd cmake-build-benchmarks ; ./json_benchmarks
@ -68,41 +68,41 @@ run_benchmarks:
fuzz_testing:
rm -fr fuzz-testing
mkdir -p fuzz-testing fuzz-testing/testcases fuzz-testing/out
$(MAKE) parse_afl_fuzzer -C test CXX=afl-clang++
mv test/parse_afl_fuzzer fuzz-testing/fuzzer
find test/data/json_tests -size -5k -name *json | xargs -I{} cp "{}" fuzz-testing/testcases
$(MAKE) parse_afl_fuzzer -C tests CXX=afl-clang++
mv tests/parse_afl_fuzzer fuzz-testing/fuzzer
find tests/data/json_tests -size -5k -name *json | xargs -I{} cp "{}" fuzz-testing/testcases
@echo "Execute: afl-fuzz -i fuzz-testing/testcases -o fuzz-testing/out fuzz-testing/fuzzer"
fuzz_testing_bson:
rm -fr fuzz-testing
mkdir -p fuzz-testing fuzz-testing/testcases fuzz-testing/out
$(MAKE) parse_bson_fuzzer -C test CXX=afl-clang++
mv test/parse_bson_fuzzer fuzz-testing/fuzzer
find test/data -size -5k -name *.bson | xargs -I{} cp "{}" fuzz-testing/testcases
$(MAKE) parse_bson_fuzzer -C tests CXX=afl-clang++
mv tests/parse_bson_fuzzer fuzz-testing/fuzzer
find tests/data -size -5k -name *.bson | xargs -I{} cp "{}" fuzz-testing/testcases
@echo "Execute: afl-fuzz -i fuzz-testing/testcases -o fuzz-testing/out fuzz-testing/fuzzer"
fuzz_testing_cbor:
rm -fr fuzz-testing
mkdir -p fuzz-testing fuzz-testing/testcases fuzz-testing/out
$(MAKE) parse_cbor_fuzzer -C test CXX=afl-clang++
mv test/parse_cbor_fuzzer fuzz-testing/fuzzer
find test/data -size -5k -name *.cbor | xargs -I{} cp "{}" fuzz-testing/testcases
$(MAKE) parse_cbor_fuzzer -C tests CXX=afl-clang++
mv tests/parse_cbor_fuzzer fuzz-testing/fuzzer
find tests/data -size -5k -name *.cbor | xargs -I{} cp "{}" fuzz-testing/testcases
@echo "Execute: afl-fuzz -i fuzz-testing/testcases -o fuzz-testing/out fuzz-testing/fuzzer"
fuzz_testing_msgpack:
rm -fr fuzz-testing
mkdir -p fuzz-testing fuzz-testing/testcases fuzz-testing/out
$(MAKE) parse_msgpack_fuzzer -C test CXX=afl-clang++
mv test/parse_msgpack_fuzzer fuzz-testing/fuzzer
find test/data -size -5k -name *.msgpack | xargs -I{} cp "{}" fuzz-testing/testcases
$(MAKE) parse_msgpack_fuzzer -C tests CXX=afl-clang++
mv tests/parse_msgpack_fuzzer fuzz-testing/fuzzer
find tests/data -size -5k -name *.msgpack | xargs -I{} cp "{}" fuzz-testing/testcases
@echo "Execute: afl-fuzz -i fuzz-testing/testcases -o fuzz-testing/out fuzz-testing/fuzzer"
fuzz_testing_ubjson:
rm -fr fuzz-testing
mkdir -p fuzz-testing fuzz-testing/testcases fuzz-testing/out
$(MAKE) parse_ubjson_fuzzer -C test CXX=afl-clang++
mv test/parse_ubjson_fuzzer fuzz-testing/fuzzer
find test/data -size -5k -name *.ubjson | xargs -I{} cp "{}" fuzz-testing/testcases
$(MAKE) parse_ubjson_fuzzer -C tests CXX=afl-clang++
mv tests/parse_ubjson_fuzzer fuzz-testing/fuzzer
find tests/data -size -5k -name *.ubjson | xargs -I{} cp "{}" fuzz-testing/testcases
@echo "Execute: afl-fuzz -i fuzz-testing/testcases -o fuzz-testing/out fuzz-testing/fuzzer"
fuzzing-start:
@ -159,18 +159,18 @@ pretty:
--preserve-date \
--suffix=none \
--formatted \
$(SRCS) $(AMALGAMATED_FILE) test/src/*.cpp test/src/*.hpp benchmarks/src/benchmarks.cpp doc/examples/*.cpp
$(SRCS) $(AMALGAMATED_FILE) tests/src/*.cpp tests/src/*.hpp tests/benchmarks/src/benchmarks.cpp docs/examples/*.cpp
# call the Clang-Format on all source files
pretty_format:
for FILE in $(SRCS) $(AMALGAMATED_FILE) test/src/*.cpp test/src/*.hpp benchmarks/src/benchmarks.cpp doc/examples/*.cpp; do echo $$FILE; clang-format -i $$FILE; done
for FILE in $(SRCS) $(AMALGAMATED_FILE) tests/src/*.cpp tests/src/*.hpp benchmarks/src/benchmarks.cpp docs/examples/*.cpp; do echo $$FILE; clang-format -i $$FILE; done
# create single header file
amalgamate: $(AMALGAMATED_FILE)
# call the amalgamation tool and pretty print
$(AMALGAMATED_FILE): $(SRCS)
third_party/amalgamate/amalgamate.py -c third_party/amalgamate/config.json -s . --verbose=yes
tools/amalgamate/amalgamate.py -c tools/amalgamate/config.json -s . --verbose=yes
$(MAKE) pretty
# check if file single_include/nlohmann/json.hpp has been amalgamated from the nlohmann sources
@ -233,10 +233,10 @@ release: include.zip json.tar.xz
# clean up
clean:
rm -fr fuzz fuzz-testing *.dSYM test/*.dSYM
rm -fr fuzz fuzz-testing *.dSYM tests/*.dSYM
rm -fr benchmarks/files/numbers/*.json
rm -fr cmake-build-benchmarks fuzz-testing cmake-build-pvs-studio release_files
$(MAKE) clean -Cdoc
$(MAKE) clean -Cdocs
##########################################################################
@ -251,3 +251,10 @@ update_hedley:
$(SED) -i '1s/^/#pragma once\n\n/' include/nlohmann/thirdparty/hedley/hedley.hpp
$(SED) -i '1s/^/#pragma once\n\n/' include/nlohmann/thirdparty/hedley/hedley_undef.hpp
$(MAKE) amalgamate
##########################################################################
# serve_header.py
##########################################################################
serve_header:
./tools/serve_header/serve_header.py --make $(MAKE)

90
README.md
View File

@ -1,4 +1,4 @@
[![JSON for Modern C++](https://raw.githubusercontent.com/nlohmann/json/master/doc/json.gif)](https://github.com/nlohmann/json/releases)
[![JSON for Modern C++](docs/json.gif)](https://github.com/nlohmann/json/releases)
[![Build Status](https://ci.appveyor.com/api/projects/status/1acb366xfyg3qybk/branch/develop?svg=true)](https://ci.appveyor.com/project/nlohmann/json)
[![Ubuntu](https://github.com/nlohmann/json/workflows/Ubuntu/badge.svg)](https://github.com/nlohmann/json/actions?query=workflow%3AUbuntu)
@ -32,7 +32,7 @@
- [Implicit conversions](#implicit-conversions)
- [Conversions to/from arbitrary types](#arbitrary-types-conversions)
- [Specializing enum conversion](#specializing-enum-conversion)
- [Binary formats (BSON, CBOR, MessagePack, and UBJSON)](#binary-formats-bson-cbor-messagepack-and-ubjson)
- [Binary formats (BSON, CBOR, MessagePack, UBJSON, and BJData)](#binary-formats-bson-cbor-messagepack-ubjson-and-bjdata)
- [Supported compilers](#supported-compilers)
- [Integration](#integration)
- [CMake](#cmake)
@ -54,7 +54,7 @@ There are myriads of [JSON](https://json.org) libraries out there, and each may
- **Trivial integration**. Our whole code consists of a single header file [`json.hpp`](https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json.hpp). That's it. No library, no subproject, no dependencies, no complex build system. The class is written in vanilla C++11. All in all, everything should require no adjustment of your compiler flags or project settings.
- **Serious testing**. Our class is heavily [unit-tested](https://github.com/nlohmann/json/tree/develop/test/src) and covers [100%](https://coveralls.io/r/nlohmann/json) of the code, including all exceptional behavior. Furthermore, we checked with [Valgrind](https://valgrind.org) and the [Clang Sanitizers](https://clang.llvm.org/docs/index.html) that there are no memory leaks. [Google OSS-Fuzz](https://github.com/google/oss-fuzz/tree/master/projects/json) additionally runs fuzz tests against all parsers 24/7, effectively executing billions of tests so far. To maintain high quality, the project is following the [Core Infrastructure Initiative (CII) best practices](https://bestpractices.coreinfrastructure.org/projects/289).
- **Serious testing**. Our code is heavily [unit-tested](https://github.com/nlohmann/json/tree/develop/tests/src) and covers [100%](https://coveralls.io/r/nlohmann/json) of the code, including all exceptional behavior. Furthermore, we checked with [Valgrind](https://valgrind.org) and the [Clang Sanitizers](https://clang.llvm.org/docs/index.html) that there are no memory leaks. [Google OSS-Fuzz](https://github.com/google/oss-fuzz/tree/master/projects/json) additionally runs fuzz tests against all parsers 24/7, effectively executing billions of tests so far. To maintain high quality, the project is following the [Core Infrastructure Initiative (CII) best practices](https://bestpractices.coreinfrastructure.org/projects/289).
Other aspects were not so important to us:
@ -69,6 +69,10 @@ See the [contribution guidelines](https://github.com/nlohmann/json/blob/master/.
You can sponsor this library at [GitHub Sponsors](https://github.com/sponsors/nlohmann).
### :office: Corporate Sponsor
[![](https://upload.wikimedia.org/wikipedia/commons/thumb/9/9e/Codacy-logo-black.svg/320px-Codacy-logo-black.svg.png)](https://github.com/codacy)
### :label: Named Sponsors
- [Michael Hartmann](https://github.com/reFX-Mike)
@ -83,7 +87,7 @@ Thanks everyone!
:question: If you have a **question**, please check if it is already answered in the [**FAQ**](https://json.nlohmann.me/home/faq/) or the [**Q&A**](https://github.com/nlohmann/json/discussions/categories/q-a) section. If not, please [**ask a new question**](https://github.com/nlohmann/json/discussions/new) there.
:books: If you want to **learn more** about how to use the library, check out the rest of the [**README**](#examples), have a look at [**code examples**](https://github.com/nlohmann/json/tree/develop/doc/examples), or browse through the [**help pages**](https://json.nlohmann.me).
:books: If you want to **learn more** about how to use the library, check out the rest of the [**README**](#examples), have a look at [**code examples**](https://github.com/nlohmann/json/tree/develop/docs/examples), or browse through the [**help pages**](https://json.nlohmann.me).
:construction: If you want to understand the **API** better, check out the [**API Reference**](https://json.nlohmann.me/api/basic_json/).
@ -93,7 +97,7 @@ There is also a [**docset**](https://github.com/Kapeli/Dash-User-Contributions/t
## Examples
Beside the examples below, you may want to check the [documentation](https://nlohmann.github.io/json/) where each function contains a separate code example (e.g., check out [`emplace()`](https://nlohmann.github.io/json/api/basic_json/emplace/)). All [example files](https://github.com/nlohmann/json/tree/develop/doc/examples) can be compiled and executed on their own (e.g., file [emplace.cpp](https://github.com/nlohmann/json/blob/develop/doc/examples/emplace.cpp)).
Beside the examples below, you may want to check the [documentation](https://json.nlohmann.me/) where each function contains a separate code example (e.g., check out [`emplace()`](https://json.nlohmann.me/api/basic_json/emplace/)). All [example files](https://github.com/nlohmann/json/tree/develop/docs/examples) can be compiled and executed on their own (e.g., file [emplace.cpp](https://github.com/nlohmann/json/blob/develop/docs/examples/emplace.cpp)).
### JSON as first-class data type
@ -162,7 +166,7 @@ json j2 = {
};
```
Note that in all these cases, you never need to "tell" the compiler which JSON value type you want to use. If you want to be explicit or express some edge cases, the functions [`json::array()`](https://nlohmann.github.io/json/api/basic_json/array/) and [`json::object()`](https://nlohmann.github.io/json/api/basic_json/object/) will help:
Note that in all these cases, you never need to "tell" the compiler which JSON value type you want to use. If you want to be explicit or express some edge cases, the functions [`json::array()`](https://json.nlohmann.me/api/basic_json/array/) and [`json::object()`](https://json.nlohmann.me/api/basic_json/object/) will help:
```cpp
// a way to express the empty array []
@ -197,7 +201,7 @@ auto j2 = R"(
Note that without appending the `_json` suffix, the passed string literal is not parsed, but just used as JSON string value. That is, `json j = "{ \"happy\": true, \"pi\": 3.141 }"` would just store the string `"{ "happy": true, "pi": 3.141 }"` rather than parsing the actual object.
The above example can also be expressed explicitly using [`json::parse()`](https://nlohmann.github.io/json/api/basic_json/parse/):
The above example can also be expressed explicitly using [`json::parse()`](https://json.nlohmann.me/api/basic_json/parse/):
```cpp
// parse explicitly
@ -240,9 +244,9 @@ std::cout << cpp_string << " == " << cpp_string2 << " == " << j_string.get<std::
std::cout << j_string << " == " << serialized_string << std::endl;
```
[`.dump()`](https://nlohmann.github.io/json/api/basic_json/dump/) returns the originally stored string value.
[`.dump()`](https://json.nlohmann.me/api/basic_json/dump/) returns the originally stored string value.
Note the library only supports UTF-8. When you store strings with different encodings in the library, calling [`dump()`](https://nlohmann.github.io/json/api/basic_json/dump/) may throw an exception unless `json::error_handler_t::replace` or `json::error_handler_t::ignore` are used as error handlers.
Note the library only supports UTF-8. When you store strings with different encodings in the library, calling [`dump()`](https://json.nlohmann.me/api/basic_json/dump/) may throw an exception unless `json::error_handler_t::replace` or `json::error_handler_t::ignore` are used as error handlers.
#### To/from streams (e.g. files, string streams)
@ -730,7 +734,7 @@ Some important things:
* Those methods **MUST** be in your type's namespace (which can be the global namespace), or the library will not be able to locate them (in this example, they are in namespace `ns`, where `person` is defined).
* Those methods **MUST** be available (e.g., proper headers must be included) everywhere you use these conversions. Look at [issue 1108](https://github.com/nlohmann/json/issues/1108) for errors that may occur otherwise.
* When using `get<your_type>()`, `your_type` **MUST** be [DefaultConstructible](https://en.cppreference.com/w/cpp/named_req/DefaultConstructible). (There is a way to bypass this requirement described later.)
* In function `from_json`, use function [`at()`](https://nlohmann.github.io/json/api/basic_json/at/) 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.
* In function `from_json`, use function [`at()`](https://json.nlohmann.me/api/basic_json/at/) 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.
#### Simplify your life with macros
@ -857,7 +861,7 @@ namespace nlohmann {
#### Can I write my own serializer? (Advanced use)
Yes. You might want to take a look at [`unit-udt.cpp`](https://github.com/nlohmann/json/blob/develop/test/src/unit-udt.cpp) in the test suite, to see a few examples.
Yes. You might want to take a look at [`unit-udt.cpp`](https://github.com/nlohmann/json/blob/develop/tests/src/unit-udt.cpp) in the test suite, to see a few examples.
If you write your own serializer, you'll need to do a few things:
@ -961,9 +965,9 @@ Other Important points:
- When using `get<ENUM_TYPE>()`, undefined JSON values will default to the first pair specified in your map. Select this default pair carefully.
- If an enum or JSON value is specified more than once in your map, the first matching occurrence from the top of the map will be returned when converting to or from JSON.
### Binary formats (BSON, CBOR, MessagePack, and UBJSON)
### Binary formats (BSON, CBOR, MessagePack, UBJSON, and BJData)
Though JSON is a ubiquitous data format, it is not a very compact format suitable for data exchange, for instance over a network. Hence, the library supports [BSON](https://bsonspec.org) (Binary JSON), [CBOR](https://cbor.io) (Concise Binary Object Representation), [MessagePack](https://msgpack.org), and [UBJSON](https://ubjson.org) (Universal Binary JSON Specification) to efficiently encode JSON values to byte vectors and to decode such vectors.
Though JSON is a ubiquitous data format, it is not a very compact format suitable for data exchange, for instance over a network. Hence, the library supports [BSON](https://bsonspec.org) (Binary JSON), [CBOR](https://cbor.io) (Concise Binary Object Representation), [MessagePack](https://msgpack.org), [UBJSON](https://ubjson.org) (Universal Binary JSON Specification) and [BJData](https://neurojson.org/bjdata) (Binary JData) to efficiently encode JSON values to byte vectors and to decode such vectors.
```cpp
// create a JSON value
@ -1083,18 +1087,11 @@ The following compilers are currently used in continuous integration at [AppVeyo
| Apple Clang 12.0.0 (clang-1200.0.32.27); Xcode 12.2 | macOS 10.15.7 | GitHub Actions |
| Apple Clang 12.0.0 (clang-1200.0.32.28); Xcode 12.3 | macOS 10.15.7 | GitHub Actions |
| Apple Clang 12.0.0 (clang-1200.0.32.29); Xcode 12.4 | macOS 10.15.7 | GitHub Actions |
| GCC 4.8.5 (Ubuntu 4.8.5-4ubuntu2) | Ubuntu 20.04.3 LTS | GitHub Actions |
| GCC 4.9.3 (Ubuntu 4.9.3-13ubuntu2) | Ubuntu 20.04.3 LTS | GitHub Actions |
| GCC 5.4.0 (Ubuntu 5.4.0-6ubuntu1~16.04.12) | Ubuntu 20.04.3 LTS | GitHub Actions |
| GCC 6.4.0 (Ubuntu 6.4.0-17ubuntu1) | Ubuntu 20.04.3 LTS | GitHub Actions |
| GCC 7.5.0 (Ubuntu 7.5.0-6ubuntu2) | Ubuntu 20.04.3 LTS | GitHub Actions |
| GCC 8.1.0 (x86_64-posix-seh-rev0, Built by MinGW-W64 project) | Windows-10.0.17763 | GitHub Actions |
| GCC 8.1.0 (i686-posix-dwarf-rev0, Built by MinGW-W64 project) | Windows-10.0.17763 | GitHub Actions |
| GCC 8.4.0 (Ubuntu 8.4.0-3ubuntu2) | Ubuntu 20.04.3 LTS | GitHub Actions |
| GCC 9.3.0 (Ubuntu 9.3.0-17ubuntu1~20.04) | Ubuntu 20.04.3 LTS | GitHub Actions |
| GCC 10.2.0 (Ubuntu 10.2.0-5ubuntu1~20.04) | Ubuntu 20.04.3 LTS | GitHub Actions |
| GCC 11.1.0 | Ubuntu (aarch64) | Drone CI |
| GCC 12.0.0 20211219 (experimental) | Ubuntu 20.04.3 LTS | GitHub Actions |
| Apple Clang 13.0.0 (clang-1300.0.29.3); Xcode 13.1 | macOS 12.3.1 | GitHub Actions |
| Apple Clang 13.0.0 (clang-1300.0.29.30); Xcode 13.2 | macOS 12.3.1 | GitHub Actions |
| Apple Clang 13.0.0 (clang-1300.0.29.30); Xcode 13.2.1 | macOS 12.3.1 | GitHub Actions |
| Apple Clang 13.1.6 (clang-1316.0.21.2); Xcode 13.3 | macOS 12.3.1 | GitHub Actions |
| Apple Clang 13.1.6 (clang-1316.0.21.2.3); Xcode 13.3.1 | macOS 12.3.1 | GitHub Actions |
| Clang 3.5.2 (3.5.2-3ubuntu1) | Ubuntu 20.04.3 LTS | GitHub Actions |
| Clang 3.6.2 (3.6.2-3ubuntu2) | Ubuntu 20.04.3 LTS | GitHub Actions |
| Clang 3.7.1 (3.7.1-2ubuntu2) | Ubuntu 20.04.3 LTS | GitHub Actions |
@ -1113,8 +1110,22 @@ The following compilers are currently used in continuous integration at [AppVeyo
| Clang 11.0.0 (11.0.0-2~ubuntu20.04.1) | Ubuntu 20.04.3 LTS | GitHub Actions |
| Clang 12.0.0 (12.0.0-3ubuntu1~20.04.3) | Ubuntu 20.04.3 LTS | GitHub Actions |
| Clang 13.0.1 (13.0.1-++20211015123032+cf15ccdeb6d5-1exp120211015003613.5) | Ubuntu 20.04.3 LTS | GitHub Actions |
| Clang 14.0.0 (14.0.0-++20211221052852+55c71c9eac9b-1exp120211221172954.95) | Ubuntu 20.04.3 LTS | GitHub Actions |
| Clang 15.0.0 (15.0.0-++20220403052648+896770c9a92e-1~exp1~20220403172744.209) | Ubuntu 20.04.3 LTS | GitHub Actions |
| Clang 14.0.5-++20220603124341+2f0a69c32a4c-1~exp1~20220603124352.149 | Ubuntu 20.04.3 LTS | GitHub Actions |
| Clang 15.0.0 (15.0.0-++20220530052901+b7d2b160c3ba-1~exp1~20220530172952.268) | Ubuntu 20.04.3 LTS | GitHub Actions |
| GCC 4.8.5 (Ubuntu 4.8.5-4ubuntu2) | Ubuntu 20.04.3 LTS | GitHub Actions |
| GCC 4.9.3 (Ubuntu 4.9.3-13ubuntu2) | Ubuntu 20.04.3 LTS | GitHub Actions |
| GCC 5.4.0 (Ubuntu 5.4.0-6ubuntu1~16.04.12) | Ubuntu 20.04.3 LTS | GitHub Actions |
| GCC 6.4.0 (Ubuntu 6.4.0-17ubuntu1) | Ubuntu 20.04.3 LTS | GitHub Actions |
| GCC 7.5.0 (Ubuntu 7.5.0-6ubuntu2) | Ubuntu 20.04.3 LTS | GitHub Actions |
| GCC 8.1.0 (i686-posix-dwarf-rev0, Built by MinGW-W64 project) | Windows-10.0.17763 | GitHub Actions |
| GCC 8.1.0 (x86_64-posix-seh-rev0, Built by MinGW-W64 project) | Windows-10.0.17763 | GitHub Actions |
| GCC 8.4.0 (Ubuntu 8.4.0-3ubuntu2) | Ubuntu 20.04.3 LTS | GitHub Actions |
| GCC 9.3.0 (Ubuntu 9.3.0-17ubuntu1~20.04) | Ubuntu 20.04.3 LTS | GitHub Actions |
| GCC 10.2.0 (Ubuntu 10.2.0-5ubuntu1~20.04) | Ubuntu 20.04.3 LTS | GitHub Actions |
| GCC 11.1.0 | Ubuntu (aarch64) | Drone CI |
| GCC 11.1.0 (Ubuntu 11.1.0-1ubuntu1~20.04) | Ubuntu 20.04.3 LTS | GitHub Actions |
| GCC 13.0.0 13.0.0 20220605 (experimental) | Ubuntu 20.04.3 LTS | GitHub Actions |
| Intel C++ Compiler 2021.5.0.20211109 | Ubuntu 20.04.3 LTS | GitHub Actions |
| NVCC 11.0.221 | Ubuntu 20.04.3 LTS | GitHub Actions |
| Visual Studio 14 2015 MSVC 19.0.24241.7 (Build Engine version 14.0.25420.1) | Windows-6.3.9600 | AppVeyor |
| Visual Studio 15 2017 MSVC 19.16.27035.0 (Build Engine version 15.9.21+g9802d43bc3 for .NET Framework) | Windows-10.0.14393 | AppVeyor |
@ -1329,7 +1340,7 @@ Only if your request would contain confidential information, please [send me an
I deeply appreciate the help of the following people.
<img src="https://raw.githubusercontent.com/nlohmann/json/develop/doc/avatars.png" align="right">
<img src="https://raw.githubusercontent.com/nlohmann/json/develop/docs/avatars.png" align="right">
- [Teemperor](https://github.com/Teemperor) implemented CMake support and lcov integration, realized escape and Unicode handling in the string parser, and fixed the JSON serialization.
- [elliotgoodrich](https://github.com/elliotgoodrich) fixed an issue with double deletion in the iterator classes.
@ -1598,6 +1609,21 @@ I deeply appreciate the help of the following people.
- [Dirk Stolle](https://github.com/striezel) fixed typos in documentation.
- [Daniel Albuschat](https://github.com/daniel-kun) corrected the parameter name in the `parse` documentation.
- [Prince Mendiratta](https://github.com/Prince-Mendiratta) fixed a link to the FAQ.
- [Florian Albrechtskirchinger](https://github.com/falbrechtskirchinger) implemented `std::string_view` support for object keys and made dozens of other improvements.
- [Qianqian Fang](https://github.com/fangq) implemented the Binary JData (BJData) format.
- [pketelsen](https://github.com/pketelsen) added macros `NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT` and `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT`.
- [DarkZeros](https://github.com/DarkZeros) adjusted to code to not clash with Arduino defines.
- [flagarde](https://github.com/flagarde) fixed the output of `meta()` for MSVC.
- [Giovanni Cerretani](https://github.com/gcerretani) fixed a check for `std::filesystem`.
- [Dimitris Apostolou](https://github.com/rex4539) fixed a typo.
- [Ferry Huberts](https://github.com/fhuberts) fixed a typo.
- [Michael Nosthoff](https://github.com/heinemml) fixed a typo.
- [JungHoon Lee](https://github.com/jhnlee) fixed a typo.
- [Faruk D.](https://github.com/fdiblen) fixed the CITATION.CFF file.
- [Andrea Cocito](https://github.com/puffetto) added a clarification on macro usage to the documentation.
- [Krzysiek Karbowiak](https://github.com/kkarbowiak) refactored the tests to use `CHECK_THROWS_WITH_AS`.
- [Chaoqi Zhang](https://github.com/prncoprs) fixed a typo.
- [ivanovmp](https://github.com/ivanovmp) fixed a whitespace error.
Thanks a lot for helping out! Please [let me know](mailto:mail@nlohmann.me) if I forgot someone.
@ -1612,7 +1638,7 @@ The library itself consists of a single header file licensed under the MIT licen
- [**Artistic Style**](http://astyle.sourceforge.net) for automatic source code indentation
- [**Clang**](https://clang.llvm.org) for compilation with code sanitizers
- [**CMake**](https://cmake.org) for build automation
- [**Codacity**](https://www.codacy.com) for further [code analysis](https://www.codacy.com/app/nlohmann/json)
- [**Codacy**](https://www.codacy.com) for further [code analysis](https://www.codacy.com/app/nlohmann/json)
- [**Coveralls**](https://coveralls.io) to measure [code coverage](https://coveralls.io/github/nlohmann/json)
- [**Coverity Scan**](https://scan.coverity.com) for [static analysis](https://scan.coverity.com/projects/nlohmann-json)
- [**cppcheck**](http://cppcheck.sourceforge.net) for static analysis
@ -1632,7 +1658,7 @@ The library itself consists of a single header file licensed under the MIT licen
## Projects using JSON for Modern C++
The library is currently used in Apple macOS Sierra and iOS 10. I am not sure what they are using the library for, but I am happy that it runs on so many devices.
The library is currently used in Apple macOS Sierra-Monterey and iOS 10-15. I am not sure what they are using the library for, but I am happy that it runs on so many devices.
## Notes
@ -1647,7 +1673,7 @@ The library supports **Unicode input** as follows:
- [Unicode noncharacters](https://www.unicode.org/faq/private_use.html#nonchar1) will not be replaced by the library.
- Invalid surrogates (e.g., incomplete pairs such as `\uDEAD`) will yield parse errors.
- The strings stored in the library are UTF-8 encoded. When using the default string type (`std::string`), note that its length/size functions return the number of stored bytes rather than the number of characters or glyphs.
- When you store strings with different encodings in the library, calling [`dump()`](https://nlohmann.github.io/json/api/basic_json/dump/) may throw an exception unless `json::error_handler_t::replace` or `json::error_handler_t::ignore` are used as error handlers.
- When you store strings with different encodings in the library, calling [`dump()`](https://json.nlohmann.me/api/basic_json/dump/) may throw an exception unless `json::error_handler_t::replace` or `json::error_handler_t::ignore` are used as error handlers.
- To store wide strings (e.g., `std::wstring`), you need to convert them to a UTF-8 encoded `std::string` before, see [an example](https://json.nlohmann.me/home/faq/#wide-string-handling).
### Comments in JSON
@ -1682,7 +1708,7 @@ Here is a related issue [#1924](https://github.com/nlohmann/json/issues/1924).
### Further notes
- The code contains numerous debug **assertions** which can be switched off by defining the preprocessor macro `NDEBUG`, see the [documentation of `assert`](https://en.cppreference.com/w/cpp/error/assert). In particular, note [`operator[]`](https://nlohmann.github.io/json/api/basic_json/operator%5B%5D/) implements **unchecked access** for const objects: If the given key is not present, the behavior is undefined (think of a dereferenced null pointer) and yields an [assertion failure](https://github.com/nlohmann/json/issues/289) if assertions are switched on. If you are not sure whether an element in an object exists, use checked access with the [`at()` function](https://nlohmann.github.io/json/api/basic_json/at/). Furthermore, you can define `JSON_ASSERT(x)` to replace calls to `assert(x)`.
- The code contains numerous debug **assertions** which can be switched off by defining the preprocessor macro `NDEBUG`, see the [documentation of `assert`](https://en.cppreference.com/w/cpp/error/assert). In particular, note [`operator[]`](https://json.nlohmann.me/api/basic_json/operator%5B%5D/) implements **unchecked access** for const objects: If the given key is not present, the behavior is undefined (think of a dereferenced null pointer) and yields an [assertion failure](https://github.com/nlohmann/json/issues/289) if assertions are switched on. If you are not sure whether an element in an object exists, use checked access with the [`at()` function](https://json.nlohmann.me/api/basic_json/at/). Furthermore, you can define `JSON_ASSERT(x)` to replace calls to `assert(x)`.
- As the exact number type is not defined in the [JSON specification](https://tools.ietf.org/html/rfc8259.html), this library tries to choose the best fitting C++ number type automatically. As a result, the type `double` may be used to store numbers which may yield [**floating-point exceptions**](https://github.com/nlohmann/json/issues/181) in certain rare situations if floating-point exceptions have been unmasked in the calling code. These exceptions are not caused by the library and need to be fixed in the calling code, such as by re-masking the exceptions prior to calling library functions.
- The code can be compiled without C++ **runtime type identification** features; that is, you can use the `-fno-rtti` compiler flag.
- **Exceptions** are used widely within the library. They can, however, be switched off with either using the compiler flag `-fno-exceptions` or by defining the symbol `JSON_NOEXCEPTION`. In this case, exceptions are replaced by `abort()` calls. You can further control this behavior by defining `JSON_THROW_USER` (overriding `throw`), `JSON_TRY_USER` (overriding `try`), and `JSON_CATCH_USER` (overriding `catch`). Note that `JSON_THROW_USER` should leave the current scope (e.g., by throwing or aborting), as continuing after it may yield undefined behavior. Note the explanatory [`what()`](https://en.cppreference.com/w/cpp/error/exception/what) string of exceptions is not available for MSVC if exceptions are disabled, see [#2824](https://github.com/nlohmann/json/discussions/2824).

109
cmake/ci.cmake
View File

@ -111,7 +111,7 @@ set(CLANG_CXXFLAGS
-Wno-reserved-identifier
)
# Warning flags determined for GCC 12.0 (experimental) with https://github.com/nlohmann/gcc_flags:
# Warning flags determined for GCC 13.0 (experimental) with https://github.com/nlohmann/gcc_flags:
# Ignored GCC warnings:
# -Wno-abi-tag We do not care about ABI tags.
# -Wno-aggregate-return The library uses aggregate returns.
@ -161,10 +161,13 @@ set(GCC_CXXFLAGS
-Wanalyzer-use-after-free
-Wanalyzer-use-of-pointer-in-stale-stack-frame
-Wanalyzer-use-of-uninitialized-value
-Wanalyzer-va-arg-type-mismatch
-Wanalyzer-va-list-exhausted
-Wanalyzer-va-list-leak
-Wanalyzer-va-list-use-after-va-end
-Wanalyzer-write-to-const
-Wanalyzer-write-to-string-literal
-Warith-conversion
-Warray-bounds
-Warray-bounds=2
-Warray-compare
-Warray-parameter=2
@ -209,6 +212,7 @@ set(GCC_CXXFLAGS
-Wctad-maybe-unsupported
-Wctor-dtor-privacy
-Wdangling-else
-Wdangling-pointer=2
-Wdate-time
-Wdelete-incomplete
-Wdelete-non-virtual-dtor
@ -279,6 +283,7 @@ set(GCC_CXXFLAGS
-Wmissing-include-dirs
-Wmissing-profile
-Wmissing-requires
-Wmissing-template-keyword
-Wmultichar
-Wmultiple-inheritance
-Wmultistatement-macros
@ -340,11 +345,9 @@ set(GCC_CXXFLAGS
-Wsizeof-pointer-div
-Wsizeof-pointer-memaccess
-Wstack-protector
-Wstrict-aliasing
-Wstrict-aliasing=3
-Wstrict-null-sentinel
-Wstrict-overflow
-Wstrict-overflow=5
-Wno-strict-overflow
-Wstring-compare
-Wstringop-overflow=4
-Wstringop-overread
@ -373,6 +376,7 @@ set(GCC_CXXFLAGS
-Wterminate
-Wtrampolines
-Wtrigraphs
-Wtrivial-auto-var-init
-Wtsan
-Wtype-limits
-Wundef
@ -392,6 +396,7 @@ set(GCC_CXXFLAGS
-Wunused-result
-Wunused-value
-Wunused-variable
-Wuse-after-free=3
-Wuseless-cast
-Wvarargs
-Wvariadic-macros
@ -411,7 +416,7 @@ set(GCC_CXXFLAGS
add_custom_target(ci_test_gcc
COMMAND CXX=${GCC_TOOL} CXXFLAGS="${GCC_CXXFLAGS}" ${CMAKE_COMMAND}
-DCMAKE_BUILD_TYPE=Debug -GNinja
-DJSON_BuildTests=ON -DJSON_MultipleHeaders=ON
-DJSON_BuildTests=ON
-S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_gcc
COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/build_gcc
COMMAND cd ${PROJECT_BINARY_DIR}/build_gcc && ${CMAKE_CTEST_COMMAND} --parallel ${N} --output-on-failure
@ -421,7 +426,7 @@ add_custom_target(ci_test_gcc
add_custom_target(ci_test_clang
COMMAND CXX=${CLANG_TOOL} CXXFLAGS="${CLANG_CXXFLAGS}" ${CMAKE_COMMAND}
-DCMAKE_BUILD_TYPE=Debug -GNinja
-DJSON_BuildTests=ON -DJSON_MultipleHeaders=ON
-DJSON_BuildTests=ON
-S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_clang
COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/build_clang
COMMAND cd ${PROJECT_BINARY_DIR}/build_clang && ${CMAKE_CTEST_COMMAND} --parallel ${N} --output-on-failure
@ -463,7 +468,7 @@ endforeach()
add_custom_target(ci_test_noexceptions
COMMAND CXX=${CLANG_TOOL} ${CMAKE_COMMAND}
-DCMAKE_BUILD_TYPE=Debug -GNinja
-DJSON_BuildTests=ON -DJSON_MultipleHeaders=ON -DCMAKE_CXX_FLAGS=-DJSON_NOEXCEPTION -DDOCTEST_TEST_FILTER=--no-throw
-DJSON_BuildTests=ON -DCMAKE_CXX_FLAGS=-DJSON_NOEXCEPTION -DDOCTEST_TEST_FILTER=--no-throw
-S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_noexceptions
COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/build_noexceptions
COMMAND cd ${PROJECT_BINARY_DIR}/build_noexceptions && ${CMAKE_CTEST_COMMAND} --parallel ${N} --output-on-failure
@ -477,7 +482,7 @@ add_custom_target(ci_test_noexceptions
add_custom_target(ci_test_noimplicitconversions
COMMAND CXX=${CLANG_TOOL} ${CMAKE_COMMAND}
-DCMAKE_BUILD_TYPE=Debug -GNinja
-DJSON_BuildTests=ON -DJSON_MultipleHeaders=ON -DJSON_ImplicitConversions=OFF
-DJSON_BuildTests=ON -DJSON_ImplicitConversions=OFF
-S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_noimplicitconversions
COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/build_noimplicitconversions
COMMAND cd ${PROJECT_BINARY_DIR}/build_noimplicitconversions && ${CMAKE_CTEST_COMMAND} --parallel ${N} --output-on-failure
@ -491,13 +496,27 @@ add_custom_target(ci_test_noimplicitconversions
add_custom_target(ci_test_diagnostics
COMMAND CXX=${CLANG_TOOL} ${CMAKE_COMMAND}
-DCMAKE_BUILD_TYPE=Debug -GNinja
-DJSON_BuildTests=ON -DJSON_MultipleHeaders=ON -DJSON_Diagnostics=ON
-DJSON_BuildTests=ON -DJSON_Diagnostics=ON
-S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_diagnostics
COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/build_diagnostics
COMMAND cd ${PROJECT_BINARY_DIR}/build_diagnostics && ${CMAKE_CTEST_COMMAND} --parallel ${N} --output-on-failure
COMMENT "Compile and test with improved diagnostics enabled"
)
###############################################################################
# Enable legacy discarded value comparison.
###############################################################################
add_custom_target(ci_test_legacycomparison
COMMAND CXX=${CLANG_TOOL} ${CMAKE_COMMAND}
-DCMAKE_BUILD_TYPE=Debug -GNinja
-DJSON_BuildTests=ON -DJSON_LegacyDiscardedValueComparison=ON
-S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_legacycomparison
COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/build_legacycomparison
COMMAND cd ${PROJECT_BINARY_DIR}/build_legacycomparison && ${CMAKE_CTEST_COMMAND} --parallel ${N} --output-on-failure
COMMENT "Compile and test with legacy discarded value comparison enabled"
)
###############################################################################
# Coverage.
###############################################################################
@ -505,14 +524,21 @@ add_custom_target(ci_test_diagnostics
add_custom_target(ci_test_coverage
COMMAND CXX=g++ ${CMAKE_COMMAND}
-DCMAKE_BUILD_TYPE=Debug -GNinja -DCMAKE_CXX_FLAGS="--coverage;-fprofile-arcs;-ftest-coverage"
-DJSON_BuildTests=ON -DJSON_MultipleHeaders=ON
-DJSON_BuildTests=ON
-S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_coverage
COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/build_coverage
COMMAND cd ${PROJECT_BINARY_DIR}/build_coverage && ${CMAKE_CTEST_COMMAND} --parallel ${N} --output-on-failure
COMMAND CXX=g++ ${CMAKE_COMMAND}
-DCMAKE_BUILD_TYPE=Debug -GNinja -DCMAKE_CXX_FLAGS="-m32;--coverage;-fprofile-arcs;-ftest-coverage"
-DJSON_BuildTests=ON -DJSON_32bitTest=ONLY
-S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_coverage32
COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/build_coverage32
COMMAND cd ${PROJECT_BINARY_DIR}/build_coverage32 && ${CMAKE_CTEST_COMMAND} --parallel ${N} --output-on-failure
COMMAND ${LCOV_TOOL} --directory . --capture --output-file json.info --rc lcov_branch_coverage=1
COMMAND ${LCOV_TOOL} -e json.info ${SRC_FILES} --output-file json.info.filtered --rc lcov_branch_coverage=1
COMMAND ${CMAKE_SOURCE_DIR}/test/thirdparty/imapdl/filterbr.py json.info.filtered > json.info.filtered.noexcept
COMMAND ${CMAKE_SOURCE_DIR}/tests/thirdparty/imapdl/filterbr.py json.info.filtered > json.info.filtered.noexcept
COMMAND genhtml --title "JSON for Modern C++" --legend --demangle-cpp --output-directory html --show-details --branch-coverage json.info.filtered.noexcept
COMMENT "Compile and test with coverage"
@ -542,16 +568,16 @@ set(ASTYLE_FLAGS --style=allman --indent=spaces=4 --indent-modifiers --indent-sw
file(GLOB_RECURSE INDENT_FILES
${PROJECT_SOURCE_DIR}/include/nlohmann/*.hpp
${PROJECT_SOURCE_DIR}/test/src/*.cpp
${PROJECT_SOURCE_DIR}/test/src/*.hpp
${PROJECT_SOURCE_DIR}/benchmarks/src/benchmarks.cpp
${PROJECT_SOURCE_DIR}/doc/examples/*.cpp
${PROJECT_SOURCE_DIR}/tests/src/*.cpp
${PROJECT_SOURCE_DIR}/tests/src/*.hpp
${PROJECT_SOURCE_DIR}/tests/benchmarks/src/benchmarks.cpp
${PROJECT_SOURCE_DIR}/docs/examples/*.cpp
)
add_custom_target(ci_test_amalgamation
COMMAND rm -fr ${PROJECT_SOURCE_DIR}/single_include/nlohmann/json.hpp~
COMMAND cp ${PROJECT_SOURCE_DIR}/single_include/nlohmann/json.hpp ${PROJECT_SOURCE_DIR}/single_include/nlohmann/json.hpp~
COMMAND ${Python3_EXECUTABLE} ${PROJECT_SOURCE_DIR}/third_party/amalgamate/amalgamate.py -c ${PROJECT_SOURCE_DIR}/third_party/amalgamate/config.json -s .
COMMAND ${Python3_EXECUTABLE} ${PROJECT_SOURCE_DIR}/tools/amalgamate/amalgamate.py -c ${PROJECT_SOURCE_DIR}/tools/amalgamate/config.json -s .
COMMAND ${ASTYLE_TOOL} ${ASTYLE_FLAGS} --suffix=none --quiet ${PROJECT_SOURCE_DIR}/single_include/nlohmann/json.hpp
COMMAND diff ${PROJECT_SOURCE_DIR}/single_include/nlohmann/json.hpp~ ${PROJECT_SOURCE_DIR}/single_include/nlohmann/json.hpp
@ -559,7 +585,21 @@ add_custom_target(ci_test_amalgamation
COMMAND cd ${PROJECT_SOURCE_DIR} && for FILE in `find . -name '*.orig'`\; do false \; done
WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}
COMMENT "Check amalagamation and indentation"
COMMENT "Check amalgamation and indentation"
)
###############################################################################
# Build and test using the amalgamated header
###############################################################################
add_custom_target(ci_test_single_header
COMMAND CXX=${GCC_TOOL} CXXFLAGS="${GCC_CXXFLAGS}" ${CMAKE_COMMAND}
-DCMAKE_BUILD_TYPE=Debug -GNinja
-DJSON_BuildTests=ON -DJSON_MultipleHeader=OFF -DJSON_FastTests=ON
-S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_single_header
COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/build_single_header
COMMAND cd ${PROJECT_BINARY_DIR}/build_single_header && ${CMAKE_CTEST_COMMAND} --parallel ${N} --output-on-failure
COMMENT "Compile and test single-header version"
)
###############################################################################
@ -605,7 +645,7 @@ add_custom_target(ci_cppcheck
###############################################################################
add_custom_target(ci_cpplint
COMMAND ${Python3_EXECUTABLE} ${CMAKE_SOURCE_DIR}/third_party/cpplint/cpplint.py --filter=-whitespace,-legal,-runtime/references,-runtime/explicit,-runtime/indentation_namespace,-readability/casting,-readability/nolint --quiet --recursive ${SRC_FILES}
COMMAND ${Python3_EXECUTABLE} ${CMAKE_SOURCE_DIR}/tools/cpplint/cpplint.py --filter=-whitespace,-legal,-runtime/references,-runtime/explicit,-runtime/indentation_namespace,-readability/casting,-readability/nolint --quiet --recursive ${SRC_FILES}
COMMENT "Check code with cpplint"
)
@ -645,7 +685,7 @@ add_custom_target(ci_clang_tidy
COMMAND CXX=${CLANG_TOOL} ${CMAKE_COMMAND}
-DCMAKE_BUILD_TYPE=Debug -GNinja
-DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DCMAKE_CXX_CLANG_TIDY=${CLANG_TIDY_TOOL}
-DJSON_BuildTests=ON -DJSON_MultipleHeaders=ON
-DJSON_BuildTests=ON
-S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_clang_tidy
COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/build_clang_tidy
COMMENT "Check code with Clang-Tidy"
@ -672,7 +712,7 @@ add_custom_target(ci_pvs_studio
add_custom_target(ci_infer
COMMAND mkdir -p ${PROJECT_BINARY_DIR}/build_infer
COMMAND cd ${PROJECT_BINARY_DIR}/build_infer && ${INFER_TOOL} compile -- ${CMAKE_COMMAND} -DCMAKE_BUILD_TYPE=Debug ${PROJECT_SOURCE_DIR} -DJSON_BuildTests=ON -DJSON_MultipleHeaders=ON
COMMAND cd ${PROJECT_BINARY_DIR}/build_infer && ${INFER_TOOL} compile -- ${CMAKE_COMMAND} -DCMAKE_BUILD_TYPE=Debug ${PROJECT_SOURCE_DIR} -DJSON_BuildTests=ON
COMMAND cd ${PROJECT_BINARY_DIR}/build_infer && ${INFER_TOOL} run -- make
COMMENT "Check code with Infer"
)
@ -683,7 +723,7 @@ add_custom_target(ci_infer
add_custom_target(ci_offline_testdata
COMMAND mkdir -p ${PROJECT_BINARY_DIR}/build_offline_testdata/test_data
COMMAND cd ${PROJECT_BINARY_DIR}/build_offline_testdata/test_data && ${GIT_TOOL} clone -c advice.detachedHead=false --branch v3.0.0 https://github.com/nlohmann/json_test_data.git --quiet --depth 1
COMMAND cd ${PROJECT_BINARY_DIR}/build_offline_testdata/test_data && ${GIT_TOOL} clone -c advice.detachedHead=false --branch v3.1.0 https://github.com/nlohmann/json_test_data.git --quiet --depth 1
COMMAND ${CMAKE_COMMAND}
-DCMAKE_BUILD_TYPE=Debug -GNinja
-DJSON_BuildTests=ON -DJSON_FastTests=ON -DJSON_TestDataDirectory=${PROJECT_BINARY_DIR}/build_offline_testdata/test_data/json_test_data
@ -698,6 +738,7 @@ add_custom_target(ci_offline_testdata
###############################################################################
add_custom_target(ci_non_git_tests
COMMAND git config --global --add safe.directory ${PROJECT_SOURCE_DIR}
COMMAND mkdir -p ${PROJECT_BINARY_DIR}/build_non_git_tests/sources
COMMAND cd ${PROJECT_SOURCE_DIR} && for FILE in `${GIT_TOOL} ls-tree --name-only HEAD`\; do cp -r $$FILE ${PROJECT_BINARY_DIR}/build_non_git_tests/sources \; done
COMMAND ${CMAKE_COMMAND}
@ -797,8 +838,9 @@ endfunction()
ci_get_cmake(3.1.0 CMAKE_3_1_0_BINARY)
ci_get_cmake(3.13.0 CMAKE_3_13_0_BINARY)
set(JSON_CMAKE_FLAGS_3_1_0 "JSON_Install;JSON_MultipleHeaders;JSON_ImplicitConversions;JSON_Valgrind;JSON_Diagnostics;JSON_SystemInclude")
set(JSON_CMAKE_FLAGS_3_13_0 "JSON_BuildTests")
set(JSON_CMAKE_FLAGS_3_1_0 JSON_Diagnostics JSON_ImplicitConversions JSON_DisableEnumSerialization
JSON_LegacyDiscardedValueComparison JSON_Install JSON_MultipleHeaders JSON_SystemInclude JSON_Valgrind)
set(JSON_CMAKE_FLAGS_3_13_0 JSON_BuildTests)
function(ci_add_cmake_flags_targets flag min_version)
string(TOLOWER "ci_cmake_flag_${flag}" flag_target)
@ -841,7 +883,7 @@ add_custom_target(ci_cmake_flags
# Use more installed compilers.
###############################################################################
foreach(COMPILER g++-4.8 g++-4.9 g++-5 g++-6 g++-7 g++-8 g++-9 g++-10 clang++-3.5 clang++-3.6 clang++-3.7 clang++-3.8 clang++-3.9 clang++-4.0 clang++-5.0 clang++-6.0 clang++-7 clang++-8 clang++-9 clang++-10 clang++-11 clang++-12 clang++-13 clang++-14)
foreach(COMPILER g++-4.8 g++-4.9 g++-5 g++-6 g++-7 g++-8 g++-9 g++-10 g++-11 clang++-3.5 clang++-3.6 clang++-3.7 clang++-3.8 clang++-3.9 clang++-4.0 clang++-5.0 clang++-6.0 clang++-7 clang++-8 clang++-9 clang++-10 clang++-11 clang++-12 clang++-13 clang++-14)
find_program(COMPILER_TOOL NAMES ${COMPILER})
if (COMPILER_TOOL)
if ("${COMPILER}" STREQUAL "clang++-9")
@ -873,10 +915,25 @@ add_custom_target(ci_cuda_example
COMMAND ${CMAKE_COMMAND}
-DCMAKE_BUILD_TYPE=Debug -GNinja
-DCMAKE_CUDA_HOST_COMPILER=g++-8
-S${PROJECT_SOURCE_DIR}/test/cuda_example -B${PROJECT_BINARY_DIR}/build_cuda_example
-S${PROJECT_SOURCE_DIR}/tests/cuda_example -B${PROJECT_BINARY_DIR}/build_cuda_example
COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/build_cuda_example
)
###############################################################################
# Intel C++ Compiler
###############################################################################
add_custom_target(ci_icpc
COMMAND ${CMAKE_COMMAND}
-DCMAKE_BUILD_TYPE=Debug -GNinja
-DCMAKE_C_COMPILER=icc -DCMAKE_CXX_COMPILER=icpc
-DJSON_BuildTests=ON -DJSON_FastTests=ON
-S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_icpc
COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/build_icpc
COMMAND cd ${PROJECT_BINARY_DIR}/build_icpc && ${CMAKE_CTEST_COMMAND} --parallel ${N} --exclude-regex "test-unicode" --output-on-failure
COMMENT "Compile and test with ICPC"
)
###############################################################################
# Clean up all generated files.
###############################################################################

2
cmake/download_test_data.cmake
View File

@ -1,5 +1,5 @@
set(JSON_TEST_DATA_URL https://github.com/nlohmann/json_test_data)
set(JSON_TEST_DATA_VERSION 3.0.0)
set(JSON_TEST_DATA_VERSION 3.1.0)
# if variable is set, use test data from given directory rather than downloading them
if(JSON_TestDataDirectory)

46
cmake/test.cmake
View File

@ -156,6 +156,7 @@ endfunction()
#############################################################################
# json_test_add_test_for(
# <file>
# [NAME <name>]
# MAIN <main>
# [CXX_STANDARDS <version_number>...] [FORCE])
#
@ -165,6 +166,7 @@ endfunction()
#
# if C++ standard <version_number> is supported by the compiler and the
# source file contains JSON_HAS_CPP_<version_number>.
# Use NAME <name> to override the filename-derived test name.
# Use FORCE to create the test regardless of the file containing
# JSON_HAS_CPP_<version_number>.
# Test targets are linked against <main>.
@ -172,15 +174,22 @@ endfunction()
#############################################################################
function(json_test_add_test_for file)
cmake_parse_arguments(args "FORCE" "MAIN" "CXX_STANDARDS" ${ARGN})
get_filename_component(file_basename ${file} NAME_WE)
string(REGEX REPLACE "unit-([^$]+)" "test-\\1" test_name ${file_basename})
cmake_parse_arguments(args "FORCE" "MAIN;NAME" "CXX_STANDARDS" ${ARGN})
if("${args_MAIN}" STREQUAL "")
message(FATAL_ERROR "Required argument MAIN <main> missing.")
endif()
if("${args_NAME}" STREQUAL "")
get_filename_component(file_basename ${file} NAME_WE)
string(REGEX REPLACE "unit-([^$]+)" "test-\\1" test_name ${file_basename})
else()
set(test_name ${args_NAME})
if(NOT test_name MATCHES "test-[^$]+")
message(FATAL_ERROR "Test name must start with 'test-'.")
endif()
endif()
if("${args_CXX_STANDARDS}" STREQUAL "")
set(args_CXX_STANDARDS 11)
endif()
@ -202,3 +211,32 @@ function(json_test_add_test_for file)
_json_test_add_test(${test_name} ${file} ${args_MAIN} ${cxx_standard})
endforeach()
endfunction()
#############################################################################
# json_test_should_build_32bit_test(
# <build_32bit_var> <build_32bit_only_var> <input>)
#
# Check if the 32bit unit test should be built based on the value of <input>
# and store the result in the variables <build_32bit_var> and
# <build_32bit_only_var>.
#############################################################################
function(json_test_should_build_32bit_test build_32bit_var build_32bit_only_var input)
set(${build_32bit_only_var} OFF PARENT_SCOPE)
string(TOUPPER "${input}" ${build_32bit_var})
if("${${build_32bit_var}}" STREQUAL AUTO)
# check if compiler is targeting 32bit by default
include(CheckTypeSize)
check_type_size("size_t" sizeof_size_t LANGUAGE CXX)
if(sizeof_size_t AND ${sizeof_size_t} EQUAL 4)
message(STATUS "Auto-enabling 32bit unit test.")
set(${build_32bit_var} ON)
else()
set(${build_32bit_var} OFF)
endif()
elseif("${${build_32bit_var}}" STREQUAL ONLY)
set(${build_32bit_only_var} ON PARENT_SCOPE)
endif()
set(${build_32bit_var} "${${build_32bit_var}}" PARENT_SCOPE)
endfunction()

29
doc/examples/iterator_wrapper.cpp
View File

@ -1,29 +0,0 @@
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create JSON values
json j_object = {{"one", 1}, {"two", 2}};
json j_array = {1, 2, 4, 8, 16};
//////////////////////////////////////////////////////////////////////////
// The static function iterator_wrapper was deprecated in version 3.1.0
// and will be removed in version 4.0.0. Please replace all occurrences
// of iterator_wrapper(j) with j.items().
//////////////////////////////////////////////////////////////////////////
// example for an object
for (auto& x : json::iterator_wrapper(j_object))
{
std::cout << "key: " << x.key() << ", value: " << x.value() << '\n';
}
// example for an array
for (auto& x : json::iterator_wrapper(j_array))
{
std::cout << "key: " << x.key() << ", value: " << x.value() << '\n';
}
}

7
doc/examples/iterator_wrapper.output
View File

@ -1,7 +0,0 @@
key: one, value: 1
key: two, value: 2
key: 0, value: 1
key: 1, value: 2
key: 2, value: 4
key: 3, value: 8
key: 4, value: 16

2
doc/examples/sax_parse.output
View File

@ -1,2 +0,0 @@
(start: object) (key: Image) (start: object) (key: Width) (value: 800) (key: Height) (value: 600) (key: Title) (value: View from 15th Floor) (key: Thumbnail) (start: object) (key: Url) (value: http://www.example.com/image/481989943) (key: Height) (value: 125) (key: Width) (value: 100) (end: object) (key: Animated) (value: false) (key: IDs) (start: array) (value: 116) (value: 943) (value: 234) (value: 38793) (end: array) (key: Distance) (value: 12.723374634) (end: object) (end: object)
result: true

55
doc/mkdocs/docs/api/basic_json/count.md
View File

@ -1,55 +0,0 @@
# <small>nlohmann::basic_json::</small>count
```cpp
template<typename KeyT>
size_type count(KeyT&& key) const;
```
Returns the number of elements with key `key`. If `ObjectType` is the default `std::map` type, the return value will
always be `0` (`key` was not found) or `1` (`key` was found).
## Template parameters
`KeyT`
: A type for an object key.
## Parameters
`key` (in)
: key value of the element to count.
## Return value
Number of elements with key `key`. If the JSON value is not an object, the return value will be `0`.
## Exception safety
Strong exception safety: if an exception occurs, the original value stays intact.
## Complexity
Logarithmic in the size of the JSON object.
## Notes
This method always returns `0` when executed on a JSON type that is not an object.
## Examples
??? example
The example shows how `count()` is used.
```cpp
--8<-- "examples/count.cpp"
```
Output:
```json
--8<-- "examples/count.output"
```
## Version history
- Added in version 1.0.0.

63
doc/mkdocs/docs/api/basic_json/find.md
View File

@ -1,63 +0,0 @@
# <small>nlohmann::basic_json::</small>find
```cpp
template<typename KeyT>
iterator find(KeyT&& key);
template<typename KeyT>
const_iterator find(KeyT&& key) const;
```
Finds an element in a JSON object with key equivalent to `key`. If the element is not found or the JSON value is not an
object, `end()` is returned.
## Template parameters
`KeyT`
: A type for an object key.
## Parameters
`key` (in)
: key value of the element to search for.
## Return value
Iterator to an element with key equivalent to `key`. If no such element is found or the JSON value is not an object,
past-the-end (see `end()`) iterator is returned.
## Exception safety
Strong exception safety: if an exception occurs, the original value stays intact.
## Complexity
Logarithmic in the size of the JSON object.
## Notes
This method always returns `end()` when executed on a JSON type that is not an object.
## Examples
??? example
The example shows how `find()` is used.
```cpp
--8<-- "examples/find__key_type.cpp"
```
Output:
```json
--8<-- "examples/find__key_type.output"
```
## See also
- [contains](contains.md) checks whether a key exists
## Version history
- Added in version 1.0.0.

19
doc/mkdocs/docs/api/basic_json/get_allocator.md
View File

@ -1,19 +0,0 @@
# <small>nlohmann::basic_json::</small>get_allocator
```cpp
static allocator_type get_allocator();
```
Returns the allocator associated with the container.
## Return value
associated allocator
## Version history
- Unknown.
!!! note
This documentation page is a stub.

16
doc/mkdocs/docs/api/basic_json/object_comparator_t.md
View File

@ -1,16 +0,0 @@
# <small>nlohmann::basic_json::</small>object_comparator_t
```cpp
using object_comparator_t = std::less<StringType>; // until C++14
using object_comparator_t = std::less<>; // since C++14
```
The comparator used in [`object_t`](object_t.md).
When C++14 is detected, a transparent com parator is used which, when combined with perfect forwarding on find() and
count() calls, prevents unnecessary string construction.
## Version history
- Unknown.

72
doc/mkdocs/docs/api/basic_json/operator_ValueType.md
View File

@ -1,72 +0,0 @@
# <small>nlohmann::basic_json::</small>operator ValueType
```cpp
template<typename ValueType>
JSON_EXPLICIT operator ValueType() const;
```
Implicit type conversion between the JSON value and a compatible value. The call is realized by calling
[`get()`](get.md). See [Notes](#notes) for the meaning of `JSON_EXPLICIT`.
## Template parameters
`ValueType`
: the value type to return
## Return value
copy of the JSON value, converted to `ValueType`
## Exceptions
Depends on what `json_serializer<ValueType>` `from_json()` method throws
## Complexity
Linear in the size of the JSON value.
## Notes
By default `JSON_EXPLICIT` defined to the empty string, so the signature is:
```cpp
template<typename ValueType>
operator ValueType() const;
```
If [`JSON_USE_IMPLICIT_CONVERSIONS`](../../features/macros.md#json_use_implicit_conversions) is set to `0`,
`JSON_EXPLICIT` is defined to `#!cpp explicit`:
```cpp
template<typename ValueType>
explicit operator ValueType() const;
```
That is, implicit conversions can be switched off by defining
[`JSON_USE_IMPLICIT_CONVERSIONS`](../../features/macros.md#json_use_implicit_conversions) to `0`.
## Examples
??? example
The example below shows several conversions from JSON values
to other types. There a few things to note: (1) Floating-point numbers can
be converted to integers, (2) A JSON array can be converted to a standard
`std::vector<short>`, (3) A JSON object can be converted to C++
associative containers such as `std::unordered_map<std::string, json>`.
```cpp
--8<-- "examples/operator__ValueType.cpp"
```
Output:
```json
--8<-- "examples/operator__ValueType.output"
```
## Version history
- Since version 1.0.0.
- Macros `JSON_EXPLICIT`/[`JSON_USE_IMPLICIT_CONVERSIONS`](../../features/macros.md#json_use_implicit_conversions) added
in version 3.9.0.

59
doc/mkdocs/docs/api/basic_json/operator_ge.md
View File

@ -1,59 +0,0 @@
# <small>nlohmann::basic_json::</small>operator>=
```cpp
bool operator>=(const_reference lhs, const_reference rhs) noexcept,
template<typename ScalarType>
bool operator>=(const_reference lhs, const ScalarType rhs) noexcept;
template<typename ScalarType>
bool operator>=(ScalarType lhs, const const_reference rhs) noexcept;
```
Compares whether one JSON value `lhs` is greater than or equal to another JSON value `rhs` by calculating
`#!cpp !(lhs < rhs)`.
## Template parameters
`ScalarType`
: a scalar type according to `std::is_scalar<ScalarType>::value`
## Parameters
`lhs` (in)
: first value to consider
`rhs` (in)
: second value to consider
## Return value
whether `lhs` is less than or equal to `rhs`
## Exception safety
No-throw guarantee: this function never throws exceptions.
## Complexity
Linear.
## Examples
??? example
The example demonstrates comparing several JSON types.
```cpp
--8<-- "examples/operator__greaterequal.cpp"
```
Output:
```json
--8<-- "examples/operator__greaterequal.output"
```
## Version history
- Added in version 1.0.0.

58
doc/mkdocs/docs/api/basic_json/operator_gt.md
View File

@ -1,58 +0,0 @@
# <small>nlohmann::basic_json::</small>operator>
```cpp
bool operator>(const_reference lhs, const_reference rhs) noexcept,
template<typename ScalarType>
bool operator>(const_reference lhs, const ScalarType rhs) noexcept;
template<typename ScalarType>
bool operator>(ScalarType lhs, const const_reference rhs) noexcept;
```
Compares whether one JSON value `lhs` is greater than another JSON value `rhs` by calculating `#!cpp !(lhs <= rhs)`.
## Template parameters
`ScalarType`
: a scalar type according to `std::is_scalar<ScalarType>::value`
## Parameters
`lhs` (in)
: first value to consider
`rhs` (in)
: second value to consider
## Return value
whether `lhs` is greater than `rhs`
## Exception safety
No-throw guarantee: this function never throws exceptions.
## Complexity
Linear.
## Examples
??? example
The example demonstrates comparing several JSON types.
```cpp
--8<-- "examples/operator__greater.cpp"
```
Output:
```json
--8<-- "examples/operator__greater.output"
```
## Version history
- Added in version 1.0.0.

59
doc/mkdocs/docs/api/basic_json/operator_le.md
View File

@ -1,59 +0,0 @@
# <small>nlohmann::basic_json::</small>operator<=
```cpp
bool operator<=(const_reference lhs, const_reference rhs) noexcept,
template<typename ScalarType>
bool operator<=(const_reference lhs, const ScalarType rhs) noexcept;
template<typename ScalarType>
bool operator<=(ScalarType lhs, const const_reference rhs) noexcept;
```
Compares whether one JSON value `lhs` is less than or equal to another JSON value `rhs` by calculating
`#cpp !(rhs < lhs)`.
## Template parameters
`ScalarType`
: a scalar type according to `std::is_scalar<ScalarType>::value`
## Parameters
`lhs` (in)
: first value to consider
`rhs` (in)
: second value to consider
## Return value
whether `lhs` is less than or equal to `rhs`
## Exception safety
No-throw guarantee: this function never throws exceptions.
## Complexity
Linear.
## Examples
??? example
The example demonstrates comparing several JSON types.
```cpp
--8<-- "examples/operator__lessequal.cpp"
```
Output:
```json
--8<-- "examples/operator__lessequal.output"
```
## Version history
- Added in version 1.0.0.

73
doc/mkdocs/docs/api/basic_json/operator_lt.md
View File

@ -1,73 +0,0 @@
# <small>nlohmann::basic_json::</small>operator<
```cpp
bool operator<(const_reference lhs, const_reference rhs) noexcept;
template<typename ScalarType>
bool operator<(const_reference lhs, const ScalarType rhs) noexcept;
template<typename ScalarType>
bool operator<(ScalarType lhs, const const_reference rhs) noexcept;
```
Compares whether one JSON value `lhs` is less than another JSON value `rhs` according to the following rules:
- If `lhs` and `rhs` have the same type, the values are compared using the default `<` operator.
- Integer and floating-point numbers are automatically converted before comparison
- Discarded values a
- In case `lhs` and `rhs` have different types, the values are ignored and the order of the types is considered, which
is:
1. null
2. boolean
3. number (all types)
4. object
5. array
6. string
7. binary
For instance, any boolean value is considered less than any string.
## Template parameters
`ScalarType`
: a scalar type according to `std::is_scalar<ScalarType>::value`
## Parameters
`lhs` (in)
: first value to consider
`rhs` (in)
: second value to consider
## Return value
whether `lhs` is less than `rhs`
## Exception safety
No-throw guarantee: this function never throws exceptions.
## Complexity
Linear.
## Examples
??? example
The example demonstrates comparing several JSON types.
```cpp
--8<-- "examples/operator__less.cpp"
```
Output:
```json
--8<-- "examples/operator__less.output"
```
## Version history
- Added in version 1.0.0.

72
doc/mkdocs/docs/api/basic_json/operator_ne.md
View File

@ -1,72 +0,0 @@
# <small>nlohmann::basic_json::</small>operator!=
```cpp
bool operator!=(const_reference lhs, const_reference rhs) noexcept;
template<typename ScalarType>
bool operator!=(const_reference lhs, const ScalarType rhs) noexcept;
template<typename ScalarType>
bool operator!=(ScalarType lhs, const const_reference rhs) noexcept;
```
Compares two JSON values for inequality by calculating `#!cpp !(lhs == rhs)`.
## Template parameters
`ScalarType`
: a scalar type according to `std::is_scalar<ScalarType>::value`
## Parameters
`lhs` (in)
: first value to consider
`rhs` (in)
: second value to consider
## Return value
whether the values `lhs` and `rhs` are not equal
## Exception safety
No-throw guarantee: this function never throws exceptions.
## Complexity
Linear.
## Examples
??? example
The example demonstrates comparing several JSON types.
```cpp
--8<-- "examples/operator__notequal.cpp"
```
Output:
```json
--8<-- "examples/operator__notequal.output"
```
??? example
The example demonstrates comparing several JSON types against the null pointer (JSON `#!json null`).
```cpp
--8<-- "examples/operator__notequal__nullptr_t.cpp"
```
Output:
```json
--8<-- "examples/operator__notequal__nullptr_t.output"
```
## Version history
- Added in version 1.0.0.

36
doc/mkdocs/docs/api/basic_json/value_t.md
View File

@ -1,36 +0,0 @@
# <small>nlohmann::basic_json::</small>value_t
```cpp
enum class value_t : std::uint8_t {
null,
object,
array,
string,
boolean,
number_integer,
number_unsigned,
number_float,
binary,
discarded
};
```
This enumeration collects the different JSON types. It is internally used to distinguish the stored values, and the
functions [`is_null`](is_null.md), [`is_object`](is_object.md), [`is_array`](is_array.md), [`is_string`](is_string.md),
[`is_boolean`](is_boolean.md), [`is_number`](is_number.md) (with [`is_number_integer`](is_number_integer.md),
[`is_number_unsigned`](is_number_unsigned.md), and [`is_number_float`](is_number_float.md)),
[`is_discarded`](is_discarded.md), [`is_binary`](is_binary.md), [`is_primitive`](is_primitive.md), and
[`is_structured`](is_structured.md) rely on it.
## Notes
There are three enumeration entries (number_integer, number_unsigned, and number_float), because the library
distinguishes these three types for numbers: [`number_unsigned_t`](number_unsigned_t.md) is used for unsigned integers,
[`number_integer_t`](number_integer_t.md) is used for signed integers, and [`number_float_t`](number_float_t.md) is used
for floating-point numbers or to approximate integers which do not fit in the limits of their respective type.
## Version history
- Added in version 1.0.0.
- Added unsigned integer type in version 2.0.0.
- Added binary type in version 3.8.0.

15
doc/mkdocs/docs/api/json_sax/end_array.md
View File

@ -1,15 +0,0 @@
# <small>nlohmann::json_sax::</small>end_array
```cpp
virtual bool end_array() = 0;
```
The end of an array was read.
## Return value
Whether parsing should proceed.
## Version history
- Added in version 3.2.0.

15
doc/mkdocs/docs/api/json_sax/end_object.md
View File

@ -1,15 +0,0 @@
# <small>nlohmann::json_sax::</small>end_object
```cpp
virtual bool end_object() = 0;
```
The end of an object was read.
## Return value
Whether parsing should proceed.
## Version history
- Added in version 3.2.0.

15
doc/mkdocs/docs/api/json_sax/null.md
View File

@ -1,15 +0,0 @@
# <small>nlohmann::json_sax::</small>null
```cpp
virtual bool null() = 0;
```
A null value was read.
## Return value
Whether parsing should proceed.
## Version history
- Added in version 3.2.0.

22
doc/mkdocs/docs/api/macros/index.md
View File

@ -1,22 +0,0 @@
# Macros
!!! note
This page is under construction. See the [macro overview page](../../features/macros.md) until then.
Some aspects of the library can be configured by defining preprocessor macros before including the `json.hpp` header.
- [`JSON_ASSERT(x)`](json_assert.md)
- `JSON_CATCH_USER(exception)`
- `JSON_DIAGNOSTICS`
- `JSON_HAS_CPP_11`, `JSON_HAS_CPP_14`, `JSON_HAS_CPP_17`, `JSON_HAS_CPP_20`
- `JSON_NOEXCEPTION`
- `JSON_NO_IO`
- `JSON_SKIP_UNSUPPORTED_COMPILER_CHECK`
- `JSON_THROW_USER(exception)`
- `JSON_TRY_USER`
- `JSON_USE_IMPLICIT_CONVERSIONS`
- `NLOHMANN_DEFINE_TYPE_INTRUSIVE(type, member...)`
- `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(type, member...)`
- `NLOHMANN_JSON_SERIALIZE_ENUM(type, ...)`
- `NLOHMANN_JSON_VERSION_MAJOR`, `NLOHMANN_JSON_VERSION_MINOR`, `NLOHMANN_JSON_VERSION_PATCH`

11
doc/mkdocs/docs/api/macros/json_assert.md
View File

@ -1,11 +0,0 @@
# JSON_ASSERT(x)
```cpp
JSON_ASSERT(x)
```
## Default implementation
```cpp
assert(x);
```

15
doc/mkdocs/docs/api/ordered_json.md
View File

@ -1,15 +0,0 @@
# <small>nlohmann::</small>ordered_json
```cpp
using ordered_json = basic_json<ordered_map>;
```
This type preserves the insertion order of object keys.
## See also
- [ordered_map](ordered_map.md)
## Version history
Since version 3.9.0.

77
doc/mkdocs/docs/features/element_access/checked_access.md
View File

@ -1,77 +0,0 @@
# Checked access: at
## Overview
The `#!cpp at()` member function performs checked access; that is, it returns a reference to the desired value if it exists and throws a [`basic_json::out_of_range` exception](../../home/exceptions.md#out-of-range) otherwise.
??? example
Consider the following JSON value:
```json
{
"name": "Mary Smith",
"age": 42,
"hobbies": ["hiking", "reading"]
}
```
Assume the value is parsed to a `json` variable `j`.
| expression | value |
| ---------- | ----- |
| `#!cpp j` | `#!json {"name": "Mary Smith", "age": 42, "hobbies": ["hiking", "reading"]}` |
| `#!cpp j.at("name")` | `#!json "Mary Smith"` |
| `#!cpp j.at("age")` | `#!json 42` |
| `#!cpp j.at("hobbies")` | `#!json ["hiking", "reading"]` |
| `#!cpp j.at("hobbies").at(0)` | `#!json "hiking"` |
| `#!cpp j.at("hobbies").at(1)` | `#!json "reading"` |
The return value is a reference, so it can be modified by the original value.
??? example
```cpp
j.at("name") = "John Smith";
```
This code produces the following JSON value:
```json
{
"name": "John Smith",
"age": 42,
"hobbies": ["hiking", "reading"]
}
```
When accessing an invalid index (i.e., an index greater than or equal to the array size) or the passed object key is non-existing, an exception is thrown.
??? example
```cpp
j.at("hobbies").at(3) = "cooking";
```
This code produces the following exception:
```
[json.exception.out_of_range.401] array index 3 is out of range
```
## Notes
!!! failure "Exceptions"
- `at` can only be used with objects (with a string argument) or with arrays (with a numeric argument). For other types, a [`basic_json::type_error`](../../home/exceptions.md#jsonexceptiontype_error304) is thrown.
- [`basic_json::out_of_range` exception](../../home/exceptions.md#out-of-range) exceptions are thrown if the provided key is not found in an object or the provided index is invalid.
## Summary
| scenario | non-const value | const value |
|-----------------------------------|------------------------------------------------|------------------------------------------------|
| access to existing object key | reference to existing value is returned | const reference to existing value is returned |
| access to valid array index | reference to existing value is returned | const reference to existing value is returned |
| access to non-existing object key | `basic_json::out_of_range` exception is thrown | `basic_json::out_of_range` exception is thrown |
| access to invalid array index | `basic_json::out_of_range` exception is thrown | `basic_json::out_of_range` exception is thrown |

311
doc/mkdocs/docs/features/macros.md
View File

@ -1,311 +0,0 @@
# Supported Macros
Some aspects of the library can be configured by defining preprocessor macros before including the `json.hpp` header.
## `JSON_ASSERT(x)`
This macro controls which code is executed for runtime assertions of the libraries.
!!! info "Default behavior"
The default value is [`#!cpp assert(x)`](https://en.cppreference.com/w/cpp/error/assert).
```cpp
#define JSON_ASSERT(x) assert(x)
```
The macro was introduced in version 3.9.0.
## `JSON_CATCH_USER(exception)`
This macro overrides [`#!cpp catch`](https://en.cppreference.com/w/cpp/language/try_catch) calls inside the library.
The argument is the type of the exception to catch. As of version 3.8.0, the library only catches `std::out_of_range`
exceptions internally to rethrow them as [`json::out_of_range`](../home/exceptions.md#out-of-range) exceptions. The
macro is always followed by a scope.
See [Switch off exceptions](../home/exceptions.md#switch-off-exceptions) for an example.
!!! info "Default behavior"
When exceptions are enabled, the default value is
[`#!cpp catch(exception)`](https://en.cppreference.com/w/cpp/language/try_catch).
```cpp
#define JSON_CATCH_USER(exception) catch(exception)
```
When exceptions are switched off by the compiler, the default value is `#!cpp if (false)` to make the catch block
unreachable.
```cpp
#define JSON_CATCH_USER(exception) if (false)
```
The macro was introduced in version 3.1.0.
## `JSON_DIAGNOSTICS`
This macro enables extended diagnostics for exception messages. Possible values are `1` to enable or `0` to disable
(default).
When enabled, exception messages contain a [JSON Pointer](json_pointer.md) to the JSON value that triggered the
exception, see [Extended diagnostic messages](../home/exceptions.md#extended-diagnostic-messages) for an example. Note
that enabling this macro increases the size of every JSON value by one pointer and adds some runtime overhead.
The diagnostics messages can also be controlled with the CMake option `JSON_Diagnostics` (`OFF` by default) which sets
`JSON_DIAGNOSTICS` accordingly.
!!! warning
As this macro changes the definition of the `basic_json` object, it MUST be defined in the same way globally, even
across different compilation units; DO NOT link together code compiled with different definitions of
`JSON_DIAGNOSTICS` as this is a violation of the One Definition Rule and will cause undefined behaviour.
!!! info "Default behavior"
```cpp
#define JSON_DIAGNOSTICS 0
```
The macro was introduced in version 3.10.0.
## `JSON_HAS_CPP_11`, `JSON_HAS_CPP_14`, `JSON_HAS_CPP_17`, `JSON_HAS_CPP_20`
The library targets C++11, but also supports some features introduced in later C++ versions (e.g., `std::string_view`
support for C++17). For these new features, the library implements some preprocessor checks to determine the C++
standard. By defining any of these symbols, the internal check is overridden and the provided C++ version is
unconditionally assumed. This can be helpful for compilers that only implement parts of the standard and would be
detected incorrectly.
!!! info "Default behavior"
The default value is detected based on the preprocessor macros `#!cpp __cplusplus`, `#!cpp _HAS_CXX17`, or
`#!cpp _MSVC_LANG`.
The macros were introduced in version 3.10.5.
## `JSON_HAS_FILESYSTEM`, `JSON_HAS_EXPERIMENTAL_FILESYSTEM`
When compiling with C++17, the library provides conversions from and to `std::filesystem::path`. As compiler support
for filesystem is limited, the library tries to detect whether `<filesystem>`/`std::filesystem` (`JSON_HAS_FILESYSTEM`)
or `<experimental/filesystem>`/`std::experimental::filesystem` (`JSON_HAS_EXPERIMENTAL_FILESYSTEM`) should be used.
To override the built-in check, define `JSON_HAS_FILESYSTEM` or `JSON_HAS_EXPERIMENTAL_FILESYSTEM` to `1`.
!!! info "Default behavior"
The default value is detected based on the preprocessor macros `#!cpp __cpp_lib_filesystem`,
`#!cpp __cpp_lib_experimental_filesystem`, `#!cpp __has_include(<filesystem>)`, or
`#!cpp __has_include(<experimental/filesystem>)`.
Note that older compilers or older versions of libstd++ also require the library `stdc++fs` to be linked to for
filesystem support.
The macros were introduced in version 3.10.5.
## `JSON_NOEXCEPTION`
Exceptions can be switched off by defining the symbol `JSON_NOEXCEPTION`. When defining `JSON_NOEXCEPTION`, `#!cpp try`
is replaced by `#!cpp if (true)`, `#!cpp catch` is replaced by `#!cpp if (false)`, and `#!cpp throw` is replaced by
`#!cpp std::abort()`.
!!! info "Default behavior"
By default, the macro is not defined.
```cpp
#undef JSON_NOEXCEPTION
```
The same effect is achieved by setting the compiler flag `-fno-exceptions`.
Note the explanatory [`what()`](https://en.cppreference.com/w/cpp/error/exception/what) string of exceptions is not
available for MSVC if exceptions are disabled, see [#2824](https://github.com/nlohmann/json/discussions/2824).
The macro was introduced in version 2.1.0.
## `JSON_NO_IO`
When defined, headers `<cstdio>`, `<ios>`, `<iosfwd>`, `<istream>`, and `<ostream>` are not included and parse functions
relying on these headers are excluded. This is relevant for environment where these I/O functions are disallowed for
security reasons (e.g., Intel Software Guard Extensions (SGX)).
!!! info "Default behavior"
By default, the macro is not defined.
```cpp
#undef JSON_NO_IO
```
The macro was introduced in version 3.10.0.
## `JSON_SKIP_LIBRARY_VERSION_CHECK`
When defined, the library will not create a compiler warning when a different version of the library was already
included.
!!! info "Default behavior"
By default, the macro is not defined.
```cpp
#undef JSON_SKIP_LIBRARY_VERSION_CHECK
```
The macro was introduced in version 3.11.0.
## `JSON_SKIP_UNSUPPORTED_COMPILER_CHECK`
When defined, the library will not create a compile error when a known unsupported compiler is detected. This allows to
use the library with compilers that do not fully support C++11 and may only work if unsupported features are not used.
!!! info "Default behavior"
By default, the macro is not defined.
```cpp
#undef JSON_SKIP_UNSUPPORTED_COMPILER_CHECK
```
The macro was introduced in version 3.2.0.
## `JSON_THROW_USER(exception)`
This macro overrides `#!cpp throw` calls inside the library. The argument is the exception to be thrown. Note that
`JSON_THROW_USER` should leave the current scope (e.g., by throwing or aborting), as continuing after it may yield
undefined behavior.
!!! info "Default behavior"
When exceptions are enabled, the default value is
[`#!cpp throw exception`](https://en.cppreference.com/w/cpp/language/throw).
```cpp
#define JSON_THROW_USER(exception) throw exception
```
When exceptions are switched off by the compiler, the default value is
[`#!cpp std::abort()`](https://en.cppreference.com/w/cpp/utility/program/abort) to make reaching the throw branch
abort the process.
```cpp
#define JSON_THROW_USER(exception) std::abort()
```
See [Switch off exceptions](../home/exceptions.md#switch-off-exceptions) for an example.
The macro was introduced in version 3.1.0.
## `JSON_TRY_USER`
This macro overrides `#!cpp try` calls inside the library. It has no arguments and is always followed by a scope.
!!! info "Default behavior"
When exceptions are enabled, the default value is
[`#!cpp try`](https://en.cppreference.com/w/cpp/language/try_catch).
```cpp
#define JSON_TRY_USER try
```
When exceptions are switched off by the compiler, the default value is `#!cpp if (true)` to unconditionally execute
the following code block.
```cpp
#define JSON_TRY_USER if (true)
```
See [Switch off exceptions](../home/exceptions.md#switch-off-exceptions) for an example.
The macro was introduced in version 3.1.0.
## `JSON_USE_IMPLICIT_CONVERSIONS`
When defined to `0`, implicit conversions are switched off. By default, implicit conversions are switched on.
??? example
This is an example for an implicit conversion:
```cpp
json j = "Hello, world!";
std::string s = j;
```
When `JSON_USE_IMPLICIT_CONVERSIONS` is defined to `0`, the code above does no longer compile. Instead, it must be
written like this:
```cpp
json j = "Hello, world!";
auto s = j.get<std::string>();
```
Implicit conversions can also be controlled with the CMake option `JSON_ImplicitConversions` (`ON` by default) which
sets `JSON_USE_IMPLICIT_CONVERSIONS` accordingly.
!!! info "Default behavior"
```cpp
#define JSON_USE_IMPLICIT_CONVERSIONS 1
```
The macro was introduced in version 3.9.0.
## `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
serialization and (2) want to use the member variable names as object keys in that object.
The macro is to be defined inside the class/struct to create code for. Unlike
[`NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE`](#nlohmann_define_type_non_intrusivetype-member), it can access private members.
The first parameter is the name of the class/struct, and all remaining parameters name the members.
See [Simplify your life with macros](arbitrary_types.md#simplify-your-life-with-macros) for an example.
The macro was introduced in version 3.9.0.
## `NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT(type, member...)`
This macro is similar to `NLOHMANN_DEFINE_TYPE_INTRUSIVE`. It will not throw an exception in `from_json()` due to a
missing value in the JSON object, but can throw due to a mismatched type. In order to support that it requires that the
type be default constructible. The `from_json()` function default constructs an object and uses its values as the
defaults when calling the `value()` function.
The macro was introduced in version 3.11.0.
## `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(type, member...)`
This macro can be used to simplify the serialization/deserialization of types if (1) want to use a JSON object as
serialization and (2) want to use the member variable names as object keys in that object.
The macro is to be defined inside the namespace of the class/struct to create code for. Private members cannot be
accessed. Use [`NLOHMANN_DEFINE_TYPE_INTRUSIVE`](#nlohmann_define_type_intrusivetype-member) in these scenarios. The
first parameter is the name of the class/struct, and all remaining parameters name the members.
See [Simplify your life with macros](arbitrary_types.md#simplify-your-life-with-macros) for an example.
The macro was introduced in version 3.9.0.
## `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT(type, member...)`
This macro is similar to `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE`. It will not throw an exception in `from_json()` due to a
missing value in the JSON object, but can throw due to a mismatched type. In order to support that it requires that the
type be default constructible. The `from_json()` function default constructs an object and uses its values as the
defaults when calling the `value()` function.
The macro was introduced in version 3.11.0.
## `NLOHMANN_JSON_SERIALIZE_ENUM(type, ...)`
This macro simplifies the serialization/deserialization of enum types. See
[Specializing enum conversion](enum_conversion.md) for more information.
The macro was introduced in version 3.4.0.
## `NLOHMANN_JSON_VERSION_MAJOR`, `NLOHMANN_JSON_VERSION_MINOR`, `NLOHMANN_JSON_VERSION_PATCH`
These macros are defined by the library and contain the version numbers according to
[Semantic Versioning 2.0.0](https://semver.org).
The macros were introduced in version 3.1.0.

29
doc/mkdocs/requirements.txt
View File

@ -1,29 +0,0 @@
click>=7.1.2
future>=0.18.2
htmlmin>=0.1.12
httplib2>=0.18.1
importlib-metadata>=1.6.0
Jinja2>=2.11.2
joblib>=0.15.1
jsmin>=2.2.2
livereload>=2.6.1
lunr>=0.5.8
Markdown>=3.2.2
markdown-include>=0.5.1
MarkupSafe>=1.1.1
mkdocs>=1.1.2
mkdocs-material>=5.2.1
mkdocs-material-extensions>=1.0
mkdocs-minify-plugin>=0.3.0
mkdocs-simple-hooks>=0.1.1
nltk>=3.5
plantuml>=0.3.0
plantuml-markdown>=3.2.2
Pygments>=2.6.1
pymdown-extensions>=7.1
PyYAML>=5.3.1
regex>=2020.5.14
six>=1.15.0
tornado>=6.0.4
tqdm>=4.46.0
zipp>=3.1.0

121
doc/mkdocs/scripts/check_structure.py
View File

@ -1,121 +0,0 @@
#!/usr/bin/env python
import glob
import os.path
def check_structure():
expected_headers = [
'Template parameters',
'Specializations',
'Iterator invalidation',
'Requirements',
'Member types',
'Member functions',
'Member variables',
'Static functions',
'Non-member functions',
'Literals',
'Helper classes',
'Parameters',
'Return value',
'Exception safety',
'Exceptions',
'Complexity',
'Possible implementation',
'Notes',
'Examples',
'See also',
'Version history'
]
required_headers = [
'Examples',
'Version history'
]
files = sorted(glob.glob('api/**/*.md', recursive=True))
for file in files:
with open(file) as file_content:
header_idx = -1
existing_headers = []
in_initial_code_example = False
previous_line = None
h1sections = 0
for lineno, line in enumerate(file_content.readlines()):
line = line.strip()
if line.startswith('# '):
h1sections += 1
# there should only be one top-level title
if h1sections > 1:
print(f'{file}:{lineno+1}: Error: unexpected top-level title "{line}"!')
h1sections = 1
# Overview pages should have a better title
if line == '# Overview':
print(f'{file}:{lineno+1}: Error: overview pages should have a better title!')
# lines longer than 160 characters are bad (unless they are tables)
if len(line) > 160 and '|' not in line:
print(f'{file}:{lineno+1}: Error: line is too long ({len(line)} vs. 160 chars)!')
# check if headers are correct
if line.startswith('## '):
header = line.strip('## ')
existing_headers.append(header)
if header in expected_headers:
idx = expected_headers.index(header)
if idx <= header_idx:
print(f'{file}:{lineno+1}: Error: header "{header}" is in an unexpected order (should be before "{expected_headers[header_idx]}")!')
header_idx = idx
else:
print(f'{file}:{lineno+1}: Error: header "{header}" is not part of the expected headers!')
# code example
if line == '```cpp' and header_idx == -1:
in_initial_code_example = True
if in_initial_code_example and line.startswith('//'):
if any(map(str.isdigit, line)) and '(' not in line:
print(f'{file}:{lineno+1}: Number should be in parentheses: {line}')
if line == '```' and in_initial_code_example:
in_initial_code_example = False
# consecutive blank lines are bad
if line == '' and previous_line == '':
print(f'{file}:{lineno}-{lineno+1}: Error: Consecutive blank lines!')
previous_line = line
for required_header in required_headers:
if required_header not in existing_headers:
print(f'{file}:{lineno+1}: Error: required header "{required_header}" was not found!')
def check_examples():
example_files = sorted(glob.glob('../../examples/*.cpp'))
markdown_files = sorted(glob.glob('**/*.md', recursive=True))
# check if every example file is used in at least one markdown file
for example_file in example_files:
example_file = os.path.join('examples', os.path.basename(example_file))
found = False
for markdown_file in markdown_files:
content = ' '.join(open(markdown_file).readlines())
if example_file in content:
found = True
break
if not found:
print(f'{example_file}: Error: example file is not used in any documentation file!')
if __name__ == '__main__':
check_structure()
check_examples()

0
doc/Makefile → docs/Makefile
View File

2
doc/README.md → docs/README.md
View File

@ -13,7 +13,7 @@ If you want to see the documentation for a specific tag or commit hash, you can
git clone https://github.com/nlohmann/json.git
cd json
git checkout v3.10.2
make install_venv serve -C doc/mkdocs
make install_venv serve -C docs/mkdocs
```
Open URL <http://127.0.0.1:8000/> in your browser. Replace from any URL from the source code `https://json.nlohmann.me`

0
doc/avatars.png → docs/avatars.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 1.3 MiB

After

Width:  |  Height:  |  Size: 1.3 MiB

0
doc/docset/Info.plist → docs/docset/Info.plist
View File

0
doc/docset/Makefile → docs/docset/Makefile
View File

0
doc/docset/README.md → docs/docset/README.md
View File

1
doc/docset/docSet.sql → docs/docset/docSet.sql
View File

@ -140,6 +140,7 @@ INSERT INTO searchIndex(name, type, path) VALUES ('SAX Interface', 'Guide', 'fea
INSERT INTO searchIndex(name, type, path) VALUES ('JSON_ASSERT', 'Macro', 'features/macros/index.html#json_assertx');
INSERT INTO searchIndex(name, type, path) VALUES ('JSON_CATCH_USER', 'Macro', 'features/macros/index.html#json_catch_userexception');
INSERT INTO searchIndex(name, type, path) VALUES ('JSON_DIAGNOSTICS', 'Macro', 'features/macros/index.html#json_diagnostics');
INSERT INTO searchIndex(name, type, path) VALUES ('JSON_DISABLE_ENUM_SERIALIZATION', 'Macro', 'features/macros/index.html#json_disable_enum_serialization');
INSERT INTO searchIndex(name, type, path) VALUES ('JSON_HAS_CPP_11', 'Macro', 'features/macros/index.html#json_has_cpp_11-json_has_cpp_14-json_has_cpp_17-json_has_cpp_20');
INSERT INTO searchIndex(name, type, path) VALUES ('JSON_HAS_CPP_14', 'Macro', 'features/macros/index.html#json_has_cpp_11-json_has_cpp_14-json_has_cpp_17-json_has_cpp_20');
INSERT INTO searchIndex(name, type, path) VALUES ('JSON_HAS_CPP_17', 'Macro', 'features/macros/index.html#json_has_cpp_11-json_has_cpp_14-json_has_cpp_17-json_has_cpp_20');

0
doc/docset/docset.json → docs/docset/docset.json
View File

0
doc/docset/icon.png → docs/docset/icon.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 700 B

After

Width:  |  Height:  |  Size: 700 B

0
doc/docset/icon@2x.png → docs/docset/icon@2x.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 1.3 KiB

After

Width:  |  Height:  |  Size: 1.3 KiB

0
doc/examples/README.cpp → docs/examples/README.cpp
View File

0
doc/examples/README.output → docs/examples/README.output
View File

0
doc/examples/accept__string.cpp → docs/examples/accept__string.cpp
View File

0
doc/examples/accept__string.output → docs/examples/accept__string.output
View File

0
doc/examples/array.cpp → docs/examples/array.cpp
View File

0
doc/examples/array.output → docs/examples/array.output
View File

0
doc/examples/array_t.cpp → docs/examples/array_t.cpp
View File

0
doc/examples/array_t.output → docs/examples/array_t.output
View File

0
doc/examples/at__object_t_key_type.cpp → docs/examples/at__object_t_key_type.cpp
View File

0
doc/examples/at__object_t_key_type.output → docs/examples/at__object_t_key_type.output
View File

0
doc/examples/at__object_t_key_type_const.cpp → docs/examples/at__object_t_key_type_const.cpp
View File

0
doc/examples/at__object_t_key_type_const.output → docs/examples/at__object_t_key_type_const.output
View File

0
doc/examples/at__size_type.cpp → docs/examples/at__size_type.cpp
View File

0
doc/examples/at__size_type.output → docs/examples/at__size_type.output
View File

0
doc/examples/at__size_type_const.cpp → docs/examples/at__size_type_const.cpp
View File

0
doc/examples/at__size_type_const.output → docs/examples/at__size_type_const.output
View File

0
doc/examples/at_json_pointer.cpp → docs/examples/at_json_pointer.cpp
View File

0
doc/examples/at_json_pointer.output → docs/examples/at_json_pointer.output
View File

0
doc/examples/at_json_pointer_const.cpp → docs/examples/at_json_pointer_const.cpp
View File

0
doc/examples/at_json_pointer_const.output → docs/examples/at_json_pointer_const.output
View File

0
doc/examples/back.cpp → docs/examples/back.cpp
View File

0
doc/examples/back.output → docs/examples/back.output
View File

0
doc/examples/basic_json__CompatibleType.cpp → docs/examples/basic_json__CompatibleType.cpp
View File

0
doc/examples/basic_json__CompatibleType.output → docs/examples/basic_json__CompatibleType.output
View File

0
doc/examples/basic_json__InputIt_InputIt.cpp → docs/examples/basic_json__InputIt_InputIt.cpp
View File

0
doc/examples/basic_json__InputIt_InputIt.output → docs/examples/basic_json__InputIt_InputIt.output
View File

0
doc/examples/basic_json__basic_json.cpp → docs/examples/basic_json__basic_json.cpp
View File

0
doc/examples/basic_json__basic_json.output → docs/examples/basic_json__basic_json.output
View File

0
doc/examples/basic_json__copyassignment.cpp → docs/examples/basic_json__copyassignment.cpp
View File

0
doc/examples/basic_json__copyassignment.output → docs/examples/basic_json__copyassignment.output
View File

0
doc/examples/basic_json__list_init_t.cpp → docs/examples/basic_json__list_init_t.cpp
View File

0
doc/examples/basic_json__list_init_t.output → docs/examples/basic_json__list_init_t.output
View File

0
doc/examples/basic_json__moveconstructor.cpp → docs/examples/basic_json__moveconstructor.cpp
View File

0
doc/examples/basic_json__moveconstructor.output → docs/examples/basic_json__moveconstructor.output
View File

0
doc/examples/basic_json__nullptr_t.cpp → docs/examples/basic_json__nullptr_t.cpp
View File

0
doc/examples/basic_json__nullptr_t.output → docs/examples/basic_json__nullptr_t.output
View File

0
doc/examples/basic_json__size_type_basic_json.cpp → docs/examples/basic_json__size_type_basic_json.cpp
View File

0
doc/examples/basic_json__size_type_basic_json.output → docs/examples/basic_json__size_type_basic_json.output
View File

0
doc/examples/basic_json__value.cpp → docs/examples/basic_json__value.cpp
View File

0
doc/examples/basic_json__value.output → docs/examples/basic_json__value.output
View File

0
doc/examples/basic_json__value_ptr.cpp → docs/examples/basic_json__value_ptr.cpp
View File

0
doc/examples/basic_json__value_ptr.output → docs/examples/basic_json__value_ptr.output
View File

0
doc/examples/basic_json__value_t.cpp → docs/examples/basic_json__value_t.cpp
View File

0
doc/examples/basic_json__value_t.output → docs/examples/basic_json__value_t.output
View File

0
doc/examples/begin.cpp → docs/examples/begin.cpp
View File

0
doc/examples/begin.output → docs/examples/begin.output
View File

0
doc/examples/binary.cpp → docs/examples/binary.cpp
View File

0
doc/examples/binary.output → docs/examples/binary.output
View File

0
doc/examples/binary_t.cpp → docs/examples/binary_t.cpp
View File

0
doc/examples/binary_t.output → docs/examples/binary_t.output
View File

0
doc/examples/boolean_t.cpp → docs/examples/boolean_t.cpp
View File

0
doc/examples/boolean_t.output → docs/examples/boolean_t.output
View File

23
docs/examples/byte_container_with_subtype__byte_container_with_subtype.cpp Normal file
View File

@ -0,0 +1,23 @@
#include <iostream>
#include <nlohmann/json.hpp>
// define a byte container based on std::vector
using byte_container_with_subtype = nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>;
using json = nlohmann::json;
int main()
{
// (1) create empty container
auto c1 = byte_container_with_subtype();
std::vector<std::uint8_t> bytes = {{0xca, 0xfe, 0xba, 0xbe}};
// (2) create container
auto c2 = byte_container_with_subtype(bytes);
// (3) create container with subtype
auto c3 = byte_container_with_subtype(bytes, 42);
std::cout << json(c1) << "\n" << json(c2) << "\n" << json(c3) << std::endl;
}

Some files were not shown because too many files have changed in this diff Show More