README.md
1[](http://master.json.cpp.al/)
2
3Branch | [`master`](https://github.com/CPPAlliance/json/tree/master) | [`develop`](https://github.com/CPPAlliance/json/tree/develop) |
4--------------- | ----------------------------------------------------------- | ------------------------------------------------------------- |
5[Azure](https://azure.microsoft.com/en-us/services/devops/pipelines/) | [](https://vinniefalco.visualstudio.com/json/_build/latest?definitionId=5&branchName=master) | [](https://vinniefalco.visualstudio.com/json/_build/latest?definitionId=8&branchName=develop)
6Docs | [](https://www.boost.org/doc/libs/master/libs/json/) | [](https://www.boost.org/doc/libs/develop/libs/json/)
7[Drone](https://drone.io/) | [](https://drone.cpp.al/boostorg/json) | [](https://drone.cpp.al/boostorg/json)
8Matrix | [](http://www.boost.org/development/tests/master/developer/json.html) | [](http://www.boost.org/development/tests/develop/developer/json.html)
9Fuzzing | --- | [](https://github.com/boostorg/json/actions?query=workflow%3Afuzz+branch%3Adevelop)
10[Appveyor](https://ci.appveyor.com/) | [](https://ci.appveyor.com/project/vinniefalco/cppalliance-json/branch/master) | [](https://ci.appveyor.com/project/vinniefalco/cppalliance-json/branch/develop)
11[codecov.io](https://codecov.io) | [](https://codecov.io/gh/boostorg/json/branch/master) | [](https://codecov.io/gh/boostorg/json/branch/develop)
12
13# Boost.JSON
14
15## Overview
16
17Boost.JSON is a portable C++ library which provides containers and
18algorithms that implement
19[JavaScript Object Notation](https://json.org/), or simply "JSON",
20a lightweight data-interchange format. This format is easy for humans to
21read and write, and easy for machines to parse and generate. It is based
22on a subset of the JavaScript Programming Language
23([Standard ECMA-262](https://www.ecma-international.org/ecma-262/10.0/index.html)).
24JSON is a text format that is language-independent but uses conventions
25that are familiar to programmers of the C-family of languages, including
26C, C++, C#, Java, JavaScript, Perl, Python, and many others. These
27properties make JSON an ideal data-interchange language.
28
29This library focuses on a common and popular use-case: parsing
30and serializing to and from a container called `value` which
31holds JSON types. Any `value` which you build can be serialized
32and then deserialized, guaranteeing that the result will be equal
33to the original value. Whatever JSON output you produce with this
34library will be readable by most common JSON implementations
35in any language.
36
37The `value` container is designed to be well suited as a
38vocabulary type appropriate for use in public interfaces and
39libraries, allowing them to be composed. The library restricts
40the representable data types to the ranges which are almost
41universally accepted by most JSON implementations, especially
42JavaScript. The parser and serializer are both highly performant,
43meeting or exceeding the benchmark performance of the best comparable
44libraries. Allocators are very well supported. Code which uses these
45types will be easy to understand, flexible, and performant.
46
47Boost.JSON offers these features:
48
49* Fast compilation
50* Require only C++11
51* Fast streaming parser and serializer
52* Constant-time key lookup for objects
53* Options to allow non-standard JSON
54* Easy and safe modern API with allocator support
55* Compile without Boost, define `BOOST_JSON_STANDALONE`
56* Optional header-only, without linking to a library
57
58## Requirements
59
60The library relies heavily on these well known C++ types in
61its interfaces (henceforth termed _standard types_):
62
63* `string_view`
64* `memory_resource`, `polymorphic_allocator`
65* `error_category`, `error_code`, `error_condition`, `system_error`
66
67The requirements for Boost.JSON depend on whether the library is used
68as part of Boost, or in the standalone flavor (without Boost):
69
70### Using Boost
71
72* Requires only C++11
73* The default configuration
74* Aliases for standard types use their Boost equivalents
75* Link to a built static or dynamic Boost library, or use header-only (see below)
76* Supports -fno-exceptions, detected automatically
77
78### Without Boost
79
80* Requires C++17
81* Aliases for standard types use their `std` equivalents
82* Obtained when defining the macro `BOOST_JSON_STANDALONE`
83* Link to a built static or dynamic standalone library, or use header-only (see below)
84* Supports -fno-exceptions: define `BOOST_NO_EXCEPTIONS` and `boost::throw_exception` manually
85
86When using without Boost, support for `<memory_resource>` is required.
87In particular, if using libstdc++ then version 8.3 or later is needed.
88
89### Header-Only
90
91To use as header-only; that is, to eliminate the requirement to
92link a program to a static or dynamic Boost.JSON library, simply
93place the following line in exactly one new or existing source
94file in your project.
95```
96#include <boost/json/src.hpp>
97```
98
99### Standalone Shared Library
100
101To build a standalone shared library, it is necessary to define the
102macros `BOOST_JSON_DECL` and `BOOST_JSON_CLASS_DECL` as appropriate
103for your toolchain. Example for MSVC:
104```
105// When building the DLL
106#define BOOST_JSON_DECL __declspec(dllexport)
107#define BOOST_JSON_CLASS_DECL __declspec(dllexport)
108
109// When building the application which uses the DLL
110#define BOOST_JSON_DECL __declspec(dllimport)
111#define BOOST_JSON_CLASS_DECL __declspec(dllimport)
112```
113
114### Embedded
115
116Boost.JSON works great on embedded devices. The library uses local
117stack buffers to increase the performance of some operations. On
118Intel platforms these buffers are large (4KB), while on non-Intel
119platforms they are small (256 bytes). To adjust the size of the
120stack buffers for embedded applications define this macro when
121building the library or including the function definitions:
122```
123#define BOOST_JSON_STACK_BUFFER_SIZE 1024
124#include <boost/json/src.hpp>
125```
126
127#### Note
128 This library uses separate inline namespacing for the standalone
129 mode to allow libraries which use different modes to compose
130 without causing link errors. Linking to both modes of Boost.JSON
131 (Boost and standalone) is possible, but not recommended.
132
133### Supported Compilers
134
135Boost.JSON has been tested with the following compilers:
136
137* clang: 3.8, 4, 5, 6, 7, 8, 9, 10, 11
138* gcc: 4.8, 4.9, 5, 6, 7, 8, 9, 10
139* msvc: 14.0, 14.1, 14.2
140
141### Quality Assurance
142
143The development infrastructure for the library includes
144these per-commit analyses:
145
146* Coverage reports
147* Benchmark performance comparisons
148* Compilation and tests on Drone.io, Azure Pipelines, Appveyor
149* Fuzzing using clang-llvm and machine learning
150
151## Visual Studio Solution
152
153 cmake -G "Visual Studio 16 2019" -A Win32 -B bin -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/msvc.cmake
154 cmake -G "Visual Studio 16 2019" -A x64 -B bin64 -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/msvc.cmake
155
156## License
157
158Distributed under the Boost Software License, Version 1.0.
159(See accompanying file [LICENSE_1_0.txt](LICENSE_1_0.txt) or copy at
160https://www.boost.org/LICENSE_1_0.txt)
161
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}