In follow up from the conversation in #1269, this adds the
`-Wno-deprecate-declarations` flag to unit tests to allow them to
test deprecated APIs without all the noisy compiler warnings.
This also refactors the setting of build properties for test targets
to use `target_<...>` commands instead of `set_target_properties()`.
Takes an lvalue reference, and returns the same reference.
This allows non-default constructible types to be converted without
specializing adl_serializer.
This overload does not require CopyConstructible either.
Implements #1227
* Make the conversion operator SFINAE correct.
* Workaround a GCC bug with some traits in type_traits.hpp
The first bullet-point implies that every `get`/`get_ptr` be SFINAE
correct as well.
These tests never worked - they weren't run before
d5aaeb4.
Note that these tests would fail because of this library
ordering dictionary keys (which is legal). So changing the
input files (or modifying stored cbor/msgpack/ubjson files)
would make the tests work and they could get removed from
"exclude_packaged".
Also move parsing of files in these unit tests to within
the inner sections, so that they're only parsed
number_of_files * number_of_sections instead of
number_of_files * number_of_files * number_of_sections
(so, instead of close to 100k parses about 700).
"Concepts" have been renamed to "named requirements".
This is because P0898R3 Standard Library Concepts has been merged into
C++20.
Cppreference have moved their links accordingly.
The branch coverage reported by lcov is weird. The code before and after has the same Godbolt assembler, but the code with the lambda has a better branch coverage.
This overload is chosen only when BasicJsonType::string_t
is not constructible from std::map::key_type.
Currently, converting a map to json treats it as an array of pairs.
fixes#1079
The README says:
> "The library itself contains of a single header file ..."
I guess "consists of a" is the wording that was intended here. Alternatively, "contains a" might also be what was intended. Either way, I think both versions work equally well and thus choose the one that I believe was intended.
CMake convention is to use a project namespace, i.e. Foo::, for imported
targets. When multiple targets are imported from a project, this looks
like Foo::Bar1 Foo::Bar2, etc. This adds the nlohmann_json:: namespace to
the exported target names.
This also allows the generated project config files to be used from the
build directory instead of just the install directory.
I contributed a package to the Spack package manager.
Spack is a flexible package manager that supports multiple versions,
configurations, platforms, and compilers. It is popular in
high-performance computing.
Before this patch, `basic_json` types with different template arguments
were treated as `CompatibleArrayType`. Which sometimes leads to recursive
calls and stack overflows.
This patch adds a constructor and a `get` overload to deal with
different `basic_json` types.
Beside the fix discussed in #961, we also had to re-adjust a test case. It seems that it was failing before, and I "fixed" it to work with the broken implementation...
- updated documentation wrt. new repository layout
- temporarily switched off Homebrew --HEAD building (can only be switched on after release)
- set copyright date to 2018
* Rename 'develop' folder to 'include/nlohmann'
* Rename 'src' folder to 'single_include/nlohmann'
* Use <nlohmann/*> headers in sources and tests
* Change amalgamate config file
- Builds and runs test cases from individual sources rather than from amalgamation.
- Checks whether amalgamation would create the same single-header file as checked in.
This is an attempt to fix#360. The algorithm produces
decimal representations which are guaranteed to roundtrip
and in ~99.8% actually produces the shortest possible
representation. So this is a nice compromise between using
a precision of digits10 and max_digits10.
Note 1:
The implementation only works for IEEE single/double precision
numbers. So the old implementation is kept for compatibility
with non-IEEE implementations and 'long double'.
Note 2:
If number_float_t is 'float', not all serialized numbers can
be recovered using strtod (strtof works, though). (There is
exactly one such number and the result is off by 1 ulp.)
This can be avoided by changing the implementation (the fix
is trivial), but then the resulting decimal numbers are not
exactly short.
The tool used before created a lot of duplicates inside the generated amalgamation. The new tool is a single Python file which seems to do the same job.
- Implemented "copy" in terms of "add".
- Added check for JSON Pointer array indices to make sure the complete reference token was processed.
- Added test suite from https://github.com/json-patch/json-patch-tests
The at function throws json::out_of_range.403 when a nonexistent object key is provided (just like the usual at function). This was not documented and users could assume json::out_of_range.404 would be thrown instead.
- Updated documentation.
- Added example code.
We had a lot of issues with failing roundtrips (i.e., parse errors from serializations) in case string were stored in the library that were not UTF-8 encoded. This PR adds an exception in this case.
The example in the documentation on how to "force" an array of arrays was wrong since the first release. Fixed the documentation and added checks for the README unit tests.
Hey, thanks for this great library which I've used in many occasions now. I know it's not much, but I wanted to contribute at least a tiny bit back to you by this PR :-) Keep up the good work!
o For some unknown reason, the complexity of the benchmark platform
prevented some C++ compilers from generating optimal code, properly
reflective of the real performance in actual deployment.
o Added the json_benchmarks_simple target, which performs the same
suite of tests as json_benchmarks.
o Simplified the benchmark platform, and emit an "Average" TPS
(Transactions Per Second) value reflective of aggregate parse/output
performance.
o We assume the same character int_type as the unerlying std::istream
o There are no assumptions on the value of eof(), other than that it
will not be a valid unsigned char value.
o To retain performance, we do not allow swapping out the underlying
std::streambuf during our use of the std::istream for parsing.
o We can retain -Weffc++ and specify default initializers by using
initializer lists. The risks are low (of additional non-conformat
compilers), because there is already one other such initialization
used in the code-base.
o An (-'ve valued, typically -1) EOF must never be allowed in
token_string, as it be converted to 255 -- a legitimate value.
o Comparing against a specific eof() (-1, typically) is more costly than
detecting +'ve/-'ve. Since EOF is the only non-positive value allowed
we can use the simpler test.
o Removed unnecessary test for token_string size, as it is already
tested in the method, and must never occur in correct code; used an
assert instead.
o Return its contents when necessary. In many cases, this avoids
construction of multiple copies of the yytext token. Exceeds
performance of current develop branch.
o Use std::streambuf I/O instead of std::istream; does not maintain
(unused) istream flags.
o Further simplify get/unget handling.
o Restore original handling of NUL in input stream; ignored during
token_string escaping.
The CBOR and MessagePack parsers now expect the input to be read until the end. Unless the new parameter "strict" is set to false (it is true by default), an exception is raised if the parser ends prematurely. This is a breaking change as the parsers ignored unread input so far.
Furthermore, the offset/startIndex paramter introduced in #462 was removed as this behavior can be mimicked with an iterator range. For instance, instead of calling "from_cbor(vec, 5);", you can write "from_cbor({vec.begin()+5, vec.end()});".
o To prevent the compilation issue on OSX with the intel compiler suite. The
error was found with icpc version 15.0.3.187 where the "__clang_version__" was
not defined correctly, while "__clang__" was.
- replaced list of pairs by flat list in next_byte_in_range
- implemented early exit in case of parse errors
- reused memory for object keys
- direct calls to embedded objects/arrays for insertions
The rewrite uses more cmake build-in automatisms and build-in generates
variables to allow better generic reuse.
* cmake files are installed to
``` <install_prefix>/lib/cmake/nlohmann_json/ ``` for best support on
most systems
* include path is set to ``` include ``` for usage as ``` #include
<nlohmann/json.hpp> ```
You can now pass a boolean "allow_exceptions" to the parse functions. If it is false, no exceptions are thrown in case of a parse error. Instead, parsing is stopped at the first error and a JSON value of type "discarded" (check with is_discarded()) is returned.
On MSVC compiler, temporaries that are constructed during a
list initialization, are sometimes destroyed even before calling
the initializing constructor, instead of at the end of the
containing full-expression. This is clearly non-conforming to
[class.temporary].
As the impact of this bug is silently producing incorrect
JSON values, move eagerly from rvalues to be safe.
See https://stackoverflow.com/questions/24586411
- You can now pass a reference to a vector to the to_cbor and to_msgpack functions. The output will be written (appended) to the vector. #476
- You can now pass an output stream with uint8_t character type to the to_cbor and to_msgpack functions. #477
- You can now read from uint8_t */size in the to_cbor and to_msgpack functions. An input adapter will be created from this pair, so you need to use braces. #478
This commit works around an issue in std::initializer_list design.
By using a detail::json_ref proxy with a mutable value inside,
rvalue-ness of an input to list initializer is remembered and
used later to move from the proxy instead of copying.
Travis found an error with Clang 3.8's sanitizers, see https://travis-ci.org/nlohmann/json/jobs/256366699. Unfortunately, I cannot reproduce this error with clang version 6.0.0 (trunk 308825) locally. However, this seems to be an issue, because so far, we did not reset a value after moving from it.
A complete rewrite of the string escape function. It now provides codepoint-to-\uxxxx escaping. Invalid UTF-8 byte sequences are not escaped, but copied as-is. I haven’t spent much time optimizing the code - but the library now agrees with Python on every single Unicode character’s escaping (see file test/data/json_nlohmann_tests/all_unicode_ascii.json).
Other minor changes: replaced "size_t" by "std::size_t"
It makes no sense to have this special exception. Instead of throwing when an input adapter is created, it is better to detect a parse error in later usage when an EOF is "read" unexpectedly.
These breaks were just added to silence a GCC warning - the GCC is right about warning as it cannot know that the expect function will not return in these two scenarios.
It seems these functions are not required any more. The code was added in commit 7e32457 to fix issue #171. There are still regression tests for #171, so when this commit passes the CI, the functions may be removed for good.
When an empty vector was passed to the parse function, an empty iterator range was used to construct an input iterator. Unfortunately, we then cannot use the start iterator to derive a pointer from.
Found with Xcode's undefined behavior sanitizer.
An optional parameter for dump() allows to set the character to use for
indentation (default: space). In case a JSON value is serialized to an
output stream, its fill character is used (and can be set with
std::setfill).
Creates all well-formed sequences of bytes up to length 4. Furthermore,
creates ill-formed sequences by removing required trailing bytes or
changing bytes. As the tests can take a lot of time, preprocessor
symbols are introduced.
As I learned in https://github.com/melpon/wandbox/issues/209, this
library is already installed at Wandbox, so we need to adjust the
examples to use `#include "json.hpp"` insteas of `#include <json.hpp>`.
These classes are now constructed with an interface adapter. This moves
complexity from various places into the interface adapter class, or to
some factories which now implement the different flavors of input.
Furthermore, input adapters are kept in std::shared_ptr to avoid the
need of manual deletion.
We totally forgot to implement the comparison operators other than ==
and != for scalar types. Consequently, comparing a JSON value with a
scalar type led to compile errors.
- removed uncached input stream adapter; it was too slow anyway
- implemented a class binary_read which parses CBOR based on input
adapters
- in the CBOR parser, numbers are created via memcpy to avoid undefined
behavior
The solution with a std::runtime_error member is more elegant. It
allows to have std::exception as base class again. However, I still
have no idea why GCC thinks the copy constructor may throw...
To have nothrow-copy-constructible exceptions, we inherit from
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.
This commit removed the re2c lexer and replaced it by a manual version.
Its integration is not yet complete: number parsing does not respect
locales or overflows. Furthermore, parsing does not need to end with
EOF. Therefore, a lot of test cases fail. The idea is to push this
branch forward so we can conduct performance comparisons. So far, a
nice side effect are better diagnosis messages in case of parse errors.
We should compare the binary serializations rather than the JSON values
themselves. This fix was already done for CBOR and apparently forgotten
for MessagePack.
- Removed unused headers.
- Added override where needed.
- Added description for parse_error.113 exception.
- Fixed some conversion warnings.
- Integrated cbor_expect_string function for CBOR maps.
- Added documentation on the supported CBOR/MessagePack features.
- Added test to check all initial bytes for CBOR input.
When <Windows.h> is included with MSVC, a macro NOMINMAX is defined
that yields compilation errors when max/min calls are encountered. This
can be fixed by un-defining NOMINMAX, or by placing parentheses around
all min/max calls. We chose the latter.
Since #329, NaN and inf numbers do not yield an exception, but are
stored internally and are dumped as “null”. This commit adjusts the
fuzz testers to deal with this special case.
- If an overflow occurs during parsing a number from a JSON text, an
exception (std::out_of_range for the moment, to be replaced by a
user-defined exception #244) is thrown so that the overflow is detected
early and roundtripping is guaranteed.
- NaN and INF floating-point values can be stored in a JSON value and
are not replaced by null. That is, the basic_json class behaves like
double in this regard (no exception occurs). However, NaN and INF are
serialized to “null”.
- Adjusted test cases appropriately.
To avoid the error described in #497, I added a function
msgpack_expect_string that is executed every time a string is expected
during the parsing of a map. In case the current byte does not belong
to a MsgPack string, an exception is thrown.
This test case relied on logics that have been replaced by CMake with
#461. This change enables compilation and execution of the test suite
without exceptions by adding an after_success task.
Added a test to check if the input stream is good() before executing
getline on it. Also added two test cases that set the failbit and
badbit before calling file_line_buffer.
I used __EXCEPTIONS to detect whether exceptions are supported.
Apparently, this is a macro that is only used by libstdc++
(https://gcc.gnu.org/bugzilla/show_bug.cgi?id=64276). It’s much cleaner
to use __cpp_exceptions as it is in the standard since C++98.
Note that compiling the unit-tests with “-fno-exceptions” still does
not work, because Catch uses throw internally. However, the library’s
exceptions can be switched off by defining JSON_NOEXCEPTION.
The original test case relied on an invalidated iterator. This error
did not occur before, but only with GCC with -D_GLIBCXX_DEBUG. This
commit fixes the test case. The library is unaffected by this change.
Added class hierarchy for user-defined exceptions (#244). Integrated
parse exceptions 101-103. Parse exceptions include the byte count of
the last read character to locate the position of the error (#301).
The constructor basic_json(std::istream&, const parser_callback_t) has
been deprecated since version 2.0.0. This commit removes it together
with its code example, deprecation macro, and test cases. The code now
also compiles with -W-deprecated-declarations.
The library does not preserve the insertion order of object keys. There
are frequent requests to change the library in this aspect. The README
and the contribution guidelines now contain links to containers that
can be used to replace std::map to preserve the insertion order.
Moved all dump()-related functions into a class "serializer". This fix includes a lot of performance improvements yielding a 7% speedup for serialization. Details on the individual steps can be found in the commit messages.
Individual benchmark numbers:
before:
dump jeopardy.json 5 374555228 ns/op
dump jeopardy.json with indent 5 430953700 ns/op
dump numbers/floats.json 5 622938509 ns/op
dump numbers/signed_ints.json 20 82177979 ns/op
after:
dump jeopardy.json 5 335449757 ns/op -11%
dump jeopardy.json with indent 5 375467773 ns/op -13%
dump numbers/floats.json 5 584611852 ns/op -7%
dump numbers/signed_ints.json 20 68289574 ns/op -17%
- Added comments for the serializer class.
- Added test case for resizing of the indentation string.
- Using std::none_of to check if “.0” needs to be added to
floating-point number.
A lot of small changes to avoid memory allocations:
- The locale is only queried once rather than with every number
serialization.
- The indentation string is recycled between different calls.
- The string escape function avoids a copy if no escaping is necessary.
- The string escape and the space function use a complete switch case
instead of cascaded ifs.
Cachegrind measures some 15% performance improvement.
Treated the size of the range as the number of thousand separators.
This logical error yielded a negative value for written_bytes and
eventually an infinite loop, as written_bytes was converted to an
unsigned value.
The class is currently just a wrapper for an std::ostream and collects
all functions related to serialization. The next step should be
recycling of variables to avoid repetitive initialization for each
recursive dump call.
numtostr now directly writes to a stream. Return value of snprintf is
reused to avoid finding end of string. Cachegrind suggests a 1%
performance increase.
All ‘<<‘ calls have been replaced by write()/put() calls. The
indentation strings needs not to be resized. Cachegrind measures 1%
performance improvement.
Indentation string is recycled to avoid allocations. Comma-separation
in objects does not need an if any more. Cachegrind measures 1%
performance improvement.
Added separate code paths for normal output and pritty-printed output.
This allowed to remove most of the ifs along the way. Benchmarks and
cachegrind suggest a 10% performance improvement.
- Add prefix header
- Include catch.hpp
- Include json.hpp
- Replace private with public for all json_unit files
- Move `unit.cpp` to an object library
- cotire issue: strip whitespace from CMAKE_INCLUDE_SYSTEM_FLAG_CXX
This can however not be done easily for value_t, since
external_constructor depends on it, as is operator< which was moved
outside basic_json too.
This is not really an issue, since all basic_json classes share the same
enum
Those warnings are not "fixed", but that's intentional.
Truncations are expected when ArithmeticType is not the same type than
number_unsigned_t (or another basic_json template argument)
only check for public types (iterators, json_pointer)
for private ones (m_array.iterator, primitive_iterator) simply double
parentheses on relevant Catch checks
- fixed a bug that did not discard strings with control characters
between 0x10 and 0x1f
- added termination proofs for two important loops
- made get_ref() constexpr
Instead of copying the test executable and the JSON files used by
the tests at install time, define CMake/CTest tests for running
the json_unit executable from any build directory with the project's
source directory as its working directory.
- call enable_testing in the main lists file to allow the definition
of tests
- remove install commands from the test directory's lists file
- define two tests
- json_unit_default for running the default tests by executing
json_unit without any arguments
- json_unit_all for running all the tests by executing json_unit
with the "*" argument
- update the AppVeyor configuration file to use the new testing method
It's sort of gnarly that it's still doing in-tree builds, but I
really, _really_ don't want to get any more friendly with CMake's
Visual Studio generator to work out how to make it stop doing it.
In-tree builds still work, after all, and the goal of this work is
to make out-of-tree builds work as well. Notional horrors like
this will have to wait ;)
The resulting install tree, when tests are enabled, looks like this:
```
.
├── cmake
│ ├── nlohmann_jsonConfig.cmake
│ ├── nlohmann_jsonConfigVersion.cmake
│ └── nlohmann_jsonTargets.cmake
├── include
│ └── nlohmann
│ └── json.hpp
└── test
├── bin
│ └── json_unit
└── data
├── json_nlohmann_tests
│ ├── all_unicode.json
│ └── bom.json
├── json.org
│ ├── 1.json
│ ├── ...
├── json_roundtrip
│ ├── roundtrip01.json
│ ├── roundtrip02.json
│ └── ...
├── json_tests
│ ├── fail10.json
│ └── ...
└── json_testsuite
└── sample.json
```
It has the property that you can invoke the test binary from the
root of the install tree and the tests work correctly (you no
longer depend on the test binary being run inside the source
tree).
If tests are disabled, the entire `test/` subtree is omitted.
Notice how that yields exactly what you want for using this
library in other projects.
I do not believe I need to update travis due to this change, as the
evil Makefile continues to do in-tree builds. I expect I'll find
out soon enough.
This introduces a clear separation between test data and test
binaries. Test data is moved into test/data, and the test binaries
move into test/src. A new CMake script specific to building the
tests is introduced in /test to slightly clean up the toplevel
one.
As well as tidying things up, this makes the next step trivial...
There exist lots of json libraries, and project/target names must
be globally unique. If someone integrated with this library in a
particularly stupid way, using a generic name like "json" might
cause a problem.
I'm not sure that using a variable for target names really helps
with clarity. Unlike paths, target names aren't really something
you change. In a sense, targets are themselves a sort of variable,
so having a variable to name a variable seems just a bit gnarly.
Generate the config files of the package in CMAKE_CURRENT_BINARY_DIR
instead of CMAKE_BINARY_DIR because the later will refer to the main
project's binary directory if the library is included in the project
using the add_subdirectory command.
- define the project's version in the cmake listfile
- create a config and config version file for the cmake package
- install the json.hpp file and the package's targets, config and
config version files
Define the library as an interface imported library so other targets
can use the library as a dependency and use the interface properties
of the library.
According to the c++11 standard, the declarations are within namespace
scope of the namespace `std'. Add `std::' to avoid unnecessary
requirement of implementations.
Internally, the elements in a map are always sorted by its key following a specific strict weak ordering criterion indicated by its internal comparison object (of type Compare).
With string type, the default comparator is alphabetical order, and thus two come after three.
"make fuzz" creates a simple executable that de-serialises stdin
and re-serialises to stdout.
"make fuzz_testcases" extracts the smaller json test cases into
a testcases directory.
The library can then be fuzzed as follows:
CC=afl-clang-fast make fuzz
make fuzz_testcases
mkdir out
afl-fuzz -i testcases -o out ./fuzz
It was a good idea to implement a const version of operator[] it in the
first place. I was a pity that this implementation was flawed. It was a
mistake to remove the const version completely. This commit
re-introduces the const version. My apologies for all the inconvenience.
STL iterators used by json::iterator don't pass this test in Debug mode.
The test does pass in Release mode, so I felt the best thing to do was selectively disable that test.
In this commit, also the semantics for values skipped via the parser
callback has changed. Now, the top-level value is returned as “null”
instead of “discarded”.
Avoid a warning with GCC 4.9:
son.hpp:2361:49: warning: declaration 'struct std::bidirectional_iterator_tag' does not declare anything
using iterator_category = typename std::bidirectional_iterator_tag;
^
- removed m_final member
- parse_internal now takes a reference to a basic_json object to fill
with data
- header is automatically regenerated if re2c file is changed
Until now it depended on the parameter-order whether
integers and floats were compared as integers or floats.
Appart from being not logical, this might even have meant that
the provided “order” was in fact not that. (not sure here, but I
like to be carefull)
Now uses std::snprintf() to generate a "%.15g" formatted string
for JSON values of type number_float. 15 decimals digits are
enough to round-trip an IEEE 754 double from string->double->string
and get an identical result.
std::snprintf is called twice. Once to determine the required
buffer size and then again after allocating a buffer of that
size.
Note that the buffer size *could* be hardcoded for better
performance. "%.15g" should result in strings of maximum length
23, plus one character for the terminating null for a buffer size
of 24.
If the new operator throws in the json::find methods then result.oi_ is
deleted again in the destructor of json::iterator/json::const_iterator,
which is a double delete and undefined behaviour.
This project started as a little excuse to exercise some of the cool new C++11 features. Over time, people actually started to use the JSON library (yey!) and started to help improve it by proposing features, finding bugs, or even fixing my mistakes. I am really [thankful](https://github.com/nlohmann/json/blob/master/README.md#thanks) for this and try to keep track of all the helpers.
To make it as easy as possible for you to contribute and for me to keep an overview, here are a few guidelines which should help us avoid all kinds of unnecessary work or disappointment. And of course, this document is subject to discussion, so please [create an issue](https://github.com/nlohmann/json/issues/new) or a pull request if you find a way to improve it!
## Private reports
Usually, all issues are tracked publicly on [GitHub](https://github.com/nlohmann/json/issues). If you want to make a private report (e.g., for a vulnerability or to attach an example that is not meant to be published), please send an email to <mail@nlohmann.me>.
## Prerequisites
Please [create an issue](https://github.com/nlohmann/json/issues/new), assuming one does not already exist, and describe your concern. Note you need a [GitHub account](https://github.com/signup/free) for this.
## Describe your issue
Clearly describe the issue:
- If it is a bug, please describe how to **reproduce** it. If possible, attach a complete example which demonstrates the error. Please also state what you **expected** to happen instead of the error.
- If you propose a change or addition, try to give an **example** how the improved code could look like or how to use it.
- If you found a compilation error, please tell us which **compiler** (version and operating system) you used and paste the (relevant part of) the error messages to the ticket.
Please stick to the [issue template](https://github.com/nlohmann/json/blob/develop/.github/ISSUE_TEMPLATE.md) if possible.
## Files to change
:exclamation: Before you make any changes, note the single-header file [`single_include/nlohmann/json.hpp`](https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json.hpp) is **generated** from the source files in the [`include/nlohmann` directory](https://github.com/nlohmann/json/tree/develop/include/nlohmann). Please **do not** edit file `single_include/nlohmann/json.hpp` directly, but change the `include/nlohmann` sources and regenerate file `single_include/nlohmann/json.hpp` by executing `make amalgamate`.
To make changes, you need to edit the following files:
1. [`include/nlohmann/*`](https://github.com/nlohmann/json/tree/develop/include/nlohmann) - These files are the sources of the library. Before testing or creating a pull request, execute `make amalgamate` to regenerate `single_include/nlohmann/json.hpp`.
2. [`test/src/unit-*.cpp`](https://github.com/nlohmann/json/tree/develop/test/src) - These files contain the [Catch](https://github.com/philsquared/Catch) unit tests which currently cover [100 %](https://coveralls.io/github/nlohmann/json) of the library's code.
If you add or change a feature, please also add a unit test to this file. The unit tests can be compiled and executed with
```sh
$ mkdir build
$ cd build
$ cmake ..
$ cmake --build .
$ ctest
```
The test cases are also executed with several different compilers on [Travis](https://travis-ci.org/nlohmann/json) once you open a pull request.
## Note
- If you open a pull request, the code will be automatically tested with [Valgrind](http://valgrind.org)'s Memcheck tool to detect memory leaks. Please be aware that the execution with Valgrind _may_ in rare cases yield different behavior than running the code directly. This can result in failing unit tests which run successfully without Valgrind.
- There is a Makefile target `make pretty` which runs [Artistic Style](http://astyle.sourceforge.net) to fix indentation. If possible, run it before opening the pull request. Otherwise, we shall run it afterward.
## Please don't
- The C++11 support varies between different **compilers** and versions. Please note the [list of supported compilers](https://github.com/nlohmann/json/blob/master/README.md#supported-compilers). Some compilers like GCC 4.7 (and earlier), Clang 3.3 (and earlier), or Microsoft Visual Studio 13.0 and earlier are known not to work due to missing or incomplete C++11 support. Please refrain from proposing changes that work around these compiler's limitations with `#ifdef`s or other means.
- Specifically, I am aware of compilation problems with **Microsoft Visual Studio** (there even is an [issue label](https://github.com/nlohmann/json/issues?utf8=✓&q=label%3A%22visual+studio%22+) for these kind of bugs). I understand that even in 2016, complete C++11 support isn't there yet. But please also understand that I do not want to drop features or uglify the code just to make Microsoft's sub-standard compiler happy. The past has shown that there are ways to express the functionality such that the code compiles with the most recent MSVC - unfortunately, this is not the main objective of the project.
- Please refrain from proposing changes that would **break [JSON](http://json.org) conformance**. If you propose a conformant extension of JSON to be supported by the library, please motivate this extension.
- We shall not extend the library to **support comments**. There is quite some [controversy](https://www.reddit.com/r/programming/comments/4v6chu/why_json_doesnt_support_comments_douglas_crockford/) around this topic, and there were quite some [issues](https://github.com/nlohmann/json/issues/376) on this. We believe that JSON is fine without comments.
- We do not preserve the **insertion order of object elements**. The [JSON standard](https://tools.ietf.org/html/rfc7159.html) defines objects as "an unordered collection of zero or more name/value pairs". To this end, this library does not preserve insertion order of name/value pairs. (In fact, keys will be traversed in alphabetical order as `std::map` with `std::less` is used by default.) Note this behavior conforms to the standard, and we shall not change it to any other order. If you do want to preserve the insertion order, you can specialize the object type with containers like [`tsl::ordered_map`](https://github.com/Tessil/ordered-map) or [`nlohmann::fifo_map`](https://github.com/nlohmann/fifo_map).
- Please do not open pull requests that address **multiple issues**.
## Wanted
The following areas really need contribution:
- Extending the **continuous integration** toward more exotic compilers such as Android NDK, Intel's Compiler, or the bleeding-edge versions of GCC or Clang.
- Improving the efficiency of the **JSON parser**. The current parser is implemented as a naive recursive descent parser with hand coded string handling. More sophisticated approaches like LALR parsers would be really appreciated. That said, parser generators like Bison or ANTLR do not play nice with single-header files -- I really would like to keep the parser inside the `json.hpp` header, and I am not aware of approaches similar to [`re2c`](http://re2c.org) for parsing.
- Extending and updating existing **benchmarks** to include (the most recent version of) this library. Though efficiency is not everything, speed and memory consumption are very important characteristics for C++ developers, so having proper comparisons would be interesting.
[Describe your pull request here. Please read the text below the line, and make sure you follow the checklist.]
* * *
## Pull request checklist
Read the [Contribution Guidelines](https://github.com/nlohmann/json/blob/develop/.github/CONTRIBUTING.md) for detailed information.
- [ ] Changes are described in the pull request, or an [existing issue is referenced](https://github.com/nlohmann/json/issues).
- [ ] The test suite [compiles and runs](https://github.com/nlohmann/json/blob/develop/README.md#execute-unit-tests) without error.
- [ ] [Code coverage](https://coveralls.io/github/nlohmann/json) is 100%. Test cases can be added by editing the [test suite](https://github.com/nlohmann/json/tree/develop/test/src).
- [ ] The source code is amalgamated; that is, after making changes to the sources in the `include/nlohmann` directory, run `make amalgamate` to create the single-header file `single_include/nlohmann/json.hpp`. The whole process is described [here](https://github.com/nlohmann/json/blob/develop/.github/CONTRIBUTING.md#files-to-change).
## Please don't
- The C++11 support varies between different **compilers** and versions. Please note the [list of supported compilers](https://github.com/nlohmann/json/blob/master/README.md#supported-compilers). Some compilers like GCC 4.7 (and earlier), Clang 3.3 (and earlier), or Microsoft Visual Studio 13.0 and earlier are known not to work due to missing or incomplete C++11 support. Please refrain from proposing changes that work around these compiler's limitations with `#ifdef`s or other means.
- Specifically, I am aware of compilation problems with **Microsoft Visual Studio** (there even is an [issue label](https://github.com/nlohmann/json/issues?utf8=✓&q=label%3A%22visual+studio%22+) for these kind of bugs). I understand that even in 2016, complete C++11 support isn't there yet. But please also understand that I do not want to drop features or uglify the code just to make Microsoft's sub-standard compiler happy. The past has shown that there are ways to express the functionality such that the code compiles with the most recent MSVC - unfortunately, this is not the main objective of the project.
- Please refrain from proposing changes that would **break [JSON](http://json.org) conformance**. If you propose a conformant extension of JSON to be supported by the library, please motivate this extension.
- Please do not open pull requests that address **multiple issues**.
# Configuration for sentiment-bot - https://github.com/behaviorbot/sentiment-bot
# *Required* toxicity threshold between 0 and .99 with the higher numbers being the most toxic
# Anything higher than this threshold will be marked as toxic and commented on
sentimentBotToxicityThreshold:.7
# *Required* Comment to reply with
sentimentBotReplyComment:>
Please be sure to review the [code of conduct](https://github.com/nlohmann/json/blob/develop/CODE_OF_CONDUCT.md) and be respectful of other users. cc/ @nlohmann
# Configuration for request-info - https://github.com/behaviorbot/request-info
# *Required* Comment to reply with
requestInfoReplyComment:>
We would appreciate it if you could provide us with more info about this issue or pull request! Please check the [issue template](https://github.com/nlohmann/json/blob/develop/.github/ISSUE_TEMPLATE.md) and the [pull request template](https://github.com/nlohmann/json/blob/develop/.github/PULL_REQUEST_TEMPLATE.md).
# *OPTIONAL* Label to be added to Issues and Pull Requests with insufficient information given
In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
## Our Standards
Examples of behavior that contributes to creating a positive environment include:
* Using welcoming and inclusive language
* Being respectful of differing viewpoints and experiences
* Gracefully accepting constructive criticism
* Focusing on what is best for the community
* Showing empathy towards other community members
Examples of unacceptable behavior by participants include:
* The use of sexualized language or imagery and unwelcome sexual attention or advances
* Trolling, insulting/derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or electronic address, without explicit permission
* Other conduct which could reasonably be considered inappropriate in a professional setting
## Our Responsibilities
Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
## Scope
This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at mail@nlohmann.me. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
gsed -i '2i All notable changes to this project will be documented in this file. This project adheres to [Semantic Versioning](http://semver.org/).' ChangeLog.md
This function is usually called by the [`get()`](https://json.nlohmann.me/api/basic_json/get/index.md) function of the [basic_json](https://json.nlohmann.me/api/basic_json/index.md) class (either explicitly or via the conversion operators).
1. This function is chosen for default-constructible value types.
1. 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
1. (none) -- the converted value is written to the output parameter `val`.
1. the JSON value `j` converted to `TargetType`
## Examples
Example: (1) Default-constructible type
The example below shows how a `from_json` function can be implemented for a user-defined type. This function is called by the `adl_serializer` when `get<ns::person>()` is called.
The example below shows how a `from_json` is implemented as part of a specialization of the `adl_serializer` to realize the conversion of a non-default-constructible type.
```
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
namespace ns
{
// a simple struct to model a person (not default constructible)
Serializer that uses ADL ([Argument-Dependent Lookup](https://en.cppreference.com/w/cpp/language/adl)) to choose `to_json`/`from_json` functions from the types' namespaces.
This function is usually called by the constructors of the [basic_json](https://json.nlohmann.me/api/basic_json/index.md) class.
## Parameters
`j` (out) : JSON value to write to
`val` (in) : value to read from
## Examples
Example
The example below shows how a `to_json` function can be implemented for a user-defined type. This function is called by the `adl_serializer` when the constructor `basic_json(ns::person)` is called.
2. Reads from a pair of character iterators, or an iterator and a sentinel of a different type (C++20 ranges support)
The value_type of the iterator must be an integral type with a size of 1, 2, or 4 bytes, which will be interpreted
respectively as UTF-8, UTF-16, and UTF-32. If `SentinelType` differs from `IteratorType`, it must be comparable to
the iterator type with `operator!=`.
Unlike the [`parse()`](parse.md) function, this function neither throws an exception in case of invalid JSON input
(i.e., a parse error) nor creates diagnostic information.
## Template parameters
`InputType`
: A compatible input, for instance:
- an `std::istream` object
- a `#!c FILE` pointer (throws if null)
- a C-style array of characters
- a pointer to a null-terminated string of single byte characters (throws if null)
- a `std::string`
- a container `obj` for which `begin(obj)` and `end(obj)` produce a valid pair of iterators
(as found via ADL or member functions, with semantics compatible to `std::begin` and `std::end`)
`IteratorType`
: 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`
`SentinelType`
: defaults to `IteratorType`; may be a different type comparable to `IteratorType` via `operator!=`, for instance.
- a custom sentinel type for C++20 ranges
-`std::default_sentinel_t`, when `IteratorType` is `std::counted_iterator`
## Parameters
`i` (in)
: Input to parse from.
`ignore_comments` (in)
: whether comments should be ignored and treated like whitespace (`#!cpp true`) or yield a parse error
(`#!cpp false`); (optional, `#!cpp false` by default)
`ignore_trailing_commas` (in)
: whether trailing commas in arrays or objects should be ignored and treated like whitespace (`#!cpp true`) or yield a parse error
(`#!cpp false`); (optional, `#!cpp false` by default)
`first` (in)
: iterator to the start of the character range
`last` (in)
: iterator to the end of the character range, or a sentinel value that compares equal to the end iterator with `operator!=`
## Return value
Whether the input is valid JSON.
## Exception safety
Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
## Exceptions
Throws [`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101) in case of an empty input like a null `#!c FILE*` or `#!c char*` pointer.
## 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 demonstrates the `accept()` function reading from a string.
```cpp
--8<-- "examples/accept__string.cpp"
```
Output:
```json
--8<-- "examples/accept__string.output"
```
## See also
- [parse](parse.md) - deserialize from a compatible input
- [sax_parse](sax_parse.md) - parse input using the SAX interface
- [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.
- Changed [runtime assertion](../../features/assertions.md) in case of `FILE*` null pointers to exception in version 3.12.0.
- Added `ignore_trailing_commas` in version 3.13.0.
- Extended container support (1) to include types with lvalue-only ADL `begin`/`end` (matching `std::begin`/`std::end` semantics) in version 3.13.0.
- Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.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
static bool accept(IteratorType first, SentinelType last,
const bool ignore_comments = false,
const bool ignore_trailing_commas = false);
```
Checks whether the input is valid JSON.
1. Reads from a compatible input.
1. Reads from a pair of character iterators, or an iterator and a sentinel of a different type (C++20 ranges support)
The value_type of the iterator must be an integral type with a size of 1, 2, or 4 bytes, which will be interpreted respectively as UTF-8, UTF-16, and UTF-32. If `SentinelType` differs from `IteratorType`, it must be comparable to the iterator type with `operator!=`.
Unlike the [`parse()`](https://json.nlohmann.me/api/basic_json/parse/index.md) function, this function neither throws an exception in case of invalid JSON input (i.e., a parse error) nor creates diagnostic information.
## Template parameters
`InputType` : A compatible input, for instance:
```
- an `std::istream` object
- a `FILE` pointer (throws if null)
- a C-style array of characters
- a pointer to a null-terminated string of single byte characters (throws if null)
- a `std::string`
- a container `obj` for which `begin(obj)` and `end(obj)` produce a valid pair of iterators
(as found via ADL or member functions, with semantics compatible to `std::begin` and `std::end`)
```
`IteratorType` : 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`
```
`SentinelType` : defaults to `IteratorType`; may be a different type comparable to `IteratorType` via `operator!=`, for instance.
```
- a custom sentinel type for C++20 ranges
- `std::default_sentinel_t`, when `IteratorType` is `std::counted_iterator`
```
## Parameters
`i` (in) : Input to parse from.
`ignore_comments` (in) : whether comments should be ignored and treated like whitespace (`true`) or yield a parse error (`false`); (optional, `false` by default)
`ignore_trailing_commas` (in) : whether trailing commas in arrays or objects should be ignored and treated like whitespace (`true`) or yield a parse error (`false`); (optional, `false` by default)
`first` (in) : iterator to the start of the character range
`last` (in) : iterator to the end of the character range, or a sentinel value that compares equal to the end iterator with `operator!=`
## Return value
Whether the input is valid JSON.
## Exception safety
Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
## Exceptions
Throws [`parse_error.101`](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error101) in case of an empty input like a null `FILE*` or `char*` pointer.
## Complexity
Linear in the length of the input. The parser is a predictive LL(1) parser.
## Notes
A UTF-8 byte order mark is silently ignored.
## Examples
Example
The example below demonstrates the `accept()` function reading from a string.
```
#include <iostream>
#include <iomanip>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// a valid JSON text
auto valid_text = R"(
{
"numbers": [1, 2, 3]
}
)";
// an invalid JSON text
auto invalid_text = R"(
{
"strings": ["extra", "comma", ]
}
)";
std::cout << std::boolalpha
<< json::accept(valid_text) << ' '
<< json::accept(invalid_text) << '\n';
}
```
Output:
```
true false
```
## See also
- [parse](https://json.nlohmann.me/api/basic_json/parse/index.md) - deserialize from a compatible input
- [sax_parse](https://json.nlohmann.me/api/basic_json/sax_parse/index.md) - parse input using the SAX interface
- [operator>>](https://json.nlohmann.me/api/operator_gtgt/index.md) - deserialize from stream
## Version history
- Added in version 3.0.0.
- Ignoring comments via `ignore_comments` added in version 3.9.0.
- Changed [runtime assertion](https://json.nlohmann.me/features/assertions/index.md) in case of `FILE*` null pointers to exception in version 3.12.0.
- Added `ignore_trailing_commas` in version 3.13.0.
- Extended container support (1) to include types with lvalue-only ADL `begin`/`end` (matching `std::begin`/`std::end` semantics) in version 3.13.0.
- Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.
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 `accept({ptr, ptr+len}, ...);` with `accept(ptr, ptr+len, ...);`.
You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated function.
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.
## Parameters
`init` (in) : initializer list with JSON values to create an array from (optional)
## Return value
JSON array value
## Exception safety
Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
## Complexity
Linear in the size of `init`.
## Notes
This function is only needed to express two edge cases that cannot be realized with the initializer list constructor ([`basic_json(initializer_list_t, bool, value_t)`](https://json.nlohmann.me/api/basic_json/basic_json/index.md)). 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
1. creating an empty array -- passing the empty initializer list to the initializer list constructor yields an empty object
## Examples
Example
The following code shows an example for the `array` function.
> 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 [`max_size`](https://json.nlohmann.me/api/basic_json/max_size/index.md) function of a JSON array.
#### Storage
Arrays are stored as pointers in a `basic_json` type. That is, for any access to array values, a pointer of type `array_t*` must be dereferenced.
## Examples
Example
The following code shows that `array_t` is by default, a typedef to `std::vector<nlohmann::json>`.
1. Returns a reference to the array element at specified location `idx`, with bounds checking.
1. Returns a reference to the object element with specified key `key`, with bounds checking.
1. See 2. This overload is only available if `KeyType` is comparable with `typename object_t::key_type` and `typename object_comparator_t::is_transparent` denotes a type.
1. Returns a reference to the element at specified JSON pointer `ptr`, with bounds checking.
## Template parameters
`KeyType` : A type for an object key other than [`json_pointer`](https://json.nlohmann.me/api/json_pointer/index.md) that is comparable with [`string_t`](https://json.nlohmann.me/api/basic_json/string_t/index.md) using [`object_comparator_t`](https://json.nlohmann.me/api/basic_json/object_comparator_t/index.md). This can also be a string view (C++17).
## Parameters
`idx` (in) : index of the element to access
`key` (in) : object key of the elements to access
`ptr` (in) : JSON pointer to the desired element
## Return value
1. reference to the element at index `idx`
1. reference to the element at key `key`
1. reference to the element at key `key`
1. 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.304`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error304) if the JSON value is not an array; in this case, calling `at` with an index makes no sense. See the example below.
- Throws [`out_of_range.401`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range401) if the index `idx` is out of range of the array; that is, `idx >= size()`. See the example below.
1. The function can throw the following exceptions:
- Throws [`type_error.304`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error304) if the JSON value is not an object; in this case, calling `at` with a key makes no sense. See the example below.
- Throws [`out_of_range.403`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range403) if the key `key` is not stored in the object; that is, `find(key) == end()`. See the example below.
1. See 2.
1. The function can throw the following exceptions:
- Throws [`parse_error.106`](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error106) if an array index in the passed JSON pointer `ptr` begins with '0'. See the example below.
- Throws [`parse_error.109`](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error109) if an array index in the passed JSON pointer `ptr` is not a number. See the example below.
- Throws [`out_of_range.401`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range401) if an array index in the passed JSON pointer `ptr` is out of range. See the example below.
- Throws [`out_of_range.402`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range402) if the array index '-' is used in the passed JSON pointer `ptr`. As `at` provides checked access (and no elements are implicitly inserted), the index '-' is always invalid. See the example below.
- Throws [`out_of_range.403`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range403) if the JSON pointer describes a key of an object which cannot be found. See the example below.
- Throws [`out_of_range.404`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range404) if the JSON pointer `ptr` can not be resolved. See the example below.
- Throws [`out_of_range.410`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range410) if an array index in the passed JSON pointer `ptr` exceeds the range of `size_type` (e.g., on 32-bit platforms).
## Complexity
1. Constant.
1. Logarithmic in the size of the container.
1. Logarithmic in the size of the container.
1. Logarithmic in the size of the container.
## Examples
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.
```
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create JSON array
json array = {"first", "2nd", "third", "fourth"};
// output element at index 2 (third element)
std::cout << array.at(2) << '\n';
// change element at index 1 (second element) to "second"
array.at(1) = "second";
// output changed array
std::cout << array << '\n';
// exception type_error.304
try
{
// use at() on a non-array type
json str = "I am a string";
str.at(0) = "Another string";
}
catch (const json::type_error& e)
{
std::cout << e.what() << '\n';
}
// exception out_of_range.401
try
{
// try to write beyond the array limit
array.at(5) = "sixth";
}
catch (const json::out_of_range& e)
{
std::cout << e.what() << '\n';
}
}
```
Output:
```
"third"
["first","second","third","fourth"]
[json.exception.type_error.304] cannot use at() with string
[json.exception.out_of_range.401] array index 5 is out of range
```
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.
Returns a reference to the last element in the container. For a JSON container `c`, the expression `c.back()` is equivalent to
```
auto tmp = c.end();
--tmp;
return *tmp;
```
## Return value
In the case of a structured type (array or object), a reference to the last element is returned. In the 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 `null`, exception [`invalid_iterator.214`](https://json.nlohmann.me/home/exceptions/#jsonexceptioninvalid_iterator214) is thrown.
## Complexity
Constant.
## Notes
Precondition
The array or object must not be empty. Calling `back` on an empty array or object yields undefined behavior.
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 | `null` |
| boolean | `false` |
| string | `""` |
| number | `0` |
| object | `{}` |
| array | `[]` |
| binary | empty array |
The postcondition of this constructor can be restored by calling [`clear()`](https://json.nlohmann.me/api/basic_json/clear/index.md).
1. 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.
1. 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 `val` to that method (to `json_serializer<U>::to_json` method with `U = uncvref_t<CompatibleType>`, to be exact).
Template type `CompatibleType` includes, but is not limited to, the following types:
- **arrays**: [`array_t`](https://json.nlohmann.me/api/basic_json/array_t/index.md) 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 `basic_json` value can be constructed.
- **objects**: [`object_t`](https://json.nlohmann.me/api/basic_json/object_t/index.md) 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 `string_t` and a `value_type` from which a `basic_json` value can be constructed.
- **strings**: `string_t`, string literals, and all compatible string containers can be used.
- **numbers**: [`number_integer_t`](https://json.nlohmann.me/api/basic_json/number_integer_t/index.md), [`number_unsigned_t`](https://json.nlohmann.me/api/basic_json/number_unsigned_t/index.md), [`number_float_t`](https://json.nlohmann.me/api/basic_json/number_float_t/index.md), and all convertible number types such as `int`, `size_t`, `int64_t`, `float` or `double` can be used.
- **boolean**: `boolean_t` / `bool` can be used.
- **binary**: `binary_t` / `std::vector<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.
1. This is a constructor for existing `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 `m_value` of the parameter. Each member value (object, array, string, etc.) is serialized via the corresponding `to_json()` overload. For objects and strings, the conversion requires that the *target*`basic_json` type's `object_t::key_type` (or `string_t`) be directly constructible from the *source* type's corresponding member type via `is_constructible`. If this requirement is not met, the conversion does not fail to compile; instead, it silently falls back to the array-conversion path, which represents objects as arrays of `[key, value]` pairs and strings as arrays of character codes. This is a known limitation tracked in [issue #3425](https://github.com/nlohmann/json/issues/3425).
1. Creates a JSON value of type array or object from the passed initializer list `init`. In case `type_deduction` is `true` (default), the type of the JSON value to be created is deducted from the initializer list `init` according to the following rules:
1. If the list is empty, an empty JSON object value `{}` is created.
1. 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.
1. 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.
1. 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.
1. In all other cases, the initializer list could not be interpreted as a JSON object type, so interpreting it as a 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 `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()`](https://json.nlohmann.me/api/basic_json/array/index.md) and [`object()`](https://json.nlohmann.me/api/basic_json/object/index.md) force array and object creation from initializer lists, respectively.
Brace initialization yields arrays
Because this constructor takes an `initializer_list_t`, brace-initializing a `json`/`ordered_json` from another `json` value wraps it in a single-element array rather than copying it:
```
json j1 = "hello";
json j2{j1}; // [!] j2 is ["hello"], NOT a copy of j1
json j3(j1); // j3 is "hello" -- parentheses copy as expected
```
See the FAQ entry on [brace initialization](https://json.nlohmann.me/home/faq/#brace-initialization-yields-arrays) for the full explanation, an opt-in macro to change this behavior, and how to explicitly create a single-element array (`json::array({value})`) if that is what you want.
1. Constructs a JSON array value by creating `cnt` copies of a passed value. In case `cnt` is `0`, an empty array is created.
1. Constructs the JSON value with the contents of the range `[first, last)`. The semantics depend on the different types a JSON value can have:
- In case of a `null` type, [invalid_iterator.206](https://json.nlohmann.me/home/exceptions/#jsonexceptioninvalid_iterator206) is thrown.
- In case of other primitive types (number, boolean, or string), `first` must be `begin()` and `last` must be `end()`. In this case, the value is copied. Otherwise, [`invalid_iterator.204`](https://json.nlohmann.me/home/exceptions/#jsonexceptioninvalid_iterator204) 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.
1. Creates a copy of a given JSON value.
1. Move constructor. Constructs a JSON value with the contents of the given value `other` using move semantics. It "steals" the resources from `other` and leaves it as JSON `null` value.
## Template parameters
`CompatibleType` : a type such that:
```
- `CompatibleType` is not derived from `std::istream`,
- `CompatibleType` is not `basic_json` (to avoid hijacking copy/move constructors),
- `CompatibleType` is not a different `basic_json` type (i.e. with different template arguments)
- `CompatibleType` is not a `basic_json` nested type (e.g., `json_pointer`, `iterator`, etc.)
- `json_serializer<U>` (with `U = uncvref_t<CompatibleType>`) has a `to_json(basic_json_t&, CompatibleType&&)`
method
```
`BasicJsonType`: : a type such that:
```
- `BasicJsonType` is a `basic_json` type.
- `BasicJsonType` has different template arguments than `basic_json_t`.
**Note:** For cross-`basic_json` conversions to produce correct results, the target `basic_json`'s
`object_t::key_type` and `string_t` must be directly constructible from the source `basic_json`'s
corresponding types. See the description of overload (4) above for details on what happens when
this requirement is not met.
```
`U`: : `uncvref_t<CompatibleType>`
## Parameters
`v` (in) : the type of the value to create
`val` (in) : the value to be forwarded to the respective constructor
`init` (in) : initializer list with JSON values
`type_deduction` (in) : internal parameter; when set to `true`, the type of the JSON value is deducted from the initializer list `init`; when set to `false`, the type provided via `manual_type` is forced. This mode is used by the functions `array(initializer_list_t)` and `object(initializer_list_t)`.
`manual_type` (in) : internal parameter; when `type_deduction` is set to `false`, the created JSON value will use the provided type (only `value_t::array` and `value_t::object` are valid); when `type_deduction` is set to `true`, this parameter has no effect
`cnt` (in) : the number of JSON copies of `val` to create
`first` (in) : the beginning of the range to copy from (included)
`last` (in) : the end of the range to copy from (excluded)
`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.
1. No-throw guarantee: this constructor never throws exceptions.
1. Depends on the called constructor. For types directly supported by the library (i.e., all types for which no `to_json()` function was provided), a strong guarantee holds: if an exception is thrown, there are no changes to any JSON value.
1. Depends on the called constructor. For types directly supported by the library (i.e., all types for which no `to_json()` function was provided), a strong guarantee holds: if an exception is thrown, there are no changes to any JSON value.
1. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
1. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
1. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
1. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
1. No-throw guarantee: this constructor never throws exceptions.
## Exceptions
1. (none)
1. The function does not throw exceptions.
1. (none)
1. (none)
1. The function can throw the following exceptions:
- Throws [`type_error.301`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error301) if `type_deduction` is `false`, `manual_type` is `value_t::object`, but `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 `type_deduction` would have been `true`, an array would have been created. See `object(initializer_list_t)` for an example.
1. (none)
1. The function can throw the following exceptions:
- Throws [`invalid_iterator.201`](https://json.nlohmann.me/home/exceptions/#jsonexceptioninvalid_iterator201) if iterators `first` and `last` are not compatible (i.e., do not belong to the same JSON value). In this case, the range `[first, last)` is undefined.
- Throws [`invalid_iterator.204`](https://json.nlohmann.me/home/exceptions/#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 anymore. In this case, the range `[first, last)` is undefined. See the example code below.
- Throws [`invalid_iterator.206`](https://json.nlohmann.me/home/exceptions/#jsonexceptioninvalid_iterator206) if iterators `first` and `last` belong to a `null` value. In this case, the range `[first, last)` is undefined.
1. (none)
1. The function does not throw exceptions.
## Complexity
1. Constant.
1. Constant.
1. Usually linear in the size of the passed `val`, also depending on the implementation of the called `to_json()` method.
1. Usually linear in the size of the passed `val`, also depending on the implementation of the called `to_json()` method.
1. Linear in the size of the initializer list `init`.
1. Linear in `cnt`.
1. Linear in distance between `first` and `last`.
1. Linear in the size of `other`.
1. Constant.
## Notes
- Overload 5:
Empty initializer list
When used without parentheses around an empty initializer list, `basic_json()` is called instead of this function, yielding the JSON `null` value.
- Overload 7:
Preconditions
- Iterators `first` and `last` must be initialized. \*\*This precondition is enforced with a [runtime assertion](https://json.nlohmann.me/features/assertions/index.md).
- Range `[first, last)` is valid. Usually, this precondition cannot be checked efficiently. Only certain edge cases are detected; see the description of the exceptions above. A violation of this precondition yields undefined behavior.
Runtime assertion
A precondition is enforced with a [runtime assertion](https://json.nlohmann.me/features/assertions/index.md).
- Overload 8:
Postcondition
`*this == other`
- Overload 9:
Postconditions
- `` `*this `` has the same value as `other` before the call.
-`other` is a JSON `null` value
## Examples
Example: (1) create an empty value with a given type
The following code shows the constructor for different `value_t` values.
```
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create the different JSON values with default values
1. Creates a JSON binary array value from a given binary container.
1. Creates a JSON binary array value from a given binary container with subtype.
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.
## Parameters
`init` (in) : container containing bytes to use as a binary type
`subtype` (in) : subtype to use in CBOR, MessagePack, and BSON
## Return value
JSON binary array value
## Exception safety
Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
## Complexity
Linear in the size of `init`; constant for `typename binary_t::container_type&& init` versions.
## Notes
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.
## Examples
Example
The following code shows how to create a binary value.
using binary_t = byte_container_with_subtype<BinaryType>;
```
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::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). The subtype is added to `BinaryType` via the helper type [byte_container_with_subtype](https://json.nlohmann.me/api/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 (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 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:
> 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++.
## Template parameters
`BinaryType` : container type to store arrays
```
Although not formally expressed as a C++ concept, `BinaryType` must be default-constructible,
copy/move-constructible, and support `push_back()`, `.data()`, and `.size()`, because
[`byte_container_with_subtype`](https://json.nlohmann.me/api/byte_container_with_subtype/index.md) derives directly from it. Its
`value_type` must additionally be exactly one byte wide (e.g., `std::uint8_t`/`char`/`std::byte`): the binary
serializers (CBOR, MessagePack, BSON, UBJSON) read and write the container's raw bytes via
`reinterpret_cast`, which is only correct for byte-sized elements -- a container like
`std::vector<std::intptr_t>` will not work as `BinaryType`.
```
## Notes
#### Default type
The default values for `BinaryType` is `std::vector<std::uint8_t>`.
#### Custom BinaryType behavior
When a custom `BinaryType` is configured (other than the default `std::vector<std::uint8_t>`), you can assign values of that type directly to a `basic_json` instance, and they will automatically be recognized as binary values rather than arrays:
custom_json j = data; // Creates a binary value, not an array
assert(j.is_binary());
// Round-tripping works seamlessly
auto extracted = j.get<std::vector<std::byte>>();
assert(extracted == data);
```
This automatic type detection is a convenience feature that only applies to custom (non-default) `BinaryType` configurations. The default `nlohmann::json` continues to treat `std::vector<std::uint8_t>` as arrays for backward compatibility.
#### Storage
Binary Arrays are stored as pointers in a `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 written as tags.
- 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 a 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 an 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 `nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>`.
This enumeration is used in the [`from_cbor`](https://json.nlohmann.me/api/basic_json/from_cbor/index.md) function to choose how to treat tags:
error : throw a `parse_error` exception in case of a tag
ignore : ignore tags
store : store tagged values as binary container with subtype (for bytes 0xd8..0xdb)
## Examples
Example
The example below shows how the different values of the `cbor_tag_handler_t` influence the behavior of [`from_cbor`](https://json.nlohmann.me/api/basic_json/from_cbor/index.md) when reading a tagged byte string.
Clears the content of a JSON value and resets it to the default value as if [`basic_json(value_t)`](https://json.nlohmann.me/api/basic_json/basic_json/index.md) would have been called with the current value type from [`type()`](https://json.nlohmann.me/api/basic_json/type/index.md):
| Value type | initial value |
| ---------- | -------------------- |
| null | `null` |
| boolean | `false` |
| string | `""` |
| number | `0` |
| binary | An empty byte vector |
| object | `{}` |
| array | `[]` |
Has the same effect as calling
```
*this = basic_json(type());
```
## Exception safety
No-throw guarantee: this function never throws exceptions.
## Complexity
Linear in the size of the JSON value.
## Notes
All iterators, pointers, and references related to this container are invalidated.
## Examples
Example
The example below shows the effect of `clear()` to different JSON types.
```
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create JSON values
json j_null;
json j_boolean = true;
json j_number_integer = 17;
json j_number_float = 23.42;
json j_object = {{"one", 1}, {"two", 2}};
json j_array = {1, 2, 4, 8, 16};
json j_string = "Hello, world";
// call clear()
j_null.clear();
j_boolean.clear();
j_number_integer.clear();
j_number_float.clear();
j_object.clear();
j_array.clear();
j_string.clear();
// serialize the cleared values()
std::cout << j_null << '\n';
std::cout << j_boolean << '\n';
std::cout << j_number_integer << '\n';
std::cout << j_number_float << '\n';
std::cout << j_object << '\n';
std::cout << j_array << '\n';
std::cout << j_string << '\n';
}
```
Output:
```
null
false
0
0.0
{}
[]
""
```
## Version history
- Added in version 1.0.0.
- Added support for binary types in version 3.8.0.
1. Check whether an element exists in a JSON object with a key equivalent to `key`. If the element is not found or the JSON value is not an object, `false` is returned.
1. See 1. This overload is only available if `KeyType` is comparable with `typename object_t::key_type` and `typename object_comparator_t::is_transparent` denotes a type.
1. Check whether the given JSON pointer `ptr` can be resolved in the current JSON value.
## Template parameters
`KeyType` : A type for an object key other than [`json_pointer`](https://json.nlohmann.me/api/json_pointer/index.md) that is comparable with [`string_t`](https://json.nlohmann.me/api/basic_json/string_t/index.md) using [`object_comparator_t`](https://json.nlohmann.me/api/basic_json/object_comparator_t/index.md). This can also be a string view (C++17).
## Parameters
`key` (in) : key value to check its existence.
`ptr` (in) : JSON pointer to check its existence.
## Return value
1. `true` if an element with specified `key` exists. If no such element with such a key is found or the JSON value is not an object, `false` is returned.
1. See 1.
1. `true` if the JSON pointer can be resolved to a stored value, `false` otherwise.
## Exception safety
Strong exception safety: if an exception occurs, the original value stays intact.
## Exceptions
1. The function does not throw exceptions.
1. The function does not throw exceptions.
1. The function does not throw exceptions.
## Complexity
Logarithmic in the size of the JSON object.
## Notes
- This method always returns `false` when executed on a JSON type that is not an object.
- This method can be executed on any JSON value type.
Postconditions
If `j.contains(x)` returns `true` for a key or JSON pointer `x`, then it is safe to call `j[x]`.
1. Returns the number of elements with key `key`. If `ObjectType` is the default `std::map` type, the return value will always be `0` (`key` was not found) or `1` (`key` was found).
1. See 1. This overload is only available if `KeyType` is comparable with `typename object_t::key_type` and `typename object_comparator_t::is_transparent` denotes a type.
## Template parameters
`KeyType` : A type for an object key other than [`json_pointer`](https://json.nlohmann.me/api/json_pointer/index.md) that is comparable with [`string_t`](https://json.nlohmann.me/api/basic_json/string_t/index.md) using [`object_comparator_t`](https://json.nlohmann.me/api/basic_json/object_comparator_t/index.md). This can also be a string view (C++17).
## Parameters
`key` (in) : key value of the element to count.
## Return value
Number of elements with key `key`. If the JSON value is not an object, the return value will be `0`.
## Exception safety
Strong exception safety: if an exception occurs, the original value stays intact.
## Complexity
Logarithmic in the size of the JSON object.
## Notes
This method always returns `0` when executed on a JSON type that is not an object.
## Examples
Example: (1) count number of elements
The example shows how `count()` is used.
```
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create a JSON object
json j_object = {{"one", 1}, {"two", 2}};
// call count()
auto count_two = j_object.count("two");
auto count_three = j_object.count("three");
// print values
std::cout << "number of elements with key \"two\": " << count_two << '\n';
std::cout << "number of elements with key \"three\": " << count_three << '\n';
}
```
Output:
```
number of elements with key "two": 1
number of elements with key "three": 0
```
Example: (2) count number of elements using string_view
The example shows how `count()` is used.
```
#include <iostream>
#include <string_view>
#include <nlohmann/json.hpp>
using namespace std::string_view_literals;
using json = nlohmann::json;
int main()
{
// create a JSON object
json j_object = {{"one", 1}, {"two", 2}};
// call count()
auto count_two = j_object.count("two"sv);
auto count_three = j_object.count("three"sv);
// print values
std::cout << "number of elements with key \"two\": " << count_two << '\n';
std::cout << "number of elements with key \"three\": " << count_three << '\n';
}
```
Output:
```
number of elements with key "two": 1
number of elements with key "three": 0
```
## See also
- [find](https://json.nlohmann.me/api/basic_json/find/index.md) find a value in an object
- [contains](https://json.nlohmann.me/api/basic_json/contains/index.md) checks whether a key exists
## Version history
1. Added in version 3.11.0.
1. Added in version 1.0.0. Changed parameter `key` type to `KeyType&&` in version 3.11.0.
Returns an iterator to the reverse-end; that is, one before the first element. This element acts as a placeholder, attempting to access it results in undefined behavior.
## Return value
reverse iterator to the element following the last element
## Exception safety
No-throw guarantee: this member function never throws exceptions.
## Complexity
Constant.
## Examples
Example
The following code shows an example for `crend()`.
```
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create an array value
json array = {1, 2, 3, 4, 5};
// get an iterator to the reverse-end
json::const_reverse_iterator it = array.crend();
// increment the iterator to point to the first element
--it;
// serialize the element that the iterator points to
using default_object_comparator_t = std::less<StringType>; // until C++14
using default_object_comparator_t = std::less<>; // since C++14
```
The default comparator used by [`object_t`](https://json.nlohmann.me/api/basic_json/object_t/index.md).
Since C++14 a transparent comparator is used which prevents unnecessary string construction when looking up a key in an object.
The actual comparator used depends on [`object_t`](https://json.nlohmann.me/api/basic_json/object_t/index.md) and can be obtained via [`object_comparator_t`](https://json.nlohmann.me/api/basic_json/object_comparator_t/index.md).
## Examples
Example
The example below demonstrates the default comparator.
Creates a [JSON Patch](http://jsonpatch.com) so that value `source` can be changed into the value `target` by calling [`patch`](https://json.nlohmann.me/api/basic_json/patch/index.md) function.
For two JSON values `source` and `target`, the following code yields always `true`:
```
source.patch(diff(source, target)) == target;
```
## Parameters
`source` (in) : JSON value to compare from
`target` (in) : JSON value to compare against
## Return value
a JSON patch to convert the `source` to `target`
## Exception safety
Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
## Complexity
Linear in the lengths of `source` and `target`.
## Notes
Currently, only `remove`, `add`, and `replace` operations are generated.
## Examples
Example
The following code shows how a JSON patch is created as a diff for two JSON values.
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
`indent` (in) : 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.
`indent_char` (in) : The character to use for indentation if `indent` is greater than `0`. The default is (space).
`ensure_ascii` (in) : If `ensure_ascii` is true, all non-ASCII characters in the output are escaped with `\uXXXX` sequences, and the result consists of ASCII characters only.
`error_handler` (in) : how to react on decoding errors; there are three possible values (see [`error_handler_t`](https://json.nlohmann.me/api/basic_json/error_handler_t/index.md): `strict` (throws an 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 valid bytes are copied to the output unchanged, and invalid bytes are dropped)).
## 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`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error316) if a string stored inside the JSON value is not UTF-8 encoded and `error_handler` is set to `strict`
## Complexity
Linear.
## Notes
Binary values are serialized as an object containing two keys:
- "bytes": an array of bytes as integers
- "subtype": the subtype as integer or `null` if the binary has no subtype
## Examples
Example
The following example shows the effect of different `indent`, `indent_char`, and `ensure_ascii` parameters to the result of the serialization.
```
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create JSON values
json j_object = {{"one", 1}, {"two", 2}};
json j_array = {1, 2, 4, 8, 16};
json j_string = "Hellö 😀!";
// call dump()
std::cout << "objects:" << '\n'
<< j_object.dump() << "\n\n"
<< j_object.dump(-1) << "\n\n"
<< j_object.dump(0) << "\n\n"
<< j_object.dump(4) << "\n\n"
<< j_object.dump(1, '\t') << "\n\n";
std::cout << "arrays:" << '\n'
<< j_array.dump() << "\n\n"
<< j_array.dump(-1) << "\n\n"
<< j_array.dump(0) << "\n\n"
<< j_array.dump(4) << "\n\n"
<< j_array.dump(1, '\t') << "\n\n";
std::cout << "strings:" << '\n'
<< j_string.dump() << '\n'
<< j_string.dump(-1, ' ', true) << '\n';
// create JSON value with invalid UTF-8 byte sequence
json j_invalid = "ä\xA9ü";
try
{
std::cout << j_invalid.dump() << std::endl;
}
catch (const json::type_error& e)
{
std::cout << e.what() << std::endl;
}
std::cout << "string with replaced invalid characters: "
Inserts a new element into a JSON object constructed in-place with the given `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 `args`.
## Template parameters
`Args` : compatible types to create a `basic_json` object
## Iterator invalidation
For [`ordered_json`](https://json.nlohmann.me/api/ordered_json/index.md), adding a value to an object can yield a reallocation, in which case all iterators (including the `end()` iterator) and all references to the elements are invalidated.
## Parameters
`args` (in) : arguments to forward to a constructor of `basic_json`
## Return value
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.
## Exception safety
Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
## Exceptions
Throws [`type_error.311`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error311) 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()`)).
## Examples
Example
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.
```
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create JSON values
json object = {{"one", 1}, {"two", 2}};
json null;
// print values
std::cout << object << '\n';
std::cout << null << '\n';
// add values
auto res1 = object.emplace("three", 3);
null.emplace("A", "a");
null.emplace("B", "b");
// the following call will not add an object, because there is already
Creates a JSON value from the passed parameters `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 `args`.
## Template parameters
`Args` : compatible types to create a `basic_json` object
## Iterator invalidation
By adding an element to the end of the array, a reallocation can happen, in which case all iterators (including the [`end()`](https://json.nlohmann.me/api/basic_json/end/index.md) iterator) and all references to the elements are invalidated. Otherwise, only the [`end()`](https://json.nlohmann.me/api/basic_json/end/index.md) iterator is invalidated.
## Parameters
`args` (in) : arguments to forward to a constructor of `basic_json`
## Return value
reference to the inserted element
## Exceptions
Throws [`type_error.311`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error311) when called on a type other than JSON array or `null`; example: `"cannot use emplace_back() with number"`
## Complexity
Amortized constant.
## Examples
Example
The example shows how `emplace_back()` can be used to add elements to a JSON array. Note how the `null` value was silently converted to a JSON array.
```
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create JSON values
json array = {1, 2, 3, 4, 5};
json null;
// print values
std::cout << array << '\n';
std::cout << null << '\n';
// add values
array.emplace_back(6);
null.emplace_back("first");
null.emplace_back(3, "second");
// print values
std::cout << array << '\n';
std::cout << null << '\n';
}
```
Output:
```
[1,2,3,4,5]
null
[1,2,3,4,5,6]
["first",["second","second","second"]]
```
## See also
- [operator+=](https://json.nlohmann.me/api/basic_json/operator%2B%3D/index.md) add a value to an array/object
- [push_back](https://json.nlohmann.me/api/basic_json/push_back/index.md) add a value to an array/object
- [Modifying values](https://json.nlohmann.me/features/modifying_values/index.md) - the article on modifying values
| object | result of function `object_t::empty()` |
| array | result of function `array_t::empty()` |
## Exception safety
No-throw guarantee: this function never throws exceptions.
## Complexity
Constant, as long as [`array_t`](https://json.nlohmann.me/api/basic_json/array_t/index.md) and [`object_t`](https://json.nlohmann.me/api/basic_json/object_t/index.md) satisfy the [Container](https://en.cppreference.com/w/cpp/named_req/Container) concept; that is, their `empty()` functions have constant complexity.
## Possible implementation
```
bool empty() const noexcept
{
return size() == 0;
}
```
## Notes
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.
## Examples
Example
The following code uses `empty()` to check if a JSON object contains any elements.
```
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create JSON values
json j_null;
json j_boolean = true;
json j_number_integer = 17;
json j_number_float = 23.42;
json j_object = {{"one", 1}, {"two", 2}};
json j_object_empty(json::value_t::object);
json j_array = {1, 2, 4, 8, 16};
json j_array_empty(json::value_t::array);
json j_string = "Hello, world";
// call empty()
std::cout << std::boolalpha;
std::cout << j_null.empty() << '\n';
std::cout << j_boolean.empty() << '\n';
std::cout << j_number_integer.empty() << '\n';
std::cout << j_number_float.empty() << '\n';
std::cout << j_object.empty() << '\n';
std::cout << j_object_empty.empty() << '\n';
std::cout << j_array.empty() << '\n';
std::cout << j_array_empty.empty() << '\n';
std::cout << j_string.empty() << '\n';
}
```
Output:
```
true
false
false
false
false
true
false
true
false
```
## Version history
- Added in version 1.0.0.
- Extended to return `false` for binary types in version 3.8.0.
File diff suppressed because one or more lines are too long
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Niels Lohmann
Niels Lohmann
Antonio Borondo
Chuck Atkins
knilch
Théo DELRIEU
Henry Fredrick Schreiner
Chris Harris
Kostiantyn Ponomarenko
David Guthrie
Ben Berman
mandreyel
Hyeon Kim
Dennis Fischer
Tsz-Ho Yu
Michael Gmelin
Sonu Lohani
Julius Rakow
Danielc
Vitaliy
Guillaume Racicot
Matthias Möller
martin-mfg
Jan Schöppach
James Upjohn
Carlos O'Ryan
Axel Huebl
Kevin Tonon
Vitaliy Manushkin
Mike Bogdanov
Wilson
Paul Fultz II
Patrik Huber
Kaido
zerodefect
Vadim Evard
abolz
Théo DELRIEU
Tobias Hermann
Matthew K. Gumbel
Eren Okka
Jorrit Wronski
Itja
Jamie Seward
Sonu Lohani
Perry Kundert
Nate Vargas
gregmarr
traits
WebProdPP
Markus Werle
Kyle Thompson
DmitryKuk
Greg Hurrell
dan-42
Ilya Polishchuk
Nikita Ofitserov
Ryan Mulder
Oleg Endo
Chocobo1
Steffen Brem
HenryLee
郭荣飞
Jay Sistar
Lukas Barth
Vladimir Petrigo
Ted Lyngmo
Berkus Decker
Krzysztof Woś
Alexander “weej” Jones
Tushar Maheshwari
Mihai STAN
Jared Grubb
Théo DELRIEU
Jonathan Lee
Alex Astashyn
Andreas Smas
Bosswestfalen
Yixin Zhang
Jared Grubb
Denis Andrejew
Vasil Dimov
Christoph Jud
Stefan Codrescu
Thomas Braun
Muri Nicanor
dtoma
Mário Feroldi
Tom Needham
Robert Marki
Chris Kitching
Kevin Dixon
Lv Zheng
Raphael Isemann
Annihil
Jett LaRue
Michael Macnair
Trevor Welsby
Volker Diels-Grabsch
dariomt
Corbin Hughes
Dario Menendez
Daniel Frey
emvivre
Huu Nguyen
silverweed
Colin Hirsch
Alexandre Hamez
AQNOUCH Mohammed
Aaron Burghardt
易思龙
Florian Weber
Daniel Kopecek
Joshua C. Randall
Trevor Hickey
WanCW
Kirk Shoop
Raphael Isemann
Elliot Goodrich