Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
63 commits
Select commit Hold shift + click to select a range
3fff4d6
Added translation using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
4af1195
Added translation using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
218e7b8
Added translation using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
eccac9f
Added translation using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
ab59886
Added translation using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
f865695
Added translation using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
0de71f3
Added translation using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
9775078
Added translation using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
8ab06ac
Added translation using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
230d960
Added translation using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
e8b7242
Added translation using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
a62e213
Added translation using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
f9c5de6
Added translation using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
dfa27d7
Added translation using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
b4f777f
Added translation using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
988eb56
Added translation using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
f8056bb
Added translation using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
949de14
Added translation using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
c8440e1
Added translation using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
2ed49f2
Added translation using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
fae6c5d
Added translation using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
0b06ea8
Added translation using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
2763404
Added translation using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
fa2449c
Added translation using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
27acdfc
Added translation using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
69b5bc6
Added translation using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
b912f37
Added translation using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
9d9df7e
Added translation using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
913a245
Added translation using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
61ed4cd
Added translation using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
f6151f1
Added translation using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
cbc8cf7
Added translation using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
af14da9
Update translation files
weblate Jun 5, 2026
7f3fb6b
Translated using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
6747afe
Translated using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
e5505ed
Translated using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
a0ae9da
Translated using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
4c34c46
Translated using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
ca6eb62
Translated using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
76b8c77
Translated using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
0e46fa8
Translated using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
53f2dde
Translated using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
7708ae9
Translated using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
a46585a
Translated using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
0420e16
Translated using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
2e2b5e2
Translated using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
cd55af5
Translated using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
07e8169
Translated using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
11e8254
Translated using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
6ed355e
Translated using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
766ec97
Translated using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
766ac76
Translated using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
a6d0497
Translated using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
f47bded
Translated using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
a4b4e4c
Translated using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
1def652
Translated using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
6f11781
Translated using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
3b316e8
Translated using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
e3e857c
Translated using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
49dd98e
Translated using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
451c647
Translated using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
b278f6a
Translated using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
902d7cb
Translated using Weblate (Chinese (Simplified Han script))
will-cppa Jun 5, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
123 changes: 123 additions & 0 deletions doc/library-detail_zh_Hans.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,123 @@
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
状态]] |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
状态]] |https://drone.cpp.al/boostorg/json[image:https://drone.cpp.al/api/badges/boostorg/json/status.svg?ref=refs/heads/develop[构建状态]]

|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
状态]] |https://ci.appveyor.com/project/vinniefalco/cppalliance-json/branch/develop[image:https://ci.appveyor.com/api/projects/status/8csswcnmfm798203?branch=develop&svg=true[构建状态]]

|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

=== 概述

Boost.JSON 是一个可移植的 C++ 库,提供了实现 [JavaScript Object Notation](https://json.org/)(简称 “JSON”)的容器和算法,这是一种轻量级的数据交换格式。该格式易于人类读写,也易于机器解析和生成。该格式基于 JavaScript 编程语言的一个子集([ECMA-262 标准](https://www.ecma-international.org/ecma-262/10.0/index.html)),目前已在 [RFC 8259](https://datatracker.ietf.org/doc/html/rfc8259) 中标准化。JSON 是一种独立于语言但使用 C 语言家族(包括 C、C++、C#、Java、JavaScript、Perl、Python 等)程序员熟悉的约定的文本格式。这些特性使 JSON 成为理想的数据交换语言。

该库专注于一个常见且广泛使用的场景:解析和序列化到一个名为 `value` 的容器,或从中进行解析和序列化(该容器用于存储 JSON 类型)。任何构建的 `value` 都可以被序列化后再反序列化,并保证结果与原始值相等。使用该库生成的任何 JSON 输出,均可被大多数主流编程语言中的常见 JSON 实现正确读取。

`value` 容器被设计为一种适合作为公共接口和库中词汇类型的组件,便于组合使用。该库将可表示的数据类型限制在绝大多数 JSON 实现(尤其是 JavaScript)普遍接受的范围内。解析器和序列化器均具备高性能,其基准性能达到或超过了同类优秀库的水平。对分配器的支持非常完善。使用这些类型的代码将易于理解、灵活且高效。

Boost.JSON 提供以下特性:

* 快速编译
* 仅需 C++11
* 高性能流式解析器和序列化器
* 对象的常量时间键查找
* 允许非标准 JSON 的选项
* 提供易于使用且安全的现代 API,并支持分配器
* 可选的纯头文件方式,无需链接库

若要获取完整文档请访问以下链接: https://boost.org/libs/json

=== 要求

* 仅需 C++11
* 可链接预构建的静态或动态 Boost 库,也可使用纯头文件方式
(见下文)
* Supports -fno-exceptions(可自动检测)

该库在其接口中大量依赖以下众所周知的 C++ 类型(以下称为 _standard types_):

* `string_view`
* `memory_resource`, `polymorphic_allocator`
* `error_category`, `error_code`, `error_condition`, `system_error`

==== 纯头文件

要使用纯头文件模式(即无需将程序链接到静态或动态的 Boost.JSON 库),只需在项目中恰好一个新建或现有源文件中添加以下行。

....
#include <boost/json/src.hpp>
....

MSVC 用户还必须定义宏 `BOOST_JSON_NO_LIB` ,以禁用自动链接。

==== 嵌入式

Boost.JSON 在嵌入式设备上表现优异。该库使用局部栈缓冲区来提升某些操作的性能。在 Intel 平台上,这些缓冲区较大(4KB),而在非 Intel 平台上则较小(256 字节)。若要在嵌入式应用中调整栈缓冲区的大小,请在构建库或包含函数定义时定义以下宏:

....
#define BOOST_JSON_STACK_BUFFER_SIZE 1024
#include <boost/json/src.hpp>
....

==== 支持的编译器

Boost.JSON 已在以下编译器上进行过测试:

* 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

==== 支持的 JSON 文本

该库要求输入文本使用 UTF-8 编码,这是 [RFC](https://datatracker.ietf.org/doc/html/rfc8259#section-8.1) 对系统间交换的所有 JSON 所规定的强制要求。同样,该库生成的文本也是有效的 UTF-8。

RFC 不允许字节顺序标记(BOM)出现在 JSON 文本中,因此该库将 BOM 视为语法错误。

该库支持多种流行的 JSON 扩展,但这些扩展必须显式启用。

==== Visual Studio 解决方案

....
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
....

=== 质量保证

该库的开发基础设施包括以下每次提交的分析:

* 覆盖率报告
* 基准性能比较
* 在 Drone.io、Azure Pipelines 和 AppVeyor 上进行编译与测试
* 使用 clang-llvm 和机器学习的模糊测试

=== 许可证

根据 Boost 软件许可协议 1.0 版分发。(详见随附文件 LICENSE_1_0.txt 文件或访问 https://www.boost.org/LICENSE_1_0.txt )
89 changes: 89 additions & 0 deletions doc/pages/allocators/background_zh_Hans.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
////
Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com)
Copyright (c) 2025 Dmitry Arkhipov (grisumbras@yandex.ru)

Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

Official repository: https://github.com/boostorg/json
////

= 背景 C++中分配器的第一个版本定义了名为{req_Allocator}的要求,并将每个标准容器设计为以分配器类型为模板参数的类模板。例如,以下是 {std_vector} 的声明:

[source]
----
include::../../../test/doc_background.cpp[tag=doc_background_1,indent=0]
----

标准分配器是{req_DefaultConstructible}。为支持有状态分配器,容器提供了额外的构造函数重载,接受一个分配器实例参数。

[source]
----
include::../../../test/doc_background.cpp[tag=doc_background_2,indent=0]
----

尽管该机制能够正常工作,但仍存在一些可用性问题:

* 容器必须是一个类模板。
* 在元素类型上参数化分配器的方式显得笨拙。
* 分配器特征机制,尤其是 POCCA 和 POCMA,
是复杂且容易出错的。

使用多种分配器类型的基于分配器的程序会引发更多的函数模板实例化,且通常编译速度更慢,因为类模板的函数定义必须在所有调用点可见。

== 多态分配器

{cpp}17通过引入一个名为 {ref_memory_resource} 的抽象接口来表示底层分配操作,从而改进分配器模型。该接口未在元素类型上参数化,且无特征:

[source]
----
include::../../../test/doc_background.cpp[tag=doc_background_3,indent=0]
----

类模板{ref_polymorphic_allocator}包装了{ref_memory_resource}指针,并满足{req_Allocator}要求,使其可在需要分配器的地方使用。标准库为使用多态分配器的标准容器提供了类型别名:

[source]
----
include::../../../test/doc_background.cpp[tag=doc_background_4,indent=0]
----

多态分配器通过一个指向内存资源的指针进行构造:

[source]
----
include::../../../test/doc_background.cpp[tag=doc_background_5,indent=0]
----

内存资源通过指针传递;所有权不发生转移。调用方需负责确保该内存资源的生命周期持续到所有使用它的容器都离开作用域为止,否则行为未定义。在某些场景下,这种模型是合适的,例如以下示例中使用了一个基于局部栈缓冲区构造的单调内存资源:

[source]
----
include::../../../test/doc_background.cpp[tag=doc_background_6,indent=0]
----

然而,有时需要共享所有权,即内存资源的生命周期应自动延长。例如,若某个库希望返回一个容器,该容器拥有该库自定义内存资源的实例,如下所示:

[source]
----
include::../../../test/doc_background.cpp[tag=doc_background_7,indent=0]
----

可通过声明容器使用自定义分配器(可能使用`std::shared_ptr&lt; std::pmr::memory_resource &gt;`作为数据成员)来解决此问题。这会阻碍库的组合;每个库都会导出各自独特且互不兼容的容器类型。原始内存资源指针也容易被误用:

[source]
----
include::../../../test/doc_background.cpp[tag=doc_background_8,indent=0]
----

针对此问题的变通方案往往比问题本身更糟糕。该库可以返回一个包含 vector 和`std::unique_ptr<std::pmr::memory_resource>`的pair,必须由调用方自行管理。或者,该库也可以修改其函数签名,接受调用方提供的{ref_memory_resource}``*``,同时将所需的内存资源(如上文的`my_resource`)公开。</std::pmr::memory_resource>

== 问题陈述

我们希望采用一种使用单一类型`T`的分配器模型,该模型具有以下特性:

* `T`不是类模板
* `T`引用一个 {ref_memory_resource}
* `T`同时支持引用语义和共享所有权
* `T`能与已使用`std::pmr`的代码互操作

Boost.JSON通过引入一个名为&lt;<ref_storage_ptr>&gt; 的新型智能指针解决此问题,该指针基于{cpp}17的内存分配接口构建,实现了上述目标。因此,使用该类型的库更易于组合,并能获得更快的编译速度,因为使用该类型的容器的成员函数可以定义在类外(out-of-line)。</ref_storage_ptr>
20 changes: 20 additions & 0 deletions doc/pages/allocators/overview_zh_Hans.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
////
Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com)
Copyright (c) 2020 Krystian Stasiowski (sdkrystian@gmail.com)
Copyright (c) 2025 Dmitry Arkhipov (grisumbras@yandex.ru)

Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

Official repository: https://github.com/boostorg/json
////

= 分配器

本文将首先讨论C++标准中使用的各种分配器模型,随后介绍本库所采用的模型及其优势,最后说明该库如何与使用多态分配器的现有代码进行互操作。

:leveloffset: +1

include::background.adoc[] include::storage_ptr.adoc[] include::uses_allocator.adoc[]

:leveloffset: -1
Loading