mirror of
https://github.com/boostorg/json.git
synced 2026-01-19 04:12:14 +00:00
172 lines
7.2 KiB
Plaintext
172 lines
7.2 KiB
Plaintext
https://www.boost.org/doc/libs/release/libs/json/[image:https://raw.githubusercontent.com/CPPAlliance/json/master/doc/images/repo-logo-3.png[Boost.JSON]]
|
|
|
|
[width="100%",cols="12%,43%,45%",options="header",]
|
|
|===
|
|
|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]
|
|
|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]]
|
|
|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
|
|
|https://www.boost.org/doc/libs/master/libs/json/[image:https://img.shields.io/badge/docs-master-brightgreen.svg[Documentation]]
|
|
|https://www.boost.org/doc/libs/develop/libs/json/[image:https://img.shields.io/badge/docs-develop-brightgreen.svg[Documentation]]
|
|
|
|
|https://drone.io/[Drone]
|
|
|https://drone.cpp.al/boostorg/json[image:https://drone.cpp.al/api/badges/boostorg/json/status.svg?ref=refs/heads/master[Build
|
|
Status]]
|
|
|https://drone.cpp.al/boostorg/json[image:https://drone.cpp.al/api/badges/boostorg/json/status.svg?ref=refs/heads/develop[Build
|
|
Status]]
|
|
|
|
|Matrix
|
|
|http://www.boost.org/development/tests/master/developer/json.html[image:https://img.shields.io/badge/matrix-master-brightgreen.svg[Matrix]]
|
|
|http://www.boost.org/development/tests/develop/developer/json.html[image:https://img.shields.io/badge/matrix-develop-brightgreen.svg[Matrix]]
|
|
|
|
|Fuzzing |—
|
|
|https://github.com/boostorg/json/actions?query=workflow%3Afuzz+branch%3Adevelop[image:https://github.com/boostorg/json/workflows/fuzz/badge.svg?branch=develop[fuzz]]
|
|
|
|
|https://ci.appveyor.com/[Appveyor]
|
|
|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]]
|
|
|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]
|
|
|https://codecov.io/gh/boostorg/json/branch/master[image:https://codecov.io/gh/boostorg/json/branch/master/graph/badge.svg[codecov]]
|
|
|https://codecov.io/gh/boostorg/json/branch/develop[image:https://codecov.io/gh/boostorg/json/branch/develop/graph/badge.svg[codecov]]
|
|
|===
|
|
|
|
== Boost.JSON
|
|
|
|
=== Overview
|
|
|
|
Boost.JSON is a portable C++ 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, C++,
|
|
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 C++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
|
|
|
|
Visit https://boost.org/libs/json for complete documentation.
|
|
|
|
=== Requirements
|
|
|
|
* Requires only C++11
|
|
* Link to a built static or dynamic Boost library, or use header-only
|
|
(see below)
|
|
* Supports -fno-exceptions, detected automatically
|
|
|
|
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.
|
|
|
|
....
|
|
#include <boost/json/src.hpp>
|
|
....
|
|
|
|
MSVC users must also define the macro `BOOST_JSON_NO_LIB` to disable
|
|
auto-linking.
|
|
|
|
==== 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:
|
|
|
|
....
|
|
#define BOOST_JSON_STACK_BUFFER_SIZE 1024
|
|
#include <boost/json/src.hpp>
|
|
....
|
|
|
|
==== 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: 4.8, 4.9, 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.
|
|
|
|
==== Visual Studio Solution
|
|
|
|
....
|
|
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
|
|
....
|
|
|
|
=== 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
|
|
|
|
=== License
|
|
|
|
Distributed under the Boost Software License, Version 1.0. (See
|
|
accompanying file LICENSE_1_0.txt or copy at
|
|
https://www.boost.org/LICENSE_1_0.txt)
|