boost/json
2
0
Fork 0
mirror of https://github.com/boostorg/json.git synced 2026-01-19 04:12:14 +00:00
Code Issues Projects Releases Wiki Activity
Files
develop
json/README.adoc
Dmitry Arkhipov 3c80c097d2 documentation fixes
2025-07-03 16:02:00 +03:00

259 lines
9.9 KiB
Plaintext
Raw Permalink Blame History

ifdef::env-github[]
:tip-caption: :bulb:
:note-caption: :information_source:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
:source-highlighter: rouge
:source-language: c++
[link=https://www.boost.org/doc/libs/latest/libs/json]
image:https://raw.githubusercontent.com/CPPAlliance/json/master/doc/images/repo-logo-3.png[Boost.JSON]
[cols=3]
|===
|Branch
|https://github.com/boostorg/json/tree/master[`master`]
|https://github.com/boostorg/json/tree/develop[`develop`]
|https://azure.microsoft.com/en-us/services/devops/pipelines/[Azure]
a|
[link=https://vinniefalco.visualstudio.com/json/_build/latest?definitionId=5&branchName=master]
image::https://img.shields.io/azure-devops/build/vinniefalco/2571d415-8cc8-4120-a762-c03a8eda0659/8/master[Build Status]
a|
[link=https://vinniefalco.visualstudio.com/json/_build/latest?definitionId=8&branchName=develop]
image::https://img.shields.io/azure-devops/build/vinniefalco/2571d415-8cc8-4120-a762-c03a8eda0659/8/develop[Build Status]
|Docs
a|
[link=https://www.boost.org/doc/libs/master/libs/json/]
image::https://img.shields.io/badge/docs-master-brightgreen.svg[Documentation]
a|
[link=https://www.boost.org/doc/libs/develop/libs/json/]
image::https://img.shields.io/badge/docs-develop-brightgreen.svg[Documentation]
|https://drone.io/[Drone]
a|
[link=https://drone.cpp.al/boostorg/json]
image::https://drone.cpp.al/api/badges/boostorg/json/status.svg?ref=refs/heads/master[Build Status]
a|
[link=https://drone.cpp.al/boostorg/json]
image::https://drone.cpp.al/api/badges/boostorg/json/status.svg?ref=refs/heads/develop[Build Status]
|Matrix
a|
[link=http://www.boost.org/development/tests/master/developer/json.html]
image::https://img.shields.io/badge/matrix-master-brightgreen.svg[Matrix]
a|
[link=https://img.shields.io/badge/matrix-develop-brightgreen.svg]
image::https://img.shields.io/badge/matrix-develop-brightgreen.svg[Matrix]
|Fuzzing
| ---
a|
[link=https://github.com/boostorg/json/workflows/fuzz/badge.svg?branch=develop]
image::https://github.com/boostorg/json/workflows/fuzz/badge.svg?branch=develop[fuzz]
|https://ci.appveyor.com/[Appveyor]
a|
[link=https://ci.appveyor.com/project/vinniefalco/cppalliance-json/branch/master]
image::https://ci.appveyor.com/api/projects/status/8csswcnmfm798203?branch=master&svg=true[Build status]
a|
[link=https://ci.appveyor.com/project/vinniefalco/cppalliance-json/branch/develop]
image::https://ci.appveyor.com/api/projects/status/8csswcnmfm798203?branch=develop&svg=true[Build status]
|https://codecov.io[codecov.io]
a|
[link=https://codecov.io/gh/boostorg/json/branch/master]
image::https://codecov.io/gh/boostorg/json/branch/master/graph/badge.svg[codecov]
a|
[link=https://codecov.io/gh/boostorg/json/branch/develop]
image::https://codecov.io/gh/boostorg/json/branch/develop/graph/badge.svg[codecov]
|===
= Boost.JSON
endif::[]
[pagelevels=0,toclevels=0]
== Overview
Boost.JSON is a portable {cpp} library which provides containers and algorithms
that implement https://json.org/[JavaScript Object Notation], or simply "JSON",
a lightweight data-interchange format. This format is easy for humans to read
and write, and easy for machines to parse and generate. It is based on a subset
of the JavaScript Programming Language
(https://www.ecma-international.org/ecma-262/10.0/index.html[Standard
ECMA-262]), and is currently standardised in
(https://datatracker.ietf.org/doc/html/rfc8259[RFC 8259]). JSON is a text
format that is language-independent but uses conventions that are familiar to
programmers of the C-family of languages, including C, {cpp}, C#, Java,
JavaScript, Perl, Python, and many others. These properties make JSON an ideal
data-interchange language.
This library focuses on a common and popular use-case: parsing and serializing
to and from a container called `value` which holds JSON types. Any `value`
which you build can be serialized and then deserialized, guaranteeing that the
result will be equal to the original value. Whatever JSON output you produce
with this library will be readable by most common JSON implementations in any
language.
The `value` container is designed to be well suited as a vocabulary type
appropriate for use in public interfaces and libraries, allowing them to be
composed. The library restricts the representable data types to the ranges
which are almost universally accepted by most JSON implementations, especially
JavaScript. The parser and serializer are both highly performant, meeting or
exceeding the benchmark performance of the best comparable libraries.
Allocators are very well supported. Code which uses these types will be easy to
understand, flexible, and performant.
Boost.JSON offers these features:
* Fast compilation
* Require only {cpp}11
* Fast streaming parser and serializer
* Constant-time key lookup for objects
* Options to allow non-standard JSON
* Easy and safe modern API with allocator support
* Optional header-only, without linking to a library
ifdef::env-github[]
Visit https://boost.org/libs/json for complete documentation.
endif::[]
=== Requirements
* Requires only {cpp}11
* Link to a built static or dynamic Boost library (build instructions can be
found https://www.boost.org/doc/libs/latest/more/getting_started/index.html[here]),
or use header-only (see below)
* Additional link to Boost.Container may be required
(as described in its
https://www.boost.org/doc/libs/latest/doc/html/container.html#container.intro.introduction_building_container[documentation])
* Supports `-fno-exceptions`, detected automatically (but read
<<Disabling Exceptions,the relevant section>> on this page).
The library relies heavily on these well known C++ types in
its interfaces (henceforth termed _standard types_):
* `string_view`
* `memory_resource`, `polymorphic_allocator`
* `error_category`, `error_code`, `error_condition`, `system_error`
==== Header-Only
To use as header-only; that is, to eliminate the requirement to link a program
to a static or dynamic Boost.JSON library, simply place the following line in
exactly one new or existing source file in your project.
[source]
----
#include <boost/json/src.hpp>
----
MSVC users must also define the macro `BOOST_JSON_NO_LIB` to disable
auto-linking. Note, that if you also want to avoid linking to Boost.Container,
which is a dependency of Boost.JSON, you have to define
`BOOST_CONTAINER_NO_LIB`. In order to disable auto-linking to Boost libraries
completely you can define `BOOST_ALL_NO_LIB` instead.
==== Disabling Exceptions
In order to support building with exceptions disabled this library uses another
Boost library,
https://www.boost.org/doc/libs/latest/libs/throw_exception[Boost.ThrowException].
This allows to automatically discover whether exception support is available.
On the other hand, as explained in Boost.ThrowException's documentation, if
exceptions are disabled, the users need to provide their own implementation for
`boost::throw_exception`, in order to link their binaries successfully. Here's
a very simple example of such implementation:
[source]
----
void throw_exception( const std::exception&, const boost::source_location& )
{
std::printf("Exceptions are not supported!");
std::abort();
}
----
==== Embedded
Boost.JSON works great on embedded devices. The library uses local stack
buffers to increase the performance of some operations. On Intel platforms
these buffers are large (4KB), while on non-Intel platforms they are small (256
bytes). To adjust the size of the stack buffers for embedded applications
define this macro when building the library or including the function
definitions:
[source]
----
#define BOOST_JSON_STACK_BUFFER_SIZE 1024
#include <boost/json/src.hpp>
----
==== Endianness
Boost.JSON uses
https://www.boost.org/doc/libs/latest/libs/endian/doc/html/endian.html[Boost.Endian]
in order to support both little endian and big endian platforms.
==== Supported Compilers
Boost.JSON has been tested with the following compilers:
* clang: 3.5, 3.6, 3.7, 3.8, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14
* gcc: 5, 6, 7, 8, 9, 10, 11, 12
* msvc: 14.0, 14.1, 14.2, 14.3
==== Supported JSON Text
The library expects input text to be encoded using UTF-8, which is
a requirement put on all JSON exchanged between systems by the
(https://datatracker.ietf.org/doc/html/rfc8259#section-8.1[RFC]). Similarly,
the text generated by the library is valid UTF-8.
The RFC does not allow byte order marks (BOM) to appear in JSON text, so the
library considers BOM syntax errors.
The library supports several popular JSON extensions. These have to be
explicitly enabled.
ifdef::env-github[]
==== Visual Studio Solution
[source,shell]
----
cmake -G "Visual Studio 16 2019" -A Win32 -B bin -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/msvc.cmake
cmake -G "Visual Studio 16 2019" -A x64 -B bin64 -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/msvc.cmake
----
endif::[]
=== Quality Assurance
The development infrastructure for the library includes these per-commit
analyses:
* Coverage reports
* Benchmark performance comparisons
* Compilation and tests on Drone.io, Azure Pipelines, Appveyor
* Fuzzing using clang-llvm and machine learning
==== Security Review (Bishop Fox)
As part of our commitment to producing the very finest C++ libraries that
application developers can trust, the C++ Alliance has commissioned Bishop Fox
to perform a security audit of the Boost.JSON library. The report is linked
here: +
https://cppalliance.org/pdf/C%20Plus%20Plus%20Alliance%20-%20Boost%20JSON%20Security%20Assessment%202020%20-%20Assessment%20Report%20-%2020210317.pdf[C Plus Plus Alliance - Boost JSON Security Assessment 2020 - Assessment Report - 20210317]
=== Credits
This library wouldn't be where it is today without the help of
https://github.com/pdimov[Peter Dimov] for design advice and optimization
assistance.
ifdef::env-github[]
== License
Distributed under the Boost Software License, Version 1.0. (See accompanying
file link:LICENSE_1_0.txt[LICENSE_1_0.txt] or copy at
https://www.boost.org/LICENSE_1_0.txt).
endif::[]
Reference in New Issue View Git Blame Copy Permalink