mirror of
https://github.com/nlohmann/json.git
synced 2026-10-11 17:07:15 +00:00
Niels Lohmann
759dd2e1b1
Add json_document and json_view, a read-only, zero-copy index of a JSON text, as the first public slice of the zero-copy view (#5295). A parse produces a flat array of 16-byte nodes in document order, one per value and one per object key. Strings stay in the source text; escaped strings are decoded into an arena. Integers are converted while their digits are in the cache; floats keep only their digit layout and are converted on read. Containers store the size of their subtree, so a reader can step over one in constant time. A document makes a handful of allocations, however many values it has. The parser accepts exactly what json::parse accepts, with every combination of ignore_comments and ignore_trailing_commas, with and without a trailing NUL, and under JSON_STRICT_NUL_HANDLING. It is portable C++11 and does not depend on byte order. basic_json_document adds parse, parse_copy, accept, read (reuses a document's memory), root, is_discarded, source, owns_source, node_count, memory_usage, and shrink_to_fit. basic_json_view adds type, the is_* queries, operator bool, size, empty, materialize, and source_offset. A parse error throws the same exception basic_json::parse would throw for the same input, message and position included. detail::abi_config keeps JSON_STRICT_NUL_HANDLING and JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON readable after json.hpp undefines them, in the ABI namespace so they always match the basic_json in use. A NUL byte that ends a // comment is the end of the input, as in parse() since #5696. Signed-off-by: Niels Lohmann <mail@nlohmann.me>
57 lines
2.6 KiB
Markdown
57 lines
2.6 KiB
Markdown
# Integration
|
|
|
|
There are several ways to add this header-only library to a C++ project. The following flowchart summarizes how to
|
|
pick one:
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
A[Add the library to a C++ project] --> B{Already using CMake?}
|
|
B -- no --> C{Using pkg-config or plain Makefiles?}
|
|
C -- yes --> D[pkg-config]
|
|
C -- no --> E[Copy the single header]
|
|
B -- yes --> F{Library installed system-wide?}
|
|
F -- yes --> G["find_package()"]
|
|
F -- no --> H{Use a package manager?}
|
|
H -- yes --> I[Package manager]
|
|
H -- no --> J["add_subdirectory() or FetchContent"]
|
|
```
|
|
|
|
- **Copy the single header**, as described [below](#header-only) — no build-system integration required.
|
|
- **CMake**: use [`find_package()`](cmake.md#external) if the library is already installed,
|
|
[`add_subdirectory()`](cmake.md#embedded) to embed the source tree, or [`FetchContent`](cmake.md#fetchcontent) to
|
|
download it at configure time; see [CMake](cmake.md).
|
|
- **Package managers**: install the library with a package manager such as Homebrew, Conan, or vcpkg; see
|
|
[Package Managers](package_managers.md).
|
|
- **pkg-config**: if you use bare Makefiles instead of CMake, [pkg-config](pkg-config.md) can supply the include flags
|
|
for an already-installed library.
|
|
|
|
Once the library is integrated, see the [Migration Guide](migration_guide.md) for how to keep your code future-proof
|
|
across releases.
|
|
|
|
## Header only
|
|
|
|
[`json.hpp`](https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json.hpp) is the single required
|
|
file in `single_include/nlohmann` or [released here](https://github.com/nlohmann/json/releases). You need to add
|
|
|
|
```cpp
|
|
#include <nlohmann/json.hpp>
|
|
|
|
// for convenience
|
|
using json = nlohmann::json;
|
|
```
|
|
|
|
to the files you want to process JSON and set the necessary switches to enable C++11 (e.g., `-std=c++11` for GCC and
|
|
Clang).
|
|
|
|
You can further use file
|
|
[`single_include/nlohmann/json_fwd.hpp`](https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json_fwd.hpp)
|
|
for forward declarations (see [Compile times](compile_times.md)), and file
|
|
[`single_include/nlohmann/json_literals.hpp`](https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json_literals.hpp)
|
|
for the user-defined string literals if you define
|
|
[`JSON_NO_AUTOMATIC_UDLS`](../api/macros/json_no_automatic_udls.md).
|
|
|
|
For the read-only, non-owning [`basic_json_document`](../api/basic_json_document/index.md)/[`basic_json_view`](../api/basic_json_view/index.md)
|
|
types, additionally include
|
|
[`single_include/nlohmann/json_view.hpp`](https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json_view.hpp);
|
|
see [Zero-copy JSON views](../features/json_view.md).
|