1[![Boost.JSON](https://raw.githubusercontent.com/CPPAlliance/json/master/doc/images/repo-logo-3.png)](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/) | [![Build Status](https://img.shields.io/azure-devops/build/vinniefalco/2571d415-8cc8-4120-a762-c03a8eda0659/8/master)](https://vinniefalco.visualstudio.com/json/_build/latest?definitionId=5&branchName=master) | [![Build Status](https://img.shields.io/azure-devops/build/vinniefalco/2571d415-8cc8-4120-a762-c03a8eda0659/8/develop)](https://vinniefalco.visualstudio.com/json/_build/latest?definitionId=8&branchName=develop) 6Docs | [![Documentation](https://img.shields.io/badge/docs-master-brightgreen.svg)](https://www.boost.org/doc/libs/master/libs/json/) | [![Documentation](https://img.shields.io/badge/docs-develop-brightgreen.svg)](https://www.boost.org/doc/libs/develop/libs/json/) 7[Drone](https://drone.io/) | [![Build Status](https://drone.cpp.al/api/badges/boostorg/json/status.svg)](https://drone.cpp.al/boostorg/json) | [![Build Status](https://drone.cpp.al/api/badges/boostorg/json/status.svg?ref=refs/heads/develop)](https://drone.cpp.al/boostorg/json) 8Matrix | [![Matrix](https://img.shields.io/badge/matrix-master-brightgreen.svg)](http://www.boost.org/development/tests/master/developer/json.html) | [![Matrix](https://img.shields.io/badge/matrix-develop-brightgreen.svg)](http://www.boost.org/development/tests/develop/developer/json.html) 9Fuzzing | --- | [![fuzz](https://github.com/boostorg/json/workflows/fuzz/badge.svg?branch=develop)](https://github.com/boostorg/json/actions?query=workflow%3Afuzz+branch%3Adevelop) 10[Appveyor](https://ci.appveyor.com/) | [![Build status](https://ci.appveyor.com/api/projects/status/8csswcnmfm798203?branch=master&svg=true)](https://ci.appveyor.com/project/vinniefalco/cppalliance-json/branch/master) | [![Build status](https://ci.appveyor.com/api/projects/status/8csswcnmfm798203?branch=develop&svg=true)](https://ci.appveyor.com/project/vinniefalco/cppalliance-json/branch/develop) 11[codecov.io](https://codecov.io) | [![codecov](https://codecov.io/gh/boostorg/json/branch/master/graph/badge.svg)](https://codecov.io/gh/boostorg/json/branch/master) | [![codecov](https://codecov.io/gh/boostorg/json/branch/develop/graph/badge.svg)](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