Merge branch 'release/3.10.5'
diff --git a/.clang-tidy b/.clang-tidy
index 33cf848..30886d7 100644
--- a/.clang-tidy
+++ b/.clang-tidy
@@ -1,6 +1,9 @@
Checks: '*,
+ -altera-id-dependent-backward-branch,
-altera-struct-pack-align,
+ -altera-unroll-loops,
-android-cloexec-fopen,
+ -bugprone-easily-swappable-parameters,
-concurrency-mt-unsafe,
-cppcoreguidelines-avoid-goto,
-cppcoreguidelines-avoid-magic-numbers,
@@ -11,6 +14,7 @@
-cppcoreguidelines-pro-bounds-pointer-arithmetic,
-cppcoreguidelines-pro-type-reinterpret-cast,
-cppcoreguidelines-pro-type-union-access,
+ -cppcoreguidelines-virtual-class-destructor,
-fuchsia-default-arguments-calls,
-fuchsia-default-arguments-declarations,
-fuchsia-overloaded-operator,
@@ -30,9 +34,12 @@
-llvmlibc-*,
-misc-no-recursion,
-misc-non-private-member-variables-in-classes,
+ -modernize-concat-nested-namespaces,
+ -modernize-use-nodiscard,
-modernize-use-trailing-return-type,
- -readability-function-size,
-readability-function-cognitive-complexity,
+ -readability-function-size,
+ -readability-identifier-length,
-readability-magic-numbers,
-readability-redundant-access-specifiers,
-readability-uppercase-literal-suffix'
diff --git a/.github/ISSUE_TEMPLATE/Bug_report.md b/.github/ISSUE_TEMPLATE/Bug_report.md
index 2b592ee..d0fbbdd 100644
--- a/.github/ISSUE_TEMPLATE/Bug_report.md
+++ b/.github/ISSUE_TEMPLATE/Bug_report.md
@@ -47,7 +47,7 @@
<!-- Please add an `x` to the respective line. -->
-- [ ] latest release version 3.10.4
+- [ ] latest release version 3.10.5
- [ ] other release - please state the version: ___
- [ ] the `develop` branch
diff --git a/.github/workflows/ubuntu.yml b/.github/workflows/ubuntu.yml
index ea9edc9..eb54400 100644
--- a/.github/workflows/ubuntu.yml
+++ b/.github/workflows/ubuntu.yml
@@ -11,7 +11,7 @@
jobs:
ci_test_clang:
runs-on: ubuntu-latest
- container: ghcr.io/nlohmann/json-ci:v1.0.0
+ container: ghcr.io/nlohmann/json-ci:v2.2.0
steps:
- uses: actions/checkout@v2
- name: cmake
@@ -21,7 +21,7 @@
ci_test_gcc:
runs-on: ubuntu-latest
- container: ghcr.io/nlohmann/json-ci:v1.0.0
+ container: ghcr.io/nlohmann/json-ci:v2.2.0
steps:
- uses: actions/checkout@v2
- name: cmake
@@ -31,7 +31,7 @@
ci_static_analysis:
runs-on: ubuntu-latest
- container: ghcr.io/nlohmann/json-ci:v1.0.0
+ container: ghcr.io/nlohmann/json-ci:v2.2.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]
@@ -44,7 +44,7 @@
ci_cmake_options:
runs-on: ubuntu-latest
- container: ghcr.io/nlohmann/json-ci:v1.0.0
+ container: ghcr.io/nlohmann/json-ci:v2.2.0
strategy:
matrix:
target: [ci_test_diagnostics, ci_test_noexceptions, ci_test_noimplicitconversions]
@@ -57,7 +57,7 @@
ci_test_coverage:
runs-on: ubuntu-latest
- container: ghcr.io/nlohmann/json-ci:v1.0.0
+ container: ghcr.io/nlohmann/json-ci:v2.2.0
steps:
- uses: actions/checkout@v2
- name: cmake
@@ -77,10 +77,10 @@
ci_test_compilers:
runs-on: ubuntu-latest
- container: ghcr.io/nlohmann/json-ci:v1.0.0
+ container: ghcr.io/nlohmann/json-ci:v2.2.0
strategy:
matrix:
- compiler: [g++-4.8, g++-4.9, g++-5, 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]
+ 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]
steps:
- uses: actions/checkout@v2
- name: cmake
@@ -90,7 +90,7 @@
ci_test_standards:
runs-on: ubuntu-latest
- container: ghcr.io/nlohmann/json-ci:v1.0.0
+ container: ghcr.io/nlohmann/json-ci:v2.2.0
strategy:
matrix:
standard: [11, 14, 17, 20]
@@ -101,3 +101,13 @@
run: cmake -S . -B build -DJSON_CI=On
- name: build
run: cmake --build build --target ci_test_${{ matrix.compiler }}_cxx${{ matrix.standard }}
+
+ ci_cuda_example:
+ 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: cmake --build build --target ci_cuda_example
diff --git a/.gitignore b/.gitignore
index a465207..a13ad89 100644
--- a/.gitignore
+++ b/.gitignore
@@ -25,7 +25,6 @@
doc/html
doc/mkdocs/venv/
-doc/mkdocs/docs/images
doc/mkdocs/docs/examples
doc/mkdocs/site
doc/mkdocs/docs/__pycache__/
diff --git a/.travis.yml b/.travis.yml
deleted file mode 100644
index e20b446..0000000
--- a/.travis.yml
+++ /dev/null
@@ -1,94 +0,0 @@
-#########################
-# project configuration #
-#########################
-
-# C++ project
-language: cpp
-
-dist: trusty
-sudo: required
-group: edge
-
-
-################
-# build matrix #
-################
-
-matrix:
- include:
-
- # Coverity (only for branch coverity_scan)
-
- - os: linux
- compiler: clang
- before_install: echo -n | openssl s_client -connect scan.coverity.com:443 | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' | sudo tee -a /etc/ssl/certs/ca-certificates.crt
- addons:
- apt:
- sources: ['ubuntu-toolchain-r-test', 'llvm-toolchain-precise-3.6']
- packages: ['g++-6', 'clang-3.6', 'ninja-build']
- coverity_scan:
- project:
- name: "nlohmann/json"
- description: "Build submitted via Travis CI"
- notification_email: niels.lohmann@gmail.com
- build_command_prepend: "mkdir coverity_build ; cd coverity_build ; cmake .. ; cd .."
- build_command: "make -C coverity_build"
- branch_pattern: coverity_scan
- env:
- - SPECIAL=coverity
- - COMPILER=clang++-3.6
- # The next declaration is the encrypted COVERITY_SCAN_TOKEN, created
- # via the "travis encrypt" command using the project repo's public key
- - secure: "m89SSgE+ASLO38rSKx7MTXK3n5NkP9bIx95jwY71YEiuFzib30PDJ/DifKnXxBjvy/AkCGztErQRk/8ZCvq+4HXozU2knEGnL/RUitvlwbhzfh2D4lmS3BvWBGS3N3NewoPBrRmdcvnT0xjOGXxtZaJ3P74TkB9GBnlz/HmKORA="
-
- # OSX / Clang
-
- - os: osx
- osx_image: xcode10.2
-
- # Linux / GCC
-
- - os: linux
- compiler: gcc
- env: COMPILER=g++-6
- addons:
- apt:
- sources: ['ubuntu-toolchain-r-test']
- packages: ['g++-6', 'ninja-build']
-
-################
-# build script #
-################
-
-script:
- # get CMake and Ninja (only for systems with brew - macOS)
- - |
- if [[ (-x $(which brew)) ]]; then
- brew update
- brew install cmake ninja
- brew upgrade cmake
- cmake --version
- fi
-
- # make sure CXX is correctly set
- - if [[ "${COMPILER}" != "" ]]; then export CXX=${COMPILER}; fi
-
- # append CXX_STANDARD to CMAKE_OPTIONS if required
- - CMAKE_OPTIONS+=${CXX_STANDARD:+ -DCMAKE_CXX_STANDARD=$CXX_STANDARD -DCMAKE_CXX_STANDARD_REQUIRED=ON}
-
- # build configuration
- - CMAKE_OPTIONS+=" -DCMAKE_BUILD_TYPE=Release"
-
- # compile and execute unit tests
- - mkdir -p build && cd build
- - cmake .. ${CMAKE_OPTIONS} -DJSON_BuildTests=On -GNinja && cmake --build .
- - ctest --timeout 2700 -V -j
- - cd ..
-
- # check if homebrew works (only checks develop branch)
- - if [ `which brew` ]; then
- brew update ;
- brew tap nlohmann/json ;
- brew install nlohmann_json --HEAD ;
- brew test nlohmann_json ;
- fi
diff --git a/CITATION.cff b/CITATION.cff
index 37dbed4..7c28d04 100644
--- a/CITATION.cff
+++ b/CITATION.cff
@@ -7,8 +7,8 @@
email: mail@nlohmann.me
website: https://nlohmann.me
title: "JSON for Modern C++"
-version: 3.10.4
-date-released: 2021
+version: 3.10.5
+date-released: 2022
license: MIT
repository-code: "https://github.com/nlohmann"
url: https://json.nlohmann.me
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 53bb06e..b93c6e4 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -4,7 +4,7 @@
## PROJECT
## name and version
##
-project(nlohmann_json VERSION 3.10.4 LANGUAGES CXX)
+project(nlohmann_json VERSION 3.10.5 LANGUAGES CXX)
##
## MAIN_PROJECT CHECK
diff --git a/ChangeLog.md b/ChangeLog.md
index 92df982..9a92b9f 100644
--- a/ChangeLog.md
+++ b/ChangeLog.md
@@ -1,22 +1,55 @@
# Changelog
All notable changes to this project will be documented in this file. This project adheres to [Semantic Versioning](http://semver.org/).
-## [3.10.4](https://github.com/nlohmann/json/releases/tag/3.10.4) (2021-10-16)
+## [3.10.5](https://github.com/nlohmann/json/releases/tag/3.10.5) (2022-01-02)
-[Full Changelog](https://github.com/nlohmann/json/compare/v3.10.3...3.10.4)
+[Full Changelog](https://github.com/nlohmann/json/compare/v3.10.4...3.10.5)
-- Compiler error in output serializer due to 'incompatible initializer' [\#3081](https://github.com/nlohmann/json/issues/3081)
-- Strange behaviour when using std::sort on std::vector\<json\> [\#3080](https://github.com/nlohmann/json/issues/3080)
-- Unhandled exception: nlohmann::detail::parse\_error [\#3078](https://github.com/nlohmann/json/issues/3078)
-- explicit constructor with default does not compile [\#3077](https://github.com/nlohmann/json/issues/3077)
-- Parse an object but get an array using GCC [\#3076](https://github.com/nlohmann/json/issues/3076)
-- Version 3.10.3 breaks backward-compatibility with 3.10.2 [\#3070](https://github.com/nlohmann/json/issues/3070)
-- Feature request, Add to\_json/from\_json to align with other to/from binary api. [\#3067](https://github.com/nlohmann/json/issues/3067)
-- vcpkg is out of date [\#3066](https://github.com/nlohmann/json/issues/3066)
+- \#include \<filesystem\> doesn't work with gcc-7 when `-std=c++17` is specified. [\#3203](https://github.com/nlohmann/json/issues/3203)
+- Not able to use nlohmann json with c++ code built using emscripten to wasm [\#3200](https://github.com/nlohmann/json/issues/3200)
+- Warning for shadowed variables [\#3188](https://github.com/nlohmann/json/issues/3188)
+- Accessing missing keys on const json object leads to assert [\#3183](https://github.com/nlohmann/json/issues/3183)
+- Data member is available, but null is reported, and program throws error [\#3173](https://github.com/nlohmann/json/issues/3173)
+- serialization problem, from\_json need construct new object [\#3169](https://github.com/nlohmann/json/issues/3169)
+- std::filesystem unavailable on macOS lower deployment targets [\#3156](https://github.com/nlohmann/json/issues/3156)
+- \[json.exception.type\_error.305\] cannot use operator\[\] with a string argument with string [\#3151](https://github.com/nlohmann/json/issues/3151)
+- json::dump\(\) is not compatible with C++ standards [\#3147](https://github.com/nlohmann/json/issues/3147)
+- Issue with json::parse decoding codepoints [\#3142](https://github.com/nlohmann/json/issues/3142)
+- Simple parse of json object thinks it should be an array [\#3136](https://github.com/nlohmann/json/issues/3136)
+- How to properly read a Json string that may be null in some cases? [\#3135](https://github.com/nlohmann/json/issues/3135)
+- Deadlock on create json - windows only [\#3129](https://github.com/nlohmann/json/issues/3129)
+- Wrong parsing of int64 values nearest of limit [\#3126](https://github.com/nlohmann/json/issues/3126)
+- ordered\_json doesn't support range based erase [\#3108](https://github.com/nlohmann/json/issues/3108)
+- Apple build failed with json/single\_include/nlohmann/json.hpp:4384:57: 'path' is unavailable [\#3097](https://github.com/nlohmann/json/issues/3097)
+- GCC 7.5.0 with --std=c++17: filesystem: No such file or directory [\#3090](https://github.com/nlohmann/json/issues/3090)
+- Drop Travis CI [\#3087](https://github.com/nlohmann/json/issues/3087)
+- ordered\_json::reset\(\) compile error with nvcc [\#3013](https://github.com/nlohmann/json/issues/3013)
+- Support for unordered\_map as object\_t [\#2932](https://github.com/nlohmann/json/issues/2932)
+- Compiler warning with Intel compiler, same as \#755 [\#2712](https://github.com/nlohmann/json/issues/2712)
+- Compiler warnings with NVCC 11.2 [\#2676](https://github.com/nlohmann/json/issues/2676)
+- some static analysis warning at line 11317 [\#1390](https://github.com/nlohmann/json/issues/1390)
+- Compiling with icpc [\#755](https://github.com/nlohmann/json/issues/755)
+- Fix compilation error with NVCC [\#3234](https://github.com/nlohmann/json/pull/3234) ([nlohmann](https://github.com/nlohmann))
+- Remove Travis CI [\#3233](https://github.com/nlohmann/json/pull/3233) ([nlohmann](https://github.com/nlohmann))
+- Add build step for NVCC and fix a warning [\#3227](https://github.com/nlohmann/json/pull/3227) ([nlohmann](https://github.com/nlohmann))
+- Update cpplint [\#3225](https://github.com/nlohmann/json/pull/3225) ([nlohmann](https://github.com/nlohmann))
+- Fix: Warning for shadowed variables \(\#3188\) [\#3193](https://github.com/nlohmann/json/pull/3193) ([kernie](https://github.com/kernie))
+- Fix FAQ hyperlink typo in readme [\#3148](https://github.com/nlohmann/json/pull/3148) ([Prince-Mendiratta](https://github.com/Prince-Mendiratta))
+- Docs: Update `skip_comments` to `ignore_comments` [\#3145](https://github.com/nlohmann/json/pull/3145) ([daniel-kun](https://github.com/daniel-kun))
+- fix typos in documentation [\#3140](https://github.com/nlohmann/json/pull/3140) ([striezel](https://github.com/striezel))
+- Fix spelling [\#3125](https://github.com/nlohmann/json/pull/3125) ([axic](https://github.com/axic))
+- Extend std specializations [\#3121](https://github.com/nlohmann/json/pull/3121) ([nlohmann](https://github.com/nlohmann))
+- Add missing erase\(first, last\) function to ordered\_map [\#3109](https://github.com/nlohmann/json/pull/3109) ([nlohmann](https://github.com/nlohmann))
+- Fix typos in operator\[\] documentation [\#3102](https://github.com/nlohmann/json/pull/3102) ([axnsan12](https://github.com/axnsan12))
+- Add C++17 copies of the test binaries [\#3101](https://github.com/nlohmann/json/pull/3101) ([nlohmann](https://github.com/nlohmann))
+- Add examples for parsing from iterator pair [\#3100](https://github.com/nlohmann/json/pull/3100) ([nlohmann](https://github.com/nlohmann))
+- Update CI [\#3088](https://github.com/nlohmann/json/pull/3088) ([nlohmann](https://github.com/nlohmann))
- Revert invalid fix [\#3082](https://github.com/nlohmann/json/pull/3082) ([nlohmann](https://github.com/nlohmann))
- Allow to use get with explicit constructor [\#3079](https://github.com/nlohmann/json/pull/3079) ([nlohmann](https://github.com/nlohmann))
- fix std::filesystem::path regression [\#3073](https://github.com/nlohmann/json/pull/3073) ([theodelrieu](https://github.com/theodelrieu))
+- Consolidate documentation [\#3071](https://github.com/nlohmann/json/pull/3071) ([nlohmann](https://github.com/nlohmann))
+- Add recursive update function [\#3069](https://github.com/nlohmann/json/pull/3069) ([nlohmann](https://github.com/nlohmann))
- Fix Clang version [\#3040](https://github.com/nlohmann/json/pull/3040) ([nlohmann](https://github.com/nlohmann))
- Fix assertion failure for JSON\_DIAGNOSTICS [\#3037](https://github.com/nlohmann/json/pull/3037) ([carlsmedstad](https://github.com/carlsmedstad))
- meta: fix is\_compatible/constructible traits [\#3020](https://github.com/nlohmann/json/pull/3020) ([theodelrieu](https://github.com/theodelrieu))
@@ -27,6 +60,19 @@
- Fix -Wunused warnings on JSON\_DIAGNOSTICS [\#2976](https://github.com/nlohmann/json/pull/2976) ([gcerretani](https://github.com/gcerretani))
- Update docset generation script [\#2967](https://github.com/nlohmann/json/pull/2967) ([nlohmann](https://github.com/nlohmann))
+## [v3.10.4](https://github.com/nlohmann/json/releases/tag/v3.10.4) (2021-10-16)
+
+[Full Changelog](https://github.com/nlohmann/json/compare/v3.10.3...v3.10.4)
+
+- Compiler error in output serializer due to 'incompatible initializer' [\#3081](https://github.com/nlohmann/json/issues/3081)
+- Strange behaviour when using std::sort on std::vector\<json\> [\#3080](https://github.com/nlohmann/json/issues/3080)
+- Unhandled exception: nlohmann::detail::parse\_error [\#3078](https://github.com/nlohmann/json/issues/3078)
+- explicit constructor with default does not compile [\#3077](https://github.com/nlohmann/json/issues/3077)
+- Parse an object but get an array using GCC [\#3076](https://github.com/nlohmann/json/issues/3076)
+- Version 3.10.3 breaks backward-compatibility with 3.10.2 [\#3070](https://github.com/nlohmann/json/issues/3070)
+- Feature request, Add to\_json/from\_json to align with other to/from binary api. [\#3067](https://github.com/nlohmann/json/issues/3067)
+- vcpkg is out of date [\#3066](https://github.com/nlohmann/json/issues/3066)
+
## [v3.10.3](https://github.com/nlohmann/json/releases/tag/v3.10.3) (2021-10-08)
[Full Changelog](https://github.com/nlohmann/json/compare/v3.10.2...v3.10.3)
@@ -768,7 +814,7 @@
- catch exceptions for json\_pointer : ..../+99 [\#1990](https://github.com/nlohmann/json/pull/1990) ([dota17](https://github.com/dota17))
- Modify the document about operator== [\#1984](https://github.com/nlohmann/json/pull/1984) ([dota17](https://github.com/dota17))
- Rename argument array\_index to array\_indx in json\_pointer methods [\#1980](https://github.com/nlohmann/json/pull/1980) ([linev](https://github.com/linev))
-- README: Fix string representation of `dump`ed `json` [\#1979](https://github.com/nlohmann/json/pull/1979) ([alex-weej](https://github.com/alex-weej))
+- README: Fix string representation of `dump`ed `json` [\#1979](https://github.com/nlohmann/json/pull/1979) ([alexweej](https://github.com/alexweej))
- fix warnings in serializer.hpp for VS2019 [\#1969](https://github.com/nlohmann/json/pull/1969) ([dota17](https://github.com/dota17))
- Fix C26451 warnnings in to\_chars.hpp [\#1967](https://github.com/nlohmann/json/pull/1967) ([dota17](https://github.com/dota17))
- appveyor.yml: Compile and test with latest version for \_\_cplusplus ma… [\#1958](https://github.com/nlohmann/json/pull/1958) ([t-b](https://github.com/t-b))
@@ -1224,7 +1270,6 @@
- Copyconstructor inserts original into array with single element [\#1397](https://github.com/nlohmann/json/issues/1397)
- Get value without explicit typecasting [\#1395](https://github.com/nlohmann/json/issues/1395)
- Big file parsing [\#1393](https://github.com/nlohmann/json/issues/1393)
-- some static analysis warning at line 11317 [\#1390](https://github.com/nlohmann/json/issues/1390)
- Adding Structured Binding Support [\#1388](https://github.com/nlohmann/json/issues/1388)
- map\<json::value\_t, string\> exhibits unexpected behavior [\#1387](https://github.com/nlohmann/json/issues/1387)
- Error Code Return [\#1386](https://github.com/nlohmann/json/issues/1386)
@@ -1812,7 +1857,7 @@
- UTF8 encoding enhancement [\#534](https://github.com/nlohmann/json/pull/534) ([TedLyngmo](https://github.com/TedLyngmo))
- Fix typo [\#530](https://github.com/nlohmann/json/pull/530) ([berkus](https://github.com/berkus))
- Make exception base class visible in basic\_json [\#526](https://github.com/nlohmann/json/pull/526) ([krzysztofwos](https://github.com/krzysztofwos))
-- :art: Namespace `uint8_t` from the C++ stdlib [\#510](https://github.com/nlohmann/json/pull/510) ([alex-weej](https://github.com/alex-weej))
+- :art: Namespace `uint8_t` from the C++ stdlib [\#510](https://github.com/nlohmann/json/pull/510) ([alexweej](https://github.com/alexweej))
- add to\_json method for C arrays [\#508](https://github.com/nlohmann/json/pull/508) ([theodelrieu](https://github.com/theodelrieu))
- Fix -Weffc++ warnings \(GNU 6.3.1\) [\#496](https://github.com/nlohmann/json/pull/496) ([TedLyngmo](https://github.com/TedLyngmo))
@@ -1901,7 +1946,6 @@
- Compilation error with unordered\_map\< int, int \> [\#758](https://github.com/nlohmann/json/issues/758)
- CBOR string [\#757](https://github.com/nlohmann/json/issues/757)
- Proposal: out\_of\_range should be a subclass of std::out\_of\_range [\#756](https://github.com/nlohmann/json/issues/756)
-- Compiling with icpc [\#755](https://github.com/nlohmann/json/issues/755)
- Getter is setting the value to null if the key does not exist [\#754](https://github.com/nlohmann/json/issues/754)
- parsing works sometimes and crashes others [\#752](https://github.com/nlohmann/json/issues/752)
- Static\_assert failed "incompatible pointer type" with Xcode [\#751](https://github.com/nlohmann/json/issues/751)
diff --git a/LICENSE.MIT b/LICENSE.MIT
index f0622d6..1c1f7a6 100644
--- a/LICENSE.MIT
+++ b/LICENSE.MIT
@@ -1,6 +1,6 @@
MIT License
-Copyright (c) 2013-2021 Niels Lohmann
+Copyright (c) 2013-2022 Niels Lohmann
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/README.md b/README.md
index cb43b4f..3132963 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,5 @@
[](https://github.com/nlohmann/json/releases)
-[](https://app.travis-ci.com/nlohmann/json)
[](https://ci.appveyor.com/project/nlohmann/json)
[](https://github.com/nlohmann/json/actions?query=workflow%3AUbuntu)
[](https://github.com/nlohmann/json/actions?query=workflow%3AmacOS)
@@ -22,7 +21,7 @@
- [Design goals](#design-goals)
- [Sponsors](#sponsors)
-- [Support](#support) ([documentation](https://json.nlohmann.me), [FAQ](http://127.0.0.1:8000/home/faq/), [discussions](https://github.com/nlohmann/json/discussions), [API](https://json.nlohmann.me/api/basic_json/), [bug issues](https://github.com/nlohmann/json/issues))
+- [Support](#support) ([documentation](https://json.nlohmann.me), [FAQ](https://json.nlohmann.me/home/faq/), [discussions](https://github.com/nlohmann/json/discussions), [API](https://json.nlohmann.me/api/basic_json/), [bug issues](https://github.com/nlohmann/json/issues))
- [Examples](#examples)
- [JSON as first-class data type](#json-as-first-class-data-type)
- [Serialization / Deserialization](#serialization--deserialization)
@@ -88,7 +87,7 @@
:construction: If you want to understand the **API** better, check out the [**API Reference**](https://json.nlohmann.me/api/basic_json/) or the [**Doxygen documentation**](https://json.nlohmann.me/doxygen/index.html).
-:bug: If you found a **bug**, please check the [**FAQ**](https://json.nlohmann.me/home/faq/) if it is a known issue or the result of a design decision. Please also have a look at the [**issue list**](https://github.com/nlohmann/json/issues) before you [**create a new issue**](https://github.com/nlohmann/json/issues/new/choose). Please provide as many information as possible to help us understand and reproduce your issue.
+:bug: If you found a **bug**, please check the [**FAQ**](https://json.nlohmann.me/home/faq/) if it is a known issue or the result of a design decision. Please also have a look at the [**issue list**](https://github.com/nlohmann/json/issues) before you [**create a new issue**](https://github.com/nlohmann/json/issues/new/choose). Please provide as much information as possible to help us understand and reproduce your issue.
There is also a [**docset**](https://github.com/Kapeli/Dash-User-Contributions/tree/master/docsets/JSON_for_Modern_C%2B%2B) for the documentation browsers [Dash](https://kapeli.com/dash), [Velocity](https://velocity.silverlakesoftware.com), and [Zeal](https://zealdocs.org) that contains the full [documentation](https://json.nlohmann.me) as offline resource.
@@ -228,7 +227,7 @@
// retrieve the string value
auto cpp_string = j_string.get<std::string>();
-// retrieve the string value (alternative when an variable already exists)
+// retrieve the string value (alternative when a variable already exists)
std::string cpp_string2;
j_string.get_to(cpp_string2);
@@ -537,7 +536,7 @@
### JSON Pointer and JSON Patch
-The library supports **JSON Pointer** ([RFC 6901](https://tools.ietf.org/html/rfc6901)) as alternative means to address structured values. On top of this, **JSON Patch** ([RFC 6902](https://tools.ietf.org/html/rfc6902)) allows to describe differences between two JSON values - effectively allowing patch and diff operations known from Unix.
+The library supports **JSON Pointer** ([RFC 6901](https://tools.ietf.org/html/rfc6901)) as alternative means to address structured values. On top of this, **JSON Patch** ([RFC 6902](https://tools.ietf.org/html/rfc6902)) allows describing differences between two JSON values - effectively allowing patch and diff operations known from Unix.
```cpp
// a JSON value
@@ -740,8 +739,8 @@
There are two macros to make your life easier as long as you (1) want to use a JSON object as serialization and (2) want to use the member variable names as object keys in that object:
-- `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(name, member1, member2, ...)` is to be defined inside of the namespace of the class/struct to create code for.
-- `NLOHMANN_DEFINE_TYPE_INTRUSIVE(name, member1, member2, ...)` is to be defined inside of the class/struct to create code for. This macro can also access private members.
+- `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(name, member1, member2, ...)` is to be defined inside the namespace of the class/struct to create code for.
+- `NLOHMANN_DEFINE_TYPE_INTRUSIVE(name, member1, member2, ...)` is to be defined inside the class/struct to create code for. This macro can also access private members.
In both macros, the first parameter is the name of the class/struct, and all remaining parameters name the members.
@@ -846,7 +845,7 @@
return {j.get<int>()};
}
- // Here's the catch! You must provide a to_json method! Otherwise you
+ // Here's the catch! You must provide a to_json method! Otherwise, you
// will not be able to convert move_only_type to json, since you fully
// specialized adl_serializer on that type
static void to_json(json& j, move_only_type t) {
@@ -955,7 +954,7 @@
```
Just as in [Arbitrary Type Conversions](#arbitrary-types-conversions) above,
-- `NLOHMANN_JSON_SERIALIZE_ENUM()` MUST be declared in your enum type's namespace (which can be the global namespace), or the library will not be able to locate it and it will default to integer serialization.
+- `NLOHMANN_JSON_SERIALIZE_ENUM()` MUST be declared in your enum type's namespace (which can be the global namespace), or the library will not be able to locate it, and it will default to integer serialization.
- It MUST be available (e.g., proper headers must be included) everywhere you use the conversions.
Other Important points:
@@ -964,7 +963,7 @@
### Binary formats (BSON, CBOR, MessagePack, and UBJSON)
-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), and [UBJSON](https://ubjson.org) (Universal Binary JSON Specification) to efficiently encode JSON values to byte vectors and to decode such vectors.
```cpp
// create a JSON value
@@ -1003,7 +1002,7 @@
json j_from_ubjson = json::from_ubjson(v_ubjson);
```
-The library also supports binary types from BSON, CBOR (byte strings), and MessagePack (bin, ext, fixext). They are stored by default as `std::vector<std::uint8_t>` to be processed outside of the library.
+The library also supports binary types from BSON, CBOR (byte strings), and MessagePack (bin, ext, fixext). They are stored by default as `std::vector<std::uint8_t>` to be processed outside the library.
```cpp
// CBOR byte string with payload 0xCAFE
@@ -1036,12 +1035,13 @@
## Supported compilers
-Though it's 2021 already, the support for C++11 is still a bit sparse. Currently, the following compilers are known to work:
+Though it's 2022 already, the support for C++11 is still a bit sparse. Currently, the following compilers are known to work:
- GCC 4.8 - 11.0 (and possibly later)
- Clang 3.4 - 13.0 (and possibly later)
-- Apple Clang 9.1 - 12.4 (and possibly later)
+- Apple Clang 9.1 - 13.0 (and possibly later)
- Intel C++ Compiler 17.0.2 (and possibly later)
+- Nvidia CUDA Compiler 11.0.221 (and possibly later)
- Microsoft Visual C++ 2015 / Build Tools 14.0.25123.0 (and possibly later)
- Microsoft Visual C++ 2017 / Build Tools 15.5.180.51428 (and possibly later)
- Microsoft Visual C++ 2019 / Build Tools 16.3.1+1def00d3d (and possibly later)
@@ -1065,59 +1065,60 @@
- Unsupported versions of GCC and Clang are rejected by `#error` directives. This can be switched off by defining `JSON_SKIP_UNSUPPORTED_COMPILER_CHECK`. Note that you can expect no support in this case.
-The following compilers are currently used in continuous integration at [Travis](https://travis-ci.org/nlohmann/json), [AppVeyor](https://ci.appveyor.com/project/nlohmann/json), [Drone CI](https://cloud.drone.io/nlohmann/json), and [GitHub Actions](https://github.com/nlohmann/json/actions):
+The following compilers are currently used in continuous integration at [AppVeyor](https://ci.appveyor.com/project/nlohmann/json), [Drone CI](https://cloud.drone.io/nlohmann/json), and [GitHub Actions](https://github.com/nlohmann/json/actions):
-| Compiler | Operating System | CI Provider |
-|-------------------------------------------------------------------|--------------------|----------------|
-| Apple Clang 10.0.1 (clang-1001.0.46.4); Xcode 10.2.1 | macOS 10.14.4 | Travis |
-| Apple Clang 10.0.1 (clang-1001.0.46.4); Xcode 10.3 | macOS 10.15.7 | GitHub Actions |
-| Apple Clang 11.0.0 (clang-1100.0.33.12); Xcode 11.2.1 | macOS 10.15.7 | GitHub Actions |
-| Apple Clang 11.0.0 (clang-1100.0.33.17); Xcode 11.3.1 | macOS 10.15.7 | GitHub Actions |
-| Apple Clang 11.0.3 (clang-1103.0.32.59); Xcode 11.4.1 | macOS 10.15.7 | GitHub Actions |
-| Apple Clang 11.0.3 (clang-1103.0.32.62); Xcode 11.5 | macOS 10.15.7 | GitHub Actions |
-| Apple Clang 11.0.3 (clang-1103.0.32.62); Xcode 11.6 | macOS 10.15.7 | GitHub Actions |
-| Apple Clang 11.0.3 (clang-1103.0.32.62); Xcode 11.7 | macOS 10.15.7 | GitHub Actions |
-| Apple Clang 12.0.0 (clang-1200.0.32.2); Xcode 12 | macOS 10.15.7 | GitHub Actions |
-| Apple Clang 12.0.0 (clang-1200.0.32.21); Xcode 12.1 | macOS 10.15.7 | GitHub Actions |
-| Apple Clang 12.0.0 (clang-1200.0.32.21); Xcode 12.1.1 | macOS 10.15.7 | GitHub Actions |
-| 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.2 LTS | GitHub Actions |
-| GCC 4.9.3 (Ubuntu 4.9.3-13ubuntu2) | Ubuntu 20.04.2 LTS | GitHub Actions |
-| GCC 5.4.0 (Ubuntu 5.4.0-6ubuntu1~16.04.12) | Ubuntu 20.04.2 LTS | GitHub Actions |
-| GCC 6.5.0 (Ubuntu 6.5.0-2ubuntu1~14.04.1) | Ubuntu 14.04.5 LTS | Travis |
-| GCC 7.5.0 (Ubuntu 7.5.0-6ubuntu2) | Ubuntu 20.04.2 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.2 LTS | GitHub Actions |
-| GCC 9.3.0 (Ubuntu 9.3.0-17ubuntu1~20.04) | Ubuntu 20.04.2 LTS | GitHub Actions |
-| GCC 10.2.0 (Ubuntu 10.2.0-5ubuntu1~20.04) | Ubuntu 20.04.2 LTS | GitHub Actions |
-| GCC 11.0.1 20210321 (experimental) | Ubuntu 20.04.2 LTS | GitHub Actions |
-| GCC 11.1.0 | Ubuntu (aarch64) | Drone CI |
-| Clang 3.5.2 (3.5.2-3ubuntu1) | Ubuntu 20.04.2 LTS | GitHub Actions |
-| Clang 3.6.2 (3.6.2-3ubuntu2) | Ubuntu 20.04.2 LTS | GitHub Actions |
-| Clang 3.7.1 (3.7.1-2ubuntu2) | Ubuntu 20.04.2 LTS | GitHub Actions |
-| Clang 3.8.0 (3.8.0-2ubuntu4) | Ubuntu 20.04.2 LTS | GitHub Actions |
-| Clang 3.9.1 (3.9.1-4ubuntu3\~16.04.2) | Ubuntu 20.04.2 LTS | GitHub Actions |
-| Clang 4.0.0 (4.0.0-1ubuntu1\~16.04.2) | Ubuntu 20.04.2 LTS | GitHub Actions |
-| Clang 5.0.0 (5.0.0-3\~16.04.1) | Ubuntu 20.04.2 LTS | GitHub Actions |
-| Clang 6.0.1 (6.0.1-14) | Ubuntu 20.04.2 LTS | GitHub Actions |
-| Clang 7.0.1 (7.0.1-12) | Ubuntu 20.04.2 LTS | GitHub Actions |
-| Clang 8.0.1 (8.0.1-9) | Ubuntu 20.04.2 LTS | GitHub Actions |
-| Clang 9.0.1 (9.0.1-12) | Ubuntu 20.04.2 LTS | GitHub Actions |
-| Clang 10.0.0 (10.0.0-4ubuntu1) | Ubuntu 20.04.2 LTS | GitHub Actions |
-| Clang 10.0.0 with GNU-like command-line | Windows-10.0.17763 | GitHub Actions |
-| Clang 11.0.0 with GNU-like command-line | Windows-10.0.17763 | GitHub Actions |
-| Clang 11.0.0 with MSVC-like command-line | Windows-10.0.17763 | GitHub Actions |
-| Clang 11.0.0 (11.0.0-2~ubuntu20.04.1) | Ubuntu 20.04.2 LTS | GitHub Actions |
-| Clang 12.0.0 (12.0.0-3ubuntu1~20.04.3) | Ubuntu 20.04.2 LTS | GitHub Actions |
-| Clang 13.0.0 (13.0.0-++20210828094952+9c49fee5e7ac-1exp120210828075752.71 | Ubuntu 20.04.2 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 |
+| Compiler | Operating System | CI Provider |
+|--------------------------------------------------------------------------------------------------------|--------------------|----------------|
+| Apple Clang 10.0.1 (clang-1001.0.46.4); Xcode 10.3 | macOS 10.15.7 | GitHub Actions |
+| Apple Clang 11.0.0 (clang-1100.0.33.12); Xcode 11.2.1 | macOS 10.15.7 | GitHub Actions |
+| Apple Clang 11.0.0 (clang-1100.0.33.17); Xcode 11.3.1 | macOS 10.15.7 | GitHub Actions |
+| Apple Clang 11.0.3 (clang-1103.0.32.59); Xcode 11.4.1 | macOS 10.15.7 | GitHub Actions |
+| Apple Clang 11.0.3 (clang-1103.0.32.62); Xcode 11.5 | macOS 10.15.7 | GitHub Actions |
+| Apple Clang 11.0.3 (clang-1103.0.32.62); Xcode 11.6 | macOS 10.15.7 | GitHub Actions |
+| Apple Clang 11.0.3 (clang-1103.0.32.62); Xcode 11.7 | macOS 10.15.7 | GitHub Actions |
+| Apple Clang 12.0.0 (clang-1200.0.32.2); Xcode 12 | macOS 10.15.7 | GitHub Actions |
+| Apple Clang 12.0.0 (clang-1200.0.32.21); Xcode 12.1 | macOS 10.15.7 | GitHub Actions |
+| Apple Clang 12.0.0 (clang-1200.0.32.21); Xcode 12.1.1 | macOS 10.15.7 | GitHub Actions |
+| 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.0.1 20210321 (experimental) | Ubuntu 20.04.3 LTS | GitHub Actions |
+| GCC 11.1.0 | Ubuntu (aarch64) | Drone CI |
+| 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 |
+| Clang 3.8.0 (3.8.0-2ubuntu4) | Ubuntu 20.04.3 LTS | GitHub Actions |
+| Clang 3.9.1 (3.9.1-4ubuntu3\~16.04.2) | Ubuntu 20.04.3 LTS | GitHub Actions |
+| Clang 4.0.0 (4.0.0-1ubuntu1\~16.04.2) | Ubuntu 20.04.3 LTS | GitHub Actions |
+| Clang 5.0.0 (5.0.0-3\~16.04.1) | Ubuntu 20.04.3 LTS | GitHub Actions |
+| Clang 6.0.1 (6.0.1-14) | Ubuntu 20.04.3 LTS | GitHub Actions |
+| Clang 7.0.1 (7.0.1-12) | Ubuntu 20.04.3 LTS | GitHub Actions |
+| Clang 8.0.1 (8.0.1-9) | Ubuntu 20.04.3 LTS | GitHub Actions |
+| Clang 9.0.1 (9.0.1-12) | Ubuntu 20.04.3 LTS | GitHub Actions |
+| Clang 10.0.0 (10.0.0-4ubuntu1) | Ubuntu 20.04.3 LTS | GitHub Actions |
+| Clang 10.0.0 with GNU-like command-line | Windows-10.0.17763 | GitHub Actions |
+| Clang 11.0.0 with GNU-like command-line | Windows-10.0.17763 | GitHub Actions |
+| Clang 11.0.0 with MSVC-like command-line | Windows-10.0.17763 | GitHub Actions |
+| 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 |
+| 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 |
| Visual Studio 15 2017 MSVC 19.16.27045.0 (Build Engine version 15.9.21+g9802d43bc3 for .NET Framework) | Windows-10.0.14393 | GitHub Actions |
-| Visual Studio 16 2019 MSVC 19.28.29912.0 (Build Engine version 16.9.0+57a23d249 for .NET Framework) | Windows-10.0.17763 | GitHub Actions |
-| Visual Studio 16 2019 MSVC 19.28.29912.0 (Build Engine version 16.9.0+57a23d249 for .NET Framework) | Windows-10.0.17763 | AppVeyor |
+| Visual Studio 16 2019 MSVC 19.28.29912.0 (Build Engine version 16.9.0+57a23d249 for .NET Framework) | Windows-10.0.17763 | GitHub Actions |
+| Visual Studio 16 2019 MSVC 19.28.29912.0 (Build Engine version 16.9.0+57a23d249 for .NET Framework) | Windows-10.0.17763 | AppVeyor |
## Integration
@@ -1244,7 +1245,7 @@
If you are using the [Meson Build System](https://mesonbuild.com), add this source tree as a [meson subproject](https://mesonbuild.com/Subprojects.html#using-a-subproject). You may also use the `include.zip` published in this project's [Releases](https://github.com/nlohmann/json/releases) to reduce the size of the vendored source tree. Alternatively, you can get a wrap file by downloading it from [Meson WrapDB](https://wrapdb.mesonbuild.com/nlohmann_json), or simply use `meson wrap install nlohmann_json`. Please see the meson project for any issues regarding the packaging.
-The provided meson.build can also be used as an alternative to cmake for installing `nlohmann_json` system-wide in which case a pkg-config file is installed. To use it, simply have your build system require the `nlohmann_json` pkg-config dependency. In Meson, it is preferred to use the [`dependency()`](https://mesonbuild.com/Reference-manual.html#dependency) object with a subproject fallback, rather than using the subproject directly.
+The provided `meson.build` can also be used as an alternative to cmake for installing `nlohmann_json` system-wide in which case a pkg-config file is installed. To use it, simply have your build system require the `nlohmann_json` pkg-config dependency. In Meson, it is preferred to use the [`dependency()`](https://mesonbuild.com/Reference-manual.html#dependency) object with a subproject fallback, rather than using the subproject directly.
If you are using [Conan](https://www.conan.io/) to manage your dependencies, merely add [`nlohmann_json/x.y.z`](https://conan.io/center/nlohmann_json) to your `conanfile`'s requires, where `x.y.z` is the release version you want to use. Please file issues [here](https://github.com/conan-io/conan-center-index/issues) if you experience problems with the packages.
@@ -1260,7 +1261,7 @@
If you are using [CocoaPods](https://cocoapods.org), you can use the library by adding pod `"nlohmann_json", '~>3.1.2'` to your podfile (see [an example](https://bitbucket.org/benman/nlohmann_json-cocoapod/src/master/)). Please file issues [here](https://bitbucket.org/benman/nlohmann_json-cocoapod/issues?status=new&status=open).
-If you are using [NuGet](https://www.nuget.org), you can use the package [nlohmann.json](https://www.nuget.org/packages/nlohmann.json/). Please check [this extensive description](https://github.com/nlohmann/json/issues/1132#issuecomment-452250255) on how to use the package. Please files issues [here](https://github.com/hnkb/nlohmann-json-nuget/issues).
+If you are using [NuGet](https://www.nuget.org), you can use the package [nlohmann.json](https://www.nuget.org/packages/nlohmann.json/). Please check [this extensive description](https://github.com/nlohmann/json/issues/1132#issuecomment-452250255) on how to use the package. Please file issues [here](https://github.com/hnkb/nlohmann-json-nuget/issues).
If you are using [conda](https://conda.io/), you can use the package [nlohmann_json](https://github.com/conda-forge/nlohmann_json-feedstock) from [conda-forge](https://conda-forge.org) executing `conda install -c conda-forge nlohmann_json`. Please file issues [here](https://github.com/conda-forge/nlohmann_json-feedstock/issues).
@@ -1290,7 +1291,7 @@
pkg-config nlohmann_json --cflags
```
-Users of the Meson build system will also be able to use a system wide library, which will be found by `pkg-config`:
+Users of the Meson build system will also be able to use a system-wide library, which will be found by `pkg-config`:
```meson
json = dependency('nlohmann_json', required: true)
@@ -1303,7 +1304,7 @@
The class is licensed under the [MIT License](https://opensource.org/licenses/MIT):
-Copyright © 2013-2021 [Niels Lohmann](https://nlohmann.me)
+Copyright © 2013-2022 [Niels Lohmann](https://nlohmann.me)
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
@@ -1420,13 +1421,13 @@
- [Markus Werle](https://github.com/daixtrose) fixed a typo.
- [WebProdPP](https://github.com/WebProdPP) fixed a subtle error in a precondition check.
- [Alex](https://github.com/leha-bot) noted an error in a code sample.
-- [Tom de Geus](https://github.com/tdegeus) reported some warnings with ICC and helped fixing them.
+- [Tom de Geus](https://github.com/tdegeus) reported some warnings with ICC and helped to fix them.
- [Perry Kundert](https://github.com/pjkundert) simplified reading from input streams.
- [Sonu Lohani](https://github.com/sonulohani) fixed a small compilation error.
- [Jamie Seward](https://github.com/jseward) fixed all MSVC warnings.
- [Nate Vargas](https://github.com/eld00d) added a Doxygen tag file.
-- [pvleuven](https://github.com/pvleuven) helped fixing a warning in ICC.
-- [Pavel](https://github.com/crea7or) helped fixing some warnings in MSVC.
+- [pvleuven](https://github.com/pvleuven) helped to fix a warning in ICC.
+- [Pavel](https://github.com/crea7or) helped to fix some warnings in MSVC.
- [Jamie Seward](https://github.com/jseward) avoided unnecessary string copies in `find()` and `count()`.
- [Mitja](https://github.com/Itja) fixed some typos.
- [Jorrit Wronski](https://github.com/jowr) updated the Hunter package links.
@@ -1469,7 +1470,7 @@
- [Henry Schreiner](https://github.com/henryiii) added support for GCC 4.8.
- [knilch](https://github.com/knilch0r) made sure the test suite does not stall when run in the wrong directory.
- [Antonio Borondo](https://github.com/antonioborondo) fixed an MSVC 2017 warning.
-- [Dan Gendreau](https://github.com/dgendreau) implemented the `NLOHMANN_JSON_SERIALIZE_ENUM` macro to quickly define a enum/JSON mapping.
+- [Dan Gendreau](https://github.com/dgendreau) implemented the `NLOHMANN_JSON_SERIALIZE_ENUM` macro to quickly define an enum/JSON mapping.
- [efp](https://github.com/efp) added line and column information to parse errors.
- [julian-becker](https://github.com/julian-becker) added BSON support.
- [Pratik Chowdhury](https://github.com/pratikpc) added support for structured bindings.
@@ -1489,7 +1490,7 @@
- [John-Mark](https://github.com/johnmarkwayve) noted a missing header.
- [Vitaly Zaitsev](https://github.com/xvitaly) fixed compilation with GCC 9.0.
- [Laurent Stacul](https://github.com/stac47) fixed compilation with GCC 9.0.
-- [Ivor Wanders](https://github.com/iwanders) helped reducing the CMake requirement to version 3.1.
+- [Ivor Wanders](https://github.com/iwanders) helped to reduce the CMake requirement to version 3.1.
- [njlr](https://github.com/njlr) updated the Buckaroo instructions.
- [Lion](https://github.com/lieff) fixed a compilation issue with GCC 7 on CentOS.
- [Isaac Nickaein](https://github.com/nickaein) improved the integer serialization performance and implemented the `contains()` function.
@@ -1503,7 +1504,7 @@
- [Michele Caini](https://github.com/skypjack) fixed links in the README.
- [Hani](https://github.com/hnkb) documented how to install the library with NuGet.
- [Mark Beckwith](https://github.com/wythe) fixed a typo.
-- [yann-morin-1998](https://github.com/yann-morin-1998) helped reducing the CMake requirement to version 3.1.
+- [yann-morin-1998](https://github.com/yann-morin-1998) helped to reduce the CMake requirement to version 3.1.
- [Konstantin Podsvirov](https://github.com/podsvirov) maintains a package for the MSYS2 software distro.
- [remyabel](https://github.com/remyabel) added GNUInstallDirs to the CMake files.
- [Taylor Howard](https://github.com/taylorhoward92) fixed a unit test.
@@ -1597,6 +1598,13 @@
- [Giovanni Cerretani](https://github.com/gcerretani) fixed `-Wunused` warnings on `JSON_DIAGNOSTICS`.
- [Bogdan Popescu](https://github.com/Kapeli) hosts the [docset](https://github.com/Kapeli/Dash-User-Contributions/tree/master/docsets/JSON_for_Modern_C%2B%2B) for offline documentation viewers.
- [Carl Smedstad](https://github.com/carlsmedstad) fixed an assertion error when using `JSON_DIAGNOSTICS`.
+- [miikka75](https://github.com/miikka75) provided an important fix to compile C++17 code with Clang 9.
+- [Maarten Becker](https://github.com/kernie) fixed a warning for shadowed variables.
+- [Cristi Vîjdea](https://github.com/axnsan12) fixed typos in the `operator[]` documentation.
+- [Alex Beregszaszi](https://github.com/axic) fixed spelling mistakes in comments.
+- [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.
Thanks a lot for helping out! Please [let me know](mailto:mail@nlohmann.me) if I forgot someone.
@@ -1621,14 +1629,11 @@
- [**GitHub Changelog Generator**](https://github.com/skywinder/github-changelog-generator) to generate the [ChangeLog](https://github.com/nlohmann/json/blob/develop/ChangeLog.md)
- [**Google Benchmark**](https://github.com/google/benchmark) to implement the benchmarks
- [**Hedley**](https://nemequ.github.io/hedley/) to avoid re-inventing several compiler-agnostic feature macros
-- [**lcov**](http://ltp.sourceforge.net/coverage/lcov.php) to process coverage information and create a HTML view
+- [**lcov**](http://ltp.sourceforge.net/coverage/lcov.php) to process coverage information and create an HTML view
- [**libFuzzer**](https://llvm.org/docs/LibFuzzer.html) to implement fuzz testing for OSS-Fuzz
- [**OSS-Fuzz**](https://github.com/google/oss-fuzz) for continuous fuzz testing of the library ([project repository](https://github.com/google/oss-fuzz/tree/master/projects/json))
- [**Probot**](https://probot.github.io) for automating maintainer tasks such as closing stale issues, requesting missing information, or detecting toxic comments.
-- [**send_to_wandbox**](https://github.com/nlohmann/json/blob/develop/doc/scripts/send_to_wandbox.py) to send code examples to [Wandbox](https://wandbox.org)
-- [**Travis**](https://travis-ci.org) for [continuous integration](https://travis-ci.org/nlohmann/json) on Linux and macOS
- [**Valgrind**](https://valgrind.org) to check for correct memory management
-- [**Wandbox**](https://wandbox.org) for [online examples](https://wandbox.org/permlink/1mp10JbaANo6FUc7)
## Projects using JSON for Modern C++
@@ -1649,7 +1654,7 @@
- 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.
-- To store wide strings (e.g., `std::wstring`), you need to convert them to a a UTF-8 encoded `std::string` before, see [an example](https://json.nlohmann.me/home/faq/#wide-string-handling).
+- 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
@@ -1676,7 +1681,7 @@
We checked with Valgrind and the Address Sanitizer (ASAN) that there are no memory leaks.
-If you find that a parsing program with this library does not release memory, please consider the following case and it maybe unrelated to this library.
+If you find that a parsing program with this library does not release memory, please consider the following case, and it may be unrelated to this library.
**Your program is compiled with glibc.** There is a tunable threshold that glibc uses to decide whether to actually return memory to the system or whether to cache it for later reuse. If in your program you make lots of small allocations and those small allocations are not a contiguous block and are presumably below the threshold, then they will not get returned to the OS.
Here is a related issue [#1924](https://github.com/nlohmann/json/issues/1924).
@@ -1684,7 +1689,7 @@
### 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)`.
-- As the exact type of a number 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.
+- 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).
diff --git a/cmake/ci.cmake b/cmake/ci.cmake
index f748c76..d0b989c 100644
--- a/cmake/ci.cmake
+++ b/cmake/ci.cmake
@@ -13,12 +13,12 @@
string(REGEX MATCH "[0-9]+(\\.[0-9]+)+" ASTYLE_TOOL_VERSION "${ASTYLE_TOOL_VERSION}")
message(STATUS "🔖 Artistic Style ${ASTYLE_TOOL_VERSION} (${ASTYLE_TOOL})")
-find_program(CLANG_TOOL NAMES clang++-HEAD clang++-13 clang++-12 clang++-11 clang++)
+find_program(CLANG_TOOL NAMES clang++-HEAD clang++-14 clang++-13 clang++-12 clang++-11 clang++)
execute_process(COMMAND ${CLANG_TOOL} --version OUTPUT_VARIABLE CLANG_TOOL_VERSION ERROR_VARIABLE CLANG_TOOL_VERSION)
string(REGEX MATCH "[0-9]+(\\.[0-9]+)+" CLANG_TOOL_VERSION "${CLANG_TOOL_VERSION}")
message(STATUS "🔖 Clang ${CLANG_TOOL_VERSION} (${CLANG_TOOL})")
-find_program(CLANG_TIDY_TOOL NAMES clang-tidy-12 clang-tidy-11 clang-tidy)
+find_program(CLANG_TIDY_TOOL NAMES clang-tidy-14 clang-tidy-13 clang-tidy-12 clang-tidy-11 clang-tidy)
execute_process(COMMAND ${CLANG_TIDY_TOOL} --version OUTPUT_VARIABLE CLANG_TIDY_TOOL_VERSION ERROR_VARIABLE CLANG_TIDY_TOOL_VERSION)
string(REGEX MATCH "[0-9]+(\\.[0-9]+)+" CLANG_TIDY_TOOL_VERSION "${CLANG_TIDY_TOOL_VERSION}")
message(STATUS "🔖 Clang-Tidy ${CLANG_TIDY_TOOL_VERSION} (${CLANG_TIDY_TOOL})")
@@ -79,7 +79,7 @@
find_program(GENHTML_TOOL NAMES genhtml)
find_program(PLOG_CONVERTER_TOOL NAMES plog-converter)
find_program(PVS_STUDIO_ANALYZER_TOOL NAMES pvs-studio-analyzer)
-find_program(SCAN_BUILD_TOOL NAMES scan-build-12 scan-build-11 scan-build)
+find_program(SCAN_BUILD_TOOL NAMES scan-build-14 scan-build-13 scan-build-12 scan-build-11 scan-build)
# the individual source files
file(GLOB_RECURSE SRC_FILES ${PROJECT_SOURCE_DIR}/include/nlohmann/*.hpp)
@@ -811,14 +811,22 @@
# Use more installed compilers.
###############################################################################
-foreach(COMPILER g++-4.8 g++-4.9 g++-5 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)
+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)
find_program(COMPILER_TOOL NAMES ${COMPILER})
if (COMPILER_TOOL)
+ if ("${COMPILER}" STREQUAL "clang++-9")
+ # fix for https://github.com/nlohmann/json/pull/3101#issuecomment-998788786 / https://stackoverflow.com/a/64051725/266378
+ set(ADDITIONAL_FLAGS "-DCMAKE_CXX_FLAGS=--gcc-toolchain=/root/gcc/9")
+ else()
+ unset(ADDITIONAL_FLAGS)
+ endif()
+
add_custom_target(ci_test_compiler_${COMPILER}
COMMAND CXX=${COMPILER} ${CMAKE_COMMAND}
-DCMAKE_BUILD_TYPE=Debug -GNinja
-DJSON_BuildTests=ON -DJSON_FastTests=ON
-S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_compiler_${COMPILER}
+ ${ADDITIONAL_FLAGS}
COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/build_compiler_${COMPILER}
COMMAND cd ${PROJECT_BINARY_DIR}/build_compiler_${COMPILER} && ${CMAKE_CTEST_COMMAND} --parallel ${N} --exclude-regex "test-unicode" --output-on-failure
COMMENT "Compile and test with ${COMPILER}"
@@ -828,6 +836,18 @@
endforeach()
###############################################################################
+# CUDA example
+###############################################################################
+
+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
+ COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/build_cuda_example
+)
+
+###############################################################################
# Clean up all generated files.
###############################################################################
diff --git a/doc/Doxyfile b/doc/Doxyfile
deleted file mode 100644
index b55813b..0000000
--- a/doc/Doxyfile
+++ /dev/null
@@ -1,335 +0,0 @@
-# Doxyfile 1.9.1
-
-#---------------------------------------------------------------------------
-# Project related configuration options
-#---------------------------------------------------------------------------
-DOXYFILE_ENCODING = UTF-8
-PROJECT_NAME = "JSON for Modern C++"
-PROJECT_NUMBER = 3.10.4
-PROJECT_BRIEF =
-PROJECT_LOGO =
-OUTPUT_DIRECTORY = .
-CREATE_SUBDIRS = NO
-ALLOW_UNICODE_NAMES = NO
-OUTPUT_LANGUAGE = English
-OUTPUT_TEXT_DIRECTION = None
-BRIEF_MEMBER_DESC = YES
-REPEAT_BRIEF = NO
-ABBREVIATE_BRIEF =
-ALWAYS_DETAILED_SEC = YES
-INLINE_INHERITED_MEMB = NO
-FULL_PATH_NAMES = YES
-STRIP_FROM_PATH =
-STRIP_FROM_INC_PATH =
-SHORT_NAMES = NO
-JAVADOC_AUTOBRIEF = NO
-JAVADOC_BANNER = NO
-QT_AUTOBRIEF = NO
-MULTILINE_CPP_IS_BRIEF = NO
-PYTHON_DOCSTRING = YES
-INHERIT_DOCS = YES
-SEPARATE_MEMBER_PAGES = YES
-TAB_SIZE = 4
-ALIASES = "complexity=@par Complexity^^" \
- "liveexample{2}=@par Example^^ \1 ^^ @includelineno \2.cpp \n Output (play with this example @htmlinclude \2.link):^^ @verbinclude \2.output ^^ The <a href= https://github.com/nlohmann/json/blob/develop/doc/examples/\2.cpp>example code</a> above can be translated with @verbatim g++ -std=c++11 -Isingle_include doc/examples/\2.cpp -o \2 @endverbatim" \
- "requirement=@par Requirements^^" \
- "exceptionsafety=@par Exception safety^^" \
- "iterators=@par Iterator validity^^"
-OPTIMIZE_OUTPUT_FOR_C = NO
-OPTIMIZE_OUTPUT_JAVA = NO
-OPTIMIZE_FOR_FORTRAN = NO
-OPTIMIZE_OUTPUT_VHDL = NO
-OPTIMIZE_OUTPUT_SLICE = NO
-EXTENSION_MAPPING =
-MARKDOWN_SUPPORT = YES
-TOC_INCLUDE_HEADINGS = 0
-AUTOLINK_SUPPORT = NO
-BUILTIN_STL_SUPPORT = YES
-CPP_CLI_SUPPORT = NO
-SIP_SUPPORT = NO
-IDL_PROPERTY_SUPPORT = YES
-DISTRIBUTE_GROUP_DOC = NO
-GROUP_NESTED_COMPOUNDS = NO
-SUBGROUPING = YES
-INLINE_GROUPED_CLASSES = NO
-INLINE_SIMPLE_STRUCTS = NO
-TYPEDEF_HIDES_STRUCT = NO
-LOOKUP_CACHE_SIZE = 0
-NUM_PROC_THREADS = 1
-#---------------------------------------------------------------------------
-# Build related configuration options
-#---------------------------------------------------------------------------
-EXTRACT_ALL = YES
-EXTRACT_PRIVATE = NO
-EXTRACT_PRIV_VIRTUAL = NO
-EXTRACT_PACKAGE = YES
-EXTRACT_STATIC = YES
-EXTRACT_LOCAL_CLASSES = YES
-EXTRACT_LOCAL_METHODS = YES
-EXTRACT_ANON_NSPACES = YES
-RESOLVE_UNNAMED_PARAMS = YES
-HIDE_UNDOC_MEMBERS = NO
-HIDE_UNDOC_CLASSES = NO
-HIDE_FRIEND_COMPOUNDS = NO
-HIDE_IN_BODY_DOCS = NO
-INTERNAL_DOCS = NO
-CASE_SENSE_NAMES = NO
-HIDE_SCOPE_NAMES = NO
-HIDE_COMPOUND_REFERENCE= NO
-SHOW_INCLUDE_FILES = YES
-SHOW_GROUPED_MEMB_INC = NO
-FORCE_LOCAL_INCLUDES = NO
-INLINE_INFO = YES
-SORT_MEMBER_DOCS = YES
-SORT_BRIEF_DOCS = YES
-SORT_MEMBERS_CTORS_1ST = YES
-SORT_GROUP_NAMES = NO
-SORT_BY_SCOPE_NAME = NO
-STRICT_PROTO_MATCHING = NO
-GENERATE_TODOLIST = YES
-GENERATE_TESTLIST = YES
-GENERATE_BUGLIST = YES
-GENERATE_DEPRECATEDLIST= YES
-ENABLED_SECTIONS =
-MAX_INITIALIZER_LINES = 30
-SHOW_USED_FILES = NO
-SHOW_FILES = NO
-SHOW_NAMESPACES = NO
-FILE_VERSION_FILTER =
-LAYOUT_FILE =
-CITE_BIB_FILES =
-#---------------------------------------------------------------------------
-# Configuration options related to warning and progress messages
-#---------------------------------------------------------------------------
-QUIET = YES
-WARNINGS = YES
-WARN_IF_UNDOCUMENTED = YES
-WARN_IF_DOC_ERROR = YES
-WARN_NO_PARAMDOC = YES
-WARN_AS_ERROR = NO
-WARN_FORMAT = "$file:$line: $text"
-WARN_LOGFILE =
-#---------------------------------------------------------------------------
-# Configuration options related to the input files
-#---------------------------------------------------------------------------
-INPUT = ../single_include/nlohmann/json.hpp \
- index.md
-INPUT_ENCODING = UTF-8
-FILE_PATTERNS =
-RECURSIVE = NO
-EXCLUDE =
-EXCLUDE_SYMLINKS = NO
-EXCLUDE_PATTERNS =
-EXCLUDE_SYMBOLS = nlohmann::detail
-EXAMPLE_PATH = examples
-EXAMPLE_PATTERNS =
-EXAMPLE_RECURSIVE = NO
-IMAGE_PATH = images
-INPUT_FILTER =
-FILTER_PATTERNS =
-FILTER_SOURCE_FILES = NO
-FILTER_SOURCE_PATTERNS =
-USE_MDFILE_AS_MAINPAGE = index.md
-#---------------------------------------------------------------------------
-# Configuration options related to source browsing
-#---------------------------------------------------------------------------
-SOURCE_BROWSER = YES
-INLINE_SOURCES = NO
-STRIP_CODE_COMMENTS = YES
-REFERENCED_BY_RELATION = NO
-REFERENCES_RELATION = NO
-REFERENCES_LINK_SOURCE = NO
-SOURCE_TOOLTIPS = YES
-USE_HTAGS = NO
-VERBATIM_HEADERS = NO
-#---------------------------------------------------------------------------
-# Configuration options related to the alphabetical class index
-#---------------------------------------------------------------------------
-ALPHABETICAL_INDEX = YES
-IGNORE_PREFIX =
-#---------------------------------------------------------------------------
-# Configuration options related to the HTML output
-#---------------------------------------------------------------------------
-GENERATE_HTML = YES
-HTML_OUTPUT = html
-HTML_FILE_EXTENSION = .html
-HTML_HEADER =
-HTML_FOOTER =
-HTML_STYLESHEET =
-HTML_EXTRA_STYLESHEET = css/mylayout.css
-HTML_EXTRA_FILES =
-HTML_COLORSTYLE_HUE = 220
-HTML_COLORSTYLE_SAT = 100
-HTML_COLORSTYLE_GAMMA = 80
-HTML_TIMESTAMP = YES
-HTML_DYNAMIC_MENUS = YES
-HTML_DYNAMIC_SECTIONS = YES
-HTML_INDEX_NUM_ENTRIES = 100
-GENERATE_DOCSET = YES
-DOCSET_FEEDNAME = "Doxygen generated docs"
-DOCSET_BUNDLE_ID = me.nlohmann.json
-DOCSET_PUBLISHER_ID = me.nlohmann
-DOCSET_PUBLISHER_NAME = NielsLohmann
-GENERATE_HTMLHELP = NO
-CHM_FILE =
-HHC_LOCATION =
-GENERATE_CHI = NO
-CHM_INDEX_ENCODING =
-BINARY_TOC = NO
-TOC_EXPAND = NO
-GENERATE_QHP = NO
-QCH_FILE =
-QHP_NAMESPACE = org.doxygen.Project
-QHP_VIRTUAL_FOLDER = doc
-QHP_CUST_FILTER_NAME =
-QHP_CUST_FILTER_ATTRS =
-QHP_SECT_FILTER_ATTRS =
-QHG_LOCATION =
-GENERATE_ECLIPSEHELP = NO
-ECLIPSE_DOC_ID = org.doxygen.Project
-DISABLE_INDEX = NO
-GENERATE_TREEVIEW = NO
-ENUM_VALUES_PER_LINE = 4
-TREEVIEW_WIDTH = 250
-EXT_LINKS_IN_WINDOW = NO
-HTML_FORMULA_FORMAT = png
-FORMULA_FONTSIZE = 10
-FORMULA_TRANSPARENT = YES
-FORMULA_MACROFILE =
-USE_MATHJAX = NO
-MATHJAX_FORMAT = HTML-CSS
-MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest
-MATHJAX_EXTENSIONS =
-MATHJAX_CODEFILE =
-SEARCHENGINE = YES
-SERVER_BASED_SEARCH = NO
-EXTERNAL_SEARCH = NO
-SEARCHENGINE_URL =
-SEARCHDATA_FILE = searchdata.xml
-EXTERNAL_SEARCH_ID =
-EXTRA_SEARCH_MAPPINGS =
-#---------------------------------------------------------------------------
-# Configuration options related to the LaTeX output
-#---------------------------------------------------------------------------
-GENERATE_LATEX = NO
-LATEX_OUTPUT = latex
-LATEX_CMD_NAME = latex
-MAKEINDEX_CMD_NAME = makeindex
-LATEX_MAKEINDEX_CMD = \makeindex
-COMPACT_LATEX = NO
-PAPER_TYPE = a4
-EXTRA_PACKAGES =
-LATEX_HEADER =
-LATEX_FOOTER =
-LATEX_EXTRA_STYLESHEET =
-LATEX_EXTRA_FILES =
-PDF_HYPERLINKS = YES
-USE_PDFLATEX = YES
-LATEX_BATCHMODE = NO
-LATEX_HIDE_INDICES = NO
-LATEX_SOURCE_CODE = NO
-LATEX_BIB_STYLE = plain
-LATEX_TIMESTAMP = NO
-LATEX_EMOJI_DIRECTORY =
-#---------------------------------------------------------------------------
-# Configuration options related to the RTF output
-#---------------------------------------------------------------------------
-GENERATE_RTF = NO
-RTF_OUTPUT = rtf
-COMPACT_RTF = NO
-RTF_HYPERLINKS = NO
-RTF_STYLESHEET_FILE =
-RTF_EXTENSIONS_FILE =
-RTF_SOURCE_CODE = NO
-#---------------------------------------------------------------------------
-# Configuration options related to the man page output
-#---------------------------------------------------------------------------
-GENERATE_MAN = NO
-MAN_OUTPUT = man
-MAN_EXTENSION = .3
-MAN_SUBDIR =
-MAN_LINKS = NO
-#---------------------------------------------------------------------------
-# Configuration options related to the XML output
-#---------------------------------------------------------------------------
-GENERATE_XML = NO
-XML_OUTPUT = xml
-XML_PROGRAMLISTING = YES
-XML_NS_MEMB_FILE_SCOPE = NO
-#---------------------------------------------------------------------------
-# Configuration options related to the DOCBOOK output
-#---------------------------------------------------------------------------
-GENERATE_DOCBOOK = NO
-DOCBOOK_OUTPUT = docbook
-DOCBOOK_PROGRAMLISTING = NO
-#---------------------------------------------------------------------------
-# Configuration options for the AutoGen Definitions output
-#---------------------------------------------------------------------------
-GENERATE_AUTOGEN_DEF = NO
-#---------------------------------------------------------------------------
-# Configuration options related to the Perl module output
-#---------------------------------------------------------------------------
-GENERATE_PERLMOD = NO
-PERLMOD_LATEX = NO
-PERLMOD_PRETTY = YES
-PERLMOD_MAKEVAR_PREFIX =
-#---------------------------------------------------------------------------
-# Configuration options related to the preprocessor
-#---------------------------------------------------------------------------
-ENABLE_PREPROCESSING = YES
-MACRO_EXPANSION = NO
-EXPAND_ONLY_PREDEF = NO
-SEARCH_INCLUDES = YES
-INCLUDE_PATH =
-INCLUDE_FILE_PATTERNS =
-PREDEFINED =
-EXPAND_AS_DEFINED =
-SKIP_FUNCTION_MACROS = YES
-#---------------------------------------------------------------------------
-# Configuration options related to external references
-#---------------------------------------------------------------------------
-TAGFILES =
-GENERATE_TAGFILE = html/nlohmann_json.tag
-ALLEXTERNALS = NO
-EXTERNAL_GROUPS = YES
-EXTERNAL_PAGES = YES
-#---------------------------------------------------------------------------
-# Configuration options related to the dot tool
-#---------------------------------------------------------------------------
-CLASS_DIAGRAMS = NO
-DIA_PATH =
-HIDE_UNDOC_RELATIONS = YES
-HAVE_DOT = YES
-DOT_NUM_THREADS = 0
-DOT_FONTNAME = Helvetica
-DOT_FONTSIZE = 10
-DOT_FONTPATH =
-CLASS_GRAPH = NO
-COLLABORATION_GRAPH = NO
-GROUP_GRAPHS = YES
-UML_LOOK = YES
-UML_LIMIT_NUM_FIELDS = 10
-DOT_UML_DETAILS = NO
-DOT_WRAP_THRESHOLD = 17
-TEMPLATE_RELATIONS = NO
-INCLUDE_GRAPH = NO
-INCLUDED_BY_GRAPH = NO
-CALL_GRAPH = NO
-CALLER_GRAPH = NO
-GRAPHICAL_HIERARCHY = NO
-DIRECTORY_GRAPH = NO
-DOT_IMAGE_FORMAT = svg
-INTERACTIVE_SVG = YES
-DOT_PATH =
-DOTFILE_DIRS =
-MSCFILE_DIRS =
-DIAFILE_DIRS =
-PLANTUML_JAR_PATH =
-PLANTUML_CFG_FILE =
-PLANTUML_INCLUDE_PATH =
-DOT_GRAPH_MAX_NODES = 50
-MAX_DOT_GRAPH_DEPTH = 0
-DOT_TRANSPARENT = NO
-DOT_MULTI_TARGETS = NO
-GENERATE_LEGEND = YES
-DOT_CLEANUP = YES
diff --git a/doc/Makefile b/doc/Makefile
index 761dd43..0de57e0 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -1,8 +1,6 @@
SRCDIR = ../single_include
-SED:=$(shell command -v gsed || which sed)
-all: doxygen
-
+all: create_output
##########################################################################
# example files
@@ -24,49 +22,13 @@
diff $@ $(<:.cpp=.output)
rm $(<:.cpp=) $@
-# create links to try the code online
-%.link: %.cpp
- rm -fr tmp
- mkdir tmp
- cp -r $(SRCDIR)/nlohmann tmp
- python2 scripts/send_to_wandbox.py tmp $< > $@.tmp
- /bin/echo -n "<a target=\"_blank\" href=\"`cat $@.tmp`\"><b>online</b></a>" > $@
- rm -fr tmp $@.tmp
-
# create output from all stand-alone example files
create_output: $(EXAMPLES:.cpp=.output)
-create_links: $(EXAMPLES:.cpp=.link)
-
# check output of all stand-alone example files
check_output: $(EXAMPLES:.cpp=.test)
-
clean:
- rm -fr me.nlohmann.json.docset html $(EXAMPLES:.cpp=)
+ rm -fr $(EXAMPLES:.cpp=)
$(MAKE) clean -C docset
$(MAKE) clean -C mkdocs
-
-
-##########################################################################
-# Doxygen HTML documentation
-##########################################################################
-
-# create Doxygen documentation
-doxygen: create_output create_links
- doxygen
- $(SED) -i 's@< ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberFloatType, AllocatorType, JSONSerializer >@@g' html/*.html
- $(SED) -i 's@< ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberFloatType, AllocatorType JSONSerializer >@@g' html/*.html
- $(SED) -i 's@< ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer >@@g' html/*.html
- $(SED) -i 's@< ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer >@@g' html/*.html
- $(SED) -i 's@< ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType JSONSerializer >@@g' html/*.html
- $(SED) -i 's@template<template< typename U, typename V, typename... Args > class ObjectType = std::map, template< typename U, typename... Args > class ArrayType = std::vector, class StringType = std::string, class BooleanType = bool, class NumberIntegerType = std::int64_t, class NumberUnsignedType = std::uint64_t, class NumberFloatType = double, template< typename U > class AllocatorType = std::allocator, template< typename T, typename SFINAE=void > class JSONSerializer = adl_serializer>@@g' html/*.html
- $(SED) -i 's@< ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer >@@g' html/*.html
- $(SED) -i 's@< ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer >@@g' html/*.html
- $(SED) -i 's@JSON_HEDLEY_RETURNS_NON_NULL@@g' html/*.html
- $(SED) -i 's@JSON_HEDLEY_WARN_UNUSED_RESULT@@g' html/*.html
-
-upload: clean doxygen check_output
- scripts/git-update-ghpages nlohmann/json html
- rm -fr html
- open http://nlohmann.github.io/json/
diff --git a/doc/README.md b/doc/README.md
new file mode 100644
index 0000000..ec5c25d
--- /dev/null
+++ b/doc/README.md
@@ -0,0 +1,20 @@
+# Documentation
+
+## Generate documentation
+
+Note on documentation: The source files contain links to the online documentation at https://json.nlohmann.me. This URL
+contains the most recent documentation and should also be applicable to previous versions; documentation for deprecated
+functions is not removed, but marked deprecated.
+
+If you want to see the documentation for a specific tag or commit hash, you can generate it as follows (here for tag
+`v3.10.2`):
+
+```shell
+git clone https://github.com/nlohmann/json.git
+cd json
+git checkout v3.10.2
+make install_venv serve -C doc/mkdocs
+```
+
+Open URL <http://127.0.0.1:8000/> in your browser. Replace from any URL from the source code `https://json.nlohmann.me`
+with `http://127.0.0.1:8000` to see the documentation for your tag or commit hash.
diff --git a/doc/avatars.png b/doc/avatars.png
index a3d8bad..5124358 100644
--- a/doc/avatars.png
+++ b/doc/avatars.png
Binary files differ
diff --git a/doc/css/mylayout.css b/doc/css/mylayout.css
deleted file mode 100644
index fe20b82..0000000
--- a/doc/css/mylayout.css
+++ /dev/null
@@ -1,26 +0,0 @@
-/* hide lengthy template information */
-.memtemplate, .memTemplParams {
- display: none;
-}
-
-/* allow compiler information to wrap */
-/* https://css-tricks.com/snippets/css/make-pre-text-wrap/ */
-pre.fragment {
- white-space: pre-wrap; /* css-3 */
- white-space: -moz-pre-wrap; /* Mozilla, since 1999 */
- white-space: -pre-wrap; /* Opera 4-6 */
- white-space: -o-pre-wrap; /* Opera 7 */
- word-wrap: break-word; /* Internet Explorer 5.5+ */
-}
-
-td.paramname {
- vertical-align: top;
-}
-
-.ok_green {
- background-color: #89C35C;
-}
-
-.nok_throws {
- background-color: #ffa500;
-}
diff --git a/doc/css/mylayout_docset.css b/doc/css/mylayout_docset.css
deleted file mode 100644
index 1a67e99..0000000
--- a/doc/css/mylayout_docset.css
+++ /dev/null
@@ -1,27 +0,0 @@
-.memtemplate {
- display: none;
-}
-
-.memTemplParams {
- display: none;
-}
-
-.navtab {
- display: none;
-}
-
-#top, .footer {
- display: none;
-}
-
-td.paramname {
- vertical-align: top;
-}
-
-.ok_green {
- background-color: #89C35C;
-}
-
-.nok_throws {
- background-color: #ffa500;
-}
diff --git a/doc/examples/README.link b/doc/examples/README.link
deleted file mode 100644
index 592a050..0000000
--- a/doc/examples/README.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/1mp10JbaANo6FUc7"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/accept__string.link b/doc/examples/accept__string.link
deleted file mode 100644
index 8456e3b..0000000
--- a/doc/examples/accept__string.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/r5Tai1spihWHTdFA"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/array.link b/doc/examples/array.link
deleted file mode 100644
index 4c69b84..0000000
--- a/doc/examples/array.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/Ptk2BoNyGfrZfxRU"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/array_t.cpp b/doc/examples/array_t.cpp
new file mode 100644
index 0000000..0964857
--- /dev/null
+++ b/doc/examples/array_t.cpp
@@ -0,0 +1,10 @@
+#include <iostream>
+#include <iomanip>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+ std::cout << std::boolalpha << std::is_same<std::vector<json>, json::array_t>::value << std::endl;
+}
diff --git a/doc/examples/array_t.output b/doc/examples/array_t.output
new file mode 100644
index 0000000..27ba77d
--- /dev/null
+++ b/doc/examples/array_t.output
@@ -0,0 +1 @@
+true
diff --git a/doc/examples/at__object_t_key_type.link b/doc/examples/at__object_t_key_type.link
deleted file mode 100644
index 0518fe6..0000000
--- a/doc/examples/at__object_t_key_type.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/055DW3OWJPwGYr92"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/at__object_t_key_type_const.link b/doc/examples/at__object_t_key_type_const.link
deleted file mode 100644
index a7cd73b..0000000
--- a/doc/examples/at__object_t_key_type_const.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/gM1uqvzukokLwjMa"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/at__size_type.link b/doc/examples/at__size_type.link
deleted file mode 100644
index a98adcb..0000000
--- a/doc/examples/at__size_type.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/H3tBOr4lpufGRHlF"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/at__size_type_const.link b/doc/examples/at__size_type_const.link
deleted file mode 100644
index 73a13bb..0000000
--- a/doc/examples/at__size_type_const.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/UtGhIQGxCYIml36F"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/at_json_pointer.cpp b/doc/examples/at_json_pointer.cpp
index ed450f7..f554d85 100644
--- a/doc/examples/at_json_pointer.cpp
+++ b/doc/examples/at_json_pointer.cpp
@@ -60,7 +60,7 @@
// out_of_range.401
try
{
- // try to use a an invalid array index
+ // try to use an invalid array index
json::reference ref = j.at("/array/4"_json_pointer);
}
catch (json::out_of_range& e)
@@ -82,7 +82,7 @@
// out_of_range.403
try
{
- // try to use a JSON pointer to an nonexistent object key
+ // try to use a JSON pointer to a nonexistent object key
json::const_reference ref = j.at("/foo"_json_pointer);
}
catch (json::out_of_range& e)
diff --git a/doc/examples/at_json_pointer.link b/doc/examples/at_json_pointer.link
deleted file mode 100644
index a4e2c24..0000000
--- a/doc/examples/at_json_pointer.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/NHe5FLR1KYaiHwBx"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/at_json_pointer_const.cpp b/doc/examples/at_json_pointer_const.cpp
index 6f2b2f5..3ac232b 100644
--- a/doc/examples/at_json_pointer_const.cpp
+++ b/doc/examples/at_json_pointer_const.cpp
@@ -36,7 +36,7 @@
// out_of_range.401
try
{
- // try to use a an invalid array index
+ // try to use an invalid array index
json::const_reference ref = j.at("/array/4"_json_pointer);
}
catch (json::out_of_range& e)
@@ -58,7 +58,7 @@
// out_of_range.403
try
{
- // try to use a JSON pointer to an nonexistent object key
+ // try to use a JSON pointer to a nonexistent object key
json::const_reference ref = j.at("/foo"_json_pointer);
}
catch (json::out_of_range& e)
diff --git a/doc/examples/at_json_pointer_const.link b/doc/examples/at_json_pointer_const.link
deleted file mode 100644
index f04bf5a..0000000
--- a/doc/examples/at_json_pointer_const.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/lbZjdwg6yII33cV5"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/back.link b/doc/examples/back.link
deleted file mode 100644
index 7fe2400..0000000
--- a/doc/examples/back.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/swnzqmd8zj6ij1fb"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/basic_json__CompatibleType.cpp b/doc/examples/basic_json__CompatibleType.cpp
index d39fd7a..e2f01aa 100644
--- a/doc/examples/basic_json__CompatibleType.cpp
+++ b/doc/examples/basic_json__CompatibleType.cpp
@@ -81,7 +81,7 @@
json j_list(c_list);
// create an array from std::forward_list
- std::forward_list<int64_t> c_flist {12345678909876, 23456789098765, 34567890987654, 45678909876543};
+ std::forward_list<std::int64_t> c_flist {12345678909876, 23456789098765, 34567890987654, 45678909876543};
json j_flist(c_flist);
// create an array from std::array
diff --git a/doc/examples/basic_json__CompatibleType.link b/doc/examples/basic_json__CompatibleType.link
deleted file mode 100644
index a633647..0000000
--- a/doc/examples/basic_json__CompatibleType.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/RodBcX8vpcP5dQ40"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/basic_json__InputIt_InputIt.link b/doc/examples/basic_json__InputIt_InputIt.link
deleted file mode 100644
index 844e914..0000000
--- a/doc/examples/basic_json__InputIt_InputIt.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/oWFo4AhVlMBjNv8E"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/basic_json__basic_json.link b/doc/examples/basic_json__basic_json.link
deleted file mode 100644
index 757e2c7..0000000
--- a/doc/examples/basic_json__basic_json.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/oRn0YsYyurs0Zi5T"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/basic_json__copyassignment.link b/doc/examples/basic_json__copyassignment.link
deleted file mode 100644
index 86beb67..0000000
--- a/doc/examples/basic_json__copyassignment.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/kVknQzPMpqjywTpG"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/basic_json__list_init_t.link b/doc/examples/basic_json__list_init_t.link
deleted file mode 100644
index 126f692..0000000
--- a/doc/examples/basic_json__list_init_t.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/yzkjGGzMOESBkCdH"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/basic_json__moveconstructor.link b/doc/examples/basic_json__moveconstructor.link
deleted file mode 100644
index 9318284..0000000
--- a/doc/examples/basic_json__moveconstructor.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/eIOvQiuID2qgxp5u"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/basic_json__nullptr_t.link b/doc/examples/basic_json__nullptr_t.link
deleted file mode 100644
index bcc4e96..0000000
--- a/doc/examples/basic_json__nullptr_t.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/Vm0nR32x6co8rq40"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/basic_json__size_type_basic_json.link b/doc/examples/basic_json__size_type_basic_json.link
deleted file mode 100644
index 6a6742b..0000000
--- a/doc/examples/basic_json__size_type_basic_json.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/w4TtEQzlVyokIrtp"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/basic_json__value.link b/doc/examples/basic_json__value.link
deleted file mode 100644
index f47a80d..0000000
--- a/doc/examples/basic_json__value.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/mNy1nyabOkeHfHGf"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/basic_json__value_ptr.link b/doc/examples/basic_json__value_ptr.link
deleted file mode 100644
index 14d3851..0000000
--- a/doc/examples/basic_json__value_ptr.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/a3H6kpORXgbVXylv"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/basic_json__value_t.link b/doc/examples/basic_json__value_t.link
deleted file mode 100644
index d80f248..0000000
--- a/doc/examples/basic_json__value_t.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/yXZGDwDHH3LOuFIr"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/begin.link b/doc/examples/begin.link
deleted file mode 100644
index 1f59a9b..0000000
--- a/doc/examples/begin.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/fS4kfQG1hmhjMScn"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/binary.cpp b/doc/examples/binary.cpp
new file mode 100644
index 0000000..617ce60
--- /dev/null
+++ b/doc/examples/binary.cpp
@@ -0,0 +1,16 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+ // create a binary vector
+ std::vector<std::uint8_t> vec = {0xCA, 0xFE, 0xBA, 0xBE};
+
+ // create a binary JSON value with subtype 42
+ json j = json::binary(vec, 42);
+
+ // output type and subtype
+ std::cout << "type: " << j.type_name() << ", subtype: " << j.get_binary().subtype() << std::endl;
+}
diff --git a/doc/examples/binary.output b/doc/examples/binary.output
new file mode 100644
index 0000000..74b05d2
--- /dev/null
+++ b/doc/examples/binary.output
@@ -0,0 +1 @@
+type: binary, subtype: 42
diff --git a/doc/examples/binary_t.cpp b/doc/examples/binary_t.cpp
new file mode 100644
index 0000000..bfaee5c
--- /dev/null
+++ b/doc/examples/binary_t.cpp
@@ -0,0 +1,10 @@
+#include <iostream>
+#include <iomanip>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+ std::cout << std::boolalpha << std::is_same<nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>, json::binary_t>::value << std::endl;
+}
diff --git a/doc/examples/binary_t.output b/doc/examples/binary_t.output
new file mode 100644
index 0000000..27ba77d
--- /dev/null
+++ b/doc/examples/binary_t.output
@@ -0,0 +1 @@
+true
diff --git a/doc/examples/boolean_t.cpp b/doc/examples/boolean_t.cpp
new file mode 100644
index 0000000..75b8c99
--- /dev/null
+++ b/doc/examples/boolean_t.cpp
@@ -0,0 +1,10 @@
+#include <iostream>
+#include <iomanip>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+ std::cout << std::boolalpha << std::is_same<bool, json::boolean_t>::value << std::endl;
+}
diff --git a/doc/examples/boolean_t.output b/doc/examples/boolean_t.output
new file mode 100644
index 0000000..27ba77d
--- /dev/null
+++ b/doc/examples/boolean_t.output
@@ -0,0 +1 @@
+true
diff --git a/doc/examples/cbegin.link b/doc/examples/cbegin.link
deleted file mode 100644
index 26ff773..0000000
--- a/doc/examples/cbegin.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/hxcSxCPPLHpZMxjS"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/cend.link b/doc/examples/cend.link
deleted file mode 100644
index a1adb3a..0000000
--- a/doc/examples/cend.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/xbnldrrN05tKIOEv"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/clear.link b/doc/examples/clear.link
deleted file mode 100644
index 0146c18..0000000
--- a/doc/examples/clear.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/gDQPYFxMrvD7RK4z"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/contains.link b/doc/examples/contains.link
deleted file mode 100644
index f57e702..0000000
--- a/doc/examples/contains.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/vVY4F4xKC3v6pG6F"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/contains_json_pointer.link b/doc/examples/contains_json_pointer.link
deleted file mode 100644
index 1648e37..0000000
--- a/doc/examples/contains_json_pointer.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/Q2GTzxF8NA10kVvD"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/count.link b/doc/examples/count.link
deleted file mode 100644
index 2c4c081..0000000
--- a/doc/examples/count.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/6LRjg1bqwchPUoDx"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/crbegin.link b/doc/examples/crbegin.link
deleted file mode 100644
index f7da8d6..0000000
--- a/doc/examples/crbegin.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/JMDd9jiP0flRKJ6C"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/crend.link b/doc/examples/crend.link
deleted file mode 100644
index fc3d145..0000000
--- a/doc/examples/crend.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/HdlqwPk8bDfrZ4AE"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/diagnostics_extended.link b/doc/examples/diagnostics_extended.link
deleted file mode 100644
index 9f10da9..0000000
--- a/doc/examples/diagnostics_extended.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/pbz3ULoJ4maRnV8N"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/diagnostics_standard.link b/doc/examples/diagnostics_standard.link
deleted file mode 100644
index cd0453b..0000000
--- a/doc/examples/diagnostics_standard.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/fWfQhHzG03P6PAcC"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/diff.link b/doc/examples/diff.link
deleted file mode 100644
index 7adb19b..0000000
--- a/doc/examples/diff.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/GHVHgDpT5vx0KMPD"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/dump.link b/doc/examples/dump.link
deleted file mode 100644
index 84d9441..0000000
--- a/doc/examples/dump.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/DyMiKrkKMwd3R7OU"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/emplace.link b/doc/examples/emplace.link
deleted file mode 100644
index 02b41d8..0000000
--- a/doc/examples/emplace.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/p9P3Ph8mdxMON6SY"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/emplace_back.link b/doc/examples/emplace_back.link
deleted file mode 100644
index 7290ca6..0000000
--- a/doc/examples/emplace_back.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/yMxKrJfRedlFygJD"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/empty.link b/doc/examples/empty.link
deleted file mode 100644
index cfe5867..0000000
--- a/doc/examples/empty.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/zaexgkNdH3HYJm8D"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/end.link b/doc/examples/end.link
deleted file mode 100644
index abe8fed..0000000
--- a/doc/examples/end.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/eQ0YI8wWcMIHtBCS"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/erase__IteratorType.link b/doc/examples/erase__IteratorType.link
deleted file mode 100644
index f1d7ba5..0000000
--- a/doc/examples/erase__IteratorType.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/SD62jUgeIuudweZu"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/erase__IteratorType_IteratorType.link b/doc/examples/erase__IteratorType_IteratorType.link
deleted file mode 100644
index 2d6d24c..0000000
--- a/doc/examples/erase__IteratorType_IteratorType.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/gG3bN97HOF04Xw6S"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/erase__key_type.link b/doc/examples/erase__key_type.link
deleted file mode 100644
index df82391..0000000
--- a/doc/examples/erase__key_type.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/WSnobkZJZHUPUIRF"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/erase__size_type.link b/doc/examples/erase__size_type.link
deleted file mode 100644
index a46d527..0000000
--- a/doc/examples/erase__size_type.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/GGoqGtqEzxAsAKnI"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/exception.link b/doc/examples/exception.link
deleted file mode 100644
index 5f40ff4..0000000
--- a/doc/examples/exception.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/vky6QCTCqtUnNVlD"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/find__key_type.link b/doc/examples/find__key_type.link
deleted file mode 100644
index 0bfcc8a..0000000
--- a/doc/examples/find__key_type.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/aQjZSjuuDUxXQCjJ"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/flatten.link b/doc/examples/flatten.link
deleted file mode 100644
index ac836a5..0000000
--- a/doc/examples/flatten.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/moO4IdryeGS8QmKo"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/from_bson.cpp b/doc/examples/from_bson.cpp
index df71dd3..c9d9fdf 100644
--- a/doc/examples/from_bson.cpp
+++ b/doc/examples/from_bson.cpp
@@ -7,11 +7,11 @@
int main()
{
// create byte vector
- std::vector<uint8_t> v = {0x1b, 0x00, 0x00, 0x00, 0x08, 0x63, 0x6f, 0x6d,
- 0x70, 0x61, 0x63, 0x74, 0x00, 0x01, 0x10, 0x73,
- 0x63, 0x68, 0x65, 0x6d, 0x61, 0x00, 0x00, 0x00,
- 0x00, 0x00, 0x00
- };
+ std::vector<std::uint8_t> v = {0x1b, 0x00, 0x00, 0x00, 0x08, 0x63, 0x6f, 0x6d,
+ 0x70, 0x61, 0x63, 0x74, 0x00, 0x01, 0x10, 0x73,
+ 0x63, 0x68, 0x65, 0x6d, 0x61, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00
+ };
// deserialize it with BSON
json j = json::from_bson(v);
diff --git a/doc/examples/from_bson.link b/doc/examples/from_bson.link
deleted file mode 100644
index 08af52b..0000000
--- a/doc/examples/from_bson.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/Q7O1liz5QrgQynqQ"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/from_cbor.cpp b/doc/examples/from_cbor.cpp
index e49987e..e685329 100644
--- a/doc/examples/from_cbor.cpp
+++ b/doc/examples/from_cbor.cpp
@@ -7,10 +7,10 @@
int main()
{
// create byte vector
- std::vector<uint8_t> v = {0xa2, 0x67, 0x63, 0x6f, 0x6d, 0x70, 0x61, 0x63,
- 0x74, 0xf5, 0x66, 0x73, 0x63, 0x68, 0x65, 0x6d,
- 0x61, 0x00
- };
+ std::vector<std::uint8_t> v = {0xa2, 0x67, 0x63, 0x6f, 0x6d, 0x70, 0x61, 0x63,
+ 0x74, 0xf5, 0x66, 0x73, 0x63, 0x68, 0x65, 0x6d,
+ 0x61, 0x00
+ };
// deserialize it with CBOR
json j = json::from_cbor(v);
diff --git a/doc/examples/from_cbor.link b/doc/examples/from_cbor.link
deleted file mode 100644
index bbb578c..0000000
--- a/doc/examples/from_cbor.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/AjdbchxfTsN9PHCL"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/from_msgpack.cpp b/doc/examples/from_msgpack.cpp
index 67fdc45..5c2183f 100644
--- a/doc/examples/from_msgpack.cpp
+++ b/doc/examples/from_msgpack.cpp
@@ -7,10 +7,10 @@
int main()
{
// create byte vector
- std::vector<uint8_t> v = {0x82, 0xa7, 0x63, 0x6f, 0x6d, 0x70, 0x61, 0x63,
- 0x74, 0xc3, 0xa6, 0x73, 0x63, 0x68, 0x65, 0x6d,
- 0x61, 0x00
- };
+ std::vector<std::uint8_t> v = {0x82, 0xa7, 0x63, 0x6f, 0x6d, 0x70, 0x61, 0x63,
+ 0x74, 0xc3, 0xa6, 0x73, 0x63, 0x68, 0x65, 0x6d,
+ 0x61, 0x00
+ };
// deserialize it with MessagePack
json j = json::from_msgpack(v);
diff --git a/doc/examples/from_msgpack.link b/doc/examples/from_msgpack.link
deleted file mode 100644
index 77a5559..0000000
--- a/doc/examples/from_msgpack.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/TdJfkKx0RAH5NB62"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/from_ubjson.cpp b/doc/examples/from_ubjson.cpp
index a84057e..1e85e4e 100644
--- a/doc/examples/from_ubjson.cpp
+++ b/doc/examples/from_ubjson.cpp
@@ -7,10 +7,10 @@
int main()
{
// create byte vector
- std::vector<uint8_t> v = {0x7B, 0x69, 0x07, 0x63, 0x6F, 0x6D, 0x70, 0x61,
- 0x63, 0x74, 0x54, 0x69, 0x06, 0x73, 0x63, 0x68,
- 0x65, 0x6D, 0x61, 0x69, 0x00, 0x7D
- };
+ std::vector<std::uint8_t> v = {0x7B, 0x69, 0x07, 0x63, 0x6F, 0x6D, 0x70, 0x61,
+ 0x63, 0x74, 0x54, 0x69, 0x06, 0x73, 0x63, 0x68,
+ 0x65, 0x6D, 0x61, 0x69, 0x00, 0x7D
+ };
// deserialize it with UBJSON
json j = json::from_ubjson(v);
diff --git a/doc/examples/from_ubjson.link b/doc/examples/from_ubjson.link
deleted file mode 100644
index c5f82cb..0000000
--- a/doc/examples/from_ubjson.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/GG9VzOZh1MDeTSsK"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/front.link b/doc/examples/front.link
deleted file mode 100644
index ab3cc8d..0000000
--- a/doc/examples/front.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/LtqaiI6oRplSg0KI"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/get__PointerType.link b/doc/examples/get__PointerType.link
deleted file mode 100644
index f4a213e..0000000
--- a/doc/examples/get__PointerType.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/ddVSXnbULrNrCbRs"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/get__ValueType_const.link b/doc/examples/get__ValueType_const.link
deleted file mode 100644
index cf444a1..0000000
--- a/doc/examples/get__ValueType_const.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/QjVgxx0bwbKuE9HI"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/get_binary.cpp b/doc/examples/get_binary.cpp
new file mode 100644
index 0000000..617ce60
--- /dev/null
+++ b/doc/examples/get_binary.cpp
@@ -0,0 +1,16 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+ // create a binary vector
+ std::vector<std::uint8_t> vec = {0xCA, 0xFE, 0xBA, 0xBE};
+
+ // create a binary JSON value with subtype 42
+ json j = json::binary(vec, 42);
+
+ // output type and subtype
+ std::cout << "type: " << j.type_name() << ", subtype: " << j.get_binary().subtype() << std::endl;
+}
diff --git a/doc/examples/get_binary.output b/doc/examples/get_binary.output
new file mode 100644
index 0000000..74b05d2
--- /dev/null
+++ b/doc/examples/get_binary.output
@@ -0,0 +1 @@
+type: binary, subtype: 42
diff --git a/doc/examples/get_ptr.link b/doc/examples/get_ptr.link
deleted file mode 100644
index 139fd04..0000000
--- a/doc/examples/get_ptr.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/eA1KrytMlQl1SURe"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/get_ref.link b/doc/examples/get_ref.link
deleted file mode 100644
index 360d002..0000000
--- a/doc/examples/get_ref.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/jVaWWe3kAjKKn99V"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/get_to.link b/doc/examples/get_to.link
deleted file mode 100644
index 5adf0ec..0000000
--- a/doc/examples/get_to.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/UvdMlXdPnXFUq1lJ"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/insert.link b/doc/examples/insert.link
deleted file mode 100644
index 4d74203..0000000
--- a/doc/examples/insert.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/N1nlz2liDCmBn40h"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/insert__count.link b/doc/examples/insert__count.link
deleted file mode 100644
index 49b892b..0000000
--- a/doc/examples/insert__count.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/eoHfSYf04soRkOto"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/insert__ilist.link b/doc/examples/insert__ilist.link
deleted file mode 100644
index ea6760f..0000000
--- a/doc/examples/insert__ilist.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/oNhgDq5ejDl5RyqW"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/insert__range.link b/doc/examples/insert__range.link
deleted file mode 100644
index a2c24a0..0000000
--- a/doc/examples/insert__range.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/LdmbgtdndQw81wQU"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/insert__range_object.link b/doc/examples/insert__range_object.link
deleted file mode 100644
index 9c45c47..0000000
--- a/doc/examples/insert__range_object.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/kp99ButEWpuNxPbq"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/invalid_iterator.link b/doc/examples/invalid_iterator.link
deleted file mode 100644
index 0ef322e..0000000
--- a/doc/examples/invalid_iterator.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/oUdIj3ZSbg7UCIuz"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/is_array.link b/doc/examples/is_array.link
deleted file mode 100644
index dd17ccb..0000000
--- a/doc/examples/is_array.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/2ZgSEJ7UBJ9d4H6b"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/is_binary.link b/doc/examples/is_binary.link
deleted file mode 100644
index 0443f91..0000000
--- a/doc/examples/is_binary.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/to5RDM1vhrDMUfVv"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/is_boolean.link b/doc/examples/is_boolean.link
deleted file mode 100644
index 3e740d6..0000000
--- a/doc/examples/is_boolean.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/20OXaCBWTM1dhFmv"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/is_discarded.link b/doc/examples/is_discarded.link
deleted file mode 100644
index de93aa9..0000000
--- a/doc/examples/is_discarded.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/rTNvfIpTXdFXIe20"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/is_null.link b/doc/examples/is_null.link
deleted file mode 100644
index fbeab6e..0000000
--- a/doc/examples/is_null.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/GCQOJn7fTbm6kPBo"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/is_number.link b/doc/examples/is_number.link
deleted file mode 100644
index b10372a..0000000
--- a/doc/examples/is_number.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/guySOWaTCKiXcueC"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/is_number_float.link b/doc/examples/is_number_float.link
deleted file mode 100644
index f58a47f..0000000
--- a/doc/examples/is_number_float.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/371XB9Jo3cwHDIBc"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/is_number_integer.link b/doc/examples/is_number_integer.link
deleted file mode 100644
index 94a351d..0000000
--- a/doc/examples/is_number_integer.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/qzb1GYNdSbeVRamt"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/is_number_unsigned.link b/doc/examples/is_number_unsigned.link
deleted file mode 100644
index c8bed21..0000000
--- a/doc/examples/is_number_unsigned.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/wcfMOOVBjQMZ6iQi"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/is_object.link b/doc/examples/is_object.link
deleted file mode 100644
index f8240d9..0000000
--- a/doc/examples/is_object.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/I9UET2tNOZLYKvf9"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/is_primitive.link b/doc/examples/is_primitive.link
deleted file mode 100644
index 7f16649..0000000
--- a/doc/examples/is_primitive.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/wdEBCnH75A2tWTPp"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/is_string.link b/doc/examples/is_string.link
deleted file mode 100644
index 999ccd9..0000000
--- a/doc/examples/is_string.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/Lcz1noVRzYcB7vXP"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/is_structured.link b/doc/examples/is_structured.link
deleted file mode 100644
index e54b5c1..0000000
--- a/doc/examples/is_structured.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/1eYTBWunXeo3dEXD"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/items.link b/doc/examples/items.link
deleted file mode 100644
index 61f1356..0000000
--- a/doc/examples/items.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/ScW4gbehjRyjHyPZ"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/iterator_wrapper.cpp b/doc/examples/iterator_wrapper.cpp
index 7ef5bc5..84d3725 100644
--- a/doc/examples/iterator_wrapper.cpp
+++ b/doc/examples/iterator_wrapper.cpp
@@ -9,6 +9,12 @@
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))
{
diff --git a/doc/examples/iterator_wrapper.link b/doc/examples/iterator_wrapper.link
deleted file mode 100644
index 43c08ab..0000000
--- a/doc/examples/iterator_wrapper.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/CwtYFd6vT8GjFFcd"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/json_pointer.link b/doc/examples/json_pointer.link
deleted file mode 100644
index 1d3074f..0000000
--- a/doc/examples/json_pointer.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/FTpanTtjcQQjZc2F"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/json_pointer__back.link b/doc/examples/json_pointer__back.link
deleted file mode 100644
index 0ab9687..0000000
--- a/doc/examples/json_pointer__back.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/qjWp2KSJctelS7Fe"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/json_pointer__empty.link b/doc/examples/json_pointer__empty.link
deleted file mode 100644
index bac9163..0000000
--- a/doc/examples/json_pointer__empty.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/0iAoI04B7iJcG1pW"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/json_pointer__operator_add.link b/doc/examples/json_pointer__operator_add.link
deleted file mode 100644
index 08cfe8c..0000000
--- a/doc/examples/json_pointer__operator_add.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/CL6FBsykrydDhRTF"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/json_pointer__operator_add_binary.link b/doc/examples/json_pointer__operator_add_binary.link
deleted file mode 100644
index b973a40..0000000
--- a/doc/examples/json_pointer__operator_add_binary.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/qbzJzB74w6QVdKPu"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/json_pointer__parent_pointer.link b/doc/examples/json_pointer__parent_pointer.link
deleted file mode 100644
index 63edd5e..0000000
--- a/doc/examples/json_pointer__parent_pointer.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/9yiqfnfuF223zRfi"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/json_pointer__pop_back.link b/doc/examples/json_pointer__pop_back.link
deleted file mode 100644
index 9387294..0000000
--- a/doc/examples/json_pointer__pop_back.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/qgH4LKyHMvQ2KdBq"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/json_pointer__push_back.link b/doc/examples/json_pointer__push_back.link
deleted file mode 100644
index df40229..0000000
--- a/doc/examples/json_pointer__push_back.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/I9NdFeO2a5DmKDNw"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/json_pointer__to_string.link b/doc/examples/json_pointer__to_string.link
deleted file mode 100644
index 51eb093..0000000
--- a/doc/examples/json_pointer__to_string.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/elxv2yYChrwAywYM"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/max_size.link b/doc/examples/max_size.link
deleted file mode 100644
index 52bd366..0000000
--- a/doc/examples/max_size.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/vv8xdYw8TIzBs5pG"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/merge_patch.link b/doc/examples/merge_patch.link
deleted file mode 100644
index 2410989..0000000
--- a/doc/examples/merge_patch.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/gYRJJgjCLw05QxMI"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/meta.link b/doc/examples/meta.link
deleted file mode 100644
index 6955de3..0000000
--- a/doc/examples/meta.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/8KPHbPXQYmIYmHVl"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/meta.output b/doc/examples/meta.output
index 9a18fab..c35a320 100644
--- a/doc/examples/meta.output
+++ b/doc/examples/meta.output
@@ -2,16 +2,16 @@
"compiler": {
"c++": "201103",
"family": "clang",
- "version": "13.0.0 (clang-1300.0.29.3)"
+ "version": "13.0.0 (clang-1300.0.29.30)"
},
- "copyright": "(C) 2013-2021 Niels Lohmann",
+ "copyright": "(C) 2013-2022 Niels Lohmann",
"name": "JSON for Modern C++",
"platform": "apple",
"url": "https://github.com/nlohmann/json",
"version": {
"major": 3,
"minor": 10,
- "patch": 4,
- "string": "3.10.4"
+ "patch": 5,
+ "string": "3.10.5"
}
}
diff --git a/doc/examples/number_float_t.cpp b/doc/examples/number_float_t.cpp
new file mode 100644
index 0000000..21211dc
--- /dev/null
+++ b/doc/examples/number_float_t.cpp
@@ -0,0 +1,10 @@
+#include <iostream>
+#include <iomanip>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+ std::cout << std::boolalpha << std::is_same<double, json::number_float_t>::value << std::endl;
+}
diff --git a/doc/examples/number_float_t.output b/doc/examples/number_float_t.output
new file mode 100644
index 0000000..27ba77d
--- /dev/null
+++ b/doc/examples/number_float_t.output
@@ -0,0 +1 @@
+true
diff --git a/doc/examples/number_integer_t.cpp b/doc/examples/number_integer_t.cpp
new file mode 100644
index 0000000..75ee57b
--- /dev/null
+++ b/doc/examples/number_integer_t.cpp
@@ -0,0 +1,10 @@
+#include <iostream>
+#include <iomanip>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+ std::cout << std::boolalpha << std::is_same<std::int64_t, json::number_integer_t>::value << std::endl;
+}
diff --git a/doc/examples/number_integer_t.output b/doc/examples/number_integer_t.output
new file mode 100644
index 0000000..27ba77d
--- /dev/null
+++ b/doc/examples/number_integer_t.output
@@ -0,0 +1 @@
+true
diff --git a/doc/examples/number_unsigned_t.cpp b/doc/examples/number_unsigned_t.cpp
new file mode 100644
index 0000000..ff3b86d
--- /dev/null
+++ b/doc/examples/number_unsigned_t.cpp
@@ -0,0 +1,10 @@
+#include <iostream>
+#include <iomanip>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+ std::cout << std::boolalpha << std::is_same<std::uint64_t, json::number_unsigned_t>::value << std::endl;
+}
diff --git a/doc/examples/number_unsigned_t.output b/doc/examples/number_unsigned_t.output
new file mode 100644
index 0000000..27ba77d
--- /dev/null
+++ b/doc/examples/number_unsigned_t.output
@@ -0,0 +1 @@
+true
diff --git a/doc/examples/object.link b/doc/examples/object.link
deleted file mode 100644
index 322128e..0000000
--- a/doc/examples/object.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/6FmKs5R3LbpOnwu5"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/object_t.cpp b/doc/examples/object_t.cpp
new file mode 100644
index 0000000..85cfa3e
--- /dev/null
+++ b/doc/examples/object_t.cpp
@@ -0,0 +1,10 @@
+#include <iostream>
+#include <iomanip>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+ std::cout << std::boolalpha << std::is_same<std::map<json::string_t, json>, json::object_t>::value << std::endl;
+}
diff --git a/doc/examples/object_t.output b/doc/examples/object_t.output
new file mode 100644
index 0000000..27ba77d
--- /dev/null
+++ b/doc/examples/object_t.output
@@ -0,0 +1 @@
+true
diff --git a/doc/examples/operator__ValueType.link b/doc/examples/operator__ValueType.link
deleted file mode 100644
index e4db023..0000000
--- a/doc/examples/operator__ValueType.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/JfMIJiDcpdQUL8Zf"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/operator__equal.link b/doc/examples/operator__equal.link
deleted file mode 100644
index 966c4f7..0000000
--- a/doc/examples/operator__equal.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/LNp7NushnJK4Qdbh"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/operator__equal__nullptr_t.link b/doc/examples/operator__equal__nullptr_t.link
deleted file mode 100644
index 5321622..0000000
--- a/doc/examples/operator__equal__nullptr_t.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/s62P9RmAe0bB7jVS"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/operator__greater.link b/doc/examples/operator__greater.link
deleted file mode 100644
index b52b4b8..0000000
--- a/doc/examples/operator__greater.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/U2Y3DKDAI3QVV6WY"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/operator__greaterequal.link b/doc/examples/operator__greaterequal.link
deleted file mode 100644
index 7b9b42c..0000000
--- a/doc/examples/operator__greaterequal.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/rPkPEfJCs9deVcDh"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/operator__less.link b/doc/examples/operator__less.link
deleted file mode 100644
index 96d69ee..0000000
--- a/doc/examples/operator__less.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/uVaxGsyeyMBSgFmD"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/operator__lessequal.link b/doc/examples/operator__lessequal.link
deleted file mode 100644
index 750c6fc..0000000
--- a/doc/examples/operator__lessequal.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/XuFcFYlyCUhSZOMh"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/operator__notequal.link b/doc/examples/operator__notequal.link
deleted file mode 100644
index bb094c4..0000000
--- a/doc/examples/operator__notequal.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/zmDAeDnNWMEipr0f"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/operator__notequal__nullptr_t.link b/doc/examples/operator__notequal__nullptr_t.link
deleted file mode 100644
index 3a013c2..0000000
--- a/doc/examples/operator__notequal__nullptr_t.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/FI3oaFMYKW21XWOx"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/operator__value_t.link b/doc/examples/operator__value_t.link
deleted file mode 100644
index 71cb214..0000000
--- a/doc/examples/operator__value_t.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/zrh9lwsqcXTRxKAB"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/operator_deserialize.link b/doc/examples/operator_deserialize.link
deleted file mode 100644
index 2e4f728..0000000
--- a/doc/examples/operator_deserialize.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/u7H6MXaycH9x6z2b"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/operator_literal_json.cpp b/doc/examples/operator_literal_json.cpp
new file mode 100644
index 0000000..2ec008e
--- /dev/null
+++ b/doc/examples/operator_literal_json.cpp
@@ -0,0 +1,12 @@
+#include <iostream>
+#include <iomanip>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+ json j = R"( {"hello": "world", "answer": 42} )"_json;
+
+ std::cout << std::setw(2) << j << '\n';
+}
diff --git a/doc/examples/operator_literal_json.output b/doc/examples/operator_literal_json.output
new file mode 100644
index 0000000..6c0a7b3
--- /dev/null
+++ b/doc/examples/operator_literal_json.output
@@ -0,0 +1,4 @@
+{
+ "answer": 42,
+ "hello": "world"
+}
diff --git a/doc/examples/operator_literal_json_pointer.cpp b/doc/examples/operator_literal_json_pointer.cpp
new file mode 100644
index 0000000..bbdb974
--- /dev/null
+++ b/doc/examples/operator_literal_json_pointer.cpp
@@ -0,0 +1,13 @@
+#include <iostream>
+#include <iomanip>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+ json j = R"( {"hello": "world", "answer": 42} )"_json;
+ auto val = j["/hello"_json_pointer];
+
+ std::cout << std::setw(2) << val << '\n';
+}
diff --git a/doc/examples/operator_literal_json_pointer.output b/doc/examples/operator_literal_json_pointer.output
new file mode 100644
index 0000000..b0fcd34
--- /dev/null
+++ b/doc/examples/operator_literal_json_pointer.output
@@ -0,0 +1 @@
+"world"
diff --git a/doc/examples/operator_serialize.link b/doc/examples/operator_serialize.link
deleted file mode 100644
index f6d157e..0000000
--- a/doc/examples/operator_serialize.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/XLOzBknv2FczmATS"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/operatorarray__key_type.link b/doc/examples/operatorarray__key_type.link
deleted file mode 100644
index e03051d..0000000
--- a/doc/examples/operatorarray__key_type.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/OpoeAt1xGB4xduPx"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/operatorarray__key_type_const.link b/doc/examples/operatorarray__key_type_const.link
deleted file mode 100644
index a902338..0000000
--- a/doc/examples/operatorarray__key_type_const.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/csxHXR7rMgsx8lD0"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/operatorarray__size_type.link b/doc/examples/operatorarray__size_type.link
deleted file mode 100644
index 73b8b16..0000000
--- a/doc/examples/operatorarray__size_type.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/FqlufeB2ykspIWMX"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/operatorarray__size_type_const.link b/doc/examples/operatorarray__size_type_const.link
deleted file mode 100644
index 3f23018..0000000
--- a/doc/examples/operatorarray__size_type_const.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/ZdkclPKi4eV5qHAO"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/operatorjson_pointer.link b/doc/examples/operatorjson_pointer.link
deleted file mode 100644
index fa7aecb..0000000
--- a/doc/examples/operatorjson_pointer.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/Ip5D5sYs4lFNTeQk"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/operatorjson_pointer_const.link b/doc/examples/operatorjson_pointer_const.link
deleted file mode 100644
index eb01e1f..0000000
--- a/doc/examples/operatorjson_pointer_const.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/cgeqOQ3Ed4B5H36y"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/ordered_map.cpp b/doc/examples/ordered_map.cpp
new file mode 100644
index 0000000..dcc60cb
--- /dev/null
+++ b/doc/examples/ordered_map.cpp
@@ -0,0 +1,43 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+// simple output function
+template<typename Map>
+void output(const char* prefix, const Map& m)
+{
+ std::cout << prefix << " = { ";
+ for (auto& element : m)
+ {
+ std::cout << element.first << ":" << element.second << ' ';
+ }
+ std::cout << "}" << std::endl;
+}
+
+int main()
+{
+ // create and fill two maps
+ nlohmann::ordered_map<std::string, std::string> m_ordered;
+ m_ordered["one"] = "eins";
+ m_ordered["two"] = "zwei";
+ m_ordered["three"] = "drei";
+
+ std::map<std::string, std::string> m_std;
+ m_std["one"] = "eins";
+ m_std["two"] = "zwei";
+ m_std["three"] = "drei";
+
+ // output: m_ordered is ordered by insertion order, m_std is ordered by key
+ output("m_ordered", m_ordered);
+ output("m_std", m_std);
+
+ // erase and re-add "one" key
+ m_ordered.erase("one");
+ m_ordered["one"] = "eins";
+
+ m_std.erase("one");
+ m_std["one"] = "eins";
+
+ // output: m_ordered shows newly added key at the end; m_std is again ordered by key
+ output("m_ordered", m_ordered);
+ output("m_std", m_std);
+}
diff --git a/doc/examples/ordered_map.output b/doc/examples/ordered_map.output
new file mode 100644
index 0000000..a4ffc45
--- /dev/null
+++ b/doc/examples/ordered_map.output
@@ -0,0 +1,4 @@
+m_ordered = { one:eins two:zwei three:drei }
+m_std = { one:eins three:drei two:zwei }
+m_ordered = { two:zwei three:drei one:eins }
+m_std = { one:eins three:drei two:zwei }
diff --git a/doc/examples/other_error.link b/doc/examples/other_error.link
deleted file mode 100644
index f542efd..0000000
--- a/doc/examples/other_error.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/arzWNZW2mX7NN4hn"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/out_of_range.link b/doc/examples/out_of_range.link
deleted file mode 100644
index 25833f3..0000000
--- a/doc/examples/out_of_range.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/N1cH6xfYoW268tU1"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/parse__allow_exceptions.link b/doc/examples/parse__allow_exceptions.link
deleted file mode 100644
index 386dfe8..0000000
--- a/doc/examples/parse__allow_exceptions.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/2TsG4VSg87HsRQC9"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/parse__array__parser_callback_t.link b/doc/examples/parse__array__parser_callback_t.link
deleted file mode 100644
index cdecb14..0000000
--- a/doc/examples/parse__array__parser_callback_t.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/GQUBprVlhQf1GAn0"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/parse__contiguouscontainer__parser_callback_t.cpp b/doc/examples/parse__contiguouscontainer__parser_callback_t.cpp
index 14cfa25..6eb409b 100644
--- a/doc/examples/parse__contiguouscontainer__parser_callback_t.cpp
+++ b/doc/examples/parse__contiguouscontainer__parser_callback_t.cpp
@@ -7,7 +7,7 @@
int main()
{
// a JSON text given as std::vector
- std::vector<uint8_t> text = {'[', '1', ',', '2', ',', '3', ']', '\0'};
+ std::vector<std::uint8_t> text = {'[', '1', ',', '2', ',', '3', ']', '\0'};
// parse and serialize JSON
json j_complete = json::parse(text);
diff --git a/doc/examples/parse__contiguouscontainer__parser_callback_t.link b/doc/examples/parse__contiguouscontainer__parser_callback_t.link
deleted file mode 100644
index c681b8c..0000000
--- a/doc/examples/parse__contiguouscontainer__parser_callback_t.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/vNtAnvMvjPVNbQWr"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/parse__istream__parser_callback_t.link b/doc/examples/parse__istream__parser_callback_t.link
deleted file mode 100644
index 21118db..0000000
--- a/doc/examples/parse__istream__parser_callback_t.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/oVoHIptkIrU5Obmp"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/parse__iterator_pair.cpp b/doc/examples/parse__iterator_pair.cpp
new file mode 100644
index 0000000..d0c30c1
--- /dev/null
+++ b/doc/examples/parse__iterator_pair.cpp
@@ -0,0 +1,15 @@
+#include <iostream>
+#include <iomanip>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+ // a JSON text given an input with other values
+ std::vector<std::uint8_t> input = {'[', '1', ',', '2', ',', '3', ']', 'o', 't', 'h', 'e', 'r'};
+
+ // parse and serialize JSON
+ json j_complete = json::parse(input.begin(), input.begin() + 7);
+ std::cout << std::setw(4) << j_complete << "\n\n";
+}
diff --git a/doc/examples/parse__iterator_pair.link b/doc/examples/parse__iterator_pair.link
new file mode 100644
index 0000000..f464e54
--- /dev/null
+++ b/doc/examples/parse__iterator_pair.link
@@ -0,0 +1 @@
+<a target="_blank" href="https://wandbox.org/permlink/hUJYo1HWmfTBLMGn"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/parse__iteratortype__parser_callback_t.output b/doc/examples/parse__iterator_pair.output
similarity index 100%
rename from doc/examples/parse__iteratortype__parser_callback_t.output
rename to doc/examples/parse__iterator_pair.output
diff --git a/doc/examples/parse__iteratortype__parser_callback_t.cpp b/doc/examples/parse__iteratortype__parser_callback_t.cpp
deleted file mode 100644
index 1b5e23d..0000000
--- a/doc/examples/parse__iteratortype__parser_callback_t.cpp
+++ /dev/null
@@ -1,15 +0,0 @@
-#include <iostream>
-#include <iomanip>
-#include <nlohmann/json.hpp>
-
-using json = nlohmann::json;
-
-int main()
-{
- // a JSON text given as std::vector
- std::vector<uint8_t> text = {'[', '1', ',', '2', ',', '3', ']', '\0'};
-
- // parse and serialize JSON
- json j_complete = json::parse(text.begin(), text.end());
- std::cout << std::setw(4) << j_complete << "\n\n";
-}
diff --git a/doc/examples/parse__iteratortype__parser_callback_t.link b/doc/examples/parse__iteratortype__parser_callback_t.link
deleted file mode 100644
index d12ba20..0000000
--- a/doc/examples/parse__iteratortype__parser_callback_t.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/9CXgX4XrjlHDszdi"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/parse__pointers.cpp b/doc/examples/parse__pointers.cpp
new file mode 100644
index 0000000..a5a16ee
--- /dev/null
+++ b/doc/examples/parse__pointers.cpp
@@ -0,0 +1,15 @@
+#include <iostream>
+#include <iomanip>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+ // a JSON text given as string that is not null-terminated
+ const char* ptr = "[1,2,3]another value";
+
+ // parse and serialize JSON
+ json j_complete = json::parse(ptr, ptr + 7);
+ std::cout << std::setw(4) << j_complete << "\n\n";
+}
diff --git a/doc/examples/parse__pointers.link b/doc/examples/parse__pointers.link
new file mode 100644
index 0000000..9a93ef1
--- /dev/null
+++ b/doc/examples/parse__pointers.link
@@ -0,0 +1 @@
+<a target="_blank" href="https://wandbox.org/permlink/AWbpa8e1xRV3y4MM"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/parse__iteratortype__parser_callback_t.output b/doc/examples/parse__pointers.output
similarity index 100%
copy from doc/examples/parse__iteratortype__parser_callback_t.output
copy to doc/examples/parse__pointers.output
diff --git a/doc/examples/parse__string__parser_callback_t.link b/doc/examples/parse__string__parser_callback_t.link
deleted file mode 100644
index 2d24e2e..0000000
--- a/doc/examples/parse__string__parser_callback_t.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/vDAnSEYiVgIdK3sK"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/parse_error.link b/doc/examples/parse_error.link
deleted file mode 100644
index f3c0da7..0000000
--- a/doc/examples/parse_error.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/ZkoSrF7OOVUQf4Db"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/patch.link b/doc/examples/patch.link
deleted file mode 100644
index d9b370a..0000000
--- a/doc/examples/patch.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/GrqC402vqxttNYPl"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/push_back.link b/doc/examples/push_back.link
deleted file mode 100644
index b89d5c6..0000000
--- a/doc/examples/push_back.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/s6FfaomLrs4KRfPj"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/push_back__initializer_list.link b/doc/examples/push_back__initializer_list.link
deleted file mode 100644
index 4e57e93..0000000
--- a/doc/examples/push_back__initializer_list.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/mbZlrIGr8Rsdjeow"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/push_back__object_t__value.link b/doc/examples/push_back__object_t__value.link
deleted file mode 100644
index 6e0cf7b..0000000
--- a/doc/examples/push_back__object_t__value.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/AdA8l0WpxC6GiE5E"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/rbegin.link b/doc/examples/rbegin.link
deleted file mode 100644
index 06beb46..0000000
--- a/doc/examples/rbegin.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/VrEpD8lD8TTaI0NX"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/rend.link b/doc/examples/rend.link
deleted file mode 100644
index bf8e33d..0000000
--- a/doc/examples/rend.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/JwrsWR45xOFouUXN"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/sax_parse.link b/doc/examples/sax_parse.link
deleted file mode 100644
index 8bab127..0000000
--- a/doc/examples/sax_parse.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/QaneqALPjiPk81vJ"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/size.link b/doc/examples/size.link
deleted file mode 100644
index 31f00ca..0000000
--- a/doc/examples/size.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/mvJT2pbloHlkrl6r"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/std_hash.cpp b/doc/examples/std_hash.cpp
new file mode 100644
index 0000000..eee0fad
--- /dev/null
+++ b/doc/examples/std_hash.cpp
@@ -0,0 +1,18 @@
+#include <iostream>
+#include <iomanip>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+ std::cout << "hash(null) = " << std::hash<json> {}(json(nullptr)) << '\n'
+ << "hash(false) = " << std::hash<json> {}(json(false)) << '\n'
+ << "hash(0) = " << std::hash<json> {}(json(0)) << '\n'
+ << "hash(0U) = " << std::hash<json> {}(json(0U)) << '\n'
+ << "hash(\"\") = " << std::hash<json> {}(json("")) << '\n'
+ << "hash({}) = " << std::hash<json> {}(json::object()) << '\n'
+ << "hash([]) = " << std::hash<json> {}(json::array()) << '\n'
+ << "hash({\"hello\": \"world\"}) = " << std::hash<json> {}("{\"hello\": \"world\"}"_json)
+ << std::endl;
+}
diff --git a/doc/examples/std_hash.output b/doc/examples/std_hash.output
new file mode 100644
index 0000000..d1b1b48
--- /dev/null
+++ b/doc/examples/std_hash.output
@@ -0,0 +1,8 @@
+hash(null) = 2654435769
+hash(false) = 2654436030
+hash(0) = 2654436095
+hash(0U) = 2654436156
+hash("") = 11160318156688833227
+hash({}) = 2654435832
+hash([]) = 2654435899
+hash({"hello": "world"}) = 3701319991624763853
diff --git a/doc/examples/std_swap.cpp b/doc/examples/std_swap.cpp
new file mode 100644
index 0000000..36ab3ce
--- /dev/null
+++ b/doc/examples/std_swap.cpp
@@ -0,0 +1,19 @@
+#include <iostream>
+#include <iomanip>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+ // create JSON values
+ json j1 = {{"one", 1}, {"two", 2}};
+ json j2 = {1, 2, 4, 8, 16};
+
+ std::cout << "j1 = " << j1 << " | j2 = " << j2 << '\n';
+
+ // swap values
+ std::swap(j1, j2);
+
+ std::cout << "j1 = " << j1 << " | j2 = " << j2 << std::endl;
+}
diff --git a/doc/examples/std_swap.output b/doc/examples/std_swap.output
new file mode 100644
index 0000000..5ae6db7
--- /dev/null
+++ b/doc/examples/std_swap.output
@@ -0,0 +1,2 @@
+j1 = {"one":1,"two":2} | j2 = [1,2,4,8,16]
+j1 = [1,2,4,8,16] | j2 = {"one":1,"two":2}
diff --git a/doc/examples/string_t.cpp b/doc/examples/string_t.cpp
new file mode 100644
index 0000000..77a9ea4
--- /dev/null
+++ b/doc/examples/string_t.cpp
@@ -0,0 +1,10 @@
+#include <iostream>
+#include <iomanip>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+ std::cout << std::boolalpha << std::is_same<std::string, json::string_t>::value << std::endl;
+}
diff --git a/doc/examples/string_t.output b/doc/examples/string_t.output
new file mode 100644
index 0000000..27ba77d
--- /dev/null
+++ b/doc/examples/string_t.output
@@ -0,0 +1 @@
+true
diff --git a/doc/examples/swap__array_t.link b/doc/examples/swap__array_t.link
deleted file mode 100644
index 7593790..0000000
--- a/doc/examples/swap__array_t.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/c0nkTOokPyL8J1JL"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/swap__binary_t.link b/doc/examples/swap__binary_t.link
deleted file mode 100644
index f035a71..0000000
--- a/doc/examples/swap__binary_t.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/OD1Yaew9vlzMYxmX"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/swap__object_t.link b/doc/examples/swap__object_t.link
deleted file mode 100644
index 45b0499..0000000
--- a/doc/examples/swap__object_t.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/IcxTHxey5qxGeAy2"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/swap__reference.link b/doc/examples/swap__reference.link
deleted file mode 100644
index f056ec4..0000000
--- a/doc/examples/swap__reference.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/WL9q27mBi3aXi5Pa"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/swap__string_t.link b/doc/examples/swap__string_t.link
deleted file mode 100644
index 9b00374..0000000
--- a/doc/examples/swap__string_t.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/SyMx0P688ApRQzMt"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/to_bson.cpp b/doc/examples/to_bson.cpp
index fd2884f..2dd4487 100644
--- a/doc/examples/to_bson.cpp
+++ b/doc/examples/to_bson.cpp
@@ -10,7 +10,7 @@
json j = R"({"compact": true, "schema": 0})"_json;
// serialize it to BSON
- std::vector<uint8_t> v = json::to_bson(j);
+ std::vector<std::uint8_t> v = json::to_bson(j);
// print the vector content
for (auto& byte : v)
diff --git a/doc/examples/to_bson.link b/doc/examples/to_bson.link
deleted file mode 100644
index 3bad4a1..0000000
--- a/doc/examples/to_bson.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/hrN6v0tVSMVw8ME9"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/to_cbor.cpp b/doc/examples/to_cbor.cpp
index 1237ca8..3d85deb 100644
--- a/doc/examples/to_cbor.cpp
+++ b/doc/examples/to_cbor.cpp
@@ -10,7 +10,7 @@
json j = R"({"compact": true, "schema": 0})"_json;
// serialize it to CBOR
- std::vector<uint8_t> v = json::to_cbor(j);
+ std::vector<std::uint8_t> v = json::to_cbor(j);
// print the vector content
for (auto& byte : v)
diff --git a/doc/examples/to_cbor.link b/doc/examples/to_cbor.link
deleted file mode 100644
index efac9b0..0000000
--- a/doc/examples/to_cbor.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/r2Sb8yJjRQG98WkO"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/to_msgpack.cpp b/doc/examples/to_msgpack.cpp
index 99cc9ed..76bb22f 100644
--- a/doc/examples/to_msgpack.cpp
+++ b/doc/examples/to_msgpack.cpp
@@ -10,7 +10,7 @@
json j = R"({"compact": true, "schema": 0})"_json;
// serialize it to MessagePack
- std::vector<uint8_t> v = json::to_msgpack(j);
+ std::vector<std::uint8_t> v = json::to_msgpack(j);
// print the vector content
for (auto& byte : v)
diff --git a/doc/examples/to_msgpack.link b/doc/examples/to_msgpack.link
deleted file mode 100644
index 4c7a078..0000000
--- a/doc/examples/to_msgpack.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/HtOtIvPkgOy5JVHb"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/to_string.cpp b/doc/examples/to_string.cpp
new file mode 100644
index 0000000..ee44283
--- /dev/null
+++ b/doc/examples/to_string.cpp
@@ -0,0 +1,20 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+using std::to_string;
+
+int main()
+{
+ // create values
+ json j = {{"one", 1}, {"two", 2}};
+ int i = 42;
+
+ // use ADL to select best to_string function
+ auto j_str = to_string(j); // calling nlohmann::to_string
+ auto i_str = to_string(i); // calling std::to_string
+
+ // serialize without indentation
+ std::cout << j_str << "\n\n"
+ << i_str << std::endl;
+}
diff --git a/doc/examples/to_string.output b/doc/examples/to_string.output
new file mode 100644
index 0000000..b261f35
--- /dev/null
+++ b/doc/examples/to_string.output
@@ -0,0 +1,3 @@
+{"one":1,"two":2}
+
+42
diff --git a/doc/examples/to_ubjson.cpp b/doc/examples/to_ubjson.cpp
index 06b2abb..2329cdd 100644
--- a/doc/examples/to_ubjson.cpp
+++ b/doc/examples/to_ubjson.cpp
@@ -23,7 +23,7 @@
json j = R"({"compact": true, "schema": false})"_json;
// serialize it to UBJSON
- std::vector<uint8_t> v = json::to_ubjson(j);
+ std::vector<std::uint8_t> v = json::to_ubjson(j);
// print the vector content
for (auto& byte : v)
@@ -36,11 +36,11 @@
json array = {1, 2, 3, 4, 5, 6, 7, 8};
// serialize it to UBJSON using default representation
- std::vector<uint8_t> v_array = json::to_ubjson(array);
+ std::vector<std::uint8_t> v_array = json::to_ubjson(array);
// serialize it to UBJSON using size optimization
- std::vector<uint8_t> v_array_size = json::to_ubjson(array, true);
+ std::vector<std::uint8_t> v_array_size = json::to_ubjson(array, true);
// serialize it to UBJSON using type optimization
- std::vector<uint8_t> v_array_size_and_type = json::to_ubjson(array, true, true);
+ std::vector<std::uint8_t> v_array_size_and_type = json::to_ubjson(array, true, true);
// print the vector contents
for (auto& byte : v_array)
diff --git a/doc/examples/to_ubjson.link b/doc/examples/to_ubjson.link
deleted file mode 100644
index 996e19d..0000000
--- a/doc/examples/to_ubjson.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/pc1zxKaned8pvvXJ"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/type.link b/doc/examples/type.link
deleted file mode 100644
index 746aaa6..0000000
--- a/doc/examples/type.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/0s7Ewz3zhZQfWzjR"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/type_error.link b/doc/examples/type_error.link
deleted file mode 100644
index d054b5c..0000000
--- a/doc/examples/type_error.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/vBuKAAPU80iMcXQC"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/type_name.link b/doc/examples/type_name.link
deleted file mode 100644
index c0c5559..0000000
--- a/doc/examples/type_name.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/hOsdmb4wLEoYc4xh"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/unflatten.link b/doc/examples/unflatten.link
deleted file mode 100644
index 0d1be78..0000000
--- a/doc/examples/unflatten.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/x5rihodknargY77f"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/update.cpp b/doc/examples/update.cpp
index fecdae7..8f8b3bf 100644
--- a/doc/examples/update.cpp
+++ b/doc/examples/update.cpp
@@ -7,12 +7,17 @@
int main()
{
// create two JSON objects
- json o1 = R"( {"color": "red", "price": 17.99} )"_json;
- json o2 = R"( {"color": "blue", "speed": 100} )"_json;
+ json o1 = R"( {"color": "red", "price": 17.99, "names": {"de": "Flugzeug"}} )"_json;
+ json o2 = R"( {"color": "blue", "speed": 100, "names": {"en": "plane"}} )"_json;
+ json o3 = o1;
- // add all keys from o2 to o1 (updating "color")
+ // add all keys from o2 to o1 (updating "color", replacing "names")
o1.update(o2);
- // output updated object o1
+ // add all keys from o2 to o1 (updating "color", merging "names")
+ o3.update(o2, true);
+
+ // output updated object o1 and o3
std::cout << std::setw(2) << o1 << '\n';
+ std::cout << std::setw(2) << o3 << '\n';
}
diff --git a/doc/examples/update.link b/doc/examples/update.link
deleted file mode 100644
index 2728616..0000000
--- a/doc/examples/update.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/KZsjDe1v3arweQPv"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/update.output b/doc/examples/update.output
index 69f0965..c35a745 100644
--- a/doc/examples/update.output
+++ b/doc/examples/update.output
@@ -1,5 +1,17 @@
{
"color": "blue",
+ "names": {
+ "en": "plane"
+ },
+ "price": 17.99,
+ "speed": 100
+}
+{
+ "color": "blue",
+ "names": {
+ "de": "Flugzeug",
+ "en": "plane"
+ },
"price": 17.99,
"speed": 100
}
diff --git a/doc/examples/update__range.cpp b/doc/examples/update__range.cpp
index 9f3e521..98a3904 100644
--- a/doc/examples/update__range.cpp
+++ b/doc/examples/update__range.cpp
@@ -7,12 +7,17 @@
int main()
{
// create two JSON objects
- json o1 = R"( {"color": "red", "price": 17.99} )"_json;
- json o2 = R"( {"color": "blue", "speed": 100} )"_json;
+ json o1 = R"( {"color": "red", "price": 17.99, "names": {"de": "Flugzeug"}} )"_json;
+ json o2 = R"( {"color": "blue", "speed": 100, "names": {"en": "plane"}} )"_json;
+ json o3 = o1;
- // add all keys from o2 to o1 (updating "color")
+ // add all keys from o2 to o1 (updating "color", replacing "names")
o1.update(o2.begin(), o2.end());
- // output updated object o1
+ // add all keys from o2 to o1 (updating "color", merging "names")
+ o3.update(o2.begin(), o2.end(), true);
+
+ // output updated object o1 and o3
std::cout << std::setw(2) << o1 << '\n';
+ std::cout << std::setw(2) << o3 << '\n';
}
diff --git a/doc/examples/update__range.link b/doc/examples/update__range.link
deleted file mode 100644
index 562ebf0..0000000
--- a/doc/examples/update__range.link
+++ /dev/null
@@ -1 +0,0 @@
-<a target="_blank" href="https://wandbox.org/permlink/O3XNqD5PQ6SyQ9vS"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/update__range.output b/doc/examples/update__range.output
index 69f0965..c35a745 100644
--- a/doc/examples/update__range.output
+++ b/doc/examples/update__range.output
@@ -1,5 +1,17 @@
{
"color": "blue",
+ "names": {
+ "en": "plane"
+ },
+ "price": 17.99,
+ "speed": 100
+}
+{
+ "color": "blue",
+ "names": {
+ "de": "Flugzeug",
+ "en": "plane"
+ },
"price": 17.99,
"speed": 100
}
diff --git a/doc/index.md b/doc/index.md
index 6ab716f..cb782e7 100644
--- a/doc/index.md
+++ b/doc/index.md
@@ -327,9 +327,9 @@
</tr>
</table>
-@copyright Copyright © 2013-2021 Niels Lohmann. The code is licensed under the [MIT License](http://opensource.org/licenses/MIT).
+@copyright Copyright © 2013-2022 Niels Lohmann. The code is licensed under the [MIT License](http://opensource.org/licenses/MIT).
@author [Niels Lohmann](http://nlohmann.me)
@see https://github.com/nlohmann/json to download the source code
-@version 3.10.4
+@version 3.10.5
diff --git a/doc/json.gif b/doc/json.gif
index 67eaf7f..9f0d8a2 100644
--- a/doc/json.gif
+++ b/doc/json.gif
Binary files differ
diff --git a/doc/mkdocs/Makefile b/doc/mkdocs/Makefile
index 1f3ccf5..3d3d5e7 100644
--- a/doc/mkdocs/Makefile
+++ b/doc/mkdocs/Makefile
@@ -7,18 +7,16 @@
# create files that are not versioned inside the mkdocs folder
prepare_files: clean
- # build Doxygen
- $(MAKE) -C ..
# create subfolders
- mkdir docs/images docs/examples
+ mkdir docs/examples
# copy images
- cp -vr ../json.gif ../images/range-begin-end.svg ../images/range-rbegin-rend.svg ../images/callback_events.png ../images/json_syntax_number.png docs/images
+ cp -vr ../json.gif docs/images
# copy examples
cp -vr ../examples/*.cpp ../examples/*.output docs/examples
# clean subfolders
clean:
- rm -fr docs/images docs/examples
+ rm -fr docs/images/json.gif docs/examples
# publish site to GitHub pages
publish: prepare_files
@@ -27,6 +25,7 @@
# install a Python virtual environment
install_venv: requirements.txt
python3 -mvenv venv
+ venv/bin/pip install wheel
venv/bin/pip install -r requirements.txt
# uninstall the virtual environment
diff --git a/doc/mkdocs/docs/api/adl_serializer/from_json.md b/doc/mkdocs/docs/api/adl_serializer/from_json.md
new file mode 100644
index 0000000..7657855
--- /dev/null
+++ b/doc/mkdocs/docs/api/adl_serializer/from_json.md
@@ -0,0 +1,41 @@
+# <small>nlohmann::adl_serializer::</small>from_json
+
+```cpp
+// (1)
+template<typename BasicJsonType, typename TargetType = ValueType>
+static auto from_json(BasicJsonType && j, TargetType& val) noexcept(
+ noexcept(::nlohmann::from_json(std::forward<BasicJsonType>(j), val)))
+-> decltype(::nlohmann::from_json(std::forward<BasicJsonType>(j), val), void())
+
+// (2)
+template<typename BasicJsonType, typename TargetType = ValueType>
+static auto from_json(BasicJsonType && j) noexcept(
+noexcept(::nlohmann::from_json(std::forward<BasicJsonType>(j), detail::identity_tag<TargetType> {})))
+-> decltype(::nlohmann::from_json(std::forward<BasicJsonType>(j), detail::identity_tag<TargetType> {}))
+```
+
+This function is usually called by the [`get()`](../basic_json/get.md) function of the
+[basic_json](../basic_json) class (either explicit or via conversion operators).
+
+1. This function is chosen for default-constructible value types.
+2. This function is chosen for value types which are not default-constructible.
+
+## Parameters
+
+`j` (in)
+: JSON value to read from
+
+`val` (out)
+: value to write to
+
+## Return value
+
+Copy of the JSON value, converted to `ValueType`
+
+!!! note
+
+ This documentation page is a stub.
+
+## Version history
+
+- Added in version 2.1.0.
diff --git a/doc/mkdocs/docs/api/adl_serializer.md b/doc/mkdocs/docs/api/adl_serializer/index.md
similarity index 74%
rename from doc/mkdocs/docs/api/adl_serializer.md
rename to doc/mkdocs/docs/api/adl_serializer/index.md
index 7b79747..95f35cd 100644
--- a/doc/mkdocs/docs/api/adl_serializer.md
+++ b/doc/mkdocs/docs/api/adl_serializer/index.md
@@ -1,4 +1,4 @@
-# adl_serializer
+# <small>nlohmann::</small>adl_serializer
```cpp
template<typename, typename>
@@ -27,5 +27,9 @@
## Member functions
-- **from_json** - convert a JSON value to any value type
-- **to_json** - convert any value type to a JSON value
+- [**from_json**](from_json.md) - convert a JSON value to any value type
+- [**to_json**](to_json.md) - convert any value type to a JSON value
+
+## Version history
+
+- Added in version 2.1.0.
diff --git a/doc/mkdocs/docs/api/adl_serializer/to_json.md b/doc/mkdocs/docs/api/adl_serializer/to_json.md
new file mode 100644
index 0000000..d39f725
--- /dev/null
+++ b/doc/mkdocs/docs/api/adl_serializer/to_json.md
@@ -0,0 +1,26 @@
+# <small>nlohmann::adl_serializer::</small>to_json
+
+```cpp
+template<typename BasicJsonType, typename TargetType = ValueType>
+static auto to_json(BasicJsonType& j, TargetType && val) noexcept(
+ noexcept(::nlohmann::to_json(j, std::forward<TargetType>(val))))
+-> decltype(::nlohmann::to_json(j, std::forward<TargetType>(val)), void())
+```
+
+This function is usually called by the constructors of the [basic_json](../basic_json) class.
+
+## Parameters
+
+`j` (out)
+: JSON value to write to
+
+`val` (in)
+: value to read from
+
+!!! note
+
+ This documentation page is a stub.
+
+## Version history
+
+- Added in version 2.1.0.
diff --git a/doc/mkdocs/docs/api/basic_json/accept.md b/doc/mkdocs/docs/api/basic_json/accept.md
index b18c539..8794c58 100644
--- a/doc/mkdocs/docs/api/basic_json/accept.md
+++ b/doc/mkdocs/docs/api/basic_json/accept.md
@@ -1,4 +1,4 @@
-# basic_json::accept
+# <small>nlohmann::basic_json::</small>accept
```cpp
// (1)
@@ -17,7 +17,7 @@
1. Reads from a compatible input.
2. Reads from a pair of character iterators
- The value_type of the iterator must be a integral type with size of 1, 2 or 4 bytes, which will be interpreted
+ The value_type of the iterator must be an integral type with size of 1, 2 or 4 bytes, which will be interpreted
respectively as UTF-8, UTF-16 and UTF-32.
Unlike the [`parse`](parse.md) function, this function neither throws an exception in case of invalid JSON input
@@ -84,7 +84,21 @@
--8<-- "examples/accept__string.output"
```
+## See also
+
+- [parse](parse.md) - deserialize from a compatible input
+- [operator>>](operator_gtgt.md) - deserialize from stream
+
## Version history
- Added in version 3.0.0.
- Ignoring comments via `ignore_comments` added in version 3.9.0.
+
+!!! warning "Deprecation"
+
+ Overload (2) replaces calls to `accept` with a pair of iterators as their first parameter which has been
+ deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
+ `#!cpp accept({ptr, ptr+len}, ...);` with `#!cpp accept(ptr, ptr+len, ...);`.
+
+ You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated
+ function.
diff --git a/doc/mkdocs/docs/api/basic_json/array.md b/doc/mkdocs/docs/api/basic_json/array.md
index 8911302..22b2ee1 100644
--- a/doc/mkdocs/docs/api/basic_json/array.md
+++ b/doc/mkdocs/docs/api/basic_json/array.md
@@ -1,4 +1,4 @@
-# basic_json::array
+# <small>nlohmann::basic_json::</small>array
```cpp
static basic_json array(initializer_list_t init = {});
@@ -50,6 +50,11 @@
--8<-- "examples/array.output"
```
+## See also
+
+- [`basic_json(initializer_list_t)`](basic_json.md) - create a JSON value from an initializer list
+- [`object`](object.md) - create a JSON object value from an initializer list
+
## Version history
- Added in version 1.0.0.
diff --git a/doc/mkdocs/docs/api/basic_json/array_t.md b/doc/mkdocs/docs/api/basic_json/array_t.md
index f84e645..dd2b901 100644
--- a/doc/mkdocs/docs/api/basic_json/array_t.md
+++ b/doc/mkdocs/docs/api/basic_json/array_t.md
@@ -1,4 +1,4 @@
-# basic_json::array_t
+# <small>nlohmann::basic_json::</small>array_t
```cpp
using array_t = ArrayType<basic_json, AllocatorType<basic_json>>;
@@ -47,6 +47,22 @@
Arrays are stored as pointers in a `basic_json` type. That is, for any access to array values, a pointer of type
`#!cpp array_t*` must be dereferenced.
+## Examples
+
+??? example
+
+ The following code shows that `array_t` is by default, a typedef to `#!cpp std::vector<nlohmann::json>`.
+
+ ```cpp
+ --8<-- "examples/array_t.cpp"
+ ```
+
+ Output:
+
+ ```json
+ --8<-- "examples/array_t.output"
+ ```
+
## Version history
- Added in version 1.0.0.
diff --git a/doc/mkdocs/docs/api/basic_json/at.md b/doc/mkdocs/docs/api/basic_json/at.md
index 75977b1..1ad6613 100644
--- a/doc/mkdocs/docs/api/basic_json/at.md
+++ b/doc/mkdocs/docs/api/basic_json/at.md
@@ -1,4 +1,4 @@
-# basic_json::at
+# <small>nlohmann::basic_json::</small>at
```cpp
// (1)
@@ -14,8 +14,8 @@
const_reference at(const json_pointer& ptr) const;
```
-1. Returns a reference to the element at specified location `idx`, with bounds checking.
-2. Returns a reference to the element at with specified key `key`, with bounds checking.
+1. Returns a reference to the array element at specified location `idx`, with bounds checking.
+2. Returns a reference to the object element at with specified key `key`, with bounds checking.
3. Returns a reference to the element at with specified JSON pointer `ptr`, with bounds checking.
## Parameters
@@ -35,6 +35,10 @@
2. reference to the element at key `key`
3. reference to the element pointed to by `ptr`
+## Exception safety
+
+Strong exception safety: if an exception occurs, the original value stays intact.
+
## Exceptions
1. The function can throw the following exceptions:
@@ -45,7 +49,7 @@
2. The function can throw the following exceptions:
- Throws [`type_error.304`](../../home/exceptions.md#jsonexceptiontype_error304) if the JSON value is not an object;
in this case, calling `at` with a key makes no sense. See example below.
- - Throws [`out_of_range.403`](../../home/exceptions.md#jsonexceptionout_of_range403) if the key `key` is is not
+ - Throws [`out_of_range.403`](../../home/exceptions.md#jsonexceptionout_of_range403) if the key `key` is not
stored in the object; that is, `find(key) == end()`. See example below.
3. The function can throw the following exceptions:
- Throws [`parse_error.106`](../../home/exceptions.md#jsonexceptionparse_error106) if an array index in the passed
@@ -62,19 +66,15 @@
- Throws [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) if the JSON pointer `ptr` can
not be resolved. See example below.
-## Exception safety
-
-Strong exception safety: if an exception occurs, the original value stays intact.
-
## Complexity
1. Constant
2. Logarithmic in the size of the container.
3. Constant
-## Example
+## Examples
-??? example
+??? example "Example: (1) access specified array element with bounds checking"
The example below shows how array elements can be read and written using `at()`. It also demonstrates the different
exceptions that can be thrown.
@@ -89,7 +89,7 @@
--8<-- "examples/at__size_type.output"
```
-??? example
+??? example "Example: (1) access specified array element with bounds checking"
The example below shows how array elements can be read using `at()`. It also demonstrates the different exceptions
that can be thrown.
@@ -104,7 +104,7 @@
--8<-- "examples/at__size_type_const.output"
```
-??? example
+??? example "Example: (2) access specified object element with bounds checking"
The example below shows how object elements can be read and written using `at()`. It also demonstrates the different
exceptions that can be thrown.
@@ -119,7 +119,7 @@
--8<-- "examples/at__object_t_key_type.output"
```
-??? example
+??? example "Example (2) access specified object element with bounds checking"
The example below shows how object elements can be read using `at()`. It also demonstrates the different exceptions
that can be thrown.
@@ -134,7 +134,7 @@
--8<-- "examples/at__object_t_key_type_const.output"
```
-??? example
+??? example "Example (3) access specified element via JSON Pointer"
The example below shows how object elements can be read and written using `at()`. It also demonstrates the different
exceptions that can be thrown.
@@ -149,7 +149,7 @@
--8<-- "examples/at_json_pointer.output"
```
-??? example
+??? example "Example (3) access specified element via JSON Pointer"
The example below shows how object elements can be read using `at()`. It also demonstrates the different exceptions
that can be thrown.
@@ -164,6 +164,11 @@
--8<-- "examples/at_json_pointer_const.output"
```
+## See also
+
+- see [`operator[]`](operator%5B%5D.md) for unchecked access by reference
+- see [`value`](value.md) for access with default value
+
## Version history
1. Added in version 1.0.0.
diff --git a/doc/mkdocs/docs/api/basic_json/back.md b/doc/mkdocs/docs/api/basic_json/back.md
index 1484153..96e1dec 100644
--- a/doc/mkdocs/docs/api/basic_json/back.md
+++ b/doc/mkdocs/docs/api/basic_json/back.md
@@ -1,4 +1,4 @@
-# basic_json::back
+# <small>nlohmann::basic_json::</small>back
```cpp
reference back();
@@ -20,26 +20,26 @@
In case of a structured type (array or object), a reference to the last element is returned. In case of number, string,
boolean, or binary values, a reference to the value is returned.
+## Exception safety
+
+Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
+
## Exceptions
If the JSON value is `#!json null`, exception
[`invalid_iterator.214`](../../home/exceptions.md#jsonexceptioninvalid_iterator214) is thrown.
-## Exception safety
-
-Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
-
## Complexity
Constant.
-## Note
+## Notes
!!! danger
Calling `back` on an empty array or object is undefined behavior and is **guarded by an assertion**!
-## Example
+## Examples
??? example
@@ -55,6 +55,10 @@
--8<-- "examples/back.output"
```
+## See also
+
+- [front](front.md) to access the first element
+
## Version history
- Added in version 1.0.0.
diff --git a/doc/mkdocs/docs/api/basic_json/basic_json.md b/doc/mkdocs/docs/api/basic_json/basic_json.md
index 9ff6fbb..ab3fea4 100644
--- a/doc/mkdocs/docs/api/basic_json/basic_json.md
+++ b/doc/mkdocs/docs/api/basic_json/basic_json.md
@@ -1,53 +1,55 @@
-# basic_json::basic_json
+# <small>nlohmann::basic_json::</small>basic_json
```cpp
-// 1
+// (1)
basic_json(const value_t v);
-// 2
+// (2)
basic_json(std::nullptr_t = nullptr) noexcept;
-// 3
+// (3)
template<typename CompatibleType>
basic_json(CompatibleType&& val) noexcept(noexcept(
JSONSerializer<U>::to_json(std::declval<basic_json_t&>(),
std::forward<CompatibleType>(val))));
-// 4
+// (4)
template<typename BasicJsonType>
basic_json(const BasicJsonType& val);
-// 5
+// (5)
basic_json(initializer_list_t init,
bool type_deduction = true,
value_t manual_type = value_t::array);
-// 6
+// (6)
basic_json(size_type cnt, const basic_json& val);
-// 7
+// (7)
basic_json(iterator first, iterator last);
basic_json(const_iterator first, const_iterator last);
-// 8
+// (8)
basic_json(const basic_json& other);
-// 9
+// (9)
basic_json(basic_json&& other) noexcept;
```
1. Create an empty JSON value with a given type. The value will be default initialized with an empty value which depends
on the type:
- Value type | initial value
- ----------- | -------------
- null | `#!json null`
- boolean | `#!json false`
- string | `#!json ""`
- number | `#!json 0`
- object | `#!json {}`
- array | `#!json []`
- binary | empty array
+ | Value type | initial value |
+ |------------|----------------|
+ | null | `#!json null` |
+ | boolean | `#!json false` |
+ | string | `#!json ""` |
+ | number | `#!json 0` |
+ | object | `#!json {}` |
+ | array | `#!json []` |
+ | binary | empty array |
+
+ The postcondition of this constructor can be restored by calling [`clear()`](clear.md).
2. Create a `#!json null` JSON value. It either takes a null pointer as parameter (explicitly creating `#!json null`)
or no parameter (implicitly creating `#!json null`). The passed null pointer itself is not read -- it is only used to
@@ -104,6 +106,9 @@
- the empty array (`#!json []`): use `array(initializer_list_t)` with an empty initializer list in this case
- arrays whose elements satisfy rule 2: use `array(initializer_list_t)` with the same initializer list in this case
+
+ Function [`array()`](array.md) and [`object()`](object.md) force array and object creation from initializer lists,
+ respectively.
6. Constructs a JSON array value by creating `cnt` copies of a passed value. In case `cnt` is `0`, an empty array is
created.
@@ -142,6 +147,9 @@
- `BasicJsonType` is a `basic_json` type.
- `BasicJsonType` has different template arguments than `basic_json_t`.
+`U`:
+: `uncvref_t<CompatibleType>`
+
## Parameters
`v` (in)
@@ -175,6 +183,22 @@
`other` (in)
: the JSON value to copy/move
+## Exception safety
+
+1. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
+2. No-throw guarantee: this constructor never throws exceptions.
+3. Depends on the called constructor. For types directly supported by the library (i.e., all types for which no
+ `to_json()` function was provided), strong guarantee holds: if an exception is thrown, there are no changes to any
+ JSON value.
+4. Depends on the called constructor. For types directly supported by the library (i.e., all types for which no
+ `to_json()` function was provided), strong guarantee holds: if an exception is thrown, there are no changes to any
+ JSON value.
+5. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
+6. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
+7. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
+8. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
+9. No-throw guarantee: this constructor never throws exceptions.
+
## Exceptions
1. /
@@ -193,28 +217,12 @@
`[first, last)` is undefined.
- Throws [`invalid_iterator.204`](../../home/exceptions.md#jsonexceptioninvalid_iterator204) if iterators `first`
and `last` belong to a primitive type (number, boolean, or string), but `first` does not point to the first
- element any more. In this case, the range `[first, last)` is undefined. See example code below.
+ element anymore. In this case, the range `[first, last)` is undefined. See example code below.
- Throws [`invalid_iterator.206`](../../home/exceptions.md#jsonexceptioninvalid_iterator206) if iterators `first`
and `last` belong to a `#!json null` value. In this case, the range `[first, last)` is undefined.
8. /
9. The function does not throw exceptions.
-## Exception safety
-
-1. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
-2. No-throw guarantee: this constructor never throws exceptions.
-3. Depends on the called constructor. For types directly supported by the library (i.e., all types for which no
- `to_json()` function was provided), strong guarantee holds: if an exception is thrown, there are no changes to any
- JSON value.
-4. Depends on the called constructor. For types directly supported by the library (i.e., all types for which no
- `to_json()` function was provided), strong guarantee holds: if an exception is thrown, there are no changes to any
- JSON value.
-5. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
-6. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
-7. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
-8. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
-9. No-throw guarantee: this constructor never throws exceptions.
-
## Complexity
1. Constant.
@@ -267,9 +275,9 @@
- `#!cpp `*this` has the same value as `other` before the call.
- `other` is a JSON `#!json null` value
-## Example
+## Examples
-??? example
+??? example "Example: (1) create an empty value with a given type"
The following code shows the constructor for different `value_t` values.
@@ -283,7 +291,7 @@
--8<-- "examples/basic_json__value_t.output"
```
-??? example
+??? example "Example: (2) create a `#!json null` object"
The following code shows the constructor with and without a null pointer parameter.
@@ -297,7 +305,7 @@
--8<-- "examples/basic_json__nullptr_t.output"
```
-??? example
+??? example "Example: (3) create a JSON value from compatible types"
The following code shows the constructor with several compatible types.
@@ -311,7 +319,7 @@
--8<-- "examples/basic_json__CompatibleType.output"
```
-??? example
+??? example "Example: (5) create a container (array or object) from an initializer list"
The example below shows how JSON values are created from initializer lists.
@@ -325,7 +333,7 @@
--8<-- "examples/basic_json__list_init_t.output"
```
-??? example
+??? example "Example: (6) construct an array with count copies of given value"
The following code shows examples for creating arrays with several copies of a given value.
@@ -339,7 +347,7 @@
--8<-- "examples/basic_json__size_type_basic_json.output"
```
-??? example
+??? example "Example: (7) construct a JSON container given an iterator range"
The example below shows several ways to create JSON values by specifying a subrange with iterators.
@@ -353,7 +361,7 @@
--8<-- "examples/basic_json__InputIt_InputIt.output"
```
-??? example
+??? example "Example: (8) copy constructor"
The following code shows an example for the copy constructor.
@@ -367,7 +375,7 @@
--8<-- "examples/basic_json__basic_json.output"
```
-??? example
+??? example "Example: (9) move constructor"
The code below shows the move constructor explicitly called via `std::move`.
diff --git a/doc/mkdocs/docs/api/basic_json/begin.md b/doc/mkdocs/docs/api/basic_json/begin.md
index 25d93b8..ef623a5 100644
--- a/doc/mkdocs/docs/api/basic_json/begin.md
+++ b/doc/mkdocs/docs/api/basic_json/begin.md
@@ -1,4 +1,4 @@
-# basic_json::begin
+# <small>nlohmann::basic_json::</small>begin
```cpp
iterator begin() noexcept;
@@ -21,7 +21,7 @@
Constant.
-## Example
+## Examples
??? example
diff --git a/doc/mkdocs/docs/api/basic_json/binary.md b/doc/mkdocs/docs/api/basic_json/binary.md
index 0b1b9f4..ce45d8a 100644
--- a/doc/mkdocs/docs/api/basic_json/binary.md
+++ b/doc/mkdocs/docs/api/basic_json/binary.md
@@ -1,4 +1,4 @@
-# basic_json::binary
+# <small>nlohmann::basic_json::</small>binary
```cpp
// (1)
@@ -45,6 +45,22 @@
JSON binary arrays are a non-standard extension it was decided that it would be best to prevent automatic initialization
of a binary array type, for backwards compatibility and so it does not happen on accident.
+## Examples
+
+??? example
+
+ The following code shows how to create a binary value.
+
+ ```cpp
+ --8<-- "examples/binary.cpp"
+ ```
+
+ Output:
+
+ ```json
+ --8<-- "examples/binary.output"
+ ```
+
## Version history
- Added in version 3.8.0.
diff --git a/doc/mkdocs/docs/api/basic_json/binary_t.md b/doc/mkdocs/docs/api/basic_json/binary_t.md
index f7da1ec..705c92c 100644
--- a/doc/mkdocs/docs/api/basic_json/binary_t.md
+++ b/doc/mkdocs/docs/api/basic_json/binary_t.md
@@ -1,4 +1,4 @@
-# basic_json::binary_t
+# <small>nlohmann::basic_json::</small>binary_t
```cpp
using binary_t = byte_container_with_subtype<BinaryType>;
@@ -8,9 +8,10 @@
2, MessagePack's bin, and BSON's generic binary subtype. This type is NOT a part of standard JSON and exists solely for
compatibility with these binary types. As such, it is simply defined as an ordered sequence of zero or more byte values.
-Additionally, as an implementation detail, the subtype of the binary data is carried around as a `std::uint8_t`, which
+Additionally, as an implementation detail, the subtype of the binary data is carried around as a `std::uint64_t`, which
is compatible with both of the binary data formats that use binary subtyping, (though the specific numbering is
-incompatible with each other, and it is up to the user to translate between them).
+incompatible with each other, and it is up to the user to translate between them). The subtype is added to `BinaryType`
+via the helper type [byte_container_with_subtype](../byte_container_with_subtype/index.md).
[CBOR's RFC 7049](https://tools.ietf.org/html/rfc7049) describes this type as:
> Major type 2: a byte string. The string's length in bytes is represented following the rules for positive integers
@@ -18,7 +19,7 @@
[MessagePack's documentation on the bin type
family](https://github.com/msgpack/msgpack/blob/master/spec.md#bin-format-family) describes this type as:
-> Bin format family stores an byte array in 2, 3, or 5 bytes of extra bytes in addition to the size of the byte array.
+> Bin format family stores a byte array in 2, 3, or 5 bytes of extra bytes in addition to the size of the byte array.
[BSON's specifications](http://bsonspec.org/spec.html) describe several binary types; however, this type is intended to
represent the generic binary type which has the description:
@@ -55,13 +56,34 @@
- MessagePack
- If a subtype is given and the binary array contains exactly 1, 2, 4, 8, or 16 elements, the fixext family (fixext1,
fixext2, fixext4, fixext8) is used. For other sizes, the ext family (ext8, ext16, ext32) is used. The subtype is
- then added as singed 8-bit integer.
+ then added as signed 8-bit integer.
- If no subtype is given, the bin family (bin8, bin16, bin32) is used.
- BSON
- If a subtype is given, it is used and added as unsigned 8-bit integer.
- If no subtype is given, the generic binary subtype 0x00 is used.
+## Examples
+
+??? example
+
+ The following code shows that `binary_t` is by default, a typedef to
+ `#!cpp nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>`.
+
+ ```cpp
+ --8<-- "examples/binary_t.cpp"
+ ```
+
+ Output:
+
+ ```json
+ --8<-- "examples/binary_t.output"
+ ```
+
+## See also
+
+- [byte_container_with_subtype](../byte_container_with_subtype/index.md)
+
## Version history
- Added in version 3.8.0. Changed type of subtype to `std::uint64_t` in version 3.10.0.
diff --git a/doc/mkdocs/docs/api/basic_json/boolean_t.md b/doc/mkdocs/docs/api/basic_json/boolean_t.md
index a611514..3ca6131 100644
--- a/doc/mkdocs/docs/api/basic_json/boolean_t.md
+++ b/doc/mkdocs/docs/api/basic_json/boolean_t.md
@@ -1,4 +1,4 @@
-# basic_json::boolean_t
+# <small>nlohmann::basic_json::</small>boolean_t
```cpp
using boolean_t = BooleanType;
@@ -21,6 +21,22 @@
Boolean values are stored directly inside a `basic_json` type.
+## Examples
+
+??? example
+
+ The following code shows that `boolean_t` is by default, a typedef to `#!cpp bool`.
+
+ ```cpp
+ --8<-- "examples/boolean_t.cpp"
+ ```
+
+ Output:
+
+ ```json
+ --8<-- "examples/boolean_t.output"
+ ```
+
## Version history
- Added in version 1.0.0.
diff --git a/doc/mkdocs/docs/api/basic_json/cbegin.md b/doc/mkdocs/docs/api/basic_json/cbegin.md
index 132934a..06504fe 100644
--- a/doc/mkdocs/docs/api/basic_json/cbegin.md
+++ b/doc/mkdocs/docs/api/basic_json/cbegin.md
@@ -1,4 +1,4 @@
-# basic_json::cbegin
+# <small>nlohmann::basic_json::</small>cbegin
```cpp
const_iterator cbegin() const noexcept;
@@ -20,7 +20,7 @@
Constant.
-## Example
+## Examples
??? example
diff --git a/doc/mkdocs/docs/api/basic_json/cbor_tag_handler_t.md b/doc/mkdocs/docs/api/basic_json/cbor_tag_handler_t.md
index 7073b9d..6622d8a 100644
--- a/doc/mkdocs/docs/api/basic_json/cbor_tag_handler_t.md
+++ b/doc/mkdocs/docs/api/basic_json/cbor_tag_handler_t.md
@@ -1,4 +1,4 @@
-# basic_json::cbor_tag_handler_t
+# <small>nlohmann::basic_json::</small>cbor_tag_handler_t
```cpp
enum class cbor_tag_handler_t
diff --git a/doc/mkdocs/docs/api/basic_json/cend.md b/doc/mkdocs/docs/api/basic_json/cend.md
index e5de7e9..3f3aa94 100644
--- a/doc/mkdocs/docs/api/basic_json/cend.md
+++ b/doc/mkdocs/docs/api/basic_json/cend.md
@@ -1,4 +1,4 @@
-# basic_json::cend
+# <small>nlohmann::basic_json::</small>cend
```cpp
const_iterator cend() const noexcept;
@@ -20,7 +20,7 @@
Constant.
-## Example
+## Examples
??? example
diff --git a/doc/mkdocs/docs/api/basic_json/clear.md b/doc/mkdocs/docs/api/basic_json/clear.md
index 5119b83..ff04b08 100644
--- a/doc/mkdocs/docs/api/basic_json/clear.md
+++ b/doc/mkdocs/docs/api/basic_json/clear.md
@@ -1,4 +1,4 @@
-# basic_json::clear
+# <small>nlohmann::basic_json::</small>clear
```cpp
void clear() noexcept;
@@ -7,15 +7,15 @@
Clears the content of a JSON value and resets it to the default value as if [`basic_json(value_t)`](basic_json.md) would
have been called with the current value type from [`type()`](type.md):
-Value type | initial value
------------ | -------------
-null | `null`
-boolean | `false`
-string | `""`
-number | `0`
-binary | An empty byte vector
-object | `{}`
-array | `[]`
+| Value type | initial value |
+|------------|----------------------|
+| null | `null` |
+| boolean | `false` |
+| string | `""` |
+| number | `0` |
+| binary | An empty byte vector |
+| object | `{}` |
+| array | `[]` |
Has the same effect as calling
@@ -35,7 +35,7 @@
All iterators, pointers and references related to this container are invalidated.
-## Example
+## Examples
??? example
diff --git a/doc/mkdocs/docs/api/basic_json/contains.md b/doc/mkdocs/docs/api/basic_json/contains.md
index 1616f0c..8463f4e 100644
--- a/doc/mkdocs/docs/api/basic_json/contains.md
+++ b/doc/mkdocs/docs/api/basic_json/contains.md
@@ -1,12 +1,17 @@
-# basic_json::contains
+# <small>nlohmann::basic_json::</small>contains
```cpp
+// (1)
template<typename KeyT>
bool contains(KeyT && key) const;
+
+// (2)
+bool contains(const json_pointer& ptr) const;
```
-Check whether an element exists in a JSON object with key equivalent to `key`. If the element is not found or the JSON
-value is not an object, `#!cpp false` is returned.
+1. Check whether an element exists in a JSON object with key equivalent to `key`. If the element is not found or the
+ JSON value is not an object, `#!cpp false` is returned.
+2. Check whether the given JSON pointer `ptr` can be resolved in the current JSON value.
## Template parameters
@@ -17,27 +22,45 @@
`key` (in)
: key value to check its existence.
-
+
+`ptr` (in)
+: JSON pointer to check its existence.
+
## Return value
-`#!cpp true` if an element with specified `key` exists. If no such element with such key is found or the JSON value is
-not an object, `#!cpp false` is returned.
+1. `#!cpp true` if an element with specified `key` exists. If no such element with such key is found or the JSON value
+ is not an object, `#!cpp false` is returned.
+2. `#!cpp true` if the JSON pointer can be resolved to a stored value, `#!cpp false` otherwise.
## Exception safety
Strong exception safety: if an exception occurs, the original value stays intact.
+## Exceptions
+
+1. The function does not throw exceptions.
+2. The function can throw the following exceptions:
+ - Throws [`parse_error.106`](../../home/exceptions.md#jsonexceptionparse_error106) if an array index begins with
+ `0`.
+ - Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) if an array index was not a
+ number.
+
## Complexity
Logarithmic in the size of the JSON object.
## Notes
-This method always returns `#!cpp false` when executed on a JSON type that is not an object.
+1. This method always returns `#!cpp false` when executed on a JSON type that is not an object.
+2. This method can be executed on any JSON value type.
-## Example
+!!! info "Postconditions"
-??? example
+ If `#!cpp j.contains(x)` returns `#!c true` for a key or JSON pointer `x`, then it is safe to call `j[x]`.
+
+## Examples
+
+??? example "Example (1) check with key"
The example shows how `contains()` is used.
@@ -51,6 +74,21 @@
--8<-- "examples/contains.output"
```
+??? example "Example (1) check with JSON pointer"
+
+ The example shows how `contains()` is used.
+
+ ```cpp
+ --8<-- "examples/contains_json_pointer.cpp"
+ ```
+
+ Output:
+
+ ```json
+ --8<-- "examples/contains_json_pointer.output"
+ ```
+
## Version history
-- Added in version 3.6.0.
+1. Added in version 3.6.0.
+2. Added in version 3.7.0.
diff --git a/doc/mkdocs/docs/api/basic_json/count.md b/doc/mkdocs/docs/api/basic_json/count.md
index 34f1605..fcfef86 100644
--- a/doc/mkdocs/docs/api/basic_json/count.md
+++ b/doc/mkdocs/docs/api/basic_json/count.md
@@ -1,4 +1,4 @@
-# basic_json::count
+# <small>nlohmann::basic_json::</small>count
```cpp
template<typename KeyT>
@@ -34,7 +34,7 @@
This method always returns `0` when executed on a JSON type that is not an object.
-## Example
+## Examples
??? example
diff --git a/doc/mkdocs/docs/api/basic_json/crbegin.md b/doc/mkdocs/docs/api/basic_json/crbegin.md
index 1419662..7af5eca 100644
--- a/doc/mkdocs/docs/api/basic_json/crbegin.md
+++ b/doc/mkdocs/docs/api/basic_json/crbegin.md
@@ -1,4 +1,4 @@
-# basic_json::crbegin
+# <small>nlohmann::basic_json::</small>crbegin
```cpp
const_reverse_iterator crbegin() const noexcept;
@@ -20,7 +20,7 @@
Constant.
-## Example
+## Examples
??? example
diff --git a/doc/mkdocs/docs/api/basic_json/crend.md b/doc/mkdocs/docs/api/basic_json/crend.md
index f98af70..0e6bc84 100644
--- a/doc/mkdocs/docs/api/basic_json/crend.md
+++ b/doc/mkdocs/docs/api/basic_json/crend.md
@@ -1,4 +1,4 @@
-# basic_json::rend
+# <small>nlohmann::basic_json::</small>crend
```cpp
const_reverse_iterator crend() const noexcept;
@@ -21,7 +21,7 @@
Constant.
-## Example
+## Examples
??? example
diff --git a/doc/mkdocs/docs/api/basic_json/diff.md b/doc/mkdocs/docs/api/basic_json/diff.md
index 736d5fb..4e84068 100644
--- a/doc/mkdocs/docs/api/basic_json/diff.md
+++ b/doc/mkdocs/docs/api/basic_json/diff.md
@@ -1,4 +1,4 @@
-# basic_json::diff
+# <small>nlohmann::basic_json::</small>diff
```cpp
static basic_json diff(const basic_json& source,
@@ -33,11 +33,11 @@
Linear in the lengths of `source` and `target`.
-## Note
+## Notes
Currently, only `remove`, `add`, and `replace` operations are generated.
-## Example
+## Examples
??? example
@@ -53,6 +53,10 @@
--8<-- "examples/diff.output"
```
+## See also
+
+- [RFC 6902 (JSON Patch)](https://tools.ietf.org/html/rfc6902)
+
## Version history
- Added in version 2.0.0.
diff --git a/doc/mkdocs/docs/api/basic_json/dump.md b/doc/mkdocs/docs/api/basic_json/dump.md
index cad06ca..41adb15 100644
--- a/doc/mkdocs/docs/api/basic_json/dump.md
+++ b/doc/mkdocs/docs/api/basic_json/dump.md
@@ -1,4 +1,4 @@
-# basic_json::dump
+# <small>nlohmann::basic_json::</small>dump
```cpp
string_t dump(const int indent = -1,
@@ -7,8 +7,9 @@
const error_handler_t error_handler = error_handler_t::strict) const;
```
-Serialization function for JSON values. The function tries to mimic Python's `json.dumps()` function, and currently
-supports its `indent` and `ensure_ascii` parameters.
+Serialization function for JSON values. The function tries to mimic Python's
+[`json.dumps()` function](https://docs.python.org/2/library/json.html#json.dump), and currently supports its `indent`
+and `ensure_ascii` parameters.
## Parameters
@@ -27,7 +28,7 @@
: how to react on decoding errors; there are three possible values (see [`error_handler_t`](error_handler_t.md):
`strict` (throws and exception in case a decoding error occurs; default), `replace` (replace invalid UTF-8 sequences
with U+FFFD), and `ignore` (ignore invalid UTF-8 sequences during serialization; all bytes are copied to the output
- unchanged).
+ unchanged)).
## Return value
@@ -37,6 +38,11 @@
Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
+## Exceptions
+
+Throws [`type_error.316`](../../home/exceptions.md#jsonexceptiontype_error316) if a string stored inside the JSON value
+is not UTF-8 encoded and `error_handler` is set to `strict`
+
## Complexity
Linear.
@@ -48,7 +54,7 @@
- "bytes": an array of bytes as integers
- "subtype": the subtype as integer or `#!json null` if the binary has no subtype
-## Example
+## Examples
??? example
@@ -64,3 +70,10 @@
```json
--8<-- "examples/dump.output"
```
+
+## Version history
+
+- Added in version 1.0.0.
+- Indentation character `indent_char`, option `ensure_ascii` and exceptions added in version 3.0.0.
+- Error handlers added in version 3.4.0.
+- Serialization of binary values added in version 3.8.0.
diff --git a/doc/mkdocs/docs/api/basic_json/emplace.md b/doc/mkdocs/docs/api/basic_json/emplace.md
index 50a9c92..6cc2c98 100644
--- a/doc/mkdocs/docs/api/basic_json/emplace.md
+++ b/doc/mkdocs/docs/api/basic_json/emplace.md
@@ -1,4 +1,4 @@
-# basic_json::emplace
+# <small>nlohmann::basic_json::</small>emplace
```cpp
template<class... Args>
diff --git a/doc/mkdocs/docs/api/basic_json/emplace_back.md b/doc/mkdocs/docs/api/basic_json/emplace_back.md
index 8a8af0c..597ad41 100644
--- a/doc/mkdocs/docs/api/basic_json/emplace_back.md
+++ b/doc/mkdocs/docs/api/basic_json/emplace_back.md
@@ -1,4 +1,4 @@
-# basic_json::emplace_back
+# <small>nlohmann::basic_json::</small>emplace_back
```cpp
template<class... Args>
diff --git a/doc/mkdocs/docs/api/basic_json/empty.md b/doc/mkdocs/docs/api/basic_json/empty.md
index 151e073..26bf6e9 100644
--- a/doc/mkdocs/docs/api/basic_json/empty.md
+++ b/doc/mkdocs/docs/api/basic_json/empty.md
@@ -1,4 +1,4 @@
-# basic_json::empty
+# <small>nlohmann::basic_json::</small>empty
```cpp
bool empty() const noexcept;
@@ -10,15 +10,15 @@
The return value depends on the different types and is defined as follows:
-Value type | return value
------------ | -------------
-null | `#!cpp true`
-boolean | `#!cpp false`
-string | `#!cpp false`
-number | `#!cpp false`
-binary | `#!cpp false`
-object | result of function `object_t::empty()`
-array | result of function `array_t::empty()`
+| Value type | return value |
+|------------|----------------------------------------|
+| null | `#!cpp true` |
+| boolean | `#!cpp false` |
+| string | `#!cpp false` |
+| number | `#!cpp false` |
+| binary | `#!cpp false` |
+| object | result of function `object_t::empty()` |
+| array | result of function `array_t::empty()` |
## Exception safety
@@ -44,7 +44,7 @@
This function does not return whether a string stored as JSON value is empty -- it returns whether the JSON container
itself is empty which is `#!cpp false` in the case of a string.
-## Example
+## Examples
??? example
diff --git a/doc/mkdocs/docs/api/basic_json/end.md b/doc/mkdocs/docs/api/basic_json/end.md
index 52bfec2..179ce9e 100644
--- a/doc/mkdocs/docs/api/basic_json/end.md
+++ b/doc/mkdocs/docs/api/basic_json/end.md
@@ -1,4 +1,4 @@
-# basic_json::end
+# <small>nlohmann::basic_json::</small>end
```cpp
iterator end() noexcept;
@@ -21,7 +21,7 @@
Constant.
-## Example
+## Examples
??? example
diff --git a/doc/mkdocs/docs/api/basic_json/erase.md b/doc/mkdocs/docs/api/basic_json/erase.md
index 3d80f5b..d94c25b 100644
--- a/doc/mkdocs/docs/api/basic_json/erase.md
+++ b/doc/mkdocs/docs/api/basic_json/erase.md
@@ -1,4 +1,4 @@
-# basic_json::erase
+# <small>nlohmann::basic_json::</small>erase
```cpp
// (1)
@@ -17,7 +17,7 @@
```
1. Removes an element from a JSON value specified by iterator `pos`. The iterator `pos` must be valid and
- dereferenceable. Thus the `end()` iterator (which is valid, but is not dereferenceable) cannot be used as a value for
+ dereferenceable. Thus, the `end()` iterator (which is valid, but is not dereferenceable) cannot be used as a value for
`pos`.
If called on a primitive type other than `#!json null`, the resulting JSON value will be `#!json null`.
@@ -58,6 +58,10 @@
(`key` was not found) or `1` (`key` was found).
4. /
+## Exception safety
+
+Strong exception safety: if an exception occurs, the original value stays intact.
+
## Exceptions
1. The function can throw the following exceptions:
@@ -68,7 +72,7 @@
- Throws [`invalid_iterator.205`](../../home/exceptions.md#jsonexceptioninvalid_iterator205) if called on a
primitive type with invalid iterator (i.e., any iterator which is not `begin()`); example: `"iterator out of
range"`
-2. The function can throw thw following exceptions:
+2. The function can throw the following exceptions:
- Throws [`type_error.307`](../../home/exceptions.md#jsonexceptiontype_error307) if called on a `null` value;
example: `"cannot use erase() with null"`
- Throws [`invalid_iterator.203`](../../home/exceptions.md#jsonexceptioninvalid_iterator203) if called on iterators
@@ -76,19 +80,15 @@
- Throws [`invalid_iterator.204`](../../home/exceptions.md#jsonexceptioninvalid_iterator204) if called on a
primitive type with invalid iterators (i.e., if `first != begin()` and `last != end()`); example: `"iterators out
of range"`
-3. The function can throw thw following exceptions:
+3. The function can throw the following exceptions:
- Throws [`type_error.307`](../../home/exceptions.md#jsonexceptiontype_error307) when called on a type other than
JSON object; example: `"cannot use erase() with null"`
-4. The function can throw thw following exceptions:
+4. The function can throw the following exceptions:
- Throws [`type_error.307`](../../home/exceptions.md#jsonexceptiontype_error307) when called on a type other than
JSON object; example: `"cannot use erase() with null"`
- Throws [`out_of_range.401`](../../home/exceptions.md#jsonexceptionout_of_range401) when `idx >= size()`; example:
`"array index 17 is out of range"`
-## Exception safety
-
-Strong exception safety: if an exception occurs, the original value stays intact.
-
## Complexity
1. The complexity depends on the type:
@@ -107,15 +107,14 @@
## Notes
-1. Invalidates iterators and references at or after the point of the
- erase, including the `end()` iterator.
+1. Invalidates iterators and references at or after the point of the `erase`, including the `end()` iterator.
2. /
3. References and iterators to the erased elements are invalidated. Other references and iterators are not affected.
4. /
-## Example
+## Examples
-??? example
+??? example "Example: (1) remove element given an iterator"
The example shows the effect of `erase()` for different JSON types using an iterator.
@@ -129,7 +128,7 @@
--8<-- "examples/erase__IteratorType.output"
```
-??? example
+??? example "Example: (2) remove elements given an iterator range"
The example shows the effect of `erase()` for different JSON types using an iterator range.
@@ -143,7 +142,7 @@
--8<-- "examples/erase__IteratorType_IteratorType.output"
```
-??? example
+??? example "Example: (3) remove element from a JSON object given a key"
The example shows the effect of `erase()` for different JSON types using an object key.
@@ -157,7 +156,7 @@
--8<-- "examples/erase__key_type.output"
```
-??? example
+??? example "Example: (4) remove element from a JSON array given an index"
The example shows the effect of `erase()` using an array index.
diff --git a/doc/mkdocs/docs/api/basic_json/error_handler_t.md b/doc/mkdocs/docs/api/basic_json/error_handler_t.md
index 050dda1..afd20f8 100644
--- a/doc/mkdocs/docs/api/basic_json/error_handler_t.md
+++ b/doc/mkdocs/docs/api/basic_json/error_handler_t.md
@@ -1,4 +1,4 @@
-# basic_json::error_handler_t
+# <small>nlohmann::basic_json::</small>error_handler_t
```cpp
enum class error_handler_t {
diff --git a/doc/mkdocs/docs/api/basic_json/exception.md b/doc/mkdocs/docs/api/basic_json/exception.md
index deedae5..b492666 100644
--- a/doc/mkdocs/docs/api/basic_json/exception.md
+++ b/doc/mkdocs/docs/api/basic_json/exception.md
@@ -1,4 +1,4 @@
-# basic_json::exception
+# <small>nlohmann::basic_json::</small>exception
```cpp
class exception : public std::exception;
@@ -44,7 +44,13 @@
- **id** - the id of the exception
-## Example
+## Notes
+
+To have nothrow-copy-constructible exceptions, we internally use `std::runtime_error` which can cope with
+arbitrary-length error messages. Intermediate strings are built with static functions and then passed to the actual
+constructor.
+
+## Examples
??? example
@@ -60,6 +66,10 @@
--8<-- "examples/exception.output"
```
+## See also
+
+[List of exceptions](127.0.0.1:8000/home/exceptions/)
+
## Version history
- Since version 3.0.0.
diff --git a/doc/mkdocs/docs/api/basic_json/find.md b/doc/mkdocs/docs/api/basic_json/find.md
index 5ff4baf..af4cb29 100644
--- a/doc/mkdocs/docs/api/basic_json/find.md
+++ b/doc/mkdocs/docs/api/basic_json/find.md
@@ -1,11 +1,11 @@
-# basic_json::find
+# <small>nlohmann::basic_json::</small>find
```cpp
template<typename KeyT>
iterator find(KeyT&& key);
template<typename KeyT>
-const_iterator find(KeyT&& key) const
+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
@@ -38,7 +38,7 @@
This method always returns `end()` when executed on a JSON type that is not an object.
-## Example
+## Examples
??? example
@@ -54,6 +54,10 @@
--8<-- "examples/find__key_type.output"
```
+## See also
+
+- [contains](contains.md) checks whether a key exists
+
## Version history
- Added in version 1.0.0.
diff --git a/doc/mkdocs/docs/api/basic_json/flatten.md b/doc/mkdocs/docs/api/basic_json/flatten.md
index 1408f38..8703e86 100644
--- a/doc/mkdocs/docs/api/basic_json/flatten.md
+++ b/doc/mkdocs/docs/api/basic_json/flatten.md
@@ -1,4 +1,4 @@
-# basic_json::flatten
+# <small>nlohmann::basic_json::</small>flatten
```cpp
basic_json flatten() const;
@@ -25,7 +25,7 @@
Empty objects and arrays are flattened to `#!json null` and will not be reconstructed correctly by the
[`unflatten()`](unflatten.md) function.
-## Example
+## Examples
??? example
@@ -41,6 +41,10 @@
--8<-- "examples/flatten.output"
```
+## See also
+
+- [unflatten](unflatten.md) the reverse function
+
## Version history
- Added in version 2.0.0.
diff --git a/doc/mkdocs/docs/api/basic_json/from_bson.md b/doc/mkdocs/docs/api/basic_json/from_bson.md
index 6df74f3..7754937 100644
--- a/doc/mkdocs/docs/api/basic_json/from_bson.md
+++ b/doc/mkdocs/docs/api/basic_json/from_bson.md
@@ -1,4 +1,4 @@
-# basic_json::from_bson
+# <small>nlohmann::basic_json::</small>from_bson
```cpp
// (1)
@@ -18,6 +18,8 @@
1. Reads from a compatible input.
2. Reads from an iterator range.
+The exact mapping and its limitations is described on a [dedicated page](../../features/binary_formats/bson.md).
+
## Template parameters
`InputType`
@@ -58,11 +60,16 @@
Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
+## Exceptions
+
+Throws [`parse_error.114`](../../home/exceptions.md#jsonexceptionparse_error114) if an unsupported BSON record type is
+encountered.
+
## Complexity
Linear in the size of the input.
-## Example
+## Examples
??? example
@@ -78,6 +85,26 @@
--8<-- "examples/from_bson.output"
```
+## See also
+
+- [BSON specification](http://bsonspec.org/spec.html)
+- [to_bson](to_bson.md) for the analogous serialization
+- [from_cbor](from_cbor.md) for the related CBOR format
+- [from_msgpack](from_msgpack.md) for the related MessagePack format
+- [from_ubjson](from_ubjson.md) for the related UBJSON format
+
## Version history
- Added in version 3.4.0.
+
+!!! warning "Deprecation"
+
+ - Overload (2) replaces calls to `from_bson` with a pointer and a length as first two parameters, which has been
+ deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
+ `#!cpp from_bson(ptr, len, ...);` with `#!cpp from_bson(ptr, ptr+len, ...);`.
+ - Overload (2) replaces calls to `from_bson` with a pair of iterators as their first parameter, which has been
+ deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
+ `#!cpp from_bson({ptr, ptr+len}, ...);` with `#!cpp from_bson(ptr, ptr+len, ...);`.
+
+ You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated
+ function.
diff --git a/doc/mkdocs/docs/api/basic_json/from_cbor.md b/doc/mkdocs/docs/api/basic_json/from_cbor.md
index ec186fc..3aa57b9 100644
--- a/doc/mkdocs/docs/api/basic_json/from_cbor.md
+++ b/doc/mkdocs/docs/api/basic_json/from_cbor.md
@@ -1,4 +1,4 @@
-# basic_json::from_cbor
+# <small>nlohmann::basic_json::</small>from_cbor
```cpp
// (1)
@@ -21,6 +21,8 @@
1. Reads from a compatible input.
2. Reads from an iterator range.
+The exact mapping and its limitations is described on a [dedicated page](../../features/binary_formats/cbor.md).
+
## Template parameters
`InputType`
@@ -65,11 +67,20 @@
Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
+## Exceptions
+
+- Throws [parse_error.110](../../home/exceptions.md#jsonexceptionparse_error110) if the given input ends prematurely or
+ the end of file was not reached when `strict` was set to true
+- Throws [parse_error.112](../../home/exceptions.md#jsonexceptionparse_error112) if unsupported features from CBOR were
+ used in the given input or if the input is not valid CBOR
+- Throws [parse_error.113](../../home/exceptions.md#jsonexceptionparse_error113) if a string was expected as map key,
+ but not found
+
## Complexity
Linear in the size of the input.
-## Example
+## Examples
??? example
@@ -92,3 +103,15 @@
- Changed to consume input adapters, removed `start_index` parameter, and added `strict` parameter in version 3.0.0.
- Added `allow_exceptions` parameter in version 3.2.0.
- Added `tag_handler` parameter in version 3.9.0.
+
+!!! warning "Deprecation"
+
+ - Overload (2) replaces calls to `from_cbor` with a pointer and a length as first two parameters, which has been
+ deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
+ `#!cpp from_cbor(ptr, len, ...);` with `#!cpp from_cbor(ptr, ptr+len, ...);`.
+ - Overload (2) replaces calls to `from_cbor` with a pair of iterators as their first parameter, which has been
+ deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
+ `#!cpp from_cbor({ptr, ptr+len}, ...);` with `#!cpp from_cbor(ptr, ptr+len, ...);`.
+
+ You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated
+ function.
diff --git a/doc/mkdocs/docs/api/basic_json/from_msgpack.md b/doc/mkdocs/docs/api/basic_json/from_msgpack.md
index 9f68524..117c386 100644
--- a/doc/mkdocs/docs/api/basic_json/from_msgpack.md
+++ b/doc/mkdocs/docs/api/basic_json/from_msgpack.md
@@ -1,4 +1,4 @@
-# basic_json::from_msgpack
+# <small>nlohmann::basic_json::</small>from_msgpack
```cpp
// (1)
@@ -18,6 +18,8 @@
1. Reads from a compatible input.
2. Reads from an iterator range.
+The exact mapping and its limitations is described on a [dedicated page](../../features/binary_formats/messagepack.md).
+
## Template parameters
`InputType`
@@ -58,11 +60,20 @@
Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
+## Exceptions
+
+- Throws [parse_error.110](../../home/exceptions.md#jsonexceptionparse_error110) if the given input ends prematurely or
+ the end of file was not reached when `strict` was set to true
+- Throws [parse_error.112](../../home/exceptions.md#jsonexceptionparse_error112) if unsupported features from
+ MessagePack were used in the given input or if the input is not valid MessagePack
+- Throws [parse_error.113](../../home/exceptions.md#jsonexceptionparse_error113) if a string was expected as map key,
+ but not found
+
## Complexity
Linear in the size of the input.
-## Example
+## Examples
??? example
@@ -84,3 +95,15 @@
- Parameter `start_index` since version 2.1.1.
- Changed to consume input adapters, removed `start_index` parameter, and added `strict` parameter in version 3.0.0.
- Added `allow_exceptions` parameter in version 3.2.0.
+
+!!! warning "Deprecation"
+
+ - Overload (2) replaces calls to `from_msgpack` with a pointer and a length as first two parameters, which has been
+ deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
+ `#!cpp from_msgpack(ptr, len, ...);` with `#!cpp from_msgpack(ptr, ptr+len, ...);`.
+ - Overload (2) replaces calls to `from_cbor` with a pair of iterators as their first parameter, which has been
+ deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
+ `#!cpp from_msgpack({ptr, ptr+len}, ...);` with `#!cpp from_msgpack(ptr, ptr+len, ...);`.
+
+ You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated
+ function.
diff --git a/doc/mkdocs/docs/api/basic_json/from_ubjson.md b/doc/mkdocs/docs/api/basic_json/from_ubjson.md
index f6213f2..08117e8 100644
--- a/doc/mkdocs/docs/api/basic_json/from_ubjson.md
+++ b/doc/mkdocs/docs/api/basic_json/from_ubjson.md
@@ -1,4 +1,4 @@
-# basic_json::from_ubjson
+# <small>nlohmann::basic_json::</small>from_ubjson
```cpp
// (1)
@@ -18,6 +18,8 @@
1. Reads from a compatible input.
2. Reads from an iterator range.
+The exact mapping and its limitations is described on a [dedicated page](../../features/binary_formats/ubjson.md).
+
## Template parameters
`InputType`
@@ -58,11 +60,19 @@
Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
+## Exceptions
+
+- Throws [parse_error.110](../../home/exceptions.md#jsonexceptionparse_error110) if the given input ends prematurely or
+ the end of file was not reached when `strict` was set to true
+- Throws [parse_error.112](../../home/exceptions.md#jsonexceptionparse_error112) if a parse error occurs
+- Throws [parse_error.113](../../home/exceptions.md#jsonexceptionparse_error113) if a string could not be parsed
+ successfully
+
## Complexity
Linear in the size of the input.
-## Example
+## Examples
??? example
@@ -82,3 +92,15 @@
- Added in version 3.1.0.
- Added `allow_exceptions` parameter in version 3.2.0.
+
+!!! warning "Deprecation"
+
+ - Overload (2) replaces calls to `from_ubjson` with a pointer and a length as first two parameters, which has been
+ deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
+ `#!cpp from_ubjson(ptr, len, ...);` with `#!cpp from_ubjson(ptr, ptr+len, ...);`.
+ - Overload (2) replaces calls to `from_ubjson` with a pair of iterators as their first parameter, which has been
+ deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
+ `#!cpp from_ubjson({ptr, ptr+len}, ...);` with `#!cpp from_ubjson(ptr, ptr+len, ...);`.
+
+ You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated
+ function.
diff --git a/doc/mkdocs/docs/api/basic_json/front.md b/doc/mkdocs/docs/api/basic_json/front.md
index 55010fb..909f0b5 100644
--- a/doc/mkdocs/docs/api/basic_json/front.md
+++ b/doc/mkdocs/docs/api/basic_json/front.md
@@ -1,4 +1,4 @@
-# basic_json::front
+# <small>nlohmann::basic_json::</small>front
```cpp
reference front();
@@ -13,26 +13,26 @@
In case of a structured type (array or object), a reference to the first element is returned. In case of number, string,
boolean, or binary values, a reference to the value is returned.
+## Exception safety
+
+Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
+
## Exceptions
If the JSON value is `#!json null`, exception
[`invalid_iterator.214`](../../home/exceptions.md#jsonexceptioninvalid_iterator214) is thrown.
-## Exception safety
-
-Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
-
## Complexity
Constant.
-## Note
+## Notes
!!! danger
Calling `front` on an empty array or object is undefined behavior and is **guarded by an assertion**!
-## Example
+## Examples
??? example
@@ -48,6 +48,10 @@
--8<-- "examples/front.output"
```
+## See also
+
+- [back](back.md) to access the last element
+
## Version history
- Added in version 1.0.0.
diff --git a/doc/mkdocs/docs/api/basic_json/get.md b/doc/mkdocs/docs/api/basic_json/get.md
index 6cd6630..0a0bc3b 100644
--- a/doc/mkdocs/docs/api/basic_json/get.md
+++ b/doc/mkdocs/docs/api/basic_json/get.md
@@ -1,4 +1,4 @@
-# basic_json::get
+# <small>nlohmann::basic_json::</small>get
```cpp
// (1)
@@ -31,7 +31,7 @@
return ret;
```
- This overloads is chosen if:
+ This overload is chosen if:
- `ValueType` is not `basic_json`,
- `json_serializer<ValueType>` has a `from_json()` method of the form
@@ -48,7 +48,7 @@
return JSONSerializer<ValueTypeCV>::from_json(*this);
```
- This overloads is chosen if:
+ This overload is chosen if:
- `ValueType` is not `basic_json` and
- `json_serializer<ValueType>` has a `from_json()` method of the form
@@ -94,7 +94,7 @@
Writing data to the pointee (overload 3) of the result yields an undefined state.
-## Example
+## Examples
??? example
diff --git a/doc/mkdocs/docs/api/basic_json/get_allocator.md b/doc/mkdocs/docs/api/basic_json/get_allocator.md
index d4133af..1b7700c 100644
--- a/doc/mkdocs/docs/api/basic_json/get_allocator.md
+++ b/doc/mkdocs/docs/api/basic_json/get_allocator.md
@@ -1,4 +1,4 @@
-# basic_json::get_allocator
+# <small>nlohmann::basic_json::</small>get_allocator
```cpp
static allocator_type get_allocator();
@@ -13,3 +13,7 @@
## Version history
- Unknown.
+
+!!! note
+
+ This documentation page is a stub.
diff --git a/doc/mkdocs/docs/api/basic_json/get_binary.md b/doc/mkdocs/docs/api/basic_json/get_binary.md
index 46d5b65..a910f3a 100644
--- a/doc/mkdocs/docs/api/basic_json/get_binary.md
+++ b/doc/mkdocs/docs/api/basic_json/get_binary.md
@@ -1,4 +1,4 @@
-# basic_json::get_binary
+# <small>nlohmann::basic_json::</small>get_binary
```cpp
binary_t& get_binary();
@@ -24,6 +24,22 @@
Constant.
+## Examples
+
+??? example
+
+ The following code shows how to query a binary value.
+
+ ```cpp
+ --8<-- "examples/get_binary.cpp"
+ ```
+
+ Output:
+
+ ```json
+ --8<-- "examples/get_binary.output"
+ ```
+
## Version history
- Added in version 3.8.0.
diff --git a/doc/mkdocs/docs/api/basic_json/get_ptr.md b/doc/mkdocs/docs/api/basic_json/get_ptr.md
index c5cee30..72517cd 100644
--- a/doc/mkdocs/docs/api/basic_json/get_ptr.md
+++ b/doc/mkdocs/docs/api/basic_json/get_ptr.md
@@ -1,8 +1,8 @@
-# basic_json::get_ptr
+# <small>nlohmann::basic_json::</small>get_ptr
```cpp
template<typename PointerType>
-PointerType get_ptr();
+PointerType get_ptr() noexcept;
template<typename PointerType>
constexpr const PointerType get_ptr() const noexcept;
@@ -10,7 +10,7 @@
Implicit pointer access to the internally stored JSON value. No copies are made.
-## Template arguments
+## Template parameters
`PointerType`
: pointer type; must be a pointer to [`array_t`](array_t.md), [`object_t`](object_t.md), [`string_t`](string_t.md),
@@ -25,7 +25,7 @@
## Exception safety
-Strong exception safety: if an exception occurs, the original value stays intact.
+No-throw guarantee: this function never throws exceptions.
## Complexity
@@ -37,7 +37,7 @@
Writing data to the pointee of the result yields an undefined state.
-## Example
+## Examples
??? example
diff --git a/doc/mkdocs/docs/api/basic_json/get_ref.md b/doc/mkdocs/docs/api/basic_json/get_ref.md
index 102aff1..1140836 100644
--- a/doc/mkdocs/docs/api/basic_json/get_ref.md
+++ b/doc/mkdocs/docs/api/basic_json/get_ref.md
@@ -1,4 +1,4 @@
-# basic_json::get_ref
+# <small>nlohmann::basic_json::</small>get_ref
```cpp
template<typename ReferenceType>
@@ -10,7 +10,7 @@
Implicit reference access to the internally stored JSON value. No copies are made.
-## Template arguments
+## Template parameters
`ReferenceType`
: reference type; must be a reference to [`array_t`](array_t.md), [`object_t`](object_t.md),
@@ -42,7 +42,7 @@
Writing data to the referee of the result yields an undefined state.
-## Example
+## Examples
??? example
diff --git a/doc/mkdocs/docs/api/basic_json/get_to.md b/doc/mkdocs/docs/api/basic_json/get_to.md
index 4a4395b..6af6d21 100644
--- a/doc/mkdocs/docs/api/basic_json/get_to.md
+++ b/doc/mkdocs/docs/api/basic_json/get_to.md
@@ -1,10 +1,10 @@
-# basic_json::get_to
+# <small>nlohmann::basic_json::</small>get_to
```cpp
template<typename ValueType>
ValueType& get_to(ValueType& v) const noexcept(
noexcept(JSONSerializer<ValueType>::from_json(
- std::declval<const basic_json_t&>(), v)))
+ std::declval<const basic_json_t&>(), v)));
```
Explicit type conversion between the JSON value and a compatible value. The value is filled into the input parameter by
@@ -16,7 +16,7 @@
JSONSerializer<ValueType>::from_json(*this, v);
```
-This overloads is chosen if:
+This overload is chosen if:
- `ValueType` is not `basic_json`,
- `json_serializer<ValueType>` has a `from_json()` method of the form `void from_json(const basic_json&, ValueType&)`
@@ -34,7 +34,7 @@
Depends on what `json_serializer<ValueType>` `from_json()` method throws
-## Example
+## Examples
??? example
diff --git a/doc/mkdocs/docs/api/basic_json/index.md b/doc/mkdocs/docs/api/basic_json/index.md
index e8841e8..eb90ac6 100644
--- a/doc/mkdocs/docs/api/basic_json/index.md
+++ b/doc/mkdocs/docs/api/basic_json/index.md
@@ -1,6 +1,6 @@
-# basic_json
+# <small>nlohmann::</small>basic_json
-Defined in header `<json.hpp>`
+<small>Defined in header `<nlohmann/json.hpp>`</small>
```cpp
template<
@@ -18,41 +18,83 @@
class basic_json;
```
+## Template parameters
+
+| Template parameter | Description | Derived type |
+|----------------------|---------------------------------------------------------------------------|---------------------------------------------|
+| `ObjectType` | type for JSON objects | [`object_t`](object_t.md) |
+| `ArrayType` | type for JSON arrays | [`array_t`](array_t.md) |
+| `StringType` | type for JSON strings and object keys | [`string_t`](string_t.md) |
+| `BooleanType` | type for JSON booleans | [`boolean_t`](boolean_t.md) |
+| `NumberIntegerType` | type for JSON integer numbers | [`number_integer_t`](number_integer_t.md) |
+| `NumberUnsignedType` | type for JSON unsigned integer numbers | [`number_unsigned_t`](number_unsigned_t.md) |
+| `NumberFloatType` | type for JSON floating-point numbers | [`number_float_t`](number_float_t.md) |
+| `AllocatorType` | type of the allocator to use | |
+| `JSONSerializer` | the serializer to resolve internal calls to `to_json()` and `from_json()` | [`json_serializer`](json_serializer.md) |
+| `BinaryType` | type for binary arrays | [`binary_t`](binary_t.md) |
+
## Specializations
- [**json**](../json.md) - default specialization
- [**ordered_json**](../ordered_json.md) - specialization that maintains the insertion order of object keys
-## Template parameters
-
-| Template parameter | Description | Derived type |
-| -------------------- | ----------- | ------------ |
-| `ObjectType` | type for JSON objects | [`object_t`](object_t.md) |
-| `ArrayType` | type for JSON arrays | [`array_t`](array_t.md) |
-| `StringType` | type for JSON strings and object keys | [`string_t`](string_t.md) |
-| `BooleanType` | type for JSON booleans | [`boolean_t`](boolean_t.md) |
-| `NumberIntegerType` | type for JSON integer numbers | [`number_integer_t`](number_integer_t.md) |
-| `NumberUnsignedType` | type for JSON unsigned integer numbers | [`number_unsigned_t`](number_unsigned_t.md) |
-| `NumberFloatType` | type for JSON floating-point numbers | [`number_float_t`](number_float_t.md) |
-| `AllocatorType` | type of the allocator to use | |
-| `JSONSerializer` | the serializer to resolve internal calls to `to_json()` and `from_json()` | [`json_serializer`](json_serializer.md) |
-| `BinaryType` | type for binary arrays | [`binary_t`](binary_t.md) |
-
## Iterator invalidation
Todo
+## Requirements
+
+The class satisfies the following concept requirements:
+
+### Basic
+
+- [DefaultConstructible](https://en.cppreference.com/w/cpp/named_req/DefaultConstructible): JSON values can be default
+ constructed. The result will be a JSON null value.
+- [MoveConstructible](https://en.cppreference.com/w/cpp/named_req/MoveConstructible): A JSON value can be constructed
+ from an rvalue argument.
+- [CopyConstructible](https://en.cppreference.com/w/cpp/named_req/CopyConstructible): A JSON value can be
+ copy-constructed from an lvalue expression.
+- [MoveAssignable](https://en.cppreference.com/w/cpp/named_req/MoveAssignable): A JSON value van be assigned from an
+ rvalue argument.
+- [CopyAssignable](https://en.cppreference.com/w/cpp/named_req/CopyAssignable): A JSON value can be copy-assigned from
+ an lvalue expression.
+- [Destructible](https://en.cppreference.com/w/cpp/named_req/Destructible): JSON values can be destructed.
+
+### Layout
+
+- [StandardLayoutType](https://en.cppreference.com/w/cpp/named_req/StandardLayoutType): JSON values have
+ [standard layout](https://en.cppreference.com/w/cpp/language/data_members#Standard_layout): All non-static data
+ members are private and standard layout types, the class has no virtual functions or (virtual) base classes.
+
+### Library-wide
+
+- [EqualityComparable](https://en.cppreference.com/w/cpp/named_req/EqualityComparable): JSON values can be compared with
+ `==`, see [`operator==`](operator_eq.md).
+- [LessThanComparable](https://en.cppreference.com/w/cpp/named_req/LessThanComparable): JSON values can be compared with
+ `<`, see [`operator<`](operator_le).
+- [Swappable](https://en.cppreference.com/w/cpp/named_req/Swappable): Any JSON lvalue or rvalue of can be swapped with
+ any lvalue or rvalue of other compatible types, using unqualified function `swap`.
+- [NullablePointer](https://en.cppreference.com/w/cpp/named_req/NullablePointer): JSON values can be compared against
+ `std::nullptr_t` objects which are used to model the `null` value.
+
+### Container
+
+- [Container](https://en.cppreference.com/w/cpp/named_req/Container): JSON values can be used like STL containers and
+ provide iterator access.
+- [ReversibleContainer](https://en.cppreference.com/w/cpp/named_req/ReversibleContainer): JSON values can be used like
+ STL containers and provide reverse iterator access.
+
## Member types
-- [**adl_serializer**](../adl_serializer.md) - the default serializer
+- [**adl_serializer**](../adl_serializer) - the default serializer
- [**value_t**](value_t.md) - the JSON type enumeration
-- [**json_pointer**](../json_pointer.md) - JSON Pointer implementation
+- [**json_pointer**](../json_pointer/index.md) - JSON Pointer implementation
- [**json_serializer**](json_serializer.md) - type of the serializer to for conversions from/to JSON
- [**error_handler_t**](error_handler_t.md) - type to choose behavior on decoding errors
- [**cbor_tag_handler_t**](cbor_tag_handler_t.md) - type to choose how to handle CBOR tags
-- initializer_list_t
+- **initializer_list_t** - type for initializer lists of `basic_json` values
- [**input_format_t**](input_format_t.md) - type to choose the format to parse
-- json_sax_t
+- [**json_sax_t**](../json_sax/index.md) - type for SAX events
### Exceptions
@@ -65,21 +107,21 @@
### Container types
-| Type | Definition |
-| ------------------------ | ---------- |
-| `value_type` | `#!cpp basic_json` |
-| `reference` | `#!cpp value_type&` |
-| `const_reference` | `#!cpp const value_type&` |
-| `difference_type` | `#!cpp std::ptrdiff_t` |
-| `size_type` | `#!cpp std::size_t` |
-| `allocator_type` | `#!cpp AllocatorType<basic_json>` |
-| `pointer` | `#!cpp std::allocator_traits<allocator_type>::pointer` |
-| `const_pointer` | `#!cpp std::allocator_traits<allocator_type>::const_pointer` |
-| `iterator` | [LegacyBidirectionalIterator](https://en.cppreference.com/w/cpp/named_req/BidirectionalIterator) |
+| Type | Definition |
+|--------------------------|-----------------------------------------------------------------------------------------------------------|
+| `value_type` | `#!cpp basic_json` |
+| `reference` | `#!cpp value_type&` |
+| `const_reference` | `#!cpp const value_type&` |
+| `difference_type` | `#!cpp std::ptrdiff_t` |
+| `size_type` | `#!cpp std::size_t` |
+| `allocator_type` | `#!cpp AllocatorType<basic_json>` |
+| `pointer` | `#!cpp std::allocator_traits<allocator_type>::pointer` |
+| `const_pointer` | `#!cpp std::allocator_traits<allocator_type>::const_pointer` |
+| `iterator` | [LegacyBidirectionalIterator](https://en.cppreference.com/w/cpp/named_req/BidirectionalIterator) |
| `const_iterator` | constant [LegacyBidirectionalIterator](https://en.cppreference.com/w/cpp/named_req/BidirectionalIterator) |
-| `reverse_iterator` | reverse iterator, derived from `iterator` |
-| `const_reverse_iterator` | reverse iterator, derived from `const_iterator` |
-| `iteration_proxy` | helper type for [`items`](items.md) function |
+| `reverse_iterator` | reverse iterator, derived from `iterator` |
+| `const_reverse_iterator` | reverse iterator, derived from `const_iterator` |
+| `iteration_proxy` | helper type for [`items`](items.md) function |
### JSON value data types
@@ -103,9 +145,9 @@
- [(constructor)](basic_json.md)
- [(destructor)](~basic_json.md)
- [**operator=**](operator=.md) - copy assignment
-- [**array**](array_t.md) (static) - explicitly create an array
-- [**binary**](binary.md) (static) - explicitly create a binary array
-- [**object**](object_t.md) (static) - explicitly create an object
+- [**array**](array_t.md) (_static_) - explicitly create an array
+- [**binary**](binary.md) (_static_) - explicitly create a binary array
+- [**object**](object_t.md) (_static_) - explicitly create an object
### Object inspection
@@ -183,7 +225,7 @@
- [**erase**](erase.md) - remove elements
- [**insert**](insert.md) - inserts elements
- [**update**](update.md) - updates a JSON object from another object, overwriting existing keys
-- swap - exchanges the values
+- [**swap**](swap.md) - exchanges the values
### Lexicographical comparison operators
@@ -197,13 +239,12 @@
### Serialization / Dumping
- [**dump**](dump.md) - serialization
-- to_string - user-defined to_string function for JSON values
### Deserialization / Parsing
-- [**parse**](parse.md) (static) - deserialize from a compatible input
-- [**accept**](accept.md) (static) - check if the input is valid JSON
-- [**sax_parse**](sax_parse.md) (static) - generate SAX events
+- [**parse**](parse.md) (_static_) - deserialize from a compatible input
+- [**accept**](accept.md) (_static_) - check if the input is valid JSON
+- [**sax_parse**](sax_parse.md) (_static_) - generate SAX events
### JSON Pointer functions
@@ -213,7 +254,7 @@
### JSON Patch functions
- [**patch**](patch.md) - applies a JSON patch
-- [**diff**](diff.md) (static) - creates a diff as a JSON patch
+- [**diff**](diff.md) (_static_) - creates a diff as a JSON patch
### JSON Merge Patch functions
@@ -226,19 +267,20 @@
### Binary formats
-- [**from_bson**](from_bson.md) (static) - create a JSON value from an input in BSON format
-- [**from_cbor**](from_cbor.md) (static) - create a JSON value from an input in CBOR format
-- [**from_msgpack**](from_msgpack.md) (static) - create a JSON value from an input in MessagePack format
-- [**from_ubjson**](from_ubjson.md) (static) - create a JSON value from an input in UBJSON format
-- [**to_bson**](to_bson.md) (static) - create a BSON serialization of a given JSON value
-- [**to_cbor**](to_cbor.md) (static) - create a CBOR serialization of a given JSON value
-- [**to_msgpack**](to_msgpack.md) (static) - create a MessagePack serialization of a given JSON value
-- [**to_ubjson**](to_ubjson.md) (static) - create a UBJSON serialization of a given JSON value
+- [**from_bson**](from_bson.md) (_static_) - create a JSON value from an input in BSON format
+- [**from_cbor**](from_cbor.md) (_static_) - create a JSON value from an input in CBOR format
+- [**from_msgpack**](from_msgpack.md) (_static_) - create a JSON value from an input in MessagePack format
+- [**from_ubjson**](from_ubjson.md) (_static_) - create a JSON value from an input in UBJSON format
+- [**to_bson**](to_bson.md) (_static_) - create a BSON serialization of a given JSON value
+- [**to_cbor**](to_cbor.md) (_static_) - create a CBOR serialization of a given JSON value
+- [**to_msgpack**](to_msgpack.md) (_static_) - create a MessagePack serialization of a given JSON value
+- [**to_ubjson**](to_ubjson.md) (_static_) - create a UBJSON serialization of a given JSON value
## Non-member functions
-- operator<<(std::ostream&) - serialize to stream
-- operator>>(std::istream&) - deserialize from stream
+- [**operator<<(std::ostream&)**](operator_ltlt.md) - serialize to stream
+- [**operator>>(std::istream&)**](operator_gtgt.md) - deserialize from stream
+- [**to_string**](to_string.md) - user-defined `to_string` function for JSON values
## Literals
@@ -247,6 +289,29 @@
## Helper classes
-- std::hash<nlohmann::json\>
-- std::less<nlohmann::value_t\>
-- std::swap<nlohmann::json\>
+- [**std::hash<basic_json>**](std_hash.md) - return a hash value for a JSON object
+- [**std::swap<basic_json>**](std_swap.md) - exchanges the values of two JSON objects
+
+## Example
+
+??? example
+
+ The example shows how the library is used.
+
+ ```cpp
+ --8<-- "examples/README.cpp"
+ ```
+
+ Output:
+
+ ```json
+ --8<-- "examples/README.output"
+ ```
+
+## See also
+
+- [RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format](https://tools.ietf.org/html/rfc8259)
+
+## Version history
+
+- Added in version 1.0.0.
diff --git a/doc/mkdocs/docs/api/basic_json/input_format_t.md b/doc/mkdocs/docs/api/basic_json/input_format_t.md
index 783085d..4accf6d 100644
--- a/doc/mkdocs/docs/api/basic_json/input_format_t.md
+++ b/doc/mkdocs/docs/api/basic_json/input_format_t.md
@@ -1,4 +1,4 @@
-# basic_json::input_format_t
+# <small>nlohmann::basic_json::</small>input_format_t
```cpp
enum class input_format_t {
@@ -25,7 +25,7 @@
: UBJSON (Universal Binary JSON)
bson
-: BSON (Binary JSON)
+: BSON (Binary JSON)
## Version history
diff --git a/doc/mkdocs/docs/api/basic_json/insert.md b/doc/mkdocs/docs/api/basic_json/insert.md
index fbd4668..fdd8fe6 100644
--- a/doc/mkdocs/docs/api/basic_json/insert.md
+++ b/doc/mkdocs/docs/api/basic_json/insert.md
@@ -1,4 +1,4 @@
-# basic_json::insert
+# <small>nlohmann::basic_json::</small>insert
```cpp
// (1)
@@ -18,11 +18,11 @@
void insert(const_iterator first, const_iterator last);
```
-1. Inserts element `val` to array before iterator `pos`.
-2. Inserts `cnt` copies of `val` to array before iterator `pos`.
-3. Inserts elements from range `[first, last)` to array before iterator `pos`.
-4. Inserts elements from initializer list `ilist` to array before iterator `pos`.
-5. Inserts elements from range `[first, last)` to object.
+1. Inserts element `val` into array before iterator `pos`.
+2. Inserts `cnt` copies of `val` into array before iterator `pos`.
+3. Inserts elements from range `[first, last)` into array before iterator `pos`.
+4. Inserts elements from initializer list `ilist` into array before iterator `pos`.
+5. Inserts elements from range `[first, last)` into object.
## Parameters
@@ -52,6 +52,10 @@
4. iterator pointing to the first element inserted, or `pos` if `ilist` is empty
5. /
+## Exception safety
+
+Strong exception safety: if an exception occurs, the original value stays intact.
+
## Exceptions
1. The function can throw the following exceptions:
@@ -59,12 +63,12 @@
arrays; example: `"cannot use insert() with string"`
- Throws [`invalid_iterator.202`](../../home/exceptions.md#jsonexceptioninvalid_iterator202) if called on an
iterator which does not belong to the current JSON value; example: `"iterator does not fit current value"`
-2. The function can throw thw following exceptions:
+2. The function can throw the following exceptions:
- Throws [`type_error.309`](../../home/exceptions.md#jsonexceptiontype_error309) if called on JSON values other than
arrays; example: `"cannot use insert() with string"`
- Throws [`invalid_iterator.202`](../../home/exceptions.md#jsonexceptioninvalid_iterator202) if called on an
iterator which does not belong to the current JSON value; example: `"iterator does not fit current value"`
-3. The function can throw thw following exceptions:
+3. The function can throw the following exceptions:
- Throws [`type_error.309`](../../home/exceptions.md#jsonexceptiontype_error309) if called on JSON values other than
arrays; example: `"cannot use insert() with string"`
- Throws [`invalid_iterator.202`](../../home/exceptions.md#jsonexceptioninvalid_iterator202) if called on an
@@ -73,12 +77,12 @@
do not belong to the same JSON value; example: `"iterators do not fit"`
- Throws [`invalid_iterator.211`](../../home/exceptions.md#jsonexceptioninvalid_iterator211) if `first` or `last`
are iterators into container for which insert is called; example: `"passed iterators may not belong to container"`
-4. The function can throw thw following exceptions:
+4. The function can throw the following exceptions:
- Throws [`type_error.309`](../../home/exceptions.md#jsonexceptiontype_error309) if called on JSON values other than
arrays; example: `"cannot use insert() with string"`
- Throws [`invalid_iterator.202`](../../home/exceptions.md#jsonexceptioninvalid_iterator202) if called on an
iterator which does not belong to the current JSON value; example: `"iterator does not fit current value"`
-5. The function can throw thw following exceptions:
+5. The function can throw the following exceptions:
- Throws [`type_error.309`](../../home/exceptions.md#jsonexceptiontype_error309) if called on JSON values other than
objects; example: `"cannot use insert() with string"`
- Throws [`invalid_iterator.202`](../../home/exceptions.md#jsonexceptioninvalid_iterator202) if called on an
@@ -86,10 +90,6 @@
- Throws [`invalid_iterator.210`](../../home/exceptions.md#jsonexceptioninvalid_iterator210) if `first` and `last`
do not belong to the same JSON value; example: `"iterators do not fit"`
-## Exception safety
-
-Strong exception safety: if an exception occurs, the original value stays intact.
-
## Complexity
1. Constant plus linear in the distance between `pos` and end of the container.
@@ -98,9 +98,9 @@
4. Linear in `ilist.size()` plus linear in the distance between `pos` and end of the container.
5. Logarithmic: `O(N*log(size() + N))`, where `N` is the number of elements to insert.
-## Example
+## Examples
-??? example
+??? example "Example (1): insert element into array"
The example shows how `insert()` is used.
@@ -114,7 +114,7 @@
--8<-- "examples/insert.output"
```
-??? example
+??? example "Example (2): insert copies of element into array"
The example shows how `insert()` is used.
@@ -128,7 +128,7 @@
--8<-- "examples/insert__count.output"
```
-??? example
+??? example "Example (3): insert range of elements into array"
The example shows how `insert()` is used.
@@ -142,7 +142,7 @@
--8<-- "examples/insert__range.output"
```
-??? example
+??? example "Example (4): insert elements from initializer list into array"
The example shows how `insert()` is used.
@@ -156,7 +156,7 @@
--8<-- "examples/insert__ilist.output"
```
-??? example
+??? example "Example (5): insert range of elements into object"
The example shows how `insert()` is used.
diff --git a/doc/mkdocs/docs/api/basic_json/invalid_iterator.md b/doc/mkdocs/docs/api/basic_json/invalid_iterator.md
index b11b27d..f9fdce5 100644
--- a/doc/mkdocs/docs/api/basic_json/invalid_iterator.md
+++ b/doc/mkdocs/docs/api/basic_json/invalid_iterator.md
@@ -1,4 +1,4 @@
-# basic_json::invalid_iterator
+# <small>nlohmann::basic_json::</small>invalid_iterator
```cpp
class invalid_iterator : public exception;
@@ -6,7 +6,7 @@
This exception is thrown if iterators passed to a library function do not match the expected semantics.
-Exceptions have ids 2xx.
+Exceptions have ids 2xx (see [list of iterator errors](../../home/exceptions.md#iterator-errors)).
```plantuml
std::exception <|-- basic_json::exception
@@ -38,7 +38,7 @@
- **id** - the id of the exception
-## Example
+## Examples
??? example
@@ -54,6 +54,14 @@
--8<-- "examples/invalid_iterator.output"
```
+## See also
+
+- [List of iterator errors](../../home/exceptions.md#iterator-errors)
+- [`parse_error`](parse_error.md) for exceptions indicating a parse error
+- [`type_error`](type_error.md) for exceptions indicating executing a member function with a wrong type
+- [`out_of_range`](out_of_range.md) for exceptions indicating access out of the defined range
+- [`other_error`](other_error.md) for exceptions indicating other library errors
+
## Version history
- Since version 3.0.0.
diff --git a/doc/mkdocs/docs/api/basic_json/is_array.md b/doc/mkdocs/docs/api/basic_json/is_array.md
index a303795..64468c3 100644
--- a/doc/mkdocs/docs/api/basic_json/is_array.md
+++ b/doc/mkdocs/docs/api/basic_json/is_array.md
@@ -1,4 +1,4 @@
-# basic_json::is_array
+# <small>nlohmann::basic_json::</small>is_array
```cpp
constexpr bool is_array() const noexcept;
@@ -18,7 +18,7 @@
Constant.
-## Example
+## Examples
??? example
diff --git a/doc/mkdocs/docs/api/basic_json/is_binary.md b/doc/mkdocs/docs/api/basic_json/is_binary.md
index f2285bb..ea48d74 100644
--- a/doc/mkdocs/docs/api/basic_json/is_binary.md
+++ b/doc/mkdocs/docs/api/basic_json/is_binary.md
@@ -1,4 +1,4 @@
-# basic_json::is_binary
+# <small>nlohmann::basic_json::</small>is_binary
```cpp
constexpr bool is_binary() const noexcept;
@@ -18,7 +18,7 @@
Constant.
-## Example
+## Examples
??? example
diff --git a/doc/mkdocs/docs/api/basic_json/is_boolean.md b/doc/mkdocs/docs/api/basic_json/is_boolean.md
index 32bb8c4..dc41d84 100644
--- a/doc/mkdocs/docs/api/basic_json/is_boolean.md
+++ b/doc/mkdocs/docs/api/basic_json/is_boolean.md
@@ -1,4 +1,4 @@
-# basic_json::is_boolean
+# <small>nlohmann::basic_json::</small>is_boolean
```cpp
constexpr bool is_boolean() const noexcept;
@@ -18,7 +18,7 @@
Constant.
-## Example
+## Examples
??? example
diff --git a/doc/mkdocs/docs/api/basic_json/is_discarded.md b/doc/mkdocs/docs/api/basic_json/is_discarded.md
index b733f62..405ae6c 100644
--- a/doc/mkdocs/docs/api/basic_json/is_discarded.md
+++ b/doc/mkdocs/docs/api/basic_json/is_discarded.md
@@ -1,4 +1,4 @@
-# basic_json::is_discarded
+# <small>nlohmann::basic_json::</small>is_discarded
```cpp
constexpr bool is_discarded() const noexcept;
@@ -51,7 +51,7 @@
This function will always be `#!cpp false` for JSON values after parsing. That is, discarded values can only occur
during parsing, but will be removed when inside a structured value or replaced by null in other cases.
-## Example
+## Examples
??? example
diff --git a/doc/mkdocs/docs/api/basic_json/is_null.md b/doc/mkdocs/docs/api/basic_json/is_null.md
index 8072642..d080ad3 100644
--- a/doc/mkdocs/docs/api/basic_json/is_null.md
+++ b/doc/mkdocs/docs/api/basic_json/is_null.md
@@ -1,4 +1,4 @@
-# basic_json::is_null
+# <small>nlohmann::basic_json::</small>is_null
```cpp
constexpr bool is_null() const noexcept;
@@ -18,7 +18,7 @@
Constant.
-## Example
+## Examples
??? example
diff --git a/doc/mkdocs/docs/api/basic_json/is_number.md b/doc/mkdocs/docs/api/basic_json/is_number.md
index 9bcb131..9807911 100644
--- a/doc/mkdocs/docs/api/basic_json/is_number.md
+++ b/doc/mkdocs/docs/api/basic_json/is_number.md
@@ -1,4 +1,4 @@
-# basic_json::is_number
+# <small>nlohmann::basic_json::</small>is_number
```cpp
constexpr bool is_number() const noexcept;
@@ -28,7 +28,7 @@
}
```
-## Example
+## Examples
??? example
@@ -44,6 +44,12 @@
--8<-- "examples/is_number.output"
```
+## See also
+
+- [is_number_integer()](is_number_integer.md) check if value is an integer or unsigned integer number
+- [is_number_unsigned()](is_number_unsigned.md) check if value is an unsigned integer number
+- [is_number_float()](is_number_float.md) check if value is a floating-point number
+
## Version history
- Added in version 1.0.0.
diff --git a/doc/mkdocs/docs/api/basic_json/is_number_float.md b/doc/mkdocs/docs/api/basic_json/is_number_float.md
index d709bf7..68d0cfb 100644
--- a/doc/mkdocs/docs/api/basic_json/is_number_float.md
+++ b/doc/mkdocs/docs/api/basic_json/is_number_float.md
@@ -1,4 +1,4 @@
-# basic_json::is_number_float
+# <small>nlohmann::basic_json::</small>is_number_float
```cpp
constexpr bool is_number_float() const noexcept;
@@ -19,7 +19,7 @@
Constant.
-## Example
+## Examples
??? example
@@ -35,6 +35,12 @@
--8<-- "examples/is_number_float.output"
```
+## See also
+
+- [is_number()](is_number.md) check if value is a number
+- [is_number_integer()](is_number_integer.md) check if value is an integer or unsigned integer number
+- [is_number_unsigned()](is_number_unsigned.md) check if value is an unsigned integer number
+
## Version history
- Added in version 1.0.0.
diff --git a/doc/mkdocs/docs/api/basic_json/is_number_integer.md b/doc/mkdocs/docs/api/basic_json/is_number_integer.md
index c308c92..8ca214a 100644
--- a/doc/mkdocs/docs/api/basic_json/is_number_integer.md
+++ b/doc/mkdocs/docs/api/basic_json/is_number_integer.md
@@ -1,4 +1,4 @@
-# basic_json::is_number_integer
+# <small>nlohmann::basic_json::</small>is_number_integer
```cpp
constexpr bool is_number_integer() const noexcept;
@@ -19,7 +19,7 @@
Constant.
-## Example
+## Examples
??? example
@@ -35,6 +35,12 @@
--8<-- "examples/is_number_integer.output"
```
+## See also
+
+- [is_number()](is_number.md) check if value is a number
+- [is_number_unsigned()](is_number_unsigned.md) check if value is an unsigned integer number
+- [is_number_float()](is_number_float.md) check if value is a floating-point number
+
## Version history
- Added in version 1.0.0.
diff --git a/doc/mkdocs/docs/api/basic_json/is_number_unsigned.md b/doc/mkdocs/docs/api/basic_json/is_number_unsigned.md
index 56493ea..2ac98a5 100644
--- a/doc/mkdocs/docs/api/basic_json/is_number_unsigned.md
+++ b/doc/mkdocs/docs/api/basic_json/is_number_unsigned.md
@@ -1,4 +1,4 @@
-# basic_json::is_number_unsigned
+# <small>nlohmann::basic_json::</small>is_number_unsigned
```cpp
constexpr bool is_number_unsigned() const noexcept;
@@ -19,7 +19,7 @@
Constant.
-## Example
+## Examples
??? example
@@ -35,6 +35,12 @@
--8<-- "examples/is_number_unsigned.output"
```
+## See also
+
+- [is_number()](is_number.md) check if value is a number
+- [is_number_integer()](is_number_integer.md) check if value is an integer or unsigned integer number
+- [is_number_float()](is_number_float.md) check if value is a floating-point number
+
## Version history
- Added in version 2.0.0.
diff --git a/doc/mkdocs/docs/api/basic_json/is_object.md b/doc/mkdocs/docs/api/basic_json/is_object.md
index 22a1563..0445701 100644
--- a/doc/mkdocs/docs/api/basic_json/is_object.md
+++ b/doc/mkdocs/docs/api/basic_json/is_object.md
@@ -1,4 +1,4 @@
-# basic_json::is_object
+# <small>nlohmann::basic_json::</small>is_object
```cpp
constexpr bool is_object() const noexcept;
@@ -18,7 +18,7 @@
Constant.
-## Example
+## Examples
??? example
diff --git a/doc/mkdocs/docs/api/basic_json/is_primitive.md b/doc/mkdocs/docs/api/basic_json/is_primitive.md
index 37be35c..cf6cbbd 100644
--- a/doc/mkdocs/docs/api/basic_json/is_primitive.md
+++ b/doc/mkdocs/docs/api/basic_json/is_primitive.md
@@ -1,4 +1,4 @@
-# basic_json::is_primitive
+# <small>nlohmann::basic_json::</small>is_primitive
```cpp
constexpr bool is_primitive() const noexcept;
@@ -38,7 +38,7 @@
This library extends primitive types to binary types, because binary types are roughly comparable to strings. Hence,
`is_primitive()` returns `#!cpp true` for binary values.
-## Example
+## Examples
??? example
@@ -54,6 +54,15 @@
--8<-- "examples/is_primitive.output"
```
+## See also
+
+- [is_structured()](is_structured.md) returns whether JSON value is structured
+- [is_null()](is_null.md) returns whether JSON value is `null`
+- [is_string()](is_string.md) returns whether JSON value is a string
+- [is_boolean()](is_boolean.md) returns whether JSON value is a boolean
+- [is_number()](is_number.md) returns whether JSON value is a number
+- [is_binary()](is_binary.md) returns whether JSON value is a binary array
+
## Version history
- Added in version 1.0.0.
diff --git a/doc/mkdocs/docs/api/basic_json/is_string.md b/doc/mkdocs/docs/api/basic_json/is_string.md
index af725fb..b82c924 100644
--- a/doc/mkdocs/docs/api/basic_json/is_string.md
+++ b/doc/mkdocs/docs/api/basic_json/is_string.md
@@ -1,4 +1,4 @@
-# basic_json::is_string
+# <small>nlohmann::basic_json::</small>is_string
```cpp
constexpr bool is_string() const noexcept;
@@ -18,7 +18,7 @@
Constant.
-## Example
+## Examples
??? example
diff --git a/doc/mkdocs/docs/api/basic_json/is_structured.md b/doc/mkdocs/docs/api/basic_json/is_structured.md
index 3975798..f8fe4dc 100644
--- a/doc/mkdocs/docs/api/basic_json/is_structured.md
+++ b/doc/mkdocs/docs/api/basic_json/is_structured.md
@@ -1,4 +1,4 @@
-# basic_json::is_structured
+# <small>nlohmann::basic_json::</small>is_structured
```cpp
constexpr bool is_structured() const noexcept;
@@ -18,6 +18,15 @@
Constant.
+## Possible implementation
+
+```cpp
+constexpr bool is_primitive() const noexcept
+{
+ return is_array() || is_object();
+}
+```
+
## Notes
The term *structured* stems from [RFC 8259](https://tools.ietf.org/html/rfc8259):
@@ -27,7 +36,7 @@
Note that though strings are containers in C++, they are treated as primitive values in JSON.
-## Example
+## Examples
??? example
@@ -43,6 +52,12 @@
--8<-- "examples/is_structured.output"
```
+## See also
+
+- [is_primitive()](is_primitive.md) returns whether JSON value is primitive
+- [is_array()](is_array.md) returns whether value is an array
+- [is_object()](is_object.md) returns whether value is an object
+
## Version history
- Added in version 1.0.0.
diff --git a/doc/mkdocs/docs/api/basic_json/items.md b/doc/mkdocs/docs/api/basic_json/items.md
index d5c7113..b388824 100644
--- a/doc/mkdocs/docs/api/basic_json/items.md
+++ b/doc/mkdocs/docs/api/basic_json/items.md
@@ -1,11 +1,11 @@
-# basic_json::items
+# <small>nlohmann::basic_json::</small>items
```cpp
iteration_proxy<iterator> items() noexcept;
iteration_proxy<const_iterator> items() const noexcept;
```
-This function allows to access `iterator::key()` and `iterator::value()` during range-based for loops. In these loops, a
+This function allows accessing `iterator::key()` and `iterator::value()` during range-based for loops. In these loops, a
reference to the JSON values is returned, so there is no access to the underlying iterator.
For loop without `items()` function:
@@ -36,7 +36,7 @@
}
```
-The `items()` function also allows to use
+The `items()` function also allows using
[structured bindings](https://en.cppreference.com/w/cpp/language/structured_binding) (C++17):
```cpp
@@ -65,10 +65,10 @@
!!! warning
- Using `items()` on temporary objects is dangerous. Make sure the object's lifetime exeeds the iteration. See
+ Using `items()` on temporary objects is dangerous. Make sure the object's lifetime exceeds the iteration. See
<https://github.com/nlohmann/json/issues/2040> for more information.
-## Example
+## Examples
??? example
@@ -86,11 +86,15 @@
## Version history
-- Added in version 3.0.0.
+- Added `iterator_wrapper` in version 3.0.0.
+- Added `items` and deprecated `iterator_wrapper` in version 3.1.0.
- Added structured binding support in version 3.5.0.
-!!! note
+!!! warning "Deprecation"
This function replaces the static function `iterator_wrapper` which was introduced in version 1.0.0, but has been
deprecated in version 3.1.0. Function `iterator_wrapper` will be removed in version 4.0.0. Please replace all
occurrences of `#!cpp iterator_wrapper(j)` with `#!cpp j.items()`.
+
+ You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated
+ function.
diff --git a/doc/mkdocs/docs/api/basic_json/json_serializer.md b/doc/mkdocs/docs/api/basic_json/json_serializer.md
index 89379ac..f091155 100644
--- a/doc/mkdocs/docs/api/basic_json/json_serializer.md
+++ b/doc/mkdocs/docs/api/basic_json/json_serializer.md
@@ -1,4 +1,4 @@
-# basic_json::json_serializer
+# <small>nlohmann::basic_json::</small>json_serializer
```cpp
template<typename T, typename SFINAE>
@@ -17,7 +17,7 @@
#### Default type
-The default values for `json_serializer` is [`adl_serializer`](../adl_serializer.md).
+The default values for `json_serializer` is [`adl_serializer`](../adl_serializer).
## Version history
diff --git a/doc/mkdocs/docs/api/basic_json/max_size.md b/doc/mkdocs/docs/api/basic_json/max_size.md
index 21fffa7..31339db 100644
--- a/doc/mkdocs/docs/api/basic_json/max_size.md
+++ b/doc/mkdocs/docs/api/basic_json/max_size.md
@@ -1,4 +1,4 @@
-# basic_json::max_size
+# <small>nlohmann::basic_json::</small>max_size
```cpp
size_type max_size() const noexcept;
@@ -11,15 +11,15 @@
The return value depends on the different types and is defined as follows:
-Value type | return value
------------ | -------------
-null | `0` (same as [`size()`](size.md))
-boolean | `1` (same as [`size()`](size.md))
-string | `1` (same as [`size()`](size.md))
-number | `1` (same as [`size()`](size.md))
-binary | `1` (same as [`size()`](size.md))
-object | result of function `object_t::max_size()`
-array | result of function `array_t::max_size()`
+| Value type | return value |
+|------------|-------------------------------------------|
+| null | `0` (same as [`size()`](size.md)) |
+| boolean | `1` (same as [`size()`](size.md)) |
+| string | `1` (same as [`size()`](size.md)) |
+| number | `1` (same as [`size()`](size.md)) |
+| binary | `1` (same as [`size()`](size.md)) |
+| object | result of function `object_t::max_size()` |
+| array | result of function `array_t::max_size()` |
## Exception safety
@@ -36,7 +36,7 @@
This function does not return the maximal length of a string stored as JSON value -- it returns the maximal number of
string elements the JSON value can store which is `1`.
-## Example
+## Examples
??? example
diff --git a/doc/mkdocs/docs/api/basic_json/merge_patch.md b/doc/mkdocs/docs/api/basic_json/merge_patch.md
index e865e89..1718c92 100644
--- a/doc/mkdocs/docs/api/basic_json/merge_patch.md
+++ b/doc/mkdocs/docs/api/basic_json/merge_patch.md
@@ -1,4 +1,4 @@
-# basic_json::merge_patch
+# <small>nlohmann::basic_json::</small>merge_patch
```cpp
void merge_patch(const basic_json& apply_patch);
@@ -37,7 +37,7 @@
Linear in the lengths of `apply_patch`.
-## Example
+## Examples
??? example
@@ -53,6 +53,11 @@
--8<-- "examples/merge_patch.output"
```
+## See also
+
+- [RFC 7396 (JSON Merge Patch)](https://tools.ietf.org/html/rfc7396)
+- [patch](patch.md) apply a JSON patch
+
## Version history
- Added in version 3.0.0.
diff --git a/doc/mkdocs/docs/api/basic_json/meta.md b/doc/mkdocs/docs/api/basic_json/meta.md
index 807c2aa..e2b312e 100644
--- a/doc/mkdocs/docs/api/basic_json/meta.md
+++ b/doc/mkdocs/docs/api/basic_json/meta.md
@@ -1,4 +1,4 @@
-# basic_json::meta
+# <small>nlohmann::basic_json::</small>meta
```cpp
static basic_json meta();
@@ -11,14 +11,14 @@
JSON object holding version information
-key | description
------------ | ---------------
-`compiler` | Information on the used compiler. It is an object with the following keys: `c++` (the used C++ standard), `family` (the compiler family; possible values are `clang`, `icc`, `gcc`, `ilecpp`, `msvc`, `pgcpp`, `sunpro`, and `unknown`), and `version` (the compiler version).
-`copyright` | The copyright line for the library as string.
-`name` | The name of the library as string.
-`platform` | The used platform as string. Possible values are `win32`, `linux`, `apple`, `unix`, and `unknown`.
-`url` | The URL of the project as string.
-`version` | The version of the library. It is an object with the following keys: `major`, `minor`, and `patch` as defined by [Semantic Versioning](http://semver.org), and `string` (the version string).
+| key | description |
+|-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `compiler` | Information on the used compiler. It is an object with the following keys: `c++` (the used C++ standard), `family` (the compiler family; possible values are `clang`, `icc`, `gcc`, `ilecpp`, `msvc`, `pgcpp`, `sunpro`, and `unknown`), and `version` (the compiler version). |
+| `copyright` | The copyright line for the library as string. |
+| `name` | The name of the library as string. |
+| `platform` | The used platform as string. Possible values are `win32`, `linux`, `apple`, `unix`, and `unknown`. |
+| `url` | The URL of the project as string. |
+| `version` | The version of the library. It is an object with the following keys: `major`, `minor`, and `patch` as defined by [Semantic Versioning](http://semver.org), and `string` (the version string). |
## Exception safety
@@ -28,20 +28,22 @@
Constant.
-## Example
+## Examples
-The following code shows an example output of the `meta()`
-function.
+??? example
-```cpp
---8<-- "examples/meta.cpp"
-```
-
-Output:
-
-```json
---8<-- "examples/meta.output"
-```
+ The following code shows an example output of the `meta()`
+ function.
+
+ ```cpp
+ --8<-- "examples/meta.cpp"
+ ```
+
+ Output:
+
+ ```json
+ --8<-- "examples/meta.output"
+ ```
## Version history
diff --git a/doc/mkdocs/docs/api/basic_json/number_float_t.md b/doc/mkdocs/docs/api/basic_json/number_float_t.md
index 0d0182b..50aa43b 100644
--- a/doc/mkdocs/docs/api/basic_json/number_float_t.md
+++ b/doc/mkdocs/docs/api/basic_json/number_float_t.md
@@ -1,4 +1,4 @@
-# basic_json::number_float_t
+# <small>nlohmann::basic_json::</small>number_float_t
```cpp
using number_float_t = NumberFloatType;
@@ -49,6 +49,22 @@
Floating-point number values are stored directly inside a `basic_json` type.
+## Examples
+
+??? example
+
+ The following code shows that `number_float_t` is by default, a typedef to `#!cpp double`.
+
+ ```cpp
+ --8<-- "examples/number_float_t.cpp"
+ ```
+
+ Output:
+
+ ```json
+ --8<-- "examples/number_float_t.output"
+ ```
+
## Version history
- Added in version 1.0.0.
diff --git a/doc/mkdocs/docs/api/basic_json/number_integer_t.md b/doc/mkdocs/docs/api/basic_json/number_integer_t.md
index 616b0b8..9bb3835 100644
--- a/doc/mkdocs/docs/api/basic_json/number_integer_t.md
+++ b/doc/mkdocs/docs/api/basic_json/number_integer_t.md
@@ -1,4 +1,4 @@
-# basic_json::number_integer_t
+# <small>nlohmann::basic_json::</small>number_integer_t
```cpp
using number_integer_t = NumberIntegerType;
@@ -45,7 +45,7 @@
will be automatically be stored as [`number_unsigned_t`](number_unsigned_t.md) or [`number_float_t`](number_float_t.md).
[RFC 8259](https://tools.ietf.org/html/rfc8259) further states:
-> Note that when such software is used, numbers that are integers and are in the range \f$[-2^{53}+1, 2^{53}-1]\f$ are
+> Note that when such software is used, numbers that are integers and are in the range $[-2^{53}+1, 2^{53}-1]$ are
> interoperable in the sense that implementations will agree exactly on their numeric values.
As this range is a subrange of the exactly supported range [INT64_MIN, INT64_MAX], this class's integer type is
@@ -55,6 +55,22 @@
Integer number values are stored directly inside a `basic_json` type.
+## Examples
+
+??? example
+
+ The following code shows that `number_integer_t` is by default, a typedef to `#!cpp std::int64_t`.
+
+ ```cpp
+ --8<-- "examples/number_integer_t.cpp"
+ ```
+
+ Output:
+
+ ```json
+ --8<-- "examples/number_integer_t.output"
+ ```
+
## Version history
- Added in version 1.0.0.
diff --git a/doc/mkdocs/docs/api/basic_json/number_unsigned_t.md b/doc/mkdocs/docs/api/basic_json/number_unsigned_t.md
index 49f0e31..8a1540a 100644
--- a/doc/mkdocs/docs/api/basic_json/number_unsigned_t.md
+++ b/doc/mkdocs/docs/api/basic_json/number_unsigned_t.md
@@ -1,4 +1,4 @@
-# basic_json::number_unsigned_t
+# <small>nlohmann::basic_json::</small>number_unsigned_t
```cpp
using number_unsigned_t = NumberUnsignedType;
@@ -55,6 +55,22 @@
Integer number values are stored directly inside a `basic_json` type.
+## Examples
+
+??? example
+
+ The following code shows that `number_unsigned_t` is by default, a typedef to `#!cpp std::uint64_t`.
+
+ ```cpp
+ --8<-- "examples/number_unsigned_t.cpp"
+ ```
+
+ Output:
+
+ ```json
+ --8<-- "examples/number_unsigned_t.output"
+ ```
+
## Version history
- Added in version 2.0.0.
diff --git a/doc/mkdocs/docs/api/basic_json/object.md b/doc/mkdocs/docs/api/basic_json/object.md
index 4aae6fe..9bdbddb 100644
--- a/doc/mkdocs/docs/api/basic_json/object.md
+++ b/doc/mkdocs/docs/api/basic_json/object.md
@@ -1,4 +1,4 @@
-# basic_json::object
+# <small>nlohmann::basic_json::</small>object
```cpp
static basic_json object(initializer_list_t init = {});
@@ -16,6 +16,10 @@
JSON object value
+## Exception safety
+
+Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
+
## Exceptions
Throws [`type_error.301`](../../home/exceptions.md#jsonexceptiontype_error301) if `init` is not a list of pairs whose
@@ -23,10 +27,6 @@
`basic_json(initializer_list_t, bool, value_t)`, an array would have been created from the passed initializer list
`init`. See example below.
-## Exception safety
-
-Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
-
## Complexity
Linear in the size of `init`.
@@ -53,6 +53,11 @@
--8<-- "examples/object.output"
```
+## See also
+
+- [`basic_json(initializer_list_t)`](basic_json.md) - create a JSON value from an initializer list
+- [`array`](array.md) - create a JSON array value from an initializer list
+
## Version history
- Added in version 1.0.0.
diff --git a/doc/mkdocs/docs/api/basic_json/object_comparator_t.md b/doc/mkdocs/docs/api/basic_json/object_comparator_t.md
index 8fb8656..44509a9 100644
--- a/doc/mkdocs/docs/api/basic_json/object_comparator_t.md
+++ b/doc/mkdocs/docs/api/basic_json/object_comparator_t.md
@@ -1,11 +1,9 @@
-# basic_json::object_comparator_t
+# <small>nlohmann::basic_json::</small>object_comparator_t
```cpp
-// until C++14
-using object_comparator_t = std::less<StringType>;
+using object_comparator_t = std::less<StringType>; // until C++14
-// since C++14
-using object_comparator_t = std::less<>;
+using object_comparator_t = std::less<>; // since C++14
```
The comparator used in [`object_t`](object_t.md).
diff --git a/doc/mkdocs/docs/api/basic_json/object_t.md b/doc/mkdocs/docs/api/basic_json/object_t.md
index e937d84..d4bea15 100644
--- a/doc/mkdocs/docs/api/basic_json/object_t.md
+++ b/doc/mkdocs/docs/api/basic_json/object_t.md
@@ -1,4 +1,4 @@
-# basic_json::object_t
+# <small>nlohmann::basic_json::</small>object_t
```cpp
using object_t = ObjectType<StringType,
@@ -92,6 +92,22 @@
alphabetical order as `std::map` with `std::less` is used by default. Please note this behavior conforms to
[RFC 8259](https://tools.ietf.org/html/rfc8259), because any order implements the specified "unordered" nature of JSON objects.
+## Examples
+
+??? example
+
+ The following code shows that `object_t` is by default, a typedef to `#!cpp std::map<json::string_t, json>`.
+
+ ```cpp
+ --8<-- "examples/object_t.cpp"
+ ```
+
+ Output:
+
+ ```json
+ --8<-- "examples/object_t.output"
+ ```
+
## Version history
- Added in version 1.0.0.
diff --git a/doc/mkdocs/docs/api/basic_json/operator+=.md b/doc/mkdocs/docs/api/basic_json/operator+=.md
index 59001a5..074b300 100644
--- a/doc/mkdocs/docs/api/basic_json/operator+=.md
+++ b/doc/mkdocs/docs/api/basic_json/operator+=.md
@@ -1,4 +1,4 @@
-# basic_json::operator+=
+# <small>nlohmann::basic_json::</small>operator+=
```cpp
// (1)
@@ -18,7 +18,7 @@
2. Inserts the given element `val` to the JSON object. If the function is called on a JSON null value, an empty object
is created before inserting `val`.
-3. This function allows to use `operator+=` with an initializer list. In case
+3. This function allows using `operator+=` with an initializer list. In case
1. the current value is an object,
2. the initializer list `init` contains only two elements, and
@@ -62,7 +62,7 @@
## Examples
-??? example
+??? example "Example: (1) add element to array"
The example shows how `push_back()` and `+=` can be used to add elements to a JSON array. Note how the `null` value
was silently converted to a JSON array.
@@ -77,7 +77,7 @@
--8<-- "examples/push_back.output"
```
-??? example
+??? example "Example: (2) add element to object"
The example shows how `push_back()` and `+=` can be used to add elements to a JSON object. Note how the `null` value
was silently converted to a JSON object.
@@ -92,7 +92,7 @@
--8<-- "examples/push_back__object_t__value.output"
```
-??? example
+??? example "Example: (3) add to object from initializer list"
The example shows how initializer lists are treated as objects when possible.
diff --git a/doc/mkdocs/docs/api/basic_json/operator=.md b/doc/mkdocs/docs/api/basic_json/operator=.md
index 340f8ea..4e0b914 100644
--- a/doc/mkdocs/docs/api/basic_json/operator=.md
+++ b/doc/mkdocs/docs/api/basic_json/operator=.md
@@ -1,4 +1,4 @@
-# basic_json::operator=
+# <small>nlohmann::basic_json::</small>operator=
```cpp
basic_json& operator=(basic_json other) noexcept (
@@ -21,7 +21,7 @@
Linear.
-## Example
+## Examples
??? example
diff --git "a/doc/mkdocs/docs/api/basic_json/operator\133\135.md" "b/doc/mkdocs/docs/api/basic_json/operator\133\135.md"
index 4b36f1a..5b6512a 100644
--- "a/doc/mkdocs/docs/api/basic_json/operator\133\135.md"
+++ "b/doc/mkdocs/docs/api/basic_json/operator\133\135.md"
@@ -1,4 +1,4 @@
-# basic_json::operator[]
+# <small>nlohmann::basic_json::</small>operator[]
```cpp
// (1)
@@ -18,8 +18,8 @@
const_reference operator[](const json_pointer& ptr) const;
```
-1. Returns a reference to the element at specified location `idx`.
-2. Returns a reference to the element at with specified key `key`.
+1. Returns a reference to the array element at specified location `idx`.
+2. Returns a reference to the object element at with specified key `key`.
3. Returns a reference to the element at with specified JSON pointer `ptr`.
## Template parameters
@@ -33,7 +33,7 @@
: index of the element to access
`key` (in)
-: object key of the elements to remove
+: object key of the element to access
`ptr` (in)
: JSON pointer to the desired element
@@ -44,14 +44,18 @@
2. reference to the element at key `key`
3. reference to the element pointed to by `ptr`
+## Exception safety
+
+Strong exception safety: if an exception occurs, the original value stays intact.
+
## Exceptions
1. The function can throw the following exceptions:
- Throws [`type_error.305`](../../home/exceptions.md#jsonexceptiontype_error305) if the JSON value is not an array
- or null; in that cases, using the `[]` operator with an index makes no sense.
+ or null; in that case, using the `[]` operator with an index makes no sense.
2. The function can throw the following exceptions:
- - Throws [`type_error.305`](../../home/exceptions.md#jsonexceptiontype_error305) if the JSON value is not an array
- or null; in that cases, using the `[]` operator with an index makes no sense.
+ - Throws [`type_error.305`](../../home/exceptions.md#jsonexceptiontype_error305) if the JSON value is not an object
+ or null; in that case, using the `[]` operator with a key makes no sense.
3. The function can throw the following exceptions:
- Throws [`parse_error.106`](../../home/exceptions.md#jsonexceptionparse_error106) if an array index in the passed
JSON pointer `ptr` begins with '0'.
@@ -62,6 +66,12 @@
- Throws [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) if the JSON pointer `ptr` can
not be resolved.
+## Complexity
+
+1. Constant if `idx` is in the range of the array. Otherwise, linear in `idx - size()`.
+2. Logarithmic in the size of the container.
+3. Constant
+
## Notes
!!! danger
@@ -80,26 +90,16 @@
In particular:
- - If the JSON pointer points to an object key that does not exist, it is created an filled with a `#!json null`
+ - If the JSON pointer points to an object key that does not exist, it is created and filled with a `#!json null`
value before a reference to it is returned.
- - If the JSON pointer points to an array index that does not exist, it is created an filled with a `#!json null`
+ - If the JSON pointer points to an array index that does not exist, it is created and filled with a `#!json null`
value before a reference to it is returned. All indices between the current maximum and the given index are also
filled with `#!json null`.
- The special value `-` is treated as a synonym for the index past the end.
-## Exception safety
+## Examples
-Strong exception safety: if an exception occurs, the original value stays intact.
-
-## Complexity
-
-1. Constant if `idx` is in the range of the array. Otherwise linear in `idx - size()`.
-2. Logarithmic in the size of the container.
-3. Constant
-
-## Example
-
-??? example
+??? example "Example (1): access specified array element"
The example below shows how array elements can be read and written using `[]` operator. Note the addition of
`#!json null` values.
@@ -114,7 +114,7 @@
--8<-- "examples/operatorarray__size_type.output"
```
-??? example
+??? example "Example (1): access specified array element"
The example below shows how array elements can be read using the `[]` operator.
@@ -128,7 +128,7 @@
--8<-- "examples/operatorarray__size_type_const.output"
```
-??? example
+??? example "Example (2): access specified object element"
The example below shows how object elements can be read and written using the `[]` operator.
@@ -142,7 +142,7 @@
--8<-- "examples/operatorarray__key_type.output"
```
-??? example
+??? example "Example (2): access specified object element"
The example below shows how object elements can be read using the `[]` operator.
@@ -156,7 +156,7 @@
--8<-- "examples/operatorarray__key_type_const.output"
```
-??? example
+??? example "Example (3): access specified element via JSON Pointer"
The example below shows how values can be read and written using JSON Pointers.
@@ -170,7 +170,7 @@
--8<-- "examples/operatorjson_pointer.output"
```
-??? example
+??? example "Example (3): access specified element via JSON Pointer"
The example below shows how values can be read using JSON Pointers.
@@ -184,6 +184,11 @@
--8<-- "examples/operatorjson_pointer_const.output"
```
+## See also
+
+- see [`at`](at.md) for access by reference with range checking
+- see [`value`](value.md) for access with default value
+
## Version history
1. Added in version 1.0.0.
diff --git a/doc/mkdocs/docs/api/basic_json/operator_ValueType.md b/doc/mkdocs/docs/api/basic_json/operator_ValueType.md
index cfb5e64..1eec135 100644
--- a/doc/mkdocs/docs/api/basic_json/operator_ValueType.md
+++ b/doc/mkdocs/docs/api/basic_json/operator_ValueType.md
@@ -1,4 +1,4 @@
-# basic_json::operator ValueType
+# <small>nlohmann::basic_json::</small>operator ValueType
```cpp
template<typename ValueType>
@@ -45,7 +45,7 @@
That is, implicit conversions can be switched off by defining
[`JSON_USE_IMPLICIT_CONVERSIONS`](../../features/macros.md#json_use_implicit_conversions) to `0`.
-## Example
+## Examples
??? example
diff --git a/doc/mkdocs/docs/api/basic_json/operator_eq.md b/doc/mkdocs/docs/api/basic_json/operator_eq.md
index 34cf553..49f96b1 100644
--- a/doc/mkdocs/docs/api/basic_json/operator_eq.md
+++ b/doc/mkdocs/docs/api/basic_json/operator_eq.md
@@ -1,4 +1,4 @@
-# basic_json::operator==
+# <small>nlohmann::basic_json::</small>operator==
```cpp
bool operator==(const_reference lhs, const_reference rhs) noexcept;
@@ -85,7 +85,7 @@
}
```
-## Example
+## Examples
??? example
@@ -101,6 +101,20 @@
--8<-- "examples/operator__equal.output"
```
+??? example
+
+ The example demonstrates comparing several JSON types against the null pointer (JSON `#!json null`).
+
+ ```cpp
+ --8<-- "examples/operator__equal__nullptr_t.cpp"
+ ```
+
+ Output:
+
+ ```json
+ --8<-- "examples/operator__equal__nullptr_t.output"
+ ```
+
## Version history
- Added in version 1.0.0.
diff --git a/doc/mkdocs/docs/api/basic_json/operator_ge.md b/doc/mkdocs/docs/api/basic_json/operator_ge.md
index 19834c0..68aac65 100644
--- a/doc/mkdocs/docs/api/basic_json/operator_ge.md
+++ b/doc/mkdocs/docs/api/basic_json/operator_ge.md
@@ -1,4 +1,4 @@
-# basic_json::operator>=
+# <small>nlohmann::basic_json::</small>operator>=
```cpp
bool operator>=(const_reference lhs, const_reference rhs) noexcept,
@@ -38,7 +38,7 @@
Linear.
-## Example
+## Examples
??? example
diff --git a/doc/mkdocs/docs/api/basic_json/operator_gt.md b/doc/mkdocs/docs/api/basic_json/operator_gt.md
index b9e3262..92ec305 100644
--- a/doc/mkdocs/docs/api/basic_json/operator_gt.md
+++ b/doc/mkdocs/docs/api/basic_json/operator_gt.md
@@ -1,4 +1,4 @@
-# basic_json::operator>
+# <small>nlohmann::basic_json::</small>operator>
```cpp
bool operator>(const_reference lhs, const_reference rhs) noexcept,
@@ -37,7 +37,7 @@
Linear.
-## Example
+## Examples
??? example
diff --git a/doc/mkdocs/docs/api/basic_json/operator_gtgt.md b/doc/mkdocs/docs/api/basic_json/operator_gtgt.md
new file mode 100644
index 0000000..97c2f0b
--- /dev/null
+++ b/doc/mkdocs/docs/api/basic_json/operator_gtgt.md
@@ -0,0 +1,65 @@
+# operator>>(basic_json)
+
+```cpp
+std::istream& operator>>(std::istream& i, basic_json& j);
+```
+
+Deserializes an input stream to a JSON value.
+
+## Parameters
+
+`i` (in, out)
+: input stream to read a serialized JSON value from
+
+`j` (in, out)
+: JSON value to write the deserialized input to
+
+## Return value
+
+the stream `i`
+
+## Exceptions
+
+- Throws [`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101) in case of an unexpected token.
+- Throws [`parse_error.102`](../../home/exceptions.md#jsonexceptionparse_error102) if to_unicode fails or surrogate
+ error.
+- Throws [`parse_error.103`](../../home/exceptions.md#jsonexceptionparse_error103) if to_unicode fails.
+
+## Complexity
+
+Linear in the length of the input. The parser is a predictive LL(1) parser.
+
+## Notes
+
+A UTF-8 byte order mark is silently ignored.
+
+## Examples
+
+??? example
+
+ The example below shows how a JSON value is constructed by reading a serialization from a stream.
+
+ ```cpp
+ --8<-- "examples/operator_deserialize.cpp"
+ ```
+
+ Output:
+
+ ```json
+ --8<-- "examples/operator_deserialize.output"
+ ```
+
+## See also
+
+- [accept](accept.md) - check if the input is valid JSON
+- [parse](parse.md) - deserialize from a compatible input
+
+## Version history
+
+- Added in version 1.0.0
+
+!!! warning "Deprecation"
+
+ This function replaces function `#!cpp std::istream& operator<<(basic_json& j, std::istream& i)` which has
+ been deprecated in version 3.0.0. It will be removed in version 4.0.0. Please replace calls like `#!cpp j << i;`
+ with `#!cpp i >> j;`.
diff --git a/doc/mkdocs/docs/api/basic_json/operator_le.md b/doc/mkdocs/docs/api/basic_json/operator_le.md
index 452ee49..54f9a28 100644
--- a/doc/mkdocs/docs/api/basic_json/operator_le.md
+++ b/doc/mkdocs/docs/api/basic_json/operator_le.md
@@ -1,4 +1,4 @@
-# basic_json::operator<=
+# <small>nlohmann::basic_json::</small>operator<=
```cpp
bool operator<=(const_reference lhs, const_reference rhs) noexcept,
@@ -38,7 +38,7 @@
Linear.
-## Example
+## Examples
??? example
diff --git a/doc/mkdocs/docs/api/basic_json/operator_literal_json.md b/doc/mkdocs/docs/api/basic_json/operator_literal_json.md
index 8c96067..8e0c65d 100644
--- a/doc/mkdocs/docs/api/basic_json/operator_literal_json.md
+++ b/doc/mkdocs/docs/api/basic_json/operator_literal_json.md
@@ -1,7 +1,7 @@
-# basic_json::operator""_json
+# <small>nlohmann::basic_json::</small>operator""_json
```cpp
-json operator "" _json(const char* s, std::size_t n)
+json operator "" _json(const char* s, std::size_t n);
```
This operator implements a user-defined string literal for JSON objects. It can be used by adding `#!cpp _json` to a
@@ -27,6 +27,22 @@
Linear.
+## Examples
+
+??? example
+
+ The following code shows how to create JSON values from string literals.
+
+ ```cpp
+ --8<-- "examples/operator_literal_json.cpp"
+ ```
+
+ Output:
+
+ ```json
+ --8<-- "examples/operator_literal_json.output"
+ ```
+
## Version history
- Added in version 1.0.0.
diff --git a/doc/mkdocs/docs/api/basic_json/operator_literal_json_pointer.md b/doc/mkdocs/docs/api/basic_json/operator_literal_json_pointer.md
index 0316b7c..38c957e 100644
--- a/doc/mkdocs/docs/api/basic_json/operator_literal_json_pointer.md
+++ b/doc/mkdocs/docs/api/basic_json/operator_literal_json_pointer.md
@@ -1,11 +1,11 @@
-# basic_json::operator""_json_pointer
+# <small>nlohmann::basic_json::</small>operator""_json_pointer
```cpp
-json_pointer operator "" _json_pointer(const char* s, std::size_t n)
+json_pointer operator "" _json_pointer(const char* s, std::size_t n);
```
This operator implements a user-defined string literal for JSON Pointers. It can be used by adding `#!cpp _json_pointer`
-to a string literal and returns a [`json_pointer`](../json_pointer.md) object if no parse error occurred.
+to a string literal and returns a [`json_pointer`](../json_pointer/index.md) object if no parse error occurred.
## Parameters
@@ -17,16 +17,32 @@
## Return value
-[`json_pointer`](../json_pointer.md) value parsed from `s`
+[`json_pointer`](../json_pointer/index.md) value parsed from `s`
## Exceptions
-The function can throw anything that [`json_pointer::json_pointer`](../json_pointer.md) would throw.
+The function can throw anything that [`json_pointer::json_pointer`](../json_pointer/index.md) would throw.
## Complexity
Linear.
+## Examples
+
+??? example
+
+ The following code shows how to create JSON Pointers from string literals.
+
+ ```cpp
+ --8<-- "examples/operator_literal_json_pointer.cpp"
+ ```
+
+ Output:
+
+ ```json
+ --8<-- "examples/operator_literal_json_pointer.output"
+ ```
+
## Version history
- Added in version 2.0.0.
diff --git a/doc/mkdocs/docs/api/basic_json/operator_lt.md b/doc/mkdocs/docs/api/basic_json/operator_lt.md
index e8d2fb3..d1a4999 100644
--- a/doc/mkdocs/docs/api/basic_json/operator_lt.md
+++ b/doc/mkdocs/docs/api/basic_json/operator_lt.md
@@ -1,7 +1,7 @@
-# basic_json::operator<
+# <small>nlohmann::basic_json::</small>operator<
```cpp
-bool operator<(const_reference lhs, const_reference rhs) noexcept,
+bool operator<(const_reference lhs, const_reference rhs) noexcept;
template<typename ScalarType>
bool operator<(const_reference lhs, const ScalarType rhs) noexcept;
@@ -52,7 +52,7 @@
Linear.
-## Example
+## Examples
??? example
diff --git a/doc/mkdocs/docs/api/basic_json/operator_ltlt.md b/doc/mkdocs/docs/api/basic_json/operator_ltlt.md
new file mode 100644
index 0000000..0cba5ea
--- /dev/null
+++ b/doc/mkdocs/docs/api/basic_json/operator_ltlt.md
@@ -0,0 +1,62 @@
+# operator<<(basic_json)
+
+```cpp
+std::ostream& operator<<(std::ostream& o, const basic_json& j);
+```
+
+Serialize the given JSON value `j` to the output stream `o`. The JSON value will be serialized using the
+[`dump`](dump.md) member function.
+
+- The indentation of the output can be controlled with the member variable `width` of the output stream `o`. For
+ instance, using the manipulator `std::setw(4)` on `o` sets the indentation level to `4` and the serialization result
+ is the same as calling `dump(4)`.
+- The indentation character can be controlled with the member variable `fill` of the output stream `o`. For instance,
+ the manipulator `std::setfill('\\t')` sets indentation to use a tab character rather than the default space character.
+
+## Parameters
+
+`o` (in, out)
+: stream to serialize to
+
+`j` (in)
+: JSON value to serialize
+
+## Return value
+
+the stream `o`
+
+## Exceptions
+
+Throws [`type_error.316`](../../home/exceptions.md#jsonexceptiontype_error316) if a string stored inside the JSON value
+is not UTF-8 encoded. Note that unlike the [`dump`](dump.md) member functions, no `error_handler` can be set.
+
+## Complexity
+
+Linear.
+
+## Examples
+
+??? example
+
+ The example below shows the serialization with different parameters to `width` to adjust the indentation level.
+
+ ```cpp
+ --8<-- "examples/operator_serialize.cpp"
+ ```
+
+ Output:
+
+ ```json
+ --8<-- "examples/operator_serialize.output"
+ ```
+
+## Version history
+
+- Added in version 1.0.0
+- Support for indentation character added in version 3.0.0.
+
+!!! warning "Deprecation"
+
+ This function replaces function `#!cpp std::ostream& operator>>(const basic_json& j, std::ostream& o)` which has
+ been deprecated in version 3.0.0. It will be removed in version 4.0.0. Please replace calls like `#!cpp j >> o;`
+ with `#!cpp o << j;`.
diff --git a/doc/mkdocs/docs/api/basic_json/operator_ne.md b/doc/mkdocs/docs/api/basic_json/operator_ne.md
index 5a86201..e94da9b 100644
--- a/doc/mkdocs/docs/api/basic_json/operator_ne.md
+++ b/doc/mkdocs/docs/api/basic_json/operator_ne.md
@@ -1,4 +1,4 @@
-# basic_json::operator!=
+# <small>nlohmann::basic_json::</small>operator!=
```cpp
bool operator!=(const_reference lhs, const_reference rhs) noexcept;
@@ -37,20 +37,35 @@
Linear.
-## Example
+## Examples
-The example demonstrates comparing several JSON
-types.
+??? example
+
+ The example demonstrates comparing several JSON types.
+
+ ```cpp
+ --8<-- "examples/operator__notequal.cpp"
+ ```
-```cpp
---8<-- "examples/operator__notequal.cpp"
-```
+ Output:
+
+ ```json
+ --8<-- "examples/operator__notequal.output"
+ ```
-Output:
+??? example
-```json
---8<-- "examples/operator__notequal.output"
-```
+ 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
diff --git a/doc/mkdocs/docs/api/basic_json/operator_value_t.md b/doc/mkdocs/docs/api/basic_json/operator_value_t.md
index 5212514..0f08f42 100644
--- a/doc/mkdocs/docs/api/basic_json/operator_value_t.md
+++ b/doc/mkdocs/docs/api/basic_json/operator_value_t.md
@@ -1,4 +1,4 @@
-# basic_json::operator value_t
+# <small>nlohmann::basic_json::</small>operator value_t
```cpp
constexpr operator value_t() const noexcept;
@@ -10,18 +10,18 @@
the type of the JSON value
-Value type | return value
-------------------------- | -------------------------
-`#!json null` | `value_t::null`
-boolean | `value_t::boolean`
-string | `value_t::string`
-number (integer) | `value_t::number_integer`
-number (unsigned integer) | `value_t::number_unsigned`
-number (floating-point) | `value_t::number_float`
-object | `value_t::object`
-array | `value_t::array`
-binary | `value_t::binary`
-discarded | `value_t::discarded`
+| Value type | return value |
+|---------------------------|----------------------------|
+| `#!json null` | `value_t::null` |
+| boolean | `value_t::boolean` |
+| string | `value_t::string` |
+| number (integer) | `value_t::number_integer` |
+| number (unsigned integer) | `value_t::number_unsigned` |
+| number (floating-point) | `value_t::number_float` |
+| object | `value_t::object` |
+| array | `value_t::array` |
+| binary | `value_t::binary` |
+| discarded | `value_t::discarded` |
## Exception safety
@@ -31,7 +31,7 @@
Constant.
-## Example
+## Examples
??? example
diff --git a/doc/mkdocs/docs/api/basic_json/other_error.md b/doc/mkdocs/docs/api/basic_json/other_error.md
index 492b2d4..9a83340 100644
--- a/doc/mkdocs/docs/api/basic_json/other_error.md
+++ b/doc/mkdocs/docs/api/basic_json/other_error.md
@@ -1,4 +1,4 @@
-# basic_json::other_error
+# <small>nlohmann::basic_json::</small>other_error
```cpp
class other_error : public exception;
@@ -6,7 +6,7 @@
This exception is thrown in case of errors that cannot be classified with the other exception types.
-Exceptions have ids 5xx.
+Exceptions have ids 5xx (see [list of other errors](../../home/exceptions.md#further-exceptions)).
```plantuml
std::exception <|-- basic_json::exception
@@ -38,7 +38,7 @@
- **id** - the id of the exception
-## Example
+## Examples
??? example
@@ -54,6 +54,14 @@
--8<-- "examples/other_error.output"
```
+## See also
+
+- [List of other errors](../../home/exceptions.md#further-exceptions)
+- [`parse_error`](parse_error.md) for exceptions indicating a parse error
+- [`invalid_iterator`](invalid_iterator.md) for exceptions indicating errors with iterators
+- [`type_error`](type_error.md) for exceptions indicating executing a member function with a wrong type
+- [`out_of_range`](out_of_range.md) for exceptions indicating access out of the defined range
+
## Version history
- Since version 3.0.0.
diff --git a/doc/mkdocs/docs/api/basic_json/out_of_range.md b/doc/mkdocs/docs/api/basic_json/out_of_range.md
index 47ead87..6c1f0df 100644
--- a/doc/mkdocs/docs/api/basic_json/out_of_range.md
+++ b/doc/mkdocs/docs/api/basic_json/out_of_range.md
@@ -1,4 +1,4 @@
-# basic_json::out_of_range
+# <small>nlohmann::basic_json::</small>out_of_range
```cpp
class out_of_range : public exception;
@@ -7,7 +7,7 @@
This exception is thrown in case a library function is called on an input parameter that exceeds the expected range, for
instance in case of array indices or nonexisting object keys.
-Exceptions have ids 4xx.
+Exceptions have ids 4xx (see [list of out-of-range errors](../../home/exceptions.md#out-of-range)).
```plantuml
std::exception <|-- basic_json::exception
@@ -39,7 +39,7 @@
- **id** - the id of the exception
-## Example
+## Examples
??? example
@@ -55,6 +55,14 @@
--8<-- "examples/out_of_range.output"
```
+## See also
+
+- [List of out-of-range errors](../../home/exceptions.md#out-of-range)
+- [`parse_error`](parse_error.md) for exceptions indicating a parse error
+- [`invalid_iterator`](invalid_iterator.md) for exceptions indicating errors with iterators
+- [`type_error`](type_error.md) for exceptions indicating executing a member function with a wrong type
+- [`other_error`](other_error.md) for exceptions indicating other library errors
+
## Version history
- Since version 3.0.0.
diff --git a/doc/mkdocs/docs/api/basic_json/parse.md b/doc/mkdocs/docs/api/basic_json/parse.md
index 4a8a692..95d876b 100644
--- a/doc/mkdocs/docs/api/basic_json/parse.md
+++ b/doc/mkdocs/docs/api/basic_json/parse.md
@@ -1,4 +1,4 @@
-# basic_json::parse
+# <small>nlohmann::basic_json::</small>parse
```cpp
// (1)
@@ -19,7 +19,7 @@
1. Deserialize from a compatible input.
2. Deserialize from a pair of character iterators
- The value_type of the iterator must be a integral type with size of 1, 2 or 4 bytes, which will be interpreted
+ The `value_type` of the iterator must be an integral type with size of 1, 2 or 4 bytes, which will be interpreted
respectively as UTF-8, UTF-16 and UTF-32.
## Template parameters
@@ -34,7 +34,10 @@
- an object `obj` for which `begin(obj)` and `end(obj)` produces a valid pair of iterators.
`IteratorType`
-: a compatible iterator type
+: a compatible iterator type, for instance.
+
+ - a pair of `std::string::iterator` or `std::vector<std::uint8_t>::iterator`
+ - a pair of pointers such as `ptr` and `ptr + len`
## Parameters
@@ -135,6 +138,34 @@
--8<-- "examples/parse__contiguouscontainer__parser_callback_t.output"
```
+??? example "Parsing from a non null-terminated string"
+
+ The example below demonstrates the `parse()` function reading from a string that is not null-terminated.
+
+ ```cpp
+ --8<-- "examples/parse__pointers.cpp"
+ ```
+
+ Output:
+
+ ```json
+ --8<-- "examples/parse__pointers.output"
+ ```
+
+??? example "Parsing from an iterator pair"
+
+ The example below demonstrates the `parse()` function reading from an iterator pair.
+
+ ```cpp
+ --8<-- "examples/parse__iterator_pair.cpp"
+ ```
+
+ Output:
+
+ ```json
+ --8<-- "examples/parse__iterator_pair.output"
+ ```
+
??? example "Effect of `allow_exceptions` parameter"
The example below demonstrates the effect of the `allow_exceptions` parameter in the ´parse()` function.
@@ -149,8 +180,22 @@
--8<-- "examples/parse__allow_exceptions.output"
```
+## See also
+
+- [accept](accept.md) - check if the input is valid JSON
+- [operator>>](operator_gtgt.md) - deserialize from stream
+
## Version history
- Added in version 1.0.0.
- Overload for contiguous containers (1) added in version 2.0.3.
- Ignoring comments via `ignore_comments` added in version 3.9.0.
+
+!!! warning "Deprecation"
+
+ Overload (2) replaces calls to `parse` with a pair of iterators as their first parameter which has been
+ deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
+ `#!cpp parse({ptr, ptr+len}, ...);` with `#!cpp parse(ptr, ptr+len, ...);`.
+
+ You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated
+ function.
diff --git a/doc/mkdocs/docs/api/basic_json/parse_error.md b/doc/mkdocs/docs/api/basic_json/parse_error.md
index de0ee40..af3e1f0 100644
--- a/doc/mkdocs/docs/api/basic_json/parse_error.md
+++ b/doc/mkdocs/docs/api/basic_json/parse_error.md
@@ -1,4 +1,4 @@
-# basic_json::parse_error
+# <small>nlohmann::basic_json::</small>parse_error
```cpp
class parse_error : public exception;
@@ -7,7 +7,9 @@
This exception is thrown by the library when a parse error occurs. Parse errors can occur during the deserialization of
JSON text, BSON, CBOR, MessagePack, UBJSON, as well as when using JSON Patch.
-Exceptions have ids 1xx.
+Member `byte` holds the byte index of the last read character in the input file (see note below).
+
+Exceptions have ids 1xx (see [list of parse errors](../../home/exceptions.md#parse-errors)).
```plantuml
std::exception <|-- basic_json::exception
@@ -38,12 +40,12 @@
- **id** - the id of the exception
- **byte** - byte index of the parse error
-## Note
+## Notes
-For an input with _n_ bytes, 1 is the index of the first character and _n_+1 is the index of the terminating null byte
+For an input with $n$ bytes, 1 is the index of the first character and $n+1$ is the index of the terminating null byte
or the end of file. This also holds true when reading a byte vector for binary formats.
-## Example
+## Examples
??? example
@@ -59,6 +61,14 @@
--8<-- "examples/parse_error.output"
```
+## See also
+
+- [List of parse errors](../../home/exceptions.md#parse-errors)
+- [`invalid_iterator`](invalid_iterator.md) for exceptions indicating errors with iterators
+- [`type_error`](type_error.md) for exceptions indicating executing a member function with a wrong type
+- [`out_of_range`](out_of_range.md) for exceptions indicating access out of the defined range
+- [`other_error`](other_error.md) for exceptions indicating other library errors
+
## Version history
- Since version 3.0.0.
diff --git a/doc/mkdocs/docs/api/basic_json/parse_event_t.md b/doc/mkdocs/docs/api/basic_json/parse_event_t.md
index 867de48..1a7c390 100644
--- a/doc/mkdocs/docs/api/basic_json/parse_event_t.md
+++ b/doc/mkdocs/docs/api/basic_json/parse_event_t.md
@@ -1,4 +1,4 @@
-# basic_json::parse_event_t
+# <small>nlohmann::basic_json::</small>parse_event_t
```cpp
enum class parse_event_t : std::uint8_t {
@@ -20,7 +20,7 @@
- `array_end`: the parser read `]` and finished processing a JSON array
- `value`: the parser finished reading a JSON value
-## Example
+## Examples
diff --git a/doc/mkdocs/docs/api/basic_json/parser_callback_t.md b/doc/mkdocs/docs/api/basic_json/parser_callback_t.md
index aeb7c27..e10402e 100644
--- a/doc/mkdocs/docs/api/basic_json/parser_callback_t.md
+++ b/doc/mkdocs/docs/api/basic_json/parser_callback_t.md
@@ -1,4 +1,4 @@
-# basic_json::parser_callback_t
+# <small>nlohmann::basic_json::</small>parser_callback_t
```cpp
template<typename BasicJsonType>
@@ -14,14 +14,14 @@
We distinguish six scenarios (determined by the event type) in which the callback function can be called. The following
table describes the values of the parameters `depth`, `event`, and `parsed`.
-parameter `event` | description | parameter `depth` | parameter `parsed`
------------------- | ----------- | ------------------ | -------------------
-`parse_event_t::object_start` | the parser read `{` and started to process a JSON object | depth of the parent of the JSON object | a JSON value with type discarded
-`parse_event_t::key` | the parser read a key of a value in an object | depth of the currently parsed JSON object | a JSON string containing the key
-`parse_event_t::object_end` | the parser read `}` and finished processing a JSON object | depth of the parent of the JSON object | the parsed JSON object
-`parse_event_t::array_start` | the parser read `[` and started to process a JSON array | depth of the parent of the JSON array | a JSON value with type discarded
-`parse_event_t::array_end` | the parser read `]` and finished processing a JSON array | depth of the parent of the JSON array | the parsed JSON array
-`parse_event_t::value` | the parser finished reading a JSON value | depth of the value | the parsed JSON value
+| parameter `event` | description | parameter `depth` | parameter `parsed` |
+|-------------------------------|-----------------------------------------------------------|-------------------------------------------|----------------------------------|
+| `parse_event_t::object_start` | the parser read `{` and started to process a JSON object | depth of the parent of the JSON object | a JSON value with type discarded |
+| `parse_event_t::key` | the parser read a key of a value in an object | depth of the currently parsed JSON object | a JSON string containing the key |
+| `parse_event_t::object_end` | the parser read `}` and finished processing a JSON object | depth of the parent of the JSON object | the parsed JSON object |
+| `parse_event_t::array_start` | the parser read `[` and started to process a JSON array | depth of the parent of the JSON array | a JSON value with type discarded |
+| `parse_event_t::array_end` | the parser read `]` and finished processing a JSON array | depth of the parent of the JSON array | the parsed JSON array |
+| `parse_event_t::value` | the parser finished reading a JSON value | depth of the value | the parsed JSON value |
@@ -51,7 +51,7 @@
Whether the JSON value which called the function during parsing should be kept (`#!cpp true`) or not (`#!cpp false`). In
the latter case, it is either skipped completely or replaced by an empty discarded object.
-# Example
+## Examples
??? example
diff --git a/doc/mkdocs/docs/api/basic_json/patch.md b/doc/mkdocs/docs/api/basic_json/patch.md
index d73e9c0..b3ef963 100644
--- a/doc/mkdocs/docs/api/basic_json/patch.md
+++ b/doc/mkdocs/docs/api/basic_json/patch.md
@@ -1,11 +1,11 @@
-# basic_json::patch
+# <small>nlohmann::basic_json::</small>patch
```cpp
basic_json patch(const basic_json& json_patch) const;
```
[JSON Patch](http://jsonpatch.com) defines a JSON document structure for expressing a sequence of operations to apply to
-a JSON) document. With this function, a JSON Patch is applied to the current JSON value by executing all operations from
+a JSON document. With this function, a JSON Patch is applied to the current JSON value by executing all operations from
the patch.
## Parameters
@@ -17,6 +17,10 @@
patched document
+## Exception safety
+
+Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
+
## Exceptions
- Throws [`parse_error.104`](../../home/exceptions.md#jsonexceptionparse_error104) if the JSON patch does not consist of
@@ -31,21 +35,17 @@
- Throws [`out_of_range.501`](../../home/exceptions.md#jsonexceptionother_error501) if "test" operation was
unsuccessful.
-## Exception safety
-
-Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
-
## Complexity
Linear in the size of the JSON value and the length of the JSON patch. As usually only a fraction of the JSON value is
affected by the patch, the complexity can usually be neglected.
-## Note
+## Notes
The application of a patch is atomic: Either all operations succeed and the patched document is returned or an exception
is thrown. In any case, the original value is not changed: the patch is applied to a copy of the value.
-## Example
+## Examples
??? example
@@ -61,6 +61,12 @@
--8<-- "examples/patch.output"
```
+## See also
+
+- [RFC 6902 (JSON Patch)](https://tools.ietf.org/html/rfc6902)
+- [RFC 6901 (JSON Pointer)](https://tools.ietf.org/html/rfc6901)
+- [merge_patch](merge_patch.md) applies a JSON Merge Patch
+
## Version history
- Added in version 2.0.0.
diff --git a/doc/mkdocs/docs/api/basic_json/push_back.md b/doc/mkdocs/docs/api/basic_json/push_back.md
index c10c94a..60bfed3 100644
--- a/doc/mkdocs/docs/api/basic_json/push_back.md
+++ b/doc/mkdocs/docs/api/basic_json/push_back.md
@@ -1,4 +1,4 @@
-# basic_json::push_back
+# <small>nlohmann::basic_json::</small>push_back
```cpp
// (1)
@@ -18,7 +18,7 @@
2. Inserts the given element `val` to the JSON object. If the function is called on a JSON null value, an empty object
is created before inserting `val`.
-3. This function allows to use `push_back` with an initializer list. In case
+3. This function allows using `push_back` with an initializer list. In case
1. the current value is an object,
2. the initializer list `init` contains only two elements, and
@@ -58,7 +58,7 @@
## Examples
-??? example
+??? example "Example: (1) add element to array"
The example shows how `push_back()` and `+=` can be used to add elements to a JSON array. Note how the `null` value
was silently converted to a JSON array.
@@ -73,7 +73,7 @@
--8<-- "examples/push_back.output"
```
-??? example
+??? example "Example: (2) add element to object"
The example shows how `push_back()` and `+=` can be used to add elements to a JSON object. Note how the `null` value
was silently converted to a JSON object.
@@ -88,7 +88,7 @@
--8<-- "examples/push_back__object_t__value.output"
```
-??? example
+??? example "Example: (3) add to object from initializer list"
The example shows how initializer lists are treated as objects when possible.
diff --git a/doc/mkdocs/docs/api/basic_json/rbegin.md b/doc/mkdocs/docs/api/basic_json/rbegin.md
index 57957b3..126c471 100644
--- a/doc/mkdocs/docs/api/basic_json/rbegin.md
+++ b/doc/mkdocs/docs/api/basic_json/rbegin.md
@@ -1,4 +1,4 @@
-# basic_json::rbegin
+# <small>nlohmann::basic_json::</small>rbegin
```cpp
reverse_iterator rbegin() noexcept;
@@ -21,7 +21,7 @@
Constant.
-## Example
+## Examples
??? example
diff --git a/doc/mkdocs/docs/api/basic_json/rend.md b/doc/mkdocs/docs/api/basic_json/rend.md
index 5d5f213..96da7a5 100644
--- a/doc/mkdocs/docs/api/basic_json/rend.md
+++ b/doc/mkdocs/docs/api/basic_json/rend.md
@@ -1,4 +1,4 @@
-# basic_json::rend
+# <small>nlohmann::basic_json::</small>rend
```cpp
reverse_iterator rend() noexcept;
@@ -22,7 +22,7 @@
Constant.
-## Example
+## Examples
??? example
diff --git a/doc/mkdocs/docs/api/basic_json/sax_parse.md b/doc/mkdocs/docs/api/basic_json/sax_parse.md
index 7a6dbad..e2ac1b4 100644
--- a/doc/mkdocs/docs/api/basic_json/sax_parse.md
+++ b/doc/mkdocs/docs/api/basic_json/sax_parse.md
@@ -1,4 +1,4 @@
-# basic_json::sax_parse
+# <small>nlohmann::basic_json::</small>sax_parse
```cpp
// (1)
@@ -23,10 +23,10 @@
1. Read from a compatible input.
2. Read from a pair of character iterators
- The value_type of the iterator must be a integral type with size of 1, 2 or 4 bytes, which will be interpreted
+ The value_type of the iterator must be an integral type with size of 1, 2 or 4 bytes, which will be interpreted
respectively as UTF-8, UTF-16 and UTF-32.
-The SAX event lister must follow the interface of `json_sax`.
+The SAX event lister must follow the interface of [`json_sax`](../json_sax/index.md).
## Template parameters
@@ -107,3 +107,9 @@
- Added in version 3.2.0.
- Ignoring comments via `ignore_comments` added in version 3.9.0.
+
+!!! warning "Deprecation"
+
+ Overload (2) replaces calls to `sax_parse` with a pair of iterators as their first parameter which has been
+ deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
+ `#!cpp sax_parse({ptr, ptr+len});` with `#!cpp sax_parse(ptr, ptr+len);`.
diff --git a/doc/mkdocs/docs/api/basic_json/size.md b/doc/mkdocs/docs/api/basic_json/size.md
index 36a9dae..4ff582d 100644
--- a/doc/mkdocs/docs/api/basic_json/size.md
+++ b/doc/mkdocs/docs/api/basic_json/size.md
@@ -1,4 +1,4 @@
-# basic_json::size
+# <small>nlohmann::basic_json::</small>size
```cpp
size_type size() const noexcept;
@@ -10,15 +10,15 @@
The return value depends on the different types and is defined as follows:
-Value type | return value
------------ | -------------
-null | `0`
-boolean | `1`
-string | `1`
-number | `1`
-binary | `1`
-object | result of function object_t::size()
-array | result of function array_t::size()
+| Value type | return value |
+|------------|-------------------------------------|
+| null | `0` |
+| boolean | `1` |
+| string | `1` |
+| number | `1` |
+| binary | `1` |
+| object | result of function object_t::size() |
+| array | result of function array_t::size() |
## Exception safety
@@ -35,7 +35,7 @@
This function does not return the length of a string stored as JSON value -- it returns the number of elements in the
JSON value which is `1` in the case of a string.
-## Example
+## Examples
??? example
diff --git a/doc/mkdocs/docs/api/basic_json/std_hash.md b/doc/mkdocs/docs/api/basic_json/std_hash.md
new file mode 100644
index 0000000..b66515d
--- /dev/null
+++ b/doc/mkdocs/docs/api/basic_json/std_hash.md
@@ -0,0 +1,32 @@
+# <small>std::</small>hash<nlohmann::basic_json\>
+
+```cpp
+namespace std {
+ struct hash<nlohmann::basic_json>;
+}
+```
+
+Return a hash value for a JSON object. The hash function tries to rely on `std::hash` where possible. Furthermore, the
+type of the JSON value is taken into account to have different hash values for `#!json null`, `#!cpp 0`, `#!cpp 0U`, and
+`#!cpp false`, etc.
+
+## Examples
+
+??? example
+
+ The example shows how to calculate hash values for different JSON values.
+
+ ```cpp
+ --8<-- "examples/std_hash.cpp"
+ ```
+
+ Output:
+
+ ```json
+ --8<-- "examples/std_hash.output"
+ ```
+
+## Version history
+
+- Added in version 1.0.0.
+- Extended for arbitrary basic_json types in version 3.10.5.
diff --git a/doc/mkdocs/docs/api/basic_json/std_swap.md b/doc/mkdocs/docs/api/basic_json/std_swap.md
new file mode 100644
index 0000000..d30f3bc
--- /dev/null
+++ b/doc/mkdocs/docs/api/basic_json/std_swap.md
@@ -0,0 +1,51 @@
+# std::swap<basic_json\>
+
+```cpp
+namespace std {
+ void swap(nlohmann::basic_json& j1, nlohmann::basic_json& j2);
+}
+```
+
+Exchanges the values of two JSON objects.
+
+## Parameters
+
+`j1` (in, out)
+: value to be replaced by `j2`
+
+`j2` (in, out)
+: value to be replaced by `j1`
+
+## Possible implementation
+
+```cpp
+void swap(nlohmann::basic_json& j1, nlohmann::basic_json& j2)
+{
+ j1.swap(j2);
+}
+```
+
+## Examples
+
+??? example
+
+ The following code shows how two values are swapped with `std::swap`.
+
+ ```cpp
+ --8<-- "examples/std_swap.cpp"
+ ```
+
+ Output:
+
+ ```json
+ --8<-- "examples/std_swap.output"
+ ```
+
+## See also
+
+- [swap](swap.md)
+
+## Version history
+
+- Added in version 1.0.0.
+- Extended for arbitrary basic_json types in version 3.10.5.
diff --git a/doc/mkdocs/docs/api/basic_json/string_t.md b/doc/mkdocs/docs/api/basic_json/string_t.md
index f6287f8..3ab4412 100644
--- a/doc/mkdocs/docs/api/basic_json/string_t.md
+++ b/doc/mkdocs/docs/api/basic_json/string_t.md
@@ -1,4 +1,4 @@
-# basic_json::string_t
+# <small>nlohmann::basic_json::</small>string_t
```cpp
using string_t = StringType;
@@ -45,6 +45,22 @@
String values are stored as pointers in a `basic_json` type. That is, for any access to string values, a pointer of type
`string_t*` must be dereferenced.
+## Examples
+
+??? example
+
+ The following code shows that `string_t` is by default, a typedef to `#!cpp std::string`.
+
+ ```cpp
+ --8<-- "examples/string_t.cpp"
+ ```
+
+ Output:
+
+ ```json
+ --8<-- "examples/string_t.output"
+ ```
+
## Version history
- Added in version 1.0.0.
diff --git a/doc/mkdocs/docs/api/basic_json/swap.md b/doc/mkdocs/docs/api/basic_json/swap.md
new file mode 100644
index 0000000..a5730ff
--- /dev/null
+++ b/doc/mkdocs/docs/api/basic_json/swap.md
@@ -0,0 +1,157 @@
+# <small>nlohmann::basic_json::</small>swap
+
+```cpp
+// (1)
+void swap(reference other) noexcept;
+
+// (2)
+void swap(reference left, reference right) noexcept;
+
+// (3)
+void swap(array_t& other);
+
+// (4)
+void swap(object_t& other);
+
+// (5)
+void swap(string_t& other);
+
+// (6)
+void swap(binary_t& other);
+
+// (7)
+void swap(typename binary_t::container_type& other);
+```
+
+1. Exchanges the contents of the JSON value with those of `other`. Does not invoke any move, copy, or swap operations on
+ individual elements. All iterators and references remain valid. The past-the-end iterator is invalidated.
+2. Exchanges the contents of the JSON value from `left` with those of `right`. Does not invoke any move, copy, or swap
+ operations on individual elements. All iterators and references remain valid. The past-the-end iterator is
+ invalidated. Implemented as a friend function callable via ADL.
+3. Exchanges the contents of a JSON array with those of `other`. Does not invoke any move, copy, or swap operations on
+ individual elements. All iterators and references remain valid. The past-the-end iterator is invalidated.
+4. Exchanges the contents of a JSON object with those of `other`. Does not invoke any move, copy, or swap operations on
+ individual elements. All iterators and references remain valid. The past-the-end iterator is invalidated.
+5. Exchanges the contents of a JSON string with those of `other`. Does not invoke any move, copy, or swap operations on
+ individual elements. All iterators and references remain valid. The past-the-end iterator is invalidated.
+6. Exchanges the contents of a binary value with those of `other`. Does not invoke any move, copy, or swap operations on
+ individual elements. All iterators and references remain valid. The past-the-end iterator is invalidated.
+7. Exchanges the contents of a binary value with those of `other`. Does not invoke any move, copy, or swap operations on
+ individual elements. All iterators and references remain valid. The past-the-end iterator is invalidated. Unlike
+ version (6), no binary subtype is involved.
+
+## Parameters
+
+`other` (in, out)
+: value to exchange the contents with
+
+`left` (in, out)
+: value to exchange the contents with
+
+`right` (in, out)
+: value to exchange the contents with
+
+## Exceptions
+
+1. No-throw guarantee: this function never throws exceptions.
+2. No-throw guarantee: this function never throws exceptions.
+3. Throws [`type_error.310`](../../home/exceptions.md#jsonexceptiontype_error310) if called on JSON values other than
+ arrays; example: `"cannot use swap() with boolean"`
+4. Throws [`type_error.310`](../../home/exceptions.md#jsonexceptiontype_error310) if called on JSON values other than
+ objects; example: `"cannot use swap() with boolean"`
+5. Throws [`type_error.310`](../../home/exceptions.md#jsonexceptiontype_error310) if called on JSON values other than
+ strings; example: `"cannot use swap() with boolean"`
+6. Throws [`type_error.310`](../../home/exceptions.md#jsonexceptiontype_error310) if called on JSON values other than
+ binaries; example: `"cannot use swap() with boolean"`
+7. Throws [`type_error.310`](../../home/exceptions.md#jsonexceptiontype_error310) if called on JSON values other than
+ binaries; example: `"cannot use swap() with boolean"`
+
+## Complexity
+
+Constant.
+
+## Examples
+
+??? example "Example: Swap JSON value (1, 2)"
+
+ The example below shows how JSON values can be swapped with `swap()`.
+
+ ```cpp
+ --8<-- "examples/swap__reference.cpp"
+ ```
+
+ Output:
+
+ ```json
+ --8<-- "examples/swap__reference.output"
+ ```
+
+??? example "Example: Swap array (3)"
+
+ The example below shows how arrays can be swapped with `swap()`.
+
+ ```cpp
+ --8<-- "examples/swap__array_t.cpp"
+ ```
+
+ Output:
+
+ ```json
+ --8<-- "examples/swap__array_t.output"
+ ```
+
+??? example "Example: Swap object (4)"
+
+ The example below shows how objects can be swapped with `swap()`.
+
+ ```cpp
+ --8<-- "examples/swap__object_t.cpp"
+ ```
+
+ Output:
+
+ ```json
+ --8<-- "examples/swap__object_t.output"
+ ```
+
+??? example "Example: Swap string (5)"
+
+ The example below shows how strings can be swapped with `swap()`.
+
+ ```cpp
+ --8<-- "examples/swap__string_t.cpp"
+ ```
+
+ Output:
+
+ ```json
+ --8<-- "examples/swap__string_t.output"
+ ```
+
+??? example "Example: Swap string (6)"
+
+ The example below shows how binary values can be swapped with `swap()`.
+
+ ```cpp
+ --8<-- "examples/swap__binary_t.cpp"
+ ```
+
+ Output:
+
+ ```json
+ --8<-- "examples/swap__binary_t.output"
+ ```
+
+## See also
+
+- [std::swap<basic_json\>](std_swap.md)
+
+## Version history
+
+1. Since version 1.0.0.
+2. Since version 1.0.0.
+3. Since version 1.0.0.
+4. Since version 1.0.0.
+5. Since version 1.0.0.
+6. Since version 3.8.0.
+7. Since version 3.8.0.
\ No newline at end of file
diff --git a/doc/mkdocs/docs/api/basic_json/to_bson.md b/doc/mkdocs/docs/api/basic_json/to_bson.md
index 747a4aa..664dd0e 100644
--- a/doc/mkdocs/docs/api/basic_json/to_bson.md
+++ b/doc/mkdocs/docs/api/basic_json/to_bson.md
@@ -1,4 +1,4 @@
-# basic_json::to_bson
+# <small>nlohmann::basic_json::</small>to_bson
```cpp
// (1)
@@ -15,6 +15,8 @@
1. Returns a byte vector containing the BSON serialization.
2. Writes the BSON serialization to an output adapter.
+The exact mapping and its limitations is described on a [dedicated page](../../features/binary_formats/bson.md).
+
## Parameters
`j` (in)
@@ -36,7 +38,7 @@
Linear in the size of the JSON value `j`.
-## Example
+## Examples
??? example
diff --git a/doc/mkdocs/docs/api/basic_json/to_cbor.md b/doc/mkdocs/docs/api/basic_json/to_cbor.md
index fd0eaa1..05d85ed 100644
--- a/doc/mkdocs/docs/api/basic_json/to_cbor.md
+++ b/doc/mkdocs/docs/api/basic_json/to_cbor.md
@@ -1,4 +1,4 @@
-# basic_json::to_cbor
+# <small>nlohmann::basic_json::</small>to_cbor
```cpp
// (1)
@@ -16,6 +16,8 @@
1. Returns a byte vector containing the CBOR serialization.
2. Writes the CBOR serialization to an output adapter.
+The exact mapping and its limitations is described on a [dedicated page](../../features/binary_formats/cbor.md).
+
## Parameters
`j` (in)
@@ -37,7 +39,7 @@
Linear in the size of the JSON value `j`.
-## Example
+## Examples
??? example
diff --git a/doc/mkdocs/docs/api/basic_json/to_msgpack.md b/doc/mkdocs/docs/api/basic_json/to_msgpack.md
index 1d438d7..fb4b40b 100644
--- a/doc/mkdocs/docs/api/basic_json/to_msgpack.md
+++ b/doc/mkdocs/docs/api/basic_json/to_msgpack.md
@@ -1,4 +1,4 @@
-# basic_json::to_msgpack
+# <small>nlohmann::basic_json::</small>to_msgpack
```cpp
// (1)
@@ -15,6 +15,8 @@
1. Returns a byte vector containing the MessagePack serialization.
2. Writes the MessagePack serialization to an output adapter.
+The exact mapping and its limitations is described on a [dedicated page](../../features/binary_formats/messagepack.md).
+
## Parameters
`j` (in)
@@ -36,7 +38,7 @@
Linear in the size of the JSON value `j`.
-## Example
+## Examples
??? example
diff --git a/doc/mkdocs/docs/api/basic_json/to_string.md b/doc/mkdocs/docs/api/basic_json/to_string.md
new file mode 100644
index 0000000..2b907e2
--- /dev/null
+++ b/doc/mkdocs/docs/api/basic_json/to_string.md
@@ -0,0 +1,65 @@
+# to_string(basic_json)
+
+```cpp
+template <typename BasicJsonType>
+std::string to_string(const BasicJsonType& j);
+```
+
+This function implements a user-defined to_string for JSON objects.
+
+## Template parameters
+
+`BasicJsonType`
+: a specialization of [`basic_json`](index.md)
+
+## Return value
+
+string containing the serialization of the JSON value
+
+## Exception safety
+
+Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
+
+## Exceptions
+
+Throws [`type_error.316`](../../home/exceptions.md#jsonexceptiontype_error316) if a string stored inside the JSON value
+is not UTF-8 encoded
+
+## Complexity
+
+Linear.
+
+## Possible implementation
+
+```cpp
+template <typename BasicJsonType>
+std::string to_string(const BasicJsonType& j)
+{
+ return j.dump();
+}
+```
+
+## Examples
+
+??? example
+
+ The following code shows how the library's `to_string()` function integrates with others, allowing
+ argument-dependent lookup.
+
+ ```cpp
+ --8<-- "examples/to_string.cpp"
+ ```
+
+ Output:
+
+ ```json
+ --8<-- "examples/to_string.output"
+ ```
+
+## See also
+
+- [dump](dump.md)
+
+## Version history
+
+Added in version 3.7.0.
diff --git a/doc/mkdocs/docs/api/basic_json/to_ubjson.md b/doc/mkdocs/docs/api/basic_json/to_ubjson.md
index a12a625..0a3d87e 100644
--- a/doc/mkdocs/docs/api/basic_json/to_ubjson.md
+++ b/doc/mkdocs/docs/api/basic_json/to_ubjson.md
@@ -1,4 +1,4 @@
-# basic_json::to_ubjson
+# <small>nlohmann::basic_json::</small>to_ubjson
```cpp
// (1)
@@ -19,6 +19,8 @@
1. Returns a byte vector containing the UBJSON serialization.
2. Writes the UBJSON serialization to an output adapter.
+The exact mapping and its limitations is described on a [dedicated page](../../features/binary_formats/ubjson.md).
+
## Parameters
`j` (in)
@@ -47,7 +49,7 @@
Linear in the size of the JSON value `j`.
-## Example
+## Examples
??? example
diff --git a/doc/mkdocs/docs/api/basic_json/type.md b/doc/mkdocs/docs/api/basic_json/type.md
index b348211..deedd6b 100644
--- a/doc/mkdocs/docs/api/basic_json/type.md
+++ b/doc/mkdocs/docs/api/basic_json/type.md
@@ -1,4 +1,4 @@
-# basic_json::type
+# <small>nlohmann::basic_json::</small>type
```cpp
constexpr value_t type() const noexcept;
@@ -10,18 +10,18 @@
the type of the JSON value
-Value type | return value
-------------------------- | -------------------------
-`#!json null` | `value_t::null`
-boolean | `value_t::boolean`
-string | `value_t::string`
-number (integer) | `value_t::number_integer`
-number (unsigned integer) | `value_t::number_unsigned`
-number (floating-point) | `value_t::number_float`
-object | `value_t::object`
-array | `value_t::array`
-binary | `value_t::binary`
-discarded | `value_t::discarded`
+| Value type | return value |
+|---------------------------|----------------------------|
+| `#!json null` | `value_t::null` |
+| boolean | `value_t::boolean` |
+| string | `value_t::string` |
+| number (integer) | `value_t::number_integer` |
+| number (unsigned integer) | `value_t::number_unsigned` |
+| number (floating-point) | `value_t::number_float` |
+| object | `value_t::object` |
+| array | `value_t::array` |
+| binary | `value_t::binary` |
+| discarded | `value_t::discarded` |
## Exception safety
@@ -31,7 +31,7 @@
Constant.
-## Example
+## Examples
??? example
diff --git a/doc/mkdocs/docs/api/basic_json/type_error.md b/doc/mkdocs/docs/api/basic_json/type_error.md
index ea0154e..cda54c0 100644
--- a/doc/mkdocs/docs/api/basic_json/type_error.md
+++ b/doc/mkdocs/docs/api/basic_json/type_error.md
@@ -1,4 +1,4 @@
-# basic_json::type_error
+# <small>nlohmann::basic_json::</small>type_error
```cpp
class type_error : public exception;
@@ -7,7 +7,7 @@
This exception is thrown in case of a type error; that is, a library function is executed on a JSON value whose type
does not match the expected semantics.
-Exceptions have ids 3xx.
+Exceptions have ids 3xx (see [list of type errors](../../home/exceptions.md#type-errors)).
```plantuml
std::exception <|-- basic_json::exception
@@ -39,7 +39,7 @@
- **id** - the id of the exception
-## Example
+## Examples
??? example
@@ -55,6 +55,14 @@
--8<-- "examples/type_error.output"
```
+## See also
+
+- [List of type errors](../../home/exceptions.md#type-errors)
+- [`parse_error`](parse_error.md) for exceptions indicating a parse error
+- [`invalid_iterator`](invalid_iterator.md) for exceptions indicating errors with iterators
+- [`out_of_range`](out_of_range.md) for exceptions indicating access out of the defined range
+- [`other_error`](other_error.md) for exceptions indicating other library errors
+
## Version history
- Since version 3.0.0.
diff --git a/doc/mkdocs/docs/api/basic_json/type_name.md b/doc/mkdocs/docs/api/basic_json/type_name.md
index 1a17526..389c2b1 100644
--- a/doc/mkdocs/docs/api/basic_json/type_name.md
+++ b/doc/mkdocs/docs/api/basic_json/type_name.md
@@ -1,4 +1,4 @@
-# basic_json::type_name
+# <small>nlohmann::basic_json::</small>type_name
```cpp
const char* type_name() const noexcept;
@@ -9,18 +9,18 @@
## Return value
-a string representation of a the type ([`value_t`](value_t.md)):
+a string representation of the type ([`value_t`](value_t.md)):
-Value type | return value
--------------------------------------------------- | -------------------------
-`#!json null` | `"null"`
-boolean | `"boolean"`
-string | `"string"`
-number (integer, unsigned integer, floating-point) | `"number"`
-object | `"object`
-array | `"array`
-binary | `"binary`
-discarded | `"discarded`
+| Value type | return value |
+|----------------------------------------------------|---------------|
+| `#!json null` | `"null"` |
+| boolean | `"boolean"` |
+| string | `"string"` |
+| number (integer, unsigned integer, floating-point) | `"number"` |
+| object | `"object"` |
+| array | `"array"` |
+| binary | `"binary"` |
+| discarded | `"discarded"` |
## Exception safety
@@ -30,7 +30,7 @@
Constant.
-## Example
+## Examples
??? example
diff --git a/doc/mkdocs/docs/api/basic_json/unflatten.md b/doc/mkdocs/docs/api/basic_json/unflatten.md
index 3794286..d977803 100644
--- a/doc/mkdocs/docs/api/basic_json/unflatten.md
+++ b/doc/mkdocs/docs/api/basic_json/unflatten.md
@@ -1,4 +1,4 @@
-# basic_json::unflatten
+# <small>nlohmann::basic_json::</small>unflatten
```cpp
basic_json unflatten() const;
@@ -15,6 +15,10 @@
the original JSON from a flattened version
+## Exception safety
+
+Strong exception safety: if an exception occurs, the original value stays intact.
+
## Exceptions
The function can throw the following exceptions:
@@ -22,10 +26,6 @@
- Throws [`type_error.314`](../../home/exceptions.md#jsonexceptiontype_error314) if value is not an object
- Throws [`type_error.315`](../../home/exceptions.md#jsonexceptiontype_error315) if object values are not primitive
-## Exception safety
-
-Strong exception safety: if an exception occurs, the original value stays intact.
-
## Complexity
Linear in the size the JSON value.
@@ -36,7 +36,7 @@
their original type. Apart from this example, for a JSON value `j`, the following is always true:
`#!cpp j == j.flatten().unflatten()`.
-## Example
+## Examples
??? example
@@ -52,6 +52,10 @@
--8<-- "examples/unflatten.output"
```
+## See also
+
+- [flatten](flatten.md) the reverse function
+
## Version history
- Added in version 2.0.0.
diff --git a/doc/mkdocs/docs/api/basic_json/update.md b/doc/mkdocs/docs/api/basic_json/update.md
index a1837c8..9eeec40 100644
--- a/doc/mkdocs/docs/api/basic_json/update.md
+++ b/doc/mkdocs/docs/api/basic_json/update.md
@@ -1,15 +1,18 @@
-# basic_json::update
+# <small>nlohmann::basic_json::</small>update
```cpp
// (1)
-void update(const_reference j);
+void update(const_reference j, bool merge_objects = false);
// (2)
-void update(const_iterator first, const_iterator last);
+void update(const_iterator first, const_iterator last, bool merge_objects = false);
```
-1. Inserts all values from JSON object `j` and overwrites existing keys.
-2. Inserts all values from from range `[first, last)` and overwrites existing keys.
+1. Inserts all values from JSON object `j`.
+2. Inserts all values from range `[first, last)`
+
+When `merge_objects` is `#!c false` (default), existing keys are overwritten. When `merge_objects` is `#!c true`,
+recursively merges objects with common keys.
The function is motivated by Python's [dict.update](https://docs.python.org/3.6/library/stdtypes.html#dict.update)
function.
@@ -19,6 +22,10 @@
`j` (in)
: JSON object to read values from
+`merge_objects` (in)
+: when `#!c true`, existing keys are not overwritten, but contents of objects are merged recursively (default:
+ `#!c false`)
+
`first` (in)
: begin of the range of elements to insert
@@ -30,7 +37,7 @@
1. The function can throw the following exceptions:
- Throws [`type_error.312`](../../home/exceptions.md#jsonexceptiontype_error312) if called on JSON values other than
objects; example: `"cannot use update() with string"`
-2. The function can throw thw following exceptions:
+2. The function can throw the following exceptions:
- Throws [`type_error.312`](../../home/exceptions.md#jsonexceptiontype_error312) if called on JSON values other than
objects; example: `"cannot use update() with string"`
- Throws [`invalid_iterator.202`](../../home/exceptions.md#jsonexceptioninvalid_iterator202) if called on an
@@ -43,7 +50,7 @@
1. O(N*log(size() + N)), where N is the number of elements to insert.
2. O(N*log(size() + N)), where N is the number of elements to insert.
-## Example
+## Examples
??? example
@@ -73,6 +80,63 @@
--8<-- "examples/update__range.output"
```
+??? example
+
+ One common usecase for this function is the handling of user settings. Assume your application can configured in
+ some aspects:
+
+ ```json
+ {
+ "color": "red",
+ "active": true,
+ "name": {"de": "Maus", "en": "mouse"}
+ }
+ ```
+
+ The user may override the default settings selectively:
+
+ ```json
+ {
+ "color": "blue",
+ "name": {"es": "ratón"},
+ }
+ ```
+
+ Then `update` manages the merging of default settings and user settings:
+
+ ```cpp
+ auto user_settings = json::parse("config.json");
+ auto effective_settings = get_default_settings();
+ effective_settings.update(user_settings);
+ ```
+
+ Now `effective_settings` contains the default settings, but those keys set by the user are overwritten:
+
+ ```json
+ {
+ "color": "blue",
+ "active": true,
+ "name": {"es": "ratón"}
+ }
+ ```
+
+ Note existing keys were just overwritten. To merge objects, `merge_objects` setting should be set to `#!c true`:
+
+ ```cpp
+ auto user_settings = json::parse("config.json");
+ auto effective_settings = get_default_settings();
+ effective_settings.update(user_settings, true);
+ ```
+
+ ```json
+ {
+ "color": "blue",
+ "active": true,
+ "name": {"de": "Maus", "en": "mouse", "es": "ratón"}
+ }
+ ```
+
## Version history
- Added in version 3.0.0.
+- Added `merge_objects` parameter in 3.10.4.
diff --git a/doc/mkdocs/docs/api/basic_json/value.md b/doc/mkdocs/docs/api/basic_json/value.md
index 8fdbc23..0b4f1cc 100644
--- a/doc/mkdocs/docs/api/basic_json/value.md
+++ b/doc/mkdocs/docs/api/basic_json/value.md
@@ -1,4 +1,4 @@
-# basic_json::value
+# <small>nlohmann::basic_json::</small>value
```cpp
// (1)
@@ -36,8 +36,11 @@
}
```
-Unlike [`operator[]`](operator[].md), this function does not implicitly add an element to the position defined by
-`key`/`ptr` key. This function is furthermore also applicable to const objects.
+!!! note
+
+ - Unlike [`at`](at.md), this function does not throw if the given `key`/`ptr` was not found.
+ - Unlike [`operator[]`](operator[].md), this function does not implicitly add an element to the position defined by
+ `key`/`ptr` key. This function is furthermore also applicable to const objects.
## Template parameters
@@ -69,12 +72,12 @@
## Exceptions
-1. The function can throw thw following exceptions:
+1. The function can throw the following exceptions:
- Throws [`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302) if `default_value` does not match
the type of the value at `key`
- Throws [`type_error.306`](../../home/exceptions.md#jsonexceptiontype_error306) if the JSON value is not an object;
in that case, using `value()` with a key makes no sense.
-2. The function can throw thw following exceptions:
+2. The function can throw the following exceptions:
- Throws [`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302) if `default_value` does not match
the type of the value at `ptr`
- Throws [`type_error.306`](../../home/exceptions.md#jsonexceptiontype_error306) if the JSON value is not an object;
@@ -85,9 +88,9 @@
1. Logarithmic in the size of the container.
2. Logarithmic in the size of the container.
-## Example
+## Examples
-??? example
+??? example "Example (1): access specified object element with default value"
The example below shows how object elements can be queried with a default value.
@@ -101,7 +104,7 @@
--8<-- "examples/basic_json__value.output"
```
-??? example
+??? example "Example (2): access specified object element via JSON Pointer with default value"
The example below shows how object elements can be queried with a default value.
@@ -115,6 +118,11 @@
--8<-- "examples/basic_json__value_ptr.output"
```
+## See also
+
+- see [`at`](at.md) for access by reference with range checking
+- see [`operator[]`](operator%5B%5D.md) for unchecked access by reference
+
## Version history
1. Added in version 1.0.0.
diff --git a/doc/mkdocs/docs/api/basic_json/value_t.md b/doc/mkdocs/docs/api/basic_json/value_t.md
index 5fa9501..768b13c 100644
--- a/doc/mkdocs/docs/api/basic_json/value_t.md
+++ b/doc/mkdocs/docs/api/basic_json/value_t.md
@@ -1,4 +1,4 @@
-# basic_json::value_t
+# <small>nlohmann::basic_json::</small>value_t
```cpp
enum class value_t : std::uint8_t {
@@ -22,7 +22,7 @@
[`is_discarded`](is_discarded.md), [`is_binary`](is_binary.md), [`is_primitive`](is_primitive.md), and
[`is_structured`](is_structured.md) rely on it.
-## Note
+## 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,
diff --git a/doc/mkdocs/docs/api/basic_json/~basic_json.md b/doc/mkdocs/docs/api/basic_json/~basic_json.md
index b089b0d..c5c74a5 100644
--- a/doc/mkdocs/docs/api/basic_json/~basic_json.md
+++ b/doc/mkdocs/docs/api/basic_json/~basic_json.md
@@ -1,7 +1,7 @@
-# basic_json::~basic_json
+# <small>nlohmann::basic_json::</small>~basic_json
```cpp
-~basic_json() noexcept
+~basic_json() noexcept;
```
Destroys the JSON value and frees all allocated memory.
diff --git a/doc/mkdocs/docs/api/byte_container_with_subtype/byte_container_with_subtype.md b/doc/mkdocs/docs/api/byte_container_with_subtype/byte_container_with_subtype.md
new file mode 100644
index 0000000..caa273d
--- /dev/null
+++ b/doc/mkdocs/docs/api/byte_container_with_subtype/byte_container_with_subtype.md
@@ -0,0 +1,30 @@
+# <small>nlohmann::byte_container_with_subtype::</small>byte_container_with_subtype
+
+```cpp
+// (1)
+byte_container_with_subtype();
+
+// (2)
+byte_container_with_subtype(const container_type& container);
+byte_container_with_subtype(container_type&& container);
+
+// (3)
+byte_container_with_subtype(const container_type& container, subtype_type subtype);
+byte_container_with_subtype(container_type&& container, subtype_type subtype);
+```
+
+1. Create empty binary container without subtype.
+2. Create binary container without subtype.
+3. Create binary container with subtype.
+
+## Parameters
+
+`container` (in)
+: binary container
+
+`subtype` (in)
+: subtype
+
+## Version history
+
+Since version 3.8.0.
diff --git a/doc/mkdocs/docs/api/byte_container_with_subtype/clear_subtype.md b/doc/mkdocs/docs/api/byte_container_with_subtype/clear_subtype.md
new file mode 100644
index 0000000..56f8ee0
--- /dev/null
+++ b/doc/mkdocs/docs/api/byte_container_with_subtype/clear_subtype.md
@@ -0,0 +1,20 @@
+# <small>nlohmann::byte_container_with_subtype::</small>clear_subtype
+
+```cpp
+void clear_subtype() noexcept;
+```
+
+Clears the binary subtype and flags the value as not having a subtype, which has implications for serialization; for
+instance MessagePack will prefer the bin family over the ext family.
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Version history
+
+Since version 3.8.0.
diff --git a/doc/mkdocs/docs/api/byte_container_with_subtype/has_subtype.md b/doc/mkdocs/docs/api/byte_container_with_subtype/has_subtype.md
new file mode 100644
index 0000000..2fe4181
--- /dev/null
+++ b/doc/mkdocs/docs/api/byte_container_with_subtype/has_subtype.md
@@ -0,0 +1,23 @@
+# <small>nlohmann::byte_container_with_subtype::</small>has_subtype
+
+```cpp
+constexpr bool has_subtype() const noexcept;
+```
+
+Returns whether the value has a subtype.
+
+## Return value
+
+whether the value has a subtype
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Version history
+
+Since version 3.8.0.
diff --git a/doc/mkdocs/docs/api/byte_container_with_subtype/index.md b/doc/mkdocs/docs/api/byte_container_with_subtype/index.md
new file mode 100644
index 0000000..277fffa
--- /dev/null
+++ b/doc/mkdocs/docs/api/byte_container_with_subtype/index.md
@@ -0,0 +1,35 @@
+# <small>nlohmann::</small>byte_container_with_subtype
+
+```cpp
+template<typename BinaryType>
+class byte_container_with_subtype : public BinaryType;
+```
+
+This type extends the template parameter `BinaryType` provided to [`basic_json`](../basic_json/index.md) with a subtype
+used by BSON and MessagePack. This type exists so that the user does not have to specify a type themselves with a
+specific naming scheme in order to override the binary type.
+
+## Template parameters
+
+`BinaryType`
+: container to store bytes (`#!cpp std::vector<std::uint8_t>` by default)
+
+## Member types
+
+- **container_type** - the type of the underlying container (`BinaryType`)
+- **subtype_type** - the type of the subtype (`#!cpp std::uint64_t`)
+
+## Member functions
+
+- [(constructor)](byte_container_with_subtype.md)
+- **operator==** - comparison: equal
+- **operator!=** - comparison: not equal
+- [**set_subtype**](subtype.md) - sets the binary subtype
+- [**subtype**](subtype.md) - return the binary subtype
+- [**has_subtype**](has_subtype.md) - return whether the value has a subtype
+- [**clear_subtype**](clear_subtype.md) - clears the binary subtype
+
+## Version history
+
+- Added in version 3.8.0.
+- Changed type of subtypes to `#!cpp std::uint64_t` in 3.10.0.
diff --git a/doc/mkdocs/docs/api/byte_container_with_subtype/set_subtype.md b/doc/mkdocs/docs/api/byte_container_with_subtype/set_subtype.md
new file mode 100644
index 0000000..40cc272
--- /dev/null
+++ b/doc/mkdocs/docs/api/byte_container_with_subtype/set_subtype.md
@@ -0,0 +1,25 @@
+# <small>nlohmann::byte_container_with_subtype::</small>set_subtype
+
+```cpp
+void set_subtype(subtype_type subtype) noexcept;
+```
+
+Sets the binary subtype of the value, also flags a binary JSON value as having a subtype, which has implications for
+serialization.
+
+## Parameters
+
+`subtype` (in)
+: subtype to set
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Version history
+
+Since version 3.8.0.
diff --git a/doc/mkdocs/docs/api/byte_container_with_subtype/subtype.md b/doc/mkdocs/docs/api/byte_container_with_subtype/subtype.md
new file mode 100644
index 0000000..e78654b
--- /dev/null
+++ b/doc/mkdocs/docs/api/byte_container_with_subtype/subtype.md
@@ -0,0 +1,25 @@
+# <small>nlohmann::byte_container_with_subtype::</small>subtype
+
+```cpp
+constexpr subtype_type subtype() const noexcept;
+```
+
+Returns the numerical subtype of the value if it has a subtype. If it does not have a subtype, this function will return
+`subtype_type(-1)` as a sentinel value.
+
+## Return value
+
+the numerical subtype of the binary value, or `subtype_type(-1)` if no subtype is set
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Version history
+
+- Added in version 3.8.0
+- Fixed return value to properly return `subtype_type(-1)` as documented in version 3.10.0.
diff --git a/doc/mkdocs/docs/api/json.md b/doc/mkdocs/docs/api/json.md
index 0aff6d2..48d3441 100644
--- a/doc/mkdocs/docs/api/json.md
+++ b/doc/mkdocs/docs/api/json.md
@@ -1,5 +1,12 @@
-# json
+# <small>nlohmann::</small>json
```cpp
using json = basic_json<>;
```
+
+This type is the default specialization of the [basic_json](basic_json/index.md) class which uses the standard template
+types.
+
+## Version history
+
+Since version 1.0.0.
diff --git a/doc/mkdocs/docs/api/json_pointer.md b/doc/mkdocs/docs/api/json_pointer.md
deleted file mode 100644
index 5aa0399..0000000
--- a/doc/mkdocs/docs/api/json_pointer.md
+++ /dev/null
@@ -1,24 +0,0 @@
-# json_pointer
-
-```cpp
-template<typename BasicJsonType>
-class json_pointer;
-```
-
-## Template parameters
-
-`BasicJsonType`
-: a specialization of [`basic_json`](basic_json/index.md)
-
-## Member functions
-
-- (constructor)
-- **to_string** - return a string representation of the JSON pointer
-- **operator std::string**- return a string representation of the JSON pointer
-- **operator/=** - append to the end of the JSON pointer
-- **operator/** - create JSON Pointer by appending
-- **parent_pointer** - returns the parent of this JSON pointer
-- **pop_back** - remove last reference token
-- **back** - return last reference token
-- **push_back** - append an unescaped token at the end of the pointer
-- **empty** - return whether pointer points to the root document
diff --git a/doc/mkdocs/docs/api/json_pointer/back.md b/doc/mkdocs/docs/api/json_pointer/back.md
new file mode 100644
index 0000000..2b267bc
--- /dev/null
+++ b/doc/mkdocs/docs/api/json_pointer/back.md
@@ -0,0 +1,39 @@
+# <small>nlohmann::json_pointer::</small>back
+
+```cpp
+const std::string& back() const;
+```
+
+Return last reference token.
+
+## Return value
+
+Last reference token.
+
+## Exceptions
+
+Throws [out_of_range.405](../../home/exceptions.md#jsonexceptionout_of_range405) if JSON pointer has no parent.
+
+## Complexity
+
+Constant.
+
+## Examples
+
+??? example
+
+ The example shows the usage of `back`.
+
+ ```cpp
+ --8<-- "examples/json_pointer__back.cpp"
+ ```
+
+ Output:
+
+ ```json
+ --8<-- "examples/json_pointer__back.output"
+ ```
+
+## Version history
+
+Added in version 3.6.0.
diff --git a/doc/mkdocs/docs/api/json_pointer/empty.md b/doc/mkdocs/docs/api/json_pointer/empty.md
new file mode 100644
index 0000000..346364a
--- /dev/null
+++ b/doc/mkdocs/docs/api/json_pointer/empty.md
@@ -0,0 +1,39 @@
+# <small>nlohmann::json_pointer::</small>empty
+
+```cpp
+bool empty() const noexcept;
+```
+
+Return whether pointer points to the root document.
+
+## Return value
+
+`#!cpp true` iff the JSON pointer points to the root document.
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Examples
+
+??? example
+
+ The example shows the result of `empty` for different JSON Pointers.
+
+ ```cpp
+ --8<-- "examples/json_pointer__empty.cpp"
+ ```
+
+ Output:
+
+ ```json
+ --8<-- "examples/json_pointer__empty.output"
+ ```
+
+## Version history
+
+Added in version 3.6.0.
diff --git a/doc/mkdocs/docs/api/json_pointer/index.md b/doc/mkdocs/docs/api/json_pointer/index.md
new file mode 100644
index 0000000..6ef9435
--- /dev/null
+++ b/doc/mkdocs/docs/api/json_pointer/index.md
@@ -0,0 +1,36 @@
+# <small>nlohmann::</small>json_pointer
+
+```cpp
+template<typename BasicJsonType>
+class json_pointer;
+```
+
+A JSON pointer defines a string syntax for identifying a specific value within a JSON document. It can be used with
+functions [`at`](../basic_json/at.md) and [`operator[]`](../basic_json/operator%5B%5D.md). Furthermore, JSON pointers
+are the base for JSON patches.
+
+## Template parameters
+
+`BasicJsonType`
+: a specialization of [`basic_json`](../basic_json/index.md)
+
+## Member functions
+
+- [(constructor)](json_pointer.md)
+- [**to_string**](to_string.md) - return a string representation of the JSON pointer
+- [**operator std::string**](operator_string.md) - return a string representation of the JSON pointer
+- [**operator/=**](operator_slasheq.md) - append to the end of the JSON pointer
+- [**operator/**](operator_slash.md) - create JSON Pointer by appending
+- [**parent_pointer**](parent_pointer.md) - returns the parent of this JSON pointer
+- [**pop_back**](pop_back.md) - remove last reference token
+- [**back**](back.md) - return last reference token
+- [**push_back**](push_back.md) - append an unescaped token at the end of the pointer
+- [**empty**](empty.md) - return whether pointer points to the root document
+
+## See also
+
+- [RFC 6901](https://datatracker.ietf.org/doc/html/rfc6901)
+
+## Version history
+
+Added in version 2.0.0.
diff --git a/doc/mkdocs/docs/api/json_pointer/json_pointer.md b/doc/mkdocs/docs/api/json_pointer/json_pointer.md
new file mode 100644
index 0000000..1e68a28
--- /dev/null
+++ b/doc/mkdocs/docs/api/json_pointer/json_pointer.md
@@ -0,0 +1,40 @@
+# <small>nlohmann::json_pointer::</small>json_pointer
+
+```cpp
+explicit json_pointer(const std::string& s = "");
+```
+
+Create a JSON pointer according to the syntax described in
+[Section 3 of RFC6901](https://tools.ietf.org/html/rfc6901#section-3).
+
+## Parameters
+
+`s` (in)
+: string representing the JSON pointer; if omitted, the empty string is assumed which references the whole JSON value
+
+## Exceptions
+
+- Throws [parse_error.107](../../home/exceptions.md#jsonexceptionparse_error107) if the given JSON pointer `s` is
+ nonempty and does not begin with a slash (`/`); see example below.
+- Throws [parse_error.108](../../home/exceptions.md#jsonexceptionparse_error108) if a tilde (`~`) in the given JSON
+ pointer `s` is not followed by `0` (representing `~`) or `1` (representing `/`); see example below.
+
+## Examples
+
+??? example
+
+ The example shows the construction several valid JSON pointers as well as the exceptional behavior.
+
+ ```cpp
+ --8<-- "examples/json_pointer.cpp"
+ ```
+
+ Output:
+
+ ```json
+ --8<-- "examples/json_pointer.output"
+ ```
+
+## Version history
+
+Added in version 2.0.0.
diff --git a/doc/mkdocs/docs/api/json_pointer/operator_slash.md b/doc/mkdocs/docs/api/json_pointer/operator_slash.md
new file mode 100644
index 0000000..c928754
--- /dev/null
+++ b/doc/mkdocs/docs/api/json_pointer/operator_slash.md
@@ -0,0 +1,64 @@
+# <small>nlohmann::json_pointer::</small>operator/
+
+```cpp
+// (1)
+json_pointer operator/(const json_pointer& lhs, const json_pointer& rhs);
+
+// (2)
+json_pointer operator/(const json_pointer& lhs, std::string token);
+
+// (3)
+json_pointer operator/(const json_pointer& lhs, std::size_t array_idx);
+```
+
+1. create a new JSON pointer by appending the right JSON pointer at the end of the left JSON pointer
+2. create a new JSON pointer by appending the unescaped token at the end of the JSON pointer
+3. create a new JSON pointer by appending the array-index-token at the end of the JSON pointer
+
+## Parameters
+
+`lhs` (in)
+: JSON pointer
+
+`rhs` (in)
+: JSON pointer to append
+
+`token` (in)
+: reference token to append
+
+`array_idx` (in)
+: array index to append
+
+## Return value
+
+1. a new JSON pointer with `rhs` appended to `lhs`
+2. a new JSON pointer with unescaped `token` appended to `lhs`
+3. a new JSON pointer with `array_idx` appended to `lhs`
+
+## Complexity
+
+1. Linear in the length of `lhs` and `rhs`.
+2. Linear in the length of `lhs`.
+3. Linear in the length of `lhs`.
+
+## Examples
+
+??? example
+
+ The example shows the usage of `operator/`.
+
+ ```cpp
+ --8<-- "examples/json_pointer__operator_add_binary.cpp"
+ ```
+
+ Output:
+
+ ```json
+ --8<-- "examples/json_pointer__operator_add_binary.output"
+ ```
+
+## Version history
+
+1. Added in version 3.6.0.
+2. Added in version 3.6.0.
+3. Added in version 3.6.0.
diff --git a/doc/mkdocs/docs/api/json_pointer/operator_slasheq.md b/doc/mkdocs/docs/api/json_pointer/operator_slasheq.md
new file mode 100644
index 0000000..eb6c308
--- /dev/null
+++ b/doc/mkdocs/docs/api/json_pointer/operator_slasheq.md
@@ -0,0 +1,61 @@
+# <small>nlohmann::json_pointer::</small>operator/=
+
+```cpp
+// (1)
+json_pointer& operator/=(const json_pointer& ptr);
+
+// (2)
+json_pointer& operator/=(std::string token);
+
+// (3)
+json_pointer& operator/=(std::size_t array_idx)
+```
+
+1. append another JSON pointer at the end of this JSON pointer
+2. append an unescaped reference token at the end of this JSON pointer
+3. append an array index at the end of this JSON pointer
+
+## Parameters
+
+`ptr` (in)
+: JSON pointer to append
+
+`token` (in)
+: reference token to append
+
+`array_idx` (in)
+: array index to append
+
+## Return value
+
+1. JSON pointer with `ptr` appended
+2. JSON pointer with `token` appended without escaping `token`
+3. JSON pointer with `array_idx` appended
+
+## Complexity
+
+1. Linear in the length of `ptr`.
+2. Amortized constant.
+3. Amortized constant.
+
+## Examples
+
+??? example
+
+ The example shows the usage of `operator/=`.
+
+ ```cpp
+ --8<-- "examples/json_pointer__operator_add.cpp"
+ ```
+
+ Output:
+
+ ```json
+ --8<-- "examples/json_pointer__operator_add.output"
+ ```
+
+## Version history
+
+1. Added in version 3.6.0.
+2. Added in version 3.6.0.
+3. Added in version 3.6.0.
diff --git a/doc/mkdocs/docs/api/json_pointer/operator_string.md b/doc/mkdocs/docs/api/json_pointer/operator_string.md
new file mode 100644
index 0000000..56d8eeb
--- /dev/null
+++ b/doc/mkdocs/docs/api/json_pointer/operator_string.md
@@ -0,0 +1,24 @@
+# <small>nlohmann::json_pointer::</small>operator std::string
+
+```cpp
+operator std::string() const
+```
+
+Return a string representation of the JSON pointer.
+
+## Return value
+
+A string representation of the JSON pointer
+
+## Possible implementation
+
+```cpp
+operator std::string() const
+{
+ return to_string();
+}
+```
+
+## Version history
+
+Since version 2.0.0.
diff --git a/doc/mkdocs/docs/api/json_pointer/parent_pointer.md b/doc/mkdocs/docs/api/json_pointer/parent_pointer.md
new file mode 100644
index 0000000..1398730
--- /dev/null
+++ b/doc/mkdocs/docs/api/json_pointer/parent_pointer.md
@@ -0,0 +1,35 @@
+# <small>nlohmann::json_pointer::</small>parent_pointer
+
+```cpp
+json_pointer parent_pointer() const;
+```
+
+Returns the parent of this JSON pointer.
+
+## Return value
+
+Parent of this JSON pointer; in case this JSON pointer is the root, the root itself is returned.
+
+## Complexity
+
+Linear in the length of the JSON pointer.
+
+## Examples
+
+??? example
+
+ The example shows the result of `parent_pointer` for different JSON Pointers.
+
+ ```cpp
+ --8<-- "examples/json_pointer__parent_pointer.cpp"
+ ```
+
+ Output:
+
+ ```json
+ --8<-- "examples/json_pointer__parent_pointer.output"
+ ```
+
+## Version history
+
+Added in version 3.6.0.
diff --git a/doc/mkdocs/docs/api/json_pointer/pop_back.md b/doc/mkdocs/docs/api/json_pointer/pop_back.md
new file mode 100644
index 0000000..3c79f36
--- /dev/null
+++ b/doc/mkdocs/docs/api/json_pointer/pop_back.md
@@ -0,0 +1,35 @@
+# <small>nlohmann::json_pointer::</small>pop_back
+
+```cpp
+void pop_back();
+```
+
+Remove last reference token.
+
+## Exceptions
+
+Throws [out_of_range.405](../../home/exceptions.md#jsonexceptionout_of_range405) if JSON pointer has no parent.
+
+## Complexity
+
+Constant.
+
+## Examples
+
+??? example
+
+ The example shows the usage of `pop_back`.
+
+ ```cpp
+ --8<-- "examples/json_pointer__pop_back.cpp"
+ ```
+
+ Output:
+
+ ```json
+ --8<-- "examples/json_pointer__pop_back.output"
+ ```
+
+## Version history
+
+Added in version 3.6.0.
diff --git a/doc/mkdocs/docs/api/json_pointer/push_back.md b/doc/mkdocs/docs/api/json_pointer/push_back.md
new file mode 100644
index 0000000..3ebcdbc
--- /dev/null
+++ b/doc/mkdocs/docs/api/json_pointer/push_back.md
@@ -0,0 +1,38 @@
+# <small>nlohmann::json_pointer::</small>push_back
+
+```cpp
+void push_back(const std::string& token);
+
+void push_back(std::string&& token);
+```
+
+Append an unescaped token at the end of the reference pointer.
+
+## Parameters
+
+`token` (in)
+: token to add
+
+## Complexity
+
+Amortized constant.
+
+## Examples
+
+??? example
+
+ The example shows the result of `push_back` for different JSON Pointers.
+
+ ```cpp
+ --8<-- "examples/json_pointer__push_back.cpp"
+ ```
+
+ Output:
+
+ ```json
+ --8<-- "examples/json_pointer__push_back.output"
+ ```
+
+## Version history
+
+Added in version 3.6.0.
diff --git a/doc/mkdocs/docs/api/json_pointer/to_string.md b/doc/mkdocs/docs/api/json_pointer/to_string.md
new file mode 100644
index 0000000..9287436
--- /dev/null
+++ b/doc/mkdocs/docs/api/json_pointer/to_string.md
@@ -0,0 +1,39 @@
+# <small>nlohmann::json_pointer::</small>to_string
+
+```cpp
+std::string to_string() const;
+```
+
+Return a string representation of the JSON pointer.
+
+## Return value
+
+A string representation of the JSON pointer
+
+## Notes
+
+For each JSON pointer `ptr`, it holds:
+
+```cpp
+ptr == json_pointer(ptr.to_string());
+```
+
+## Examples
+
+??? example
+
+ The example shows the result of `to_string`.
+
+ ```cpp
+ --8<-- "examples/json_pointer__to_string.cpp"
+ ```
+
+ Output:
+
+ ```json
+ --8<-- "examples/json_pointer__to_string.output"
+ ```
+
+## Version history
+
+Since version 2.0.0.
diff --git a/doc/mkdocs/docs/api/json_sax/binary.md b/doc/mkdocs/docs/api/json_sax/binary.md
new file mode 100644
index 0000000..e9a1d39
--- /dev/null
+++ b/doc/mkdocs/docs/api/json_sax/binary.md
@@ -0,0 +1,24 @@
+# <small>nlohmann::json_sax::</small>binary
+
+```cpp
+virtual bool binary(binary_t& val) = 0;
+```
+
+A binary value was read.
+
+## Parameters
+
+`val` (in)
+: binary value
+
+## Return value
+
+Whether parsing should proceed.
+
+## Notes
+
+It is safe to move the passed binary value.
+
+## Version history
+
+- Added in version 3.8.0.
diff --git a/doc/mkdocs/docs/api/json_sax/boolean.md b/doc/mkdocs/docs/api/json_sax/boolean.md
new file mode 100644
index 0000000..a5a8ddc
--- /dev/null
+++ b/doc/mkdocs/docs/api/json_sax/boolean.md
@@ -0,0 +1,20 @@
+# <small>nlohmann::json_sax::</small>boolean
+
+```cpp
+virtual bool boolean(bool val) = 0;
+```
+
+A boolean value was read.
+
+## Parameters
+
+`val` (in)
+: boolean value
+
+## Return value
+
+Whether parsing should proceed.
+
+## Version history
+
+- Added in version 3.2.0.
diff --git a/doc/mkdocs/docs/api/json_sax/end_array.md b/doc/mkdocs/docs/api/json_sax/end_array.md
new file mode 100644
index 0000000..245cf97
--- /dev/null
+++ b/doc/mkdocs/docs/api/json_sax/end_array.md
@@ -0,0 +1,15 @@
+# <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.
diff --git a/doc/mkdocs/docs/api/json_sax/end_object.md b/doc/mkdocs/docs/api/json_sax/end_object.md
new file mode 100644
index 0000000..5654e26
--- /dev/null
+++ b/doc/mkdocs/docs/api/json_sax/end_object.md
@@ -0,0 +1,15 @@
+# <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.
diff --git a/doc/mkdocs/docs/api/json_sax/index.md b/doc/mkdocs/docs/api/json_sax/index.md
new file mode 100644
index 0000000..f63e85c
--- /dev/null
+++ b/doc/mkdocs/docs/api/json_sax/index.md
@@ -0,0 +1,44 @@
+# <small>nlohmann::</small>json_sax
+
+```cpp
+template<typename BasicJsonType>
+struct json_sax;
+```
+
+This class describes the SAX interface used by [sax_parse](../basic_json/sax_parse.md). Each function is called in
+different situations while the input is parsed. The boolean return value informs the parser whether to continue
+processing the input.
+
+## Template parameters
+
+`BasicJsonType`
+: a specialization of [`basic_json`](../basic_json/index.md)
+
+## Member types
+
+- [**number_integer_t**](../basic_json/number_integer_t.md) - `BasicJsonType`'s type for numbers (integer)
+- [**number_unsigned_t**](../basic_json/number_unsigned_t.md) - `BasicJsonType`'s type for numbers (unsigned)
+- [**number_float_t**](../basic_json/number_float_t.md) - `BasicJsonType`'s type for numbers (floating-point)
+- [**string_t**](../basic_json/string_t.md) - `BasicJsonType`'s type for strings
+- [**binary_t**](../basic_json/binary_t.md) - `BasicJsonType`'s type for binary arrays
+
+## Member functions
+
+- [**binary**](binary.md) (_virtual_) - a binary value was read
+- [**boolean**](boolean.md) (_virtual_) - a boolean value was read
+- [**end_array**](end_array.md) (_virtual_) - the end of an array was read
+- [**end_object**](end_object.md) (_virtual_) - the end of an object was read
+- [**key**](key.md) (_virtual_) - an object key was read
+- [**null**](null.md) (_virtual_) - a null value was read
+- [**number_float**](number_float.md) (_virtual_) - a floating-point number was read
+- [**number_integer**](number_integer.md) (_virtual_) - an integer number was read
+- [**number_unsigned**](number_unsigned.md) (_virtual_) - an unsigned integer number was read
+- [**parse_error**](parse_error.md) (_virtual_) - a parse error occurred
+- [**start_array**](start_array.md) (_virtual_) - the beginning of an array was read
+- [**start_object**](start_object.md) (_virtual_) - the beginning of an object was read
+- [**string**](string.md) (_virtual_) - a string value was read
+
+## Version history
+
+- Added in version 3.2.0.
+- Support for binary values (`binary_t`, `binary`) added in version 3.8.0.
diff --git a/doc/mkdocs/docs/api/json_sax/key.md b/doc/mkdocs/docs/api/json_sax/key.md
new file mode 100644
index 0000000..5e79272
--- /dev/null
+++ b/doc/mkdocs/docs/api/json_sax/key.md
@@ -0,0 +1,24 @@
+# <small>nlohmann::json_sax::</small>key
+
+```cpp
+virtual bool key(string_t& val) = 0;
+```
+
+An object key was read.
+
+## Parameters
+
+`val` (in)
+: object key
+
+## Return value
+
+Whether parsing should proceed.
+
+## Notes
+
+It is safe to move the passed object key value.
+
+## Version history
+
+- Added in version 3.2.0.
diff --git a/doc/mkdocs/docs/api/json_sax/null.md b/doc/mkdocs/docs/api/json_sax/null.md
new file mode 100644
index 0000000..bcbb4a3
--- /dev/null
+++ b/doc/mkdocs/docs/api/json_sax/null.md
@@ -0,0 +1,15 @@
+# <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.
diff --git a/doc/mkdocs/docs/api/json_sax/number_float.md b/doc/mkdocs/docs/api/json_sax/number_float.md
new file mode 100644
index 0000000..9419328
--- /dev/null
+++ b/doc/mkdocs/docs/api/json_sax/number_float.md
@@ -0,0 +1,23 @@
+# <small>nlohmann::json_sax::</small>number_float
+
+```cpp
+virtual bool number_float(number_float_t val, const string_t& s) = 0;
+```
+
+A floating-point number was read.
+
+## Parameters
+
+`val` (in)
+: floating-point value
+
+`s` (in)
+: string representation of the original input
+
+## Return value
+
+Whether parsing should proceed.
+
+## Version history
+
+- Added in version 3.2.0.
diff --git a/doc/mkdocs/docs/api/json_sax/number_integer.md b/doc/mkdocs/docs/api/json_sax/number_integer.md
new file mode 100644
index 0000000..00ff2ea
--- /dev/null
+++ b/doc/mkdocs/docs/api/json_sax/number_integer.md
@@ -0,0 +1,20 @@
+# <small>nlohmann::json_sax::</small>number_integer
+
+```cpp
+virtual bool number_integer(number_integer_t val) = 0;
+```
+
+An integer number was read.
+
+## Parameters
+
+`val` (in)
+: integer value
+
+## Return value
+
+Whether parsing should proceed.
+
+## Version history
+
+- Added in version 3.2.0.
diff --git a/doc/mkdocs/docs/api/json_sax/number_unsigned.md b/doc/mkdocs/docs/api/json_sax/number_unsigned.md
new file mode 100644
index 0000000..66d0bda
--- /dev/null
+++ b/doc/mkdocs/docs/api/json_sax/number_unsigned.md
@@ -0,0 +1,20 @@
+# <small>nlohmann::json_sax::</small>number_unsigned
+
+```cpp
+virtual bool number_unsigned(number_unsigned_t val) = 0;
+```
+
+An unsigned integer number was read.
+
+## Parameters
+
+`val` (in)
+: unsigned integer value
+
+## Return value
+
+Whether parsing should proceed.
+
+## Version history
+
+- Added in version 3.2.0.
diff --git a/doc/mkdocs/docs/api/json_sax/parse_error.md b/doc/mkdocs/docs/api/json_sax/parse_error.md
new file mode 100644
index 0000000..00f1aa9
--- /dev/null
+++ b/doc/mkdocs/docs/api/json_sax/parse_error.md
@@ -0,0 +1,28 @@
+# <small>nlohmann::json_sax::</small>parse_error
+
+```cpp
+virtual bool parse_error(std::size_t position,
+ const std::string& last_token,
+ const detail::exception& ex) = 0;
+```
+
+A parse error occurred.
+
+## Parameters
+
+`position` (in)
+: the position in the input where the error occurs
+
+`last_token` (in)
+: the last read token
+
+`ex` (in)
+: an exception object describing the error
+
+## Return value
+
+Whether parsing should proceed (**must return `#!cpp false`**).
+
+## Version history
+
+- Added in version 3.2.0.
diff --git a/doc/mkdocs/docs/api/json_sax/start_array.md b/doc/mkdocs/docs/api/json_sax/start_array.md
new file mode 100644
index 0000000..d10a6e5
--- /dev/null
+++ b/doc/mkdocs/docs/api/json_sax/start_array.md
@@ -0,0 +1,24 @@
+# <small>nlohmann::json_sax::</small>start_array
+
+```cpp
+virtual bool start_array(std::size_t elements) = 0;
+```
+
+The beginning of an array was read.
+
+## Parameters
+
+`elements` (in)
+: number of object elements or `#!cpp -1` if unknown
+
+## Return value
+
+Whether parsing should proceed.
+
+## Notes
+
+Binary formats may report the number of elements.
+
+## Version history
+
+- Added in version 3.2.0.
diff --git a/doc/mkdocs/docs/api/json_sax/start_object.md b/doc/mkdocs/docs/api/json_sax/start_object.md
new file mode 100644
index 0000000..fd90f19
--- /dev/null
+++ b/doc/mkdocs/docs/api/json_sax/start_object.md
@@ -0,0 +1,24 @@
+# <small>nlohmann::json_sax::</small>start_object
+
+```cpp
+virtual bool start_object(std::size_t elements) = 0;
+```
+
+The beginning of an object was read.
+
+## Parameters
+
+`elements` (in)
+: number of object elements or `#!cpp -1` if unknown
+
+## Return value
+
+Whether parsing should proceed.
+
+## Notes
+
+Binary formats may report the number of elements.
+
+## Version history
+
+- Added in version 3.2.0.
diff --git a/doc/mkdocs/docs/api/json_sax/string.md b/doc/mkdocs/docs/api/json_sax/string.md
new file mode 100644
index 0000000..113fe13
--- /dev/null
+++ b/doc/mkdocs/docs/api/json_sax/string.md
@@ -0,0 +1,24 @@
+# <small>nlohmann::json_sax::</small>string
+
+```cpp
+virtual bool string(string_t& val) = 0;
+```
+
+A string value was read.
+
+## Parameters
+
+`val` (in)
+: string value
+
+## Return value
+
+Whether parsing should proceed.
+
+## Notes
+
+It is safe to move the passed string value.
+
+## Version history
+
+- Added in version 3.2.0.
diff --git a/doc/mkdocs/docs/api/macros/index.md b/doc/mkdocs/docs/api/macros/index.md
new file mode 100644
index 0000000..9c390d5
--- /dev/null
+++ b/doc/mkdocs/docs/api/macros/index.md
@@ -0,0 +1,18 @@
+# Macros
+
+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`
diff --git a/doc/mkdocs/docs/api/macros/json_assert.md b/doc/mkdocs/docs/api/macros/json_assert.md
new file mode 100644
index 0000000..63d4ae0
--- /dev/null
+++ b/doc/mkdocs/docs/api/macros/json_assert.md
@@ -0,0 +1,11 @@
+# JSON_ASSERT(x)
+
+```cpp
+JSON_ASSERT(x)
+```
+
+## Default implementation
+
+```cpp
+assert(x);
+```
diff --git a/doc/mkdocs/docs/api/ordered_json.md b/doc/mkdocs/docs/api/ordered_json.md
index 8ce8dfe..8b122f9 100644
--- a/doc/mkdocs/docs/api/ordered_json.md
+++ b/doc/mkdocs/docs/api/ordered_json.md
@@ -1,5 +1,15 @@
-# ordered_json
+# <small>nlohmann::</small>ordered_json
```cpp
-using ordered_json = basic_json<nlohmann::ordered_map>;
+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.
diff --git a/doc/mkdocs/docs/api/ordered_map.md b/doc/mkdocs/docs/api/ordered_map.md
index 1a99b63..74b248f 100644
--- a/doc/mkdocs/docs/api/ordered_map.md
+++ b/doc/mkdocs/docs/api/ordered_map.md
@@ -1,7 +1,70 @@
-# ordered_map
+# <small>nlohmann::</small>ordered_map
```cpp
template<class Key, class T, class IgnoredLess = std::less<Key>,
class Allocator = std::allocator<std::pair<const Key, T>>>
struct ordered_map : std::vector<std::pair<const Key, T>, Allocator>;
```
+
+A minimal map-like container that preserves insertion order for use within [`nlohmann::ordered_json`](ordered_json.md)
+(`nlohmann::basic_json<ordered_map>`).
+
+## Template parameters
+
+`Key`
+: key type
+
+`T`
+: mapped type
+
+`IgnoredLess`
+: comparison function (ignored and only added to ensure compatibility with `#!cpp std::map`)
+
+`Allocator`
+: allocator type
+
+## Member types
+
+- **key_type** - key type (`Key`)
+- **mapped_type** - mapped type (`T`)
+- **Container** - base container type (`#!cpp std::vector<std::pair<const Key, T>, Allocator>`)
+- **iterator**
+- **const_iterator**
+- **size_type**
+- **value_type**
+
+## Member functions
+
+- (constructor)
+- (destructor)
+- **emplace**
+- **operator\[\]**
+- **at**
+- **erase**
+- **count**
+- **find**
+- **insert**
+
+## Examples
+
+??? example
+
+ The example shows the different behavior of `std::map` and `nlohmann::ordered_map`.
+
+ ```cpp
+ --8<-- "examples/ordered_map.cpp"
+ ```
+
+ Output:
+
+ ```json
+ --8<-- "examples/ordered_map.output"
+ ```
+
+## See also
+
+- [ordered_json](ordered_json.md)
+
+## Version history
+
+- Added in version 3.9.0 to implement [`nlohmann::ordered_json`](ordered_json.md).
diff --git a/doc/mkdocs/docs/features/arbitrary_types.md b/doc/mkdocs/docs/features/arbitrary_types.md
index 4234191..fe80dc7 100644
--- a/doc/mkdocs/docs/features/arbitrary_types.md
+++ b/doc/mkdocs/docs/features/arbitrary_types.md
@@ -87,8 +87,8 @@
There are two macros to make your life easier as long as you (1) want to use a JSON object as serialization and (2) want to use the member variable names as object keys in that object:
-- `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(name, member1, member2, ...)` is to be defined inside of the namespace of the class/struct to create code for.
-- `NLOHMANN_DEFINE_TYPE_INTRUSIVE(name, member1, member2, ...)` is to be defined inside of the class/struct to create code for. This macro can also access private members.
+- `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(name, member1, member2, ...)` is to be defined inside the namespace of the class/struct to create code for.
+- `NLOHMANN_DEFINE_TYPE_INTRUSIVE(name, member1, member2, ...)` is to be defined inside the class/struct to create code for. This macro can also access private members.
In both macros, the first parameter is the name of the class/struct, and all remaining parameters name the members.
@@ -197,7 +197,7 @@
return {j.get<int>()};
}
- // Here's the catch! You must provide a to_json method! Otherwise you
+ // Here's the catch! You must provide a to_json method! Otherwise, you
// will not be able to convert move_only_type to json, since you fully
// specialized adl_serializer on that type
static void to_json(json& j, move_only_type t) {
diff --git a/doc/mkdocs/docs/features/binary_formats/bson.md b/doc/mkdocs/docs/features/binary_formats/bson.md
index 0ed2a78..8c7716d 100644
--- a/doc/mkdocs/docs/features/binary_formats/bson.md
+++ b/doc/mkdocs/docs/features/binary_formats/bson.md
@@ -1,6 +1,8 @@
# BSON
-BSON, short for Binary JSON, is a binary-encoded serialization of JSON-like documents. Like JSON, BSON supports the embedding of documents and arrays within other documents and arrays. BSON also contains extensions that allow representation of data types that are not part of the JSON spec. For example, BSON has a Date type and a BinData type.
+BSON, short for Binary JSON, is a binary-encoded serialization of JSON-like documents. Like JSON, BSON supports the
+embedding of documents and arrays within other documents and arrays. BSON also contains extensions that allow
+representation of data types that are not part of the JSON spec. For example, BSON has a Date type and a BinData type.
!!! abstract "References"
@@ -12,21 +14,21 @@
The library uses the following mapping from JSON values types to BSON types:
-JSON value type | value/range | BSON type | marker
---------------- | --------------------------------- | ----------- | ------
-null | `null` | null | 0x0A
-boolean | `true`, `false` | boolean | 0x08
-number_integer | -9223372036854775808..-2147483649 | int64 | 0x12
-number_integer | -2147483648..2147483647 | int32 | 0x10
-number_integer | 2147483648..9223372036854775807 | int64 | 0x12
-number_unsigned | 0..2147483647 | int32 | 0x10
-number_unsigned | 2147483648..9223372036854775807 | int64 | 0x12
-number_unsigned | 9223372036854775808..18446744073709551615| -- | --
-number_float | *any value* | double | 0x01
-string | *any value* | string | 0x02
-array | *any value* | document | 0x04
-object | *any value* | document | 0x03
-binary | *any value* | binary | 0x05
+| JSON value type | value/range | BSON type | marker |
+|-----------------|-------------------------------------------|-----------|--------|
+| null | `null` | null | 0x0A |
+| boolean | `true`, `false` | boolean | 0x08 |
+| number_integer | -9223372036854775808..-2147483649 | int64 | 0x12 |
+| number_integer | -2147483648..2147483647 | int32 | 0x10 |
+| number_integer | 2147483648..9223372036854775807 | int64 | 0x12 |
+| number_unsigned | 0..2147483647 | int32 | 0x10 |
+| number_unsigned | 2147483648..9223372036854775807 | int64 | 0x12 |
+| number_unsigned | 9223372036854775808..18446744073709551615 | -- | -- |
+| number_float | *any value* | double | 0x01 |
+| string | *any value* | string | 0x02 |
+| array | *any value* | document | 0x04 |
+| object | *any value* | document | 0x03 |
+| binary | *any value* | binary | 0x05 |
!!! warning "Incomplete mapping"
@@ -53,28 +55,28 @@
The library maps BSON record types to JSON value types as follows:
-BSON type | BSON marker byte | JSON value type
---------------- | ---------------- | ---------------------------
-double | 0x01 | number_float
-string | 0x02 | string
-document | 0x03 | object
-array | 0x04 | array
-binary | 0x05 | binary
-undefined | 0x06 | *unsupported*
-ObjectId | 0x07 | *unsupported*
-boolean | 0x08 | boolean
-UTC Date-Time | 0x09 | *unsupported*
-null | 0x0A | null
-Regular Expr. | 0x0B | *unsupported*
-DB Pointer | 0x0C | *unsupported*
-JavaScript Code | 0x0D | *unsupported*
-Symbol | 0x0E | *unsupported*
-JavaScript Code | 0x0F | *unsupported*
-int32 | 0x10 | number_integer
-Timestamp | 0x11 | *unsupported*
-128-bit decimal float | 0x13 | *unsupported*
-Max Key | 0x7F | *unsupported*
-Min Key | 0xFF | *unsupported*
+| BSON type | BSON marker byte | JSON value type |
+|-----------------------|------------------|-----------------|
+| double | 0x01 | number_float |
+| string | 0x02 | string |
+| document | 0x03 | object |
+| array | 0x04 | array |
+| binary | 0x05 | binary |
+| undefined | 0x06 | *unsupported* |
+| ObjectId | 0x07 | *unsupported* |
+| boolean | 0x08 | boolean |
+| UTC Date-Time | 0x09 | *unsupported* |
+| null | 0x0A | null |
+| Regular Expr. | 0x0B | *unsupported* |
+| DB Pointer | 0x0C | *unsupported* |
+| JavaScript Code | 0x0D | *unsupported* |
+| Symbol | 0x0E | *unsupported* |
+| JavaScript Code | 0x0F | *unsupported* |
+| int32 | 0x10 | number_integer |
+| Timestamp | 0x11 | *unsupported* |
+| 128-bit decimal float | 0x13 | *unsupported* |
+| Max Key | 0x7F | *unsupported* |
+| Min Key | 0xFF | *unsupported* |
!!! warning "Incomplete mapping"
diff --git a/doc/mkdocs/docs/features/binary_formats/cbor.md b/doc/mkdocs/docs/features/binary_formats/cbor.md
index a7a8fc0..280bf57 100644
--- a/doc/mkdocs/docs/features/binary_formats/cbor.md
+++ b/doc/mkdocs/docs/features/binary_formats/cbor.md
@@ -1,6 +1,7 @@
# CBOR
-The Concise Binary Object Representation (CBOR) is a data format whose design goals include the possibility of extremely small code size, fairly small message size, and extensibility without the need for version negotiation.
+The Concise Binary Object Representation (CBOR) is a data format whose design goals include the possibility of extremely
+small code size, fairly small message size, and extensibility without the need for version negotiation.
!!! abstract "References"
@@ -12,48 +13,48 @@
The library uses the following mapping from JSON values types to CBOR types according to the CBOR specification (RFC 7049):
-JSON value type | value/range | CBOR type | first byte
---------------- | ------------------------------------------ | ---------------------------------- | ---------------
-null | `null` | Null | 0xF6
-boolean | `true` | True | 0xF5
-boolean | `false` | False | 0xF4
-number_integer | -9223372036854775808..-2147483649 | Negative integer (8 bytes follow) | 0x3B
-number_integer | -2147483648..-32769 | Negative integer (4 bytes follow) | 0x3A
-number_integer | -32768..-129 | Negative integer (2 bytes follow) | 0x39
-number_integer | -128..-25 | Negative integer (1 byte follow) | 0x38
-number_integer | -24..-1 | Negative integer | 0x20..0x37
-number_integer | 0..23 | Integer | 0x00..0x17
-number_integer | 24..255 | Unsigned integer (1 byte follow) | 0x18
-number_integer | 256..65535 | Unsigned integer (2 bytes follow) | 0x19
-number_integer | 65536..4294967295 | Unsigned integer (4 bytes follow) | 0x1A
-number_integer | 4294967296..18446744073709551615 | Unsigned integer (8 bytes follow) | 0x1B
-number_unsigned | 0..23 | Integer | 0x00..0x17
-number_unsigned | 24..255 | Unsigned integer (1 byte follow) | 0x18
-number_unsigned | 256..65535 | Unsigned integer (2 bytes follow) | 0x19
-number_unsigned | 65536..4294967295 | Unsigned integer (4 bytes follow) | 0x1A
-number_unsigned | 4294967296..18446744073709551615 | Unsigned integer (8 bytes follow) | 0x1B
-number_float | *any value representable by a float* | Single-Precision Float | 0xFA
-number_float | *any value NOT representable by a float* | Double-Precision Float | 0xFB
-string | *length*: 0..23 | UTF-8 string | 0x60..0x77
-string | *length*: 23..255 | UTF-8 string (1 byte follow) | 0x78
-string | *length*: 256..65535 | UTF-8 string (2 bytes follow) | 0x79
-string | *length*: 65536..4294967295 | UTF-8 string (4 bytes follow) | 0x7A
-string | *length*: 4294967296..18446744073709551615 | UTF-8 string (8 bytes follow) | 0x7B
-array | *size*: 0..23 | array | 0x80..0x97
-array | *size*: 23..255 | array (1 byte follow) | 0x98
-array | *size*: 256..65535 | array (2 bytes follow) | 0x99
-array | *size*: 65536..4294967295 | array (4 bytes follow) | 0x9A
-array | *size*: 4294967296..18446744073709551615 | array (8 bytes follow) | 0x9B
-object | *size*: 0..23 | map | 0xA0..0xB7
-object | *size*: 23..255 | map (1 byte follow) | 0xB8
-object | *size*: 256..65535 | map (2 bytes follow) | 0xB9
-object | *size*: 65536..4294967295 | map (4 bytes follow) | 0xBA
-object | *size*: 4294967296..18446744073709551615 | map (8 bytes follow) | 0xBB
-binary | *size*: 0..23 | byte string | 0x40..0x57
-binary | *size*: 23..255 | byte string (1 byte follow) | 0x58
-binary | *size*: 256..65535 | byte string (2 bytes follow) | 0x59
-binary | *size*: 65536..4294967295 | byte string (4 bytes follow) | 0x5A
-binary | *size*: 4294967296..18446744073709551615 | byte string (8 bytes follow) | 0x5B
+| JSON value type | value/range | CBOR type | first byte |
+|-----------------|--------------------------------------------|-----------------------------------|------------|
+| null | `null` | Null | 0xF6 |
+| boolean | `true` | True | 0xF5 |
+| boolean | `false` | False | 0xF4 |
+| number_integer | -9223372036854775808..-2147483649 | Negative integer (8 bytes follow) | 0x3B |
+| number_integer | -2147483648..-32769 | Negative integer (4 bytes follow) | 0x3A |
+| number_integer | -32768..-129 | Negative integer (2 bytes follow) | 0x39 |
+| number_integer | -128..-25 | Negative integer (1 byte follow) | 0x38 |
+| number_integer | -24..-1 | Negative integer | 0x20..0x37 |
+| number_integer | 0..23 | Integer | 0x00..0x17 |
+| number_integer | 24..255 | Unsigned integer (1 byte follow) | 0x18 |
+| number_integer | 256..65535 | Unsigned integer (2 bytes follow) | 0x19 |
+| number_integer | 65536..4294967295 | Unsigned integer (4 bytes follow) | 0x1A |
+| number_integer | 4294967296..18446744073709551615 | Unsigned integer (8 bytes follow) | 0x1B |
+| number_unsigned | 0..23 | Integer | 0x00..0x17 |
+| number_unsigned | 24..255 | Unsigned integer (1 byte follow) | 0x18 |
+| number_unsigned | 256..65535 | Unsigned integer (2 bytes follow) | 0x19 |
+| number_unsigned | 65536..4294967295 | Unsigned integer (4 bytes follow) | 0x1A |
+| number_unsigned | 4294967296..18446744073709551615 | Unsigned integer (8 bytes follow) | 0x1B |
+| number_float | *any value representable by a float* | Single-Precision Float | 0xFA |
+| number_float | *any value NOT representable by a float* | Double-Precision Float | 0xFB |
+| string | *length*: 0..23 | UTF-8 string | 0x60..0x77 |
+| string | *length*: 23..255 | UTF-8 string (1 byte follow) | 0x78 |
+| string | *length*: 256..65535 | UTF-8 string (2 bytes follow) | 0x79 |
+| string | *length*: 65536..4294967295 | UTF-8 string (4 bytes follow) | 0x7A |
+| string | *length*: 4294967296..18446744073709551615 | UTF-8 string (8 bytes follow) | 0x7B |
+| array | *size*: 0..23 | array | 0x80..0x97 |
+| array | *size*: 23..255 | array (1 byte follow) | 0x98 |
+| array | *size*: 256..65535 | array (2 bytes follow) | 0x99 |
+| array | *size*: 65536..4294967295 | array (4 bytes follow) | 0x9A |
+| array | *size*: 4294967296..18446744073709551615 | array (8 bytes follow) | 0x9B |
+| object | *size*: 0..23 | map | 0xA0..0xB7 |
+| object | *size*: 23..255 | map (1 byte follow) | 0xB8 |
+| object | *size*: 256..65535 | map (2 bytes follow) | 0xB9 |
+| object | *size*: 65536..4294967295 | map (4 bytes follow) | 0xBA |
+| object | *size*: 4294967296..18446744073709551615 | map (8 bytes follow) | 0xBB |
+| binary | *size*: 0..23 | byte string | 0x40..0x57 |
+| binary | *size*: 23..255 | byte string (1 byte follow) | 0x58 |
+| binary | *size*: 256..65535 | byte string (2 bytes follow) | 0x59 |
+| binary | *size*: 65536..4294967295 | byte string (4 bytes follow) | 0x5A |
+| binary | *size*: 4294967296..18446744073709551615 | byte string (8 bytes follow) | 0x5B |
Binary values with subtype are mapped to tagged values (0xD8..0xDB) depending on the subtype, followed by a byte string,
see "binary" cells in the table above.
@@ -104,47 +105,47 @@
The library maps CBOR types to JSON value types as follows:
-CBOR type | JSON value type | first byte
----------------------- | --------------- | ----------
-Integer | number_unsigned | 0x00..0x17
-Unsigned integer | number_unsigned | 0x18
-Unsigned integer | number_unsigned | 0x19
-Unsigned integer | number_unsigned | 0x1A
-Unsigned integer | number_unsigned | 0x1B
-Negative integer | number_integer | 0x20..0x37
-Negative integer | number_integer | 0x38
-Negative integer | number_integer | 0x39
-Negative integer | number_integer | 0x3A
-Negative integer | number_integer | 0x3B
-Byte string | binary | 0x40..0x57
-Byte string | binary | 0x58
-Byte string | binary | 0x59
-Byte string | binary | 0x5A
-Byte string | binary | 0x5B
-UTF-8 string | string | 0x60..0x77
-UTF-8 string | string | 0x78
-UTF-8 string | string | 0x79
-UTF-8 string | string | 0x7A
-UTF-8 string | string | 0x7B
-UTF-8 string | string | 0x7F
-array | array | 0x80..0x97
-array | array | 0x98
-array | array | 0x99
-array | array | 0x9A
-array | array | 0x9B
-array | array | 0x9F
-map | object | 0xA0..0xB7
-map | object | 0xB8
-map | object | 0xB9
-map | object | 0xBA
-map | object | 0xBB
-map | object | 0xBF
-False | `false` | 0xF4
-True | `true` | 0xF5
-Null | `null` | 0xF6
-Half-Precision Float | number_float | 0xF9
-Single-Precision Float | number_float | 0xFA
-Double-Precision Float | number_float | 0xFB
+| CBOR type | JSON value type | first byte |
+|------------------------|-----------------|------------|
+| Integer | number_unsigned | 0x00..0x17 |
+| Unsigned integer | number_unsigned | 0x18 |
+| Unsigned integer | number_unsigned | 0x19 |
+| Unsigned integer | number_unsigned | 0x1A |
+| Unsigned integer | number_unsigned | 0x1B |
+| Negative integer | number_integer | 0x20..0x37 |
+| Negative integer | number_integer | 0x38 |
+| Negative integer | number_integer | 0x39 |
+| Negative integer | number_integer | 0x3A |
+| Negative integer | number_integer | 0x3B |
+| Byte string | binary | 0x40..0x57 |
+| Byte string | binary | 0x58 |
+| Byte string | binary | 0x59 |
+| Byte string | binary | 0x5A |
+| Byte string | binary | 0x5B |
+| UTF-8 string | string | 0x60..0x77 |
+| UTF-8 string | string | 0x78 |
+| UTF-8 string | string | 0x79 |
+| UTF-8 string | string | 0x7A |
+| UTF-8 string | string | 0x7B |
+| UTF-8 string | string | 0x7F |
+| array | array | 0x80..0x97 |
+| array | array | 0x98 |
+| array | array | 0x99 |
+| array | array | 0x9A |
+| array | array | 0x9B |
+| array | array | 0x9F |
+| map | object | 0xA0..0xB7 |
+| map | object | 0xB8 |
+| map | object | 0xB9 |
+| map | object | 0xBA |
+| map | object | 0xBB |
+| map | object | 0xBF |
+| False | `false` | 0xF4 |
+| True | `true` | 0xF5 |
+| Null | `null` | 0xF6 |
+| Half-Precision Float | number_float | 0xF9 |
+| Single-Precision Float | number_float | 0xFA |
+| Double-Precision Float | number_float | 0xFB |
!!! warning "Incomplete mapping"
diff --git a/doc/mkdocs/docs/features/binary_formats/index.md b/doc/mkdocs/docs/features/binary_formats/index.md
index 279009d..3a969a5 100644
--- a/doc/mkdocs/docs/features/binary_formats/index.md
+++ b/doc/mkdocs/docs/features/binary_formats/index.md
@@ -1,4 +1,4 @@
-# Overview
+# Binary Formats
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
@@ -14,7 +14,7 @@
### Completeness
| Format | Serialization | Deserialization |
-| ----------- |---------------------------------------------- | -------------------------------------------- |
+|-------------|-----------------------------------------------|----------------------------------------------|
| BSON | incomplete: top-level value must be an object | incomplete, but all JSON types are supported |
| CBOR | complete | incomplete, but all JSON types are supported |
| MessagePack | complete | complete |
@@ -23,7 +23,7 @@
### Binary values
| Format | Binary values | Binary subtypes |
-| ----------- | ------------- | --------------- |
+|-------------|---------------|-----------------|
| BSON | supported | supported |
| CBOR | supported | supported |
| MessagePack | supported | supported |
@@ -34,7 +34,7 @@
### Sizes
| Format | canada.json | twitter.json | citm_catalog.json | jeopardy.json |
-| ------------------ | ----------- | ------------ | ----------------- | ------------- |
+|--------------------|-------------|--------------|-------------------|---------------|
| BSON | 85,8 % | 95,2 % | 95,8 % | 106,7 % |
| CBOR | 50,5 % | 86,3 % | 68,4 % | 88,0 % |
| MessagePack | 50,6 % | 86,0 % | 68,5 % | 87,9 % |
diff --git a/doc/mkdocs/docs/features/binary_formats/messagepack.md b/doc/mkdocs/docs/features/binary_formats/messagepack.md
index 3e041bb..b0139b4 100644
--- a/doc/mkdocs/docs/features/binary_formats/messagepack.md
+++ b/doc/mkdocs/docs/features/binary_formats/messagepack.md
@@ -11,41 +11,41 @@
The library uses the following mapping from JSON values types to MessagePack types according to the MessagePack specification:
-JSON value type | value/range | MessagePack type | first byte
---------------- | --------------------------------- | ---------------- | ----------
-null | `null` | nil | 0xC0
-boolean | `true` | true | 0xC3
-boolean | `false` | false | 0xC2
-number_integer | -9223372036854775808..-2147483649 | int64 | 0xD3
-number_integer | -2147483648..-32769 | int32 | 0xD2
-number_integer | -32768..-129 | int16 | 0xD1
-number_integer | -128..-33 | int8 | 0xD0
-number_integer | -32..-1 | negative fixint | 0xE0..0xFF
-number_integer | 0..127 | positive fixint | 0x00..0x7F
-number_integer | 128..255 | uint 8 | 0xCC
-number_integer | 256..65535 | uint 16 | 0xCD
-number_integer | 65536..4294967295 | uint 32 | 0xCE
-number_integer | 4294967296..18446744073709551615 | uint 64 | 0xCF
-number_unsigned | 0..127 | positive fixint | 0x00..0x7F
-number_unsigned | 128..255 | uint 8 | 0xCC
-number_unsigned | 256..65535 | uint 16 | 0xCD
-number_unsigned | 65536..4294967295 | uint 32 | 0xCE
-number_unsigned | 4294967296..18446744073709551615 | uint 64 | 0xCF
-number_float | *any value representable by a float* | float 32 | 0xCA
-number_float | *any value NOT representable by a float* | float 64 | 0xCB
-string | *length*: 0..31 | fixstr | 0xA0..0xBF
-string | *length*: 32..255 | str 8 | 0xD9
-string | *length*: 256..65535 | str 16 | 0xDA
-string | *length*: 65536..4294967295 | str 32 | 0xDB
-array | *size*: 0..15 | fixarray | 0x90..0x9F
-array | *size*: 16..65535 | array 16 | 0xDC
-array | *size*: 65536..4294967295 | array 32 | 0xDD
-object | *size*: 0..15 | fix map | 0x80..0x8F
-object | *size*: 16..65535 | map 16 | 0xDE
-object | *size*: 65536..4294967295 | map 32 | 0xDF
-binary | *size*: 0..255 | bin 8 | 0xC4
-binary | *size*: 256..65535 | bin 16 | 0xC5
-binary | *size*: 65536..4294967295 | bin 32 | 0xC6
+| JSON value type | value/range | MessagePack type | first byte |
+|-----------------|------------------------------------------|------------------|------------|
+| null | `null` | nil | 0xC0 |
+| boolean | `true` | true | 0xC3 |
+| boolean | `false` | false | 0xC2 |
+| number_integer | -9223372036854775808..-2147483649 | int64 | 0xD3 |
+| number_integer | -2147483648..-32769 | int32 | 0xD2 |
+| number_integer | -32768..-129 | int16 | 0xD1 |
+| number_integer | -128..-33 | int8 | 0xD0 |
+| number_integer | -32..-1 | negative fixint | 0xE0..0xFF |
+| number_integer | 0..127 | positive fixint | 0x00..0x7F |
+| number_integer | 128..255 | uint 8 | 0xCC |
+| number_integer | 256..65535 | uint 16 | 0xCD |
+| number_integer | 65536..4294967295 | uint 32 | 0xCE |
+| number_integer | 4294967296..18446744073709551615 | uint 64 | 0xCF |
+| number_unsigned | 0..127 | positive fixint | 0x00..0x7F |
+| number_unsigned | 128..255 | uint 8 | 0xCC |
+| number_unsigned | 256..65535 | uint 16 | 0xCD |
+| number_unsigned | 65536..4294967295 | uint 32 | 0xCE |
+| number_unsigned | 4294967296..18446744073709551615 | uint 64 | 0xCF |
+| number_float | *any value representable by a float* | float 32 | 0xCA |
+| number_float | *any value NOT representable by a float* | float 64 | 0xCB |
+| string | *length*: 0..31 | fixstr | 0xA0..0xBF |
+| string | *length*: 32..255 | str 8 | 0xD9 |
+| string | *length*: 256..65535 | str 16 | 0xDA |
+| string | *length*: 65536..4294967295 | str 32 | 0xDB |
+| array | *size*: 0..15 | fixarray | 0x90..0x9F |
+| array | *size*: 16..65535 | array 16 | 0xDC |
+| array | *size*: 65536..4294967295 | array 32 | 0xDD |
+| object | *size*: 0..15 | fix map | 0x80..0x8F |
+| object | *size*: 16..65535 | map 16 | 0xDE |
+| object | *size*: 65536..4294967295 | map 32 | 0xDF |
+| binary | *size*: 0..255 | bin 8 | 0xC4 |
+| binary | *size*: 256..65535 | bin 16 | 0xC5 |
+| binary | *size*: 65536..4294967295 | bin 32 | 0xC6 |
!!! success "Complete mapping"
@@ -82,44 +82,44 @@
The library maps MessagePack types to JSON value types as follows:
-MessagePack type | JSON value type | first byte
----------------- | --------------- | ----------
-positive fixint | number_unsigned | 0x00..0x7F
-fixmap | object | 0x80..0x8F
-fixarray | array | 0x90..0x9F
-fixstr | string | 0xA0..0xBF
-nil | `null` | 0xC0
-false | `false` | 0xC2
-true | `true` | 0xC3
-float 32 | number_float | 0xCA
-float 64 | number_float | 0xCB
-uint 8 | number_unsigned | 0xCC
-uint 16 | number_unsigned | 0xCD
-uint 32 | number_unsigned | 0xCE
-uint 64 | number_unsigned | 0xCF
-int 8 | number_integer | 0xD0
-int 16 | number_integer | 0xD1
-int 32 | number_integer | 0xD2
-int 64 | number_integer | 0xD3
-str 8 | string | 0xD9
-str 16 | string | 0xDA
-str 32 | string | 0xDB
-array 16 | array | 0xDC
-array 32 | array | 0xDD
-map 16 | object | 0xDE
-map 32 | object | 0xDF
-bin 8 | binary | 0xC4
-bin 16 | binary | 0xC5
-bin 32 | binary | 0xC6
-ext 8 | binary | 0xC7
-ext 16 | binary | 0xC8
-ext 32 | binary | 0xC9
-fixext 1 | binary | 0xD4
-fixext 2 | binary | 0xD5
-fixext 4 | binary | 0xD6
-fixext 8 | binary | 0xD7
-fixext 16 | binary | 0xD8
-negative fixint | number_integer | 0xE0-0xFF
+| MessagePack type | JSON value type | first byte |
+|------------------|-----------------|------------|
+| positive fixint | number_unsigned | 0x00..0x7F |
+| fixmap | object | 0x80..0x8F |
+| fixarray | array | 0x90..0x9F |
+| fixstr | string | 0xA0..0xBF |
+| nil | `null` | 0xC0 |
+| false | `false` | 0xC2 |
+| true | `true` | 0xC3 |
+| float 32 | number_float | 0xCA |
+| float 64 | number_float | 0xCB |
+| uint 8 | number_unsigned | 0xCC |
+| uint 16 | number_unsigned | 0xCD |
+| uint 32 | number_unsigned | 0xCE |
+| uint 64 | number_unsigned | 0xCF |
+| int 8 | number_integer | 0xD0 |
+| int 16 | number_integer | 0xD1 |
+| int 32 | number_integer | 0xD2 |
+| int 64 | number_integer | 0xD3 |
+| str 8 | string | 0xD9 |
+| str 16 | string | 0xDA |
+| str 32 | string | 0xDB |
+| array 16 | array | 0xDC |
+| array 32 | array | 0xDD |
+| map 16 | object | 0xDE |
+| map 32 | object | 0xDF |
+| bin 8 | binary | 0xC4 |
+| bin 16 | binary | 0xC5 |
+| bin 32 | binary | 0xC6 |
+| ext 8 | binary | 0xC7 |
+| ext 16 | binary | 0xC8 |
+| ext 32 | binary | 0xC9 |
+| fixext 1 | binary | 0xD4 |
+| fixext 2 | binary | 0xD5 |
+| fixext 4 | binary | 0xD6 |
+| fixext 8 | binary | 0xD7 |
+| fixext 16 | binary | 0xD8 |
+| negative fixint | number_integer | 0xE0-0xFF |
!!! info
diff --git a/doc/mkdocs/docs/features/binary_formats/ubjson.md b/doc/mkdocs/docs/features/binary_formats/ubjson.md
index 050b4ec..509d9f5 100644
--- a/doc/mkdocs/docs/features/binary_formats/ubjson.md
+++ b/doc/mkdocs/docs/features/binary_formats/ubjson.md
@@ -10,29 +10,29 @@
The library uses the following mapping from JSON values types to UBJSON types according to the UBJSON specification:
-JSON value type | value/range | UBJSON type | marker
---------------- | --------------------------------- | ----------- | ------
-null | `null` | null | `Z`
-boolean | `true` | true | `T`
-boolean | `false` | false | `F`
-number_integer | -9223372036854775808..-2147483649 | int64 | `L`
-number_integer | -2147483648..-32769 | int32 | `l`
-number_integer | -32768..-129 | int16 | `I`
-number_integer | -128..127 | int8 | `i`
-number_integer | 128..255 | uint8 | `U`
-number_integer | 256..32767 | int16 | `I`
-number_integer | 32768..2147483647 | int32 | `l`
-number_integer | 2147483648..9223372036854775807 | int64 | `L`
-number_unsigned | 0..127 | int8 | `i`
-number_unsigned | 128..255 | uint8 | `U`
-number_unsigned | 256..32767 | int16 | `I`
-number_unsigned | 32768..2147483647 | int32 | `l`
-number_unsigned | 2147483648..9223372036854775807 | int64 | `L`
-number_unsigned | 2147483649..18446744073709551615 | high-precision | `H`
-number_float | *any value* | float64 | `D`
-string | *with shortest length indicator* | string | `S`
-array | *see notes on optimized format* | array | `[`
-object | *see notes on optimized format* | map | `{`
+| JSON value type | value/range | UBJSON type | marker |
+|-----------------|-----------------------------------|----------------|--------|
+| null | `null` | null | `Z` |
+| boolean | `true` | true | `T` |
+| boolean | `false` | false | `F` |
+| number_integer | -9223372036854775808..-2147483649 | int64 | `L` |
+| number_integer | -2147483648..-32769 | int32 | `l` |
+| number_integer | -32768..-129 | int16 | `I` |
+| number_integer | -128..127 | int8 | `i` |
+| number_integer | 128..255 | uint8 | `U` |
+| number_integer | 256..32767 | int16 | `I` |
+| number_integer | 32768..2147483647 | int32 | `l` |
+| number_integer | 2147483648..9223372036854775807 | int64 | `L` |
+| number_unsigned | 0..127 | int8 | `i` |
+| number_unsigned | 128..255 | uint8 | `U` |
+| number_unsigned | 256..32767 | int16 | `I` |
+| number_unsigned | 32768..2147483647 | int32 | `l` |
+| number_unsigned | 2147483648..9223372036854775807 | int64 | `L` |
+| number_unsigned | 2147483649..18446744073709551615 | high-precision | `H` |
+| number_float | *any value* | float64 | `D` |
+| string | *with shortest length indicator* | string | `S` |
+| array | *see notes on optimized format* | array | `[` |
+| object | *see notes on optimized format* | map | `{` |
!!! success "Complete mapping"
@@ -97,23 +97,23 @@
The library maps UBJSON types to JSON value types as follows:
-UBJSON type | JSON value type | marker
------------ | --------------------------------------- | ------
-no-op | *no value, next value is read* | `N`
-null | `null` | `Z`
-false | `false` | `F`
-true | `true` | `T`
-float32 | number_float | `d`
-float64 | number_float | `D`
-uint8 | number_unsigned | `U`
-int8 | number_integer | `i`
-int16 | number_integer | `I`
-int32 | number_integer | `l`
-int64 | number_integer | `L`
-string | string | `S`
-char | string | `C`
-array | array (optimized values are supported) | `[`
-object | object (optimized values are supported) | `{`
+| UBJSON type | JSON value type | marker |
+|-------------|-----------------------------------------|--------|
+| no-op | *no value, next value is read* | `N` |
+| null | `null` | `Z` |
+| false | `false` | `F` |
+| true | `true` | `T` |
+| float32 | number_float | `d` |
+| float64 | number_float | `D` |
+| uint8 | number_unsigned | `U` |
+| int8 | number_integer | `i` |
+| int16 | number_integer | `I` |
+| int32 | number_integer | `l` |
+| int64 | number_integer | `L` |
+| string | string | `S` |
+| char | string | `C` |
+| array | array (optimized values are supported) | `[` |
+| object | object (optimized values are supported) | `{` |
!!! success "Complete mapping"
diff --git a/doc/mkdocs/docs/features/binary_values.md b/doc/mkdocs/docs/features/binary_values.md
index 66e7216..c58834c 100644
--- a/doc/mkdocs/docs/features/binary_values.md
+++ b/doc/mkdocs/docs/features/binary_values.md
@@ -198,7 +198,7 @@
### MessagePack
-[MessagePack](binary_formats/messagepack.md) supports binary values and subtypes. If a subtype is given, the ext family is used. The library will choose the smallest representation among fixext1, fixext2, fixext4, fixext8, ext8, ext16, and ext32. The subtype is then added as singed 8-bit integer.
+[MessagePack](binary_formats/messagepack.md) supports binary values and subtypes. If a subtype is given, the ext family is used. The library will choose the smallest representation among fixext1, fixext2, fixext4, fixext8, ext8, ext16, and ext32. The subtype is then added as signed 8-bit integer.
If no subtype is given, the bin family (bin8, bin16, bin32) is used.
@@ -282,7 +282,7 @@
0x23 0x69 0x01 // '#' i 1 number of object elements
0x69 0x06 // i 6 (length of the key)
0x62 0x69 0x6E 0x61 0x72 0x79 // "binary"
- 0x24 0x55 // '$' 'U' type of the array elements: unsinged integers
+ 0x24 0x55 // '$' 'U' type of the array elements: unsigned integers
0x23 0x69 0x04 // '#' i 4 number of array elements
0xCA 0xFE 0xBA 0xBE // content
```
diff --git a/doc/mkdocs/docs/features/comments.md b/doc/mkdocs/docs/features/comments.md
index f82029e..c5874c9 100644
--- a/doc/mkdocs/docs/features/comments.md
+++ b/doc/mkdocs/docs/features/comments.md
@@ -25,7 +25,7 @@
}
```
- When calling `parse` without additional argument, a parse error exception is thrown. If `skip_comments` is set to `#! true`, the comments are skipped during parsing:
+ When calling `parse` without additional argument, a parse error exception is thrown. If `ignore_comments` is set to `#! true`, the comments are ignored during parsing:
```cpp
#include <iostream>
@@ -55,7 +55,7 @@
json j = json::parse(s,
/* callback */ nullptr,
/* allow exceptions */ true,
- /* skip_comments */ true);
+ /* ignore_comments */ true);
std::cout << j.dump(2) << '\n';
}
```
@@ -80,4 +80,4 @@
"Neptune"
]
}
- ```
\ No newline at end of file
+ ```
diff --git a/doc/mkdocs/docs/features/element_access/checked_access.md b/doc/mkdocs/docs/features/element_access/checked_access.md
index 19c7525..fd444be 100644
--- a/doc/mkdocs/docs/features/element_access/checked_access.md
+++ b/doc/mkdocs/docs/features/element_access/checked_access.md
@@ -27,7 +27,7 @@
| `#!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 modify the original value.
+The return value is a reference, so it can be modified by the original value.
??? example
@@ -69,9 +69,9 @@
## 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 |
+| 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 |
+| access to invalid array index | `basic_json::out_of_range` exception is thrown | `basic_json::out_of_range` exception is thrown |
diff --git a/doc/mkdocs/docs/features/element_access/index.md b/doc/mkdocs/docs/features/element_access/index.md
index 1755fe8..0b39547 100644
--- a/doc/mkdocs/docs/features/element_access/index.md
+++ b/doc/mkdocs/docs/features/element_access/index.md
@@ -1,4 +1,4 @@
-# Overview
+# Element Access
There are many ways elements in a JSON value can be accessed:
diff --git a/doc/mkdocs/docs/features/element_access/unchecked_access.md b/doc/mkdocs/docs/features/element_access/unchecked_access.md
index fff7f2b..bb72287 100644
--- a/doc/mkdocs/docs/features/element_access/unchecked_access.md
+++ b/doc/mkdocs/docs/features/element_access/unchecked_access.md
@@ -27,7 +27,7 @@
| `#!cpp j["hobbies"][0]` | `#!json "hiking"` |
| `#!cpp j["hobbies"][1]` | `#!json "reading"` |
-The return value is a reference, so it can be modify the original value. In case the passed object key is non-existing, a `#!json null` value is inserted which can be immediately be overwritten.
+The return value is a reference, so it can modify the original value. In case the passed object key is non-existing, a `#!json null` value is inserted which can be immediately be overwritten.
??? example
@@ -94,9 +94,9 @@
## 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 | reference to newly inserted `#!json null` value is returned | **undefined behavior**; assertion in debug mode |
-| access to invalid array index | reference to newly inserted `#!json null` value is returned; any index between previous maximal index and passed index are filled with `#!json null` | **undefined behavior**; assertion in debug mode |
+| 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 | reference to newly inserted `#!json null` value is returned | **undefined behavior**; assertion in debug mode |
+| access to invalid array index | reference to newly inserted `#!json null` value is returned; any index between previous maximal index and passed index are filled with `#!json null` | **undefined behavior**; assertion in debug mode |
diff --git a/doc/mkdocs/docs/features/enum_conversion.md b/doc/mkdocs/docs/features/enum_conversion.md
index 1c1bb80..8f474a7 100644
--- a/doc/mkdocs/docs/features/enum_conversion.md
+++ b/doc/mkdocs/docs/features/enum_conversion.md
@@ -1,6 +1,8 @@
# Specializing enum conversion
-By default, enum values are serialized to JSON as integers. In some cases this could result in undesired behavior. If an enum is modified or re-ordered after data has been serialized to JSON, the later de-serialized JSON data may be undefined or a different enum value than was originally intended.
+By default, enum values are serialized to JSON as integers. In some cases this could result in undesired behavior. If an
+enum is modified or re-ordered after data has been serialized to JSON, the later de-serialized JSON data may be
+undefined or a different enum value than was originally intended.
It is possible to more precisely specify how a given enum is mapped to and from JSON as shown below:
@@ -22,7 +24,8 @@
})
```
-The `NLOHMANN_JSON_SERIALIZE_ENUM()` macro declares a set of `to_json()` / `from_json()` functions for type `TaskState` while avoiding repetition and boilerplate serialization code.
+The `NLOHMANN_JSON_SERIALIZE_ENUM()` macro declares a set of `to_json()` / `from_json()` functions for type `TaskState`
+while avoiding repetition and boilerplate serialization code.
## Usage
@@ -44,10 +47,13 @@
Just as in [Arbitrary Type Conversions](#arbitrary-types-conversions) above,
-- `NLOHMANN_JSON_SERIALIZE_ENUM()` MUST be declared in your enum type's namespace (which can be the global namespace), or the library will not be able to locate it and it will default to integer serialization.
+- `NLOHMANN_JSON_SERIALIZE_ENUM()` MUST be declared in your enum type's namespace (which can be the global namespace),
+ or the library will not be able to locate it, and it will default to integer serialization.
- It MUST be available (e.g., proper headers must be included) everywhere you use the conversions.
Other Important points:
-- When using `get<ENUM_TYPE>()`, undefined JSON values will default to the first pair specified in your map. Select this default pair carefully.
-- If an enum or JSON value is specified more than once in your map, the first matching occurrence from the top of the map will be returned when converting to or from JSON.
+- 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.
diff --git a/doc/mkdocs/docs/features/iterators.md b/doc/mkdocs/docs/features/iterators.md
index fd9d679..46f28f1 100644
--- a/doc/mkdocs/docs/features/iterators.md
+++ b/doc/mkdocs/docs/features/iterators.md
@@ -66,7 +66,7 @@
### Range-based for loops
-C++11 allows to use range-based for loops to iterate over a container.
+C++11 allows using range-based for loops to iterate over a container.
```cpp
for (auto it : j_object)
@@ -76,7 +76,7 @@
}
```
-For this reason, the `items()` function allows to access `iterator::key()` and `iterator::value()` during range-based for loops. In these loops, a reference to the JSON values is returned, so there is no access to the underlying iterator.
+For this reason, the `items()` function allows accessing `iterator::key()` and `iterator::value()` during range-based for loops. In these loops, a reference to the JSON values is returned, so there is no access to the underlying iterator.
```cpp
for (auto& el : j_object.items())
@@ -85,7 +85,7 @@
}
```
-The items() function also allows to use structured bindings (C++17):
+The items() function also allows using structured bindings (C++17):
```cpp
for (auto& [key, val] : j_object.items())
@@ -100,7 +100,7 @@
!!! warning
- Using `items()` on temporary objects is dangerous. Make sure the object's lifetime exeeds the iteration. See <https://github.com/nlohmann/json/issues/2040> for more information.
+ Using `items()` on temporary objects is dangerous. Make sure the object's lifetime exceeds the iteration. See <https://github.com/nlohmann/json/issues/2040> for more information.
### Reverse iteration order
@@ -151,5 +151,5 @@
## Iterator invalidation
| Operations | invalidated iterators |
-| ---------- | --------------------- |
+|------------|-----------------------|
| `clear` | all |
diff --git a/doc/mkdocs/docs/features/json_patch.md b/doc/mkdocs/docs/features/json_patch.md
index 24cebdd..88c731a 100644
--- a/doc/mkdocs/docs/features/json_patch.md
+++ b/doc/mkdocs/docs/features/json_patch.md
@@ -2,7 +2,9 @@
## Patches
-JSON Patch ([RFC 6902](https://tools.ietf.org/html/rfc6902)) defines a JSON document structure for expressing a sequence of operations to apply to a JSON) document. With the `patch` function, a JSON Patch is applied to the current JSON value by executing all operations from the patch.
+JSON Patch ([RFC 6902](https://tools.ietf.org/html/rfc6902)) defines a JSON document structure for expressing a sequence
+of operations to apply to a JSON document. With the `patch` function, a JSON Patch is applied to the current JSON value
+by executing all operations from the patch.
??? example
diff --git a/doc/mkdocs/docs/features/json_pointer.md b/doc/mkdocs/docs/features/json_pointer.md
index b95c5bc..8f5d60e 100644
--- a/doc/mkdocs/docs/features/json_pointer.md
+++ b/doc/mkdocs/docs/features/json_pointer.md
@@ -13,3 +13,7 @@
j_original["/baz/1"_json_pointer];
// "two"
```
+
+## See also
+
+- Class [`json_pointer`](../api/json_pointer/index.md)
diff --git a/doc/mkdocs/docs/features/macros.md b/doc/mkdocs/docs/features/macros.md
index 8b10ef1..d324a13 100644
--- a/doc/mkdocs/docs/features/macros.md
+++ b/doc/mkdocs/docs/features/macros.md
@@ -8,43 +8,66 @@
## `JSON_CATCH_USER(exception)`
-This macro overrides `#!cpp 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.
+This macro overrides `#!cpp 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.
## `JSON_DIAGNOSTICS`
-This macro enables extended diagnostics for exception messages. Possible values are `1` to enable or `0` to disable (default).
+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.
+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.
+The diagnostics messages can also be controlled with the CMake option `JSON_Diagnostics` (`OFF` by default) which sets
+`JSON_DIAGNOSTICS` accordingly.
## `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.
+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.
+
+## `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`.
## `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()`.
+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()`.
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).
+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).
## `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)).
+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)).
## `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.
+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.
## `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.
+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.
See [Switch off exceptions](../home/exceptions.md#switch-off-exceptions) for an example.
@@ -67,33 +90,45 @@
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:
+ 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.
+Implicit conversions can also be controlled with the CMake option `JSON_ImplicitConversions` (`ON` by default) which
+sets `JSON_USE_IMPLICIT_CONVERSIONS` accordingly.
## `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.
+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 of 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 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.
## `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.
+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 of 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.
+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.
## `NLOHMANN_JSON_SERIALIZE_ENUM(type, ...)`
-This macro simplifies the serialization/deserialization of enum types. See [Specializing enum conversion](enum_conversion.md) for more information.
+This macro simplifies the serialization/deserialization of enum types. See
+[Specializing enum conversion](enum_conversion.md) for more information.
+
+## `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).
diff --git a/doc/mkdocs/docs/features/parsing/index.md b/doc/mkdocs/docs/features/parsing/index.md
index 5cf59bf..2949352 100644
--- a/doc/mkdocs/docs/features/parsing/index.md
+++ b/doc/mkdocs/docs/features/parsing/index.md
@@ -1,4 +1,4 @@
-# Overview
+# Parsing
!!! note
diff --git a/doc/mkdocs/docs/features/parsing/parser_callbacks.md b/doc/mkdocs/docs/features/parsing/parser_callbacks.md
index dbf8884..12136f5 100644
--- a/doc/mkdocs/docs/features/parsing/parser_callbacks.md
+++ b/doc/mkdocs/docs/features/parsing/parser_callbacks.md
@@ -20,14 +20,14 @@
We distinguish six scenarios (determined by the event type) in which the callback function can be called. The following table describes the values
of the parameters `depth`, `event`, and `parsed`.
-parameter `event` | description | parameter `depth` | parameter `parsed`
------------------- | ----------- | ------------------ | -------------------
-`parse_event_t::object_start` | the parser read `{` and started to process a JSON object | depth of the parent of the JSON object | a JSON value with type discarded
-`parse_event_t::key` | the parser read a key of a value in an object | depth of the currently parsed JSON object | a JSON string containing the key
-`parse_event_t::object_end` | the parser read `}` and finished processing a JSON object | depth of the parent of the JSON object | the parsed JSON object
-`parse_event_t::array_start` | the parser read `[` and started to process a JSON array | depth of the parent of the JSON array | a JSON value with type discarded
-`parse_event_t::array_end` | the parser read `]` and finished processing a JSON array | depth of the parent of the JSON array | the parsed JSON array
-`parse_event_t::value` | the parser finished reading a JSON value | depth of the value | the parsed JSON value
+| parameter `event` | description | parameter `depth` | parameter `parsed` |
+|-------------------------------|-----------------------------------------------------------|-------------------------------------------|----------------------------------|
+| `parse_event_t::object_start` | the parser read `{` and started to process a JSON object | depth of the parent of the JSON object | a JSON value with type discarded |
+| `parse_event_t::key` | the parser read a key of a value in an object | depth of the currently parsed JSON object | a JSON string containing the key |
+| `parse_event_t::object_end` | the parser read `}` and finished processing a JSON object | depth of the parent of the JSON object | the parsed JSON object |
+| `parse_event_t::array_start` | the parser read `[` and started to process a JSON array | depth of the parent of the JSON array | a JSON value with type discarded |
+| `parse_event_t::array_end` | the parser read `]` and finished processing a JSON array | depth of the parent of the JSON array | the parsed JSON array |
+| `parse_event_t::value` | the parser finished reading a JSON value | depth of the value | the parsed JSON value |
??? example
diff --git a/doc/mkdocs/docs/features/parsing/sax_interface.md b/doc/mkdocs/docs/features/parsing/sax_interface.md
index 7315348..0796a55 100644
--- a/doc/mkdocs/docs/features/parsing/sax_interface.md
+++ b/doc/mkdocs/docs/features/parsing/sax_interface.md
@@ -66,3 +66,8 @@
3. Call `#!cpp bool json::sax_parse(input, &my_sax);` where the first parameter can be any input like a string or an input stream and the second parameter is a pointer to your SAX interface.
Note the `sax_parse` function only returns a `#!cpp bool` indicating the result of the last executed SAX event. It does not return `json` value - it is up to you to decide what to do with the SAX events. Furthermore, no exceptions are thrown in case of a parse error - it is up to you what to do with the exception object passed to your `parse_error` implementation. Internally, the SAX interface is used for the DOM parser (class `json_sax_dom_parser`) as well as the acceptor (`json_sax_acceptor`), see file `json_sax.hpp`.
+
+## See also
+
+- [json_sax](../../api/json_sax/index.md) - documentation of the SAX interface
+- [sax_parse](../../api/basic_json/sax_parse.md) - SAX parser
diff --git a/doc/mkdocs/docs/features/types/index.md b/doc/mkdocs/docs/features/types/index.md
index b2da9a9..d9dfcc2 100644
--- a/doc/mkdocs/docs/features/types/index.md
+++ b/doc/mkdocs/docs/features/types/index.md
@@ -1,4 +1,4 @@
-# Overview
+# Types
This page gives an overview how JSON values are stored and how this can be configured.
@@ -6,13 +6,13 @@
By default, JSON values are stored as follows:
-| JSON type | C++ type |
-| --------- | -------- |
-| object | `std::map<std::string, basic_json>` |
-| array | `std::vector<basic_json>` |
-| null | `std::nullptr_t` |
-| string | `std::string` |
-| boolean | `bool` |
+| JSON type | C++ type |
+|-----------|-----------------------------------------------|
+| object | `std::map<std::string, basic_json>` |
+| array | `std::vector<basic_json>` |
+| null | `std::nullptr_t` |
+| string | `std::string` |
+| boolean | `bool` |
| number | `std::int64_t`, `std::uint64_t`, and `double` |
Note there are three different types for numbers - when parsing JSON text, the best fitting type is chosen.
diff --git a/doc/mkdocs/docs/features/types/number_handling.md b/doc/mkdocs/docs/features/types/number_handling.md
index aa8df7a..dd65073 100644
--- a/doc/mkdocs/docs/features/types/number_handling.md
+++ b/doc/mkdocs/docs/features/types/number_handling.md
@@ -80,7 +80,7 @@
### Number limits
-- Any 64 bit signed or unsigned integer can be stored without loss of precision.
+- Any 64-bit signed or unsigned integer can be stored without loss of precision.
- Numbers exceeding the limits of `#!c double` (i.e., numbers that after conversion via
[`std::strtod`](https://en.cppreference.com/w/cpp/string/byte/strtof) are not satisfying
[`std::isfinite`](https://en.cppreference.com/w/cpp/numeric/math/isfinite) such as `#!c 1E400`) will throw exception
@@ -100,14 +100,14 @@
The JSON number grammar allows for different ways to express zero, and this library will store zeros differently:
-| Literal | Stored value and type | Serialization |
-| ------- | --------------------- | ------------- |
-| `0` | `#!c std::uint64_t(0)` | `0` |
-| `-0` | `#!c std::int64_t(0)` | `0` |
-| `0.0` | `#!c double(0.0)` | `0.0` |
-| `-0.0` | `#!c double(-0.0)` | `-0.0` |
-| `0E0` | `#!c double(0.0)` | `0.0` |
-| `-0E0` | `#!c double(-0.0)` | `-0.0` |
+| Literal | Stored value and type | Serialization |
+|---------|------------------------|---------------|
+| `0` | `#!c std::uint64_t(0)` | `0` |
+| `-0` | `#!c std::int64_t(0)` | `0` |
+| `0.0` | `#!c double(0.0)` | `0.0` |
+| `-0.0` | `#!c double(-0.0)` | `-0.0` |
+| `0E0` | `#!c double(0.0)` | `0.0` |
+| `-0E0` | `#!c double(-0.0)` | `-0.0` |
That is, `-0` is stored as a signed integer, but the serialization does not reproduce the `-`.
@@ -116,7 +116,7 @@
- Integer numbers are serialized as is; that is, no scientific notation is used.
- Floating-point numbers are serialized as specified by the `#!c %g` printf modifier with
[`std::numeric_limits<double>::max_digits10`](https://en.cppreference.com/w/cpp/types/numeric_limits/max_digits10)
- significant digits). The rationale is to use the shortest representation while still allow round-tripping.
+ significant digits. The rationale is to use the shortest representation while still allow round-tripping.
!!! hint "Notes regarding precision of floating-point numbers"
@@ -128,7 +128,7 @@
- The serialization can be in scientific notation even if the input is not: `#!c 0.0000972439793401814` will be
serialized as `#!c 9.72439793401814e-05`. The reverse can also be true: `#!c 12345E-5` will be serialized as
`#!c 0.12345`.
- - Conversions from `#!c float` to `#!c double` can also introduce rouding errors:
+ - Conversions from `#!c float` to `#!c double` can also introduce rounding errors:
```cpp
float f = 0.3;
json j = f;
@@ -283,27 +283,27 @@
- [`is_number_unsigned()`](../../api/basic_json/is_number_unsigned.md) returns `#!c true` for unsigned integers only
- [`is_number_float()`](../../api/basic_json/is_number_float.md) returns `#!c true` for floating-point numbers
- [`type_name()`](../../api/basic_json/type_name.md) returns `#!c "number"` for any number type
-- [`type()`](../../api/basic_json/type.md) returns an different enumerator of
+- [`type()`](../../api/basic_json/type.md) returns a different enumerator of
[`value_t`](../../api/basic_json/value_t.md) for all number types
-| function | unsigned integer | signed integer | floating-point | string |
-| -------- | ---------------- | -------------- | -------------- | ------ |
-| [`is_number()`](../../api/basic_json/is_number.md) | `#!c true` | `#!c true` | `#!c true` | `#!c false` |
-| [`is_number_integer()`](../../api/basic_json/is_number_integer.md) | `#!c true` | `#!c true` | `#!c false` | `#!c false` |
-| [`is_number_unsigned()`](../../api/basic_json/is_number_unsigned.md) | `#!c true` | `#!c false` | `#!c false` | `#!c false` |
-| [`is_number_float()`](../../api/basic_json/is_number_float.md) | `#!c false` | `#!c false` | `#!c true` | `#!c false` |
-| [`type_name()`](../../api/basic_json/type_name.md) | `#!c "number"` | `#!c "number"` | `#!c "number"` | `#!c "string"` |
-| [`type()`](../../api/basic_json/type.md) | `number_unsigned` | `number_integer` | `number_float` | `string` |
+| function | unsigned integer | signed integer | floating-point | string |
+|----------------------------------------------------------------------|-------------------|------------------|----------------|----------------|
+| [`is_number()`](../../api/basic_json/is_number.md) | `#!c true` | `#!c true` | `#!c true` | `#!c false` |
+| [`is_number_integer()`](../../api/basic_json/is_number_integer.md) | `#!c true` | `#!c true` | `#!c false` | `#!c false` |
+| [`is_number_unsigned()`](../../api/basic_json/is_number_unsigned.md) | `#!c true` | `#!c false` | `#!c false` | `#!c false` |
+| [`is_number_float()`](../../api/basic_json/is_number_float.md) | `#!c false` | `#!c false` | `#!c true` | `#!c false` |
+| [`type_name()`](../../api/basic_json/type_name.md) | `#!c "number"` | `#!c "number"` | `#!c "number"` | `#!c "string"` |
+| [`type()`](../../api/basic_json/type.md) | `number_unsigned` | `number_integer` | `number_float` | `string` |
### Template number types
The number types can be changed with template parameters.
-| position | number type | default type | possible values |
-| -------- | ----------- | ------------ | --------------- |
-| 5 | signed integers | `#!c std::int64_t` | `#!c std::int32_t`, `#!c std::int16_t`, etc. |
+| position | number type | default type | possible values |
+|----------|-------------------|---------------------|------------------------------------------------|
+| 5 | signed integers | `#!c std::int64_t` | `#!c std::int32_t`, `#!c std::int16_t`, etc. |
| 6 | unsigned integers | `#!c std::uint64_t` | `#!c std::uint32_t`, `#!c std::uint16_t`, etc. |
-| 7 | floating-point | `#!c double` | `#!c float`, `#!c long double` |
+| 7 | floating-point | `#!c double` | `#!c float`, `#!c long double` |
!!! info "Constraints on number types"
diff --git a/doc/mkdocs/docs/home/design_goals.md b/doc/mkdocs/docs/home/design_goals.md
index 91b3875..b80551f 100644
--- a/doc/mkdocs/docs/home/design_goals.md
+++ b/doc/mkdocs/docs/home/design_goals.md
@@ -2,7 +2,7 @@
There are myriads of [JSON](https://json.org) libraries out there, and each may even have its reason to exist. Our class had these design goals:
-- **Intuitive syntax**. In languages such as Python, JSON feels like a first class data type. We used all the operator magic of modern C++ to achieve the same feeling in your code. Check out the [examples below](#examples) and you'll know what I mean.
+- **Intuitive syntax**. In languages such as Python, JSON feels like a first class data type. We used all the operator magic of modern C++ to achieve the same feeling in your code. Check out the [examples below](#examples), and you'll know what I mean.
- **Trivial integration**. Our whole code consists of a single header file [`json.hpp`](https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json.hpp). That's it. No library, no subproject, no dependencies, no complex build system. The class is written in vanilla C++11. All in all, everything should require no adjustment of your compiler flags or project settings.
diff --git a/doc/mkdocs/docs/home/exceptions.md b/doc/mkdocs/docs/home/exceptions.md
index a04b60f..1241926 100644
--- a/doc/mkdocs/docs/home/exceptions.md
+++ b/doc/mkdocs/docs/home/exceptions.md
@@ -177,12 +177,12 @@
!!! tip
- - Make sure the input is correctly read. Try to write the input to standard output to check if, for instance, the input file was successfully openened.
+ - Make sure the input is correctly read. Try to write the input to standard output to check if, for instance, the input file was successfully opened.
- Paste the input to a JSON validator like <http://jsonlint.com> or a tool like [jq](https://stedolan.github.io/jq/).
### json.exception.parse_error.102
-JSON uses the `\uxxxx` format to describe Unicode characters. Code points above above 0xFFFF are split into two `\uxxxx` entries ("surrogate pairs"). This error indicates that the surrogate pair is incomplete or contains an invalid code point.
+JSON uses the `\uxxxx` format to describe Unicode characters. Code points above 0xFFFF are split into two `\uxxxx` entries ("surrogate pairs"). This error indicates that the surrogate pair is incomplete or contains an invalid code point.
!!! failure "Example message"
@@ -369,7 +369,7 @@
### json.exception.invalid_iterator.202
-In an [erase](../api/basic_json/erase.md) or insert function, the passed iterator `pos` does not belong to the JSON value for which the function was called. It hence does not define a valid position for the deletion/insertion.
+In the [erase](../api/basic_json/erase.md) or insert function, the passed iterator `pos` does not belong to the JSON value for which the function was called. It hence does not define a valid position for the deletion/insertion.
!!! failure "Example message"
@@ -661,7 +661,7 @@
### json.exception.type_error.313
-The `unflatten` function converts an object whose keys are JSON Pointers back into an arbitrary nested JSON value. The JSON Pointers must not overlap, because then the resulting value would not be well defined.
+The `unflatten` function converts an object whose keys are JSON Pointers back into an arbitrary nested JSON value. The JSON Pointers must not overlap, because then the resulting value would not be well-defined.
!!! failure "Example message"
diff --git a/doc/mkdocs/docs/home/license.md b/doc/mkdocs/docs/home/license.md
index d359468..baef2f5 100644
--- a/doc/mkdocs/docs/home/license.md
+++ b/doc/mkdocs/docs/home/license.md
@@ -4,7 +4,7 @@
The class is licensed under the [MIT License](https://opensource.org/licenses/MIT):
-Copyright © 2013-2021 [Niels Lohmann](https://nlohmann.me)
+Copyright © 2013-2022 [Niels Lohmann](https://nlohmann.me)
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
diff --git a/doc/mkdocs/docs/home/releases.md b/doc/mkdocs/docs/home/releases.md
index 298c377..2cf5b3c 100644
--- a/doc/mkdocs/docs/home/releases.md
+++ b/doc/mkdocs/docs/home/releases.md
@@ -468,7 +468,7 @@
- allow compare user-defined string types (#1130)
- better support for algorithms using iterators from `items()` (#1045, #1134)
- added parameter to avoid compilation error with MSVC 2015 debug builds (#1114)
-- re-added accidentially skipped unit tests (#1176)
+- re-added accidentally skipped unit tests (#1176)
- fixed MSVC issue with `std::swap` (#1168)
### :zap: Improvements
@@ -1008,7 +1008,7 @@
This release fixes the semantics of `operator[]` for JSON Pointers (see below). This fix is backwards compatible.
### Changes
-- **`operator[]` for JSON Pointers** now behaves like the other versions of `operator[]` and transforms `null` values into objects or arrays if required. This allows to created nested structues like `j["/foo/bar/2"] = 17` (yielding `{"foo": "bar": [null, null, 17]}`) without problems.
+- **`operator[]` for JSON Pointers** now behaves like the other versions of `operator[]` and transforms `null` values into objects or arrays if required. This allows to created nested structures like `j["/foo/bar/2"] = 17` (yielding `{"foo": "bar": [null, null, 17]}`) without problems.
- overworked a helper SFINAE function
- fixed some documentation issues
- fixed the CMake files to allow to run the test suite outside the main project directory
@@ -1093,7 +1093,7 @@
### Changes
- The **parser** has been overworked, and a lot of small issues have been fixed:
- Improved parser performance by avoiding recursion and using move semantics for the return value.
- - Unescaped control charaters `\x10`-`\x1f` are not accepted any more.
+ - Unescaped control characters `\x10`-`\x1f` are not accepted any more.
- Fixed a bug in the parser when reading from an input stream.
- Improved test case coverage for UTF-8 parsing: now, all valid Unicode code points are tested both escaped and unescaped.
- The precision of output streams is now preserved by the parser.
diff --git a/doc/mkdocs/docs/hooks.py b/doc/mkdocs/docs/hooks.py
deleted file mode 100644
index 8fee839..0000000
--- a/doc/mkdocs/docs/hooks.py
+++ /dev/null
@@ -1,10 +0,0 @@
-import shutil
-import os.path
-
-
-def copy_doxygen(*args, **kwargs):
- doxygen_dir = os.path.join(kwargs['config']['site_dir'], 'doxygen')
- if not os.path.isdir(doxygen_dir) or not os.listdir(doxygen_dir):
- print('Copy Doxygen files...')
- shutil.copytree('../html', doxygen_dir)
- print('Copy Doxygen complete')
diff --git a/doc/images/callback_events.png b/doc/mkdocs/docs/images/callback_events.png
similarity index 100%
rename from doc/images/callback_events.png
rename to doc/mkdocs/docs/images/callback_events.png
Binary files differ
diff --git a/doc/images/json_syntax_number.png b/doc/mkdocs/docs/images/json_syntax_number.png
similarity index 100%
rename from doc/images/json_syntax_number.png
rename to doc/mkdocs/docs/images/json_syntax_number.png
Binary files differ
diff --git a/doc/images/range-begin-end.svg b/doc/mkdocs/docs/images/range-begin-end.svg
similarity index 100%
rename from doc/images/range-begin-end.svg
rename to doc/mkdocs/docs/images/range-begin-end.svg
diff --git a/doc/images/range-rbegin-rend.svg b/doc/mkdocs/docs/images/range-rbegin-rend.svg
similarity index 100%
rename from doc/images/range-rbegin-rend.svg
rename to doc/mkdocs/docs/images/range-rbegin-rend.svg
diff --git a/doc/mkdocs/docs/integration/package_managers.md b/doc/mkdocs/docs/integration/package_managers.md
index a4eda83..d98005d 100644
--- a/doc/mkdocs/docs/integration/package_managers.md
+++ b/doc/mkdocs/docs/integration/package_managers.md
@@ -54,7 +54,7 @@
If you are using the [Meson Build System](http://mesonbuild.com), add this source tree as a [meson subproject](https://mesonbuild.com/Subprojects.html#using-a-subproject). You may also use the `include.zip` published in this project's [Releases](https://github.com/nlohmann/json/releases) to reduce the size of the vendored source tree. Alternatively, you can get a wrap file by downloading it from [Meson WrapDB](https://wrapdb.mesonbuild.com/nlohmann_json), or simply use `meson wrap install nlohmann_json`. Please see the meson project for any issues regarding the packaging.
-The provided meson.build can also be used as an alternative to cmake for installing `nlohmann_json` system-wide in which case a pkg-config file is installed. To use it, simply have your build system require the `nlohmann_json` pkg-config dependency. In Meson, it is preferred to use the [`dependency()`](https://mesonbuild.com/Reference-manual.html#dependency) object with a subproject fallback, rather than using the subproject directly.
+The provided `meson.build` can also be used as an alternative to cmake for installing `nlohmann_json` system-wide in which case a pkg-config file is installed. To use it, simply have your build system require the `nlohmann_json` pkg-config dependency. In Meson, it is preferred to use the [`dependency()`](https://mesonbuild.com/Reference-manual.html#dependency) object with a subproject fallback, rather than using the subproject directly.
## Conan
@@ -152,7 +152,7 @@
## NuGet
-If you are using [NuGet](https://www.nuget.org), you can use the package [nlohmann.json](https://www.nuget.org/packages/nlohmann.json/). Please check [this extensive description](https://github.com/nlohmann/json/issues/1132#issuecomment-452250255) on how to use the package. Please files issues [here](https://github.com/hnkb/nlohmann-json-nuget/issues).
+If you are using [NuGet](https://www.nuget.org), you can use the package [nlohmann.json](https://www.nuget.org/packages/nlohmann.json/). Please check [this extensive description](https://github.com/nlohmann/json/issues/1132#issuecomment-452250255) on how to use the package. Please file issues [here](https://github.com/hnkb/nlohmann-json-nuget/issues).
## Conda
diff --git a/doc/mkdocs/docs/integration/pkg-config.md b/doc/mkdocs/docs/integration/pkg-config.md
index 56f8644..429d0de 100644
--- a/doc/mkdocs/docs/integration/pkg-config.md
+++ b/doc/mkdocs/docs/integration/pkg-config.md
@@ -6,7 +6,7 @@
pkg-config nlohmann_json --cflags
```
-Users of the [Meson build system](package_managers.md#meson) will also be able to use a system wide library, which will be found by `pkg-config`:
+Users of the [Meson build system](package_managers.md#meson) will also be able to use a system-wide library, which will be found by `pkg-config`:
```meson
json = dependency('nlohmann_json', required: true)
diff --git a/doc/mkdocs/mkdocs.yml b/doc/mkdocs/mkdocs.yml
index 7aa6e2c..542d4f1 100644
--- a/doc/mkdocs/mkdocs.yml
+++ b/doc/mkdocs/mkdocs.yml
@@ -9,7 +9,7 @@
edit_uri: edit/develop/doc/mkdocs/docs
# Copyright
-copyright: Copyright © 2013 - 2021 Niels Lohmann
+copyright: Copyright © 2013 - 2022 Niels Lohmann
# Configuration
theme:
@@ -20,10 +20,13 @@
accent: indigo
font:
text: Roboto
- code: Roboto Mono
+ code: JetBrains Mono
features:
- - tabs
- - instant
+ - navigation.instant
+ - navigation.tracking
+ - navigation.tabs
+ - navigation.indexes
+ - navigation.top
nav:
- Home:
@@ -70,120 +73,164 @@
- integration/cmake.md
- integration/package_managers.md
- integration/pkg-config.md
- - Doxygen: doxygen/index.html
- - API:
+ - API Documentation:
- basic_json:
- - api/basic_json/index.md
- - api/basic_json/accept.md
- - api/basic_json/array.md
- - api/basic_json/array_t.md
- - api/basic_json/at.md
- - api/basic_json/back.md
- - api/basic_json/basic_json.md
- - api/basic_json/~basic_json.md
- - api/basic_json/begin.md
- - api/basic_json/binary.md
- - api/basic_json/binary_t.md
- - api/basic_json/boolean_t.md
- - api/basic_json/cbegin.md
- - api/basic_json/cbor_tag_handler_t.md
- - api/basic_json/cend.md
- - api/basic_json/clear.md
- - api/basic_json/contains.md
- - api/basic_json/count.md
- - api/basic_json/crbegin.md
- - api/basic_json/crend.md
- - api/basic_json/diff.md
- - api/basic_json/dump.md
- - api/basic_json/emplace.md
- - api/basic_json/emplace_back.md
- - api/basic_json/empty.md
- - api/basic_json/end.md
- - api/basic_json/erase.md
- - api/basic_json/error_handler_t.md
- - api/basic_json/exception.md
- - api/basic_json/find.md
- - api/basic_json/flatten.md
- - api/basic_json/from_bson.md
- - api/basic_json/from_cbor.md
- - api/basic_json/from_msgpack.md
- - api/basic_json/from_ubjson.md
- - api/basic_json/front.md
- - api/basic_json/get.md
- - api/basic_json/get_allocator.md
- - api/basic_json/get_binary.md
- - api/basic_json/get_ptr.md
- - api/basic_json/get_ref.md
- - api/basic_json/get_to.md
- - api/basic_json/input_format_t.md
- - api/basic_json/insert.md
- - api/basic_json/invalid_iterator.md
- - api/basic_json/is_array.md
- - api/basic_json/is_binary.md
- - api/basic_json/is_boolean.md
- - api/basic_json/is_discarded.md
- - api/basic_json/is_null.md
- - api/basic_json/is_number.md
- - api/basic_json/is_number_float.md
- - api/basic_json/is_number_integer.md
- - api/basic_json/is_number_unsigned.md
- - api/basic_json/is_object.md
- - api/basic_json/is_primitive.md
- - api/basic_json/is_string.md
- - api/basic_json/is_structured.md
- - api/basic_json/items.md
- - api/basic_json/json_serializer.md
- - api/basic_json/max_size.md
- - api/basic_json/meta.md
- - api/basic_json/merge_patch.md
- - api/basic_json/number_float_t.md
- - api/basic_json/number_integer_t.md
- - api/basic_json/number_unsigned_t.md
- - api/basic_json/object.md
- - api/basic_json/object_comparator_t.md
- - api/basic_json/object_t.md
- - api/basic_json/operator_ValueType.md
- - api/basic_json/operator_value_t.md
- - api/basic_json/operator[].md
- - api/basic_json/operator=.md
- - api/basic_json/operator_eq.md
- - api/basic_json/operator_ne.md
- - api/basic_json/operator_lt.md
- - api/basic_json/operator_le.md
- - api/basic_json/operator_gt.md
- - api/basic_json/operator_ge.md
- - api/basic_json/operator+=.md
- - api/basic_json/operator_literal_json.md
- - api/basic_json/operator_literal_json_pointer.md
- - api/basic_json/out_of_range.md
- - api/basic_json/other_error.md
- - api/basic_json/parse.md
- - api/basic_json/parse_error.md
- - api/basic_json/parse_event_t.md
- - api/basic_json/parser_callback_t.md
- - api/basic_json/patch.md
- - api/basic_json/push_back.md
- - api/basic_json/rbegin.md
- - api/basic_json/rend.md
- - api/basic_json/sax_parse.md
- - api/basic_json/size.md
- - api/basic_json/string_t.md
- - api/basic_json/to_bson.md
- - api/basic_json/to_cbor.md
- - api/basic_json/to_msgpack.md
- - api/basic_json/to_ubjson.md
- - api/basic_json/type.md
- - api/basic_json/type_error.md
- - api/basic_json/type_name.md
- - api/basic_json/unflatten.md
- - api/basic_json/update.md
- - api/basic_json/value.md
- - api/basic_json/value_t.md
- - api/adl_serializer.md
- - api/json.md
- - api/json_pointer.md
- - api/ordered_map.md
- - api/ordered_json.md
+ - 'Overview': api/basic_json/index.md
+ - '(Constructor)': api/basic_json/basic_json.md
+ - '(Destructor)': api/basic_json/~basic_json.md
+ - 'accept': api/basic_json/accept.md
+ - 'array': api/basic_json/array.md
+ - 'array_t': api/basic_json/array_t.md
+ - 'at': api/basic_json/at.md
+ - 'back': api/basic_json/back.md
+ - 'begin': api/basic_json/begin.md
+ - 'binary': api/basic_json/binary.md
+ - 'binary_t': api/basic_json/binary_t.md
+ - 'boolean_t': api/basic_json/boolean_t.md
+ - 'cbegin': api/basic_json/cbegin.md
+ - 'cbor_tag_handler_t': api/basic_json/cbor_tag_handler_t.md
+ - 'cend': api/basic_json/cend.md
+ - 'clear': api/basic_json/clear.md
+ - 'contains': api/basic_json/contains.md
+ - 'count': api/basic_json/count.md
+ - 'crbegin': api/basic_json/crbegin.md
+ - 'crend': api/basic_json/crend.md
+ - 'diff': api/basic_json/diff.md
+ - 'dump': api/basic_json/dump.md
+ - 'emplace': api/basic_json/emplace.md
+ - 'emplace_back': api/basic_json/emplace_back.md
+ - 'empty': api/basic_json/empty.md
+ - 'end': api/basic_json/end.md
+ - 'erase': api/basic_json/erase.md
+ - 'error_handler_t': api/basic_json/error_handler_t.md
+ - 'exception': api/basic_json/exception.md
+ - 'find': api/basic_json/find.md
+ - 'flatten': api/basic_json/flatten.md
+ - 'from_bson': api/basic_json/from_bson.md
+ - 'from_cbor': api/basic_json/from_cbor.md
+ - 'from_msgpack': api/basic_json/from_msgpack.md
+ - 'from_ubjson': api/basic_json/from_ubjson.md
+ - 'front': api/basic_json/front.md
+ - 'get': api/basic_json/get.md
+ - 'get_allocator': api/basic_json/get_allocator.md
+ - 'get_binary': api/basic_json/get_binary.md
+ - 'get_ptr': api/basic_json/get_ptr.md
+ - 'get_ref': api/basic_json/get_ref.md
+ - 'get_to': api/basic_json/get_to.md
+ - 'std::hash<basic_json>': api/basic_json/std_hash.md
+ - 'input_format_t': api/basic_json/input_format_t.md
+ - 'insert': api/basic_json/insert.md
+ - 'invalid_iterator': api/basic_json/invalid_iterator.md
+ - 'is_array': api/basic_json/is_array.md
+ - 'is_binary': api/basic_json/is_binary.md
+ - 'is_boolean': api/basic_json/is_boolean.md
+ - 'is_discarded': api/basic_json/is_discarded.md
+ - 'is_null': api/basic_json/is_null.md
+ - 'is_number': api/basic_json/is_number.md
+ - 'is_number_float': api/basic_json/is_number_float.md
+ - 'is_number_integer': api/basic_json/is_number_integer.md
+ - 'is_number_unsigned': api/basic_json/is_number_unsigned.md
+ - 'is_object': api/basic_json/is_object.md
+ - 'is_primitive': api/basic_json/is_primitive.md
+ - 'is_string': api/basic_json/is_string.md
+ - 'is_structured': api/basic_json/is_structured.md
+ - 'items': api/basic_json/items.md
+ - 'json_serializer': api/basic_json/json_serializer.md
+ - 'max_size': api/basic_json/max_size.md
+ - 'meta': api/basic_json/meta.md
+ - 'merge_patch': api/basic_json/merge_patch.md
+ - 'number_float_t': api/basic_json/number_float_t.md
+ - 'number_integer_t': api/basic_json/number_integer_t.md
+ - 'number_unsigned_t': api/basic_json/number_unsigned_t.md
+ - 'object': api/basic_json/object.md
+ - 'object_comparator_t': api/basic_json/object_comparator_t.md
+ - 'object_t': api/basic_json/object_t.md
+ - 'operator ValueType': api/basic_json/operator_ValueType.md
+ - 'operator value_t': api/basic_json/operator_value_t.md
+ - 'operator[]': api/basic_json/operator[].md
+ - 'operator=': api/basic_json/operator=.md
+ - 'operator==': api/basic_json/operator_eq.md
+ - 'operator!=': api/basic_json/operator_ne.md
+ - 'operator<': api/basic_json/operator_lt.md
+ - 'operator<<': api/basic_json/operator_ltlt.md
+ - 'operator<=': api/basic_json/operator_le.md
+ - 'operator>': api/basic_json/operator_gt.md
+ - 'operator>>': api/basic_json/operator_gtgt.md
+ - 'operator>=': api/basic_json/operator_ge.md
+ - 'operator+=': api/basic_json/operator+=.md
+ - 'operator""_json': api/basic_json/operator_literal_json.md
+ - 'operator""_json_pointer': api/basic_json/operator_literal_json_pointer.md
+ - 'out_of_range': api/basic_json/out_of_range.md
+ - 'other_error': api/basic_json/other_error.md
+ - 'parse': api/basic_json/parse.md
+ - 'parse_error': api/basic_json/parse_error.md
+ - 'parse_event_t': api/basic_json/parse_event_t.md
+ - 'parser_callback_t': api/basic_json/parser_callback_t.md
+ - 'patch': api/basic_json/patch.md
+ - 'push_back': api/basic_json/push_back.md
+ - 'rbegin': api/basic_json/rbegin.md
+ - 'rend': api/basic_json/rend.md
+ - 'sax_parse': api/basic_json/sax_parse.md
+ - 'size': api/basic_json/size.md
+ - 'string_t': api/basic_json/string_t.md
+ - 'swap': api/basic_json/swap.md
+ - 'std::swap<basic_json>': api/basic_json/std_swap.md
+ - 'to_bson': api/basic_json/to_bson.md
+ - 'to_cbor': api/basic_json/to_cbor.md
+ - 'to_msgpack': api/basic_json/to_msgpack.md
+ - 'to_string': api/basic_json/to_string.md
+ - 'to_ubjson': api/basic_json/to_ubjson.md
+ - 'type': api/basic_json/type.md
+ - 'type_error': api/basic_json/type_error.md
+ - 'type_name': api/basic_json/type_name.md
+ - 'unflatten': api/basic_json/unflatten.md
+ - 'update': api/basic_json/update.md
+ - 'value': api/basic_json/value.md
+ - 'value_t': api/basic_json/value_t.md
+ - byte_container_with_subtype:
+ - 'Overview': api/byte_container_with_subtype/index.md
+ - '(constructor)': api/byte_container_with_subtype/byte_container_with_subtype.md
+ - 'clear_subtype': api/byte_container_with_subtype/clear_subtype.md
+ - 'has_subtype': api/byte_container_with_subtype/has_subtype.md
+ - 'set_subtype': api/byte_container_with_subtype/set_subtype.md
+ - 'subtype': api/byte_container_with_subtype/subtype.md
+ - adl_serializer:
+ - 'Overview': api/adl_serializer/index.md
+ - 'from_json': api/adl_serializer/from_json.md
+ - 'to_json': api/adl_serializer/to_json.md
+ - 'json': api/json.md
+ - json_pointer:
+ - 'Overview': api/json_pointer/index.md
+ - '(Constructor)': api/json_pointer/json_pointer.md
+ - 'back': api/json_pointer/back.md
+ - 'empty': api/json_pointer/empty.md
+ - 'operator std::string': api/json_pointer/operator_string.md
+ - 'operator/': api/json_pointer/operator_slash.md
+ - 'operator/=': api/json_pointer/operator_slasheq.md
+ - 'parent_pointer': api/json_pointer/parent_pointer.md
+ - 'pop_back': api/json_pointer/pop_back.md
+ - 'push_back': api/json_pointer/push_back.md
+ - 'to_string': api/json_pointer/to_string.md
+ - json_sax:
+ - 'Overview': api/json_sax/index.md
+ - 'binary': api/json_sax/binary.md
+ - 'boolean': api/json_sax/boolean.md
+ - 'end_array': api/json_sax/end_array.md
+ - 'end_object': api/json_sax/end_object.md
+ - 'key': api/json_sax/key.md
+ - 'null': api/json_sax/null.md
+ - 'number_float': api/json_sax/number_float.md
+ - 'number_integer': api/json_sax/number_integer.md
+ - 'number_unsigned': api/json_sax/number_unsigned.md
+ - 'parse_error': api/json_sax/parse_error.md
+ - 'start_array': api/json_sax/start_array.md
+ - 'start_object': api/json_sax/start_object.md
+ - 'string': api/json_sax/string.md
+ - 'ordered_json': api/ordered_json.md
+ - 'ordered_map': api/ordered_map.md
+ - macros:
+ - 'Overview': api/macros/index.md
+ - 'JSON_ASSERT(x)': api/macros/json_assert.md
# Extras
extra:
@@ -198,10 +245,13 @@
link: https://www.xing.com/profile/Niels_Lohmann
- icon: fontawesome/brands/paypal
link: https://www.paypal.me/nlohmann
+ generator: false
# Extensions
markdown_extensions:
+ - abbr
- admonition
+ - attr_list
- def_list
- codehilite:
guess_lang: false
@@ -233,10 +283,8 @@
plugins:
- search:
- separator: '[\s\-\.]+'
- - mkdocs-simple-hooks:
- hooks:
- on_post_build: "docs.hooks:copy_doxygen"
+ separator: '[\s\-\.]'
+ lang: en
- minify:
minify_html: true
diff --git a/doc/mkdocs/scripts/check_structure.py b/doc/mkdocs/scripts/check_structure.py
new file mode 100644
index 0000000..cacc51c
--- /dev/null
+++ b/doc/mkdocs/scripts/check_structure.py
@@ -0,0 +1,121 @@
+#!/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()
diff --git a/doc/scripts/git-update-ghpages b/doc/scripts/git-update-ghpages
deleted file mode 100755
index 393650c..0000000
--- a/doc/scripts/git-update-ghpages
+++ /dev/null
@@ -1,193 +0,0 @@
-#!/usr/bin/env bash
-set -o errexit
-
-copy_contents() {
- local source="$1"
- status "Copying contents from $source"
- if [[ ! "$dryrun" == "1" ]]; then
- (cd "$source" >/dev/null && tar c .) | tar xv
- else
- _ "(cd \"$source\" >/dev/null && tar c .) | tar xv"
- fi
-}
-
-# Sets git config
-set_config() {
- if [ -n "$GIT_NAME" ]; then _ git config user.name "$GIT_NAME"; fi
- if [ -n "$GIT_EMAIL" ]; then _ git config user.email "$GIT_EMAIL"; fi
-}
-
-# Runs the deployment
-run() {
- if [ ! -d "$source" ]; then
- echo "Source is not a directory: $source"
- exit 1
- fi
-
- local tmpdir="$(mktemp -d)"
-
- if [[ "$force" == "1" ]]; then
- _ cd "$tmpdir"
- _ git init
- _ git checkout -b "$branch"
- copy_contents "$source"
- if [[ "$useenv" == "1" ]]; then set_config; fi
- _ git add -A .
- git_commit
- git_push --force
- else
- _ cd "$tmpdir"
- _ git clone "$repo" . -b "$branch" || ( \
- _ git init && \
- _ git checkout -b "$branch")
- if [[ "$keep" == "0" ]]; then _ rm -rf ./*; fi
- copy_contents "$source"
- if [[ "$useenv" == "1" ]]; then set_config; fi
- _ git add -A .
- git_commit || true
- git_push
- fi
- _ rm -rf "$tmpdir"
- status_ "Done"
-}
-
-git_commit() {
- if [ -z "$author" ]; then
- _ git commit -m "$message"
- else
- _ git commit -m "$message" --author "$author"
- fi
-}
-
-git_push() {
- if [ -z "$GITHUB_TOKEN" ]; then
- _ git push "${repo}" "$branch" "$@"
- else
- status "Pushing via \$GITHUB_TOKEN $@"
- _ git push "https://${GITHUB_TOKEN}@github.com/${repospec}.git" "$branch" "$@" \
- --quiet >/dev/null 2>&1 || \
- ( status_ "Failed to push"; exit 1 )
- fi
-}
-
-status() {
- echo -e "\n\033[34m==>\033[0;1m" "$@\033[0m"
-}
-status_() {
- echo -e "\033[33;1m==>\033[0m" "$@"
-}
-
-_() {
- echo ""
- status_ "$@"
- if [[ ! "$dryrun" == "1" ]]; then "$@"; fi
-}
-
-help() {
- local cmd="$(basename $0)"
- echo 'Usage:'
- echo " $cmd <REPO> <SOURCE>"
- echo ''
- echo 'Parameters:'
- echo " REPO repository to push to in 'user/repo' form"
- echo " SOURCE path to upload to repository's gh-pages branch"
- echo ''
- echo 'Options:'
- echo ' -h, --help show help screen'
- echo ' -f, --force force push'
- echo ' -n, --dry-run run in simulation mode'
- echo ' -e, --use-env pick up arguments from environment variables'
- echo ' -b, --branch use this branch name (default: gh-pages)'
- echo ' -a, --author set the author'
- echo ' -k, --keep keep existing files in the repo'
- echo ''
- echo 'Env var options:'
- echo ' GITHUB_TOKEN if set, use this to push to the repo'
- echo ''
- echo 'Optional env vars:'
- echo " Run with '-e' to enable the use of these variables."
- echo " GIT_NAME set this as the repos user.name"
- echo ' GIT_EMAIL set this as the repos user.email'
- echo ' GITHUB_REPO substitute as the REPO (1st argument)'
- echo ' GIT_SOURCE substitute as the SOURCE (2nd argument)'
- echo ' GIT_BRANCH use this branch name (--branch)'
- echo ''
- echo 'Example:'
- echo " $cmd rstacruz/myproject doc"
- echo " # pushes './doc' into the gh-pages branch of rstacruz/myproject"
- echo ''
- echo " export GITHUB_REPO='xyz/abc'"
- echo " export GIT_SOURCE='docs'"
- echo " $cmd -e"
- echo " # pushes './doc' into the gh-pages branch of xyz/abc"
-}
-
-#
-# Defaults
-#
-
-force=0
-dryrun=0
-repospec=
-source=
-branch=
-message="Update"
-useenv=0
-author=""
-keep=0
-
-#
-# Parse args
-#
-
-while [[ "$1" =~ ^- && ! "$1" == '--' ]]; do case $1 in
- -h | --help )
- help
- exit
- ;;
- -b | --branch )
- shift
- branch="$1"
- ;;
- -n | --dry-run )
- dryrun=1
- ;;
- -e | --use-env )
- useenv=1
- ;;
- -k | --keep )
- keep=1
- ;;
- -a | --author)
- shift
- author="$1"
- ;;
- -f | --force )
- force=1
- ;;
-esac; shift; done
-if [[ "$1" == '--' ]]; then shift; fi
-
-if [[ "$useenv" == "1" ]] && [[ -n "$GIT_BRANCH" ]] && [[ -z "$branch" ]]; then
- branch="$GIT_BRANCH"
-fi
-
-if [[ "$useenv" == "1" ]] && [[ -n "$GITHUB_REPO" ]] && [[ -n "$GIT_SOURCE" ]] && [[ -z "$2" ]]; then
- repospec="$GITHUB_REPO"
- source="$GIT_SOURCE"
-else
- repospec="$1"
- source="$2"
-fi
-
-: ${branch:="gh-pages"}
-
-if [ -z "$source" ]; then
- help
- exit 1
-fi
-
-source="`pwd -LP`/$source"
-repo="https://github.com/${repospec}.git"
-
-run
diff --git a/doc/scripts/send_to_wandbox.py b/doc/scripts/send_to_wandbox.py
deleted file mode 100755
index 1126566..0000000
--- a/doc/scripts/send_to_wandbox.py
+++ /dev/null
@@ -1,120 +0,0 @@
-#! /usr/bin/env python
-
-# This script uploads a directory to Wandbox (http://melpon.org/wandbox),
-# which is an online compiler environment, and prints a permalink to the
-# uploaded code. We use this to provide a "Try it online" version of the
-# library to make the barrier to entry as low as possible.
-#
-# This script was adapted from the script proposed in
-# https://github.com/melpon/wandbox/issues/153.
-#
-# To know how to use this script: ./wandbox.py --help
-#
-# Copyright Louis Dionne 2015
-# Distributed under the Boost Software License, Version 1.0.
-# (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
-
-import argparse
-import fnmatch
-import json
-import os
-import re
-import urllib2
-
-
-# Strips C and C++ comments from the given string.
-#
-# Copied from https://stackoverflow.com/a/241506/627587.
-def strip_comments(text):
- def replacer(match):
- s = match.group(0)
- if s.startswith('/'):
- return " " # note: a space and not an empty string
- else:
- return s
- pattern = re.compile(
- r'//.*?$|/\*.*?\*/|\'(?:\\.|[^\\\'])*\'|"(?:\\.|[^\\"])*"',
- re.DOTALL | re.MULTILINE
- )
- return re.sub(pattern, replacer, text)
-
-
-# Post the given JSON data to Wandbox's API, and return the result
-# as a JSON object.
-def upload(options):
- request = urllib2.Request('https://melpon.org/wandbox/api/compile.json')
- request.add_header('Content-Type', 'application/json')
- response = urllib2.urlopen(request, json.dumps(options))
- return json.loads(response.read())
-
-
-# Returns a list of the '.hpp' headers in the given directory and in
-# subdirectories.
-#
-# The path must be absolute, and the returned paths are all absolute too.
-def headers(path):
- return [
- os.path.join(dir, file)
- for (dir, _, files) in os.walk(path)
- for file in fnmatch.filter(files, "*.hpp")
- ]
-
-
-def main():
- parser = argparse.ArgumentParser(description=
- """Upload a directory to Wandbox (http://melpon.org/wandbox).
-
- On success, the program prints a permalink to the uploaded
- directory on Wandbox and returns 0. On error, it prints the
- response from the Wandbox API and returns 1.
-
- Note that the comments are stripped from all the headers in the
- uploaded directory.
- """
- )
- parser.add_argument('directory', type=str, help=
- """A directory to upload to Wandbox.
-
- The path may be either absolute or relative to the current directory.
- However, the names of the files uploaded to Wandbox will all be
- relative to this directory. This way, one can easily specify the
- directory to be '/some/project/include', and the uploaded files
- will be uploaded as-if they were rooted at '/some/project/include'
- """)
- parser.add_argument('main', type=str, help=
- """The main source file.
-
- The path may be either absolute or relative to the current directory.
- """
- )
- args = parser.parse_args()
- directory = os.path.abspath(args.directory)
- if not os.path.exists(directory):
- raise Exception("'%s' is not a valid directory" % args.directory)
-
- cpp = os.path.abspath(args.main)
- if not os.path.exists(cpp):
- raise Exception("'%s' is not a valid file name" % args.main)
-
- response = upload({
- 'code': open(cpp).read(),
- 'codes': [{
- 'file': os.path.relpath(header, directory),
- #'code': strip_comments(open(header).read())
- 'code': open(header).read()
- } for header in headers(directory)],
- 'options': 'boost-nothing,c++11',
- 'compiler': 'gcc-4.9.2',
- 'save': True,
- 'compiler-option-raw': '-I.'
- })
-
- if 'status' in response and response['status'] == '0':
- print response['url']
- return 0
- else:
- print response
- return 1
-
-
-exit(main())
diff --git a/include/nlohmann/adl_serializer.hpp b/include/nlohmann/adl_serializer.hpp
index f967612..030063e 100644
--- a/include/nlohmann/adl_serializer.hpp
+++ b/include/nlohmann/adl_serializer.hpp
@@ -11,20 +11,12 @@
namespace nlohmann
{
+/// @sa https://json.nlohmann.me/api/adl_serializer/
template<typename ValueType, typename>
struct adl_serializer
{
- /*!
- @brief convert a JSON value to any value type
-
- This function is usually called by the `get()` function of the
- @ref basic_json class (either explicit or via conversion operators).
-
- @note This function is chosen for default-constructible value types.
-
- @param[in] j JSON value to read from
- @param[in,out] val value to write to
- */
+ /// @brief convert a JSON value to any value type
+ /// @sa https://json.nlohmann.me/api/adl_serializer/from_json/
template<typename BasicJsonType, typename TargetType = ValueType>
static auto from_json(BasicJsonType && j, TargetType& val) noexcept(
noexcept(::nlohmann::from_json(std::forward<BasicJsonType>(j), val)))
@@ -33,18 +25,8 @@
::nlohmann::from_json(std::forward<BasicJsonType>(j), val);
}
- /*!
- @brief convert a JSON value to any value type
-
- This function is usually called by the `get()` function of the
- @ref basic_json class (either explicit or via conversion operators).
-
- @note This function is chosen for value types which are not default-constructible.
-
- @param[in] j JSON value to read from
-
- @return copy of the JSON value, converted to @a ValueType
- */
+ /// @brief convert a JSON value to any value type
+ /// @sa https://json.nlohmann.me/api/adl_serializer/from_json/
template<typename BasicJsonType, typename TargetType = ValueType>
static auto from_json(BasicJsonType && j) noexcept(
noexcept(::nlohmann::from_json(std::forward<BasicJsonType>(j), detail::identity_tag<TargetType> {})))
@@ -53,15 +35,8 @@
return ::nlohmann::from_json(std::forward<BasicJsonType>(j), detail::identity_tag<TargetType> {});
}
- /*!
- @brief convert any value type to a JSON value
-
- This function is usually called by the constructors of the @ref basic_json
- class.
-
- @param[in,out] j JSON value to write to
- @param[in] val value to read from
- */
+ /// @brief convert any value type to a JSON value
+ /// @sa https://json.nlohmann.me/api/adl_serializer/to_json/
template<typename BasicJsonType, typename TargetType = ValueType>
static auto to_json(BasicJsonType& j, TargetType && val) noexcept(
noexcept(::nlohmann::to_json(j, std::forward<TargetType>(val))))
diff --git a/include/nlohmann/byte_container_with_subtype.hpp b/include/nlohmann/byte_container_with_subtype.hpp
index 4086e08..6e9e38d 100644
--- a/include/nlohmann/byte_container_with_subtype.hpp
+++ b/include/nlohmann/byte_container_with_subtype.hpp
@@ -7,46 +7,38 @@
namespace nlohmann
{
-/*!
-@brief an internal type for a backed binary type
-
-This type extends the template parameter @a BinaryType provided to `basic_json`
-with a subtype used by BSON and MessagePack. This type exists so that the user
-does not have to specify a type themselves with a specific naming scheme in
-order to override the binary type.
-
-@tparam BinaryType container to store bytes (`std::vector<std::uint8_t>` by
- default)
-
-@since version 3.8.0; changed type of subtypes to std::uint64_t in 3.10.0.
-*/
+/// @brief an internal type for a backed binary type
+/// @sa https://json.nlohmann.me/api/byte_container_with_subtype/
template<typename BinaryType>
class byte_container_with_subtype : public BinaryType
{
public:
- /// the type of the underlying container
using container_type = BinaryType;
- /// the type of the subtype
using subtype_type = std::uint64_t;
+ /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/byte_container_with_subtype/
byte_container_with_subtype() noexcept(noexcept(container_type()))
: container_type()
{}
+ /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/byte_container_with_subtype/
byte_container_with_subtype(const container_type& b) noexcept(noexcept(container_type(b)))
: container_type(b)
{}
+ /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/byte_container_with_subtype/
byte_container_with_subtype(container_type&& b) noexcept(noexcept(container_type(std::move(b))))
: container_type(std::move(b))
{}
+ /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/byte_container_with_subtype/
byte_container_with_subtype(const container_type& b, subtype_type subtype_) noexcept(noexcept(container_type(b)))
: container_type(b)
, m_subtype(subtype_)
, m_has_subtype(true)
{}
+ /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/byte_container_with_subtype/
byte_container_with_subtype(container_type&& b, subtype_type subtype_) noexcept(noexcept(container_type(std::move(b))))
: container_type(std::move(b))
, m_subtype(subtype_)
@@ -64,97 +56,30 @@
return !(rhs == *this);
}
- /*!
- @brief sets the binary subtype
-
- Sets the binary subtype of the value, also flags a binary JSON value as
- having a subtype, which has implications for serialization.
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this member function never throws
- exceptions.
-
- @sa see @ref subtype() -- return the binary subtype
- @sa see @ref clear_subtype() -- clears the binary subtype
- @sa see @ref has_subtype() -- returns whether or not the binary value has a
- subtype
-
- @since version 3.8.0
- */
+ /// @brief sets the binary subtype
+ /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/set_subtype/
void set_subtype(subtype_type subtype_) noexcept
{
m_subtype = subtype_;
m_has_subtype = true;
}
- /*!
- @brief return the binary subtype
-
- Returns the numerical subtype of the value if it has a subtype. If it does
- not have a subtype, this function will return subtype_type(-1) as a sentinel
- value.
-
- @return the numerical subtype of the binary value
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this member function never throws
- exceptions.
-
- @sa see @ref set_subtype() -- sets the binary subtype
- @sa see @ref clear_subtype() -- clears the binary subtype
- @sa see @ref has_subtype() -- returns whether or not the binary value has a
- subtype
-
- @since version 3.8.0; fixed return value to properly return
- subtype_type(-1) as documented in version 3.10.0
- */
+ /// @brief return the binary subtype
+ /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/subtype/
constexpr subtype_type subtype() const noexcept
{
- return m_has_subtype ? m_subtype : subtype_type(-1);
+ return m_has_subtype ? m_subtype : static_cast<subtype_type>(-1);
}
- /*!
- @brief return whether the value has a subtype
-
- @return whether the value has a subtype
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this member function never throws
- exceptions.
-
- @sa see @ref subtype() -- return the binary subtype
- @sa see @ref set_subtype() -- sets the binary subtype
- @sa see @ref clear_subtype() -- clears the binary subtype
-
- @since version 3.8.0
- */
+ /// @brief return whether the value has a subtype
+ /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/has_subtype/
constexpr bool has_subtype() const noexcept
{
return m_has_subtype;
}
- /*!
- @brief clears the binary subtype
-
- Clears the binary subtype and flags the value as not having a subtype, which
- has implications for serialization; for instance MessagePack will prefer the
- bin family over the ext family.
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this member function never throws
- exceptions.
-
- @sa see @ref subtype() -- return the binary subtype
- @sa see @ref set_subtype() -- sets the binary subtype
- @sa see @ref has_subtype() -- returns whether or not the binary value has a
- subtype
-
- @since version 3.8.0
- */
+ /// @brief clears the binary subtype
+ /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/clear_subtype/
void clear_subtype() noexcept
{
m_subtype = 0;
diff --git a/include/nlohmann/detail/conversions/from_json.hpp b/include/nlohmann/detail/conversions/from_json.hpp
index 71e32aa..207d3e3 100644
--- a/include/nlohmann/detail/conversions/from_json.hpp
+++ b/include/nlohmann/detail/conversions/from_json.hpp
@@ -19,8 +19,18 @@
#include <nlohmann/detail/meta/type_traits.hpp>
#include <nlohmann/detail/value_t.hpp>
-#ifdef JSON_HAS_CPP_17
- #include <filesystem>
+#if JSON_HAS_EXPERIMENTAL_FILESYSTEM
+#include <experimental/filesystem>
+namespace nlohmann::detail
+{
+namespace std_fs = std::experimental::filesystem;
+} // namespace nlohmann::detail
+#elif JSON_HAS_FILESYSTEM
+#include <filesystem>
+namespace nlohmann::detail
+{
+namespace std_fs = std::filesystem;
+} // namespace nlohmann::detail
#endif
namespace nlohmann
@@ -448,9 +458,9 @@
}
}
-#ifdef JSON_HAS_CPP_17
+#if JSON_HAS_FILESYSTEM || JSON_HAS_EXPERIMENTAL_FILESYSTEM
template<typename BasicJsonType>
-void from_json(const BasicJsonType& j, std::filesystem::path& p)
+void from_json(const BasicJsonType& j, std_fs::path& p)
{
if (JSON_HEDLEY_UNLIKELY(!j.is_string()))
{
diff --git a/include/nlohmann/detail/conversions/to_chars.hpp b/include/nlohmann/detail/conversions/to_chars.hpp
index 1728948..f6c729b 100644
--- a/include/nlohmann/detail/conversions/to_chars.hpp
+++ b/include/nlohmann/detail/conversions/to_chars.hpp
@@ -891,7 +891,7 @@
//
// The documentation for 'std::to_chars' (https://en.cppreference.com/w/cpp/utility/to_chars)
// says "value is converted to a string as if by std::sprintf in the default ("C") locale"
- // and since sprintf promotes float's to double's, I think this is exactly what 'std::to_chars'
+ // and since sprintf promotes floats to doubles, I think this is exactly what 'std::to_chars'
// does.
// On the other hand, the documentation for 'std::to_chars' requires that "parsing the
// representation using the corresponding std::from_chars function recovers value exactly". That
diff --git a/include/nlohmann/detail/conversions/to_json.hpp b/include/nlohmann/detail/conversions/to_json.hpp
index 79fdb32..7628ae0 100644
--- a/include/nlohmann/detail/conversions/to_json.hpp
+++ b/include/nlohmann/detail/conversions/to_json.hpp
@@ -15,8 +15,18 @@
#include <nlohmann/detail/meta/type_traits.hpp>
#include <nlohmann/detail/value_t.hpp>
-#ifdef JSON_HAS_CPP_17
- #include <filesystem>
+#if JSON_HAS_EXPERIMENTAL_FILESYSTEM
+#include <experimental/filesystem>
+namespace nlohmann::detail
+{
+namespace std_fs = std::experimental::filesystem;
+} // namespace nlohmann::detail
+#elif JSON_HAS_FILESYSTEM
+#include <filesystem>
+namespace nlohmann::detail
+{
+namespace std_fs = std::filesystem;
+} // namespace nlohmann::detail
#endif
namespace nlohmann
@@ -391,9 +401,9 @@
to_json_tuple_impl(j, t, make_index_sequence<std::tuple_size<T>::value> {});
}
-#ifdef JSON_HAS_CPP_17
+#if JSON_HAS_FILESYSTEM || JSON_HAS_EXPERIMENTAL_FILESYSTEM
template<typename BasicJsonType>
-void to_json(BasicJsonType& j, const std::filesystem::path& p)
+void to_json(BasicJsonType& j, const std_fs::path& p)
{
j = p.string();
}
diff --git a/include/nlohmann/detail/exceptions.hpp b/include/nlohmann/detail/exceptions.hpp
index 02f1b40..b4b1804 100644
--- a/include/nlohmann/detail/exceptions.hpp
+++ b/include/nlohmann/detail/exceptions.hpp
@@ -18,34 +18,8 @@
// exceptions //
////////////////
-/*!
-@brief general exception of the @ref basic_json class
-
-This class is an extension of `std::exception` objects with a member @a id for
-exception ids. It is used as the base class for all exceptions thrown by the
-@ref basic_json class. This class can hence be used as "wildcard" to catch
-exceptions.
-
-Subclasses:
-- @ref parse_error for exceptions indicating a parse error
-- @ref invalid_iterator for exceptions indicating errors with iterators
-- @ref type_error for exceptions indicating executing a member function with
- a wrong type
-- @ref out_of_range for exceptions indicating access out of the defined range
-- @ref other_error for exceptions indicating other library errors
-
-@internal
-@note To have nothrow-copy-constructible exceptions, we internally use
- `std::runtime_error` which can cope with arbitrary-length error messages.
- Intermediate strings are built with static functions and then passed to
- the actual constructor.
-@endinternal
-
-@liveexample{The following code shows how arbitrary library exceptions can be
-caught.,exception}
-
-@since version 3.0.0
-*/
+/// @brief general exception of the @ref basic_json class
+/// @sa https://json.nlohmann.me/api/basic_json/exception/
class exception : public std::exception
{
public:
@@ -60,7 +34,7 @@
protected:
JSON_HEDLEY_NON_NULL(3)
- exception(int id_, const char* what_arg) : id(id_), m(what_arg) {}
+ exception(int id_, const char* what_arg) : id(id_), m(what_arg) {} // NOLINT(bugprone-throw-keyword-missing)
static std::string name(const std::string& ename, int id_)
{
@@ -136,51 +110,8 @@
std::runtime_error m;
};
-/*!
-@brief exception indicating a parse error
-
-This exception is thrown by the library when a parse error occurs. Parse errors
-can occur during the deserialization of JSON text, CBOR, MessagePack, as well
-as when using JSON Patch.
-
-Member @a byte holds the byte index of the last read character in the input
-file.
-
-Exceptions have ids 1xx.
-
-name / id | example message | description
------------------------------- | --------------- | -------------------------
-json.exception.parse_error.101 | parse error at 2: unexpected end of input; expected string literal | This error indicates a syntax error while deserializing a JSON text. The error message describes that an unexpected token (character) was encountered, and the member @a byte indicates the error position.
-json.exception.parse_error.102 | parse error at 14: missing or wrong low surrogate | JSON uses the `\uxxxx` format to describe Unicode characters. Code points above above 0xFFFF are split into two `\uxxxx` entries ("surrogate pairs"). This error indicates that the surrogate pair is incomplete or contains an invalid code point.
-json.exception.parse_error.103 | parse error: code points above 0x10FFFF are invalid | Unicode supports code points up to 0x10FFFF. Code points above 0x10FFFF are invalid.
-json.exception.parse_error.104 | parse error: JSON patch must be an array of objects | [RFC 6902](https://tools.ietf.org/html/rfc6902) requires a JSON Patch document to be a JSON document that represents an array of objects.
-json.exception.parse_error.105 | parse error: operation must have string member 'op' | An operation of a JSON Patch document must contain exactly one "op" member, whose value indicates the operation to perform. Its value must be one of "add", "remove", "replace", "move", "copy", or "test"; other values are errors.
-json.exception.parse_error.106 | parse error: array index '01' must not begin with '0' | An array index in a JSON Pointer ([RFC 6901](https://tools.ietf.org/html/rfc6901)) may be `0` or any number without a leading `0`.
-json.exception.parse_error.107 | parse error: JSON pointer must be empty or begin with '/' - was: 'foo' | A JSON Pointer must be a Unicode string containing a sequence of zero or more reference tokens, each prefixed by a `/` character.
-json.exception.parse_error.108 | parse error: escape character '~' must be followed with '0' or '1' | In a JSON Pointer, only `~0` and `~1` are valid escape sequences.
-json.exception.parse_error.109 | parse error: array index 'one' is not a number | A JSON Pointer array index must be a number.
-json.exception.parse_error.110 | parse error at 1: cannot read 2 bytes from vector | When parsing CBOR or MessagePack, the byte vector ends before the complete value has been read.
-json.exception.parse_error.112 | parse error at 1: error reading CBOR; last byte: 0xF8 | Not all types of CBOR or MessagePack are supported. This exception occurs if an unsupported byte was read.
-json.exception.parse_error.113 | parse error at 2: expected a CBOR string; last byte: 0x98 | While parsing a map key, a value that is not a string has been read.
-json.exception.parse_error.114 | parse error: Unsupported BSON record type 0x0F | The parsing of the corresponding BSON record type is not implemented (yet).
-json.exception.parse_error.115 | parse error at byte 5: syntax error while parsing UBJSON high-precision number: invalid number text: 1A | A UBJSON high-precision number could not be parsed.
-
-@note For an input with n bytes, 1 is the index of the first character and n+1
- is the index of the terminating null byte or the end of file. This also
- holds true when reading a byte vector (CBOR or MessagePack).
-
-@liveexample{The following code shows how a `parse_error` exception can be
-caught.,parse_error}
-
-@sa - @ref exception for the base class of the library exceptions
-@sa - @ref invalid_iterator for exceptions indicating errors with iterators
-@sa - @ref type_error for exceptions indicating executing a member function with
- a wrong type
-@sa - @ref out_of_range for exceptions indicating access out of the defined range
-@sa - @ref other_error for exceptions indicating other library errors
-
-@since version 3.0.0
-*/
+/// @brief exception indicating a parse error
+/// @sa https://json.nlohmann.me/api/basic_json/parse_error/
class parse_error : public exception
{
public:
@@ -198,7 +129,7 @@
{
std::string w = exception::name("parse_error", id_) + "parse error" +
position_string(pos) + ": " + exception::diagnostics(context) + what_arg;
- return parse_error(id_, pos.chars_read_total, w.c_str());
+ return {id_, pos.chars_read_total, w.c_str()};
}
template<typename BasicJsonType>
@@ -207,7 +138,7 @@
std::string w = exception::name("parse_error", id_) + "parse error" +
(byte_ != 0 ? (" at byte " + std::to_string(byte_)) : "") +
": " + exception::diagnostics(context) + what_arg;
- return parse_error(id_, byte_, w.c_str());
+ return {id_, byte_, w.c_str()};
}
/*!
@@ -232,43 +163,8 @@
}
};
-/*!
-@brief exception indicating errors with iterators
-
-This exception is thrown if iterators passed to a library function do not match
-the expected semantics.
-
-Exceptions have ids 2xx.
-
-name / id | example message | description
------------------------------------ | --------------- | -------------------------
-json.exception.invalid_iterator.201 | iterators are not compatible | The iterators passed to constructor @ref basic_json(InputIT first, InputIT last) are not compatible, meaning they do not belong to the same container. Therefore, the range (@a first, @a last) is invalid.
-json.exception.invalid_iterator.202 | iterator does not fit current value | In an erase or insert function, the passed iterator @a pos does not belong to the JSON value for which the function was called. It hence does not define a valid position for the deletion/insertion.
-json.exception.invalid_iterator.203 | iterators do not fit current value | Either iterator passed to function @ref erase(IteratorType first, IteratorType last) does not belong to the JSON value from which values shall be erased. It hence does not define a valid range to delete values from.
-json.exception.invalid_iterator.204 | iterators out of range | When an iterator range for a primitive type (number, boolean, or string) is passed to a constructor or an erase function, this range has to be exactly (@ref begin(), @ref end()), because this is the only way the single stored value is expressed. All other ranges are invalid.
-json.exception.invalid_iterator.205 | iterator out of range | When an iterator for a primitive type (number, boolean, or string) is passed to an erase function, the iterator has to be the @ref begin() iterator, because it is the only way to address the stored value. All other iterators are invalid.
-json.exception.invalid_iterator.206 | cannot construct with iterators from null | The iterators passed to constructor @ref basic_json(InputIT first, InputIT last) belong to a JSON null value and hence to not define a valid range.
-json.exception.invalid_iterator.207 | cannot use key() for non-object iterators | The key() member function can only be used on iterators belonging to a JSON object, because other types do not have a concept of a key.
-json.exception.invalid_iterator.208 | cannot use operator[] for object iterators | The operator[] to specify a concrete offset cannot be used on iterators belonging to a JSON object, because JSON objects are unordered.
-json.exception.invalid_iterator.209 | cannot use offsets with object iterators | The offset operators (+, -, +=, -=) cannot be used on iterators belonging to a JSON object, because JSON objects are unordered.
-json.exception.invalid_iterator.210 | iterators do not fit | The iterator range passed to the insert function are not compatible, meaning they do not belong to the same container. Therefore, the range (@a first, @a last) is invalid.
-json.exception.invalid_iterator.211 | passed iterators may not belong to container | The iterator range passed to the insert function must not be a subrange of the container to insert to.
-json.exception.invalid_iterator.212 | cannot compare iterators of different containers | When two iterators are compared, they must belong to the same container.
-json.exception.invalid_iterator.213 | cannot compare order of object iterators | The order of object iterators cannot be compared, because JSON objects are unordered.
-json.exception.invalid_iterator.214 | cannot get value | Cannot get value for iterator: Either the iterator belongs to a null value or it is an iterator to a primitive type (number, boolean, or string), but the iterator is different to @ref begin().
-
-@liveexample{The following code shows how an `invalid_iterator` exception can be
-caught.,invalid_iterator}
-
-@sa - @ref exception for the base class of the library exceptions
-@sa - @ref parse_error for exceptions indicating a parse error
-@sa - @ref type_error for exceptions indicating executing a member function with
- a wrong type
-@sa - @ref out_of_range for exceptions indicating access out of the defined range
-@sa - @ref other_error for exceptions indicating other library errors
-
-@since version 3.0.0
-*/
+/// @brief exception indicating errors with iterators
+/// @sa https://json.nlohmann.me/api/basic_json/invalid_iterator/
class invalid_iterator : public exception
{
public:
@@ -276,7 +172,7 @@
static invalid_iterator create(int id_, const std::string& what_arg, const BasicJsonType& context)
{
std::string w = exception::name("invalid_iterator", id_) + exception::diagnostics(context) + what_arg;
- return invalid_iterator(id_, w.c_str());
+ return {id_, w.c_str()};
}
private:
@@ -285,45 +181,8 @@
: exception(id_, what_arg) {}
};
-/*!
-@brief exception indicating executing a member function with a wrong type
-
-This exception is thrown in case of a type error; that is, a library function is
-executed on a JSON value whose type does not match the expected semantics.
-
-Exceptions have ids 3xx.
-
-name / id | example message | description
------------------------------ | --------------- | -------------------------
-json.exception.type_error.301 | cannot create object from initializer list | To create an object from an initializer list, the initializer list must consist only of a list of pairs whose first element is a string. When this constraint is violated, an array is created instead.
-json.exception.type_error.302 | type must be object, but is array | During implicit or explicit value conversion, the JSON type must be compatible to the target type. For instance, a JSON string can only be converted into string types, but not into numbers or boolean types.
-json.exception.type_error.303 | incompatible ReferenceType for get_ref, actual type is object | To retrieve a reference to a value stored in a @ref basic_json object with @ref get_ref, the type of the reference must match the value type. For instance, for a JSON array, the @a ReferenceType must be @ref array_t &.
-json.exception.type_error.304 | cannot use at() with string | The @ref at() member functions can only be executed for certain JSON types.
-json.exception.type_error.305 | cannot use operator[] with string | The @ref operator[] member functions can only be executed for certain JSON types.
-json.exception.type_error.306 | cannot use value() with string | The @ref value() member functions can only be executed for certain JSON types.
-json.exception.type_error.307 | cannot use erase() with string | The @ref erase() member functions can only be executed for certain JSON types.
-json.exception.type_error.308 | cannot use push_back() with string | The @ref push_back() and @ref operator+= member functions can only be executed for certain JSON types.
-json.exception.type_error.309 | cannot use insert() with | The @ref insert() member functions can only be executed for certain JSON types.
-json.exception.type_error.310 | cannot use swap() with number | The @ref swap() member functions can only be executed for certain JSON types.
-json.exception.type_error.311 | cannot use emplace_back() with string | The @ref emplace_back() member function can only be executed for certain JSON types.
-json.exception.type_error.312 | cannot use update() with string | The @ref update() member functions can only be executed for certain JSON types.
-json.exception.type_error.313 | invalid value to unflatten | The @ref unflatten function converts an object whose keys are JSON Pointers back into an arbitrary nested JSON value. The JSON Pointers must not overlap, because then the resulting value would not be well defined.
-json.exception.type_error.314 | only objects can be unflattened | The @ref unflatten function only works for an object whose keys are JSON Pointers.
-json.exception.type_error.315 | values in object must be primitive | The @ref unflatten function only works for an object whose keys are JSON Pointers and whose values are primitive.
-json.exception.type_error.316 | invalid UTF-8 byte at index 10: 0x7E | The @ref dump function only works with UTF-8 encoded strings; that is, if you assign a `std::string` to a JSON value, make sure it is UTF-8 encoded. |
-json.exception.type_error.317 | JSON value cannot be serialized to requested format | The dynamic type of the object cannot be represented in the requested serialization format (e.g. a raw `true` or `null` JSON object cannot be serialized to BSON) |
-
-@liveexample{The following code shows how a `type_error` exception can be
-caught.,type_error}
-
-@sa - @ref exception for the base class of the library exceptions
-@sa - @ref parse_error for exceptions indicating a parse error
-@sa - @ref invalid_iterator for exceptions indicating errors with iterators
-@sa - @ref out_of_range for exceptions indicating access out of the defined range
-@sa - @ref other_error for exceptions indicating other library errors
-
-@since version 3.0.0
-*/
+/// @brief exception indicating executing a member function with a wrong type
+/// @sa https://json.nlohmann.me/api/basic_json/type_error/
class type_error : public exception
{
public:
@@ -331,7 +190,7 @@
static type_error create(int id_, const std::string& what_arg, const BasicJsonType& context)
{
std::string w = exception::name("type_error", id_) + exception::diagnostics(context) + what_arg;
- return type_error(id_, w.c_str());
+ return {id_, w.c_str()};
}
private:
@@ -339,39 +198,8 @@
type_error(int id_, const char* what_arg) : exception(id_, what_arg) {}
};
-/*!
-@brief exception indicating access out of the defined range
-
-This exception is thrown in case a library function is called on an input
-parameter that exceeds the expected range, for instance in case of array
-indices or nonexisting object keys.
-
-Exceptions have ids 4xx.
-
-name / id | example message | description
-------------------------------- | --------------- | -------------------------
-json.exception.out_of_range.401 | array index 3 is out of range | The provided array index @a i is larger than @a size-1.
-json.exception.out_of_range.402 | array index '-' (3) is out of range | The special array index `-` in a JSON Pointer never describes a valid element of the array, but the index past the end. That is, it can only be used to add elements at this position, but not to read it.
-json.exception.out_of_range.403 | key 'foo' not found | The provided key was not found in the JSON object.
-json.exception.out_of_range.404 | unresolved reference token 'foo' | A reference token in a JSON Pointer could not be resolved.
-json.exception.out_of_range.405 | JSON pointer has no parent | The JSON Patch operations 'remove' and 'add' can not be applied to the root element of the JSON value.
-json.exception.out_of_range.406 | number overflow parsing '10E1000' | A parsed number could not be stored as without changing it to NaN or INF.
-json.exception.out_of_range.407 | number overflow serializing '9223372036854775808' | UBJSON and BSON only support integer numbers up to 9223372036854775807. (until version 3.8.0) |
-json.exception.out_of_range.408 | excessive array size: 8658170730974374167 | The size (following `#`) of an UBJSON array or object exceeds the maximal capacity. |
-json.exception.out_of_range.409 | BSON key cannot contain code point U+0000 (at byte 2) | Key identifiers to be serialized to BSON cannot contain code point U+0000, since the key is stored as zero-terminated c-string |
-
-@liveexample{The following code shows how an `out_of_range` exception can be
-caught.,out_of_range}
-
-@sa - @ref exception for the base class of the library exceptions
-@sa - @ref parse_error for exceptions indicating a parse error
-@sa - @ref invalid_iterator for exceptions indicating errors with iterators
-@sa - @ref type_error for exceptions indicating executing a member function with
- a wrong type
-@sa - @ref other_error for exceptions indicating other library errors
-
-@since version 3.0.0
-*/
+/// @brief exception indicating access out of the defined range
+/// @sa https://json.nlohmann.me/api/basic_json/out_of_range/
class out_of_range : public exception
{
public:
@@ -379,7 +207,7 @@
static out_of_range create(int id_, const std::string& what_arg, const BasicJsonType& context)
{
std::string w = exception::name("out_of_range", id_) + exception::diagnostics(context) + what_arg;
- return out_of_range(id_, w.c_str());
+ return {id_, w.c_str()};
}
private:
@@ -387,30 +215,8 @@
out_of_range(int id_, const char* what_arg) : exception(id_, what_arg) {}
};
-/*!
-@brief exception indicating other library errors
-
-This exception is thrown in case of errors that cannot be classified with the
-other exception types.
-
-Exceptions have ids 5xx.
-
-name / id | example message | description
------------------------------- | --------------- | -------------------------
-json.exception.other_error.501 | unsuccessful: {"op":"test","path":"/baz", "value":"bar"} | A JSON Patch operation 'test' failed. The unsuccessful operation is also printed.
-
-@sa - @ref exception for the base class of the library exceptions
-@sa - @ref parse_error for exceptions indicating a parse error
-@sa - @ref invalid_iterator for exceptions indicating errors with iterators
-@sa - @ref type_error for exceptions indicating executing a member function with
- a wrong type
-@sa - @ref out_of_range for exceptions indicating access out of the defined range
-
-@liveexample{The following code shows how an `other_error` exception can be
-caught.,other_error}
-
-@since version 3.0.0
-*/
+/// @brief exception indicating other library errors
+/// @sa https://json.nlohmann.me/api/basic_json/other_error/
class other_error : public exception
{
public:
@@ -418,12 +224,13 @@
static other_error create(int id_, const std::string& what_arg, const BasicJsonType& context)
{
std::string w = exception::name("other_error", id_) + exception::diagnostics(context) + what_arg;
- return other_error(id_, w.c_str());
+ return {id_, w.c_str()};
}
private:
JSON_HEDLEY_NON_NULL(3)
other_error(int id_, const char* what_arg) : exception(id_, what_arg) {}
};
+
} // namespace detail
} // namespace nlohmann
diff --git a/include/nlohmann/detail/input/binary_reader.hpp b/include/nlohmann/detail/input/binary_reader.hpp
index f1b65ba..65e0047 100644
--- a/include/nlohmann/detail/input/binary_reader.hpp
+++ b/include/nlohmann/detail/input/binary_reader.hpp
@@ -42,7 +42,7 @@
@note from https://stackoverflow.com/a/1001328/266378
*/
-static inline bool little_endianess(int num = 1) noexcept
+static inline bool little_endianness(int num = 1) noexcept
{
return *reinterpret_cast<char*>(&num) == 1;
}
@@ -161,7 +161,7 @@
std::int32_t document_size{};
get_number<std::int32_t, true>(input_format_t::bson, document_size);
- if (JSON_HEDLEY_UNLIKELY(!sax->start_object(std::size_t(-1))))
+ if (JSON_HEDLEY_UNLIKELY(!sax->start_object(static_cast<std::size_t>(-1))))
{
return false;
}
@@ -318,7 +318,7 @@
default: // anything else not supported (yet)
{
std::array<char, 3> cr{{}};
- (std::snprintf)(cr.data(), cr.size(), "%.2hhX", static_cast<unsigned char>(element_type)); // NOLINT(cppcoreguidelines-pro-type-vararg,hicpp-vararg)
+ static_cast<void>((std::snprintf)(cr.data(), cr.size(), "%.2hhX", static_cast<unsigned char>(element_type))); // NOLINT(cppcoreguidelines-pro-type-vararg,hicpp-vararg)
return sax->parse_error(element_type_parse_position, std::string(cr.data()), parse_error::create(114, element_type_parse_position, "Unsupported BSON record type 0x" + std::string(cr.data()), BasicJsonType()));
}
}
@@ -379,7 +379,7 @@
std::int32_t document_size{};
get_number<std::int32_t, true>(input_format_t::bson, document_size);
- if (JSON_HEDLEY_UNLIKELY(!sax->start_array(std::size_t(-1))))
+ if (JSON_HEDLEY_UNLIKELY(!sax->start_array(static_cast<std::size_t>(-1))))
{
return false;
}
@@ -638,7 +638,7 @@
}
case 0x9F: // array (indefinite length)
- return get_cbor_array(std::size_t(-1), tag_handler);
+ return get_cbor_array(static_cast<std::size_t>(-1), tag_handler);
// map (0x00..0x17 pairs of data items follow)
case 0xA0:
@@ -692,7 +692,7 @@
}
case 0xBF: // map (indefinite length)
- return get_cbor_object(std::size_t(-1), tag_handler);
+ return get_cbor_object(static_cast<std::size_t>(-1), tag_handler);
case 0xC6: // tagged item
case 0xC7:
@@ -1076,7 +1076,7 @@
}
/*!
- @param[in] len the length of the array or std::size_t(-1) for an
+ @param[in] len the length of the array or static_cast<std::size_t>(-1) for an
array of indefinite size
@param[in] tag_handler how CBOR tags should be treated
@return whether array creation completed
@@ -1089,7 +1089,7 @@
return false;
}
- if (len != std::size_t(-1))
+ if (len != static_cast<std::size_t>(-1))
{
for (std::size_t i = 0; i < len; ++i)
{
@@ -1114,7 +1114,7 @@
}
/*!
- @param[in] len the length of the object or std::size_t(-1) for an
+ @param[in] len the length of the object or static_cast<std::size_t>(-1) for an
object of indefinite size
@param[in] tag_handler how CBOR tags should be treated
@return whether object creation completed
@@ -1130,7 +1130,7 @@
if (len != 0)
{
string_t key;
- if (len != std::size_t(-1))
+ if (len != static_cast<std::size_t>(-1))
{
for (std::size_t i = 0; i < len; ++i)
{
@@ -2140,7 +2140,7 @@
}
else
{
- if (JSON_HEDLEY_UNLIKELY(!sax->start_array(std::size_t(-1))))
+ if (JSON_HEDLEY_UNLIKELY(!sax->start_array(static_cast<std::size_t>(-1))))
{
return false;
}
@@ -2210,7 +2210,7 @@
}
else
{
- if (JSON_HEDLEY_UNLIKELY(!sax->start_object(std::size_t(-1))))
+ if (JSON_HEDLEY_UNLIKELY(!sax->start_object(static_cast<std::size_t>(-1))))
{
return false;
}
@@ -2341,7 +2341,7 @@
@return whether conversion completed
- @note This function needs to respect the system's endianess, because
+ @note This function needs to respect the system's endianness, because
bytes in CBOR, MessagePack, and UBJSON are stored in network order
(big endian) and therefore need reordering on little endian systems.
*/
@@ -2462,7 +2462,7 @@
std::string get_token_string() const
{
std::array<char, 3> cr{{}};
- (std::snprintf)(cr.data(), cr.size(), "%.2hhX", static_cast<unsigned char>(current)); // NOLINT(cppcoreguidelines-pro-type-vararg,hicpp-vararg)
+ static_cast<void>((std::snprintf)(cr.data(), cr.size(), "%.2hhX", static_cast<unsigned char>(current))); // NOLINT(cppcoreguidelines-pro-type-vararg,hicpp-vararg)
return std::string{cr.data()};
}
@@ -2514,8 +2514,8 @@
/// the number of characters read
std::size_t chars_read = 0;
- /// whether we can assume little endianess
- const bool is_little_endian = little_endianess();
+ /// whether we can assume little endianness
+ const bool is_little_endian = little_endianness();
/// the SAX parser
json_sax_t* sax = nullptr;
diff --git a/include/nlohmann/detail/input/input_adapters.hpp b/include/nlohmann/detail/input/input_adapters.hpp
index 6df58a1..d196aec 100644
--- a/include/nlohmann/detail/input/input_adapters.hpp
+++ b/include/nlohmann/detail/input/input_adapters.hpp
@@ -104,7 +104,7 @@
// std::istream/std::streambuf use std::char_traits<char>::to_int_type, to
// ensure that std::char_traits<char>::eof() and the character 0xFF do not
- // end up as the same value, eg. 0xFFFFFFFF.
+ // end up as the same value, e.g. 0xFFFFFFFF.
std::char_traits<char>::int_type get_character()
{
auto res = sb->sbumpc();
@@ -450,7 +450,7 @@
}
// This class only handles inputs of input_buffer_adapter type.
-// It's required so that expressions like {ptr, len} can be implicitely casted
+// It's required so that expressions like {ptr, len} can be implicitly cast
// to the correct adapter.
class span_input_adapter
{
diff --git a/include/nlohmann/detail/input/json_sax.hpp b/include/nlohmann/detail/input/json_sax.hpp
index 67278f8..fd9dab8 100644
--- a/include/nlohmann/detail/input/json_sax.hpp
+++ b/include/nlohmann/detail/input/json_sax.hpp
@@ -56,7 +56,7 @@
virtual bool number_unsigned(number_unsigned_t val) = 0;
/*!
- @brief an floating-point number was read
+ @brief a floating-point number was read
@param[in] val floating-point value
@param[in] s raw token value
@return whether parsing should proceed
@@ -64,18 +64,18 @@
virtual bool number_float(number_float_t val, const string_t& s) = 0;
/*!
- @brief a string was read
+ @brief a string value was read
@param[in] val string value
@return whether parsing should proceed
- @note It is safe to move the passed string.
+ @note It is safe to move the passed string value.
*/
virtual bool string(string_t& val) = 0;
/*!
- @brief a binary string was read
+ @brief a binary value was read
@param[in] val binary value
@return whether parsing should proceed
- @note It is safe to move the passed binary.
+ @note It is safe to move the passed binary value.
*/
virtual bool binary(binary_t& val) = 0;
@@ -222,7 +222,7 @@
{
ref_stack.push_back(handle_value(BasicJsonType::value_t::object));
- if (JSON_HEDLEY_UNLIKELY(len != std::size_t(-1) && len > ref_stack.back()->max_size()))
+ if (JSON_HEDLEY_UNLIKELY(len != static_cast<std::size_t>(-1) && len > ref_stack.back()->max_size()))
{
JSON_THROW(out_of_range::create(408, "excessive object size: " + std::to_string(len), *ref_stack.back()));
}
@@ -248,7 +248,7 @@
{
ref_stack.push_back(handle_value(BasicJsonType::value_t::array));
- if (JSON_HEDLEY_UNLIKELY(len != std::size_t(-1) && len > ref_stack.back()->max_size()))
+ if (JSON_HEDLEY_UNLIKELY(len != static_cast<std::size_t>(-1) && len > ref_stack.back()->max_size()))
{
JSON_THROW(out_of_range::create(408, "excessive array size: " + std::to_string(len), *ref_stack.back()));
}
@@ -403,7 +403,7 @@
ref_stack.push_back(val.second);
// check object limit
- if (ref_stack.back() && JSON_HEDLEY_UNLIKELY(len != std::size_t(-1) && len > ref_stack.back()->max_size()))
+ if (ref_stack.back() && JSON_HEDLEY_UNLIKELY(len != static_cast<std::size_t>(-1) && len > ref_stack.back()->max_size()))
{
JSON_THROW(out_of_range::create(408, "excessive object size: " + std::to_string(len), *ref_stack.back()));
}
@@ -473,7 +473,7 @@
ref_stack.push_back(val.second);
// check array limit
- if (ref_stack.back() && JSON_HEDLEY_UNLIKELY(len != std::size_t(-1) && len > ref_stack.back()->max_size()))
+ if (ref_stack.back() && JSON_HEDLEY_UNLIKELY(len != static_cast<std::size_t>(-1) && len > ref_stack.back()->max_size()))
{
JSON_THROW(out_of_range::create(408, "excessive array size: " + std::to_string(len), *ref_stack.back()));
}
@@ -676,7 +676,7 @@
return true;
}
- bool start_object(std::size_t /*unused*/ = std::size_t(-1))
+ bool start_object(std::size_t /*unused*/ = static_cast<std::size_t>(-1))
{
return true;
}
@@ -691,7 +691,7 @@
return true;
}
- bool start_array(std::size_t /*unused*/ = std::size_t(-1))
+ bool start_array(std::size_t /*unused*/ = static_cast<std::size_t>(-1))
{
return true;
}
diff --git a/include/nlohmann/detail/input/lexer.hpp b/include/nlohmann/detail/input/lexer.hpp
index 3a47167..d0c063a 100644
--- a/include/nlohmann/detail/input/lexer.hpp
+++ b/include/nlohmann/detail/input/lexer.hpp
@@ -343,7 +343,7 @@
// low surrogate occupies the least significant 15 bits
+ static_cast<unsigned int>(codepoint2)
// there is still the 0xD800, 0xDC00 and 0x10000 noise
- // in the result so we have to subtract with:
+ // in the result, so we have to subtract with:
// (0xD800 << 10) + DC00 - 0x10000 = 0x35FDC00
- 0x35FDC00u);
}
@@ -1447,7 +1447,7 @@
{
// escape control characters
std::array<char, 9> cs{{}};
- (std::snprintf)(cs.data(), cs.size(), "<U+%.4X>", static_cast<unsigned char>(c)); // NOLINT(cppcoreguidelines-pro-type-vararg,hicpp-vararg)
+ static_cast<void>((std::snprintf)(cs.data(), cs.size(), "<U+%.4X>", static_cast<unsigned char>(c))); // NOLINT(cppcoreguidelines-pro-type-vararg,hicpp-vararg)
result += cs.data();
}
else
@@ -1541,17 +1541,17 @@
// literals
case 't':
{
- std::array<char_type, 4> true_literal = {{char_type('t'), char_type('r'), char_type('u'), char_type('e')}};
+ std::array<char_type, 4> true_literal = {{static_cast<char_type>('t'), static_cast<char_type>('r'), static_cast<char_type>('u'), static_cast<char_type>('e')}};
return scan_literal(true_literal.data(), true_literal.size(), token_type::literal_true);
}
case 'f':
{
- std::array<char_type, 5> false_literal = {{char_type('f'), char_type('a'), char_type('l'), char_type('s'), char_type('e')}};
+ std::array<char_type, 5> false_literal = {{static_cast<char_type>('f'), static_cast<char_type>('a'), static_cast<char_type>('l'), static_cast<char_type>('s'), static_cast<char_type>('e')}};
return scan_literal(false_literal.data(), false_literal.size(), token_type::literal_false);
}
case 'n':
{
- std::array<char_type, 4> null_literal = {{char_type('n'), char_type('u'), char_type('l'), char_type('l')}};
+ std::array<char_type, 4> null_literal = {{static_cast<char_type>('n'), static_cast<char_type>('u'), static_cast<char_type>('l'), static_cast<char_type>('l')}};
return scan_literal(null_literal.data(), null_literal.size(), token_type::literal_null);
}
diff --git a/include/nlohmann/detail/input/parser.hpp b/include/nlohmann/detail/input/parser.hpp
index 99cdd05..024dd04 100644
--- a/include/nlohmann/detail/input/parser.hpp
+++ b/include/nlohmann/detail/input/parser.hpp
@@ -186,7 +186,7 @@
{
case token_type::begin_object:
{
- if (JSON_HEDLEY_UNLIKELY(!sax->start_object(std::size_t(-1))))
+ if (JSON_HEDLEY_UNLIKELY(!sax->start_object(static_cast<std::size_t>(-1))))
{
return false;
}
@@ -231,7 +231,7 @@
case token_type::begin_array:
{
- if (JSON_HEDLEY_UNLIKELY(!sax->start_array(std::size_t(-1))))
+ if (JSON_HEDLEY_UNLIKELY(!sax->start_array(static_cast<std::size_t>(-1))))
{
return false;
}
diff --git a/include/nlohmann/detail/iterators/iter_impl.hpp b/include/nlohmann/detail/iterators/iter_impl.hpp
index aaff2b6..434a62d 100644
--- a/include/nlohmann/detail/iterators/iter_impl.hpp
+++ b/include/nlohmann/detail/iterators/iter_impl.hpp
@@ -36,7 +36,7 @@
iterators in version 3.0.0 (see https://github.com/nlohmann/json/issues/593)
*/
template<typename BasicJsonType>
-class iter_impl
+class iter_impl // NOLINT(cppcoreguidelines-special-member-functions,hicpp-special-member-functions)
{
/// the iterator with BasicJsonType of different const-ness
using other_iter_impl = iter_impl<typename std::conditional<std::is_const<BasicJsonType>::value, typename std::remove_const<BasicJsonType>::type, const BasicJsonType>::type>;
diff --git a/include/nlohmann/detail/json_pointer.hpp b/include/nlohmann/detail/json_pointer.hpp
index d727ecc..caed67c 100644
--- a/include/nlohmann/detail/json_pointer.hpp
+++ b/include/nlohmann/detail/json_pointer.hpp
@@ -15,6 +15,9 @@
namespace nlohmann
{
+
+/// @brief JSON Pointer defines a string syntax for identifying a specific value within a JSON document
+/// @sa https://json.nlohmann.me/api/json_pointer/
template<typename BasicJsonType>
class json_pointer
{
@@ -23,45 +26,14 @@
friend class basic_json;
public:
- /*!
- @brief create JSON pointer
-
- Create a JSON pointer according to the syntax described in
- [Section 3 of RFC6901](https://tools.ietf.org/html/rfc6901#section-3).
-
- @param[in] s string representing the JSON pointer; if omitted, the empty
- string is assumed which references the whole JSON value
-
- @throw parse_error.107 if the given JSON pointer @a s is nonempty and does
- not begin with a slash (`/`); see example below
-
- @throw parse_error.108 if a tilde (`~`) in the given JSON pointer @a s is
- not followed by `0` (representing `~`) or `1` (representing `/`); see
- example below
-
- @liveexample{The example shows the construction several valid JSON pointers
- as well as the exceptional behavior.,json_pointer}
-
- @since version 2.0.0
- */
+ /// @brief create JSON pointer
+ /// @sa https://json.nlohmann.me/api/json_pointer/json_pointer/
explicit json_pointer(const std::string& s = "")
: reference_tokens(split(s))
{}
- /*!
- @brief return a string representation of the JSON pointer
-
- @invariant For each JSON pointer `ptr`, it holds:
- @code {.cpp}
- ptr == json_pointer(ptr.to_string());
- @endcode
-
- @return a string representation of the JSON pointer
-
- @liveexample{The example shows the result of `to_string`.,json_pointer__to_string}
-
- @since version 2.0.0
- */
+ /// @brief return a string representation of the JSON pointer
+ /// @sa https://json.nlohmann.me/api/json_pointer/to_string/
std::string to_string() const
{
return std::accumulate(reference_tokens.begin(), reference_tokens.end(),
@@ -72,28 +44,15 @@
});
}
- /// @copydoc to_string()
+ /// @brief return a string representation of the JSON pointer
+ /// @sa https://json.nlohmann.me/api/json_pointer/operator_string/
operator std::string() const
{
return to_string();
}
- /*!
- @brief append another JSON pointer at the end of this JSON pointer
-
- @param[in] ptr JSON pointer to append
- @return JSON pointer with @a ptr appended
-
- @liveexample{The example shows the usage of `operator/=`.,json_pointer__operator_add}
-
- @complexity Linear in the length of @a ptr.
-
- @sa see @ref operator/=(std::string) to append a reference token
- @sa see @ref operator/=(std::size_t) to append an array index
- @sa see @ref operator/(const json_pointer&, const json_pointer&) for a binary operator
-
- @since version 3.6.0
- */
+ /// @brief append another JSON pointer at the end of this JSON pointer
+ /// @sa https://json.nlohmann.me/api/json_pointer/operator_slasheq/
json_pointer& operator/=(const json_pointer& ptr)
{
reference_tokens.insert(reference_tokens.end(),
@@ -102,123 +61,45 @@
return *this;
}
- /*!
- @brief append an unescaped reference token at the end of this JSON pointer
-
- @param[in] token reference token to append
- @return JSON pointer with @a token appended without escaping @a token
-
- @liveexample{The example shows the usage of `operator/=`.,json_pointer__operator_add}
-
- @complexity Amortized constant.
-
- @sa see @ref operator/=(const json_pointer&) to append a JSON pointer
- @sa see @ref operator/=(std::size_t) to append an array index
- @sa see @ref operator/(const json_pointer&, std::size_t) for a binary operator
-
- @since version 3.6.0
- */
+ /// @brief append an unescaped reference token at the end of this JSON pointer
+ /// @sa https://json.nlohmann.me/api/json_pointer/operator_slasheq/
json_pointer& operator/=(std::string token)
{
push_back(std::move(token));
return *this;
}
- /*!
- @brief append an array index at the end of this JSON pointer
-
- @param[in] array_idx array index to append
- @return JSON pointer with @a array_idx appended
-
- @liveexample{The example shows the usage of `operator/=`.,json_pointer__operator_add}
-
- @complexity Amortized constant.
-
- @sa see @ref operator/=(const json_pointer&) to append a JSON pointer
- @sa see @ref operator/=(std::string) to append a reference token
- @sa see @ref operator/(const json_pointer&, std::string) for a binary operator
-
- @since version 3.6.0
- */
+ /// @brief append an array index at the end of this JSON pointer
+ /// @sa https://json.nlohmann.me/api/json_pointer/operator_slasheq/
json_pointer& operator/=(std::size_t array_idx)
{
return *this /= std::to_string(array_idx);
}
- /*!
- @brief create a new JSON pointer by appending the right JSON pointer at the end of the left JSON pointer
-
- @param[in] lhs JSON pointer
- @param[in] rhs JSON pointer
- @return a new JSON pointer with @a rhs appended to @a lhs
-
- @liveexample{The example shows the usage of `operator/`.,json_pointer__operator_add_binary}
-
- @complexity Linear in the length of @a lhs and @a rhs.
-
- @sa see @ref operator/=(const json_pointer&) to append a JSON pointer
-
- @since version 3.6.0
- */
+ /// @brief create a new JSON pointer by appending the right JSON pointer at the end of the left JSON pointer
+ /// @sa https://json.nlohmann.me/api/json_pointer/operator_slash/
friend json_pointer operator/(const json_pointer& lhs,
const json_pointer& rhs)
{
return json_pointer(lhs) /= rhs;
}
- /*!
- @brief create a new JSON pointer by appending the unescaped token at the end of the JSON pointer
-
- @param[in] ptr JSON pointer
- @param[in] token reference token
- @return a new JSON pointer with unescaped @a token appended to @a ptr
-
- @liveexample{The example shows the usage of `operator/`.,json_pointer__operator_add_binary}
-
- @complexity Linear in the length of @a ptr.
-
- @sa see @ref operator/=(std::string) to append a reference token
-
- @since version 3.6.0
- */
- friend json_pointer operator/(const json_pointer& ptr, std::string token) // NOLINT(performance-unnecessary-value-param)
+ /// @brief create a new JSON pointer by appending the unescaped token at the end of the JSON pointer
+ /// @sa https://json.nlohmann.me/api/json_pointer/operator_slash/
+ friend json_pointer operator/(const json_pointer& lhs, std::string token) // NOLINT(performance-unnecessary-value-param)
{
- return json_pointer(ptr) /= std::move(token);
+ return json_pointer(lhs) /= std::move(token);
}
- /*!
- @brief create a new JSON pointer by appending the array-index-token at the end of the JSON pointer
-
- @param[in] ptr JSON pointer
- @param[in] array_idx array index
- @return a new JSON pointer with @a array_idx appended to @a ptr
-
- @liveexample{The example shows the usage of `operator/`.,json_pointer__operator_add_binary}
-
- @complexity Linear in the length of @a ptr.
-
- @sa see @ref operator/=(std::size_t) to append an array index
-
- @since version 3.6.0
- */
- friend json_pointer operator/(const json_pointer& ptr, std::size_t array_idx)
+ /// @brief create a new JSON pointer by appending the array-index-token at the end of the JSON pointer
+ /// @sa https://json.nlohmann.me/api/json_pointer/operator_slash/
+ friend json_pointer operator/(const json_pointer& lhs, std::size_t array_idx)
{
- return json_pointer(ptr) /= array_idx;
+ return json_pointer(lhs) /= array_idx;
}
- /*!
- @brief returns the parent of this JSON pointer
-
- @return parent of this JSON pointer; in case this JSON pointer is the root,
- the root itself is returned
-
- @complexity Linear in the length of the JSON pointer.
-
- @liveexample{The example shows the result of `parent_pointer` for different
- JSON Pointers.,json_pointer__parent_pointer}
-
- @since version 3.6.0
- */
+ /// @brief returns the parent of this JSON pointer
+ /// @sa https://json.nlohmann.me/api/json_pointer/parent_pointer/
json_pointer parent_pointer() const
{
if (empty())
@@ -231,19 +112,8 @@
return res;
}
- /*!
- @brief remove last reference token
-
- @pre not `empty()`
-
- @liveexample{The example shows the usage of `pop_back`.,json_pointer__pop_back}
-
- @complexity Constant.
-
- @throw out_of_range.405 if JSON pointer has no parent
-
- @since version 3.6.0
- */
+ /// @brief remove last reference token
+ /// @sa https://json.nlohmann.me/api/json_pointer/pop_back/
void pop_back()
{
if (JSON_HEDLEY_UNLIKELY(empty()))
@@ -254,20 +124,8 @@
reference_tokens.pop_back();
}
- /*!
- @brief return last reference token
-
- @pre not `empty()`
- @return last reference token
-
- @liveexample{The example shows the usage of `back`.,json_pointer__back}
-
- @complexity Constant.
-
- @throw out_of_range.405 if JSON pointer has no parent
-
- @since version 3.6.0
- */
+ /// @brief return last reference token
+ /// @sa https://json.nlohmann.me/api/json_pointer/back/
const std::string& back() const
{
if (JSON_HEDLEY_UNLIKELY(empty()))
@@ -278,43 +136,22 @@
return reference_tokens.back();
}
- /*!
- @brief append an unescaped token at the end of the reference pointer
-
- @param[in] token token to add
-
- @complexity Amortized constant.
-
- @liveexample{The example shows the result of `push_back` for different
- JSON Pointers.,json_pointer__push_back}
-
- @since version 3.6.0
- */
+ /// @brief append an unescaped token at the end of the reference pointer
+ /// @sa https://json.nlohmann.me/api/json_pointer/push_back/
void push_back(const std::string& token)
{
reference_tokens.push_back(token);
}
- /// @copydoc push_back(const std::string&)
+ /// @brief append an unescaped token at the end of the reference pointer
+ /// @sa https://json.nlohmann.me/api/json_pointer/push_back/
void push_back(std::string&& token)
{
reference_tokens.push_back(std::move(token));
}
- /*!
- @brief return whether pointer points to the root document
-
- @return true iff the JSON pointer points to the root document
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this function never throws exceptions.
-
- @liveexample{The example shows the result of `empty` for different JSON
- Pointers.,json_pointer__empty}
-
- @since version 3.6.0
- */
+ /// @brief return whether pointer points to the root document
+ /// @sa https://json.nlohmann.me/api/json_pointer/empty/
bool empty() const noexcept
{
return reference_tokens.empty();
diff --git a/include/nlohmann/detail/macro_scope.hpp b/include/nlohmann/detail/macro_scope.hpp
index c2a65bd..b2843f0 100644
--- a/include/nlohmann/detail/macro_scope.hpp
+++ b/include/nlohmann/detail/macro_scope.hpp
@@ -37,6 +37,66 @@
#define JSON_HAS_CPP_11
#endif
+#if !defined(JSON_HAS_FILESYSTEM) && !defined(JSON_HAS_EXPERIMENTAL_FILESYSTEM)
+ #ifdef JSON_HAS_CPP_17
+ #if defined(__cpp_lib_filesystem)
+ #define JSON_HAS_FILESYSTEM 1
+ #elif defined(__cpp_lib_experimental_filesystem)
+ #define JSON_HAS_EXPERIMENTAL_FILESYSTEM 1
+ #elif !defined(__has_include)
+ #define JSON_HAS_EXPERIMENTAL_FILESYSTEM 1
+ #elif __has_include(<filesystem>)
+ #define JSON_HAS_FILESYSTEM 1
+ #elif __has_include(<experimental/filesystem>)
+ #define JSON_HAS_EXPERIMENTAL_FILESYSTEM 1
+ #endif
+
+ // std::filesystem does not work on MinGW GCC 8: https://sourceforge.net/p/mingw-w64/bugs/737/
+ #if defined(__MINGW32__) && defined(__GNUC__) && __GNUC__ == 8
+ #undef JSON_HAS_FILESYSTEM
+ #undef JSON_HAS_EXPERIMENTAL_FILESYSTEM
+ #endif
+
+ // no filesystem support before GCC 8: https://en.cppreference.com/w/cpp/compiler_support
+ #if defined(__GNUC__) && !defined(__clang__) && __GNUC__ < 8
+ #undef JSON_HAS_FILESYSTEM
+ #undef JSON_HAS_EXPERIMENTAL_FILESYSTEM
+ #endif
+
+ // no filesystem support before Clang 7: https://en.cppreference.com/w/cpp/compiler_support
+ #if defined(__clang_major__) && __clang_major__ < 7
+ #undef JSON_HAS_FILESYSTEM
+ #undef JSON_HAS_EXPERIMENTAL_FILESYSTEM
+ #endif
+
+ // no filesystem support before MSVC 19.14: https://en.cppreference.com/w/cpp/compiler_support
+ #if defined(_MSC_VER) && _MSC_VER < 1940
+ #undef JSON_HAS_FILESYSTEM
+ #undef JSON_HAS_EXPERIMENTAL_FILESYSTEM
+ #endif
+
+ // no filesystem support before iOS 13
+ #if defined(__IPHONE_OS_VERSION_MIN_REQUIRED) && __IPHONE_OS_VERSION_MIN_REQUIRED < 130000
+ #undef JSON_HAS_FILESYSTEM
+ #undef JSON_HAS_EXPERIMENTAL_FILESYSTEM
+ #endif
+
+ // no filesystem support before macOS Catalina
+ #if defined(__MAC_OS_X_VERSION_MIN_REQUIRED) && __MAC_OS_X_VERSION_MIN_REQUIRED < 101500
+ #undef JSON_HAS_FILESYSTEM
+ #undef JSON_HAS_EXPERIMENTAL_FILESYSTEM
+ #endif
+ #endif
+#endif
+
+#ifndef JSON_HAS_EXPERIMENTAL_FILESYSTEM
+ #define JSON_HAS_EXPERIMENTAL_FILESYSTEM 0
+#endif
+
+#ifndef JSON_HAS_FILESYSTEM
+ #define JSON_HAS_FILESYSTEM 0
+#endif
+
// disable documentation warnings on clang
#if defined(__clang__)
#pragma clang diagnostic push
@@ -44,7 +104,7 @@
#pragma clang diagnostic ignored "-Wdocumentation-unknown-command"
#endif
-// allow to disable exceptions
+// allow disabling exceptions
#if (defined(__cpp_exceptions) || defined(__EXCEPTIONS) || defined(_CPPUNWIND)) && !defined(JSON_NOEXCEPTION)
#define JSON_THROW(exception) throw exception
#define JSON_TRY try
@@ -78,7 +138,7 @@
#define JSON_INTERNAL_CATCH JSON_INTERNAL_CATCH_USER
#endif
-// allow to override assert
+// allow overriding assert
#if !defined(JSON_ASSERT)
#include <cassert> // assert
#define JSON_ASSERT(x) assert(x)
diff --git a/include/nlohmann/detail/macro_unscope.hpp b/include/nlohmann/detail/macro_unscope.hpp
index 67bf146..1a29fb5 100644
--- a/include/nlohmann/detail/macro_unscope.hpp
+++ b/include/nlohmann/detail/macro_unscope.hpp
@@ -16,6 +16,8 @@
#undef JSON_HAS_CPP_14
#undef JSON_HAS_CPP_17
#undef JSON_HAS_CPP_20
+#undef JSON_HAS_FILESYSTEM
+#undef JSON_HAS_EXPERIMENTAL_FILESYSTEM
#undef NLOHMANN_BASIC_JSON_TPL_DECLARATION
#undef NLOHMANN_BASIC_JSON_TPL
#undef JSON_EXPLICIT
diff --git a/include/nlohmann/detail/meta/cpp_future.hpp b/include/nlohmann/detail/meta/cpp_future.hpp
index e24518f..147f2fa 100644
--- a/include/nlohmann/detail/meta/cpp_future.hpp
+++ b/include/nlohmann/detail/meta/cpp_future.hpp
@@ -148,7 +148,7 @@
};
template<typename T>
-constexpr T static_const<T>::value;
+constexpr T static_const<T>::value; // NOLINT(readability-redundant-declaration)
} // namespace detail
} // namespace nlohmann
diff --git a/include/nlohmann/detail/output/binary_writer.hpp b/include/nlohmann/detail/output/binary_writer.hpp
index 42fd50e..5985871 100644
--- a/include/nlohmann/detail/output/binary_writer.hpp
+++ b/include/nlohmann/detail/output/binary_writer.hpp
@@ -1083,7 +1083,7 @@
{
std::size_t array_index = 0ul;
- const std::size_t embedded_document_size = std::accumulate(std::begin(value), std::end(value), std::size_t(0), [&array_index](std::size_t result, const typename BasicJsonType::array_t::value_type & el)
+ const std::size_t embedded_document_size = std::accumulate(std::begin(value), std::end(value), static_cast<std::size_t>(0), [&array_index](std::size_t result, const typename BasicJsonType::array_t::value_type & el)
{
return result + calc_bson_element_size(std::to_string(array_index++), el);
});
@@ -1127,7 +1127,7 @@
write_bson_entry_header(name, 0x05);
write_number<std::int32_t, true>(static_cast<std::int32_t>(value.size()));
- write_number(value.has_subtype() ? static_cast<std::uint8_t>(value.subtype()) : std::uint8_t(0x00));
+ write_number(value.has_subtype() ? static_cast<std::uint8_t>(value.subtype()) : static_cast<std::uint8_t>(0x00));
oa->write_characters(reinterpret_cast<const CharType*>(value.data()), value.size());
}
@@ -1233,7 +1233,7 @@
*/
static std::size_t calc_bson_object_size(const typename BasicJsonType::object_t& value)
{
- std::size_t document_size = std::accumulate(value.begin(), value.end(), std::size_t(0),
+ std::size_t document_size = std::accumulate(value.begin(), value.end(), static_cast<std::size_t>(0),
[](size_t result, const typename BasicJsonType::object_t::value_type & el)
{
return result += calc_bson_element_size(el.first, el.second);
@@ -1535,7 +1535,7 @@
@tparam OutputIsLittleEndian Set to true if output data is
required to be little endian
- @note This function needs to respect the system's endianess, because bytes
+ @note This function needs to respect the system's endianness, because bytes
in CBOR, MessagePack, and UBJSON are stored in network order (big
endian) and therefore need reordering on little endian systems.
*/
@@ -1625,8 +1625,8 @@
}
private:
- /// whether we can assume little endianess
- const bool is_little_endian = little_endianess();
+ /// whether we can assume little endianness
+ const bool is_little_endian = little_endianness();
/// the output
output_adapter_t<CharType> oa = nullptr;
diff --git a/include/nlohmann/detail/output/serializer.hpp b/include/nlohmann/detail/output/serializer.hpp
index fabb3d3..7cce7d5 100644
--- a/include/nlohmann/detail/output/serializer.hpp
+++ b/include/nlohmann/detail/output/serializer.hpp
@@ -9,6 +9,8 @@
#include <cstdio> // snprintf
#include <limits> // numeric_limits
#include <string> // string, char_traits
+#include <iomanip> // setfill, setw
+#include <sstream> // stringstream
#include <type_traits> // is_same
#include <utility> // move
@@ -455,16 +457,16 @@
if (codepoint <= 0xFFFF)
{
// NOLINTNEXTLINE(cppcoreguidelines-pro-type-vararg,hicpp-vararg)
- (std::snprintf)(string_buffer.data() + bytes, 7, "\\u%04x",
- static_cast<std::uint16_t>(codepoint));
+ static_cast<void>((std::snprintf)(string_buffer.data() + bytes, 7, "\\u%04x",
+ static_cast<std::uint16_t>(codepoint)));
bytes += 6;
}
else
{
// NOLINTNEXTLINE(cppcoreguidelines-pro-type-vararg,hicpp-vararg)
- (std::snprintf)(string_buffer.data() + bytes, 13, "\\u%04x\\u%04x",
- static_cast<std::uint16_t>(0xD7C0u + (codepoint >> 10u)),
- static_cast<std::uint16_t>(0xDC00u + (codepoint & 0x3FFu)));
+ static_cast<void>((std::snprintf)(string_buffer.data() + bytes, 13, "\\u%04x\\u%04x",
+ static_cast<std::uint16_t>(0xD7C0u + (codepoint >> 10u)),
+ static_cast<std::uint16_t>(0xDC00u + (codepoint & 0x3FFu))));
bytes += 12;
}
}
@@ -499,10 +501,9 @@
{
case error_handler_t::strict:
{
- std::string sn(9, '\0');
- // NOLINTNEXTLINE(cppcoreguidelines-pro-type-vararg,hicpp-vararg)
- (std::snprintf)(&sn[0], sn.size(), "%.2X", byte);
- JSON_THROW(type_error::create(316, "invalid UTF-8 byte at index " + std::to_string(i) + ": 0x" + sn, BasicJsonType()));
+ std::stringstream ss;
+ ss << std::uppercase << std::setfill('0') << std::setw(2) << std::hex << (byte | 0);
+ JSON_THROW(type_error::create(316, "invalid UTF-8 byte at index " + std::to_string(i) + ": 0x" + ss.str(), BasicJsonType()));
}
case error_handler_t::ignore:
@@ -594,10 +595,9 @@
{
case error_handler_t::strict:
{
- std::string sn(9, '\0');
- // NOLINTNEXTLINE(cppcoreguidelines-pro-type-vararg,hicpp-vararg)
- (std::snprintf)(&sn[0], sn.size(), "%.2X", static_cast<std::uint8_t>(s.back()));
- JSON_THROW(type_error::create(316, "incomplete UTF-8 string; last byte: 0x" + sn, BasicJsonType()));
+ std::stringstream ss;
+ ss << std::uppercase << std::setfill('0') << std::setw(2) << std::hex << (static_cast<std::uint8_t>(s.back()) | 0);
+ JSON_THROW(type_error::create(316, "incomplete UTF-8 string; last byte: 0x" + ss.str(), BasicJsonType()));
}
case error_handler_t::ignore:
@@ -664,6 +664,19 @@
}
}
+ // templates to avoid warnings about useless casts
+ template <typename NumberType, enable_if_t<std::is_signed<NumberType>::value, int> = 0>
+ bool is_negative_number(NumberType x)
+ {
+ return x < 0;
+ }
+
+ template < typename NumberType, enable_if_t <std::is_unsigned<NumberType>::value, int > = 0 >
+ bool is_negative_number(NumberType /*unused*/)
+ {
+ return false;
+ }
+
/*!
@brief dump an integer
@@ -707,12 +720,11 @@
// use a pointer to fill the buffer
auto buffer_ptr = number_buffer.begin(); // NOLINT(llvm-qualified-auto,readability-qualified-auto,cppcoreguidelines-pro-type-vararg,hicpp-vararg)
- const bool is_negative = std::is_signed<NumberType>::value && !(x >= 0); // see issue #755
number_unsigned_t abs_value;
unsigned int n_chars{};
- if (is_negative)
+ if (is_negative_number(x))
{
*buffer_ptr = '-';
abs_value = remove_sign(static_cast<number_integer_t>(x));
@@ -729,7 +741,7 @@
// spare 1 byte for '\0'
JSON_ASSERT(n_chars < number_buffer.size() - 1);
- // jump to the end to generate the string from backward
+ // jump to the end to generate the string from backward,
// so we later avoid reversing the result
buffer_ptr += n_chars;
@@ -831,7 +843,7 @@
o->write_characters(number_buffer.data(), static_cast<std::size_t>(len));
- // determine if need to append ".0"
+ // determine if we need to append ".0"
const bool value_is_int_like =
std::none_of(number_buffer.begin(), number_buffer.begin() + len + 1,
[](char c)
diff --git a/include/nlohmann/json.hpp b/include/nlohmann/json.hpp
index bc6797d..a79be2d 100644
--- a/include/nlohmann/json.hpp
+++ b/include/nlohmann/json.hpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
@@ -27,12 +27,21 @@
SOFTWARE.
*/
+/****************************************************************************\
+ * Note on documentation: The source files contain links to the online *
+ * documentation of the public API at https://json.nlohmann.me. This URL *
+ * contains the most recent documentation and should also be applicable to *
+ * previous versions; documentation for deprecated functions is not *
+ * removed, but marked deprecated. See "Generate documentation" section in *
+ * file doc/README.md. *
+\****************************************************************************/
+
#ifndef INCLUDE_NLOHMANN_JSON_HPP_
#define INCLUDE_NLOHMANN_JSON_HPP_
#define NLOHMANN_JSON_VERSION_MAJOR 3
#define NLOHMANN_JSON_VERSION_MINOR 10
-#define NLOHMANN_JSON_VERSION_PATCH 4
+#define NLOHMANN_JSON_VERSION_PATCH 5
#include <algorithm> // all_of, find, for_each
#include <cstddef> // nullptr_t, ptrdiff_t, size_t
@@ -91,69 +100,7 @@
/*!
@brief a class to store JSON values
-@tparam ObjectType type for JSON objects (`std::map` by default; will be used
-in @ref object_t)
-@tparam ArrayType type for JSON arrays (`std::vector` by default; will be used
-in @ref array_t)
-@tparam StringType type for JSON strings and object keys (`std::string` by
-default; will be used in @ref string_t)
-@tparam BooleanType type for JSON booleans (`bool` by default; will be used
-in @ref boolean_t)
-@tparam NumberIntegerType type for JSON integer numbers (`int64_t` by
-default; will be used in @ref number_integer_t)
-@tparam NumberUnsignedType type for JSON unsigned integer numbers (@c
-`uint64_t` by default; will be used in @ref number_unsigned_t)
-@tparam NumberFloatType type for JSON floating-point numbers (`double` by
-default; will be used in @ref number_float_t)
-@tparam BinaryType type for packed binary data for compatibility with binary
-serialization formats (`std::vector<std::uint8_t>` by default; will be used in
-@ref binary_t)
-@tparam AllocatorType type of the allocator to use (`std::allocator` by
-default)
-@tparam JSONSerializer the serializer to resolve internal calls to `to_json()`
-and `from_json()` (@ref adl_serializer by default)
-
-@requirement The class satisfies the following concept requirements:
-- Basic
- - [DefaultConstructible](https://en.cppreference.com/w/cpp/named_req/DefaultConstructible):
- JSON values can be default constructed. The result will be a JSON null
- value.
- - [MoveConstructible](https://en.cppreference.com/w/cpp/named_req/MoveConstructible):
- A JSON value can be constructed from an rvalue argument.
- - [CopyConstructible](https://en.cppreference.com/w/cpp/named_req/CopyConstructible):
- A JSON value can be copy-constructed from an lvalue expression.
- - [MoveAssignable](https://en.cppreference.com/w/cpp/named_req/MoveAssignable):
- A JSON value van be assigned from an rvalue argument.
- - [CopyAssignable](https://en.cppreference.com/w/cpp/named_req/CopyAssignable):
- A JSON value can be copy-assigned from an lvalue expression.
- - [Destructible](https://en.cppreference.com/w/cpp/named_req/Destructible):
- JSON values can be destructed.
-- Layout
- - [StandardLayoutType](https://en.cppreference.com/w/cpp/named_req/StandardLayoutType):
- JSON values have
- [standard layout](https://en.cppreference.com/w/cpp/language/data_members#Standard_layout):
- All non-static data members are private and standard layout types, the
- class has no virtual functions or (virtual) base classes.
-- Library-wide
- - [EqualityComparable](https://en.cppreference.com/w/cpp/named_req/EqualityComparable):
- JSON values can be compared with `==`, see @ref
- operator==(const_reference,const_reference).
- - [LessThanComparable](https://en.cppreference.com/w/cpp/named_req/LessThanComparable):
- JSON values can be compared with `<`, see @ref
- operator<(const_reference,const_reference).
- - [Swappable](https://en.cppreference.com/w/cpp/named_req/Swappable):
- Any JSON lvalue or rvalue of can be swapped with any lvalue or rvalue of
- other compatible types, using unqualified function call @ref swap().
- - [NullablePointer](https://en.cppreference.com/w/cpp/named_req/NullablePointer):
- JSON values can be compared against `std::nullptr_t` objects which are used
- to model the `null` value.
-- Container
- - [Container](https://en.cppreference.com/w/cpp/named_req/Container):
- JSON values can be used like STL containers and provide iterator access.
- - [ReversibleContainer](https://en.cppreference.com/w/cpp/named_req/ReversibleContainer);
- JSON values can be used like STL containers and provide reverse iterator
- access.
-
+@internal
@invariant The member variables @a m_value and @a m_type have the following
relationship:
- If `m_type == value_t::object`, then `m_value.object != nullptr`.
@@ -161,13 +108,9 @@
- If `m_type == value_t::string`, then `m_value.string != nullptr`.
The invariants are checked by member function assert_invariant().
-@internal
@note ObjectType trick from https://stackoverflow.com/a/9860911
@endinternal
-@see [RFC 8259: The JavaScript Object Notation (JSON) Data Interchange
-Format](https://tools.ietf.org/html/rfc8259)
-
@since version 1.0.0
@nosubgrouping
@@ -258,17 +201,11 @@
/// Classes to implement user-defined exceptions.
/// @{
- /// @copydoc detail::exception
using exception = detail::exception;
- /// @copydoc detail::parse_error
using parse_error = detail::parse_error;
- /// @copydoc detail::invalid_iterator
using invalid_iterator = detail::invalid_iterator;
- /// @copydoc detail::type_error
using type_error = detail::type_error;
- /// @copydoc detail::out_of_range
using out_of_range = detail::out_of_range;
- /// @copydoc detail::other_error
using other_error = detail::other_error;
/// @}
@@ -316,46 +253,21 @@
/// @}
- /*!
- @brief returns the allocator associated with the container
- */
+ /// @brief returns the allocator associated with the container
+ /// @sa https://json.nlohmann.me/api/basic_json/get_allocator/
static allocator_type get_allocator()
{
return allocator_type();
}
- /*!
- @brief returns version information on the library
-
- This function returns a JSON object with information about the library,
- including the version number and information on the platform and compiler.
-
- @return JSON object holding version information
- key | description
- ----------- | ---------------
- `compiler` | Information on the used compiler. It is an object with the following keys: `c++` (the used C++ standard), `family` (the compiler family; possible values are `clang`, `icc`, `gcc`, `ilecpp`, `msvc`, `pgcpp`, `sunpro`, and `unknown`), and `version` (the compiler version).
- `copyright` | The copyright line for the library as string.
- `name` | The name of the library as string.
- `platform` | The used platform as string. Possible values are `win32`, `linux`, `apple`, `unix`, and `unknown`.
- `url` | The URL of the project as string.
- `version` | The version of the library. It is an object with the following keys: `major`, `minor`, and `patch` as defined by [Semantic Versioning](http://semver.org), and `string` (the version string).
-
- @liveexample{The following code shows an example output of the `meta()`
- function.,meta}
-
- @exceptionsafety Strong guarantee: if an exception is thrown, there are no
- changes to any JSON value.
-
- @complexity Constant.
-
- @since 2.1.0
- */
+ /// @brief returns version information on the library
+ /// @sa https://json.nlohmann.me/api/basic_json/meta/
JSON_HEDLEY_WARN_UNUSED_RESULT
static basic_json meta()
{
basic_json result;
- result["copyright"] = "(C) 2013-2021 Niels Lohmann";
+ result["copyright"] = "(C) 2013-2022 Niels Lohmann";
result["name"] = "JSON for Modern C++";
result["url"] = "https://github.com/nlohmann/json";
result["version"]["string"] =
@@ -416,6 +328,8 @@
/// the template arguments passed to class @ref basic_json.
/// @{
+ /// @brief object key comparator type
+ /// @sa https://json.nlohmann.me/api/basic_json/object_comparator_t/
#if defined(JSON_HAS_CPP_14)
// Use transparent comparator if possible, combined with perfect forwarding
// on find() and count() calls prevents unnecessary string construction.
@@ -424,501 +338,42 @@
using object_comparator_t = std::less<StringType>;
#endif
- /*!
- @brief a type for an object
-
- [RFC 8259](https://tools.ietf.org/html/rfc8259) describes JSON objects as follows:
- > An object is an unordered collection of zero or more name/value pairs,
- > where a name is a string and a value is a string, number, boolean, null,
- > object, or array.
-
- To store objects in C++, a type is defined by the template parameters
- described below.
-
- @tparam ObjectType the container to store objects (e.g., `std::map` or
- `std::unordered_map`)
- @tparam StringType the type of the keys or names (e.g., `std::string`).
- The comparison function `std::less<StringType>` is used to order elements
- inside the container.
- @tparam AllocatorType the allocator to use for objects (e.g.,
- `std::allocator`)
-
- #### Default type
-
- With the default values for @a ObjectType (`std::map`), @a StringType
- (`std::string`), and @a AllocatorType (`std::allocator`), the default
- value for @a object_t is:
-
- @code {.cpp}
- std::map<
- std::string, // key_type
- basic_json, // value_type
- std::less<std::string>, // key_compare
- std::allocator<std::pair<const std::string, basic_json>> // allocator_type
- >
- @endcode
-
- #### Behavior
-
- The choice of @a object_t influences the behavior of the JSON class. With
- the default type, objects have the following behavior:
-
- - When all names are unique, objects will be interoperable in the sense
- that all software implementations receiving that object will agree on
- the name-value mappings.
- - When the names within an object are not unique, it is unspecified which
- one of the values for a given key will be chosen. For instance,
- `{"key": 2, "key": 1}` could be equal to either `{"key": 1}` or
- `{"key": 2}`.
- - Internally, name/value pairs are stored in lexicographical order of the
- names. Objects will also be serialized (see @ref dump) in this order.
- For instance, `{"b": 1, "a": 2}` and `{"a": 2, "b": 1}` will be stored
- and serialized as `{"a": 2, "b": 1}`.
- - When comparing objects, the order of the name/value pairs is irrelevant.
- This makes objects interoperable in the sense that they will not be
- affected by these differences. For instance, `{"b": 1, "a": 2}` and
- `{"a": 2, "b": 1}` will be treated as equal.
-
- #### Limits
-
- [RFC 8259](https://tools.ietf.org/html/rfc8259) specifies:
- > An implementation may set limits on the maximum depth of nesting.
-
- In this class, the object's limit of nesting is not explicitly constrained.
- However, a maximum depth of nesting may be introduced by the compiler or
- runtime environment. A theoretical limit can be queried by calling the
- @ref max_size function of a JSON object.
-
- #### Storage
-
- Objects are stored as pointers in a @ref basic_json type. That is, for any
- access to object values, a pointer of type `object_t*` must be
- dereferenced.
-
- @sa see @ref array_t -- type for an array value
-
- @since version 1.0.0
-
- @note The order name/value pairs are added to the object is *not*
- preserved by the library. Therefore, iterating an object may return
- name/value pairs in a different order than they were originally stored. In
- fact, keys will be traversed in alphabetical order as `std::map` with
- `std::less` is used by default. Please note this behavior conforms to [RFC
- 8259](https://tools.ietf.org/html/rfc8259), because any order implements the
- specified "unordered" nature of JSON objects.
- */
+ /// @brief a type for an object
+ /// @sa https://json.nlohmann.me/api/basic_json/object_t/
using object_t = ObjectType<StringType,
basic_json,
object_comparator_t,
AllocatorType<std::pair<const StringType,
basic_json>>>;
- /*!
- @brief a type for an array
-
- [RFC 8259](https://tools.ietf.org/html/rfc8259) describes JSON arrays as follows:
- > An array is an ordered sequence of zero or more values.
-
- To store objects in C++, a type is defined by the template parameters
- explained below.
-
- @tparam ArrayType container type to store arrays (e.g., `std::vector` or
- `std::list`)
- @tparam AllocatorType allocator to use for arrays (e.g., `std::allocator`)
-
- #### Default type
-
- With the default values for @a ArrayType (`std::vector`) and @a
- AllocatorType (`std::allocator`), the default value for @a array_t is:
-
- @code {.cpp}
- std::vector<
- basic_json, // value_type
- std::allocator<basic_json> // allocator_type
- >
- @endcode
-
- #### Limits
-
- [RFC 8259](https://tools.ietf.org/html/rfc8259) specifies:
- > An implementation may set limits on the maximum depth of nesting.
-
- In this class, the array's limit of nesting is not explicitly constrained.
- However, a maximum depth of nesting may be introduced by the compiler or
- runtime environment. A theoretical limit can be queried by calling the
- @ref max_size function of a JSON array.
-
- #### Storage
-
- Arrays are stored as pointers in a @ref basic_json type. That is, for any
- access to array values, a pointer of type `array_t*` must be dereferenced.
-
- @sa see @ref object_t -- type for an object value
-
- @since version 1.0.0
- */
+ /// @brief a type for an array
+ /// @sa https://json.nlohmann.me/api/basic_json/array_t/
using array_t = ArrayType<basic_json, AllocatorType<basic_json>>;
- /*!
- @brief a type for a string
-
- [RFC 8259](https://tools.ietf.org/html/rfc8259) describes JSON strings as follows:
- > A string is a sequence of zero or more Unicode characters.
-
- To store objects in C++, a type is defined by the template parameter
- described below. Unicode values are split by the JSON class into
- byte-sized characters during deserialization.
-
- @tparam StringType the container to store strings (e.g., `std::string`).
- Note this container is used for keys/names in objects, see @ref object_t.
-
- #### Default type
-
- With the default values for @a StringType (`std::string`), the default
- value for @a string_t is:
-
- @code {.cpp}
- std::string
- @endcode
-
- #### Encoding
-
- Strings are stored in UTF-8 encoding. Therefore, functions like
- `std::string::size()` or `std::string::length()` return the number of
- bytes in the string rather than the number of characters or glyphs.
-
- #### String comparison
-
- [RFC 8259](https://tools.ietf.org/html/rfc8259) states:
- > Software implementations are typically required to test names of object
- > members for equality. Implementations that transform the textual
- > representation into sequences of Unicode code units and then perform the
- > comparison numerically, code unit by code unit, are interoperable in the
- > sense that implementations will agree in all cases on equality or
- > inequality of two strings. For example, implementations that compare
- > strings with escaped characters unconverted may incorrectly find that
- > `"a\\b"` and `"a\u005Cb"` are not equal.
-
- This implementation is interoperable as it does compare strings code unit
- by code unit.
-
- #### Storage
-
- String values are stored as pointers in a @ref basic_json type. That is,
- for any access to string values, a pointer of type `string_t*` must be
- dereferenced.
-
- @since version 1.0.0
- */
+ /// @brief a type for a string
+ /// @sa https://json.nlohmann.me/api/basic_json/string_t/
using string_t = StringType;
- /*!
- @brief a type for a boolean
-
- [RFC 8259](https://tools.ietf.org/html/rfc8259) implicitly describes a boolean as a
- type which differentiates the two literals `true` and `false`.
-
- To store objects in C++, a type is defined by the template parameter @a
- BooleanType which chooses the type to use.
-
- #### Default type
-
- With the default values for @a BooleanType (`bool`), the default value for
- @a boolean_t is:
-
- @code {.cpp}
- bool
- @endcode
-
- #### Storage
-
- Boolean values are stored directly inside a @ref basic_json type.
-
- @since version 1.0.0
- */
+ /// @brief a type for a boolean
+ /// @sa https://json.nlohmann.me/api/basic_json/boolean_t/
using boolean_t = BooleanType;
- /*!
- @brief a type for a number (integer)
-
- [RFC 8259](https://tools.ietf.org/html/rfc8259) describes numbers as follows:
- > The representation of numbers is similar to that used in most
- > programming languages. A number is represented in base 10 using decimal
- > digits. It contains an integer component that may be prefixed with an
- > optional minus sign, which may be followed by a fraction part and/or an
- > exponent part. Leading zeros are not allowed. (...) Numeric values that
- > cannot be represented in the grammar below (such as Infinity and NaN)
- > are not permitted.
-
- This description includes both integer and floating-point numbers.
- However, C++ allows more precise storage if it is known whether the number
- is a signed integer, an unsigned integer or a floating-point number.
- Therefore, three different types, @ref number_integer_t, @ref
- number_unsigned_t and @ref number_float_t are used.
-
- To store integer numbers in C++, a type is defined by the template
- parameter @a NumberIntegerType which chooses the type to use.
-
- #### Default type
-
- With the default values for @a NumberIntegerType (`int64_t`), the default
- value for @a number_integer_t is:
-
- @code {.cpp}
- int64_t
- @endcode
-
- #### Default behavior
-
- - The restrictions about leading zeros is not enforced in C++. Instead,
- leading zeros in integer literals lead to an interpretation as octal
- number. Internally, the value will be stored as decimal number. For
- instance, the C++ integer literal `010` will be serialized to `8`.
- During deserialization, leading zeros yield an error.
- - Not-a-number (NaN) values will be serialized to `null`.
-
- #### Limits
-
- [RFC 8259](https://tools.ietf.org/html/rfc8259) specifies:
- > An implementation may set limits on the range and precision of numbers.
-
- When the default type is used, the maximal integer number that can be
- stored is `9223372036854775807` (INT64_MAX) and the minimal integer number
- that can be stored is `-9223372036854775808` (INT64_MIN). Integer numbers
- that are out of range will yield over/underflow when used in a
- constructor. During deserialization, too large or small integer numbers
- will be automatically be stored as @ref number_unsigned_t or @ref
- number_float_t.
-
- [RFC 8259](https://tools.ietf.org/html/rfc8259) further states:
- > Note that when such software is used, numbers that are integers and are
- > in the range \f$[-2^{53}+1, 2^{53}-1]\f$ are interoperable in the sense
- > that implementations will agree exactly on their numeric values.
-
- As this range is a subrange of the exactly supported range [INT64_MIN,
- INT64_MAX], this class's integer type is interoperable.
-
- #### Storage
-
- Integer number values are stored directly inside a @ref basic_json type.
-
- @sa see @ref number_float_t -- type for number values (floating-point)
-
- @sa see @ref number_unsigned_t -- type for number values (unsigned integer)
-
- @since version 1.0.0
- */
+ /// @brief a type for a number (integer)
+ /// @sa https://json.nlohmann.me/api/basic_json/number_integer_t/
using number_integer_t = NumberIntegerType;
- /*!
- @brief a type for a number (unsigned)
-
- [RFC 8259](https://tools.ietf.org/html/rfc8259) describes numbers as follows:
- > The representation of numbers is similar to that used in most
- > programming languages. A number is represented in base 10 using decimal
- > digits. It contains an integer component that may be prefixed with an
- > optional minus sign, which may be followed by a fraction part and/or an
- > exponent part. Leading zeros are not allowed. (...) Numeric values that
- > cannot be represented in the grammar below (such as Infinity and NaN)
- > are not permitted.
-
- This description includes both integer and floating-point numbers.
- However, C++ allows more precise storage if it is known whether the number
- is a signed integer, an unsigned integer or a floating-point number.
- Therefore, three different types, @ref number_integer_t, @ref
- number_unsigned_t and @ref number_float_t are used.
-
- To store unsigned integer numbers in C++, a type is defined by the
- template parameter @a NumberUnsignedType which chooses the type to use.
-
- #### Default type
-
- With the default values for @a NumberUnsignedType (`uint64_t`), the
- default value for @a number_unsigned_t is:
-
- @code {.cpp}
- uint64_t
- @endcode
-
- #### Default behavior
-
- - The restrictions about leading zeros is not enforced in C++. Instead,
- leading zeros in integer literals lead to an interpretation as octal
- number. Internally, the value will be stored as decimal number. For
- instance, the C++ integer literal `010` will be serialized to `8`.
- During deserialization, leading zeros yield an error.
- - Not-a-number (NaN) values will be serialized to `null`.
-
- #### Limits
-
- [RFC 8259](https://tools.ietf.org/html/rfc8259) specifies:
- > An implementation may set limits on the range and precision of numbers.
-
- When the default type is used, the maximal integer number that can be
- stored is `18446744073709551615` (UINT64_MAX) and the minimal integer
- number that can be stored is `0`. Integer numbers that are out of range
- will yield over/underflow when used in a constructor. During
- deserialization, too large or small integer numbers will be automatically
- be stored as @ref number_integer_t or @ref number_float_t.
-
- [RFC 8259](https://tools.ietf.org/html/rfc8259) further states:
- > Note that when such software is used, numbers that are integers and are
- > in the range \f$[-2^{53}+1, 2^{53}-1]\f$ are interoperable in the sense
- > that implementations will agree exactly on their numeric values.
-
- As this range is a subrange (when considered in conjunction with the
- number_integer_t type) of the exactly supported range [0, UINT64_MAX],
- this class's integer type is interoperable.
-
- #### Storage
-
- Integer number values are stored directly inside a @ref basic_json type.
-
- @sa see @ref number_float_t -- type for number values (floating-point)
- @sa see @ref number_integer_t -- type for number values (integer)
-
- @since version 2.0.0
- */
+ /// @brief a type for a number (unsigned)
+ /// @sa https://json.nlohmann.me/api/basic_json/number_unsigned_t/
using number_unsigned_t = NumberUnsignedType;
- /*!
- @brief a type for a number (floating-point)
-
- [RFC 8259](https://tools.ietf.org/html/rfc8259) describes numbers as follows:
- > The representation of numbers is similar to that used in most
- > programming languages. A number is represented in base 10 using decimal
- > digits. It contains an integer component that may be prefixed with an
- > optional minus sign, which may be followed by a fraction part and/or an
- > exponent part. Leading zeros are not allowed. (...) Numeric values that
- > cannot be represented in the grammar below (such as Infinity and NaN)
- > are not permitted.
-
- This description includes both integer and floating-point numbers.
- However, C++ allows more precise storage if it is known whether the number
- is a signed integer, an unsigned integer or a floating-point number.
- Therefore, three different types, @ref number_integer_t, @ref
- number_unsigned_t and @ref number_float_t are used.
-
- To store floating-point numbers in C++, a type is defined by the template
- parameter @a NumberFloatType which chooses the type to use.
-
- #### Default type
-
- With the default values for @a NumberFloatType (`double`), the default
- value for @a number_float_t is:
-
- @code {.cpp}
- double
- @endcode
-
- #### Default behavior
-
- - The restrictions about leading zeros is not enforced in C++. Instead,
- leading zeros in floating-point literals will be ignored. Internally,
- the value will be stored as decimal number. For instance, the C++
- floating-point literal `01.2` will be serialized to `1.2`. During
- deserialization, leading zeros yield an error.
- - Not-a-number (NaN) values will be serialized to `null`.
-
- #### Limits
-
- [RFC 8259](https://tools.ietf.org/html/rfc8259) states:
- > This specification allows implementations to set limits on the range and
- > precision of numbers accepted. Since software that implements IEEE
- > 754-2008 binary64 (double precision) numbers is generally available and
- > widely used, good interoperability can be achieved by implementations
- > that expect no more precision or range than these provide, in the sense
- > that implementations will approximate JSON numbers within the expected
- > precision.
-
- This implementation does exactly follow this approach, as it uses double
- precision floating-point numbers. Note values smaller than
- `-1.79769313486232e+308` and values greater than `1.79769313486232e+308`
- will be stored as NaN internally and be serialized to `null`.
-
- #### Storage
-
- Floating-point number values are stored directly inside a @ref basic_json
- type.
-
- @sa see @ref number_integer_t -- type for number values (integer)
-
- @sa see @ref number_unsigned_t -- type for number values (unsigned integer)
-
- @since version 1.0.0
- */
+ /// @brief a type for a number (floating-point)
+ /// @sa https://json.nlohmann.me/api/basic_json/number_float_t/
using number_float_t = NumberFloatType;
- /*!
- @brief a type for a packed binary type
-
- This type is a type designed to carry binary data that appears in various
- serialized formats, such as CBOR's Major Type 2, MessagePack's bin, and
- BSON's generic binary subtype. This type is NOT a part of standard JSON and
- exists solely for compatibility with these binary types. As such, it is
- simply defined as an ordered sequence of zero or more byte values.
-
- Additionally, as an implementation detail, the subtype of the binary data is
- carried around as a `std::uint8_t`, which is compatible with both of the
- binary data formats that use binary subtyping, (though the specific
- numbering is incompatible with each other, and it is up to the user to
- translate between them).
-
- [CBOR's RFC 7049](https://tools.ietf.org/html/rfc7049) describes this type
- as:
- > Major type 2: a byte string. The string's length in bytes is represented
- > following the rules for positive integers (major type 0).
-
- [MessagePack's documentation on the bin type
- family](https://github.com/msgpack/msgpack/blob/master/spec.md#bin-format-family)
- describes this type as:
- > Bin format family stores an byte array in 2, 3, or 5 bytes of extra bytes
- > in addition to the size of the byte array.
-
- [BSON's specifications](http://bsonspec.org/spec.html) describe several
- binary types; however, this type is intended to represent the generic binary
- type which has the description:
- > Generic binary subtype - This is the most commonly used binary subtype and
- > should be the 'default' for drivers and tools.
-
- None of these impose any limitations on the internal representation other
- than the basic unit of storage be some type of array whose parts are
- decomposable into bytes.
-
- The default representation of this binary format is a
- `std::vector<std::uint8_t>`, which is a very common way to represent a byte
- array in modern C++.
-
- #### Default type
-
- The default values for @a BinaryType is `std::vector<std::uint8_t>`
-
- #### Storage
-
- Binary Arrays are stored as pointers in a @ref basic_json type. That is,
- for any access to array values, a pointer of the type `binary_t*` must be
- dereferenced.
-
- #### Notes on subtypes
-
- - CBOR
- - Binary values are represented as byte strings. Subtypes are serialized
- as tagged values.
- - MessagePack
- - If a subtype is given and the binary array contains exactly 1, 2, 4, 8,
- or 16 elements, the fixext family (fixext1, fixext2, fixext4, fixext8)
- is used. For other sizes, the ext family (ext8, ext16, ext32) is used.
- The subtype is then added as singed 8-bit integer.
- - If no subtype is given, the bin family (bin8, bin16, bin32) is used.
- - BSON
- - If a subtype is given, it is used and added as unsigned 8-bit integer.
- - If no subtype is given, the generic binary subtype 0x00 is used.
-
- @sa see @ref binary -- create a binary array
-
- @since version 3.8.0
- */
+ /// @brief a type for a packed binary type
+ /// @sa https://json.nlohmann.me/api/basic_json/binary_t/
using binary_t = nlohmann::byte_container_with_subtype<BinaryType>;
+
/// @}
private:
@@ -1031,25 +486,25 @@
case value_t::boolean:
{
- boolean = boolean_t(false);
+ boolean = static_cast<boolean_t>(false);
break;
}
case value_t::number_integer:
{
- number_integer = number_integer_t(0);
+ number_integer = static_cast<number_integer_t>(0);
break;
}
case value_t::number_unsigned:
{
- number_unsigned = number_unsigned_t(0);
+ number_unsigned = static_cast<number_unsigned_t>(0);
break;
}
case value_t::number_float:
{
- number_float = number_float_t(0.0);
+ number_float = static_cast<number_float_t>(0.0);
break;
}
@@ -1065,7 +520,7 @@
object = nullptr; // silence warning, see #821
if (JSON_HEDLEY_UNLIKELY(t == value_t::null))
{
- JSON_THROW(other_error::create(500, "961c151d2e87f2686a955a9be24d316f1362bf21 3.10.4", basic_json())); // LCOV_EXCL_LINE
+ JSON_THROW(other_error::create(500, "961c151d2e87f2686a955a9be24d316f1362bf21 3.10.5", basic_json())); // LCOV_EXCL_LINE
}
break;
}
@@ -1073,64 +528,34 @@
}
/// constructor for strings
- json_value(const string_t& value)
- {
- string = create<string_t>(value);
- }
+ json_value(const string_t& value) : string(create<string_t>(value)) {}
/// constructor for rvalue strings
- json_value(string_t&& value)
- {
- string = create<string_t>(std::move(value));
- }
+ json_value(string_t&& value) : string(create<string_t>(std::move(value))) {}
/// constructor for objects
- json_value(const object_t& value)
- {
- object = create<object_t>(value);
- }
+ json_value(const object_t& value) : object(create<object_t>(value)) {}
/// constructor for rvalue objects
- json_value(object_t&& value)
- {
- object = create<object_t>(std::move(value));
- }
+ json_value(object_t&& value) : object(create<object_t>(std::move(value))) {}
/// constructor for arrays
- json_value(const array_t& value)
- {
- array = create<array_t>(value);
- }
+ json_value(const array_t& value) : array(create<array_t>(value)) {}
/// constructor for rvalue arrays
- json_value(array_t&& value)
- {
- array = create<array_t>(std::move(value));
- }
+ json_value(array_t&& value) : array(create<array_t>(std::move(value))) {}
/// constructor for binary arrays
- json_value(const typename binary_t::container_type& value)
- {
- binary = create<binary_t>(value);
- }
+ json_value(const typename binary_t::container_type& value) : binary(create<binary_t>(value)) {}
/// constructor for rvalue binary arrays
- json_value(typename binary_t::container_type&& value)
- {
- binary = create<binary_t>(std::move(value));
- }
+ json_value(typename binary_t::container_type&& value) : binary(create<binary_t>(std::move(value))) {}
/// constructor for binary arrays (internal type)
- json_value(const binary_t& value)
- {
- binary = create<binary_t>(value);
- }
+ json_value(const binary_t& value) : binary(create<binary_t>(value)) {}
/// constructor for rvalue binary arrays (internal type)
- json_value(binary_t&& value)
- {
- binary = create<binary_t>(std::move(value));
- }
+ json_value(binary_t&& value) : binary(create<binary_t>(std::move(value))) {}
void destroy(value_t t)
{
@@ -1308,23 +733,23 @@
#endif
}
- iterator set_parents(iterator it, typename iterator::difference_type count)
+ iterator set_parents(iterator it, typename iterator::difference_type count_set_parents)
{
#if JSON_DIAGNOSTICS
- for (typename iterator::difference_type i = 0; i < count; ++i)
+ for (typename iterator::difference_type i = 0; i < count_set_parents; ++i)
{
(it + i)->m_parent = this;
}
#else
- static_cast<void>(count);
+ static_cast<void>(count_set_parents);
#endif
return it;
}
- reference set_parent(reference j, std::size_t old_capacity = std::size_t(-1))
+ reference set_parent(reference j, std::size_t old_capacity = static_cast<std::size_t>(-1))
{
#if JSON_DIAGNOSTICS
- if (old_capacity != std::size_t(-1))
+ if (old_capacity != static_cast<std::size_t>(-1))
{
// see https://github.com/nlohmann/json/issues/2838
JSON_ASSERT(type() == value_t::array);
@@ -1364,72 +789,12 @@
// JSON parser callback //
//////////////////////////
- /*!
- @brief parser event types
-
- The parser callback distinguishes the following events:
- - `object_start`: the parser read `{` and started to process a JSON object
- - `key`: the parser read a key of a value in an object
- - `object_end`: the parser read `}` and finished processing a JSON object
- - `array_start`: the parser read `[` and started to process a JSON array
- - `array_end`: the parser read `]` and finished processing a JSON array
- - `value`: the parser finished reading a JSON value
-
- @image html callback_events.png "Example when certain parse events are triggered"
-
- @sa see @ref parser_callback_t for more information and examples
- */
+ /// @brief parser event types
+ /// @sa https://json.nlohmann.me/api/basic_json/parse_event_t/
using parse_event_t = detail::parse_event_t;
- /*!
- @brief per-element parser callback type
-
- With a parser callback function, the result of parsing a JSON text can be
- influenced. When passed to @ref parse, it is called on certain events
- (passed as @ref parse_event_t via parameter @a event) with a set recursion
- depth @a depth and context JSON value @a parsed. The return value of the
- callback function is a boolean indicating whether the element that emitted
- the callback shall be kept or not.
-
- We distinguish six scenarios (determined by the event type) in which the
- callback function can be called. The following table describes the values
- of the parameters @a depth, @a event, and @a parsed.
-
- parameter @a event | description | parameter @a depth | parameter @a parsed
- ------------------ | ----------- | ------------------ | -------------------
- parse_event_t::object_start | the parser read `{` and started to process a JSON object | depth of the parent of the JSON object | a JSON value with type discarded
- parse_event_t::key | the parser read a key of a value in an object | depth of the currently parsed JSON object | a JSON string containing the key
- parse_event_t::object_end | the parser read `}` and finished processing a JSON object | depth of the parent of the JSON object | the parsed JSON object
- parse_event_t::array_start | the parser read `[` and started to process a JSON array | depth of the parent of the JSON array | a JSON value with type discarded
- parse_event_t::array_end | the parser read `]` and finished processing a JSON array | depth of the parent of the JSON array | the parsed JSON array
- parse_event_t::value | the parser finished reading a JSON value | depth of the value | the parsed JSON value
-
- @image html callback_events.png "Example when certain parse events are triggered"
-
- Discarding a value (i.e., returning `false`) has different effects
- depending on the context in which function was called:
-
- - Discarded values in structured types are skipped. That is, the parser
- will behave as if the discarded value was never read.
- - In case a value outside a structured type is skipped, it is replaced
- with `null`. This case happens if the top-level element is skipped.
-
- @param[in] depth the depth of the recursion during parsing
-
- @param[in] event an event of type parse_event_t indicating the context in
- the callback function has been called
-
- @param[in,out] parsed the current intermediate parse result; note that
- writing to this value has no effect for parse_event_t::key events
-
- @return Whether the JSON value which called the function during parsing
- should be kept (`true`) or not (`false`). In the latter case, it is either
- skipped completely or replaced by an empty discarded object.
-
- @sa see @ref parse for examples
-
- @since version 1.0.0
- */
+ /// @brief per-element parser callback type
+ /// @sa https://json.nlohmann.me/api/basic_json/parser_callback_t/
using parser_callback_t = detail::parser_callback_t<basic_json>;
//////////////////
@@ -1441,128 +806,24 @@
/// assignment, static functions creating objects, and the destructor.
/// @{
- /*!
- @brief create an empty value with a given type
-
- Create an empty JSON value with a given type. The value will be default
- initialized with an empty value which depends on the type:
-
- Value type | initial value
- ----------- | -------------
- null | `null`
- boolean | `false`
- string | `""`
- number | `0`
- object | `{}`
- array | `[]`
- binary | empty array
-
- @param[in] v the type of the value to create
-
- @complexity Constant.
-
- @exceptionsafety Strong guarantee: if an exception is thrown, there are no
- changes to any JSON value.
-
- @liveexample{The following code shows the constructor for different @ref
- value_t values,basic_json__value_t}
-
- @sa see @ref clear() -- restores the postcondition of this constructor
-
- @since version 1.0.0
- */
+ /// @brief create an empty value with a given type
+ /// @sa https://json.nlohmann.me/api/basic_json/basic_json/
basic_json(const value_t v)
: m_type(v), m_value(v)
{
assert_invariant();
}
- /*!
- @brief create a null object
-
- Create a `null` JSON value. It either takes a null pointer as parameter
- (explicitly creating `null`) or no parameter (implicitly creating `null`).
- The passed null pointer itself is not read -- it is only used to choose
- the right constructor.
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this constructor never throws
- exceptions.
-
- @liveexample{The following code shows the constructor with and without a
- null pointer parameter.,basic_json__nullptr_t}
-
- @since version 1.0.0
- */
+ /// @brief create a null object
+ /// @sa https://json.nlohmann.me/api/basic_json/basic_json/
basic_json(std::nullptr_t = nullptr) noexcept
: basic_json(value_t::null)
{
assert_invariant();
}
- /*!
- @brief create a JSON value
-
- This is a "catch all" constructor for all compatible JSON types; that is,
- types for which a `to_json()` method exists. The constructor forwards the
- parameter @a val to that method (to `json_serializer<U>::to_json` method
- with `U = uncvref_t<CompatibleType>`, to be exact).
-
- Template type @a CompatibleType includes, but is not limited to, the
- following types:
- - **arrays**: @ref array_t and all kinds of compatible containers such as
- `std::vector`, `std::deque`, `std::list`, `std::forward_list`,
- `std::array`, `std::valarray`, `std::set`, `std::unordered_set`,
- `std::multiset`, and `std::unordered_multiset` with a `value_type` from
- which a @ref basic_json value can be constructed.
- - **objects**: @ref object_t and all kinds of compatible associative
- containers such as `std::map`, `std::unordered_map`, `std::multimap`,
- and `std::unordered_multimap` with a `key_type` compatible to
- @ref string_t and a `value_type` from which a @ref basic_json value can
- be constructed.
- - **strings**: @ref string_t, string literals, and all compatible string
- containers can be used.
- - **numbers**: @ref number_integer_t, @ref number_unsigned_t,
- @ref number_float_t, and all convertible number types such as `int`,
- `size_t`, `int64_t`, `float` or `double` can be used.
- - **boolean**: @ref boolean_t / `bool` can be used.
- - **binary**: @ref binary_t / `std::vector<std::uint8_t>` may be used,
- unfortunately because string literals cannot be distinguished from binary
- character arrays by the C++ type system, all types compatible with `const
- char*` will be directed to the string constructor instead. This is both
- for backwards compatibility, and due to the fact that a binary type is not
- a standard JSON type.
-
- See the examples below.
-
- @tparam CompatibleType a type such that:
- - @a CompatibleType is not derived from `std::istream`,
- - @a CompatibleType is not @ref basic_json (to avoid hijacking copy/move
- constructors),
- - @a CompatibleType is not a different @ref basic_json type (i.e. with different template arguments)
- - @a CompatibleType is not a @ref basic_json nested type (e.g.,
- @ref json_pointer, @ref iterator, etc ...)
- - `json_serializer<U>` has a `to_json(basic_json_t&, CompatibleType&&)` method
-
- @tparam U = `uncvref_t<CompatibleType>`
-
- @param[in] val the value to be forwarded to the respective constructor
-
- @complexity Usually linear in the size of the passed @a val, also
- depending on the implementation of the called `to_json()`
- method.
-
- @exceptionsafety Depends on the called constructor. For types directly
- supported by the library (i.e., all types for which no `to_json()` function
- was provided), strong guarantee holds: if an exception is thrown, there are
- no changes to any JSON value.
-
- @liveexample{The following code shows the constructor with several
- compatible types.,basic_json__CompatibleType}
-
- @since version 2.1.0
- */
+ /// @brief create a JSON value from compatible types
+ /// @sa https://json.nlohmann.me/api/basic_json/basic_json/
template < typename CompatibleType,
typename U = detail::uncvref_t<CompatibleType>,
detail::enable_if_t <
@@ -1576,32 +837,8 @@
assert_invariant();
}
- /*!
- @brief create a JSON value from an existing one
-
- This is a constructor for existing @ref basic_json types.
- It does not hijack copy/move constructors, since the parameter has different
- template arguments than the current ones.
-
- The constructor tries to convert the internal @ref m_value of the parameter.
-
- @tparam BasicJsonType a type such that:
- - @a BasicJsonType is a @ref basic_json type.
- - @a BasicJsonType has different template arguments than @ref basic_json_t.
-
- @param[in] val the @ref basic_json value to be converted.
-
- @complexity Usually linear in the size of the passed @a val, also
- depending on the implementation of the called `to_json()`
- method.
-
- @exceptionsafety Depends on the called constructor. For types directly
- supported by the library (i.e., all types for which no `to_json()` function
- was provided), strong guarantee holds: if an exception is thrown, there are
- no changes to any JSON value.
-
- @since version 3.2.0
- */
+ /// @brief create a JSON value from an existing one
+ /// @sa https://json.nlohmann.me/api/basic_json/basic_json/
template < typename BasicJsonType,
detail::enable_if_t <
detail::is_basic_json<BasicJsonType>::value&& !std::is_same<basic_json, BasicJsonType>::value, int > = 0 >
@@ -1655,80 +892,8 @@
assert_invariant();
}
- /*!
- @brief create a container (array or object) from an initializer list
-
- Creates a JSON value of type array or object from the passed initializer
- list @a init. In case @a type_deduction is `true` (default), the type of
- the JSON value to be created is deducted from the initializer list @a init
- according to the following rules:
-
- 1. If the list is empty, an empty JSON object value `{}` is created.
- 2. If the list consists of pairs whose first element is a string, a JSON
- object value is created where the first elements of the pairs are
- treated as keys and the second elements are as values.
- 3. In all other cases, an array is created.
-
- The rules aim to create the best fit between a C++ initializer list and
- JSON values. The rationale is as follows:
-
- 1. The empty initializer list is written as `{}` which is exactly an empty
- JSON object.
- 2. C++ has no way of describing mapped types other than to list a list of
- pairs. As JSON requires that keys must be of type string, rule 2 is the
- weakest constraint one can pose on initializer lists to interpret them
- as an object.
- 3. In all other cases, the initializer list could not be interpreted as
- JSON object type, so interpreting it as JSON array type is safe.
-
- With the rules described above, the following JSON values cannot be
- expressed by an initializer list:
-
- - the empty array (`[]`): use @ref array(initializer_list_t)
- with an empty initializer list in this case
- - arrays whose elements satisfy rule 2: use @ref
- array(initializer_list_t) with the same initializer list
- in this case
-
- @note When used without parentheses around an empty initializer list, @ref
- basic_json() is called instead of this function, yielding the JSON null
- value.
-
- @param[in] init initializer list with JSON values
-
- @param[in] type_deduction internal parameter; when set to `true`, the type
- of the JSON value is deducted from the initializer list @a init; when set
- to `false`, the type provided via @a manual_type is forced. This mode is
- used by the functions @ref array(initializer_list_t) and
- @ref object(initializer_list_t).
-
- @param[in] manual_type internal parameter; when @a type_deduction is set
- to `false`, the created JSON value will use the provided type (only @ref
- value_t::array and @ref value_t::object are valid); when @a type_deduction
- is set to `true`, this parameter has no effect
-
- @throw type_error.301 if @a type_deduction is `false`, @a manual_type is
- `value_t::object`, but @a init contains an element which is not a pair
- whose first element is a string. In this case, the constructor could not
- create an object. If @a type_deduction would have be `true`, an array
- would have been created. See @ref object(initializer_list_t)
- for an example.
-
- @complexity Linear in the size of the initializer list @a init.
-
- @exceptionsafety Strong guarantee: if an exception is thrown, there are no
- changes to any JSON value.
-
- @liveexample{The example below shows how JSON values are created from
- initializer lists.,basic_json__list_init_t}
-
- @sa see @ref array(initializer_list_t) -- create a JSON array
- value from an initializer list
- @sa see @ref object(initializer_list_t) -- create a JSON object
- value from an initializer list
-
- @since version 1.0.0
- */
+ /// @brief create a container (array or object) from an initializer list
+ /// @sa https://json.nlohmann.me/api/basic_json/basic_json/
basic_json(initializer_list_t init,
bool type_deduction = true,
value_t manual_type = value_t::array)
@@ -1782,33 +947,8 @@
assert_invariant();
}
- /*!
- @brief explicitly create a binary array (without subtype)
-
- Creates a JSON binary array value from a given binary container. Binary
- values are part of various binary formats, such as CBOR, MessagePack, and
- BSON. This constructor is used to create a value for serialization to those
- formats.
-
- @note Note, this function exists because of the difficulty in correctly
- specifying the correct template overload in the standard value ctor, as both
- JSON arrays and JSON binary arrays are backed with some form of a
- `std::vector`. Because JSON binary arrays are a non-standard extension it
- was decided that it would be best to prevent automatic initialization of a
- binary array type, for backwards compatibility and so it does not happen on
- accident.
-
- @param[in] init container containing bytes to use as binary type
-
- @return JSON binary array value
-
- @complexity Linear in the size of @a init.
-
- @exceptionsafety Strong guarantee: if an exception is thrown, there are no
- changes to any JSON value.
-
- @since version 3.8.0
- */
+ /// @brief explicitly create a binary array (without subtype)
+ /// @sa https://json.nlohmann.me/api/basic_json/binary/
JSON_HEDLEY_WARN_UNUSED_RESULT
static basic_json binary(const typename binary_t::container_type& init)
{
@@ -1818,34 +958,8 @@
return res;
}
- /*!
- @brief explicitly create a binary array (with subtype)
-
- Creates a JSON binary array value from a given binary container. Binary
- values are part of various binary formats, such as CBOR, MessagePack, and
- BSON. This constructor is used to create a value for serialization to those
- formats.
-
- @note Note, this function exists because of the difficulty in correctly
- specifying the correct template overload in the standard value ctor, as both
- JSON arrays and JSON binary arrays are backed with some form of a
- `std::vector`. Because JSON binary arrays are a non-standard extension it
- was decided that it would be best to prevent automatic initialization of a
- binary array type, for backwards compatibility and so it does not happen on
- accident.
-
- @param[in] init container containing bytes to use as binary type
- @param[in] subtype subtype to use in MessagePack and BSON
-
- @return JSON binary array value
-
- @complexity Linear in the size of @a init.
-
- @exceptionsafety Strong guarantee: if an exception is thrown, there are no
- changes to any JSON value.
-
- @since version 3.8.0
- */
+ /// @brief explicitly create a binary array (with subtype)
+ /// @sa https://json.nlohmann.me/api/basic_json/binary/
JSON_HEDLEY_WARN_UNUSED_RESULT
static basic_json binary(const typename binary_t::container_type& init, typename binary_t::subtype_type subtype)
{
@@ -1855,7 +969,8 @@
return res;
}
- /// @copydoc binary(const typename binary_t::container_type&)
+ /// @brief explicitly create a binary array
+ /// @sa https://json.nlohmann.me/api/basic_json/binary/
JSON_HEDLEY_WARN_UNUSED_RESULT
static basic_json binary(typename binary_t::container_type&& init)
{
@@ -1865,7 +980,8 @@
return res;
}
- /// @copydoc binary(const typename binary_t::container_type&, typename binary_t::subtype_type)
+ /// @brief explicitly create a binary array (with subtype)
+ /// @sa https://json.nlohmann.me/api/basic_json/binary/
JSON_HEDLEY_WARN_UNUSED_RESULT
static basic_json binary(typename binary_t::container_type&& init, typename binary_t::subtype_type subtype)
{
@@ -1875,115 +991,24 @@
return res;
}
- /*!
- @brief explicitly create an array from an initializer list
-
- Creates a JSON array value from a given initializer list. That is, given a
- list of values `a, b, c`, creates the JSON value `[a, b, c]`. If the
- initializer list is empty, the empty array `[]` is created.
-
- @note This function is only needed to express two edge cases that cannot
- be realized with the initializer list constructor (@ref
- basic_json(initializer_list_t, bool, value_t)). These cases
- are:
- 1. creating an array whose elements are all pairs whose first element is a
- string -- in this case, the initializer list constructor would create an
- object, taking the first elements as keys
- 2. creating an empty array -- passing the empty initializer list to the
- initializer list constructor yields an empty object
-
- @param[in] init initializer list with JSON values to create an array from
- (optional)
-
- @return JSON array value
-
- @complexity Linear in the size of @a init.
-
- @exceptionsafety Strong guarantee: if an exception is thrown, there are no
- changes to any JSON value.
-
- @liveexample{The following code shows an example for the `array`
- function.,array}
-
- @sa see @ref basic_json(initializer_list_t, bool, value_t) --
- create a JSON value from an initializer list
- @sa see @ref object(initializer_list_t) -- create a JSON object
- value from an initializer list
-
- @since version 1.0.0
- */
+ /// @brief explicitly create an array from an initializer list
+ /// @sa https://json.nlohmann.me/api/basic_json/array/
JSON_HEDLEY_WARN_UNUSED_RESULT
static basic_json array(initializer_list_t init = {})
{
return basic_json(init, false, value_t::array);
}
- /*!
- @brief explicitly create an object from an initializer list
-
- Creates a JSON object value from a given initializer list. The initializer
- lists elements must be pairs, and their first elements must be strings. If
- the initializer list is empty, the empty object `{}` is created.
-
- @note This function is only added for symmetry reasons. In contrast to the
- related function @ref array(initializer_list_t), there are
- no cases which can only be expressed by this function. That is, any
- initializer list @a init can also be passed to the initializer list
- constructor @ref basic_json(initializer_list_t, bool, value_t).
-
- @param[in] init initializer list to create an object from (optional)
-
- @return JSON object value
-
- @throw type_error.301 if @a init is not a list of pairs whose first
- elements are strings. In this case, no object can be created. When such a
- value is passed to @ref basic_json(initializer_list_t, bool, value_t),
- an array would have been created from the passed initializer list @a init.
- See example below.
-
- @complexity Linear in the size of @a init.
-
- @exceptionsafety Strong guarantee: if an exception is thrown, there are no
- changes to any JSON value.
-
- @liveexample{The following code shows an example for the `object`
- function.,object}
-
- @sa see @ref basic_json(initializer_list_t, bool, value_t) --
- create a JSON value from an initializer list
- @sa see @ref array(initializer_list_t) -- create a JSON array
- value from an initializer list
-
- @since version 1.0.0
- */
+ /// @brief explicitly create an object from an initializer list
+ /// @sa https://json.nlohmann.me/api/basic_json/object/
JSON_HEDLEY_WARN_UNUSED_RESULT
static basic_json object(initializer_list_t init = {})
{
return basic_json(init, false, value_t::object);
}
- /*!
- @brief construct an array with count copies of given value
-
- Constructs a JSON array value by creating @a cnt copies of a passed value.
- In case @a cnt is `0`, an empty array is created.
-
- @param[in] cnt the number of JSON copies of @a val to create
- @param[in] val the JSON value to copy
-
- @post `std::distance(begin(),end()) == cnt` holds.
-
- @complexity Linear in @a cnt.
-
- @exceptionsafety Strong guarantee: if an exception is thrown, there are no
- changes to any JSON value.
-
- @liveexample{The following code shows examples for the @ref
- basic_json(size_type\, const basic_json&)
- constructor.,basic_json__size_type_basic_json}
-
- @since version 1.0.0
- */
+ /// @brief construct an array with count copies of given value
+ /// @sa https://json.nlohmann.me/api/basic_json/basic_json/
basic_json(size_type cnt, const basic_json& val)
: m_type(value_t::array)
{
@@ -1992,61 +1017,8 @@
assert_invariant();
}
- /*!
- @brief construct a JSON container given an iterator range
-
- Constructs the JSON value with the contents of the range `[first, last)`.
- The semantics depends on the different types a JSON value can have:
- - In case of a null type, invalid_iterator.206 is thrown.
- - In case of other primitive types (number, boolean, or string), @a first
- must be `begin()` and @a last must be `end()`. In this case, the value is
- copied. Otherwise, invalid_iterator.204 is thrown.
- - In case of structured types (array, object), the constructor behaves as
- similar versions for `std::vector` or `std::map`; that is, a JSON array
- or object is constructed from the values in the range.
-
- @tparam InputIT an input iterator type (@ref iterator or @ref
- const_iterator)
-
- @param[in] first begin of the range to copy from (included)
- @param[in] last end of the range to copy from (excluded)
-
- @pre Iterators @a first and @a last must be initialized. **This
- precondition is enforced with an assertion (see warning).** If
- assertions are switched off, a violation of this precondition yields
- undefined behavior.
-
- @pre Range `[first, last)` is valid. Usually, this precondition cannot be
- checked efficiently. Only certain edge cases are detected; see the
- description of the exceptions below. A violation of this precondition
- yields undefined behavior.
-
- @warning A precondition is enforced with a runtime assertion that will
- result in calling `std::abort` if this precondition is not met.
- Assertions can be disabled by defining `NDEBUG` at compile time.
- See https://en.cppreference.com/w/cpp/error/assert for more
- information.
-
- @throw invalid_iterator.201 if iterators @a first and @a last are not
- compatible (i.e., do not belong to the same JSON value). In this case,
- the range `[first, last)` is undefined.
- @throw invalid_iterator.204 if iterators @a first and @a last belong to a
- primitive type (number, boolean, or string), but @a first does not point
- to the first element any more. In this case, the range `[first, last)` is
- undefined. See example code below.
- @throw invalid_iterator.206 if iterators @a first and @a last belong to a
- null value. In this case, the range `[first, last)` is undefined.
-
- @complexity Linear in distance between @a first and @a last.
-
- @exceptionsafety Strong guarantee: if an exception is thrown, there are no
- changes to any JSON value.
-
- @liveexample{The example below shows several ways to create JSON values by
- specifying a subrange with iterators.,basic_json__InputIt_InputIt}
-
- @since version 1.0.0
- */
+ /// @brief construct a JSON container given an iterator range
+ /// @sa https://json.nlohmann.me/api/basic_json/basic_json/
template < class InputIT, typename std::enable_if <
std::is_same<InputIT, typename basic_json_t::iterator>::value ||
std::is_same<InputIT, typename basic_json_t::const_iterator>::value, int >::type = 0 >
@@ -2162,31 +1134,8 @@
std::is_same<typename JsonRef::value_type, basic_json>>::value, int> = 0 >
basic_json(const JsonRef& ref) : basic_json(ref.moved_or_copied()) {}
- /*!
- @brief copy constructor
-
- Creates a copy of a given JSON value.
-
- @param[in] other the JSON value to copy
-
- @post `*this == other`
-
- @complexity Linear in the size of @a other.
-
- @exceptionsafety Strong guarantee: if an exception is thrown, there are no
- changes to any JSON value.
-
- @requirement This function helps `basic_json` satisfying the
- [Container](https://en.cppreference.com/w/cpp/named_req/Container)
- requirements:
- - The complexity is linear.
- - As postcondition, it holds: `other == basic_json(other)`.
-
- @liveexample{The following code shows an example for the copy
- constructor.,basic_json__basic_json}
-
- @since version 1.0.0
- */
+ /// @brief copy constructor
+ /// @sa https://json.nlohmann.me/api/basic_json/basic_json/
basic_json(const basic_json& other)
: m_type(other.m_type)
{
@@ -2253,32 +1202,8 @@
assert_invariant();
}
- /*!
- @brief move constructor
-
- Move constructor. Constructs a JSON value with the contents of the given
- value @a other using move semantics. It "steals" the resources from @a
- other and leaves it as JSON null value.
-
- @param[in,out] other value to move to this object
-
- @post `*this` has the same value as @a other before the call.
- @post @a other is a JSON null value.
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this constructor never throws
- exceptions.
-
- @requirement This function helps `basic_json` satisfying the
- [MoveConstructible](https://en.cppreference.com/w/cpp/named_req/MoveConstructible)
- requirements.
-
- @liveexample{The code below shows the move constructor explicitly called
- via std::move.,basic_json__moveconstructor}
-
- @since version 1.0.0
- */
+ /// @brief move constructor
+ /// @sa https://json.nlohmann.me/api/basic_json/basic_json/
basic_json(basic_json&& other) noexcept
: m_type(std::move(other.m_type)),
m_value(std::move(other.m_value))
@@ -2294,29 +1219,8 @@
assert_invariant();
}
- /*!
- @brief copy assignment
-
- Copy assignment operator. Copies a JSON value via the "copy and swap"
- strategy: It is expressed in terms of the copy constructor, destructor,
- and the `swap()` member function.
-
- @param[in] other value to copy from
-
- @complexity Linear.
-
- @requirement This function helps `basic_json` satisfying the
- [Container](https://en.cppreference.com/w/cpp/named_req/Container)
- requirements:
- - The complexity is linear.
-
- @liveexample{The code below shows and example for the copy assignment. It
- creates a copy of value `a` which is then swapped with `b`. Finally\, the
- copy of `a` (which is the null value after the swap) is
- destroyed.,basic_json__copyassignment}
-
- @since version 1.0.0
- */
+ /// @brief copy assignment
+ /// @sa https://json.nlohmann.me/api/basic_json/operator=/
basic_json& operator=(basic_json other) noexcept (
std::is_nothrow_move_constructible<value_t>::value&&
std::is_nothrow_move_assignable<value_t>::value&&
@@ -2336,21 +1240,8 @@
return *this;
}
- /*!
- @brief destructor
-
- Destroys the JSON value and frees all allocated memory.
-
- @complexity Linear.
-
- @requirement This function helps `basic_json` satisfying the
- [Container](https://en.cppreference.com/w/cpp/named_req/Container)
- requirements:
- - The complexity is linear.
- - All stored elements are destroyed and all memory is freed.
-
- @since version 1.0.0
- */
+ /// @brief destructor
+ /// @sa https://json.nlohmann.me/api/basic_json/~basic_json/
~basic_json() noexcept
{
assert_invariant(false);
@@ -2368,53 +1259,8 @@
/// Functions to inspect the type of a JSON value.
/// @{
- /*!
- @brief serialization
-
- Serialization function for JSON values. The function tries to mimic
- Python's `json.dumps()` function, and currently supports its @a indent
- and @a ensure_ascii parameters.
-
- @param[in] indent If indent is nonnegative, then array elements and object
- members will be pretty-printed with that indent level. An indent level of
- `0` will only insert newlines. `-1` (the default) selects the most compact
- representation.
- @param[in] indent_char The character to use for indentation if @a indent is
- greater than `0`. The default is ` ` (space).
- @param[in] ensure_ascii If @a ensure_ascii is true, all non-ASCII characters
- in the output are escaped with `\uXXXX` sequences, and the result consists
- of ASCII characters only.
- @param[in] error_handler how to react on decoding errors; there are three
- possible values: `strict` (throws and exception in case a decoding error
- occurs; default), `replace` (replace invalid UTF-8 sequences with U+FFFD),
- and `ignore` (ignore invalid UTF-8 sequences during serialization; all
- bytes are copied to the output unchanged).
-
- @return string containing the serialization of the JSON value
-
- @throw type_error.316 if a string stored inside the JSON value is not
- UTF-8 encoded and @a error_handler is set to strict
-
- @note Binary values are serialized as object containing two keys:
- - "bytes": an array of bytes as integers
- - "subtype": the subtype as integer or "null" if the binary has no subtype
-
- @complexity Linear.
-
- @exceptionsafety Strong guarantee: if an exception is thrown, there are no
- changes in the JSON value.
-
- @liveexample{The following example shows the effect of different @a indent\,
- @a indent_char\, and @a ensure_ascii parameters to the result of the
- serialization.,dump}
-
- @see https://docs.python.org/2/library/json.html#json.dump
-
- @since version 1.0.0; indentation character @a indent_char, option
- @a ensure_ascii and exceptions added in version 3.0.0; error
- handlers added in version 3.4.0; serialization of binary values added
- in version 3.8.0.
- */
+ /// @brief serialization
+ /// @sa https://json.nlohmann.me/api/basic_json/dump/
string_t dump(const int indent = -1,
const char indent_char = ' ',
const bool ensure_ascii = false,
@@ -2435,397 +1281,106 @@
return result;
}
- /*!
- @brief return the type of the JSON value (explicit)
-
- Return the type of the JSON value as a value from the @ref value_t
- enumeration.
-
- @return the type of the JSON value
- Value type | return value
- ------------------------- | -------------------------
- null | value_t::null
- boolean | value_t::boolean
- string | value_t::string
- number (integer) | value_t::number_integer
- number (unsigned integer) | value_t::number_unsigned
- number (floating-point) | value_t::number_float
- object | value_t::object
- array | value_t::array
- binary | value_t::binary
- discarded | value_t::discarded
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this member function never throws
- exceptions.
-
- @liveexample{The following code exemplifies `type()` for all JSON
- types.,type}
-
- @sa see @ref operator value_t() -- return the type of the JSON value (implicit)
- @sa see @ref type_name() -- return the type as string
-
- @since version 1.0.0
- */
+ /// @brief return the type of the JSON value (explicit)
+ /// @sa https://json.nlohmann.me/api/basic_json/type/
constexpr value_t type() const noexcept
{
return m_type;
}
- /*!
- @brief return whether type is primitive
-
- This function returns true if and only if the JSON type is primitive
- (string, number, boolean, or null).
-
- @return `true` if type is primitive (string, number, boolean, or null),
- `false` otherwise.
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this member function never throws
- exceptions.
-
- @liveexample{The following code exemplifies `is_primitive()` for all JSON
- types.,is_primitive}
-
- @sa see @ref is_structured() -- returns whether JSON value is structured
- @sa see @ref is_null() -- returns whether JSON value is `null`
- @sa see @ref is_string() -- returns whether JSON value is a string
- @sa see @ref is_boolean() -- returns whether JSON value is a boolean
- @sa see @ref is_number() -- returns whether JSON value is a number
- @sa see @ref is_binary() -- returns whether JSON value is a binary array
-
- @since version 1.0.0
- */
+ /// @brief return whether type is primitive
+ /// @sa https://json.nlohmann.me/api/basic_json/is_primitive/
constexpr bool is_primitive() const noexcept
{
return is_null() || is_string() || is_boolean() || is_number() || is_binary();
}
- /*!
- @brief return whether type is structured
-
- This function returns true if and only if the JSON type is structured
- (array or object).
-
- @return `true` if type is structured (array or object), `false` otherwise.
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this member function never throws
- exceptions.
-
- @liveexample{The following code exemplifies `is_structured()` for all JSON
- types.,is_structured}
-
- @sa see @ref is_primitive() -- returns whether value is primitive
- @sa see @ref is_array() -- returns whether value is an array
- @sa see @ref is_object() -- returns whether value is an object
-
- @since version 1.0.0
- */
+ /// @brief return whether type is structured
+ /// @sa https://json.nlohmann.me/api/basic_json/is_structured/
constexpr bool is_structured() const noexcept
{
return is_array() || is_object();
}
- /*!
- @brief return whether value is null
-
- This function returns true if and only if the JSON value is null.
-
- @return `true` if type is null, `false` otherwise.
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this member function never throws
- exceptions.
-
- @liveexample{The following code exemplifies `is_null()` for all JSON
- types.,is_null}
-
- @since version 1.0.0
- */
+ /// @brief return whether value is null
+ /// @sa https://json.nlohmann.me/api/basic_json/is_null/
constexpr bool is_null() const noexcept
{
return m_type == value_t::null;
}
- /*!
- @brief return whether value is a boolean
-
- This function returns true if and only if the JSON value is a boolean.
-
- @return `true` if type is boolean, `false` otherwise.
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this member function never throws
- exceptions.
-
- @liveexample{The following code exemplifies `is_boolean()` for all JSON
- types.,is_boolean}
-
- @since version 1.0.0
- */
+ /// @brief return whether value is a boolean
+ /// @sa https://json.nlohmann.me/api/basic_json/is_boolean/
constexpr bool is_boolean() const noexcept
{
return m_type == value_t::boolean;
}
- /*!
- @brief return whether value is a number
-
- This function returns true if and only if the JSON value is a number. This
- includes both integer (signed and unsigned) and floating-point values.
-
- @return `true` if type is number (regardless whether integer, unsigned
- integer or floating-type), `false` otherwise.
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this member function never throws
- exceptions.
-
- @liveexample{The following code exemplifies `is_number()` for all JSON
- types.,is_number}
-
- @sa see @ref is_number_integer() -- check if value is an integer or unsigned
- integer number
- @sa see @ref is_number_unsigned() -- check if value is an unsigned integer
- number
- @sa see @ref is_number_float() -- check if value is a floating-point number
-
- @since version 1.0.0
- */
+ /// @brief return whether value is a number
+ /// @sa https://json.nlohmann.me/api/basic_json/is_number/
constexpr bool is_number() const noexcept
{
return is_number_integer() || is_number_float();
}
- /*!
- @brief return whether value is an integer number
-
- This function returns true if and only if the JSON value is a signed or
- unsigned integer number. This excludes floating-point values.
-
- @return `true` if type is an integer or unsigned integer number, `false`
- otherwise.
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this member function never throws
- exceptions.
-
- @liveexample{The following code exemplifies `is_number_integer()` for all
- JSON types.,is_number_integer}
-
- @sa see @ref is_number() -- check if value is a number
- @sa see @ref is_number_unsigned() -- check if value is an unsigned integer
- number
- @sa see @ref is_number_float() -- check if value is a floating-point number
-
- @since version 1.0.0
- */
+ /// @brief return whether value is an integer number
+ /// @sa https://json.nlohmann.me/api/basic_json/is_number_integer/
constexpr bool is_number_integer() const noexcept
{
return m_type == value_t::number_integer || m_type == value_t::number_unsigned;
}
- /*!
- @brief return whether value is an unsigned integer number
-
- This function returns true if and only if the JSON value is an unsigned
- integer number. This excludes floating-point and signed integer values.
-
- @return `true` if type is an unsigned integer number, `false` otherwise.
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this member function never throws
- exceptions.
-
- @liveexample{The following code exemplifies `is_number_unsigned()` for all
- JSON types.,is_number_unsigned}
-
- @sa see @ref is_number() -- check if value is a number
- @sa see @ref is_number_integer() -- check if value is an integer or unsigned
- integer number
- @sa see @ref is_number_float() -- check if value is a floating-point number
-
- @since version 2.0.0
- */
+ /// @brief return whether value is an unsigned integer number
+ /// @sa https://json.nlohmann.me/api/basic_json/is_number_unsigned/
constexpr bool is_number_unsigned() const noexcept
{
return m_type == value_t::number_unsigned;
}
- /*!
- @brief return whether value is a floating-point number
-
- This function returns true if and only if the JSON value is a
- floating-point number. This excludes signed and unsigned integer values.
-
- @return `true` if type is a floating-point number, `false` otherwise.
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this member function never throws
- exceptions.
-
- @liveexample{The following code exemplifies `is_number_float()` for all
- JSON types.,is_number_float}
-
- @sa see @ref is_number() -- check if value is number
- @sa see @ref is_number_integer() -- check if value is an integer number
- @sa see @ref is_number_unsigned() -- check if value is an unsigned integer
- number
-
- @since version 1.0.0
- */
+ /// @brief return whether value is a floating-point number
+ /// @sa https://json.nlohmann.me/api/basic_json/is_number_float/
constexpr bool is_number_float() const noexcept
{
return m_type == value_t::number_float;
}
- /*!
- @brief return whether value is an object
-
- This function returns true if and only if the JSON value is an object.
-
- @return `true` if type is object, `false` otherwise.
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this member function never throws
- exceptions.
-
- @liveexample{The following code exemplifies `is_object()` for all JSON
- types.,is_object}
-
- @since version 1.0.0
- */
+ /// @brief return whether value is an object
+ /// @sa https://json.nlohmann.me/api/basic_json/is_object/
constexpr bool is_object() const noexcept
{
return m_type == value_t::object;
}
- /*!
- @brief return whether value is an array
-
- This function returns true if and only if the JSON value is an array.
-
- @return `true` if type is array, `false` otherwise.
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this member function never throws
- exceptions.
-
- @liveexample{The following code exemplifies `is_array()` for all JSON
- types.,is_array}
-
- @since version 1.0.0
- */
+ /// @brief return whether value is an array
+ /// @sa https://json.nlohmann.me/api/basic_json/is_array/
constexpr bool is_array() const noexcept
{
return m_type == value_t::array;
}
- /*!
- @brief return whether value is a string
-
- This function returns true if and only if the JSON value is a string.
-
- @return `true` if type is string, `false` otherwise.
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this member function never throws
- exceptions.
-
- @liveexample{The following code exemplifies `is_string()` for all JSON
- types.,is_string}
-
- @since version 1.0.0
- */
+ /// @brief return whether value is a string
+ /// @sa https://json.nlohmann.me/api/basic_json/is_string/
constexpr bool is_string() const noexcept
{
return m_type == value_t::string;
}
- /*!
- @brief return whether value is a binary array
-
- This function returns true if and only if the JSON value is a binary array.
-
- @return `true` if type is binary array, `false` otherwise.
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this member function never throws
- exceptions.
-
- @liveexample{The following code exemplifies `is_binary()` for all JSON
- types.,is_binary}
-
- @since version 3.8.0
- */
+ /// @brief return whether value is a binary array
+ /// @sa https://json.nlohmann.me/api/basic_json/is_binary/
constexpr bool is_binary() const noexcept
{
return m_type == value_t::binary;
}
- /*!
- @brief return whether value is discarded
-
- This function returns true if and only if the JSON value was discarded
- during parsing with a callback function (see @ref parser_callback_t).
-
- @note This function will always be `false` for JSON values after parsing.
- That is, discarded values can only occur during parsing, but will be
- removed when inside a structured value or replaced by null in other cases.
-
- @return `true` if type is discarded, `false` otherwise.
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this member function never throws
- exceptions.
-
- @liveexample{The following code exemplifies `is_discarded()` for all JSON
- types.,is_discarded}
-
- @since version 1.0.0
- */
+ /// @brief return whether value is discarded
+ /// @sa https://json.nlohmann.me/api/basic_json/is_discarded/
constexpr bool is_discarded() const noexcept
{
return m_type == value_t::discarded;
}
- /*!
- @brief return the type of the JSON value (implicit)
-
- Implicitly return the type of the JSON value as a value from the @ref
- value_t enumeration.
-
- @return the type of the JSON value
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this member function never throws
- exceptions.
-
- @liveexample{The following code exemplifies the @ref value_t operator for
- all JSON types.,operator__value_t}
-
- @sa see @ref type() -- return the type of the JSON value (explicit)
- @sa see @ref type_name() -- return the type as string
-
- @since version 1.0.0
- */
+ /// @brief return the type of the JSON value (implicit)
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_value_t/
constexpr operator value_t() const noexcept
{
return m_type;
@@ -2975,32 +1530,8 @@
/// Direct access to the stored value of a JSON value.
/// @{
- /*!
- @brief get a pointer value (implicit)
-
- Implicit pointer access to the internally stored JSON value. No copies are
- made.
-
- @warning Writing data to the pointee of the result yields an undefined
- state.
-
- @tparam PointerType pointer type; must be a pointer to @ref array_t, @ref
- object_t, @ref string_t, @ref boolean_t, @ref number_integer_t,
- @ref number_unsigned_t, or @ref number_float_t. Enforced by a static
- assertion.
-
- @return pointer to the internally stored JSON value if the requested
- pointer type @a PointerType fits to the JSON value; `nullptr` otherwise
-
- @complexity Constant.
-
- @liveexample{The example below shows how pointers to internal values of a
- JSON value can be requested. Note that no type conversions are made and a
- `nullptr` is returned if the value and the requested pointer type does not
- match.,get_ptr}
-
- @since version 1.0.0
- */
+ /// @brief get a pointer value (implicit)
+ /// @sa https://json.nlohmann.me/api/basic_json/get_ptr/
template<typename PointerType, typename std::enable_if<
std::is_pointer<PointerType>::value, int>::type = 0>
auto get_ptr() noexcept -> decltype(std::declval<basic_json_t&>().get_impl_ptr(std::declval<PointerType>()))
@@ -3009,10 +1540,8 @@
return get_impl_ptr(static_cast<PointerType>(nullptr));
}
- /*!
- @brief get a pointer value (implicit)
- @copydoc get_ptr()
- */
+ /// @brief get a pointer value (implicit)
+ /// @sa https://json.nlohmann.me/api/basic_json/get_ptr/
template < typename PointerType, typename std::enable_if <
std::is_pointer<PointerType>::value&&
std::is_const<typename std::remove_pointer<PointerType>::type>::value, int >::type = 0 >
@@ -3251,39 +1780,8 @@
return get_ptr<PointerType>();
}
- /*!
- @brief get a value (explicit)
-
- Explicit type conversion between the JSON value and a compatible value.
- The value is filled into the input parameter by calling the @ref json_serializer<ValueType>
- `from_json()` method.
-
- The function is equivalent to executing
- @code {.cpp}
- ValueType v;
- JSONSerializer<ValueType>::from_json(*this, v);
- @endcode
-
- This overloads is chosen if:
- - @a ValueType is not @ref basic_json,
- - @ref json_serializer<ValueType> has a `from_json()` method of the form
- `void from_json(const basic_json&, ValueType&)`, and
-
- @tparam ValueType the input parameter type.
-
- @return the input parameter, allowing chaining calls.
-
- @throw what @ref json_serializer<ValueType> `from_json()` method throws
-
- @liveexample{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>`.,get_to}
-
- @since version 3.3.0
- */
+ /// @brief get a value (explicit)
+ /// @sa https://json.nlohmann.me/api/basic_json/get_to/
template < typename ValueType,
detail::enable_if_t <
!detail::is_basic_json<ValueType>::value&&
@@ -3296,7 +1794,7 @@
return v;
}
- // specialization to allow to call get_to with a basic_json value
+ // specialization to allow calling get_to with a basic_json value
// see https://github.com/nlohmann/json/issues/2175
template<typename ValueType,
detail::enable_if_t <
@@ -3321,32 +1819,8 @@
return v;
}
- /*!
- @brief get a reference value (implicit)
-
- Implicit reference access to the internally stored JSON value. No copies
- are made.
-
- @warning Writing data to the referee of the result yields an undefined
- state.
-
- @tparam ReferenceType reference type; must be a reference to @ref array_t,
- @ref object_t, @ref string_t, @ref boolean_t, @ref number_integer_t, or
- @ref number_float_t. Enforced by static assertion.
-
- @return reference to the internally stored JSON value if the requested
- reference type @a ReferenceType fits to the JSON value; throws
- type_error.303 otherwise
-
- @throw type_error.303 in case passed type @a ReferenceType is incompatible
- with the stored JSON value; see example below
-
- @complexity Constant.
-
- @liveexample{The example shows several calls to `get_ref()`.,get_ref}
-
- @since version 1.1.0
- */
+ /// @brief get a reference value (implicit)
+ /// @sa https://json.nlohmann.me/api/basic_json/get_ref/
template<typename ReferenceType, typename std::enable_if<
std::is_reference<ReferenceType>::value, int>::type = 0>
ReferenceType get_ref()
@@ -3355,10 +1829,8 @@
return get_ref_impl<ReferenceType>(*this);
}
- /*!
- @brief get a reference value (implicit)
- @copydoc get_ref()
- */
+ /// @brief get a reference value (implicit)
+ /// @sa https://json.nlohmann.me/api/basic_json/get_ref/
template < typename ReferenceType, typename std::enable_if <
std::is_reference<ReferenceType>::value&&
std::is_const<typename std::remove_reference<ReferenceType>::type>::value, int >::type = 0 >
@@ -3416,15 +1888,8 @@
return get<ValueType>();
}
- /*!
- @return reference to the binary value
-
- @throw type_error.302 if the value is not binary
-
- @sa see @ref is_binary() to check if the value is binary
-
- @since version 3.8.0
- */
+ /// @brief get a binary value
+ /// @sa https://json.nlohmann.me/api/basic_json/get_binary/
binary_t& get_binary()
{
if (!is_binary())
@@ -3435,7 +1900,8 @@
return *get_ptr<binary_t*>();
}
- /// @copydoc get_binary()
+ /// @brief get a binary value
+ /// @sa https://json.nlohmann.me/api/basic_json/get_binary/
const binary_t& get_binary() const
{
if (!is_binary())
@@ -3457,32 +1923,8 @@
/// Access to the JSON value.
/// @{
- /*!
- @brief access specified array element with bounds checking
-
- Returns a reference to the element at specified location @a idx, with
- bounds checking.
-
- @param[in] idx index of the element to access
-
- @return reference to the element at index @a idx
-
- @throw type_error.304 if the JSON value is not an array; in this case,
- calling `at` with an index makes no sense. See example below.
- @throw out_of_range.401 if the index @a idx is out of range of the array;
- that is, `idx >= size()`. See example below.
-
- @exceptionsafety Strong guarantee: if an exception is thrown, there are no
- changes in the JSON value.
-
- @complexity Constant.
-
- @since version 1.0.0
-
- @liveexample{The example below shows how array elements can be read and
- written using `at()`. It also demonstrates the different exceptions that
- can be thrown.,at__size_type}
- */
+ /// @brief access specified array element with bounds checking
+ /// @sa https://json.nlohmann.me/api/basic_json/at/
reference at(size_type idx)
{
// at only works for arrays
@@ -3504,32 +1946,8 @@
}
}
- /*!
- @brief access specified array element with bounds checking
-
- Returns a const reference to the element at specified location @a idx,
- with bounds checking.
-
- @param[in] idx index of the element to access
-
- @return const reference to the element at index @a idx
-
- @throw type_error.304 if the JSON value is not an array; in this case,
- calling `at` with an index makes no sense. See example below.
- @throw out_of_range.401 if the index @a idx is out of range of the array;
- that is, `idx >= size()`. See example below.
-
- @exceptionsafety Strong guarantee: if an exception is thrown, there are no
- changes in the JSON value.
-
- @complexity Constant.
-
- @since version 1.0.0
-
- @liveexample{The example below shows how array elements can be read using
- `at()`. It also demonstrates the different exceptions that can be thrown.,
- at__size_type_const}
- */
+ /// @brief access specified array element with bounds checking
+ /// @sa https://json.nlohmann.me/api/basic_json/at/
const_reference at(size_type idx) const
{
// at only works for arrays
@@ -3551,36 +1969,8 @@
}
}
- /*!
- @brief access specified object element with bounds checking
-
- Returns a reference to the element at with specified key @a key, with
- bounds checking.
-
- @param[in] key key of the element to access
-
- @return reference to the element at key @a key
-
- @throw type_error.304 if the JSON value is not an object; in this case,
- calling `at` with a key makes no sense. See example below.
- @throw out_of_range.403 if the key @a key is is not stored in the object;
- that is, `find(key) == end()`. See example below.
-
- @exceptionsafety Strong guarantee: if an exception is thrown, there are no
- changes in the JSON value.
-
- @complexity Logarithmic in the size of the container.
-
- @sa see @ref operator[](const typename object_t::key_type&) for unchecked
- access by reference
- @sa see @ref value() for access by value with a default value
-
- @since version 1.0.0
-
- @liveexample{The example below shows how object elements can be read and
- written using `at()`. It also demonstrates the different exceptions that
- can be thrown.,at__object_t_key_type}
- */
+ /// @brief access specified object element with bounds checking
+ /// @sa https://json.nlohmann.me/api/basic_json/at/
reference at(const typename object_t::key_type& key)
{
// at only works for objects
@@ -3602,36 +1992,8 @@
}
}
- /*!
- @brief access specified object element with bounds checking
-
- Returns a const reference to the element at with specified key @a key,
- with bounds checking.
-
- @param[in] key key of the element to access
-
- @return const reference to the element at key @a key
-
- @throw type_error.304 if the JSON value is not an object; in this case,
- calling `at` with a key makes no sense. See example below.
- @throw out_of_range.403 if the key @a key is is not stored in the object;
- that is, `find(key) == end()`. See example below.
-
- @exceptionsafety Strong guarantee: if an exception is thrown, there are no
- changes in the JSON value.
-
- @complexity Logarithmic in the size of the container.
-
- @sa see @ref operator[](const typename object_t::key_type&) for unchecked
- access by reference
- @sa see @ref value() for access by value with a default value
-
- @since version 1.0.0
-
- @liveexample{The example below shows how object elements can be read using
- `at()`. It also demonstrates the different exceptions that can be thrown.,
- at__object_t_key_type_const}
- */
+ /// @brief access specified object element with bounds checking
+ /// @sa https://json.nlohmann.me/api/basic_json/at/
const_reference at(const typename object_t::key_type& key) const
{
// at only works for objects
@@ -3653,31 +2015,8 @@
}
}
- /*!
- @brief access specified array element
-
- Returns a reference to the element at specified location @a idx.
-
- @note If @a idx is beyond the range of the array (i.e., `idx >= size()`),
- then the array is silently filled up with `null` values to make `idx` a
- valid reference to the last stored element.
-
- @param[in] idx index of the element to access
-
- @return reference to the element at index @a idx
-
- @throw type_error.305 if the JSON value is not an array or null; in that
- cases, using the [] operator with an index makes no sense.
-
- @complexity Constant if @a idx is in the range of the array. Otherwise
- linear in `idx - size()`.
-
- @liveexample{The example below shows how array elements can be read and
- written using `[]` operator. Note the addition of `null`
- values.,operatorarray__size_type}
-
- @since version 1.0.0
- */
+ /// @brief access specified array element
+ /// @sa https://json.nlohmann.me/api/basic_json/operator%5B%5D/
reference operator[](size_type idx)
{
// implicitly convert null value to an empty array
@@ -3722,25 +2061,8 @@
JSON_THROW(type_error::create(305, "cannot use operator[] with a numeric argument with " + std::string(type_name()), *this));
}
- /*!
- @brief access specified array element
-
- Returns a const reference to the element at specified location @a idx.
-
- @param[in] idx index of the element to access
-
- @return const reference to the element at index @a idx
-
- @throw type_error.305 if the JSON value is not an array; in that case,
- using the [] operator with an index makes no sense.
-
- @complexity Constant.
-
- @liveexample{The example below shows how array elements can be read using
- the `[]` operator.,operatorarray__size_type_const}
-
- @since version 1.0.0
- */
+ /// @brief access specified array element
+ /// @sa https://json.nlohmann.me/api/basic_json/operator%5B%5D/
const_reference operator[](size_type idx) const
{
// const operator[] only works for arrays
@@ -3752,33 +2074,8 @@
JSON_THROW(type_error::create(305, "cannot use operator[] with a numeric argument with " + std::string(type_name()), *this));
}
- /*!
- @brief access specified object element
-
- Returns a reference to the element at with specified key @a key.
-
- @note If @a key is not found in the object, then it is silently added to
- the object and filled with a `null` value to make `key` a valid reference.
- In case the value was `null` before, it is converted to an object.
-
- @param[in] key key of the element to access
-
- @return reference to the element at key @a key
-
- @throw type_error.305 if the JSON value is not an object or null; in that
- cases, using the [] operator with a key makes no sense.
-
- @complexity Logarithmic in the size of the container.
-
- @liveexample{The example below shows how object elements can be read and
- written using the `[]` operator.,operatorarray__key_type}
-
- @sa see @ref at(const typename object_t::key_type&) for access by reference
- with range checking
- @sa see @ref value() for access by value with a default value
-
- @since version 1.0.0
- */
+ /// @brief access specified object element
+ /// @sa https://json.nlohmann.me/api/basic_json/operator%5B%5D/
reference operator[](const typename object_t::key_type& key)
{
// implicitly convert null value to an empty object
@@ -3798,36 +2095,8 @@
JSON_THROW(type_error::create(305, "cannot use operator[] with a string argument with " + std::string(type_name()), *this));
}
- /*!
- @brief read-only access specified object element
-
- Returns a const reference to the element at with specified key @a key. No
- bounds checking is performed.
-
- @warning If the element with key @a key does not exist, the behavior is
- undefined.
-
- @param[in] key key of the element to access
-
- @return const reference to the element at key @a key
-
- @pre The element with key @a key must exist. **This precondition is
- enforced with an assertion.**
-
- @throw type_error.305 if the JSON value is not an object; in that case,
- using the [] operator with a key makes no sense.
-
- @complexity Logarithmic in the size of the container.
-
- @liveexample{The example below shows how object elements can be read using
- the `[]` operator.,operatorarray__key_type_const}
-
- @sa see @ref at(const typename object_t::key_type&) for access by reference
- with range checking
- @sa see @ref value() for access by value with a default value
-
- @since version 1.0.0
- */
+ /// @brief access specified object element
+ /// @sa https://json.nlohmann.me/api/basic_json/operator%5B%5D/
const_reference operator[](const typename object_t::key_type& key) const
{
// const operator[] only works for objects
@@ -3840,33 +2109,8 @@
JSON_THROW(type_error::create(305, "cannot use operator[] with a string argument with " + std::string(type_name()), *this));
}
- /*!
- @brief access specified object element
-
- Returns a reference to the element at with specified key @a key.
-
- @note If @a key is not found in the object, then it is silently added to
- the object and filled with a `null` value to make `key` a valid reference.
- In case the value was `null` before, it is converted to an object.
-
- @param[in] key key of the element to access
-
- @return reference to the element at key @a key
-
- @throw type_error.305 if the JSON value is not an object or null; in that
- cases, using the [] operator with a key makes no sense.
-
- @complexity Logarithmic in the size of the container.
-
- @liveexample{The example below shows how object elements can be read and
- written using the `[]` operator.,operatorarray__key_type}
-
- @sa see @ref at(const typename object_t::key_type&) for access by reference
- with range checking
- @sa see @ref value() for access by value with a default value
-
- @since version 1.1.0
- */
+ /// @brief access specified object element
+ /// @sa https://json.nlohmann.me/api/basic_json/operator%5B%5D/
template<typename T>
JSON_HEDLEY_NON_NULL(2)
reference operator[](T* key)
@@ -3888,36 +2132,8 @@
JSON_THROW(type_error::create(305, "cannot use operator[] with a string argument with " + std::string(type_name()), *this));
}
- /*!
- @brief read-only access specified object element
-
- Returns a const reference to the element at with specified key @a key. No
- bounds checking is performed.
-
- @warning If the element with key @a key does not exist, the behavior is
- undefined.
-
- @param[in] key key of the element to access
-
- @return const reference to the element at key @a key
-
- @pre The element with key @a key must exist. **This precondition is
- enforced with an assertion.**
-
- @throw type_error.305 if the JSON value is not an object; in that case,
- using the [] operator with a key makes no sense.
-
- @complexity Logarithmic in the size of the container.
-
- @liveexample{The example below shows how object elements can be read using
- the `[]` operator.,operatorarray__key_type_const}
-
- @sa see @ref at(const typename object_t::key_type&) for access by reference
- with range checking
- @sa see @ref value() for access by value with a default value
-
- @since version 1.1.0
- */
+ /// @brief access specified object element
+ /// @sa https://json.nlohmann.me/api/basic_json/operator%5B%5D/
template<typename T>
JSON_HEDLEY_NON_NULL(2)
const_reference operator[](T* key) const
@@ -3932,57 +2148,9 @@
JSON_THROW(type_error::create(305, "cannot use operator[] with a string argument with " + std::string(type_name()), *this));
}
- /*!
- @brief access specified object element with default value
-
- Returns either a copy of an object's element at the specified key @a key
- or a given default value if no element with key @a key exists.
-
- The function is basically equivalent to executing
- @code {.cpp}
- try {
- return at(key);
- } catch(out_of_range) {
- return default_value;
- }
- @endcode
-
- @note Unlike @ref at(const typename object_t::key_type&), this function
- does not throw if the given key @a key was not found.
-
- @note Unlike @ref operator[](const typename object_t::key_type& key), this
- function does not implicitly add an element to the position defined by @a
- key. This function is furthermore also applicable to const objects.
-
- @param[in] key key of the element to access
- @param[in] default_value the value to return if @a key is not found
-
- @tparam ValueType type compatible to JSON values, for instance `int` for
- JSON integer numbers, `bool` for JSON booleans, or `std::vector` types for
- JSON arrays. Note the type of the expected value at @a key and the default
- value @a default_value must be compatible.
-
- @return copy of the element at key @a key or @a default_value if @a key
- is not found
-
- @throw type_error.302 if @a default_value does not match the type of the
- value at @a key
- @throw type_error.306 if the JSON value is not an object; in that case,
- using `value()` with a key makes no sense.
-
- @complexity Logarithmic in the size of the container.
-
- @liveexample{The example below shows how object elements can be queried
- with a default value.,basic_json__value}
-
- @sa see @ref at(const typename object_t::key_type&) for access by reference
- with range checking
- @sa see @ref operator[](const typename object_t::key_type&) for unchecked
- access by reference
-
- @since version 1.0.0
- */
- // using std::is_convertible in a std::enable_if will fail when using explicit conversions
+ /// @brief access specified object element with default value
+ /// @sa https://json.nlohmann.me/api/basic_json/value/
+ /// using std::is_convertible in a std::enable_if will fail when using explicit conversions
template < class ValueType, typename std::enable_if <
detail::is_getable<basic_json_t, ValueType>::value
&& !std::is_same<value_t, ValueType>::value, int >::type = 0 >
@@ -4004,58 +2172,16 @@
JSON_THROW(type_error::create(306, "cannot use value() with " + std::string(type_name()), *this));
}
- /*!
- @brief overload for a default value of type const char*
- @copydoc basic_json::value(const typename object_t::key_type&, const ValueType&) const
- */
+ /// @brief access specified object element with default value
+ /// @sa https://json.nlohmann.me/api/basic_json/value/
+ /// overload for a default value of type const char*
string_t value(const typename object_t::key_type& key, const char* default_value) const
{
return value(key, string_t(default_value));
}
- /*!
- @brief access specified object element via JSON Pointer with default value
-
- Returns either a copy of an object's element at the specified key @a key
- or a given default value if no element with key @a key exists.
-
- The function is basically equivalent to executing
- @code {.cpp}
- try {
- return at(ptr);
- } catch(out_of_range) {
- return default_value;
- }
- @endcode
-
- @note Unlike @ref at(const json_pointer&), this function does not throw
- if the given key @a key was not found.
-
- @param[in] ptr a JSON pointer to the element to access
- @param[in] default_value the value to return if @a ptr found no value
-
- @tparam ValueType type compatible to JSON values, for instance `int` for
- JSON integer numbers, `bool` for JSON booleans, or `std::vector` types for
- JSON arrays. Note the type of the expected value at @a key and the default
- value @a default_value must be compatible.
-
- @return copy of the element at key @a key or @a default_value if @a key
- is not found
-
- @throw type_error.302 if @a default_value does not match the type of the
- value at @a ptr
- @throw type_error.306 if the JSON value is not an object; in that case,
- using `value()` with a key makes no sense.
-
- @complexity Logarithmic in the size of the container.
-
- @liveexample{The example below shows how object elements can be queried
- with a default value.,basic_json__value_ptr}
-
- @sa see @ref operator[](const json_pointer&) for unchecked access by reference
-
- @since version 2.0.2
- */
+ /// @brief access specified object element via JSON Pointer with default value
+ /// @sa https://json.nlohmann.me/api/basic_json/value/
template<class ValueType, typename std::enable_if<
detail::is_getable<basic_json_t, ValueType>::value, int>::type = 0>
ValueType value(const json_pointer& ptr, const ValueType& default_value) const
@@ -4077,85 +2203,31 @@
JSON_THROW(type_error::create(306, "cannot use value() with " + std::string(type_name()), *this));
}
- /*!
- @brief overload for a default value of type const char*
- @copydoc basic_json::value(const json_pointer&, ValueType) const
- */
+ /// @brief access specified object element via JSON Pointer with default value
+ /// @sa https://json.nlohmann.me/api/basic_json/value/
+ /// overload for a default value of type const char*
JSON_HEDLEY_NON_NULL(3)
string_t value(const json_pointer& ptr, const char* default_value) const
{
return value(ptr, string_t(default_value));
}
- /*!
- @brief access the first element
-
- Returns a reference to the first element in the container. For a JSON
- container `c`, the expression `c.front()` is equivalent to `*c.begin()`.
-
- @return In case of a structured type (array or object), a reference to the
- first element is returned. In case of number, string, boolean, or binary
- values, a reference to the value is returned.
-
- @complexity Constant.
-
- @pre The JSON value must not be `null` (would throw `std::out_of_range`)
- or an empty array or object (undefined behavior, **guarded by
- assertions**).
- @post The JSON value remains unchanged.
-
- @throw invalid_iterator.214 when called on `null` value
-
- @liveexample{The following code shows an example for `front()`.,front}
-
- @sa see @ref back() -- access the last element
-
- @since version 1.0.0
- */
+ /// @brief access the first element
+ /// @sa https://json.nlohmann.me/api/basic_json/front/
reference front()
{
return *begin();
}
- /*!
- @copydoc basic_json::front()
- */
+ /// @brief access the first element
+ /// @sa https://json.nlohmann.me/api/basic_json/front/
const_reference front() const
{
return *cbegin();
}
- /*!
- @brief access the last element
-
- Returns a reference to the last element in the container. For a JSON
- container `c`, the expression `c.back()` is equivalent to
- @code {.cpp}
- auto tmp = c.end();
- --tmp;
- return *tmp;
- @endcode
-
- @return In case of a structured type (array or object), a reference to the
- last element is returned. In case of number, string, boolean, or binary
- values, a reference to the value is returned.
-
- @complexity Constant.
-
- @pre The JSON value must not be `null` (would throw `std::out_of_range`)
- or an empty array or object (undefined behavior, **guarded by
- assertions**).
- @post The JSON value remains unchanged.
-
- @throw invalid_iterator.214 when called on a `null` value. See example
- below.
-
- @liveexample{The following code shows an example for `back()`.,back}
-
- @sa see @ref front() -- access the first element
-
- @since version 1.0.0
- */
+ /// @brief access the last element
+ /// @sa https://json.nlohmann.me/api/basic_json/back/
reference back()
{
auto tmp = end();
@@ -4163,9 +2235,8 @@
return *tmp;
}
- /*!
- @copydoc basic_json::back()
- */
+ /// @brief access the last element
+ /// @sa https://json.nlohmann.me/api/basic_json/back/
const_reference back() const
{
auto tmp = cend();
@@ -4173,52 +2244,8 @@
return *tmp;
}
- /*!
- @brief remove element given an iterator
-
- Removes the element specified by iterator @a pos. The iterator @a pos must
- be valid and dereferenceable. Thus the `end()` iterator (which is valid,
- but is not dereferenceable) cannot be used as a value for @a pos.
-
- If called on a primitive type other than `null`, the resulting JSON value
- will be `null`.
-
- @param[in] pos iterator to the element to remove
- @return Iterator following the last removed element. If the iterator @a
- pos refers to the last element, the `end()` iterator is returned.
-
- @tparam IteratorType an @ref iterator or @ref const_iterator
-
- @post Invalidates iterators and references at or after the point of the
- erase, including the `end()` iterator.
-
- @throw type_error.307 if called on a `null` value; example: `"cannot use
- erase() with null"`
- @throw invalid_iterator.202 if called on an iterator which does not belong
- to the current JSON value; example: `"iterator does not fit current
- value"`
- @throw invalid_iterator.205 if called on a primitive type with invalid
- iterator (i.e., any iterator which is not `begin()`); example: `"iterator
- out of range"`
-
- @complexity The complexity depends on the type:
- - objects: amortized constant
- - arrays: linear in distance between @a pos and the end of the container
- - strings and binary: linear in the length of the member
- - other types: constant
-
- @liveexample{The example shows the result of `erase()` for different JSON
- types.,erase__IteratorType}
-
- @sa see @ref erase(IteratorType, IteratorType) -- removes the elements in
- the given range
- @sa see @ref erase(const typename object_t::key_type&) -- removes the element
- from an object at the given key
- @sa see @ref erase(const size_type) -- removes the element from an array at
- the given index
-
- @since version 1.0.0
- */
+ /// @brief remove element given an iterator
+ /// @sa https://json.nlohmann.me/api/basic_json/erase/
template < class IteratorType, typename std::enable_if <
std::is_same<IteratorType, typename basic_json_t::iterator>::value ||
std::is_same<IteratorType, typename basic_json_t::const_iterator>::value, int >::type
@@ -4288,52 +2315,8 @@
return result;
}
- /*!
- @brief remove elements given an iterator range
-
- Removes the element specified by the range `[first; last)`. The iterator
- @a first does not need to be dereferenceable if `first == last`: erasing
- an empty range is a no-op.
-
- If called on a primitive type other than `null`, the resulting JSON value
- will be `null`.
-
- @param[in] first iterator to the beginning of the range to remove
- @param[in] last iterator past the end of the range to remove
- @return Iterator following the last removed element. If the iterator @a
- second refers to the last element, the `end()` iterator is returned.
-
- @tparam IteratorType an @ref iterator or @ref const_iterator
-
- @post Invalidates iterators and references at or after the point of the
- erase, including the `end()` iterator.
-
- @throw type_error.307 if called on a `null` value; example: `"cannot use
- erase() with null"`
- @throw invalid_iterator.203 if called on iterators which does not belong
- to the current JSON value; example: `"iterators do not fit current value"`
- @throw invalid_iterator.204 if called on a primitive type with invalid
- iterators (i.e., if `first != begin()` and `last != end()`); example:
- `"iterators out of range"`
-
- @complexity The complexity depends on the type:
- - objects: `log(size()) + std::distance(first, last)`
- - arrays: linear in the distance between @a first and @a last, plus linear
- in the distance between @a last and end of the container
- - strings and binary: linear in the length of the member
- - other types: constant
-
- @liveexample{The example shows the result of `erase()` for different JSON
- types.,erase__IteratorType_IteratorType}
-
- @sa see @ref erase(IteratorType) -- removes the element at a given position
- @sa see @ref erase(const typename object_t::key_type&) -- removes the element
- from an object at the given key
- @sa see @ref erase(const size_type) -- removes the element from an array at
- the given index
-
- @since version 1.0.0
- */
+ /// @brief remove elements given an iterator range
+ /// @sa https://json.nlohmann.me/api/basic_json/erase/
template < class IteratorType, typename std::enable_if <
std::is_same<IteratorType, typename basic_json_t::iterator>::value ||
std::is_same<IteratorType, typename basic_json_t::const_iterator>::value, int >::type
@@ -4406,35 +2389,8 @@
return result;
}
- /*!
- @brief remove element from a JSON object given a key
-
- Removes elements from a JSON object with the key value @a key.
-
- @param[in] key value of the elements to remove
-
- @return Number of elements removed. If @a ObjectType is the default
- `std::map` type, the return value will always be `0` (@a key was not
- found) or `1` (@a key was found).
-
- @post References and iterators to the erased elements are invalidated.
- Other references and iterators are not affected.
-
- @throw type_error.307 when called on a type other than JSON object;
- example: `"cannot use erase() with null"`
-
- @complexity `log(size()) + count(key)`
-
- @liveexample{The example shows the effect of `erase()`.,erase__key_type}
-
- @sa see @ref erase(IteratorType) -- removes the element at a given position
- @sa see @ref erase(IteratorType, IteratorType) -- removes the elements in
- the given range
- @sa see @ref erase(const size_type) -- removes the element from an array at
- the given index
-
- @since version 1.0.0
- */
+ /// @brief remove element from a JSON object given a key
+ /// @sa https://json.nlohmann.me/api/basic_json/erase/
size_type erase(const typename object_t::key_type& key)
{
// this erase only works for objects
@@ -4446,30 +2402,8 @@
JSON_THROW(type_error::create(307, "cannot use erase() with " + std::string(type_name()), *this));
}
- /*!
- @brief remove element from a JSON array given an index
-
- Removes element from a JSON array at the index @a idx.
-
- @param[in] idx index of the element to remove
-
- @throw type_error.307 when called on a type other than JSON object;
- example: `"cannot use erase() with null"`
- @throw out_of_range.401 when `idx >= size()`; example: `"array index 17
- is out of range"`
-
- @complexity Linear in distance between @a idx and the end of the container.
-
- @liveexample{The example shows the effect of `erase()`.,erase__size_type}
-
- @sa see @ref erase(IteratorType) -- removes the element at a given position
- @sa see @ref erase(IteratorType, IteratorType) -- removes the elements in
- the given range
- @sa see @ref erase(const typename object_t::key_type&) -- removes the element
- from an object at the given key
-
- @since version 1.0.0
- */
+ /// @brief remove element from a JSON array given an index
+ /// @sa https://json.nlohmann.me/api/basic_json/erase/
void erase(const size_type idx)
{
// this erase only works for arrays
@@ -4498,30 +2432,8 @@
/// @name lookup
/// @{
- /*!
- @brief find an element in a JSON object
-
- Finds an element in a JSON object with key equivalent to @a key. If the
- element is not found or the JSON value is not an object, end() is
- returned.
-
- @note This method always returns @ref end() when executed on a JSON type
- that is not an object.
-
- @param[in] key key value of the element to search for.
-
- @return Iterator to an element with key equivalent to @a key. If no such
- element is found or the JSON value is not an object, past-the-end (see
- @ref end()) iterator is returned.
-
- @complexity Logarithmic in the size of the JSON object.
-
- @liveexample{The example shows how `find()` is used.,find__key_type}
-
- @sa see @ref contains(KeyT&&) const -- checks whether a key exists
-
- @since version 1.0.0
- */
+ /// @brief find an element in a JSON object
+ /// @sa https://json.nlohmann.me/api/basic_json/find/
template<typename KeyT>
iterator find(KeyT&& key)
{
@@ -4535,10 +2447,8 @@
return result;
}
- /*!
- @brief find an element in a JSON object
- @copydoc find(KeyT&&)
- */
+ /// @brief find an element in a JSON object
+ /// @sa https://json.nlohmann.me/api/basic_json/find/
template<typename KeyT>
const_iterator find(KeyT&& key) const
{
@@ -4552,27 +2462,8 @@
return result;
}
- /*!
- @brief returns the number of occurrences of a key in a JSON object
-
- Returns the number of elements with key @a key. If ObjectType is the
- default `std::map` type, the return value will always be `0` (@a key was
- not found) or `1` (@a key was found).
-
- @note This method always returns `0` when executed on a JSON type that is
- not an object.
-
- @param[in] key key value of the element to count
-
- @return Number of elements with key @a key. If the JSON value is not an
- object, the return value will be `0`.
-
- @complexity Logarithmic in the size of the JSON object.
-
- @liveexample{The example shows how `count()` is used.,count}
-
- @since version 1.0.0
- */
+ /// @brief returns the number of occurrences of a key in a JSON object
+ /// @sa https://json.nlohmann.me/api/basic_json/count/
template<typename KeyT>
size_type count(KeyT&& key) const
{
@@ -4580,31 +2471,8 @@
return is_object() ? m_value.object->count(std::forward<KeyT>(key)) : 0;
}
- /*!
- @brief check the existence of an element in a JSON object
-
- Check whether an element exists in a JSON object with key equivalent to
- @a key. If the element is not found or the JSON value is not an object,
- false is returned.
-
- @note This method always returns false when executed on a JSON type
- that is not an object.
-
- @param[in] key key value to check its existence.
-
- @return true if an element with specified @a key exists. If no such
- element with such key is found or the JSON value is not an object,
- false is returned.
-
- @complexity Logarithmic in the size of the JSON object.
-
- @liveexample{The following code shows an example for `contains()`.,contains}
-
- @sa see @ref find(KeyT&&) -- returns an iterator to an object element
- @sa see @ref contains(const json_pointer&) const -- checks the existence for a JSON pointer
-
- @since version 3.6.0
- */
+ /// @brief check the existence of an element in a JSON object
+ /// @sa https://json.nlohmann.me/api/basic_json/contains/
template < typename KeyT, typename std::enable_if <
!std::is_same<typename std::decay<KeyT>::type, json_pointer>::value, int >::type = 0 >
bool contains(KeyT && key) const
@@ -4612,32 +2480,8 @@
return is_object() && m_value.object->find(std::forward<KeyT>(key)) != m_value.object->end();
}
- /*!
- @brief check the existence of an element in a JSON object given a JSON pointer
-
- Check whether the given JSON pointer @a ptr can be resolved in the current
- JSON value.
-
- @note This method can be executed on any JSON value type.
-
- @param[in] ptr JSON pointer to check its existence.
-
- @return true if the JSON pointer can be resolved to a stored value, false
- otherwise.
-
- @post If `j.contains(ptr)` returns true, it is safe to call `j[ptr]`.
-
- @throw parse_error.106 if an array index begins with '0'
- @throw parse_error.109 if an array index was not a number
-
- @complexity Logarithmic in the size of the JSON object.
-
- @liveexample{The following code shows an example for `contains()`.,contains_json_pointer}
-
- @sa see @ref contains(KeyT &&) const -- checks the existence of a key
-
- @since version 3.7.0
- */
+ /// @brief check the existence of an element in a JSON object given a JSON pointer
+ /// @sa https://json.nlohmann.me/api/basic_json/contains/
bool contains(const json_pointer& ptr) const
{
return ptr.contains(this);
@@ -4653,30 +2497,8 @@
/// @name iterators
/// @{
- /*!
- @brief returns an iterator to the first element
-
- Returns an iterator to the first element.
-
- @image html range-begin-end.svg "Illustration from cppreference.com"
-
- @return iterator to the first element
-
- @complexity Constant.
-
- @requirement This function helps `basic_json` satisfying the
- [Container](https://en.cppreference.com/w/cpp/named_req/Container)
- requirements:
- - The complexity is constant.
-
- @liveexample{The following code shows an example for `begin()`.,begin}
-
- @sa see @ref cbegin() -- returns a const iterator to the beginning
- @sa see @ref end() -- returns an iterator to the end
- @sa see @ref cend() -- returns a const iterator to the end
-
- @since version 1.0.0
- */
+ /// @brief returns an iterator to the first element
+ /// @sa https://json.nlohmann.me/api/basic_json/begin/
iterator begin() noexcept
{
iterator result(this);
@@ -4684,39 +2506,15 @@
return result;
}
- /*!
- @copydoc basic_json::cbegin()
- */
+ /// @brief returns an iterator to the first element
+ /// @sa https://json.nlohmann.me/api/basic_json/begin/
const_iterator begin() const noexcept
{
return cbegin();
}
- /*!
- @brief returns a const iterator to the first element
-
- Returns a const iterator to the first element.
-
- @image html range-begin-end.svg "Illustration from cppreference.com"
-
- @return const iterator to the first element
-
- @complexity Constant.
-
- @requirement This function helps `basic_json` satisfying the
- [Container](https://en.cppreference.com/w/cpp/named_req/Container)
- requirements:
- - The complexity is constant.
- - Has the semantics of `const_cast<const basic_json&>(*this).begin()`.
-
- @liveexample{The following code shows an example for `cbegin()`.,cbegin}
-
- @sa see @ref begin() -- returns an iterator to the beginning
- @sa see @ref end() -- returns an iterator to the end
- @sa see @ref cend() -- returns a const iterator to the end
-
- @since version 1.0.0
- */
+ /// @brief returns a const iterator to the first element
+ /// @sa https://json.nlohmann.me/api/basic_json/cbegin/
const_iterator cbegin() const noexcept
{
const_iterator result(this);
@@ -4724,30 +2522,8 @@
return result;
}
- /*!
- @brief returns an iterator to one past the last element
-
- Returns an iterator to one past the last element.
-
- @image html range-begin-end.svg "Illustration from cppreference.com"
-
- @return iterator one past the last element
-
- @complexity Constant.
-
- @requirement This function helps `basic_json` satisfying the
- [Container](https://en.cppreference.com/w/cpp/named_req/Container)
- requirements:
- - The complexity is constant.
-
- @liveexample{The following code shows an example for `end()`.,end}
-
- @sa see @ref cend() -- returns a const iterator to the end
- @sa see @ref begin() -- returns an iterator to the beginning
- @sa see @ref cbegin() -- returns a const iterator to the beginning
-
- @since version 1.0.0
- */
+ /// @brief returns an iterator to one past the last element
+ /// @sa https://json.nlohmann.me/api/basic_json/end/
iterator end() noexcept
{
iterator result(this);
@@ -4755,39 +2531,15 @@
return result;
}
- /*!
- @copydoc basic_json::cend()
- */
+ /// @brief returns an iterator to one past the last element
+ /// @sa https://json.nlohmann.me/api/basic_json/end/
const_iterator end() const noexcept
{
return cend();
}
- /*!
- @brief returns a const iterator to one past the last element
-
- Returns a const iterator to one past the last element.
-
- @image html range-begin-end.svg "Illustration from cppreference.com"
-
- @return const iterator one past the last element
-
- @complexity Constant.
-
- @requirement This function helps `basic_json` satisfying the
- [Container](https://en.cppreference.com/w/cpp/named_req/Container)
- requirements:
- - The complexity is constant.
- - Has the semantics of `const_cast<const basic_json&>(*this).end()`.
-
- @liveexample{The following code shows an example for `cend()`.,cend}
-
- @sa see @ref end() -- returns an iterator to the end
- @sa see @ref begin() -- returns an iterator to the beginning
- @sa see @ref cbegin() -- returns a const iterator to the beginning
-
- @since version 1.0.0
- */
+ /// @brief returns an iterator to one past the last element
+ /// @sa https://json.nlohmann.me/api/basic_json/cend/
const_iterator cend() const noexcept
{
const_iterator result(this);
@@ -4795,286 +2547,80 @@
return result;
}
- /*!
- @brief returns an iterator to the reverse-beginning
-
- Returns an iterator to the reverse-beginning; that is, the last element.
-
- @image html range-rbegin-rend.svg "Illustration from cppreference.com"
-
- @complexity Constant.
-
- @requirement This function helps `basic_json` satisfying the
- [ReversibleContainer](https://en.cppreference.com/w/cpp/named_req/ReversibleContainer)
- requirements:
- - The complexity is constant.
- - Has the semantics of `reverse_iterator(end())`.
-
- @liveexample{The following code shows an example for `rbegin()`.,rbegin}
-
- @sa see @ref crbegin() -- returns a const reverse iterator to the beginning
- @sa see @ref rend() -- returns a reverse iterator to the end
- @sa see @ref crend() -- returns a const reverse iterator to the end
-
- @since version 1.0.0
- */
+ /// @brief returns an iterator to the reverse-beginning
+ /// @sa https://json.nlohmann.me/api/basic_json/rbegin/
reverse_iterator rbegin() noexcept
{
return reverse_iterator(end());
}
- /*!
- @copydoc basic_json::crbegin()
- */
+ /// @brief returns an iterator to the reverse-beginning
+ /// @sa https://json.nlohmann.me/api/basic_json/rbegin/
const_reverse_iterator rbegin() const noexcept
{
return crbegin();
}
- /*!
- @brief returns an iterator to the reverse-end
-
- Returns an iterator to the reverse-end; that is, one before the first
- element.
-
- @image html range-rbegin-rend.svg "Illustration from cppreference.com"
-
- @complexity Constant.
-
- @requirement This function helps `basic_json` satisfying the
- [ReversibleContainer](https://en.cppreference.com/w/cpp/named_req/ReversibleContainer)
- requirements:
- - The complexity is constant.
- - Has the semantics of `reverse_iterator(begin())`.
-
- @liveexample{The following code shows an example for `rend()`.,rend}
-
- @sa see @ref crend() -- returns a const reverse iterator to the end
- @sa see @ref rbegin() -- returns a reverse iterator to the beginning
- @sa see @ref crbegin() -- returns a const reverse iterator to the beginning
-
- @since version 1.0.0
- */
+ /// @brief returns an iterator to the reverse-end
+ /// @sa https://json.nlohmann.me/api/basic_json/rend/
reverse_iterator rend() noexcept
{
return reverse_iterator(begin());
}
- /*!
- @copydoc basic_json::crend()
- */
+ /// @brief returns an iterator to the reverse-end
+ /// @sa https://json.nlohmann.me/api/basic_json/rend/
const_reverse_iterator rend() const noexcept
{
return crend();
}
- /*!
- @brief returns a const reverse iterator to the last element
-
- Returns a const iterator to the reverse-beginning; that is, the last
- element.
-
- @image html range-rbegin-rend.svg "Illustration from cppreference.com"
-
- @complexity Constant.
-
- @requirement This function helps `basic_json` satisfying the
- [ReversibleContainer](https://en.cppreference.com/w/cpp/named_req/ReversibleContainer)
- requirements:
- - The complexity is constant.
- - Has the semantics of `const_cast<const basic_json&>(*this).rbegin()`.
-
- @liveexample{The following code shows an example for `crbegin()`.,crbegin}
-
- @sa see @ref rbegin() -- returns a reverse iterator to the beginning
- @sa see @ref rend() -- returns a reverse iterator to the end
- @sa see @ref crend() -- returns a const reverse iterator to the end
-
- @since version 1.0.0
- */
+ /// @brief returns a const reverse iterator to the last element
+ /// @sa https://json.nlohmann.me/api/basic_json/crbegin/
const_reverse_iterator crbegin() const noexcept
{
return const_reverse_iterator(cend());
}
- /*!
- @brief returns a const reverse iterator to one before the first
-
- Returns a const reverse iterator to the reverse-end; that is, one before
- the first element.
-
- @image html range-rbegin-rend.svg "Illustration from cppreference.com"
-
- @complexity Constant.
-
- @requirement This function helps `basic_json` satisfying the
- [ReversibleContainer](https://en.cppreference.com/w/cpp/named_req/ReversibleContainer)
- requirements:
- - The complexity is constant.
- - Has the semantics of `const_cast<const basic_json&>(*this).rend()`.
-
- @liveexample{The following code shows an example for `crend()`.,crend}
-
- @sa see @ref rend() -- returns a reverse iterator to the end
- @sa see @ref rbegin() -- returns a reverse iterator to the beginning
- @sa see @ref crbegin() -- returns a const reverse iterator to the beginning
-
- @since version 1.0.0
- */
+ /// @brief returns a const reverse iterator to one before the first
+ /// @sa https://json.nlohmann.me/api/basic_json/crend/
const_reverse_iterator crend() const noexcept
{
return const_reverse_iterator(cbegin());
}
public:
- /*!
- @brief wrapper to access iterator member functions in range-based for
-
- This function allows to access @ref iterator::key() and @ref
- iterator::value() during range-based for loops. In these loops, a
- reference to the JSON values is returned, so there is no access to the
- underlying iterator.
-
- For loop without iterator_wrapper:
-
- @code{cpp}
- for (auto it = j_object.begin(); it != j_object.end(); ++it)
- {
- std::cout << "key: " << it.key() << ", value:" << it.value() << '\n';
- }
- @endcode
-
- Range-based for loop without iterator proxy:
-
- @code{cpp}
- for (auto it : j_object)
- {
- // "it" is of type json::reference and has no key() member
- std::cout << "value: " << it << '\n';
- }
- @endcode
-
- Range-based for loop with iterator proxy:
-
- @code{cpp}
- for (auto it : json::iterator_wrapper(j_object))
- {
- std::cout << "key: " << it.key() << ", value:" << it.value() << '\n';
- }
- @endcode
-
- @note When iterating over an array, `key()` will return the index of the
- element as string (see example).
-
- @param[in] ref reference to a JSON value
- @return iteration proxy object wrapping @a ref with an interface to use in
- range-based for loops
-
- @liveexample{The following code shows how the wrapper is used,iterator_wrapper}
-
- @exceptionsafety Strong guarantee: if an exception is thrown, there are no
- changes in the JSON value.
-
- @complexity Constant.
-
- @note The name of this function is not yet final and may change in the
- future.
-
- @deprecated This stream operator is deprecated and will be removed in
- future 4.0.0 of the library. Please use @ref items() instead;
- that is, replace `json::iterator_wrapper(j)` with `j.items()`.
- */
+ /// @brief wrapper to access iterator member functions in range-based for
+ /// @sa https://json.nlohmann.me/api/basic_json/items/
+ /// @deprecated This function is deprecated since 3.1.0 and will be removed in
+ /// version 4.0.0 of the library. Please use @ref items() instead;
+ /// that is, replace `json::iterator_wrapper(j)` with `j.items()`.
JSON_HEDLEY_DEPRECATED_FOR(3.1.0, items())
static iteration_proxy<iterator> iterator_wrapper(reference ref) noexcept
{
return ref.items();
}
- /*!
- @copydoc iterator_wrapper(reference)
- */
+ /// @brief wrapper to access iterator member functions in range-based for
+ /// @sa https://json.nlohmann.me/api/basic_json/items/
+ /// @deprecated This function is deprecated since 3.1.0 and will be removed in
+ /// version 4.0.0 of the library. Please use @ref items() instead;
+ /// that is, replace `json::iterator_wrapper(j)` with `j.items()`.
JSON_HEDLEY_DEPRECATED_FOR(3.1.0, items())
static iteration_proxy<const_iterator> iterator_wrapper(const_reference ref) noexcept
{
return ref.items();
}
- /*!
- @brief helper to access iterator member functions in range-based for
-
- This function allows to access @ref iterator::key() and @ref
- iterator::value() during range-based for loops. In these loops, a
- reference to the JSON values is returned, so there is no access to the
- underlying iterator.
-
- For loop without `items()` function:
-
- @code{cpp}
- for (auto it = j_object.begin(); it != j_object.end(); ++it)
- {
- std::cout << "key: " << it.key() << ", value:" << it.value() << '\n';
- }
- @endcode
-
- Range-based for loop without `items()` function:
-
- @code{cpp}
- for (auto it : j_object)
- {
- // "it" is of type json::reference and has no key() member
- std::cout << "value: " << it << '\n';
- }
- @endcode
-
- Range-based for loop with `items()` function:
-
- @code{cpp}
- for (auto& el : j_object.items())
- {
- std::cout << "key: " << el.key() << ", value:" << el.value() << '\n';
- }
- @endcode
-
- The `items()` function also allows to use
- [structured bindings](https://en.cppreference.com/w/cpp/language/structured_binding)
- (C++17):
-
- @code{cpp}
- for (auto& [key, val] : j_object.items())
- {
- std::cout << "key: " << key << ", value:" << val << '\n';
- }
- @endcode
-
- @note When iterating over an array, `key()` will return the index of the
- element as string (see example). For primitive types (e.g., numbers),
- `key()` returns an empty string.
-
- @warning Using `items()` on temporary objects is dangerous. Make sure the
- object's lifetime exeeds the iteration. See
- <https://github.com/nlohmann/json/issues/2040> for more
- information.
-
- @return iteration proxy object wrapping @a ref with an interface to use in
- range-based for loops
-
- @liveexample{The following code shows how the function is used.,items}
-
- @exceptionsafety Strong guarantee: if an exception is thrown, there are no
- changes in the JSON value.
-
- @complexity Constant.
-
- @since version 3.1.0, structured bindings support since 3.5.0.
- */
+ /// @brief helper to access iterator member functions in range-based for
+ /// @sa https://json.nlohmann.me/api/basic_json/items/
iteration_proxy<iterator> items() noexcept
{
return iteration_proxy<iterator>(*this);
}
- /*!
- @copydoc items()
- */
+ /// @brief helper to access iterator member functions in range-based for
+ /// @sa https://json.nlohmann.me/api/basic_json/items/
iteration_proxy<const_iterator> items() const noexcept
{
return iteration_proxy<const_iterator>(*this);
@@ -5090,48 +2636,8 @@
/// @name capacity
/// @{
- /*!
- @brief checks whether the container is empty.
-
- Checks if a JSON value has no elements (i.e. whether its @ref size is `0`).
-
- @return The return value depends on the different types and is
- defined as follows:
- Value type | return value
- ----------- | -------------
- null | `true`
- boolean | `false`
- string | `false`
- number | `false`
- binary | `false`
- object | result of function `object_t::empty()`
- array | result of function `array_t::empty()`
-
- @liveexample{The following code uses `empty()` to check if a JSON
- object contains any elements.,empty}
-
- @complexity Constant, as long as @ref array_t and @ref object_t satisfy
- the Container concept; that is, their `empty()` functions have constant
- complexity.
-
- @iterators No changes.
-
- @exceptionsafety No-throw guarantee: this function never throws exceptions.
-
- @note This function does not return whether a string stored as JSON value
- is empty - it returns whether the JSON container itself is empty which is
- false in the case of a string.
-
- @requirement This function helps `basic_json` satisfying the
- [Container](https://en.cppreference.com/w/cpp/named_req/Container)
- requirements:
- - The complexity is constant.
- - Has the semantics of `begin() == end()`.
-
- @sa see @ref size() -- returns the number of elements
-
- @since version 1.0.0
- */
+ /// @brief checks whether the container is empty.
+ /// @sa https://json.nlohmann.me/api/basic_json/empty/
bool empty() const noexcept
{
switch (m_type)
@@ -5169,49 +2675,8 @@
}
}
- /*!
- @brief returns the number of elements
-
- Returns the number of elements in a JSON value.
-
- @return The return value depends on the different types and is
- defined as follows:
- Value type | return value
- ----------- | -------------
- null | `0`
- boolean | `1`
- string | `1`
- number | `1`
- binary | `1`
- object | result of function object_t::size()
- array | result of function array_t::size()
-
- @liveexample{The following code calls `size()` on the different value
- types.,size}
-
- @complexity Constant, as long as @ref array_t and @ref object_t satisfy
- the Container concept; that is, their size() functions have constant
- complexity.
-
- @iterators No changes.
-
- @exceptionsafety No-throw guarantee: this function never throws exceptions.
-
- @note This function does not return the length of a string stored as JSON
- value - it returns the number of elements in the JSON value which is 1 in
- the case of a string.
-
- @requirement This function helps `basic_json` satisfying the
- [Container](https://en.cppreference.com/w/cpp/named_req/Container)
- requirements:
- - The complexity is constant.
- - Has the semantics of `std::distance(begin(), end())`.
-
- @sa see @ref empty() -- checks whether the container is empty
- @sa see @ref max_size() -- returns the maximal number of elements
-
- @since version 1.0.0
- */
+ /// @brief returns the number of elements
+ /// @sa https://json.nlohmann.me/api/basic_json/size/
size_type size() const noexcept
{
switch (m_type)
@@ -5249,47 +2714,8 @@
}
}
- /*!
- @brief returns the maximum possible number of elements
-
- Returns the maximum number of elements a JSON value is able to hold due to
- system or library implementation limitations, i.e. `std::distance(begin(),
- end())` for the JSON value.
-
- @return The return value depends on the different types and is
- defined as follows:
- Value type | return value
- ----------- | -------------
- null | `0` (same as `size()`)
- boolean | `1` (same as `size()`)
- string | `1` (same as `size()`)
- number | `1` (same as `size()`)
- binary | `1` (same as `size()`)
- object | result of function `object_t::max_size()`
- array | result of function `array_t::max_size()`
-
- @liveexample{The following code calls `max_size()` on the different value
- types. Note the output is implementation specific.,max_size}
-
- @complexity Constant, as long as @ref array_t and @ref object_t satisfy
- the Container concept; that is, their `max_size()` functions have constant
- complexity.
-
- @iterators No changes.
-
- @exceptionsafety No-throw guarantee: this function never throws exceptions.
-
- @requirement This function helps `basic_json` satisfying the
- [Container](https://en.cppreference.com/w/cpp/named_req/Container)
- requirements:
- - The complexity is constant.
- - Has the semantics of returning `b.size()` where `b` is the largest
- possible JSON value.
-
- @sa see @ref size() -- returns the number of elements
-
- @since version 1.0.0
- */
+ /// @brief returns the maximum possible number of elements
+ /// @sa https://json.nlohmann.me/api/basic_json/max_size/
size_type max_size() const noexcept
{
switch (m_type)
@@ -5332,43 +2758,8 @@
/// @name modifiers
/// @{
- /*!
- @brief clears the contents
-
- Clears the content of a JSON value and resets it to the default value as
- if @ref basic_json(value_t) would have been called with the current value
- type from @ref type():
-
- Value type | initial value
- ----------- | -------------
- null | `null`
- boolean | `false`
- string | `""`
- number | `0`
- binary | An empty byte vector
- object | `{}`
- array | `[]`
-
- @post Has the same effect as calling
- @code {.cpp}
- *this = basic_json(type());
- @endcode
-
- @liveexample{The example below shows the effect of `clear()` to different
- JSON types.,clear}
-
- @complexity Linear in the size of the JSON value.
-
- @iterators All iterators, pointers and references related to this container
- are invalidated.
-
- @exceptionsafety No-throw guarantee: this function never throws exceptions.
-
- @sa see @ref basic_json(value_t) -- constructor that creates an object with the
- same value than calling `clear()`
-
- @since version 1.0.0
- */
+ /// @brief clears the contents
+ /// @sa https://json.nlohmann.me/api/basic_json/clear/
void clear() noexcept
{
switch (m_type)
@@ -5428,26 +2819,8 @@
}
}
- /*!
- @brief add an object to an array
-
- Appends the given element @a val to the end of the JSON value. If the
- function is called on a JSON null value, an empty array is created before
- appending @a val.
-
- @param[in] val the value to add to the JSON array
-
- @throw type_error.308 when called on a type other than JSON array or
- null; example: `"cannot use push_back() with number"`
-
- @complexity Amortized constant.
-
- @liveexample{The example shows how `push_back()` and `+=` can be used to
- add elements to a JSON array. Note how the `null` value was silently
- converted to a JSON array.,push_back}
-
- @since version 1.0.0
- */
+ /// @brief add an object to an array
+ /// @sa https://json.nlohmann.me/api/basic_json/push_back/
void push_back(basic_json&& val)
{
// push_back only works for null objects or arrays
@@ -5468,23 +2841,19 @@
const auto old_capacity = m_value.array->capacity();
m_value.array->push_back(std::move(val));
set_parent(m_value.array->back(), old_capacity);
- // if val is moved from, basic_json move constructor marks it null so we do not call the destructor
+ // if val is moved from, basic_json move constructor marks it null, so we do not call the destructor
}
- /*!
- @brief add an object to an array
- @copydoc push_back(basic_json&&)
- */
+ /// @brief add an object to an array
+ /// @sa https://json.nlohmann.me/api/basic_json/operator+=/
reference operator+=(basic_json&& val)
{
push_back(std::move(val));
return *this;
}
- /*!
- @brief add an object to an array
- @copydoc push_back(basic_json&&)
- */
+ /// @brief add an object to an array
+ /// @sa https://json.nlohmann.me/api/basic_json/push_back/
void push_back(const basic_json& val)
{
// push_back only works for null objects or arrays
@@ -5507,36 +2876,16 @@
set_parent(m_value.array->back(), old_capacity);
}
- /*!
- @brief add an object to an array
- @copydoc push_back(basic_json&&)
- */
+ /// @brief add an object to an array
+ /// @sa https://json.nlohmann.me/api/basic_json/operator+=/
reference operator+=(const basic_json& val)
{
push_back(val);
return *this;
}
- /*!
- @brief add an object to an object
-
- Inserts the given element @a val to the JSON object. If the function is
- called on a JSON null value, an empty object is created before inserting
- @a val.
-
- @param[in] val the value to add to the JSON object
-
- @throw type_error.308 when called on a type other than JSON object or
- null; example: `"cannot use push_back() with number"`
-
- @complexity Logarithmic in the size of the container, O(log(`size()`)).
-
- @liveexample{The example shows how `push_back()` and `+=` can be used to
- add elements to a JSON object. Note how the `null` value was silently
- converted to a JSON object.,push_back__object_t__value}
-
- @since version 1.0.0
- */
+ /// @brief add an object to an object
+ /// @sa https://json.nlohmann.me/api/basic_json/push_back/
void push_back(const typename object_t::value_type& val)
{
// push_back only works for null objects or objects
@@ -5558,41 +2907,16 @@
set_parent(res.first->second);
}
- /*!
- @brief add an object to an object
- @copydoc push_back(const typename object_t::value_type&)
- */
+ /// @brief add an object to an object
+ /// @sa https://json.nlohmann.me/api/basic_json/operator+=/
reference operator+=(const typename object_t::value_type& val)
{
push_back(val);
return *this;
}
- /*!
- @brief add an object to an object
-
- This function allows to use `push_back` with an initializer list. In case
-
- 1. the current value is an object,
- 2. the initializer list @a init contains only two elements, and
- 3. the first element of @a init is a string,
-
- @a init is converted into an object element and added using
- @ref push_back(const typename object_t::value_type&). Otherwise, @a init
- is converted to a JSON value and added using @ref push_back(basic_json&&).
-
- @param[in] init an initializer list
-
- @complexity Linear in the size of the initializer list @a init.
-
- @note This function is required to resolve an ambiguous overload error,
- because pairs like `{"key", "value"}` can be both interpreted as
- `object_t::value_type` or `std::initializer_list<basic_json>`, see
- https://github.com/nlohmann/json/issues/235 for more information.
-
- @liveexample{The example shows how initializer lists are treated as
- objects when possible.,push_back__initializer_list}
- */
+ /// @brief add an object to an object
+ /// @sa https://json.nlohmann.me/api/basic_json/push_back/
void push_back(initializer_list_t init)
{
if (is_object() && init.size() == 2 && (*init.begin())->is_string())
@@ -5607,39 +2931,16 @@
}
}
- /*!
- @brief add an object to an object
- @copydoc push_back(initializer_list_t)
- */
+ /// @brief add an object to an object
+ /// @sa https://json.nlohmann.me/api/basic_json/operator+=/
reference operator+=(initializer_list_t init)
{
push_back(init);
return *this;
}
- /*!
- @brief add an object to an array
-
- Creates a JSON value from the passed parameters @a args to the end of the
- JSON value. If the function is called on a JSON null value, an empty array
- is created before appending the value created from @a args.
-
- @param[in] args arguments to forward to a constructor of @ref basic_json
- @tparam Args compatible types to create a @ref basic_json object
-
- @return reference to the inserted element
-
- @throw type_error.311 when called on a type other than JSON array or
- null; example: `"cannot use emplace_back() with number"`
-
- @complexity Amortized constant.
-
- @liveexample{The example shows how `push_back()` can be used to add
- elements to a JSON array. Note how the `null` value was silently converted
- to a JSON array.,emplace_back}
-
- @since version 2.0.8, returns reference since 3.7.0
- */
+ /// @brief add an object to an array
+ /// @sa https://json.nlohmann.me/api/basic_json/emplace_back/
template<class... Args>
reference emplace_back(Args&& ... args)
{
@@ -5663,33 +2964,8 @@
return set_parent(m_value.array->back(), old_capacity);
}
- /*!
- @brief add an object to an object if key does not exist
-
- Inserts a new element into a JSON object constructed in-place with the
- given @a args if there is no element with the key in the container. If the
- function is called on a JSON null value, an empty object is created before
- appending the value created from @a args.
-
- @param[in] args arguments to forward to a constructor of @ref basic_json
- @tparam Args compatible types to create a @ref basic_json object
-
- @return a pair consisting of an iterator to the inserted element, or the
- already-existing element if no insertion happened, and a bool
- denoting whether the insertion took place.
-
- @throw type_error.311 when called on a type other than JSON object or
- null; example: `"cannot use emplace() with number"`
-
- @complexity Logarithmic in the size of the container, O(log(`size()`)).
-
- @liveexample{The example shows how `emplace()` can be used to add elements
- to a JSON object. Note how the `null` value was silently converted to a
- JSON object. Further note how no value is added if there was already one
- value stored with the same key.,emplace}
-
- @since version 2.0.8
- */
+ /// @brief add an object to an object if key does not exist
+ /// @sa https://json.nlohmann.me/api/basic_json/emplace/
template<class... Args>
std::pair<iterator, bool> emplace(Args&& ... args)
{
@@ -5740,28 +3016,8 @@
return result;
}
- /*!
- @brief inserts element
-
- Inserts element @a val before iterator @a pos.
-
- @param[in] pos iterator before which the content will be inserted; may be
- the end() iterator
- @param[in] val element to insert
- @return iterator pointing to the inserted @a val.
-
- @throw type_error.309 if called on JSON values other than arrays;
- example: `"cannot use insert() with string"`
- @throw invalid_iterator.202 if @a pos is not an iterator of *this;
- example: `"iterator does not fit current value"`
-
- @complexity Constant plus linear in the distance between @a pos and end of
- the container.
-
- @liveexample{The example shows how `insert()` is used.,insert}
-
- @since version 1.0.0
- */
+ /// @brief inserts element into array
+ /// @sa https://json.nlohmann.me/api/basic_json/insert/
iterator insert(const_iterator pos, const basic_json& val)
{
// insert only works for arrays
@@ -5780,39 +3036,15 @@
JSON_THROW(type_error::create(309, "cannot use insert() with " + std::string(type_name()), *this));
}
- /*!
- @brief inserts element
- @copydoc insert(const_iterator, const basic_json&)
- */
+ /// @brief inserts element into array
+ /// @sa https://json.nlohmann.me/api/basic_json/insert/
iterator insert(const_iterator pos, basic_json&& val)
{
return insert(pos, val);
}
- /*!
- @brief inserts elements
-
- Inserts @a cnt copies of @a val before iterator @a pos.
-
- @param[in] pos iterator before which the content will be inserted; may be
- the end() iterator
- @param[in] cnt number of copies of @a val to insert
- @param[in] val element to insert
- @return iterator pointing to the first element inserted, or @a pos if
- `cnt==0`
-
- @throw type_error.309 if called on JSON values other than arrays; example:
- `"cannot use insert() with string"`
- @throw invalid_iterator.202 if @a pos is not an iterator of *this;
- example: `"iterator does not fit current value"`
-
- @complexity Linear in @a cnt plus linear in the distance between @a pos
- and end of the container.
-
- @liveexample{The example shows how `insert()` is used.,insert__count}
-
- @since version 1.0.0
- */
+ /// @brief inserts copies of element into array
+ /// @sa https://json.nlohmann.me/api/basic_json/insert/
iterator insert(const_iterator pos, size_type cnt, const basic_json& val)
{
// insert only works for arrays
@@ -5831,36 +3063,8 @@
JSON_THROW(type_error::create(309, "cannot use insert() with " + std::string(type_name()), *this));
}
- /*!
- @brief inserts elements
-
- Inserts elements from range `[first, last)` before iterator @a pos.
-
- @param[in] pos iterator before which the content will be inserted; may be
- the end() iterator
- @param[in] first begin of the range of elements to insert
- @param[in] last end of the range of elements to insert
-
- @throw type_error.309 if called on JSON values other than arrays; example:
- `"cannot use insert() with string"`
- @throw invalid_iterator.202 if @a pos is not an iterator of *this;
- example: `"iterator does not fit current value"`
- @throw invalid_iterator.210 if @a first and @a last do not belong to the
- same JSON value; example: `"iterators do not fit"`
- @throw invalid_iterator.211 if @a first or @a last are iterators into
- container for which insert is called; example: `"passed iterators may not
- belong to container"`
-
- @return iterator pointing to the first element inserted, or @a pos if
- `first==last`
-
- @complexity Linear in `std::distance(first, last)` plus linear in the
- distance between @a pos and end of the container.
-
- @liveexample{The example shows how `insert()` is used.,insert__range}
-
- @since version 1.0.0
- */
+ /// @brief inserts range of elements into array
+ /// @sa https://json.nlohmann.me/api/basic_json/insert/
iterator insert(const_iterator pos, const_iterator first, const_iterator last)
{
// insert only works for arrays
@@ -5890,30 +3094,8 @@
return insert_iterator(pos, first.m_it.array_iterator, last.m_it.array_iterator);
}
- /*!
- @brief inserts elements
-
- Inserts elements from initializer list @a ilist before iterator @a pos.
-
- @param[in] pos iterator before which the content will be inserted; may be
- the end() iterator
- @param[in] ilist initializer list to insert the values from
-
- @throw type_error.309 if called on JSON values other than arrays; example:
- `"cannot use insert() with string"`
- @throw invalid_iterator.202 if @a pos is not an iterator of *this;
- example: `"iterator does not fit current value"`
-
- @return iterator pointing to the first element inserted, or @a pos if
- `ilist` is empty
-
- @complexity Linear in `ilist.size()` plus linear in the distance between
- @a pos and end of the container.
-
- @liveexample{The example shows how `insert()` is used.,insert__ilist}
-
- @since version 1.0.0
- */
+ /// @brief inserts elements from initializer list into array
+ /// @sa https://json.nlohmann.me/api/basic_json/insert/
iterator insert(const_iterator pos, initializer_list_t ilist)
{
// insert only works for arrays
@@ -5932,29 +3114,8 @@
return insert_iterator(pos, ilist.begin(), ilist.end());
}
- /*!
- @brief inserts elements
-
- Inserts elements from range `[first, last)`.
-
- @param[in] first begin of the range of elements to insert
- @param[in] last end of the range of elements to insert
-
- @throw type_error.309 if called on JSON values other than objects; example:
- `"cannot use insert() with string"`
- @throw invalid_iterator.202 if iterator @a first or @a last does does not
- point to an object; example: `"iterators first and last must point to
- objects"`
- @throw invalid_iterator.210 if @a first and @a last do not belong to the
- same JSON value; example: `"iterators do not fit"`
-
- @complexity Logarithmic: `O(N*log(size() + N))`, where `N` is the number
- of elements to insert.
-
- @liveexample{The example shows how `insert()` is used.,insert__range_object}
-
- @since version 3.0.0
- */
+ /// @brief inserts range of elements into object
+ /// @sa https://json.nlohmann.me/api/basic_json/insert/
void insert(const_iterator first, const_iterator last)
{
// insert only works for objects
@@ -5978,80 +3139,16 @@
m_value.object->insert(first.m_it.object_iterator, last.m_it.object_iterator);
}
- /*!
- @brief updates a JSON object from another object, overwriting existing keys
-
- Inserts all values from JSON object @a j and overwrites existing keys.
-
- @param[in] j JSON object to read values from
-
- @throw type_error.312 if called on JSON values other than objects; example:
- `"cannot use update() with string"`
-
- @complexity O(N*log(size() + N)), where N is the number of elements to
- insert.
-
- @liveexample{The example shows how `update()` is used.,update}
-
- @sa https://docs.python.org/3.6/library/stdtypes.html#dict.update
-
- @since version 3.0.0
- */
- void update(const_reference j)
+ /// @brief updates a JSON object from another object, overwriting existing keys
+ /// @sa https://json.nlohmann.me/api/basic_json/update/
+ void update(const_reference j, bool merge_objects = false)
{
- // implicitly convert null value to an empty object
- if (is_null())
- {
- m_type = value_t::object;
- m_value.object = create<object_t>();
- assert_invariant();
- }
-
- if (JSON_HEDLEY_UNLIKELY(!is_object()))
- {
- JSON_THROW(type_error::create(312, "cannot use update() with " + std::string(type_name()), *this));
- }
- if (JSON_HEDLEY_UNLIKELY(!j.is_object()))
- {
- JSON_THROW(type_error::create(312, "cannot use update() with " + std::string(j.type_name()), *this));
- }
-
- for (auto it = j.cbegin(); it != j.cend(); ++it)
- {
- m_value.object->operator[](it.key()) = it.value();
-#if JSON_DIAGNOSTICS
- m_value.object->operator[](it.key()).m_parent = this;
-#endif
- }
+ update(j.begin(), j.end(), merge_objects);
}
- /*!
- @brief updates a JSON object from another object, overwriting existing keys
-
- Inserts all values from from range `[first, last)` and overwrites existing
- keys.
-
- @param[in] first begin of the range of elements to insert
- @param[in] last end of the range of elements to insert
-
- @throw type_error.312 if called on JSON values other than objects; example:
- `"cannot use update() with string"`
- @throw invalid_iterator.202 if iterator @a first or @a last does does not
- point to an object; example: `"iterators first and last must point to
- objects"`
- @throw invalid_iterator.210 if @a first and @a last do not belong to the
- same JSON value; example: `"iterators do not fit"`
-
- @complexity O(N*log(size() + N)), where N is the number of elements to
- insert.
-
- @liveexample{The example shows how `update()` is used__range.,update}
-
- @sa https://docs.python.org/3.6/library/stdtypes.html#dict.update
-
- @since version 3.0.0
- */
- void update(const_iterator first, const_iterator last)
+ /// @brief updates a JSON object from another object, overwriting existing keys
+ /// @sa https://json.nlohmann.me/api/basic_json/update/
+ void update(const_iterator first, const_iterator last, bool merge_objects = false)
{
// implicitly convert null value to an empty object
if (is_null())
@@ -6073,14 +3170,22 @@
}
// passed iterators must belong to objects
- if (JSON_HEDLEY_UNLIKELY(!first.m_object->is_object()
- || !last.m_object->is_object()))
+ if (JSON_HEDLEY_UNLIKELY(!first.m_object->is_object()))
{
- JSON_THROW(invalid_iterator::create(202, "iterators first and last must point to objects", *this));
+ JSON_THROW(type_error::create(312, "cannot use update() with " + std::string(first.m_object->type_name()), *first.m_object));
}
for (auto it = first; it != last; ++it)
{
+ if (merge_objects && it.value().is_object())
+ {
+ auto it2 = m_value.object->find(it.key());
+ if (it2 != m_value.object->end())
+ {
+ it2->second.update(it.value(), true);
+ continue;
+ }
+ }
m_value.object->operator[](it.key()) = it.value();
#if JSON_DIAGNOSTICS
m_value.object->operator[](it.key()).m_parent = this;
@@ -6088,23 +3193,8 @@
}
}
- /*!
- @brief exchanges the values
-
- Exchanges the contents of the JSON value with those of @a other. Does not
- invoke any move, copy, or swap operations on individual elements. All
- iterators and references remain valid. The past-the-end iterator is
- invalidated.
-
- @param[in,out] other JSON value to exchange the contents with
-
- @complexity Constant.
-
- @liveexample{The example below shows how JSON values can be swapped with
- `swap()`.,swap__reference}
-
- @since version 1.0.0
- */
+ /// @brief exchanges the values
+ /// @sa https://json.nlohmann.me/api/basic_json/swap/
void swap(reference other) noexcept (
std::is_nothrow_move_constructible<value_t>::value&&
std::is_nothrow_move_assignable<value_t>::value&&
@@ -6120,24 +3210,8 @@
assert_invariant();
}
- /*!
- @brief exchanges the values
-
- Exchanges the contents of the JSON value from @a left with those of @a right. Does not
- invoke any move, copy, or swap operations on individual elements. All
- iterators and references remain valid. The past-the-end iterator is
- invalidated. implemented as a friend function callable via ADL.
-
- @param[in,out] left JSON value to exchange the contents with
- @param[in,out] right JSON value to exchange the contents with
-
- @complexity Constant.
-
- @liveexample{The example below shows how JSON values can be swapped with
- `swap()`.,swap__reference}
-
- @since version 1.0.0
- */
+ /// @brief exchanges the values
+ /// @sa https://json.nlohmann.me/api/basic_json/swap/
friend void swap(reference left, reference right) noexcept (
std::is_nothrow_move_constructible<value_t>::value&&
std::is_nothrow_move_assignable<value_t>::value&&
@@ -6148,26 +3222,8 @@
left.swap(right);
}
- /*!
- @brief exchanges the values
-
- Exchanges the contents of a JSON array with those of @a other. Does not
- invoke any move, copy, or swap operations on individual elements. All
- iterators and references remain valid. The past-the-end iterator is
- invalidated.
-
- @param[in,out] other array to exchange the contents with
-
- @throw type_error.310 when JSON value is not an array; example: `"cannot
- use swap() with string"`
-
- @complexity Constant.
-
- @liveexample{The example below shows how arrays can be swapped with
- `swap()`.,swap__array_t}
-
- @since version 1.0.0
- */
+ /// @brief exchanges the values
+ /// @sa https://json.nlohmann.me/api/basic_json/swap/
void swap(array_t& other) // NOLINT(bugprone-exception-escape)
{
// swap only works for arrays
@@ -6181,26 +3237,8 @@
}
}
- /*!
- @brief exchanges the values
-
- Exchanges the contents of a JSON object with those of @a other. Does not
- invoke any move, copy, or swap operations on individual elements. All
- iterators and references remain valid. The past-the-end iterator is
- invalidated.
-
- @param[in,out] other object to exchange the contents with
-
- @throw type_error.310 when JSON value is not an object; example:
- `"cannot use swap() with string"`
-
- @complexity Constant.
-
- @liveexample{The example below shows how objects can be swapped with
- `swap()`.,swap__object_t}
-
- @since version 1.0.0
- */
+ /// @brief exchanges the values
+ /// @sa https://json.nlohmann.me/api/basic_json/swap/
void swap(object_t& other) // NOLINT(bugprone-exception-escape)
{
// swap only works for objects
@@ -6214,26 +3252,8 @@
}
}
- /*!
- @brief exchanges the values
-
- Exchanges the contents of a JSON string with those of @a other. Does not
- invoke any move, copy, or swap operations on individual elements. All
- iterators and references remain valid. The past-the-end iterator is
- invalidated.
-
- @param[in,out] other string to exchange the contents with
-
- @throw type_error.310 when JSON value is not a string; example: `"cannot
- use swap() with boolean"`
-
- @complexity Constant.
-
- @liveexample{The example below shows how strings can be swapped with
- `swap()`.,swap__string_t}
-
- @since version 1.0.0
- */
+ /// @brief exchanges the values
+ /// @sa https://json.nlohmann.me/api/basic_json/swap/
void swap(string_t& other) // NOLINT(bugprone-exception-escape)
{
// swap only works for strings
@@ -6247,26 +3267,8 @@
}
}
- /*!
- @brief exchanges the values
-
- Exchanges the contents of a JSON string with those of @a other. Does not
- invoke any move, copy, or swap operations on individual elements. All
- iterators and references remain valid. The past-the-end iterator is
- invalidated.
-
- @param[in,out] other binary to exchange the contents with
-
- @throw type_error.310 when JSON value is not a string; example: `"cannot
- use swap() with boolean"`
-
- @complexity Constant.
-
- @liveexample{The example below shows how strings can be swapped with
- `swap()`.,swap__binary_t}
-
- @since version 3.8.0
- */
+ /// @brief exchanges the values
+ /// @sa https://json.nlohmann.me/api/basic_json/swap/
void swap(binary_t& other) // NOLINT(bugprone-exception-escape)
{
// swap only works for strings
@@ -6280,7 +3282,8 @@
}
}
- /// @copydoc swap(binary_t&)
+ /// @brief exchanges the values
+ /// @sa https://json.nlohmann.me/api/basic_json/swap/
void swap(typename binary_t::container_type& other) // NOLINT(bugprone-exception-escape)
{
// swap only works for strings
@@ -6304,61 +3307,8 @@
/// @name lexicographical comparison operators
/// @{
- /*!
- @brief comparison: equal
-
- Compares two JSON values for equality according to the following rules:
- - Two JSON values are equal if (1) they are from the same type and (2)
- their stored values are the same according to their respective
- `operator==`.
- - Integer and floating-point numbers are automatically converted before
- comparison. Note that two NaN values are always treated as unequal.
- - Two JSON null values are equal.
-
- @note Floating-point inside JSON values numbers are compared with
- `json::number_float_t::operator==` which is `double::operator==` by
- default. To compare floating-point while respecting an epsilon, an alternative
- [comparison function](https://github.com/mariokonrad/marnav/blob/master/include/marnav/math/floatingpoint.hpp#L34-#L39)
- could be used, for instance
- @code {.cpp}
- template<typename T, typename = typename std::enable_if<std::is_floating_point<T>::value, T>::type>
- inline bool is_same(T a, T b, T epsilon = std::numeric_limits<T>::epsilon()) noexcept
- {
- return std::abs(a - b) <= epsilon;
- }
- @endcode
- Or you can self-defined operator equal function like this:
- @code {.cpp}
- bool my_equal(const_reference lhs, const_reference rhs) {
- const auto lhs_type lhs.type();
- const auto rhs_type rhs.type();
- if (lhs_type == rhs_type) {
- switch(lhs_type)
- // self_defined case
- case value_t::number_float:
- return std::abs(lhs - rhs) <= std::numeric_limits<float>::epsilon();
- // other cases remain the same with the original
- ...
- }
- ...
- }
- @endcode
-
- @note NaN values never compare equal to themselves or to other NaN values.
-
- @param[in] lhs first JSON value to consider
- @param[in] rhs second JSON value to consider
- @return whether the values @a lhs and @a rhs are equal
-
- @exceptionsafety No-throw guarantee: this function never throws exceptions.
-
- @complexity Linear.
-
- @liveexample{The example demonstrates comparing several JSON
- types.,operator__equal}
-
- @since version 1.0.0
- */
+ /// @brief comparison: equal
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_eq/
friend bool operator==(const_reference lhs, const_reference rhs) noexcept
{
#ifdef __GNUC__
@@ -6435,10 +3385,8 @@
#endif
}
- /*!
- @brief comparison: equal
- @copydoc operator==(const_reference, const_reference)
- */
+ /// @brief comparison: equal
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_eq/
template<typename ScalarType, typename std::enable_if<
std::is_scalar<ScalarType>::value, int>::type = 0>
friend bool operator==(const_reference lhs, ScalarType rhs) noexcept
@@ -6446,10 +3394,8 @@
return lhs == basic_json(rhs);
}
- /*!
- @brief comparison: equal
- @copydoc operator==(const_reference, const_reference)
- */
+ /// @brief comparison: equal
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_eq/
template<typename ScalarType, typename std::enable_if<
std::is_scalar<ScalarType>::value, int>::type = 0>
friend bool operator==(ScalarType lhs, const_reference rhs) noexcept
@@ -6457,33 +3403,15 @@
return basic_json(lhs) == rhs;
}
- /*!
- @brief comparison: not equal
-
- Compares two JSON values for inequality by calculating `not (lhs == rhs)`.
-
- @param[in] lhs first JSON value to consider
- @param[in] rhs second JSON value to consider
- @return whether the values @a lhs and @a rhs are not equal
-
- @complexity Linear.
-
- @exceptionsafety No-throw guarantee: this function never throws exceptions.
-
- @liveexample{The example demonstrates comparing several JSON
- types.,operator__notequal}
-
- @since version 1.0.0
- */
+ /// @brief comparison: not equal
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_ne/
friend bool operator!=(const_reference lhs, const_reference rhs) noexcept
{
return !(lhs == rhs);
}
- /*!
- @brief comparison: not equal
- @copydoc operator!=(const_reference, const_reference)
- */
+ /// @brief comparison: not equal
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_ne/
template<typename ScalarType, typename std::enable_if<
std::is_scalar<ScalarType>::value, int>::type = 0>
friend bool operator!=(const_reference lhs, ScalarType rhs) noexcept
@@ -6491,10 +3419,8 @@
return lhs != basic_json(rhs);
}
- /*!
- @brief comparison: not equal
- @copydoc operator!=(const_reference, const_reference)
- */
+ /// @brief comparison: not equal
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_ne/
template<typename ScalarType, typename std::enable_if<
std::is_scalar<ScalarType>::value, int>::type = 0>
friend bool operator!=(ScalarType lhs, const_reference rhs) noexcept
@@ -6502,32 +3428,8 @@
return basic_json(lhs) != rhs;
}
- /*!
- @brief comparison: less than
-
- Compares whether one JSON value @a lhs is less than another JSON value @a
- rhs according to the following rules:
- - If @a lhs and @a rhs have the same type, the values are compared using
- the default `<` operator.
- - Integer and floating-point numbers are automatically converted before
- comparison
- - In case @a lhs and @a rhs have different types, the values are ignored
- and the order of the types is considered, see
- @ref operator<(const value_t, const value_t).
-
- @param[in] lhs first JSON value to consider
- @param[in] rhs second JSON value to consider
- @return whether @a lhs is less than @a rhs
-
- @complexity Linear.
-
- @exceptionsafety No-throw guarantee: this function never throws exceptions.
-
- @liveexample{The example demonstrates comparing several JSON
- types.,operator__less}
-
- @since version 1.0.0
- */
+ /// @brief comparison: less than
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_lt/
friend bool operator<(const_reference lhs, const_reference rhs) noexcept
{
const auto lhs_type = lhs.type();
@@ -6602,10 +3504,8 @@
return operator<(lhs_type, rhs_type);
}
- /*!
- @brief comparison: less than
- @copydoc operator<(const_reference, const_reference)
- */
+ /// @brief comparison: less than
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_lt/
template<typename ScalarType, typename std::enable_if<
std::is_scalar<ScalarType>::value, int>::type = 0>
friend bool operator<(const_reference lhs, ScalarType rhs) noexcept
@@ -6613,10 +3513,8 @@
return lhs < basic_json(rhs);
}
- /*!
- @brief comparison: less than
- @copydoc operator<(const_reference, const_reference)
- */
+ /// @brief comparison: less than
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_lt/
template<typename ScalarType, typename std::enable_if<
std::is_scalar<ScalarType>::value, int>::type = 0>
friend bool operator<(ScalarType lhs, const_reference rhs) noexcept
@@ -6624,34 +3522,15 @@
return basic_json(lhs) < rhs;
}
- /*!
- @brief comparison: less than or equal
-
- Compares whether one JSON value @a lhs is less than or equal to another
- JSON value by calculating `not (rhs < lhs)`.
-
- @param[in] lhs first JSON value to consider
- @param[in] rhs second JSON value to consider
- @return whether @a lhs is less than or equal to @a rhs
-
- @complexity Linear.
-
- @exceptionsafety No-throw guarantee: this function never throws exceptions.
-
- @liveexample{The example demonstrates comparing several JSON
- types.,operator__greater}
-
- @since version 1.0.0
- */
+ /// @brief comparison: less than or equal
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_le/
friend bool operator<=(const_reference lhs, const_reference rhs) noexcept
{
return !(rhs < lhs);
}
- /*!
- @brief comparison: less than or equal
- @copydoc operator<=(const_reference, const_reference)
- */
+ /// @brief comparison: less than or equal
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_le/
template<typename ScalarType, typename std::enable_if<
std::is_scalar<ScalarType>::value, int>::type = 0>
friend bool operator<=(const_reference lhs, ScalarType rhs) noexcept
@@ -6659,10 +3538,8 @@
return lhs <= basic_json(rhs);
}
- /*!
- @brief comparison: less than or equal
- @copydoc operator<=(const_reference, const_reference)
- */
+ /// @brief comparison: less than or equal
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_le/
template<typename ScalarType, typename std::enable_if<
std::is_scalar<ScalarType>::value, int>::type = 0>
friend bool operator<=(ScalarType lhs, const_reference rhs) noexcept
@@ -6670,34 +3547,15 @@
return basic_json(lhs) <= rhs;
}
- /*!
- @brief comparison: greater than
-
- Compares whether one JSON value @a lhs is greater than another
- JSON value by calculating `not (lhs <= rhs)`.
-
- @param[in] lhs first JSON value to consider
- @param[in] rhs second JSON value to consider
- @return whether @a lhs is greater than to @a rhs
-
- @complexity Linear.
-
- @exceptionsafety No-throw guarantee: this function never throws exceptions.
-
- @liveexample{The example demonstrates comparing several JSON
- types.,operator__lessequal}
-
- @since version 1.0.0
- */
+ /// @brief comparison: greater than
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_gt/
friend bool operator>(const_reference lhs, const_reference rhs) noexcept
{
return !(lhs <= rhs);
}
- /*!
- @brief comparison: greater than
- @copydoc operator>(const_reference, const_reference)
- */
+ /// @brief comparison: greater than
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_gt/
template<typename ScalarType, typename std::enable_if<
std::is_scalar<ScalarType>::value, int>::type = 0>
friend bool operator>(const_reference lhs, ScalarType rhs) noexcept
@@ -6705,10 +3563,8 @@
return lhs > basic_json(rhs);
}
- /*!
- @brief comparison: greater than
- @copydoc operator>(const_reference, const_reference)
- */
+ /// @brief comparison: greater than
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_gt/
template<typename ScalarType, typename std::enable_if<
std::is_scalar<ScalarType>::value, int>::type = 0>
friend bool operator>(ScalarType lhs, const_reference rhs) noexcept
@@ -6716,34 +3572,15 @@
return basic_json(lhs) > rhs;
}
- /*!
- @brief comparison: greater than or equal
-
- Compares whether one JSON value @a lhs is greater than or equal to another
- JSON value by calculating `not (lhs < rhs)`.
-
- @param[in] lhs first JSON value to consider
- @param[in] rhs second JSON value to consider
- @return whether @a lhs is greater than or equal to @a rhs
-
- @complexity Linear.
-
- @exceptionsafety No-throw guarantee: this function never throws exceptions.
-
- @liveexample{The example demonstrates comparing several JSON
- types.,operator__greaterequal}
-
- @since version 1.0.0
- */
+ /// @brief comparison: greater than or equal
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_ge/
friend bool operator>=(const_reference lhs, const_reference rhs) noexcept
{
return !(lhs < rhs);
}
- /*!
- @brief comparison: greater than or equal
- @copydoc operator>=(const_reference, const_reference)
- */
+ /// @brief comparison: greater than or equal
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_ge/
template<typename ScalarType, typename std::enable_if<
std::is_scalar<ScalarType>::value, int>::type = 0>
friend bool operator>=(const_reference lhs, ScalarType rhs) noexcept
@@ -6751,10 +3588,8 @@
return lhs >= basic_json(rhs);
}
- /*!
- @brief comparison: greater than or equal
- @copydoc operator>=(const_reference, const_reference)
- */
+ /// @brief comparison: greater than or equal
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_ge/
template<typename ScalarType, typename std::enable_if<
std::is_scalar<ScalarType>::value, int>::type = 0>
friend bool operator>=(ScalarType lhs, const_reference rhs) noexcept
@@ -6771,37 +3606,8 @@
/// @name serialization
/// @{
#ifndef JSON_NO_IO
- /*!
- @brief serialize to stream
-
- Serialize the given JSON value @a j to the output stream @a o. The JSON
- value will be serialized using the @ref dump member function.
-
- - The indentation of the output can be controlled with the member variable
- `width` of the output stream @a o. For instance, using the manipulator
- `std::setw(4)` on @a o sets the indentation level to `4` and the
- serialization result is the same as calling `dump(4)`.
-
- - The indentation character can be controlled with the member variable
- `fill` of the output stream @a o. For instance, the manipulator
- `std::setfill('\\t')` sets indentation to use a tab character rather than
- the default space character.
-
- @param[in,out] o stream to serialize to
- @param[in] j JSON value to serialize
-
- @return the stream @a o
-
- @throw type_error.316 if a string stored inside the JSON value is not
- UTF-8 encoded
-
- @complexity Linear.
-
- @liveexample{The example below shows the serialization with different
- parameters to `width` to adjust the indentation level.,operator_serialize}
-
- @since version 1.0.0; indentation character added in version 3.0.0
- */
+ /// @brief serialize to stream
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_ltlt/
friend std::ostream& operator<<(std::ostream& o, const basic_json& j)
{
// read width member and use it as indentation parameter if nonzero
@@ -6817,14 +3623,12 @@
return o;
}
- /*!
- @brief serialize to stream
- @deprecated This stream operator is deprecated and will be removed in
- future 4.0.0 of the library. Please use
- @ref operator<<(std::ostream&, const basic_json&)
- instead; that is, replace calls like `j >> o;` with `o << j;`.
- @since version 1.0.0; deprecated since version 3.0.0
- */
+ /// @brief serialize to stream
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_ltlt/
+ /// @deprecated This function is deprecated since 3.0.0 and will be removed in
+ /// version 4.0.0 of the library. Please use
+ /// operator<<(std::ostream&, const basic_json&) instead; that is,
+ /// replace calls like `j >> o;` with `o << j;`.
JSON_HEDLEY_DEPRECATED_FOR(3.0.0, operator<<(std::ostream&, const basic_json&))
friend std::ostream& operator>>(const basic_json& j, std::ostream& o)
{
@@ -6841,57 +3645,8 @@
/// @name deserialization
/// @{
- /*!
- @brief deserialize from a compatible input
-
- @tparam InputType A compatible input, for instance
- - an std::istream object
- - a FILE pointer
- - a C-style array of characters
- - a pointer to a null-terminated string of single byte characters
- - an object obj for which begin(obj) and end(obj) produces a valid pair of
- iterators.
-
- @param[in] i input to read from
- @param[in] cb a parser callback function of type @ref parser_callback_t
- which is used to control the deserialization by filtering unwanted values
- (optional)
- @param[in] allow_exceptions whether to throw exceptions in case of a
- parse error (optional, true by default)
- @param[in] ignore_comments whether comments should be ignored and treated
- like whitespace (true) or yield a parse error (true); (optional, false by
- default)
-
- @return deserialized JSON value; in case of a parse error and
- @a allow_exceptions set to `false`, the return value will be
- value_t::discarded.
-
- @throw parse_error.101 if a parse error occurs; example: `""unexpected end
- of input; expected string literal""`
- @throw parse_error.102 if to_unicode fails or surrogate error
- @throw parse_error.103 if to_unicode fails
-
- @complexity Linear in the length of the input. The parser is a predictive
- LL(1) parser. The complexity can be higher if the parser callback function
- @a cb or reading from the input @a i has a super-linear complexity.
-
- @note A UTF-8 byte order mark is silently ignored.
-
- @liveexample{The example below demonstrates the `parse()` function reading
- from an array.,parse__array__parser_callback_t}
-
- @liveexample{The example below demonstrates the `parse()` function with
- and without callback function.,parse__string__parser_callback_t}
-
- @liveexample{The example below demonstrates the `parse()` function with
- and without callback function.,parse__istream__parser_callback_t}
-
- @liveexample{The example below demonstrates the `parse()` function reading
- from a contiguous container.,parse__contiguouscontainer__parser_callback_t}
-
- @since version 2.0.3 (contiguous containers); version 3.9.0 allowed to
- ignore comments.
- */
+ /// @brief deserialize from a compatible input
+ /// @sa https://json.nlohmann.me/api/basic_json/parse/
template<typename InputType>
JSON_HEDLEY_WARN_UNUSED_RESULT
static basic_json parse(InputType&& i,
@@ -6904,32 +3659,8 @@
return result;
}
- /*!
- @brief deserialize from a pair of character iterators
-
- The value_type of the iterator must be a integral type with size of 1, 2 or
- 4 bytes, which will be interpreted respectively as UTF-8, UTF-16 and UTF-32.
-
- @param[in] first iterator to start of character range
- @param[in] last iterator to end of character range
- @param[in] cb a parser callback function of type @ref parser_callback_t
- which is used to control the deserialization by filtering unwanted values
- (optional)
- @param[in] allow_exceptions whether to throw exceptions in case of a
- parse error (optional, true by default)
- @param[in] ignore_comments whether comments should be ignored and treated
- like whitespace (true) or yield a parse error (true); (optional, false by
- default)
-
- @return deserialized JSON value; in case of a parse error and
- @a allow_exceptions set to `false`, the return value will be
- value_t::discarded.
-
- @throw parse_error.101 if a parse error occurs; example: `""unexpected end
- of input; expected string literal""`
- @throw parse_error.102 if to_unicode fails or surrogate error
- @throw parse_error.103 if to_unicode fails
- */
+ /// @brief deserialize from a pair of character iterators
+ /// @sa https://json.nlohmann.me/api/basic_json/parse/
template<typename IteratorType>
JSON_HEDLEY_WARN_UNUSED_RESULT
static basic_json parse(IteratorType first,
@@ -6955,36 +3686,8 @@
return result;
}
- /*!
- @brief check if the input is valid JSON
-
- Unlike the @ref parse(InputType&&, const parser_callback_t,const bool)
- function, this function neither throws an exception in case of invalid JSON
- input (i.e., a parse error) nor creates diagnostic information.
-
- @tparam InputType A compatible input, for instance
- - an std::istream object
- - a FILE pointer
- - a C-style array of characters
- - a pointer to a null-terminated string of single byte characters
- - an object obj for which begin(obj) and end(obj) produces a valid pair of
- iterators.
-
- @param[in] i input to read from
- @param[in] ignore_comments whether comments should be ignored and treated
- like whitespace (true) or yield a parse error (true); (optional, false by
- default)
-
- @return Whether the input read from @a i is valid JSON.
-
- @complexity Linear in the length of the input. The parser is a predictive
- LL(1) parser.
-
- @note A UTF-8 byte order mark is silently ignored.
-
- @liveexample{The example below demonstrates the `accept()` function reading
- from a string.,accept__string}
- */
+ /// @brief check if the input is valid JSON
+ /// @sa https://json.nlohmann.me/api/basic_json/accept/
template<typename InputType>
static bool accept(InputType&& i,
const bool ignore_comments = false)
@@ -6992,6 +3695,8 @@
return parser(detail::input_adapter(std::forward<InputType>(i)), nullptr, false, ignore_comments).accept(true);
}
+ /// @brief check if the input is valid JSON
+ /// @sa https://json.nlohmann.me/api/basic_json/accept/
template<typename IteratorType>
static bool accept(IteratorType first, IteratorType last,
const bool ignore_comments = false)
@@ -7007,46 +3712,8 @@
return parser(i.get(), nullptr, false, ignore_comments).accept(true);
}
- /*!
- @brief generate SAX events
-
- The SAX event lister must follow the interface of @ref json_sax.
-
- This function reads from a compatible input. Examples are:
- - an std::istream object
- - a FILE pointer
- - a C-style array of characters
- - a pointer to a null-terminated string of single byte characters
- - an object obj for which begin(obj) and end(obj) produces a valid pair of
- iterators.
-
- @param[in] i input to read from
- @param[in,out] sax SAX event listener
- @param[in] format the format to parse (JSON, CBOR, MessagePack, or UBJSON)
- @param[in] strict whether the input has to be consumed completely
- @param[in] ignore_comments whether comments should be ignored and treated
- like whitespace (true) or yield a parse error (true); (optional, false by
- default); only applies to the JSON file format.
-
- @return return value of the last processed SAX event
-
- @throw parse_error.101 if a parse error occurs; example: `""unexpected end
- of input; expected string literal""`
- @throw parse_error.102 if to_unicode fails or surrogate error
- @throw parse_error.103 if to_unicode fails
-
- @complexity Linear in the length of the input. The parser is a predictive
- LL(1) parser. The complexity can be higher if the SAX consumer @a sax has
- a super-linear complexity.
-
- @note A UTF-8 byte order mark is silently ignored.
-
- @liveexample{The example below demonstrates the `sax_parse()` function
- reading from string and processing the events with a user-defined SAX
- event consumer.,sax_parse}
-
- @since version 3.2.0
- */
+ /// @brief generate SAX events
+ /// @sa https://json.nlohmann.me/api/basic_json/sax_parse/
template <typename InputType, typename SAX>
JSON_HEDLEY_NON_NULL(2)
static bool sax_parse(InputType&& i, SAX* sax,
@@ -7060,6 +3727,8 @@
: detail::binary_reader<basic_json, decltype(ia), SAX>(std::move(ia)).sax_parse(format, sax, strict);
}
+ /// @brief generate SAX events
+ /// @sa https://json.nlohmann.me/api/basic_json/sax_parse/
template<class IteratorType, class SAX>
JSON_HEDLEY_NON_NULL(3)
static bool sax_parse(IteratorType first, IteratorType last, SAX* sax,
@@ -7073,6 +3742,11 @@
: detail::binary_reader<basic_json, decltype(ia), SAX>(std::move(ia)).sax_parse(format, sax, strict);
}
+ /// @brief generate SAX events
+ /// @sa https://json.nlohmann.me/api/basic_json/sax_parse/
+ /// @deprecated This function is deprecated since 3.8.0 and will be removed in
+ /// version 4.0.0 of the library. Please use
+ /// sax_parse(ptr, ptr + len) instead.
template <typename SAX>
JSON_HEDLEY_DEPRECATED_FOR(3.8.0, sax_parse(ptr, ptr + len, ...))
JSON_HEDLEY_NON_NULL(2)
@@ -7089,45 +3763,20 @@
: detail::binary_reader<basic_json, decltype(ia), SAX>(std::move(ia)).sax_parse(format, sax, strict);
}
#ifndef JSON_NO_IO
- /*!
- @brief deserialize from stream
- @deprecated This stream operator is deprecated and will be removed in
- version 4.0.0 of the library. Please use
- @ref operator>>(std::istream&, basic_json&)
- instead; that is, replace calls like `j << i;` with `i >> j;`.
- @since version 1.0.0; deprecated since version 3.0.0
- */
+ /// @brief deserialize from stream
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_gtgt/
+ /// @deprecated This stream operator is deprecated since 3.0.0 and will be removed in
+ /// version 4.0.0 of the library. Please use
+ /// operator>>(std::istream&, basic_json&) instead; that is,
+ /// replace calls like `j << i;` with `i >> j;`.
JSON_HEDLEY_DEPRECATED_FOR(3.0.0, operator>>(std::istream&, basic_json&))
friend std::istream& operator<<(basic_json& j, std::istream& i)
{
return operator>>(i, j);
}
- /*!
- @brief deserialize from stream
-
- Deserializes an input stream to a JSON value.
-
- @param[in,out] i input stream to read a serialized JSON value from
- @param[in,out] j JSON value to write the deserialized input to
-
- @throw parse_error.101 in case of an unexpected token
- @throw parse_error.102 if to_unicode fails or surrogate error
- @throw parse_error.103 if to_unicode fails
-
- @complexity Linear in the length of the input. The parser is a predictive
- LL(1) parser.
-
- @note A UTF-8 byte order mark is silently ignored.
-
- @liveexample{The example below shows how a JSON value is constructed by
- reading a serialization from a stream.,operator_deserialize}
-
- @sa parse(std::istream&, const parser_callback_t) for a variant with a
- parser callback function to filter values while parsing
-
- @since version 1.0.0
- */
+ /// @brief deserialize from stream
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_gtgt/
friend std::istream& operator>>(std::istream& i, basic_json& j)
{
parser(detail::input_adapter(i)).parse(false, j);
@@ -7140,63 +3789,32 @@
// convenience functions //
///////////////////////////
- /*!
- @brief return the type as string
-
- Returns the type name as string to be used in error messages - usually to
- indicate that a function was called on a wrong JSON type.
-
- @return a string representation of a the @a m_type member:
- Value type | return value
- ----------- | -------------
- null | `"null"`
- boolean | `"boolean"`
- string | `"string"`
- number | `"number"` (for all number types)
- object | `"object"`
- array | `"array"`
- binary | `"binary"`
- discarded | `"discarded"`
-
- @exceptionsafety No-throw guarantee: this function never throws exceptions.
-
- @complexity Constant.
-
- @liveexample{The following code exemplifies `type_name()` for all JSON
- types.,type_name}
-
- @sa see @ref type() -- return the type of the JSON value
- @sa see @ref operator value_t() -- return the type of the JSON value (implicit)
-
- @since version 1.0.0, public since 2.1.0, `const char*` and `noexcept`
- since 3.0.0
- */
+ /// @brief return the type as string
+ /// @sa https://json.nlohmann.me/api/basic_json/type_name/
JSON_HEDLEY_RETURNS_NON_NULL
const char* type_name() const noexcept
{
+ switch (m_type)
{
- switch (m_type)
- {
- case value_t::null:
- return "null";
- case value_t::object:
- return "object";
- case value_t::array:
- return "array";
- case value_t::string:
- return "string";
- case value_t::boolean:
- return "boolean";
- case value_t::binary:
- return "binary";
- case value_t::discarded:
- return "discarded";
- case value_t::number_integer:
- case value_t::number_unsigned:
- case value_t::number_float:
- default:
- return "number";
- }
+ case value_t::null:
+ return "null";
+ case value_t::object:
+ return "object";
+ case value_t::array:
+ return "array";
+ case value_t::string:
+ return "string";
+ case value_t::boolean:
+ return "boolean";
+ case value_t::binary:
+ return "binary";
+ case value_t::discarded:
+ return "discarded";
+ case value_t::number_integer:
+ case value_t::number_unsigned:
+ case value_t::number_float:
+ default:
+ return "number";
}
}
@@ -7225,104 +3843,8 @@
/// @{
public:
- /*!
- @brief create a CBOR serialization of a given JSON value
-
- Serializes a given JSON value @a j to a byte vector using the CBOR (Concise
- Binary Object Representation) serialization format. CBOR is a binary
- serialization format which aims to be more compact than JSON itself, yet
- more efficient to parse.
-
- The library uses the following mapping from JSON values types to
- CBOR types according to the CBOR specification (RFC 7049):
-
- JSON value type | value/range | CBOR type | first byte
- --------------- | ------------------------------------------ | ---------------------------------- | ---------------
- null | `null` | Null | 0xF6
- boolean | `true` | True | 0xF5
- boolean | `false` | False | 0xF4
- number_integer | -9223372036854775808..-2147483649 | Negative integer (8 bytes follow) | 0x3B
- number_integer | -2147483648..-32769 | Negative integer (4 bytes follow) | 0x3A
- number_integer | -32768..-129 | Negative integer (2 bytes follow) | 0x39
- number_integer | -128..-25 | Negative integer (1 byte follow) | 0x38
- number_integer | -24..-1 | Negative integer | 0x20..0x37
- number_integer | 0..23 | Integer | 0x00..0x17
- number_integer | 24..255 | Unsigned integer (1 byte follow) | 0x18
- number_integer | 256..65535 | Unsigned integer (2 bytes follow) | 0x19
- number_integer | 65536..4294967295 | Unsigned integer (4 bytes follow) | 0x1A
- number_integer | 4294967296..18446744073709551615 | Unsigned integer (8 bytes follow) | 0x1B
- number_unsigned | 0..23 | Integer | 0x00..0x17
- number_unsigned | 24..255 | Unsigned integer (1 byte follow) | 0x18
- number_unsigned | 256..65535 | Unsigned integer (2 bytes follow) | 0x19
- number_unsigned | 65536..4294967295 | Unsigned integer (4 bytes follow) | 0x1A
- number_unsigned | 4294967296..18446744073709551615 | Unsigned integer (8 bytes follow) | 0x1B
- number_float | *any value representable by a float* | Single-Precision Float | 0xFA
- number_float | *any value NOT representable by a float* | Double-Precision Float | 0xFB
- string | *length*: 0..23 | UTF-8 string | 0x60..0x77
- string | *length*: 23..255 | UTF-8 string (1 byte follow) | 0x78
- string | *length*: 256..65535 | UTF-8 string (2 bytes follow) | 0x79
- string | *length*: 65536..4294967295 | UTF-8 string (4 bytes follow) | 0x7A
- string | *length*: 4294967296..18446744073709551615 | UTF-8 string (8 bytes follow) | 0x7B
- array | *size*: 0..23 | array | 0x80..0x97
- array | *size*: 23..255 | array (1 byte follow) | 0x98
- array | *size*: 256..65535 | array (2 bytes follow) | 0x99
- array | *size*: 65536..4294967295 | array (4 bytes follow) | 0x9A
- array | *size*: 4294967296..18446744073709551615 | array (8 bytes follow) | 0x9B
- object | *size*: 0..23 | map | 0xA0..0xB7
- object | *size*: 23..255 | map (1 byte follow) | 0xB8
- object | *size*: 256..65535 | map (2 bytes follow) | 0xB9
- object | *size*: 65536..4294967295 | map (4 bytes follow) | 0xBA
- object | *size*: 4294967296..18446744073709551615 | map (8 bytes follow) | 0xBB
- binary | *size*: 0..23 | byte string | 0x40..0x57
- binary | *size*: 23..255 | byte string (1 byte follow) | 0x58
- binary | *size*: 256..65535 | byte string (2 bytes follow) | 0x59
- binary | *size*: 65536..4294967295 | byte string (4 bytes follow) | 0x5A
- binary | *size*: 4294967296..18446744073709551615 | byte string (8 bytes follow) | 0x5B
-
- Binary values with subtype are mapped to tagged values (0xD8..0xDB)
- depending on the subtype, followed by a byte string, see "binary" cells
- in the table above.
-
- @note The mapping is **complete** in the sense that any JSON value type
- can be converted to a CBOR value.
-
- @note If NaN or Infinity are stored inside a JSON number, they are
- serialized properly. This behavior differs from the @ref dump()
- function which serializes NaN or Infinity to `null`.
-
- @note The following CBOR types are not used in the conversion:
- - UTF-8 strings terminated by "break" (0x7F)
- - arrays terminated by "break" (0x9F)
- - maps terminated by "break" (0xBF)
- - byte strings terminated by "break" (0x5F)
- - date/time (0xC0..0xC1)
- - bignum (0xC2..0xC3)
- - decimal fraction (0xC4)
- - bigfloat (0xC5)
- - expected conversions (0xD5..0xD7)
- - simple values (0xE0..0xF3, 0xF8)
- - undefined (0xF7)
- - half-precision floats (0xF9)
- - break (0xFF)
-
- @param[in] j JSON value to serialize
- @return CBOR serialization as byte vector
-
- @complexity Linear in the size of the JSON value @a j.
-
- @liveexample{The example shows the serialization of a JSON value to a byte
- vector in CBOR format.,to_cbor}
-
- @sa http://cbor.io
- @sa see @ref from_cbor(InputType&&, const bool, const bool, const cbor_tag_handler_t) for the
- analogous deserialization
- @sa see @ref to_msgpack(const basic_json&) for the related MessagePack format
- @sa see @ref to_ubjson(const basic_json&, const bool, const bool) for the
- related UBJSON format
-
- @since version 2.0.9; compact representation of floating-point numbers
- since version 3.8.0
- */
+ /// @brief create a CBOR serialization of a given JSON value
+ /// @sa https://json.nlohmann.me/api/basic_json/to_cbor/
static std::vector<std::uint8_t> to_cbor(const basic_json& j)
{
std::vector<std::uint8_t> result;
@@ -7330,94 +3852,22 @@
return result;
}
+ /// @brief create a CBOR serialization of a given JSON value
+ /// @sa https://json.nlohmann.me/api/basic_json/to_cbor/
static void to_cbor(const basic_json& j, detail::output_adapter<std::uint8_t> o)
{
binary_writer<std::uint8_t>(o).write_cbor(j);
}
+ /// @brief create a CBOR serialization of a given JSON value
+ /// @sa https://json.nlohmann.me/api/basic_json/to_cbor/
static void to_cbor(const basic_json& j, detail::output_adapter<char> o)
{
binary_writer<char>(o).write_cbor(j);
}
- /*!
- @brief create a MessagePack serialization of a given JSON value
-
- Serializes a given JSON value @a j to a byte vector using the MessagePack
- serialization format. MessagePack is a binary serialization format which
- aims to be more compact than JSON itself, yet more efficient to parse.
-
- The library uses the following mapping from JSON values types to
- MessagePack types according to the MessagePack specification:
-
- JSON value type | value/range | MessagePack type | first byte
- --------------- | --------------------------------- | ---------------- | ----------
- null | `null` | nil | 0xC0
- boolean | `true` | true | 0xC3
- boolean | `false` | false | 0xC2
- number_integer | -9223372036854775808..-2147483649 | int64 | 0xD3
- number_integer | -2147483648..-32769 | int32 | 0xD2
- number_integer | -32768..-129 | int16 | 0xD1
- number_integer | -128..-33 | int8 | 0xD0
- number_integer | -32..-1 | negative fixint | 0xE0..0xFF
- number_integer | 0..127 | positive fixint | 0x00..0x7F
- number_integer | 128..255 | uint 8 | 0xCC
- number_integer | 256..65535 | uint 16 | 0xCD
- number_integer | 65536..4294967295 | uint 32 | 0xCE
- number_integer | 4294967296..18446744073709551615 | uint 64 | 0xCF
- number_unsigned | 0..127 | positive fixint | 0x00..0x7F
- number_unsigned | 128..255 | uint 8 | 0xCC
- number_unsigned | 256..65535 | uint 16 | 0xCD
- number_unsigned | 65536..4294967295 | uint 32 | 0xCE
- number_unsigned | 4294967296..18446744073709551615 | uint 64 | 0xCF
- number_float | *any value representable by a float* | float 32 | 0xCA
- number_float | *any value NOT representable by a float* | float 64 | 0xCB
- string | *length*: 0..31 | fixstr | 0xA0..0xBF
- string | *length*: 32..255 | str 8 | 0xD9
- string | *length*: 256..65535 | str 16 | 0xDA
- string | *length*: 65536..4294967295 | str 32 | 0xDB
- array | *size*: 0..15 | fixarray | 0x90..0x9F
- array | *size*: 16..65535 | array 16 | 0xDC
- array | *size*: 65536..4294967295 | array 32 | 0xDD
- object | *size*: 0..15 | fix map | 0x80..0x8F
- object | *size*: 16..65535 | map 16 | 0xDE
- object | *size*: 65536..4294967295 | map 32 | 0xDF
- binary | *size*: 0..255 | bin 8 | 0xC4
- binary | *size*: 256..65535 | bin 16 | 0xC5
- binary | *size*: 65536..4294967295 | bin 32 | 0xC6
-
- @note The mapping is **complete** in the sense that any JSON value type
- can be converted to a MessagePack value.
-
- @note The following values can **not** be converted to a MessagePack value:
- - strings with more than 4294967295 bytes
- - byte strings with more than 4294967295 bytes
- - arrays with more than 4294967295 elements
- - objects with more than 4294967295 elements
-
- @note Any MessagePack output created @ref to_msgpack can be successfully
- parsed by @ref from_msgpack.
-
- @note If NaN or Infinity are stored inside a JSON number, they are
- serialized properly. This behavior differs from the @ref dump()
- function which serializes NaN or Infinity to `null`.
-
- @param[in] j JSON value to serialize
- @return MessagePack serialization as byte vector
-
- @complexity Linear in the size of the JSON value @a j.
-
- @liveexample{The example shows the serialization of a JSON value to a byte
- vector in MessagePack format.,to_msgpack}
-
- @sa http://msgpack.org
- @sa see @ref from_msgpack for the analogous deserialization
- @sa see @ref to_cbor(const basic_json& for the related CBOR format
- @sa see @ref to_ubjson(const basic_json&, const bool, const bool) for the
- related UBJSON format
-
- @since version 2.0.9
- */
+ /// @brief create a MessagePack serialization of a given JSON value
+ /// @sa https://json.nlohmann.me/api/basic_json/to_msgpack/
static std::vector<std::uint8_t> to_msgpack(const basic_json& j)
{
std::vector<std::uint8_t> result;
@@ -7425,102 +3875,22 @@
return result;
}
+ /// @brief create a MessagePack serialization of a given JSON value
+ /// @sa https://json.nlohmann.me/api/basic_json/to_msgpack/
static void to_msgpack(const basic_json& j, detail::output_adapter<std::uint8_t> o)
{
binary_writer<std::uint8_t>(o).write_msgpack(j);
}
+ /// @brief create a MessagePack serialization of a given JSON value
+ /// @sa https://json.nlohmann.me/api/basic_json/to_msgpack/
static void to_msgpack(const basic_json& j, detail::output_adapter<char> o)
{
binary_writer<char>(o).write_msgpack(j);
}
- /*!
- @brief create a UBJSON serialization of a given JSON value
-
- Serializes a given JSON value @a j to a byte vector using the UBJSON
- (Universal Binary JSON) serialization format. UBJSON aims to be more compact
- than JSON itself, yet more efficient to parse.
-
- The library uses the following mapping from JSON values types to
- UBJSON types according to the UBJSON specification:
-
- JSON value type | value/range | UBJSON type | marker
- --------------- | --------------------------------- | ----------- | ------
- null | `null` | null | `Z`
- boolean | `true` | true | `T`
- boolean | `false` | false | `F`
- number_integer | -9223372036854775808..-2147483649 | int64 | `L`
- number_integer | -2147483648..-32769 | int32 | `l`
- number_integer | -32768..-129 | int16 | `I`
- number_integer | -128..127 | int8 | `i`
- number_integer | 128..255 | uint8 | `U`
- number_integer | 256..32767 | int16 | `I`
- number_integer | 32768..2147483647 | int32 | `l`
- number_integer | 2147483648..9223372036854775807 | int64 | `L`
- number_unsigned | 0..127 | int8 | `i`
- number_unsigned | 128..255 | uint8 | `U`
- number_unsigned | 256..32767 | int16 | `I`
- number_unsigned | 32768..2147483647 | int32 | `l`
- number_unsigned | 2147483648..9223372036854775807 | int64 | `L`
- number_unsigned | 2147483649..18446744073709551615 | high-precision | `H`
- number_float | *any value* | float64 | `D`
- string | *with shortest length indicator* | string | `S`
- array | *see notes on optimized format* | array | `[`
- object | *see notes on optimized format* | map | `{`
-
- @note The mapping is **complete** in the sense that any JSON value type
- can be converted to a UBJSON value.
-
- @note The following values can **not** be converted to a UBJSON value:
- - strings with more than 9223372036854775807 bytes (theoretical)
-
- @note The following markers are not used in the conversion:
- - `Z`: no-op values are not created.
- - `C`: single-byte strings are serialized with `S` markers.
-
- @note Any UBJSON output created @ref to_ubjson can be successfully parsed
- by @ref from_ubjson.
-
- @note If NaN or Infinity are stored inside a JSON number, they are
- serialized properly. This behavior differs from the @ref dump()
- function which serializes NaN or Infinity to `null`.
-
- @note The optimized formats for containers are supported: Parameter
- @a use_size adds size information to the beginning of a container and
- removes the closing marker. Parameter @a use_type further checks
- whether all elements of a container have the same type and adds the
- type marker to the beginning of the container. The @a use_type
- parameter must only be used together with @a use_size = true. Note
- that @a use_size = true alone may result in larger representations -
- the benefit of this parameter is that the receiving side is
- immediately informed on the number of elements of the container.
-
- @note If the JSON data contains the binary type, the value stored is a list
- of integers, as suggested by the UBJSON documentation. In particular,
- this means that serialization and the deserialization of a JSON
- containing binary values into UBJSON and back will result in a
- different JSON object.
-
- @param[in] j JSON value to serialize
- @param[in] use_size whether to add size annotations to container types
- @param[in] use_type whether to add type annotations to container types
- (must be combined with @a use_size = true)
- @return UBJSON serialization as byte vector
-
- @complexity Linear in the size of the JSON value @a j.
-
- @liveexample{The example shows the serialization of a JSON value to a byte
- vector in UBJSON format.,to_ubjson}
-
- @sa http://ubjson.org
- @sa see @ref from_ubjson(InputType&&, const bool, const bool) for the
- analogous deserialization
- @sa see @ref to_cbor(const basic_json& for the related CBOR format
- @sa see @ref to_msgpack(const basic_json&) for the related MessagePack format
-
- @since version 3.1.0
- */
+ /// @brief create a UBJSON serialization of a given JSON value
+ /// @sa https://json.nlohmann.me/api/basic_json/to_ubjson/
static std::vector<std::uint8_t> to_ubjson(const basic_json& j,
const bool use_size = false,
const bool use_type = false)
@@ -7530,75 +3900,24 @@
return result;
}
+ /// @brief create a UBJSON serialization of a given JSON value
+ /// @sa https://json.nlohmann.me/api/basic_json/to_ubjson/
static void to_ubjson(const basic_json& j, detail::output_adapter<std::uint8_t> o,
const bool use_size = false, const bool use_type = false)
{
binary_writer<std::uint8_t>(o).write_ubjson(j, use_size, use_type);
}
+ /// @brief create a UBJSON serialization of a given JSON value
+ /// @sa https://json.nlohmann.me/api/basic_json/to_ubjson/
static void to_ubjson(const basic_json& j, detail::output_adapter<char> o,
const bool use_size = false, const bool use_type = false)
{
binary_writer<char>(o).write_ubjson(j, use_size, use_type);
}
-
- /*!
- @brief Serializes the given JSON object `j` to BSON and returns a vector
- containing the corresponding BSON-representation.
-
- BSON (Binary JSON) is a binary format in which zero or more ordered key/value pairs are
- stored as a single entity (a so-called document).
-
- The library uses the following mapping from JSON values types to BSON types:
-
- JSON value type | value/range | BSON type | marker
- --------------- | --------------------------------- | ----------- | ------
- null | `null` | null | 0x0A
- boolean | `true`, `false` | boolean | 0x08
- number_integer | -9223372036854775808..-2147483649 | int64 | 0x12
- number_integer | -2147483648..2147483647 | int32 | 0x10
- number_integer | 2147483648..9223372036854775807 | int64 | 0x12
- number_unsigned | 0..2147483647 | int32 | 0x10
- number_unsigned | 2147483648..9223372036854775807 | int64 | 0x12
- number_unsigned | 9223372036854775808..18446744073709551615| -- | --
- number_float | *any value* | double | 0x01
- string | *any value* | string | 0x02
- array | *any value* | document | 0x04
- object | *any value* | document | 0x03
- binary | *any value* | binary | 0x05
-
- @warning The mapping is **incomplete**, since only JSON-objects (and things
- contained therein) can be serialized to BSON.
- Also, integers larger than 9223372036854775807 cannot be serialized to BSON,
- and the keys may not contain U+0000, since they are serialized a
- zero-terminated c-strings.
-
- @throw out_of_range.407 if `j.is_number_unsigned() && j.get<std::uint64_t>() > 9223372036854775807`
- @throw out_of_range.409 if a key in `j` contains a NULL (U+0000)
- @throw type_error.317 if `!j.is_object()`
-
- @pre The input `j` is required to be an object: `j.is_object() == true`.
-
- @note Any BSON output created via @ref to_bson can be successfully parsed
- by @ref from_bson.
-
- @param[in] j JSON value to serialize
- @return BSON serialization as byte vector
-
- @complexity Linear in the size of the JSON value @a j.
-
- @liveexample{The example shows the serialization of a JSON value to a byte
- vector in BSON format.,to_bson}
-
- @sa http://bsonspec.org/spec.html
- @sa see @ref from_bson(detail::input_adapter&&, const bool strict) for the
- analogous deserialization
- @sa see @ref to_ubjson(const basic_json&, const bool, const bool) for the
- related UBJSON format
- @sa see @ref to_cbor(const basic_json&) for the related CBOR format
- @sa see @ref to_msgpack(const basic_json&) for the related MessagePack format
- */
+ /// @brief create a BSON serialization of a given JSON value
+ /// @sa https://json.nlohmann.me/api/basic_json/to_bson/
static std::vector<std::uint8_t> to_bson(const basic_json& j)
{
std::vector<std::uint8_t> result;
@@ -7606,130 +3925,22 @@
return result;
}
- /*!
- @brief Serializes the given JSON object `j` to BSON and forwards the
- corresponding BSON-representation to the given output_adapter `o`.
- @param j The JSON object to convert to BSON.
- @param o The output adapter that receives the binary BSON representation.
- @pre The input `j` shall be an object: `j.is_object() == true`
- @sa see @ref to_bson(const basic_json&)
- */
+ /// @brief create a BSON serialization of a given JSON value
+ /// @sa https://json.nlohmann.me/api/basic_json/to_bson/
static void to_bson(const basic_json& j, detail::output_adapter<std::uint8_t> o)
{
binary_writer<std::uint8_t>(o).write_bson(j);
}
- /*!
- @copydoc to_bson(const basic_json&, detail::output_adapter<std::uint8_t>)
- */
+ /// @brief create a BSON serialization of a given JSON value
+ /// @sa https://json.nlohmann.me/api/basic_json/to_bson/
static void to_bson(const basic_json& j, detail::output_adapter<char> o)
{
binary_writer<char>(o).write_bson(j);
}
-
- /*!
- @brief create a JSON value from an input in CBOR format
-
- Deserializes a given input @a i to a JSON value using the CBOR (Concise
- Binary Object Representation) serialization format.
-
- The library maps CBOR types to JSON value types as follows:
-
- CBOR type | JSON value type | first byte
- ---------------------- | --------------- | ----------
- Integer | number_unsigned | 0x00..0x17
- Unsigned integer | number_unsigned | 0x18
- Unsigned integer | number_unsigned | 0x19
- Unsigned integer | number_unsigned | 0x1A
- Unsigned integer | number_unsigned | 0x1B
- Negative integer | number_integer | 0x20..0x37
- Negative integer | number_integer | 0x38
- Negative integer | number_integer | 0x39
- Negative integer | number_integer | 0x3A
- Negative integer | number_integer | 0x3B
- Byte string | binary | 0x40..0x57
- Byte string | binary | 0x58
- Byte string | binary | 0x59
- Byte string | binary | 0x5A
- Byte string | binary | 0x5B
- UTF-8 string | string | 0x60..0x77
- UTF-8 string | string | 0x78
- UTF-8 string | string | 0x79
- UTF-8 string | string | 0x7A
- UTF-8 string | string | 0x7B
- UTF-8 string | string | 0x7F
- array | array | 0x80..0x97
- array | array | 0x98
- array | array | 0x99
- array | array | 0x9A
- array | array | 0x9B
- array | array | 0x9F
- map | object | 0xA0..0xB7
- map | object | 0xB8
- map | object | 0xB9
- map | object | 0xBA
- map | object | 0xBB
- map | object | 0xBF
- False | `false` | 0xF4
- True | `true` | 0xF5
- Null | `null` | 0xF6
- Half-Precision Float | number_float | 0xF9
- Single-Precision Float | number_float | 0xFA
- Double-Precision Float | number_float | 0xFB
-
- @warning The mapping is **incomplete** in the sense that not all CBOR
- types can be converted to a JSON value. The following CBOR types
- are not supported and will yield parse errors (parse_error.112):
- - date/time (0xC0..0xC1)
- - bignum (0xC2..0xC3)
- - decimal fraction (0xC4)
- - bigfloat (0xC5)
- - expected conversions (0xD5..0xD7)
- - simple values (0xE0..0xF3, 0xF8)
- - undefined (0xF7)
-
- @warning CBOR allows map keys of any type, whereas JSON only allows
- strings as keys in object values. Therefore, CBOR maps with keys
- other than UTF-8 strings are rejected (parse_error.113).
-
- @note Any CBOR output created @ref to_cbor can be successfully parsed by
- @ref from_cbor.
-
- @param[in] i an input in CBOR format convertible to an input adapter
- @param[in] strict whether to expect the input to be consumed until EOF
- (true by default)
- @param[in] allow_exceptions whether to throw exceptions in case of a
- parse error (optional, true by default)
- @param[in] tag_handler how to treat CBOR tags (optional, error by default)
-
- @return deserialized JSON value; in case of a parse error and
- @a allow_exceptions set to `false`, the return value will be
- value_t::discarded.
-
- @throw parse_error.110 if the given input ends prematurely or the end of
- file was not reached when @a strict was set to true
- @throw parse_error.112 if unsupported features from CBOR were
- used in the given input @a v or if the input is not valid CBOR
- @throw parse_error.113 if a string was expected as map key, but not found
-
- @complexity Linear in the size of the input @a i.
-
- @liveexample{The example shows the deserialization of a byte vector in CBOR
- format to a JSON value.,from_cbor}
-
- @sa http://cbor.io
- @sa see @ref to_cbor(const basic_json&) for the analogous serialization
- @sa see @ref from_msgpack(InputType&&, const bool, const bool) for the
- related MessagePack format
- @sa see @ref from_ubjson(InputType&&, const bool, const bool) for the
- related UBJSON format
-
- @since version 2.0.9; parameter @a start_index since 2.1.1; changed to
- consume input adapters, removed start_index parameter, and added
- @a strict parameter since 3.0.0; added @a allow_exceptions parameter
- since 3.2.0; added @a tag_handler parameter since 3.9.0.
- */
+ /// @brief create a JSON value from an input in CBOR format
+ /// @sa https://json.nlohmann.me/api/basic_json/from_cbor/
template<typename InputType>
JSON_HEDLEY_WARN_UNUSED_RESULT
static basic_json from_cbor(InputType&& i,
@@ -7744,9 +3955,8 @@
return res ? result : basic_json(value_t::discarded);
}
- /*!
- @copydoc from_cbor(InputType&&, const bool, const bool, const cbor_tag_handler_t)
- */
+ /// @brief create a JSON value from an input in CBOR format
+ /// @sa https://json.nlohmann.me/api/basic_json/from_cbor/
template<typename IteratorType>
JSON_HEDLEY_WARN_UNUSED_RESULT
static basic_json from_cbor(IteratorType first, IteratorType last,
@@ -7788,92 +3998,8 @@
return res ? result : basic_json(value_t::discarded);
}
- /*!
- @brief create a JSON value from an input in MessagePack format
-
- Deserializes a given input @a i to a JSON value using the MessagePack
- serialization format.
-
- The library maps MessagePack types to JSON value types as follows:
-
- MessagePack type | JSON value type | first byte
- ---------------- | --------------- | ----------
- positive fixint | number_unsigned | 0x00..0x7F
- fixmap | object | 0x80..0x8F
- fixarray | array | 0x90..0x9F
- fixstr | string | 0xA0..0xBF
- nil | `null` | 0xC0
- false | `false` | 0xC2
- true | `true` | 0xC3
- float 32 | number_float | 0xCA
- float 64 | number_float | 0xCB
- uint 8 | number_unsigned | 0xCC
- uint 16 | number_unsigned | 0xCD
- uint 32 | number_unsigned | 0xCE
- uint 64 | number_unsigned | 0xCF
- int 8 | number_integer | 0xD0
- int 16 | number_integer | 0xD1
- int 32 | number_integer | 0xD2
- int 64 | number_integer | 0xD3
- str 8 | string | 0xD9
- str 16 | string | 0xDA
- str 32 | string | 0xDB
- array 16 | array | 0xDC
- array 32 | array | 0xDD
- map 16 | object | 0xDE
- map 32 | object | 0xDF
- bin 8 | binary | 0xC4
- bin 16 | binary | 0xC5
- bin 32 | binary | 0xC6
- ext 8 | binary | 0xC7
- ext 16 | binary | 0xC8
- ext 32 | binary | 0xC9
- fixext 1 | binary | 0xD4
- fixext 2 | binary | 0xD5
- fixext 4 | binary | 0xD6
- fixext 8 | binary | 0xD7
- fixext 16 | binary | 0xD8
- negative fixint | number_integer | 0xE0-0xFF
-
- @note Any MessagePack output created @ref to_msgpack can be successfully
- parsed by @ref from_msgpack.
-
- @param[in] i an input in MessagePack format convertible to an input
- adapter
- @param[in] strict whether to expect the input to be consumed until EOF
- (true by default)
- @param[in] allow_exceptions whether to throw exceptions in case of a
- parse error (optional, true by default)
-
- @return deserialized JSON value; in case of a parse error and
- @a allow_exceptions set to `false`, the return value will be
- value_t::discarded.
-
- @throw parse_error.110 if the given input ends prematurely or the end of
- file was not reached when @a strict was set to true
- @throw parse_error.112 if unsupported features from MessagePack were
- used in the given input @a i or if the input is not valid MessagePack
- @throw parse_error.113 if a string was expected as map key, but not found
-
- @complexity Linear in the size of the input @a i.
-
- @liveexample{The example shows the deserialization of a byte vector in
- MessagePack format to a JSON value.,from_msgpack}
-
- @sa http://msgpack.org
- @sa see @ref to_msgpack(const basic_json&) for the analogous serialization
- @sa see @ref from_cbor(InputType&&, const bool, const bool, const cbor_tag_handler_t) for the
- related CBOR format
- @sa see @ref from_ubjson(InputType&&, const bool, const bool) for
- the related UBJSON format
- @sa see @ref from_bson(InputType&&, const bool, const bool) for
- the related BSON format
-
- @since version 2.0.9; parameter @a start_index since 2.1.1; changed to
- consume input adapters, removed start_index parameter, and added
- @a strict parameter since 3.0.0; added @a allow_exceptions parameter
- since 3.2.0
- */
+ /// @brief create a JSON value from an input in MessagePack format
+ /// @sa https://json.nlohmann.me/api/basic_json/from_msgpack/
template<typename InputType>
JSON_HEDLEY_WARN_UNUSED_RESULT
static basic_json from_msgpack(InputType&& i,
@@ -7887,9 +4013,8 @@
return res ? result : basic_json(value_t::discarded);
}
- /*!
- @copydoc from_msgpack(InputType&&, const bool, const bool)
- */
+ /// @brief create a JSON value from an input in MessagePack format
+ /// @sa https://json.nlohmann.me/api/basic_json/from_msgpack/
template<typename IteratorType>
JSON_HEDLEY_WARN_UNUSED_RESULT
static basic_json from_msgpack(IteratorType first, IteratorType last,
@@ -7903,7 +4028,6 @@
return res ? result : basic_json(value_t::discarded);
}
-
template<typename T>
JSON_HEDLEY_WARN_UNUSED_RESULT
JSON_HEDLEY_DEPRECATED_FOR(3.8.0, from_msgpack(ptr, ptr + len))
@@ -7928,69 +4052,8 @@
return res ? result : basic_json(value_t::discarded);
}
-
- /*!
- @brief create a JSON value from an input in UBJSON format
-
- Deserializes a given input @a i to a JSON value using the UBJSON (Universal
- Binary JSON) serialization format.
-
- The library maps UBJSON types to JSON value types as follows:
-
- UBJSON type | JSON value type | marker
- ----------- | --------------------------------------- | ------
- no-op | *no value, next value is read* | `N`
- null | `null` | `Z`
- false | `false` | `F`
- true | `true` | `T`
- float32 | number_float | `d`
- float64 | number_float | `D`
- uint8 | number_unsigned | `U`
- int8 | number_integer | `i`
- int16 | number_integer | `I`
- int32 | number_integer | `l`
- int64 | number_integer | `L`
- high-precision number | number_integer, number_unsigned, or number_float - depends on number string | 'H'
- string | string | `S`
- char | string | `C`
- array | array (optimized values are supported) | `[`
- object | object (optimized values are supported) | `{`
-
- @note The mapping is **complete** in the sense that any UBJSON value can
- be converted to a JSON value.
-
- @param[in] i an input in UBJSON format convertible to an input adapter
- @param[in] strict whether to expect the input to be consumed until EOF
- (true by default)
- @param[in] allow_exceptions whether to throw exceptions in case of a
- parse error (optional, true by default)
-
- @return deserialized JSON value; in case of a parse error and
- @a allow_exceptions set to `false`, the return value will be
- value_t::discarded.
-
- @throw parse_error.110 if the given input ends prematurely or the end of
- file was not reached when @a strict was set to true
- @throw parse_error.112 if a parse error occurs
- @throw parse_error.113 if a string could not be parsed successfully
-
- @complexity Linear in the size of the input @a i.
-
- @liveexample{The example shows the deserialization of a byte vector in
- UBJSON format to a JSON value.,from_ubjson}
-
- @sa http://ubjson.org
- @sa see @ref to_ubjson(const basic_json&, const bool, const bool) for the
- analogous serialization
- @sa see @ref from_cbor(InputType&&, const bool, const bool, const cbor_tag_handler_t) for the
- related CBOR format
- @sa see @ref from_msgpack(InputType&&, const bool, const bool) for
- the related MessagePack format
- @sa see @ref from_bson(InputType&&, const bool, const bool) for
- the related BSON format
-
- @since version 3.1.0; added @a allow_exceptions parameter since 3.2.0
- */
+ /// @brief create a JSON value from an input in UBJSON format
+ /// @sa https://json.nlohmann.me/api/basic_json/from_ubjson/
template<typename InputType>
JSON_HEDLEY_WARN_UNUSED_RESULT
static basic_json from_ubjson(InputType&& i,
@@ -8004,9 +4067,8 @@
return res ? result : basic_json(value_t::discarded);
}
- /*!
- @copydoc from_ubjson(InputType&&, const bool, const bool)
- */
+ /// @brief create a JSON value from an input in UBJSON format
+ /// @sa https://json.nlohmann.me/api/basic_json/from_ubjson/
template<typename IteratorType>
JSON_HEDLEY_WARN_UNUSED_RESULT
static basic_json from_ubjson(IteratorType first, IteratorType last,
@@ -8044,67 +4106,8 @@
return res ? result : basic_json(value_t::discarded);
}
-
- /*!
- @brief Create a JSON value from an input in BSON format
-
- Deserializes a given input @a i to a JSON value using the BSON (Binary JSON)
- serialization format.
-
- The library maps BSON record types to JSON value types as follows:
-
- BSON type | BSON marker byte | JSON value type
- --------------- | ---------------- | ---------------------------
- double | 0x01 | number_float
- string | 0x02 | string
- document | 0x03 | object
- array | 0x04 | array
- binary | 0x05 | binary
- undefined | 0x06 | still unsupported
- ObjectId | 0x07 | still unsupported
- boolean | 0x08 | boolean
- UTC Date-Time | 0x09 | still unsupported
- null | 0x0A | null
- Regular Expr. | 0x0B | still unsupported
- DB Pointer | 0x0C | still unsupported
- JavaScript Code | 0x0D | still unsupported
- Symbol | 0x0E | still unsupported
- JavaScript Code | 0x0F | still unsupported
- int32 | 0x10 | number_integer
- Timestamp | 0x11 | still unsupported
- 128-bit decimal float | 0x13 | still unsupported
- Max Key | 0x7F | still unsupported
- Min Key | 0xFF | still unsupported
-
- @warning The mapping is **incomplete**. The unsupported mappings
- are indicated in the table above.
-
- @param[in] i an input in BSON format convertible to an input adapter
- @param[in] strict whether to expect the input to be consumed until EOF
- (true by default)
- @param[in] allow_exceptions whether to throw exceptions in case of a
- parse error (optional, true by default)
-
- @return deserialized JSON value; in case of a parse error and
- @a allow_exceptions set to `false`, the return value will be
- value_t::discarded.
-
- @throw parse_error.114 if an unsupported BSON record type is encountered
-
- @complexity Linear in the size of the input @a i.
-
- @liveexample{The example shows the deserialization of a byte vector in
- BSON format to a JSON value.,from_bson}
-
- @sa http://bsonspec.org/spec.html
- @sa see @ref to_bson(const basic_json&) for the analogous serialization
- @sa see @ref from_cbor(InputType&&, const bool, const bool, const cbor_tag_handler_t) for the
- related CBOR format
- @sa see @ref from_msgpack(InputType&&, const bool, const bool) for
- the related MessagePack format
- @sa see @ref from_ubjson(InputType&&, const bool, const bool) for the
- related UBJSON format
- */
+ /// @brief create a JSON value from an input in BSON format
+ /// @sa https://json.nlohmann.me/api/basic_json/from_bson/
template<typename InputType>
JSON_HEDLEY_WARN_UNUSED_RESULT
static basic_json from_bson(InputType&& i,
@@ -8118,9 +4121,8 @@
return res ? result : basic_json(value_t::discarded);
}
- /*!
- @copydoc from_bson(InputType&&, const bool, const bool)
- */
+ /// @brief create a JSON value from an input in BSON format
+ /// @sa https://json.nlohmann.me/api/basic_json/from_bson/
template<typename IteratorType>
JSON_HEDLEY_WARN_UNUSED_RESULT
static basic_json from_bson(IteratorType first, IteratorType last,
@@ -8166,180 +4168,36 @@
/// @name JSON Pointer functions
/// @{
- /*!
- @brief access specified element via JSON Pointer
-
- Uses a JSON pointer to retrieve a reference to the respective JSON value.
- No bound checking is performed. Similar to @ref operator[](const typename
- object_t::key_type&), `null` values are created in arrays and objects if
- necessary.
-
- In particular:
- - If the JSON pointer points to an object key that does not exist, it
- is created an filled with a `null` value before a reference to it
- is returned.
- - If the JSON pointer points to an array index that does not exist, it
- is created an filled with a `null` value before a reference to it
- is returned. All indices between the current maximum and the given
- index are also filled with `null`.
- - The special value `-` is treated as a synonym for the index past the
- end.
-
- @param[in] ptr a JSON pointer
-
- @return reference to the element pointed to by @a ptr
-
- @complexity Constant.
-
- @throw parse_error.106 if an array index begins with '0'
- @throw parse_error.109 if an array index was not a number
- @throw out_of_range.404 if the JSON pointer can not be resolved
-
- @liveexample{The behavior is shown in the example.,operatorjson_pointer}
-
- @since version 2.0.0
- */
+ /// @brief access specified element via JSON Pointer
+ /// @sa https://json.nlohmann.me/api/basic_json/operator%5B%5D/
reference operator[](const json_pointer& ptr)
{
return ptr.get_unchecked(this);
}
- /*!
- @brief access specified element via JSON Pointer
-
- Uses a JSON pointer to retrieve a reference to the respective JSON value.
- No bound checking is performed. The function does not change the JSON
- value; no `null` values are created. In particular, the special value
- `-` yields an exception.
-
- @param[in] ptr JSON pointer to the desired element
-
- @return const reference to the element pointed to by @a ptr
-
- @complexity Constant.
-
- @throw parse_error.106 if an array index begins with '0'
- @throw parse_error.109 if an array index was not a number
- @throw out_of_range.402 if the array index '-' is used
- @throw out_of_range.404 if the JSON pointer can not be resolved
-
- @liveexample{The behavior is shown in the example.,operatorjson_pointer_const}
-
- @since version 2.0.0
- */
+ /// @brief access specified element via JSON Pointer
+ /// @sa https://json.nlohmann.me/api/basic_json/operator%5B%5D/
const_reference operator[](const json_pointer& ptr) const
{
return ptr.get_unchecked(this);
}
- /*!
- @brief access specified element via JSON Pointer
-
- Returns a reference to the element at with specified JSON pointer @a ptr,
- with bounds checking.
-
- @param[in] ptr JSON pointer to the desired element
-
- @return reference to the element pointed to by @a ptr
-
- @throw parse_error.106 if an array index in the passed JSON pointer @a ptr
- begins with '0'. See example below.
-
- @throw parse_error.109 if an array index in the passed JSON pointer @a ptr
- is not a number. See example below.
-
- @throw out_of_range.401 if an array index in the passed JSON pointer @a ptr
- is out of range. See example below.
-
- @throw out_of_range.402 if the array index '-' is used in the passed JSON
- pointer @a ptr. As `at` provides checked access (and no elements are
- implicitly inserted), the index '-' is always invalid. See example below.
-
- @throw out_of_range.403 if the JSON pointer describes a key of an object
- which cannot be found. See example below.
-
- @throw out_of_range.404 if the JSON pointer @a ptr can not be resolved.
- See example below.
-
- @exceptionsafety Strong guarantee: if an exception is thrown, there are no
- changes in the JSON value.
-
- @complexity Constant.
-
- @since version 2.0.0
-
- @liveexample{The behavior is shown in the example.,at_json_pointer}
- */
+ /// @brief access specified element via JSON Pointer
+ /// @sa https://json.nlohmann.me/api/basic_json/at/
reference at(const json_pointer& ptr)
{
return ptr.get_checked(this);
}
- /*!
- @brief access specified element via JSON Pointer
-
- Returns a const reference to the element at with specified JSON pointer @a
- ptr, with bounds checking.
-
- @param[in] ptr JSON pointer to the desired element
-
- @return reference to the element pointed to by @a ptr
-
- @throw parse_error.106 if an array index in the passed JSON pointer @a ptr
- begins with '0'. See example below.
-
- @throw parse_error.109 if an array index in the passed JSON pointer @a ptr
- is not a number. See example below.
-
- @throw out_of_range.401 if an array index in the passed JSON pointer @a ptr
- is out of range. See example below.
-
- @throw out_of_range.402 if the array index '-' is used in the passed JSON
- pointer @a ptr. As `at` provides checked access (and no elements are
- implicitly inserted), the index '-' is always invalid. See example below.
-
- @throw out_of_range.403 if the JSON pointer describes a key of an object
- which cannot be found. See example below.
-
- @throw out_of_range.404 if the JSON pointer @a ptr can not be resolved.
- See example below.
-
- @exceptionsafety Strong guarantee: if an exception is thrown, there are no
- changes in the JSON value.
-
- @complexity Constant.
-
- @since version 2.0.0
-
- @liveexample{The behavior is shown in the example.,at_json_pointer_const}
- */
+ /// @brief access specified element via JSON Pointer
+ /// @sa https://json.nlohmann.me/api/basic_json/at/
const_reference at(const json_pointer& ptr) const
{
return ptr.get_checked(this);
}
- /*!
- @brief return flattened JSON value
-
- The function creates a JSON object whose keys are JSON pointers (see [RFC
- 6901](https://tools.ietf.org/html/rfc6901)) and whose values are all
- primitive. The original JSON value can be restored using the @ref
- unflatten() function.
-
- @return an object that maps JSON pointers to primitive values
-
- @note Empty objects and arrays are flattened to `null` and will not be
- reconstructed correctly by the @ref unflatten() function.
-
- @complexity Linear in the size the JSON value.
-
- @liveexample{The following code shows how a JSON object is flattened to an
- object whose keys consist of JSON pointers.,flatten}
-
- @sa see @ref unflatten() for the reverse function
-
- @since version 2.0.0
- */
+ /// @brief return flattened JSON value
+ /// @sa https://json.nlohmann.me/api/basic_json/flatten/
basic_json flatten() const
{
basic_json result(value_t::object);
@@ -8347,36 +4205,8 @@
return result;
}
- /*!
- @brief unflatten a previously flattened JSON value
-
- The function restores the arbitrary nesting of a JSON value that has been
- flattened before using the @ref flatten() function. The JSON value must
- meet certain constraints:
- 1. The value must be an object.
- 2. The keys must be JSON pointers (see
- [RFC 6901](https://tools.ietf.org/html/rfc6901))
- 3. The mapped values must be primitive JSON types.
-
- @return the original JSON from a flattened version
-
- @note Empty objects and arrays are flattened by @ref flatten() to `null`
- values and can not unflattened to their original type. Apart from
- this example, for a JSON value `j`, the following is always true:
- `j == j.flatten().unflatten()`.
-
- @complexity Linear in the size the JSON value.
-
- @throw type_error.314 if value is not an object
- @throw type_error.315 if object values are not primitive
-
- @liveexample{The following code shows how a flattened JSON object is
- unflattened into the original nested JSON object.,unflatten}
-
- @sa see @ref flatten() for the reverse function
-
- @since version 2.0.0
- */
+ /// @brief unflatten a previously flattened JSON value
+ /// @sa https://json.nlohmann.me/api/basic_json/unflatten/
basic_json unflatten() const
{
return json_pointer::unflatten(*this);
@@ -8391,53 +4221,8 @@
/// @name JSON Patch functions
/// @{
- /*!
- @brief applies a JSON patch
-
- [JSON Patch](http://jsonpatch.com) defines a JSON document structure for
- expressing a sequence of operations to apply to a JSON) document. With
- this function, a JSON Patch is applied to the current JSON value by
- executing all operations from the patch.
-
- @param[in] json_patch JSON patch document
- @return patched document
-
- @note The application of a patch is atomic: Either all operations succeed
- and the patched document is returned or an exception is thrown. In
- any case, the original value is not changed: the patch is applied
- to a copy of the value.
-
- @throw parse_error.104 if the JSON patch does not consist of an array of
- objects
-
- @throw parse_error.105 if the JSON patch is malformed (e.g., mandatory
- attributes are missing); example: `"operation add must have member path"`
-
- @throw out_of_range.401 if an array index is out of range.
-
- @throw out_of_range.403 if a JSON pointer inside the patch could not be
- resolved successfully in the current JSON value; example: `"key baz not
- found"`
-
- @throw out_of_range.405 if JSON pointer has no parent ("add", "remove",
- "move")
-
- @throw other_error.501 if "test" operation was unsuccessful
-
- @complexity Linear in the size of the JSON value and the length of the
- JSON patch. As usually only a fraction of the JSON value is affected by
- the patch, the complexity can usually be neglected.
-
- @liveexample{The following code shows how a JSON patch is applied to a
- value.,patch}
-
- @sa see @ref diff -- create a JSON patch by comparing two JSON values
-
- @sa [RFC 6902 (JSON Patch)](https://tools.ietf.org/html/rfc6902)
- @sa [RFC 6901 (JSON Pointer)](https://tools.ietf.org/html/rfc6901)
-
- @since version 2.0.0
- */
+ /// @brief applies a JSON patch
+ /// @sa https://json.nlohmann.me/api/basic_json/patch/
basic_json patch(const basic_json& json_patch) const
{
// make a working copy to apply the patch to
@@ -8710,39 +4495,8 @@
return result;
}
- /*!
- @brief creates a diff as a JSON patch
-
- Creates a [JSON Patch](http://jsonpatch.com) so that value @a source can
- be changed into the value @a target by calling @ref patch function.
-
- @invariant For two JSON values @a source and @a target, the following code
- yields always `true`:
- @code {.cpp}
- source.patch(diff(source, target)) == target;
- @endcode
-
- @note Currently, only `remove`, `add`, and `replace` operations are
- generated.
-
- @param[in] source JSON value to compare from
- @param[in] target JSON value to compare against
- @param[in] path helper value to create JSON pointers
-
- @return a JSON patch to convert the @a source to @a target
-
- @complexity Linear in the lengths of @a source and @a target.
-
- @liveexample{The following code shows how a JSON patch is created as a
- diff for two JSON values.,diff}
-
- @sa see @ref patch -- apply a JSON patch
- @sa see @ref merge_patch -- apply a JSON Merge Patch
-
- @sa [RFC 6902 (JSON Patch)](https://tools.ietf.org/html/rfc6902)
-
- @since version 2.0.0
- */
+ /// @brief creates a diff as a JSON patch
+ /// @sa https://json.nlohmann.me/api/basic_json/diff/
JSON_HEDLEY_WARN_UNUSED_RESULT
static basic_json diff(const basic_json& source, const basic_json& target,
const std::string& path = "")
@@ -8780,7 +4534,7 @@
++i;
}
- // i now reached the end of at least one array
+ // We now reached the end of at least one array
// in a second pass, traverse the remaining elements
// remove my remaining elements
@@ -8885,48 +4639,8 @@
/// @name JSON Merge Patch functions
/// @{
- /*!
- @brief applies a JSON Merge Patch
-
- The merge patch format is primarily intended for use with the HTTP PATCH
- method as a means of describing a set of modifications to a target
- resource's content. This function applies a merge patch to the current
- JSON value.
-
- The function implements the following algorithm from Section 2 of
- [RFC 7396 (JSON Merge Patch)](https://tools.ietf.org/html/rfc7396):
-
- ```
- define MergePatch(Target, Patch):
- if Patch is an Object:
- if Target is not an Object:
- Target = {} // Ignore the contents and set it to an empty Object
- for each Name/Value pair in Patch:
- if Value is null:
- if Name exists in Target:
- remove the Name/Value pair from Target
- else:
- Target[Name] = MergePatch(Target[Name], Value)
- return Target
- else:
- return Patch
- ```
-
- Thereby, `Target` is the current object; that is, the patch is applied to
- the current value.
-
- @param[in] apply_patch the patch to apply
-
- @complexity Linear in the lengths of @a patch.
-
- @liveexample{The following code shows how a JSON Merge Patch is applied to
- a JSON document.,merge_patch}
-
- @sa see @ref patch -- apply a JSON patch
- @sa [RFC 7396 (JSON Merge Patch)](https://tools.ietf.org/html/rfc7396)
-
- @since version 3.0.0
- */
+ /// @brief applies a JSON Merge Patch
+ /// @sa https://json.nlohmann.me/api/basic_json/merge_patch/
void merge_patch(const basic_json& apply_patch)
{
if (apply_patch.is_object())
@@ -8956,50 +4670,37 @@
/// @}
};
-/*!
-@brief user-defined to_string function for JSON values
-
-This function implements a user-defined to_string for JSON objects.
-
-@param[in] j a JSON object
-@return a std::string object
-*/
-
+/// @brief user-defined to_string function for JSON values
+/// @sa https://json.nlohmann.me/api/basic_json/to_string/
NLOHMANN_BASIC_JSON_TPL_DECLARATION
std::string to_string(const NLOHMANN_BASIC_JSON_TPL& j)
{
return j.dump();
}
+
} // namespace nlohmann
///////////////////////
// nonmember support //
///////////////////////
-// specialization of std::swap, and std::hash
-namespace std
+namespace std // NOLINT(cert-dcl58-cpp)
{
-/// hash value for JSON objects
-template<>
-struct hash<nlohmann::json>
+/// @brief hash value for JSON objects
+/// @sa https://json.nlohmann.me/api/basic_json/std_hash/
+NLOHMANN_BASIC_JSON_TPL_DECLARATION
+struct hash<nlohmann::NLOHMANN_BASIC_JSON_TPL>
{
- /*!
- @brief return a hash value for a JSON object
-
- @since version 1.0.0
- */
- std::size_t operator()(const nlohmann::json& j) const
+ std::size_t operator()(const nlohmann::NLOHMANN_BASIC_JSON_TPL& j) const
{
return nlohmann::detail::hash(j);
}
};
-/// specialization for std::less<value_t>
-/// @note: do not remove the space after '<',
-/// see https://github.com/nlohmann/json/pull/679
+// specialization for std::less<value_t>
template<>
-struct less<::nlohmann::detail::value_t>
+struct less< ::nlohmann::detail::value_t> // do not remove the space after '<', see https://github.com/nlohmann/json/pull/679
{
/*!
@brief compare two value_t enum values
@@ -9015,16 +4716,12 @@
// C++20 prohibit function specialization in the std namespace.
#ifndef JSON_HAS_CPP_20
-/*!
-@brief exchanges the values of two JSON objects
-
-@since version 1.0.0
-*/
-template<>
-inline void swap<nlohmann::json>(nlohmann::json& j1, nlohmann::json& j2) noexcept( // NOLINT(readability-inconsistent-declaration-parameter-name)
- is_nothrow_move_constructible<nlohmann::json>::value&& // NOLINT(misc-redundant-expression)
- is_nothrow_move_assignable<nlohmann::json>::value
- )
+/// @brief exchanges the values of two JSON objects
+/// @sa https://json.nlohmann.me/api/basic_json/std_swap/
+NLOHMANN_BASIC_JSON_TPL_DECLARATION
+inline void swap(nlohmann::NLOHMANN_BASIC_JSON_TPL& j1, nlohmann::NLOHMANN_BASIC_JSON_TPL& j2) noexcept( // NOLINT(readability-inconsistent-declaration-parameter-name)
+ is_nothrow_move_constructible<nlohmann::NLOHMANN_BASIC_JSON_TPL>::value&& // NOLINT(misc-redundant-expression)
+ is_nothrow_move_assignable<nlohmann::NLOHMANN_BASIC_JSON_TPL>::value)
{
j1.swap(j2);
}
@@ -9033,38 +4730,16 @@
} // namespace std
-/*!
-@brief user-defined string literal for JSON values
-
-This operator implements a user-defined string literal for JSON objects. It
-can be used by adding `"_json"` to a string literal and returns a JSON object
-if no parse error occurred.
-
-@param[in] s a string representation of a JSON object
-@param[in] n the length of string @a s
-@return a JSON object
-
-@since version 1.0.0
-*/
+/// @brief user-defined string literal for JSON values
+/// @sa https://json.nlohmann.me/api/basic_json/operator_literal_json/
JSON_HEDLEY_NON_NULL(1)
inline nlohmann::json operator "" _json(const char* s, std::size_t n)
{
return nlohmann::json::parse(s, s + n);
}
-/*!
-@brief user-defined string literal for JSON pointer
-
-This operator implements a user-defined string literal for JSON Pointers. It
-can be used by adding `"_json_pointer"` to a string literal and returns a JSON pointer
-object if no parse error occurred.
-
-@param[in] s a string representation of a JSON Pointer
-@param[in] n the length of string @a s
-@return a JSON pointer object
-
-@since version 2.0.0
-*/
+/// @brief user-defined string literal for JSON pointer
+/// @sa https://json.nlohmann.me/api/basic_json/operator_literal_json_pointer/
JSON_HEDLEY_NON_NULL(1)
inline nlohmann::json::json_pointer operator "" _json_pointer(const char* s, std::size_t n)
{
diff --git a/include/nlohmann/json_fwd.hpp b/include/nlohmann/json_fwd.hpp
index 332227c..2d5ba38 100644
--- a/include/nlohmann/json_fwd.hpp
+++ b/include/nlohmann/json_fwd.hpp
@@ -24,6 +24,8 @@
template<typename T = void, typename SFINAE = void>
struct adl_serializer;
+/// a class to store JSON values
+/// @sa https://json.nlohmann.me/api/basic_json/
template<template<typename U, typename V, typename... Args> class ObjectType =
std::map,
template<typename U, typename... Args> class ArrayType = std::vector,
@@ -37,40 +39,24 @@
class BinaryType = std::vector<std::uint8_t>>
class basic_json;
-/*!
-@brief JSON Pointer
-
-A JSON pointer defines a string syntax for identifying a specific value
-within a JSON document. It can be used with functions `at` and
-`operator[]`. Furthermore, JSON pointers are the base for JSON patches.
-
-@sa [RFC 6901](https://tools.ietf.org/html/rfc6901)
-
-@since version 2.0.0
-*/
+/// @brief JSON Pointer defines a string syntax for identifying a specific value within a JSON document
+/// @sa https://json.nlohmann.me/api/json_pointer/
template<typename BasicJsonType>
class json_pointer;
/*!
-@brief default JSON class
-
-This type is the default specialization of the @ref basic_json class which
-uses the standard template types.
-
-@since version 1.0.0
+@brief default specialization
+@sa https://json.nlohmann.me/api/json/
*/
using json = basic_json<>;
+/// @brief a minimal map-like container that preserves insertion order
+/// @sa https://json.nlohmann.me/api/ordered_map/
template<class Key, class T, class IgnoredLess, class Allocator>
struct ordered_map;
-/*!
-@brief ordered JSON class
-
-This type preserves the insertion order of object keys.
-
-@since version 3.9.0
-*/
+/// @brief specialization that maintains the insertion order of object keys
+/// @sa https://json.nlohmann.me/api/ordered_json/
using ordered_json = basic_json<nlohmann::ordered_map>;
} // namespace nlohmann
diff --git a/include/nlohmann/ordered_map.hpp b/include/nlohmann/ordered_map.hpp
index cf5f133..bfcf89a 100644
--- a/include/nlohmann/ordered_map.hpp
+++ b/include/nlohmann/ordered_map.hpp
@@ -23,10 +23,10 @@
using key_type = Key;
using mapped_type = T;
using Container = std::vector<std::pair<const Key, T>, Allocator>;
- using typename Container::iterator;
- using typename Container::const_iterator;
- using typename Container::size_type;
- using typename Container::value_type;
+ using iterator = typename Container::iterator;
+ using const_iterator = typename Container::const_iterator;
+ using size_type = typename Container::size_type;
+ using value_type = typename Container::value_type;
// Explicit constructors instead of `using Container::Container`
// otherwise older compilers choke on it (GCC <= 5.5, xcode <= 9.4)
@@ -107,16 +107,55 @@
iterator erase(iterator pos)
{
- auto it = pos;
+ return erase(pos, std::next(pos));
+ }
- // Since we cannot move const Keys, re-construct them in place
- for (auto next = it; ++next != this->end(); ++it)
+ iterator erase(iterator first, iterator last)
+ {
+ const auto elements_affected = std::distance(first, last);
+ const auto offset = std::distance(Container::begin(), first);
+
+ // This is the start situation. We need to delete elements_affected
+ // elements (3 in this example: e, f, g), and need to return an
+ // iterator past the last deleted element (h in this example).
+ // Note that offset is the distance from the start of the vector
+ // to first. We will need this later.
+
+ // [ a, b, c, d, e, f, g, h, i, j ]
+ // ^ ^
+ // first last
+
+ // Since we cannot move const Keys, we re-construct them in place.
+ // We start at first and re-construct (viz. copy) the elements from
+ // the back of the vector. Example for first iteration:
+
+ // ,--------.
+ // v | destroy e and re-construct with h
+ // [ a, b, c, d, e, f, g, h, i, j ]
+ // ^ ^
+ // it it + elements_affected
+
+ for (auto it = first; std::next(it, elements_affected) != Container::end(); ++it)
{
- it->~value_type(); // Destroy but keep allocation
- new (&*it) value_type{std::move(*next)};
+ it->~value_type(); // destroy but keep allocation
+ new (&*it) value_type{std::move(*std::next(it, elements_affected))}; // "move" next element to it
}
- Container::pop_back();
- return pos;
+
+ // [ a, b, c, d, h, i, j, h, i, j ]
+ // ^ ^
+ // first last
+
+ // remove the unneeded elements at the end of the vector
+ Container::resize(this->size() - static_cast<size_type>(elements_affected));
+
+ // [ a, b, c, d, h, i, j ]
+ // ^ ^
+ // first last
+
+ // first is now pointing past the last deleted element, but we cannot
+ // use this iterator, because it may have been invalidated by the
+ // resize call. Instead, we can return begin() + offset.
+ return Container::begin() + offset;
}
size_type count(const Key& key) const
diff --git a/meson.build b/meson.build
index a7a41f3..d61dc25 100644
--- a/meson.build
+++ b/meson.build
@@ -1,6 +1,6 @@
project('nlohmann_json',
'cpp',
- version : '3.10.4',
+ version : '3.10.5',
license : 'MIT',
)
diff --git a/single_include/nlohmann/json.hpp b/single_include/nlohmann/json.hpp
index 87475ab..cb27e05 100644
--- a/single_include/nlohmann/json.hpp
+++ b/single_include/nlohmann/json.hpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
@@ -27,12 +27,21 @@
SOFTWARE.
*/
+/****************************************************************************\
+ * Note on documentation: The source files contain links to the online *
+ * documentation of the public API at https://json.nlohmann.me. This URL *
+ * contains the most recent documentation and should also be applicable to *
+ * previous versions; documentation for deprecated functions is not *
+ * removed, but marked deprecated. See "Generate documentation" section in *
+ * file doc/README.md. *
+\****************************************************************************/
+
#ifndef INCLUDE_NLOHMANN_JSON_HPP_
#define INCLUDE_NLOHMANN_JSON_HPP_
#define NLOHMANN_JSON_VERSION_MAJOR 3
#define NLOHMANN_JSON_VERSION_MINOR 10
-#define NLOHMANN_JSON_VERSION_PATCH 4
+#define NLOHMANN_JSON_VERSION_PATCH 5
#include <algorithm> // all_of, find, for_each
#include <cstddef> // nullptr_t, ptrdiff_t, size_t
@@ -2325,6 +2334,66 @@
#define JSON_HAS_CPP_11
#endif
+#if !defined(JSON_HAS_FILESYSTEM) && !defined(JSON_HAS_EXPERIMENTAL_FILESYSTEM)
+ #ifdef JSON_HAS_CPP_17
+ #if defined(__cpp_lib_filesystem)
+ #define JSON_HAS_FILESYSTEM 1
+ #elif defined(__cpp_lib_experimental_filesystem)
+ #define JSON_HAS_EXPERIMENTAL_FILESYSTEM 1
+ #elif !defined(__has_include)
+ #define JSON_HAS_EXPERIMENTAL_FILESYSTEM 1
+ #elif __has_include(<filesystem>)
+ #define JSON_HAS_FILESYSTEM 1
+ #elif __has_include(<experimental/filesystem>)
+ #define JSON_HAS_EXPERIMENTAL_FILESYSTEM 1
+ #endif
+
+ // std::filesystem does not work on MinGW GCC 8: https://sourceforge.net/p/mingw-w64/bugs/737/
+ #if defined(__MINGW32__) && defined(__GNUC__) && __GNUC__ == 8
+ #undef JSON_HAS_FILESYSTEM
+ #undef JSON_HAS_EXPERIMENTAL_FILESYSTEM
+ #endif
+
+ // no filesystem support before GCC 8: https://en.cppreference.com/w/cpp/compiler_support
+ #if defined(__GNUC__) && !defined(__clang__) && __GNUC__ < 8
+ #undef JSON_HAS_FILESYSTEM
+ #undef JSON_HAS_EXPERIMENTAL_FILESYSTEM
+ #endif
+
+ // no filesystem support before Clang 7: https://en.cppreference.com/w/cpp/compiler_support
+ #if defined(__clang_major__) && __clang_major__ < 7
+ #undef JSON_HAS_FILESYSTEM
+ #undef JSON_HAS_EXPERIMENTAL_FILESYSTEM
+ #endif
+
+ // no filesystem support before MSVC 19.14: https://en.cppreference.com/w/cpp/compiler_support
+ #if defined(_MSC_VER) && _MSC_VER < 1940
+ #undef JSON_HAS_FILESYSTEM
+ #undef JSON_HAS_EXPERIMENTAL_FILESYSTEM
+ #endif
+
+ // no filesystem support before iOS 13
+ #if defined(__IPHONE_OS_VERSION_MIN_REQUIRED) && __IPHONE_OS_VERSION_MIN_REQUIRED < 130000
+ #undef JSON_HAS_FILESYSTEM
+ #undef JSON_HAS_EXPERIMENTAL_FILESYSTEM
+ #endif
+
+ // no filesystem support before macOS Catalina
+ #if defined(__MAC_OS_X_VERSION_MIN_REQUIRED) && __MAC_OS_X_VERSION_MIN_REQUIRED < 101500
+ #undef JSON_HAS_FILESYSTEM
+ #undef JSON_HAS_EXPERIMENTAL_FILESYSTEM
+ #endif
+ #endif
+#endif
+
+#ifndef JSON_HAS_EXPERIMENTAL_FILESYSTEM
+ #define JSON_HAS_EXPERIMENTAL_FILESYSTEM 0
+#endif
+
+#ifndef JSON_HAS_FILESYSTEM
+ #define JSON_HAS_FILESYSTEM 0
+#endif
+
// disable documentation warnings on clang
#if defined(__clang__)
#pragma clang diagnostic push
@@ -2332,7 +2401,7 @@
#pragma clang diagnostic ignored "-Wdocumentation-unknown-command"
#endif
-// allow to disable exceptions
+// allow disabling exceptions
#if (defined(__cpp_exceptions) || defined(__EXCEPTIONS) || defined(_CPPUNWIND)) && !defined(JSON_NOEXCEPTION)
#define JSON_THROW(exception) throw exception
#define JSON_TRY try
@@ -2366,7 +2435,7 @@
#define JSON_INTERNAL_CATCH JSON_INTERNAL_CATCH_USER
#endif
-// allow to override assert
+// allow overriding assert
#if !defined(JSON_ASSERT)
#include <cassert> // assert
#define JSON_ASSERT(x) assert(x)
@@ -2734,34 +2803,8 @@
// exceptions //
////////////////
-/*!
-@brief general exception of the @ref basic_json class
-
-This class is an extension of `std::exception` objects with a member @a id for
-exception ids. It is used as the base class for all exceptions thrown by the
-@ref basic_json class. This class can hence be used as "wildcard" to catch
-exceptions.
-
-Subclasses:
-- @ref parse_error for exceptions indicating a parse error
-- @ref invalid_iterator for exceptions indicating errors with iterators
-- @ref type_error for exceptions indicating executing a member function with
- a wrong type
-- @ref out_of_range for exceptions indicating access out of the defined range
-- @ref other_error for exceptions indicating other library errors
-
-@internal
-@note To have nothrow-copy-constructible exceptions, we internally use
- `std::runtime_error` which can cope with arbitrary-length error messages.
- Intermediate strings are built with static functions and then passed to
- the actual constructor.
-@endinternal
-
-@liveexample{The following code shows how arbitrary library exceptions can be
-caught.,exception}
-
-@since version 3.0.0
-*/
+/// @brief general exception of the @ref basic_json class
+/// @sa https://json.nlohmann.me/api/basic_json/exception/
class exception : public std::exception
{
public:
@@ -2776,7 +2819,7 @@
protected:
JSON_HEDLEY_NON_NULL(3)
- exception(int id_, const char* what_arg) : id(id_), m(what_arg) {}
+ exception(int id_, const char* what_arg) : id(id_), m(what_arg) {} // NOLINT(bugprone-throw-keyword-missing)
static std::string name(const std::string& ename, int id_)
{
@@ -2852,51 +2895,8 @@
std::runtime_error m;
};
-/*!
-@brief exception indicating a parse error
-
-This exception is thrown by the library when a parse error occurs. Parse errors
-can occur during the deserialization of JSON text, CBOR, MessagePack, as well
-as when using JSON Patch.
-
-Member @a byte holds the byte index of the last read character in the input
-file.
-
-Exceptions have ids 1xx.
-
-name / id | example message | description
------------------------------- | --------------- | -------------------------
-json.exception.parse_error.101 | parse error at 2: unexpected end of input; expected string literal | This error indicates a syntax error while deserializing a JSON text. The error message describes that an unexpected token (character) was encountered, and the member @a byte indicates the error position.
-json.exception.parse_error.102 | parse error at 14: missing or wrong low surrogate | JSON uses the `\uxxxx` format to describe Unicode characters. Code points above above 0xFFFF are split into two `\uxxxx` entries ("surrogate pairs"). This error indicates that the surrogate pair is incomplete or contains an invalid code point.
-json.exception.parse_error.103 | parse error: code points above 0x10FFFF are invalid | Unicode supports code points up to 0x10FFFF. Code points above 0x10FFFF are invalid.
-json.exception.parse_error.104 | parse error: JSON patch must be an array of objects | [RFC 6902](https://tools.ietf.org/html/rfc6902) requires a JSON Patch document to be a JSON document that represents an array of objects.
-json.exception.parse_error.105 | parse error: operation must have string member 'op' | An operation of a JSON Patch document must contain exactly one "op" member, whose value indicates the operation to perform. Its value must be one of "add", "remove", "replace", "move", "copy", or "test"; other values are errors.
-json.exception.parse_error.106 | parse error: array index '01' must not begin with '0' | An array index in a JSON Pointer ([RFC 6901](https://tools.ietf.org/html/rfc6901)) may be `0` or any number without a leading `0`.
-json.exception.parse_error.107 | parse error: JSON pointer must be empty or begin with '/' - was: 'foo' | A JSON Pointer must be a Unicode string containing a sequence of zero or more reference tokens, each prefixed by a `/` character.
-json.exception.parse_error.108 | parse error: escape character '~' must be followed with '0' or '1' | In a JSON Pointer, only `~0` and `~1` are valid escape sequences.
-json.exception.parse_error.109 | parse error: array index 'one' is not a number | A JSON Pointer array index must be a number.
-json.exception.parse_error.110 | parse error at 1: cannot read 2 bytes from vector | When parsing CBOR or MessagePack, the byte vector ends before the complete value has been read.
-json.exception.parse_error.112 | parse error at 1: error reading CBOR; last byte: 0xF8 | Not all types of CBOR or MessagePack are supported. This exception occurs if an unsupported byte was read.
-json.exception.parse_error.113 | parse error at 2: expected a CBOR string; last byte: 0x98 | While parsing a map key, a value that is not a string has been read.
-json.exception.parse_error.114 | parse error: Unsupported BSON record type 0x0F | The parsing of the corresponding BSON record type is not implemented (yet).
-json.exception.parse_error.115 | parse error at byte 5: syntax error while parsing UBJSON high-precision number: invalid number text: 1A | A UBJSON high-precision number could not be parsed.
-
-@note For an input with n bytes, 1 is the index of the first character and n+1
- is the index of the terminating null byte or the end of file. This also
- holds true when reading a byte vector (CBOR or MessagePack).
-
-@liveexample{The following code shows how a `parse_error` exception can be
-caught.,parse_error}
-
-@sa - @ref exception for the base class of the library exceptions
-@sa - @ref invalid_iterator for exceptions indicating errors with iterators
-@sa - @ref type_error for exceptions indicating executing a member function with
- a wrong type
-@sa - @ref out_of_range for exceptions indicating access out of the defined range
-@sa - @ref other_error for exceptions indicating other library errors
-
-@since version 3.0.0
-*/
+/// @brief exception indicating a parse error
+/// @sa https://json.nlohmann.me/api/basic_json/parse_error/
class parse_error : public exception
{
public:
@@ -2914,7 +2914,7 @@
{
std::string w = exception::name("parse_error", id_) + "parse error" +
position_string(pos) + ": " + exception::diagnostics(context) + what_arg;
- return parse_error(id_, pos.chars_read_total, w.c_str());
+ return {id_, pos.chars_read_total, w.c_str()};
}
template<typename BasicJsonType>
@@ -2923,7 +2923,7 @@
std::string w = exception::name("parse_error", id_) + "parse error" +
(byte_ != 0 ? (" at byte " + std::to_string(byte_)) : "") +
": " + exception::diagnostics(context) + what_arg;
- return parse_error(id_, byte_, w.c_str());
+ return {id_, byte_, w.c_str()};
}
/*!
@@ -2948,43 +2948,8 @@
}
};
-/*!
-@brief exception indicating errors with iterators
-
-This exception is thrown if iterators passed to a library function do not match
-the expected semantics.
-
-Exceptions have ids 2xx.
-
-name / id | example message | description
------------------------------------ | --------------- | -------------------------
-json.exception.invalid_iterator.201 | iterators are not compatible | The iterators passed to constructor @ref basic_json(InputIT first, InputIT last) are not compatible, meaning they do not belong to the same container. Therefore, the range (@a first, @a last) is invalid.
-json.exception.invalid_iterator.202 | iterator does not fit current value | In an erase or insert function, the passed iterator @a pos does not belong to the JSON value for which the function was called. It hence does not define a valid position for the deletion/insertion.
-json.exception.invalid_iterator.203 | iterators do not fit current value | Either iterator passed to function @ref erase(IteratorType first, IteratorType last) does not belong to the JSON value from which values shall be erased. It hence does not define a valid range to delete values from.
-json.exception.invalid_iterator.204 | iterators out of range | When an iterator range for a primitive type (number, boolean, or string) is passed to a constructor or an erase function, this range has to be exactly (@ref begin(), @ref end()), because this is the only way the single stored value is expressed. All other ranges are invalid.
-json.exception.invalid_iterator.205 | iterator out of range | When an iterator for a primitive type (number, boolean, or string) is passed to an erase function, the iterator has to be the @ref begin() iterator, because it is the only way to address the stored value. All other iterators are invalid.
-json.exception.invalid_iterator.206 | cannot construct with iterators from null | The iterators passed to constructor @ref basic_json(InputIT first, InputIT last) belong to a JSON null value and hence to not define a valid range.
-json.exception.invalid_iterator.207 | cannot use key() for non-object iterators | The key() member function can only be used on iterators belonging to a JSON object, because other types do not have a concept of a key.
-json.exception.invalid_iterator.208 | cannot use operator[] for object iterators | The operator[] to specify a concrete offset cannot be used on iterators belonging to a JSON object, because JSON objects are unordered.
-json.exception.invalid_iterator.209 | cannot use offsets with object iterators | The offset operators (+, -, +=, -=) cannot be used on iterators belonging to a JSON object, because JSON objects are unordered.
-json.exception.invalid_iterator.210 | iterators do not fit | The iterator range passed to the insert function are not compatible, meaning they do not belong to the same container. Therefore, the range (@a first, @a last) is invalid.
-json.exception.invalid_iterator.211 | passed iterators may not belong to container | The iterator range passed to the insert function must not be a subrange of the container to insert to.
-json.exception.invalid_iterator.212 | cannot compare iterators of different containers | When two iterators are compared, they must belong to the same container.
-json.exception.invalid_iterator.213 | cannot compare order of object iterators | The order of object iterators cannot be compared, because JSON objects are unordered.
-json.exception.invalid_iterator.214 | cannot get value | Cannot get value for iterator: Either the iterator belongs to a null value or it is an iterator to a primitive type (number, boolean, or string), but the iterator is different to @ref begin().
-
-@liveexample{The following code shows how an `invalid_iterator` exception can be
-caught.,invalid_iterator}
-
-@sa - @ref exception for the base class of the library exceptions
-@sa - @ref parse_error for exceptions indicating a parse error
-@sa - @ref type_error for exceptions indicating executing a member function with
- a wrong type
-@sa - @ref out_of_range for exceptions indicating access out of the defined range
-@sa - @ref other_error for exceptions indicating other library errors
-
-@since version 3.0.0
-*/
+/// @brief exception indicating errors with iterators
+/// @sa https://json.nlohmann.me/api/basic_json/invalid_iterator/
class invalid_iterator : public exception
{
public:
@@ -2992,7 +2957,7 @@
static invalid_iterator create(int id_, const std::string& what_arg, const BasicJsonType& context)
{
std::string w = exception::name("invalid_iterator", id_) + exception::diagnostics(context) + what_arg;
- return invalid_iterator(id_, w.c_str());
+ return {id_, w.c_str()};
}
private:
@@ -3001,45 +2966,8 @@
: exception(id_, what_arg) {}
};
-/*!
-@brief exception indicating executing a member function with a wrong type
-
-This exception is thrown in case of a type error; that is, a library function is
-executed on a JSON value whose type does not match the expected semantics.
-
-Exceptions have ids 3xx.
-
-name / id | example message | description
------------------------------ | --------------- | -------------------------
-json.exception.type_error.301 | cannot create object from initializer list | To create an object from an initializer list, the initializer list must consist only of a list of pairs whose first element is a string. When this constraint is violated, an array is created instead.
-json.exception.type_error.302 | type must be object, but is array | During implicit or explicit value conversion, the JSON type must be compatible to the target type. For instance, a JSON string can only be converted into string types, but not into numbers or boolean types.
-json.exception.type_error.303 | incompatible ReferenceType for get_ref, actual type is object | To retrieve a reference to a value stored in a @ref basic_json object with @ref get_ref, the type of the reference must match the value type. For instance, for a JSON array, the @a ReferenceType must be @ref array_t &.
-json.exception.type_error.304 | cannot use at() with string | The @ref at() member functions can only be executed for certain JSON types.
-json.exception.type_error.305 | cannot use operator[] with string | The @ref operator[] member functions can only be executed for certain JSON types.
-json.exception.type_error.306 | cannot use value() with string | The @ref value() member functions can only be executed for certain JSON types.
-json.exception.type_error.307 | cannot use erase() with string | The @ref erase() member functions can only be executed for certain JSON types.
-json.exception.type_error.308 | cannot use push_back() with string | The @ref push_back() and @ref operator+= member functions can only be executed for certain JSON types.
-json.exception.type_error.309 | cannot use insert() with | The @ref insert() member functions can only be executed for certain JSON types.
-json.exception.type_error.310 | cannot use swap() with number | The @ref swap() member functions can only be executed for certain JSON types.
-json.exception.type_error.311 | cannot use emplace_back() with string | The @ref emplace_back() member function can only be executed for certain JSON types.
-json.exception.type_error.312 | cannot use update() with string | The @ref update() member functions can only be executed for certain JSON types.
-json.exception.type_error.313 | invalid value to unflatten | The @ref unflatten function converts an object whose keys are JSON Pointers back into an arbitrary nested JSON value. The JSON Pointers must not overlap, because then the resulting value would not be well defined.
-json.exception.type_error.314 | only objects can be unflattened | The @ref unflatten function only works for an object whose keys are JSON Pointers.
-json.exception.type_error.315 | values in object must be primitive | The @ref unflatten function only works for an object whose keys are JSON Pointers and whose values are primitive.
-json.exception.type_error.316 | invalid UTF-8 byte at index 10: 0x7E | The @ref dump function only works with UTF-8 encoded strings; that is, if you assign a `std::string` to a JSON value, make sure it is UTF-8 encoded. |
-json.exception.type_error.317 | JSON value cannot be serialized to requested format | The dynamic type of the object cannot be represented in the requested serialization format (e.g. a raw `true` or `null` JSON object cannot be serialized to BSON) |
-
-@liveexample{The following code shows how a `type_error` exception can be
-caught.,type_error}
-
-@sa - @ref exception for the base class of the library exceptions
-@sa - @ref parse_error for exceptions indicating a parse error
-@sa - @ref invalid_iterator for exceptions indicating errors with iterators
-@sa - @ref out_of_range for exceptions indicating access out of the defined range
-@sa - @ref other_error for exceptions indicating other library errors
-
-@since version 3.0.0
-*/
+/// @brief exception indicating executing a member function with a wrong type
+/// @sa https://json.nlohmann.me/api/basic_json/type_error/
class type_error : public exception
{
public:
@@ -3047,7 +2975,7 @@
static type_error create(int id_, const std::string& what_arg, const BasicJsonType& context)
{
std::string w = exception::name("type_error", id_) + exception::diagnostics(context) + what_arg;
- return type_error(id_, w.c_str());
+ return {id_, w.c_str()};
}
private:
@@ -3055,39 +2983,8 @@
type_error(int id_, const char* what_arg) : exception(id_, what_arg) {}
};
-/*!
-@brief exception indicating access out of the defined range
-
-This exception is thrown in case a library function is called on an input
-parameter that exceeds the expected range, for instance in case of array
-indices or nonexisting object keys.
-
-Exceptions have ids 4xx.
-
-name / id | example message | description
-------------------------------- | --------------- | -------------------------
-json.exception.out_of_range.401 | array index 3 is out of range | The provided array index @a i is larger than @a size-1.
-json.exception.out_of_range.402 | array index '-' (3) is out of range | The special array index `-` in a JSON Pointer never describes a valid element of the array, but the index past the end. That is, it can only be used to add elements at this position, but not to read it.
-json.exception.out_of_range.403 | key 'foo' not found | The provided key was not found in the JSON object.
-json.exception.out_of_range.404 | unresolved reference token 'foo' | A reference token in a JSON Pointer could not be resolved.
-json.exception.out_of_range.405 | JSON pointer has no parent | The JSON Patch operations 'remove' and 'add' can not be applied to the root element of the JSON value.
-json.exception.out_of_range.406 | number overflow parsing '10E1000' | A parsed number could not be stored as without changing it to NaN or INF.
-json.exception.out_of_range.407 | number overflow serializing '9223372036854775808' | UBJSON and BSON only support integer numbers up to 9223372036854775807. (until version 3.8.0) |
-json.exception.out_of_range.408 | excessive array size: 8658170730974374167 | The size (following `#`) of an UBJSON array or object exceeds the maximal capacity. |
-json.exception.out_of_range.409 | BSON key cannot contain code point U+0000 (at byte 2) | Key identifiers to be serialized to BSON cannot contain code point U+0000, since the key is stored as zero-terminated c-string |
-
-@liveexample{The following code shows how an `out_of_range` exception can be
-caught.,out_of_range}
-
-@sa - @ref exception for the base class of the library exceptions
-@sa - @ref parse_error for exceptions indicating a parse error
-@sa - @ref invalid_iterator for exceptions indicating errors with iterators
-@sa - @ref type_error for exceptions indicating executing a member function with
- a wrong type
-@sa - @ref other_error for exceptions indicating other library errors
-
-@since version 3.0.0
-*/
+/// @brief exception indicating access out of the defined range
+/// @sa https://json.nlohmann.me/api/basic_json/out_of_range/
class out_of_range : public exception
{
public:
@@ -3095,7 +2992,7 @@
static out_of_range create(int id_, const std::string& what_arg, const BasicJsonType& context)
{
std::string w = exception::name("out_of_range", id_) + exception::diagnostics(context) + what_arg;
- return out_of_range(id_, w.c_str());
+ return {id_, w.c_str()};
}
private:
@@ -3103,30 +3000,8 @@
out_of_range(int id_, const char* what_arg) : exception(id_, what_arg) {}
};
-/*!
-@brief exception indicating other library errors
-
-This exception is thrown in case of errors that cannot be classified with the
-other exception types.
-
-Exceptions have ids 5xx.
-
-name / id | example message | description
------------------------------- | --------------- | -------------------------
-json.exception.other_error.501 | unsuccessful: {"op":"test","path":"/baz", "value":"bar"} | A JSON Patch operation 'test' failed. The unsuccessful operation is also printed.
-
-@sa - @ref exception for the base class of the library exceptions
-@sa - @ref parse_error for exceptions indicating a parse error
-@sa - @ref invalid_iterator for exceptions indicating errors with iterators
-@sa - @ref type_error for exceptions indicating executing a member function with
- a wrong type
-@sa - @ref out_of_range for exceptions indicating access out of the defined range
-
-@liveexample{The following code shows how an `other_error` exception can be
-caught.,other_error}
-
-@since version 3.0.0
-*/
+/// @brief exception indicating other library errors
+/// @sa https://json.nlohmann.me/api/basic_json/other_error/
class other_error : public exception
{
public:
@@ -3134,13 +3009,14 @@
static other_error create(int id_, const std::string& what_arg, const BasicJsonType& context)
{
std::string w = exception::name("other_error", id_) + exception::diagnostics(context) + what_arg;
- return other_error(id_, w.c_str());
+ return {id_, w.c_str()};
}
private:
JSON_HEDLEY_NON_NULL(3)
other_error(int id_, const char* what_arg) : exception(id_, what_arg) {}
};
+
} // namespace detail
} // namespace nlohmann
@@ -3298,7 +3174,7 @@
};
template<typename T>
-constexpr T static_const<T>::value;
+constexpr T static_const<T>::value; // NOLINT(readability-redundant-declaration)
} // namespace detail
} // namespace nlohmann
@@ -3434,6 +3310,8 @@
template<typename T = void, typename SFINAE = void>
struct adl_serializer;
+/// a class to store JSON values
+/// @sa https://json.nlohmann.me/api/basic_json/
template<template<typename U, typename V, typename... Args> class ObjectType =
std::map,
template<typename U, typename... Args> class ArrayType = std::vector,
@@ -3447,40 +3325,24 @@
class BinaryType = std::vector<std::uint8_t>>
class basic_json;
-/*!
-@brief JSON Pointer
-
-A JSON pointer defines a string syntax for identifying a specific value
-within a JSON document. It can be used with functions `at` and
-`operator[]`. Furthermore, JSON pointers are the base for JSON patches.
-
-@sa [RFC 6901](https://tools.ietf.org/html/rfc6901)
-
-@since version 2.0.0
-*/
+/// @brief JSON Pointer defines a string syntax for identifying a specific value within a JSON document
+/// @sa https://json.nlohmann.me/api/json_pointer/
template<typename BasicJsonType>
class json_pointer;
/*!
-@brief default JSON class
-
-This type is the default specialization of the @ref basic_json class which
-uses the standard template types.
-
-@since version 1.0.0
+@brief default specialization
+@sa https://json.nlohmann.me/api/json/
*/
using json = basic_json<>;
+/// @brief a minimal map-like container that preserves insertion order
+/// @sa https://json.nlohmann.me/api/ordered_map/
template<class Key, class T, class IgnoredLess, class Allocator>
struct ordered_map;
-/*!
-@brief ordered JSON class
-
-This type preserves the insertion order of object keys.
-
-@since version 3.9.0
-*/
+/// @brief specialization that maintains the insertion order of object keys
+/// @sa https://json.nlohmann.me/api/ordered_json/
using ordered_json = basic_json<nlohmann::ordered_map>;
} // namespace nlohmann
@@ -3950,8 +3812,18 @@
// #include <nlohmann/detail/value_t.hpp>
-#ifdef JSON_HAS_CPP_17
- #include <filesystem>
+#if JSON_HAS_EXPERIMENTAL_FILESYSTEM
+#include <experimental/filesystem>
+namespace nlohmann::detail
+{
+namespace std_fs = std::experimental::filesystem;
+} // namespace nlohmann::detail
+#elif JSON_HAS_FILESYSTEM
+#include <filesystem>
+namespace nlohmann::detail
+{
+namespace std_fs = std::filesystem;
+} // namespace nlohmann::detail
#endif
namespace nlohmann
@@ -4379,9 +4251,9 @@
}
}
-#ifdef JSON_HAS_CPP_17
+#if JSON_HAS_FILESYSTEM || JSON_HAS_EXPERIMENTAL_FILESYSTEM
template<typename BasicJsonType>
-void from_json(const BasicJsonType& j, std::filesystem::path& p)
+void from_json(const BasicJsonType& j, std_fs::path& p)
{
if (JSON_HEDLEY_UNLIKELY(!j.is_string()))
{
@@ -4626,8 +4498,18 @@
// #include <nlohmann/detail/value_t.hpp>
-#ifdef JSON_HAS_CPP_17
- #include <filesystem>
+#if JSON_HAS_EXPERIMENTAL_FILESYSTEM
+#include <experimental/filesystem>
+namespace nlohmann::detail
+{
+namespace std_fs = std::experimental::filesystem;
+} // namespace nlohmann::detail
+#elif JSON_HAS_FILESYSTEM
+#include <filesystem>
+namespace nlohmann::detail
+{
+namespace std_fs = std::filesystem;
+} // namespace nlohmann::detail
#endif
namespace nlohmann
@@ -5002,9 +4884,9 @@
to_json_tuple_impl(j, t, make_index_sequence<std::tuple_size<T>::value> {});
}
-#ifdef JSON_HAS_CPP_17
+#if JSON_HAS_FILESYSTEM || JSON_HAS_EXPERIMENTAL_FILESYSTEM
template<typename BasicJsonType>
-void to_json(BasicJsonType& j, const std::filesystem::path& p)
+void to_json(BasicJsonType& j, const std_fs::path& p)
{
j = p.string();
}
@@ -5038,20 +4920,12 @@
namespace nlohmann
{
+/// @sa https://json.nlohmann.me/api/adl_serializer/
template<typename ValueType, typename>
struct adl_serializer
{
- /*!
- @brief convert a JSON value to any value type
-
- This function is usually called by the `get()` function of the
- @ref basic_json class (either explicit or via conversion operators).
-
- @note This function is chosen for default-constructible value types.
-
- @param[in] j JSON value to read from
- @param[in,out] val value to write to
- */
+ /// @brief convert a JSON value to any value type
+ /// @sa https://json.nlohmann.me/api/adl_serializer/from_json/
template<typename BasicJsonType, typename TargetType = ValueType>
static auto from_json(BasicJsonType && j, TargetType& val) noexcept(
noexcept(::nlohmann::from_json(std::forward<BasicJsonType>(j), val)))
@@ -5060,18 +4934,8 @@
::nlohmann::from_json(std::forward<BasicJsonType>(j), val);
}
- /*!
- @brief convert a JSON value to any value type
-
- This function is usually called by the `get()` function of the
- @ref basic_json class (either explicit or via conversion operators).
-
- @note This function is chosen for value types which are not default-constructible.
-
- @param[in] j JSON value to read from
-
- @return copy of the JSON value, converted to @a ValueType
- */
+ /// @brief convert a JSON value to any value type
+ /// @sa https://json.nlohmann.me/api/adl_serializer/from_json/
template<typename BasicJsonType, typename TargetType = ValueType>
static auto from_json(BasicJsonType && j) noexcept(
noexcept(::nlohmann::from_json(std::forward<BasicJsonType>(j), detail::identity_tag<TargetType> {})))
@@ -5080,15 +4944,8 @@
return ::nlohmann::from_json(std::forward<BasicJsonType>(j), detail::identity_tag<TargetType> {});
}
- /*!
- @brief convert any value type to a JSON value
-
- This function is usually called by the constructors of the @ref basic_json
- class.
-
- @param[in,out] j JSON value to write to
- @param[in] val value to read from
- */
+ /// @brief convert any value type to a JSON value
+ /// @sa https://json.nlohmann.me/api/adl_serializer/to_json/
template<typename BasicJsonType, typename TargetType = ValueType>
static auto to_json(BasicJsonType& j, TargetType && val) noexcept(
noexcept(::nlohmann::to_json(j, std::forward<TargetType>(val))))
@@ -5109,46 +4966,38 @@
namespace nlohmann
{
-/*!
-@brief an internal type for a backed binary type
-
-This type extends the template parameter @a BinaryType provided to `basic_json`
-with a subtype used by BSON and MessagePack. This type exists so that the user
-does not have to specify a type themselves with a specific naming scheme in
-order to override the binary type.
-
-@tparam BinaryType container to store bytes (`std::vector<std::uint8_t>` by
- default)
-
-@since version 3.8.0; changed type of subtypes to std::uint64_t in 3.10.0.
-*/
+/// @brief an internal type for a backed binary type
+/// @sa https://json.nlohmann.me/api/byte_container_with_subtype/
template<typename BinaryType>
class byte_container_with_subtype : public BinaryType
{
public:
- /// the type of the underlying container
using container_type = BinaryType;
- /// the type of the subtype
using subtype_type = std::uint64_t;
+ /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/byte_container_with_subtype/
byte_container_with_subtype() noexcept(noexcept(container_type()))
: container_type()
{}
+ /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/byte_container_with_subtype/
byte_container_with_subtype(const container_type& b) noexcept(noexcept(container_type(b)))
: container_type(b)
{}
+ /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/byte_container_with_subtype/
byte_container_with_subtype(container_type&& b) noexcept(noexcept(container_type(std::move(b))))
: container_type(std::move(b))
{}
+ /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/byte_container_with_subtype/
byte_container_with_subtype(const container_type& b, subtype_type subtype_) noexcept(noexcept(container_type(b)))
: container_type(b)
, m_subtype(subtype_)
, m_has_subtype(true)
{}
+ /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/byte_container_with_subtype/
byte_container_with_subtype(container_type&& b, subtype_type subtype_) noexcept(noexcept(container_type(std::move(b))))
: container_type(std::move(b))
, m_subtype(subtype_)
@@ -5166,97 +5015,30 @@
return !(rhs == *this);
}
- /*!
- @brief sets the binary subtype
-
- Sets the binary subtype of the value, also flags a binary JSON value as
- having a subtype, which has implications for serialization.
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this member function never throws
- exceptions.
-
- @sa see @ref subtype() -- return the binary subtype
- @sa see @ref clear_subtype() -- clears the binary subtype
- @sa see @ref has_subtype() -- returns whether or not the binary value has a
- subtype
-
- @since version 3.8.0
- */
+ /// @brief sets the binary subtype
+ /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/set_subtype/
void set_subtype(subtype_type subtype_) noexcept
{
m_subtype = subtype_;
m_has_subtype = true;
}
- /*!
- @brief return the binary subtype
-
- Returns the numerical subtype of the value if it has a subtype. If it does
- not have a subtype, this function will return subtype_type(-1) as a sentinel
- value.
-
- @return the numerical subtype of the binary value
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this member function never throws
- exceptions.
-
- @sa see @ref set_subtype() -- sets the binary subtype
- @sa see @ref clear_subtype() -- clears the binary subtype
- @sa see @ref has_subtype() -- returns whether or not the binary value has a
- subtype
-
- @since version 3.8.0; fixed return value to properly return
- subtype_type(-1) as documented in version 3.10.0
- */
+ /// @brief return the binary subtype
+ /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/subtype/
constexpr subtype_type subtype() const noexcept
{
- return m_has_subtype ? m_subtype : subtype_type(-1);
+ return m_has_subtype ? m_subtype : static_cast<subtype_type>(-1);
}
- /*!
- @brief return whether the value has a subtype
-
- @return whether the value has a subtype
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this member function never throws
- exceptions.
-
- @sa see @ref subtype() -- return the binary subtype
- @sa see @ref set_subtype() -- sets the binary subtype
- @sa see @ref clear_subtype() -- clears the binary subtype
-
- @since version 3.8.0
- */
+ /// @brief return whether the value has a subtype
+ /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/has_subtype/
constexpr bool has_subtype() const noexcept
{
return m_has_subtype;
}
- /*!
- @brief clears the binary subtype
-
- Clears the binary subtype and flags the value as not having a subtype, which
- has implications for serialization; for instance MessagePack will prefer the
- bin family over the ext family.
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this member function never throws
- exceptions.
-
- @sa see @ref subtype() -- return the binary subtype
- @sa see @ref set_subtype() -- sets the binary subtype
- @sa see @ref has_subtype() -- returns whether or not the binary value has a
- subtype
-
- @since version 3.8.0
- */
+ /// @brief clears the binary subtype
+ /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/clear_subtype/
void clear_subtype() noexcept
{
m_subtype = 0;
@@ -5529,7 +5311,7 @@
// std::istream/std::streambuf use std::char_traits<char>::to_int_type, to
// ensure that std::char_traits<char>::eof() and the character 0xFF do not
- // end up as the same value, eg. 0xFFFFFFFF.
+ // end up as the same value, e.g. 0xFFFFFFFF.
std::char_traits<char>::int_type get_character()
{
auto res = sb->sbumpc();
@@ -5875,7 +5657,7 @@
}
// This class only handles inputs of input_buffer_adapter type.
-// It's required so that expressions like {ptr, len} can be implicitely casted
+// It's required so that expressions like {ptr, len} can be implicitly cast
// to the correct adapter.
class span_input_adapter
{
@@ -5968,7 +5750,7 @@
virtual bool number_unsigned(number_unsigned_t val) = 0;
/*!
- @brief an floating-point number was read
+ @brief a floating-point number was read
@param[in] val floating-point value
@param[in] s raw token value
@return whether parsing should proceed
@@ -5976,18 +5758,18 @@
virtual bool number_float(number_float_t val, const string_t& s) = 0;
/*!
- @brief a string was read
+ @brief a string value was read
@param[in] val string value
@return whether parsing should proceed
- @note It is safe to move the passed string.
+ @note It is safe to move the passed string value.
*/
virtual bool string(string_t& val) = 0;
/*!
- @brief a binary string was read
+ @brief a binary value was read
@param[in] val binary value
@return whether parsing should proceed
- @note It is safe to move the passed binary.
+ @note It is safe to move the passed binary value.
*/
virtual bool binary(binary_t& val) = 0;
@@ -6134,7 +5916,7 @@
{
ref_stack.push_back(handle_value(BasicJsonType::value_t::object));
- if (JSON_HEDLEY_UNLIKELY(len != std::size_t(-1) && len > ref_stack.back()->max_size()))
+ if (JSON_HEDLEY_UNLIKELY(len != static_cast<std::size_t>(-1) && len > ref_stack.back()->max_size()))
{
JSON_THROW(out_of_range::create(408, "excessive object size: " + std::to_string(len), *ref_stack.back()));
}
@@ -6160,7 +5942,7 @@
{
ref_stack.push_back(handle_value(BasicJsonType::value_t::array));
- if (JSON_HEDLEY_UNLIKELY(len != std::size_t(-1) && len > ref_stack.back()->max_size()))
+ if (JSON_HEDLEY_UNLIKELY(len != static_cast<std::size_t>(-1) && len > ref_stack.back()->max_size()))
{
JSON_THROW(out_of_range::create(408, "excessive array size: " + std::to_string(len), *ref_stack.back()));
}
@@ -6315,7 +6097,7 @@
ref_stack.push_back(val.second);
// check object limit
- if (ref_stack.back() && JSON_HEDLEY_UNLIKELY(len != std::size_t(-1) && len > ref_stack.back()->max_size()))
+ if (ref_stack.back() && JSON_HEDLEY_UNLIKELY(len != static_cast<std::size_t>(-1) && len > ref_stack.back()->max_size()))
{
JSON_THROW(out_of_range::create(408, "excessive object size: " + std::to_string(len), *ref_stack.back()));
}
@@ -6385,7 +6167,7 @@
ref_stack.push_back(val.second);
// check array limit
- if (ref_stack.back() && JSON_HEDLEY_UNLIKELY(len != std::size_t(-1) && len > ref_stack.back()->max_size()))
+ if (ref_stack.back() && JSON_HEDLEY_UNLIKELY(len != static_cast<std::size_t>(-1) && len > ref_stack.back()->max_size()))
{
JSON_THROW(out_of_range::create(408, "excessive array size: " + std::to_string(len), *ref_stack.back()));
}
@@ -6588,7 +6370,7 @@
return true;
}
- bool start_object(std::size_t /*unused*/ = std::size_t(-1))
+ bool start_object(std::size_t /*unused*/ = static_cast<std::size_t>(-1))
{
return true;
}
@@ -6603,7 +6385,7 @@
return true;
}
- bool start_array(std::size_t /*unused*/ = std::size_t(-1))
+ bool start_array(std::size_t /*unused*/ = static_cast<std::size_t>(-1))
{
return true;
}
@@ -6971,7 +6753,7 @@
// low surrogate occupies the least significant 15 bits
+ static_cast<unsigned int>(codepoint2)
// there is still the 0xD800, 0xDC00 and 0x10000 noise
- // in the result so we have to subtract with:
+ // in the result, so we have to subtract with:
// (0xD800 << 10) + DC00 - 0x10000 = 0x35FDC00
- 0x35FDC00u);
}
@@ -8075,7 +7857,7 @@
{
// escape control characters
std::array<char, 9> cs{{}};
- (std::snprintf)(cs.data(), cs.size(), "<U+%.4X>", static_cast<unsigned char>(c)); // NOLINT(cppcoreguidelines-pro-type-vararg,hicpp-vararg)
+ static_cast<void>((std::snprintf)(cs.data(), cs.size(), "<U+%.4X>", static_cast<unsigned char>(c))); // NOLINT(cppcoreguidelines-pro-type-vararg,hicpp-vararg)
result += cs.data();
}
else
@@ -8169,17 +7951,17 @@
// literals
case 't':
{
- std::array<char_type, 4> true_literal = {{char_type('t'), char_type('r'), char_type('u'), char_type('e')}};
+ std::array<char_type, 4> true_literal = {{static_cast<char_type>('t'), static_cast<char_type>('r'), static_cast<char_type>('u'), static_cast<char_type>('e')}};
return scan_literal(true_literal.data(), true_literal.size(), token_type::literal_true);
}
case 'f':
{
- std::array<char_type, 5> false_literal = {{char_type('f'), char_type('a'), char_type('l'), char_type('s'), char_type('e')}};
+ std::array<char_type, 5> false_literal = {{static_cast<char_type>('f'), static_cast<char_type>('a'), static_cast<char_type>('l'), static_cast<char_type>('s'), static_cast<char_type>('e')}};
return scan_literal(false_literal.data(), false_literal.size(), token_type::literal_false);
}
case 'n':
{
- std::array<char_type, 4> null_literal = {{char_type('n'), char_type('u'), char_type('l'), char_type('l')}};
+ std::array<char_type, 4> null_literal = {{static_cast<char_type>('n'), static_cast<char_type>('u'), static_cast<char_type>('l'), static_cast<char_type>('l')}};
return scan_literal(null_literal.data(), null_literal.size(), token_type::literal_null);
}
@@ -8430,7 +8212,7 @@
@note from https://stackoverflow.com/a/1001328/266378
*/
-static inline bool little_endianess(int num = 1) noexcept
+static inline bool little_endianness(int num = 1) noexcept
{
return *reinterpret_cast<char*>(&num) == 1;
}
@@ -8549,7 +8331,7 @@
std::int32_t document_size{};
get_number<std::int32_t, true>(input_format_t::bson, document_size);
- if (JSON_HEDLEY_UNLIKELY(!sax->start_object(std::size_t(-1))))
+ if (JSON_HEDLEY_UNLIKELY(!sax->start_object(static_cast<std::size_t>(-1))))
{
return false;
}
@@ -8706,7 +8488,7 @@
default: // anything else not supported (yet)
{
std::array<char, 3> cr{{}};
- (std::snprintf)(cr.data(), cr.size(), "%.2hhX", static_cast<unsigned char>(element_type)); // NOLINT(cppcoreguidelines-pro-type-vararg,hicpp-vararg)
+ static_cast<void>((std::snprintf)(cr.data(), cr.size(), "%.2hhX", static_cast<unsigned char>(element_type))); // NOLINT(cppcoreguidelines-pro-type-vararg,hicpp-vararg)
return sax->parse_error(element_type_parse_position, std::string(cr.data()), parse_error::create(114, element_type_parse_position, "Unsupported BSON record type 0x" + std::string(cr.data()), BasicJsonType()));
}
}
@@ -8767,7 +8549,7 @@
std::int32_t document_size{};
get_number<std::int32_t, true>(input_format_t::bson, document_size);
- if (JSON_HEDLEY_UNLIKELY(!sax->start_array(std::size_t(-1))))
+ if (JSON_HEDLEY_UNLIKELY(!sax->start_array(static_cast<std::size_t>(-1))))
{
return false;
}
@@ -9026,7 +8808,7 @@
}
case 0x9F: // array (indefinite length)
- return get_cbor_array(std::size_t(-1), tag_handler);
+ return get_cbor_array(static_cast<std::size_t>(-1), tag_handler);
// map (0x00..0x17 pairs of data items follow)
case 0xA0:
@@ -9080,7 +8862,7 @@
}
case 0xBF: // map (indefinite length)
- return get_cbor_object(std::size_t(-1), tag_handler);
+ return get_cbor_object(static_cast<std::size_t>(-1), tag_handler);
case 0xC6: // tagged item
case 0xC7:
@@ -9464,7 +9246,7 @@
}
/*!
- @param[in] len the length of the array or std::size_t(-1) for an
+ @param[in] len the length of the array or static_cast<std::size_t>(-1) for an
array of indefinite size
@param[in] tag_handler how CBOR tags should be treated
@return whether array creation completed
@@ -9477,7 +9259,7 @@
return false;
}
- if (len != std::size_t(-1))
+ if (len != static_cast<std::size_t>(-1))
{
for (std::size_t i = 0; i < len; ++i)
{
@@ -9502,7 +9284,7 @@
}
/*!
- @param[in] len the length of the object or std::size_t(-1) for an
+ @param[in] len the length of the object or static_cast<std::size_t>(-1) for an
object of indefinite size
@param[in] tag_handler how CBOR tags should be treated
@return whether object creation completed
@@ -9518,7 +9300,7 @@
if (len != 0)
{
string_t key;
- if (len != std::size_t(-1))
+ if (len != static_cast<std::size_t>(-1))
{
for (std::size_t i = 0; i < len; ++i)
{
@@ -10528,7 +10310,7 @@
}
else
{
- if (JSON_HEDLEY_UNLIKELY(!sax->start_array(std::size_t(-1))))
+ if (JSON_HEDLEY_UNLIKELY(!sax->start_array(static_cast<std::size_t>(-1))))
{
return false;
}
@@ -10598,7 +10380,7 @@
}
else
{
- if (JSON_HEDLEY_UNLIKELY(!sax->start_object(std::size_t(-1))))
+ if (JSON_HEDLEY_UNLIKELY(!sax->start_object(static_cast<std::size_t>(-1))))
{
return false;
}
@@ -10729,7 +10511,7 @@
@return whether conversion completed
- @note This function needs to respect the system's endianess, because
+ @note This function needs to respect the system's endianness, because
bytes in CBOR, MessagePack, and UBJSON are stored in network order
(big endian) and therefore need reordering on little endian systems.
*/
@@ -10850,7 +10632,7 @@
std::string get_token_string() const
{
std::array<char, 3> cr{{}};
- (std::snprintf)(cr.data(), cr.size(), "%.2hhX", static_cast<unsigned char>(current)); // NOLINT(cppcoreguidelines-pro-type-vararg,hicpp-vararg)
+ static_cast<void>((std::snprintf)(cr.data(), cr.size(), "%.2hhX", static_cast<unsigned char>(current))); // NOLINT(cppcoreguidelines-pro-type-vararg,hicpp-vararg)
return std::string{cr.data()};
}
@@ -10902,8 +10684,8 @@
/// the number of characters read
std::size_t chars_read = 0;
- /// whether we can assume little endianess
- const bool is_little_endian = little_endianess();
+ /// whether we can assume little endianness
+ const bool is_little_endian = little_endianness();
/// the SAX parser
json_sax_t* sax = nullptr;
@@ -11111,7 +10893,7 @@
{
case token_type::begin_object:
{
- if (JSON_HEDLEY_UNLIKELY(!sax->start_object(std::size_t(-1))))
+ if (JSON_HEDLEY_UNLIKELY(!sax->start_object(static_cast<std::size_t>(-1))))
{
return false;
}
@@ -11156,7 +10938,7 @@
case token_type::begin_array:
{
- if (JSON_HEDLEY_UNLIKELY(!sax->start_array(std::size_t(-1))))
+ if (JSON_HEDLEY_UNLIKELY(!sax->start_array(static_cast<std::size_t>(-1))))
{
return false;
}
@@ -11621,7 +11403,7 @@
iterators in version 3.0.0 (see https://github.com/nlohmann/json/issues/593)
*/
template<typename BasicJsonType>
-class iter_impl
+class iter_impl // NOLINT(cppcoreguidelines-special-member-functions,hicpp-special-member-functions)
{
/// the iterator with BasicJsonType of different const-ness
using other_iter_impl = iter_impl<typename std::conditional<std::is_const<BasicJsonType>::value, typename std::remove_const<BasicJsonType>::type, const BasicJsonType>::type>;
@@ -12470,6 +12252,9 @@
namespace nlohmann
{
+
+/// @brief JSON Pointer defines a string syntax for identifying a specific value within a JSON document
+/// @sa https://json.nlohmann.me/api/json_pointer/
template<typename BasicJsonType>
class json_pointer
{
@@ -12478,45 +12263,14 @@
friend class basic_json;
public:
- /*!
- @brief create JSON pointer
-
- Create a JSON pointer according to the syntax described in
- [Section 3 of RFC6901](https://tools.ietf.org/html/rfc6901#section-3).
-
- @param[in] s string representing the JSON pointer; if omitted, the empty
- string is assumed which references the whole JSON value
-
- @throw parse_error.107 if the given JSON pointer @a s is nonempty and does
- not begin with a slash (`/`); see example below
-
- @throw parse_error.108 if a tilde (`~`) in the given JSON pointer @a s is
- not followed by `0` (representing `~`) or `1` (representing `/`); see
- example below
-
- @liveexample{The example shows the construction several valid JSON pointers
- as well as the exceptional behavior.,json_pointer}
-
- @since version 2.0.0
- */
+ /// @brief create JSON pointer
+ /// @sa https://json.nlohmann.me/api/json_pointer/json_pointer/
explicit json_pointer(const std::string& s = "")
: reference_tokens(split(s))
{}
- /*!
- @brief return a string representation of the JSON pointer
-
- @invariant For each JSON pointer `ptr`, it holds:
- @code {.cpp}
- ptr == json_pointer(ptr.to_string());
- @endcode
-
- @return a string representation of the JSON pointer
-
- @liveexample{The example shows the result of `to_string`.,json_pointer__to_string}
-
- @since version 2.0.0
- */
+ /// @brief return a string representation of the JSON pointer
+ /// @sa https://json.nlohmann.me/api/json_pointer/to_string/
std::string to_string() const
{
return std::accumulate(reference_tokens.begin(), reference_tokens.end(),
@@ -12527,28 +12281,15 @@
});
}
- /// @copydoc to_string()
+ /// @brief return a string representation of the JSON pointer
+ /// @sa https://json.nlohmann.me/api/json_pointer/operator_string/
operator std::string() const
{
return to_string();
}
- /*!
- @brief append another JSON pointer at the end of this JSON pointer
-
- @param[in] ptr JSON pointer to append
- @return JSON pointer with @a ptr appended
-
- @liveexample{The example shows the usage of `operator/=`.,json_pointer__operator_add}
-
- @complexity Linear in the length of @a ptr.
-
- @sa see @ref operator/=(std::string) to append a reference token
- @sa see @ref operator/=(std::size_t) to append an array index
- @sa see @ref operator/(const json_pointer&, const json_pointer&) for a binary operator
-
- @since version 3.6.0
- */
+ /// @brief append another JSON pointer at the end of this JSON pointer
+ /// @sa https://json.nlohmann.me/api/json_pointer/operator_slasheq/
json_pointer& operator/=(const json_pointer& ptr)
{
reference_tokens.insert(reference_tokens.end(),
@@ -12557,123 +12298,45 @@
return *this;
}
- /*!
- @brief append an unescaped reference token at the end of this JSON pointer
-
- @param[in] token reference token to append
- @return JSON pointer with @a token appended without escaping @a token
-
- @liveexample{The example shows the usage of `operator/=`.,json_pointer__operator_add}
-
- @complexity Amortized constant.
-
- @sa see @ref operator/=(const json_pointer&) to append a JSON pointer
- @sa see @ref operator/=(std::size_t) to append an array index
- @sa see @ref operator/(const json_pointer&, std::size_t) for a binary operator
-
- @since version 3.6.0
- */
+ /// @brief append an unescaped reference token at the end of this JSON pointer
+ /// @sa https://json.nlohmann.me/api/json_pointer/operator_slasheq/
json_pointer& operator/=(std::string token)
{
push_back(std::move(token));
return *this;
}
- /*!
- @brief append an array index at the end of this JSON pointer
-
- @param[in] array_idx array index to append
- @return JSON pointer with @a array_idx appended
-
- @liveexample{The example shows the usage of `operator/=`.,json_pointer__operator_add}
-
- @complexity Amortized constant.
-
- @sa see @ref operator/=(const json_pointer&) to append a JSON pointer
- @sa see @ref operator/=(std::string) to append a reference token
- @sa see @ref operator/(const json_pointer&, std::string) for a binary operator
-
- @since version 3.6.0
- */
+ /// @brief append an array index at the end of this JSON pointer
+ /// @sa https://json.nlohmann.me/api/json_pointer/operator_slasheq/
json_pointer& operator/=(std::size_t array_idx)
{
return *this /= std::to_string(array_idx);
}
- /*!
- @brief create a new JSON pointer by appending the right JSON pointer at the end of the left JSON pointer
-
- @param[in] lhs JSON pointer
- @param[in] rhs JSON pointer
- @return a new JSON pointer with @a rhs appended to @a lhs
-
- @liveexample{The example shows the usage of `operator/`.,json_pointer__operator_add_binary}
-
- @complexity Linear in the length of @a lhs and @a rhs.
-
- @sa see @ref operator/=(const json_pointer&) to append a JSON pointer
-
- @since version 3.6.0
- */
+ /// @brief create a new JSON pointer by appending the right JSON pointer at the end of the left JSON pointer
+ /// @sa https://json.nlohmann.me/api/json_pointer/operator_slash/
friend json_pointer operator/(const json_pointer& lhs,
const json_pointer& rhs)
{
return json_pointer(lhs) /= rhs;
}
- /*!
- @brief create a new JSON pointer by appending the unescaped token at the end of the JSON pointer
-
- @param[in] ptr JSON pointer
- @param[in] token reference token
- @return a new JSON pointer with unescaped @a token appended to @a ptr
-
- @liveexample{The example shows the usage of `operator/`.,json_pointer__operator_add_binary}
-
- @complexity Linear in the length of @a ptr.
-
- @sa see @ref operator/=(std::string) to append a reference token
-
- @since version 3.6.0
- */
- friend json_pointer operator/(const json_pointer& ptr, std::string token) // NOLINT(performance-unnecessary-value-param)
+ /// @brief create a new JSON pointer by appending the unescaped token at the end of the JSON pointer
+ /// @sa https://json.nlohmann.me/api/json_pointer/operator_slash/
+ friend json_pointer operator/(const json_pointer& lhs, std::string token) // NOLINT(performance-unnecessary-value-param)
{
- return json_pointer(ptr) /= std::move(token);
+ return json_pointer(lhs) /= std::move(token);
}
- /*!
- @brief create a new JSON pointer by appending the array-index-token at the end of the JSON pointer
-
- @param[in] ptr JSON pointer
- @param[in] array_idx array index
- @return a new JSON pointer with @a array_idx appended to @a ptr
-
- @liveexample{The example shows the usage of `operator/`.,json_pointer__operator_add_binary}
-
- @complexity Linear in the length of @a ptr.
-
- @sa see @ref operator/=(std::size_t) to append an array index
-
- @since version 3.6.0
- */
- friend json_pointer operator/(const json_pointer& ptr, std::size_t array_idx)
+ /// @brief create a new JSON pointer by appending the array-index-token at the end of the JSON pointer
+ /// @sa https://json.nlohmann.me/api/json_pointer/operator_slash/
+ friend json_pointer operator/(const json_pointer& lhs, std::size_t array_idx)
{
- return json_pointer(ptr) /= array_idx;
+ return json_pointer(lhs) /= array_idx;
}
- /*!
- @brief returns the parent of this JSON pointer
-
- @return parent of this JSON pointer; in case this JSON pointer is the root,
- the root itself is returned
-
- @complexity Linear in the length of the JSON pointer.
-
- @liveexample{The example shows the result of `parent_pointer` for different
- JSON Pointers.,json_pointer__parent_pointer}
-
- @since version 3.6.0
- */
+ /// @brief returns the parent of this JSON pointer
+ /// @sa https://json.nlohmann.me/api/json_pointer/parent_pointer/
json_pointer parent_pointer() const
{
if (empty())
@@ -12686,19 +12349,8 @@
return res;
}
- /*!
- @brief remove last reference token
-
- @pre not `empty()`
-
- @liveexample{The example shows the usage of `pop_back`.,json_pointer__pop_back}
-
- @complexity Constant.
-
- @throw out_of_range.405 if JSON pointer has no parent
-
- @since version 3.6.0
- */
+ /// @brief remove last reference token
+ /// @sa https://json.nlohmann.me/api/json_pointer/pop_back/
void pop_back()
{
if (JSON_HEDLEY_UNLIKELY(empty()))
@@ -12709,20 +12361,8 @@
reference_tokens.pop_back();
}
- /*!
- @brief return last reference token
-
- @pre not `empty()`
- @return last reference token
-
- @liveexample{The example shows the usage of `back`.,json_pointer__back}
-
- @complexity Constant.
-
- @throw out_of_range.405 if JSON pointer has no parent
-
- @since version 3.6.0
- */
+ /// @brief return last reference token
+ /// @sa https://json.nlohmann.me/api/json_pointer/back/
const std::string& back() const
{
if (JSON_HEDLEY_UNLIKELY(empty()))
@@ -12733,43 +12373,22 @@
return reference_tokens.back();
}
- /*!
- @brief append an unescaped token at the end of the reference pointer
-
- @param[in] token token to add
-
- @complexity Amortized constant.
-
- @liveexample{The example shows the result of `push_back` for different
- JSON Pointers.,json_pointer__push_back}
-
- @since version 3.6.0
- */
+ /// @brief append an unescaped token at the end of the reference pointer
+ /// @sa https://json.nlohmann.me/api/json_pointer/push_back/
void push_back(const std::string& token)
{
reference_tokens.push_back(token);
}
- /// @copydoc push_back(const std::string&)
+ /// @brief append an unescaped token at the end of the reference pointer
+ /// @sa https://json.nlohmann.me/api/json_pointer/push_back/
void push_back(std::string&& token)
{
reference_tokens.push_back(std::move(token));
}
- /*!
- @brief return whether pointer points to the root document
-
- @return true iff the JSON pointer points to the root document
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this function never throws exceptions.
-
- @liveexample{The example shows the result of `empty` for different JSON
- Pointers.,json_pointer__empty}
-
- @since version 3.6.0
- */
+ /// @brief return whether pointer points to the root document
+ /// @sa https://json.nlohmann.me/api/json_pointer/empty/
bool empty() const noexcept
{
return reference_tokens.empty();
@@ -14750,7 +14369,7 @@
{
std::size_t array_index = 0ul;
- const std::size_t embedded_document_size = std::accumulate(std::begin(value), std::end(value), std::size_t(0), [&array_index](std::size_t result, const typename BasicJsonType::array_t::value_type & el)
+ const std::size_t embedded_document_size = std::accumulate(std::begin(value), std::end(value), static_cast<std::size_t>(0), [&array_index](std::size_t result, const typename BasicJsonType::array_t::value_type & el)
{
return result + calc_bson_element_size(std::to_string(array_index++), el);
});
@@ -14794,7 +14413,7 @@
write_bson_entry_header(name, 0x05);
write_number<std::int32_t, true>(static_cast<std::int32_t>(value.size()));
- write_number(value.has_subtype() ? static_cast<std::uint8_t>(value.subtype()) : std::uint8_t(0x00));
+ write_number(value.has_subtype() ? static_cast<std::uint8_t>(value.subtype()) : static_cast<std::uint8_t>(0x00));
oa->write_characters(reinterpret_cast<const CharType*>(value.data()), value.size());
}
@@ -14900,7 +14519,7 @@
*/
static std::size_t calc_bson_object_size(const typename BasicJsonType::object_t& value)
{
- std::size_t document_size = std::accumulate(value.begin(), value.end(), std::size_t(0),
+ std::size_t document_size = std::accumulate(value.begin(), value.end(), static_cast<std::size_t>(0),
[](size_t result, const typename BasicJsonType::object_t::value_type & el)
{
return result += calc_bson_element_size(el.first, el.second);
@@ -15202,7 +14821,7 @@
@tparam OutputIsLittleEndian Set to true if output data is
required to be little endian
- @note This function needs to respect the system's endianess, because bytes
+ @note This function needs to respect the system's endianness, because bytes
in CBOR, MessagePack, and UBJSON are stored in network order (big
endian) and therefore need reordering on little endian systems.
*/
@@ -15292,8 +14911,8 @@
}
private:
- /// whether we can assume little endianess
- const bool is_little_endian = little_endianess();
+ /// whether we can assume little endianness
+ const bool is_little_endian = little_endianness();
/// the output
output_adapter_t<CharType> oa = nullptr;
@@ -15315,6 +14934,8 @@
#include <cstdio> // snprintf
#include <limits> // numeric_limits
#include <string> // string, char_traits
+#include <iomanip> // setfill, setw
+#include <sstream> // stringstream
#include <type_traits> // is_same
#include <utility> // move
@@ -16213,7 +15834,7 @@
//
// The documentation for 'std::to_chars' (https://en.cppreference.com/w/cpp/utility/to_chars)
// says "value is converted to a string as if by std::sprintf in the default ("C") locale"
- // and since sprintf promotes float's to double's, I think this is exactly what 'std::to_chars'
+ // and since sprintf promotes floats to doubles, I think this is exactly what 'std::to_chars'
// does.
// On the other hand, the documentation for 'std::to_chars' requires that "parsing the
// representation using the corresponding std::from_chars function recovers value exactly". That
@@ -16879,16 +16500,16 @@
if (codepoint <= 0xFFFF)
{
// NOLINTNEXTLINE(cppcoreguidelines-pro-type-vararg,hicpp-vararg)
- (std::snprintf)(string_buffer.data() + bytes, 7, "\\u%04x",
- static_cast<std::uint16_t>(codepoint));
+ static_cast<void>((std::snprintf)(string_buffer.data() + bytes, 7, "\\u%04x",
+ static_cast<std::uint16_t>(codepoint)));
bytes += 6;
}
else
{
// NOLINTNEXTLINE(cppcoreguidelines-pro-type-vararg,hicpp-vararg)
- (std::snprintf)(string_buffer.data() + bytes, 13, "\\u%04x\\u%04x",
- static_cast<std::uint16_t>(0xD7C0u + (codepoint >> 10u)),
- static_cast<std::uint16_t>(0xDC00u + (codepoint & 0x3FFu)));
+ static_cast<void>((std::snprintf)(string_buffer.data() + bytes, 13, "\\u%04x\\u%04x",
+ static_cast<std::uint16_t>(0xD7C0u + (codepoint >> 10u)),
+ static_cast<std::uint16_t>(0xDC00u + (codepoint & 0x3FFu))));
bytes += 12;
}
}
@@ -16923,10 +16544,9 @@
{
case error_handler_t::strict:
{
- std::string sn(9, '\0');
- // NOLINTNEXTLINE(cppcoreguidelines-pro-type-vararg,hicpp-vararg)
- (std::snprintf)(&sn[0], sn.size(), "%.2X", byte);
- JSON_THROW(type_error::create(316, "invalid UTF-8 byte at index " + std::to_string(i) + ": 0x" + sn, BasicJsonType()));
+ std::stringstream ss;
+ ss << std::uppercase << std::setfill('0') << std::setw(2) << std::hex << (byte | 0);
+ JSON_THROW(type_error::create(316, "invalid UTF-8 byte at index " + std::to_string(i) + ": 0x" + ss.str(), BasicJsonType()));
}
case error_handler_t::ignore:
@@ -17018,10 +16638,9 @@
{
case error_handler_t::strict:
{
- std::string sn(9, '\0');
- // NOLINTNEXTLINE(cppcoreguidelines-pro-type-vararg,hicpp-vararg)
- (std::snprintf)(&sn[0], sn.size(), "%.2X", static_cast<std::uint8_t>(s.back()));
- JSON_THROW(type_error::create(316, "incomplete UTF-8 string; last byte: 0x" + sn, BasicJsonType()));
+ std::stringstream ss;
+ ss << std::uppercase << std::setfill('0') << std::setw(2) << std::hex << (static_cast<std::uint8_t>(s.back()) | 0);
+ JSON_THROW(type_error::create(316, "incomplete UTF-8 string; last byte: 0x" + ss.str(), BasicJsonType()));
}
case error_handler_t::ignore:
@@ -17088,6 +16707,19 @@
}
}
+ // templates to avoid warnings about useless casts
+ template <typename NumberType, enable_if_t<std::is_signed<NumberType>::value, int> = 0>
+ bool is_negative_number(NumberType x)
+ {
+ return x < 0;
+ }
+
+ template < typename NumberType, enable_if_t <std::is_unsigned<NumberType>::value, int > = 0 >
+ bool is_negative_number(NumberType /*unused*/)
+ {
+ return false;
+ }
+
/*!
@brief dump an integer
@@ -17131,12 +16763,11 @@
// use a pointer to fill the buffer
auto buffer_ptr = number_buffer.begin(); // NOLINT(llvm-qualified-auto,readability-qualified-auto,cppcoreguidelines-pro-type-vararg,hicpp-vararg)
- const bool is_negative = std::is_signed<NumberType>::value && !(x >= 0); // see issue #755
number_unsigned_t abs_value;
unsigned int n_chars{};
- if (is_negative)
+ if (is_negative_number(x))
{
*buffer_ptr = '-';
abs_value = remove_sign(static_cast<number_integer_t>(x));
@@ -17153,7 +16784,7 @@
// spare 1 byte for '\0'
JSON_ASSERT(n_chars < number_buffer.size() - 1);
- // jump to the end to generate the string from backward
+ // jump to the end to generate the string from backward,
// so we later avoid reversing the result
buffer_ptr += n_chars;
@@ -17255,7 +16886,7 @@
o->write_characters(number_buffer.data(), static_cast<std::size_t>(len));
- // determine if need to append ".0"
+ // determine if we need to append ".0"
const bool value_is_int_like =
std::none_of(number_buffer.begin(), number_buffer.begin() + len + 1,
[](char c)
@@ -17410,10 +17041,10 @@
using key_type = Key;
using mapped_type = T;
using Container = std::vector<std::pair<const Key, T>, Allocator>;
- using typename Container::iterator;
- using typename Container::const_iterator;
- using typename Container::size_type;
- using typename Container::value_type;
+ using iterator = typename Container::iterator;
+ using const_iterator = typename Container::const_iterator;
+ using size_type = typename Container::size_type;
+ using value_type = typename Container::value_type;
// Explicit constructors instead of `using Container::Container`
// otherwise older compilers choke on it (GCC <= 5.5, xcode <= 9.4)
@@ -17494,16 +17125,55 @@
iterator erase(iterator pos)
{
- auto it = pos;
+ return erase(pos, std::next(pos));
+ }
- // Since we cannot move const Keys, re-construct them in place
- for (auto next = it; ++next != this->end(); ++it)
+ iterator erase(iterator first, iterator last)
+ {
+ const auto elements_affected = std::distance(first, last);
+ const auto offset = std::distance(Container::begin(), first);
+
+ // This is the start situation. We need to delete elements_affected
+ // elements (3 in this example: e, f, g), and need to return an
+ // iterator past the last deleted element (h in this example).
+ // Note that offset is the distance from the start of the vector
+ // to first. We will need this later.
+
+ // [ a, b, c, d, e, f, g, h, i, j ]
+ // ^ ^
+ // first last
+
+ // Since we cannot move const Keys, we re-construct them in place.
+ // We start at first and re-construct (viz. copy) the elements from
+ // the back of the vector. Example for first iteration:
+
+ // ,--------.
+ // v | destroy e and re-construct with h
+ // [ a, b, c, d, e, f, g, h, i, j ]
+ // ^ ^
+ // it it + elements_affected
+
+ for (auto it = first; std::next(it, elements_affected) != Container::end(); ++it)
{
- it->~value_type(); // Destroy but keep allocation
- new (&*it) value_type{std::move(*next)};
+ it->~value_type(); // destroy but keep allocation
+ new (&*it) value_type{std::move(*std::next(it, elements_affected))}; // "move" next element to it
}
- Container::pop_back();
- return pos;
+
+ // [ a, b, c, d, h, i, j, h, i, j ]
+ // ^ ^
+ // first last
+
+ // remove the unneeded elements at the end of the vector
+ Container::resize(this->size() - static_cast<size_type>(elements_affected));
+
+ // [ a, b, c, d, h, i, j ]
+ // ^ ^
+ // first last
+
+ // first is now pointing past the last deleted element, but we cannot
+ // use this iterator, because it may have been invalidated by the
+ // resize call. Instead, we can return begin() + offset.
+ return Container::begin() + offset;
}
size_type count(const Key& key) const
@@ -17592,69 +17262,7 @@
/*!
@brief a class to store JSON values
-@tparam ObjectType type for JSON objects (`std::map` by default; will be used
-in @ref object_t)
-@tparam ArrayType type for JSON arrays (`std::vector` by default; will be used
-in @ref array_t)
-@tparam StringType type for JSON strings and object keys (`std::string` by
-default; will be used in @ref string_t)
-@tparam BooleanType type for JSON booleans (`bool` by default; will be used
-in @ref boolean_t)
-@tparam NumberIntegerType type for JSON integer numbers (`int64_t` by
-default; will be used in @ref number_integer_t)
-@tparam NumberUnsignedType type for JSON unsigned integer numbers (@c
-`uint64_t` by default; will be used in @ref number_unsigned_t)
-@tparam NumberFloatType type for JSON floating-point numbers (`double` by
-default; will be used in @ref number_float_t)
-@tparam BinaryType type for packed binary data for compatibility with binary
-serialization formats (`std::vector<std::uint8_t>` by default; will be used in
-@ref binary_t)
-@tparam AllocatorType type of the allocator to use (`std::allocator` by
-default)
-@tparam JSONSerializer the serializer to resolve internal calls to `to_json()`
-and `from_json()` (@ref adl_serializer by default)
-
-@requirement The class satisfies the following concept requirements:
-- Basic
- - [DefaultConstructible](https://en.cppreference.com/w/cpp/named_req/DefaultConstructible):
- JSON values can be default constructed. The result will be a JSON null
- value.
- - [MoveConstructible](https://en.cppreference.com/w/cpp/named_req/MoveConstructible):
- A JSON value can be constructed from an rvalue argument.
- - [CopyConstructible](https://en.cppreference.com/w/cpp/named_req/CopyConstructible):
- A JSON value can be copy-constructed from an lvalue expression.
- - [MoveAssignable](https://en.cppreference.com/w/cpp/named_req/MoveAssignable):
- A JSON value van be assigned from an rvalue argument.
- - [CopyAssignable](https://en.cppreference.com/w/cpp/named_req/CopyAssignable):
- A JSON value can be copy-assigned from an lvalue expression.
- - [Destructible](https://en.cppreference.com/w/cpp/named_req/Destructible):
- JSON values can be destructed.
-- Layout
- - [StandardLayoutType](https://en.cppreference.com/w/cpp/named_req/StandardLayoutType):
- JSON values have
- [standard layout](https://en.cppreference.com/w/cpp/language/data_members#Standard_layout):
- All non-static data members are private and standard layout types, the
- class has no virtual functions or (virtual) base classes.
-- Library-wide
- - [EqualityComparable](https://en.cppreference.com/w/cpp/named_req/EqualityComparable):
- JSON values can be compared with `==`, see @ref
- operator==(const_reference,const_reference).
- - [LessThanComparable](https://en.cppreference.com/w/cpp/named_req/LessThanComparable):
- JSON values can be compared with `<`, see @ref
- operator<(const_reference,const_reference).
- - [Swappable](https://en.cppreference.com/w/cpp/named_req/Swappable):
- Any JSON lvalue or rvalue of can be swapped with any lvalue or rvalue of
- other compatible types, using unqualified function call @ref swap().
- - [NullablePointer](https://en.cppreference.com/w/cpp/named_req/NullablePointer):
- JSON values can be compared against `std::nullptr_t` objects which are used
- to model the `null` value.
-- Container
- - [Container](https://en.cppreference.com/w/cpp/named_req/Container):
- JSON values can be used like STL containers and provide iterator access.
- - [ReversibleContainer](https://en.cppreference.com/w/cpp/named_req/ReversibleContainer);
- JSON values can be used like STL containers and provide reverse iterator
- access.
-
+@internal
@invariant The member variables @a m_value and @a m_type have the following
relationship:
- If `m_type == value_t::object`, then `m_value.object != nullptr`.
@@ -17662,13 +17270,9 @@
- If `m_type == value_t::string`, then `m_value.string != nullptr`.
The invariants are checked by member function assert_invariant().
-@internal
@note ObjectType trick from https://stackoverflow.com/a/9860911
@endinternal
-@see [RFC 8259: The JavaScript Object Notation (JSON) Data Interchange
-Format](https://tools.ietf.org/html/rfc8259)
-
@since version 1.0.0
@nosubgrouping
@@ -17759,17 +17363,11 @@
/// Classes to implement user-defined exceptions.
/// @{
- /// @copydoc detail::exception
using exception = detail::exception;
- /// @copydoc detail::parse_error
using parse_error = detail::parse_error;
- /// @copydoc detail::invalid_iterator
using invalid_iterator = detail::invalid_iterator;
- /// @copydoc detail::type_error
using type_error = detail::type_error;
- /// @copydoc detail::out_of_range
using out_of_range = detail::out_of_range;
- /// @copydoc detail::other_error
using other_error = detail::other_error;
/// @}
@@ -17817,46 +17415,21 @@
/// @}
- /*!
- @brief returns the allocator associated with the container
- */
+ /// @brief returns the allocator associated with the container
+ /// @sa https://json.nlohmann.me/api/basic_json/get_allocator/
static allocator_type get_allocator()
{
return allocator_type();
}
- /*!
- @brief returns version information on the library
-
- This function returns a JSON object with information about the library,
- including the version number and information on the platform and compiler.
-
- @return JSON object holding version information
- key | description
- ----------- | ---------------
- `compiler` | Information on the used compiler. It is an object with the following keys: `c++` (the used C++ standard), `family` (the compiler family; possible values are `clang`, `icc`, `gcc`, `ilecpp`, `msvc`, `pgcpp`, `sunpro`, and `unknown`), and `version` (the compiler version).
- `copyright` | The copyright line for the library as string.
- `name` | The name of the library as string.
- `platform` | The used platform as string. Possible values are `win32`, `linux`, `apple`, `unix`, and `unknown`.
- `url` | The URL of the project as string.
- `version` | The version of the library. It is an object with the following keys: `major`, `minor`, and `patch` as defined by [Semantic Versioning](http://semver.org), and `string` (the version string).
-
- @liveexample{The following code shows an example output of the `meta()`
- function.,meta}
-
- @exceptionsafety Strong guarantee: if an exception is thrown, there are no
- changes to any JSON value.
-
- @complexity Constant.
-
- @since 2.1.0
- */
+ /// @brief returns version information on the library
+ /// @sa https://json.nlohmann.me/api/basic_json/meta/
JSON_HEDLEY_WARN_UNUSED_RESULT
static basic_json meta()
{
basic_json result;
- result["copyright"] = "(C) 2013-2021 Niels Lohmann";
+ result["copyright"] = "(C) 2013-2022 Niels Lohmann";
result["name"] = "JSON for Modern C++";
result["url"] = "https://github.com/nlohmann/json";
result["version"]["string"] =
@@ -17917,6 +17490,8 @@
/// the template arguments passed to class @ref basic_json.
/// @{
+ /// @brief object key comparator type
+ /// @sa https://json.nlohmann.me/api/basic_json/object_comparator_t/
#if defined(JSON_HAS_CPP_14)
// Use transparent comparator if possible, combined with perfect forwarding
// on find() and count() calls prevents unnecessary string construction.
@@ -17925,501 +17500,42 @@
using object_comparator_t = std::less<StringType>;
#endif
- /*!
- @brief a type for an object
-
- [RFC 8259](https://tools.ietf.org/html/rfc8259) describes JSON objects as follows:
- > An object is an unordered collection of zero or more name/value pairs,
- > where a name is a string and a value is a string, number, boolean, null,
- > object, or array.
-
- To store objects in C++, a type is defined by the template parameters
- described below.
-
- @tparam ObjectType the container to store objects (e.g., `std::map` or
- `std::unordered_map`)
- @tparam StringType the type of the keys or names (e.g., `std::string`).
- The comparison function `std::less<StringType>` is used to order elements
- inside the container.
- @tparam AllocatorType the allocator to use for objects (e.g.,
- `std::allocator`)
-
- #### Default type
-
- With the default values for @a ObjectType (`std::map`), @a StringType
- (`std::string`), and @a AllocatorType (`std::allocator`), the default
- value for @a object_t is:
-
- @code {.cpp}
- std::map<
- std::string, // key_type
- basic_json, // value_type
- std::less<std::string>, // key_compare
- std::allocator<std::pair<const std::string, basic_json>> // allocator_type
- >
- @endcode
-
- #### Behavior
-
- The choice of @a object_t influences the behavior of the JSON class. With
- the default type, objects have the following behavior:
-
- - When all names are unique, objects will be interoperable in the sense
- that all software implementations receiving that object will agree on
- the name-value mappings.
- - When the names within an object are not unique, it is unspecified which
- one of the values for a given key will be chosen. For instance,
- `{"key": 2, "key": 1}` could be equal to either `{"key": 1}` or
- `{"key": 2}`.
- - Internally, name/value pairs are stored in lexicographical order of the
- names. Objects will also be serialized (see @ref dump) in this order.
- For instance, `{"b": 1, "a": 2}` and `{"a": 2, "b": 1}` will be stored
- and serialized as `{"a": 2, "b": 1}`.
- - When comparing objects, the order of the name/value pairs is irrelevant.
- This makes objects interoperable in the sense that they will not be
- affected by these differences. For instance, `{"b": 1, "a": 2}` and
- `{"a": 2, "b": 1}` will be treated as equal.
-
- #### Limits
-
- [RFC 8259](https://tools.ietf.org/html/rfc8259) specifies:
- > An implementation may set limits on the maximum depth of nesting.
-
- In this class, the object's limit of nesting is not explicitly constrained.
- However, a maximum depth of nesting may be introduced by the compiler or
- runtime environment. A theoretical limit can be queried by calling the
- @ref max_size function of a JSON object.
-
- #### Storage
-
- Objects are stored as pointers in a @ref basic_json type. That is, for any
- access to object values, a pointer of type `object_t*` must be
- dereferenced.
-
- @sa see @ref array_t -- type for an array value
-
- @since version 1.0.0
-
- @note The order name/value pairs are added to the object is *not*
- preserved by the library. Therefore, iterating an object may return
- name/value pairs in a different order than they were originally stored. In
- fact, keys will be traversed in alphabetical order as `std::map` with
- `std::less` is used by default. Please note this behavior conforms to [RFC
- 8259](https://tools.ietf.org/html/rfc8259), because any order implements the
- specified "unordered" nature of JSON objects.
- */
+ /// @brief a type for an object
+ /// @sa https://json.nlohmann.me/api/basic_json/object_t/
using object_t = ObjectType<StringType,
basic_json,
object_comparator_t,
AllocatorType<std::pair<const StringType,
basic_json>>>;
- /*!
- @brief a type for an array
-
- [RFC 8259](https://tools.ietf.org/html/rfc8259) describes JSON arrays as follows:
- > An array is an ordered sequence of zero or more values.
-
- To store objects in C++, a type is defined by the template parameters
- explained below.
-
- @tparam ArrayType container type to store arrays (e.g., `std::vector` or
- `std::list`)
- @tparam AllocatorType allocator to use for arrays (e.g., `std::allocator`)
-
- #### Default type
-
- With the default values for @a ArrayType (`std::vector`) and @a
- AllocatorType (`std::allocator`), the default value for @a array_t is:
-
- @code {.cpp}
- std::vector<
- basic_json, // value_type
- std::allocator<basic_json> // allocator_type
- >
- @endcode
-
- #### Limits
-
- [RFC 8259](https://tools.ietf.org/html/rfc8259) specifies:
- > An implementation may set limits on the maximum depth of nesting.
-
- In this class, the array's limit of nesting is not explicitly constrained.
- However, a maximum depth of nesting may be introduced by the compiler or
- runtime environment. A theoretical limit can be queried by calling the
- @ref max_size function of a JSON array.
-
- #### Storage
-
- Arrays are stored as pointers in a @ref basic_json type. That is, for any
- access to array values, a pointer of type `array_t*` must be dereferenced.
-
- @sa see @ref object_t -- type for an object value
-
- @since version 1.0.0
- */
+ /// @brief a type for an array
+ /// @sa https://json.nlohmann.me/api/basic_json/array_t/
using array_t = ArrayType<basic_json, AllocatorType<basic_json>>;
- /*!
- @brief a type for a string
-
- [RFC 8259](https://tools.ietf.org/html/rfc8259) describes JSON strings as follows:
- > A string is a sequence of zero or more Unicode characters.
-
- To store objects in C++, a type is defined by the template parameter
- described below. Unicode values are split by the JSON class into
- byte-sized characters during deserialization.
-
- @tparam StringType the container to store strings (e.g., `std::string`).
- Note this container is used for keys/names in objects, see @ref object_t.
-
- #### Default type
-
- With the default values for @a StringType (`std::string`), the default
- value for @a string_t is:
-
- @code {.cpp}
- std::string
- @endcode
-
- #### Encoding
-
- Strings are stored in UTF-8 encoding. Therefore, functions like
- `std::string::size()` or `std::string::length()` return the number of
- bytes in the string rather than the number of characters or glyphs.
-
- #### String comparison
-
- [RFC 8259](https://tools.ietf.org/html/rfc8259) states:
- > Software implementations are typically required to test names of object
- > members for equality. Implementations that transform the textual
- > representation into sequences of Unicode code units and then perform the
- > comparison numerically, code unit by code unit, are interoperable in the
- > sense that implementations will agree in all cases on equality or
- > inequality of two strings. For example, implementations that compare
- > strings with escaped characters unconverted may incorrectly find that
- > `"a\\b"` and `"a\u005Cb"` are not equal.
-
- This implementation is interoperable as it does compare strings code unit
- by code unit.
-
- #### Storage
-
- String values are stored as pointers in a @ref basic_json type. That is,
- for any access to string values, a pointer of type `string_t*` must be
- dereferenced.
-
- @since version 1.0.0
- */
+ /// @brief a type for a string
+ /// @sa https://json.nlohmann.me/api/basic_json/string_t/
using string_t = StringType;
- /*!
- @brief a type for a boolean
-
- [RFC 8259](https://tools.ietf.org/html/rfc8259) implicitly describes a boolean as a
- type which differentiates the two literals `true` and `false`.
-
- To store objects in C++, a type is defined by the template parameter @a
- BooleanType which chooses the type to use.
-
- #### Default type
-
- With the default values for @a BooleanType (`bool`), the default value for
- @a boolean_t is:
-
- @code {.cpp}
- bool
- @endcode
-
- #### Storage
-
- Boolean values are stored directly inside a @ref basic_json type.
-
- @since version 1.0.0
- */
+ /// @brief a type for a boolean
+ /// @sa https://json.nlohmann.me/api/basic_json/boolean_t/
using boolean_t = BooleanType;
- /*!
- @brief a type for a number (integer)
-
- [RFC 8259](https://tools.ietf.org/html/rfc8259) describes numbers as follows:
- > The representation of numbers is similar to that used in most
- > programming languages. A number is represented in base 10 using decimal
- > digits. It contains an integer component that may be prefixed with an
- > optional minus sign, which may be followed by a fraction part and/or an
- > exponent part. Leading zeros are not allowed. (...) Numeric values that
- > cannot be represented in the grammar below (such as Infinity and NaN)
- > are not permitted.
-
- This description includes both integer and floating-point numbers.
- However, C++ allows more precise storage if it is known whether the number
- is a signed integer, an unsigned integer or a floating-point number.
- Therefore, three different types, @ref number_integer_t, @ref
- number_unsigned_t and @ref number_float_t are used.
-
- To store integer numbers in C++, a type is defined by the template
- parameter @a NumberIntegerType which chooses the type to use.
-
- #### Default type
-
- With the default values for @a NumberIntegerType (`int64_t`), the default
- value for @a number_integer_t is:
-
- @code {.cpp}
- int64_t
- @endcode
-
- #### Default behavior
-
- - The restrictions about leading zeros is not enforced in C++. Instead,
- leading zeros in integer literals lead to an interpretation as octal
- number. Internally, the value will be stored as decimal number. For
- instance, the C++ integer literal `010` will be serialized to `8`.
- During deserialization, leading zeros yield an error.
- - Not-a-number (NaN) values will be serialized to `null`.
-
- #### Limits
-
- [RFC 8259](https://tools.ietf.org/html/rfc8259) specifies:
- > An implementation may set limits on the range and precision of numbers.
-
- When the default type is used, the maximal integer number that can be
- stored is `9223372036854775807` (INT64_MAX) and the minimal integer number
- that can be stored is `-9223372036854775808` (INT64_MIN). Integer numbers
- that are out of range will yield over/underflow when used in a
- constructor. During deserialization, too large or small integer numbers
- will be automatically be stored as @ref number_unsigned_t or @ref
- number_float_t.
-
- [RFC 8259](https://tools.ietf.org/html/rfc8259) further states:
- > Note that when such software is used, numbers that are integers and are
- > in the range \f$[-2^{53}+1, 2^{53}-1]\f$ are interoperable in the sense
- > that implementations will agree exactly on their numeric values.
-
- As this range is a subrange of the exactly supported range [INT64_MIN,
- INT64_MAX], this class's integer type is interoperable.
-
- #### Storage
-
- Integer number values are stored directly inside a @ref basic_json type.
-
- @sa see @ref number_float_t -- type for number values (floating-point)
-
- @sa see @ref number_unsigned_t -- type for number values (unsigned integer)
-
- @since version 1.0.0
- */
+ /// @brief a type for a number (integer)
+ /// @sa https://json.nlohmann.me/api/basic_json/number_integer_t/
using number_integer_t = NumberIntegerType;
- /*!
- @brief a type for a number (unsigned)
-
- [RFC 8259](https://tools.ietf.org/html/rfc8259) describes numbers as follows:
- > The representation of numbers is similar to that used in most
- > programming languages. A number is represented in base 10 using decimal
- > digits. It contains an integer component that may be prefixed with an
- > optional minus sign, which may be followed by a fraction part and/or an
- > exponent part. Leading zeros are not allowed. (...) Numeric values that
- > cannot be represented in the grammar below (such as Infinity and NaN)
- > are not permitted.
-
- This description includes both integer and floating-point numbers.
- However, C++ allows more precise storage if it is known whether the number
- is a signed integer, an unsigned integer or a floating-point number.
- Therefore, three different types, @ref number_integer_t, @ref
- number_unsigned_t and @ref number_float_t are used.
-
- To store unsigned integer numbers in C++, a type is defined by the
- template parameter @a NumberUnsignedType which chooses the type to use.
-
- #### Default type
-
- With the default values for @a NumberUnsignedType (`uint64_t`), the
- default value for @a number_unsigned_t is:
-
- @code {.cpp}
- uint64_t
- @endcode
-
- #### Default behavior
-
- - The restrictions about leading zeros is not enforced in C++. Instead,
- leading zeros in integer literals lead to an interpretation as octal
- number. Internally, the value will be stored as decimal number. For
- instance, the C++ integer literal `010` will be serialized to `8`.
- During deserialization, leading zeros yield an error.
- - Not-a-number (NaN) values will be serialized to `null`.
-
- #### Limits
-
- [RFC 8259](https://tools.ietf.org/html/rfc8259) specifies:
- > An implementation may set limits on the range and precision of numbers.
-
- When the default type is used, the maximal integer number that can be
- stored is `18446744073709551615` (UINT64_MAX) and the minimal integer
- number that can be stored is `0`. Integer numbers that are out of range
- will yield over/underflow when used in a constructor. During
- deserialization, too large or small integer numbers will be automatically
- be stored as @ref number_integer_t or @ref number_float_t.
-
- [RFC 8259](https://tools.ietf.org/html/rfc8259) further states:
- > Note that when such software is used, numbers that are integers and are
- > in the range \f$[-2^{53}+1, 2^{53}-1]\f$ are interoperable in the sense
- > that implementations will agree exactly on their numeric values.
-
- As this range is a subrange (when considered in conjunction with the
- number_integer_t type) of the exactly supported range [0, UINT64_MAX],
- this class's integer type is interoperable.
-
- #### Storage
-
- Integer number values are stored directly inside a @ref basic_json type.
-
- @sa see @ref number_float_t -- type for number values (floating-point)
- @sa see @ref number_integer_t -- type for number values (integer)
-
- @since version 2.0.0
- */
+ /// @brief a type for a number (unsigned)
+ /// @sa https://json.nlohmann.me/api/basic_json/number_unsigned_t/
using number_unsigned_t = NumberUnsignedType;
- /*!
- @brief a type for a number (floating-point)
-
- [RFC 8259](https://tools.ietf.org/html/rfc8259) describes numbers as follows:
- > The representation of numbers is similar to that used in most
- > programming languages. A number is represented in base 10 using decimal
- > digits. It contains an integer component that may be prefixed with an
- > optional minus sign, which may be followed by a fraction part and/or an
- > exponent part. Leading zeros are not allowed. (...) Numeric values that
- > cannot be represented in the grammar below (such as Infinity and NaN)
- > are not permitted.
-
- This description includes both integer and floating-point numbers.
- However, C++ allows more precise storage if it is known whether the number
- is a signed integer, an unsigned integer or a floating-point number.
- Therefore, three different types, @ref number_integer_t, @ref
- number_unsigned_t and @ref number_float_t are used.
-
- To store floating-point numbers in C++, a type is defined by the template
- parameter @a NumberFloatType which chooses the type to use.
-
- #### Default type
-
- With the default values for @a NumberFloatType (`double`), the default
- value for @a number_float_t is:
-
- @code {.cpp}
- double
- @endcode
-
- #### Default behavior
-
- - The restrictions about leading zeros is not enforced in C++. Instead,
- leading zeros in floating-point literals will be ignored. Internally,
- the value will be stored as decimal number. For instance, the C++
- floating-point literal `01.2` will be serialized to `1.2`. During
- deserialization, leading zeros yield an error.
- - Not-a-number (NaN) values will be serialized to `null`.
-
- #### Limits
-
- [RFC 8259](https://tools.ietf.org/html/rfc8259) states:
- > This specification allows implementations to set limits on the range and
- > precision of numbers accepted. Since software that implements IEEE
- > 754-2008 binary64 (double precision) numbers is generally available and
- > widely used, good interoperability can be achieved by implementations
- > that expect no more precision or range than these provide, in the sense
- > that implementations will approximate JSON numbers within the expected
- > precision.
-
- This implementation does exactly follow this approach, as it uses double
- precision floating-point numbers. Note values smaller than
- `-1.79769313486232e+308` and values greater than `1.79769313486232e+308`
- will be stored as NaN internally and be serialized to `null`.
-
- #### Storage
-
- Floating-point number values are stored directly inside a @ref basic_json
- type.
-
- @sa see @ref number_integer_t -- type for number values (integer)
-
- @sa see @ref number_unsigned_t -- type for number values (unsigned integer)
-
- @since version 1.0.0
- */
+ /// @brief a type for a number (floating-point)
+ /// @sa https://json.nlohmann.me/api/basic_json/number_float_t/
using number_float_t = NumberFloatType;
- /*!
- @brief a type for a packed binary type
-
- This type is a type designed to carry binary data that appears in various
- serialized formats, such as CBOR's Major Type 2, MessagePack's bin, and
- BSON's generic binary subtype. This type is NOT a part of standard JSON and
- exists solely for compatibility with these binary types. As such, it is
- simply defined as an ordered sequence of zero or more byte values.
-
- Additionally, as an implementation detail, the subtype of the binary data is
- carried around as a `std::uint8_t`, which is compatible with both of the
- binary data formats that use binary subtyping, (though the specific
- numbering is incompatible with each other, and it is up to the user to
- translate between them).
-
- [CBOR's RFC 7049](https://tools.ietf.org/html/rfc7049) describes this type
- as:
- > Major type 2: a byte string. The string's length in bytes is represented
- > following the rules for positive integers (major type 0).
-
- [MessagePack's documentation on the bin type
- family](https://github.com/msgpack/msgpack/blob/master/spec.md#bin-format-family)
- describes this type as:
- > Bin format family stores an byte array in 2, 3, or 5 bytes of extra bytes
- > in addition to the size of the byte array.
-
- [BSON's specifications](http://bsonspec.org/spec.html) describe several
- binary types; however, this type is intended to represent the generic binary
- type which has the description:
- > Generic binary subtype - This is the most commonly used binary subtype and
- > should be the 'default' for drivers and tools.
-
- None of these impose any limitations on the internal representation other
- than the basic unit of storage be some type of array whose parts are
- decomposable into bytes.
-
- The default representation of this binary format is a
- `std::vector<std::uint8_t>`, which is a very common way to represent a byte
- array in modern C++.
-
- #### Default type
-
- The default values for @a BinaryType is `std::vector<std::uint8_t>`
-
- #### Storage
-
- Binary Arrays are stored as pointers in a @ref basic_json type. That is,
- for any access to array values, a pointer of the type `binary_t*` must be
- dereferenced.
-
- #### Notes on subtypes
-
- - CBOR
- - Binary values are represented as byte strings. Subtypes are serialized
- as tagged values.
- - MessagePack
- - If a subtype is given and the binary array contains exactly 1, 2, 4, 8,
- or 16 elements, the fixext family (fixext1, fixext2, fixext4, fixext8)
- is used. For other sizes, the ext family (ext8, ext16, ext32) is used.
- The subtype is then added as singed 8-bit integer.
- - If no subtype is given, the bin family (bin8, bin16, bin32) is used.
- - BSON
- - If a subtype is given, it is used and added as unsigned 8-bit integer.
- - If no subtype is given, the generic binary subtype 0x00 is used.
-
- @sa see @ref binary -- create a binary array
-
- @since version 3.8.0
- */
+ /// @brief a type for a packed binary type
+ /// @sa https://json.nlohmann.me/api/basic_json/binary_t/
using binary_t = nlohmann::byte_container_with_subtype<BinaryType>;
+
/// @}
private:
@@ -18532,25 +17648,25 @@
case value_t::boolean:
{
- boolean = boolean_t(false);
+ boolean = static_cast<boolean_t>(false);
break;
}
case value_t::number_integer:
{
- number_integer = number_integer_t(0);
+ number_integer = static_cast<number_integer_t>(0);
break;
}
case value_t::number_unsigned:
{
- number_unsigned = number_unsigned_t(0);
+ number_unsigned = static_cast<number_unsigned_t>(0);
break;
}
case value_t::number_float:
{
- number_float = number_float_t(0.0);
+ number_float = static_cast<number_float_t>(0.0);
break;
}
@@ -18566,7 +17682,7 @@
object = nullptr; // silence warning, see #821
if (JSON_HEDLEY_UNLIKELY(t == value_t::null))
{
- JSON_THROW(other_error::create(500, "961c151d2e87f2686a955a9be24d316f1362bf21 3.10.4", basic_json())); // LCOV_EXCL_LINE
+ JSON_THROW(other_error::create(500, "961c151d2e87f2686a955a9be24d316f1362bf21 3.10.5", basic_json())); // LCOV_EXCL_LINE
}
break;
}
@@ -18574,64 +17690,34 @@
}
/// constructor for strings
- json_value(const string_t& value)
- {
- string = create<string_t>(value);
- }
+ json_value(const string_t& value) : string(create<string_t>(value)) {}
/// constructor for rvalue strings
- json_value(string_t&& value)
- {
- string = create<string_t>(std::move(value));
- }
+ json_value(string_t&& value) : string(create<string_t>(std::move(value))) {}
/// constructor for objects
- json_value(const object_t& value)
- {
- object = create<object_t>(value);
- }
+ json_value(const object_t& value) : object(create<object_t>(value)) {}
/// constructor for rvalue objects
- json_value(object_t&& value)
- {
- object = create<object_t>(std::move(value));
- }
+ json_value(object_t&& value) : object(create<object_t>(std::move(value))) {}
/// constructor for arrays
- json_value(const array_t& value)
- {
- array = create<array_t>(value);
- }
+ json_value(const array_t& value) : array(create<array_t>(value)) {}
/// constructor for rvalue arrays
- json_value(array_t&& value)
- {
- array = create<array_t>(std::move(value));
- }
+ json_value(array_t&& value) : array(create<array_t>(std::move(value))) {}
/// constructor for binary arrays
- json_value(const typename binary_t::container_type& value)
- {
- binary = create<binary_t>(value);
- }
+ json_value(const typename binary_t::container_type& value) : binary(create<binary_t>(value)) {}
/// constructor for rvalue binary arrays
- json_value(typename binary_t::container_type&& value)
- {
- binary = create<binary_t>(std::move(value));
- }
+ json_value(typename binary_t::container_type&& value) : binary(create<binary_t>(std::move(value))) {}
/// constructor for binary arrays (internal type)
- json_value(const binary_t& value)
- {
- binary = create<binary_t>(value);
- }
+ json_value(const binary_t& value) : binary(create<binary_t>(value)) {}
/// constructor for rvalue binary arrays (internal type)
- json_value(binary_t&& value)
- {
- binary = create<binary_t>(std::move(value));
- }
+ json_value(binary_t&& value) : binary(create<binary_t>(std::move(value))) {}
void destroy(value_t t)
{
@@ -18809,23 +17895,23 @@
#endif
}
- iterator set_parents(iterator it, typename iterator::difference_type count)
+ iterator set_parents(iterator it, typename iterator::difference_type count_set_parents)
{
#if JSON_DIAGNOSTICS
- for (typename iterator::difference_type i = 0; i < count; ++i)
+ for (typename iterator::difference_type i = 0; i < count_set_parents; ++i)
{
(it + i)->m_parent = this;
}
#else
- static_cast<void>(count);
+ static_cast<void>(count_set_parents);
#endif
return it;
}
- reference set_parent(reference j, std::size_t old_capacity = std::size_t(-1))
+ reference set_parent(reference j, std::size_t old_capacity = static_cast<std::size_t>(-1))
{
#if JSON_DIAGNOSTICS
- if (old_capacity != std::size_t(-1))
+ if (old_capacity != static_cast<std::size_t>(-1))
{
// see https://github.com/nlohmann/json/issues/2838
JSON_ASSERT(type() == value_t::array);
@@ -18865,72 +17951,12 @@
// JSON parser callback //
//////////////////////////
- /*!
- @brief parser event types
-
- The parser callback distinguishes the following events:
- - `object_start`: the parser read `{` and started to process a JSON object
- - `key`: the parser read a key of a value in an object
- - `object_end`: the parser read `}` and finished processing a JSON object
- - `array_start`: the parser read `[` and started to process a JSON array
- - `array_end`: the parser read `]` and finished processing a JSON array
- - `value`: the parser finished reading a JSON value
-
- @image html callback_events.png "Example when certain parse events are triggered"
-
- @sa see @ref parser_callback_t for more information and examples
- */
+ /// @brief parser event types
+ /// @sa https://json.nlohmann.me/api/basic_json/parse_event_t/
using parse_event_t = detail::parse_event_t;
- /*!
- @brief per-element parser callback type
-
- With a parser callback function, the result of parsing a JSON text can be
- influenced. When passed to @ref parse, it is called on certain events
- (passed as @ref parse_event_t via parameter @a event) with a set recursion
- depth @a depth and context JSON value @a parsed. The return value of the
- callback function is a boolean indicating whether the element that emitted
- the callback shall be kept or not.
-
- We distinguish six scenarios (determined by the event type) in which the
- callback function can be called. The following table describes the values
- of the parameters @a depth, @a event, and @a parsed.
-
- parameter @a event | description | parameter @a depth | parameter @a parsed
- ------------------ | ----------- | ------------------ | -------------------
- parse_event_t::object_start | the parser read `{` and started to process a JSON object | depth of the parent of the JSON object | a JSON value with type discarded
- parse_event_t::key | the parser read a key of a value in an object | depth of the currently parsed JSON object | a JSON string containing the key
- parse_event_t::object_end | the parser read `}` and finished processing a JSON object | depth of the parent of the JSON object | the parsed JSON object
- parse_event_t::array_start | the parser read `[` and started to process a JSON array | depth of the parent of the JSON array | a JSON value with type discarded
- parse_event_t::array_end | the parser read `]` and finished processing a JSON array | depth of the parent of the JSON array | the parsed JSON array
- parse_event_t::value | the parser finished reading a JSON value | depth of the value | the parsed JSON value
-
- @image html callback_events.png "Example when certain parse events are triggered"
-
- Discarding a value (i.e., returning `false`) has different effects
- depending on the context in which function was called:
-
- - Discarded values in structured types are skipped. That is, the parser
- will behave as if the discarded value was never read.
- - In case a value outside a structured type is skipped, it is replaced
- with `null`. This case happens if the top-level element is skipped.
-
- @param[in] depth the depth of the recursion during parsing
-
- @param[in] event an event of type parse_event_t indicating the context in
- the callback function has been called
-
- @param[in,out] parsed the current intermediate parse result; note that
- writing to this value has no effect for parse_event_t::key events
-
- @return Whether the JSON value which called the function during parsing
- should be kept (`true`) or not (`false`). In the latter case, it is either
- skipped completely or replaced by an empty discarded object.
-
- @sa see @ref parse for examples
-
- @since version 1.0.0
- */
+ /// @brief per-element parser callback type
+ /// @sa https://json.nlohmann.me/api/basic_json/parser_callback_t/
using parser_callback_t = detail::parser_callback_t<basic_json>;
//////////////////
@@ -18942,128 +17968,24 @@
/// assignment, static functions creating objects, and the destructor.
/// @{
- /*!
- @brief create an empty value with a given type
-
- Create an empty JSON value with a given type. The value will be default
- initialized with an empty value which depends on the type:
-
- Value type | initial value
- ----------- | -------------
- null | `null`
- boolean | `false`
- string | `""`
- number | `0`
- object | `{}`
- array | `[]`
- binary | empty array
-
- @param[in] v the type of the value to create
-
- @complexity Constant.
-
- @exceptionsafety Strong guarantee: if an exception is thrown, there are no
- changes to any JSON value.
-
- @liveexample{The following code shows the constructor for different @ref
- value_t values,basic_json__value_t}
-
- @sa see @ref clear() -- restores the postcondition of this constructor
-
- @since version 1.0.0
- */
+ /// @brief create an empty value with a given type
+ /// @sa https://json.nlohmann.me/api/basic_json/basic_json/
basic_json(const value_t v)
: m_type(v), m_value(v)
{
assert_invariant();
}
- /*!
- @brief create a null object
-
- Create a `null` JSON value. It either takes a null pointer as parameter
- (explicitly creating `null`) or no parameter (implicitly creating `null`).
- The passed null pointer itself is not read -- it is only used to choose
- the right constructor.
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this constructor never throws
- exceptions.
-
- @liveexample{The following code shows the constructor with and without a
- null pointer parameter.,basic_json__nullptr_t}
-
- @since version 1.0.0
- */
+ /// @brief create a null object
+ /// @sa https://json.nlohmann.me/api/basic_json/basic_json/
basic_json(std::nullptr_t = nullptr) noexcept
: basic_json(value_t::null)
{
assert_invariant();
}
- /*!
- @brief create a JSON value
-
- This is a "catch all" constructor for all compatible JSON types; that is,
- types for which a `to_json()` method exists. The constructor forwards the
- parameter @a val to that method (to `json_serializer<U>::to_json` method
- with `U = uncvref_t<CompatibleType>`, to be exact).
-
- Template type @a CompatibleType includes, but is not limited to, the
- following types:
- - **arrays**: @ref array_t and all kinds of compatible containers such as
- `std::vector`, `std::deque`, `std::list`, `std::forward_list`,
- `std::array`, `std::valarray`, `std::set`, `std::unordered_set`,
- `std::multiset`, and `std::unordered_multiset` with a `value_type` from
- which a @ref basic_json value can be constructed.
- - **objects**: @ref object_t and all kinds of compatible associative
- containers such as `std::map`, `std::unordered_map`, `std::multimap`,
- and `std::unordered_multimap` with a `key_type` compatible to
- @ref string_t and a `value_type` from which a @ref basic_json value can
- be constructed.
- - **strings**: @ref string_t, string literals, and all compatible string
- containers can be used.
- - **numbers**: @ref number_integer_t, @ref number_unsigned_t,
- @ref number_float_t, and all convertible number types such as `int`,
- `size_t`, `int64_t`, `float` or `double` can be used.
- - **boolean**: @ref boolean_t / `bool` can be used.
- - **binary**: @ref binary_t / `std::vector<std::uint8_t>` may be used,
- unfortunately because string literals cannot be distinguished from binary
- character arrays by the C++ type system, all types compatible with `const
- char*` will be directed to the string constructor instead. This is both
- for backwards compatibility, and due to the fact that a binary type is not
- a standard JSON type.
-
- See the examples below.
-
- @tparam CompatibleType a type such that:
- - @a CompatibleType is not derived from `std::istream`,
- - @a CompatibleType is not @ref basic_json (to avoid hijacking copy/move
- constructors),
- - @a CompatibleType is not a different @ref basic_json type (i.e. with different template arguments)
- - @a CompatibleType is not a @ref basic_json nested type (e.g.,
- @ref json_pointer, @ref iterator, etc ...)
- - `json_serializer<U>` has a `to_json(basic_json_t&, CompatibleType&&)` method
-
- @tparam U = `uncvref_t<CompatibleType>`
-
- @param[in] val the value to be forwarded to the respective constructor
-
- @complexity Usually linear in the size of the passed @a val, also
- depending on the implementation of the called `to_json()`
- method.
-
- @exceptionsafety Depends on the called constructor. For types directly
- supported by the library (i.e., all types for which no `to_json()` function
- was provided), strong guarantee holds: if an exception is thrown, there are
- no changes to any JSON value.
-
- @liveexample{The following code shows the constructor with several
- compatible types.,basic_json__CompatibleType}
-
- @since version 2.1.0
- */
+ /// @brief create a JSON value from compatible types
+ /// @sa https://json.nlohmann.me/api/basic_json/basic_json/
template < typename CompatibleType,
typename U = detail::uncvref_t<CompatibleType>,
detail::enable_if_t <
@@ -19077,32 +17999,8 @@
assert_invariant();
}
- /*!
- @brief create a JSON value from an existing one
-
- This is a constructor for existing @ref basic_json types.
- It does not hijack copy/move constructors, since the parameter has different
- template arguments than the current ones.
-
- The constructor tries to convert the internal @ref m_value of the parameter.
-
- @tparam BasicJsonType a type such that:
- - @a BasicJsonType is a @ref basic_json type.
- - @a BasicJsonType has different template arguments than @ref basic_json_t.
-
- @param[in] val the @ref basic_json value to be converted.
-
- @complexity Usually linear in the size of the passed @a val, also
- depending on the implementation of the called `to_json()`
- method.
-
- @exceptionsafety Depends on the called constructor. For types directly
- supported by the library (i.e., all types for which no `to_json()` function
- was provided), strong guarantee holds: if an exception is thrown, there are
- no changes to any JSON value.
-
- @since version 3.2.0
- */
+ /// @brief create a JSON value from an existing one
+ /// @sa https://json.nlohmann.me/api/basic_json/basic_json/
template < typename BasicJsonType,
detail::enable_if_t <
detail::is_basic_json<BasicJsonType>::value&& !std::is_same<basic_json, BasicJsonType>::value, int > = 0 >
@@ -19156,80 +18054,8 @@
assert_invariant();
}
- /*!
- @brief create a container (array or object) from an initializer list
-
- Creates a JSON value of type array or object from the passed initializer
- list @a init. In case @a type_deduction is `true` (default), the type of
- the JSON value to be created is deducted from the initializer list @a init
- according to the following rules:
-
- 1. If the list is empty, an empty JSON object value `{}` is created.
- 2. If the list consists of pairs whose first element is a string, a JSON
- object value is created where the first elements of the pairs are
- treated as keys and the second elements are as values.
- 3. In all other cases, an array is created.
-
- The rules aim to create the best fit between a C++ initializer list and
- JSON values. The rationale is as follows:
-
- 1. The empty initializer list is written as `{}` which is exactly an empty
- JSON object.
- 2. C++ has no way of describing mapped types other than to list a list of
- pairs. As JSON requires that keys must be of type string, rule 2 is the
- weakest constraint one can pose on initializer lists to interpret them
- as an object.
- 3. In all other cases, the initializer list could not be interpreted as
- JSON object type, so interpreting it as JSON array type is safe.
-
- With the rules described above, the following JSON values cannot be
- expressed by an initializer list:
-
- - the empty array (`[]`): use @ref array(initializer_list_t)
- with an empty initializer list in this case
- - arrays whose elements satisfy rule 2: use @ref
- array(initializer_list_t) with the same initializer list
- in this case
-
- @note When used without parentheses around an empty initializer list, @ref
- basic_json() is called instead of this function, yielding the JSON null
- value.
-
- @param[in] init initializer list with JSON values
-
- @param[in] type_deduction internal parameter; when set to `true`, the type
- of the JSON value is deducted from the initializer list @a init; when set
- to `false`, the type provided via @a manual_type is forced. This mode is
- used by the functions @ref array(initializer_list_t) and
- @ref object(initializer_list_t).
-
- @param[in] manual_type internal parameter; when @a type_deduction is set
- to `false`, the created JSON value will use the provided type (only @ref
- value_t::array and @ref value_t::object are valid); when @a type_deduction
- is set to `true`, this parameter has no effect
-
- @throw type_error.301 if @a type_deduction is `false`, @a manual_type is
- `value_t::object`, but @a init contains an element which is not a pair
- whose first element is a string. In this case, the constructor could not
- create an object. If @a type_deduction would have be `true`, an array
- would have been created. See @ref object(initializer_list_t)
- for an example.
-
- @complexity Linear in the size of the initializer list @a init.
-
- @exceptionsafety Strong guarantee: if an exception is thrown, there are no
- changes to any JSON value.
-
- @liveexample{The example below shows how JSON values are created from
- initializer lists.,basic_json__list_init_t}
-
- @sa see @ref array(initializer_list_t) -- create a JSON array
- value from an initializer list
- @sa see @ref object(initializer_list_t) -- create a JSON object
- value from an initializer list
-
- @since version 1.0.0
- */
+ /// @brief create a container (array or object) from an initializer list
+ /// @sa https://json.nlohmann.me/api/basic_json/basic_json/
basic_json(initializer_list_t init,
bool type_deduction = true,
value_t manual_type = value_t::array)
@@ -19283,33 +18109,8 @@
assert_invariant();
}
- /*!
- @brief explicitly create a binary array (without subtype)
-
- Creates a JSON binary array value from a given binary container. Binary
- values are part of various binary formats, such as CBOR, MessagePack, and
- BSON. This constructor is used to create a value for serialization to those
- formats.
-
- @note Note, this function exists because of the difficulty in correctly
- specifying the correct template overload in the standard value ctor, as both
- JSON arrays and JSON binary arrays are backed with some form of a
- `std::vector`. Because JSON binary arrays are a non-standard extension it
- was decided that it would be best to prevent automatic initialization of a
- binary array type, for backwards compatibility and so it does not happen on
- accident.
-
- @param[in] init container containing bytes to use as binary type
-
- @return JSON binary array value
-
- @complexity Linear in the size of @a init.
-
- @exceptionsafety Strong guarantee: if an exception is thrown, there are no
- changes to any JSON value.
-
- @since version 3.8.0
- */
+ /// @brief explicitly create a binary array (without subtype)
+ /// @sa https://json.nlohmann.me/api/basic_json/binary/
JSON_HEDLEY_WARN_UNUSED_RESULT
static basic_json binary(const typename binary_t::container_type& init)
{
@@ -19319,34 +18120,8 @@
return res;
}
- /*!
- @brief explicitly create a binary array (with subtype)
-
- Creates a JSON binary array value from a given binary container. Binary
- values are part of various binary formats, such as CBOR, MessagePack, and
- BSON. This constructor is used to create a value for serialization to those
- formats.
-
- @note Note, this function exists because of the difficulty in correctly
- specifying the correct template overload in the standard value ctor, as both
- JSON arrays and JSON binary arrays are backed with some form of a
- `std::vector`. Because JSON binary arrays are a non-standard extension it
- was decided that it would be best to prevent automatic initialization of a
- binary array type, for backwards compatibility and so it does not happen on
- accident.
-
- @param[in] init container containing bytes to use as binary type
- @param[in] subtype subtype to use in MessagePack and BSON
-
- @return JSON binary array value
-
- @complexity Linear in the size of @a init.
-
- @exceptionsafety Strong guarantee: if an exception is thrown, there are no
- changes to any JSON value.
-
- @since version 3.8.0
- */
+ /// @brief explicitly create a binary array (with subtype)
+ /// @sa https://json.nlohmann.me/api/basic_json/binary/
JSON_HEDLEY_WARN_UNUSED_RESULT
static basic_json binary(const typename binary_t::container_type& init, typename binary_t::subtype_type subtype)
{
@@ -19356,7 +18131,8 @@
return res;
}
- /// @copydoc binary(const typename binary_t::container_type&)
+ /// @brief explicitly create a binary array
+ /// @sa https://json.nlohmann.me/api/basic_json/binary/
JSON_HEDLEY_WARN_UNUSED_RESULT
static basic_json binary(typename binary_t::container_type&& init)
{
@@ -19366,7 +18142,8 @@
return res;
}
- /// @copydoc binary(const typename binary_t::container_type&, typename binary_t::subtype_type)
+ /// @brief explicitly create a binary array (with subtype)
+ /// @sa https://json.nlohmann.me/api/basic_json/binary/
JSON_HEDLEY_WARN_UNUSED_RESULT
static basic_json binary(typename binary_t::container_type&& init, typename binary_t::subtype_type subtype)
{
@@ -19376,115 +18153,24 @@
return res;
}
- /*!
- @brief explicitly create an array from an initializer list
-
- Creates a JSON array value from a given initializer list. That is, given a
- list of values `a, b, c`, creates the JSON value `[a, b, c]`. If the
- initializer list is empty, the empty array `[]` is created.
-
- @note This function is only needed to express two edge cases that cannot
- be realized with the initializer list constructor (@ref
- basic_json(initializer_list_t, bool, value_t)). These cases
- are:
- 1. creating an array whose elements are all pairs whose first element is a
- string -- in this case, the initializer list constructor would create an
- object, taking the first elements as keys
- 2. creating an empty array -- passing the empty initializer list to the
- initializer list constructor yields an empty object
-
- @param[in] init initializer list with JSON values to create an array from
- (optional)
-
- @return JSON array value
-
- @complexity Linear in the size of @a init.
-
- @exceptionsafety Strong guarantee: if an exception is thrown, there are no
- changes to any JSON value.
-
- @liveexample{The following code shows an example for the `array`
- function.,array}
-
- @sa see @ref basic_json(initializer_list_t, bool, value_t) --
- create a JSON value from an initializer list
- @sa see @ref object(initializer_list_t) -- create a JSON object
- value from an initializer list
-
- @since version 1.0.0
- */
+ /// @brief explicitly create an array from an initializer list
+ /// @sa https://json.nlohmann.me/api/basic_json/array/
JSON_HEDLEY_WARN_UNUSED_RESULT
static basic_json array(initializer_list_t init = {})
{
return basic_json(init, false, value_t::array);
}
- /*!
- @brief explicitly create an object from an initializer list
-
- Creates a JSON object value from a given initializer list. The initializer
- lists elements must be pairs, and their first elements must be strings. If
- the initializer list is empty, the empty object `{}` is created.
-
- @note This function is only added for symmetry reasons. In contrast to the
- related function @ref array(initializer_list_t), there are
- no cases which can only be expressed by this function. That is, any
- initializer list @a init can also be passed to the initializer list
- constructor @ref basic_json(initializer_list_t, bool, value_t).
-
- @param[in] init initializer list to create an object from (optional)
-
- @return JSON object value
-
- @throw type_error.301 if @a init is not a list of pairs whose first
- elements are strings. In this case, no object can be created. When such a
- value is passed to @ref basic_json(initializer_list_t, bool, value_t),
- an array would have been created from the passed initializer list @a init.
- See example below.
-
- @complexity Linear in the size of @a init.
-
- @exceptionsafety Strong guarantee: if an exception is thrown, there are no
- changes to any JSON value.
-
- @liveexample{The following code shows an example for the `object`
- function.,object}
-
- @sa see @ref basic_json(initializer_list_t, bool, value_t) --
- create a JSON value from an initializer list
- @sa see @ref array(initializer_list_t) -- create a JSON array
- value from an initializer list
-
- @since version 1.0.0
- */
+ /// @brief explicitly create an object from an initializer list
+ /// @sa https://json.nlohmann.me/api/basic_json/object/
JSON_HEDLEY_WARN_UNUSED_RESULT
static basic_json object(initializer_list_t init = {})
{
return basic_json(init, false, value_t::object);
}
- /*!
- @brief construct an array with count copies of given value
-
- Constructs a JSON array value by creating @a cnt copies of a passed value.
- In case @a cnt is `0`, an empty array is created.
-
- @param[in] cnt the number of JSON copies of @a val to create
- @param[in] val the JSON value to copy
-
- @post `std::distance(begin(),end()) == cnt` holds.
-
- @complexity Linear in @a cnt.
-
- @exceptionsafety Strong guarantee: if an exception is thrown, there are no
- changes to any JSON value.
-
- @liveexample{The following code shows examples for the @ref
- basic_json(size_type\, const basic_json&)
- constructor.,basic_json__size_type_basic_json}
-
- @since version 1.0.0
- */
+ /// @brief construct an array with count copies of given value
+ /// @sa https://json.nlohmann.me/api/basic_json/basic_json/
basic_json(size_type cnt, const basic_json& val)
: m_type(value_t::array)
{
@@ -19493,61 +18179,8 @@
assert_invariant();
}
- /*!
- @brief construct a JSON container given an iterator range
-
- Constructs the JSON value with the contents of the range `[first, last)`.
- The semantics depends on the different types a JSON value can have:
- - In case of a null type, invalid_iterator.206 is thrown.
- - In case of other primitive types (number, boolean, or string), @a first
- must be `begin()` and @a last must be `end()`. In this case, the value is
- copied. Otherwise, invalid_iterator.204 is thrown.
- - In case of structured types (array, object), the constructor behaves as
- similar versions for `std::vector` or `std::map`; that is, a JSON array
- or object is constructed from the values in the range.
-
- @tparam InputIT an input iterator type (@ref iterator or @ref
- const_iterator)
-
- @param[in] first begin of the range to copy from (included)
- @param[in] last end of the range to copy from (excluded)
-
- @pre Iterators @a first and @a last must be initialized. **This
- precondition is enforced with an assertion (see warning).** If
- assertions are switched off, a violation of this precondition yields
- undefined behavior.
-
- @pre Range `[first, last)` is valid. Usually, this precondition cannot be
- checked efficiently. Only certain edge cases are detected; see the
- description of the exceptions below. A violation of this precondition
- yields undefined behavior.
-
- @warning A precondition is enforced with a runtime assertion that will
- result in calling `std::abort` if this precondition is not met.
- Assertions can be disabled by defining `NDEBUG` at compile time.
- See https://en.cppreference.com/w/cpp/error/assert for more
- information.
-
- @throw invalid_iterator.201 if iterators @a first and @a last are not
- compatible (i.e., do not belong to the same JSON value). In this case,
- the range `[first, last)` is undefined.
- @throw invalid_iterator.204 if iterators @a first and @a last belong to a
- primitive type (number, boolean, or string), but @a first does not point
- to the first element any more. In this case, the range `[first, last)` is
- undefined. See example code below.
- @throw invalid_iterator.206 if iterators @a first and @a last belong to a
- null value. In this case, the range `[first, last)` is undefined.
-
- @complexity Linear in distance between @a first and @a last.
-
- @exceptionsafety Strong guarantee: if an exception is thrown, there are no
- changes to any JSON value.
-
- @liveexample{The example below shows several ways to create JSON values by
- specifying a subrange with iterators.,basic_json__InputIt_InputIt}
-
- @since version 1.0.0
- */
+ /// @brief construct a JSON container given an iterator range
+ /// @sa https://json.nlohmann.me/api/basic_json/basic_json/
template < class InputIT, typename std::enable_if <
std::is_same<InputIT, typename basic_json_t::iterator>::value ||
std::is_same<InputIT, typename basic_json_t::const_iterator>::value, int >::type = 0 >
@@ -19663,31 +18296,8 @@
std::is_same<typename JsonRef::value_type, basic_json>>::value, int> = 0 >
basic_json(const JsonRef& ref) : basic_json(ref.moved_or_copied()) {}
- /*!
- @brief copy constructor
-
- Creates a copy of a given JSON value.
-
- @param[in] other the JSON value to copy
-
- @post `*this == other`
-
- @complexity Linear in the size of @a other.
-
- @exceptionsafety Strong guarantee: if an exception is thrown, there are no
- changes to any JSON value.
-
- @requirement This function helps `basic_json` satisfying the
- [Container](https://en.cppreference.com/w/cpp/named_req/Container)
- requirements:
- - The complexity is linear.
- - As postcondition, it holds: `other == basic_json(other)`.
-
- @liveexample{The following code shows an example for the copy
- constructor.,basic_json__basic_json}
-
- @since version 1.0.0
- */
+ /// @brief copy constructor
+ /// @sa https://json.nlohmann.me/api/basic_json/basic_json/
basic_json(const basic_json& other)
: m_type(other.m_type)
{
@@ -19754,32 +18364,8 @@
assert_invariant();
}
- /*!
- @brief move constructor
-
- Move constructor. Constructs a JSON value with the contents of the given
- value @a other using move semantics. It "steals" the resources from @a
- other and leaves it as JSON null value.
-
- @param[in,out] other value to move to this object
-
- @post `*this` has the same value as @a other before the call.
- @post @a other is a JSON null value.
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this constructor never throws
- exceptions.
-
- @requirement This function helps `basic_json` satisfying the
- [MoveConstructible](https://en.cppreference.com/w/cpp/named_req/MoveConstructible)
- requirements.
-
- @liveexample{The code below shows the move constructor explicitly called
- via std::move.,basic_json__moveconstructor}
-
- @since version 1.0.0
- */
+ /// @brief move constructor
+ /// @sa https://json.nlohmann.me/api/basic_json/basic_json/
basic_json(basic_json&& other) noexcept
: m_type(std::move(other.m_type)),
m_value(std::move(other.m_value))
@@ -19795,29 +18381,8 @@
assert_invariant();
}
- /*!
- @brief copy assignment
-
- Copy assignment operator. Copies a JSON value via the "copy and swap"
- strategy: It is expressed in terms of the copy constructor, destructor,
- and the `swap()` member function.
-
- @param[in] other value to copy from
-
- @complexity Linear.
-
- @requirement This function helps `basic_json` satisfying the
- [Container](https://en.cppreference.com/w/cpp/named_req/Container)
- requirements:
- - The complexity is linear.
-
- @liveexample{The code below shows and example for the copy assignment. It
- creates a copy of value `a` which is then swapped with `b`. Finally\, the
- copy of `a` (which is the null value after the swap) is
- destroyed.,basic_json__copyassignment}
-
- @since version 1.0.0
- */
+ /// @brief copy assignment
+ /// @sa https://json.nlohmann.me/api/basic_json/operator=/
basic_json& operator=(basic_json other) noexcept (
std::is_nothrow_move_constructible<value_t>::value&&
std::is_nothrow_move_assignable<value_t>::value&&
@@ -19837,21 +18402,8 @@
return *this;
}
- /*!
- @brief destructor
-
- Destroys the JSON value and frees all allocated memory.
-
- @complexity Linear.
-
- @requirement This function helps `basic_json` satisfying the
- [Container](https://en.cppreference.com/w/cpp/named_req/Container)
- requirements:
- - The complexity is linear.
- - All stored elements are destroyed and all memory is freed.
-
- @since version 1.0.0
- */
+ /// @brief destructor
+ /// @sa https://json.nlohmann.me/api/basic_json/~basic_json/
~basic_json() noexcept
{
assert_invariant(false);
@@ -19869,53 +18421,8 @@
/// Functions to inspect the type of a JSON value.
/// @{
- /*!
- @brief serialization
-
- Serialization function for JSON values. The function tries to mimic
- Python's `json.dumps()` function, and currently supports its @a indent
- and @a ensure_ascii parameters.
-
- @param[in] indent If indent is nonnegative, then array elements and object
- members will be pretty-printed with that indent level. An indent level of
- `0` will only insert newlines. `-1` (the default) selects the most compact
- representation.
- @param[in] indent_char The character to use for indentation if @a indent is
- greater than `0`. The default is ` ` (space).
- @param[in] ensure_ascii If @a ensure_ascii is true, all non-ASCII characters
- in the output are escaped with `\uXXXX` sequences, and the result consists
- of ASCII characters only.
- @param[in] error_handler how to react on decoding errors; there are three
- possible values: `strict` (throws and exception in case a decoding error
- occurs; default), `replace` (replace invalid UTF-8 sequences with U+FFFD),
- and `ignore` (ignore invalid UTF-8 sequences during serialization; all
- bytes are copied to the output unchanged).
-
- @return string containing the serialization of the JSON value
-
- @throw type_error.316 if a string stored inside the JSON value is not
- UTF-8 encoded and @a error_handler is set to strict
-
- @note Binary values are serialized as object containing two keys:
- - "bytes": an array of bytes as integers
- - "subtype": the subtype as integer or "null" if the binary has no subtype
-
- @complexity Linear.
-
- @exceptionsafety Strong guarantee: if an exception is thrown, there are no
- changes in the JSON value.
-
- @liveexample{The following example shows the effect of different @a indent\,
- @a indent_char\, and @a ensure_ascii parameters to the result of the
- serialization.,dump}
-
- @see https://docs.python.org/2/library/json.html#json.dump
-
- @since version 1.0.0; indentation character @a indent_char, option
- @a ensure_ascii and exceptions added in version 3.0.0; error
- handlers added in version 3.4.0; serialization of binary values added
- in version 3.8.0.
- */
+ /// @brief serialization
+ /// @sa https://json.nlohmann.me/api/basic_json/dump/
string_t dump(const int indent = -1,
const char indent_char = ' ',
const bool ensure_ascii = false,
@@ -19936,397 +18443,106 @@
return result;
}
- /*!
- @brief return the type of the JSON value (explicit)
-
- Return the type of the JSON value as a value from the @ref value_t
- enumeration.
-
- @return the type of the JSON value
- Value type | return value
- ------------------------- | -------------------------
- null | value_t::null
- boolean | value_t::boolean
- string | value_t::string
- number (integer) | value_t::number_integer
- number (unsigned integer) | value_t::number_unsigned
- number (floating-point) | value_t::number_float
- object | value_t::object
- array | value_t::array
- binary | value_t::binary
- discarded | value_t::discarded
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this member function never throws
- exceptions.
-
- @liveexample{The following code exemplifies `type()` for all JSON
- types.,type}
-
- @sa see @ref operator value_t() -- return the type of the JSON value (implicit)
- @sa see @ref type_name() -- return the type as string
-
- @since version 1.0.0
- */
+ /// @brief return the type of the JSON value (explicit)
+ /// @sa https://json.nlohmann.me/api/basic_json/type/
constexpr value_t type() const noexcept
{
return m_type;
}
- /*!
- @brief return whether type is primitive
-
- This function returns true if and only if the JSON type is primitive
- (string, number, boolean, or null).
-
- @return `true` if type is primitive (string, number, boolean, or null),
- `false` otherwise.
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this member function never throws
- exceptions.
-
- @liveexample{The following code exemplifies `is_primitive()` for all JSON
- types.,is_primitive}
-
- @sa see @ref is_structured() -- returns whether JSON value is structured
- @sa see @ref is_null() -- returns whether JSON value is `null`
- @sa see @ref is_string() -- returns whether JSON value is a string
- @sa see @ref is_boolean() -- returns whether JSON value is a boolean
- @sa see @ref is_number() -- returns whether JSON value is a number
- @sa see @ref is_binary() -- returns whether JSON value is a binary array
-
- @since version 1.0.0
- */
+ /// @brief return whether type is primitive
+ /// @sa https://json.nlohmann.me/api/basic_json/is_primitive/
constexpr bool is_primitive() const noexcept
{
return is_null() || is_string() || is_boolean() || is_number() || is_binary();
}
- /*!
- @brief return whether type is structured
-
- This function returns true if and only if the JSON type is structured
- (array or object).
-
- @return `true` if type is structured (array or object), `false` otherwise.
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this member function never throws
- exceptions.
-
- @liveexample{The following code exemplifies `is_structured()` for all JSON
- types.,is_structured}
-
- @sa see @ref is_primitive() -- returns whether value is primitive
- @sa see @ref is_array() -- returns whether value is an array
- @sa see @ref is_object() -- returns whether value is an object
-
- @since version 1.0.0
- */
+ /// @brief return whether type is structured
+ /// @sa https://json.nlohmann.me/api/basic_json/is_structured/
constexpr bool is_structured() const noexcept
{
return is_array() || is_object();
}
- /*!
- @brief return whether value is null
-
- This function returns true if and only if the JSON value is null.
-
- @return `true` if type is null, `false` otherwise.
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this member function never throws
- exceptions.
-
- @liveexample{The following code exemplifies `is_null()` for all JSON
- types.,is_null}
-
- @since version 1.0.0
- */
+ /// @brief return whether value is null
+ /// @sa https://json.nlohmann.me/api/basic_json/is_null/
constexpr bool is_null() const noexcept
{
return m_type == value_t::null;
}
- /*!
- @brief return whether value is a boolean
-
- This function returns true if and only if the JSON value is a boolean.
-
- @return `true` if type is boolean, `false` otherwise.
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this member function never throws
- exceptions.
-
- @liveexample{The following code exemplifies `is_boolean()` for all JSON
- types.,is_boolean}
-
- @since version 1.0.0
- */
+ /// @brief return whether value is a boolean
+ /// @sa https://json.nlohmann.me/api/basic_json/is_boolean/
constexpr bool is_boolean() const noexcept
{
return m_type == value_t::boolean;
}
- /*!
- @brief return whether value is a number
-
- This function returns true if and only if the JSON value is a number. This
- includes both integer (signed and unsigned) and floating-point values.
-
- @return `true` if type is number (regardless whether integer, unsigned
- integer or floating-type), `false` otherwise.
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this member function never throws
- exceptions.
-
- @liveexample{The following code exemplifies `is_number()` for all JSON
- types.,is_number}
-
- @sa see @ref is_number_integer() -- check if value is an integer or unsigned
- integer number
- @sa see @ref is_number_unsigned() -- check if value is an unsigned integer
- number
- @sa see @ref is_number_float() -- check if value is a floating-point number
-
- @since version 1.0.0
- */
+ /// @brief return whether value is a number
+ /// @sa https://json.nlohmann.me/api/basic_json/is_number/
constexpr bool is_number() const noexcept
{
return is_number_integer() || is_number_float();
}
- /*!
- @brief return whether value is an integer number
-
- This function returns true if and only if the JSON value is a signed or
- unsigned integer number. This excludes floating-point values.
-
- @return `true` if type is an integer or unsigned integer number, `false`
- otherwise.
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this member function never throws
- exceptions.
-
- @liveexample{The following code exemplifies `is_number_integer()` for all
- JSON types.,is_number_integer}
-
- @sa see @ref is_number() -- check if value is a number
- @sa see @ref is_number_unsigned() -- check if value is an unsigned integer
- number
- @sa see @ref is_number_float() -- check if value is a floating-point number
-
- @since version 1.0.0
- */
+ /// @brief return whether value is an integer number
+ /// @sa https://json.nlohmann.me/api/basic_json/is_number_integer/
constexpr bool is_number_integer() const noexcept
{
return m_type == value_t::number_integer || m_type == value_t::number_unsigned;
}
- /*!
- @brief return whether value is an unsigned integer number
-
- This function returns true if and only if the JSON value is an unsigned
- integer number. This excludes floating-point and signed integer values.
-
- @return `true` if type is an unsigned integer number, `false` otherwise.
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this member function never throws
- exceptions.
-
- @liveexample{The following code exemplifies `is_number_unsigned()` for all
- JSON types.,is_number_unsigned}
-
- @sa see @ref is_number() -- check if value is a number
- @sa see @ref is_number_integer() -- check if value is an integer or unsigned
- integer number
- @sa see @ref is_number_float() -- check if value is a floating-point number
-
- @since version 2.0.0
- */
+ /// @brief return whether value is an unsigned integer number
+ /// @sa https://json.nlohmann.me/api/basic_json/is_number_unsigned/
constexpr bool is_number_unsigned() const noexcept
{
return m_type == value_t::number_unsigned;
}
- /*!
- @brief return whether value is a floating-point number
-
- This function returns true if and only if the JSON value is a
- floating-point number. This excludes signed and unsigned integer values.
-
- @return `true` if type is a floating-point number, `false` otherwise.
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this member function never throws
- exceptions.
-
- @liveexample{The following code exemplifies `is_number_float()` for all
- JSON types.,is_number_float}
-
- @sa see @ref is_number() -- check if value is number
- @sa see @ref is_number_integer() -- check if value is an integer number
- @sa see @ref is_number_unsigned() -- check if value is an unsigned integer
- number
-
- @since version 1.0.0
- */
+ /// @brief return whether value is a floating-point number
+ /// @sa https://json.nlohmann.me/api/basic_json/is_number_float/
constexpr bool is_number_float() const noexcept
{
return m_type == value_t::number_float;
}
- /*!
- @brief return whether value is an object
-
- This function returns true if and only if the JSON value is an object.
-
- @return `true` if type is object, `false` otherwise.
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this member function never throws
- exceptions.
-
- @liveexample{The following code exemplifies `is_object()` for all JSON
- types.,is_object}
-
- @since version 1.0.0
- */
+ /// @brief return whether value is an object
+ /// @sa https://json.nlohmann.me/api/basic_json/is_object/
constexpr bool is_object() const noexcept
{
return m_type == value_t::object;
}
- /*!
- @brief return whether value is an array
-
- This function returns true if and only if the JSON value is an array.
-
- @return `true` if type is array, `false` otherwise.
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this member function never throws
- exceptions.
-
- @liveexample{The following code exemplifies `is_array()` for all JSON
- types.,is_array}
-
- @since version 1.0.0
- */
+ /// @brief return whether value is an array
+ /// @sa https://json.nlohmann.me/api/basic_json/is_array/
constexpr bool is_array() const noexcept
{
return m_type == value_t::array;
}
- /*!
- @brief return whether value is a string
-
- This function returns true if and only if the JSON value is a string.
-
- @return `true` if type is string, `false` otherwise.
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this member function never throws
- exceptions.
-
- @liveexample{The following code exemplifies `is_string()` for all JSON
- types.,is_string}
-
- @since version 1.0.0
- */
+ /// @brief return whether value is a string
+ /// @sa https://json.nlohmann.me/api/basic_json/is_string/
constexpr bool is_string() const noexcept
{
return m_type == value_t::string;
}
- /*!
- @brief return whether value is a binary array
-
- This function returns true if and only if the JSON value is a binary array.
-
- @return `true` if type is binary array, `false` otherwise.
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this member function never throws
- exceptions.
-
- @liveexample{The following code exemplifies `is_binary()` for all JSON
- types.,is_binary}
-
- @since version 3.8.0
- */
+ /// @brief return whether value is a binary array
+ /// @sa https://json.nlohmann.me/api/basic_json/is_binary/
constexpr bool is_binary() const noexcept
{
return m_type == value_t::binary;
}
- /*!
- @brief return whether value is discarded
-
- This function returns true if and only if the JSON value was discarded
- during parsing with a callback function (see @ref parser_callback_t).
-
- @note This function will always be `false` for JSON values after parsing.
- That is, discarded values can only occur during parsing, but will be
- removed when inside a structured value or replaced by null in other cases.
-
- @return `true` if type is discarded, `false` otherwise.
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this member function never throws
- exceptions.
-
- @liveexample{The following code exemplifies `is_discarded()` for all JSON
- types.,is_discarded}
-
- @since version 1.0.0
- */
+ /// @brief return whether value is discarded
+ /// @sa https://json.nlohmann.me/api/basic_json/is_discarded/
constexpr bool is_discarded() const noexcept
{
return m_type == value_t::discarded;
}
- /*!
- @brief return the type of the JSON value (implicit)
-
- Implicitly return the type of the JSON value as a value from the @ref
- value_t enumeration.
-
- @return the type of the JSON value
-
- @complexity Constant.
-
- @exceptionsafety No-throw guarantee: this member function never throws
- exceptions.
-
- @liveexample{The following code exemplifies the @ref value_t operator for
- all JSON types.,operator__value_t}
-
- @sa see @ref type() -- return the type of the JSON value (explicit)
- @sa see @ref type_name() -- return the type as string
-
- @since version 1.0.0
- */
+ /// @brief return the type of the JSON value (implicit)
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_value_t/
constexpr operator value_t() const noexcept
{
return m_type;
@@ -20476,32 +18692,8 @@
/// Direct access to the stored value of a JSON value.
/// @{
- /*!
- @brief get a pointer value (implicit)
-
- Implicit pointer access to the internally stored JSON value. No copies are
- made.
-
- @warning Writing data to the pointee of the result yields an undefined
- state.
-
- @tparam PointerType pointer type; must be a pointer to @ref array_t, @ref
- object_t, @ref string_t, @ref boolean_t, @ref number_integer_t,
- @ref number_unsigned_t, or @ref number_float_t. Enforced by a static
- assertion.
-
- @return pointer to the internally stored JSON value if the requested
- pointer type @a PointerType fits to the JSON value; `nullptr` otherwise
-
- @complexity Constant.
-
- @liveexample{The example below shows how pointers to internal values of a
- JSON value can be requested. Note that no type conversions are made and a
- `nullptr` is returned if the value and the requested pointer type does not
- match.,get_ptr}
-
- @since version 1.0.0
- */
+ /// @brief get a pointer value (implicit)
+ /// @sa https://json.nlohmann.me/api/basic_json/get_ptr/
template<typename PointerType, typename std::enable_if<
std::is_pointer<PointerType>::value, int>::type = 0>
auto get_ptr() noexcept -> decltype(std::declval<basic_json_t&>().get_impl_ptr(std::declval<PointerType>()))
@@ -20510,10 +18702,8 @@
return get_impl_ptr(static_cast<PointerType>(nullptr));
}
- /*!
- @brief get a pointer value (implicit)
- @copydoc get_ptr()
- */
+ /// @brief get a pointer value (implicit)
+ /// @sa https://json.nlohmann.me/api/basic_json/get_ptr/
template < typename PointerType, typename std::enable_if <
std::is_pointer<PointerType>::value&&
std::is_const<typename std::remove_pointer<PointerType>::type>::value, int >::type = 0 >
@@ -20752,39 +18942,8 @@
return get_ptr<PointerType>();
}
- /*!
- @brief get a value (explicit)
-
- Explicit type conversion between the JSON value and a compatible value.
- The value is filled into the input parameter by calling the @ref json_serializer<ValueType>
- `from_json()` method.
-
- The function is equivalent to executing
- @code {.cpp}
- ValueType v;
- JSONSerializer<ValueType>::from_json(*this, v);
- @endcode
-
- This overloads is chosen if:
- - @a ValueType is not @ref basic_json,
- - @ref json_serializer<ValueType> has a `from_json()` method of the form
- `void from_json(const basic_json&, ValueType&)`, and
-
- @tparam ValueType the input parameter type.
-
- @return the input parameter, allowing chaining calls.
-
- @throw what @ref json_serializer<ValueType> `from_json()` method throws
-
- @liveexample{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>`.,get_to}
-
- @since version 3.3.0
- */
+ /// @brief get a value (explicit)
+ /// @sa https://json.nlohmann.me/api/basic_json/get_to/
template < typename ValueType,
detail::enable_if_t <
!detail::is_basic_json<ValueType>::value&&
@@ -20797,7 +18956,7 @@
return v;
}
- // specialization to allow to call get_to with a basic_json value
+ // specialization to allow calling get_to with a basic_json value
// see https://github.com/nlohmann/json/issues/2175
template<typename ValueType,
detail::enable_if_t <
@@ -20822,32 +18981,8 @@
return v;
}
- /*!
- @brief get a reference value (implicit)
-
- Implicit reference access to the internally stored JSON value. No copies
- are made.
-
- @warning Writing data to the referee of the result yields an undefined
- state.
-
- @tparam ReferenceType reference type; must be a reference to @ref array_t,
- @ref object_t, @ref string_t, @ref boolean_t, @ref number_integer_t, or
- @ref number_float_t. Enforced by static assertion.
-
- @return reference to the internally stored JSON value if the requested
- reference type @a ReferenceType fits to the JSON value; throws
- type_error.303 otherwise
-
- @throw type_error.303 in case passed type @a ReferenceType is incompatible
- with the stored JSON value; see example below
-
- @complexity Constant.
-
- @liveexample{The example shows several calls to `get_ref()`.,get_ref}
-
- @since version 1.1.0
- */
+ /// @brief get a reference value (implicit)
+ /// @sa https://json.nlohmann.me/api/basic_json/get_ref/
template<typename ReferenceType, typename std::enable_if<
std::is_reference<ReferenceType>::value, int>::type = 0>
ReferenceType get_ref()
@@ -20856,10 +18991,8 @@
return get_ref_impl<ReferenceType>(*this);
}
- /*!
- @brief get a reference value (implicit)
- @copydoc get_ref()
- */
+ /// @brief get a reference value (implicit)
+ /// @sa https://json.nlohmann.me/api/basic_json/get_ref/
template < typename ReferenceType, typename std::enable_if <
std::is_reference<ReferenceType>::value&&
std::is_const<typename std::remove_reference<ReferenceType>::type>::value, int >::type = 0 >
@@ -20917,15 +19050,8 @@
return get<ValueType>();
}
- /*!
- @return reference to the binary value
-
- @throw type_error.302 if the value is not binary
-
- @sa see @ref is_binary() to check if the value is binary
-
- @since version 3.8.0
- */
+ /// @brief get a binary value
+ /// @sa https://json.nlohmann.me/api/basic_json/get_binary/
binary_t& get_binary()
{
if (!is_binary())
@@ -20936,7 +19062,8 @@
return *get_ptr<binary_t*>();
}
- /// @copydoc get_binary()
+ /// @brief get a binary value
+ /// @sa https://json.nlohmann.me/api/basic_json/get_binary/
const binary_t& get_binary() const
{
if (!is_binary())
@@ -20958,32 +19085,8 @@
/// Access to the JSON value.
/// @{
- /*!
- @brief access specified array element with bounds checking
-
- Returns a reference to the element at specified location @a idx, with
- bounds checking.
-
- @param[in] idx index of the element to access
-
- @return reference to the element at index @a idx
-
- @throw type_error.304 if the JSON value is not an array; in this case,
- calling `at` with an index makes no sense. See example below.
- @throw out_of_range.401 if the index @a idx is out of range of the array;
- that is, `idx >= size()`. See example below.
-
- @exceptionsafety Strong guarantee: if an exception is thrown, there are no
- changes in the JSON value.
-
- @complexity Constant.
-
- @since version 1.0.0
-
- @liveexample{The example below shows how array elements can be read and
- written using `at()`. It also demonstrates the different exceptions that
- can be thrown.,at__size_type}
- */
+ /// @brief access specified array element with bounds checking
+ /// @sa https://json.nlohmann.me/api/basic_json/at/
reference at(size_type idx)
{
// at only works for arrays
@@ -21005,32 +19108,8 @@
}
}
- /*!
- @brief access specified array element with bounds checking
-
- Returns a const reference to the element at specified location @a idx,
- with bounds checking.
-
- @param[in] idx index of the element to access
-
- @return const reference to the element at index @a idx
-
- @throw type_error.304 if the JSON value is not an array; in this case,
- calling `at` with an index makes no sense. See example below.
- @throw out_of_range.401 if the index @a idx is out of range of the array;
- that is, `idx >= size()`. See example below.
-
- @exceptionsafety Strong guarantee: if an exception is thrown, there are no
- changes in the JSON value.
-
- @complexity Constant.
-
- @since version 1.0.0
-
- @liveexample{The example below shows how array elements can be read using
- `at()`. It also demonstrates the different exceptions that can be thrown.,
- at__size_type_const}
- */
+ /// @brief access specified array element with bounds checking
+ /// @sa https://json.nlohmann.me/api/basic_json/at/
const_reference at(size_type idx) const
{
// at only works for arrays
@@ -21052,36 +19131,8 @@
}
}
- /*!
- @brief access specified object element with bounds checking
-
- Returns a reference to the element at with specified key @a key, with
- bounds checking.
-
- @param[in] key key of the element to access
-
- @return reference to the element at key @a key
-
- @throw type_error.304 if the JSON value is not an object; in this case,
- calling `at` with a key makes no sense. See example below.
- @throw out_of_range.403 if the key @a key is is not stored in the object;
- that is, `find(key) == end()`. See example below.
-
- @exceptionsafety Strong guarantee: if an exception is thrown, there are no
- changes in the JSON value.
-
- @complexity Logarithmic in the size of the container.
-
- @sa see @ref operator[](const typename object_t::key_type&) for unchecked
- access by reference
- @sa see @ref value() for access by value with a default value
-
- @since version 1.0.0
-
- @liveexample{The example below shows how object elements can be read and
- written using `at()`. It also demonstrates the different exceptions that
- can be thrown.,at__object_t_key_type}
- */
+ /// @brief access specified object element with bounds checking
+ /// @sa https://json.nlohmann.me/api/basic_json/at/
reference at(const typename object_t::key_type& key)
{
// at only works for objects
@@ -21103,36 +19154,8 @@
}
}
- /*!
- @brief access specified object element with bounds checking
-
- Returns a const reference to the element at with specified key @a key,
- with bounds checking.
-
- @param[in] key key of the element to access
-
- @return const reference to the element at key @a key
-
- @throw type_error.304 if the JSON value is not an object; in this case,
- calling `at` with a key makes no sense. See example below.
- @throw out_of_range.403 if the key @a key is is not stored in the object;
- that is, `find(key) == end()`. See example below.
-
- @exceptionsafety Strong guarantee: if an exception is thrown, there are no
- changes in the JSON value.
-
- @complexity Logarithmic in the size of the container.
-
- @sa see @ref operator[](const typename object_t::key_type&) for unchecked
- access by reference
- @sa see @ref value() for access by value with a default value
-
- @since version 1.0.0
-
- @liveexample{The example below shows how object elements can be read using
- `at()`. It also demonstrates the different exceptions that can be thrown.,
- at__object_t_key_type_const}
- */
+ /// @brief access specified object element with bounds checking
+ /// @sa https://json.nlohmann.me/api/basic_json/at/
const_reference at(const typename object_t::key_type& key) const
{
// at only works for objects
@@ -21154,31 +19177,8 @@
}
}
- /*!
- @brief access specified array element
-
- Returns a reference to the element at specified location @a idx.
-
- @note If @a idx is beyond the range of the array (i.e., `idx >= size()`),
- then the array is silently filled up with `null` values to make `idx` a
- valid reference to the last stored element.
-
- @param[in] idx index of the element to access
-
- @return reference to the element at index @a idx
-
- @throw type_error.305 if the JSON value is not an array or null; in that
- cases, using the [] operator with an index makes no sense.
-
- @complexity Constant if @a idx is in the range of the array. Otherwise
- linear in `idx - size()`.
-
- @liveexample{The example below shows how array elements can be read and
- written using `[]` operator. Note the addition of `null`
- values.,operatorarray__size_type}
-
- @since version 1.0.0
- */
+ /// @brief access specified array element
+ /// @sa https://json.nlohmann.me/api/basic_json/operator%5B%5D/
reference operator[](size_type idx)
{
// implicitly convert null value to an empty array
@@ -21223,25 +19223,8 @@
JSON_THROW(type_error::create(305, "cannot use operator[] with a numeric argument with " + std::string(type_name()), *this));
}
- /*!
- @brief access specified array element
-
- Returns a const reference to the element at specified location @a idx.
-
- @param[in] idx index of the element to access
-
- @return const reference to the element at index @a idx
-
- @throw type_error.305 if the JSON value is not an array; in that case,
- using the [] operator with an index makes no sense.
-
- @complexity Constant.
-
- @liveexample{The example below shows how array elements can be read using
- the `[]` operator.,operatorarray__size_type_const}
-
- @since version 1.0.0
- */
+ /// @brief access specified array element
+ /// @sa https://json.nlohmann.me/api/basic_json/operator%5B%5D/
const_reference operator[](size_type idx) const
{
// const operator[] only works for arrays
@@ -21253,33 +19236,8 @@
JSON_THROW(type_error::create(305, "cannot use operator[] with a numeric argument with " + std::string(type_name()), *this));
}
- /*!
- @brief access specified object element
-
- Returns a reference to the element at with specified key @a key.
-
- @note If @a key is not found in the object, then it is silently added to
- the object and filled with a `null` value to make `key` a valid reference.
- In case the value was `null` before, it is converted to an object.
-
- @param[in] key key of the element to access
-
- @return reference to the element at key @a key
-
- @throw type_error.305 if the JSON value is not an object or null; in that
- cases, using the [] operator with a key makes no sense.
-
- @complexity Logarithmic in the size of the container.
-
- @liveexample{The example below shows how object elements can be read and
- written using the `[]` operator.,operatorarray__key_type}
-
- @sa see @ref at(const typename object_t::key_type&) for access by reference
- with range checking
- @sa see @ref value() for access by value with a default value
-
- @since version 1.0.0
- */
+ /// @brief access specified object element
+ /// @sa https://json.nlohmann.me/api/basic_json/operator%5B%5D/
reference operator[](const typename object_t::key_type& key)
{
// implicitly convert null value to an empty object
@@ -21299,36 +19257,8 @@
JSON_THROW(type_error::create(305, "cannot use operator[] with a string argument with " + std::string(type_name()), *this));
}
- /*!
- @brief read-only access specified object element
-
- Returns a const reference to the element at with specified key @a key. No
- bounds checking is performed.
-
- @warning If the element with key @a key does not exist, the behavior is
- undefined.
-
- @param[in] key key of the element to access
-
- @return const reference to the element at key @a key
-
- @pre The element with key @a key must exist. **This precondition is
- enforced with an assertion.**
-
- @throw type_error.305 if the JSON value is not an object; in that case,
- using the [] operator with a key makes no sense.
-
- @complexity Logarithmic in the size of the container.
-
- @liveexample{The example below shows how object elements can be read using
- the `[]` operator.,operatorarray__key_type_const}
-
- @sa see @ref at(const typename object_t::key_type&) for access by reference
- with range checking
- @sa see @ref value() for access by value with a default value
-
- @since version 1.0.0
- */
+ /// @brief access specified object element
+ /// @sa https://json.nlohmann.me/api/basic_json/operator%5B%5D/
const_reference operator[](const typename object_t::key_type& key) const
{
// const operator[] only works for objects
@@ -21341,33 +19271,8 @@
JSON_THROW(type_error::create(305, "cannot use operator[] with a string argument with " + std::string(type_name()), *this));
}
- /*!
- @brief access specified object element
-
- Returns a reference to the element at with specified key @a key.
-
- @note If @a key is not found in the object, then it is silently added to
- the object and filled with a `null` value to make `key` a valid reference.
- In case the value was `null` before, it is converted to an object.
-
- @param[in] key key of the element to access
-
- @return reference to the element at key @a key
-
- @throw type_error.305 if the JSON value is not an object or null; in that
- cases, using the [] operator with a key makes no sense.
-
- @complexity Logarithmic in the size of the container.
-
- @liveexample{The example below shows how object elements can be read and
- written using the `[]` operator.,operatorarray__key_type}
-
- @sa see @ref at(const typename object_t::key_type&) for access by reference
- with range checking
- @sa see @ref value() for access by value with a default value
-
- @since version 1.1.0
- */
+ /// @brief access specified object element
+ /// @sa https://json.nlohmann.me/api/basic_json/operator%5B%5D/
template<typename T>
JSON_HEDLEY_NON_NULL(2)
reference operator[](T* key)
@@ -21389,36 +19294,8 @@
JSON_THROW(type_error::create(305, "cannot use operator[] with a string argument with " + std::string(type_name()), *this));
}
- /*!
- @brief read-only access specified object element
-
- Returns a const reference to the element at with specified key @a key. No
- bounds checking is performed.
-
- @warning If the element with key @a key does not exist, the behavior is
- undefined.
-
- @param[in] key key of the element to access
-
- @return const reference to the element at key @a key
-
- @pre The element with key @a key must exist. **This precondition is
- enforced with an assertion.**
-
- @throw type_error.305 if the JSON value is not an object; in that case,
- using the [] operator with a key makes no sense.
-
- @complexity Logarithmic in the size of the container.
-
- @liveexample{The example below shows how object elements can be read using
- the `[]` operator.,operatorarray__key_type_const}
-
- @sa see @ref at(const typename object_t::key_type&) for access by reference
- with range checking
- @sa see @ref value() for access by value with a default value
-
- @since version 1.1.0
- */
+ /// @brief access specified object element
+ /// @sa https://json.nlohmann.me/api/basic_json/operator%5B%5D/
template<typename T>
JSON_HEDLEY_NON_NULL(2)
const_reference operator[](T* key) const
@@ -21433,57 +19310,9 @@
JSON_THROW(type_error::create(305, "cannot use operator[] with a string argument with " + std::string(type_name()), *this));
}
- /*!
- @brief access specified object element with default value
-
- Returns either a copy of an object's element at the specified key @a key
- or a given default value if no element with key @a key exists.
-
- The function is basically equivalent to executing
- @code {.cpp}
- try {
- return at(key);
- } catch(out_of_range) {
- return default_value;
- }
- @endcode
-
- @note Unlike @ref at(const typename object_t::key_type&), this function
- does not throw if the given key @a key was not found.
-
- @note Unlike @ref operator[](const typename object_t::key_type& key), this
- function does not implicitly add an element to the position defined by @a
- key. This function is furthermore also applicable to const objects.
-
- @param[in] key key of the element to access
- @param[in] default_value the value to return if @a key is not found
-
- @tparam ValueType type compatible to JSON values, for instance `int` for
- JSON integer numbers, `bool` for JSON booleans, or `std::vector` types for
- JSON arrays. Note the type of the expected value at @a key and the default
- value @a default_value must be compatible.
-
- @return copy of the element at key @a key or @a default_value if @a key
- is not found
-
- @throw type_error.302 if @a default_value does not match the type of the
- value at @a key
- @throw type_error.306 if the JSON value is not an object; in that case,
- using `value()` with a key makes no sense.
-
- @complexity Logarithmic in the size of the container.
-
- @liveexample{The example below shows how object elements can be queried
- with a default value.,basic_json__value}
-
- @sa see @ref at(const typename object_t::key_type&) for access by reference
- with range checking
- @sa see @ref operator[](const typename object_t::key_type&) for unchecked
- access by reference
-
- @since version 1.0.0
- */
- // using std::is_convertible in a std::enable_if will fail when using explicit conversions
+ /// @brief access specified object element with default value
+ /// @sa https://json.nlohmann.me/api/basic_json/value/
+ /// using std::is_convertible in a std::enable_if will fail when using explicit conversions
template < class ValueType, typename std::enable_if <
detail::is_getable<basic_json_t, ValueType>::value
&& !std::is_same<value_t, ValueType>::value, int >::type = 0 >
@@ -21505,58 +19334,16 @@
JSON_THROW(type_error::create(306, "cannot use value() with " + std::string(type_name()), *this));
}
- /*!
- @brief overload for a default value of type const char*
- @copydoc basic_json::value(const typename object_t::key_type&, const ValueType&) const
- */
+ /// @brief access specified object element with default value
+ /// @sa https://json.nlohmann.me/api/basic_json/value/
+ /// overload for a default value of type const char*
string_t value(const typename object_t::key_type& key, const char* default_value) const
{
return value(key, string_t(default_value));
}
- /*!
- @brief access specified object element via JSON Pointer with default value
-
- Returns either a copy of an object's element at the specified key @a key
- or a given default value if no element with key @a key exists.
-
- The function is basically equivalent to executing
- @code {.cpp}
- try {
- return at(ptr);
- } catch(out_of_range) {
- return default_value;
- }
- @endcode
-
- @note Unlike @ref at(const json_pointer&), this function does not throw
- if the given key @a key was not found.
-
- @param[in] ptr a JSON pointer to the element to access
- @param[in] default_value the value to return if @a ptr found no value
-
- @tparam ValueType type compatible to JSON values, for instance `int` for
- JSON integer numbers, `bool` for JSON booleans, or `std::vector` types for
- JSON arrays. Note the type of the expected value at @a key and the default
- value @a default_value must be compatible.
-
- @return copy of the element at key @a key or @a default_value if @a key
- is not found
-
- @throw type_error.302 if @a default_value does not match the type of the
- value at @a ptr
- @throw type_error.306 if the JSON value is not an object; in that case,
- using `value()` with a key makes no sense.
-
- @complexity Logarithmic in the size of the container.
-
- @liveexample{The example below shows how object elements can be queried
- with a default value.,basic_json__value_ptr}
-
- @sa see @ref operator[](const json_pointer&) for unchecked access by reference
-
- @since version 2.0.2
- */
+ /// @brief access specified object element via JSON Pointer with default value
+ /// @sa https://json.nlohmann.me/api/basic_json/value/
template<class ValueType, typename std::enable_if<
detail::is_getable<basic_json_t, ValueType>::value, int>::type = 0>
ValueType value(const json_pointer& ptr, const ValueType& default_value) const
@@ -21578,85 +19365,31 @@
JSON_THROW(type_error::create(306, "cannot use value() with " + std::string(type_name()), *this));
}
- /*!
- @brief overload for a default value of type const char*
- @copydoc basic_json::value(const json_pointer&, ValueType) const
- */
+ /// @brief access specified object element via JSON Pointer with default value
+ /// @sa https://json.nlohmann.me/api/basic_json/value/
+ /// overload for a default value of type const char*
JSON_HEDLEY_NON_NULL(3)
string_t value(const json_pointer& ptr, const char* default_value) const
{
return value(ptr, string_t(default_value));
}
- /*!
- @brief access the first element
-
- Returns a reference to the first element in the container. For a JSON
- container `c`, the expression `c.front()` is equivalent to `*c.begin()`.
-
- @return In case of a structured type (array or object), a reference to the
- first element is returned. In case of number, string, boolean, or binary
- values, a reference to the value is returned.
-
- @complexity Constant.
-
- @pre The JSON value must not be `null` (would throw `std::out_of_range`)
- or an empty array or object (undefined behavior, **guarded by
- assertions**).
- @post The JSON value remains unchanged.
-
- @throw invalid_iterator.214 when called on `null` value
-
- @liveexample{The following code shows an example for `front()`.,front}
-
- @sa see @ref back() -- access the last element
-
- @since version 1.0.0
- */
+ /// @brief access the first element
+ /// @sa https://json.nlohmann.me/api/basic_json/front/
reference front()
{
return *begin();
}
- /*!
- @copydoc basic_json::front()
- */
+ /// @brief access the first element
+ /// @sa https://json.nlohmann.me/api/basic_json/front/
const_reference front() const
{
return *cbegin();
}
- /*!
- @brief access the last element
-
- Returns a reference to the last element in the container. For a JSON
- container `c`, the expression `c.back()` is equivalent to
- @code {.cpp}
- auto tmp = c.end();
- --tmp;
- return *tmp;
- @endcode
-
- @return In case of a structured type (array or object), a reference to the
- last element is returned. In case of number, string, boolean, or binary
- values, a reference to the value is returned.
-
- @complexity Constant.
-
- @pre The JSON value must not be `null` (would throw `std::out_of_range`)
- or an empty array or object (undefined behavior, **guarded by
- assertions**).
- @post The JSON value remains unchanged.
-
- @throw invalid_iterator.214 when called on a `null` value. See example
- below.
-
- @liveexample{The following code shows an example for `back()`.,back}
-
- @sa see @ref front() -- access the first element
-
- @since version 1.0.0
- */
+ /// @brief access the last element
+ /// @sa https://json.nlohmann.me/api/basic_json/back/
reference back()
{
auto tmp = end();
@@ -21664,9 +19397,8 @@
return *tmp;
}
- /*!
- @copydoc basic_json::back()
- */
+ /// @brief access the last element
+ /// @sa https://json.nlohmann.me/api/basic_json/back/
const_reference back() const
{
auto tmp = cend();
@@ -21674,52 +19406,8 @@
return *tmp;
}
- /*!
- @brief remove element given an iterator
-
- Removes the element specified by iterator @a pos. The iterator @a pos must
- be valid and dereferenceable. Thus the `end()` iterator (which is valid,
- but is not dereferenceable) cannot be used as a value for @a pos.
-
- If called on a primitive type other than `null`, the resulting JSON value
- will be `null`.
-
- @param[in] pos iterator to the element to remove
- @return Iterator following the last removed element. If the iterator @a
- pos refers to the last element, the `end()` iterator is returned.
-
- @tparam IteratorType an @ref iterator or @ref const_iterator
-
- @post Invalidates iterators and references at or after the point of the
- erase, including the `end()` iterator.
-
- @throw type_error.307 if called on a `null` value; example: `"cannot use
- erase() with null"`
- @throw invalid_iterator.202 if called on an iterator which does not belong
- to the current JSON value; example: `"iterator does not fit current
- value"`
- @throw invalid_iterator.205 if called on a primitive type with invalid
- iterator (i.e., any iterator which is not `begin()`); example: `"iterator
- out of range"`
-
- @complexity The complexity depends on the type:
- - objects: amortized constant
- - arrays: linear in distance between @a pos and the end of the container
- - strings and binary: linear in the length of the member
- - other types: constant
-
- @liveexample{The example shows the result of `erase()` for different JSON
- types.,erase__IteratorType}
-
- @sa see @ref erase(IteratorType, IteratorType) -- removes the elements in
- the given range
- @sa see @ref erase(const typename object_t::key_type&) -- removes the element
- from an object at the given key
- @sa see @ref erase(const size_type) -- removes the element from an array at
- the given index
-
- @since version 1.0.0
- */
+ /// @brief remove element given an iterator
+ /// @sa https://json.nlohmann.me/api/basic_json/erase/
template < class IteratorType, typename std::enable_if <
std::is_same<IteratorType, typename basic_json_t::iterator>::value ||
std::is_same<IteratorType, typename basic_json_t::const_iterator>::value, int >::type
@@ -21789,52 +19477,8 @@
return result;
}
- /*!
- @brief remove elements given an iterator range
-
- Removes the element specified by the range `[first; last)`. The iterator
- @a first does not need to be dereferenceable if `first == last`: erasing
- an empty range is a no-op.
-
- If called on a primitive type other than `null`, the resulting JSON value
- will be `null`.
-
- @param[in] first iterator to the beginning of the range to remove
- @param[in] last iterator past the end of the range to remove
- @return Iterator following the last removed element. If the iterator @a
- second refers to the last element, the `end()` iterator is returned.
-
- @tparam IteratorType an @ref iterator or @ref const_iterator
-
- @post Invalidates iterators and references at or after the point of the
- erase, including the `end()` iterator.
-
- @throw type_error.307 if called on a `null` value; example: `"cannot use
- erase() with null"`
- @throw invalid_iterator.203 if called on iterators which does not belong
- to the current JSON value; example: `"iterators do not fit current value"`
- @throw invalid_iterator.204 if called on a primitive type with invalid
- iterators (i.e., if `first != begin()` and `last != end()`); example:
- `"iterators out of range"`
-
- @complexity The complexity depends on the type:
- - objects: `log(size()) + std::distance(first, last)`
- - arrays: linear in the distance between @a first and @a last, plus linear
- in the distance between @a last and end of the container
- - strings and binary: linear in the length of the member
- - other types: constant
-
- @liveexample{The example shows the result of `erase()` for different JSON
- types.,erase__IteratorType_IteratorType}
-
- @sa see @ref erase(IteratorType) -- removes the element at a given position
- @sa see @ref erase(const typename object_t::key_type&) -- removes the element
- from an object at the given key
- @sa see @ref erase(const size_type) -- removes the element from an array at
- the given index
-
- @since version 1.0.0
- */
+ /// @brief remove elements given an iterator range
+ /// @sa https://json.nlohmann.me/api/basic_json/erase/
template < class IteratorType, typename std::enable_if <
std::is_same<IteratorType, typename basic_json_t::iterator>::value ||
std::is_same<IteratorType, typename basic_json_t::const_iterator>::value, int >::type
@@ -21907,35 +19551,8 @@
return result;
}
- /*!
- @brief remove element from a JSON object given a key
-
- Removes elements from a JSON object with the key value @a key.
-
- @param[in] key value of the elements to remove
-
- @return Number of elements removed. If @a ObjectType is the default
- `std::map` type, the return value will always be `0` (@a key was not
- found) or `1` (@a key was found).
-
- @post References and iterators to the erased elements are invalidated.
- Other references and iterators are not affected.
-
- @throw type_error.307 when called on a type other than JSON object;
- example: `"cannot use erase() with null"`
-
- @complexity `log(size()) + count(key)`
-
- @liveexample{The example shows the effect of `erase()`.,erase__key_type}
-
- @sa see @ref erase(IteratorType) -- removes the element at a given position
- @sa see @ref erase(IteratorType, IteratorType) -- removes the elements in
- the given range
- @sa see @ref erase(const size_type) -- removes the element from an array at
- the given index
-
- @since version 1.0.0
- */
+ /// @brief remove element from a JSON object given a key
+ /// @sa https://json.nlohmann.me/api/basic_json/erase/
size_type erase(const typename object_t::key_type& key)
{
// this erase only works for objects
@@ -21947,30 +19564,8 @@
JSON_THROW(type_error::create(307, "cannot use erase() with " + std::string(type_name()), *this));
}
- /*!
- @brief remove element from a JSON array given an index
-
- Removes element from a JSON array at the index @a idx.
-
- @param[in] idx index of the element to remove
-
- @throw type_error.307 when called on a type other than JSON object;
- example: `"cannot use erase() with null"`
- @throw out_of_range.401 when `idx >= size()`; example: `"array index 17
- is out of range"`
-
- @complexity Linear in distance between @a idx and the end of the container.
-
- @liveexample{The example shows the effect of `erase()`.,erase__size_type}
-
- @sa see @ref erase(IteratorType) -- removes the element at a given position
- @sa see @ref erase(IteratorType, IteratorType) -- removes the elements in
- the given range
- @sa see @ref erase(const typename object_t::key_type&) -- removes the element
- from an object at the given key
-
- @since version 1.0.0
- */
+ /// @brief remove element from a JSON array given an index
+ /// @sa https://json.nlohmann.me/api/basic_json/erase/
void erase(const size_type idx)
{
// this erase only works for arrays
@@ -21999,30 +19594,8 @@
/// @name lookup
/// @{
- /*!
- @brief find an element in a JSON object
-
- Finds an element in a JSON object with key equivalent to @a key. If the
- element is not found or the JSON value is not an object, end() is
- returned.
-
- @note This method always returns @ref end() when executed on a JSON type
- that is not an object.
-
- @param[in] key key value of the element to search for.
-
- @return Iterator to an element with key equivalent to @a key. If no such
- element is found or the JSON value is not an object, past-the-end (see
- @ref end()) iterator is returned.
-
- @complexity Logarithmic in the size of the JSON object.
-
- @liveexample{The example shows how `find()` is used.,find__key_type}
-
- @sa see @ref contains(KeyT&&) const -- checks whether a key exists
-
- @since version 1.0.0
- */
+ /// @brief find an element in a JSON object
+ /// @sa https://json.nlohmann.me/api/basic_json/find/
template<typename KeyT>
iterator find(KeyT&& key)
{
@@ -22036,10 +19609,8 @@
return result;
}
- /*!
- @brief find an element in a JSON object
- @copydoc find(KeyT&&)
- */
+ /// @brief find an element in a JSON object
+ /// @sa https://json.nlohmann.me/api/basic_json/find/
template<typename KeyT>
const_iterator find(KeyT&& key) const
{
@@ -22053,27 +19624,8 @@
return result;
}
- /*!
- @brief returns the number of occurrences of a key in a JSON object
-
- Returns the number of elements with key @a key. If ObjectType is the
- default `std::map` type, the return value will always be `0` (@a key was
- not found) or `1` (@a key was found).
-
- @note This method always returns `0` when executed on a JSON type that is
- not an object.
-
- @param[in] key key value of the element to count
-
- @return Number of elements with key @a key. If the JSON value is not an
- object, the return value will be `0`.
-
- @complexity Logarithmic in the size of the JSON object.
-
- @liveexample{The example shows how `count()` is used.,count}
-
- @since version 1.0.0
- */
+ /// @brief returns the number of occurrences of a key in a JSON object
+ /// @sa https://json.nlohmann.me/api/basic_json/count/
template<typename KeyT>
size_type count(KeyT&& key) const
{
@@ -22081,31 +19633,8 @@
return is_object() ? m_value.object->count(std::forward<KeyT>(key)) : 0;
}
- /*!
- @brief check the existence of an element in a JSON object
-
- Check whether an element exists in a JSON object with key equivalent to
- @a key. If the element is not found or the JSON value is not an object,
- false is returned.
-
- @note This method always returns false when executed on a JSON type
- that is not an object.
-
- @param[in] key key value to check its existence.
-
- @return true if an element with specified @a key exists. If no such
- element with such key is found or the JSON value is not an object,
- false is returned.
-
- @complexity Logarithmic in the size of the JSON object.
-
- @liveexample{The following code shows an example for `contains()`.,contains}
-
- @sa see @ref find(KeyT&&) -- returns an iterator to an object element
- @sa see @ref contains(const json_pointer&) const -- checks the existence for a JSON pointer
-
- @since version 3.6.0
- */
+ /// @brief check the existence of an element in a JSON object
+ /// @sa https://json.nlohmann.me/api/basic_json/contains/
template < typename KeyT, typename std::enable_if <
!std::is_same<typename std::decay<KeyT>::type, json_pointer>::value, int >::type = 0 >
bool contains(KeyT && key) const
@@ -22113,32 +19642,8 @@
return is_object() && m_value.object->find(std::forward<KeyT>(key)) != m_value.object->end();
}
- /*!
- @brief check the existence of an element in a JSON object given a JSON pointer
-
- Check whether the given JSON pointer @a ptr can be resolved in the current
- JSON value.
-
- @note This method can be executed on any JSON value type.
-
- @param[in] ptr JSON pointer to check its existence.
-
- @return true if the JSON pointer can be resolved to a stored value, false
- otherwise.
-
- @post If `j.contains(ptr)` returns true, it is safe to call `j[ptr]`.
-
- @throw parse_error.106 if an array index begins with '0'
- @throw parse_error.109 if an array index was not a number
-
- @complexity Logarithmic in the size of the JSON object.
-
- @liveexample{The following code shows an example for `contains()`.,contains_json_pointer}
-
- @sa see @ref contains(KeyT &&) const -- checks the existence of a key
-
- @since version 3.7.0
- */
+ /// @brief check the existence of an element in a JSON object given a JSON pointer
+ /// @sa https://json.nlohmann.me/api/basic_json/contains/
bool contains(const json_pointer& ptr) const
{
return ptr.contains(this);
@@ -22154,30 +19659,8 @@
/// @name iterators
/// @{
- /*!
- @brief returns an iterator to the first element
-
- Returns an iterator to the first element.
-
- @image html range-begin-end.svg "Illustration from cppreference.com"
-
- @return iterator to the first element
-
- @complexity Constant.
-
- @requirement This function helps `basic_json` satisfying the
- [Container](https://en.cppreference.com/w/cpp/named_req/Container)
- requirements:
- - The complexity is constant.
-
- @liveexample{The following code shows an example for `begin()`.,begin}
-
- @sa see @ref cbegin() -- returns a const iterator to the beginning
- @sa see @ref end() -- returns an iterator to the end
- @sa see @ref cend() -- returns a const iterator to the end
-
- @since version 1.0.0
- */
+ /// @brief returns an iterator to the first element
+ /// @sa https://json.nlohmann.me/api/basic_json/begin/
iterator begin() noexcept
{
iterator result(this);
@@ -22185,39 +19668,15 @@
return result;
}
- /*!
- @copydoc basic_json::cbegin()
- */
+ /// @brief returns an iterator to the first element
+ /// @sa https://json.nlohmann.me/api/basic_json/begin/
const_iterator begin() const noexcept
{
return cbegin();
}
- /*!
- @brief returns a const iterator to the first element
-
- Returns a const iterator to the first element.
-
- @image html range-begin-end.svg "Illustration from cppreference.com"
-
- @return const iterator to the first element
-
- @complexity Constant.
-
- @requirement This function helps `basic_json` satisfying the
- [Container](https://en.cppreference.com/w/cpp/named_req/Container)
- requirements:
- - The complexity is constant.
- - Has the semantics of `const_cast<const basic_json&>(*this).begin()`.
-
- @liveexample{The following code shows an example for `cbegin()`.,cbegin}
-
- @sa see @ref begin() -- returns an iterator to the beginning
- @sa see @ref end() -- returns an iterator to the end
- @sa see @ref cend() -- returns a const iterator to the end
-
- @since version 1.0.0
- */
+ /// @brief returns a const iterator to the first element
+ /// @sa https://json.nlohmann.me/api/basic_json/cbegin/
const_iterator cbegin() const noexcept
{
const_iterator result(this);
@@ -22225,30 +19684,8 @@
return result;
}
- /*!
- @brief returns an iterator to one past the last element
-
- Returns an iterator to one past the last element.
-
- @image html range-begin-end.svg "Illustration from cppreference.com"
-
- @return iterator one past the last element
-
- @complexity Constant.
-
- @requirement This function helps `basic_json` satisfying the
- [Container](https://en.cppreference.com/w/cpp/named_req/Container)
- requirements:
- - The complexity is constant.
-
- @liveexample{The following code shows an example for `end()`.,end}
-
- @sa see @ref cend() -- returns a const iterator to the end
- @sa see @ref begin() -- returns an iterator to the beginning
- @sa see @ref cbegin() -- returns a const iterator to the beginning
-
- @since version 1.0.0
- */
+ /// @brief returns an iterator to one past the last element
+ /// @sa https://json.nlohmann.me/api/basic_json/end/
iterator end() noexcept
{
iterator result(this);
@@ -22256,39 +19693,15 @@
return result;
}
- /*!
- @copydoc basic_json::cend()
- */
+ /// @brief returns an iterator to one past the last element
+ /// @sa https://json.nlohmann.me/api/basic_json/end/
const_iterator end() const noexcept
{
return cend();
}
- /*!
- @brief returns a const iterator to one past the last element
-
- Returns a const iterator to one past the last element.
-
- @image html range-begin-end.svg "Illustration from cppreference.com"
-
- @return const iterator one past the last element
-
- @complexity Constant.
-
- @requirement This function helps `basic_json` satisfying the
- [Container](https://en.cppreference.com/w/cpp/named_req/Container)
- requirements:
- - The complexity is constant.
- - Has the semantics of `const_cast<const basic_json&>(*this).end()`.
-
- @liveexample{The following code shows an example for `cend()`.,cend}
-
- @sa see @ref end() -- returns an iterator to the end
- @sa see @ref begin() -- returns an iterator to the beginning
- @sa see @ref cbegin() -- returns a const iterator to the beginning
-
- @since version 1.0.0
- */
+ /// @brief returns an iterator to one past the last element
+ /// @sa https://json.nlohmann.me/api/basic_json/cend/
const_iterator cend() const noexcept
{
const_iterator result(this);
@@ -22296,286 +19709,80 @@
return result;
}
- /*!
- @brief returns an iterator to the reverse-beginning
-
- Returns an iterator to the reverse-beginning; that is, the last element.
-
- @image html range-rbegin-rend.svg "Illustration from cppreference.com"
-
- @complexity Constant.
-
- @requirement This function helps `basic_json` satisfying the
- [ReversibleContainer](https://en.cppreference.com/w/cpp/named_req/ReversibleContainer)
- requirements:
- - The complexity is constant.
- - Has the semantics of `reverse_iterator(end())`.
-
- @liveexample{The following code shows an example for `rbegin()`.,rbegin}
-
- @sa see @ref crbegin() -- returns a const reverse iterator to the beginning
- @sa see @ref rend() -- returns a reverse iterator to the end
- @sa see @ref crend() -- returns a const reverse iterator to the end
-
- @since version 1.0.0
- */
+ /// @brief returns an iterator to the reverse-beginning
+ /// @sa https://json.nlohmann.me/api/basic_json/rbegin/
reverse_iterator rbegin() noexcept
{
return reverse_iterator(end());
}
- /*!
- @copydoc basic_json::crbegin()
- */
+ /// @brief returns an iterator to the reverse-beginning
+ /// @sa https://json.nlohmann.me/api/basic_json/rbegin/
const_reverse_iterator rbegin() const noexcept
{
return crbegin();
}
- /*!
- @brief returns an iterator to the reverse-end
-
- Returns an iterator to the reverse-end; that is, one before the first
- element.
-
- @image html range-rbegin-rend.svg "Illustration from cppreference.com"
-
- @complexity Constant.
-
- @requirement This function helps `basic_json` satisfying the
- [ReversibleContainer](https://en.cppreference.com/w/cpp/named_req/ReversibleContainer)
- requirements:
- - The complexity is constant.
- - Has the semantics of `reverse_iterator(begin())`.
-
- @liveexample{The following code shows an example for `rend()`.,rend}
-
- @sa see @ref crend() -- returns a const reverse iterator to the end
- @sa see @ref rbegin() -- returns a reverse iterator to the beginning
- @sa see @ref crbegin() -- returns a const reverse iterator to the beginning
-
- @since version 1.0.0
- */
+ /// @brief returns an iterator to the reverse-end
+ /// @sa https://json.nlohmann.me/api/basic_json/rend/
reverse_iterator rend() noexcept
{
return reverse_iterator(begin());
}
- /*!
- @copydoc basic_json::crend()
- */
+ /// @brief returns an iterator to the reverse-end
+ /// @sa https://json.nlohmann.me/api/basic_json/rend/
const_reverse_iterator rend() const noexcept
{
return crend();
}
- /*!
- @brief returns a const reverse iterator to the last element
-
- Returns a const iterator to the reverse-beginning; that is, the last
- element.
-
- @image html range-rbegin-rend.svg "Illustration from cppreference.com"
-
- @complexity Constant.
-
- @requirement This function helps `basic_json` satisfying the
- [ReversibleContainer](https://en.cppreference.com/w/cpp/named_req/ReversibleContainer)
- requirements:
- - The complexity is constant.
- - Has the semantics of `const_cast<const basic_json&>(*this).rbegin()`.
-
- @liveexample{The following code shows an example for `crbegin()`.,crbegin}
-
- @sa see @ref rbegin() -- returns a reverse iterator to the beginning
- @sa see @ref rend() -- returns a reverse iterator to the end
- @sa see @ref crend() -- returns a const reverse iterator to the end
-
- @since version 1.0.0
- */
+ /// @brief returns a const reverse iterator to the last element
+ /// @sa https://json.nlohmann.me/api/basic_json/crbegin/
const_reverse_iterator crbegin() const noexcept
{
return const_reverse_iterator(cend());
}
- /*!
- @brief returns a const reverse iterator to one before the first
-
- Returns a const reverse iterator to the reverse-end; that is, one before
- the first element.
-
- @image html range-rbegin-rend.svg "Illustration from cppreference.com"
-
- @complexity Constant.
-
- @requirement This function helps `basic_json` satisfying the
- [ReversibleContainer](https://en.cppreference.com/w/cpp/named_req/ReversibleContainer)
- requirements:
- - The complexity is constant.
- - Has the semantics of `const_cast<const basic_json&>(*this).rend()`.
-
- @liveexample{The following code shows an example for `crend()`.,crend}
-
- @sa see @ref rend() -- returns a reverse iterator to the end
- @sa see @ref rbegin() -- returns a reverse iterator to the beginning
- @sa see @ref crbegin() -- returns a const reverse iterator to the beginning
-
- @since version 1.0.0
- */
+ /// @brief returns a const reverse iterator to one before the first
+ /// @sa https://json.nlohmann.me/api/basic_json/crend/
const_reverse_iterator crend() const noexcept
{
return const_reverse_iterator(cbegin());
}
public:
- /*!
- @brief wrapper to access iterator member functions in range-based for
-
- This function allows to access @ref iterator::key() and @ref
- iterator::value() during range-based for loops. In these loops, a
- reference to the JSON values is returned, so there is no access to the
- underlying iterator.
-
- For loop without iterator_wrapper:
-
- @code{cpp}
- for (auto it = j_object.begin(); it != j_object.end(); ++it)
- {
- std::cout << "key: " << it.key() << ", value:" << it.value() << '\n';
- }
- @endcode
-
- Range-based for loop without iterator proxy:
-
- @code{cpp}
- for (auto it : j_object)
- {
- // "it" is of type json::reference and has no key() member
- std::cout << "value: " << it << '\n';
- }
- @endcode
-
- Range-based for loop with iterator proxy:
-
- @code{cpp}
- for (auto it : json::iterator_wrapper(j_object))
- {
- std::cout << "key: " << it.key() << ", value:" << it.value() << '\n';
- }
- @endcode
-
- @note When iterating over an array, `key()` will return the index of the
- element as string (see example).
-
- @param[in] ref reference to a JSON value
- @return iteration proxy object wrapping @a ref with an interface to use in
- range-based for loops
-
- @liveexample{The following code shows how the wrapper is used,iterator_wrapper}
-
- @exceptionsafety Strong guarantee: if an exception is thrown, there are no
- changes in the JSON value.
-
- @complexity Constant.
-
- @note The name of this function is not yet final and may change in the
- future.
-
- @deprecated This stream operator is deprecated and will be removed in
- future 4.0.0 of the library. Please use @ref items() instead;
- that is, replace `json::iterator_wrapper(j)` with `j.items()`.
- */
+ /// @brief wrapper to access iterator member functions in range-based for
+ /// @sa https://json.nlohmann.me/api/basic_json/items/
+ /// @deprecated This function is deprecated since 3.1.0 and will be removed in
+ /// version 4.0.0 of the library. Please use @ref items() instead;
+ /// that is, replace `json::iterator_wrapper(j)` with `j.items()`.
JSON_HEDLEY_DEPRECATED_FOR(3.1.0, items())
static iteration_proxy<iterator> iterator_wrapper(reference ref) noexcept
{
return ref.items();
}
- /*!
- @copydoc iterator_wrapper(reference)
- */
+ /// @brief wrapper to access iterator member functions in range-based for
+ /// @sa https://json.nlohmann.me/api/basic_json/items/
+ /// @deprecated This function is deprecated since 3.1.0 and will be removed in
+ /// version 4.0.0 of the library. Please use @ref items() instead;
+ /// that is, replace `json::iterator_wrapper(j)` with `j.items()`.
JSON_HEDLEY_DEPRECATED_FOR(3.1.0, items())
static iteration_proxy<const_iterator> iterator_wrapper(const_reference ref) noexcept
{
return ref.items();
}
- /*!
- @brief helper to access iterator member functions in range-based for
-
- This function allows to access @ref iterator::key() and @ref
- iterator::value() during range-based for loops. In these loops, a
- reference to the JSON values is returned, so there is no access to the
- underlying iterator.
-
- For loop without `items()` function:
-
- @code{cpp}
- for (auto it = j_object.begin(); it != j_object.end(); ++it)
- {
- std::cout << "key: " << it.key() << ", value:" << it.value() << '\n';
- }
- @endcode
-
- Range-based for loop without `items()` function:
-
- @code{cpp}
- for (auto it : j_object)
- {
- // "it" is of type json::reference and has no key() member
- std::cout << "value: " << it << '\n';
- }
- @endcode
-
- Range-based for loop with `items()` function:
-
- @code{cpp}
- for (auto& el : j_object.items())
- {
- std::cout << "key: " << el.key() << ", value:" << el.value() << '\n';
- }
- @endcode
-
- The `items()` function also allows to use
- [structured bindings](https://en.cppreference.com/w/cpp/language/structured_binding)
- (C++17):
-
- @code{cpp}
- for (auto& [key, val] : j_object.items())
- {
- std::cout << "key: " << key << ", value:" << val << '\n';
- }
- @endcode
-
- @note When iterating over an array, `key()` will return the index of the
- element as string (see example). For primitive types (e.g., numbers),
- `key()` returns an empty string.
-
- @warning Using `items()` on temporary objects is dangerous. Make sure the
- object's lifetime exeeds the iteration. See
- <https://github.com/nlohmann/json/issues/2040> for more
- information.
-
- @return iteration proxy object wrapping @a ref with an interface to use in
- range-based for loops
-
- @liveexample{The following code shows how the function is used.,items}
-
- @exceptionsafety Strong guarantee: if an exception is thrown, there are no
- changes in the JSON value.
-
- @complexity Constant.
-
- @since version 3.1.0, structured bindings support since 3.5.0.
- */
+ /// @brief helper to access iterator member functions in range-based for
+ /// @sa https://json.nlohmann.me/api/basic_json/items/
iteration_proxy<iterator> items() noexcept
{
return iteration_proxy<iterator>(*this);
}
- /*!
- @copydoc items()
- */
+ /// @brief helper to access iterator member functions in range-based for
+ /// @sa https://json.nlohmann.me/api/basic_json/items/
iteration_proxy<const_iterator> items() const noexcept
{
return iteration_proxy<const_iterator>(*this);
@@ -22591,48 +19798,8 @@
/// @name capacity
/// @{
- /*!
- @brief checks whether the container is empty.
-
- Checks if a JSON value has no elements (i.e. whether its @ref size is `0`).
-
- @return The return value depends on the different types and is
- defined as follows:
- Value type | return value
- ----------- | -------------
- null | `true`
- boolean | `false`
- string | `false`
- number | `false`
- binary | `false`
- object | result of function `object_t::empty()`
- array | result of function `array_t::empty()`
-
- @liveexample{The following code uses `empty()` to check if a JSON
- object contains any elements.,empty}
-
- @complexity Constant, as long as @ref array_t and @ref object_t satisfy
- the Container concept; that is, their `empty()` functions have constant
- complexity.
-
- @iterators No changes.
-
- @exceptionsafety No-throw guarantee: this function never throws exceptions.
-
- @note This function does not return whether a string stored as JSON value
- is empty - it returns whether the JSON container itself is empty which is
- false in the case of a string.
-
- @requirement This function helps `basic_json` satisfying the
- [Container](https://en.cppreference.com/w/cpp/named_req/Container)
- requirements:
- - The complexity is constant.
- - Has the semantics of `begin() == end()`.
-
- @sa see @ref size() -- returns the number of elements
-
- @since version 1.0.0
- */
+ /// @brief checks whether the container is empty.
+ /// @sa https://json.nlohmann.me/api/basic_json/empty/
bool empty() const noexcept
{
switch (m_type)
@@ -22670,49 +19837,8 @@
}
}
- /*!
- @brief returns the number of elements
-
- Returns the number of elements in a JSON value.
-
- @return The return value depends on the different types and is
- defined as follows:
- Value type | return value
- ----------- | -------------
- null | `0`
- boolean | `1`
- string | `1`
- number | `1`
- binary | `1`
- object | result of function object_t::size()
- array | result of function array_t::size()
-
- @liveexample{The following code calls `size()` on the different value
- types.,size}
-
- @complexity Constant, as long as @ref array_t and @ref object_t satisfy
- the Container concept; that is, their size() functions have constant
- complexity.
-
- @iterators No changes.
-
- @exceptionsafety No-throw guarantee: this function never throws exceptions.
-
- @note This function does not return the length of a string stored as JSON
- value - it returns the number of elements in the JSON value which is 1 in
- the case of a string.
-
- @requirement This function helps `basic_json` satisfying the
- [Container](https://en.cppreference.com/w/cpp/named_req/Container)
- requirements:
- - The complexity is constant.
- - Has the semantics of `std::distance(begin(), end())`.
-
- @sa see @ref empty() -- checks whether the container is empty
- @sa see @ref max_size() -- returns the maximal number of elements
-
- @since version 1.0.0
- */
+ /// @brief returns the number of elements
+ /// @sa https://json.nlohmann.me/api/basic_json/size/
size_type size() const noexcept
{
switch (m_type)
@@ -22750,47 +19876,8 @@
}
}
- /*!
- @brief returns the maximum possible number of elements
-
- Returns the maximum number of elements a JSON value is able to hold due to
- system or library implementation limitations, i.e. `std::distance(begin(),
- end())` for the JSON value.
-
- @return The return value depends on the different types and is
- defined as follows:
- Value type | return value
- ----------- | -------------
- null | `0` (same as `size()`)
- boolean | `1` (same as `size()`)
- string | `1` (same as `size()`)
- number | `1` (same as `size()`)
- binary | `1` (same as `size()`)
- object | result of function `object_t::max_size()`
- array | result of function `array_t::max_size()`
-
- @liveexample{The following code calls `max_size()` on the different value
- types. Note the output is implementation specific.,max_size}
-
- @complexity Constant, as long as @ref array_t and @ref object_t satisfy
- the Container concept; that is, their `max_size()` functions have constant
- complexity.
-
- @iterators No changes.
-
- @exceptionsafety No-throw guarantee: this function never throws exceptions.
-
- @requirement This function helps `basic_json` satisfying the
- [Container](https://en.cppreference.com/w/cpp/named_req/Container)
- requirements:
- - The complexity is constant.
- - Has the semantics of returning `b.size()` where `b` is the largest
- possible JSON value.
-
- @sa see @ref size() -- returns the number of elements
-
- @since version 1.0.0
- */
+ /// @brief returns the maximum possible number of elements
+ /// @sa https://json.nlohmann.me/api/basic_json/max_size/
size_type max_size() const noexcept
{
switch (m_type)
@@ -22833,43 +19920,8 @@
/// @name modifiers
/// @{
- /*!
- @brief clears the contents
-
- Clears the content of a JSON value and resets it to the default value as
- if @ref basic_json(value_t) would have been called with the current value
- type from @ref type():
-
- Value type | initial value
- ----------- | -------------
- null | `null`
- boolean | `false`
- string | `""`
- number | `0`
- binary | An empty byte vector
- object | `{}`
- array | `[]`
-
- @post Has the same effect as calling
- @code {.cpp}
- *this = basic_json(type());
- @endcode
-
- @liveexample{The example below shows the effect of `clear()` to different
- JSON types.,clear}
-
- @complexity Linear in the size of the JSON value.
-
- @iterators All iterators, pointers and references related to this container
- are invalidated.
-
- @exceptionsafety No-throw guarantee: this function never throws exceptions.
-
- @sa see @ref basic_json(value_t) -- constructor that creates an object with the
- same value than calling `clear()`
-
- @since version 1.0.0
- */
+ /// @brief clears the contents
+ /// @sa https://json.nlohmann.me/api/basic_json/clear/
void clear() noexcept
{
switch (m_type)
@@ -22929,26 +19981,8 @@
}
}
- /*!
- @brief add an object to an array
-
- Appends the given element @a val to the end of the JSON value. If the
- function is called on a JSON null value, an empty array is created before
- appending @a val.
-
- @param[in] val the value to add to the JSON array
-
- @throw type_error.308 when called on a type other than JSON array or
- null; example: `"cannot use push_back() with number"`
-
- @complexity Amortized constant.
-
- @liveexample{The example shows how `push_back()` and `+=` can be used to
- add elements to a JSON array. Note how the `null` value was silently
- converted to a JSON array.,push_back}
-
- @since version 1.0.0
- */
+ /// @brief add an object to an array
+ /// @sa https://json.nlohmann.me/api/basic_json/push_back/
void push_back(basic_json&& val)
{
// push_back only works for null objects or arrays
@@ -22969,23 +20003,19 @@
const auto old_capacity = m_value.array->capacity();
m_value.array->push_back(std::move(val));
set_parent(m_value.array->back(), old_capacity);
- // if val is moved from, basic_json move constructor marks it null so we do not call the destructor
+ // if val is moved from, basic_json move constructor marks it null, so we do not call the destructor
}
- /*!
- @brief add an object to an array
- @copydoc push_back(basic_json&&)
- */
+ /// @brief add an object to an array
+ /// @sa https://json.nlohmann.me/api/basic_json/operator+=/
reference operator+=(basic_json&& val)
{
push_back(std::move(val));
return *this;
}
- /*!
- @brief add an object to an array
- @copydoc push_back(basic_json&&)
- */
+ /// @brief add an object to an array
+ /// @sa https://json.nlohmann.me/api/basic_json/push_back/
void push_back(const basic_json& val)
{
// push_back only works for null objects or arrays
@@ -23008,36 +20038,16 @@
set_parent(m_value.array->back(), old_capacity);
}
- /*!
- @brief add an object to an array
- @copydoc push_back(basic_json&&)
- */
+ /// @brief add an object to an array
+ /// @sa https://json.nlohmann.me/api/basic_json/operator+=/
reference operator+=(const basic_json& val)
{
push_back(val);
return *this;
}
- /*!
- @brief add an object to an object
-
- Inserts the given element @a val to the JSON object. If the function is
- called on a JSON null value, an empty object is created before inserting
- @a val.
-
- @param[in] val the value to add to the JSON object
-
- @throw type_error.308 when called on a type other than JSON object or
- null; example: `"cannot use push_back() with number"`
-
- @complexity Logarithmic in the size of the container, O(log(`size()`)).
-
- @liveexample{The example shows how `push_back()` and `+=` can be used to
- add elements to a JSON object. Note how the `null` value was silently
- converted to a JSON object.,push_back__object_t__value}
-
- @since version 1.0.0
- */
+ /// @brief add an object to an object
+ /// @sa https://json.nlohmann.me/api/basic_json/push_back/
void push_back(const typename object_t::value_type& val)
{
// push_back only works for null objects or objects
@@ -23059,41 +20069,16 @@
set_parent(res.first->second);
}
- /*!
- @brief add an object to an object
- @copydoc push_back(const typename object_t::value_type&)
- */
+ /// @brief add an object to an object
+ /// @sa https://json.nlohmann.me/api/basic_json/operator+=/
reference operator+=(const typename object_t::value_type& val)
{
push_back(val);
return *this;
}
- /*!
- @brief add an object to an object
-
- This function allows to use `push_back` with an initializer list. In case
-
- 1. the current value is an object,
- 2. the initializer list @a init contains only two elements, and
- 3. the first element of @a init is a string,
-
- @a init is converted into an object element and added using
- @ref push_back(const typename object_t::value_type&). Otherwise, @a init
- is converted to a JSON value and added using @ref push_back(basic_json&&).
-
- @param[in] init an initializer list
-
- @complexity Linear in the size of the initializer list @a init.
-
- @note This function is required to resolve an ambiguous overload error,
- because pairs like `{"key", "value"}` can be both interpreted as
- `object_t::value_type` or `std::initializer_list<basic_json>`, see
- https://github.com/nlohmann/json/issues/235 for more information.
-
- @liveexample{The example shows how initializer lists are treated as
- objects when possible.,push_back__initializer_list}
- */
+ /// @brief add an object to an object
+ /// @sa https://json.nlohmann.me/api/basic_json/push_back/
void push_back(initializer_list_t init)
{
if (is_object() && init.size() == 2 && (*init.begin())->is_string())
@@ -23108,39 +20093,16 @@
}
}
- /*!
- @brief add an object to an object
- @copydoc push_back(initializer_list_t)
- */
+ /// @brief add an object to an object
+ /// @sa https://json.nlohmann.me/api/basic_json/operator+=/
reference operator+=(initializer_list_t init)
{
push_back(init);
return *this;
}
- /*!
- @brief add an object to an array
-
- Creates a JSON value from the passed parameters @a args to the end of the
- JSON value. If the function is called on a JSON null value, an empty array
- is created before appending the value created from @a args.
-
- @param[in] args arguments to forward to a constructor of @ref basic_json
- @tparam Args compatible types to create a @ref basic_json object
-
- @return reference to the inserted element
-
- @throw type_error.311 when called on a type other than JSON array or
- null; example: `"cannot use emplace_back() with number"`
-
- @complexity Amortized constant.
-
- @liveexample{The example shows how `push_back()` can be used to add
- elements to a JSON array. Note how the `null` value was silently converted
- to a JSON array.,emplace_back}
-
- @since version 2.0.8, returns reference since 3.7.0
- */
+ /// @brief add an object to an array
+ /// @sa https://json.nlohmann.me/api/basic_json/emplace_back/
template<class... Args>
reference emplace_back(Args&& ... args)
{
@@ -23164,33 +20126,8 @@
return set_parent(m_value.array->back(), old_capacity);
}
- /*!
- @brief add an object to an object if key does not exist
-
- Inserts a new element into a JSON object constructed in-place with the
- given @a args if there is no element with the key in the container. If the
- function is called on a JSON null value, an empty object is created before
- appending the value created from @a args.
-
- @param[in] args arguments to forward to a constructor of @ref basic_json
- @tparam Args compatible types to create a @ref basic_json object
-
- @return a pair consisting of an iterator to the inserted element, or the
- already-existing element if no insertion happened, and a bool
- denoting whether the insertion took place.
-
- @throw type_error.311 when called on a type other than JSON object or
- null; example: `"cannot use emplace() with number"`
-
- @complexity Logarithmic in the size of the container, O(log(`size()`)).
-
- @liveexample{The example shows how `emplace()` can be used to add elements
- to a JSON object. Note how the `null` value was silently converted to a
- JSON object. Further note how no value is added if there was already one
- value stored with the same key.,emplace}
-
- @since version 2.0.8
- */
+ /// @brief add an object to an object if key does not exist
+ /// @sa https://json.nlohmann.me/api/basic_json/emplace/
template<class... Args>
std::pair<iterator, bool> emplace(Args&& ... args)
{
@@ -23241,28 +20178,8 @@
return result;
}
- /*!
- @brief inserts element
-
- Inserts element @a val before iterator @a pos.
-
- @param[in] pos iterator before which the content will be inserted; may be
- the end() iterator
- @param[in] val element to insert
- @return iterator pointing to the inserted @a val.
-
- @throw type_error.309 if called on JSON values other than arrays;
- example: `"cannot use insert() with string"`
- @throw invalid_iterator.202 if @a pos is not an iterator of *this;
- example: `"iterator does not fit current value"`
-
- @complexity Constant plus linear in the distance between @a pos and end of
- the container.
-
- @liveexample{The example shows how `insert()` is used.,insert}
-
- @since version 1.0.0
- */
+ /// @brief inserts element into array
+ /// @sa https://json.nlohmann.me/api/basic_json/insert/
iterator insert(const_iterator pos, const basic_json& val)
{
// insert only works for arrays
@@ -23281,39 +20198,15 @@
JSON_THROW(type_error::create(309, "cannot use insert() with " + std::string(type_name()), *this));
}
- /*!
- @brief inserts element
- @copydoc insert(const_iterator, const basic_json&)
- */
+ /// @brief inserts element into array
+ /// @sa https://json.nlohmann.me/api/basic_json/insert/
iterator insert(const_iterator pos, basic_json&& val)
{
return insert(pos, val);
}
- /*!
- @brief inserts elements
-
- Inserts @a cnt copies of @a val before iterator @a pos.
-
- @param[in] pos iterator before which the content will be inserted; may be
- the end() iterator
- @param[in] cnt number of copies of @a val to insert
- @param[in] val element to insert
- @return iterator pointing to the first element inserted, or @a pos if
- `cnt==0`
-
- @throw type_error.309 if called on JSON values other than arrays; example:
- `"cannot use insert() with string"`
- @throw invalid_iterator.202 if @a pos is not an iterator of *this;
- example: `"iterator does not fit current value"`
-
- @complexity Linear in @a cnt plus linear in the distance between @a pos
- and end of the container.
-
- @liveexample{The example shows how `insert()` is used.,insert__count}
-
- @since version 1.0.0
- */
+ /// @brief inserts copies of element into array
+ /// @sa https://json.nlohmann.me/api/basic_json/insert/
iterator insert(const_iterator pos, size_type cnt, const basic_json& val)
{
// insert only works for arrays
@@ -23332,36 +20225,8 @@
JSON_THROW(type_error::create(309, "cannot use insert() with " + std::string(type_name()), *this));
}
- /*!
- @brief inserts elements
-
- Inserts elements from range `[first, last)` before iterator @a pos.
-
- @param[in] pos iterator before which the content will be inserted; may be
- the end() iterator
- @param[in] first begin of the range of elements to insert
- @param[in] last end of the range of elements to insert
-
- @throw type_error.309 if called on JSON values other than arrays; example:
- `"cannot use insert() with string"`
- @throw invalid_iterator.202 if @a pos is not an iterator of *this;
- example: `"iterator does not fit current value"`
- @throw invalid_iterator.210 if @a first and @a last do not belong to the
- same JSON value; example: `"iterators do not fit"`
- @throw invalid_iterator.211 if @a first or @a last are iterators into
- container for which insert is called; example: `"passed iterators may not
- belong to container"`
-
- @return iterator pointing to the first element inserted, or @a pos if
- `first==last`
-
- @complexity Linear in `std::distance(first, last)` plus linear in the
- distance between @a pos and end of the container.
-
- @liveexample{The example shows how `insert()` is used.,insert__range}
-
- @since version 1.0.0
- */
+ /// @brief inserts range of elements into array
+ /// @sa https://json.nlohmann.me/api/basic_json/insert/
iterator insert(const_iterator pos, const_iterator first, const_iterator last)
{
// insert only works for arrays
@@ -23391,30 +20256,8 @@
return insert_iterator(pos, first.m_it.array_iterator, last.m_it.array_iterator);
}
- /*!
- @brief inserts elements
-
- Inserts elements from initializer list @a ilist before iterator @a pos.
-
- @param[in] pos iterator before which the content will be inserted; may be
- the end() iterator
- @param[in] ilist initializer list to insert the values from
-
- @throw type_error.309 if called on JSON values other than arrays; example:
- `"cannot use insert() with string"`
- @throw invalid_iterator.202 if @a pos is not an iterator of *this;
- example: `"iterator does not fit current value"`
-
- @return iterator pointing to the first element inserted, or @a pos if
- `ilist` is empty
-
- @complexity Linear in `ilist.size()` plus linear in the distance between
- @a pos and end of the container.
-
- @liveexample{The example shows how `insert()` is used.,insert__ilist}
-
- @since version 1.0.0
- */
+ /// @brief inserts elements from initializer list into array
+ /// @sa https://json.nlohmann.me/api/basic_json/insert/
iterator insert(const_iterator pos, initializer_list_t ilist)
{
// insert only works for arrays
@@ -23433,29 +20276,8 @@
return insert_iterator(pos, ilist.begin(), ilist.end());
}
- /*!
- @brief inserts elements
-
- Inserts elements from range `[first, last)`.
-
- @param[in] first begin of the range of elements to insert
- @param[in] last end of the range of elements to insert
-
- @throw type_error.309 if called on JSON values other than objects; example:
- `"cannot use insert() with string"`
- @throw invalid_iterator.202 if iterator @a first or @a last does does not
- point to an object; example: `"iterators first and last must point to
- objects"`
- @throw invalid_iterator.210 if @a first and @a last do not belong to the
- same JSON value; example: `"iterators do not fit"`
-
- @complexity Logarithmic: `O(N*log(size() + N))`, where `N` is the number
- of elements to insert.
-
- @liveexample{The example shows how `insert()` is used.,insert__range_object}
-
- @since version 3.0.0
- */
+ /// @brief inserts range of elements into object
+ /// @sa https://json.nlohmann.me/api/basic_json/insert/
void insert(const_iterator first, const_iterator last)
{
// insert only works for objects
@@ -23479,80 +20301,16 @@
m_value.object->insert(first.m_it.object_iterator, last.m_it.object_iterator);
}
- /*!
- @brief updates a JSON object from another object, overwriting existing keys
-
- Inserts all values from JSON object @a j and overwrites existing keys.
-
- @param[in] j JSON object to read values from
-
- @throw type_error.312 if called on JSON values other than objects; example:
- `"cannot use update() with string"`
-
- @complexity O(N*log(size() + N)), where N is the number of elements to
- insert.
-
- @liveexample{The example shows how `update()` is used.,update}
-
- @sa https://docs.python.org/3.6/library/stdtypes.html#dict.update
-
- @since version 3.0.0
- */
- void update(const_reference j)
+ /// @brief updates a JSON object from another object, overwriting existing keys
+ /// @sa https://json.nlohmann.me/api/basic_json/update/
+ void update(const_reference j, bool merge_objects = false)
{
- // implicitly convert null value to an empty object
- if (is_null())
- {
- m_type = value_t::object;
- m_value.object = create<object_t>();
- assert_invariant();
- }
-
- if (JSON_HEDLEY_UNLIKELY(!is_object()))
- {
- JSON_THROW(type_error::create(312, "cannot use update() with " + std::string(type_name()), *this));
- }
- if (JSON_HEDLEY_UNLIKELY(!j.is_object()))
- {
- JSON_THROW(type_error::create(312, "cannot use update() with " + std::string(j.type_name()), *this));
- }
-
- for (auto it = j.cbegin(); it != j.cend(); ++it)
- {
- m_value.object->operator[](it.key()) = it.value();
-#if JSON_DIAGNOSTICS
- m_value.object->operator[](it.key()).m_parent = this;
-#endif
- }
+ update(j.begin(), j.end(), merge_objects);
}
- /*!
- @brief updates a JSON object from another object, overwriting existing keys
-
- Inserts all values from from range `[first, last)` and overwrites existing
- keys.
-
- @param[in] first begin of the range of elements to insert
- @param[in] last end of the range of elements to insert
-
- @throw type_error.312 if called on JSON values other than objects; example:
- `"cannot use update() with string"`
- @throw invalid_iterator.202 if iterator @a first or @a last does does not
- point to an object; example: `"iterators first and last must point to
- objects"`
- @throw invalid_iterator.210 if @a first and @a last do not belong to the
- same JSON value; example: `"iterators do not fit"`
-
- @complexity O(N*log(size() + N)), where N is the number of elements to
- insert.
-
- @liveexample{The example shows how `update()` is used__range.,update}
-
- @sa https://docs.python.org/3.6/library/stdtypes.html#dict.update
-
- @since version 3.0.0
- */
- void update(const_iterator first, const_iterator last)
+ /// @brief updates a JSON object from another object, overwriting existing keys
+ /// @sa https://json.nlohmann.me/api/basic_json/update/
+ void update(const_iterator first, const_iterator last, bool merge_objects = false)
{
// implicitly convert null value to an empty object
if (is_null())
@@ -23574,14 +20332,22 @@
}
// passed iterators must belong to objects
- if (JSON_HEDLEY_UNLIKELY(!first.m_object->is_object()
- || !last.m_object->is_object()))
+ if (JSON_HEDLEY_UNLIKELY(!first.m_object->is_object()))
{
- JSON_THROW(invalid_iterator::create(202, "iterators first and last must point to objects", *this));
+ JSON_THROW(type_error::create(312, "cannot use update() with " + std::string(first.m_object->type_name()), *first.m_object));
}
for (auto it = first; it != last; ++it)
{
+ if (merge_objects && it.value().is_object())
+ {
+ auto it2 = m_value.object->find(it.key());
+ if (it2 != m_value.object->end())
+ {
+ it2->second.update(it.value(), true);
+ continue;
+ }
+ }
m_value.object->operator[](it.key()) = it.value();
#if JSON_DIAGNOSTICS
m_value.object->operator[](it.key()).m_parent = this;
@@ -23589,23 +20355,8 @@
}
}
- /*!
- @brief exchanges the values
-
- Exchanges the contents of the JSON value with those of @a other. Does not
- invoke any move, copy, or swap operations on individual elements. All
- iterators and references remain valid. The past-the-end iterator is
- invalidated.
-
- @param[in,out] other JSON value to exchange the contents with
-
- @complexity Constant.
-
- @liveexample{The example below shows how JSON values can be swapped with
- `swap()`.,swap__reference}
-
- @since version 1.0.0
- */
+ /// @brief exchanges the values
+ /// @sa https://json.nlohmann.me/api/basic_json/swap/
void swap(reference other) noexcept (
std::is_nothrow_move_constructible<value_t>::value&&
std::is_nothrow_move_assignable<value_t>::value&&
@@ -23621,24 +20372,8 @@
assert_invariant();
}
- /*!
- @brief exchanges the values
-
- Exchanges the contents of the JSON value from @a left with those of @a right. Does not
- invoke any move, copy, or swap operations on individual elements. All
- iterators and references remain valid. The past-the-end iterator is
- invalidated. implemented as a friend function callable via ADL.
-
- @param[in,out] left JSON value to exchange the contents with
- @param[in,out] right JSON value to exchange the contents with
-
- @complexity Constant.
-
- @liveexample{The example below shows how JSON values can be swapped with
- `swap()`.,swap__reference}
-
- @since version 1.0.0
- */
+ /// @brief exchanges the values
+ /// @sa https://json.nlohmann.me/api/basic_json/swap/
friend void swap(reference left, reference right) noexcept (
std::is_nothrow_move_constructible<value_t>::value&&
std::is_nothrow_move_assignable<value_t>::value&&
@@ -23649,26 +20384,8 @@
left.swap(right);
}
- /*!
- @brief exchanges the values
-
- Exchanges the contents of a JSON array with those of @a other. Does not
- invoke any move, copy, or swap operations on individual elements. All
- iterators and references remain valid. The past-the-end iterator is
- invalidated.
-
- @param[in,out] other array to exchange the contents with
-
- @throw type_error.310 when JSON value is not an array; example: `"cannot
- use swap() with string"`
-
- @complexity Constant.
-
- @liveexample{The example below shows how arrays can be swapped with
- `swap()`.,swap__array_t}
-
- @since version 1.0.0
- */
+ /// @brief exchanges the values
+ /// @sa https://json.nlohmann.me/api/basic_json/swap/
void swap(array_t& other) // NOLINT(bugprone-exception-escape)
{
// swap only works for arrays
@@ -23682,26 +20399,8 @@
}
}
- /*!
- @brief exchanges the values
-
- Exchanges the contents of a JSON object with those of @a other. Does not
- invoke any move, copy, or swap operations on individual elements. All
- iterators and references remain valid. The past-the-end iterator is
- invalidated.
-
- @param[in,out] other object to exchange the contents with
-
- @throw type_error.310 when JSON value is not an object; example:
- `"cannot use swap() with string"`
-
- @complexity Constant.
-
- @liveexample{The example below shows how objects can be swapped with
- `swap()`.,swap__object_t}
-
- @since version 1.0.0
- */
+ /// @brief exchanges the values
+ /// @sa https://json.nlohmann.me/api/basic_json/swap/
void swap(object_t& other) // NOLINT(bugprone-exception-escape)
{
// swap only works for objects
@@ -23715,26 +20414,8 @@
}
}
- /*!
- @brief exchanges the values
-
- Exchanges the contents of a JSON string with those of @a other. Does not
- invoke any move, copy, or swap operations on individual elements. All
- iterators and references remain valid. The past-the-end iterator is
- invalidated.
-
- @param[in,out] other string to exchange the contents with
-
- @throw type_error.310 when JSON value is not a string; example: `"cannot
- use swap() with boolean"`
-
- @complexity Constant.
-
- @liveexample{The example below shows how strings can be swapped with
- `swap()`.,swap__string_t}
-
- @since version 1.0.0
- */
+ /// @brief exchanges the values
+ /// @sa https://json.nlohmann.me/api/basic_json/swap/
void swap(string_t& other) // NOLINT(bugprone-exception-escape)
{
// swap only works for strings
@@ -23748,26 +20429,8 @@
}
}
- /*!
- @brief exchanges the values
-
- Exchanges the contents of a JSON string with those of @a other. Does not
- invoke any move, copy, or swap operations on individual elements. All
- iterators and references remain valid. The past-the-end iterator is
- invalidated.
-
- @param[in,out] other binary to exchange the contents with
-
- @throw type_error.310 when JSON value is not a string; example: `"cannot
- use swap() with boolean"`
-
- @complexity Constant.
-
- @liveexample{The example below shows how strings can be swapped with
- `swap()`.,swap__binary_t}
-
- @since version 3.8.0
- */
+ /// @brief exchanges the values
+ /// @sa https://json.nlohmann.me/api/basic_json/swap/
void swap(binary_t& other) // NOLINT(bugprone-exception-escape)
{
// swap only works for strings
@@ -23781,7 +20444,8 @@
}
}
- /// @copydoc swap(binary_t&)
+ /// @brief exchanges the values
+ /// @sa https://json.nlohmann.me/api/basic_json/swap/
void swap(typename binary_t::container_type& other) // NOLINT(bugprone-exception-escape)
{
// swap only works for strings
@@ -23805,61 +20469,8 @@
/// @name lexicographical comparison operators
/// @{
- /*!
- @brief comparison: equal
-
- Compares two JSON values for equality according to the following rules:
- - Two JSON values are equal if (1) they are from the same type and (2)
- their stored values are the same according to their respective
- `operator==`.
- - Integer and floating-point numbers are automatically converted before
- comparison. Note that two NaN values are always treated as unequal.
- - Two JSON null values are equal.
-
- @note Floating-point inside JSON values numbers are compared with
- `json::number_float_t::operator==` which is `double::operator==` by
- default. To compare floating-point while respecting an epsilon, an alternative
- [comparison function](https://github.com/mariokonrad/marnav/blob/master/include/marnav/math/floatingpoint.hpp#L34-#L39)
- could be used, for instance
- @code {.cpp}
- template<typename T, typename = typename std::enable_if<std::is_floating_point<T>::value, T>::type>
- inline bool is_same(T a, T b, T epsilon = std::numeric_limits<T>::epsilon()) noexcept
- {
- return std::abs(a - b) <= epsilon;
- }
- @endcode
- Or you can self-defined operator equal function like this:
- @code {.cpp}
- bool my_equal(const_reference lhs, const_reference rhs) {
- const auto lhs_type lhs.type();
- const auto rhs_type rhs.type();
- if (lhs_type == rhs_type) {
- switch(lhs_type)
- // self_defined case
- case value_t::number_float:
- return std::abs(lhs - rhs) <= std::numeric_limits<float>::epsilon();
- // other cases remain the same with the original
- ...
- }
- ...
- }
- @endcode
-
- @note NaN values never compare equal to themselves or to other NaN values.
-
- @param[in] lhs first JSON value to consider
- @param[in] rhs second JSON value to consider
- @return whether the values @a lhs and @a rhs are equal
-
- @exceptionsafety No-throw guarantee: this function never throws exceptions.
-
- @complexity Linear.
-
- @liveexample{The example demonstrates comparing several JSON
- types.,operator__equal}
-
- @since version 1.0.0
- */
+ /// @brief comparison: equal
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_eq/
friend bool operator==(const_reference lhs, const_reference rhs) noexcept
{
#ifdef __GNUC__
@@ -23936,10 +20547,8 @@
#endif
}
- /*!
- @brief comparison: equal
- @copydoc operator==(const_reference, const_reference)
- */
+ /// @brief comparison: equal
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_eq/
template<typename ScalarType, typename std::enable_if<
std::is_scalar<ScalarType>::value, int>::type = 0>
friend bool operator==(const_reference lhs, ScalarType rhs) noexcept
@@ -23947,10 +20556,8 @@
return lhs == basic_json(rhs);
}
- /*!
- @brief comparison: equal
- @copydoc operator==(const_reference, const_reference)
- */
+ /// @brief comparison: equal
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_eq/
template<typename ScalarType, typename std::enable_if<
std::is_scalar<ScalarType>::value, int>::type = 0>
friend bool operator==(ScalarType lhs, const_reference rhs) noexcept
@@ -23958,33 +20565,15 @@
return basic_json(lhs) == rhs;
}
- /*!
- @brief comparison: not equal
-
- Compares two JSON values for inequality by calculating `not (lhs == rhs)`.
-
- @param[in] lhs first JSON value to consider
- @param[in] rhs second JSON value to consider
- @return whether the values @a lhs and @a rhs are not equal
-
- @complexity Linear.
-
- @exceptionsafety No-throw guarantee: this function never throws exceptions.
-
- @liveexample{The example demonstrates comparing several JSON
- types.,operator__notequal}
-
- @since version 1.0.0
- */
+ /// @brief comparison: not equal
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_ne/
friend bool operator!=(const_reference lhs, const_reference rhs) noexcept
{
return !(lhs == rhs);
}
- /*!
- @brief comparison: not equal
- @copydoc operator!=(const_reference, const_reference)
- */
+ /// @brief comparison: not equal
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_ne/
template<typename ScalarType, typename std::enable_if<
std::is_scalar<ScalarType>::value, int>::type = 0>
friend bool operator!=(const_reference lhs, ScalarType rhs) noexcept
@@ -23992,10 +20581,8 @@
return lhs != basic_json(rhs);
}
- /*!
- @brief comparison: not equal
- @copydoc operator!=(const_reference, const_reference)
- */
+ /// @brief comparison: not equal
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_ne/
template<typename ScalarType, typename std::enable_if<
std::is_scalar<ScalarType>::value, int>::type = 0>
friend bool operator!=(ScalarType lhs, const_reference rhs) noexcept
@@ -24003,32 +20590,8 @@
return basic_json(lhs) != rhs;
}
- /*!
- @brief comparison: less than
-
- Compares whether one JSON value @a lhs is less than another JSON value @a
- rhs according to the following rules:
- - If @a lhs and @a rhs have the same type, the values are compared using
- the default `<` operator.
- - Integer and floating-point numbers are automatically converted before
- comparison
- - In case @a lhs and @a rhs have different types, the values are ignored
- and the order of the types is considered, see
- @ref operator<(const value_t, const value_t).
-
- @param[in] lhs first JSON value to consider
- @param[in] rhs second JSON value to consider
- @return whether @a lhs is less than @a rhs
-
- @complexity Linear.
-
- @exceptionsafety No-throw guarantee: this function never throws exceptions.
-
- @liveexample{The example demonstrates comparing several JSON
- types.,operator__less}
-
- @since version 1.0.0
- */
+ /// @brief comparison: less than
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_lt/
friend bool operator<(const_reference lhs, const_reference rhs) noexcept
{
const auto lhs_type = lhs.type();
@@ -24103,10 +20666,8 @@
return operator<(lhs_type, rhs_type);
}
- /*!
- @brief comparison: less than
- @copydoc operator<(const_reference, const_reference)
- */
+ /// @brief comparison: less than
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_lt/
template<typename ScalarType, typename std::enable_if<
std::is_scalar<ScalarType>::value, int>::type = 0>
friend bool operator<(const_reference lhs, ScalarType rhs) noexcept
@@ -24114,10 +20675,8 @@
return lhs < basic_json(rhs);
}
- /*!
- @brief comparison: less than
- @copydoc operator<(const_reference, const_reference)
- */
+ /// @brief comparison: less than
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_lt/
template<typename ScalarType, typename std::enable_if<
std::is_scalar<ScalarType>::value, int>::type = 0>
friend bool operator<(ScalarType lhs, const_reference rhs) noexcept
@@ -24125,34 +20684,15 @@
return basic_json(lhs) < rhs;
}
- /*!
- @brief comparison: less than or equal
-
- Compares whether one JSON value @a lhs is less than or equal to another
- JSON value by calculating `not (rhs < lhs)`.
-
- @param[in] lhs first JSON value to consider
- @param[in] rhs second JSON value to consider
- @return whether @a lhs is less than or equal to @a rhs
-
- @complexity Linear.
-
- @exceptionsafety No-throw guarantee: this function never throws exceptions.
-
- @liveexample{The example demonstrates comparing several JSON
- types.,operator__greater}
-
- @since version 1.0.0
- */
+ /// @brief comparison: less than or equal
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_le/
friend bool operator<=(const_reference lhs, const_reference rhs) noexcept
{
return !(rhs < lhs);
}
- /*!
- @brief comparison: less than or equal
- @copydoc operator<=(const_reference, const_reference)
- */
+ /// @brief comparison: less than or equal
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_le/
template<typename ScalarType, typename std::enable_if<
std::is_scalar<ScalarType>::value, int>::type = 0>
friend bool operator<=(const_reference lhs, ScalarType rhs) noexcept
@@ -24160,10 +20700,8 @@
return lhs <= basic_json(rhs);
}
- /*!
- @brief comparison: less than or equal
- @copydoc operator<=(const_reference, const_reference)
- */
+ /// @brief comparison: less than or equal
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_le/
template<typename ScalarType, typename std::enable_if<
std::is_scalar<ScalarType>::value, int>::type = 0>
friend bool operator<=(ScalarType lhs, const_reference rhs) noexcept
@@ -24171,34 +20709,15 @@
return basic_json(lhs) <= rhs;
}
- /*!
- @brief comparison: greater than
-
- Compares whether one JSON value @a lhs is greater than another
- JSON value by calculating `not (lhs <= rhs)`.
-
- @param[in] lhs first JSON value to consider
- @param[in] rhs second JSON value to consider
- @return whether @a lhs is greater than to @a rhs
-
- @complexity Linear.
-
- @exceptionsafety No-throw guarantee: this function never throws exceptions.
-
- @liveexample{The example demonstrates comparing several JSON
- types.,operator__lessequal}
-
- @since version 1.0.0
- */
+ /// @brief comparison: greater than
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_gt/
friend bool operator>(const_reference lhs, const_reference rhs) noexcept
{
return !(lhs <= rhs);
}
- /*!
- @brief comparison: greater than
- @copydoc operator>(const_reference, const_reference)
- */
+ /// @brief comparison: greater than
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_gt/
template<typename ScalarType, typename std::enable_if<
std::is_scalar<ScalarType>::value, int>::type = 0>
friend bool operator>(const_reference lhs, ScalarType rhs) noexcept
@@ -24206,10 +20725,8 @@
return lhs > basic_json(rhs);
}
- /*!
- @brief comparison: greater than
- @copydoc operator>(const_reference, const_reference)
- */
+ /// @brief comparison: greater than
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_gt/
template<typename ScalarType, typename std::enable_if<
std::is_scalar<ScalarType>::value, int>::type = 0>
friend bool operator>(ScalarType lhs, const_reference rhs) noexcept
@@ -24217,34 +20734,15 @@
return basic_json(lhs) > rhs;
}
- /*!
- @brief comparison: greater than or equal
-
- Compares whether one JSON value @a lhs is greater than or equal to another
- JSON value by calculating `not (lhs < rhs)`.
-
- @param[in] lhs first JSON value to consider
- @param[in] rhs second JSON value to consider
- @return whether @a lhs is greater than or equal to @a rhs
-
- @complexity Linear.
-
- @exceptionsafety No-throw guarantee: this function never throws exceptions.
-
- @liveexample{The example demonstrates comparing several JSON
- types.,operator__greaterequal}
-
- @since version 1.0.0
- */
+ /// @brief comparison: greater than or equal
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_ge/
friend bool operator>=(const_reference lhs, const_reference rhs) noexcept
{
return !(lhs < rhs);
}
- /*!
- @brief comparison: greater than or equal
- @copydoc operator>=(const_reference, const_reference)
- */
+ /// @brief comparison: greater than or equal
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_ge/
template<typename ScalarType, typename std::enable_if<
std::is_scalar<ScalarType>::value, int>::type = 0>
friend bool operator>=(const_reference lhs, ScalarType rhs) noexcept
@@ -24252,10 +20750,8 @@
return lhs >= basic_json(rhs);
}
- /*!
- @brief comparison: greater than or equal
- @copydoc operator>=(const_reference, const_reference)
- */
+ /// @brief comparison: greater than or equal
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_ge/
template<typename ScalarType, typename std::enable_if<
std::is_scalar<ScalarType>::value, int>::type = 0>
friend bool operator>=(ScalarType lhs, const_reference rhs) noexcept
@@ -24272,37 +20768,8 @@
/// @name serialization
/// @{
#ifndef JSON_NO_IO
- /*!
- @brief serialize to stream
-
- Serialize the given JSON value @a j to the output stream @a o. The JSON
- value will be serialized using the @ref dump member function.
-
- - The indentation of the output can be controlled with the member variable
- `width` of the output stream @a o. For instance, using the manipulator
- `std::setw(4)` on @a o sets the indentation level to `4` and the
- serialization result is the same as calling `dump(4)`.
-
- - The indentation character can be controlled with the member variable
- `fill` of the output stream @a o. For instance, the manipulator
- `std::setfill('\\t')` sets indentation to use a tab character rather than
- the default space character.
-
- @param[in,out] o stream to serialize to
- @param[in] j JSON value to serialize
-
- @return the stream @a o
-
- @throw type_error.316 if a string stored inside the JSON value is not
- UTF-8 encoded
-
- @complexity Linear.
-
- @liveexample{The example below shows the serialization with different
- parameters to `width` to adjust the indentation level.,operator_serialize}
-
- @since version 1.0.0; indentation character added in version 3.0.0
- */
+ /// @brief serialize to stream
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_ltlt/
friend std::ostream& operator<<(std::ostream& o, const basic_json& j)
{
// read width member and use it as indentation parameter if nonzero
@@ -24318,14 +20785,12 @@
return o;
}
- /*!
- @brief serialize to stream
- @deprecated This stream operator is deprecated and will be removed in
- future 4.0.0 of the library. Please use
- @ref operator<<(std::ostream&, const basic_json&)
- instead; that is, replace calls like `j >> o;` with `o << j;`.
- @since version 1.0.0; deprecated since version 3.0.0
- */
+ /// @brief serialize to stream
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_ltlt/
+ /// @deprecated This function is deprecated since 3.0.0 and will be removed in
+ /// version 4.0.0 of the library. Please use
+ /// operator<<(std::ostream&, const basic_json&) instead; that is,
+ /// replace calls like `j >> o;` with `o << j;`.
JSON_HEDLEY_DEPRECATED_FOR(3.0.0, operator<<(std::ostream&, const basic_json&))
friend std::ostream& operator>>(const basic_json& j, std::ostream& o)
{
@@ -24342,57 +20807,8 @@
/// @name deserialization
/// @{
- /*!
- @brief deserialize from a compatible input
-
- @tparam InputType A compatible input, for instance
- - an std::istream object
- - a FILE pointer
- - a C-style array of characters
- - a pointer to a null-terminated string of single byte characters
- - an object obj for which begin(obj) and end(obj) produces a valid pair of
- iterators.
-
- @param[in] i input to read from
- @param[in] cb a parser callback function of type @ref parser_callback_t
- which is used to control the deserialization by filtering unwanted values
- (optional)
- @param[in] allow_exceptions whether to throw exceptions in case of a
- parse error (optional, true by default)
- @param[in] ignore_comments whether comments should be ignored and treated
- like whitespace (true) or yield a parse error (true); (optional, false by
- default)
-
- @return deserialized JSON value; in case of a parse error and
- @a allow_exceptions set to `false`, the return value will be
- value_t::discarded.
-
- @throw parse_error.101 if a parse error occurs; example: `""unexpected end
- of input; expected string literal""`
- @throw parse_error.102 if to_unicode fails or surrogate error
- @throw parse_error.103 if to_unicode fails
-
- @complexity Linear in the length of the input. The parser is a predictive
- LL(1) parser. The complexity can be higher if the parser callback function
- @a cb or reading from the input @a i has a super-linear complexity.
-
- @note A UTF-8 byte order mark is silently ignored.
-
- @liveexample{The example below demonstrates the `parse()` function reading
- from an array.,parse__array__parser_callback_t}
-
- @liveexample{The example below demonstrates the `parse()` function with
- and without callback function.,parse__string__parser_callback_t}
-
- @liveexample{The example below demonstrates the `parse()` function with
- and without callback function.,parse__istream__parser_callback_t}
-
- @liveexample{The example below demonstrates the `parse()` function reading
- from a contiguous container.,parse__contiguouscontainer__parser_callback_t}
-
- @since version 2.0.3 (contiguous containers); version 3.9.0 allowed to
- ignore comments.
- */
+ /// @brief deserialize from a compatible input
+ /// @sa https://json.nlohmann.me/api/basic_json/parse/
template<typename InputType>
JSON_HEDLEY_WARN_UNUSED_RESULT
static basic_json parse(InputType&& i,
@@ -24405,32 +20821,8 @@
return result;
}
- /*!
- @brief deserialize from a pair of character iterators
-
- The value_type of the iterator must be a integral type with size of 1, 2 or
- 4 bytes, which will be interpreted respectively as UTF-8, UTF-16 and UTF-32.
-
- @param[in] first iterator to start of character range
- @param[in] last iterator to end of character range
- @param[in] cb a parser callback function of type @ref parser_callback_t
- which is used to control the deserialization by filtering unwanted values
- (optional)
- @param[in] allow_exceptions whether to throw exceptions in case of a
- parse error (optional, true by default)
- @param[in] ignore_comments whether comments should be ignored and treated
- like whitespace (true) or yield a parse error (true); (optional, false by
- default)
-
- @return deserialized JSON value; in case of a parse error and
- @a allow_exceptions set to `false`, the return value will be
- value_t::discarded.
-
- @throw parse_error.101 if a parse error occurs; example: `""unexpected end
- of input; expected string literal""`
- @throw parse_error.102 if to_unicode fails or surrogate error
- @throw parse_error.103 if to_unicode fails
- */
+ /// @brief deserialize from a pair of character iterators
+ /// @sa https://json.nlohmann.me/api/basic_json/parse/
template<typename IteratorType>
JSON_HEDLEY_WARN_UNUSED_RESULT
static basic_json parse(IteratorType first,
@@ -24456,36 +20848,8 @@
return result;
}
- /*!
- @brief check if the input is valid JSON
-
- Unlike the @ref parse(InputType&&, const parser_callback_t,const bool)
- function, this function neither throws an exception in case of invalid JSON
- input (i.e., a parse error) nor creates diagnostic information.
-
- @tparam InputType A compatible input, for instance
- - an std::istream object
- - a FILE pointer
- - a C-style array of characters
- - a pointer to a null-terminated string of single byte characters
- - an object obj for which begin(obj) and end(obj) produces a valid pair of
- iterators.
-
- @param[in] i input to read from
- @param[in] ignore_comments whether comments should be ignored and treated
- like whitespace (true) or yield a parse error (true); (optional, false by
- default)
-
- @return Whether the input read from @a i is valid JSON.
-
- @complexity Linear in the length of the input. The parser is a predictive
- LL(1) parser.
-
- @note A UTF-8 byte order mark is silently ignored.
-
- @liveexample{The example below demonstrates the `accept()` function reading
- from a string.,accept__string}
- */
+ /// @brief check if the input is valid JSON
+ /// @sa https://json.nlohmann.me/api/basic_json/accept/
template<typename InputType>
static bool accept(InputType&& i,
const bool ignore_comments = false)
@@ -24493,6 +20857,8 @@
return parser(detail::input_adapter(std::forward<InputType>(i)), nullptr, false, ignore_comments).accept(true);
}
+ /// @brief check if the input is valid JSON
+ /// @sa https://json.nlohmann.me/api/basic_json/accept/
template<typename IteratorType>
static bool accept(IteratorType first, IteratorType last,
const bool ignore_comments = false)
@@ -24508,46 +20874,8 @@
return parser(i.get(), nullptr, false, ignore_comments).accept(true);
}
- /*!
- @brief generate SAX events
-
- The SAX event lister must follow the interface of @ref json_sax.
-
- This function reads from a compatible input. Examples are:
- - an std::istream object
- - a FILE pointer
- - a C-style array of characters
- - a pointer to a null-terminated string of single byte characters
- - an object obj for which begin(obj) and end(obj) produces a valid pair of
- iterators.
-
- @param[in] i input to read from
- @param[in,out] sax SAX event listener
- @param[in] format the format to parse (JSON, CBOR, MessagePack, or UBJSON)
- @param[in] strict whether the input has to be consumed completely
- @param[in] ignore_comments whether comments should be ignored and treated
- like whitespace (true) or yield a parse error (true); (optional, false by
- default); only applies to the JSON file format.
-
- @return return value of the last processed SAX event
-
- @throw parse_error.101 if a parse error occurs; example: `""unexpected end
- of input; expected string literal""`
- @throw parse_error.102 if to_unicode fails or surrogate error
- @throw parse_error.103 if to_unicode fails
-
- @complexity Linear in the length of the input. The parser is a predictive
- LL(1) parser. The complexity can be higher if the SAX consumer @a sax has
- a super-linear complexity.
-
- @note A UTF-8 byte order mark is silently ignored.
-
- @liveexample{The example below demonstrates the `sax_parse()` function
- reading from string and processing the events with a user-defined SAX
- event consumer.,sax_parse}
-
- @since version 3.2.0
- */
+ /// @brief generate SAX events
+ /// @sa https://json.nlohmann.me/api/basic_json/sax_parse/
template <typename InputType, typename SAX>
JSON_HEDLEY_NON_NULL(2)
static bool sax_parse(InputType&& i, SAX* sax,
@@ -24561,6 +20889,8 @@
: detail::binary_reader<basic_json, decltype(ia), SAX>(std::move(ia)).sax_parse(format, sax, strict);
}
+ /// @brief generate SAX events
+ /// @sa https://json.nlohmann.me/api/basic_json/sax_parse/
template<class IteratorType, class SAX>
JSON_HEDLEY_NON_NULL(3)
static bool sax_parse(IteratorType first, IteratorType last, SAX* sax,
@@ -24574,6 +20904,11 @@
: detail::binary_reader<basic_json, decltype(ia), SAX>(std::move(ia)).sax_parse(format, sax, strict);
}
+ /// @brief generate SAX events
+ /// @sa https://json.nlohmann.me/api/basic_json/sax_parse/
+ /// @deprecated This function is deprecated since 3.8.0 and will be removed in
+ /// version 4.0.0 of the library. Please use
+ /// sax_parse(ptr, ptr + len) instead.
template <typename SAX>
JSON_HEDLEY_DEPRECATED_FOR(3.8.0, sax_parse(ptr, ptr + len, ...))
JSON_HEDLEY_NON_NULL(2)
@@ -24590,45 +20925,20 @@
: detail::binary_reader<basic_json, decltype(ia), SAX>(std::move(ia)).sax_parse(format, sax, strict);
}
#ifndef JSON_NO_IO
- /*!
- @brief deserialize from stream
- @deprecated This stream operator is deprecated and will be removed in
- version 4.0.0 of the library. Please use
- @ref operator>>(std::istream&, basic_json&)
- instead; that is, replace calls like `j << i;` with `i >> j;`.
- @since version 1.0.0; deprecated since version 3.0.0
- */
+ /// @brief deserialize from stream
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_gtgt/
+ /// @deprecated This stream operator is deprecated since 3.0.0 and will be removed in
+ /// version 4.0.0 of the library. Please use
+ /// operator>>(std::istream&, basic_json&) instead; that is,
+ /// replace calls like `j << i;` with `i >> j;`.
JSON_HEDLEY_DEPRECATED_FOR(3.0.0, operator>>(std::istream&, basic_json&))
friend std::istream& operator<<(basic_json& j, std::istream& i)
{
return operator>>(i, j);
}
- /*!
- @brief deserialize from stream
-
- Deserializes an input stream to a JSON value.
-
- @param[in,out] i input stream to read a serialized JSON value from
- @param[in,out] j JSON value to write the deserialized input to
-
- @throw parse_error.101 in case of an unexpected token
- @throw parse_error.102 if to_unicode fails or surrogate error
- @throw parse_error.103 if to_unicode fails
-
- @complexity Linear in the length of the input. The parser is a predictive
- LL(1) parser.
-
- @note A UTF-8 byte order mark is silently ignored.
-
- @liveexample{The example below shows how a JSON value is constructed by
- reading a serialization from a stream.,operator_deserialize}
-
- @sa parse(std::istream&, const parser_callback_t) for a variant with a
- parser callback function to filter values while parsing
-
- @since version 1.0.0
- */
+ /// @brief deserialize from stream
+ /// @sa https://json.nlohmann.me/api/basic_json/operator_gtgt/
friend std::istream& operator>>(std::istream& i, basic_json& j)
{
parser(detail::input_adapter(i)).parse(false, j);
@@ -24641,63 +20951,32 @@
// convenience functions //
///////////////////////////
- /*!
- @brief return the type as string
-
- Returns the type name as string to be used in error messages - usually to
- indicate that a function was called on a wrong JSON type.
-
- @return a string representation of a the @a m_type member:
- Value type | return value
- ----------- | -------------
- null | `"null"`
- boolean | `"boolean"`
- string | `"string"`
- number | `"number"` (for all number types)
- object | `"object"`
- array | `"array"`
- binary | `"binary"`
- discarded | `"discarded"`
-
- @exceptionsafety No-throw guarantee: this function never throws exceptions.
-
- @complexity Constant.
-
- @liveexample{The following code exemplifies `type_name()` for all JSON
- types.,type_name}
-
- @sa see @ref type() -- return the type of the JSON value
- @sa see @ref operator value_t() -- return the type of the JSON value (implicit)
-
- @since version 1.0.0, public since 2.1.0, `const char*` and `noexcept`
- since 3.0.0
- */
+ /// @brief return the type as string
+ /// @sa https://json.nlohmann.me/api/basic_json/type_name/
JSON_HEDLEY_RETURNS_NON_NULL
const char* type_name() const noexcept
{
+ switch (m_type)
{
- switch (m_type)
- {
- case value_t::null:
- return "null";
- case value_t::object:
- return "object";
- case value_t::array:
- return "array";
- case value_t::string:
- return "string";
- case value_t::boolean:
- return "boolean";
- case value_t::binary:
- return "binary";
- case value_t::discarded:
- return "discarded";
- case value_t::number_integer:
- case value_t::number_unsigned:
- case value_t::number_float:
- default:
- return "number";
- }
+ case value_t::null:
+ return "null";
+ case value_t::object:
+ return "object";
+ case value_t::array:
+ return "array";
+ case value_t::string:
+ return "string";
+ case value_t::boolean:
+ return "boolean";
+ case value_t::binary:
+ return "binary";
+ case value_t::discarded:
+ return "discarded";
+ case value_t::number_integer:
+ case value_t::number_unsigned:
+ case value_t::number_float:
+ default:
+ return "number";
}
}
@@ -24726,104 +21005,8 @@
/// @{
public:
- /*!
- @brief create a CBOR serialization of a given JSON value
-
- Serializes a given JSON value @a j to a byte vector using the CBOR (Concise
- Binary Object Representation) serialization format. CBOR is a binary
- serialization format which aims to be more compact than JSON itself, yet
- more efficient to parse.
-
- The library uses the following mapping from JSON values types to
- CBOR types according to the CBOR specification (RFC 7049):
-
- JSON value type | value/range | CBOR type | first byte
- --------------- | ------------------------------------------ | ---------------------------------- | ---------------
- null | `null` | Null | 0xF6
- boolean | `true` | True | 0xF5
- boolean | `false` | False | 0xF4
- number_integer | -9223372036854775808..-2147483649 | Negative integer (8 bytes follow) | 0x3B
- number_integer | -2147483648..-32769 | Negative integer (4 bytes follow) | 0x3A
- number_integer | -32768..-129 | Negative integer (2 bytes follow) | 0x39
- number_integer | -128..-25 | Negative integer (1 byte follow) | 0x38
- number_integer | -24..-1 | Negative integer | 0x20..0x37
- number_integer | 0..23 | Integer | 0x00..0x17
- number_integer | 24..255 | Unsigned integer (1 byte follow) | 0x18
- number_integer | 256..65535 | Unsigned integer (2 bytes follow) | 0x19
- number_integer | 65536..4294967295 | Unsigned integer (4 bytes follow) | 0x1A
- number_integer | 4294967296..18446744073709551615 | Unsigned integer (8 bytes follow) | 0x1B
- number_unsigned | 0..23 | Integer | 0x00..0x17
- number_unsigned | 24..255 | Unsigned integer (1 byte follow) | 0x18
- number_unsigned | 256..65535 | Unsigned integer (2 bytes follow) | 0x19
- number_unsigned | 65536..4294967295 | Unsigned integer (4 bytes follow) | 0x1A
- number_unsigned | 4294967296..18446744073709551615 | Unsigned integer (8 bytes follow) | 0x1B
- number_float | *any value representable by a float* | Single-Precision Float | 0xFA
- number_float | *any value NOT representable by a float* | Double-Precision Float | 0xFB
- string | *length*: 0..23 | UTF-8 string | 0x60..0x77
- string | *length*: 23..255 | UTF-8 string (1 byte follow) | 0x78
- string | *length*: 256..65535 | UTF-8 string (2 bytes follow) | 0x79
- string | *length*: 65536..4294967295 | UTF-8 string (4 bytes follow) | 0x7A
- string | *length*: 4294967296..18446744073709551615 | UTF-8 string (8 bytes follow) | 0x7B
- array | *size*: 0..23 | array | 0x80..0x97
- array | *size*: 23..255 | array (1 byte follow) | 0x98
- array | *size*: 256..65535 | array (2 bytes follow) | 0x99
- array | *size*: 65536..4294967295 | array (4 bytes follow) | 0x9A
- array | *size*: 4294967296..18446744073709551615 | array (8 bytes follow) | 0x9B
- object | *size*: 0..23 | map | 0xA0..0xB7
- object | *size*: 23..255 | map (1 byte follow) | 0xB8
- object | *size*: 256..65535 | map (2 bytes follow) | 0xB9
- object | *size*: 65536..4294967295 | map (4 bytes follow) | 0xBA
- object | *size*: 4294967296..18446744073709551615 | map (8 bytes follow) | 0xBB
- binary | *size*: 0..23 | byte string | 0x40..0x57
- binary | *size*: 23..255 | byte string (1 byte follow) | 0x58
- binary | *size*: 256..65535 | byte string (2 bytes follow) | 0x59
- binary | *size*: 65536..4294967295 | byte string (4 bytes follow) | 0x5A
- binary | *size*: 4294967296..18446744073709551615 | byte string (8 bytes follow) | 0x5B
-
- Binary values with subtype are mapped to tagged values (0xD8..0xDB)
- depending on the subtype, followed by a byte string, see "binary" cells
- in the table above.
-
- @note The mapping is **complete** in the sense that any JSON value type
- can be converted to a CBOR value.
-
- @note If NaN or Infinity are stored inside a JSON number, they are
- serialized properly. This behavior differs from the @ref dump()
- function which serializes NaN or Infinity to `null`.
-
- @note The following CBOR types are not used in the conversion:
- - UTF-8 strings terminated by "break" (0x7F)
- - arrays terminated by "break" (0x9F)
- - maps terminated by "break" (0xBF)
- - byte strings terminated by "break" (0x5F)
- - date/time (0xC0..0xC1)
- - bignum (0xC2..0xC3)
- - decimal fraction (0xC4)
- - bigfloat (0xC5)
- - expected conversions (0xD5..0xD7)
- - simple values (0xE0..0xF3, 0xF8)
- - undefined (0xF7)
- - half-precision floats (0xF9)
- - break (0xFF)
-
- @param[in] j JSON value to serialize
- @return CBOR serialization as byte vector
-
- @complexity Linear in the size of the JSON value @a j.
-
- @liveexample{The example shows the serialization of a JSON value to a byte
- vector in CBOR format.,to_cbor}
-
- @sa http://cbor.io
- @sa see @ref from_cbor(InputType&&, const bool, const bool, const cbor_tag_handler_t) for the
- analogous deserialization
- @sa see @ref to_msgpack(const basic_json&) for the related MessagePack format
- @sa see @ref to_ubjson(const basic_json&, const bool, const bool) for the
- related UBJSON format
-
- @since version 2.0.9; compact representation of floating-point numbers
- since version 3.8.0
- */
+ /// @brief create a CBOR serialization of a given JSON value
+ /// @sa https://json.nlohmann.me/api/basic_json/to_cbor/
static std::vector<std::uint8_t> to_cbor(const basic_json& j)
{
std::vector<std::uint8_t> result;
@@ -24831,94 +21014,22 @@
return result;
}
+ /// @brief create a CBOR serialization of a given JSON value
+ /// @sa https://json.nlohmann.me/api/basic_json/to_cbor/
static void to_cbor(const basic_json& j, detail::output_adapter<std::uint8_t> o)
{
binary_writer<std::uint8_t>(o).write_cbor(j);
}
+ /// @brief create a CBOR serialization of a given JSON value
+ /// @sa https://json.nlohmann.me/api/basic_json/to_cbor/
static void to_cbor(const basic_json& j, detail::output_adapter<char> o)
{
binary_writer<char>(o).write_cbor(j);
}
- /*!
- @brief create a MessagePack serialization of a given JSON value
-
- Serializes a given JSON value @a j to a byte vector using the MessagePack
- serialization format. MessagePack is a binary serialization format which
- aims to be more compact than JSON itself, yet more efficient to parse.
-
- The library uses the following mapping from JSON values types to
- MessagePack types according to the MessagePack specification:
-
- JSON value type | value/range | MessagePack type | first byte
- --------------- | --------------------------------- | ---------------- | ----------
- null | `null` | nil | 0xC0
- boolean | `true` | true | 0xC3
- boolean | `false` | false | 0xC2
- number_integer | -9223372036854775808..-2147483649 | int64 | 0xD3
- number_integer | -2147483648..-32769 | int32 | 0xD2
- number_integer | -32768..-129 | int16 | 0xD1
- number_integer | -128..-33 | int8 | 0xD0
- number_integer | -32..-1 | negative fixint | 0xE0..0xFF
- number_integer | 0..127 | positive fixint | 0x00..0x7F
- number_integer | 128..255 | uint 8 | 0xCC
- number_integer | 256..65535 | uint 16 | 0xCD
- number_integer | 65536..4294967295 | uint 32 | 0xCE
- number_integer | 4294967296..18446744073709551615 | uint 64 | 0xCF
- number_unsigned | 0..127 | positive fixint | 0x00..0x7F
- number_unsigned | 128..255 | uint 8 | 0xCC
- number_unsigned | 256..65535 | uint 16 | 0xCD
- number_unsigned | 65536..4294967295 | uint 32 | 0xCE
- number_unsigned | 4294967296..18446744073709551615 | uint 64 | 0xCF
- number_float | *any value representable by a float* | float 32 | 0xCA
- number_float | *any value NOT representable by a float* | float 64 | 0xCB
- string | *length*: 0..31 | fixstr | 0xA0..0xBF
- string | *length*: 32..255 | str 8 | 0xD9
- string | *length*: 256..65535 | str 16 | 0xDA
- string | *length*: 65536..4294967295 | str 32 | 0xDB
- array | *size*: 0..15 | fixarray | 0x90..0x9F
- array | *size*: 16..65535 | array 16 | 0xDC
- array | *size*: 65536..4294967295 | array 32 | 0xDD
- object | *size*: 0..15 | fix map | 0x80..0x8F
- object | *size*: 16..65535 | map 16 | 0xDE
- object | *size*: 65536..4294967295 | map 32 | 0xDF
- binary | *size*: 0..255 | bin 8 | 0xC4
- binary | *size*: 256..65535 | bin 16 | 0xC5
- binary | *size*: 65536..4294967295 | bin 32 | 0xC6
-
- @note The mapping is **complete** in the sense that any JSON value type
- can be converted to a MessagePack value.
-
- @note The following values can **not** be converted to a MessagePack value:
- - strings with more than 4294967295 bytes
- - byte strings with more than 4294967295 bytes
- - arrays with more than 4294967295 elements
- - objects with more than 4294967295 elements
-
- @note Any MessagePack output created @ref to_msgpack can be successfully
- parsed by @ref from_msgpack.
-
- @note If NaN or Infinity are stored inside a JSON number, they are
- serialized properly. This behavior differs from the @ref dump()
- function which serializes NaN or Infinity to `null`.
-
- @param[in] j JSON value to serialize
- @return MessagePack serialization as byte vector
-
- @complexity Linear in the size of the JSON value @a j.
-
- @liveexample{The example shows the serialization of a JSON value to a byte
- vector in MessagePack format.,to_msgpack}
-
- @sa http://msgpack.org
- @sa see @ref from_msgpack for the analogous deserialization
- @sa see @ref to_cbor(const basic_json& for the related CBOR format
- @sa see @ref to_ubjson(const basic_json&, const bool, const bool) for the
- related UBJSON format
-
- @since version 2.0.9
- */
+ /// @brief create a MessagePack serialization of a given JSON value
+ /// @sa https://json.nlohmann.me/api/basic_json/to_msgpack/
static std::vector<std::uint8_t> to_msgpack(const basic_json& j)
{
std::vector<std::uint8_t> result;
@@ -24926,102 +21037,22 @@
return result;
}
+ /// @brief create a MessagePack serialization of a given JSON value
+ /// @sa https://json.nlohmann.me/api/basic_json/to_msgpack/
static void to_msgpack(const basic_json& j, detail::output_adapter<std::uint8_t> o)
{
binary_writer<std::uint8_t>(o).write_msgpack(j);
}
+ /// @brief create a MessagePack serialization of a given JSON value
+ /// @sa https://json.nlohmann.me/api/basic_json/to_msgpack/
static void to_msgpack(const basic_json& j, detail::output_adapter<char> o)
{
binary_writer<char>(o).write_msgpack(j);
}
- /*!
- @brief create a UBJSON serialization of a given JSON value
-
- Serializes a given JSON value @a j to a byte vector using the UBJSON
- (Universal Binary JSON) serialization format. UBJSON aims to be more compact
- than JSON itself, yet more efficient to parse.
-
- The library uses the following mapping from JSON values types to
- UBJSON types according to the UBJSON specification:
-
- JSON value type | value/range | UBJSON type | marker
- --------------- | --------------------------------- | ----------- | ------
- null | `null` | null | `Z`
- boolean | `true` | true | `T`
- boolean | `false` | false | `F`
- number_integer | -9223372036854775808..-2147483649 | int64 | `L`
- number_integer | -2147483648..-32769 | int32 | `l`
- number_integer | -32768..-129 | int16 | `I`
- number_integer | -128..127 | int8 | `i`
- number_integer | 128..255 | uint8 | `U`
- number_integer | 256..32767 | int16 | `I`
- number_integer | 32768..2147483647 | int32 | `l`
- number_integer | 2147483648..9223372036854775807 | int64 | `L`
- number_unsigned | 0..127 | int8 | `i`
- number_unsigned | 128..255 | uint8 | `U`
- number_unsigned | 256..32767 | int16 | `I`
- number_unsigned | 32768..2147483647 | int32 | `l`
- number_unsigned | 2147483648..9223372036854775807 | int64 | `L`
- number_unsigned | 2147483649..18446744073709551615 | high-precision | `H`
- number_float | *any value* | float64 | `D`
- string | *with shortest length indicator* | string | `S`
- array | *see notes on optimized format* | array | `[`
- object | *see notes on optimized format* | map | `{`
-
- @note The mapping is **complete** in the sense that any JSON value type
- can be converted to a UBJSON value.
-
- @note The following values can **not** be converted to a UBJSON value:
- - strings with more than 9223372036854775807 bytes (theoretical)
-
- @note The following markers are not used in the conversion:
- - `Z`: no-op values are not created.
- - `C`: single-byte strings are serialized with `S` markers.
-
- @note Any UBJSON output created @ref to_ubjson can be successfully parsed
- by @ref from_ubjson.
-
- @note If NaN or Infinity are stored inside a JSON number, they are
- serialized properly. This behavior differs from the @ref dump()
- function which serializes NaN or Infinity to `null`.
-
- @note The optimized formats for containers are supported: Parameter
- @a use_size adds size information to the beginning of a container and
- removes the closing marker. Parameter @a use_type further checks
- whether all elements of a container have the same type and adds the
- type marker to the beginning of the container. The @a use_type
- parameter must only be used together with @a use_size = true. Note
- that @a use_size = true alone may result in larger representations -
- the benefit of this parameter is that the receiving side is
- immediately informed on the number of elements of the container.
-
- @note If the JSON data contains the binary type, the value stored is a list
- of integers, as suggested by the UBJSON documentation. In particular,
- this means that serialization and the deserialization of a JSON
- containing binary values into UBJSON and back will result in a
- different JSON object.
-
- @param[in] j JSON value to serialize
- @param[in] use_size whether to add size annotations to container types
- @param[in] use_type whether to add type annotations to container types
- (must be combined with @a use_size = true)
- @return UBJSON serialization as byte vector
-
- @complexity Linear in the size of the JSON value @a j.
-
- @liveexample{The example shows the serialization of a JSON value to a byte
- vector in UBJSON format.,to_ubjson}
-
- @sa http://ubjson.org
- @sa see @ref from_ubjson(InputType&&, const bool, const bool) for the
- analogous deserialization
- @sa see @ref to_cbor(const basic_json& for the related CBOR format
- @sa see @ref to_msgpack(const basic_json&) for the related MessagePack format
-
- @since version 3.1.0
- */
+ /// @brief create a UBJSON serialization of a given JSON value
+ /// @sa https://json.nlohmann.me/api/basic_json/to_ubjson/
static std::vector<std::uint8_t> to_ubjson(const basic_json& j,
const bool use_size = false,
const bool use_type = false)
@@ -25031,75 +21062,24 @@
return result;
}
+ /// @brief create a UBJSON serialization of a given JSON value
+ /// @sa https://json.nlohmann.me/api/basic_json/to_ubjson/
static void to_ubjson(const basic_json& j, detail::output_adapter<std::uint8_t> o,
const bool use_size = false, const bool use_type = false)
{
binary_writer<std::uint8_t>(o).write_ubjson(j, use_size, use_type);
}
+ /// @brief create a UBJSON serialization of a given JSON value
+ /// @sa https://json.nlohmann.me/api/basic_json/to_ubjson/
static void to_ubjson(const basic_json& j, detail::output_adapter<char> o,
const bool use_size = false, const bool use_type = false)
{
binary_writer<char>(o).write_ubjson(j, use_size, use_type);
}
-
- /*!
- @brief Serializes the given JSON object `j` to BSON and returns a vector
- containing the corresponding BSON-representation.
-
- BSON (Binary JSON) is a binary format in which zero or more ordered key/value pairs are
- stored as a single entity (a so-called document).
-
- The library uses the following mapping from JSON values types to BSON types:
-
- JSON value type | value/range | BSON type | marker
- --------------- | --------------------------------- | ----------- | ------
- null | `null` | null | 0x0A
- boolean | `true`, `false` | boolean | 0x08
- number_integer | -9223372036854775808..-2147483649 | int64 | 0x12
- number_integer | -2147483648..2147483647 | int32 | 0x10
- number_integer | 2147483648..9223372036854775807 | int64 | 0x12
- number_unsigned | 0..2147483647 | int32 | 0x10
- number_unsigned | 2147483648..9223372036854775807 | int64 | 0x12
- number_unsigned | 9223372036854775808..18446744073709551615| -- | --
- number_float | *any value* | double | 0x01
- string | *any value* | string | 0x02
- array | *any value* | document | 0x04
- object | *any value* | document | 0x03
- binary | *any value* | binary | 0x05
-
- @warning The mapping is **incomplete**, since only JSON-objects (and things
- contained therein) can be serialized to BSON.
- Also, integers larger than 9223372036854775807 cannot be serialized to BSON,
- and the keys may not contain U+0000, since they are serialized a
- zero-terminated c-strings.
-
- @throw out_of_range.407 if `j.is_number_unsigned() && j.get<std::uint64_t>() > 9223372036854775807`
- @throw out_of_range.409 if a key in `j` contains a NULL (U+0000)
- @throw type_error.317 if `!j.is_object()`
-
- @pre The input `j` is required to be an object: `j.is_object() == true`.
-
- @note Any BSON output created via @ref to_bson can be successfully parsed
- by @ref from_bson.
-
- @param[in] j JSON value to serialize
- @return BSON serialization as byte vector
-
- @complexity Linear in the size of the JSON value @a j.
-
- @liveexample{The example shows the serialization of a JSON value to a byte
- vector in BSON format.,to_bson}
-
- @sa http://bsonspec.org/spec.html
- @sa see @ref from_bson(detail::input_adapter&&, const bool strict) for the
- analogous deserialization
- @sa see @ref to_ubjson(const basic_json&, const bool, const bool) for the
- related UBJSON format
- @sa see @ref to_cbor(const basic_json&) for the related CBOR format
- @sa see @ref to_msgpack(const basic_json&) for the related MessagePack format
- */
+ /// @brief create a BSON serialization of a given JSON value
+ /// @sa https://json.nlohmann.me/api/basic_json/to_bson/
static std::vector<std::uint8_t> to_bson(const basic_json& j)
{
std::vector<std::uint8_t> result;
@@ -25107,130 +21087,22 @@
return result;
}
- /*!
- @brief Serializes the given JSON object `j` to BSON and forwards the
- corresponding BSON-representation to the given output_adapter `o`.
- @param j The JSON object to convert to BSON.
- @param o The output adapter that receives the binary BSON representation.
- @pre The input `j` shall be an object: `j.is_object() == true`
- @sa see @ref to_bson(const basic_json&)
- */
+ /// @brief create a BSON serialization of a given JSON value
+ /// @sa https://json.nlohmann.me/api/basic_json/to_bson/
static void to_bson(const basic_json& j, detail::output_adapter<std::uint8_t> o)
{
binary_writer<std::uint8_t>(o).write_bson(j);
}
- /*!
- @copydoc to_bson(const basic_json&, detail::output_adapter<std::uint8_t>)
- */
+ /// @brief create a BSON serialization of a given JSON value
+ /// @sa https://json.nlohmann.me/api/basic_json/to_bson/
static void to_bson(const basic_json& j, detail::output_adapter<char> o)
{
binary_writer<char>(o).write_bson(j);
}
-
- /*!
- @brief create a JSON value from an input in CBOR format
-
- Deserializes a given input @a i to a JSON value using the CBOR (Concise
- Binary Object Representation) serialization format.
-
- The library maps CBOR types to JSON value types as follows:
-
- CBOR type | JSON value type | first byte
- ---------------------- | --------------- | ----------
- Integer | number_unsigned | 0x00..0x17
- Unsigned integer | number_unsigned | 0x18
- Unsigned integer | number_unsigned | 0x19
- Unsigned integer | number_unsigned | 0x1A
- Unsigned integer | number_unsigned | 0x1B
- Negative integer | number_integer | 0x20..0x37
- Negative integer | number_integer | 0x38
- Negative integer | number_integer | 0x39
- Negative integer | number_integer | 0x3A
- Negative integer | number_integer | 0x3B
- Byte string | binary | 0x40..0x57
- Byte string | binary | 0x58
- Byte string | binary | 0x59
- Byte string | binary | 0x5A
- Byte string | binary | 0x5B
- UTF-8 string | string | 0x60..0x77
- UTF-8 string | string | 0x78
- UTF-8 string | string | 0x79
- UTF-8 string | string | 0x7A
- UTF-8 string | string | 0x7B
- UTF-8 string | string | 0x7F
- array | array | 0x80..0x97
- array | array | 0x98
- array | array | 0x99
- array | array | 0x9A
- array | array | 0x9B
- array | array | 0x9F
- map | object | 0xA0..0xB7
- map | object | 0xB8
- map | object | 0xB9
- map | object | 0xBA
- map | object | 0xBB
- map | object | 0xBF
- False | `false` | 0xF4
- True | `true` | 0xF5
- Null | `null` | 0xF6
- Half-Precision Float | number_float | 0xF9
- Single-Precision Float | number_float | 0xFA
- Double-Precision Float | number_float | 0xFB
-
- @warning The mapping is **incomplete** in the sense that not all CBOR
- types can be converted to a JSON value. The following CBOR types
- are not supported and will yield parse errors (parse_error.112):
- - date/time (0xC0..0xC1)
- - bignum (0xC2..0xC3)
- - decimal fraction (0xC4)
- - bigfloat (0xC5)
- - expected conversions (0xD5..0xD7)
- - simple values (0xE0..0xF3, 0xF8)
- - undefined (0xF7)
-
- @warning CBOR allows map keys of any type, whereas JSON only allows
- strings as keys in object values. Therefore, CBOR maps with keys
- other than UTF-8 strings are rejected (parse_error.113).
-
- @note Any CBOR output created @ref to_cbor can be successfully parsed by
- @ref from_cbor.
-
- @param[in] i an input in CBOR format convertible to an input adapter
- @param[in] strict whether to expect the input to be consumed until EOF
- (true by default)
- @param[in] allow_exceptions whether to throw exceptions in case of a
- parse error (optional, true by default)
- @param[in] tag_handler how to treat CBOR tags (optional, error by default)
-
- @return deserialized JSON value; in case of a parse error and
- @a allow_exceptions set to `false`, the return value will be
- value_t::discarded.
-
- @throw parse_error.110 if the given input ends prematurely or the end of
- file was not reached when @a strict was set to true
- @throw parse_error.112 if unsupported features from CBOR were
- used in the given input @a v or if the input is not valid CBOR
- @throw parse_error.113 if a string was expected as map key, but not found
-
- @complexity Linear in the size of the input @a i.
-
- @liveexample{The example shows the deserialization of a byte vector in CBOR
- format to a JSON value.,from_cbor}
-
- @sa http://cbor.io
- @sa see @ref to_cbor(const basic_json&) for the analogous serialization
- @sa see @ref from_msgpack(InputType&&, const bool, const bool) for the
- related MessagePack format
- @sa see @ref from_ubjson(InputType&&, const bool, const bool) for the
- related UBJSON format
-
- @since version 2.0.9; parameter @a start_index since 2.1.1; changed to
- consume input adapters, removed start_index parameter, and added
- @a strict parameter since 3.0.0; added @a allow_exceptions parameter
- since 3.2.0; added @a tag_handler parameter since 3.9.0.
- */
+ /// @brief create a JSON value from an input in CBOR format
+ /// @sa https://json.nlohmann.me/api/basic_json/from_cbor/
template<typename InputType>
JSON_HEDLEY_WARN_UNUSED_RESULT
static basic_json from_cbor(InputType&& i,
@@ -25245,9 +21117,8 @@
return res ? result : basic_json(value_t::discarded);
}
- /*!
- @copydoc from_cbor(InputType&&, const bool, const bool, const cbor_tag_handler_t)
- */
+ /// @brief create a JSON value from an input in CBOR format
+ /// @sa https://json.nlohmann.me/api/basic_json/from_cbor/
template<typename IteratorType>
JSON_HEDLEY_WARN_UNUSED_RESULT
static basic_json from_cbor(IteratorType first, IteratorType last,
@@ -25289,92 +21160,8 @@
return res ? result : basic_json(value_t::discarded);
}
- /*!
- @brief create a JSON value from an input in MessagePack format
-
- Deserializes a given input @a i to a JSON value using the MessagePack
- serialization format.
-
- The library maps MessagePack types to JSON value types as follows:
-
- MessagePack type | JSON value type | first byte
- ---------------- | --------------- | ----------
- positive fixint | number_unsigned | 0x00..0x7F
- fixmap | object | 0x80..0x8F
- fixarray | array | 0x90..0x9F
- fixstr | string | 0xA0..0xBF
- nil | `null` | 0xC0
- false | `false` | 0xC2
- true | `true` | 0xC3
- float 32 | number_float | 0xCA
- float 64 | number_float | 0xCB
- uint 8 | number_unsigned | 0xCC
- uint 16 | number_unsigned | 0xCD
- uint 32 | number_unsigned | 0xCE
- uint 64 | number_unsigned | 0xCF
- int 8 | number_integer | 0xD0
- int 16 | number_integer | 0xD1
- int 32 | number_integer | 0xD2
- int 64 | number_integer | 0xD3
- str 8 | string | 0xD9
- str 16 | string | 0xDA
- str 32 | string | 0xDB
- array 16 | array | 0xDC
- array 32 | array | 0xDD
- map 16 | object | 0xDE
- map 32 | object | 0xDF
- bin 8 | binary | 0xC4
- bin 16 | binary | 0xC5
- bin 32 | binary | 0xC6
- ext 8 | binary | 0xC7
- ext 16 | binary | 0xC8
- ext 32 | binary | 0xC9
- fixext 1 | binary | 0xD4
- fixext 2 | binary | 0xD5
- fixext 4 | binary | 0xD6
- fixext 8 | binary | 0xD7
- fixext 16 | binary | 0xD8
- negative fixint | number_integer | 0xE0-0xFF
-
- @note Any MessagePack output created @ref to_msgpack can be successfully
- parsed by @ref from_msgpack.
-
- @param[in] i an input in MessagePack format convertible to an input
- adapter
- @param[in] strict whether to expect the input to be consumed until EOF
- (true by default)
- @param[in] allow_exceptions whether to throw exceptions in case of a
- parse error (optional, true by default)
-
- @return deserialized JSON value; in case of a parse error and
- @a allow_exceptions set to `false`, the return value will be
- value_t::discarded.
-
- @throw parse_error.110 if the given input ends prematurely or the end of
- file was not reached when @a strict was set to true
- @throw parse_error.112 if unsupported features from MessagePack were
- used in the given input @a i or if the input is not valid MessagePack
- @throw parse_error.113 if a string was expected as map key, but not found
-
- @complexity Linear in the size of the input @a i.
-
- @liveexample{The example shows the deserialization of a byte vector in
- MessagePack format to a JSON value.,from_msgpack}
-
- @sa http://msgpack.org
- @sa see @ref to_msgpack(const basic_json&) for the analogous serialization
- @sa see @ref from_cbor(InputType&&, const bool, const bool, const cbor_tag_handler_t) for the
- related CBOR format
- @sa see @ref from_ubjson(InputType&&, const bool, const bool) for
- the related UBJSON format
- @sa see @ref from_bson(InputType&&, const bool, const bool) for
- the related BSON format
-
- @since version 2.0.9; parameter @a start_index since 2.1.1; changed to
- consume input adapters, removed start_index parameter, and added
- @a strict parameter since 3.0.0; added @a allow_exceptions parameter
- since 3.2.0
- */
+ /// @brief create a JSON value from an input in MessagePack format
+ /// @sa https://json.nlohmann.me/api/basic_json/from_msgpack/
template<typename InputType>
JSON_HEDLEY_WARN_UNUSED_RESULT
static basic_json from_msgpack(InputType&& i,
@@ -25388,9 +21175,8 @@
return res ? result : basic_json(value_t::discarded);
}
- /*!
- @copydoc from_msgpack(InputType&&, const bool, const bool)
- */
+ /// @brief create a JSON value from an input in MessagePack format
+ /// @sa https://json.nlohmann.me/api/basic_json/from_msgpack/
template<typename IteratorType>
JSON_HEDLEY_WARN_UNUSED_RESULT
static basic_json from_msgpack(IteratorType first, IteratorType last,
@@ -25404,7 +21190,6 @@
return res ? result : basic_json(value_t::discarded);
}
-
template<typename T>
JSON_HEDLEY_WARN_UNUSED_RESULT
JSON_HEDLEY_DEPRECATED_FOR(3.8.0, from_msgpack(ptr, ptr + len))
@@ -25429,69 +21214,8 @@
return res ? result : basic_json(value_t::discarded);
}
-
- /*!
- @brief create a JSON value from an input in UBJSON format
-
- Deserializes a given input @a i to a JSON value using the UBJSON (Universal
- Binary JSON) serialization format.
-
- The library maps UBJSON types to JSON value types as follows:
-
- UBJSON type | JSON value type | marker
- ----------- | --------------------------------------- | ------
- no-op | *no value, next value is read* | `N`
- null | `null` | `Z`
- false | `false` | `F`
- true | `true` | `T`
- float32 | number_float | `d`
- float64 | number_float | `D`
- uint8 | number_unsigned | `U`
- int8 | number_integer | `i`
- int16 | number_integer | `I`
- int32 | number_integer | `l`
- int64 | number_integer | `L`
- high-precision number | number_integer, number_unsigned, or number_float - depends on number string | 'H'
- string | string | `S`
- char | string | `C`
- array | array (optimized values are supported) | `[`
- object | object (optimized values are supported) | `{`
-
- @note The mapping is **complete** in the sense that any UBJSON value can
- be converted to a JSON value.
-
- @param[in] i an input in UBJSON format convertible to an input adapter
- @param[in] strict whether to expect the input to be consumed until EOF
- (true by default)
- @param[in] allow_exceptions whether to throw exceptions in case of a
- parse error (optional, true by default)
-
- @return deserialized JSON value; in case of a parse error and
- @a allow_exceptions set to `false`, the return value will be
- value_t::discarded.
-
- @throw parse_error.110 if the given input ends prematurely or the end of
- file was not reached when @a strict was set to true
- @throw parse_error.112 if a parse error occurs
- @throw parse_error.113 if a string could not be parsed successfully
-
- @complexity Linear in the size of the input @a i.
-
- @liveexample{The example shows the deserialization of a byte vector in
- UBJSON format to a JSON value.,from_ubjson}
-
- @sa http://ubjson.org
- @sa see @ref to_ubjson(const basic_json&, const bool, const bool) for the
- analogous serialization
- @sa see @ref from_cbor(InputType&&, const bool, const bool, const cbor_tag_handler_t) for the
- related CBOR format
- @sa see @ref from_msgpack(InputType&&, const bool, const bool) for
- the related MessagePack format
- @sa see @ref from_bson(InputType&&, const bool, const bool) for
- the related BSON format
-
- @since version 3.1.0; added @a allow_exceptions parameter since 3.2.0
- */
+ /// @brief create a JSON value from an input in UBJSON format
+ /// @sa https://json.nlohmann.me/api/basic_json/from_ubjson/
template<typename InputType>
JSON_HEDLEY_WARN_UNUSED_RESULT
static basic_json from_ubjson(InputType&& i,
@@ -25505,9 +21229,8 @@
return res ? result : basic_json(value_t::discarded);
}
- /*!
- @copydoc from_ubjson(InputType&&, const bool, const bool)
- */
+ /// @brief create a JSON value from an input in UBJSON format
+ /// @sa https://json.nlohmann.me/api/basic_json/from_ubjson/
template<typename IteratorType>
JSON_HEDLEY_WARN_UNUSED_RESULT
static basic_json from_ubjson(IteratorType first, IteratorType last,
@@ -25545,67 +21268,8 @@
return res ? result : basic_json(value_t::discarded);
}
-
- /*!
- @brief Create a JSON value from an input in BSON format
-
- Deserializes a given input @a i to a JSON value using the BSON (Binary JSON)
- serialization format.
-
- The library maps BSON record types to JSON value types as follows:
-
- BSON type | BSON marker byte | JSON value type
- --------------- | ---------------- | ---------------------------
- double | 0x01 | number_float
- string | 0x02 | string
- document | 0x03 | object
- array | 0x04 | array
- binary | 0x05 | binary
- undefined | 0x06 | still unsupported
- ObjectId | 0x07 | still unsupported
- boolean | 0x08 | boolean
- UTC Date-Time | 0x09 | still unsupported
- null | 0x0A | null
- Regular Expr. | 0x0B | still unsupported
- DB Pointer | 0x0C | still unsupported
- JavaScript Code | 0x0D | still unsupported
- Symbol | 0x0E | still unsupported
- JavaScript Code | 0x0F | still unsupported
- int32 | 0x10 | number_integer
- Timestamp | 0x11 | still unsupported
- 128-bit decimal float | 0x13 | still unsupported
- Max Key | 0x7F | still unsupported
- Min Key | 0xFF | still unsupported
-
- @warning The mapping is **incomplete**. The unsupported mappings
- are indicated in the table above.
-
- @param[in] i an input in BSON format convertible to an input adapter
- @param[in] strict whether to expect the input to be consumed until EOF
- (true by default)
- @param[in] allow_exceptions whether to throw exceptions in case of a
- parse error (optional, true by default)
-
- @return deserialized JSON value; in case of a parse error and
- @a allow_exceptions set to `false`, the return value will be
- value_t::discarded.
-
- @throw parse_error.114 if an unsupported BSON record type is encountered
-
- @complexity Linear in the size of the input @a i.
-
- @liveexample{The example shows the deserialization of a byte vector in
- BSON format to a JSON value.,from_bson}
-
- @sa http://bsonspec.org/spec.html
- @sa see @ref to_bson(const basic_json&) for the analogous serialization
- @sa see @ref from_cbor(InputType&&, const bool, const bool, const cbor_tag_handler_t) for the
- related CBOR format
- @sa see @ref from_msgpack(InputType&&, const bool, const bool) for
- the related MessagePack format
- @sa see @ref from_ubjson(InputType&&, const bool, const bool) for the
- related UBJSON format
- */
+ /// @brief create a JSON value from an input in BSON format
+ /// @sa https://json.nlohmann.me/api/basic_json/from_bson/
template<typename InputType>
JSON_HEDLEY_WARN_UNUSED_RESULT
static basic_json from_bson(InputType&& i,
@@ -25619,9 +21283,8 @@
return res ? result : basic_json(value_t::discarded);
}
- /*!
- @copydoc from_bson(InputType&&, const bool, const bool)
- */
+ /// @brief create a JSON value from an input in BSON format
+ /// @sa https://json.nlohmann.me/api/basic_json/from_bson/
template<typename IteratorType>
JSON_HEDLEY_WARN_UNUSED_RESULT
static basic_json from_bson(IteratorType first, IteratorType last,
@@ -25667,180 +21330,36 @@
/// @name JSON Pointer functions
/// @{
- /*!
- @brief access specified element via JSON Pointer
-
- Uses a JSON pointer to retrieve a reference to the respective JSON value.
- No bound checking is performed. Similar to @ref operator[](const typename
- object_t::key_type&), `null` values are created in arrays and objects if
- necessary.
-
- In particular:
- - If the JSON pointer points to an object key that does not exist, it
- is created an filled with a `null` value before a reference to it
- is returned.
- - If the JSON pointer points to an array index that does not exist, it
- is created an filled with a `null` value before a reference to it
- is returned. All indices between the current maximum and the given
- index are also filled with `null`.
- - The special value `-` is treated as a synonym for the index past the
- end.
-
- @param[in] ptr a JSON pointer
-
- @return reference to the element pointed to by @a ptr
-
- @complexity Constant.
-
- @throw parse_error.106 if an array index begins with '0'
- @throw parse_error.109 if an array index was not a number
- @throw out_of_range.404 if the JSON pointer can not be resolved
-
- @liveexample{The behavior is shown in the example.,operatorjson_pointer}
-
- @since version 2.0.0
- */
+ /// @brief access specified element via JSON Pointer
+ /// @sa https://json.nlohmann.me/api/basic_json/operator%5B%5D/
reference operator[](const json_pointer& ptr)
{
return ptr.get_unchecked(this);
}
- /*!
- @brief access specified element via JSON Pointer
-
- Uses a JSON pointer to retrieve a reference to the respective JSON value.
- No bound checking is performed. The function does not change the JSON
- value; no `null` values are created. In particular, the special value
- `-` yields an exception.
-
- @param[in] ptr JSON pointer to the desired element
-
- @return const reference to the element pointed to by @a ptr
-
- @complexity Constant.
-
- @throw parse_error.106 if an array index begins with '0'
- @throw parse_error.109 if an array index was not a number
- @throw out_of_range.402 if the array index '-' is used
- @throw out_of_range.404 if the JSON pointer can not be resolved
-
- @liveexample{The behavior is shown in the example.,operatorjson_pointer_const}
-
- @since version 2.0.0
- */
+ /// @brief access specified element via JSON Pointer
+ /// @sa https://json.nlohmann.me/api/basic_json/operator%5B%5D/
const_reference operator[](const json_pointer& ptr) const
{
return ptr.get_unchecked(this);
}
- /*!
- @brief access specified element via JSON Pointer
-
- Returns a reference to the element at with specified JSON pointer @a ptr,
- with bounds checking.
-
- @param[in] ptr JSON pointer to the desired element
-
- @return reference to the element pointed to by @a ptr
-
- @throw parse_error.106 if an array index in the passed JSON pointer @a ptr
- begins with '0'. See example below.
-
- @throw parse_error.109 if an array index in the passed JSON pointer @a ptr
- is not a number. See example below.
-
- @throw out_of_range.401 if an array index in the passed JSON pointer @a ptr
- is out of range. See example below.
-
- @throw out_of_range.402 if the array index '-' is used in the passed JSON
- pointer @a ptr. As `at` provides checked access (and no elements are
- implicitly inserted), the index '-' is always invalid. See example below.
-
- @throw out_of_range.403 if the JSON pointer describes a key of an object
- which cannot be found. See example below.
-
- @throw out_of_range.404 if the JSON pointer @a ptr can not be resolved.
- See example below.
-
- @exceptionsafety Strong guarantee: if an exception is thrown, there are no
- changes in the JSON value.
-
- @complexity Constant.
-
- @since version 2.0.0
-
- @liveexample{The behavior is shown in the example.,at_json_pointer}
- */
+ /// @brief access specified element via JSON Pointer
+ /// @sa https://json.nlohmann.me/api/basic_json/at/
reference at(const json_pointer& ptr)
{
return ptr.get_checked(this);
}
- /*!
- @brief access specified element via JSON Pointer
-
- Returns a const reference to the element at with specified JSON pointer @a
- ptr, with bounds checking.
-
- @param[in] ptr JSON pointer to the desired element
-
- @return reference to the element pointed to by @a ptr
-
- @throw parse_error.106 if an array index in the passed JSON pointer @a ptr
- begins with '0'. See example below.
-
- @throw parse_error.109 if an array index in the passed JSON pointer @a ptr
- is not a number. See example below.
-
- @throw out_of_range.401 if an array index in the passed JSON pointer @a ptr
- is out of range. See example below.
-
- @throw out_of_range.402 if the array index '-' is used in the passed JSON
- pointer @a ptr. As `at` provides checked access (and no elements are
- implicitly inserted), the index '-' is always invalid. See example below.
-
- @throw out_of_range.403 if the JSON pointer describes a key of an object
- which cannot be found. See example below.
-
- @throw out_of_range.404 if the JSON pointer @a ptr can not be resolved.
- See example below.
-
- @exceptionsafety Strong guarantee: if an exception is thrown, there are no
- changes in the JSON value.
-
- @complexity Constant.
-
- @since version 2.0.0
-
- @liveexample{The behavior is shown in the example.,at_json_pointer_const}
- */
+ /// @brief access specified element via JSON Pointer
+ /// @sa https://json.nlohmann.me/api/basic_json/at/
const_reference at(const json_pointer& ptr) const
{
return ptr.get_checked(this);
}
- /*!
- @brief return flattened JSON value
-
- The function creates a JSON object whose keys are JSON pointers (see [RFC
- 6901](https://tools.ietf.org/html/rfc6901)) and whose values are all
- primitive. The original JSON value can be restored using the @ref
- unflatten() function.
-
- @return an object that maps JSON pointers to primitive values
-
- @note Empty objects and arrays are flattened to `null` and will not be
- reconstructed correctly by the @ref unflatten() function.
-
- @complexity Linear in the size the JSON value.
-
- @liveexample{The following code shows how a JSON object is flattened to an
- object whose keys consist of JSON pointers.,flatten}
-
- @sa see @ref unflatten() for the reverse function
-
- @since version 2.0.0
- */
+ /// @brief return flattened JSON value
+ /// @sa https://json.nlohmann.me/api/basic_json/flatten/
basic_json flatten() const
{
basic_json result(value_t::object);
@@ -25848,36 +21367,8 @@
return result;
}
- /*!
- @brief unflatten a previously flattened JSON value
-
- The function restores the arbitrary nesting of a JSON value that has been
- flattened before using the @ref flatten() function. The JSON value must
- meet certain constraints:
- 1. The value must be an object.
- 2. The keys must be JSON pointers (see
- [RFC 6901](https://tools.ietf.org/html/rfc6901))
- 3. The mapped values must be primitive JSON types.
-
- @return the original JSON from a flattened version
-
- @note Empty objects and arrays are flattened by @ref flatten() to `null`
- values and can not unflattened to their original type. Apart from
- this example, for a JSON value `j`, the following is always true:
- `j == j.flatten().unflatten()`.
-
- @complexity Linear in the size the JSON value.
-
- @throw type_error.314 if value is not an object
- @throw type_error.315 if object values are not primitive
-
- @liveexample{The following code shows how a flattened JSON object is
- unflattened into the original nested JSON object.,unflatten}
-
- @sa see @ref flatten() for the reverse function
-
- @since version 2.0.0
- */
+ /// @brief unflatten a previously flattened JSON value
+ /// @sa https://json.nlohmann.me/api/basic_json/unflatten/
basic_json unflatten() const
{
return json_pointer::unflatten(*this);
@@ -25892,53 +21383,8 @@
/// @name JSON Patch functions
/// @{
- /*!
- @brief applies a JSON patch
-
- [JSON Patch](http://jsonpatch.com) defines a JSON document structure for
- expressing a sequence of operations to apply to a JSON) document. With
- this function, a JSON Patch is applied to the current JSON value by
- executing all operations from the patch.
-
- @param[in] json_patch JSON patch document
- @return patched document
-
- @note The application of a patch is atomic: Either all operations succeed
- and the patched document is returned or an exception is thrown. In
- any case, the original value is not changed: the patch is applied
- to a copy of the value.
-
- @throw parse_error.104 if the JSON patch does not consist of an array of
- objects
-
- @throw parse_error.105 if the JSON patch is malformed (e.g., mandatory
- attributes are missing); example: `"operation add must have member path"`
-
- @throw out_of_range.401 if an array index is out of range.
-
- @throw out_of_range.403 if a JSON pointer inside the patch could not be
- resolved successfully in the current JSON value; example: `"key baz not
- found"`
-
- @throw out_of_range.405 if JSON pointer has no parent ("add", "remove",
- "move")
-
- @throw other_error.501 if "test" operation was unsuccessful
-
- @complexity Linear in the size of the JSON value and the length of the
- JSON patch. As usually only a fraction of the JSON value is affected by
- the patch, the complexity can usually be neglected.
-
- @liveexample{The following code shows how a JSON patch is applied to a
- value.,patch}
-
- @sa see @ref diff -- create a JSON patch by comparing two JSON values
-
- @sa [RFC 6902 (JSON Patch)](https://tools.ietf.org/html/rfc6902)
- @sa [RFC 6901 (JSON Pointer)](https://tools.ietf.org/html/rfc6901)
-
- @since version 2.0.0
- */
+ /// @brief applies a JSON patch
+ /// @sa https://json.nlohmann.me/api/basic_json/patch/
basic_json patch(const basic_json& json_patch) const
{
// make a working copy to apply the patch to
@@ -26211,39 +21657,8 @@
return result;
}
- /*!
- @brief creates a diff as a JSON patch
-
- Creates a [JSON Patch](http://jsonpatch.com) so that value @a source can
- be changed into the value @a target by calling @ref patch function.
-
- @invariant For two JSON values @a source and @a target, the following code
- yields always `true`:
- @code {.cpp}
- source.patch(diff(source, target)) == target;
- @endcode
-
- @note Currently, only `remove`, `add`, and `replace` operations are
- generated.
-
- @param[in] source JSON value to compare from
- @param[in] target JSON value to compare against
- @param[in] path helper value to create JSON pointers
-
- @return a JSON patch to convert the @a source to @a target
-
- @complexity Linear in the lengths of @a source and @a target.
-
- @liveexample{The following code shows how a JSON patch is created as a
- diff for two JSON values.,diff}
-
- @sa see @ref patch -- apply a JSON patch
- @sa see @ref merge_patch -- apply a JSON Merge Patch
-
- @sa [RFC 6902 (JSON Patch)](https://tools.ietf.org/html/rfc6902)
-
- @since version 2.0.0
- */
+ /// @brief creates a diff as a JSON patch
+ /// @sa https://json.nlohmann.me/api/basic_json/diff/
JSON_HEDLEY_WARN_UNUSED_RESULT
static basic_json diff(const basic_json& source, const basic_json& target,
const std::string& path = "")
@@ -26281,7 +21696,7 @@
++i;
}
- // i now reached the end of at least one array
+ // We now reached the end of at least one array
// in a second pass, traverse the remaining elements
// remove my remaining elements
@@ -26386,48 +21801,8 @@
/// @name JSON Merge Patch functions
/// @{
- /*!
- @brief applies a JSON Merge Patch
-
- The merge patch format is primarily intended for use with the HTTP PATCH
- method as a means of describing a set of modifications to a target
- resource's content. This function applies a merge patch to the current
- JSON value.
-
- The function implements the following algorithm from Section 2 of
- [RFC 7396 (JSON Merge Patch)](https://tools.ietf.org/html/rfc7396):
-
- ```
- define MergePatch(Target, Patch):
- if Patch is an Object:
- if Target is not an Object:
- Target = {} // Ignore the contents and set it to an empty Object
- for each Name/Value pair in Patch:
- if Value is null:
- if Name exists in Target:
- remove the Name/Value pair from Target
- else:
- Target[Name] = MergePatch(Target[Name], Value)
- return Target
- else:
- return Patch
- ```
-
- Thereby, `Target` is the current object; that is, the patch is applied to
- the current value.
-
- @param[in] apply_patch the patch to apply
-
- @complexity Linear in the lengths of @a patch.
-
- @liveexample{The following code shows how a JSON Merge Patch is applied to
- a JSON document.,merge_patch}
-
- @sa see @ref patch -- apply a JSON patch
- @sa [RFC 7396 (JSON Merge Patch)](https://tools.ietf.org/html/rfc7396)
-
- @since version 3.0.0
- */
+ /// @brief applies a JSON Merge Patch
+ /// @sa https://json.nlohmann.me/api/basic_json/merge_patch/
void merge_patch(const basic_json& apply_patch)
{
if (apply_patch.is_object())
@@ -26457,50 +21832,37 @@
/// @}
};
-/*!
-@brief user-defined to_string function for JSON values
-
-This function implements a user-defined to_string for JSON objects.
-
-@param[in] j a JSON object
-@return a std::string object
-*/
-
+/// @brief user-defined to_string function for JSON values
+/// @sa https://json.nlohmann.me/api/basic_json/to_string/
NLOHMANN_BASIC_JSON_TPL_DECLARATION
std::string to_string(const NLOHMANN_BASIC_JSON_TPL& j)
{
return j.dump();
}
+
} // namespace nlohmann
///////////////////////
// nonmember support //
///////////////////////
-// specialization of std::swap, and std::hash
-namespace std
+namespace std // NOLINT(cert-dcl58-cpp)
{
-/// hash value for JSON objects
-template<>
-struct hash<nlohmann::json>
+/// @brief hash value for JSON objects
+/// @sa https://json.nlohmann.me/api/basic_json/std_hash/
+NLOHMANN_BASIC_JSON_TPL_DECLARATION
+struct hash<nlohmann::NLOHMANN_BASIC_JSON_TPL>
{
- /*!
- @brief return a hash value for a JSON object
-
- @since version 1.0.0
- */
- std::size_t operator()(const nlohmann::json& j) const
+ std::size_t operator()(const nlohmann::NLOHMANN_BASIC_JSON_TPL& j) const
{
return nlohmann::detail::hash(j);
}
};
-/// specialization for std::less<value_t>
-/// @note: do not remove the space after '<',
-/// see https://github.com/nlohmann/json/pull/679
+// specialization for std::less<value_t>
template<>
-struct less<::nlohmann::detail::value_t>
+struct less< ::nlohmann::detail::value_t> // do not remove the space after '<', see https://github.com/nlohmann/json/pull/679
{
/*!
@brief compare two value_t enum values
@@ -26516,16 +21878,12 @@
// C++20 prohibit function specialization in the std namespace.
#ifndef JSON_HAS_CPP_20
-/*!
-@brief exchanges the values of two JSON objects
-
-@since version 1.0.0
-*/
-template<>
-inline void swap<nlohmann::json>(nlohmann::json& j1, nlohmann::json& j2) noexcept( // NOLINT(readability-inconsistent-declaration-parameter-name)
- is_nothrow_move_constructible<nlohmann::json>::value&& // NOLINT(misc-redundant-expression)
- is_nothrow_move_assignable<nlohmann::json>::value
- )
+/// @brief exchanges the values of two JSON objects
+/// @sa https://json.nlohmann.me/api/basic_json/std_swap/
+NLOHMANN_BASIC_JSON_TPL_DECLARATION
+inline void swap(nlohmann::NLOHMANN_BASIC_JSON_TPL& j1, nlohmann::NLOHMANN_BASIC_JSON_TPL& j2) noexcept( // NOLINT(readability-inconsistent-declaration-parameter-name)
+ is_nothrow_move_constructible<nlohmann::NLOHMANN_BASIC_JSON_TPL>::value&& // NOLINT(misc-redundant-expression)
+ is_nothrow_move_assignable<nlohmann::NLOHMANN_BASIC_JSON_TPL>::value)
{
j1.swap(j2);
}
@@ -26534,38 +21892,16 @@
} // namespace std
-/*!
-@brief user-defined string literal for JSON values
-
-This operator implements a user-defined string literal for JSON objects. It
-can be used by adding `"_json"` to a string literal and returns a JSON object
-if no parse error occurred.
-
-@param[in] s a string representation of a JSON object
-@param[in] n the length of string @a s
-@return a JSON object
-
-@since version 1.0.0
-*/
+/// @brief user-defined string literal for JSON values
+/// @sa https://json.nlohmann.me/api/basic_json/operator_literal_json/
JSON_HEDLEY_NON_NULL(1)
inline nlohmann::json operator "" _json(const char* s, std::size_t n)
{
return nlohmann::json::parse(s, s + n);
}
-/*!
-@brief user-defined string literal for JSON pointer
-
-This operator implements a user-defined string literal for JSON Pointers. It
-can be used by adding `"_json_pointer"` to a string literal and returns a JSON pointer
-object if no parse error occurred.
-
-@param[in] s a string representation of a JSON Pointer
-@param[in] n the length of string @a s
-@return a JSON pointer object
-
-@since version 2.0.0
-*/
+/// @brief user-defined string literal for JSON pointer
+/// @sa https://json.nlohmann.me/api/basic_json/operator_literal_json_pointer/
JSON_HEDLEY_NON_NULL(1)
inline nlohmann::json::json_pointer operator "" _json_pointer(const char* s, std::size_t n)
{
@@ -26591,6 +21927,8 @@
#undef JSON_HAS_CPP_14
#undef JSON_HAS_CPP_17
#undef JSON_HAS_CPP_20
+#undef JSON_HAS_FILESYSTEM
+#undef JSON_HAS_EXPERIMENTAL_FILESYSTEM
#undef NLOHMANN_BASIC_JSON_TPL_DECLARATION
#undef NLOHMANN_BASIC_JSON_TPL
#undef JSON_EXPLICIT
diff --git a/test/CMakeLists.txt b/test/CMakeLists.txt
index 447192c..4c741f2 100644
--- a/test/CMakeLists.txt
+++ b/test/CMakeLists.txt
@@ -52,6 +52,21 @@
# one executable for each unit test file
#############################################################################
+# check if compiler supports C++17
+foreach(feature ${CMAKE_CXX_COMPILE_FEATURES})
+ if (${feature} STREQUAL cxx_std_17)
+ set(compiler_supports_cpp_17 TRUE)
+ endif()
+endforeach()
+# Clang only supports C++17 starting from Clang 5.0
+if ("${CMAKE_CXX_COMPILER_ID}" MATCHES "Clang" AND CMAKE_CXX_COMPILER_VERSION VERSION_LESS 5.0)
+ unset(compiler_supports_cpp_17)
+endif()
+# MSVC 2015 (14.0) does not support C++17
+if ("${CMAKE_CXX_COMPILER_ID}" MATCHES "MSVC" AND CMAKE_CXX_COMPILER_VERSION VERSION_LESS 19.1)
+ unset(compiler_supports_cpp_17)
+endif()
+
file(GLOB files src/unit-*.cpp)
foreach(file ${files})
@@ -68,6 +83,42 @@
target_include_directories(${testcase} PRIVATE ${CMAKE_BINARY_DIR}/include thirdparty/doctest thirdparty/fifo_map)
target_link_libraries(${testcase} PRIVATE ${NLOHMANN_JSON_TARGET_NAME})
+ # add a copy with C++17 compilation
+ if (compiler_supports_cpp_17)
+ file(READ ${file} FILE_CONTENT)
+ string(FIND "${FILE_CONTENT}" "JSON_HAS_CPP_17" CPP_17_FOUND)
+ if(NOT ${CPP_17_FOUND} EQUAL -1)
+ add_executable(${testcase}_cpp17 $<TARGET_OBJECTS:doctest_main> ${file})
+ target_compile_definitions(${testcase}_cpp17 PRIVATE DOCTEST_CONFIG_SUPER_FAST_ASSERTS)
+ target_compile_options(${testcase}_cpp17 PRIVATE
+ $<$<CXX_COMPILER_ID:MSVC>:/EHsc;$<$<CONFIG:Release>:/Od>>
+ $<$<NOT:$<CXX_COMPILER_ID:MSVC>>:-Wno-deprecated;-Wno-float-equal>
+ $<$<CXX_COMPILER_ID:GNU>:-Wno-deprecated-declarations>
+ )
+ target_include_directories(${testcase}_cpp17 PRIVATE ${CMAKE_BINARY_DIR}/include thirdparty/doctest thirdparty/fifo_map)
+ target_link_libraries(${testcase}_cpp17 PRIVATE ${NLOHMANN_JSON_TARGET_NAME})
+ target_compile_features(${testcase}_cpp17 PRIVATE cxx_std_17)
+
+ if (CMAKE_CXX_COMPILER_ID STREQUAL "GNU" AND CMAKE_CXX_COMPILER_VERSION VERSION_GREATER_EQUAL 8.0 AND CMAKE_CXX_COMPILER_VERSION VERSION_LESS 9.0 AND NOT MINGW)
+ # fix for https://gcc.gnu.org/bugzilla/show_bug.cgi?id=90050
+ target_link_libraries(${testcase}_cpp17 PRIVATE stdc++fs)
+ endif()
+
+ if (JSON_FastTests)
+ add_test(NAME "${testcase}_cpp17"
+ COMMAND ${testcase}_cpp17 ${DOCTEST_TEST_FILTER}
+ WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
+ )
+ else()
+ add_test(NAME "${testcase}_cpp17"
+ COMMAND ${testcase}_cpp17 ${DOCTEST_TEST_FILTER} --no-skip
+ WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
+ )
+ endif()
+ set_tests_properties("${testcase}_cpp17" PROPERTIES LABELS "all" FIXTURES_REQUIRED TEST_DATA)
+ endif()
+ endif()
+
if (JSON_FastTests)
add_test(NAME "${testcase}"
COMMAND ${testcase} ${DOCTEST_TEST_FILTER}
diff --git a/test/cuda_example/CMakeLists.txt b/test/cuda_example/CMakeLists.txt
new file mode 100644
index 0000000..26b57f2
--- /dev/null
+++ b/test/cuda_example/CMakeLists.txt
@@ -0,0 +1,10 @@
+cmake_minimum_required(VERSION 3.18)
+project(json_cuda LANGUAGES CUDA)
+
+add_executable(json_cuda json_cuda.cu)
+target_include_directories(json_cuda PRIVATE ../../include)
+target_compile_features(json_cuda PUBLIC cuda_std_11)
+set_target_properties(json_cuda PROPERTIES
+ CUDA_EXTENSIONS OFF
+ CUDA_STANDARD_REQUIRED ON
+)
diff --git a/test/cuda_example/json_cuda.cu b/test/cuda_example/json_cuda.cu
new file mode 100644
index 0000000..d686cd0
--- /dev/null
+++ b/test/cuda_example/json_cuda.cu
@@ -0,0 +1,11 @@
+#include <nlohmann/json.hpp>
+
+int main()
+{
+ nlohmann::ordered_json json = {"Test"};
+ json.dump();
+
+ // regression for #3013 (ordered_json::reset() compile error with nvcc)
+ nlohmann::ordered_json metadata;
+ metadata.erase("key");
+}
diff --git a/test/src/fuzzer-driver_afl.cpp b/test/src/fuzzer-driver_afl.cpp
index 410362c..840f589 100644
--- a/test/src/fuzzer-driver_afl.cpp
+++ b/test/src/fuzzer-driver_afl.cpp
@@ -1,7 +1,7 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (fuzz test support)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
This file implements a driver for American Fuzzy Lop (afl-fuzz). It relies on
diff --git a/test/src/fuzzer-parse_bson.cpp b/test/src/fuzzer-parse_bson.cpp
index 3d68149..79287ce 100644
--- a/test/src/fuzzer-parse_bson.cpp
+++ b/test/src/fuzzer-parse_bson.cpp
@@ -1,7 +1,7 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (fuzz test support)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
This file implements a parser test suitable for fuzz testing. Given a byte
diff --git a/test/src/fuzzer-parse_cbor.cpp b/test/src/fuzzer-parse_cbor.cpp
index 0dd7945..88e7b43 100644
--- a/test/src/fuzzer-parse_cbor.cpp
+++ b/test/src/fuzzer-parse_cbor.cpp
@@ -1,7 +1,7 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (fuzz test support)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
This file implements a parser test suitable for fuzz testing. Given a byte
diff --git a/test/src/fuzzer-parse_json.cpp b/test/src/fuzzer-parse_json.cpp
index c58fcfe..9f63628 100644
--- a/test/src/fuzzer-parse_json.cpp
+++ b/test/src/fuzzer-parse_json.cpp
@@ -1,7 +1,7 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (fuzz test support)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
This file implements a parser test suitable for fuzz testing. Given a byte
diff --git a/test/src/fuzzer-parse_msgpack.cpp b/test/src/fuzzer-parse_msgpack.cpp
index a225614..b58498c 100644
--- a/test/src/fuzzer-parse_msgpack.cpp
+++ b/test/src/fuzzer-parse_msgpack.cpp
@@ -1,7 +1,7 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (fuzz test support)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
This file implements a parser test suitable for fuzz testing. Given a byte
diff --git a/test/src/fuzzer-parse_ubjson.cpp b/test/src/fuzzer-parse_ubjson.cpp
index ff04ad6..7774b4b 100644
--- a/test/src/fuzzer-parse_ubjson.cpp
+++ b/test/src/fuzzer-parse_ubjson.cpp
@@ -1,7 +1,7 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (fuzz test support)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
This file implements a parser test suitable for fuzz testing. Given a byte
diff --git a/test/src/unit-algorithms.cpp b/test/src/unit-algorithms.cpp
index 2034825..36f02e1 100644
--- a/test/src/unit-algorithms.cpp
+++ b/test/src/unit-algorithms.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit-allocator.cpp b/test/src/unit-allocator.cpp
index e430c10..2671212 100644
--- a/test/src/unit-allocator.cpp
+++ b/test/src/unit-allocator.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit-alt-string.cpp b/test/src/unit-alt-string.cpp
index 4ba6002..2c599a4 100644
--- a/test/src/unit-alt-string.cpp
+++ b/test/src/unit-alt-string.cpp
@@ -1,7 +1,7 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
diff --git a/test/src/unit-assert_macro.cpp b/test/src/unit-assert_macro.cpp
index 9d466b7..02dd54b 100644
--- a/test/src/unit-assert_macro.cpp
+++ b/test/src/unit-assert_macro.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit-bson.cpp b/test/src/unit-bson.cpp
index 2b7cdcf..64c3607 100644
--- a/test/src/unit-bson.cpp
+++ b/test/src/unit-bson.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit-byte_container_with_subtype.cpp b/test/src/unit-byte_container_with_subtype.cpp
index 51ce9c0..3f39749 100644
--- a/test/src/unit-byte_container_with_subtype.cpp
+++ b/test/src/unit-byte_container_with_subtype.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
@@ -41,11 +41,11 @@
nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>> container;
CHECK(!container.has_subtype());
- CHECK(container.subtype() == subtype_type(-1));
+ CHECK(container.subtype() == static_cast<subtype_type>(-1));
container.clear_subtype();
CHECK(!container.has_subtype());
- CHECK(container.subtype() == subtype_type(-1));
+ CHECK(container.subtype() == static_cast<subtype_type>(-1));
container.set_subtype(42);
CHECK(container.has_subtype());
@@ -60,7 +60,7 @@
container.clear_subtype();
CHECK(!container.has_subtype());
- CHECK(container.subtype() == subtype_type(-1));
+ CHECK(container.subtype() == static_cast<subtype_type>(-1));
}
SECTION("comparisons")
diff --git a/test/src/unit-capacity.cpp b/test/src/unit-capacity.cpp
index 99d8d40..c8362d4 100644
--- a/test/src/unit-capacity.cpp
+++ b/test/src/unit-capacity.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit-cbor.cpp b/test/src/unit-cbor.cpp
index d67745e..59ff2af 100644
--- a/test/src/unit-cbor.cpp
+++ b/test/src/unit-cbor.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
@@ -610,7 +610,7 @@
SECTION("-32768..-129 (int 16)")
{
- for (int16_t i = -32768; i <= int16_t(-129); ++i)
+ for (int16_t i = -32768; i <= static_cast<std::int16_t>(-129); ++i)
{
CAPTURE(i)
diff --git a/test/src/unit-class_const_iterator.cpp b/test/src/unit-class_const_iterator.cpp
index 1a0e026..33ec857 100644
--- a/test/src/unit-class_const_iterator.cpp
+++ b/test/src/unit-class_const_iterator.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit-class_iterator.cpp b/test/src/unit-class_iterator.cpp
index c32dad4..0e159fc 100644
--- a/test/src/unit-class_iterator.cpp
+++ b/test/src/unit-class_iterator.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit-class_lexer.cpp b/test/src/unit-class_lexer.cpp
index 8adbada..42050b2 100644
--- a/test/src/unit-class_lexer.cpp
+++ b/test/src/unit-class_lexer.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit-class_parser.cpp b/test/src/unit-class_parser.cpp
index 2248504..78fc7dd 100644
--- a/test/src/unit-class_parser.cpp
+++ b/test/src/unit-class_parser.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
@@ -93,7 +93,7 @@
bool start_object(std::size_t elements)
{
- if (elements == std::size_t(-1))
+ if (elements == static_cast<std::size_t>(-1))
{
events.emplace_back("start_object()");
}
@@ -118,7 +118,7 @@
bool start_array(std::size_t elements)
{
- if (elements == std::size_t(-1))
+ if (elements == static_cast<std::size_t>(-1))
{
events.emplace_back("start_array()");
}
diff --git a/test/src/unit-comparison.cpp b/test/src/unit-comparison.cpp
index 05250e4..4feccef 100644
--- a/test/src/unit-comparison.cpp
+++ b/test/src/unit-comparison.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit-concepts.cpp b/test/src/unit-concepts.cpp
index 170e9e9..389c7f3 100644
--- a/test/src/unit-concepts.cpp
+++ b/test/src/unit-concepts.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit-constructor1.cpp b/test/src/unit-constructor1.cpp
index b7973ec..03ad689 100644
--- a/test/src/unit-constructor1.cpp
+++ b/test/src/unit-constructor1.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit-constructor2.cpp b/test/src/unit-constructor2.cpp
index ff623e9..1627ded 100644
--- a/test/src/unit-constructor2.cpp
+++ b/test/src/unit-constructor2.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit-convenience.cpp b/test/src/unit-convenience.cpp
index 22cd3bb..e66b42c 100644
--- a/test/src/unit-convenience.cpp
+++ b/test/src/unit-convenience.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit-conversions.cpp b/test/src/unit-conversions.cpp
index 4ff9152..092d5b8 100644
--- a/test/src/unit-conversions.cpp
+++ b/test/src/unit-conversions.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit-deserialization.cpp b/test/src/unit-deserialization.cpp
index 500966e..bb24241 100644
--- a/test/src/unit-deserialization.cpp
+++ b/test/src/unit-deserialization.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
@@ -93,7 +93,7 @@
bool start_object(std::size_t elements) override
{
- if (elements == std::size_t(-1))
+ if (elements == static_cast<std::size_t>(-1))
{
events.emplace_back("start_object()");
}
@@ -118,7 +118,7 @@
bool start_array(std::size_t elements) override
{
- if (elements == std::size_t(-1))
+ if (elements == static_cast<std::size_t>(-1))
{
events.emplace_back("start_array()");
}
@@ -148,7 +148,7 @@
{
bool start_object(std::size_t elements) override
{
- if (elements == std::size_t(-1))
+ if (elements == static_cast<std::size_t>(-1))
{
events.emplace_back("start_object()");
}
@@ -173,7 +173,7 @@
{
bool start_array(std::size_t elements) override
{
- if (elements == std::size_t(-1))
+ if (elements == static_cast<std::size_t>(-1))
{
events.emplace_back("start_array()");
}
diff --git a/test/src/unit-diagnostics.cpp b/test/src/unit-diagnostics.cpp
index d877da4..c4d7a6a 100644
--- a/test/src/unit-diagnostics.cpp
+++ b/test/src/unit-diagnostics.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
@@ -97,6 +97,18 @@
CHECK_THROWS_WITH_AS(_ = json::parse(""), "[json.exception.parse_error.101] parse error at line 1, column 1: syntax error while parsing value - unexpected end of input; expected '[', '{', or a literal", json::parse_error);
}
+ SECTION("Wrong type in update()")
+ {
+ json j = {{"foo", "bar"}};
+ json k = {{"bla", 1}};
+
+ CHECK_THROWS_WITH_AS(j.update(k["bla"].begin(), k["bla"].end()), "[json.exception.type_error.312] (/bla) cannot use update() with number", json::type_error);
+ CHECK_THROWS_WITH_AS(j.update(k["bla"]), "[json.exception.type_error.312] (/bla) cannot use update() with number", json::type_error);
+ }
+}
+
+TEST_CASE("Regression tests for extended diagnostics")
+{
SECTION("Regression test for https://github.com/nlohmann/json/pull/2562#pullrequestreview-574858448")
{
CHECK_THROWS_WITH_AS(json({"0", "0"})[1].get<int>(), "[json.exception.type_error.302] (/1) type must be number, but is string", json::type_error);
@@ -110,7 +122,7 @@
CHECK_THROWS_WITH_AS(j.unflatten(), "[json.exception.type_error.315] (/~1foo) values in object must be primitive", json::type_error);
}
- SECTION("Regression test for https://github.com/nlohmann/json/issues/2838")
+ SECTION("Regression test for issue #2838 - Assertion failure when inserting into arrays with JSON_DIAGNOSTICS set")
{
// void push_back(basic_json&& val)
{
@@ -235,7 +247,7 @@
}
}
- SECTION("Regression test for https://github.com/nlohmann/json/issues/3032")
+ SECTION("Regression test for issue #3032 - Yet another assertion failure when inserting into arrays with JSON_DIAGNOSTICS set")
{
// reference operator[](size_type idx)
{
diff --git a/test/src/unit-disabled_exceptions.cpp b/test/src/unit-disabled_exceptions.cpp
index fd037d1..44a2b6c 100644
--- a/test/src/unit-disabled_exceptions.cpp
+++ b/test/src/unit-disabled_exceptions.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit-element_access1.cpp b/test/src/unit-element_access1.cpp
index 4eb07cf..f3e7942 100644
--- a/test/src/unit-element_access1.cpp
+++ b/test/src/unit-element_access1.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit-element_access2.cpp b/test/src/unit-element_access2.cpp
index 63a1f99..670458c 100644
--- a/test/src/unit-element_access2.cpp
+++ b/test/src/unit-element_access2.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit-hash.cpp b/test/src/unit-hash.cpp
index 28970d1..efe977b 100644
--- a/test/src/unit-hash.cpp
+++ b/test/src/unit-hash.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
@@ -31,10 +31,11 @@
#include <nlohmann/json.hpp>
using json = nlohmann::json;
+using ordered_json = nlohmann::ordered_json;
#include <set>
-TEST_CASE("hash")
+TEST_CASE("hash<nlohmann::json>")
{
// Collect hashes for different JSON values and make sure that they are distinct
// We cannot compare against fixed values, because the implementation of
@@ -55,7 +56,7 @@
// number
hashes.insert(std::hash<json> {}(json(0)));
- hashes.insert(std::hash<json> {}(json(unsigned(0))));
+ hashes.insert(std::hash<json> {}(json(static_cast<unsigned>(0))));
hashes.insert(std::hash<json> {}(json(-1)));
hashes.insert(std::hash<json> {}(json(0.0)));
@@ -82,3 +83,52 @@
CHECK(hashes.size() == 21);
}
+
+TEST_CASE("hash<nlohmann::ordered_json>")
+{
+ // Collect hashes for different JSON values and make sure that they are distinct
+ // We cannot compare against fixed values, because the implementation of
+ // std::hash may differ between compilers.
+
+ std::set<std::size_t> hashes;
+
+ // null
+ hashes.insert(std::hash<ordered_json> {}(ordered_json(nullptr)));
+
+ // boolean
+ hashes.insert(std::hash<ordered_json> {}(ordered_json(true)));
+ hashes.insert(std::hash<ordered_json> {}(ordered_json(false)));
+
+ // string
+ hashes.insert(std::hash<ordered_json> {}(ordered_json("")));
+ hashes.insert(std::hash<ordered_json> {}(ordered_json("foo")));
+
+ // number
+ hashes.insert(std::hash<ordered_json> {}(ordered_json(0)));
+ hashes.insert(std::hash<ordered_json> {}(ordered_json(static_cast<unsigned>(0))));
+
+ hashes.insert(std::hash<ordered_json> {}(ordered_json(-1)));
+ hashes.insert(std::hash<ordered_json> {}(ordered_json(0.0)));
+ hashes.insert(std::hash<ordered_json> {}(ordered_json(42.23)));
+
+ // array
+ hashes.insert(std::hash<ordered_json> {}(ordered_json::array()));
+ hashes.insert(std::hash<ordered_json> {}(ordered_json::array({1, 2, 3})));
+
+ // object
+ hashes.insert(std::hash<ordered_json> {}(ordered_json::object()));
+ hashes.insert(std::hash<ordered_json> {}(ordered_json::object({{"foo", "bar"}})));
+
+ // binary
+ hashes.insert(std::hash<ordered_json> {}(ordered_json::binary({})));
+ hashes.insert(std::hash<ordered_json> {}(ordered_json::binary({}, 0)));
+ hashes.insert(std::hash<ordered_json> {}(ordered_json::binary({}, 42)));
+ hashes.insert(std::hash<ordered_json> {}(ordered_json::binary({1, 2, 3})));
+ hashes.insert(std::hash<ordered_json> {}(ordered_json::binary({1, 2, 3}, 0)));
+ hashes.insert(std::hash<ordered_json> {}(ordered_json::binary({1, 2, 3}, 42)));
+
+ // discarded
+ hashes.insert(std::hash<ordered_json> {}(ordered_json(ordered_json::value_t::discarded)));
+
+ CHECK(hashes.size() == 21);
+}
diff --git a/test/src/unit-inspection.cpp b/test/src/unit-inspection.cpp
index 69d5327..49d2431 100644
--- a/test/src/unit-inspection.cpp
+++ b/test/src/unit-inspection.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit-items.cpp b/test/src/unit-items.cpp
index 5a7290b..f9021fe 100644
--- a/test/src/unit-items.cpp
+++ b/test/src/unit-items.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit-iterators1.cpp b/test/src/unit-iterators1.cpp
index 71b863d..758e2b5 100644
--- a/test/src/unit-iterators1.cpp
+++ b/test/src/unit-iterators1.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit-iterators2.cpp b/test/src/unit-iterators2.cpp
index 678c84f..bf0b35f 100644
--- a/test/src/unit-iterators2.cpp
+++ b/test/src/unit-iterators2.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit-json_patch.cpp b/test/src/unit-json_patch.cpp
index 8047cac..2c6b9cf 100644
--- a/test/src/unit-json_patch.cpp
+++ b/test/src/unit-json_patch.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
@@ -648,7 +648,7 @@
CHECK(target == R"({ "D": "Berlin", "F": "Paris", "GB": "London" })"_json);
// create a diff from two JSONs
- json p2 = json::diff(target, source);
+ json p2 = json::diff(target, source); // NOLINT(readability-suspicious-call-argument)
// p2 = [{"op": "delete", "path": "/GB"}]
CHECK(p2 == R"([{"op":"remove","path":"/GB"}])"_json);
}
diff --git a/test/src/unit-json_pointer.cpp b/test/src/unit-json_pointer.cpp
index 37a828e..41d7d3a 100644
--- a/test/src/unit-json_pointer.cpp
+++ b/test/src/unit-json_pointer.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit-large_json.cpp b/test/src/unit-large_json.cpp
index cf2f892..bf1a3c5 100644
--- a/test/src/unit-large_json.cpp
+++ b/test/src/unit-large_json.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
@@ -40,7 +40,7 @@
{
const auto depth = 5000000;
- std::string s(2 * depth, '[');
+ std::string s(static_cast<std::size_t>(2 * depth), '[');
std::fill(s.begin() + depth, s.end(), ']');
json _;
diff --git a/test/src/unit-merge_patch.cpp b/test/src/unit-merge_patch.cpp
index 5119b65..6455403 100644
--- a/test/src/unit-merge_patch.cpp
+++ b/test/src/unit-merge_patch.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit-meta.cpp b/test/src/unit-meta.cpp
index 7eec728..65af799 100644
--- a/test/src/unit-meta.cpp
+++ b/test/src/unit-meta.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
@@ -39,14 +39,14 @@
json j = json::meta();
CHECK(j["name"] == "JSON for Modern C++");
- CHECK(j["copyright"] == "(C) 2013-2021 Niels Lohmann");
+ CHECK(j["copyright"] == "(C) 2013-2022 Niels Lohmann");
CHECK(j["url"] == "https://github.com/nlohmann/json");
CHECK(j["version"] == json(
{
- {"string", "3.10.4"},
+ {"string", "3.10.5"},
{"major", 3},
{"minor", 10},
- {"patch", 4}
+ {"patch", 5}
}));
CHECK(j.find("platform") != j.end());
diff --git a/test/src/unit-modifiers.cpp b/test/src/unit-modifiers.cpp
index 9737c14..ca26930 100644
--- a/test/src/unit-modifiers.cpp
+++ b/test/src/unit-modifiers.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
@@ -796,64 +796,89 @@
SECTION("update()")
{
- json j_object1 = {{"one", "eins"}, {"two", "zwei"}};
- json j_object2 = {{"three", "drei"}, {"two", "zwo"}};
- json j_array = {1, 2, 3, 4};
-
- SECTION("const reference")
+ SECTION("non-recursive (default)")
{
- SECTION("proper usage")
- {
- j_object1.update(j_object2);
- CHECK(j_object1 == json({{"one", "eins"}, {"two", "zwo"}, {"three", "drei"}}));
+ json j_object1 = {{"one", "eins"}, {"two", "zwei"}};
+ json j_object2 = {{"three", "drei"}, {"two", "zwo"}};
+ json j_array = {1, 2, 3, 4};
- json j_null;
- j_null.update(j_object2);
- CHECK(j_null == j_object2);
+ SECTION("const reference")
+ {
+ SECTION("proper usage")
+ {
+ j_object1.update(j_object2);
+ CHECK(j_object1 == json({{"one", "eins"}, {"two", "zwo"}, {"three", "drei"}}));
+
+ json j_null;
+ j_null.update(j_object2);
+ CHECK(j_null == j_object2);
+ }
+
+ SECTION("wrong types")
+ {
+ CHECK_THROWS_AS(j_array.update(j_object1), json::type_error&);
+ CHECK_THROWS_WITH(j_array.update(j_object1), "[json.exception.type_error.312] cannot use update() with array");
+
+ CHECK_THROWS_AS(j_object1.update(j_array), json::type_error&);
+ CHECK_THROWS_WITH(j_object1.update(j_array), "[json.exception.type_error.312] cannot use update() with array");
+ }
}
- SECTION("wrong types")
+ SECTION("iterator range")
{
- CHECK_THROWS_AS(j_array.update(j_object1), json::type_error&);
- CHECK_THROWS_WITH(j_array.update(j_object1), "[json.exception.type_error.312] cannot use update() with array");
+ SECTION("proper usage")
+ {
+ j_object1.update(j_object2.begin(), j_object2.end());
+ CHECK(j_object1 == json({{"one", "eins"}, {"two", "zwo"}, {"three", "drei"}}));
- CHECK_THROWS_AS(j_object1.update(j_array), json::type_error&);
- CHECK_THROWS_WITH(j_object1.update(j_array), "[json.exception.type_error.312] cannot use update() with array");
+ json j_null;
+ j_null.update(j_object2.begin(), j_object2.end());
+ CHECK(j_null == j_object2);
+ }
+
+ SECTION("empty range")
+ {
+ j_object1.update(j_object2.begin(), j_object2.begin());
+ CHECK(j_object1 == json({{"one", "eins"}, {"two", "zwei"}}));
+ }
+
+ SECTION("invalid iterators")
+ {
+ json j_other_array2 = {"first", "second"};
+
+ CHECK_THROWS_AS(j_array.update(j_object2.begin(), j_object2.end()), json::type_error&);
+ CHECK_THROWS_AS(j_object1.update(j_object1.begin(), j_object2.end()), json::invalid_iterator&);
+ CHECK_THROWS_AS(j_object1.update(j_array.begin(), j_array.end()), json::type_error&);
+
+ CHECK_THROWS_WITH(j_array.update(j_object2.begin(), j_object2.end()),
+ "[json.exception.type_error.312] cannot use update() with array");
+ CHECK_THROWS_WITH(j_object1.update(j_object1.begin(), j_object2.end()),
+ "[json.exception.invalid_iterator.210] iterators do not fit");
+ CHECK_THROWS_WITH(j_object1.update(j_array.begin(), j_array.end()),
+ "[json.exception.type_error.312] cannot use update() with array");
+ }
}
}
- SECTION("iterator range")
+ SECTION("recursive")
{
- SECTION("proper usage")
+ SECTION("const reference")
{
- j_object1.update(j_object2.begin(), j_object2.end());
- CHECK(j_object1 == json({{"one", "eins"}, {"two", "zwo"}, {"three", "drei"}}));
+ SECTION("extend object")
+ {
+ json j1 = {{"string", "s"}, {"numbers", {{"one", 1}}}};
+ json j2 = {{"string", "t"}, {"numbers", {{"two", 2}}}};
+ j1.update(j2, true);
+ CHECK(j1 == json({{"string", "t"}, {"numbers", {{"one", 1}, {"two", 2}}}}));
+ }
- json j_null;
- j_null.update(j_object2.begin(), j_object2.end());
- CHECK(j_null == j_object2);
- }
-
- SECTION("empty range")
- {
- j_object1.update(j_object2.begin(), j_object2.begin());
- CHECK(j_object1 == json({{"one", "eins"}, {"two", "zwei"}}));
- }
-
- SECTION("invalid iterators")
- {
- json j_other_array2 = {"first", "second"};
-
- CHECK_THROWS_AS(j_array.update(j_object2.begin(), j_object2.end()), json::type_error&);
- CHECK_THROWS_AS(j_object1.update(j_object1.begin(), j_object2.end()), json::invalid_iterator&);
- CHECK_THROWS_AS(j_object1.update(j_array.begin(), j_array.end()), json::invalid_iterator&);
-
- CHECK_THROWS_WITH(j_array.update(j_object2.begin(), j_object2.end()),
- "[json.exception.type_error.312] cannot use update() with array");
- CHECK_THROWS_WITH(j_object1.update(j_object1.begin(), j_object2.end()),
- "[json.exception.invalid_iterator.210] iterators do not fit");
- CHECK_THROWS_WITH(j_object1.update(j_array.begin(), j_array.end()),
- "[json.exception.invalid_iterator.202] iterators first and last must point to objects");
+ SECTION("replace object")
+ {
+ json j1 = {{"string", "s"}, {"numbers", {{"one", 1}}}};
+ json j2 = {{"string", "t"}, {"numbers", 1}};
+ j1.update(j2, true);
+ CHECK(j1 == json({{"string", "t"}, {"numbers", 1}}));
+ }
}
}
}
diff --git a/test/src/unit-msgpack.cpp b/test/src/unit-msgpack.cpp
index 1c4c8ed..70bd6a0 100644
--- a/test/src/unit-msgpack.cpp
+++ b/test/src/unit-msgpack.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
@@ -349,7 +349,7 @@
{
for (uint64_t i :
{
- 4294967296lu, 9223372036854775807lu
+ 4294967296LU, 9223372036854775807LU
})
{
CAPTURE(i)
@@ -446,7 +446,7 @@
SECTION("-32768..-129 (int 16)")
{
- for (int16_t i = -32768; i <= int16_t(-129); ++i)
+ for (int16_t i = -32768; i <= static_cast<std::int16_t>(-129); ++i)
{
CAPTURE(i)
@@ -719,7 +719,7 @@
{
for (uint64_t i :
{
- 4294967296lu, 18446744073709551615lu
+ 4294967296LU, 18446744073709551615LU
})
{
CAPTURE(i)
diff --git a/test/src/unit-noexcept.cpp b/test/src/unit-noexcept.cpp
index 8e89639..bc805bc 100644
--- a/test/src/unit-noexcept.cpp
+++ b/test/src/unit-noexcept.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit-ordered_json.cpp b/test/src/unit-ordered_json.cpp
index 8a6abd6..551ae76 100644
--- a/test/src/unit-ordered_json.cpp
+++ b/test/src/unit-ordered_json.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit-ordered_map.cpp b/test/src/unit-ordered_map.cpp
index 7a23e36..6d511f6 100644
--- a/test/src/unit-ordered_map.cpp
+++ b/test/src/unit-ordered_map.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
@@ -210,6 +210,45 @@
++it2;
CHECK(it2 == om.end());
}
+
+ SECTION("with iterator pair")
+ {
+ SECTION("range in the middle")
+ {
+ // need more elements
+ om["vier"] = "four";
+ om["fünf"] = "five";
+
+ // delete "zwei" and "drei"
+ auto it = om.erase(om.begin() + 1, om.begin() + 3);
+ CHECK(it->first == "vier");
+ CHECK(om.size() == 3);
+ }
+
+ SECTION("range at the beginning")
+ {
+ // need more elements
+ om["vier"] = "four";
+ om["fünf"] = "five";
+
+ // delete "eins" and "zwei"
+ auto it = om.erase(om.begin(), om.begin() + 2);
+ CHECK(it->first == "drei");
+ CHECK(om.size() == 3);
+ }
+
+ SECTION("range at the end")
+ {
+ // need more elements
+ om["vier"] = "four";
+ om["fünf"] = "five";
+
+ // delete "vier" and "fünf"
+ auto it = om.erase(om.begin() + 3, om.end());
+ CHECK(it == om.end());
+ CHECK(om.size() == 3);
+ }
+ }
}
SECTION("count")
diff --git a/test/src/unit-pointer_access.cpp b/test/src/unit-pointer_access.cpp
index 6d1dc3c..5aa38f6 100644
--- a/test/src/unit-pointer_access.cpp
+++ b/test/src/unit-pointer_access.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit-readme.cpp b/test/src/unit-readme.cpp
index 73d81fb..33fadae 100644
--- a/test/src/unit-readme.cpp
+++ b/test/src/unit-readme.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit-reference_access.cpp b/test/src/unit-reference_access.cpp
index 8a7505c..1342d47 100644
--- a/test/src/unit-reference_access.cpp
+++ b/test/src/unit-reference_access.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit-regression1.cpp b/test/src/unit-regression1.cpp
index 92c27ff..8991b82 100644
--- a/test/src/unit-regression1.cpp
+++ b/test/src/unit-regression1.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
@@ -170,7 +170,7 @@
json::number_float_t f1{j1};
CHECK(std::isnan(f1));
- json j2 = json::number_float_t(NAN);
+ json j2 = static_cast<json::number_float_t>(NAN);
CHECK(j2.is_number_float());
json::number_float_t f2{j2};
CHECK(std::isnan(f2));
@@ -183,7 +183,7 @@
json::number_float_t f1{j1};
CHECK(!std::isfinite(f1));
- json j2 = json::number_float_t(INFINITY);
+ json j2 = static_cast<json::number_float_t>(INFINITY);
CHECK(j2.is_number_float());
json::number_float_t f2{j2};
CHECK(!std::isfinite(f2));
@@ -205,7 +205,7 @@
// check if the actual value was stored
CHECK(j2 == 102);
- static_assert(std::is_same<decltype(anon_enum_value), decltype(u)>::value, "");
+ static_assert(std::is_same<decltype(anon_enum_value), decltype(u)>::value, "types must be the same");
j.push_back(json::object(
{
@@ -567,17 +567,17 @@
SECTION("issue #378 - locale-independent num-to-str")
{
- setlocale(LC_NUMERIC, "de_DE.UTF-8");
+ static_cast<void>(setlocale(LC_NUMERIC, "de_DE.UTF-8"));
// verify that dumped correctly with '.' and no grouping
const json j1 = 12345.67;
CHECK(json(12345.67).dump() == "12345.67");
- setlocale(LC_NUMERIC, "C");
+ static_cast<void>(setlocale(LC_NUMERIC, "C"));
}
SECTION("issue #379 - locale-independent str-to-num")
{
- setlocale(LC_NUMERIC, "de_DE.UTF-8");
+ static_cast<void>(setlocale(LC_NUMERIC, "de_DE.UTF-8"));
// verify that parsed correctly despite using strtod internally
CHECK(json::parse("3.14").get<double>() == 3.14);
@@ -910,7 +910,7 @@
++i;
}
- std::remove("test.json");
+ static_cast<void>(std::remove("test.json"));
}
}
diff --git a/test/src/unit-regression2.cpp b/test/src/unit-regression2.cpp
index f0c4ef4..52db358 100644
--- a/test/src/unit-regression2.cpp
+++ b/test/src/unit-regression2.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
@@ -47,10 +47,82 @@
#endif
#ifdef JSON_HAS_CPP_17
- #include <filesystem>
#include <variant>
+
+ #if !defined(JSON_HAS_FILESYSTEM) && !defined(JSON_HAS_EXPERIMENTAL_FILESYSTEM)
+ #if defined(__cpp_lib_filesystem)
+ #define JSON_HAS_FILESYSTEM 1
+ #elif defined(__cpp_lib_experimental_filesystem)
+ #define JSON_HAS_EXPERIMENTAL_FILESYSTEM 1
+ #elif !defined(__has_include)
+ #define JSON_HAS_EXPERIMENTAL_FILESYSTEM 1
+ #elif __has_include(<filesystem>)
+ #define JSON_HAS_FILESYSTEM 1
+ #elif __has_include(<experimental/filesystem>)
+ #define JSON_HAS_EXPERIMENTAL_FILESYSTEM 1
+ #endif
+
+ // std::filesystem does not work on MinGW GCC 8: https://sourceforge.net/p/mingw-w64/bugs/737/
+ #if defined(__MINGW32__) && defined(__GNUC__) && __GNUC__ == 8
+ #undef JSON_HAS_FILESYSTEM
+ #undef JSON_HAS_EXPERIMENTAL_FILESYSTEM
+ #endif
+
+ // no filesystem support before GCC 8: https://en.cppreference.com/w/cpp/compiler_support
+ #if defined(__GNUC__) && __GNUC__ < 8 && !defined(__clang__)
+ #undef JSON_HAS_FILESYSTEM
+ #undef JSON_HAS_EXPERIMENTAL_FILESYSTEM
+ #endif
+
+ // no filesystem support before Clang 7: https://en.cppreference.com/w/cpp/compiler_support
+ #if defined(__clang_major__) && __clang_major__ < 7
+ #undef JSON_HAS_FILESYSTEM
+ #undef JSON_HAS_EXPERIMENTAL_FILESYSTEM
+ #endif
+
+ // no filesystem support before MSVC 19.14: https://en.cppreference.com/w/cpp/compiler_support
+ #if defined(_MSC_VER) && _MSC_VER < 1940
+ #undef JSON_HAS_FILESYSTEM
+ #undef JSON_HAS_EXPERIMENTAL_FILESYSTEM
+ #endif
+
+ // no filesystem support before iOS 13
+ #if defined(__IPHONE_OS_VERSION_MIN_REQUIRED) && __IPHONE_OS_VERSION_MIN_REQUIRED < 130000
+ #undef JSON_HAS_FILESYSTEM
+ #undef JSON_HAS_EXPERIMENTAL_FILESYSTEM
+ #endif
+
+ // no filesystem support before macOS Catalina
+ #if defined(__MAC_OS_X_VERSION_MIN_REQUIRED) && __MAC_OS_X_VERSION_MIN_REQUIRED < 101500
+ #undef JSON_HAS_FILESYSTEM
+ #undef JSON_HAS_EXPERIMENTAL_FILESYSTEM
+ #endif
+ #endif
#endif
+#ifndef JSON_HAS_EXPERIMENTAL_FILESYSTEM
+ #define JSON_HAS_EXPERIMENTAL_FILESYSTEM 0
+#endif
+
+#ifndef JSON_HAS_FILESYSTEM
+ #define JSON_HAS_FILESYSTEM 0
+#endif
+
+#if JSON_HAS_EXPERIMENTAL_FILESYSTEM
+#include <experimental/filesystem>
+namespace nlohmann::detail
+{
+namespace std_fs = std::experimental::filesystem;
+} // namespace nlohmann::detail
+#elif JSON_HAS_FILESYSTEM
+#include <filesystem>
+namespace nlohmann::detail
+{
+namespace std_fs = std::filesystem;
+} // namespace nlohmann::detail
+#endif
+
+
#ifdef JSON_HAS_CPP_20
#include <span>
#endif
@@ -351,9 +423,7 @@
#ifdef JSON_HAS_CPP_17
SECTION("issue #1292 - Serializing std::variant causes stack overflow")
{
- static_assert(
- !std::is_constructible<json, std::variant<int, float>>::value,
- "");
+ static_assert(!std::is_constructible<json, std::variant<int, float>>::value, "unexpected value");
}
#endif
@@ -492,15 +562,15 @@
SECTION("issue #1805 - A pair<T1, T2> is json constructible only if T1 and T2 are json constructible")
{
- static_assert(!std::is_constructible<json, std::pair<std::string, NotSerializableData>>::value, "");
- static_assert(!std::is_constructible<json, std::pair<NotSerializableData, std::string>>::value, "");
- static_assert(std::is_constructible<json, std::pair<int, std::string>>::value, "");
+ static_assert(!std::is_constructible<json, std::pair<std::string, NotSerializableData>>::value, "unexpected result");
+ static_assert(!std::is_constructible<json, std::pair<NotSerializableData, std::string>>::value, "unexpected result");
+ static_assert(std::is_constructible<json, std::pair<int, std::string>>::value, "unexpected result");
}
SECTION("issue #1825 - A tuple<Args..> is json constructible only if all T in Args are json constructible")
{
- static_assert(!std::is_constructible<json, std::tuple<std::string, NotSerializableData>>::value, "");
- static_assert(!std::is_constructible<json, std::tuple<NotSerializableData, std::string>>::value, "");
- static_assert(std::is_constructible<json, std::tuple<int, std::string>>::value, "");
+ static_assert(!std::is_constructible<json, std::tuple<std::string, NotSerializableData>>::value, "unexpected result");
+ static_assert(!std::is_constructible<json, std::tuple<NotSerializableData, std::string>>::value, "unexpected result");
+ static_assert(std::is_constructible<json, std::tuple<int, std::string>>::value, "unexpected result");
}
SECTION("issue #1983 - JSON patch diff for op=add formation is not as per standard (RFC 6902)")
@@ -532,7 +602,7 @@
auto val2 = j.value("y", defval);
}
- SECTION("issue #2293 - eof doesnt cause parsing to stop")
+ SECTION("issue #2293 - eof doesn't cause parsing to stop")
{
std::vector<uint8_t> data =
{
@@ -697,7 +767,7 @@
SECTION("issue #2825 - Properly constrain the basic_json conversion operator")
{
- static_assert(std::is_copy_assignable<nlohmann::ordered_json>::value, "");
+ static_assert(std::is_copy_assignable<nlohmann::ordered_json>::value, "ordered_json must be copy assignable");
}
SECTION("issue #2958 - Inserting in unordered json using a pointer retains the leading slash")
@@ -728,14 +798,16 @@
CHECK(j == k);
}
-#ifdef JSON_HAS_CPP_17
+#if JSON_HAS_FILESYSTEM || JSON_HAS_EXPERIMENTAL_FILESYSTEM
SECTION("issue #3070 - Version 3.10.3 breaks backward-compatibility with 3.10.2 ")
{
- std::filesystem::path text_path("/tmp/text.txt");
+ nlohmann::detail::std_fs::path text_path("/tmp/text.txt");
json j(text_path);
- const auto j_path = j.get<std::filesystem::path>();
+ const auto j_path = j.get<nlohmann::detail::std_fs::path>();
CHECK(j_path == text_path);
+
+ CHECK_THROWS_WITH_AS(nlohmann::detail::std_fs::path(json(1)), "[json.exception.type_error.302] type must be string, but is number", json::type_error);
}
#endif
@@ -746,6 +818,23 @@
std::vector<FooBar> foo;
j.get_to(foo);
}
+
+ SECTION("issue #3108 - ordered_json doesn't support range based erase")
+ {
+ ordered_json j = {1, 2, 2, 4};
+
+ auto last = std::unique(j.begin(), j.end());
+ j.erase(last, j.end());
+
+ CHECK(j.dump() == "[1,2,4]");
+
+ j.erase(std::remove_if(j.begin(), j.end(), [](const ordered_json & val)
+ {
+ return val == 2;
+ }), j.end());
+
+ CHECK(j.dump() == "[1,4]");
+ }
}
DOCTEST_CLANG_SUPPRESS_WARNING_POP
diff --git a/test/src/unit-serialization.cpp b/test/src/unit-serialization.cpp
index e8f488e..b07c349 100644
--- a/test/src/unit-serialization.cpp
+++ b/test/src/unit-serialization.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit-testsuites.cpp b/test/src/unit-testsuites.cpp
index dbfc58d..7fbf831 100644
--- a/test/src/unit-testsuites.cpp
+++ b/test/src/unit-testsuites.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit-to_chars.cpp b/test/src/unit-to_chars.cpp
index 588da69..09bdc86 100644
--- a/test/src/unit-to_chars.cpp
+++ b/test/src/unit-to_chars.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit-ubjson.cpp b/test/src/unit-ubjson.cpp
index 7c1e276..84568f8 100644
--- a/test/src/unit-ubjson.cpp
+++ b/test/src/unit-ubjson.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit-udt.cpp b/test/src/unit-udt.cpp
index af1159a..0bc3241 100644
--- a/test/src/unit-udt.cpp
+++ b/test/src/unit-udt.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit-udt_macro.cpp b/test/src/unit-udt_macro.cpp
index e696177..5aef227 100644
--- a/test/src/unit-udt_macro.cpp
+++ b/test/src/unit-udt_macro.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit-unicode1.cpp b/test/src/unit-unicode1.cpp
index 9101044..3a736b0 100644
--- a/test/src/unit-unicode1.cpp
+++ b/test/src/unit-unicode1.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit-unicode2.cpp b/test/src/unit-unicode2.cpp
index 9712983..8438f17 100644
--- a/test/src/unit-unicode2.cpp
+++ b/test/src/unit-unicode2.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit-unicode3.cpp b/test/src/unit-unicode3.cpp
index d94d332..5bc1afe 100644
--- a/test/src/unit-unicode3.cpp
+++ b/test/src/unit-unicode3.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit-unicode4.cpp b/test/src/unit-unicode4.cpp
index f7817ce..d51880d 100644
--- a/test/src/unit-unicode4.cpp
+++ b/test/src/unit-unicode4.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit-unicode5.cpp b/test/src/unit-unicode5.cpp
index 99d53b9..b63ad16 100644
--- a/test/src/unit-unicode5.cpp
+++ b/test/src/unit-unicode5.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit-user_defined_input.cpp b/test/src/unit-user_defined_input.cpp
index 773a181..3308fec 100644
--- a/test/src/unit-user_defined_input.cpp
+++ b/test/src/unit-user_defined_input.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit-wstring.cpp b/test/src/unit-wstring.cpp
index 8598401..d15ac84 100644
--- a/test/src/unit-wstring.cpp
+++ b/test/src/unit-wstring.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/test/src/unit.cpp b/test/src/unit.cpp
index 52c7c7b..efb0ff5 100644
--- a/test/src/unit.cpp
+++ b/test/src/unit.cpp
@@ -1,12 +1,12 @@
/*
__ _____ _____ _____
__| | __| | | | JSON for Modern C++ (test suite)
-| | |__ | | | | | | version 3.10.4
+| | |__ | | | | | | version 3.10.5
|_____|_____|_____|_|___| https://github.com/nlohmann/json
Licensed under the MIT License <http://opensource.org/licenses/MIT>.
SPDX-License-Identifier: MIT
-Copyright (c) 2013-2019 Niels Lohmann <http://nlohmann.me>.
+Copyright (c) 2013-2022 Niels Lohmann <http://nlohmann.me>.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/third_party/cpplint/README.rst b/third_party/cpplint/README.rst
index 4208f35..18af13c 100644
--- a/third_party/cpplint/README.rst
+++ b/third_party/cpplint/README.rst
@@ -26,9 +26,10 @@
:target: https://pypi.python.org/pypi/cpplint
Cpplint is a command-line tool to check C/C++ files for style issues following `Google's C++ style guide <http://google.github.io/styleguide/cppguide.html>`_.
-Cpplint is developed and maintained by Google Inc. at `google/styleguide <https://github.com/google/styleguide>`_, also see see the `wikipedia entry <http://en.wikipedia.org/wiki/Cpplint>`_
+Cpplint is developed and maintained by Google Inc. at `google/styleguide <https://github.com/google/styleguide>`_, also see the `wikipedia entry <http://en.wikipedia.org/wiki/Cpplint>`_
While Google maintains cpplint, Google is not (very) responsive to issues and pull requests, this fork aims to be (somewhat) more open to add fixes to cpplint to enable fixes, when those fixes make cpplint usable in wider contexts.
+Also see discussion here https://github.com/google/styleguide/pull/528.
Installation
@@ -56,10 +57,10 @@
Changes
-------
-The modifications in this fork are minor fixes and cosmetic changes:
+The modifications in this fork are minor fixes and cosmetic changes, such as:
-* more default extensions
* python 3 compatibility
+* more default file extensions
* customizable file extensions with the --extensions argument
* continuous integration on travis
* support for recursive file discovery via the --recursive argument
@@ -67,6 +68,7 @@
* JUnit XML output format
* Overriding repository root auto-detection via --repository
* Support ``#pragma once`` as an alternative to header include guards
+* ... and a few more (most of which are open PRs on upstream)
Acknowledgements
diff --git a/third_party/cpplint/cpplint.py b/third_party/cpplint/cpplint.py
index 81bc98b..3bf3441 100755
--- a/third_party/cpplint/cpplint.py
+++ b/third_party/cpplint/cpplint.py
@@ -59,7 +59,7 @@
# if empty, use defaults
_valid_extensions = set([])
-__VERSION__ = '1.4.4'
+__VERSION__ = '1.5.5'
try:
xrange # Python 2
@@ -69,7 +69,7 @@
_USAGE = """
-Syntax: cpplint.py [--verbose=#] [--output=emacs|eclipse|vs7|junit]
+Syntax: cpplint.py [--verbose=#] [--output=emacs|eclipse|vs7|junit|sed|gsed]
[--filter=-x,+y,...]
[--counting=total|toplevel|detailed] [--root=subdir]
[--repository=path]
@@ -77,6 +77,7 @@
[--recursive]
[--exclude=path]
[--extensions=hpp,cpp,...]
+ [--includeorder=default|standardcfirst]
[--quiet]
[--version]
<file> [file] ...
@@ -102,11 +103,16 @@
Flags:
- output=emacs|eclipse|vs7|junit
+ output=emacs|eclipse|vs7|junit|sed|gsed
By default, the output is formatted to ease emacs parsing. Visual Studio
compatible output (vs7) may also be used. Further support exists for
eclipse (eclipse), and JUnit (junit). XML parsers such as those used
- in Jenkins and Bamboo may also be used. Other formats are unsupported.
+ in Jenkins and Bamboo may also be used.
+ The sed format outputs sed commands that should fix some of the errors.
+ Note that this requires gnu sed. If that is installed as gsed on your
+ system (common e.g. on macOS with homebrew) you can use the gsed output
+ format. Sed commands are written to stdout, not stderr, so you should be
+ able to pipe output straight to a shell to run the fixes.
verbose=#
Specify a number 0-5 to restrict errors to certain verbosity levels.
@@ -121,11 +127,11 @@
error messages whose category names pass the filters will be printed.
(Category names are printed with the message and look like
"[whitespace/indent]".) Filters are evaluated left to right.
- "-FOO" and "FOO" means "do not print categories that start with FOO".
+ "-FOO" means "do not print categories that start with FOO".
"+FOO" means "do print categories that start with FOO".
Examples: --filter=-whitespace,+whitespace/braces
- --filter=whitespace,runtime/printf,+runtime/printf_format
+ --filter=-whitespace,-runtime/printf,+runtime/printf_format
--filter=-,+build/include_what_you_use
To see a list of all the categories used in cpplint, pass no arg:
@@ -209,6 +215,15 @@
Examples:
--extensions=%s
+ includeorder=default|standardcfirst
+ For the build/include_order rule, the default is to blindly assume angle
+ bracket includes with file extension are c-system-headers (default),
+ even knowing this will have false classifications.
+ The default is established at google.
+ standardcfirst means to instead use an allow-list of known c headers and
+ treat all others as separate group of "other system headers". The C headers
+ included are those of the C-standard lib and closely related ones.
+
headers=x,y,...
The header extensions that cpplint will treat as .h in checks. Values are
automatically added to --extensions list.
@@ -282,6 +297,7 @@
'build/include_alpha',
'build/include_order',
'build/include_what_you_use',
+ 'build/namespaces_headers',
'build/namespaces_literals',
'build/namespaces',
'build/printf_format',
@@ -338,6 +354,13 @@
'whitespace/todo',
]
+# keywords to use with --outputs which generate stdout for machine processing
+_MACHINE_OUTPUTS = [
+ 'junit',
+ 'sed',
+ 'gsed'
+]
+
# These error categories are no longer enforced by cpplint, but for backwards-
# compatibility they may still appear in NOLINT comments.
_LEGACY_ERROR_CATEGORIES = [
@@ -514,6 +537,186 @@
'cwctype',
])
+# C headers
+_C_HEADERS = frozenset([
+ # System C headers
+ 'assert.h',
+ 'complex.h',
+ 'ctype.h',
+ 'errno.h',
+ 'fenv.h',
+ 'float.h',
+ 'inttypes.h',
+ 'iso646.h',
+ 'limits.h',
+ 'locale.h',
+ 'math.h',
+ 'setjmp.h',
+ 'signal.h',
+ 'stdalign.h',
+ 'stdarg.h',
+ 'stdatomic.h',
+ 'stdbool.h',
+ 'stddef.h',
+ 'stdint.h',
+ 'stdio.h',
+ 'stdlib.h',
+ 'stdnoreturn.h',
+ 'string.h',
+ 'tgmath.h',
+ 'threads.h',
+ 'time.h',
+ 'uchar.h',
+ 'wchar.h',
+ 'wctype.h',
+ # additional POSIX C headers
+ 'aio.h',
+ 'arpa/inet.h',
+ 'cpio.h',
+ 'dirent.h',
+ 'dlfcn.h',
+ 'fcntl.h',
+ 'fmtmsg.h',
+ 'fnmatch.h',
+ 'ftw.h',
+ 'glob.h',
+ 'grp.h',
+ 'iconv.h',
+ 'langinfo.h',
+ 'libgen.h',
+ 'monetary.h',
+ 'mqueue.h',
+ 'ndbm.h',
+ 'net/if.h',
+ 'netdb.h',
+ 'netinet/in.h',
+ 'netinet/tcp.h',
+ 'nl_types.h',
+ 'poll.h',
+ 'pthread.h',
+ 'pwd.h',
+ 'regex.h',
+ 'sched.h',
+ 'search.h',
+ 'semaphore.h',
+ 'setjmp.h',
+ 'signal.h',
+ 'spawn.h',
+ 'strings.h',
+ 'stropts.h',
+ 'syslog.h',
+ 'tar.h',
+ 'termios.h',
+ 'trace.h',
+ 'ulimit.h',
+ 'unistd.h',
+ 'utime.h',
+ 'utmpx.h',
+ 'wordexp.h',
+ # additional GNUlib headers
+ 'a.out.h',
+ 'aliases.h',
+ 'alloca.h',
+ 'ar.h',
+ 'argp.h',
+ 'argz.h',
+ 'byteswap.h',
+ 'crypt.h',
+ 'endian.h',
+ 'envz.h',
+ 'err.h',
+ 'error.h',
+ 'execinfo.h',
+ 'fpu_control.h',
+ 'fstab.h',
+ 'fts.h',
+ 'getopt.h',
+ 'gshadow.h',
+ 'ieee754.h',
+ 'ifaddrs.h',
+ 'libintl.h',
+ 'mcheck.h',
+ 'mntent.h',
+ 'obstack.h',
+ 'paths.h',
+ 'printf.h',
+ 'pty.h',
+ 'resolv.h',
+ 'shadow.h',
+ 'sysexits.h',
+ 'ttyent.h',
+ # Additional linux glibc headers
+ 'dlfcn.h',
+ 'elf.h',
+ 'features.h',
+ 'gconv.h',
+ 'gnu-versions.h',
+ 'lastlog.h',
+ 'libio.h',
+ 'link.h',
+ 'malloc.h',
+ 'memory.h',
+ 'netash/ash.h',
+ 'netatalk/at.h',
+ 'netax25/ax25.h',
+ 'neteconet/ec.h',
+ 'netipx/ipx.h',
+ 'netiucv/iucv.h',
+ 'netpacket/packet.h',
+ 'netrom/netrom.h',
+ 'netrose/rose.h',
+ 'nfs/nfs.h',
+ 'nl_types.h',
+ 'nss.h',
+ 're_comp.h',
+ 'regexp.h',
+ 'sched.h',
+ 'sgtty.h',
+ 'stab.h',
+ 'stdc-predef.h',
+ 'stdio_ext.h',
+ 'syscall.h',
+ 'termio.h',
+ 'thread_db.h',
+ 'ucontext.h',
+ 'ustat.h',
+ 'utmp.h',
+ 'values.h',
+ 'wait.h',
+ 'xlocale.h',
+ # Hardware specific headers
+ 'arm_neon.h',
+ 'emmintrin.h',
+ 'xmmintin.h',
+ ])
+
+# Folders of C libraries so commonly used in C++,
+# that they have parity with standard C libraries.
+C_STANDARD_HEADER_FOLDERS = frozenset([
+ # standard C library
+ "sys",
+ # glibc for linux
+ "arpa",
+ "asm-generic",
+ "bits",
+ "gnu",
+ "net",
+ "netinet",
+ "protocols",
+ "rpc",
+ "rpcsvc",
+ "scsi",
+ # linux kernel header
+ "drm",
+ "linux",
+ "misc",
+ "mtd",
+ "rdma",
+ "sound",
+ "video",
+ "xen",
+ ])
+
# Type names
_TYPES = re.compile(
r'^(?:'
@@ -600,9 +803,10 @@
# _IncludeState.CheckNextIncludeOrder().
_C_SYS_HEADER = 1
_CPP_SYS_HEADER = 2
-_LIKELY_MY_HEADER = 3
-_POSSIBLE_MY_HEADER = 4
-_OTHER_HEADER = 5
+_OTHER_SYS_HEADER = 3
+_LIKELY_MY_HEADER = 4
+_POSSIBLE_MY_HEADER = 5
+_OTHER_HEADER = 6
# These constants define the current inline assembly state
_NO_ASM = 0 # Outside of inline assembly block
@@ -622,6 +826,22 @@
# Match string that indicates we're working on a Linux Kernel file.
_SEARCH_KERNEL_FILE = re.compile(r'\b(?:LINT_KERNEL_FILE)')
+# Commands for sed to fix the problem
+_SED_FIXUPS = {
+ 'Remove spaces around =': r's/ = /=/',
+ 'Remove spaces around !=': r's/ != /!=/',
+ 'Remove space before ( in if (': r's/if (/if(/',
+ 'Remove space before ( in for (': r's/for (/for(/',
+ 'Remove space before ( in while (': r's/while (/while(/',
+ 'Remove space before ( in switch (': r's/switch (/switch(/',
+ 'Should have a space between // and comment': r's/\/\//\/\/ /',
+ 'Missing space before {': r's/\([^ ]\){/\1 {/',
+ 'Tab found, replace by spaces': r's/\t/ /g',
+ 'Line ends in whitespace. Consider deleting these extra spaces.': r's/\s*$//',
+ 'You don\'t need a ; after a }': r's/};/}/',
+ 'Missing space after ,': r's/,\([^ ]\)/, \1/g',
+}
+
_regexp_compile_cache = {}
# {str, set(int)}: a map from error categories to sets of linenumbers
@@ -641,13 +861,16 @@
# Files to exclude from linting. This is set by the --exclude flag.
_excludes = None
-# Whether to supress PrintInfo messages
+# Whether to supress all PrintInfo messages, UNRELATED to --quiet flag
_quiet = False
# The allowed line length of files.
# This is set by --linelength flag.
_line_length = 80
+# This allows to use different include order rule than default
+_include_order = "default"
+
try:
unicode
except NameError:
@@ -678,7 +901,7 @@
# Treat all headers starting with 'h' equally: .h, .hpp, .hxx etc.
# This is set by --headers flag.
-_hpp_headers = set(['h', 'hh', 'hpp', 'hxx', 'h++', 'cuh'])
+_hpp_headers = set([])
# {str, bool}: a map from error categories to booleans which indicate if the
# category should be suppressed for every line.
@@ -687,30 +910,48 @@
def ProcessHppHeadersOption(val):
global _hpp_headers
try:
- _hpp_headers = set(val.split(','))
- # Automatically append to extensions list so it does not have to be set 2 times
- _valid_extensions.update(_hpp_headers)
+ _hpp_headers = {ext.strip() for ext in val.split(',')}
except ValueError:
PrintUsage('Header extensions must be comma separated list.')
+def ProcessIncludeOrderOption(val):
+ if val is None or val == "default":
+ pass
+ elif val == "standardcfirst":
+ global _include_order
+ _include_order = val
+ else:
+ PrintUsage('Invalid includeorder value %s. Expected default|standardcfirst')
+
def IsHeaderExtension(file_extension):
- return file_extension in _hpp_headers
+ return file_extension in GetHeaderExtensions()
def GetHeaderExtensions():
- return _hpp_headers or ['h']
+ if _hpp_headers:
+ return _hpp_headers
+ if _valid_extensions:
+ return {h for h in _valid_extensions if 'h' in h}
+ return set(['h', 'hh', 'hpp', 'hxx', 'h++', 'cuh'])
# The allowed extensions for file names
# This is set by --extensions flag
def GetAllExtensions():
- if not _valid_extensions:
- return GetHeaderExtensions().union(set(['c', 'cc', 'cpp', 'cxx', 'c++', 'cu']))
- return _valid_extensions
+ return GetHeaderExtensions().union(_valid_extensions or set(
+ ['c', 'cc', 'cpp', 'cxx', 'c++', 'cu']))
+
+def ProcessExtensionsOption(val):
+ global _valid_extensions
+ try:
+ extensions = [ext.strip() for ext in val.split(',')]
+ _valid_extensions = set(extensions)
+ except ValueError:
+ PrintUsage('Extensions should be a comma-separated list of values;'
+ 'for example: extensions=hpp,cpp\n'
+ 'This could not be parsed: "%s"' % (val,))
def GetNonHeaderExtensions():
return GetAllExtensions().difference(GetHeaderExtensions())
-
-
def ParseNolintSuppressions(filename, raw_line, linenum, error):
"""Updates the global list of line error-suppressions.
@@ -843,11 +1084,13 @@
_MY_H_SECTION = 1
_C_SECTION = 2
_CPP_SECTION = 3
- _OTHER_H_SECTION = 4
+ _OTHER_SYS_SECTION = 4
+ _OTHER_H_SECTION = 5
_TYPE_NAMES = {
_C_SYS_HEADER: 'C system header',
_CPP_SYS_HEADER: 'C++ system header',
+ _OTHER_SYS_HEADER: 'other system header',
_LIKELY_MY_HEADER: 'header this file implements',
_POSSIBLE_MY_HEADER: 'header this file may implement',
_OTHER_HEADER: 'other header',
@@ -857,6 +1100,7 @@
_MY_H_SECTION: 'a header this file implements',
_C_SECTION: 'C system header',
_CPP_SECTION: 'C++ system header',
+ _OTHER_SYS_SECTION: 'other system header',
_OTHER_H_SECTION: 'other header',
}
@@ -970,6 +1214,12 @@
else:
self._last_header = ''
return error_message
+ elif header_type == _OTHER_SYS_HEADER:
+ if self._section <= self._OTHER_SYS_SECTION:
+ self._section = self._OTHER_SYS_SECTION
+ else:
+ self._last_header = ''
+ return error_message
elif header_type == _LIKELY_MY_HEADER:
if self._section <= self._MY_H_SECTION:
self._section = self._MY_H_SECTION
@@ -1011,6 +1261,8 @@
# "eclipse" - format that eclipse can parse
# "vs7" - format that Microsoft Visual Studio 7 can parse
# "junit" - format that Jenkins, Bamboo, etc can parse
+ # "sed" - returns a gnu sed command to fix the problem
+ # "gsed" - like sed, but names the command gsed, e.g. for macOS homebrew users
self.output_format = 'emacs'
# For JUnit output, save errors and failures until the end so that they
@@ -1099,7 +1351,9 @@
self.PrintInfo('Total errors found: %d\n' % self.error_count)
def PrintInfo(self, message):
- if not _quiet and self.output_format != 'junit':
+ # _quiet does not represent --quiet flag.
+ # Hide infos from stdout to keep stdout pure for machine consumption
+ if not _quiet and self.output_format not in _MACHINE_OUTPUTS:
sys.stdout.write(message)
def PrintError(self, message):
@@ -1117,9 +1371,9 @@
num_failures = len(self._junit_failures)
testsuite = xml.etree.ElementTree.Element('testsuite')
- testsuite.attrib['name'] = 'cpplint'
testsuite.attrib['errors'] = str(num_errors)
testsuite.attrib['failures'] = str(num_failures)
+ testsuite.attrib['name'] = 'cpplint'
if num_errors == 0 and num_failures == 0:
testsuite.attrib['tests'] = str(1)
@@ -1313,7 +1567,7 @@
If we have a real absolute path name here we can try to do something smart:
detecting the root of the checkout and truncating /path/to/checkout from
the name so that we get header guards that don't include things like
- "C:\Documents and Settings\..." or "/home/username/..." in them and thus
+ "C:\\Documents and Settings\\..." or "/home/username/..." in them and thus
people on different computers who have checked the source out to different
locations won't see bogus errors.
"""
@@ -1459,6 +1713,13 @@
elif _cpplint_state.output_format == 'junit':
_cpplint_state.AddJUnitFailure(filename, linenum, message, category,
confidence)
+ elif _cpplint_state.output_format in ['sed', 'gsed']:
+ if message in _SED_FIXUPS:
+ sys.stdout.write(_cpplint_state.output_format + " -i '%s%s' %s # %s [%s] [%d]\n" % (
+ linenum, _SED_FIXUPS[message], filename, message, category, confidence))
+ else:
+ sys.stderr.write('# %s:%s: "%s" [%s] [%d]\n' % (
+ filename, linenum, message, category, confidence))
else:
final_message = '%s:%s: %s [%s] [%d]\n' % (
filename, linenum, message, category, confidence)
@@ -1599,7 +1860,7 @@
def RemoveMultiLineCommentsFromRange(lines, begin, end):
"""Clears a range of lines for multi-line comments."""
- # Having // dummy comments makes the lines non-empty, so we will not get
+ # Having // <empty> comments makes the lines non-empty, so we will not get
# unnecessary blank line warnings later in the code.
for i in range(begin, end):
lines[i] = '/**/'
@@ -1973,7 +2234,7 @@
"""Logs an error if no Copyright message appears at the top of the file."""
# We'll say it should occur by line 10. Don't forget there's a
- # dummy line at the front.
+ # placeholder line at the front.
for line in xrange(1, min(len(lines), 11)):
if re.search(r'Copyright', lines[line], re.I): break
else: # means no copyright line was found
@@ -2076,7 +2337,8 @@
# --root=.. , will prepend the outer directory to the header guard
full_path = fileinfo.FullName()
- root_abspath = os.path.abspath(_root)
+ # adapt slashes for windows
+ root_abspath = os.path.abspath(_root).replace('\\', '/')
maybe_path = StripListPrefix(PathSplitToList(full_path),
PathSplitToList(root_abspath))
@@ -2216,16 +2478,22 @@
continue
headername = FileInfo(headerfile).RepositoryName()
first_include = None
+ include_uses_unix_dir_aliases = False
for section_list in include_state.include_list:
for f in section_list:
- if headername in f[0] or f[0] in headername:
+ include_text = f[0]
+ if "./" in include_text:
+ include_uses_unix_dir_aliases = True
+ if headername in include_text or include_text in headername:
return
if not first_include:
first_include = f[1]
- error(filename, first_include, 'build/include', 5,
- '%s should include its header file %s' % (fileinfo.RepositoryName(),
- headername))
+ message = '%s should include its header file %s' % (fileinfo.RepositoryName(), headername)
+ if include_uses_unix_dir_aliases:
+ message += ". Relative paths like . and .. are not allowed."
+
+ error(filename, first_include, 'build/include', 5, message)
def CheckForBadCharacters(filename, lines, error):
@@ -2876,7 +3144,7 @@
# };
class_decl_match = Match(
r'^(\s*(?:template\s*<[\w\s<>,:=]*>\s*)?'
- r'(class|struct)\s+(?:[A-Z_]+\s+)*(\w+(?:::\w+)*))'
+ r'(class|struct)\s+(?:[a-zA-Z0-9_]+\s+)*(\w+(?:::\w+)*))'
r'(.*)$', line)
if (class_decl_match and
(not self.stack or self.stack[-1].open_parentheses == 0)):
@@ -3144,7 +3412,8 @@
Search(r'\bstd\s*::\s*initializer_list\b', constructor_args[0]))
copy_constructor = bool(
onearg_constructor and
- Match(r'(const\s+)?%s(\s*<[^>]*>)?(\s+const)?\s*(?:<\w+>\s*)?&'
+ Match(r'((const\s+(volatile\s+)?)?|(volatile\s+(const\s+)?))?'
+ r'%s(\s*<[^>]*>)?(\s+const)?\s*(?:<\w+>\s*)?&'
% re.escape(base_classname), constructor_args[0].strip()))
if (not is_marked_explicit and
@@ -3203,7 +3472,7 @@
# Note that we assume the contents of [] to be short enough that
# they'll never need to wrap.
if ( # Ignore control structures.
- not Search(r'\b(if|for|while|switch|return|new|delete|catch|sizeof)\b',
+ not Search(r'\b(if|elif|for|while|switch|return|new|delete|catch|sizeof)\b',
fncall) and
# Ignore pointers/references to functions.
not Search(r' \([^)]+\)\([^)]*(\)|,$)', fncall) and
@@ -3316,7 +3585,7 @@
if Search(r'(;|})', start_line): # Declarations and trivial functions
body_found = True
break # ... ignore
- elif Search(r'{', start_line):
+ if Search(r'{', start_line):
body_found = True
function = Search(r'((\w|:)*)\(', line).group(1)
if Match(r'TEST', function): # Handle TEST... macros
@@ -3509,9 +3778,10 @@
# get rid of comments and strings
line = clean_lines.elided[linenum]
- # You shouldn't have spaces before your brackets, except maybe after
- # 'delete []' or 'return []() {};'
- if Search(r'\w\s+\[', line) and not Search(r'(?:delete|return)\s+\[', line):
+ # You shouldn't have spaces before your brackets, except for C++11 attributes
+ # or maybe after 'delete []', 'return []() {};', or 'auto [abc, ...] = ...;'.
+ if (Search(r'\w\s+\[(?!\[)', line) and
+ not Search(r'(?:auto&?|delete|return)\s+\[', line)):
error(filename, linenum, 'whitespace/braces', 5,
'Extra space before [')
@@ -4029,11 +4299,11 @@
# its line, and the line after that should have an indent level equal to or
# lower than the if. We also check for ambiguous if/else nesting without
# braces.
- if_else_match = Search(r'\b(if\s*\(|else\b)', line)
+ if_else_match = Search(r'\b(if\s*(|constexpr)\s*\(|else\b)', line)
if if_else_match and not Match(r'\s*#', line):
if_indent = GetIndentLevel(line)
endline, endlinenum, endpos = line, linenum, if_else_match.end()
- if_match = Search(r'\bif\s*\(', line)
+ if_match = Search(r'\bif\s*(|constexpr)\s*\(', line)
if if_match:
# This could be a multiline if condition, so find the end first.
pos = if_match.end() - 1
@@ -4092,9 +4362,9 @@
# Block bodies should not be followed by a semicolon. Due to C++11
# brace initialization, there are more places where semicolons are
- # required than not, so we use a whitelist approach to check these
- # rather than a blacklist. These are the places where "};" should
- # be replaced by just "}":
+ # required than not, so we explicitly list the allowed rules rather
+ # than listing the disallowed ones. These are the places where "};"
+ # should be replaced by just "}":
# 1. Some flavor of block following closing parenthesis:
# for (;;) {};
# while (...) {};
@@ -4150,11 +4420,11 @@
# - INTERFACE_DEF
# - EXCLUSIVE_LOCKS_REQUIRED, SHARED_LOCKS_REQUIRED, LOCKS_EXCLUDED:
#
- # We implement a whitelist of safe macros instead of a blacklist of
+ # We implement a list of safe macros instead of a list of
# unsafe macros, even though the latter appears less frequently in
# google code and would have been easier to implement. This is because
- # the downside for getting the whitelist wrong means some extra
- # semicolons, while the downside for getting the blacklist wrong
+ # the downside for getting the allowed checks wrong means some extra
+ # semicolons, while the downside for getting disallowed checks wrong
# would result in compile errors.
#
# In addition to macros, we also don't want to warn on
@@ -4575,7 +4845,7 @@
# if(match($0, " <<")) complain = 0;
# if(match(prev, " +for \\(")) complain = 0;
# if(prevodd && match(prevprev, " +for \\(")) complain = 0;
- scope_or_label_pattern = r'\s*\w+\s*:\s*\\?$'
+ scope_or_label_pattern = r'\s*(?:public|private|protected|signals)(?:\s+(?:slots\s*)?)?:\s*\\?$'
classinfo = nesting_state.InnermostClass()
initial_spaces = 0
cleansed_line = clean_lines.elided[linenum]
@@ -4699,13 +4969,14 @@
return os.path.splitext(filename)[0]
-def _ClassifyInclude(fileinfo, include, is_system):
+def _ClassifyInclude(fileinfo, include, used_angle_brackets, include_order="default"):
"""Figures out what kind of header 'include' is.
Args:
fileinfo: The current file cpplint is running over. A FileInfo instance.
include: The path to a #included file.
- is_system: True if the #include used <> rather than "".
+ used_angle_brackets: True if the #include used <> rather than "".
+ include_order: "default" or other value allowed in program arguments
Returns:
One of the _XXX_HEADER constants.
@@ -4715,6 +4986,8 @@
_C_SYS_HEADER
>>> _ClassifyInclude(FileInfo('foo/foo.cc'), 'string', True)
_CPP_SYS_HEADER
+ >>> _ClassifyInclude(FileInfo('foo/foo.cc'), 'foo/foo.h', True, "standardcfirst")
+ _OTHER_SYS_HEADER
>>> _ClassifyInclude(FileInfo('foo/foo.cc'), 'foo/foo.h', False)
_LIKELY_MY_HEADER
>>> _ClassifyInclude(FileInfo('foo/foo_unknown_extension.cc'),
@@ -4725,17 +4998,23 @@
"""
# This is a list of all standard c++ header files, except
# those already checked for above.
- is_cpp_h = include in _CPP_HEADERS
+ is_cpp_header = include in _CPP_HEADERS
+
+ # Mark include as C header if in list or in a known folder for standard-ish C headers.
+ is_std_c_header = (include_order == "default") or (include in _C_HEADERS
+ # additional linux glibc header folders
+ or Search(r'(?:%s)\/.*\.h' % "|".join(C_STANDARD_HEADER_FOLDERS), include))
# Headers with C++ extensions shouldn't be considered C system headers
- if is_system and os.path.splitext(include)[1] in ['.hpp', '.hxx', '.h++']:
- is_system = False
+ is_system = used_angle_brackets and not os.path.splitext(include)[1] in ['.hpp', '.hxx', '.h++']
if is_system:
- if is_cpp_h:
+ if is_cpp_header:
return _CPP_SYS_HEADER
- else:
+ if is_std_c_header:
return _C_SYS_HEADER
+ else:
+ return _OTHER_SYS_HEADER
# If the target file and the include we're checking share a
# basename when we drop common extensions, and the include
@@ -4800,7 +5079,7 @@
match = _RE_PATTERN_INCLUDE.search(line)
if match:
include = match.group(2)
- is_system = (match.group(1) == '<')
+ used_angle_brackets = (match.group(1) == '<')
duplicate_line = include_state.FindHeader(include)
if duplicate_line >= 0:
error(filename, linenum, 'build/include', 4,
@@ -4815,7 +5094,19 @@
'Do not include .' + extension + ' files from other packages')
return
- if not _THIRD_PARTY_HEADERS_PATTERN.match(include):
+ # We DO want to include a 3rd party looking header if it matches the
+ # filename. Otherwise we get an erroneous error "...should include its
+ # header" error later.
+ third_src_header = False
+ for ext in GetHeaderExtensions():
+ basefilename = filename[0:len(filename) - len(fileinfo.Extension())]
+ headerfile = basefilename + '.' + ext
+ headername = FileInfo(headerfile).RepositoryName()
+ if headername in include or include in headername:
+ third_src_header = True
+ break
+
+ if third_src_header or not _THIRD_PARTY_HEADERS_PATTERN.match(include):
include_state.include_list[-1].append((include, linenum))
# We want to ensure that headers appear in the right order:
@@ -4830,7 +5121,7 @@
# track of the highest type seen, and complains if we see a
# lower type after that.
error_message = include_state.CheckNextIncludeOrder(
- _ClassifyInclude(fileinfo, include, is_system))
+ _ClassifyInclude(fileinfo, include, used_angle_brackets, _include_order))
if error_message:
error(filename, linenum, 'build/include_order', 4,
'%s. Should be: %s.h, c system, c++ system, other.' %
@@ -5084,7 +5375,7 @@
if (IsHeaderExtension(file_extension)
and Search(r'\bnamespace\s*{', line)
and line[-1] != '\\'):
- error(filename, linenum, 'build/namespaces', 4,
+ error(filename, linenum, 'build/namespaces_headers', 4,
'Do not use unnamed namespaces in header files. See '
'https://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Namespaces'
' for more information.')
@@ -5374,19 +5665,19 @@
#
# We also accept & in static_assert, which looks like a function but
# it's actually a declaration expression.
- whitelisted_functions = (r'(?:[sS]wap(?:<\w:+>)?|'
+ allowed_functions = (r'(?:[sS]wap(?:<\w:+>)?|'
r'operator\s*[<>][<>]|'
r'static_assert|COMPILE_ASSERT'
r')\s*\(')
- if Search(whitelisted_functions, line):
+ if Search(allowed_functions, line):
return
elif not Search(r'\S+\([^)]*$', line):
- # Don't see a whitelisted function on this line. Actually we
+ # Don't see an allowed function on this line. Actually we
# didn't see any function name on this line, so this is likely a
# multi-line parameter list. Try a bit harder to catch this case.
for i in xrange(2):
if (linenum > i and
- Search(whitelisted_functions, clean_lines.elided[linenum - i - 1])):
+ Search(allowed_functions, clean_lines.elided[linenum - i - 1])):
return
decls = ReplaceAll(r'{[^}]*}', ' ', line) # exclude function body
@@ -5461,7 +5752,7 @@
if not expecting_function:
CheckCStyleCast(filename, clean_lines, linenum, 'static_cast',
- r'\((int|float|double|bool|char|u?int(16|32|64))\)', error)
+ r'\((int|float|double|bool|char|u?int(16|32|64)|size_t)\)', error)
# This doesn't catch all cases. Consider (const char * const)"hello".
#
@@ -5614,11 +5905,11 @@
)),
('<limits>', ('numeric_limits',)),
('<list>', ('list',)),
- ('<map>', ('map', 'multimap',)),
+ ('<map>', ('multimap',)),
('<memory>', ('allocator', 'make_shared', 'make_unique', 'shared_ptr',
'unique_ptr', 'weak_ptr')),
('<queue>', ('queue', 'priority_queue',)),
- ('<set>', ('set', 'multiset',)),
+ ('<set>', ('multiset',)),
('<stack>', ('stack',)),
('<string>', ('char_traits', 'basic_string',)),
('<tuple>', ('tuple',)),
@@ -5652,6 +5943,16 @@
(re.compile(r'[^>.]\b' + _template + r'(<.*?>)?\([^\)]'),
_template,
_header))
+# Match set<type>, but not foo->set<type>, foo.set<type>
+_re_pattern_headers_maybe_templates.append(
+ (re.compile(r'[^>.]\bset\s*\<'),
+ 'set<>',
+ '<set>'))
+# Match 'map<type> var' and 'std::map<type>(...)', but not 'map<type>(...)''
+_re_pattern_headers_maybe_templates.append(
+ (re.compile(r'(std\b::\bmap\s*\<)|(^(std\b::\b)map\b\(\s*\<)'),
+ 'map<>',
+ '<map>'))
# Other scripts may reach in and modify this pattern.
_re_pattern_templates = []
@@ -5734,18 +6035,19 @@
"""
headerfile = None
try:
- headerfile = io.open(filename, 'r', 'utf8', 'replace')
+ with io.open(filename, 'r', 'utf8', 'replace') as headerfile:
+ linenum = 0
+ for line in headerfile:
+ linenum += 1
+ clean_line = CleanseComments(line)
+ match = _RE_PATTERN_INCLUDE.search(clean_line)
+ if match:
+ include = match.group(2)
+ include_dict.setdefault(include, linenum)
+ return True
except IOError:
return False
- linenum = 0
- for line in headerfile:
- linenum += 1
- clean_line = CleanseComments(line)
- match = _RE_PATTERN_INCLUDE.search(clean_line)
- if match:
- include = match.group(2)
- include_dict.setdefault(include, linenum)
- return True
+
def CheckForIncludeWhatYouUse(filename, clean_lines, include_state, error,
@@ -6259,20 +6561,15 @@
except ValueError:
_cpplint_state.PrintError('Line length must be numeric.')
elif name == 'extensions':
- global _valid_extensions
- try:
- extensions = [ext.strip() for ext in val.split(',')]
- _valid_extensions = set(extensions)
- except ValueError:
- sys.stderr.write('Extensions should be a comma-separated list of values;'
- 'for example: extensions=hpp,cpp\n'
- 'This could not be parsed: "%s"' % (val,))
+ ProcessExtensionsOption(val)
elif name == 'root':
global _root
# root directories are specified relative to CPPLINT.cfg dir.
_root = os.path.join(os.path.dirname(cfg_file), val)
elif name == 'headers':
ProcessHppHeadersOption(val)
+ elif name == 'includeorder':
+ ProcessIncludeOrderOption(val)
else:
_cpplint_state.PrintError(
'Invalid configuration option (%s) in file %s\n' %
@@ -6329,7 +6626,8 @@
codecs.getwriter('utf8'),
'replace').read().split('\n')
else:
- lines = codecs.open(filename, 'r', 'utf8', 'replace').read().split('\n')
+ with codecs.open(filename, 'r', 'utf8', 'replace') as target_file:
+ lines = target_file.read().split('\n')
# Remove trailing '\r'.
# The -1 accounts for the extra trailing blank line we get from split()
@@ -6389,10 +6687,10 @@
Args:
message: The optional error message.
"""
- sys.stderr.write(_USAGE % (list(GetAllExtensions()),
- ','.join(list(GetAllExtensions())),
- GetHeaderExtensions(),
- ','.join(GetHeaderExtensions())))
+ sys.stderr.write(_USAGE % (sorted(list(GetAllExtensions())),
+ ','.join(sorted(list(GetAllExtensions()))),
+ sorted(GetHeaderExtensions()),
+ ','.join(sorted(GetHeaderExtensions()))))
if message:
sys.exit('\nFATAL ERROR: ' + message)
@@ -6438,6 +6736,7 @@
'exclude=',
'recursive',
'headers=',
+ 'includeorder=',
'quiet'])
except getopt.GetoptError:
PrintUsage('Invalid arguments.')
@@ -6455,9 +6754,9 @@
if opt == '--version':
PrintVersion()
elif opt == '--output':
- if val not in ('emacs', 'vs7', 'eclipse', 'junit'):
+ if val not in ('emacs', 'vs7', 'eclipse', 'junit', 'sed', 'gsed'):
PrintUsage('The only allowed output formats are emacs, vs7, eclipse '
- 'and junit.')
+ 'sed, gsed and junit.')
output_format = val
elif opt == '--quiet':
quiet = True
@@ -6489,15 +6788,13 @@
_excludes = set()
_excludes.update(glob.glob(val))
elif opt == '--extensions':
- global _valid_extensions
- try:
- _valid_extensions = set(val.split(','))
- except ValueError:
- PrintUsage('Extensions must be comma seperated list.')
+ ProcessExtensionsOption(val)
elif opt == '--headers':
ProcessHppHeadersOption(val)
elif opt == '--recursive':
recursive = True
+ elif opt == '--includeorder':
+ ProcessIncludeOrderOption(val)
if not filenames:
PrintUsage('No files were specified.')
@@ -6514,6 +6811,7 @@
_SetFilters(filters)
_SetCountingStyle(counting_style)
+ filenames.sort()
return filenames
def _ExpandDirectories(filenames):
@@ -6545,15 +6843,35 @@
for filename in expanded:
if os.path.splitext(filename)[1][1:] in GetAllExtensions():
filtered.append(filename)
-
return filtered
-def _FilterExcludedFiles(filenames):
+def _FilterExcludedFiles(fnames):
"""Filters out files listed in the --exclude command line switch. File paths
in the switch are evaluated relative to the current working directory
"""
exclude_paths = [os.path.abspath(f) for f in _excludes]
- return [f for f in filenames if os.path.abspath(f) not in exclude_paths]
+ # because globbing does not work recursively, exclude all subpath of all excluded entries
+ return [f for f in fnames
+ if not any(e for e in exclude_paths
+ if _IsParentOrSame(e, os.path.abspath(f)))]
+
+def _IsParentOrSame(parent, child):
+ """Return true if child is subdirectory of parent.
+ Assumes both paths are absolute and don't contain symlinks.
+ """
+ parent = os.path.normpath(parent)
+ child = os.path.normpath(child)
+ if parent == child:
+ return True
+
+ prefix = os.path.commonprefix([parent, child])
+ if prefix != parent:
+ return False
+ # Note: os.path.commonprefix operates on character basis, so
+ # take extra care of situations like '/foo/ba' and '/foo/bar/baz'
+ child_suffix = child[len(prefix):]
+ child_suffix = child_suffix.lstrip(os.sep)
+ return child == os.path.join(prefix, child_suffix)
def main():
filenames = ParseArguments(sys.argv[1:])
diff --git a/wsjcpp.yml b/wsjcpp.yml
index 91ec796..dff50e8 100644
--- a/wsjcpp.yml
+++ b/wsjcpp.yml
@@ -2,7 +2,7 @@
cmake_minimum_required: "3.0"
cmake_cxx_standard: "11"
name: "nlohmann/json"
-version: "v3.10.4"
+version: "v3.10.5"
description: "JSON for Modern C++"
issues: "https://github.com/nlohmann/json/issues"
keywords:
