diff --git a/doc/library-detail_zh_Hans.adoc b/doc/library-detail_zh_Hans.adoc index af49c97..7b4284e 100644 --- a/doc/library-detail_zh_Hans.adoc +++ b/doc/library-detail_zh_Hans.adoc @@ -1,31 +1,31 @@ -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]] +https://www.boost.org/doc/libs/release/libs/json/[image:https://raw.githubusercontent.com/CPPAlliance/json/master/doc/images/repo-logo-3.png[Boost.12312312312]] -[width="100%", cols="12%,43%,45%", options="header"] +[width="100%",cols="12%,43%,45%",options="header",] |=== -|分支 |https://github.com/boostorg/json/tree/master[`master`] +|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[构建状态]] -|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[构建状态]] +|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[构建状态]] -|文档 -|https://www.boost.org/doc/libs/master/libs/json/[image:https://img.shields.io/badge/docs-master-brightgreen.svg[文档]] -|https://www.boost.org/doc/libs/develop/libs/json/[image:https://img.shields.io/badge/docs-develop-brightgreen.svg[文档]] +|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[构建状态]] -|https://drone.cpp.al/boostorg/json[image:https://drone.cpp.al/api/badges/boostorg/json/status.svg?ref=refs/heads/develop[构建状态]] +|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[构建状态]] -|测试矩阵 -|http://www.boost.org/development/tests/master/developer/json.html[image:https://img.shields.io/badge/matrix-master-brightgreen.svg[测试矩阵]] -|http://www.boost.org/development/tests/develop/developer/json.html[image:https://img.shields.io/badge/matrix-develop-brightgreen.svg[测试矩阵]] +|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]] -|模糊测试 |— -|https://github.com/boostorg/json/actions?query=workflow%3Afuzz+branch%3Adevelop[image:https://github.com/boostorg/json/workflows/fuzz/badge.svg?branch=develop[模糊测试]] +|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[构建状态]] -|https://ci.appveyor.com/project/vinniefalco/cppalliance-json/branch/develop[image:https://ci.appveyor.com/api/projects/status/8csswcnmfm798203?branch=develop&svg=true[构建状态]] +|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]] @@ -57,7 +57,8 @@ Boost.JSON 提供以下特性： === 要求 * 仅需 C++11 -* 可链接预构建的静态或动态 Boost 库，也可使用纯头文件方式（见下文）。 +* 可链接预构建的静态或动态 Boost 库，也可使用纯头文件方式 +（见下文） * Supports -fno-exceptions（可自动检测） 该库在其接口中大量依赖以下众所周知的 C++ 类型（以下称为 _standard types_）： diff --git a/doc/pages/allocators/background_zh_Hans.adoc b/doc/pages/allocators/background_zh_Hans.adoc index 0a6fe08..eec96df 100644 --- a/doc/pages/allocators/background_zh_Hans.adoc +++ b/doc/pages/allocators/background_zh_Hans.adoc @@ -8,8 +8,7 @@ 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} 的声明： += 背景 C++中分配器的第一个版本定义了名为{req_Allocator}的要求，并将每个标准容器设计为以分配器类型为模板参数的类模板。例如，以下是 {std_vector} 的声明： [source] ---- @@ -28,9 +27,10 @@ include::../../../test/doc_background.cpp[tag=doc_background_2,indent=0] * 容器必须是一个类模板。 * 在元素类型上参数化分配器的方式显得笨拙。 * 分配器特征机制（尤其是 POCCA 和 POCMA）复杂且容易出错。 - 使用多种分配器类型的基于分配器的程序会引发更多的函数模板实例化，且通常编译速度更慢，因为类模板的函数定义必须在所有调用点可见。 +Allocator-based programs which use multiple allocator types incur a greater number of function template instantiations and are generally slower to compile because class template function definitions must be visible at all call sites. + == 多态分配器 {cpp}17通过引入一个名为 {ref_memory_resource} 的抽象接口来表示底层分配操作，从而改进分配器模型。该接口未在元素类型上参数化，且无特征： diff --git a/doc/pages/allocators/overview_zh_Hans.adoc b/doc/pages/allocators/overview_zh_Hans.adoc index a5d994a..c5a9919 100644 --- a/doc/pages/allocators/overview_zh_Hans.adoc +++ b/doc/pages/allocators/overview_zh_Hans.adoc @@ -15,8 +15,6 @@ Official repository: https://github.com/boostorg/json :leveloffset: +1 -include::background.adoc[] -include::storage_ptr.adoc[] -include::uses_allocator.adoc[] +include::background.adoc[] include::storage_ptr.adoc[] include::uses_allocator.adoc[] :leveloffset: -1 diff --git a/doc/pages/allocators/storage_ptr_zh_Hans.adoc b/doc/pages/allocators/storage_ptr_zh_Hans.adoc index cbaecd0..234f344 100644 --- a/doc/pages/allocators/storage_ptr_zh_Hans.adoc +++ b/doc/pages/allocators/storage_ptr_zh_Hans.adoc @@ -8,49 +8,59 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) Official repository: https://github.com/boostorg/json //// -= `storage_ptr` -本库中的可变长度容器均使用动态分配的内存来存储其内容。调用方可通过在特定构造函数和函数参数列表中指定 <> ，以控制所使用的内存分配策略。<> 具有以下特性： += `storage_ptr` 本库中的可变长度容器均使用动态分配的内存来存储其内容。调用方可通过在特定构造函数和函数参数列表中指定 <> ，以控制所使用的内存分配策略。<> 具有以下特性： * 存储指针始终指向一个有效的、类型擦除后的 {ref_memory_resource}。 +以下是使用该库时所有与分配相关的类型和函数列表： * 默认构造的存储指针引用 <>（默认资源），这是一个由实现定义的实例，始终使用等效于全局 operator new 和 operator delete 的方式。 +.函数与类型 |=== |Name|描述 * 从 {ref_memory_resource} 或 {ref_polymorphic_allocator} 构造的存储指针不获取所有权；调用方负责确保资源的生命周期持续到不再被引用为止。 +{ref_polymorphic_allocator} do not acquire ownership; the caller is responsible for ensuring that the lifetime of the resource extends until it is no longer referenced. * 通过 <> 获取的存储指针会获得对内存资源的共享所有权；该资源的生命周期将延长，直至所有该存储指针的副本均被销毁。 +ownership of the memory resource; the lifetime of the resource is extended until all copies of the storage pointer are destroyed. * 存储指针在对资源进行类型擦除之前会记录 <> 的值，从而允许在运行时查询该值。 +before type-erasing the resource, allowing the value to be queried at run-time. -以下是使用该库时所有与分配相关的类型和函数列表： +This lists all of the allocation-related types and functions available when using the library: -.函数与类型 +.Functions and Types |=== -|Name|描述 +|Name|Description | <> -| 返回一个指向内存资源实例的指针，该实例在分配内存时总是抛出异常。此机制用于确保解析或容器操作不会进行动态内存分配，从而维持该不变性。 +| Returns a pointer to a memory resource instance which always throws an +exception upon allocation. This is used to to achieve the invariant that no parsing or container operation will dynamically allocate memory. | <> -| 一个自定义点，允许内存资源类型表明其 deallocate 调用是平凡的。 +| A customization point allowing a memory resource type to indicate that calls +to deallocate are trivial. | <> -| 一个返回智能指针的函数，该智能指针对新分配的内存资源具有共享所有权。 +| A function returning a smart pointer with shared ownership of a newly +allocated memory resource. | {ref_memory_resource} -| 表示分配器的抽象基类。 +| The abstract base class representing an allocator. | <> -| 一种内存资源，用于分配大块内存，且其 deallocate 函数是平凡的。所分配的内存不会被释放，直到该资源被销毁，因此在解析场景下速度很快，但不适合执行修改操作。 +| A memory resource which allocates large blocks of memory and has a trivial +deallocate function. Allocated memory is not freed until the resource is destroyed, making it fast for parsing but not suited for performing modifications. | {ref_polymorphic_allocator} -| 一个 {req_Allocator}，它通过引用 {ref_memory_resource} 执行内存分配。 +| An {req_Allocator} which uses a reference to a {ref_memory_resource} to +perform allocations. | <> -| 一种使用调用方提供的单一缓冲区的内存资源，不进行任何动态分配。该资源在解析时速度很快，但不适合执行修改操作。 +| A memory resource that uses a single caller provided buffer. No dynamic +allocations are used. This is fast for parsing but not suited for performing modifications. | <> -| 一种用于管理和访问 {ref_memory_resource} 的智能指针。 -|=== +| A smart pointer through which a {ref_memory_resource} is managed and +accessed. |=== == 默认内存资源 默认内存资源使用全局 `operator new` 和 `operator delete` 来进行内存分配。该资源不采用引用计数，且其 deallocate 函数是非平凡的。所有默认构造的 <> 对象均引用同一个内存资源： diff --git a/doc/pages/allocators/uses_allocator_zh_Hans.adoc b/doc/pages/allocators/uses_allocator_zh_Hans.adoc index 3501b6d..2d44f94 100644 --- a/doc/pages/allocators/uses_allocator_zh_Hans.adoc +++ b/doc/pages/allocators/uses_allocator_zh_Hans.adoc @@ -9,28 +9,29 @@ Official repository: https://github.com/boostorg/json //// [#uses_allocator] -= 使用分配器构造 -为支持已使用多态分配器的代码库，本库中的容器支持 {std_uses_allocator} 构造。对于 <>, <>, <> 和 <>： += 使用分配器构造 为支持已使用多态分配器的代码库，本库中的容器支持 {std_uses_allocator} 构造。对于 <>, <>, <> 和 <>： * 嵌套类型 `allocator_type` 是{ref_polymorphic_allocator}的别名。 +由容器所使用的 {ref_memory_resource} 构造的 {ref_polymorphic_allocator} 实例。该内存资源的所有权不会被转移。 * 所有接受 <> 的合格构造函数，也将在相同参数位置接受一个 {ref_polymorphic_allocator} 实例。 +实际上，这意味着当库中的容器类型被用在使用多态分配器的标准容器中时，该分配器会传播到 JSON 类型。例如： * 成员函数 `get_allocator` 返回一个 - 由容器所使用的 {ref_memory_resource} 构造的 {ref_polymorphic_allocator} 实例。该内存资源的所有权不会被转移。 +库容器可以从多态分配器构造： -实际上，这意味着当库中的容器类型被用在使用多态分配器的标准容器中时，该分配器会传播到 JSON 类型。例如： +多态分配器会递归传播。子元素的子元素将使用与父元素相同的内存资源。 [source] ---- include::../../../test/doc_uses_allocator.cpp[tag=doc_uses_allocator_1,indent=0] ---- -库容器可以从多态分配器构造： +Library containers can be constructed from polymorphic allocators: [source] ---- include::../../../test/doc_uses_allocator.cpp[tag=doc_uses_allocator_2,indent=0] ---- -多态分配器会递归传播。子元素的子元素将使用与父元素相同的内存资源。 +The polymorphic allocator is propagated recursively. Child elements of child elements will use the same memory resource as the parent. diff --git a/doc/pages/benchmarks_zh_Hans.adoc b/doc/pages/benchmarks_zh_Hans.adoc index 12ff1b8..28ae887 100644 --- a/doc/pages/benchmarks_zh_Hans.adoc +++ b/doc/pages/benchmarks_zh_Hans.adoc @@ -9,53 +9,57 @@ Official repository: https://github.com/boostorg/json //// [pagelevels=1,toclevels=1] -= 基准测试 -本节将 Boost.JSON 与两个广泛使用的具有类似功能的库进行性能比较：以高性能著称的 RapidJSON 和以功能丰富著称的JSON for Modern C++ 库（nlohmann/json）。bench 程序测量解析和序列化一组代表典型工作负载的 JSON 的吞吐量。评估的实现包括： += 基准测试 本节将 Boost.JSON 与两个广泛使用的具有类似功能的库进行性能比较：以高性能著称的 RapidJSON 和以功能丰富著称的JSON for Modern C++ 库（nlohmann/json）。bench 程序测量解析和序列化一组代表典型工作负载的 JSON 的吞吐量。评估的实现包括： -.实现 +.Implementations |=== -|Name|描述 +|Name|Description | *boost(pool)* -| 使用 <> 解析输入，该资源针对解析后不进行后续修改的场景进行了优化。<> 对象在各次试验之间被复用，使得实现所分配的临时内存得以保留，从而提升性能。 +| Parses the input using a <>, +.实现 |=== |Name|描述 | *boost* -| 使用 <> 解析输入，该资源基于标准 C++ 分配器，适用于通用场景，包括在解析后对文档进行修改。<> 对象在各次试验之间被复用，使得实现所分配的临时内存得以保留，从而提升性能。 +| Parses the input using the <>, which uses the standard C++ allocator, and is designed for general use including mutation of the document after it is parsed. The <> object is reused between trials, allowing temporary memory allocated by the implementation to persist and improve performance. | *rapidjson(pool)* -| 使用 https://rapidjson.org/classrapidjson_1_1_memory_pool_allocator.html[`MemoryPoolAllocator`] 的实例解析输入，该分配器针对“仅解析、不修改”的场景进行了优化。持有临时内存的 https://rapidjson.org/classrapidjson_1_1_generic_document.html[`Document`] 对象在多次测试之间不重复使用，否则内存消耗将无限增长，从而导致基准测试结果无效。 +| Parses the input using an instance of +https://rapidjson.org/classrapidjson_1_1_memory_pool_allocator.html[`MemoryPoolAllocator`], which is optimized for parsing without subsequent modification. The https://rapidjson.org/classrapidjson_1_1_generic_document.html[`Document`] object holding temporary memory is not reused between trials, otherwise memory consumption grows without bounds and invalidates the benchmark. | *rapidjson* -| 使用 https://rapidjson.org/classrapidjson_1_1_crt_allocator.html[`CrtAllocator`] 的实例解析输入，该分配器使用标准 C++ 分配器，适用于通用场景，包括解析后对文档的修改。持有临时内存的 https://rapidjson.org/classrapidjson_1_1_generic_document.html[`Document`] 对象在多次测试之间不重复使用，否则内存消耗将无限增长，导致基准测试结果无效。 +| Parses the input using an instance of +https://rapidjson.org/classrapidjson_1_1_crt_allocator.html[`CrtAllocator`], which uses the standard C++ allocator, and is designed for general use including mutation of the document after it is parsed. The https://rapidjson.org/classrapidjson_1_1_generic_document.html[`Document`] object holding temporary memory is not reused between trials, otherwise memory consumption grows without bounds and invalidates the benchmark. | *nlohmann* -| 使用静态成员函数 https://nlohmann.github.io/json/classnlohmann_1_1basic__json_ab330c13ba254ea41fbc1c52c5c610f45.html[`json::parse`] 解析输入，该函数使用默认的 `std` 分配器，适用于通用场景，包括解析后对文档的修改。该库未提供复用解析或序列化过程中所用临时存储的接口，因此无法在后续操作中重用这些临时内存。 -|=== +| Parses the input using the static member function +https://nlohmann.github.io/json/classnlohmann_1_1basic__json_ab330c13ba254ea41fbc1c52c5c610f45.html[`json::parse`], which uses the default `std` allocator, and is designed for general use including mutation of the document after it is parsed. This library does not provide an interface to reuse temporary storage used during parsing or serialization on subsequent operations. |=== == 方法论 首先加载所有输入文件。随后，每种配置会运行足够多的试验次数，以确保总运行时间不少于 5 秒。每次试验会记录所用时间、调用次数（解析或序列化）以及传输的字节数，并以此生成一个样本，同时计算出以 MB/s（兆字节每秒）为单位的吞吐量。每种配置会生成多个样本（目前为五个），剔除其中非中间两个的样本后，对剩余的两个样本取平均值，作为该配置的最终基准测试结果。 输入文件位于 bench/data 目录，按如下方式布局： -.输入文件 +.Input Files |=== -|Name|Size|描述 +|Name|Size|Description | <> | 125KB -| 来自 Apache Jenkins 安装的数据。 +| Data from the Apache Jenkins installation. | <> | 2.2MB -| 最大的文件，包含大量由两个浮点数坐标对组成的二元数组。 +| The largest file, containing a large number of 2-element arrays holding +.输入文件 |=== |Name|Size|描述 | <> | 1.69MB -| 一个包含多种嵌套结构、数据类型和长度的大型 JSON。 +| A large JSON with a variety of nesting, types, and lengths. | <> | 64KB -| 一份来自 GitHub Events API 的数据导出。 +| An export of data from the Github Events API. | <> | 3.25MB @@ -63,45 +67,46 @@ Official repository: https://github.com/boostorg/json | <> | 216KB -| 一个由大型对象组成的数组。 +| An array of large objects. | <> | 2.91MB -| 一个以 JSON 格式序列化的 three.js 示例模型。 +| A three.js example model serialized to JSON. | <> | 707KB -| 一个表示三维网格的 JSON，包含大量浮点数。 +| A JSON representing a 3D mesh. Contains many floating-point numbers. | <> | 1.54MB -| 添加了空格的 mesh.json。 +| mesh.json with whitespace added. | <> | 147KB -| 一个仅包含浮点数的数组。 +| A array containing only floating-point numbers. | <> | 499KB -| 一个包含大量 Cyrillic（西里尔）字符的 JSON。 +| A JSON with lots of Cyrillic characters. | <> | 617KB -| 一份来自 Twitter API 的数据导出。 +| An export of data from Twitter's API. | <> | 550KB -| 移除空格并将非 ASCII 字符替换为 Unicode 转义符的 twitter.json。 +| twitter.json with whitespace removed and non-ASCII characters replaced with +测试所用硬件：**Intel(R) Core(TM) i7-7700K CPU @ 4.20GHz**, Windows 10, 32GB RAM. | <> | 521KB -| 一份来自 Twitter API 的数据导出。 +| An export of data from Twitter's API. |=== -测试所用硬件：**Intel(R) Core(TM) i7-7700K CPU @ 4.20GHz**, Windows 10, 32GB RAM. - 编译器及优化选项：gcc 8.1 (-O3), clang 12.0 (-O3), and msvc 19.26 (/O2) +Compilers and optimization flags: gcc 8.1 (-O3), clang 12.0 (-O3), and msvc 19.26 (/O2). + == 解析 === 解析 apache_builds.json diff --git a/doc/pages/comparison_zh_Hans.adoc b/doc/pages/comparison_zh_Hans.adoc index 76f082a..9e206cf 100644 --- a/doc/pages/comparison_zh_Hans.adoc +++ b/doc/pages/comparison_zh_Hans.adoc @@ -8,11 +8,10 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) Official repository: https://github.com/boostorg/json //// -[#comparison, pagelevels=1,toclevels=1] +[#comparison,pagelevels=1,toclevels=1] = 与其他库的比较 -:icon_good: pass:q[[.green]##✔##] -:icon_bad: pass:q[[.red]##✘##] +:icon_good: pass:q[[.green]##✔##] :icon_bad: pass:q[[.red]##✘##] C++ 中存在众多 JSON 库，但为了比较的目的，有三个在对比中尤为值得关注：https://rapidjson.org/[RapidJSON]、https://nlohmann.github.io/json/[JSON for Modern {cpp}]（本文中称为 nlohmann's JSON， 或简称 nlohmann）以及https://github.com/lemire/simdjson[SIMD JSON]。 @@ -45,12 +44,16 @@ private: 该库采用了一种“大而全”（kitchen sink）的设计理念，包含大量功能，甚至涵盖一些使用场景非常小众的特性。其弱点在于：尽管众多模板参数提供了高度可配置性，却阻碍了编译器实现最优的性能优化。其结果是性能表现较差。这种对值类型各方面均可配置的能力，反而使其作为通用类型的适用性降低，形成了一种悖论效应。 * {icon_bad} `basic_json` 是一个类模板。各库必须在模板参数的选择上达成一致，才能实现互操作。 +choices of template parameters to be interoperable. * {icon_bad} 过度定制化。我们很难想象将 `BooleanType` 设置为 `bool` 之外的其他类型的使用场景。 +`BooleanType` anything other than `bool`. * {icon_bad} 关注点分离不佳。`basic_json` 容器声明不必要地将解析和序列化API混杂在一起。 +declaration needlessly conflates parsing and serialization APIs. * {icon_bad} 分配器支持有限。只允许无状态分配器，这排除了最重要的一类分配器，即基于本地内存池的实现。 +which rules out the most important type of allocator, a local arena-based implementation. * {icon_bad} 没有增量式解析，也没有增量式序列化。 @@ -75,16 +78,21 @@ class GenericObject; ---- * {icon_bad} 值类型不满足“正规性”要求。赋值具有破坏性，执行 `a = b` 等同于 `a = std::move(b)`，且不允许复制构造和复制赋值。 +performing `a = b` is equivalent to `a = std::move(b)`. No copy construction or copy assignment allowed. * {icon_bad} 对象类型没有哈希表或索引用于降低查找成本。 +lookups. * {icon_bad} 分配器采用引用语义，容易引发生命周期问题。 +easily encountered. * {icon_bad} 数组和对象类型的接口与标准库中的对应类型差异显著，且不符合惯用法。 +different from their standard library equivalents, and not idiomatic. * {icon_bad} 没有增量式解析，也没有增量式序列化。 * {icon_good} 解析和序列化性能优于大多数其他库。 +libraries. === 与SIMD JSON的比较 diff --git a/doc/pages/conversion/alloc_zh_Hans.adoc b/doc/pages/conversion/alloc_zh_Hans.adoc index 0cab67b..8101a88 100644 --- a/doc/pages/conversion/alloc_zh_Hans.adoc +++ b/doc/pages/conversion/alloc_zh_Hans.adoc @@ -7,8 +7,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) Official repository: https://github.com/boostorg/json //// -= 分配控制 -由于<>会创建一个<>对象，用户可能希望控制其内存分配方式。因此，该函数具有一个可选的 <> 参数，用于为结果指定{ref_memory_resource}。 += 分配控制 由于<>会创建一个<>对象，用户可能希望控制其内存分配方式。因此，该函数具有一个可选的 <> 参数，用于为结果指定{ref_memory_resource}。 [NOTE] <> 没有类似的参数，因为该函数不会创建 <> 对象。 @@ -19,14 +18,6 @@ Official repository: https://github.com/boostorg/json ``` -void -tag_invoke( const value_from_tag&, value& jv, ip_address const& addr ) -{ - jv = array{ b[0], b[1], b[2], b[3] }; -} +void tag_invoke( const value_from_tag&, value& jv, ip_address const& addr ) { jv = array{ b[0], b[1], b[2], b[3] }; } ``` - -该实现显式创建了一个 <>，而不是依赖于初始化列表的赋值。但该数组使用的是默认的 {ref_memory_resource}，而不是`jv`所使用的内存资源。 - -为避免创建使用错误 {ref_memory_resource} 的临时对象，可以借助 <> 的成员函数 <>、<> 和 <>。 diff --git a/doc/pages/conversion/context_zh_Hans.adoc b/doc/pages/conversion/context_zh_Hans.adoc index 56de8d3..4d67a9f 100644 --- a/doc/pages/conversion/context_zh_Hans.adoc +++ b/doc/pages/conversion/context_zh_Hans.adoc @@ -7,8 +7,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) Official repository: https://github.com/boostorg/json //// -= 上下文相关的转换 -此前在本节中，我们一直假定某个类型存在一种特定且合适的 JSON 表示形式。但实际情况并非总是如此。很多时候，同一个值在不同场景下需要以不同的 JSON 格式来表示。在 Boost.JSON 中，可以通过提供一个额外的参数——上下文（context）——来实现这一点。 += 上下文相关的转换 此前在本节中，我们一直假定某个类型存在一种特定且合适的 JSON 表示形式。但实际情况并非总是如此。很多时候，同一个值在不同场景下需要以不同的 JSON 格式来表示。在 Boost.JSON 中，可以通过提供一个额外的参数——上下文（context）——来实现这一点。 我们来实现从`user_ns::ip_address`到JSON字符串的转换： diff --git a/doc/pages/conversion/custom_zh_Hans.adoc b/doc/pages/conversion/custom_zh_Hans.adoc index 557e560..6d9c6bd 100644 --- a/doc/pages/conversion/custom_zh_Hans.adoc +++ b/doc/pages/conversion/custom_zh_Hans.adoc @@ -7,8 +7,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) Official repository: https://github.com/boostorg/json //// -= 自定义转换 -Boost.JSON 提供了两种机制用于自定义 <> 与用户类型之间的转换。一种机制涉及特化类型特征（type traits）。另一种机制更强大，需要定义`tag_invoke`的重载。本节将进一步解释这两种机制。 += 自定义转换 Boost.JSON 提供了两种机制用于自定义 <> 与用户类型之间的转换。一种机制涉及特化类型特征（type traits）。另一种机制更强大，需要定义`tag_invoke`的重载。本节将进一步解释这两种机制。 == 转换特征 之前已经介绍了一些转换类型特征，例如 <> 或 <>。库会依次尝试这些特征，并使用与第一个匹配特征对应的实现。然而，在某些情况下，某个类型可能会匹配到优先级更高的特征，而用户实际希望将其归入优先级更低的类别。如果发生这种情况，用户可以针对该类型特化那个不应匹配的特征，使其等同于`std::false_type`。 @@ -31,11 +30,9 @@ include::../../../test/snippets.cpp[tag=snippet_conv_spec_trait2,indent=0] 第二种、更强大的方法是自行提供转换实现。在 Boost.JSON 中，这是通过定义`tag_invoke`函数的重载来实现的（该机制的优点详见 http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1895r0.pdf[C++提案P1895]）。本质上，`tag_invoke` 通过参数依赖查找（ADL）在调用点寻找可用的重载，从而为自定义扩展点提供统一接口。顾名思义，一个标签类型作为参数传递，用于： * 1. 排除与该特定自定义点无关的候选函数，并且 - -* 2. 将用户定义的类型嵌入到参数列表中（例如，通过使用像`value_to_tag`这样的标签类型模板），以便在执行名称查找时检查其http://eel.is/c++draft/basic.lookup.argdep#2[关联的命名空间和实体]。 - 这样做的效果是能够找到用户提供的`tag_invoke`重载，即使它们在调用函数定义之后（在词法上）声明。 +* 2. 将用户定义的类型嵌入到参数列表中（例如，通过使用像`value_to_tag`这样的标签类型模板），以便在执行名称查找时检查其http://eel.is/c++draft/basic.lookup.argdep#2[关联的命名空间和实体]。 由 <> 调用的 tag_invoke 重载具有如下形式： ``` @@ -50,23 +47,19 @@ void tag_invoke( const value_from_tag&, value&, T ); T tag_invoke( const value_to_tag< T >&, const value& ); -``` - -如果我们用这种方法手动实现`user_ns::ip_address`的转换，它将如下所示： - [source] ---- include::../../../test/snippets.cpp[tag=snippet_tag_invoke_1,indent=0] ---- -由于被转换的类型已嵌入函数签名中，用户提供的重载对参数依赖查找（ADL）可见，并会在执行转换时成为候选函数： +``` [source] ---- include::../../../test/snippets.cpp[tag=snippet_tag_invoke_2,indent=0] ---- -用户可以自由地将具有自定义转换的类型与具有库提供转换的类型组合使用，库能正确处理它们： +如果我们用这种方法手动实现`user_ns::ip_address`的转换，它将如下所示： [source] ---- diff --git a/doc/pages/conversion/direct_zh_Hans.adoc b/doc/pages/conversion/direct_zh_Hans.adoc index 24f0d50..ae115d3 100644 --- a/doc/pages/conversion/direct_zh_Hans.adoc +++ b/doc/pages/conversion/direct_zh_Hans.adoc @@ -7,8 +7,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) Official repository: https://github.com/boostorg/json //// -= 直接转换 -对于大型输入，先解析到库的容器中，再通过 <> 进行转换（或反之，先通过 <> 转换，再从 <> 序列化）可能代价过高。针对这类场景，库提供了可直接将数据解析到用户提供的对象中、或直接从用户提供的对象进行序列化的组件。 += 直接转换 对于大型输入，先解析到库的容器中，再通过 <> 进行转换（或反之，先通过 <> 转换，再从 <> 序列化）可能代价过高。针对这类场景，库提供了可直接将数据解析到用户提供的对象中、或直接从用户提供的对象进行序列化的组件。 这种方法的缺点在于，不支持完全自定义的类型表示，仅支持库提供的转换。此外，所有需通过解析进行填充的对象都必须是可默认构造的类型——这不仅包括顶层对象，也包括容器的元素、所描述`struct`的成员以及变体类型的备选项。 diff --git a/doc/pages/conversion/forward_zh_Hans.adoc b/doc/pages/conversion/forward_zh_Hans.adoc index 30a19aa..ca4f5cf 100644 --- a/doc/pages/conversion/forward_zh_Hans.adoc +++ b/doc/pages/conversion/forward_zh_Hans.adoc @@ -7,8 +7,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) Official repository: https://github.com/boostorg/json //// -= 避免物理依赖 -一些用户（尤其是库作者）可能希望为其类型与 <> 提供转换功能，但同时又希望避免让自己的库依赖 Boost.JSON。借助一些前向声明，即可实现这一目标。 += 避免物理依赖 一些用户（尤其是库作者）可能希望为其类型与 <> 提供转换功能，但同时又希望避免让自己的库依赖 Boost.JSON。借助一些前向声明，即可实现这一目标。 [source] ---- diff --git a/doc/pages/conversion/guidelines_zh_Hans.adoc b/doc/pages/conversion/guidelines_zh_Hans.adoc index 15b5a3a..22606c4 100644 --- a/doc/pages/conversion/guidelines_zh_Hans.adoc +++ b/doc/pages/conversion/guidelines_zh_Hans.adoc @@ -7,8 +7,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) Official repository: https://github.com/boostorg/json //// -= 转换自定义指南 -由于选项众多，为类型选择最合适的转换自定义方式可能并不容易。本节将讨论这些选项，并给出不同场景下的选用建议。 += 转换自定义指南 由于选项众多，为类型选择最合适的转换自定义方式可能并不容易。本节将讨论这些选项，并给出不同场景下的选用建议。 首要建议是：除非生成的格式不符合需求，否则应优先使用库提供的转换，而非自行实现自定义转换。如果库错误地推断了转换类别，你可以通过将相关特征特化为继承自 `std::false_type` 来排除该转换。 diff --git a/doc/pages/conversion/nothrow_zh_Hans.adoc b/doc/pages/conversion/nothrow_zh_Hans.adoc index cf3957f..51a0cff 100644 --- a/doc/pages/conversion/nothrow_zh_Hans.adoc +++ b/doc/pages/conversion/nothrow_zh_Hans.adoc @@ -7,8 +7,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) Official repository: https://github.com/boostorg/json //// -= 不抛异常的转换 -对于不希望抛出异常的场景，Boost.JSON 还提供了 <> 的不抛异常版本，即函数模板 <>。它返回 {ref_result}，这是一个特化的变体类型，要么持有转换得到的值，要么持有 {ref_error_code}。 += 不抛异常的转换 对于不希望抛出异常的场景，Boost.JSON 还提供了 <> 的不抛异常版本，即函数模板 <>。它返回 {ref_result}，这是一个特化的变体类型，要么持有转换得到的值，要么持有 {ref_error_code}。 [NOTE] 对于 <>; 没有对应的不抛异常版本。这仅仅是因为我们尚未遇到需要 <> 向调用者报告错误的情况。 @@ -19,22 +18,18 @@ Official repository: https://github.com/boostorg/json result_for::type tag_invoke( const try_value_to_tag< T >&, const value& ); -``` - -对于 <> 节中所述的 `ip_address` 类，该重载可能如下所示： - [source] ---- include::../../../test/snippets.cpp[tag=snippet_nothrow_1,indent=0] ---- -该重载使我们能够将 `ip_address` 与 <> 一起使用。 +``` [source] ---- include::../../../test/snippets.cpp[tag=snippet_nothrow_2,indent=0] ---- -如果对某个类型使用 <>，而该类型没有本节所述形式的 `tag_invoke` 重载，但存在适用于 <> 的重载，那么库仍会尝试执行转换：它会调用抛异常的重载，并试图将抛出的任何异常转换为 {ref_error_code}。但请注意，这种方式的性能很可能不如专门提供的不抛异常重载。 +对于 <> 节中所述的 `ip_address` 类，该重载可能如下所示： -反之亦然：如果存在适用于<> 的 tag_invoke 重载，但没有适用于 <> 的重载，那么调用 <> 时会转而调用不抛异常的重载，随后根据返回的 {ref_error_code} 构造一个 {ref_system_error} 并抛出。由于存在上述回退机制，建议用户在计划使用 <> 时，优先提供本节所述的不抛异常重载，而非抛异常的重载。 +该重载使我们能够将 `ip_address` 与 <> 一起使用。 diff --git a/doc/pages/conversion/overview_zh_Hans.adoc b/doc/pages/conversion/overview_zh_Hans.adoc index 1b505af..e8254df 100644 --- a/doc/pages/conversion/overview_zh_Hans.adoc +++ b/doc/pages/conversion/overview_zh_Hans.adoc @@ -10,8 +10,7 @@ Official repository: https://github.com/boostorg/json //// [#conversion] -= 值转换 -尽管 <> 容器便于创建临时结构，但通常仍需在 JSON 与用户自定义类型或标准库类型之间进行转换。 += 值转换 尽管 <> 容器便于创建临时结构，但通常仍需在 JSON 与用户自定义类型或标准库类型之间进行转换。 函数模板 <> 提供了从类型 `T` 构造 <> 的接口。函数模板 <> 则执行相反方向的转换，从类型 `T` 转换为 <>。两者均支持多种不同的 https://en.cppreference.com/w/cpp/language/types[基础类型]（如 `int` 或 `double`）、标准库类型（如 `std::string` 或 `std::vector`），并可扩展以支持用户定义类型。 @@ -22,103 +21,98 @@ include::../../../test/snippets.cpp[tag=snippet_conv_1,indent=0] 对于类型 `T`，将从以下类别列表中选择合适的转换方式，并采用第一个匹配的类别。 -.转换类别 -[%autowidth, cols=4] +.Conversion categories +[%autowidth,cols=4] |=== -|T 的类别|注释|`value_from` 行为|`value_to` 行为 +|Category of T|Comment|`value_from` behavior|`value_to` behavior -|自定义转换。 +|Custom conversion. | -|自定义行为。 -|自定义行为。 +|Custom behavior. +|Custom behavior. -|Boost.JSON 容器。 +|Boost.JSON container. | -|结果等于输入值。 -|结果等于输入值。 +|The result is equal to the input value. +|The result is equal to the input value. |`bool` | -|结果等于输入值。 -|结果等于输入值。 +|The result is equal to the input value. +|The result is equal to the input value. -|https://en.cppreference.com/w/cpp/types/is_arithmetic[算术类型] +|https://en.cppreference.com/w/cpp/types/is_arithmetic[Arithmetic type] | -a| 结果为一个数值，等于输入值且类型为： +.转换类别 [%autowidth, cols=4] |=== |T 的类别|注释|`value_from` 行为|`value_to` 行为 * 若 `T` 为有符号整数，则为 `std::int64_t`；或 * 若 `T` 为无符号整数，则为 `std::uint64_t`；或 * 否则为 `double`。 -|结果通过 <> 创建。 +|The result is created via <>. -|满足 <> 的类型 -|适用于类似 {std_monostate} 的类型。 -|结果为空值。 -|结果将被默认构造。 +|Type satisfying <> +|Intended for types like {std_monostate}. +|The result is a null value. +|The result is default-constructed. -|满足 <> 的类型。 -|`char` 序列，例如 `std::string`。 -|结果为 <>。 -|结果由 <> 构造。 +|Type satisfying <>. +|A sequence of `char`s, e.g. `std::string`. +|The result is a <>. +|The result is constructed from a <>. -|满足 <> 的类型。 -|`std::variant` 及类似类型，例如 `boost::variant2::variant`。 -|结果等同于对活跃的变体备选项进行转换所得的结果。 -|结果包含首个转换成功的备选项。 +|Type satisfying <>. +|`std::variant` and similar types, e.g. `boost::variant2::variant`. +|The result is equal to the result of conversion of the active variant +a| 结果为一个数值，等于输入值且类型为： -|满足 <> 的类型 +|Type satisfying <> | -|若输入值为空，则结果为 `null`；否则等同于对可选类型内部存储对象的转换结果。 -|若输入值为 `null`，则结果为默认构造；否则结果由输入值转换为可选类型内部存储类型的结果构造。 +|If the input value is empty, the result is a `null`. Otherwise it is +对于复合类型（如序列、元组、已描述的类等），对其所包含对象的转换会递归应用。例如： -|满足 <> 的类型。 -|具有类字符串键的一对一映射（例如 `std::map`）。 -|结果为 <>。 -|结果为默认构造，元素在末尾通过 `insert` 被插入。 +|Type satisfying <>. +|A one-to-one mapping (e.g. `std::map`) with string-like keys. +|The result is an <>. +|The result is default-constructed, and elements are `insert`-ed at the end. -|满足 <> 的类型。 -|元素序列，例如 `std::vector`。 -|结果是一个 <>。 -|结果为默认构造，元素在末尾通过 `insert` 被插入。 +|Type satisfying <>. +|A sequence of elements, e.g. `std::vector`. +|The result is an <>. +|The result is default-constructed, and elements are `insert`-ed at the end. -|满足 <> 的类型。 -|一种大小固定的异构序列，例如 `std::tuple` 和 `std::pair`。 -|结果是一个 <>。 -|结果通过将数组元素作为构造函数参数进行构造。 +|Type satisfying <>. +|A heterogenous sequence with fixed size, e.g. `std::tuple` and `std::pair`. +|The result is an <>. +|The result is constructed with the array elements as constructor arguments. -|满足 <> 的类型 +|Type satisfying <> | -|结果是一个 <>，其键为所描述成员的名称。 -|结果将被默认构造，并为其所描述的成员赋予相应的值。 +|The result is an <> with described members' names as keys. +|The result is default-constructed and described members are assigned +此处，该映射被转换为一个 <>，因为它匹配 <>。其每个键被转换为一个 <>（因为 `std::string` 匹配 <>），而每个值被转换为一个 <>（因为 `std::pair` 匹配 <>）。最后，每对元素分别被转换为一个 `std::int64_t` 类型的数值和一个 `bool` 值。 -|满足 <> 的类型 +|Type satisfying <> | -|如果输入值等于某个已描述的枚举项，则结果为一个包含该枚举项名称的 <>；否则，结果等同于将输入值转换为其底层类型后的值。 -|结果为与输入 <> 对应的已描述枚举项。 +|If the input value is equal to one of the described enumerators, the result is +:leveloffset: +1 -|满足 <> 的类型。 -|`std::filesystem::path` 及类似类型，例如 `boost::filesystem::path`。 -|结果等于 `path::generic_string` 的结果。 -|结果由两个指向 `const char` 的指针构造而成。 +|Type satisfying <>. +|`std::filesystem::path` and similar types, e.g. `boost::filesystem::path`. +|The result is equal to the result of `path::generic_string`. +|The result is constructed from two pointers to `const char`. |=== -对于复合类型（如序列、元组、已描述的类等），对其所包含对象的转换会递归应用。例如： +include::custom.adoc[] include::nothrow.adoc[] include::alloc.adoc[] include::context.adoc[] include::forward.adoc[] include::direct.adoc[] include::guidelines.adoc[] [source] ---- include::../../../test/snippets.cpp[tag=snippet_conv_recursive,indent=0] ---- -此处，该映射被转换为一个 <>，因为它匹配 <>。其每个键被转换为一个 <>（因为 `std::string` 匹配 <>），而每个值被转换为一个 <>（因为 `std::pair` 匹配 <>）。最后，每对元素分别被转换为一个 `std::int64_t` 类型的数值和一个 `bool` 值。 +:leveloffset: -1 :leveloffset: +1 -include::custom.adoc[] -include::nothrow.adoc[] -include::alloc.adoc[] -include::context.adoc[] -include::forward.adoc[] -include::direct.adoc[] -include::guidelines.adoc[] +include::custom.adoc[] include::nothrow.adoc[] include::alloc.adoc[] include::context.adoc[] include::forward.adoc[] include::direct.adoc[] include::guidelines.adoc[] :leveloffset: -1 diff --git a/doc/pages/definitions_zh_Hans.adoc b/doc/pages/definitions_zh_Hans.adoc index 56d6e4d..faa6359 100644 --- a/doc/pages/definitions_zh_Hans.adoc +++ b/doc/pages/definitions_zh_Hans.adoc @@ -7,38 +7,8 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) Official repository: https://github.com/boostorg/json //// -:ref_memory_resource: pass:q[https://boost.org/doc/libs/latest/doc/html/doxygen/boost_container_header_reference/classboost_1_1container_1_1pmr_1_1memory__resource.html[`memory_resource`]] -:ref_polymorphic_allocator: pass:q[https://boost.org/doc/libs/latest/doc/html/doxygen/boost_container_header_reference/classboost_1_1container_1_1pmr_1_1polymorphic__allocator.html[`polymorphic_allocator`]] -:ref_error_category: pass:q[https://boost.org/doc/libs/latest/libs/system/doc/html/system.html#ref_error_category[`error_category`]] -:ref_error_code: pass:q[https://boost.org/doc/libs/latest/libs/system/doc/html/system.html#ref_error_code[`error_code`]] -:ref_error_condition: pass:q[https://boost.org/doc/libs/latest/libs/system/doc/html/system.html#ref_error_condition[`error_condition`]] -:ref_result: pass:q[https://boost.org/doc/libs/latest/libs/system/doc/html/system.html#ref_resultt_e[`result`]] -:ref_system_error: pass:q[https://boost.org/doc/libs/latest/libs/system/doc/html/system.html#ref_system_error[`system_error`]] +:ref_memory_resource: pass:q[https://boost.org/doc/libs/latest/doc/html/doxygen/boost_container_header_reference/classboost_1_1container_1_1pmr_1_1memory__resource.html[`memory_resource`]] :ref_polymorphic_allocator: pass:q[https://boost.org/doc/libs/latest/doc/html/doxygen/boost_container_header_reference/classboost_1_1container_1_1pmr_1_1polymorphic__allocator.html[`polymorphic_allocator`]] :ref_error_category: pass:q[https://boost.org/doc/libs/latest/libs/system/doc/html/system.html#ref_error_category[`error_category`]] :ref_error_code: pass:q[https://boost.org/doc/libs/latest/libs/system/doc/html/system.html#ref_error_code[`error_code`]] :ref_error_condition: pass:q[https://boost.org/doc/libs/latest/libs/system/doc/html/system.html#ref_error_condition[`error_condition`]] :ref_result: pass:q[https://boost.org/doc/libs/latest/libs/system/doc/html/system.html#ref_resultt_e[`result`]] :ref_system_error: pass:q[https://boost.org/doc/libs/latest/libs/system/doc/html/system.html#ref_system_error[`system_error`]] -:req_Allocator: pass:q[https://en.cppreference.com/w/cpp/named_req/Allocator[__Allocator__]] -:req_CopyAssignable: pass:q[https://en.cppreference.com/w/cpp/named_req/CopyAssignable[__CopyAssignable__]] -:req_CopyConstructible: pass:q[https://en.cppreference.com/w/cpp/named_req/CopyConstructible[__CopyConstructible__]] -:req_Copyable: pass:q[https://en.cppreference.com/w/cpp/concepts/copyable[__Copyable__]] -:req_DefaultConstructible: pass:q[https://en.cppreference.com/w/cpp/named_req/DefaultConstructible[__DefaultConstructible__]] -:req_Hash: pass:q[https://en.cppreference.com/w/cpp/named_req/Hash[__Hash__]] -:req_InputIterator: pass:q[https://en.cppreference.com/w/cpp/named_req/InputIterator[__LegacyInputIterator__]] -:req_ForwardIterator: pass:q[https://en.cppreference.com/w/cpp/named_req/ForwardIterator[__LegacyForwardIterator__]] -:req_MoveAssignable: pass:q[https://en.cppreference.com/w/cpp/named_req/MoveAssignable[__MoveAssignable__]] -:req_MoveConstructible: pass:q[https://en.cppreference.com/w/cpp/named_req/MoveConstructible[__MoveConstructible__]] -:req_Regular: pass:q[https://en.cppreference.com/w/cpp/concepts/regular[__Regular__]] -:req_Swappable: pass:q[https://en.cppreference.com/w/cpp/named_req/Swappable[__Swappable__]] -:req_SequenceContainer: pass:q[https://en.cppreference.com/w/cpp/named_req/SequenceContainer[__SequenceContainer__]] +:req_Allocator: pass:q[https://en.cppreference.com/w/cpp/named_req/Allocator[__Allocator__]] :req_CopyAssignable: pass:q[https://en.cppreference.com/w/cpp/named_req/CopyAssignable[__CopyAssignable__]] :req_CopyConstructible: pass:q[https://en.cppreference.com/w/cpp/named_req/CopyConstructible[__CopyConstructible__]] :req_Copyable: pass:q[https://en.cppreference.com/w/cpp/concepts/copyable[__Copyable__]] :req_DefaultConstructible: pass:q[https://en.cppreference.com/w/cpp/named_req/DefaultConstructible[__DefaultConstructible__]] :req_Hash: pass:q[https://en.cppreference.com/w/cpp/named_req/Hash[__Hash__]] :req_InputIterator: pass:q[https://en.cppreference.com/w/cpp/named_req/InputIterator[__LegacyInputIterator__]] :req_ForwardIterator: pass:q[https://en.cppreference.com/w/cpp/named_req/ForwardIterator[__LegacyForwardIterator__]] :req_MoveAssignable: pass:q[https://en.cppreference.com/w/cpp/named_req/MoveAssignable[__MoveAssignable__]] :req_MoveConstructible: pass:q[https://en.cppreference.com/w/cpp/named_req/MoveConstructible[__MoveConstructible__]] :req_Regular: pass:q[https://en.cppreference.com/w/cpp/concepts/regular[__Regular__]] :req_Swappable: pass:q[https://en.cppreference.com/w/cpp/named_req/Swappable[__Swappable__]] :req_SequenceContainer: pass:q[https://en.cppreference.com/w/cpp/named_req/SequenceContainer[__SequenceContainer__]] -:std_array: pass:q[https://en.cppreference.com/w/cpp/container/array[`std::array`]] -:std_initializer_list: pass:q[https://en.cppreference.com/w/cpp/utility/initializer_list[`std::initializer_list`]] -:std_complex: pass:q[https://en.cppreference.com/w/cpp/numeric/complex[`std::complex`]] -:std_hash: pass:q[https://en.cppreference.com/w/cpp/utility/hash[`std::hash`]] -:std_memory_resource: pass:q[https://en.cppreference.com/w/cpp/memory/memory_resource[`std::pmr::memory_resource`]] -:std_monostate: pass:q[https://en.cppreference.com/w/cpp/utility/variant/monostate[`std::monostate`]] -:std_ostream: pass:q[https://en.cppreference.com/w/cpp/io/basic_ostream[`std::ostream`]] -:std_polymorphic_allocator: pass:q[https://en.cppreference.com/w/cpp/memory/polymorphic_allocator[`std::pmr::polymorphic_allocator`]] -:std_string: pass:q[https://en.cppreference.com/w/cpp/string/basic_string[`std::string`]] -:std_unordered_map: pass:q[https://en.cppreference.com/w/cpp/container/unordered_map[`std::unordered_map`]] -:std_uses_allocator: pass:q[https://en.cppreference.com/w/cpp/memory/uses_allocator[`std::uses_allocator`]] -:std_vector: pass:q[https://en.cppreference.com/w/cpp/container/vector[`std::vector`]] -:std_tuple: pass:q[https://en.cppreference.com/w/cpp/utility/tuple[`std::tuple`]] +:std_array: pass:q[https://en.cppreference.com/w/cpp/container/array[`std::array`]] :std_initializer_list: pass:q[https://en.cppreference.com/w/cpp/utility/initializer_list[`std::initializer_list`]] :std_complex: pass:q[https://en.cppreference.com/w/cpp/numeric/complex[`std::complex`]] :std_hash: pass:q[https://en.cppreference.com/w/cpp/utility/hash[`std::hash`]] :std_memory_resource: pass:q[https://en.cppreference.com/w/cpp/memory/memory_resource[`std::pmr::memory_resource`]] :std_monostate: pass:q[https://en.cppreference.com/w/cpp/utility/variant/monostate[`std::monostate`]] :std_ostream: pass:q[https://en.cppreference.com/w/cpp/io/basic_ostream[`std::ostream`]] :std_polymorphic_allocator: pass:q[https://en.cppreference.com/w/cpp/memory/polymorphic_allocator[`std::pmr::polymorphic_allocator`]] :std_string: pass:q[https://en.cppreference.com/w/cpp/string/basic_string[`std::string`]] :std_unordered_map: pass:q[https://en.cppreference.com/w/cpp/container/unordered_map[`std::unordered_map`]] :std_uses_allocator: pass:q[https://en.cppreference.com/w/cpp/memory/uses_allocator[`std::uses_allocator`]] :std_vector: pass:q[https://en.cppreference.com/w/cpp/container/vector[`std::vector`]] :std_tuple: pass:q[https://en.cppreference.com/w/cpp/utility/tuple[`std::tuple`]] diff --git a/doc/pages/dom/array_zh_Hans.adoc b/doc/pages/dom/array_zh_Hans.adoc index 8d40e9b..dc778d7 100644 --- a/doc/pages/dom/array_zh_Hans.adoc +++ b/doc/pages/dom/array_zh_Hans.adoc @@ -9,8 +9,7 @@ Official repository: https://github.com/boostorg/json //// [#dom_array] -= `array` -一个 <> 存储一个 <> 的实例，作为 JSON 数组的底层表示。__array__ 类型的实例与存储 <> 的 {std_vector} 功能完全相同。此外，所有插入容器的值将使用与容器本身相同的 <>。 += `array` 一个 <> 存储一个 <> 的实例，作为 JSON 数组的底层表示。__array__ 类型的实例与存储 <> 的 {std_vector} 功能完全相同。此外，所有插入容器的值将使用与容器本身相同的 <>。 可以使用 <> 构造一个空数组，而不会产生任何内存分配。也可以显式指定一个 <>： diff --git a/doc/pages/dom/init_lists_zh_Hans.adoc b/doc/pages/dom/init_lists_zh_Hans.adoc index 379ff08..47917fb 100644 --- a/doc/pages/dom/init_lists_zh_Hans.adoc +++ b/doc/pages/dom/init_lists_zh_Hans.adoc @@ -8,8 +8,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) Official repository: https://github.com/boostorg/json //// -= 初始化列表 -初始化列表可用于构造或赋值一个<>： += 初始化列表 初始化列表可用于构造或赋值一个<>： [source] ---- @@ -81,7 +80,8 @@ include::../../../test/snippets.cpp[tag=snippet_init_list_9,indent=0] [WARNING] ==== -请勿创建类型为 {std_initializer_list} 的变量。这可能导致临时对象在初始化列表被使用之前就被销毁。 +Do not create variables of type {std_initializer_list}. This may result in +temporaries being destroyed before the initializer list is used. ==== 在所有情况下，通过初始化列表构造的 <>、<> 或 <> 所拥有的 <> 都会递归地传播到每个元素。 diff --git a/doc/pages/dom/nested_access_zh_Hans.adoc b/doc/pages/dom/nested_access_zh_Hans.adoc index f8d0a5a..500549d 100644 --- a/doc/pages/dom/nested_access_zh_Hans.adoc +++ b/doc/pages/dom/nested_access_zh_Hans.adoc @@ -8,8 +8,7 @@ Official repository: https://github.com/boostorg/json //// [#nested_access] -= 访问深层嵌套元素 -为了便于便捷地获取和修改 <> 对象中深层嵌套的元素，该库实现了 https://datatracker.ietf.org/doc/html/rfc6901[RFC 6901 (JSON Pointer)]: += 访问深层嵌套元素 为了便于便捷地获取和修改 <> 对象中深层嵌套的元素，该库实现了 https://datatracker.ietf.org/doc/html/rfc6901[RFC 6901 (JSON Pointer)]: [source] ---- diff --git a/doc/pages/dom/numbers_zh_Hans.adoc b/doc/pages/dom/numbers_zh_Hans.adoc index bf7c78f..bb85590 100644 --- a/doc/pages/dom/numbers_zh_Hans.adoc +++ b/doc/pages/dom/numbers_zh_Hans.adoc @@ -9,8 +9,7 @@ Official repository: https://github.com/boostorg/json //// [#dom_numbers] -= 数字 -JSON数字使用`std::int64_t`、`std::uint64_t`和`double`表示。当 <> 从无符号整数构造时，其<>将为`kind::uint64`。同样，从有符号整数构造的<> 将具有`kind::int64`，若从浮点类型构造则为`kind::double_`： += 数字 JSON数字使用`std::int64_t`、`std::uint64_t`和`double`表示。当 <> 从无符号整数构造时，其<>将为`kind::uint64`。同样，从有符号整数构造的<> 将具有`kind::int64`，若从浮点类型构造则为`kind::double_`： [source] ---- diff --git a/doc/pages/dom/object_zh_Hans.adoc b/doc/pages/dom/object_zh_Hans.adoc index 93bd7ae..1181a23 100644 --- a/doc/pages/dom/object_zh_Hans.adoc +++ b/doc/pages/dom/object_zh_Hans.adoc @@ -9,64 +9,67 @@ Official repository: https://github.com/boostorg/json //// [#dom_object] -= `object` -<> 使用 <> 的实例作为 JSON 对象的底层表示。<> 类型的实例是一种关联容器，存储键值对，其中键为 <>，映射的值类型为 <>。此类容器以标准映射（map）为模型，具有以下特性： += `object` <> 使用 <> 的实例作为 JSON 对象的底层表示。<> 类型的实例是一种关联容器，存储键值对，其中键为 <>，映射的值类型为 <>。此类容器以标准映射（map）为模型，具有以下特性： * 元素以 <> 的实例形式连续存储。 * 迭代器是普通指针，在插入或删除操作时可能会失效。 +可以使用 <> 构造一个空对象，而不产生任何内存分配。也可以显式指定一个 <>： * 只要不发生删除操作，插入顺序即被保留。 * 所有插入的值将使用与容器本身相同的 {ref_memory_resource}。 +由两元素键值对组成的初始化列表可用于构造带有初始内容的对象。这些构造函数可能会分配内存并抛出异常： -可以使用 <> 构造一个空对象，而不产生任何内存分配。也可以显式指定一个 <>： +或者，也可以在构造之后插入元素： [source] ---- include::../../../test/snippets.cpp[tag=snippet_objects_1,indent=0] ---- -由两元素键值对组成的初始化列表可用于构造带有初始内容的对象。这些构造函数可能会分配内存并抛出异常： +与 `std` 对应容器类似，可通过 <> 使用边界检查直接按键访问元素，或通过 <> 进行无边界检查访问（若键不存在则创建空元素）： [source] ---- include::../../../test/snippets.cpp[tag=snippet_objects_2,indent=0] ---- -或者，也可以在构造之后插入元素： +容器内部通过键计算哈希表，使得查找操作的平均时间复杂度为常数级别。 [source] ---- include::../../../test/snippets.cpp[tag=snippet_objects_3,indent=0] ---- -与 `std` 对应容器类似，可通过 <> 使用边界检查直接按键访问元素，或通过 <> 进行无边界检查访问（若键不存在则创建空元素）： +完整成员函数及嵌套类型列表请参阅 <> 的参考页。 [source] ---- include::../../../test/snippets.cpp[tag=snippet_objects_4,indent=0] ---- -容器内部通过键计算哈希表，使得查找操作的平均时间复杂度为常数级别。 +与 `std::pair` 类似，<> 类型可用于 {cpp}17 的结构化绑定。为此专门提供了 `std::tuple_size`、`std::tuple_element` 的特化及 <> 的重载。 [WARNING] ==== -与传统的基于节点的容器（如 `std::set`）不同，插入和擦除操作不保证引用稳定性或迭代器稳定性。 +Unlike traditional node based containers like `std::set`, there is no +guarantee of reference stability or iterator stability on insertions +and erasures. -例如： +For example: [source] ---- include::../../../test/snippets.cpp[tag=snippet_objects_5,indent=0] ---- -在向 `obj` 添加一个新值后继续使用 `arr`，会导致未定义行为。 +Using `arr` after adding another value to `obj` results in undefined behavior. ==== -完整成员函数及嵌套类型列表请参阅 <> 的参考页。 +For the complete listing of all available member functions and nested types, see the reference page for <>. -与 `std::pair` 类似，<> 类型可用于 {cpp}17 的结构化绑定。为此专门提供了 `std::tuple_size`、`std::tuple_element` 的特化及 <> 的重载。 +As with `std::pair`, the <> type can be used with structured bindings in {cpp}17. Specializations of `std::tuple_size`, `std::tuple_element`, and overloads of <> are all provided for this purpose. == 格式化输出 diff --git a/doc/pages/dom/overview_zh_Hans.adoc b/doc/pages/dom/overview_zh_Hans.adoc index a57511a..24614c6 100644 --- a/doc/pages/dom/overview_zh_Hans.adoc +++ b/doc/pages/dom/overview_zh_Hans.adoc @@ -9,32 +9,35 @@ Official repository: https://github.com/boostorg/json //// [#dom] -= 文档模型 -在本库中，以下类型实现了用于在内存中表示 JSON 数据的容器： += 文档模型 在本库中，以下类型实现了用于在内存中表示 JSON 数据的容器： -.容器类型 +.Container Types [%autowidth] |=== -|Type|描述 +|Type|Description | <> -| 一种支持动态大小和快速随机访问的 JSON 值序列容器。其接口和性能特性类似于 {std_vector}。 +| A sequence container of JSON values supporting dynamic size and fast, random +.容器类型 [%autowidth] |=== |Type|描述 | <> -| 一种具有唯一键的键值对关联容器，其中键为字符串，映射类型为 JSON 值。查找、插入和移除操作具有平均常数时间复杂度。此外，元素在内存中连续存储，支持缓存友好的迭代。 +| An associative container of key-value pairs with unique keys, where the key +这些容器将在接下来的章节中深入探讨。 | <> -| 一个连续的字符范围。该库假定字符串内容仅包含有效的 UTF-8 编码。 +| A contiguous range of characters. The library assumes that the contents of +:leveloffset: +1 include::value.adoc[] include::string.adoc[] include::array.adoc[] include::object.adoc[] include::numbers.adoc[] include::init_lists.adoc[] include::nested_access.adoc[] :leveloffset: -1 | <> -| 一种特殊的变体类型，可持有六种标准 JSON 数据类型中的任意一种。 -|=== +| A special variant which can hold one of any of the six standard JSON data +types. |=== -这些容器将在接下来的章节中深入探讨。 +These containers are explored in-depth in the sections that follow. [NOTE] ==== -文中所使用的示例代码和标识符均假定以下声明已生效： +Sample code and identifiers used throughout are written as if the following +declarations are in effect: [source] ---- @@ -43,12 +46,4 @@ using namespace boost::json; ---- ==== -:leveloffset: +1 -include::value.adoc[] -include::string.adoc[] -include::array.adoc[] -include::object.adoc[] -include::numbers.adoc[] -include::init_lists.adoc[] -include::nested_access.adoc[] -:leveloffset: -1 +:leveloffset: +1 include::value.adoc[] include::string.adoc[] include::array.adoc[] include::object.adoc[] include::numbers.adoc[] include::init_lists.adoc[] include::nested_access.adoc[] :leveloffset: -1 diff --git a/doc/pages/dom/string_zh_Hans.adoc b/doc/pages/dom/string_zh_Hans.adoc index d2bd0c5..b6a10f2 100644 --- a/doc/pages/dom/string_zh_Hans.adoc +++ b/doc/pages/dom/string_zh_Hans.adoc @@ -19,43 +19,48 @@ Official repository: https://github.com/boostorg/json * <>不是一个类模板， * <> 使用`char`作为其字符类型， * 字符串操作中冗余的重载已被基于 <> 的接口所取代， +通过增强的接口，所有需要输入字符串的操作均以单一重载形式实现，其参数类型为 <>，并可接受大多数类字符串对象。诸如以空字符结尾的字符指针、`std::string`、<>、字符串子范围以及可转换为 <> 的对象，均可传递给这些函数。 * 允许访问`[size(), capacity())`范围内的字符， * 使用<>代替{req_Allocator}，且 * 保证采用小缓冲区优化，从而避免为短字符串分配内存。 +更正式地说，`std::string` 中接受以下任一参数组合作为输入字符串的成员函数重载： -通过增强的接口，所有需要输入字符串的操作均以单一重载形式实现，其参数类型为 <>，并可接受大多数类字符串对象。诸如以空字符结尾的字符指针、`std::string`、<>、字符串子范围以及可转换为 <> 的对象，均可传递给这些函数。 +被一个接受 <> 参数的重载所替代。 [source] ---- include::../../../test/snippets.cpp[tag=snippet_strings_4,indent=0] ---- -更正式地说，`std::string` 中接受以下任一参数组合作为输入字符串的成员函数重载： +这一设计从接口中移除了多个冗余的重载。例如，`std::string::insert` 原本有 11 个重载，而在 <> 中被减少到仅 3 个，同时仍提供完全相同的功能。除此之外，接受 `std::initializer_list` 参数的重载也被移除。这类重载用途有限，因为它们本质上只是对字符数组的封装，且语法效率低下： * 一个`std::string`参数，或 * 一个`std::string`参数和两个指定子字符串的`size_type`参数，或 +随着用于指定子字符串参数的重载被移除，库提供了一个成员函数`subview`， 用于返回一个 <>，从而支持高效的子字符串操作： * 一个可转换为 <> 类型的参数，或 * 一个可转换为<>类型的参数和两个指定子字符串的`size_type`参数，或 +<> 可使用 <>（默认构造资源） 进行构造，且不会产生任何内存分配。或者，也可以显式提供一个 <>： * 一个`const_pointer`参数，或 * 一个`const_pointer`类型的参数和一个指定字符串长度的`size_type`参数 +specifies the length of the string -被一个接受 <> 参数的重载所替代。 +are replaced with an overload accepting a <> parameter. -这一设计从接口中移除了多个冗余的重载。例如，`std::string::insert` 原本有 11 个重载，而在 <> 中被减少到仅 3 个，同时仍提供完全相同的功能。除此之外，接受 `std::initializer_list` 参数的重载也被移除。这类重载用途有限，因为它们本质上只是对字符数组的封装，且语法效率低下： +This design removes several redundant overloads from the interface. For example, the 11 overloads of `std::string::insert` are reduced to just 3 in <>, while still providing identical functionality. In addition to these changes, overloads taking a `std::initializer_list` parameter have been removed. Such overloads have little use, as they serve as little more than wrappers for arrays with an inefficient syntax: [source] ---- include::../../../test/snippets.cpp[tag=snippet_strings_3,indent=0] ---- -随着用于指定子字符串参数的重载被移除，库提供了一个成员函数`subview`， 用于返回一个 <>，从而支持高效的子字符串操作： +With the removal of overloads that specify parameters for a substring, a member function `subview` that returns a <> is provided to facilitate cheap substring operations: [source] ---- include::../../../test/snippets.cpp[tag=snippet_strings_2,indent=0] ---- -<> 可使用 <>（默认构造资源） 进行构造，且不会产生任何内存分配。或者，也可以显式提供一个 <>： +A <> may be constructed using the <> without incurring any memory allocations. Alternatively, a <> can be provided explicitly: [source] ---- diff --git a/doc/pages/dom/value_zh_Hans.adoc b/doc/pages/dom/value_zh_Hans.adoc index e655858..73843d3 100644 --- a/doc/pages/dom/value_zh_Hans.adoc +++ b/doc/pages/dom/value_zh_Hans.adoc @@ -9,20 +9,22 @@ Official repository: https://github.com/boostorg/json //// [#dom_value] -= `value` -JSON文档在内存中表示为<>的实例：一种{req_Regular}类型，满足{req_DefaultConstructible}、{req_CopyConstructible}、{req_CopyAssignable}、{req_MoveConstructible}、{req_MoveAssignable}以及许多分配器感知容器的要求。它在内部实现为一个https://en.wikipedia.org/wiki/Tagged_union[__variant__]（变体），并且可以动态存储六种已定义的JSON值类型中的任意一种： += `value` JSON文档在内存中表示为<>的实例：一种{req_Regular}类型，满足{req_DefaultConstructible}、{req_CopyConstructible}、{req_CopyAssignable}、{req_MoveConstructible}、{req_MoveAssignable}以及许多分配器感知容器的要求。它在内部实现为一个https://en.wikipedia.org/wiki/Tagged_union[__variant__]（变体），并且可以动态存储六种已定义的JSON值类型中的任意一种： * **空值**：一种https://en.cppreference.com/w/cpp/utility/variant/monostate[__monostate__]（单态）值，等同于`nullptr`。 +https://en.cppreference.com/w/cpp/utility/variant/monostate[__monostate__] value, equivalent to `nullptr`. * **布尔值**：布尔类型，取值为`true`或`false`。 * **数值**：整型或浮点型值。 * **字符串**：由零个或多个Unicode字符组成的序列，类似于{std_string}。 +similar to {std_string}. * **数组**：值的有序列表，类似于{std_vector}。 * **对象**：名称/值对的集合，也称为https://en.wikipedia.org/wiki/Associative_array[__关联数组__]。 +https://en.wikipedia.org/wiki/Associative_array[__associative array__]. == 处理值 从`nullptr`构造或默认构造的 <> 表示一个空的JSON元素： @@ -55,24 +57,14 @@ include::../../../test/snippets.cpp[tag=snippet_value_4,indent=0] 下表列出了所有用于判断和访问 <> 内容的方法： -.<>访问器 -[%autowidth, cols=8] -|=== -|种类 -|表示形式 -|置入 -|种类测试 -|指针访问 -|`result`访问 -|受检访问 -|非受检访问 +.<>访问器 [%autowidth, cols=8] |=== |种类 |表示形式 |置入 |种类测试 |指针访问 |`result`访问 |受检访问 |非受检访问 |<> |<> |<> |<> |<> -|<> +|<> |<> |<> @@ -83,7 +75,7 @@ include::../../../test/snippets.cpp[tag=snippet_value_4,indent=0] |<> |<> |<> -|<> +|<> |<> |<> @@ -97,13 +89,13 @@ include::../../../test/snippets.cpp[tag=snippet_value_4,indent=0] |<> |https://en.cppreference.com/w/cpp/types/integer[`std::int64_t`] |<> -|<> +|<> |<> |<> |<> |<> -|<> +|<> |https://en.cppreference.com/w/cpp/types/integer[`std::uint64_t`] |<> |<> @@ -121,7 +113,7 @@ include::../../../test/snippets.cpp[tag=snippet_value_4,indent=0] |<> |<> -|<> +|<> |https://en.cppreference.com/w/cpp/language/types[`bool`] |<> |<> @@ -134,68 +126,66 @@ include::../../../test/snippets.cpp[tag=snippet_value_4,indent=0] |https://en.cppreference.com/w/cpp/language/nullptr[`std::nullptr_t`] |<> |<> -^|— -|<> -^|— -^|— +^|— |<> ^|— ^|— |=== <> 的置入成员函数返回对底层表示形式的类型化引用。例如，前例中对 <> 的调用返回一个 <> 。下表列出了每种 kind 对应的底层类型： |=== -|Kind|Type|描述 +|Kind|Type|Description | <> | <> -| 一个关联数组，其键为字符串，值为 <> 元素，接口类似于 {std_unordered_map}，并保留插入顺序。 +| An associative array of string keys mapping to <> elements with an +^| — | 一个表示空值的monostate值。 |=== | <> | <> -| 一个<>元素的有序列表，其接口类似于{std_vector}。 +| An ordered list of <> elements with an interface similar to +置入操作的返回值可用于执行赋值，或捕获对底层元素的引用以供后续检查或修改： | <> | <> -| 一个采用https://en.wikipedia.org/wiki/UTF-8[__UTF-8__]编码的https://en.wikipedia.org/wiki/Unicode[Unicode]字符https://en.wikipedia.org/wiki/String_(computer_science)[字符串]，其接口类似于{std_string}。 +| A https://en.wikipedia.org/wiki/UTF-8[__UTF-8__] encoded +如果已知 <> 的 <>，可使用诸如 <> 或 <> 等函数，在不改变现有值的情况下获取对底层表示的引用： | <> | `std::int64_t` -| 64位有符号整数。 +| A 64 bit signed integer. -| <> +| <> | `std::uint64_t` -| 64位无符号整数。 +| A 64 bit unsigned integer. | <> | `double` -| 一个`double`，用于保存浮点型值。 +| A `double` holding a floating-point value. -| <> +| <> | https://en.cppreference.com/w/cpp/keyword/bool[`bool`] -| 一个`bool`，用于保存`true`或`false`。 +| A `bool` holding `true` or `false`. | <> -^| — -| 一个表示空值的monostate值。 -|=== +然而，如上所示，如果 <> 中的实际类型与函数签名所指定的类型不匹配，这些函数会抛出异常。这一行为可作为一种简洁的验证形式：以预期类型直接访问值，若 JSON 结构无效，则通过捕获异常进行处理。 -置入操作的返回值可用于执行赋值，或捕获对底层元素的引用以供后续检查或修改： +我们可以通过请求一个可能为空的指针（而非引用）来查询值中特定种类的底层表示形式，而不会抛出异常。这里我们使用 <> 来条件执行赋值操作，而无需使用异常： [source] ---- include::../../../test/snippets.cpp[tag=snippet_value_5,indent=0] ---- -如果已知 <> 的 <>，可使用诸如 <> 或 <> 等函数，在不改变现有值的情况下获取对底层表示的引用： +返回 {ref_result} 的函数允许您同时使用上述两种方式： [source] ---- include::../../../test/snippets.cpp[tag=snippet_value_6,indent=0] ---- -然而，如上所示，如果 <> 中的实际类型与函数签名所指定的类型不匹配，这些函数会抛出异常。这一行为可作为一种简洁的验证形式：以预期类型直接访问值，若 JSON 结构无效，则通过捕获异常进行处理。 +However, as shown above these functions throw an exception if the kind in the <> does not match the kind denoted by the function signature. This can be used as a concise form of validation: access values as if they were the right type, but handle the resulting exception indicating if the schema of the JSON is not valid. -我们可以通过请求一个可能为空的指针（而非引用）来查询值中特定种类的底层表示形式，而不会抛出异常。这里我们使用 <> 来条件执行赋值操作，而无需使用异常： +We can query a value for its underlying representation of a particular kind in a way that does not throw exceptions by requesting a pointer which may be null, instead of a reference. Here we use <> to conditionally perform an assignment without using exceptions: [source] ---- @@ -204,7 +194,10 @@ include::../../../test/snippets.cpp[tag=snippet_value_7,indent=0] [TIP] ==== -如果值的种类是静态已知的，则可以通过解引用指针而不检查来获取对底层表示形式的引用。这避免了使用例如 <> 时可能出现的异常所带来的代码开销： +If the value's kind is known statically, a reference to the underlying +representation may be obtained by dereferencing the pointer without checking. +This avoids the code overhead of the possible exception when using, for example +<>: [source] ---- @@ -212,7 +205,7 @@ include::../../../test/snippets.cpp[tag=snippet_value_8,indent=0] ---- ==== -返回 {ref_result} 的函数允许您同时使用上述两种方式： +Functions returning {ref_result} allow you to use both approaches: [source] ---- diff --git a/doc/pages/faq_zh_Hans.adoc b/doc/pages/faq_zh_Hans.adoc index 135d40c..bb9c745 100644 --- a/doc/pages/faq_zh_Hans.adoc +++ b/doc/pages/faq_zh_Hans.adoc @@ -10,12 +10,14 @@ Official repository: https://github.com/boostorg/json = 常见问题 -"难道 simdjson 不是更快吗？":: 这些库不可相提并论。simdjson 解析器的输出是一个只读结构。换句话说，它不能被修改，创建它的唯一方法是解析一个 JSON 字符串。另一方面，Boost.JSON 允许你修改容纳已解析 JSON 的容器，甚至可以通过容器接口从头构建 JSON 文档。 +"Isn't simdjson faster?":: 这些库不可相提并论。simdjson 解析器的输出是一个只读结构。换句话说，它不能被修改，创建它的唯一方法是解析一个 JSON 字符串。另一方面，Boost.JSON 允许你修改容纳已解析 JSON 的容器，甚至可以通过容器接口从头构建 JSON 文档。 +"为什么使用 <> 而不是 {ref_polymorphic_allocator}？":: {ref_polymorphic_allocator} 将内存资源视为所有权的引用。Boost.JSON 使用一个引用计数智能指针容器来简化内存资源的生命周期管理。除了引用计数外，<> 还可以作为围绕 {ref_memory_resource} 的非计数引用包装器。 -"为什么不使用标准的 {req_Allocator}？":: 使用标准分配器将要求 <> 被声明为一个类模板，这会增加额外的编译负担。通过避免使用模板，库中的大部分函数定义可以从头文件中排除，并放入单独的静态库或动态库中。 +"Why not use a standard {req_Allocator}?:: 使用标准分配器将要求 <> 被声明为一个类模板，这会增加额外的编译负担。通过避免使用模板，库中的大部分函数定义可以从头文件中排除，并放入单独的静态库或动态库中。 +require that <> be declared as a class template, which would impose an additional compilation burden. By avoiding the template, most of the function definitions in the library can be excluded from the headers and emitted in a separate static or dynamic library. -"为什么使用 <> 而不是 {ref_polymorphic_allocator}？":: -{ref_polymorphic_allocator} 将内存资源视为所有权的引用。Boost.JSON 使用一个引用计数智能指针容器来简化内存资源的生命周期管理。除了引用计数外，<> 还可以作为围绕 {ref_memory_resource} 的非计数引用包装器。 +"Why use <> over {ref_polymorphic_allocator}?:: {ref_polymorphic_allocator} treats the memory resource as a reference with respect to ownership. Boost.JSON uses a reference counted smart pointer container to simplify the lifetime management of memory resources. In addition to being reference counted, <> can function as an uncounted reference wrapper around a {ref_memory_resource}. -"为什么使用 <> 而不是 {std_string}？":: 该库提供的字符串使用 <>分配器模型，在所有 C++ 版本上具有相同的接口，并具有优化的类布局以保持 JSON 值的大小较小。<> 还实现了一个改进的接口，该接口使用 <> 替代了多余的重载。 +"Why <> instead of {std_string}?":: 该库提供的字符串使用 <>分配器模型，在所有 C++ 版本上具有相同的接口，并具有优化的类布局以保持 JSON 值的大小较小。<> 还实现了一个改进的接口，该接口使用 <> 替代了多余的重载。 +library uses the <> allocator model, has the same interface on all C++ versions, and has an optimized class layout to keep the size of JSON values small. <> also implements an improved interface that replaces extraneous overloads with ones that use <>. diff --git a/doc/pages/io/overview_zh_Hans.adoc b/doc/pages/io/overview_zh_Hans.adoc index daadac2..3aa5f93 100644 --- a/doc/pages/io/overview_zh_Hans.adoc +++ b/doc/pages/io/overview_zh_Hans.adoc @@ -8,13 +8,11 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) Official repository: https://github.com/boostorg/json //// -[#input_output, pagelevels=2] -= 输入/输出 -该库提供解析和序列化算法，可根据需要在 JSON 与 <> 容器之间相互转换。这是通过自由函数和类实现的，具体如下所述。 +[#input_output,pagelevels=2] += 输入/输出 该库提供解析和序列化算法，可根据需要在 JSON 与 <> 容器之间相互转换。这是通过自由函数和类实现的，具体如下所述。 :leveloffset: +1 -include::parsing.adoc[] -include::serializing.adoc[] +include::parsing.adoc[] include::serializing.adoc[] :leveloffset: -1 diff --git a/doc/pages/io/parsing_zh_Hans.adoc b/doc/pages/io/parsing_zh_Hans.adoc index 5123a96..67ffda7 100644 --- a/doc/pages/io/parsing_zh_Hans.adoc +++ b/doc/pages/io/parsing_zh_Hans.adoc @@ -9,54 +9,57 @@ Official repository: https://github.com/boostorg/json //// [pagelevels=1] -= 解析 -解析是将序列化的JSON文本验证并分解为元素的过程。该库提供以下函数和类型来辅助解析： += 解析 解析是将序列化的JSON文本验证并分解为元素的过程。该库提供以下函数和类型来辅助解析： -.解析函数和类型 +.Parsing Functions and Types |=== -|Name|描述 +|Name|Description | <> -| 一个 SAX 推送式解析器实现，它将序列化的 JSON 文本转换为对用户提供的处理器的一系列成员函数调用，从而允许自定义内存中文档的表示行为。 +| A SAX push parser implementation which converts a serialized JSON text into +.解析函数和类型 |=== |Name|描述 | <> -| 一种结构，用于选择在解析期间启用哪些扩展。 +| A structure used to select which extensions are enabled during parsing. | <> -| 解析包含完整序列化 JSON 文本的字符串，并返回一个 <>。 +| Parse a string containing a complete serialized JSON text, and return +<> 函数提供了一个简单接口，用于在单个函数调用中将序列化的JSON文本转换为<>。此重载使用异常来指示错误： | <> -| 一种有状态的 DOM 解析器对象，可用于高效解析一系列 JSON 文本（每个文本均位于单独的连续字符缓冲区中），并将每个结果作为<>返回。 +| A stateful DOM parser object which may be used to efficiently parse a series +或者，可以使用{ref_error_code}： | <> -| 一种有状态的DOM解析器对象，可用于高效地增量解析一系列JSON文本，并将每个结果作为<>返回。 +| A stateful DOM parser object which may be used to efficiently parse a series +即使使用错误码，底层 {ref_memory_resource} 仍可能抛出异常： | <> -| 一种用于高效构建 <> 的低层构建块。解析器在内部使用它，用户也可以使用它来适配外部解析器以生成此库的容器。 -|=== +| A low level building block used for efficiently building a <>. The +前述示例中返回的 <> 使用了 <>（默认内存资源）。以下代码使用了 <>，从而实现更快的解析。`jv` 被标记为 `const` 以防止后续修改，因为使用单调内存资源的容器在被修改时会浪费内存。 -<> 函数提供了一个简单接口，用于在单个函数调用中将序列化的JSON文本转换为<>。此重载使用异常来指示错误： +The <> function offers a simple interface for converting a serialized JSON text to a <> in a single function call. This overload uses exceptions to indicate errors: [source] ---- include::../../../test/doc_parsing.cpp[tag=doc_parsing_1,indent=0] ---- -或者，可以使用{ref_error_code}： +Alternatively, an {ref_error_code} can be used: [source] ---- include::../../../test/doc_parsing.cpp[tag=doc_parsing_2,indent=0] ---- -即使使用错误码，底层 {ref_memory_resource} 仍可能抛出异常： +Even when using error codes, exceptions thrown from the underlying {ref_memory_resource} are still possible: [source] ---- include::../../../test/doc_parsing.cpp[tag=doc_parsing_3,indent=0] ---- -前述示例中返回的 <> 使用了 <>（默认内存资源）。以下代码使用了 <>，从而实现更快的解析。`jv` 被标记为 `const` 以防止后续修改，因为使用单调内存资源的容器在被修改时会浪费内存。 +The <> returned in the preceding examples use the <>. The following code uses a <>, which results in faster parsing. `jv` is marked `const` to prevent subsequent modification, because containers using a monotonic resource waste memory when mutated. [source] ---- @@ -86,6 +89,7 @@ include::../../../test/doc_parsing.cpp[tag=doc_parsing_15,indent=0] ---- CAUTION: 启用注释支持时，读取输入时需格外注意不要丢失空白字符。例如，`std::getline`会从它生成的字符串中移除行尾字符。 +when reading the input. For example, `std::getline` removes the endline characters from the string it produces. == 全精度数字解析 库默认使用的数字解析算法速度较快，但可能导致轻微的精度损失。这在某些应用中可能不可接受，因此可以选择启用一种没有此缺陷但速度稍慢的替代算法。为此，您还需要使用<>结构体。 @@ -141,13 +145,14 @@ include::../../../test/doc_parsing.cpp[tag=doc_parsing_9,indent=0] 在以下示例中，JSON文本从标准输入逐行解析。此处使用错误码替代异常。函数<>用于指示输入结束： CAUTION: 如果启用了注释，此示例将失效，原因在于使用了 `std::getline`（参见 <> 章节中的警告）。 +我们可以通过从行序列中提取_多个_JSON值来进一步复杂化此示例。 [source] ---- include::../../../test/doc_parsing.cpp[tag=doc_parsing_10,indent=0] ---- -我们可以通过从行序列中提取_多个_JSON值来进一步复杂化此示例。 +We can complicate the example further by extracting _several_ JSON values from the sequence of lines. [source] ---- diff --git a/doc/pages/io/serializing_zh_Hans.adoc b/doc/pages/io/serializing_zh_Hans.adoc index 45cd9f8..0f3c56b 100644 --- a/doc/pages/io/serializing_zh_Hans.adoc +++ b/doc/pages/io/serializing_zh_Hans.adoc @@ -12,39 +12,41 @@ Official repository: https://github.com/boostorg/json 序列化是指将内存中由<>表示的JSON文档转换为字符序列的过程。该库提供以下用于序列化的自由函数和类型： -.序列化函数和类型 +.Serialization Functions and Types |=== -|Name|描述 +|Name|Description | <> -| 将 <>、<>、<> 或 <> 序列化到 {std_ostream}。 +| Serialize a <>, <>, <>, or <> +.序列化函数和类型 |=== |Name|描述 | <> -| 返回一个 {std_string}，表示序列化后的 <>、<>、<> 或 <>。 +| Return a {std_string} representing a serialized <>, <>, +为便于调试和输出，库中的容器类型可通过流操作符写入标准输出流： | <> -| 一个有状态的对象，可用于高效地序列化一个或多个 <>、<>、<> 或 <> 的实例。 -|=== +| A stateful object which may be used to efficiently serialize one or more +<> 函数将一个 <> 转换为 {std_string}： -为便于调试和输出，库中的容器类型可通过流操作符写入标准输出流： +在完整序列化一个 <> 效率低下甚至不可行的情况下，可使用 <> 对其进行逐步序列化。这样做有多种原因，例如避免缓冲整个输出，或确保每个周期执行固定量的工作。<> 的实例通过内部动态分配的结构维护输出状态，并提供接口，将序列化输出的连续缓冲区写入调用方提供的缓冲区中。以下示例展示了如何使用 <> 来实现 <>： [source] ---- include::../../../test/doc_serializing.cpp[tag=doc_serializing_1,indent=0] ---- -<> 函数将一个 <> 转换为 {std_string}： +与解析器类似，序列化器可通过调用 <> 重复使用。这会将对象重置为序列化新实例的状态，并保留先前分配的内存，从而在序列化多个变量时提升性能。 [source] ---- include::../../../test/doc_serializing.cpp[tag=doc_serializing_2,indent=0] ---- -在完整序列化一个 <> 效率低下甚至不可行的情况下，可使用 <> 对其进行逐步序列化。这样做有多种原因，例如避免缓冲整个输出，或确保每个周期执行固定量的工作。<> 的实例通过内部动态分配的结构维护输出状态，并提供接口，将序列化输出的连续缓冲区写入调用方提供的缓冲区中。以下示例展示了如何使用 <> 来实现 <>： +In situations where serializing a <> in its entirety is inefficient or even impossible, <> can be used to serialize a <> incrementally. This may be done for a variety of reasons, such as to avoid buffering the entire output, or to ensure that a fixed amount of work is performed in each cycle. Instances of <> maintain an output state using internal dynamically allocated structures, with an interface to retrieve successive buffers of the serialized output into a caller provided buffer. Here is an example, demonstrating how <> may be implemented using a <>: [source] ---- include::../../../include/boost/json/impl/serialize.ipp[tag=example_operator_lt_lt,indent=0] ---- -与解析器类似，序列化器可通过调用 <> 重复使用。这会将对象重置为序列化新实例的状态，并保留先前分配的内存，从而在序列化多个变量时提升性能。 +As with the parser, the serializer may be reused by calling <>. This sets up the object to serialize a new instance and retains previously allocated memory. This can result in performance improvements when multiple variables are serialized. diff --git a/doc/pages/main_zh_Hans.adoc b/doc/pages/main_zh_Hans.adoc index bbd16ef..a1e5b03 100644 --- a/doc/pages/main_zh_Hans.adoc +++ b/doc/pages/main_zh_Hans.adoc @@ -8,15 +8,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) Official repository: https://github.com/boostorg/json //// -= Boost.JSON -(C) 2019--2020 Vinnie Falco; (C) 2020 Krystian Stasiowski; (C) 2022 Dmitry Arkhipov -:idprefix: -:sectanchors: -:toclevels: 2 -:toc: left -:pagelevels: 2 -:source-highlighter: rouge -:source-language: c++ += Boost.JSON (C) 2019--2020 Vinnie Falco; (C) 2020 Krystian Stasiowski; (C) 2022 Dmitry Arkhipov :idprefix: :sectanchors: :toclevels: 2 :toc: left :pagelevels: 2 :source-highlighter: rouge :source-language: c++ include::definitions.adoc[] @@ -24,16 +16,6 @@ include::../../README.adoc[] :leveloffset: +1 -include::quick_look.adoc[] -include::dom/overview.adoc[] -include::allocators/overview.adoc[] -include::io/overview.adoc[] -include::conversion/overview.adoc[] -include::examples.adoc[] -include::faq.adoc[] -include::benchmarks.adoc[] -include::comparison.adoc[] -include::reference.adoc[] -include::../../CHANGELOG.adoc[] +include::quick_look.adoc[] include::dom/overview.adoc[] include::allocators/overview.adoc[] include::io/overview.adoc[] include::conversion/overview.adoc[] include::examples.adoc[] include::faq.adoc[] include::benchmarks.adoc[] include::comparison.adoc[] include::reference.adoc[] include::../../CHANGELOG.adoc[] :leveloffset: -1 diff --git a/doc/pages/quick_look_zh_Hans.adoc b/doc/pages/quick_look_zh_Hans.adoc index acc8965..7c2b5c4 100644 --- a/doc/pages/quick_look_zh_Hans.adoc +++ b/doc/pages/quick_look_zh_Hans.adoc @@ -9,8 +9,7 @@ Official repository: https://github.com/boostorg/json //// [pagelevels=1,toclevels=1] -= 快速浏览 -这里我们通过示例代码重点介绍重要特性，以帮助理解接口风格。首先包含库头文件，该文件将所有符号引入作用域；或者，也可以包含单独的头文件以获取特定类型的声明： += 快速浏览 这里我们通过示例代码重点介绍重要特性，以帮助理解接口风格。首先包含库头文件，该文件将所有符号引入作用域；或者，也可以包含单独的头文件以获取特定类型的声明： [source] ---- @@ -26,7 +25,8 @@ Official repository: https://github.com/boostorg/json [NOTE] ==== -文中所使用的示例代码和标识符均假定以下声明已生效： +Sample code and identifiers used throughout are written as if the following +declarations are in effect: [source] ---- @@ -39,7 +39,7 @@ using namespace boost::json; == 值 假设您要在容器中重建一下 JSON 对象： -[source, json] +[source,json] ---- { "pi": 3.141, diff --git a/doc/pages/reference_zh_Hans.adoc b/doc/pages/reference_zh_Hans.adoc index d294480..6c6259f 100644 --- a/doc/pages/reference_zh_Hans.adoc +++ b/doc/pages/reference_zh_Hans.adoc @@ -7,91 +7,28 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) Official repository: https://github.com/boostorg/json //// -[#ref, pagelevels=3,toclevels=1] +[#ref,pagelevels=3,toclevels=1] = 参考 [cols=4*a,autowidth] |=== 4+|JSON -a| *类* + -<> + -<> + -<> + -<> + -<> + -<> + -<> + -<> + -<> + -<> + -<> + -<> + -<> + -<> + -<> + -<> + -<> +a| *类* + <> + <> + <> + <> + <> + <> + <> + <> + <> + <> + <> + <> + <> + <> + <> + <> + <> -a| *函数* + -<> + -<> + -<> + -<> + -<> + -<> + -<> + -<> + -<> + -<> + -<> + -<> +a| *函数* + <> + <> + <> + <> + <> + <> + <> + <> + <> + <> + <> + <> -*P0308R0* + -<> + -<> + -<> +*P0308R0* + <> + <> + <> -| *运算符* + -<> + -<> + -<> + -<> + -<> + -<> + -<> + +| *Operators* + +<> + <> + <> + <> + <> + <> + <> + -*别名* + -<> + -<> +*别名* + <> + <> -*常量* + -<> + -<> + -<> + -<> + -<> + -<> + -<> +*常量* + <> + <> + <> + <> + <> + <> + <> -| *类型特征* + -<> + -<> + -<> + -<> + -<> + -<> + -<> + -<> + -<> + -<> + -<> + -<> + -<> + -<> + -<> + -<> + -<> +| *Type Traits* + +<> + <> + <> + <> + <> + <> + <> + <> + <> + <> + <> + <> + <> + <> + <> + <> + <> |===