From 6be974c3bb8d4dfe03fc3ec6fb25665ef332609d Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Wed, 22 Apr 2026 22:10:45 +0000 Subject: [PATCH 01/68] Added translation using Weblate (Chinese (Simplified Han script)) --- doc/library-detail_zh_Hans.adoc | 128 ++++++++++++++++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 doc/library-detail_zh_Hans.adoc diff --git a/doc/library-detail_zh_Hans.adoc b/doc/library-detail_zh_Hans.adoc new file mode 100644 index 0000000..7ff837c --- /dev/null +++ b/doc/library-detail_zh_Hans.adoc @@ -0,0 +1,128 @@ +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 +.... + +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 +.... + +==== 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) From cca70eba25751d066ae552d21a60d71aa3ace48a Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Wed, 22 Apr 2026 22:11:07 +0000 Subject: [PATCH 02/68] Added translation using Weblate (Chinese (Simplified Han script)) --- doc/pages/reference_zh_Hans.adoc | 98 ++++++++++++++++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 doc/pages/reference_zh_Hans.adoc diff --git a/doc/pages/reference_zh_Hans.adoc b/doc/pages/reference_zh_Hans.adoc new file mode 100644 index 0000000..a0c60c6 --- /dev/null +++ b/doc/pages/reference_zh_Hans.adoc @@ -0,0 +1,98 @@ +//// +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 +//// + +[#ref, pagelevels=3,toclevels=1] += Reference + +[cols=4*a,autowidth] +|=== +4+|JSON + +a| *Classes* + +<> + +<> + +<> + +<> + +<> + +<> + +<> + +<> + +<> + +<> + +<> + +<> + +<> + +<> + +<> + +<> + +<> + +a| *Functions* + +<> + +<> + +<> + +<> + +<> + +<> + +<> + +<> + +<> + +<> + +<> + +<> + +*P0308R0* + +<> + +<> + +<> + +| *Operators* + +<> + +<> + +<> + +<> + +<> + +<> + +<> + + +*Aliases* + +<> + +<> + +*Constants* + +<> + +<> + +<> + +<> + +<> + +<> + +<> + +| *Type Traits* + +<> + +<> + +<> + +<> + +<> + +<> + +<> + +<> + +<> + +<> + +<> + +<> + +<> + +<> + +<> + +<> + +<> + +|=== + +include::{entities-file}[leveloffset=+1] From f4492679d6aacc5bd975c8c9b8b10606135e5585 Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Wed, 22 Apr 2026 22:11:22 +0000 Subject: [PATCH 03/68] Added translation using Weblate (Chinese (Simplified Han script)) --- doc/pages/quick_look_zh_Hans.adoc | 217 ++++++++++++++++++++++++++++++ 1 file changed, 217 insertions(+) create mode 100644 doc/pages/quick_look_zh_Hans.adoc diff --git a/doc/pages/quick_look_zh_Hans.adoc b/doc/pages/quick_look_zh_Hans.adoc new file mode 100644 index 0000000..4a79f31 --- /dev/null +++ b/doc/pages/quick_look_zh_Hans.adoc @@ -0,0 +1,217 @@ +//// +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 +//// + +[pagelevels=1,toclevels=1] += Quick Look +Here we highlight important features through example code to help convey the style of the interface. We begin by including the library header file which brings all the symbols into scope. Alternatively, individual headers may be included to obtain the declarations for specific types: + +[source] +---- +#include +---- + +In order to link your program you will need to link with a built library. Alternatively you can use the header-only configuration simply by including this header file in any __one__ of your new or existing source files: + +[source] +---- +#include +---- + +[NOTE] +==== +Sample code and identifiers used throughout are written as if the following declarations are in effect: + +[source] +---- +#include +using namespace boost::json; +---- +==== + +[#quick_look_values] +== Values +Say you want to recreate this JSON object in a container: + +[source, json] +---- +{ + "pi": 3.141, + "happy": true, + "name": "Boost", + "nothing": null, + "answer": { + "everything": 42 + }, + "list": [1, 0, 2], + "object": { + "currency": "USD", + "value": 42.99 + } +} +---- + +In this library the types <>, <>, and <> hold JSON arrays, objects, and strings respectively while the type <> is a special variant which can hold any JSON element. Here we construct an empty object and then insert the elements above: + +[source] +---- +include::../../test/doc_quick_look.cpp[tag=doc_quick_look_1] +---- + +While keys are strings, the mapped type of objects and the element type of arrays is the aforementioned type <> which can hold any JSON element, as seen in the previous assignments. Instead of building the JSON document using a series of function calls, we can build it in one statement using an initializer list: + +[source] +---- +include::../../test/doc_quick_look.cpp[tag=doc_quick_look_2] +---- + +When a <>, <>, or <> is assigned or constructed from an initializer list, the creation of the new value happens only once. This makes initializer lists equally efficient as using the other ways to create a value. The types in this library are first-class, supporting copy and move construction and assignment: + +[source] +---- +include::../../test/doc_quick_look.cpp[tag=doc_quick_look_3] +---- + +[#quick_look_allocators] +== Allocators +To permit custom memory allocation strategies, these containers all allow construction with a <> which is a smart pointer to a {ref_memory_resource}. The constructor signatures have the same ordering as their `std` equivalents which use {req_Allocator} parameters. Once a container is constructed its memory resource can never change. Here we create an array without performing any dynamic allocations: + +[source] +---- +include::../../test/doc_quick_look.cpp[tag=doc_quick_look_4] +---- + +The containers in this library enforce the invariant that every element of the container will use the same memory resource: + +[source] +---- +include::../../test/doc_quick_look.cpp[tag=doc_quick_look_5] +---- + +When a library type is used as the element type of a PMR container; that is, a container which uses a {ref_polymorphic_allocator}, the memory resource will automatically propagate to the type and all of its children: + +[source] +---- +include::../../test/doc_quick_look.cpp[tag=doc_quick_look_6] +---- + +Up until now we have shown how values may be constructed from a memory resource pointer, where ownership is not transferred. In this case the caller is responsible for ensuring that the lifetime of the resource is extended for the life of the container. Sometimes you want the container to acquire shared ownership of the resource. This is accomplished with <>: + +[source] +---- +include::../../test/doc_quick_look.cpp[tag=doc_quick_look_7] +---- + +A counted memory resource will not be destroyed until every container with shared ownership of the resource is destroyed. + +[#quick_look_parsing] +== Parsing +JSON can be parsed into the value container in one step using a free function. In the following snippet, a parse error is indicated by a thrown exception: + +[source] +---- +include::../../test/doc_quick_look.cpp[tag=doc_quick_look_8] +---- + +Error codes are also possible: + +[source] +---- +include::../../test/doc_quick_look.cpp[tag=doc_quick_look_9] +---- + +By default, the parser is strict and only accepts JSON compliant with the standard. However this behavior can be relaxed by filling out an options structure enabling one or more extensions. Here we use a static buffer and enable two non-standard extensions: + +[source] +---- +include::../../test/doc_quick_look.cpp[tag=doc_quick_look_10] +---- + +The parser in this library implements a https://en.wikipedia.org/wiki/Online_algorithm[__streaming algorithm__]; it can process JSON piece-by-piece, without the requirement that the entire input is available from the start. The parser uses a temporary memory allocation to do its work. If you plan on parsing multiple JSONs, for example in a network server, keeping the same parser instance will allow re-use of this temporary storage, improving performance. + +[source] +---- +include::../../test/doc_quick_look.cpp[tag=doc_quick_look_11] +---- + +With strategic use of the right memory resources, parser instance, and calculated upper limits on buffer sizes, it is possible to parse and examine JSON without __any__ dynamic memory allocations. This is explored in more detail in a later section. + +[#quick_look_serializing] +== Serializing +Simple free functions are provided for serializing a <> to a {std_string} containing JSON: + +[source] +---- +include::../../test/doc_quick_look.cpp[tag=doc_quick_look_12] +---- + +The serializer in this library implements a https://en.wikipedia.org/wiki/Online_algorithm[__streaming algorithm__]; it can output JSON a piece at a time, without the requirement that the entire output area is allocated at once: + +[source] +---- +include::../../test/doc_quick_look.cpp[tag=doc_quick_look_13] +---- + +[#quick_look_conversion] +== Value Conversion +Given a user-defined type: + +[source] +---- +include::../../test/doc_quick_look.cpp[tag=doc_quick_look_14] +---- + +We can define a conversion from the user-defined type to a <> by defining an overload of `tag_invoke` in the same namespace. This maps `customer` to a JSON object: + +[source] +---- +include::../../test/doc_quick_look.cpp[tag=doc_quick_look_15] +---- + +This allows us to use the library function <> to produce a <> from our type: + +[source] +---- +include::../../test/doc_quick_look.cpp[tag=doc_quick_look_16] +---- + +The library knows what to do with standard containers. Here we convert an array of customers to a value: + +[source] +---- +include::../../test/doc_quick_look.cpp[tag=doc_quick_look_17] +---- + +To go from JSON to a user-defined type we use <>, which uses another overload of `tag_invoke`. This converts a JSON value to a `customer`. It throws an exception if the contents of the value do not match what is expected: + +[source] +---- +include::../../test/doc_quick_look.cpp[tag=doc_quick_look_18] +---- + +The code above defines the convenience function `extract`, which deduces the types of the struct members. This works, but requires that the struct is {req_DefaultConstructible}. An alternative is to construct the object directly, which is a little more verbose but doesn't require default construction: + +[source] +---- +include::../../test/doc_quick_look.cpp[tag=doc_quick_look_19] +---- + +Now we can construct customers from JSON: + +[source] +---- +include::../../test/doc_quick_look.cpp[tag=doc_quick_look_20] +---- + +The library's generic algorithms recognize when you are converting a <> to a container which resembles an array or object, so if you wanted to turn a JSON array into a vector of customers you might write: + +[source] +---- +include::../../test/doc_quick_look.cpp[tag=doc_quick_look_21] +---- From 320547c2ed0e194d0efcf5423e47f7de9446e9b9 Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Wed, 22 Apr 2026 22:11:27 +0000 Subject: [PATCH 04/68] Added translation using Weblate (Chinese (Simplified Han script)) --- doc/pages/main_zh_Hans.adoc | 39 +++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 doc/pages/main_zh_Hans.adoc diff --git a/doc/pages/main_zh_Hans.adoc b/doc/pages/main_zh_Hans.adoc new file mode 100644 index 0000000..bbd16ef --- /dev/null +++ b/doc/pages/main_zh_Hans.adoc @@ -0,0 +1,39 @@ +//// +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 +//// + += 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[] + +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[] + +:leveloffset: -1 From 6466528ee5dc6cb3ea4315b05fb968aeb7887f08 Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Wed, 22 Apr 2026 22:11:34 +0000 Subject: [PATCH 05/68] Added translation using Weblate (Chinese (Simplified Han script)) --- doc/pages/faq_zh_Hans.adoc | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 doc/pages/faq_zh_Hans.adoc diff --git a/doc/pages/faq_zh_Hans.adoc b/doc/pages/faq_zh_Hans.adoc new file mode 100644 index 0000000..a1cb527 --- /dev/null +++ b/doc/pages/faq_zh_Hans.adoc @@ -0,0 +1,21 @@ +//// +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 +//// + += Frequently Asked Questions + +"Isn't simdjson faster?":: These libraries are not comparable. The output of the simdjson parser is a read-only structure. In other words, it can't be changed, and the only way to create one is by parsing a JSON string. On the other hand, Boost.JSON allows you to modify the container holding the parsed JSON, or even build a JSON document from scratch through the container interface. + +"Why not use a standard {req_Allocator}?:: Using standard allocators would 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. + +"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}. + + +"Why <> instead of {std_string}?":: The string provided by the 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 <>. From 6d6fd22ec928570b987c5ca1950829849daf6aec Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Wed, 22 Apr 2026 22:11:43 +0000 Subject: [PATCH 06/68] Added translation using Weblate (Chinese (Simplified Han script)) --- doc/pages/examples_zh_Hans.adoc | 41 +++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 doc/pages/examples_zh_Hans.adoc diff --git a/doc/pages/examples_zh_Hans.adoc b/doc/pages/examples_zh_Hans.adoc new file mode 100644 index 0000000..f4e661c --- /dev/null +++ b/doc/pages/examples_zh_Hans.adoc @@ -0,0 +1,41 @@ +//// +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 +//// + +[pagelevels=1] += Examples + +== Pretty + +[source] +---- +include::../../example/pretty.cpp[tag=example_pretty,indent=0] +---- + +[#examples_validate] +== Validate + +[source] +---- +include::../../example/validate.cpp[tag=example_validate,indent=0] +---- + +== Allocator-Aware Conversion + +[source] +---- +include::../../example/use_allocator.cpp[tag=example_use_allocator,indent=0] +---- + +== CBOR + +[source] +---- +include::../../example/cbor.cpp[tag=example_cbor,indent=0] +---- From f5284bc9a657c04bcdd3e77dacea2b356c1dc7eb Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Wed, 22 Apr 2026 22:11:50 +0000 Subject: [PATCH 07/68] Added translation using Weblate (Chinese (Simplified Han script)) --- doc/pages/definitions_zh_Hans.adoc | 44 ++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 doc/pages/definitions_zh_Hans.adoc diff --git a/doc/pages/definitions_zh_Hans.adoc b/doc/pages/definitions_zh_Hans.adoc new file mode 100644 index 0000000..56d6e4d --- /dev/null +++ b/doc/pages/definitions_zh_Hans.adoc @@ -0,0 +1,44 @@ +//// +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 +//// + +: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__]] + +: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`]] From 77c529d083d28a4540431d678c5401fa6541dfe0 Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Wed, 22 Apr 2026 22:11:56 +0000 Subject: [PATCH 08/68] Added translation using Weblate (Chinese (Simplified Han script)) --- doc/pages/comparison_zh_Hans.adoc | 102 ++++++++++++++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 doc/pages/comparison_zh_Hans.adoc diff --git a/doc/pages/comparison_zh_Hans.adoc b/doc/pages/comparison_zh_Hans.adoc new file mode 100644 index 0000000..bac951c --- /dev/null +++ b/doc/pages/comparison_zh_Hans.adoc @@ -0,0 +1,102 @@ +//// +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 +//// + +[#comparison, pagelevels=1,toclevels=1] += Comparison to Other Libraries + +:icon_good: pass:q[[.green]##✔##] +:icon_bad: pass:q[[.red]##✘##] + +There exist many C++ JSON libraries, but two are particularly noteworthy for the purpose of comparison: https://rapidjson.org/[RapidJSON], https://nlohmann.github.io/json/[JSON for Modern {cpp}] (referred to herein as nlohmann's JSON, or nlohmann), and https://github.com/lemire/simdjson[SIMD JSON]. + +== Comparison to nlohmann JSON + +Value Type: https://github.com/nlohmann/json/blob/00cb98a3d170161711ab912ae6acefba31f29f75/include/nlohmann/json.hpp#L165[`nlohmann::basic_json`] + +[source] +---- +template< + template class ObjectType, + template class ArrayType, + class StringType, + class BooleanType, + class NumberIntegerType, + class NumberUnsignedType, + class NumberFloatType, + template class AllocatorType, + template class JSONSerializer + > +class basic_json +{ +private: + .... + friend ::nlohmann::detail::parser; + friend ::nlohmann::detail::serializer; +... +---- + +This library adopts a "kitchen sink" approach. It contains a wealth of features, even those with niche uses. Its weakness is that the many template parameters, while allowing for configurability, inhibit the best possible optimizations. The consequence is that the library performs poorly. The ability to configure every aspect of the value type has the paradoxical effect of making it less suitable as a vocabulary type. + +* {icon_bad} `basic_json` is a class template. Libraries must agree on the choices of template parameters to be interoperable. + +* {icon_bad} Too much customization. We struggle to see a use case for making `BooleanType` anything other than `bool`. + +* {icon_bad} Poor separation of concerns. The `basic_json` container declaration needlessly conflates parsing and serialization APIs. + +* {icon_bad} Limited allocator support. Only stateless allocators are allowed, which rules out the most important type of allocator, a local arena-based implementation. + +* {icon_bad} No incremental parsing, no incremental serialization. + +* {icon_bad} Slow parsing and serialization performance. + +* {icon_good} Full-featured, including JSON Pointer, CBOR, and others. + +== Comparison to RapidJSON + +Value Type: https://github.com/Tencent/rapidjson/blob/bb5f966b9939d6cdfbac3462a0410e185099b3af/include/rapidjson/document.h#L608[`rapidjson::GenericValue`] + +[source] +---- +template > +class GenericValue; + +template +class GenericArray; + +template +class GenericObject; +---- + +* {icon_bad} The value type is not regular. Assignment is destructive, performing `a = b` is equivalent to `a = std::move(b)`. No copy construction or copy assignment allowed. + +* {icon_bad} Object types have no hash table or index to reduce the cost of lookups. + +* {icon_bad} Allocators have reference semantics. Problems with lifetime are easily encountered. + +* {icon_bad} The interface of the array and object types are considerably different from their standard library equivalents, and not idiomatic. + +* {icon_bad} No incremental parsing, no incremental serialization. + +* {icon_good} Parsing and serialization performance is better than most other libraries. + +=== Comparison to SIMD JSON + +[source] +---- +class ParsedJson; +---- + +This is quite an interesting data structure, which is optimized to work well with the SIMD parser. It makes very good design choices for the intended use-case. However it is not well suited as a vocabulary type due to the necessary limitations. + +* {icon_bad} Sequential access only, via `ParsedJson::BasicIterator` + +* {icon_bad} Read-only, can only be populated by the provided SIMD JSON parser. + +* {icon_good} The fastest available JSON parser. From ba86f6a3ac883021ea3bfa0aef419260c2544ed5 Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Wed, 22 Apr 2026 22:12:06 +0000 Subject: [PATCH 09/68] Added translation using Weblate (Chinese (Simplified Han script)) --- doc/pages/benchmarks_zh_Hans.adoc | 215 ++++++++++++++++++++++++++++++ 1 file changed, 215 insertions(+) create mode 100644 doc/pages/benchmarks_zh_Hans.adoc diff --git a/doc/pages/benchmarks_zh_Hans.adoc b/doc/pages/benchmarks_zh_Hans.adoc new file mode 100644 index 0000000..aa94aca --- /dev/null +++ b/doc/pages/benchmarks_zh_Hans.adoc @@ -0,0 +1,215 @@ +//// +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 +//// + +[pagelevels=1,toclevels=1] += Benchmarks +This section compares the performance of Boost.JSON with two widely used libraries with similar functionality: RapidJSON which is known for its performance, and JSON for Modern C++ which is known for feature-richness. The bench program measures the throughput of parsing and serialization for the a set of JSON representing typical workloads. These implementations are evaluated: + +.Implementations +|=== +|Name|Description + +| *boost(pool)* +| Parses the input using a <>, + which is optimized for parsing without subsequent + modification. + The <> object is reused between + trials, allowing temporary memory allocated by the + implementation to persist and improve performance. + +| *boost* +| 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)* +| 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* +| 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* +| 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. +|=== + +== Methodology +The input files are all loaded first. Then each configuration is run for a sufficient number of trials to last at least 5 seconds. The elapsed time, number of invocations (of parse or serialize), and bytes transferred are emitted as a sample along with a calculation of throughput expressed in megabytes per second. Several samples (currently five) are generated for each configuration. All but the median two samples are discarded, with the remaining samples averaged to produce a single number which is reported as the benchmark result. + +The input files, available in the bench/data directory, are laid out thusly: + +.Input Files +|=== +|Name|Size|Description + +| <> +| 125KB +| Data from the Apache Jenkins installation. + +| <> +| 2.2MB +| The largest file, containing a large number of 2-element arrays holding + floating-point coordinate pairs. + +| <> +| 1.69MB +| A large JSON with a variety of nesting, types, and lengths. + +| <> +| 64KB +| An export of data from the Github Events API. + +| <> +| 3.25MB +| Google Summer of Code 2018 data. + +| <> +| 216KB +| An array of large objects. + +| <> +| 2.91MB +| A three.js example model serialized to JSON. + +| <> +| 707KB +| A JSON representing a 3D mesh. Contains many floating-point numbers. + +| <> +| 1.54MB +| mesh.json with whitespace added. + +| <> +| 147KB +| A array containing only floating-point numbers. + +| <> +| 499KB +| A JSON with lots of Cyrillic characters. + +| <> +| 617KB +| An export of data from Twitter's API. + +| <> +| 550KB +| twitter.json with whitespace removed and non-ASCII characters replaced with + Unicode escapes. + +| <> +| 521KB +| An export of data from Twitter's API. +|=== + +Hardware used for testing: **Intel(R) Core(TM) i7-7700K CPU @ 4.20GHz**, Windows 10, 32GB RAM. + +Compilers and optimization flags: gcc 8.1 (-O3), clang 12.0 (-O3), and msvc 19.26 (/O2). + +== Parsing + +=== Parse apache_builds.json +image::images/parse_apache_builds.png[width=668,align="left"] + +=== Parse canada.json +image::images/parse_canada.png[width=668,align="left"] + +=== Parse citm_catalog.json +image::images/parse_citm_catalog.png[width=668,align="left"] + +=== Parse github_events.json +image::images/parse_github_events.png[width=668,align="left"] + +=== Parse gsoc-2018.json +image::images/parse_gsoc_2018.png[width=668,align="left"] + +=== Parse instruments.json +image::images/parse_instruments.png[width=668,align="left"] + +=== Parse marine_ik.json +image::images/parse_marine_ik.png[width=668,align="left"] + +=== Parse mesh.json +image::images/parse_mesh.png[width=668,align="left"] + +=== Parse mesh.pretty.json +image::images/parse_mesh_pretty.png[width=668,align="left"] + +=== Parse numbers.json +image::images/parse_numbers.png[width=668,align="left"] + +=== Parse random.json +image::images/parse_random.png[width=668,align="left"] + +=== Parse twitter.json +image::images/parse_twitter.png[width=668,align="left"] + +=== Parse twitterescaped.json +image::images/parse_twitterescaped.png[width=668,align="left"] + +=== Parse update-center.json +image::images/parse_update_center.png[width=668,align="left"] + +== Serialization + +=== Serialize canada.json +image::images/serialize_canada.png[width=668,align="left"] + +=== Serialize citm_catalog.json +image::images/serialize_citm_catalog.png[width=668,align="left"] + +=== Serialize github_events.json +image::images/serialize_github_events.png[width=668,align="left"] + +=== Serialize gsoc-2018.json +image::images/serialize_gsoc_2018.png[width=668,align="left"] + +=== Serialize instruments.json +image::images/serialize_instruments.png[width=668,align="left"] + +=== Serialize marine_ik.json +image::images/serialize_marine_ik.png[width=668,align="left"] + +=== Serialize mesh.json +image::images/serialize_mesh.png[width=668,align="left"] + +=== Serialize mesh.pretty.json +image::images/serialize_mesh_pretty.png[width=668,align="left"] + +=== Serialize numbers.json +image::images/serialize_numbers.png[width=668,align="left"] + +=== Serialize random.json +image::images/serialize_random.png[width=668,align="left"] + +=== Serialize twitter.json +image::images/serialize_twitter.png[width=668,align="left"] + +=== Serialize twitterescaped.json +image::images/serialize_twitterescaped.png[width=668,align="left"] + +=== Serialize update-center.json +image::images/serialize_update_center.png[width=668,align="left"] From c6b90c980dde22264a5a3b954726eb49dc2344c6 Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Wed, 22 Apr 2026 22:12:11 +0000 Subject: [PATCH 10/68] Added translation using Weblate (Chinese (Simplified Han script)) --- doc/pages/io/serializing_zh_Hans.adoc | 53 +++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 doc/pages/io/serializing_zh_Hans.adoc diff --git a/doc/pages/io/serializing_zh_Hans.adoc b/doc/pages/io/serializing_zh_Hans.adoc new file mode 100644 index 0000000..5ac2d2b --- /dev/null +++ b/doc/pages/io/serializing_zh_Hans.adoc @@ -0,0 +1,53 @@ +//// +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 +//// + += Serializing + +Serialization is the process where a JSON document represented in memory by a <> is turned into a sequence of characters. The library provides the following free functions and types for serialization: + +.Serialization Functions and Types +|=== +|Name|Description + +| <> +| Serialize a <>, <>, <>, or <> + to a {std_ostream}. + +| <> +| Return a {std_string} representing a serialized <>, <>, + <>, or <>. + +| <> +| A stateful object which may be used to efficiently serialize one or more + instances of <>, <>, <>, or <>. +|=== + +To facilitate debugging and ease of output, library container types may be written to standard output streams using the stream operator: + +[source] +---- +include::../../../test/doc_serializing.cpp[tag=doc_serializing_1,indent=0] +---- + +The <> function converts a <> into a {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. From 08df0df52ed8381cdae33bac05257719bc0f88cd Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Wed, 22 Apr 2026 22:12:32 +0000 Subject: [PATCH 11/68] Added translation using Weblate (Chinese (Simplified Han script)) --- doc/pages/io/parsing_zh_Hans.adoc | 189 ++++++++++++++++++++++++++++++ 1 file changed, 189 insertions(+) create mode 100644 doc/pages/io/parsing_zh_Hans.adoc diff --git a/doc/pages/io/parsing_zh_Hans.adoc b/doc/pages/io/parsing_zh_Hans.adoc new file mode 100644 index 0000000..4b2d142 --- /dev/null +++ b/doc/pages/io/parsing_zh_Hans.adoc @@ -0,0 +1,189 @@ +//// +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 +//// + +[pagelevels=1] += Parsing +Parsing is the process where a serialized JSON text is validated and decomposed into elements. The library provides these functions and types to assist with parsing: + +.Parsing Functions and Types +|=== +|Name|Description + +| <> +| A SAX push parser implementation which converts a serialized JSON text into + a series of member function calls to a user provided handler. This allows + custom behaviors to be implemented for representing the document in memory. + +| <> +| A structure used to select which extensions are enabled during parsing. + +| <> +| Parse a string containing a complete serialized JSON text, and return + a <>. + +| <> +| A stateful DOM parser object which may be used to efficiently parse a series + of JSON texts each contained in a single contiguous character buffer, + returning each result as a <>. + +| <> +| A stateful DOM parser object which may be used to efficiently parse a series + of JSON texts incrementally, returning each result as a <>. + +| <> +| A low level building block used for efficiently building a <>. The + parsers use this internally, and users may use it to adapt foreign parsers to + produce this library's containers. +|=== + +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] +---- + +Alternatively, an {ref_error_code} can be used: + +[source] +---- +include::../../../test/doc_parsing.cpp[tag=doc_parsing_2,indent=0] +---- + +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] +---- + +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] +---- +include::../../../test/doc_parsing.cpp[tag=doc_parsing_4,indent=0] +---- + +== Non-Standard JSON +Unless otherwise specified, the parser in this library is strict. It recognizes only valid, standard JSON. The parser can be configured to allow certain non-standard extensions by filling in a <> structure and passing it by value. By default all extensions are disabled: + +[source] +---- +include::../../../test/doc_parsing.cpp[tag=doc_parsing_5,indent=0] +---- + +When building with {cpp}20 or later, the use of https://en.cppreference.com/w/cpp/language/aggregate_initialization#Designated_initializers[designated initializers] with <> is possible: + +[source] +---- +include::../../../test/doc_parsing.cpp[tag=doc_parsing_6,indent=0] +---- + +When `allow_invalid_utf16` is enabled, the parser will not throw an error in the case of illegal leading, trailing, or half a surrogate. Instead, it will replace the invalid UTF-16 code point(s) with the Unicode replacement character. + +[source] +---- +include::../../../test/doc_parsing.cpp[tag=doc_parsing_15,indent=0] +---- + +CAUTION: When enabling comment support take extra care not to drop whitespace when reading the input. For example, `std::getline` removes the endline characters from the string it produces. + +== Full Precision Number Parsing +The default algorithm that the library uses to parse numbers is fast, but may result in slight precision loss. This may not be suitable for some applications, so there is an option to enable an alternative algorithm that doesn't have that flaw, but is somewhat slower. To do this, you also need to use <> structure. + +[source] +---- +include::../../../test/doc_parsing.cpp[tag=doc_parsing_precise,indent=0] +---- + +Note that full precision number parsing requires the algorithm to see the full number. This means, that when used with <>, additional memory allocations may be necessary to store the number parts which were so far accepted by the parser. The library does try its best to avoid such allocations. + +== Parser +Instances of <> and <> offer functionality beyond what is available when using the <> free functions: + +* More control over memory +* Streaming API, parse input JSON incrementally +* Improved performance when parsing multiple JSON texts +* Ignore non-JSON content after the end of a JSON text + +The parser implementation uses temporary storage space to accumulate values during parsing. When using the <> free functions, this storage is allocated and freed in each call. However, by declaring an instance of <> or <>, this temporary storage can be reused when parsing more than one JSON text, reducing the total number of dynamic memory allocations. + +To use the <>, declare an instance. Then call <> once with the buffer containing representing the input JSON. Finally, call <> to take ownership of the resulting <> upon success. This example persists the parser instance in a class member to reuse across calls: + +[source] +---- +include::../../../test/doc_parsing.cpp[tag=doc_parsing_7,indent=0] +---- + +Sometimes a protocol may have a JSON text followed by data that is in a different format or specification. The JSON portion can still be parsed by using the function <>. Upon success, the return value will indicate the number of characters consumed from the input, which will exclude the non-JSON characters: + +[source] +---- +include::../../../test/doc_parsing.cpp[tag=doc_parsing_8,indent=0] +---- + +The parser instance may be constructed with parse options which allow some non-standard JSON extensions to be recognized: + +[source] +---- +include::../../../test/doc_parsing.cpp[tag=doc_parsing_9,indent=0] +---- + +== Streaming Parser +The <> implements a https://en.wikipedia.org/wiki/Online_algorithm[__streaming algorithm__]; it allows incremental processing of large JSON inputs using one or more contiguous character buffers. The entire input JSON does not need to be loaded into memory at once. A network server can use the streaming interface to process incoming JSON in fixed-size amounts, providing these benefits: + +* CPU consumption per I/O cycle is bounded +* Memory consumption per I/O cycle is bounded +* Jitter, unfairness, and latency is reduced +* Less total memory is required to process the full input + +To use the <>, declare an instance. Then call <> zero or more times with successive buffers representing the input JSON. When there are no more buffers, call <>. The function <> returns `true` after a successful call to `write` or `finish` if parsing is complete. + +In the following example a JSON text is parsed from standard input a line at a time. Error codes are used instead. The function <> is used to indicate the end of the input: + +CAUTION: This example will break, if comments are enabled, because of `std::getline` use (see the warning in <> section). + +[source] +---- +include::../../../test/doc_parsing.cpp[tag=doc_parsing_10,indent=0] +---- + +We can complicate the example further by extracting _several_ JSON values from the sequence of lines. + +[source] +---- +include::../../../test/doc_parsing.cpp[tag=doc_parsing_14,indent=0] +---- + +== Controlling Memory +After default construction, or after <> is called with no arguments, the <> produced after a successful parse operation uses the default memory resource. To use a different memory resource, call `reset` with the resource to use. Here we use a <>, which is optimized for parsing but not subsequent modification: + +[source] +---- +include::../../../test/doc_parsing.cpp[tag=doc_parsing_11,indent=0] +---- + +To achieve performance and memory efficiency, the parser uses a temporary storage area to hold intermediate results. This storage is reused when parsing more than one JSON text, reducing the total number of calls to allocate memory and thus improving performance. Upon construction, the memory resource used to perform allocations for this temporary storage area may be specified. Otherwise, the default memory resource is used. In addition to a memory resource, the parser can make use of a caller-owned buffer for temporary storage. This can help avoid dynamic allocations for small inputs. The following example uses a four kilobyte temporary buffer for the parser, and falls back to the default memory resource if needed: + +[source] +---- +include::../../../test/doc_parsing.cpp[tag=doc_parsing_12,indent=0] +---- + +== Avoiding Dynamic Allocations +Through careful specification of buffers and memory resources, it is possible to eliminate all dynamic allocation completely when parsing JSON, for the case where the entire JSON text is available in a single character buffer, as shown here: + +[source] +---- +include::../../../test/doc_parsing.cpp[tag=doc_parsing_13,indent=0] +---- + +== Custom Parsers +Users who wish to implement custom parsing strategies may create their own handler to use with an instance of <>. The handler implements the function signatures required by SAX event interface. In <> example we define the "null" parser, which throws out the parsed results, to use in the implementation of a function that determines if a JSON text is valid. From c46595d90b2b1d16770aa9065f2ad202e2d37bf4 Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Wed, 22 Apr 2026 22:12:37 +0000 Subject: [PATCH 12/68] Added translation using Weblate (Chinese (Simplified Han script)) --- doc/pages/io/overview_zh_Hans.adoc | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 doc/pages/io/overview_zh_Hans.adoc diff --git a/doc/pages/io/overview_zh_Hans.adoc b/doc/pages/io/overview_zh_Hans.adoc new file mode 100644 index 0000000..caadbea --- /dev/null +++ b/doc/pages/io/overview_zh_Hans.adoc @@ -0,0 +1,20 @@ +//// +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 +//// + +[#input_output, pagelevels=2] += Input/Output +The library provides parsing and serialization algorithms to transform JSON to and from the <> container as needed. This is accomplished through free functions and classes, described as follows. + +:leveloffset: +1 + +include::parsing.adoc[] +include::serializing.adoc[] + +:leveloffset: -1 From b83996adc1db875716933e25f1610e03a5dd1fc8 Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Wed, 22 Apr 2026 22:12:46 +0000 Subject: [PATCH 13/68] Added translation using Weblate (Chinese (Simplified Han script)) --- doc/pages/dom/value_zh_Hans.adoc | 228 +++++++++++++++++++++++++++++++ 1 file changed, 228 insertions(+) create mode 100644 doc/pages/dom/value_zh_Hans.adoc diff --git a/doc/pages/dom/value_zh_Hans.adoc b/doc/pages/dom/value_zh_Hans.adoc new file mode 100644 index 0000000..033d574 --- /dev/null +++ b/doc/pages/dom/value_zh_Hans.adoc @@ -0,0 +1,228 @@ +//// +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 +//// + +[#dom_value] += `value` +JSON documents are represented in memory as instances of <>: a {req_Regular} type which satisfies {req_DefaultConstructible}, {req_CopyConstructible}, {req_CopyAssignable}, {req_MoveConstructible}, {req_MoveAssignable}, and many of the requirements of allocator-aware containers. It is implemented as a https://en.wikipedia.org/wiki/Tagged_union[__variant__] internally, and can dynamically store any of the six defined JSON value types: + +* **null**: A https://en.cppreference.com/w/cpp/utility/variant/monostate[__monostate__] value, equivalent to `nullptr`. + +* **boolean**: A boolean: either `true` or `false`. + +* **number**: An integral or floating point value. + +* **string**: A sequence of zero or more Unicode characters, similar to {std_string}. + +* **array**: An ordered list of values, like {std_vector}. + +* **object**: A collection of name/value pairs, also known as an https://en.wikipedia.org/wiki/Associative_array[__associative array__]. + +== Working With Values +A <> constructed from `nullptr` or default constructed represents a null JSON element: + +[source] +---- +include::../../../test/snippets.cpp[tag=snippet_value_1,indent=0] +---- + +The member function <> may be used to query the kind stored in the value. Alternatively, member functions like <> <> may be used to check whether or not the value is a particular kind: + +[source] +---- +include::../../../test/snippets.cpp[tag=snippet_value_2,indent=0] +---- + +Functions like <> actually return a pointer to the object if the value is an object, otherwise they return null. This allows them to be used both in boolean contexts as above, and in assignments or conditional expressions to capture the value of the pointer: + +[source] +---- +include::../../../test/snippets.cpp[tag=snippet_value_3,indent=0] +---- + +After a <> is constructed, its kind can change depending on what is assigned to it, or by calling functions such as <> or <>. If the assignment is successful, in other words it completes without any exceptions then the value is replaced. Otherwise, the value is unchanged. All operations which can fail to modify a value offer the strong exception safety guarantee. + +[source] +---- +include::../../../test/snippets.cpp[tag=snippet_value_4,indent=0] +---- + +The following table shows all of the ways to determine and access the contents of a <>: + +.<> Accessors +[%autowidth, cols=8] +|=== +|Kind +|Representation +|Emplacement +|Kind Test +|Pointer Access +|`result` Access +|Checked Access +|Unchecked Access + +|<> +|<> +|<> +|<> +|<> +|<> +|<> +|<> + +|<> +|<> +|<> +|<> +|<> +|<> +|<> +|<> + +|<> +|<> +|<> +|<> +|<> +|<> +|<> +|<> + +|<> +|https://en.cppreference.com/w/cpp/types/integer[`std::int64_t`] +|<> +|<> +|<> +|<> +|<> +|<> + +|<> +|https://en.cppreference.com/w/cpp/types/integer[`std::uint64_t`] +|<> +|<> +|<> +|<> +|<> +|<> + +|<> +|https://en.cppreference.com/w/cpp/language/types[`double`] +|<> +|<> +|<> +|<> +|<> +|<> + +|<> +|https://en.cppreference.com/w/cpp/language/types[`bool`] +|<> +|<> +|<> +|<> +|<> +|<> + +|<> +|https://en.cppreference.com/w/cpp/language/nullptr[`std::nullptr_t`] +|<> +|<> +^|— +|<> +^|— +^|— + +|=== + +The emplace members of <> return a typed reference to the underlying representation. For example, the call to <> in the previous example returns a <>. This table shows the underlying type for each kind: + +|=== +|Kind|Type|Description + +| <> +| <> +| An associative array of string keys mapping to <> elements with an + interface similar to {std_unordered_map}, that remembers insertion order. + +| <> +| <> +| An ordered list of <> elements with an interface similar to + {std_vector}. + +| <> +| <> +| A https://en.wikipedia.org/wiki/UTF-8[__UTF-8__] encoded + https://en.wikipedia.org/wiki/Unicode[Unicode] + https://en.wikipedia.org/wiki/String_(computer_science)[string] of characters + with an interface similar to {std_string}. + +| <> +| `std::int64_t` +| A 64 bit signed integer. + +| <> +| `std::uint64_t` +| A 64 bit unsigned integer. + +| <> +| `double` +| A `double` holding a floating-point value. + +| <> +| https://en.cppreference.com/w/cpp/keyword/bool[`bool`] +| A `bool` holding `true` or `false`. + +| <> +^| — +| A monostate value representing null. +|=== + +The return value from emplace can be used to perform assignment or to capture a reference to the underlying element for later inspection or modification: + +[source] +---- +include::../../../test/snippets.cpp[tag=snippet_value_5,indent=0] +---- + +If the <> of a <> is known, functions such as <> or <> may be used to obtain a reference to the underlying representation without changing the existing value: + +[source] +---- +include::../../../test/snippets.cpp[tag=snippet_value_6,indent=0] +---- + +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] +---- +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] +---- +include::../../../test/snippets.cpp[tag=snippet_value_8,indent=0] +---- +==== + +Functions returning {ref_result} allow you to use both approaches: + +[source] +---- +include::../../../test/snippets.cpp[tag=snippet_value_9,indent=0] +---- + +=== Formatted Output +When a <> is formatted to a {std_ostream}, the result is serialized JSON as if by calling <>. From 5b3673e26acc78bdcfb43002349f31ac192e1960 Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Wed, 22 Apr 2026 22:12:55 +0000 Subject: [PATCH 14/68] Added translation using Weblate (Chinese (Simplified Han script)) --- doc/pages/dom/string_zh_Hans.adoc | 76 +++++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 doc/pages/dom/string_zh_Hans.adoc diff --git a/doc/pages/dom/string_zh_Hans.adoc b/doc/pages/dom/string_zh_Hans.adoc new file mode 100644 index 0000000..143d788 --- /dev/null +++ b/doc/pages/dom/string_zh_Hans.adoc @@ -0,0 +1,76 @@ +//// +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 +//// + +[#dom_string] += `string` + +Modifiable sequences of characters are represented using objects of type <>. + +The interface and functionality of <> is the same as {std_string} except that: + +* <> is not a class template, +* <> uses `char` as its character type, +* redundant overloads for string operations have been replaced with a <>-based interface, +* access to characters in the range `[size(), capacity())` is permitted, +* <> is used instead of {req_Allocator}, and +* small buffer optimisation is guaranteed, which avoids allocating memory for small strings. + +With augmented interface, operations requiring an input string are implemented as a single overload with a parameter of type <>, and can accept most string-like objects. Objects such as null terminated character pointers, `std::string`, <>, subranges of strings, and objects convertible to <> can all be passed to these functions. + +[source] +---- +include::../../../test/snippets.cpp[tag=snippet_strings_4,indent=0] +---- + +More formally, `std::string` member function overloads that accept any of the following parameter combinations as an input string: + +* a `std::string` parameter, or +* a `std::string` parameter and two `size_type` parameters that specify a substring, or +* a parameter of a type convertible to <>, or +* a parameter of a type convertible to <> and two `size_type` parameters that specify a substring, or +* a `const_pointer` parameter, or +* a parameter of type `const_pointer` and a `size_type` parameter that specifies the length of the string + +are replaced with an overload accepting a <> parameter. + +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] +---- + +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] +---- +include::../../../test/snippets.cpp[tag=snippet_strings_1,indent=0] +---- + +== Formatted Output + +When a <> is formatted to a {std_ostream}, the result is a valid JSON. That is, the result will be double quoted and the contents properly escaped per the JSON specification. + +== Accessing Storage Beyond `size()` + +<> directly supports access to its storage in the range `[size(), capacity())`. This can be used for efficient assembly of a string from several parts. After the string is assembled, use the member function <> to update the string's size and insert the null terminator. For example: + +[source] +---- +include::../../../test/snippets.cpp[tag=snippet_strings_5,indent=0] +---- From 93041213909451ca367e42a1970ffda13f30ef5b Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Wed, 22 Apr 2026 22:13:05 +0000 Subject: [PATCH 15/68] Added translation using Weblate (Chinese (Simplified Han script)) --- doc/pages/dom/overview_zh_Hans.adoc | 61 +++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 doc/pages/dom/overview_zh_Hans.adoc diff --git a/doc/pages/dom/overview_zh_Hans.adoc b/doc/pages/dom/overview_zh_Hans.adoc new file mode 100644 index 0000000..57f0a89 --- /dev/null +++ b/doc/pages/dom/overview_zh_Hans.adoc @@ -0,0 +1,61 @@ +//// +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 +//// + +[#dom] += Document Model +In this library the following types implement containers used to represent JSON data in memory: + +.Container Types +[%autowidth] +|=== +|Type|Description + +| <> +| A sequence container of JSON values supporting dynamic size and fast, random + access. The interface and performance characteristics are similar to + {std_vector}. + +| <> +| An associative container of key-value pairs with unique keys, where the key + is a string and the mapped type is a JSON value. Search, insertion, and + removal have average contant-time complexity. In addition, elements are + stored contiguously in memory allowing cache-friendly iteration. + +| <> +| A contiguous range of characters. The library assumes that the contents of + the string holds only valid UTF-8. + +| <> +| 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] +---- +#include +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 From 8b6bc0b14d4a25fd4270bbd91a06d7ee3c186fab Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Wed, 22 Apr 2026 22:13:16 +0000 Subject: [PATCH 16/68] Added translation using Weblate (Chinese (Simplified Han script)) --- doc/pages/dom/object_zh_Hans.adoc | 73 +++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 doc/pages/dom/object_zh_Hans.adoc diff --git a/doc/pages/dom/object_zh_Hans.adoc b/doc/pages/dom/object_zh_Hans.adoc new file mode 100644 index 0000000..6557eed --- /dev/null +++ b/doc/pages/dom/object_zh_Hans.adoc @@ -0,0 +1,73 @@ +//// +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 +//// + +[#dom_object] += `object` +A <> stores an instance of <> as the underlying representation for a JSON object. Instances of the <> type are associative containers holding key and value pairs, where the key is a <> and the mapped type is a <>. These containers are modelled after standard maps with these properties: + +* The elements are stored contiguously as instances of <>. + +* Iterators are ordinary pointers, and may become invalidated on insertions and removals. + +* The order of insertions is preserved, as long as there are no removals. + +* All inserted values will use the same {ref_memory_resource} as the container itself. + +An empty object may be constructed without incurring any memory allocations using the <>. A <> can also be explicitly specified: + +[source] +---- +include::../../../test/snippets.cpp[tag=snippet_objects_1,indent=0] +---- + +Initializer lists consisting of two-element key value pairs can be used to construct objects with initial contents. These constructors may allocate memory and throw: + +[source] +---- +include::../../../test/snippets.cpp[tag=snippet_objects_2,indent=0] +---- + +Alternatively, elements may be inserted after construction: + +[source] +---- +include::../../../test/snippets.cpp[tag=snippet_objects_3,indent=0] +---- + +Similar to the `std` counterpart, elements may be accessed directly by their key with bounds checking using <>, or without bounds checking using <> which creates a null element if the key does not already exist: + +[source] +---- +include::../../../test/snippets.cpp[tag=snippet_objects_4,indent=0] +---- + +Internally, the container computes a hash table over the keys so that the complexity of lookups is in constant time, on average. + +[WARNING] +==== +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] +---- + +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 <>. + +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. + +== Formatted Output + +When an <> is formatted to a {std_ostream}, the result is a valid JSON. That is, the object will be output with curly braces and a comma separated list of key/value pairs, as per the JSON specification. From 936a38cc0240422c78a23c78c7ba378de7a00fb1 Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Wed, 22 Apr 2026 22:13:27 +0000 Subject: [PATCH 17/68] Added translation using Weblate (Chinese (Simplified Han script)) --- doc/pages/dom/numbers_zh_Hans.adoc | 62 ++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 doc/pages/dom/numbers_zh_Hans.adoc diff --git a/doc/pages/dom/numbers_zh_Hans.adoc b/doc/pages/dom/numbers_zh_Hans.adoc new file mode 100644 index 0000000..94111d3 --- /dev/null +++ b/doc/pages/dom/numbers_zh_Hans.adoc @@ -0,0 +1,62 @@ +//// +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 +//// + +[#dom_numbers] += Numbers +JSON numbers are represented using `std::int64_t`, `std::uint64_t`, and `double`. When a <> is constructed from an unsigned integer, its <> will be `kind::uint64`. Likewise, a <> constructed from a signed integer will have `kind::int64`, or `kind::double_` if constructed from a floating-point type: + +[source] +---- +include::../../../test/doc_using_numbers.cpp[tag=doc_using_numbers_1,indent=0] +---- + +When accessing a number contained within a <>, the function used must match the value's <> exactly; no conversions will be performed. For example if `as_double` is called on a <> that contains a `std::uint64_t`, an exception is thrown. Similarly, the function `if_double` will return `nullptr` and calling `get_double` will result in undefined behavior: + +[source] +---- +include::../../../test/doc_using_numbers.cpp[tag=doc_using_numbers_2,indent=0] +---- + +In cases where you know that a <> contains a number but don't know its <>, `value::to_number` can be used to convert the <> to an arithmetic type: + +[source] +---- +include::../../../test/doc_using_numbers.cpp[tag=doc_using_numbers_3,indent=0] +---- + +If the <> does not contain a number, or if the conversion is to an integer type `T` and the number cannot be represented exactly by `T`, the conversion will fail. Otherwise, the result is the number converted to `T` as-if by `static_cast`: + +[source] +---- +include::../../../test/doc_using_numbers.cpp[tag=doc_using_numbers_4,indent=0] +---- + +In settings where exceptions cannot be used, an overload of `value::to_number` accepting {ref_error_code} can be used instead with identical semantics to its throwing counterpart: + +[source] +---- +include::../../../test/doc_using_numbers.cpp[tag=doc_using_numbers_5,indent=0] +---- + +When parsing a JSON document, the type used to represent a number is not explicitly specified and must be determined from its value. In general, the parser will choose the best type which can accurately store the number as it appears in the document. Integers (i.e. numbers without decimals or exponents) that cannot be represented by `std::uint64_t` and `std::int64_t` will be represented as `double` to preserve their magnitude: + +[source] +---- +include::../../../test/doc_using_numbers.cpp[tag=doc_using_numbers_6,indent=0] +---- + +More formally, if the number: + +* contains a decimal point, or +* contains an exponent, or +* is negative and its value is less than `INT64_MIN`, or +* is positive and its value is greater than `UINT64_MAX`, + +then its type is `double`. Otherwise, if the number is positive and its value is greater than `INT64_MAX`, then its type is `std::uint64_t`. All other numbers are parsed as `std::int64_t`. From 24edc61cb60ff655286a259703e8f721842ba0cc Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Wed, 22 Apr 2026 22:13:37 +0000 Subject: [PATCH 18/68] Added translation using Weblate (Chinese (Simplified Han script)) --- doc/pages/dom/nested_access_zh_Hans.adoc | 45 ++++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 doc/pages/dom/nested_access_zh_Hans.adoc diff --git a/doc/pages/dom/nested_access_zh_Hans.adoc b/doc/pages/dom/nested_access_zh_Hans.adoc new file mode 100644 index 0000000..dd2719a --- /dev/null +++ b/doc/pages/dom/nested_access_zh_Hans.adoc @@ -0,0 +1,45 @@ +//// +Copyright (c) 2022 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 +//// + +[#nested_access] += Accessing Deeply Nested Elements +In order to allow conveniently retrieving and changing deeply nested elements of <> objects the library implements https://datatracker.ietf.org/doc/html/rfc6901[RFC 6901 (JSON Pointer)]: + +[source] +---- +include::../../../test/snippets.cpp[tag=snippet_pointer_1,indent=0] +---- + +This is particularly useful when throwing exceptions is undesirable. For example, compare + +[source] +---- +include::../../../test/snippets.cpp[tag=snippet_pointer_2,indent=0] +---- + +with + +[source] +---- +include::../../../test/snippets.cpp[tag=snippet_pointer_3,indent=0] +---- + +The library also allows changing and adding deeply nested elements. The function <> traverses the value similarly to <>, but additionally, it can create missing elements in certain cases: + +[source] +---- +include::../../../test/snippets.cpp[tag=snippet_pointer_4,indent=0] +---- + +The specific behavior is controlled by an optional parameter of type <>. For example, here's the same example with a different option: + +[source] +---- +include::../../../test/snippets.cpp[tag=snippet_pointer_5,indent=0] +---- From 9f94c739bbfe263eef2ed81b9ee613acca57034d Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Wed, 22 Apr 2026 22:13:44 +0000 Subject: [PATCH 19/68] Added translation using Weblate (Chinese (Simplified Han script)) --- doc/pages/dom/init_lists_zh_Hans.adoc | 87 +++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 doc/pages/dom/init_lists_zh_Hans.adoc diff --git a/doc/pages/dom/init_lists_zh_Hans.adoc b/doc/pages/dom/init_lists_zh_Hans.adoc new file mode 100644 index 0000000..b77ce9d --- /dev/null +++ b/doc/pages/dom/init_lists_zh_Hans.adoc @@ -0,0 +1,87 @@ +//// +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 +//// + += Initializer Lists +Initializer lists can be used to construct or assign a <>: + +[source] +---- +include::../../../test/snippets.cpp[tag=snippet_init_list_1,indent=0] +---- + +Simple initializer lists produce an <>: + +[source] +---- +include::../../../test/snippets.cpp[tag=snippet_init_list_2,indent=0] +---- + +Initializer lists can be nested. Here we construct an array as an element of an array: + +[source] +---- +include::../../../test/snippets.cpp[tag=snippet_init_list_3,indent=0] +---- + +When a two element initializer list is nested within an enclosing initializer list, it is unclear whether it represents an <> or an <>: + +[source] +---- +include::../../../test/snippets.cpp[tag=snippet_init_list_4,indent=0] +---- + +In such cases, if every element consists of a string followed by a single value, then the enclosing initializer list is interpreted as an <>. Otherwise, it is interpreted as an <>. + +[source] +---- +include::../../../test/snippets.cpp[tag=snippet_init_list_5,indent=0] +---- + +To resolve the ambiguity manually, use an explicit constructor: + +[source] +---- +include::../../../test/snippets.cpp[tag=snippet_init_list_6,indent=0] +---- + +Initializer lists can be used to unambiguously construct or assign an <> or <>: + +[source] +---- +include::../../../test/snippets.cpp[tag=snippet_init_list_7,indent=0] +---- + +Similarly, an initializer list for an <> is always interpreted as an <>. In such cases, the initializer list must be a list of key-value pairs. For example, the following code will not compile because `1` is not convertible to a string: + +[source] +---- +object jo = { { 1, 0.39 }, { "venus", 0.72 }, { "earth", 1 } }; +---- + +The requirement for an initializer list to be interpreted as an <> or <> when initializing such an entity only applies to the outermost initializer list; subsequent nested elements will follow the usual ambiguity resolution rules. + +[source] +---- +include::../../../test/snippets.cpp[tag=snippet_init_list_8,indent=0] +---- + +Elements that are rvalues will be moved upon initialization: + +[source] +---- +include::../../../test/snippets.cpp[tag=snippet_init_list_9,indent=0] +---- + +[WARNING] +==== +Do not create variables of type {std_initializer_list}. This may result in temporaries being destroyed before the initializer list is used. +==== + +In all cases, the <> owned by an <>, <>, or <> constructed from an initializer list will be propagated to each element, recursively. From f9d0d1c3d2910ec64902f537bc213c3e0dd977e3 Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Wed, 22 Apr 2026 22:13:53 +0000 Subject: [PATCH 20/68] Added translation using Weblate (Chinese (Simplified Han script)) --- doc/pages/dom/array_zh_Hans.adoc | 47 ++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 doc/pages/dom/array_zh_Hans.adoc diff --git a/doc/pages/dom/array_zh_Hans.adoc b/doc/pages/dom/array_zh_Hans.adoc new file mode 100644 index 0000000..de5deff --- /dev/null +++ b/doc/pages/dom/array_zh_Hans.adoc @@ -0,0 +1,47 @@ +//// +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 +//// + +[#dom_array] += `array` +A <> stores an instance of <> as the underlying representation for a JSON array. Instances of the __array__ type function identically to a {std_vector} of <>. Additionally, all values inserted into the container will use the same <> as the container itself. + +An empty array may be constructed without incurring any memory allocations using the <>. A <> can also be explicitly specified: + +[source] +---- +include::../../../test/snippets.cpp[tag=snippet_arrays_1,indent=0] +---- + +Initializer lists can be used to construct objects with initial contents. These constructors may allocate memory and throw: + +[source] +---- +include::../../../test/snippets.cpp[tag=snippet_arrays_2,indent=0] +---- + +Alternatively, elements may be inserted after construction: + +[source] +---- +include::../../../test/snippets.cpp[tag=snippet_arrays_3,indent=0] +---- + +Similar to its standard library counterpart, elements may be accessed directly by their 0-based index with bounds checking using <>, or without bounds checking using <>: + +[source] +---- +include::../../../test/snippets.cpp[tag=snippet_arrays_4,indent=0] +---- + +For the complete listing of all available member functions and nested types, see the reference page for <>. + +== Formatted Output + +When an <> is formatted to a {std_ostream}, the result is a valid JSON. That is, the array will be output with square brackets and the comma separated list of values, as per the JSON specification. From 99693216f7d6d15d3f4093a8a5bab410f9d01798 Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Wed, 22 Apr 2026 22:14:03 +0000 Subject: [PATCH 21/68] Added translation using Weblate (Chinese (Simplified Han script)) --- doc/pages/conversion/overview_zh_Hans.adoc | 132 +++++++++++++++++++++ 1 file changed, 132 insertions(+) create mode 100644 doc/pages/conversion/overview_zh_Hans.adoc diff --git a/doc/pages/conversion/overview_zh_Hans.adoc b/doc/pages/conversion/overview_zh_Hans.adoc new file mode 100644 index 0000000..bfd315e --- /dev/null +++ b/doc/pages/conversion/overview_zh_Hans.adoc @@ -0,0 +1,132 @@ +//// +Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com) +Copyright (c) 2020 Krystian Stasiowski (sdkrystian@gmail.com) +Copyright (c) 2021 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 +//// + +[#conversion] += Value Conversion +While the <> container makes it easy to create ad-hoc structures, often it is necessary to convert between JSON and user-defined types or types from the standard library. + +The function template <> provides an interface to construct a <> from a type `T`. The function template <> converts in the opposite direction, from a type `T` to <>. Both support a wide variety of different https://en.cppreference.com/w/cpp/language/types[fundamental types], such as `int` or `double`, standard library types, such as `std::string` or `std::vector`, and can be extended to support user-defined types. + +[source] +---- +include::../../../test/snippets.cpp[tag=snippet_conv_1,indent=0] +---- + +For the type `T`, the appropriate conversion approach is chosen from the following list of categories. The first matching category is selected. + +.Conversion categories +[%autowidth, cols=4] +|=== +|Category of T|Comment|`value_from` behavior|`value_to` behavior + +|Custom conversion. +| +|Custom behavior. +|Custom behavior. + +|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[Arithmetic type] +| +a| The result is a number equal to input and has the type + +* `std::int64_t`, if `T` is a signed integer'; or +* `std::uint64_t`, if `T` is an unsigned integer; or +* `double` otherwise. +|The result is created via <>. + +|Type satisfying <> +|Intended for types like {std_monostate}. +|The result is a null value. +|The result is default-constructed. + +|Type satisfying <>. +|A sequence of `char`s, e.g. `std::string`. +|The result is a <>. +|The result is constructed from a <>. + +|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 + alternative. +|The result holds the first alternative for which a conversion succeeds. + +|Type satisfying <> +| +|If the input value is empty, the result is a `null`. Otherwise it is + equivalent to conversion of the object stored inside of optional. +|The result is default constructed if the input value is `null`. Otherwise the + result is constructed from the result of conversion of the input to the + type stored in optional. + +|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. + +|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. + +|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 + corresponding values. + +|Type satisfying <> +| +|If the input value is equal to one of the described enumerators, the result is + a <>, containing its name. Otherwise it's equal to the input + value converted to its underlying type. +|The result is the described enumerator, corresponding to the input + <>. + +|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`. +|=== + +For composite types (sequences, tuples, described classes, etc.) conversion of contained objects is applied recursively. For example: + +[source] +---- +include::../../../test/snippets.cpp[tag=snippet_conv_recursive,indent=0] +---- + +Here, the map is converted into an <>, since it matches <>. Each of its keys is converted into a <>, as `std::string` matches <>, and each of its values is converted into an <>, as `std::pair` matches <>. Finally, elements of pairs are converted into a `std::int64_t` number and a `bool`. + +:leveloffset: +1 + +include::custom.adoc[] +include::nothrow.adoc[] +include::alloc.adoc[] +include::context.adoc[] +include::forward.adoc[] +include::direct.adoc[] +include::guidelines.adoc[] + +:leveloffset: -1 From 305e5b8ea96987a8413baf0ccd564af748430df1 Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Wed, 22 Apr 2026 22:14:12 +0000 Subject: [PATCH 22/68] Added translation using Weblate (Chinese (Simplified Han script)) --- doc/pages/conversion/nothrow_zh_Hans.adoc | 40 +++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 doc/pages/conversion/nothrow_zh_Hans.adoc diff --git a/doc/pages/conversion/nothrow_zh_Hans.adoc b/doc/pages/conversion/nothrow_zh_Hans.adoc new file mode 100644 index 0000000..462f5da --- /dev/null +++ b/doc/pages/conversion/nothrow_zh_Hans.adoc @@ -0,0 +1,40 @@ +//// +Copyright (c) 2022 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 +//// + += Non-Throwing Conversions +For the case where throwing exceptions is undesirable, Boost.JSON also provides a non-throwing version of <>, the function template <>. It returns {ref_result}, a specialised variant that either holds a value or an {ref_error_code}. + +[NOTE] +There's no non-throwing equivalent for <>. This is simply because we haven't yet encountered a situation where <> needed to communicate an error to the caller. + +The library provides non-throwing conversions for all the categories of types it supports with <>. If a user wants to use it with custom types, an overload of `tag_invoke` of this form needs to be provided: + +``` + +result_for::type tag_invoke( const try_value_to_tag< T >&, const value& ); + +``` + +For the class `ip_address` from the section <> this overload may look like this: + +[source] +---- +include::../../../test/snippets.cpp[tag=snippet_nothrow_1,indent=0] +---- + +The overload lets us use `ip_address` with <>. + +[source] +---- +include::../../../test/snippets.cpp[tag=snippet_nothrow_2,indent=0] +---- + +If <> is used with a type, for which there's no `tag_invoke` overload of the form described in this section, but there is one of the form intended for <>, then the library still tries to perform the conversion. It uses the throwing overload, and attempts to convert any thrown exception into an {ref_error_code}. Note, though, that such approach will likely be slower then a dedicated overload. + +The opposite is also true: if there's a `tag_invoke` overload intended for <>, but not for <>, then calling <> will invoke the non-throwing overload, then construct a {ref_system_error} from the {ref_error_code} and throw it. Due to these fallbacks, it is recommended that users provide the overload from this section, rather then the other one, if they ever intend to use <>. From 74c501ee03ce1d2bc7cd24e6732440f3829013cf Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Wed, 22 Apr 2026 22:14:23 +0000 Subject: [PATCH 23/68] Added translation using Weblate (Chinese (Simplified Han script)) --- doc/pages/conversion/guidelines_zh_Hans.adoc | 21 ++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 doc/pages/conversion/guidelines_zh_Hans.adoc diff --git a/doc/pages/conversion/guidelines_zh_Hans.adoc b/doc/pages/conversion/guidelines_zh_Hans.adoc new file mode 100644 index 0000000..162b62a --- /dev/null +++ b/doc/pages/conversion/guidelines_zh_Hans.adoc @@ -0,0 +1,21 @@ +//// +Copyright (c) 2023 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 +//// + += Conversion Customization Guidelines +With so many options, it can be hard to choose the best way to customise conversion for your type. In this section, we will discuss those options and suggest which to choose when. + +The first advice is to use one of the library-provided conversions, rather then providing a custom one, unless the resulting format is undesirable. If the library deduces the wrong conversion category, you can opt out by specialising the relevant trait to inherit from `std::false_type`. + +If library-provided conversions are suitable for you, you have the option to use direct conversions. This also puts the requirement of being default constructible on many of your types. + +The next thing to consider is whether your conversions are intended for internal use, or whether your users are not members of your team. If your users are external, then they will ultimately determine the conditions in which these conversions will be used. Conversely, for internal libraries and applications, you have the full control of usage conditions. + +If your users are external, they and not you decide whether throwing exceptions is acceptable. So, in this case it is better to use non-throwing `tag_invoke` overloads. In addition, for customising conversion of composite types, always use `tag_invoke` overload with 2 context parameters. This will allow correct context propagation to elements of composites. This will also allow propagation of exceptions from conversion of elements. + +Finally, it is worth mentioning that due to the ability to provide conversions to JSON containers without a binary dependency on the library, you don't have to push such dependency on your users. This is particularly relevant for libraries for which interoperation with Boost.JSON is only ancillary. From fe0a6dbd3520ab63510dc0b648f185e8b72fffdd Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Wed, 22 Apr 2026 22:14:33 +0000 Subject: [PATCH 24/68] Added translation using Weblate (Chinese (Simplified Han script)) --- doc/pages/conversion/forward_zh_Hans.adoc | 34 +++++++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 doc/pages/conversion/forward_zh_Hans.adoc diff --git a/doc/pages/conversion/forward_zh_Hans.adoc b/doc/pages/conversion/forward_zh_Hans.adoc new file mode 100644 index 0000000..bb45b01 --- /dev/null +++ b/doc/pages/conversion/forward_zh_Hans.adoc @@ -0,0 +1,34 @@ +//// +Copyright (c) 2022 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 +//// + += Avoiding Physical Dependency +Some users, particularly library authors, may wish to provide conversions between their types and <>, but at the same time would prefer to avoid having their library depend on Boost.JSON. This is possible to achieve with the help of a few forward declarations. + +[source] +---- +include::../../../test/doc_forward_conversion.cpp[tag=doc_forward_conversion_1,indent=0] +---- + +Note that <> is declared using an out-parameter, rather then returning its result. This overload is specifically designed for this use-case. + +After that the definitions of `tag_invoke` overloads should be provided. These overloads have to be templates, since <> is only forward-declared and hence is an incomplete type. + +[source] +---- +include::../../../test/doc_forward_conversion.cpp[tag=doc_forward_conversion_2,indent=0] +---- + +As discussed previously, we prefer to define a non-throwing overload of `tag_invoke` for <>, rather then the throwing overload for <>, as the latter can fallback to the former without performance degradation. + +Forward declarations of contextual conversions are done very similarly: + +[source] +---- +include::../../../test/doc_forward_conversion.cpp[tag=doc_forward_conversion_3,indent=0] +---- From b3b811d9039b44353b8e546bf59730f9d8cd396c Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Wed, 22 Apr 2026 22:14:43 +0000 Subject: [PATCH 25/68] Added translation using Weblate (Chinese (Simplified Han script)) --- doc/pages/conversion/direct_zh_Hans.adoc | 26 ++++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 doc/pages/conversion/direct_zh_Hans.adoc diff --git a/doc/pages/conversion/direct_zh_Hans.adoc b/doc/pages/conversion/direct_zh_Hans.adoc new file mode 100644 index 0000000..1d89d1e --- /dev/null +++ b/doc/pages/conversion/direct_zh_Hans.adoc @@ -0,0 +1,26 @@ +//// +Copyright (c) 2023 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 +//// + += Direct Conversion +For large inputs parsing into the library's containers followed by conversion via <> (or vice versa <> followed by serialization from a <>) might be prohibitively expensive. For these cases the library provides components that allow parsing directly into and serializing directly from user-provided objects. + +The drawback of this approach is that fully custom type representations are not supported, only the library-provided conversions are. Also all objects that should be populated by parsing have to be default constructible types. This includes not only the top-level object, but e.g. elements of containers, members of described `struct`s, and alternatives of variants. + +That being said, if your types are default-constructible and you don't need the customisability allowed by <> and <>, then you can get a significant performance boost with direct conversions. + +Direct parsing is performed by the <> family of functions. The library provides overloads that take either <> or `std::istream`, and can report errors either via throwing exceptions or setting an error code. + +[source] +---- +include::../../../test/snippets.cpp[tag=doc_parse_into_1,indent=0] +---- + +If you need to combine incremental parsing with direct parsing, you can resort to <>. `parser_for` is an instantiation of <> that parses into an object of type `T`, and is what <> uses under the hood. + +Direct serialization doesn't require any special components and works with the regular <> and <>. From f0f1ddd0a50465de8e08e43401cc31a8bb4351ce Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Wed, 22 Apr 2026 22:14:58 +0000 Subject: [PATCH 26/68] Added translation using Weblate (Chinese (Simplified Han script)) --- doc/pages/conversion/custom_zh_Hans.adoc | 74 ++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 doc/pages/conversion/custom_zh_Hans.adoc diff --git a/doc/pages/conversion/custom_zh_Hans.adoc b/doc/pages/conversion/custom_zh_Hans.adoc new file mode 100644 index 0000000..e4ad29d --- /dev/null +++ b/doc/pages/conversion/custom_zh_Hans.adoc @@ -0,0 +1,74 @@ +//// +Copyright (c) 2022 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 +//// + += Custom Conversions +Boost.JSON uses two mechanisms to customize conversion between <> and user types. One mechanism involves specializing type traits. The other one is more powerful and requires defining overloads of `tag_invoke`. Both mechanisms will be further explained in this section. + +== Conversion Traits +Previously a number of conversion type traits, like <> or <>, were introduced. The library tries the traits one after another and uses the implementation that corresponds to the first matching trait. In some cases, though, a type would match a trait with a higher priority, but the user intends for it to belong to a lower priority category. If this happens the user can specialize the trait that's not supposed to match for that type to be an equivalent of `std::false_type`. + +Consider this type: + +[source] +---- +include::../../../test/doc_types.hpp[tag=snippet_conv_spec_trait1,indent=0] +---- + +It exposes both a sequence API and a tuple API. But converting from <> to `user_ns::ip_address` would not be able to use implementation for sequences, since those are constructed empty and then populated one element at a time, while `ip_address` has a fixed size of 4. The tuple conversion would fit, though. The only problem is that <> has a lower priority than <>. In order to circumvent this, the user only needs to specialize <> to not match `ip_address`. + +[source] +---- +include::../../../test/snippets.cpp[tag=snippet_conv_spec_trait2,indent=0] +---- + +== `tag_invoke` Overloads +The second, more powerful approach, is to provide the conversion implementation yourself. With Boost.JSON this is done by defining an overload of `tag_invoke` function (the benefits of this mechanism are outlined in http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1895r0.pdf[C++ proposal P1895]. In essence, `tag_invoke` provides a uniform interface for defining customization points by using argument-dependent lookup to find a viable overload from the point at which it is called. As the name suggests, a tag type is passed as an argument in order to: + +* discard candidates that are unrelated to that particular customization point, and + +* embed the user-defined type into the arguments list (e.g. by using a tag type template such as `value_to_tag`) so that its http://eel.is/c++draft/basic.lookup.argdep#2[associated namespaces and entities] are examined when name lookup is performed. + +This has the effect of finding user-provided `tag_invoke` overloads, even if they are declared (lexically) after the definition of the calling function. + +Overloads of `tag_invoke` called by <> take the form: + +``` + +void tag_invoke( const value_from_tag&, value&, T ); + +``` + +While overloads of `tag_invoke` called by <> take the form: + +``` + +T tag_invoke( const value_to_tag< T >&, const value& ); + +``` + +If we implemented conversion for `user_ns::ip_address` manually with this approach, it would look like this: + +[source] +---- +include::../../../test/snippets.cpp[tag=snippet_tag_invoke_1,indent=0] +---- + +Since the type being converted is embedded into the function's signature, user-provided overloads are visible to argument-dependent lookup and will be candidates when a conversion is performed: + +[source] +---- +include::../../../test/snippets.cpp[tag=snippet_tag_invoke_2,indent=0] +---- + +Users can freely combine types with custom conversions with types with library-provided conversions. The library handles them correctly: + +[source] +---- +include::../../../test/snippets.cpp[tag=snippet_tag_invoke_3,indent=0] +---- From bac9abd6af7ade6c35997cecbb0ca543c93e58e1 Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Wed, 22 Apr 2026 22:15:03 +0000 Subject: [PATCH 27/68] Added translation using Weblate (Chinese (Simplified Han script)) --- doc/pages/conversion/context_zh_Hans.adoc | 98 +++++++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 doc/pages/conversion/context_zh_Hans.adoc diff --git a/doc/pages/conversion/context_zh_Hans.adoc b/doc/pages/conversion/context_zh_Hans.adoc new file mode 100644 index 0000000..a59d22c --- /dev/null +++ b/doc/pages/conversion/context_zh_Hans.adoc @@ -0,0 +1,98 @@ +//// +Copyright (c) 2022 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 +//// + += Contextual Conversions +Previously in this section we've been assuming that there is a particular fitting JSON representation for a type. But this is not always the case. Often one needs to represent particular value with JSON of certain format in one situation and with another format in a different situation. This can be achieved with Boost.JSON by providing an extra argument---context. + +Let's implement conversion from `user_ns::ip_address` to a JSON string: + +[source] +---- +include::../../../test/snippets.cpp[tag=doc_context_conversion_1,indent=0] +---- + + +These `tag_invoke` overloads take an extra `as_string` parameter, which disambiguates this specific representation of `ip_address` from all other potential representations. In order to take advantage of them one needs to pass an `as_string` object to <> or <> as the last argument: + +[source] +---- +include::../../../test/snippets.cpp[tag=doc_context_conversion_2,indent=0] +---- + +Note, that if there is no dedicated `tag_invoke` overload for a given type and a given context, the implementation falls back to overloads without context. Thus it is easy to combine contextual conversions with conversions provided by the library: + +[source] +---- +include::../../../test/snippets.cpp[tag=doc_context_conversion_3,indent=0] +---- + +== Conversions for Third-Party Types +Normally, you wouldn't be able to provide conversions for types from third-party libraries and standard types, because it would require yout to put `tag_invoke` overloads into namespaces you do not control. But with contexts you can put the overloads into your namespaces. This is because the context will add its associated namespaces into the list of namespaces where `tag_invoke` overloads are searched. + +As an example, let's implement conversion for https://en.cppreference.com/w/cpp/chrono/system_clock[``std::chrono::system_clock::time_point``s] using https://en.wikipedia.org/wiki/ISO_8601[ISO 8601] format. + +[source] +---- +include::../../../test/snippets.cpp[tag=doc_context_conversion_4,indent=0] +---- + +Reverse conversion is left out for brevity. + +The new context is used in a similar fashion to `as_string` previously in this section. + +[source] +---- +include::../../../test/snippets.cpp[tag=doc_context_conversion_5,indent=0] +---- + +One particular use case that is enabled by contexts is adaptor libraries that define JSON conversion logic for types from a different library. + +== Passing Data to Conversion Functions +Contexts we used so far were empty classes. But contexts may have data members and member functions just as any class. Implementers of conversion functions can take advantage of that to have conversions configurable at runtime or pass special objects to conversions (e.g. allocators). + +Let's rewrite conversion for ``system_clock::time_point``s to allow any format supported by `std::strftime`. + +[source] +---- +include::../../../test/snippets.cpp[tag=doc_context_conversion_6,indent=0] +---- + +This `tag_invoke` overload lets us change date conversion format at runtime. Also note, that there is no ambiguity between `as_iso_8601` overload and `date_format` overload. You can use both in your program: + +[source] +---- +include::../../../test/snippets.cpp[tag=doc_context_conversion_7,indent=0] +---- + +== Combining Contexts +Often it is needed to use several conversion contexts together. For example, consider a log of remote users identified by IP addresses accessing a system. We can represent it as `std::vector>`. We want to serialize both ``ip_address``es and ``time_point``s as strings, but for this we need both `as_string` and `as_iso_8601` contexts. To combine several contexts just use {std_tuple}. Conversion functions will select the first element of the tuple for which a `tag_invoke` overload exists and will call that overload. As usual, `tag_invoke` overloads that don't use contexts and library-provided generic conversions are also supported. Thus, here's our example: + +[source] +---- +include::../../../test/snippets.cpp[tag=doc_context_conversion_8,indent=0] +---- + +In this snippet `time_point` is converted using `tag_invoke` overload that takes `as_iso_8601`, `ip_address` is converted using `tag_invoke` overload that takes `as_string`, and {std_vector} is converted using a generic conversion provided by the library. + +== Contexts and Composite Types +As was shown previously, generic conversions provided by the library forward contexts to conversions of nested objects. And in the case when you want to provide your own conversion function for a composite type enabled by a particular context, you usually also need to do that. + +Consider this example. As was discussed in a previous section, <> requires that your key type satisfies <>. Now, let's say your keys are not string-like, but they do convert to <>. You can make such maps to also convert to objects using a context. But if you want to also use another context for values, you need a way to pass the full combined context to map elements. So, you want the following test to succeed. + +[source] +---- +include::../../../test/snippets.cpp[tag=doc_context_conversion_9,indent=0] +---- + +For this you will have to use a different overload of `tag_invoke`. This time it has to be a function template, and it should have two parameters for contexts. The first parameter is the specific context that disambiguates that particular overload. The second parameter is the full context passed to <> or <>. + +[source] +---- +include::../../../test/snippets.cpp[tag=doc_context_conversion_10,indent=0] +---- From 4170e8721420160697ca858f405e41af92aae3ea Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Wed, 22 Apr 2026 22:15:18 +0000 Subject: [PATCH 28/68] Added translation using Weblate (Chinese (Simplified Han script)) --- doc/pages/conversion/alloc_zh_Hans.adoc | 32 +++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 doc/pages/conversion/alloc_zh_Hans.adoc diff --git a/doc/pages/conversion/alloc_zh_Hans.adoc b/doc/pages/conversion/alloc_zh_Hans.adoc new file mode 100644 index 0000000..75d87f1 --- /dev/null +++ b/doc/pages/conversion/alloc_zh_Hans.adoc @@ -0,0 +1,32 @@ +//// +Copyright (c) 2022 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 +//// + += Allocation Control +As <> creates a <> object, users may want to control the way memory is allocated for it. For this reason the function has an optional <> parameter, that is used to set the {ref_memory_resource} for the result. + +[NOTE] +<> does not have a similar parameter, as <> is not created. + +As the conversion result is set via an output parameter of type `value&`, the intended <> is correctly propagated. But users still should take care to not create temporaries using the default {ref_memory_resource} by accident. + +For example, consider this alternative implementation of `tag_invoke` for `ip_address` from the section <>. + +``` + +void +tag_invoke( const value_from_tag&, value& jv, ip_address const& addr ) +{ + jv = array{ b[0], b[1], b[2], b[3] }; +} + +``` + +This implementation explicitly creates an <> rather than relying on assignment from an initializer list. But the array uses default {ref_memory_resource}, not the one used by `jv`. + +To avoid creating such temporaries with an incorrect {ref_memory_resource}, using <>'s member functions <>, <>, and <> can be helpful. From 5801ea186dae49250046a433b2e1ae3ae85cd535 Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Wed, 22 Apr 2026 22:15:22 +0000 Subject: [PATCH 29/68] Added translation using Weblate (Chinese (Simplified Han script)) --- .../allocators/uses_allocator_zh_Hans.adoc | 36 +++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 doc/pages/allocators/uses_allocator_zh_Hans.adoc diff --git a/doc/pages/allocators/uses_allocator_zh_Hans.adoc b/doc/pages/allocators/uses_allocator_zh_Hans.adoc new file mode 100644 index 0000000..218f6f8 --- /dev/null +++ b/doc/pages/allocators/uses_allocator_zh_Hans.adoc @@ -0,0 +1,36 @@ +//// +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 +//// + +[#uses_allocator] += Uses-allocator Construction +To support code bases which are already using polymorphic allocators, the containers in this library support {std_uses_allocator} construction. For <>, <>, <>, and <>: + +* The nested type `allocator_type` is an alias for a {ref_polymorphic_allocator}. + +* All eligible constructors which accept <> will also accept an instance of {ref_polymorphic_allocator} in the same argument position. + +* The member function `get_allocator` returns an instance of + {ref_polymorphic_allocator} constructed from the {ref_memory_resource} used by the container. Ownership of this memory resource is not transferred. + +Practically, this means that when a library container type is used in a standard container that uses a polymorphic allocator, the allocator will propagate to the JSON type. For example: + +[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. From b2a4658e08df7983464bdfbe424b71dfa185656a Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Wed, 22 Apr 2026 22:15:35 +0000 Subject: [PATCH 30/68] Added translation using Weblate (Chinese (Simplified Han script)) --- doc/pages/allocators/storage_ptr_zh_Hans.adoc | 160 ++++++++++++++++++ 1 file changed, 160 insertions(+) create mode 100644 doc/pages/allocators/storage_ptr_zh_Hans.adoc diff --git a/doc/pages/allocators/storage_ptr_zh_Hans.adoc b/doc/pages/allocators/storage_ptr_zh_Hans.adoc new file mode 100644 index 0000000..78e9775 --- /dev/null +++ b/doc/pages/allocators/storage_ptr_zh_Hans.adoc @@ -0,0 +1,160 @@ +//// +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 +//// + += `storage_ptr` +Variable-length containers in this library all use dynamically allocated memory to store their contents. Callers can gain control over the strategy used for allocation by specifying a <> in select constructors and function parameter lists. A <> has these properties: + +* A storage pointer always points to a valid, type-erased {ref_memory_resource}. + +* Default-constructed storage pointers reference the <>, an implementation-defined instance which always uses the equivalent of global operator new and delete. + +* Storage pointers constructed from a {ref_memory_resource} or {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. + +* A storage pointer obtained from <> acquires shared ownership of the memory resource; the lifetime of the resource is extended until all copies of the storage pointer are destroyed. + +* The storage pointer remembers the value of <> 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|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. + +| <> +| 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. + +| <> +| 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} +| 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. + +| <> +| A smart pointer through which a {ref_memory_resource} is managed and + accessed. +|=== + +== Default Memory Resource +The default memory resource uses the global `operator new` and `operator delete` to allocate memory. This resource is not reference counted and has a non-trivial deallocate function. All default-constructed <> objects reference the same memory resource: + +[source] +---- +include::../../../test/doc_storage_ptr.cpp[tag=doc_storage_ptr_1,indent=0] +---- + +Default-constructed library containers use the default memory resource: + +[source] +---- +include::../../../test/doc_storage_ptr.cpp[tag=doc_storage_ptr_2,indent=0] +---- + +The default memory resource is well suited for general usage. It offers reasonable performance for parsing, and conservative memory usage for modification of the contents of containers. + +[NOTE] +This memory resource is not guaranteed to be the same as the result of `boost::container::pmr::get_default_resource`. It also cannot be changed with `boost::container::pmr::set_default_resource`. + +== Monotonic Resource +Consider the pattern of memory allocation during parsing: when an array, object, or string is encountered the parser accumulates elements in its temporary storage area. When all of the elements are known, a single memory allocation is requested from the resource when constructing the value. Thus, parsing only allocates and constructs containers at their final size. Memory is not reallocated; that is, a memory buffer never needs to grow by allocating a new larger buffer and deallocating the previous buffer. + +The <> optimizes this memory allocation pattern by allocating increasingly large blocks of global memory internally and parceling those blocks out in smaller pieces to fulfill allocation requests. It has a trivial deallocate function. The monotonic resource does not actually deallocate memory until the resource is destroyed. Thus, it is ideally suited for the use-case where JSON is parsed, and the resulting value is then inspected but not modified. + +The resource to use when constructing values may be specified in calls to <> as shown here: + +[source] +---- +include::../../../test/doc_storage_ptr.cpp[tag=doc_storage_ptr_3,indent=0] +---- + +Or, to parse into a value with shared ownership of the memory resource: + +[source] +---- +include::../../../test/doc_storage_ptr.cpp[tag=doc_storage_ptr_4,indent=0] +---- + +A monotonic resource may be optionally constructed with an initial buffer to use first, before going to the heap. This allows the caller to use stack space and avoid dynamic allocations for most parsed JSON, falling back to dynamic allocation from the heap if the input JSON is larger than average, as shown here: + +[source] +---- +include::../../../test/doc_storage_ptr.cpp[tag=doc_storage_ptr_5,indent=0] +---- + +== Static Resource +A <> constructs from a caller-provided buffer, and satisfies all memory allocation requests from the buffer. Once the buffer is exhausted, subsequent calls to allocate throw the exception `std::bad_alloc`. The resource offers a simple invariant: dynamic heap allocations are never performed. + +To use the resource, construct it with a local buffer: + +[source] +---- +include::../../../test/doc_storage_ptr.cpp[tag=doc_storage_ptr_6,indent=0] +---- + +== Null Resource +The function <> returns a global instance of the null resource. This resource offers a simple invariant: all calls to allocate will throw the exception `std::bad_alloc`. An instance of the null resource can be used to make parsing guarantee that allocations from the heap are never made. This is explored in more detail in a later section. + +== Allocator Propagation +The containers <>, <>, and <> all propagate the memory resource they were constructed with to child elements: + +[source] +---- +include::../../../test/doc_storage_ptr.cpp[tag=doc_storage_ptr_7,indent=0] +---- + +This propagation acts recursively, containers within containers will all have the resource propagated. Once a container is constructed, its memory resource can never be changed. + +== Resource Lifetime +It is important to note that <> supports both shared-ownership and reference lifetime models. Construction from a memory resource pointer does not transfer ownership: + +[source] +---- +include::../../../test/doc_storage_ptr.cpp[tag=doc_storage_ptr_8,indent=0] +---- + +When using a memory resource in this fashion, including the case where a storage pointer or container is constructed from a {ref_polymorphic_allocator}, the caller must ensure that the lifetime of the resource is extended until it is no longer referenced by any variables; otherwise, undefined behavior is possible. + +Shared ownership is achieved using the function <>, which creates a new, reference-counted memory resource using a dynamic memory allocation and returns it as a <>: + +[source] +---- +include::../../../test/doc_storage_ptr.cpp[tag=doc_storage_ptr_9,indent=0] +---- + +When a storage pointer is constructed this way, the lifetime of the referenced memory resource is extended until all variables which reference it are destroyed. + +== User-Defined Resource +To implement custom memory allocation strategies, derive your class from {ref_memory_resource} and implement the functions `do_allocate`, `do_deallocate`, and `do_is_equal` as seen in this example below, which logs each operation it performs to the console: + +[source] +---- +include::../../../test/doc_storage_ptr.cpp[tag=doc_storage_ptr_10,indent=0] +---- From 00304f23647dd95ad368f79691f44375ae6c90b7 Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Wed, 22 Apr 2026 22:15:51 +0000 Subject: [PATCH 31/68] Added translation using Weblate (Chinese (Simplified Han script)) --- doc/pages/allocators/overview_zh_Hans.adoc | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 doc/pages/allocators/overview_zh_Hans.adoc diff --git a/doc/pages/allocators/overview_zh_Hans.adoc b/doc/pages/allocators/overview_zh_Hans.adoc new file mode 100644 index 0000000..8394a6e --- /dev/null +++ b/doc/pages/allocators/overview_zh_Hans.adoc @@ -0,0 +1,22 @@ +//// +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 +//// + += Allocators + +Here we discuss the various allocator models used in the C++ standard, followed by an explanation of the model used in this library and its benefits. Finally we discuss how the library interoperates with existing code that uses polymorphic allocators. + +:leveloffset: +1 + +include::background.adoc[] +include::storage_ptr.adoc[] +include::uses_allocator.adoc[] + +:leveloffset: -1 From f946e4433a0be95ce9d7351e2e4ce58d838f2215 Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Wed, 22 Apr 2026 22:16:06 +0000 Subject: [PATCH 32/68] Added translation using Weblate (Chinese (Simplified Han script)) --- doc/pages/allocators/background_zh_Hans.adoc | 89 ++++++++++++++++++++ 1 file changed, 89 insertions(+) create mode 100644 doc/pages/allocators/background_zh_Hans.adoc diff --git a/doc/pages/allocators/background_zh_Hans.adoc b/doc/pages/allocators/background_zh_Hans.adoc new file mode 100644 index 0000000..461ed5e --- /dev/null +++ b/doc/pages/allocators/background_zh_Hans.adoc @@ -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 +//// + += Background +The first version of allocators in C++ defined the named requirement {req_Allocator}, and made each standard container a class template parameterized on the allocator type. For example, here is the declaration for {std_vector}: + +[source] +---- +include::../../../test/doc_background.cpp[tag=doc_background_1,indent=0] +---- + +The standard allocator is {req_DefaultConstructible}. To support stateful allocators, containers provide additional constructor overloads taking an allocator instance parameter. + +[source] +---- +include::../../../test/doc_background.cpp[tag=doc_background_2,indent=0] +---- + +While the system works, it has some usability problems: + +* The container must be a class template. +* Parameterizing the allocator on the element type is clumsy. +* The system of allocator traits, especially POCCA and POCMA, is complicated and error-prone. + +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. + +== Polymorphic Allocators + +{cpp}17 improves the allocator model by representing the low-level allocation operation with an abstract interface called {ref_memory_resource}, which is not parameterized on the element type, and has no traits: + +[source] +---- +include::../../../test/doc_background.cpp[tag=doc_background_3,indent=0] +---- + +The class template {ref_polymorphic_allocator} wraps a {ref_memory_resource} pointer and meets the requirements of {req_Allocator}, allowing it to be used where an allocator is expected. The standard provides type aliases using the polymorphic allocator for standard containers: + +[source] +---- +include::../../../test/doc_background.cpp[tag=doc_background_4,indent=0] +---- + +A polymorphic allocator constructs with a pointer to a memory resource: + +[source] +---- +include::../../../test/doc_background.cpp[tag=doc_background_5,indent=0] +---- + +The memory resource is passed by pointer; ownership is not transferred. The caller is responsible for extending the lifetime of the memory resource until the last container which is using it goes out of scope, otherwise the behavior is undefined. Sometimes this is the correct model, such as in this example which uses a monotonic resource constructed from a local stack buffer: + +[source] +---- +include::../../../test/doc_background.cpp[tag=doc_background_6,indent=0] +---- + +However, sometimes shared ownership is needed. Specifically, that the lifetime extension of the memory resource should be automatic. For example, if a library wants to return a container which owns an instance of the library's custom memory resource as shown below: + +[source] +---- +include::../../../test/doc_background.cpp[tag=doc_background_7,indent=0] +---- + +This can be worked around by declaring the container to use a custom allocator (perhaps using a `std::shared_ptr< std::pmr::memory_resource >` as a data member). This hinders library composition; every library now exports unique, incompatible container types. A raw memory resource pointer is also easy to misuse: + +[source] +---- +include::../../../test/doc_background.cpp[tag=doc_background_8,indent=0] +---- + +Workarounds for this problem are worse than the problem itself. The library could return a pair with the vector and `std::unique_ptr` which the caller must manage. Or the library could change its function signatures to accept a {ref_memory_resource}``*`` provided by the caller, where the library also makes public the desired memory resources (`my_resource` above). + +== Problem Statement + +We would like an allocator model using a single type `T` with the following properties: + +* `T` is not a class template +* `T` references a {ref_memory_resource} +* `T` supports both reference semantics or shared ownership +* `T` interoperates with code already using `std::pmr` + +Boost.JSON solves this problem by introducing a new smart pointer called <> which builds upon {cpp}17's memory allocation interfaces, accomplishing the goals above. As a result, libraries which use this type compose more easily and enjoy faster compilation, as member functions for containers which use the type can be defined out-of-line. From 5d8d7b28385146b7824b51abda5af119caa6a139 Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Thu, 23 Apr 2026 15:07:58 +0000 Subject: [PATCH 33/68] Translated using Weblate (Chinese (Simplified Han script)) Currently translated at 100.0% (73 of 73 strings) Translation: Boost Json Translation (zh_Hans)/Doc / Library Detail (adoc) Translate-URL: https://boost-weblate.cloud/projects/boost-json-documentation-zh_Hans/doc-library-detail-adoc/zh_Hans/ --- doc/library-detail_zh_Hans.adoc | 112 +++++++++++++++----------------- 1 file changed, 53 insertions(+), 59 deletions(-) diff --git a/doc/library-detail_zh_Hans.adoc b/doc/library-detail_zh_Hans.adoc index 7ff837c..af49c97 100644 --- a/doc/library-detail_zh_Hans.adoc +++ b/doc/library-detail_zh_Hans.adoc @@ -2,36 +2,30 @@ https://www.boost.org/doc/libs/release/libs/json/[image:https://raw.githubuserco [width="100%", cols="12%,43%,45%", options="header"] |=== -|Branch |https://github.com/boostorg/json/tree/master[`master`] +|分支 |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]] +|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[构建状态]] -|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://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[文档]] |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]] +|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[构建状态]] -|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]] +|测试矩阵 +|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[测试矩阵]] -|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://github.com/boostorg/json/actions?query=workflow%3Afuzz+branch%3Adevelop[image:https://github.com/boostorg/json/workflows/fuzz/badge.svg?branch=develop[模糊测试]] |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://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://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]] @@ -40,89 +34,89 @@ status]] == 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. +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 成为理想的数据交换语言。 -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. +该库专注于一个常见且广泛使用的场景：解析和序列化到一个名为 `value` 的容器，或从中进行解析和序列化（该容器用于存储 JSON 类型）。任何构建的 `value` 都可以被序列化后再反序列化，并保证结果与原始值相等。使用该库生成的任何 JSON 输出，均可被大多数主流编程语言中的常见 JSON 实现正确读取。 -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. +`value` 容器被设计为一种适合作为公共接口和库中词汇类型的组件，便于组合使用。该库将可表示的数据类型限制在绝大多数 JSON 实现（尤其是 JavaScript）普遍接受的范围内。解析器和序列化器均具备高性能，其基准性能达到或超过了同类优秀库的水平。对分配器的支持非常完善。使用这些类型的代码将易于理解、灵活且高效。 -Boost.JSON offers these features: +Boost.JSON 提供以下特性： -* 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 +* 快速编译 +* 仅需 C++11 +* 高性能流式解析器和序列化器 +* 对象的常量时间键查找 +* 允许非标准 JSON 的选项 +* 提供易于使用且安全的现代 API，并支持分配器 +* 可选的纯头文件方式，无需链接库 -Visit https://boost.org/libs/json for complete documentation. +若要获取完整文档请访问以下链接： https://boost.org/libs/json -=== 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 +* 仅需 C++11 +* 可链接预构建的静态或动态 Boost 库，也可使用纯头文件方式（见下文）。 +* Supports -fno-exceptions（可自动检测） -The library relies heavily on these well known C++ types in its interfaces (henceforth termed _standard types_): +该库在其接口中大量依赖以下众所周知的 C++ 类型（以下称为 _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. +要使用纯头文件模式（即无需将程序链接到静态或动态的 Boost.JSON 库），只需在项目中恰好一个新建或现有源文件中添加以下行。 .... #include .... -MSVC users must also define the macro `BOOST_JSON_NO_LIB` to disable auto-linking. +MSVC 用户还必须定义宏 `BOOST_JSON_NO_LIB` ，以禁用自动链接。 -==== 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: +Boost.JSON 在嵌入式设备上表现优异。该库使用局部栈缓冲区来提升某些操作的性能。在 Intel 平台上，这些缓冲区较大（4KB），而在非 Intel 平台上则较小（256 字节）。若要在嵌入式应用中调整栈缓冲区的大小，请在构建库或包含函数定义时定义以下宏： .... #define BOOST_JSON_STACK_BUFFER_SIZE 1024 #include .... -==== Supported Compilers +==== 支持的编译器 -Boost.JSON has been tested with the following compilers: +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 -==== Supported JSON Text +==== 支持的 JSON 文本 -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. +该库要求输入文本使用 UTF-8 编码，这是 [RFC](https://datatracker.ietf.org/doc/html/rfc8259#section-8.1) 对系统间交换的所有 JSON 所规定的强制要求。同样，该库生成的文本也是有效的 UTF-8。 -The RFC does not allow byte order marks (BOM) to appear in JSON text, so the library considers BOM syntax errors. +RFC 不允许字节顺序标记（BOM）出现在 JSON 文本中，因此该库将 BOM 视为语法错误。 -The library supports several popular JSON extensions. These have to be explicitly enabled. +该库支持多种流行的 JSON 扩展，但这些扩展必须显式启用。 -==== Visual Studio Solution +==== 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 .... -=== 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 +* 覆盖率报告 +* 基准性能比较 +* 在 Drone.io、Azure Pipelines 和 AppVeyor 上进行编译与测试 +* 使用 clang-llvm 和机器学习的模糊测试 -=== 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) +根据 Boost 软件许可协议 1.0 版分发。（详见随附文件 LICENSE_1_0.txt 文件或访问 https://www.boost.org/LICENSE_1_0.txt ） From ad270c8377bfaf06e1a8ba836a15cd7a466ec15d Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Thu, 23 Apr 2026 15:08:48 +0000 Subject: [PATCH 34/68] Translated using Weblate (Chinese (Simplified Han script)) Currently translated at 100.0% (31 of 31 strings) Translation: Boost Json Translation (zh_Hans)/Doc / Pages / Allocators / Background (adoc) Translate-URL: https://boost-weblate.cloud/projects/boost-json-documentation-zh_Hans/doc-pages-allocators-background-adoc/zh_Hans/ --- doc/pages/allocators/background_zh_Hans.adoc | 46 ++++++++++---------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/doc/pages/allocators/background_zh_Hans.adoc b/doc/pages/allocators/background_zh_Hans.adoc index 461ed5e..0a6fe08 100644 --- a/doc/pages/allocators/background_zh_Hans.adoc +++ b/doc/pages/allocators/background_zh_Hans.adoc @@ -8,82 +8,82 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) Official repository: https://github.com/boostorg/json //// -= Background -The first version of allocators in C++ defined the named requirement {req_Allocator}, and made each standard container a class template parameterized on the allocator type. For example, here is the declaration for {std_vector}: += 背景 +C++中分配器的第一个版本定义了名为{req_Allocator}的要求，并将每个标准容器设计为以分配器类型为模板参数的类模板。例如，以下是 {std_vector} 的声明： [source] ---- include::../../../test/doc_background.cpp[tag=doc_background_1,indent=0] ---- -The standard allocator is {req_DefaultConstructible}. To support stateful allocators, containers provide additional constructor overloads taking an allocator instance parameter. +标准分配器是{req_DefaultConstructible}。为支持有状态分配器，容器提供了额外的构造函数重载，接受一个分配器实例参数。 [source] ---- include::../../../test/doc_background.cpp[tag=doc_background_2,indent=0] ---- -While the system works, it has some usability problems: +尽管该机制能够正常工作，但仍存在一些可用性问题： -* The container must be a class template. -* Parameterizing the allocator on the element type is clumsy. -* The system of allocator traits, especially POCCA and POCMA, is complicated and error-prone. +* 容器必须是一个类模板。 +* 在元素类型上参数化分配器的方式显得笨拙。 +* 分配器特征机制（尤其是 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. +使用多种分配器类型的基于分配器的程序会引发更多的函数模板实例化，且通常编译速度更慢，因为类模板的函数定义必须在所有调用点可见。 -== Polymorphic Allocators +== 多态分配器 -{cpp}17 improves the allocator model by representing the low-level allocation operation with an abstract interface called {ref_memory_resource}, which is not parameterized on the element type, and has no traits: +{cpp}17通过引入一个名为 {ref_memory_resource} 的抽象接口来表示底层分配操作，从而改进分配器模型。该接口未在元素类型上参数化，且无特征： [source] ---- include::../../../test/doc_background.cpp[tag=doc_background_3,indent=0] ---- -The class template {ref_polymorphic_allocator} wraps a {ref_memory_resource} pointer and meets the requirements of {req_Allocator}, allowing it to be used where an allocator is expected. The standard provides type aliases using the polymorphic allocator for standard containers: +类模板{ref_polymorphic_allocator}包装了{ref_memory_resource}指针，并满足{req_Allocator}要求，使其可在需要分配器的地方使用。标准库为使用多态分配器的标准容器提供了类型别名： [source] ---- include::../../../test/doc_background.cpp[tag=doc_background_4,indent=0] ---- -A polymorphic allocator constructs with a pointer to a memory resource: +多态分配器通过一个指向内存资源的指针进行构造： [source] ---- include::../../../test/doc_background.cpp[tag=doc_background_5,indent=0] ---- -The memory resource is passed by pointer; ownership is not transferred. The caller is responsible for extending the lifetime of the memory resource until the last container which is using it goes out of scope, otherwise the behavior is undefined. Sometimes this is the correct model, such as in this example which uses a monotonic resource constructed from a local stack buffer: +内存资源通过指针传递；所有权不发生转移。调用方需负责确保该内存资源的生命周期持续到所有使用它的容器都离开作用域为止，否则行为未定义。在某些场景下，这种模型是合适的，例如以下示例中使用了一个基于局部栈缓冲区构造的单调内存资源： [source] ---- include::../../../test/doc_background.cpp[tag=doc_background_6,indent=0] ---- -However, sometimes shared ownership is needed. Specifically, that the lifetime extension of the memory resource should be automatic. For example, if a library wants to return a container which owns an instance of the library's custom memory resource as shown below: +然而，有时需要共享所有权，即内存资源的生命周期应自动延长。例如，若某个库希望返回一个容器，该容器拥有该库自定义内存资源的实例，如下所示： [source] ---- include::../../../test/doc_background.cpp[tag=doc_background_7,indent=0] ---- -This can be worked around by declaring the container to use a custom allocator (perhaps using a `std::shared_ptr< std::pmr::memory_resource >` as a data member). This hinders library composition; every library now exports unique, incompatible container types. A raw memory resource pointer is also easy to misuse: +可通过声明容器使用自定义分配器（可能使用`std::shared_ptr< std::pmr::memory_resource >`作为数据成员）来解决此问题。这会阻碍库的组合；每个库都会导出各自独特且互不兼容的容器类型。原始内存资源指针也容易被误用： [source] ---- include::../../../test/doc_background.cpp[tag=doc_background_8,indent=0] ---- -Workarounds for this problem are worse than the problem itself. The library could return a pair with the vector and `std::unique_ptr` which the caller must manage. Or the library could change its function signatures to accept a {ref_memory_resource}``*`` provided by the caller, where the library also makes public the desired memory resources (`my_resource` above). +针对此问题的变通方案往往比问题本身更糟糕。该库可以返回一个包含 vector 和`std::unique_ptr`的pair，必须由调用方自行管理。或者，该库也可以修改其函数签名，接受调用方提供的{ref_memory_resource}``*``，同时将所需的内存资源（如上文的`my_resource`）公开。 -== Problem Statement +== 问题陈述 -We would like an allocator model using a single type `T` with the following properties: +我们希望采用一种使用单一类型`T`的分配器模型，该模型具有以下特性： -* `T` is not a class template -* `T` references a {ref_memory_resource} -* `T` supports both reference semantics or shared ownership -* `T` interoperates with code already using `std::pmr` +* `T`不是类模板 +* `T`引用一个 {ref_memory_resource} +* `T`同时支持引用语义和共享所有权 +* `T`能与已使用`std::pmr`的代码互操作 -Boost.JSON solves this problem by introducing a new smart pointer called <> which builds upon {cpp}17's memory allocation interfaces, accomplishing the goals above. As a result, libraries which use this type compose more easily and enjoy faster compilation, as member functions for containers which use the type can be defined out-of-line. +Boost.JSON通过引入一个名为<> 的新型智能指针解决此问题，该指针基于{cpp}17的内存分配接口构建，实现了上述目标。因此，使用该类型的库更易于组合，并能获得更快的编译速度，因为使用该类型的容器的成员函数可以定义在类外（out-of-line）。 From 5fdbb046c674416270812bc080c8952649b5d90c Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Thu, 23 Apr 2026 15:08:55 +0000 Subject: [PATCH 35/68] Translated using Weblate (Chinese (Simplified Han script)) Currently translated at 100.0% (2 of 2 strings) Translation: Boost Json Translation (zh_Hans)/Doc / Pages / Allocators / Overview (adoc) Translate-URL: https://boost-weblate.cloud/projects/boost-json-documentation-zh_Hans/doc-pages-allocators-overview-adoc/zh_Hans/ --- doc/pages/allocators/overview_zh_Hans.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/pages/allocators/overview_zh_Hans.adoc b/doc/pages/allocators/overview_zh_Hans.adoc index 8394a6e..a5d994a 100644 --- a/doc/pages/allocators/overview_zh_Hans.adoc +++ b/doc/pages/allocators/overview_zh_Hans.adoc @@ -9,9 +9,9 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) Official repository: https://github.com/boostorg/json //// -= Allocators += 分配器 -Here we discuss the various allocator models used in the C++ standard, followed by an explanation of the model used in this library and its benefits. Finally we discuss how the library interoperates with existing code that uses polymorphic allocators. +本文将首先讨论C++标准中使用的各种分配器模型，随后介绍本库所采用的模型及其优势，最后说明该库如何与使用多态分配器的现有代码进行互操作。 :leveloffset: +1 From f8ec73027a7295c9cd9e00dba0ac71f4c5aa3db0 Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Thu, 23 Apr 2026 15:10:15 +0000 Subject: [PATCH 36/68] Translated using Weblate (Chinese (Simplified Han script)) Currently translated at 100.0% (63 of 63 strings) Translation: Boost Json Translation (zh_Hans)/Doc / Pages / Allocators / Storage Ptr (adoc) Translate-URL: https://boost-weblate.cloud/projects/boost-json-documentation-zh_Hans/doc-pages-allocators-storage-ptr-adoc/zh_Hans/ --- doc/pages/allocators/storage_ptr_zh_Hans.adoc | 97 ++++++++----------- 1 file changed, 43 insertions(+), 54 deletions(-) diff --git a/doc/pages/allocators/storage_ptr_zh_Hans.adoc b/doc/pages/allocators/storage_ptr_zh_Hans.adoc index 78e9775..cbaecd0 100644 --- a/doc/pages/allocators/storage_ptr_zh_Hans.adoc +++ b/doc/pages/allocators/storage_ptr_zh_Hans.adoc @@ -9,150 +9,139 @@ Official repository: https://github.com/boostorg/json //// = `storage_ptr` -Variable-length containers in this library all use dynamically allocated memory to store their contents. Callers can gain control over the strategy used for allocation by specifying a <> in select constructors and function parameter lists. A <> has these properties: +本库中的可变长度容器均使用动态分配的内存来存储其内容。调用方可通过在特定构造函数和函数参数列表中指定 <> ，以控制所使用的内存分配策略。<> 具有以下特性： -* A storage pointer always points to a valid, type-erased {ref_memory_resource}. +* 存储指针始终指向一个有效的、类型擦除后的 {ref_memory_resource}。 -* Default-constructed storage pointers reference the <>, an implementation-defined instance which always uses the equivalent of global operator new and delete. +* 默认构造的存储指针引用 <>（默认资源），这是一个由实现定义的实例，始终使用等效于全局 operator new 和 operator delete 的方式。 -* Storage pointers constructed from a {ref_memory_resource} or {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. +* 从 {ref_memory_resource} 或 {ref_polymorphic_allocator} 构造的存储指针不获取所有权；调用方负责确保资源的生命周期持续到不再被引用为止。 -* A storage pointer obtained from <> acquires shared ownership of the memory resource; the lifetime of the resource is extended until all copies of the storage pointer are destroyed. +* 通过 <> 获取的存储指针会获得对内存资源的共享所有权；该资源的生命周期将延长，直至所有该存储指针的副本均被销毁。 -* The storage pointer remembers the value of <> 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|Description +|Name|描述 | <> -| 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. +| 返回一个指向内存资源实例的指针，该实例在分配内存时总是抛出异常。此机制用于确保解析或容器操作不会进行动态内存分配，从而维持该不变性。 | <> -| A customization point allowing a memory resource type to indicate that calls - to deallocate are trivial. +| 一个自定义点，允许内存资源类型表明其 deallocate 调用是平凡的。 | <> -| 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. +| 表示分配器的抽象基类。 | <> -| 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. +| 一种内存资源，用于分配大块内存，且其 deallocate 函数是平凡的。所分配的内存不会被释放，直到该资源被销毁，因此在解析场景下速度很快，但不适合执行修改操作。 | {ref_polymorphic_allocator} -| An {req_Allocator} which uses a reference to a {ref_memory_resource} to - perform allocations. +| 一个 {req_Allocator}，它通过引用 {ref_memory_resource} 执行内存分配。 | <> -| 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. +| 一种使用调用方提供的单一缓冲区的内存资源，不进行任何动态分配。该资源在解析时速度很快，但不适合执行修改操作。 | <> -| A smart pointer through which a {ref_memory_resource} is managed and - accessed. +| 一种用于管理和访问 {ref_memory_resource} 的智能指针。 |=== -== Default Memory Resource -The default memory resource uses the global `operator new` and `operator delete` to allocate memory. This resource is not reference counted and has a non-trivial deallocate function. All default-constructed <> objects reference the same memory resource: +== 默认内存资源 +默认内存资源使用全局 `operator new` 和 `operator delete` 来进行内存分配。该资源不采用引用计数，且其 deallocate 函数是非平凡的。所有默认构造的 <> 对象均引用同一个内存资源： [source] ---- include::../../../test/doc_storage_ptr.cpp[tag=doc_storage_ptr_1,indent=0] ---- -Default-constructed library containers use the default memory resource: +默认构造的库容器使用默认内存资源： [source] ---- include::../../../test/doc_storage_ptr.cpp[tag=doc_storage_ptr_2,indent=0] ---- -The default memory resource is well suited for general usage. It offers reasonable performance for parsing, and conservative memory usage for modification of the contents of containers. +默认内存资源适用于一般用途。它在解析时提供合理的性能，在修改容器内容时则具有保守的内存使用特性。 [NOTE] -This memory resource is not guaranteed to be the same as the result of `boost::container::pmr::get_default_resource`. It also cannot be changed with `boost::container::pmr::set_default_resource`. +该内存资源不保证与 `boost::container::pmr::get_default_resource` 的返回结果相同，也无法通过 `boost::container::pmr::set_default_resource` 进行更改。 -== Monotonic Resource -Consider the pattern of memory allocation during parsing: when an array, object, or string is encountered the parser accumulates elements in its temporary storage area. When all of the elements are known, a single memory allocation is requested from the resource when constructing the value. Thus, parsing only allocates and constructs containers at their final size. Memory is not reallocated; that is, a memory buffer never needs to grow by allocating a new larger buffer and deallocating the previous buffer. +== 单调资源 +考虑解析过程中的内存分配模式：当遇到数组、对象或字符串时，解析器会将其元素累积在临时存储区中。当所有元素都已知后，在构造值时会向内存资源发起一次内存分配请求。因此，解析过程仅在容器最终大小确定时进行一次分配和构造，不会发生内存重分配；也就是说，内存缓冲区无需通过分配更大的新缓冲区并释放旧缓冲区的方式来扩容。 -The <> optimizes this memory allocation pattern by allocating increasingly large blocks of global memory internally and parceling those blocks out in smaller pieces to fulfill allocation requests. It has a trivial deallocate function. The monotonic resource does not actually deallocate memory until the resource is destroyed. Thus, it is ideally suited for the use-case where JSON is parsed, and the resulting value is then inspected but not modified. +<> 通过在内部分配逐渐增大的全局内存块，并将这些块切分为更小的部分以满足分配请求，从而优化了该内存分配模式。它具有平凡的 deallocate 函数，实际上不会释放内存，直到该资源被销毁。因此，它非常适合用于解析 JSON 后仅检查结果值而不对其进行修改的场景。 -The resource to use when constructing values may be specified in calls to <> as shown here: +在调用 <> 时，可按如下方式指定构造值所使用的内存资源： [source] ---- include::../../../test/doc_storage_ptr.cpp[tag=doc_storage_ptr_3,indent=0] ---- -Or, to parse into a value with shared ownership of the memory resource: +或者，可按如下方式解析到一个对内存资源具有共享所有权的值： [source] ---- include::../../../test/doc_storage_ptr.cpp[tag=doc_storage_ptr_4,indent=0] ---- -A monotonic resource may be optionally constructed with an initial buffer to use first, before going to the heap. This allows the caller to use stack space and avoid dynamic allocations for most parsed JSON, falling back to dynamic allocation from the heap if the input JSON is larger than average, as shown here: +单调资源在构造时可选择性地指定一个初始缓冲区，优先使用该缓冲区，之后才会转而使用堆内存。这使得调用方可以利用栈空间，避免对大多数 JSON 解析进行动态分配；仅当输入的 JSON 大于平均水平时，才会退回到从堆中进行动态分配，如下所示： [source] ---- include::../../../test/doc_storage_ptr.cpp[tag=doc_storage_ptr_5,indent=0] ---- -== Static Resource -A <> constructs from a caller-provided buffer, and satisfies all memory allocation requests from the buffer. Once the buffer is exhausted, subsequent calls to allocate throw the exception `std::bad_alloc`. The resource offers a simple invariant: dynamic heap allocations are never performed. +== 静态资源 +<> 由调用方提供的缓冲区构造而成，并从该缓冲区满足所有内存分配请求。一旦缓冲区耗尽，后续的分配调用将抛出 `std::bad_alloc` 异常。该资源提供一个简单的不变式：永不执行动态堆分配。 -To use the resource, construct it with a local buffer: +要使用该资源，请用一个局部缓冲区对其进行构造： [source] ---- include::../../../test/doc_storage_ptr.cpp[tag=doc_storage_ptr_6,indent=0] ---- -== Null Resource -The function <> returns a global instance of the null resource. This resource offers a simple invariant: all calls to allocate will throw the exception `std::bad_alloc`. An instance of the null resource can be used to make parsing guarantee that allocations from the heap are never made. This is explored in more detail in a later section. +== 空资源 +函数 <> 返回一个全局的空资源实例。该资源提供一个简单的不变式：所有内存分配调用都会抛出 `std::bad_alloc` 异常。通过使用空资源实例，可确保解析过程绝不会进行堆内存分配。这一点将在后文进一步详细说明。 -== Allocator Propagation -The containers <>, <>, and <> all propagate the memory resource they were constructed with to child elements: +== 分配器传播 +容器 <>, <> 和 <> 在构造时所使用的内存资源会自动传播给其子元素： [source] ---- include::../../../test/doc_storage_ptr.cpp[tag=doc_storage_ptr_7,indent=0] ---- -This propagation acts recursively, containers within containers will all have the resource propagated. Once a container is constructed, its memory resource can never be changed. +这种传播是递归进行的：嵌套容器中的所有子容器都会获得相同的内存资源。一旦容器被构造，其内存资源就永远无法更改。 -== Resource Lifetime -It is important to note that <> supports both shared-ownership and reference lifetime models. Construction from a memory resource pointer does not transfer ownership: +== 资源生命周期 +需要注意的是，<> 同时支持共享所有权和引用生命周期模型。从内存资源指针构造时不会转移所有权： [source] ---- include::../../../test/doc_storage_ptr.cpp[tag=doc_storage_ptr_8,indent=0] ---- -When using a memory resource in this fashion, including the case where a storage pointer or container is constructed from a {ref_polymorphic_allocator}, the caller must ensure that the lifetime of the resource is extended until it is no longer referenced by any variables; otherwise, undefined behavior is possible. +以这种方式使用内存资源时（包括从 {ref_polymorphic_allocator} 构造存储指针或容器的情况），调用方必须确保资源的生命周期延长至不再被任何变量引用为止；否则，可能会出现未定义行为。 -Shared ownership is achieved using the function <>, which creates a new, reference-counted memory resource using a dynamic memory allocation and returns it as a <>: +通过函数 <> 可实现共享所有权，该函数会动态分配内存以创建一个新的、带引用计数的内存资源，并将其以 <> 的形式返回： [source] ---- include::../../../test/doc_storage_ptr.cpp[tag=doc_storage_ptr_9,indent=0] ---- -When a storage pointer is constructed this way, the lifetime of the referenced memory resource is extended until all variables which reference it are destroyed. +当存储指针以这种方式构造时，其所引用的内存资源的生命周期将延长，直至所有引用它的变量均被销毁为止。 -== User-Defined Resource -To implement custom memory allocation strategies, derive your class from {ref_memory_resource} and implement the functions `do_allocate`, `do_deallocate`, and `do_is_equal` as seen in this example below, which logs each operation it performs to the console: +== 用户定义资源 +要实现自定义内存分配策略，请从 {ref_memory_resource} 派生类，并实现函数 `do_allocate`、`do_deallocate` 和 `do_is_equal`，如下例所示，该示例将其执行的每个操作记录到控制台： [source] ---- From 816a73a60716ce78ada6c83a6954e2d2a1e86bb8 Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Thu, 23 Apr 2026 15:10:32 +0000 Subject: [PATCH 37/68] Translated using Weblate (Chinese (Simplified Han script)) Currently translated at 100.0% (11 of 11 strings) Translation: Boost Json Translation (zh_Hans)/Doc / Pages / Allocators / Uses Allocator (adoc) Translate-URL: https://boost-weblate.cloud/projects/boost-json-documentation-zh_Hans/doc-pages-allocators-uses-allocator-adoc/zh_Hans/ --- .../allocators/uses_allocator_zh_Hans.adoc | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/doc/pages/allocators/uses_allocator_zh_Hans.adoc b/doc/pages/allocators/uses_allocator_zh_Hans.adoc index 218f6f8..3501b6d 100644 --- a/doc/pages/allocators/uses_allocator_zh_Hans.adoc +++ b/doc/pages/allocators/uses_allocator_zh_Hans.adoc @@ -9,28 +9,28 @@ Official repository: https://github.com/boostorg/json //// [#uses_allocator] -= Uses-allocator Construction -To support code bases which are already using polymorphic allocators, the containers in this library support {std_uses_allocator} construction. For <>, <>, <>, and <>: += 使用分配器构造 +为支持已使用多态分配器的代码库，本库中的容器支持 {std_uses_allocator} 构造。对于 <>, <>, <> 和 <>： -* The nested type `allocator_type` is an alias for a {ref_polymorphic_allocator}. +* 嵌套类型 `allocator_type` 是{ref_polymorphic_allocator}的别名。 -* All eligible constructors which accept <> will also accept an instance of {ref_polymorphic_allocator} in the same argument position. +* 所有接受 <> 的合格构造函数，也将在相同参数位置接受一个 {ref_polymorphic_allocator} 实例。 -* The member function `get_allocator` returns an instance of - {ref_polymorphic_allocator} constructed from the {ref_memory_resource} used by the container. Ownership of this memory resource is not transferred. +* 成员函数 `get_allocator` 返回一个 + 由容器所使用的 {ref_memory_resource} 构造的 {ref_polymorphic_allocator} 实例。该内存资源的所有权不会被转移。 -Practically, this means that when a library container type is used in a standard container that uses a polymorphic allocator, the allocator will propagate to the JSON type. For example: +实际上，这意味着当库中的容器类型被用在使用多态分配器的标准容器中时，该分配器会传播到 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. +多态分配器会递归传播。子元素的子元素将使用与父元素相同的内存资源。 From bcbffea8a7bd31d8fd8d553e7fd747924edd85ad Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Thu, 23 Apr 2026 15:12:49 +0000 Subject: [PATCH 38/68] Translated using Weblate (Chinese (Simplified Han script)) Currently translated at 100.0% (119 of 119 strings) Translation: Boost Json Translation (zh_Hans)/Doc / Pages / Benchmarks (adoc) Translate-URL: https://boost-weblate.cloud/projects/boost-json-documentation-zh_Hans/doc-pages-benchmarks-adoc/zh_Hans/ --- doc/pages/benchmarks_zh_Hans.adoc | 143 ++++++++++++------------------ 1 file changed, 58 insertions(+), 85 deletions(-) diff --git a/doc/pages/benchmarks_zh_Hans.adoc b/doc/pages/benchmarks_zh_Hans.adoc index aa94aca..12ff1b8 100644 --- a/doc/pages/benchmarks_zh_Hans.adoc +++ b/doc/pages/benchmarks_zh_Hans.adoc @@ -9,79 +9,53 @@ Official repository: https://github.com/boostorg/json //// [pagelevels=1,toclevels=1] -= Benchmarks -This section compares the performance of Boost.JSON with two widely used libraries with similar functionality: RapidJSON which is known for its performance, and JSON for Modern C++ which is known for feature-richness. The bench program measures the throughput of parsing and serialization for the a set of JSON representing typical workloads. These implementations are evaluated: += 基准测试 +本节将 Boost.JSON 与两个广泛使用的具有类似功能的库进行性能比较：以高性能著称的 RapidJSON 和以功能丰富著称的JSON for Modern C++ 库（nlohmann/json）。bench 程序测量解析和序列化一组代表典型工作负载的 JSON 的吞吐量。评估的实现包括： -.Implementations +.实现 |=== -|Name|Description +|Name|描述 | *boost(pool)* -| Parses the input using a <>, - which is optimized for parsing without subsequent - modification. - The <> object is reused between - trials, allowing temporary memory allocated by the - implementation to persist and improve performance. +| 使用 <> 解析输入，该资源针对解析后不进行后续修改的场景进行了优化。<> 对象在各次试验之间被复用，使得实现所分配的临时内存得以保留，从而提升性能。 | *boost* -| 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. +| 使用 <> 解析输入，该资源基于标准 C++ 分配器，适用于通用场景，包括在解析后对文档进行修改。<> 对象在各次试验之间被复用，使得实现所分配的临时内存得以保留，从而提升性能。 | *rapidjson(pool)* -| 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. +| 使用 https://rapidjson.org/classrapidjson_1_1_memory_pool_allocator.html[`MemoryPoolAllocator`] 的实例解析输入，该分配器针对“仅解析、不修改”的场景进行了优化。持有临时内存的 https://rapidjson.org/classrapidjson_1_1_generic_document.html[`Document`] 对象在多次测试之间不重复使用，否则内存消耗将无限增长，从而导致基准测试结果无效。 | *rapidjson* -| 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. +| 使用 https://rapidjson.org/classrapidjson_1_1_crt_allocator.html[`CrtAllocator`] 的实例解析输入，该分配器使用标准 C++ 分配器，适用于通用场景，包括解析后对文档的修改。持有临时内存的 https://rapidjson.org/classrapidjson_1_1_generic_document.html[`Document`] 对象在多次测试之间不重复使用，否则内存消耗将无限增长，导致基准测试结果无效。 | *nlohmann* -| 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. +| 使用静态成员函数 https://nlohmann.github.io/json/classnlohmann_1_1basic__json_ab330c13ba254ea41fbc1c52c5c610f45.html[`json::parse`] 解析输入，该函数使用默认的 `std` 分配器，适用于通用场景，包括解析后对文档的修改。该库未提供复用解析或序列化过程中所用临时存储的接口，因此无法在后续操作中重用这些临时内存。 |=== -== Methodology -The input files are all loaded first. Then each configuration is run for a sufficient number of trials to last at least 5 seconds. The elapsed time, number of invocations (of parse or serialize), and bytes transferred are emitted as a sample along with a calculation of throughput expressed in megabytes per second. Several samples (currently five) are generated for each configuration. All but the median two samples are discarded, with the remaining samples averaged to produce a single number which is reported as the benchmark result. +== 方法论 +首先加载所有输入文件。随后，每种配置会运行足够多的试验次数，以确保总运行时间不少于 5 秒。每次试验会记录所用时间、调用次数（解析或序列化）以及传输的字节数，并以此生成一个样本，同时计算出以 MB/s（兆字节每秒）为单位的吞吐量。每种配置会生成多个样本（目前为五个），剔除其中非中间两个的样本后，对剩余的两个样本取平均值，作为该配置的最终基准测试结果。 -The input files, available in the bench/data directory, are laid out thusly: +输入文件位于 bench/data 目录，按如下方式布局： -.Input Files +.输入文件 |=== -|Name|Size|Description +|Name|Size|描述 | <> | 125KB -| Data from the Apache Jenkins installation. +| 来自 Apache Jenkins 安装的数据。 | <> | 2.2MB -| The largest file, containing a large number of 2-element arrays holding - floating-point coordinate pairs. +| 最大的文件，包含大量由两个浮点数坐标对组成的二元数组。 | <> | 1.69MB -| A large JSON with a variety of nesting, types, and lengths. +| 一个包含多种嵌套结构、数据类型和长度的大型 JSON。 | <> | 64KB -| An export of data from the Github Events API. +| 一份来自 GitHub Events API 的数据导出。 | <> | 3.25MB @@ -89,127 +63,126 @@ The input files, available in the bench/data directory, are laid out thusly: | <> | 216KB -| An array of large objects. +| 一个由大型对象组成的数组。 | <> | 2.91MB -| A three.js example model serialized to JSON. +| 一个以 JSON 格式序列化的 three.js 示例模型。 | <> | 707KB -| A JSON representing a 3D mesh. Contains many floating-point numbers. +| 一个表示三维网格的 JSON，包含大量浮点数。 | <> | 1.54MB -| mesh.json with whitespace added. +| 添加了空格的 mesh.json。 | <> | 147KB -| A array containing only floating-point numbers. +| 一个仅包含浮点数的数组。 | <> | 499KB -| A JSON with lots of Cyrillic characters. +| 一个包含大量 Cyrillic（西里尔）字符的 JSON。 | <> | 617KB -| An export of data from Twitter's API. +| 一份来自 Twitter API 的数据导出。 | <> | 550KB -| twitter.json with whitespace removed and non-ASCII characters replaced with - Unicode escapes. +| 移除空格并将非 ASCII 字符替换为 Unicode 转义符的 twitter.json。 | <> | 521KB -| An export of data from Twitter's API. +| 一份来自 Twitter API 的数据导出。 |=== -Hardware used for testing: **Intel(R) Core(TM) i7-7700K CPU @ 4.20GHz**, Windows 10, 32GB RAM. +测试所用硬件：**Intel(R) Core(TM) i7-7700K CPU @ 4.20GHz**, Windows 10, 32GB RAM. -Compilers and optimization flags: gcc 8.1 (-O3), clang 12.0 (-O3), and msvc 19.26 (/O2). +编译器及优化选项：gcc 8.1 (-O3), clang 12.0 (-O3), and msvc 19.26 (/O2) -== Parsing +== 解析 -=== Parse apache_builds.json +=== 解析 apache_builds.json image::images/parse_apache_builds.png[width=668,align="left"] -=== Parse canada.json +=== 解析 canada.json image::images/parse_canada.png[width=668,align="left"] -=== Parse citm_catalog.json +=== 解析 citm_catalog.json image::images/parse_citm_catalog.png[width=668,align="left"] -=== Parse github_events.json +=== 解析 github_events.json image::images/parse_github_events.png[width=668,align="left"] -=== Parse gsoc-2018.json +=== 解析 gsoc-2018.json image::images/parse_gsoc_2018.png[width=668,align="left"] -=== Parse instruments.json +=== 解析 instruments.json image::images/parse_instruments.png[width=668,align="left"] -=== Parse marine_ik.json +=== 解析 marine_ik.json image::images/parse_marine_ik.png[width=668,align="left"] -=== Parse mesh.json +=== 解析 mesh.json image::images/parse_mesh.png[width=668,align="left"] -=== Parse mesh.pretty.json +=== 解析 mesh.pretty.json image::images/parse_mesh_pretty.png[width=668,align="left"] -=== Parse numbers.json +=== 解析 numbers.json image::images/parse_numbers.png[width=668,align="left"] -=== Parse random.json +=== 解析 random.json image::images/parse_random.png[width=668,align="left"] -=== Parse twitter.json +=== 解析 twitter.json image::images/parse_twitter.png[width=668,align="left"] -=== Parse twitterescaped.json +=== 解析 twitterescaped.json image::images/parse_twitterescaped.png[width=668,align="left"] -=== Parse update-center.json +=== 解析 update-center.json image::images/parse_update_center.png[width=668,align="left"] -== Serialization +== 序列化 -=== Serialize canada.json +=== 序列化 canada.json image::images/serialize_canada.png[width=668,align="left"] -=== Serialize citm_catalog.json +=== 序列化 citm_catalog.json image::images/serialize_citm_catalog.png[width=668,align="left"] -=== Serialize github_events.json +=== 序列化 github_events.json image::images/serialize_github_events.png[width=668,align="left"] -=== Serialize gsoc-2018.json +=== 序列化 gsoc-2018.json image::images/serialize_gsoc_2018.png[width=668,align="left"] -=== Serialize instruments.json +=== 序列化 instruments.json image::images/serialize_instruments.png[width=668,align="left"] -=== Serialize marine_ik.json +=== 序列化 marine_ik.json image::images/serialize_marine_ik.png[width=668,align="left"] -=== Serialize mesh.json +=== 序列化 mesh.json image::images/serialize_mesh.png[width=668,align="left"] -=== Serialize mesh.pretty.json +=== 序列化 mesh.pretty.json image::images/serialize_mesh_pretty.png[width=668,align="left"] -=== Serialize numbers.json +=== 序列化 numbers.json image::images/serialize_numbers.png[width=668,align="left"] -=== Serialize random.json +=== 序列化 random.json image::images/serialize_random.png[width=668,align="left"] -=== Serialize twitter.json +=== 序列化 twitter.json image::images/serialize_twitter.png[width=668,align="left"] -=== Serialize twitterescaped.json +=== 序列化 twitterescaped.json image::images/serialize_twitterescaped.png[width=668,align="left"] -=== Serialize update-center.json +=== 序列化 update-center.json image::images/serialize_update_center.png[width=668,align="left"] From e5ec0329aeadf21adbec09863055d1bc737f607d Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Thu, 23 Apr 2026 15:13:27 +0000 Subject: [PATCH 39/68] Translated using Weblate (Chinese (Simplified Han script)) Currently translated at 100.0% (29 of 29 strings) Translation: Boost Json Translation (zh_Hans)/Doc / Pages / Comparison (adoc) Translate-URL: https://boost-weblate.cloud/projects/boost-json-documentation-zh_Hans/doc-pages-comparison-adoc/zh_Hans/ --- doc/pages/comparison_zh_Hans.adoc | 50 +++++++++++++++---------------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/doc/pages/comparison_zh_Hans.adoc b/doc/pages/comparison_zh_Hans.adoc index bac951c..76f082a 100644 --- a/doc/pages/comparison_zh_Hans.adoc +++ b/doc/pages/comparison_zh_Hans.adoc @@ -9,16 +9,16 @@ Official repository: https://github.com/boostorg/json //// [#comparison, pagelevels=1,toclevels=1] -= Comparison to Other Libraries += 与其他库的比较 :icon_good: pass:q[[.green]##✔##] :icon_bad: pass:q[[.red]##✘##] -There exist many C++ JSON libraries, but two are particularly noteworthy for the purpose of comparison: https://rapidjson.org/[RapidJSON], https://nlohmann.github.io/json/[JSON for Modern {cpp}] (referred to herein as nlohmann's JSON, or nlohmann), and https://github.com/lemire/simdjson[SIMD JSON]. +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]。 -== Comparison to nlohmann JSON +== 与nlohmann JSON的比较 -Value Type: https://github.com/nlohmann/json/blob/00cb98a3d170161711ab912ae6acefba31f29f75/include/nlohmann/json.hpp#L165[`nlohmann::basic_json`] +值类型：https://github.com/nlohmann/json/blob/00cb98a3d170161711ab912ae6acefba31f29f75/include/nlohmann/json.hpp#L165[`nlohmann::basic_json`] [source] ---- @@ -42,25 +42,25 @@ private: ... ---- -This library adopts a "kitchen sink" approach. It contains a wealth of features, even those with niche uses. Its weakness is that the many template parameters, while allowing for configurability, inhibit the best possible optimizations. The consequence is that the library performs poorly. The ability to configure every aspect of the value type has the paradoxical effect of making it less suitable as a vocabulary type. +该库采用了一种“大而全”（kitchen sink）的设计理念，包含大量功能，甚至涵盖一些使用场景非常小众的特性。其弱点在于：尽管众多模板参数提供了高度可配置性，却阻碍了编译器实现最优的性能优化。其结果是性能表现较差。这种对值类型各方面均可配置的能力，反而使其作为通用类型的适用性降低，形成了一种悖论效应。 -* {icon_bad} `basic_json` is a class template. Libraries must agree on the choices of template parameters to be interoperable. +* {icon_bad} `basic_json` 是一个类模板。各库必须在模板参数的选择上达成一致，才能实现互操作。 -* {icon_bad} Too much customization. We struggle to see a use case for making `BooleanType` anything other than `bool`. +* {icon_bad} 过度定制化。我们很难想象将 `BooleanType` 设置为 `bool` 之外的其他类型的使用场景。 -* {icon_bad} Poor separation of concerns. The `basic_json` container declaration needlessly conflates parsing and serialization APIs. +* {icon_bad} 关注点分离不佳。`basic_json` 容器声明不必要地将解析和序列化API混杂在一起。 -* {icon_bad} Limited allocator support. Only stateless allocators are allowed, which rules out the most important type of allocator, a local arena-based implementation. +* {icon_bad} 分配器支持有限。只允许无状态分配器，这排除了最重要的一类分配器，即基于本地内存池的实现。 -* {icon_bad} No incremental parsing, no incremental serialization. +* {icon_bad} 没有增量式解析，也没有增量式序列化。 -* {icon_bad} Slow parsing and serialization performance. +* {icon_bad} 解析和序列化性能较差。 -* {icon_good} Full-featured, including JSON Pointer, CBOR, and others. +* {icon_good} 功能全面，包含 JSON Pointer、CBOR 等特性。 -== Comparison to RapidJSON +== 与RapidJSON的比较 -Value Type: https://github.com/Tencent/rapidjson/blob/bb5f966b9939d6cdfbac3462a0410e185099b3af/include/rapidjson/document.h#L608[`rapidjson::GenericValue`] +值类型：https://github.com/Tencent/rapidjson/blob/bb5f966b9939d6cdfbac3462a0410e185099b3af/include/rapidjson/document.h#L608[`rapidjson::GenericValue`] [source] ---- @@ -74,29 +74,29 @@ template class GenericObject; ---- -* {icon_bad} The value type is not regular. Assignment is destructive, performing `a = b` is equivalent to `a = std::move(b)`. No copy construction or copy assignment allowed. +* {icon_bad} 值类型不满足“正规性”要求。赋值具有破坏性，执行 `a = b` 等同于 `a = std::move(b)`，且不允许复制构造和复制赋值。 -* {icon_bad} Object types have no hash table or index to reduce the cost of lookups. +* {icon_bad} 对象类型没有哈希表或索引用于降低查找成本。 -* {icon_bad} Allocators have reference semantics. Problems with lifetime are easily encountered. +* {icon_bad} 分配器采用引用语义，容易引发生命周期问题。 -* {icon_bad} The interface of the array and object types are considerably different from their standard library equivalents, and not idiomatic. +* {icon_bad} 数组和对象类型的接口与标准库中的对应类型差异显著，且不符合惯用法。 -* {icon_bad} No incremental parsing, no incremental serialization. +* {icon_bad} 没有增量式解析，也没有增量式序列化。 -* {icon_good} Parsing and serialization performance is better than most other libraries. +* {icon_good} 解析和序列化性能优于大多数其他库。 -=== Comparison to SIMD JSON +=== 与SIMD JSON的比较 [source] ---- class ParsedJson; ---- -This is quite an interesting data structure, which is optimized to work well with the SIMD parser. It makes very good design choices for the intended use-case. However it is not well suited as a vocabulary type due to the necessary limitations. +这是一种相当有趣的数据结构，专为与 SIMD 解析器协同工作而优化。它在目标使用场景下做出了非常优秀的设计选择。然而，由于其必要的限制，它不太适合作为通用类型。 -* {icon_bad} Sequential access only, via `ParsedJson::BasicIterator` +* {icon_bad} 仅支持通过 `ParsedJson::BasicIterator` 进行顺序访问 -* {icon_bad} Read-only, can only be populated by the provided SIMD JSON parser. +* {icon_bad} 为只读类型，仅能通过所提供的 SIMD JSON 解析器进行填充。 -* {icon_good} The fastest available JSON parser. +* {icon_good} 为目前最快的JSON解析器。 From cc81a66402ad4ee1a82e6a7791602a53aaac468d Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Thu, 23 Apr 2026 15:13:40 +0000 Subject: [PATCH 40/68] Translated using Weblate (Chinese (Simplified Han script)) Currently translated at 100.0% (8 of 8 strings) Translation: Boost Json Translation (zh_Hans)/Doc / Pages / Conversion / Alloc (adoc) Translate-URL: https://boost-weblate.cloud/projects/boost-json-documentation-zh_Hans/doc-pages-conversion-alloc-adoc/zh_Hans/ --- doc/pages/conversion/alloc_zh_Hans.adoc | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/doc/pages/conversion/alloc_zh_Hans.adoc b/doc/pages/conversion/alloc_zh_Hans.adoc index 75d87f1..0cab67b 100644 --- a/doc/pages/conversion/alloc_zh_Hans.adoc +++ b/doc/pages/conversion/alloc_zh_Hans.adoc @@ -7,15 +7,15 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) Official repository: https://github.com/boostorg/json //// -= Allocation Control -As <> creates a <> object, users may want to control the way memory is allocated for it. For this reason the function has an optional <> parameter, that is used to set the {ref_memory_resource} for the result. += 分配控制 +由于<>会创建一个<>对象，用户可能希望控制其内存分配方式。因此，该函数具有一个可选的 <> 参数，用于为结果指定{ref_memory_resource}。 [NOTE] -<> does not have a similar parameter, as <> is not created. +<> 没有类似的参数，因为该函数不会创建 <> 对象。 -As the conversion result is set via an output parameter of type `value&`, the intended <> is correctly propagated. But users still should take care to not create temporaries using the default {ref_memory_resource} by accident. +由于转换结果是通过类型为`value&`的输出参数设置的，因此预期的<>会被正确传播。但用户仍需注意，避免意外创建使用默认 {ref_memory_resource} 的临时对象。 -For example, consider this alternative implementation of `tag_invoke` for `ip_address` from the section <>. +例如，考虑<>节中针对`ip_address`的`tag_invoke`的替代实现。 ``` @@ -27,6 +27,6 @@ tag_invoke( const value_from_tag&, value& jv, ip_address const& addr ) ``` -This implementation explicitly creates an <> rather than relying on assignment from an initializer list. But the array uses default {ref_memory_resource}, not the one used by `jv`. +该实现显式创建了一个 <>，而不是依赖于初始化列表的赋值。但该数组使用的是默认的 {ref_memory_resource}，而不是`jv`所使用的内存资源。 -To avoid creating such temporaries with an incorrect {ref_memory_resource}, using <>'s member functions <>, <>, and <> can be helpful. +为避免创建使用错误 {ref_memory_resource} 的临时对象，可以借助 <> 的成员函数 <>、<> 和 <>。 From a048efa1fd6fe56ff1c5b67d3c8853e142e2bea7 Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Thu, 23 Apr 2026 15:14:20 +0000 Subject: [PATCH 41/68] Translated using Weblate (Chinese (Simplified Han script)) Currently translated at 100.0% (32 of 32 strings) Translation: Boost Json Translation (zh_Hans)/Doc / Pages / Conversion / Context (adoc) Translate-URL: https://boost-weblate.cloud/projects/boost-json-documentation-zh_Hans/doc-pages-conversion-context-adoc/zh_Hans/ --- doc/pages/conversion/context_zh_Hans.adoc | 44 +++++++++++------------ 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/doc/pages/conversion/context_zh_Hans.adoc b/doc/pages/conversion/context_zh_Hans.adoc index a59d22c..56de8d3 100644 --- a/doc/pages/conversion/context_zh_Hans.adoc +++ b/doc/pages/conversion/context_zh_Hans.adoc @@ -7,10 +7,10 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) Official repository: https://github.com/boostorg/json //// -= Contextual Conversions -Previously in this section we've been assuming that there is a particular fitting JSON representation for a type. But this is not always the case. Often one needs to represent particular value with JSON of certain format in one situation and with another format in a different situation. This can be achieved with Boost.JSON by providing an extra argument---context. += 上下文相关的转换 +此前在本节中，我们一直假定某个类型存在一种特定且合适的 JSON 表示形式。但实际情况并非总是如此。很多时候，同一个值在不同场景下需要以不同的 JSON 格式来表示。在 Boost.JSON 中，可以通过提供一个额外的参数——上下文（context）——来实现这一点。 -Let's implement conversion from `user_ns::ip_address` to a JSON string: +我们来实现从`user_ns::ip_address`到JSON字符串的转换： [source] ---- @@ -18,79 +18,79 @@ include::../../../test/snippets.cpp[tag=doc_context_conversion_1,indent=0] ---- -These `tag_invoke` overloads take an extra `as_string` parameter, which disambiguates this specific representation of `ip_address` from all other potential representations. In order to take advantage of them one needs to pass an `as_string` object to <> or <> as the last argument: +这些`tag_invoke`重载接受一个额外的`as_string`参数，用于将`ip_address`的这种特定表示形式与其他所有可能的表示形式区分开来。要使用这些重载，需要将`as_string`对象作为最后一个参数传递给 <> 或 <>： [source] ---- include::../../../test/snippets.cpp[tag=doc_context_conversion_2,indent=0] ---- -Note, that if there is no dedicated `tag_invoke` overload for a given type and a given context, the implementation falls back to overloads without context. Thus it is easy to combine contextual conversions with conversions provided by the library: +请注意，如果对于给定类型和给定上下文没有专用的`tag_invoke`重载，实现将回退到不带上下文的重载。因此，可以轻松地将上下文相关的转换与库提供的转换结合起来： [source] ---- include::../../../test/snippets.cpp[tag=doc_context_conversion_3,indent=0] ---- -== Conversions for Third-Party Types -Normally, you wouldn't be able to provide conversions for types from third-party libraries and standard types, because it would require yout to put `tag_invoke` overloads into namespaces you do not control. But with contexts you can put the overloads into your namespaces. This is because the context will add its associated namespaces into the list of namespaces where `tag_invoke` overloads are searched. +== 第三方类型的转换 +通常，您无法为第三方库或标准库中的类型提供转换函数，因为这需要将`tag_invoke`重载放入您无法控制的命名空间中。但借助上下文，您可以将这些重载放在自己的命名空间里。这是因为上下文会将其关联的命名空间添加到搜索`tag_invoke`重载的命名空间列表中。 -As an example, let's implement conversion for https://en.cppreference.com/w/cpp/chrono/system_clock[``std::chrono::system_clock::time_point``s] using https://en.wikipedia.org/wiki/ISO_8601[ISO 8601] format. +例如，我们来使用 https://en.wikipedia.org/wiki/ISO_8601[ISO 8601]格式，对 https://en.cppreference.com/w/cpp/chrono/system_clock[``std::chrono::system_clock::time_point``] 实现转换。 [source] ---- include::../../../test/snippets.cpp[tag=doc_context_conversion_4,indent=0] ---- -Reverse conversion is left out for brevity. +为简洁起见，反向转换在此省略。 -The new context is used in a similar fashion to `as_string` previously in this section. +这个新上下文的使用方式与本节前面介绍的`as_string`类似。 [source] ---- include::../../../test/snippets.cpp[tag=doc_context_conversion_5,indent=0] ---- -One particular use case that is enabled by contexts is adaptor libraries that define JSON conversion logic for types from a different library. +上下文支持的一个特定用例是适配器库，这些库为来自不同库的类型定义JSON转换逻辑。 -== Passing Data to Conversion Functions -Contexts we used so far were empty classes. But contexts may have data members and member functions just as any class. Implementers of conversion functions can take advantage of that to have conversions configurable at runtime or pass special objects to conversions (e.g. allocators). +== 向转换函数传递数据 +到目前为止，我们使用的上下文都是空类。但上下文可以像普通类一样拥有数据成员和成员函数。转换函数的实现者可以利用这一点，在运行时对转换行为进行配置，或向转换函数传递特殊对象（例如分配器）。 -Let's rewrite conversion for ``system_clock::time_point``s to allow any format supported by `std::strftime`. +我们来重写``system_clock::time_point``的转换，以支持`std::strftime`所支持的任意格式。 [source] ---- include::../../../test/snippets.cpp[tag=doc_context_conversion_6,indent=0] ---- -This `tag_invoke` overload lets us change date conversion format at runtime. Also note, that there is no ambiguity between `as_iso_8601` overload and `date_format` overload. You can use both in your program: +这个`tag_invoke`重载允许我们在运行时更改日期转换的格式。另外请注意，`as_iso_8601`重载和`date_format`重载之间不存在歧义。您可以在程序中使用两者： [source] ---- include::../../../test/snippets.cpp[tag=doc_context_conversion_7,indent=0] ---- -== Combining Contexts -Often it is needed to use several conversion contexts together. For example, consider a log of remote users identified by IP addresses accessing a system. We can represent it as `std::vector>`. We want to serialize both ``ip_address``es and ``time_point``s as strings, but for this we need both `as_string` and `as_iso_8601` contexts. To combine several contexts just use {std_tuple}. Conversion functions will select the first element of the tuple for which a `tag_invoke` overload exists and will call that overload. As usual, `tag_invoke` overloads that don't use contexts and library-provided generic conversions are also supported. Thus, here's our example: +== 组合上下文 +通常需要同时使用多个转换上下文。例如，考虑一个记录远程用户（通过 IP 地址标识）访问系统的日志，我们可以将其表示为 `std::vector>`。我们希望将``ip_address``和``time_point``都序列化为字符串，但这需要同时使用`as_string`和`as_iso_8601`两个上下文。要组合多个上下文，只需使用{std_tuple}。转换函数会从元组中选择第一个存在对应 `tag_invoke` 重载的元素，并调用该重载。与往常一样，不使用上下文的`tag_invoke`重载和库提供的通用转换也受支持。因此，我们的示例如下： [source] ---- include::../../../test/snippets.cpp[tag=doc_context_conversion_8,indent=0] ---- -In this snippet `time_point` is converted using `tag_invoke` overload that takes `as_iso_8601`, `ip_address` is converted using `tag_invoke` overload that takes `as_string`, and {std_vector} is converted using a generic conversion provided by the library. +在此代码片段中，`time_point`通过接受`as_iso_8601`的`tag_invoke`重载进行转换，`ip_address`通过接受`as_string`的`tag_invoke`重载进行转换，而{std_vector}则使用库提供的通用转换进行转换。 -== Contexts and Composite Types -As was shown previously, generic conversions provided by the library forward contexts to conversions of nested objects. And in the case when you want to provide your own conversion function for a composite type enabled by a particular context, you usually also need to do that. +== 上下文与复合类型 +如前所示，库提供的通用转换会将上下文传递给嵌套对象的转换函数。因此，当您希望为特定上下文启用的某个复合类型提供自己的转换函数时，通常也需要这样做 -Consider this example. As was discussed in a previous section, <> requires that your key type satisfies <>. Now, let's say your keys are not string-like, but they do convert to <>. You can make such maps to also convert to objects using a context. But if you want to also use another context for values, you need a way to pass the full combined context to map elements. So, you want the following test to succeed. +考虑以下示例。如前一节所述，<>要求键类型满足<>。现在，假设您的键不是类字符串类型，但它们确实可以转换为<>。您可以通过上下文使此类映射也转换为对象。但如果您想同时为值使用另一个上下文，则需要一种方式将完整的组合上下文传递给映射元素。因此，您希望以下测试能够成功。 [source] ---- include::../../../test/snippets.cpp[tag=doc_context_conversion_9,indent=0] ---- -For this you will have to use a different overload of `tag_invoke`. This time it has to be a function template, and it should have two parameters for contexts. The first parameter is the specific context that disambiguates that particular overload. The second parameter is the full context passed to <> or <>. +为此，您必须使用另一个`tag_invoke`重载。这次，它必须是一个函数模板，并且应包含两个上下文参数。第一个参数是用于区分该特定重载的具体上下文；第二个参数是传递给 <> 或<>的完整上下文。 [source] ---- From 8ff1a82580fbc4e917f537a054da2abc7f3813a6 Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Thu, 23 Apr 2026 15:14:50 +0000 Subject: [PATCH 42/68] Translated using Weblate (Chinese (Simplified Han script)) Currently translated at 100.0% (23 of 23 strings) Translation: Boost Json Translation (zh_Hans)/Doc / Pages / Conversion / Custom (adoc) Translate-URL: https://boost-weblate.cloud/projects/boost-json-documentation-zh_Hans/doc-pages-conversion-custom-adoc/zh_Hans/ --- doc/pages/conversion/custom_zh_Hans.adoc | 32 ++++++++++++------------ 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/doc/pages/conversion/custom_zh_Hans.adoc b/doc/pages/conversion/custom_zh_Hans.adoc index e4ad29d..557e560 100644 --- a/doc/pages/conversion/custom_zh_Hans.adoc +++ b/doc/pages/conversion/custom_zh_Hans.adoc @@ -7,36 +7,36 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) Official repository: https://github.com/boostorg/json //// -= Custom Conversions -Boost.JSON uses two mechanisms to customize conversion between <> and user types. One mechanism involves specializing type traits. The other one is more powerful and requires defining overloads of `tag_invoke`. Both mechanisms will be further explained in this section. += 自定义转换 +Boost.JSON 提供了两种机制用于自定义 <> 与用户类型之间的转换。一种机制涉及特化类型特征（type traits）。另一种机制更强大，需要定义`tag_invoke`的重载。本节将进一步解释这两种机制。 -== Conversion Traits -Previously a number of conversion type traits, like <> or <>, were introduced. The library tries the traits one after another and uses the implementation that corresponds to the first matching trait. In some cases, though, a type would match a trait with a higher priority, but the user intends for it to belong to a lower priority category. If this happens the user can specialize the trait that's not supposed to match for that type to be an equivalent of `std::false_type`. +== 转换特征 +之前已经介绍了一些转换类型特征，例如 <> 或 <>。库会依次尝试这些特征，并使用与第一个匹配特征对应的实现。然而，在某些情况下，某个类型可能会匹配到优先级更高的特征，而用户实际希望将其归入优先级更低的类别。如果发生这种情况，用户可以针对该类型特化那个不应匹配的特征，使其等同于`std::false_type`。 -Consider this type: +考虑以下类型： [source] ---- include::../../../test/doc_types.hpp[tag=snippet_conv_spec_trait1,indent=0] ---- -It exposes both a sequence API and a tuple API. But converting from <> to `user_ns::ip_address` would not be able to use implementation for sequences, since those are constructed empty and then populated one element at a time, while `ip_address` has a fixed size of 4. The tuple conversion would fit, though. The only problem is that <> has a lower priority than <>. In order to circumvent this, the user only needs to specialize <> to not match `ip_address`. +它同时暴露了序列（sequence）API 和元组（tuple）API。然而，从 <> 转换到 user_ns::ip_address 时无法使用序列的实现，因为序列类型的转换会先构造一个空对象，再逐个填充元素，而 ip_address 的大小固定为 4。相比之下，元组转换是合适的。唯一的问题在于 <> 的优先级低于 <>。为绕过此问题，用户只需特化 <>，使其对 ip_address 不匹配即可。 [source] ---- include::../../../test/snippets.cpp[tag=snippet_conv_spec_trait2,indent=0] ---- -== `tag_invoke` Overloads -The second, more powerful approach, is to provide the conversion implementation yourself. With Boost.JSON this is done by defining an overload of `tag_invoke` function (the benefits of this mechanism are outlined in http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1895r0.pdf[C++ proposal P1895]. In essence, `tag_invoke` provides a uniform interface for defining customization points by using argument-dependent lookup to find a viable overload from the point at which it is called. As the name suggests, a tag type is passed as an argument in order to: +== `tag_invoke`重载 +第二种、更强大的方法是自行提供转换实现。在 Boost.JSON 中，这是通过定义`tag_invoke`函数的重载来实现的（该机制的优点详见 http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1895r0.pdf[C++提案P1895]）。本质上，`tag_invoke` 通过参数依赖查找（ADL）在调用点寻找可用的重载，从而为自定义扩展点提供统一接口。顾名思义，一个标签类型作为参数传递，用于： -* discard candidates that are unrelated to that particular customization point, and +* 1. 排除与该特定自定义点无关的候选函数，并且 -* embed the user-defined type into the arguments list (e.g. by using a tag type template such as `value_to_tag`) so that its http://eel.is/c++draft/basic.lookup.argdep#2[associated namespaces and entities] are examined when name lookup is performed. +* 2. 将用户定义的类型嵌入到参数列表中（例如，通过使用像`value_to_tag`这样的标签类型模板），以便在执行名称查找时检查其http://eel.is/c++draft/basic.lookup.argdep#2[关联的命名空间和实体]。 -This has the effect of finding user-provided `tag_invoke` overloads, even if they are declared (lexically) after the definition of the calling function. +这样做的效果是能够找到用户提供的`tag_invoke`重载，即使它们在调用函数定义之后（在词法上）声明。 -Overloads of `tag_invoke` called by <> take the form: +由 <> 调用的 tag_invoke 重载具有如下形式： ``` @@ -44,7 +44,7 @@ void tag_invoke( const value_from_tag&, value&, T ); ``` -While overloads of `tag_invoke` called by <> take the form: +而由 <> 调用的`tag_invoke`重载采用以下形式： ``` @@ -52,21 +52,21 @@ T tag_invoke( const value_to_tag< T >&, const value& ); ``` -If we implemented conversion for `user_ns::ip_address` manually with this approach, it would look like this: +如果我们用这种方法手动实现`user_ns::ip_address`的转换，它将如下所示： [source] ---- include::../../../test/snippets.cpp[tag=snippet_tag_invoke_1,indent=0] ---- -Since the type being converted is embedded into the function's signature, user-provided overloads are visible to argument-dependent lookup and will be candidates when a conversion is performed: +由于被转换的类型已嵌入函数签名中，用户提供的重载对参数依赖查找（ADL）可见，并会在执行转换时成为候选函数： [source] ---- include::../../../test/snippets.cpp[tag=snippet_tag_invoke_2,indent=0] ---- -Users can freely combine types with custom conversions with types with library-provided conversions. The library handles them correctly: +用户可以自由地将具有自定义转换的类型与具有库提供转换的类型组合使用，库能正确处理它们： [source] ---- From 557f1f0ecc23d931d3e80b8cafd89123346e4f51 Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Thu, 23 Apr 2026 15:15:03 +0000 Subject: [PATCH 43/68] Translated using Weblate (Chinese (Simplified Han script)) Currently translated at 100.0% (8 of 8 strings) Translation: Boost Json Translation (zh_Hans)/Doc / Pages / Conversion / Direct (adoc) Translate-URL: https://boost-weblate.cloud/projects/boost-json-documentation-zh_Hans/doc-pages-conversion-direct-adoc/zh_Hans/ --- doc/pages/conversion/direct_zh_Hans.adoc | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/doc/pages/conversion/direct_zh_Hans.adoc b/doc/pages/conversion/direct_zh_Hans.adoc index 1d89d1e..24f0d50 100644 --- a/doc/pages/conversion/direct_zh_Hans.adoc +++ b/doc/pages/conversion/direct_zh_Hans.adoc @@ -7,20 +7,20 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) Official repository: https://github.com/boostorg/json //// -= Direct Conversion -For large inputs parsing into the library's containers followed by conversion via <> (or vice versa <> followed by serialization from a <>) might be prohibitively expensive. For these cases the library provides components that allow parsing directly into and serializing directly from user-provided objects. += 直接转换 +对于大型输入，先解析到库的容器中，再通过 <> 进行转换（或反之，先通过 <> 转换，再从 <> 序列化）可能代价过高。针对这类场景，库提供了可直接将数据解析到用户提供的对象中、或直接从用户提供的对象进行序列化的组件。 -The drawback of this approach is that fully custom type representations are not supported, only the library-provided conversions are. Also all objects that should be populated by parsing have to be default constructible types. This includes not only the top-level object, but e.g. elements of containers, members of described `struct`s, and alternatives of variants. +这种方法的缺点在于，不支持完全自定义的类型表示，仅支持库提供的转换。此外，所有需通过解析进行填充的对象都必须是可默认构造的类型——这不仅包括顶层对象，也包括容器的元素、所描述`struct`的成员以及变体类型的备选项。 -That being said, if your types are default-constructible and you don't need the customisability allowed by <> and <>, then you can get a significant performance boost with direct conversions. +尽管如此，如果你的类型是可默认构造的，并且不需要 <> 和 <> 所提供的自定义能力，那么使用直接转换可以获得显著的性能提升。 -Direct parsing is performed by the <> family of functions. The library provides overloads that take either <> or `std::istream`, and can report errors either via throwing exceptions or setting an error code. +直接解析是由<> 系列函数执行的。库提供了接受<<> 或`std::istream`的重载，并且可以通过抛出异常或设置错误码来报告错误。 [source] ---- include::../../../test/snippets.cpp[tag=doc_parse_into_1,indent=0] ---- -If you need to combine incremental parsing with direct parsing, you can resort to <>. `parser_for` is an instantiation of <> that parses into an object of type `T`, and is what <> uses under the hood. +如果需要将增量解析与直接解析结合使用，可以借助 <>。`parser_for`是<> 的一个实例化，用于将数据解析到类型为`T`的对象中，并且是<>在底层所使用的。 -Direct serialization doesn't require any special components and works with the regular <> and <>. +直接序列化不需要任何特殊组件，可直接使用常规的 <> 和<>。 From 4c846b6abcb9cfbd2a189d3d36da2dc0276dfc94 Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Thu, 23 Apr 2026 15:15:18 +0000 Subject: [PATCH 44/68] Translated using Weblate (Chinese (Simplified Han script)) Currently translated at 100.0% (9 of 9 strings) Translation: Boost Json Translation (zh_Hans)/Doc / Pages / Conversion / Forward (adoc) Translate-URL: https://boost-weblate.cloud/projects/boost-json-documentation-zh_Hans/doc-pages-conversion-forward-adoc/zh_Hans/ --- doc/pages/conversion/forward_zh_Hans.adoc | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/pages/conversion/forward_zh_Hans.adoc b/doc/pages/conversion/forward_zh_Hans.adoc index bb45b01..30a19aa 100644 --- a/doc/pages/conversion/forward_zh_Hans.adoc +++ b/doc/pages/conversion/forward_zh_Hans.adoc @@ -7,26 +7,26 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) Official repository: https://github.com/boostorg/json //// -= Avoiding Physical Dependency -Some users, particularly library authors, may wish to provide conversions between their types and <>, but at the same time would prefer to avoid having their library depend on Boost.JSON. This is possible to achieve with the help of a few forward declarations. += 避免物理依赖 +一些用户（尤其是库作者）可能希望为其类型与 <> 提供转换功能，但同时又希望避免让自己的库依赖 Boost.JSON。借助一些前向声明，即可实现这一目标。 [source] ---- include::../../../test/doc_forward_conversion.cpp[tag=doc_forward_conversion_1,indent=0] ---- -Note that <> is declared using an out-parameter, rather then returning its result. This overload is specifically designed for this use-case. +请注意，<> 是通过输出参数声明的，而非返回其结果。该重载正是为这一使用场景而设计的。 -After that the definitions of `tag_invoke` overloads should be provided. These overloads have to be templates, since <> is only forward-declared and hence is an incomplete type. +之后应提供 `tag_invoke` 重载的定义。这些重载必须是模板，因为 <> 仅是前向声明的，因此是一个不完整类型。 [source] ---- include::../../../test/doc_forward_conversion.cpp[tag=doc_forward_conversion_2,indent=0] ---- -As discussed previously, we prefer to define a non-throwing overload of `tag_invoke` for <>, rather then the throwing overload for <>, as the latter can fallback to the former without performance degradation. +如前所述，我们更倾向于为 <> 定义不抛异常的 `tag_invoke` 重载，而不是为 <> 定义抛异常的重载，因为后者可以在无性能损失的情况下回退到前者。 -Forward declarations of contextual conversions are done very similarly: +上下文相关转换的前向声明方式与此非常相似： [source] ---- From dcc4b35aae2513df906f8bc5d76fe91f9ad50cab Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Thu, 23 Apr 2026 15:15:30 +0000 Subject: [PATCH 45/68] Translated using Weblate (Chinese (Simplified Han script)) Currently translated at 100.0% (7 of 7 strings) Translation: Boost Json Translation (zh_Hans)/Doc / Pages / Conversion / Guidelines (adoc) Translate-URL: https://boost-weblate.cloud/projects/boost-json-documentation-zh_Hans/doc-pages-conversion-guidelines-adoc/zh_Hans/ --- doc/pages/conversion/guidelines_zh_Hans.adoc | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/doc/pages/conversion/guidelines_zh_Hans.adoc b/doc/pages/conversion/guidelines_zh_Hans.adoc index 162b62a..15b5a3a 100644 --- a/doc/pages/conversion/guidelines_zh_Hans.adoc +++ b/doc/pages/conversion/guidelines_zh_Hans.adoc @@ -7,15 +7,15 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) Official repository: https://github.com/boostorg/json //// -= Conversion Customization Guidelines -With so many options, it can be hard to choose the best way to customise conversion for your type. In this section, we will discuss those options and suggest which to choose when. += 转换自定义指南 +由于选项众多，为类型选择最合适的转换自定义方式可能并不容易。本节将讨论这些选项，并给出不同场景下的选用建议。 -The first advice is to use one of the library-provided conversions, rather then providing a custom one, unless the resulting format is undesirable. If the library deduces the wrong conversion category, you can opt out by specialising the relevant trait to inherit from `std::false_type`. +首要建议是：除非生成的格式不符合需求，否则应优先使用库提供的转换，而非自行实现自定义转换。如果库错误地推断了转换类别，你可以通过将相关特征特化为继承自 `std::false_type` 来排除该转换。 -If library-provided conversions are suitable for you, you have the option to use direct conversions. This also puts the requirement of being default constructible on many of your types. +如果库提供的转换对你适用，你可以选择使用直接转换。但这同时也要求你的许多类型必须是可默认构造的。 -The next thing to consider is whether your conversions are intended for internal use, or whether your users are not members of your team. If your users are external, then they will ultimately determine the conditions in which these conversions will be used. Conversely, for internal libraries and applications, you have the full control of usage conditions. +接下来需要考虑的是：您的转换是仅供内部使用，还是面向团队以外的用户。如果您的用户属于外部人员，那么他们最终将决定这些转换的使用条件；反之，对于内部库和应用程序，您可以完全掌控其使用条件。 -If your users are external, they and not you decide whether throwing exceptions is acceptable. So, in this case it is better to use non-throwing `tag_invoke` overloads. In addition, for customising conversion of composite types, always use `tag_invoke` overload with 2 context parameters. This will allow correct context propagation to elements of composites. This will also allow propagation of exceptions from conversion of elements. +如果您的用户是外部的，那么是否允许抛出异常是由他们而非您来决定的。因此，在这种情况下，最好使用不抛异常的 `tag_invoke` 重载。此外，在自定义复合类型的转换时，应始终使用带有两个上下文参数的 `tag_invoke` 重载。这将确保上下文能正确传递给复合类型的各个元素，同时也支持从元素转换中传播异常。 -Finally, it is worth mentioning that due to the ability to provide conversions to JSON containers without a binary dependency on the library, you don't have to push such dependency on your users. This is particularly relevant for libraries for which interoperation with Boost.JSON is only ancillary. +最后值得一提的是，由于可以在不引入对库的二进制依赖的前提下提供到 JSON 容器的转换，因此您无需将此类依赖强加给您的用户。这一点对于那些仅需与 Boost.JSON 进行辅助性互操作的库尤为重要。 From 3867d159879060a0224ec0d3434055fd3e6552ed Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Thu, 23 Apr 2026 15:15:46 +0000 Subject: [PATCH 46/68] Translated using Weblate (Chinese (Simplified Han script)) Currently translated at 100.0% (11 of 11 strings) Translation: Boost Json Translation (zh_Hans)/Doc / Pages / Conversion / Nothrow (adoc) Translate-URL: https://boost-weblate.cloud/projects/boost-json-documentation-zh_Hans/doc-pages-conversion-nothrow-adoc/zh_Hans/ --- doc/pages/conversion/nothrow_zh_Hans.adoc | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/pages/conversion/nothrow_zh_Hans.adoc b/doc/pages/conversion/nothrow_zh_Hans.adoc index 462f5da..cf3957f 100644 --- a/doc/pages/conversion/nothrow_zh_Hans.adoc +++ b/doc/pages/conversion/nothrow_zh_Hans.adoc @@ -7,13 +7,13 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) Official repository: https://github.com/boostorg/json //// -= Non-Throwing Conversions -For the case where throwing exceptions is undesirable, Boost.JSON also provides a non-throwing version of <>, the function template <>. It returns {ref_result}, a specialised variant that either holds a value or an {ref_error_code}. += 不抛异常的转换 +对于不希望抛出异常的场景，Boost.JSON 还提供了 <> 的不抛异常版本，即函数模板 <>。它返回 {ref_result}，这是一个特化的变体类型，要么持有转换得到的值，要么持有 {ref_error_code}。 [NOTE] -There's no non-throwing equivalent for <>. This is simply because we haven't yet encountered a situation where <> needed to communicate an error to the caller. +对于 <>; 没有对应的不抛异常版本。这仅仅是因为我们尚未遇到需要 <> 向调用者报告错误的情况。 -The library provides non-throwing conversions for all the categories of types it supports with <>. If a user wants to use it with custom types, an overload of `tag_invoke` of this form needs to be provided: +该库为 <> 所支持的所有类型类别均提供了不抛异常的转换。如果用户希望将其用于自定义类型，则需要提供如下形式的 `tag_invoke` 重载： ``` @@ -21,20 +21,20 @@ result_for::type tag_invoke( const try_value_to_tag< T >&, const value ``` -For the class `ip_address` from the section <> this overload may look like this: +对于 <> 节中所述的 `ip_address` 类，该重载可能如下所示： [source] ---- include::../../../test/snippets.cpp[tag=snippet_nothrow_1,indent=0] ---- -The overload lets us use `ip_address` with <>. +该重载使我们能够将 `ip_address` 与 <> 一起使用。 [source] ---- include::../../../test/snippets.cpp[tag=snippet_nothrow_2,indent=0] ---- -If <> is used with a type, for which there's no `tag_invoke` overload of the form described in this section, but there is one of the form intended for <>, then the library still tries to perform the conversion. It uses the throwing overload, and attempts to convert any thrown exception into an {ref_error_code}. Note, though, that such approach will likely be slower then a dedicated overload. +如果对某个类型使用 <>，而该类型没有本节所述形式的 `tag_invoke` 重载，但存在适用于 <> 的重载，那么库仍会尝试执行转换：它会调用抛异常的重载，并试图将抛出的任何异常转换为 {ref_error_code}。但请注意，这种方式的性能很可能不如专门提供的不抛异常重载。 -The opposite is also true: if there's a `tag_invoke` overload intended for <>, but not for <>, then calling <> will invoke the non-throwing overload, then construct a {ref_system_error} from the {ref_error_code} and throw it. Due to these fallbacks, it is recommended that users provide the overload from this section, rather then the other one, if they ever intend to use <>. +反之亦然：如果存在适用于<> 的 tag_invoke 重载，但没有适用于 <> 的重载，那么调用 <> 时会转而调用不抛异常的重载，随后根据返回的 {ref_error_code} 构造一个 {ref_system_error} 并抛出。由于存在上述回退机制，建议用户在计划使用 <> 时，优先提供本节所述的不抛异常重载，而非抛异常的重载。 From 23ad003d7876838321168152179037fabee0c36a Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Thu, 23 Apr 2026 15:16:53 +0000 Subject: [PATCH 47/68] Translated using Weblate (Chinese (Simplified Han script)) Currently translated at 100.0% (56 of 56 strings) Translation: Boost Json Translation (zh_Hans)/Doc / Pages / Conversion / Overview (adoc) Translate-URL: https://boost-weblate.cloud/projects/boost-json-documentation-zh_Hans/doc-pages-conversion-overview-adoc/zh_Hans/ --- doc/pages/conversion/overview_zh_Hans.adoc | 146 ++++++++++----------- 1 file changed, 69 insertions(+), 77 deletions(-) diff --git a/doc/pages/conversion/overview_zh_Hans.adoc b/doc/pages/conversion/overview_zh_Hans.adoc index bfd315e..1b505af 100644 --- a/doc/pages/conversion/overview_zh_Hans.adoc +++ b/doc/pages/conversion/overview_zh_Hans.adoc @@ -10,114 +10,106 @@ Official repository: https://github.com/boostorg/json //// [#conversion] -= Value Conversion -While the <> container makes it easy to create ad-hoc structures, often it is necessary to convert between JSON and user-defined types or types from the standard library. += 值转换 +尽管 <> 容器便于创建临时结构，但通常仍需在 JSON 与用户自定义类型或标准库类型之间进行转换。 -The function template <> provides an interface to construct a <> from a type `T`. The function template <> converts in the opposite direction, from a type `T` to <>. Both support a wide variety of different https://en.cppreference.com/w/cpp/language/types[fundamental types], such as `int` or `double`, standard library types, such as `std::string` or `std::vector`, and can be extended to support user-defined types. +函数模板 <> 提供了从类型 `T` 构造 <> 的接口。函数模板 <> 则执行相反方向的转换，从类型 `T` 转换为 <>。两者均支持多种不同的 https://en.cppreference.com/w/cpp/language/types[基础类型]（如 `int` 或 `double`）、标准库类型（如 `std::string` 或 `std::vector`），并可扩展以支持用户定义类型。 [source] ---- include::../../../test/snippets.cpp[tag=snippet_conv_1,indent=0] ---- -For the type `T`, the appropriate conversion approach is chosen from the following list of categories. The first matching category is selected. +对于类型 `T`，将从以下类别列表中选择合适的转换方式，并采用第一个匹配的类别。 -.Conversion categories +.转换类别 [%autowidth, cols=4] |=== -|Category of T|Comment|`value_from` behavior|`value_to` behavior +|T 的类别|注释|`value_from` 行为|`value_to` 行为 -|Custom conversion. +|自定义转换。 | -|Custom behavior. -|Custom behavior. +|自定义行为。 +|自定义行为。 -|Boost.JSON container. +|Boost.JSON 容器。 | -|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[Arithmetic type] +|https://en.cppreference.com/w/cpp/types/is_arithmetic[算术类型] | -a| The result is a number equal to input and has the type - -* `std::int64_t`, if `T` is a signed integer'; or -* `std::uint64_t`, if `T` is an unsigned integer; or -* `double` otherwise. -|The result is created via <>. - -|Type satisfying <> -|Intended for types like {std_monostate}. -|The result is a null value. -|The result is default-constructed. - -|Type satisfying <>. -|A sequence of `char`s, e.g. `std::string`. -|The result is a <>. -|The result is constructed from a <>. - -|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 - alternative. -|The result holds the first alternative for which a conversion succeeds. - -|Type satisfying <> +a| 结果为一个数值，等于输入值且类型为： + +* 若 `T` 为有符号整数，则为 `std::int64_t`；或 +* 若 `T` 为无符号整数，则为 `std::uint64_t`；或 +* 否则为 `double`。 +|结果通过 <> 创建。 + +|满足 <> 的类型 +|适用于类似 {std_monostate} 的类型。 +|结果为空值。 +|结果将被默认构造。 + +|满足 <> 的类型。 +|`char` 序列，例如 `std::string`。 +|结果为 <>。 +|结果由 <> 构造。 + +|满足 <> 的类型。 +|`std::variant` 及类似类型，例如 `boost::variant2::variant`。 +|结果等同于对活跃的变体备选项进行转换所得的结果。 +|结果包含首个转换成功的备选项。 + +|满足 <> 的类型 | -|If the input value is empty, the result is a `null`. Otherwise it is - equivalent to conversion of the object stored inside of optional. -|The result is default constructed if the input value is `null`. Otherwise the - result is constructed from the result of conversion of the input to the - type stored in optional. - -|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. - -|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. - -|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 <> +|若输入值为空，则结果为 `null`；否则等同于对可选类型内部存储对象的转换结果。 +|若输入值为 `null`，则结果为默认构造；否则结果由输入值转换为可选类型内部存储类型的结果构造。 + +|满足 <> 的类型。 +|具有类字符串键的一对一映射（例如 `std::map`）。 +|结果为 <>。 +|结果为默认构造，元素在末尾通过 `insert` 被插入。 + +|满足 <> 的类型。 +|元素序列，例如 `std::vector`。 +|结果是一个 <>。 +|结果为默认构造，元素在末尾通过 `insert` 被插入。 + +|满足 <> 的类型。 +|一种大小固定的异构序列，例如 `std::tuple` 和 `std::pair`。 +|结果是一个 <>。 +|结果通过将数组元素作为构造函数参数进行构造。 + +|满足 <> 的类型 | -|The result is an <> with described members' names as keys. -|The result is default-constructed and described members are assigned - corresponding values. +|结果是一个 <>，其键为所描述成员的名称。 +|结果将被默认构造，并为其所描述的成员赋予相应的值。 -|Type satisfying <> +|满足 <> 的类型 | -|If the input value is equal to one of the described enumerators, the result is - a <>, containing its name. Otherwise it's equal to the input - value converted to its underlying type. -|The result is the described enumerator, corresponding to the input - <>. - -|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`. +|如果输入值等于某个已描述的枚举项，则结果为一个包含该枚举项名称的 <>；否则，结果等同于将输入值转换为其底层类型后的值。 +|结果为与输入 <> 对应的已描述枚举项。 + +|满足 <> 的类型。 +|`std::filesystem::path` 及类似类型，例如 `boost::filesystem::path`。 +|结果等于 `path::generic_string` 的结果。 +|结果由两个指向 `const char` 的指针构造而成。 |=== -For composite types (sequences, tuples, described classes, etc.) conversion of contained objects is applied recursively. For example: +对于复合类型（如序列、元组、已描述的类等），对其所包含对象的转换会递归应用。例如： [source] ---- include::../../../test/snippets.cpp[tag=snippet_conv_recursive,indent=0] ---- -Here, the map is converted into an <>, since it matches <>. Each of its keys is converted into a <>, as `std::string` matches <>, and each of its values is converted into an <>, as `std::pair` matches <>. Finally, elements of pairs are converted into a `std::int64_t` number and a `bool`. +此处，该映射被转换为一个 <>，因为它匹配 <>。其每个键被转换为一个 <>（因为 `std::string` 匹配 <>），而每个值被转换为一个 <>（因为 `std::pair` 匹配 <>）。最后，每对元素分别被转换为一个 `std::int64_t` 类型的数值和一个 `bool` 值。 :leveloffset: +1 From bbf4d49f0773c8f7bc09b9c7b606dd040ec3d26b Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Thu, 23 Apr 2026 15:17:12 +0000 Subject: [PATCH 48/68] Translated using Weblate (Chinese (Simplified Han script)) Currently translated at 100.0% (13 of 13 strings) Translation: Boost Json Translation (zh_Hans)/Doc / Pages / Dom / Array (adoc) Translate-URL: https://boost-weblate.cloud/projects/boost-json-documentation-zh_Hans/doc-pages-dom-array-adoc/zh_Hans/ --- doc/pages/dom/array_zh_Hans.adoc | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/pages/dom/array_zh_Hans.adoc b/doc/pages/dom/array_zh_Hans.adoc index de5deff..8d40e9b 100644 --- a/doc/pages/dom/array_zh_Hans.adoc +++ b/doc/pages/dom/array_zh_Hans.adoc @@ -10,38 +10,38 @@ Official repository: https://github.com/boostorg/json [#dom_array] = `array` -A <> stores an instance of <> as the underlying representation for a JSON array. Instances of the __array__ type function identically to a {std_vector} of <>. Additionally, all values inserted into the container will use the same <> as the container itself. +一个 <> 存储一个 <> 的实例，作为 JSON 数组的底层表示。__array__ 类型的实例与存储 <> 的 {std_vector} 功能完全相同。此外，所有插入容器的值将使用与容器本身相同的 <>。 -An empty array may be constructed without incurring any memory allocations using the <>. A <> can also be explicitly specified: +可以使用 <> 构造一个空数组，而不会产生任何内存分配。也可以显式指定一个 <>： [source] ---- include::../../../test/snippets.cpp[tag=snippet_arrays_1,indent=0] ---- -Initializer lists can be used to construct objects with initial contents. These constructors may allocate memory and throw: +可以使用初始化列表来构造带有初始内容的对象。这些构造函数可能会分配内存并抛出异常： [source] ---- include::../../../test/snippets.cpp[tag=snippet_arrays_2,indent=0] ---- -Alternatively, elements may be inserted after construction: +或者，也可以在构造之后插入元素： [source] ---- include::../../../test/snippets.cpp[tag=snippet_arrays_3,indent=0] ---- -Similar to its standard library counterpart, elements may be accessed directly by their 0-based index with bounds checking using <>, or without bounds checking using <>: +与标准库中的对应容器类似，元素可通过从 0 开始的索引直接访问：使用 <<> 进行带边界检查的访问，或使用 <> 进行不带边界检查的访问： [source] ---- include::../../../test/snippets.cpp[tag=snippet_arrays_4,indent=0] ---- -For the complete listing of all available member functions and nested types, see the reference page for <>. +有关所有可用成员函数和嵌套类型的完整列表，请参阅 <> 的参考页面。 -== Formatted Output +== 格式化输出 -When an <> is formatted to a {std_ostream}, the result is a valid JSON. That is, the array will be output with square brackets and the comma separated list of values, as per the JSON specification. +当将 <> 输出到 {std_ostream} 时，结果是一个符合 JSON 规范的有效 JSON：数组将以方括号括起，并以逗号分隔其中的值。 From c2d3b8f63b7c792ae8d8c9d10ca2e04c1d81f1c8 Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Thu, 23 Apr 2026 15:17:43 +0000 Subject: [PATCH 49/68] Translated using Weblate (Chinese (Simplified Han script)) Currently translated at 100.0% (23 of 23 strings) Translation: Boost Json Translation (zh_Hans)/Doc / Pages / Dom / Init Lists (adoc) Translate-URL: https://boost-weblate.cloud/projects/boost-json-documentation-zh_Hans/doc-pages-dom-init-lists-adoc/zh_Hans/ --- doc/pages/dom/init_lists_zh_Hans.adoc | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/doc/pages/dom/init_lists_zh_Hans.adoc b/doc/pages/dom/init_lists_zh_Hans.adoc index b77ce9d..379ff08 100644 --- a/doc/pages/dom/init_lists_zh_Hans.adoc +++ b/doc/pages/dom/init_lists_zh_Hans.adoc @@ -8,71 +8,71 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) Official repository: https://github.com/boostorg/json //// -= Initializer Lists -Initializer lists can be used to construct or assign a <>: += 初始化列表 +初始化列表可用于构造或赋值一个<>： [source] ---- include::../../../test/snippets.cpp[tag=snippet_init_list_1,indent=0] ---- -Simple initializer lists produce an <>: +简单的初始化列表会生成一个 <>： [source] ---- include::../../../test/snippets.cpp[tag=snippet_init_list_2,indent=0] ---- -Initializer lists can be nested. Here we construct an array as an element of an array: +初始化列表可以嵌套。以下示例中，我们构造了一个以数组作为元素的数组： [source] ---- include::../../../test/snippets.cpp[tag=snippet_init_list_3,indent=0] ---- -When a two element initializer list is nested within an enclosing initializer list, it is unclear whether it represents an <> or an <>: +当一个包含两个元素的初始化列表嵌套在外部初始化列表中时，尚不明确它表示的是一个 <> 还是一个 <>： [source] ---- include::../../../test/snippets.cpp[tag=snippet_init_list_4,indent=0] ---- -In such cases, if every element consists of a string followed by a single value, then the enclosing initializer list is interpreted as an <>. Otherwise, it is interpreted as an <>. +在这种情况下，如果每个元素均由一个字符串后跟一个值组成，则外层的初始化列表会被解释为一个 <>；否则，它会被解释为一个 <>。 [source] ---- include::../../../test/snippets.cpp[tag=snippet_init_list_5,indent=0] ---- -To resolve the ambiguity manually, use an explicit constructor: +要手动消除歧义，请使用显式构造函数： [source] ---- include::../../../test/snippets.cpp[tag=snippet_init_list_6,indent=0] ---- -Initializer lists can be used to unambiguously construct or assign an <> or <>: +初始化列表可用于明确地构造或赋值一个<> 或 <>： [source] ---- include::../../../test/snippets.cpp[tag=snippet_init_list_7,indent=0] ---- -Similarly, an initializer list for an <> is always interpreted as an <>. In such cases, the initializer list must be a list of key-value pairs. For example, the following code will not compile because `1` is not convertible to a string: +同样，用于 <> 的初始化列表始终会被解释为 <>。此时，初始化列表必须由键值对组成。例如，以下代码无法编译，因为` `1 无法转换为字符串： [source] ---- object jo = { { 1, 0.39 }, { "venus", 0.72 }, { "earth", 1 } }; ---- -The requirement for an initializer list to be interpreted as an <> or <> when initializing such an entity only applies to the outermost initializer list; subsequent nested elements will follow the usual ambiguity resolution rules. +当初始化一个 <> 或 <> 时，要求初始化列表被解释为对应类型的规则仅适用于最外层的初始化列表；后续嵌套的元素将遵循常规的歧义解析规则。 [source] ---- include::../../../test/snippets.cpp[tag=snippet_init_list_8,indent=0] ---- -Elements that are rvalues will be moved upon initialization: +在初始化时，右值元素将被移动。 [source] ---- @@ -81,7 +81,7 @@ include::../../../test/snippets.cpp[tag=snippet_init_list_9,indent=0] [WARNING] ==== -Do not create variables of type {std_initializer_list}. This may result in temporaries being destroyed before the initializer list is used. +请勿创建类型为 {std_initializer_list} 的变量。这可能导致临时对象在初始化列表被使用之前就被销毁。 ==== -In all cases, the <> owned by an <>, <>, or <> constructed from an initializer list will be propagated to each element, recursively. +在所有情况下，通过初始化列表构造的 <>、<> 或 <> 所拥有的 <> 都会递归地传播到每个元素。 From fbc1c1f598660500d93c7e34aebfba0c6a40aeef Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Thu, 23 Apr 2026 15:18:00 +0000 Subject: [PATCH 50/68] Translated using Weblate (Chinese (Simplified Han script)) Currently translated at 100.0% (11 of 11 strings) Translation: Boost Json Translation (zh_Hans)/Doc / Pages / Dom / Nested Access (adoc) Translate-URL: https://boost-weblate.cloud/projects/boost-json-documentation-zh_Hans/doc-pages-dom-nested-access-adoc/zh_Hans/ --- doc/pages/dom/nested_access_zh_Hans.adoc | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/pages/dom/nested_access_zh_Hans.adoc b/doc/pages/dom/nested_access_zh_Hans.adoc index dd2719a..f8d0a5a 100644 --- a/doc/pages/dom/nested_access_zh_Hans.adoc +++ b/doc/pages/dom/nested_access_zh_Hans.adoc @@ -8,36 +8,36 @@ Official repository: https://github.com/boostorg/json //// [#nested_access] -= Accessing Deeply Nested Elements -In order to allow conveniently retrieving and changing deeply nested elements of <> objects the library implements https://datatracker.ietf.org/doc/html/rfc6901[RFC 6901 (JSON Pointer)]: += 访问深层嵌套元素 +为了便于便捷地获取和修改 <> 对象中深层嵌套的元素，该库实现了 https://datatracker.ietf.org/doc/html/rfc6901[RFC 6901 (JSON Pointer)]: [source] ---- include::../../../test/snippets.cpp[tag=snippet_pointer_1,indent=0] ---- -This is particularly useful when throwing exceptions is undesirable. For example, compare +这在不希望抛出异常的场景中尤为有用。例如，对比以下两种方式： [source] ---- include::../../../test/snippets.cpp[tag=snippet_pointer_2,indent=0] ---- -with +与 [source] ---- include::../../../test/snippets.cpp[tag=snippet_pointer_3,indent=0] ---- -The library also allows changing and adding deeply nested elements. The function <> traverses the value similarly to <>, but additionally, it can create missing elements in certain cases: +该库还支持修改和添加深层嵌套的元素。函数 <> 以与 <> 类似的方式遍历值，但在某些情况下还能创建缺失的元素： [source] ---- include::../../../test/snippets.cpp[tag=snippet_pointer_4,indent=0] ---- -The specific behavior is controlled by an optional parameter of type <>. For example, here's the same example with a different option: +具体行为由一个类型为 <> 的可选参数控制。例如，以下是使用不同选项的相同示例： [source] ---- From 0b6d84c04d19677f64ce2327163b2ed4f93b2b8e Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Thu, 23 Apr 2026 15:18:25 +0000 Subject: [PATCH 51/68] Translated using Weblate (Chinese (Simplified Han script)) Currently translated at 100.0% (19 of 19 strings) Translation: Boost Json Translation (zh_Hans)/Doc / Pages / Dom / Numbers (adoc) Translate-URL: https://boost-weblate.cloud/projects/boost-json-documentation-zh_Hans/doc-pages-dom-numbers-adoc/zh_Hans/ --- doc/pages/dom/numbers_zh_Hans.adoc | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/doc/pages/dom/numbers_zh_Hans.adoc b/doc/pages/dom/numbers_zh_Hans.adoc index 94111d3..bf7c78f 100644 --- a/doc/pages/dom/numbers_zh_Hans.adoc +++ b/doc/pages/dom/numbers_zh_Hans.adoc @@ -9,54 +9,54 @@ Official repository: https://github.com/boostorg/json //// [#dom_numbers] -= Numbers -JSON numbers are represented using `std::int64_t`, `std::uint64_t`, and `double`. When a <> is constructed from an unsigned integer, its <> will be `kind::uint64`. Likewise, a <> constructed from a signed integer will have `kind::int64`, or `kind::double_` if constructed from a floating-point type: += 数字 +JSON数字使用`std::int64_t`、`std::uint64_t`和`double`表示。当 <> 从无符号整数构造时，其<>将为`kind::uint64`。同样，从有符号整数构造的<> 将具有`kind::int64`，若从浮点类型构造则为`kind::double_`： [source] ---- include::../../../test/doc_using_numbers.cpp[tag=doc_using_numbers_1,indent=0] ---- -When accessing a number contained within a <>, the function used must match the value's <> exactly; no conversions will be performed. For example if `as_double` is called on a <> that contains a `std::uint64_t`, an exception is thrown. Similarly, the function `if_double` will return `nullptr` and calling `get_double` will result in undefined behavior: +访问<>内包含的数字时，所使用的函数必须与该值的<>完全匹配；不会执行任何转换。例如，如果在一个包含`std::uint64_t` 的 <> 上调用 `as_double`，将抛出异常。类似地，函数 `if_double` 将返回`nullptr`，而调用 `get_double` 将导致未定义行为： [source] ---- include::../../../test/doc_using_numbers.cpp[tag=doc_using_numbers_2,indent=0] ---- -In cases where you know that a <> contains a number but don't know its <>, `value::to_number` can be used to convert the <> to an arithmetic type: +若已知 <> 包含数字，但不确定其 <>，可使用 `value::to_number` 将该<> 转换为算术类型： [source] ---- include::../../../test/doc_using_numbers.cpp[tag=doc_using_numbers_3,indent=0] ---- -If the <> does not contain a number, or if the conversion is to an integer type `T` and the number cannot be represented exactly by `T`, the conversion will fail. Otherwise, the result is the number converted to `T` as-if by `static_cast`: +若<>不包含数字，或当转换目标为整数类型`T`且数字无法被`T`精确表示时，将导致转换失败。否则，结果是通过`static_cast`将数字转换为`T`所得的值： [source] ---- include::../../../test/doc_using_numbers.cpp[tag=doc_using_numbers_4,indent=0] ---- -In settings where exceptions cannot be used, an overload of `value::to_number` accepting {ref_error_code} can be used instead with identical semantics to its throwing counterpart: +在无法使用异常的场合，可改用接受{ref_error_code}的`value::to_number`重载，其语义与抛出异常版本完全相同： [source] ---- include::../../../test/doc_using_numbers.cpp[tag=doc_using_numbers_5,indent=0] ---- -When parsing a JSON document, the type used to represent a number is not explicitly specified and must be determined from its value. In general, the parser will choose the best type which can accurately store the number as it appears in the document. Integers (i.e. numbers without decimals or exponents) that cannot be represented by `std::uint64_t` and `std::int64_t` will be represented as `double` to preserve their magnitude: +在解析 JSON 文档时，数字的表示类型并未显式指定，而必须根据其值来确定。通常，解析器会选择能够精确存储文档中所出现数字的最佳类型。对于整数（即不带小数部分或指数的数字），若其值无法用 `std::uint64_t` 或 `std::int64_t` 表示，则会以 `double` 类型存储，以保留其数量级。 [source] ---- include::../../../test/doc_using_numbers.cpp[tag=doc_using_numbers_6,indent=0] ---- -More formally, if the number: +更正式地，如果该数字： -* contains a decimal point, or -* contains an exponent, or -* is negative and its value is less than `INT64_MIN`, or -* is positive and its value is greater than `UINT64_MAX`, +* 包含小数点，或 +* 包含指数，或 +* 为负数且其值小于`INT64_MIN`，或 +* 为正数且其值大于`UINT64_MAX`， -then its type is `double`. Otherwise, if the number is positive and its value is greater than `INT64_MAX`, then its type is `std::uint64_t`. All other numbers are parsed as `std::int64_t`. +则其类型为`double`。否则，若数字为正数且其值大于`INT64_MAX`，则其类型为`std::uint64_t`。其余所有数字均被解析为`std::int64_t`。 From 3db17b72cb9a9d01714e903de1875675739cd9b5 Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Thu, 23 Apr 2026 15:18:55 +0000 Subject: [PATCH 52/68] Translated using Weblate (Chinese (Simplified Han script)) Currently translated at 100.0% (23 of 23 strings) Translation: Boost Json Translation (zh_Hans)/Doc / Pages / Dom / Object (adoc) Translate-URL: https://boost-weblate.cloud/projects/boost-json-documentation-zh_Hans/doc-pages-dom-object-adoc/zh_Hans/ --- doc/pages/dom/object_zh_Hans.adoc | 34 +++++++++++++++---------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/doc/pages/dom/object_zh_Hans.adoc b/doc/pages/dom/object_zh_Hans.adoc index 6557eed..93bd7ae 100644 --- a/doc/pages/dom/object_zh_Hans.adoc +++ b/doc/pages/dom/object_zh_Hans.adoc @@ -10,64 +10,64 @@ Official repository: https://github.com/boostorg/json [#dom_object] = `object` -A <> stores an instance of <> as the underlying representation for a JSON object. Instances of the <> type are associative containers holding key and value pairs, where the key is a <> and the mapped type is a <>. These containers are modelled after standard maps with these properties: +<> 使用 <> 的实例作为 JSON 对象的底层表示。<> 类型的实例是一种关联容器，存储键值对，其中键为 <>，映射的值类型为 <>。此类容器以标准映射（map）为模型，具有以下特性： -* The elements are stored contiguously as instances of <>. +* 元素以 <> 的实例形式连续存储。 -* Iterators are ordinary pointers, and may become invalidated on insertions and removals. +* 迭代器是普通指针，在插入或删除操作时可能会失效。 -* The order of insertions is preserved, as long as there are no removals. +* 只要不发生删除操作，插入顺序即被保留。 -* All inserted values will use the same {ref_memory_resource} as the container itself. +* 所有插入的值将使用与容器本身相同的 {ref_memory_resource}。 -An empty object may be constructed without incurring any memory allocations using the <>. A <> can also be explicitly specified: +可以使用 <> 构造一个空对象，而不产生任何内存分配。也可以显式指定一个 <>： [source] ---- include::../../../test/snippets.cpp[tag=snippet_objects_1,indent=0] ---- -Initializer lists consisting of two-element key value pairs can be used to construct objects with initial contents. These constructors may allocate memory and throw: +由两元素键值对组成的初始化列表可用于构造带有初始内容的对象。这些构造函数可能会分配内存并抛出异常： [source] ---- include::../../../test/snippets.cpp[tag=snippet_objects_2,indent=0] ---- -Alternatively, elements may be inserted after construction: +或者，也可以在构造之后插入元素： [source] ---- include::../../../test/snippets.cpp[tag=snippet_objects_3,indent=0] ---- -Similar to the `std` counterpart, elements may be accessed directly by their key with bounds checking using <>, or without bounds checking using <> which creates a null element if the key does not already exist: +与 `std` 对应容器类似，可通过 <> 使用边界检查直接按键访问元素，或通过 <> 进行无边界检查访问（若键不存在则创建空元素）： [source] ---- include::../../../test/snippets.cpp[tag=snippet_objects_4,indent=0] ---- -Internally, the container computes a hash table over the keys so that the complexity of lookups is in constant time, on average. +容器内部通过键计算哈希表，使得查找操作的平均时间复杂度为常数级别。 [WARNING] ==== -Unlike traditional node based containers like `std::set`, there is no guarantee of reference stability or iterator stability on insertions and erasures. +与传统的基于节点的容器（如 `std::set`）不同，插入和擦除操作不保证引用稳定性或迭代器稳定性。 -For example: +例如： [source] ---- include::../../../test/snippets.cpp[tag=snippet_objects_5,indent=0] ---- -Using `arr` after adding another value to `obj` results in undefined behavior. +在向 `obj` 添加一个新值后继续使用 `arr`，会导致未定义行为。 ==== -For the complete listing of all available member functions and nested types, see the reference page for <>. +完整成员函数及嵌套类型列表请参阅 <> 的参考页。 -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. +与 `std::pair` 类似，<> 类型可用于 {cpp}17 的结构化绑定。为此专门提供了 `std::tuple_size`、`std::tuple_element` 的特化及 <> 的重载。 -== Formatted Output +== 格式化输出 -When an <> is formatted to a {std_ostream}, the result is a valid JSON. That is, the object will be output with curly braces and a comma separated list of key/value pairs, as per the JSON specification. +当 <> 被格式化输出到 {std_ostream} 时，结果将是有效的 JSON。即根据 JSON 规范，对象将以花括号和逗号分隔的键/值对列表形式输出。 From 198912b9c0613e83bf3d5678d8d94ed2f9b9550f Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Thu, 23 Apr 2026 15:19:17 +0000 Subject: [PATCH 53/68] Translated using Weblate (Chinese (Simplified Han script)) Currently translated at 100.0% (16 of 16 strings) Translation: Boost Json Translation (zh_Hans)/Doc / Pages / Dom / Overview (adoc) Translate-URL: https://boost-weblate.cloud/projects/boost-json-documentation-zh_Hans/doc-pages-dom-overview-adoc/zh_Hans/ --- doc/pages/dom/overview_zh_Hans.adoc | 27 ++++++++++----------------- 1 file changed, 10 insertions(+), 17 deletions(-) diff --git a/doc/pages/dom/overview_zh_Hans.adoc b/doc/pages/dom/overview_zh_Hans.adoc index 57f0a89..a57511a 100644 --- a/doc/pages/dom/overview_zh_Hans.adoc +++ b/doc/pages/dom/overview_zh_Hans.adoc @@ -9,39 +9,32 @@ Official repository: https://github.com/boostorg/json //// [#dom] -= Document Model -In this library the following types implement containers used to represent JSON data in memory: += 文档模型 +在本库中，以下类型实现了用于在内存中表示 JSON 数据的容器： -.Container Types +.容器类型 [%autowidth] |=== -|Type|Description +|Type|描述 | <> -| A sequence container of JSON values supporting dynamic size and fast, random - access. The interface and performance characteristics are similar to - {std_vector}. +| 一种支持动态大小和快速随机访问的 JSON 值序列容器。其接口和性能特性类似于 {std_vector}。 | <> -| An associative container of key-value pairs with unique keys, where the key - is a string and the mapped type is a JSON value. Search, insertion, and - removal have average contant-time complexity. In addition, elements are - stored contiguously in memory allowing cache-friendly iteration. +| 一种具有唯一键的键值对关联容器，其中键为字符串，映射类型为 JSON 值。查找、插入和移除操作具有平均常数时间复杂度。此外，元素在内存中连续存储，支持缓存友好的迭代。 | <> -| A contiguous range of characters. The library assumes that the contents of - the string holds only valid UTF-8. +| 一个连续的字符范围。该库假定字符串内容仅包含有效的 UTF-8 编码。 | <> -| A special variant which can hold one of any of the six standard JSON data - types. +| 一种特殊的变体类型，可持有六种标准 JSON 数据类型中的任意一种。 |=== -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] ---- From 7de8b827faebe68d354710eb61458655471d9ef5 Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Thu, 23 Apr 2026 15:19:55 +0000 Subject: [PATCH 54/68] Translated using Weblate (Chinese (Simplified Han script)) Currently translated at 100.0% (30 of 30 strings) Translation: Boost Json Translation (zh_Hans)/Doc / Pages / Dom / String (adoc) Translate-URL: https://boost-weblate.cloud/projects/boost-json-documentation-zh_Hans/doc-pages-dom-string-adoc/zh_Hans/ --- doc/pages/dom/string_zh_Hans.adoc | 48 +++++++++++++++---------------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/doc/pages/dom/string_zh_Hans.adoc b/doc/pages/dom/string_zh_Hans.adoc index 143d788..d2bd0c5 100644 --- a/doc/pages/dom/string_zh_Hans.adoc +++ b/doc/pages/dom/string_zh_Hans.adoc @@ -12,63 +12,63 @@ Official repository: https://github.com/boostorg/json [#dom_string] = `string` -Modifiable sequences of characters are represented using objects of type <>. +可修改的字符序列通过 <> 类型的对象表示。 -The interface and functionality of <> is the same as {std_string} except that: +<> 的接口和功能与 {std_string} 相同，但有以下例外： -* <> is not a class template, -* <> uses `char` as its character type, -* redundant overloads for string operations have been replaced with a <>-based interface, -* access to characters in the range `[size(), capacity())` is permitted, -* <> is used instead of {req_Allocator}, and -* small buffer optimisation is guaranteed, which avoids allocating memory for small strings. +* <>不是一个类模板， +* <> 使用`char`作为其字符类型， +* 字符串操作中冗余的重载已被基于 <> 的接口所取代， +* 允许访问`[size(), capacity())`范围内的字符， +* 使用<>代替{req_Allocator}，且 +* 保证采用小缓冲区优化，从而避免为短字符串分配内存。 -With augmented interface, operations requiring an input string are implemented as a single overload with a parameter of type <>, and can accept most string-like objects. Objects such as null terminated character pointers, `std::string`, <>, subranges of strings, and objects convertible to <> can all be passed to these functions. +通过增强的接口，所有需要输入字符串的操作均以单一重载形式实现，其参数类型为 <>，并可接受大多数类字符串对象。诸如以空字符结尾的字符指针、`std::string`、<>、字符串子范围以及可转换为 <> 的对象，均可传递给这些函数。 [source] ---- include::../../../test/snippets.cpp[tag=snippet_strings_4,indent=0] ---- -More formally, `std::string` member function overloads that accept any of the following parameter combinations as an input string: +更正式地说，`std::string` 中接受以下任一参数组合作为输入字符串的成员函数重载： -* a `std::string` parameter, or -* a `std::string` parameter and two `size_type` parameters that specify a substring, or -* a parameter of a type convertible to <>, or -* a parameter of a type convertible to <> and two `size_type` parameters that specify a substring, or -* a `const_pointer` parameter, or -* a parameter of type `const_pointer` and a `size_type` parameter that specifies the length of the string +* 一个`std::string`参数，或 +* 一个`std::string`参数和两个指定子字符串的`size_type`参数，或 +* 一个可转换为 <> 类型的参数，或 +* 一个可转换为<>类型的参数和两个指定子字符串的`size_type`参数，或 +* 一个`const_pointer`参数，或 +* 一个`const_pointer`类型的参数和一个指定字符串长度的`size_type`参数 -are replaced with an overload accepting a <> parameter. +被一个接受 <> 参数的重载所替代。 -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: +这一设计从接口中移除了多个冗余的重载。例如，`std::string::insert` 原本有 11 个重载，而在 <> 中被减少到仅 3 个，同时仍提供完全相同的功能。除此之外，接受 `std::initializer_list` 参数的重载也被移除。这类重载用途有限，因为它们本质上只是对字符数组的封装，且语法效率低下： [source] ---- include::../../../test/snippets.cpp[tag=snippet_strings_3,indent=0] ---- -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: +随着用于指定子字符串参数的重载被移除，库提供了一个成员函数`subview`， 用于返回一个 <>，从而支持高效的子字符串操作： [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] ---- include::../../../test/snippets.cpp[tag=snippet_strings_1,indent=0] ---- -== Formatted Output +== 格式化输出 -When a <> is formatted to a {std_ostream}, the result is a valid JSON. That is, the result will be double quoted and the contents properly escaped per the JSON specification. +当<>被格式化到{std_ostream}时，结果是一个有效的JSON。即输出结果将被双引号括起来，并且内容会根据JSON规范进行正确转义。 -== Accessing Storage Beyond `size()` +== 访问超出`size()`范围的存储空间 -<> directly supports access to its storage in the range `[size(), capacity())`. This can be used for efficient assembly of a string from several parts. After the string is assembled, use the member function <> to update the string's size and insert the null terminator. For example: +<> 直接支持访问其在`[size(), capacity())`范围内的存储空间。这可用于高效地将字符串从多个部分组装起来。字符串组装完成后，可调用成员函数 <> 来更新字符串的大小并插入空终止符。例如： [source] ---- From c2e29ec527f34d80fe063870b3ca59f4765459de Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Thu, 23 Apr 2026 15:22:36 +0000 Subject: [PATCH 55/68] Translated using Weblate (Chinese (Simplified Han script)) Currently translated at 100.0% (118 of 118 strings) Translation: Boost Json Translation (zh_Hans)/Doc / Pages / Dom / Value (adoc) Translate-URL: https://boost-weblate.cloud/projects/boost-json-documentation-zh_Hans/doc-pages-dom-value-adoc/zh_Hans/ --- doc/pages/dom/value_zh_Hans.adoc | 99 +++++++++++++++----------------- 1 file changed, 47 insertions(+), 52 deletions(-) diff --git a/doc/pages/dom/value_zh_Hans.adoc b/doc/pages/dom/value_zh_Hans.adoc index 033d574..e655858 100644 --- a/doc/pages/dom/value_zh_Hans.adoc +++ b/doc/pages/dom/value_zh_Hans.adoc @@ -10,69 +10,69 @@ Official repository: https://github.com/boostorg/json [#dom_value] = `value` -JSON documents are represented in memory as instances of <>: a {req_Regular} type which satisfies {req_DefaultConstructible}, {req_CopyConstructible}, {req_CopyAssignable}, {req_MoveConstructible}, {req_MoveAssignable}, and many of the requirements of allocator-aware containers. It is implemented as a https://en.wikipedia.org/wiki/Tagged_union[__variant__] internally, and can dynamically store any of the six defined JSON value types: +JSON文档在内存中表示为<>的实例：一种{req_Regular}类型，满足{req_DefaultConstructible}、{req_CopyConstructible}、{req_CopyAssignable}、{req_MoveConstructible}、{req_MoveAssignable}以及许多分配器感知容器的要求。它在内部实现为一个https://en.wikipedia.org/wiki/Tagged_union[__variant__]（变体），并且可以动态存储六种已定义的JSON值类型中的任意一种： -* **null**: A https://en.cppreference.com/w/cpp/utility/variant/monostate[__monostate__] value, equivalent to `nullptr`. +* **空值**：一种https://en.cppreference.com/w/cpp/utility/variant/monostate[__monostate__]（单态）值，等同于`nullptr`。 -* **boolean**: A boolean: either `true` or `false`. +* **布尔值**：布尔类型，取值为`true`或`false`。 -* **number**: An integral or floating point value. +* **数值**：整型或浮点型值。 -* **string**: A sequence of zero or more Unicode characters, similar to {std_string}. +* **字符串**：由零个或多个Unicode字符组成的序列，类似于{std_string}。 -* **array**: An ordered list of values, like {std_vector}. +* **数组**：值的有序列表，类似于{std_vector}。 -* **object**: A collection of name/value pairs, also known as an https://en.wikipedia.org/wiki/Associative_array[__associative array__]. +* **对象**：名称/值对的集合，也称为https://en.wikipedia.org/wiki/Associative_array[__关联数组__]。 -== Working With Values -A <> constructed from `nullptr` or default constructed represents a null JSON element: +== 处理值 +从`nullptr`构造或默认构造的 <> 表示一个空的JSON元素： [source] ---- include::../../../test/snippets.cpp[tag=snippet_value_1,indent=0] ---- -The member function <> may be used to query the kind stored in the value. Alternatively, member functions like <> <> may be used to check whether or not the value is a particular kind: +成员函数<>可用于查询值中存储的种类。或者，也可以使用诸如<>、<> 等成员函数来检查值是否为特定种类： [source] ---- include::../../../test/snippets.cpp[tag=snippet_value_2,indent=0] ---- -Functions like <> actually return a pointer to the object if the value is an object, otherwise they return null. This allows them to be used both in boolean contexts as above, and in assignments or conditional expressions to capture the value of the pointer: +诸如 <> 的函数在值为对象时返回指向该对象的指针，否则返回空指针。这使得它们既可用于上述的布尔上下文，也可用于赋值或条件表达式中，以捕获指针的值： [source] ---- include::../../../test/snippets.cpp[tag=snippet_value_3,indent=0] ---- -After a <> is constructed, its kind can change depending on what is assigned to it, or by calling functions such as <> or <>. If the assignment is successful, in other words it completes without any exceptions then the value is replaced. Otherwise, the value is unchanged. All operations which can fail to modify a value offer the strong exception safety guarantee. +<> 构造之后，其类型可根据赋值内容或通过调用<> 或 <> 等函数来改变。如果赋值成功，即未引发任何异常，则该值将被替换。否则，原值保持不变。所有可能修改值失败的操作均提供强异常安全保证。 [source] ---- include::../../../test/snippets.cpp[tag=snippet_value_4,indent=0] ---- -The following table shows all of the ways to determine and access the contents of a <>: +下表列出了所有用于判断和访问 <> 内容的方法： -.<> Accessors +.<>访问器 [%autowidth, cols=8] |=== -|Kind -|Representation -|Emplacement -|Kind Test -|Pointer Access -|`result` Access -|Checked Access -|Unchecked Access +|种类 +|表示形式 +|置入 +|种类测试 +|指针访问 +|`result`访问 +|受检访问 +|非受检访问 |<> |<> |<> |<> |<> -|<> +|<> |<> |<> @@ -83,7 +83,7 @@ The following table shows all of the ways to determine and access the contents o |<> |<> |<> -|<> +|<> |<> |<> @@ -97,13 +97,13 @@ The following table shows all of the ways to determine and access the contents o |<> |https://en.cppreference.com/w/cpp/types/integer[`std::int64_t`] |<> -|<> +|<> |<> |<> |<> |<> -|<> +|<> |https://en.cppreference.com/w/cpp/types/integer[`std::uint64_t`] |<> |<> @@ -121,7 +121,7 @@ The following table shows all of the ways to determine and access the contents o |<> |<> -|<> +|<> |https://en.cppreference.com/w/cpp/language/types[`bool`] |<> |<> @@ -141,66 +141,61 @@ The following table shows all of the ways to determine and access the contents o |=== -The emplace members of <> return a typed reference to the underlying representation. For example, the call to <> in the previous example returns a <>. This table shows the underlying type for each kind: +<> 的置入成员函数返回对底层表示形式的类型化引用。例如，前例中对 <> 的调用返回一个 <> 。下表列出了每种 kind 对应的底层类型： |=== -|Kind|Type|Description +|Kind|Type|描述 | <> | <> -| An associative array of string keys mapping to <> elements with an - interface similar to {std_unordered_map}, that remembers insertion order. +| 一个关联数组，其键为字符串，值为 <> 元素，接口类似于 {std_unordered_map}，并保留插入顺序。 | <> | <> -| An ordered list of <> elements with an interface similar to - {std_vector}. +| 一个<>元素的有序列表，其接口类似于{std_vector}。 | <> | <> -| A https://en.wikipedia.org/wiki/UTF-8[__UTF-8__] encoded - https://en.wikipedia.org/wiki/Unicode[Unicode] - https://en.wikipedia.org/wiki/String_(computer_science)[string] of characters - with an interface similar to {std_string}. +| 一个采用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}。 | <> | `std::int64_t` -| A 64 bit signed integer. +| 64位有符号整数。 -| <> +| <> | `std::uint64_t` -| A 64 bit unsigned integer. +| 64位无符号整数。 | <> | `double` -| A `double` holding a floating-point value. +| 一个`double`，用于保存浮点型值。 -| <> +| <> | https://en.cppreference.com/w/cpp/keyword/bool[`bool`] -| A `bool` holding `true` or `false`. +| 一个`bool`，用于保存`true`或`false`。 | <> ^| — -| A monostate value representing null. +| 一个表示空值的monostate值。 |=== -The return value from emplace can be used to perform assignment or to capture a reference to the underlying element for later inspection or modification: +置入操作的返回值可用于执行赋值，或捕获对底层元素的引用以供后续检查或修改： [source] ---- include::../../../test/snippets.cpp[tag=snippet_value_5,indent=0] ---- -If the <> of a <> is known, functions such as <> or <> may be used to obtain a reference to the underlying representation without changing the existing value: +如果已知 <> 的 <>，可使用诸如 <> 或 <> 等函数，在不改变现有值的情况下获取对底层表示的引用： [source] ---- include::../../../test/snippets.cpp[tag=snippet_value_6,indent=0] ---- -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. +然而，如上所示，如果 <> 中的实际类型与函数签名所指定的类型不匹配，这些函数会抛出异常。这一行为可作为一种简洁的验证形式：以预期类型直接访问值，若 JSON 结构无效，则通过捕获异常进行处理。 -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] ---- @@ -209,7 +204,7 @@ 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] ---- @@ -217,12 +212,12 @@ include::../../../test/snippets.cpp[tag=snippet_value_8,indent=0] ---- ==== -Functions returning {ref_result} allow you to use both approaches: +返回 {ref_result} 的函数允许您同时使用上述两种方式： [source] ---- include::../../../test/snippets.cpp[tag=snippet_value_9,indent=0] ---- -=== Formatted Output -When a <> is formatted to a {std_ostream}, the result is serialized JSON as if by calling <>. +=== 格式化输出 +当将 <> 输出到 {std_ostream} 时，其结果等同于调用 <> 所生成的序列化 JSON。 From be660c7d9d5e7dfe0860243fa81195f5e329330e Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Thu, 23 Apr 2026 15:22:51 +0000 Subject: [PATCH 56/68] Translated using Weblate (Chinese (Simplified Han script)) Currently translated at 100.0% (9 of 9 strings) Translation: Boost Json Translation (zh_Hans)/Doc / Pages / Examples (adoc) Translate-URL: https://boost-weblate.cloud/projects/boost-json-documentation-zh_Hans/doc-pages-examples-adoc/zh_Hans/ --- doc/pages/examples_zh_Hans.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/pages/examples_zh_Hans.adoc b/doc/pages/examples_zh_Hans.adoc index f4e661c..6ed6b88 100644 --- a/doc/pages/examples_zh_Hans.adoc +++ b/doc/pages/examples_zh_Hans.adoc @@ -9,9 +9,9 @@ Official repository: https://github.com/boostorg/json //// [pagelevels=1] -= Examples += 示例 -== Pretty +== 美化 [source] ---- @@ -19,14 +19,14 @@ include::../../example/pretty.cpp[tag=example_pretty,indent=0] ---- [#examples_validate] -== Validate +== 验证 [source] ---- include::../../example/validate.cpp[tag=example_validate,indent=0] ---- -== Allocator-Aware Conversion +== 感知分配器的转换 [source] ---- From 8de4b0a8bbe203fb7cd55b3cc20958c1ef3e5a98 Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Thu, 23 Apr 2026 15:23:05 +0000 Subject: [PATCH 57/68] Translated using Weblate (Chinese (Simplified Han script)) Currently translated at 100.0% (9 of 9 strings) Translation: Boost Json Translation (zh_Hans)/Doc / Pages / Faq (adoc) Translate-URL: https://boost-weblate.cloud/projects/boost-json-documentation-zh_Hans/doc-pages-faq-adoc/zh_Hans/ --- doc/pages/faq_zh_Hans.adoc | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/pages/faq_zh_Hans.adoc b/doc/pages/faq_zh_Hans.adoc index a1cb527..135d40c 100644 --- a/doc/pages/faq_zh_Hans.adoc +++ b/doc/pages/faq_zh_Hans.adoc @@ -8,14 +8,14 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) Official repository: https://github.com/boostorg/json //// -= Frequently Asked Questions += 常见问题 -"Isn't simdjson faster?":: These libraries are not comparable. The output of the simdjson parser is a read-only structure. In other words, it can't be changed, and the only way to create one is by parsing a JSON string. On the other hand, Boost.JSON allows you to modify the container holding the parsed JSON, or even build a JSON document from scratch through the container interface. +"难道 simdjson 不是更快吗？":: 这些库不可相提并论。simdjson 解析器的输出是一个只读结构。换句话说，它不能被修改，创建它的唯一方法是解析一个 JSON 字符串。另一方面，Boost.JSON 允许你修改容纳已解析 JSON 的容器，甚至可以通过容器接口从头构建 JSON 文档。 -"Why not use a standard {req_Allocator}?:: Using standard allocators would 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. +"为什么不使用标准的 {req_Allocator}？":: 使用标准分配器将要求 <> 被声明为一个类模板，这会增加额外的编译负担。通过避免使用模板，库中的大部分函数定义可以从头文件中排除，并放入单独的静态库或动态库中。 -"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}. +"为什么使用 <> 而不是 {ref_polymorphic_allocator}？":: +{ref_polymorphic_allocator} 将内存资源视为所有权的引用。Boost.JSON 使用一个引用计数智能指针容器来简化内存资源的生命周期管理。除了引用计数外，<> 还可以作为围绕 {ref_memory_resource} 的非计数引用包装器。 -"Why <> instead of {std_string}?":: The string provided by the 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 <>. +"为什么使用 <> 而不是 {std_string}？":: 该库提供的字符串使用 <>分配器模型，在所有 C++ 版本上具有相同的接口，并具有优化的类布局以保持 JSON 值的大小较小。<> 还实现了一个改进的接口，该接口使用 <> 替代了多余的重载。 From 2fd7faccdcbaed052ea048220f5574ae52614388 Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Thu, 23 Apr 2026 15:23:11 +0000 Subject: [PATCH 58/68] Translated using Weblate (Chinese (Simplified Han script)) Currently translated at 100.0% (2 of 2 strings) Translation: Boost Json Translation (zh_Hans)/Doc / Pages / Io / Overview (adoc) Translate-URL: https://boost-weblate.cloud/projects/boost-json-documentation-zh_Hans/doc-pages-io-overview-adoc/zh_Hans/ --- doc/pages/io/overview_zh_Hans.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/pages/io/overview_zh_Hans.adoc b/doc/pages/io/overview_zh_Hans.adoc index caadbea..daadac2 100644 --- a/doc/pages/io/overview_zh_Hans.adoc +++ b/doc/pages/io/overview_zh_Hans.adoc @@ -9,8 +9,8 @@ Official repository: https://github.com/boostorg/json //// [#input_output, pagelevels=2] -= Input/Output -The library provides parsing and serialization algorithms to transform JSON to and from the <> container as needed. This is accomplished through free functions and classes, described as follows. += 输入/输出 +该库提供解析和序列化算法，可根据需要在 JSON 与 <> 容器之间相互转换。这是通过自由函数和类实现的，具体如下所述。 :leveloffset: +1 From acf8373e672eca14b4e4f0d8dba8c6d695390179 Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Thu, 23 Apr 2026 15:24:36 +0000 Subject: [PATCH 59/68] Translated using Weblate (Chinese (Simplified Han script)) Currently translated at 100.0% (72 of 72 strings) Translation: Boost Json Translation (zh_Hans)/Doc / Pages / Io / Parsing (adoc) Translate-URL: https://boost-weblate.cloud/projects/boost-json-documentation-zh_Hans/doc-pages-io-parsing-adoc/zh_Hans/ --- doc/pages/io/parsing_zh_Hans.adoc | 106 ++++++++++++++---------------- 1 file changed, 49 insertions(+), 57 deletions(-) diff --git a/doc/pages/io/parsing_zh_Hans.adoc b/doc/pages/io/parsing_zh_Hans.adoc index 4b2d142..5123a96 100644 --- a/doc/pages/io/parsing_zh_Hans.adoc +++ b/doc/pages/io/parsing_zh_Hans.adoc @@ -9,181 +9,173 @@ Official repository: https://github.com/boostorg/json //// [pagelevels=1] -= Parsing -Parsing is the process where a serialized JSON text is validated and decomposed into elements. The library provides these functions and types to assist with parsing: += 解析 +解析是将序列化的JSON文本验证并分解为元素的过程。该库提供以下函数和类型来辅助解析： -.Parsing Functions and Types +.解析函数和类型 |=== -|Name|Description +|Name|描述 | <> -| A SAX push parser implementation which converts a serialized JSON text into - a series of member function calls to a user provided handler. This allows - custom behaviors to be implemented for representing the document in memory. +| 一个 SAX 推送式解析器实现，它将序列化的 JSON 文本转换为对用户提供的处理器的一系列成员函数调用，从而允许自定义内存中文档的表示行为。 | <> -| A structure used to select which extensions are enabled during parsing. +| 一种结构，用于选择在解析期间启用哪些扩展。 | <> -| Parse a string containing a complete serialized JSON text, and return - a <>. +| 解析包含完整序列化 JSON 文本的字符串，并返回一个 <>。 | <> -| A stateful DOM parser object which may be used to efficiently parse a series - of JSON texts each contained in a single contiguous character buffer, - returning each result as a <>. +| 一种有状态的 DOM 解析器对象，可用于高效解析一系列 JSON 文本（每个文本均位于单独的连续字符缓冲区中），并将每个结果作为<>返回。 | <> -| A stateful DOM parser object which may be used to efficiently parse a series - of JSON texts incrementally, returning each result as a <>. +| 一种有状态的DOM解析器对象，可用于高效地增量解析一系列JSON文本，并将每个结果作为<>返回。 | <> -| A low level building block used for efficiently building a <>. The - parsers use this internally, and users may use it to adapt foreign parsers to - produce this library's containers. +| 一种用于高效构建 <> 的低层构建块。解析器在内部使用它，用户也可以使用它来适配外部解析器以生成此库的容器。 |=== -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: +<> 函数提供了一个简单接口，用于在单个函数调用中将序列化的JSON文本转换为<>。此重载使用异常来指示错误： [source] ---- include::../../../test/doc_parsing.cpp[tag=doc_parsing_1,indent=0] ---- -Alternatively, an {ref_error_code} can be used: +或者，可以使用{ref_error_code}： [source] ---- include::../../../test/doc_parsing.cpp[tag=doc_parsing_2,indent=0] ---- -Even when using error codes, exceptions thrown from the underlying {ref_memory_resource} are still possible: +即使使用错误码，底层 {ref_memory_resource} 仍可能抛出异常： [source] ---- include::../../../test/doc_parsing.cpp[tag=doc_parsing_3,indent=0] ---- -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. +前述示例中返回的 <> 使用了 <>（默认内存资源）。以下代码使用了 <>，从而实现更快的解析。`jv` 被标记为 `const` 以防止后续修改，因为使用单调内存资源的容器在被修改时会浪费内存。 [source] ---- include::../../../test/doc_parsing.cpp[tag=doc_parsing_4,indent=0] ---- -== Non-Standard JSON -Unless otherwise specified, the parser in this library is strict. It recognizes only valid, standard JSON. The parser can be configured to allow certain non-standard extensions by filling in a <> structure and passing it by value. By default all extensions are disabled: +== 非标准JSON +除非另有说明，本库中的解析器采用严格模式，仅识别有效的标准 JSON。通过填充一个 <> 结构并按值传递它来配置解析器，以允许某些非标准扩展。默认情况下，所有扩展都被禁用： [source] ---- include::../../../test/doc_parsing.cpp[tag=doc_parsing_5,indent=0] ---- -When building with {cpp}20 or later, the use of https://en.cppreference.com/w/cpp/language/aggregate_initialization#Designated_initializers[designated initializers] with <> is possible: +当使用 {cpp}20 或更高版本构建时，可以对 <> 使用 https://en.cppreference.com/w/cpp/language/aggregate_initialization#Designated_initializers[指定初始化器]： [source] ---- include::../../../test/doc_parsing.cpp[tag=doc_parsing_6,indent=0] ---- -When `allow_invalid_utf16` is enabled, the parser will not throw an error in the case of illegal leading, trailing, or half a surrogate. Instead, it will replace the invalid UTF-16 code point(s) with the Unicode replacement character. +启用 allow_invalid_utf16 后，解析器在遇到非法的前导代理、尾随代理或半个代理时不会抛出错误，而是将无效的 UTF-16 码点替换为 Unicode 替换字符。 [source] ---- include::../../../test/doc_parsing.cpp[tag=doc_parsing_15,indent=0] ---- -CAUTION: When enabling comment support take extra care not to drop whitespace when reading the input. For example, `std::getline` removes the endline characters from the string it produces. +CAUTION: 启用注释支持时，读取输入时需格外注意不要丢失空白字符。例如，`std::getline`会从它生成的字符串中移除行尾字符。 -== Full Precision Number Parsing -The default algorithm that the library uses to parse numbers is fast, but may result in slight precision loss. This may not be suitable for some applications, so there is an option to enable an alternative algorithm that doesn't have that flaw, but is somewhat slower. To do this, you also need to use <> structure. +== 全精度数字解析 +库默认使用的数字解析算法速度较快，但可能导致轻微的精度损失。这在某些应用中可能不可接受，因此可以选择启用一种没有此缺陷但速度稍慢的替代算法。为此，您还需要使用<>结构体。 [source] ---- include::../../../test/doc_parsing.cpp[tag=doc_parsing_precise,indent=0] ---- -Note that full precision number parsing requires the algorithm to see the full number. This means, that when used with <>, additional memory allocations may be necessary to store the number parts which were so far accepted by the parser. The library does try its best to avoid such allocations. +请注意，全精度数字解析要求算法看到完整的数字。这意味着，当与<>一起使用时，可能需要额外的内存分配来存储解析器迄今为止接受的数字部分。该库尽力避免此类分配。 -== Parser -Instances of <> and <> offer functionality beyond what is available when using the <> free functions: +== 解析器 +<> 和 <> 的实例所提供的功能超出了使用 <> 自由函数时可用的功能： -* More control over memory -* Streaming API, parse input JSON incrementally -* Improved performance when parsing multiple JSON texts -* Ignore non-JSON content after the end of a JSON text +* 对内存的更精细控制 +* 流式 API，可增量解析输入的 JSON +* 在解析多个JSON文本时性能更佳 +* 忽略JSON文本末尾之后的非JSON内容 -The parser implementation uses temporary storage space to accumulate values during parsing. When using the <> free functions, this storage is allocated and freed in each call. However, by declaring an instance of <> or <>, this temporary storage can be reused when parsing more than one JSON text, reducing the total number of dynamic memory allocations. +解析器实现使用临时存储空间在解析过程中累积值。使用 <> 自由函数时，该存储在每次调用中都会被分配和释放。然而，通过声明一个 <> 或 <> 实例，可在解析多个 JSON 文本时重用该临时存储，从而减少动态内存分配的总次数。 -To use the <>, declare an instance. Then call <> once with the buffer containing representing the input JSON. Finally, call <> to take ownership of the resulting <> upon success. This example persists the parser instance in a class member to reuse across calls: +要使用 <>，先声明一个实例。然后调用 <> 一次，传入包含输入 JSON 的缓冲区。最后，在成功时调用 <> 以获取生成的 <> 的所有权。以下示例将解析器实例作为类成员保存，以便在多次调用间复用： [source] ---- include::../../../test/doc_parsing.cpp[tag=doc_parsing_7,indent=0] ---- -Sometimes a protocol may have a JSON text followed by data that is in a different format or specification. The JSON portion can still be parsed by using the function <>. Upon success, the return value will indicate the number of characters consumed from the input, which will exclude the non-JSON characters: +有时，某个协议可能在 JSON 文本之后跟随采用不同格式或规范的数据。此时仍可使用函数 <> 来解析 JSON 部分。成功时，其返回值将指示从输入中消耗的字符数，该数量不包括非 JSON 的字符： [source] ---- include::../../../test/doc_parsing.cpp[tag=doc_parsing_8,indent=0] ---- -The parser instance may be constructed with parse options which allow some non-standard JSON extensions to be recognized: +解析器实例可以使用解析选项构造，这些选项允许识别一些非标准JSON扩展： [source] ---- include::../../../test/doc_parsing.cpp[tag=doc_parsing_9,indent=0] ---- -== Streaming Parser -The <> implements a https://en.wikipedia.org/wiki/Online_algorithm[__streaming algorithm__]; it allows incremental processing of large JSON inputs using one or more contiguous character buffers. The entire input JSON does not need to be loaded into memory at once. A network server can use the streaming interface to process incoming JSON in fixed-size amounts, providing these benefits: +== 流式解析器 +<>实现了一种https://en.wikipedia.org/wiki/Online_algorithm[__流式算法__]；它允许使用一个或多个连续字符缓冲区增量处理大型JSON输入。整个输入JSON无需一次性加载到内存中。网络服务器可以使用流式接口以固定大小的量处理传入的JSON，从而提供以下优势： -* CPU consumption per I/O cycle is bounded -* Memory consumption per I/O cycle is bounded -* Jitter, unfairness, and latency is reduced -* Less total memory is required to process the full input +* 每个 I/O 周期的 CPU 消耗是有上限的 +* 每个 I/O 周期的内存消耗是有上限的 +* 减少抖动、不公平性和延迟 +* 处理完整输入所需的总内存更少 -To use the <>, declare an instance. Then call <> zero or more times with successive buffers representing the input JSON. When there are no more buffers, call <>. The function <> returns `true` after a successful call to `write` or `finish` if parsing is complete. +要使用 <>，请先声明一个实例。然后对表示输入 JSON 的连续缓冲区零次或多次调用 <>。当没有更多缓冲区时，调用 <>。在成功调用`write`或`finish`后，若解析已完成，函数 <> 将返回`true`。 -In the following example a JSON text is parsed from standard input a line at a time. Error codes are used instead. The function <> is used to indicate the end of the input: +在以下示例中，JSON文本从标准输入逐行解析。此处使用错误码替代异常。函数<>用于指示输入结束： -CAUTION: This example will break, if comments are enabled, because of `std::getline` use (see the warning in <> section). +CAUTION: 如果启用了注释，此示例将失效，原因在于使用了 `std::getline`（参见 <> 章节中的警告）。 [source] ---- include::../../../test/doc_parsing.cpp[tag=doc_parsing_10,indent=0] ---- -We can complicate the example further by extracting _several_ JSON values from the sequence of lines. +我们可以通过从行序列中提取_多个_JSON值来进一步复杂化此示例。 [source] ---- include::../../../test/doc_parsing.cpp[tag=doc_parsing_14,indent=0] ---- -== Controlling Memory -After default construction, or after <> is called with no arguments, the <> produced after a successful parse operation uses the default memory resource. To use a different memory resource, call `reset` with the resource to use. Here we use a <>, which is optimized for parsing but not subsequent modification: +== 控制内存 +在默认构造之后，或在无参调用 <> 之后，成功解析操作所生成的 <> 将使用默认内存资源。若要使用不同的内存资源，可调用 `reset`并传入目标资源。以下示例使用了 <>，该资源针对解析进行了优化，但不适合后续修改 [source] ---- include::../../../test/doc_parsing.cpp[tag=doc_parsing_11,indent=0] ---- -To achieve performance and memory efficiency, the parser uses a temporary storage area to hold intermediate results. This storage is reused when parsing more than one JSON text, reducing the total number of calls to allocate memory and thus improving performance. Upon construction, the memory resource used to perform allocations for this temporary storage area may be specified. Otherwise, the default memory resource is used. In addition to a memory resource, the parser can make use of a caller-owned buffer for temporary storage. This can help avoid dynamic allocations for small inputs. The following example uses a four kilobyte temporary buffer for the parser, and falls back to the default memory resource if needed: +为实现性能与内存效率，解析器使用一块临时存储区来保存中间结果。在解析多个 JSON 文本时，该存储区会被复用，从而减少内存分配的总次数，提升性能。构造解析器时，可指定用于此临时存储区分配的内存资源；若未指定，则使用默认内存资源。此外，解析器还可利用调用方提供的缓冲区作为临时存储，有助于避免对小型输入进行动态分配。以下示例为解析器提供了一个 4 KB 的临时缓冲区，并在需要时回退到默认内存资源： [source] ---- include::../../../test/doc_parsing.cpp[tag=doc_parsing_12,indent=0] ---- -== Avoiding Dynamic Allocations -Through careful specification of buffers and memory resources, it is possible to eliminate all dynamic allocation completely when parsing JSON, for the case where the entire JSON text is available in a single character buffer, as shown here: +== 避免动态分配 +通过精心指定缓冲区和内存资源，可以在解析 JSON 时完全消除所有动态内存分配，前提是整个JSON文本在单个字符缓冲区中可用，如下所示： [source] ---- include::../../../test/doc_parsing.cpp[tag=doc_parsing_13,indent=0] ---- -== Custom Parsers -Users who wish to implement custom parsing strategies may create their own handler to use with an instance of <>. The handler implements the function signatures required by SAX event interface. In <> example we define the "null" parser, which throws out the parsed results, to use in the implementation of a function that determines if a JSON text is valid. +== 自定义解析器 +希望实现自定义解析策略的用户可以创建自己的处理器（handler），并与 <> 实例配合使用。该处理器需实现 SAX 事件接口所要求的函数签名。在 <> 示例中，我们定义了一个“空”解析器（null parser），它会丢弃所有解析结果，用于实现一个判断 JSON 文本是否有效的函数。 From 951a6a47fce7fbf9de4be91a0bb938dc472d9386 Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Thu, 23 Apr 2026 15:25:01 +0000 Subject: [PATCH 60/68] Translated using Weblate (Chinese (Simplified Han script)) Currently translated at 100.0% (18 of 18 strings) Translation: Boost Json Translation (zh_Hans)/Doc / Pages / Io / Serializing (adoc) Translate-URL: https://boost-weblate.cloud/projects/boost-json-documentation-zh_Hans/doc-pages-io-serializing-adoc/zh_Hans/ --- doc/pages/io/serializing_zh_Hans.adoc | 25 +++++++++++-------------- 1 file changed, 11 insertions(+), 14 deletions(-) diff --git a/doc/pages/io/serializing_zh_Hans.adoc b/doc/pages/io/serializing_zh_Hans.adoc index 5ac2d2b..45cd9f8 100644 --- a/doc/pages/io/serializing_zh_Hans.adoc +++ b/doc/pages/io/serializing_zh_Hans.adoc @@ -8,46 +8,43 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) Official repository: https://github.com/boostorg/json //// -= Serializing += 序列化 -Serialization is the process where a JSON document represented in memory by a <> is turned into a sequence of characters. The library provides the following free functions and types for serialization: +序列化是指将内存中由<>表示的JSON文档转换为字符序列的过程。该库提供以下用于序列化的自由函数和类型： -.Serialization Functions and Types +.序列化函数和类型 |=== -|Name|Description +|Name|描述 | <> -| Serialize a <>, <>, <>, or <> - to a {std_ostream}. +| 将 <>、<>、<> 或 <> 序列化到 {std_ostream}。 | <> -| Return a {std_string} representing a serialized <>, <>, - <>, or <>. +| 返回一个 {std_string}，表示序列化后的 <>、<>、<> 或 <>。 | <> -| A stateful object which may be used to efficiently serialize one or more - instances of <>, <>, <>, or <>. +| 一个有状态的对象，可用于高效地序列化一个或多个 <>、<>、<> 或 <> 的实例。 |=== -To facilitate debugging and ease of output, library container types may be written to standard output streams using the stream operator: +为便于调试和输出，库中的容器类型可通过流操作符写入标准输出流： [source] ---- include::../../../test/doc_serializing.cpp[tag=doc_serializing_1,indent=0] ---- -The <> function converts a <> into a {std_string}: +<> 函数将一个 <> 转换为 {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. +与解析器类似，序列化器可通过调用 <> 重复使用。这会将对象重置为序列化新实例的状态，并保留先前分配的内存，从而在序列化多个变量时提升性能。 From 3de6bf3103a34ce77138a68df3c484f6fdfc99fe Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Thu, 23 Apr 2026 15:26:19 +0000 Subject: [PATCH 61/68] Translated using Weblate (Chinese (Simplified Han script)) Currently translated at 100.0% (58 of 58 strings) Translation: Boost Json Translation (zh_Hans)/Doc / Pages / Quick Look (adoc) Translate-URL: https://boost-weblate.cloud/projects/boost-json-documentation-zh_Hans/doc-pages-quick-look-adoc/zh_Hans/ --- doc/pages/quick_look_zh_Hans.adoc | 66 +++++++++++++++---------------- 1 file changed, 33 insertions(+), 33 deletions(-) diff --git a/doc/pages/quick_look_zh_Hans.adoc b/doc/pages/quick_look_zh_Hans.adoc index 4a79f31..acc8965 100644 --- a/doc/pages/quick_look_zh_Hans.adoc +++ b/doc/pages/quick_look_zh_Hans.adoc @@ -9,15 +9,15 @@ Official repository: https://github.com/boostorg/json //// [pagelevels=1,toclevels=1] -= Quick Look -Here we highlight important features through example code to help convey the style of the interface. We begin by including the library header file which brings all the symbols into scope. Alternatively, individual headers may be included to obtain the declarations for specific types: += 快速浏览 +这里我们通过示例代码重点介绍重要特性，以帮助理解接口风格。首先包含库头文件，该文件将所有符号引入作用域；或者，也可以包含单独的头文件以获取特定类型的声明： [source] ---- #include ---- -In order to link your program you will need to link with a built library. Alternatively you can use the header-only configuration simply by including this header file in any __one__ of your new or existing source files: +为链接程序，您需要链接已构建的库。或者，您可以使用仅需头文件（header-only）的配置，只需在任意__一个__新建或现有源文件中包含此头文件： [source] ---- @@ -26,7 +26,7 @@ In order to link your program you will need to link with a built library. Altern [NOTE] ==== -Sample code and identifiers used throughout are written as if the following declarations are in effect: +文中所使用的示例代码和标识符均假定以下声明已生效： [source] ---- @@ -36,8 +36,8 @@ using namespace boost::json; ==== [#quick_look_values] -== Values -Say you want to recreate this JSON object in a container: +== 值 +假设您要在容器中重建一下 JSON 对象： [source, json] ---- @@ -57,21 +57,21 @@ Say you want to recreate this JSON object in a container: } ---- -In this library the types <>, <>, and <> hold JSON arrays, objects, and strings respectively while the type <> is a special variant which can hold any JSON element. Here we construct an empty object and then insert the elements above: +在本库中，类型 <>、<> 和 <> 分别用于表示 JSON 数组、对象和字符串，而类型 <> 是一种特殊的变体（variant），可容纳任意 JSON 元素。以下示例首先构造一个空对象，然后插入上述元素： [source] ---- include::../../test/doc_quick_look.cpp[tag=doc_quick_look_1] ---- -While keys are strings, the mapped type of objects and the element type of arrays is the aforementioned type <> which can hold any JSON element, as seen in the previous assignments. Instead of building the JSON document using a series of function calls, we can build it in one statement using an initializer list: +尽管键是字符串，但对象的映射类型和数组的元素类型均为前述的 <> 类型，它可以保存任意 JSON 元素，如前文赋值所示。除了通过一系列函数调用构建 JSON 文档外，我们还可以使用初始化列表在一条语句中完成构建： [source] ---- include::../../test/doc_quick_look.cpp[tag=doc_quick_look_2] ---- -When a <>, <>, or <> is assigned or constructed from an initializer list, the creation of the new value happens only once. This makes initializer lists equally efficient as using the other ways to create a value. The types in this library are first-class, supporting copy and move construction and assignment: +当 <>, <>, 或 <> 通过初始化列表进行赋值或构造时，新值的创建仅发生一次。这使得初始化列表在效率上与其他创建值的方式相当。本库中的类型均为一等类型，支持复制和移动构造及赋值： [source] ---- @@ -79,79 +79,79 @@ include::../../test/doc_quick_look.cpp[tag=doc_quick_look_3] ---- [#quick_look_allocators] -== Allocators -To permit custom memory allocation strategies, these containers all allow construction with a <> which is a smart pointer to a {ref_memory_resource}. The constructor signatures have the same ordering as their `std` equivalents which use {req_Allocator} parameters. Once a container is constructed its memory resource can never change. Here we create an array without performing any dynamic allocations: +== 分配器 +为支持自定义内存分配策略，这些容器均允许通过一个 <>（指向 {ref_memory_resource} 的智能指针）进行构造。其构造函数签名的参数顺序与使用 {req_Allocator} 参数的标准库等价类型一致。容器一旦构造完成，其内存资源便不可更改。以下代码创建了一个未执行任何动态分配的数组： [source] ---- include::../../test/doc_quick_look.cpp[tag=doc_quick_look_4] ---- -The containers in this library enforce the invariant that every element of the container will use the same memory resource: +本库中的容器强制保持一个不变式：容器的每个元素都使用相同的内存资源： [source] ---- include::../../test/doc_quick_look.cpp[tag=doc_quick_look_5] ---- -When a library type is used as the element type of a PMR container; that is, a container which uses a {ref_polymorphic_allocator}, the memory resource will automatically propagate to the type and all of its children: +当库类型用作 PMR 容器（即使用 {ref_polymorphic_allocator} 的容器）的元素类型时，内存资源将自动传播至该类型及其所有子元素： [source] ---- include::../../test/doc_quick_look.cpp[tag=doc_quick_look_6] ---- -Up until now we have shown how values may be constructed from a memory resource pointer, where ownership is not transferred. In this case the caller is responsible for ensuring that the lifetime of the resource is extended for the life of the container. Sometimes you want the container to acquire shared ownership of the resource. This is accomplished with <>: +截至目前，我们已展示如何通过内存资源指针（不转移所有权）构造值。此时调用方需确保资源生命周期覆盖容器的生命周期。有时您希望容器获取资源的共享所有权。这可通过 <> 实现： [source] ---- include::../../test/doc_quick_look.cpp[tag=doc_quick_look_7] ---- -A counted memory resource will not be destroyed until every container with shared ownership of the resource is destroyed. +计数内存资源在拥有其共享所有权的每个容器均被销毁之前，是不会被销毁的。 [#quick_look_parsing] -== Parsing -JSON can be parsed into the value container in one step using a free function. In the following snippet, a parse error is indicated by a thrown exception: +== 解析 +可使用自由函数将 JSON 一步解析至值容器。在以下代码片段中，解析错误通过抛出异常指示： [source] ---- include::../../test/doc_quick_look.cpp[tag=doc_quick_look_8] ---- -Error codes are also possible: +也支持错误码： [source] ---- include::../../test/doc_quick_look.cpp[tag=doc_quick_look_9] ---- -By default, the parser is strict and only accepts JSON compliant with the standard. However this behavior can be relaxed by filling out an options structure enabling one or more extensions. Here we use a static buffer and enable two non-standard extensions: +默认情况下，解析器采用严格模式，仅接受符合标准的 JSON。但可通过填充一个选项结构体来启用一个或多个扩展，从而放宽此行为。以下示例使用静态缓冲区并启用了两个非标准扩展： [source] ---- include::../../test/doc_quick_look.cpp[tag=doc_quick_look_10] ---- -The parser in this library implements a https://en.wikipedia.org/wiki/Online_algorithm[__streaming algorithm__]; it can process JSON piece-by-piece, without the requirement that the entire input is available from the start. The parser uses a temporary memory allocation to do its work. If you plan on parsing multiple JSONs, for example in a network server, keeping the same parser instance will allow re-use of this temporary storage, improving performance. +本库中的解析器实现了一种 https://en.wikipedia.org/wiki/Online_algorithm[__streaming algorithm__]（流式算法）；它可逐段处理 JSON，无需从一开始就提供完整输入。解析器在工作时会使用临时内存分配。如果计划解析多个 JSON（例如在网络服务器中），复用同一个解析器实例可以重用该临时存储，从而提升性能。 [source] ---- include::../../test/doc_quick_look.cpp[tag=doc_quick_look_11] ---- -With strategic use of the right memory resources, parser instance, and calculated upper limits on buffer sizes, it is possible to parse and examine JSON without __any__ dynamic memory allocations. This is explored in more detail in a later section. +通过合理使用适当的内存资源、解析器实例及缓冲区大小的计算上限，可在不进行__任何__动态内存分配的情况下解析和检查 JSON。后续章节将对此进行更详细探讨。 [#quick_look_serializing] -== Serializing -Simple free functions are provided for serializing a <> to a {std_string} containing JSON: +== 序列化 +提供了简单的自由函数，用于将 <> 序列化为包含 JSON 的 {std_string}： [source] ---- include::../../test/doc_quick_look.cpp[tag=doc_quick_look_12] ---- -The serializer in this library implements a https://en.wikipedia.org/wiki/Online_algorithm[__streaming algorithm__]; it can output JSON a piece at a time, without the requirement that the entire output area is allocated at once: +本库中的序列化器实现了 https://en.wikipedia.org/wiki/Online_algorithm[__streaming algorithm__]（流式算法）；它可逐段输出 JSON，无需一次性分配整个输出空间： [source] ---- @@ -159,57 +159,57 @@ include::../../test/doc_quick_look.cpp[tag=doc_quick_look_13] ---- [#quick_look_conversion] -== Value Conversion -Given a user-defined type: +== 值转换 +给定一个用户定义的类型： [source] ---- include::../../test/doc_quick_look.cpp[tag=doc_quick_look_14] ---- -We can define a conversion from the user-defined type to a <> by defining an overload of `tag_invoke` in the same namespace. This maps `customer` to a JSON object: +我们可在同一命名空间中定义 `tag_invoke` 的重载，来实现从用户定义类型到 <> 的转换。此操作将 `customer` 映射为 JSON 对象： [source] ---- include::../../test/doc_quick_look.cpp[tag=doc_quick_look_15] ---- -This allows us to use the library function <> to produce a <> from our type: +这允许我们可以使用库函数 <> 从我们的类型生成一个 <>： [source] ---- include::../../test/doc_quick_look.cpp[tag=doc_quick_look_16] ---- -The library knows what to do with standard containers. Here we convert an array of customers to a value: +该库能够自动处理标准容器。以下我们将一个客户数组转换为一个值： [source] ---- include::../../test/doc_quick_look.cpp[tag=doc_quick_look_17] ---- -To go from JSON to a user-defined type we use <>, which uses another overload of `tag_invoke`. This converts a JSON value to a `customer`. It throws an exception if the contents of the value do not match what is expected: +为将 JSON 转换为用户定义类型，我们使用 <>（它会调用 `tag_invoke` 的另一个重载）。此操作将 JSON 值转换为 `customer`。若值内容不符合预期，则抛出异常： [source] ---- include::../../test/doc_quick_look.cpp[tag=doc_quick_look_18] ---- -The code above defines the convenience function `extract`, which deduces the types of the struct members. This works, but requires that the struct is {req_DefaultConstructible}. An alternative is to construct the object directly, which is a little more verbose but doesn't require default construction: +上述代码定义了便捷函数 `extract`，它能推导结构体成员的类型。这种方式可行，但要求该结构体是 {req_DefaultConstructible}。另一种方法是直接构造对象，虽然略显冗长，但无需默认构造： [source] ---- include::../../test/doc_quick_look.cpp[tag=doc_quick_look_19] ---- -Now we can construct customers from JSON: +现在我们可以从 JSON 构造客户对象（customer）： [source] ---- include::../../test/doc_quick_look.cpp[tag=doc_quick_look_20] ---- -The library's generic algorithms recognize when you are converting a <> to a container which resembles an array or object, so if you wanted to turn a JSON array into a vector of customers you might write: +当将 <> 转换为类似数组或对象的容器时，库的通用算法可自动识别。因此若要将 JSON 数组转换为客户向量，可编写如下代码： [source] ---- From 40a213ece4b9e0ce9fee1a55f441050cd2195344 Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Thu, 23 Apr 2026 15:26:30 +0000 Subject: [PATCH 62/68] Translated using Weblate (Chinese (Simplified Han script)) Currently translated at 100.0% (6 of 6 strings) Translation: Boost Json Translation (zh_Hans)/Doc / Pages / Reference (adoc) Translate-URL: https://boost-weblate.cloud/projects/boost-json-documentation-zh_Hans/doc-pages-reference-adoc/zh_Hans/ --- doc/pages/reference_zh_Hans.adoc | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/doc/pages/reference_zh_Hans.adoc b/doc/pages/reference_zh_Hans.adoc index a0c60c6..d294480 100644 --- a/doc/pages/reference_zh_Hans.adoc +++ b/doc/pages/reference_zh_Hans.adoc @@ -8,13 +8,13 @@ Official repository: https://github.com/boostorg/json //// [#ref, pagelevels=3,toclevels=1] -= Reference += 参考 [cols=4*a,autowidth] |=== 4+|JSON -a| *Classes* + +a| *类* + <> + <> + <> + @@ -33,7 +33,7 @@ a| *Classes* + <> + <> -a| *Functions* + +a| *函数* + <> + <> + <> + @@ -52,7 +52,7 @@ a| *Functions* + <> + <> -| *Operators* + +| *运算符* + <> + <> + <> + @@ -61,11 +61,11 @@ a| *Functions* + <> + <> + -*Aliases* + +*别名* + <> + <> -*Constants* + +*常量* + <> + <> + <> + @@ -74,7 +74,7 @@ a| *Functions* + <> + <> -| *Type Traits* + +| *类型特征* + <> + <> + <> + From 070bd5a8ec9eb87fa0fa8cb0bc0d39d2788124dc Mon Sep 17 00:00:00 2001 From: Weblate Date: Thu, 23 Apr 2026 21:21:04 +0000 Subject: [PATCH 63/68] Update translation files Updated by "Cleanup translation files" add-on in Weblate. Translation: Boost Json Translation (zh_Hans)/Doc / Pages / Conversion / Nothrow (adoc) Translate-URL: https://boost-weblate.cloud/projects/boost-json-documentation-zh_Hans/doc-pages-conversion-nothrow-adoc/ --- doc/pages/conversion/nothrow_zh_Hans.adoc | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/pages/conversion/nothrow_zh_Hans.adoc b/doc/pages/conversion/nothrow_zh_Hans.adoc index cf3957f..462f5da 100644 --- a/doc/pages/conversion/nothrow_zh_Hans.adoc +++ b/doc/pages/conversion/nothrow_zh_Hans.adoc @@ -7,13 +7,13 @@ 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}。 += Non-Throwing Conversions +For the case where throwing exceptions is undesirable, Boost.JSON also provides a non-throwing version of <>, the function template <>. It returns {ref_result}, a specialised variant that either holds a value or an {ref_error_code}. [NOTE] -对于 <>; 没有对应的不抛异常版本。这仅仅是因为我们尚未遇到需要 <> 向调用者报告错误的情况。 +There's no non-throwing equivalent for <>. This is simply because we haven't yet encountered a situation where <> needed to communicate an error to the caller. -该库为 <> 所支持的所有类型类别均提供了不抛异常的转换。如果用户希望将其用于自定义类型，则需要提供如下形式的 `tag_invoke` 重载： +The library provides non-throwing conversions for all the categories of types it supports with <>. If a user wants to use it with custom types, an overload of `tag_invoke` of this form needs to be provided: ``` @@ -21,20 +21,20 @@ result_for::type tag_invoke( const try_value_to_tag< T >&, const value ``` -对于 <> 节中所述的 `ip_address` 类，该重载可能如下所示： +For the class `ip_address` from the section <> this overload may look like this: [source] ---- include::../../../test/snippets.cpp[tag=snippet_nothrow_1,indent=0] ---- -该重载使我们能够将 `ip_address` 与 <> 一起使用。 +The overload lets us use `ip_address` with <>. [source] ---- include::../../../test/snippets.cpp[tag=snippet_nothrow_2,indent=0] ---- -如果对某个类型使用 <>，而该类型没有本节所述形式的 `tag_invoke` 重载，但存在适用于 <> 的重载，那么库仍会尝试执行转换：它会调用抛异常的重载，并试图将抛出的任何异常转换为 {ref_error_code}。但请注意，这种方式的性能很可能不如专门提供的不抛异常重载。 +If <> is used with a type, for which there's no `tag_invoke` overload of the form described in this section, but there is one of the form intended for <>, then the library still tries to perform the conversion. It uses the throwing overload, and attempts to convert any thrown exception into an {ref_error_code}. Note, though, that such approach will likely be slower then a dedicated overload. -反之亦然：如果存在适用于<> 的 tag_invoke 重载，但没有适用于 <> 的重载，那么调用 <> 时会转而调用不抛异常的重载，随后根据返回的 {ref_error_code} 构造一个 {ref_system_error} 并抛出。由于存在上述回退机制，建议用户在计划使用 <> 时，优先提供本节所述的不抛异常重载，而非抛异常的重载。 +The opposite is also true: if there's a `tag_invoke` overload intended for <>, but not for <>, then calling <> will invoke the non-throwing overload, then construct a {ref_system_error} from the {ref_error_code} and throw it. Due to these fallbacks, it is recommended that users provide the overload from this section, rather then the other one, if they ever intend to use <>. From fb32ada444ee8ecb79bfac83589f53ac1a6387d1 Mon Sep 17 00:00:00 2001 From: Weblate Date: Thu, 23 Apr 2026 21:21:08 +0000 Subject: [PATCH 64/68] Update translation files Updated by "Cleanup translation files" add-on in Weblate. Translation: Boost Json Translation (zh_Hans)/Doc / Pages / Conversion / Custom (adoc) Translate-URL: https://boost-weblate.cloud/projects/boost-json-documentation-zh_Hans/doc-pages-conversion-custom-adoc/ --- doc/pages/conversion/custom_zh_Hans.adoc | 32 ++++++++++++------------ 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/doc/pages/conversion/custom_zh_Hans.adoc b/doc/pages/conversion/custom_zh_Hans.adoc index 557e560..e4ad29d 100644 --- a/doc/pages/conversion/custom_zh_Hans.adoc +++ b/doc/pages/conversion/custom_zh_Hans.adoc @@ -7,36 +7,36 @@ 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`的重载。本节将进一步解释这两种机制。 += Custom Conversions +Boost.JSON uses two mechanisms to customize conversion between <> and user types. One mechanism involves specializing type traits. The other one is more powerful and requires defining overloads of `tag_invoke`. Both mechanisms will be further explained in this section. -== 转换特征 -之前已经介绍了一些转换类型特征，例如 <> 或 <>。库会依次尝试这些特征，并使用与第一个匹配特征对应的实现。然而，在某些情况下，某个类型可能会匹配到优先级更高的特征，而用户实际希望将其归入优先级更低的类别。如果发生这种情况，用户可以针对该类型特化那个不应匹配的特征，使其等同于`std::false_type`。 +== Conversion Traits +Previously a number of conversion type traits, like <> or <>, were introduced. The library tries the traits one after another and uses the implementation that corresponds to the first matching trait. In some cases, though, a type would match a trait with a higher priority, but the user intends for it to belong to a lower priority category. If this happens the user can specialize the trait that's not supposed to match for that type to be an equivalent of `std::false_type`. -考虑以下类型： +Consider this type: [source] ---- include::../../../test/doc_types.hpp[tag=snippet_conv_spec_trait1,indent=0] ---- -它同时暴露了序列（sequence）API 和元组（tuple）API。然而，从 <> 转换到 user_ns::ip_address 时无法使用序列的实现，因为序列类型的转换会先构造一个空对象，再逐个填充元素，而 ip_address 的大小固定为 4。相比之下，元组转换是合适的。唯一的问题在于 <> 的优先级低于 <>。为绕过此问题，用户只需特化 <>，使其对 ip_address 不匹配即可。 +It exposes both a sequence API and a tuple API. But converting from <> to `user_ns::ip_address` would not be able to use implementation for sequences, since those are constructed empty and then populated one element at a time, while `ip_address` has a fixed size of 4. The tuple conversion would fit, though. The only problem is that <> has a lower priority than <>. In order to circumvent this, the user only needs to specialize <> to not match `ip_address`. [source] ---- include::../../../test/snippets.cpp[tag=snippet_conv_spec_trait2,indent=0] ---- -== `tag_invoke`重载 -第二种、更强大的方法是自行提供转换实现。在 Boost.JSON 中，这是通过定义`tag_invoke`函数的重载来实现的（该机制的优点详见 http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1895r0.pdf[C++提案P1895]）。本质上，`tag_invoke` 通过参数依赖查找（ADL）在调用点寻找可用的重载，从而为自定义扩展点提供统一接口。顾名思义，一个标签类型作为参数传递，用于： +== `tag_invoke` Overloads +The second, more powerful approach, is to provide the conversion implementation yourself. With Boost.JSON this is done by defining an overload of `tag_invoke` function (the benefits of this mechanism are outlined in http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1895r0.pdf[C++ proposal P1895]. In essence, `tag_invoke` provides a uniform interface for defining customization points by using argument-dependent lookup to find a viable overload from the point at which it is called. As the name suggests, a tag type is passed as an argument in order to: -* 1. 排除与该特定自定义点无关的候选函数，并且 +* discard candidates that are unrelated to that particular customization point, and -* 2. 将用户定义的类型嵌入到参数列表中（例如，通过使用像`value_to_tag`这样的标签类型模板），以便在执行名称查找时检查其http://eel.is/c++draft/basic.lookup.argdep#2[关联的命名空间和实体]。 +* embed the user-defined type into the arguments list (e.g. by using a tag type template such as `value_to_tag`) so that its http://eel.is/c++draft/basic.lookup.argdep#2[associated namespaces and entities] are examined when name lookup is performed. -这样做的效果是能够找到用户提供的`tag_invoke`重载，即使它们在调用函数定义之后（在词法上）声明。 +This has the effect of finding user-provided `tag_invoke` overloads, even if they are declared (lexically) after the definition of the calling function. -由 <> 调用的 tag_invoke 重载具有如下形式： +Overloads of `tag_invoke` called by <> take the form: ``` @@ -44,7 +44,7 @@ void tag_invoke( const value_from_tag&, value&, T ); ``` -而由 <> 调用的`tag_invoke`重载采用以下形式： +While overloads of `tag_invoke` called by <> take the form: ``` @@ -52,21 +52,21 @@ T tag_invoke( const value_to_tag< T >&, const value& ); ``` -如果我们用这种方法手动实现`user_ns::ip_address`的转换，它将如下所示： +If we implemented conversion for `user_ns::ip_address` manually with this approach, it would look like this: [source] ---- include::../../../test/snippets.cpp[tag=snippet_tag_invoke_1,indent=0] ---- -由于被转换的类型已嵌入函数签名中，用户提供的重载对参数依赖查找（ADL）可见，并会在执行转换时成为候选函数： +Since the type being converted is embedded into the function's signature, user-provided overloads are visible to argument-dependent lookup and will be candidates when a conversion is performed: [source] ---- include::../../../test/snippets.cpp[tag=snippet_tag_invoke_2,indent=0] ---- -用户可以自由地将具有自定义转换的类型与具有库提供转换的类型组合使用，库能正确处理它们： +Users can freely combine types with custom conversions with types with library-provided conversions. The library handles them correctly: [source] ---- From fcb4049b7d703229a4bf743af37ab4c02a0b7406 Mon Sep 17 00:00:00 2001 From: Weblate Date: Thu, 23 Apr 2026 21:21:10 +0000 Subject: [PATCH 65/68] Update translation files Updated by "Cleanup translation files" add-on in Weblate. Translation: Boost Json Translation (zh_Hans)/Doc / Pages / Conversion / Alloc (adoc) Translate-URL: https://boost-weblate.cloud/projects/boost-json-documentation-zh_Hans/doc-pages-conversion-alloc-adoc/ --- doc/pages/conversion/alloc_zh_Hans.adoc | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/doc/pages/conversion/alloc_zh_Hans.adoc b/doc/pages/conversion/alloc_zh_Hans.adoc index 0cab67b..75d87f1 100644 --- a/doc/pages/conversion/alloc_zh_Hans.adoc +++ b/doc/pages/conversion/alloc_zh_Hans.adoc @@ -7,15 +7,15 @@ 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}。 += Allocation Control +As <> creates a <> object, users may want to control the way memory is allocated for it. For this reason the function has an optional <> parameter, that is used to set the {ref_memory_resource} for the result. [NOTE] -<> 没有类似的参数，因为该函数不会创建 <> 对象。 +<> does not have a similar parameter, as <> is not created. -由于转换结果是通过类型为`value&`的输出参数设置的，因此预期的<>会被正确传播。但用户仍需注意，避免意外创建使用默认 {ref_memory_resource} 的临时对象。 +As the conversion result is set via an output parameter of type `value&`, the intended <> is correctly propagated. But users still should take care to not create temporaries using the default {ref_memory_resource} by accident. -例如，考虑<>节中针对`ip_address`的`tag_invoke`的替代实现。 +For example, consider this alternative implementation of `tag_invoke` for `ip_address` from the section <>. ``` @@ -27,6 +27,6 @@ tag_invoke( const value_from_tag&, value& jv, ip_address const& addr ) ``` -该实现显式创建了一个 <>，而不是依赖于初始化列表的赋值。但该数组使用的是默认的 {ref_memory_resource}，而不是`jv`所使用的内存资源。 +This implementation explicitly creates an <> rather than relying on assignment from an initializer list. But the array uses default {ref_memory_resource}, not the one used by `jv`. -为避免创建使用错误 {ref_memory_resource} 的临时对象，可以借助 <> 的成员函数 <>、<> 和 <>。 +To avoid creating such temporaries with an incorrect {ref_memory_resource}, using <>'s member functions <>, <>, and <> can be helpful. From ed9e3c8e815751f9738e7cc59d1e0b4ba901f73f Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Thu, 23 Apr 2026 21:34:03 +0000 Subject: [PATCH 66/68] Translated using Weblate (Chinese (Simplified Han script)) Currently translated at 100.0% (8 of 8 strings) Translation: Boost Json Translation (zh_Hans)/Doc / Pages / Conversion / Alloc (adoc) Translate-URL: https://boost-weblate.cloud/projects/boost-json-documentation-zh_Hans/doc-pages-conversion-alloc-adoc/zh_Hans/ --- doc/pages/conversion/alloc_zh_Hans.adoc | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/doc/pages/conversion/alloc_zh_Hans.adoc b/doc/pages/conversion/alloc_zh_Hans.adoc index 75d87f1..0cab67b 100644 --- a/doc/pages/conversion/alloc_zh_Hans.adoc +++ b/doc/pages/conversion/alloc_zh_Hans.adoc @@ -7,15 +7,15 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) Official repository: https://github.com/boostorg/json //// -= Allocation Control -As <> creates a <> object, users may want to control the way memory is allocated for it. For this reason the function has an optional <> parameter, that is used to set the {ref_memory_resource} for the result. += 分配控制 +由于<>会创建一个<>对象，用户可能希望控制其内存分配方式。因此，该函数具有一个可选的 <> 参数，用于为结果指定{ref_memory_resource}。 [NOTE] -<> does not have a similar parameter, as <> is not created. +<> 没有类似的参数，因为该函数不会创建 <> 对象。 -As the conversion result is set via an output parameter of type `value&`, the intended <> is correctly propagated. But users still should take care to not create temporaries using the default {ref_memory_resource} by accident. +由于转换结果是通过类型为`value&`的输出参数设置的，因此预期的<>会被正确传播。但用户仍需注意，避免意外创建使用默认 {ref_memory_resource} 的临时对象。 -For example, consider this alternative implementation of `tag_invoke` for `ip_address` from the section <>. +例如，考虑<>节中针对`ip_address`的`tag_invoke`的替代实现。 ``` @@ -27,6 +27,6 @@ tag_invoke( const value_from_tag&, value& jv, ip_address const& addr ) ``` -This implementation explicitly creates an <> rather than relying on assignment from an initializer list. But the array uses default {ref_memory_resource}, not the one used by `jv`. +该实现显式创建了一个 <>，而不是依赖于初始化列表的赋值。但该数组使用的是默认的 {ref_memory_resource}，而不是`jv`所使用的内存资源。 -To avoid creating such temporaries with an incorrect {ref_memory_resource}, using <>'s member functions <>, <>, and <> can be helpful. +为避免创建使用错误 {ref_memory_resource} 的临时对象，可以借助 <> 的成员函数 <>、<> 和 <>。 From dcc902e16f20c63e4d5d1275b6c5759f77462a4e Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Thu, 23 Apr 2026 21:34:47 +0000 Subject: [PATCH 67/68] Translated using Weblate (Chinese (Simplified Han script)) Currently translated at 100.0% (23 of 23 strings) Translation: Boost Json Translation (zh_Hans)/Doc / Pages / Conversion / Custom (adoc) Translate-URL: https://boost-weblate.cloud/projects/boost-json-documentation-zh_Hans/doc-pages-conversion-custom-adoc/zh_Hans/ --- doc/pages/conversion/custom_zh_Hans.adoc | 32 ++++++++++++------------ 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/doc/pages/conversion/custom_zh_Hans.adoc b/doc/pages/conversion/custom_zh_Hans.adoc index e4ad29d..557e560 100644 --- a/doc/pages/conversion/custom_zh_Hans.adoc +++ b/doc/pages/conversion/custom_zh_Hans.adoc @@ -7,36 +7,36 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) Official repository: https://github.com/boostorg/json //// -= Custom Conversions -Boost.JSON uses two mechanisms to customize conversion between <> and user types. One mechanism involves specializing type traits. The other one is more powerful and requires defining overloads of `tag_invoke`. Both mechanisms will be further explained in this section. += 自定义转换 +Boost.JSON 提供了两种机制用于自定义 <> 与用户类型之间的转换。一种机制涉及特化类型特征（type traits）。另一种机制更强大，需要定义`tag_invoke`的重载。本节将进一步解释这两种机制。 -== Conversion Traits -Previously a number of conversion type traits, like <> or <>, were introduced. The library tries the traits one after another and uses the implementation that corresponds to the first matching trait. In some cases, though, a type would match a trait with a higher priority, but the user intends for it to belong to a lower priority category. If this happens the user can specialize the trait that's not supposed to match for that type to be an equivalent of `std::false_type`. +== 转换特征 +之前已经介绍了一些转换类型特征，例如 <> 或 <>。库会依次尝试这些特征，并使用与第一个匹配特征对应的实现。然而，在某些情况下，某个类型可能会匹配到优先级更高的特征，而用户实际希望将其归入优先级更低的类别。如果发生这种情况，用户可以针对该类型特化那个不应匹配的特征，使其等同于`std::false_type`。 -Consider this type: +考虑以下类型： [source] ---- include::../../../test/doc_types.hpp[tag=snippet_conv_spec_trait1,indent=0] ---- -It exposes both a sequence API and a tuple API. But converting from <> to `user_ns::ip_address` would not be able to use implementation for sequences, since those are constructed empty and then populated one element at a time, while `ip_address` has a fixed size of 4. The tuple conversion would fit, though. The only problem is that <> has a lower priority than <>. In order to circumvent this, the user only needs to specialize <> to not match `ip_address`. +它同时暴露了序列（sequence）API 和元组（tuple）API。然而，从 <> 转换到 user_ns::ip_address 时无法使用序列的实现，因为序列类型的转换会先构造一个空对象，再逐个填充元素，而 ip_address 的大小固定为 4。相比之下，元组转换是合适的。唯一的问题在于 <> 的优先级低于 <>。为绕过此问题，用户只需特化 <>，使其对 ip_address 不匹配即可。 [source] ---- include::../../../test/snippets.cpp[tag=snippet_conv_spec_trait2,indent=0] ---- -== `tag_invoke` Overloads -The second, more powerful approach, is to provide the conversion implementation yourself. With Boost.JSON this is done by defining an overload of `tag_invoke` function (the benefits of this mechanism are outlined in http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1895r0.pdf[C++ proposal P1895]. In essence, `tag_invoke` provides a uniform interface for defining customization points by using argument-dependent lookup to find a viable overload from the point at which it is called. As the name suggests, a tag type is passed as an argument in order to: +== `tag_invoke`重载 +第二种、更强大的方法是自行提供转换实现。在 Boost.JSON 中，这是通过定义`tag_invoke`函数的重载来实现的（该机制的优点详见 http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1895r0.pdf[C++提案P1895]）。本质上，`tag_invoke` 通过参数依赖查找（ADL）在调用点寻找可用的重载，从而为自定义扩展点提供统一接口。顾名思义，一个标签类型作为参数传递，用于： -* discard candidates that are unrelated to that particular customization point, and +* 1. 排除与该特定自定义点无关的候选函数，并且 -* embed the user-defined type into the arguments list (e.g. by using a tag type template such as `value_to_tag`) so that its http://eel.is/c++draft/basic.lookup.argdep#2[associated namespaces and entities] are examined when name lookup is performed. +* 2. 将用户定义的类型嵌入到参数列表中（例如，通过使用像`value_to_tag`这样的标签类型模板），以便在执行名称查找时检查其http://eel.is/c++draft/basic.lookup.argdep#2[关联的命名空间和实体]。 -This has the effect of finding user-provided `tag_invoke` overloads, even if they are declared (lexically) after the definition of the calling function. +这样做的效果是能够找到用户提供的`tag_invoke`重载，即使它们在调用函数定义之后（在词法上）声明。 -Overloads of `tag_invoke` called by <> take the form: +由 <> 调用的 tag_invoke 重载具有如下形式： ``` @@ -44,7 +44,7 @@ void tag_invoke( const value_from_tag&, value&, T ); ``` -While overloads of `tag_invoke` called by <> take the form: +而由 <> 调用的`tag_invoke`重载采用以下形式： ``` @@ -52,21 +52,21 @@ T tag_invoke( const value_to_tag< T >&, const value& ); ``` -If we implemented conversion for `user_ns::ip_address` manually with this approach, it would look like this: +如果我们用这种方法手动实现`user_ns::ip_address`的转换，它将如下所示： [source] ---- include::../../../test/snippets.cpp[tag=snippet_tag_invoke_1,indent=0] ---- -Since the type being converted is embedded into the function's signature, user-provided overloads are visible to argument-dependent lookup and will be candidates when a conversion is performed: +由于被转换的类型已嵌入函数签名中，用户提供的重载对参数依赖查找（ADL）可见，并会在执行转换时成为候选函数： [source] ---- include::../../../test/snippets.cpp[tag=snippet_tag_invoke_2,indent=0] ---- -Users can freely combine types with custom conversions with types with library-provided conversions. The library handles them correctly: +用户可以自由地将具有自定义转换的类型与具有库提供转换的类型组合使用，库能正确处理它们： [source] ---- From bb47117a9a22b0e3ba9895f055b9ef388c62de3a Mon Sep 17 00:00:00 2001 From: Boost-Weblate Admin Date: Thu, 23 Apr 2026 21:35:17 +0000 Subject: [PATCH 68/68] Translated using Weblate (Chinese (Simplified Han script)) Currently translated at 100.0% (11 of 11 strings) Translation: Boost Json Translation (zh_Hans)/Doc / Pages / Conversion / Nothrow (adoc) Translate-URL: https://boost-weblate.cloud/projects/boost-json-documentation-zh_Hans/doc-pages-conversion-nothrow-adoc/zh_Hans/ --- doc/pages/conversion/nothrow_zh_Hans.adoc | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/pages/conversion/nothrow_zh_Hans.adoc b/doc/pages/conversion/nothrow_zh_Hans.adoc index 462f5da..cf3957f 100644 --- a/doc/pages/conversion/nothrow_zh_Hans.adoc +++ b/doc/pages/conversion/nothrow_zh_Hans.adoc @@ -7,13 +7,13 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) Official repository: https://github.com/boostorg/json //// -= Non-Throwing Conversions -For the case where throwing exceptions is undesirable, Boost.JSON also provides a non-throwing version of <>, the function template <>. It returns {ref_result}, a specialised variant that either holds a value or an {ref_error_code}. += 不抛异常的转换 +对于不希望抛出异常的场景，Boost.JSON 还提供了 <> 的不抛异常版本，即函数模板 <>。它返回 {ref_result}，这是一个特化的变体类型，要么持有转换得到的值，要么持有 {ref_error_code}。 [NOTE] -There's no non-throwing equivalent for <>. This is simply because we haven't yet encountered a situation where <> needed to communicate an error to the caller. +对于 <>; 没有对应的不抛异常版本。这仅仅是因为我们尚未遇到需要 <> 向调用者报告错误的情况。 -The library provides non-throwing conversions for all the categories of types it supports with <>. If a user wants to use it with custom types, an overload of `tag_invoke` of this form needs to be provided: +该库为 <> 所支持的所有类型类别均提供了不抛异常的转换。如果用户希望将其用于自定义类型，则需要提供如下形式的 `tag_invoke` 重载： ``` @@ -21,20 +21,20 @@ result_for::type tag_invoke( const try_value_to_tag< T >&, const value ``` -For the class `ip_address` from the section <> this overload may look like this: +对于 <> 节中所述的 `ip_address` 类，该重载可能如下所示： [source] ---- include::../../../test/snippets.cpp[tag=snippet_nothrow_1,indent=0] ---- -The overload lets us use `ip_address` with <>. +该重载使我们能够将 `ip_address` 与 <> 一起使用。 [source] ---- include::../../../test/snippets.cpp[tag=snippet_nothrow_2,indent=0] ---- -If <> is used with a type, for which there's no `tag_invoke` overload of the form described in this section, but there is one of the form intended for <>, then the library still tries to perform the conversion. It uses the throwing overload, and attempts to convert any thrown exception into an {ref_error_code}. Note, though, that such approach will likely be slower then a dedicated overload. +如果对某个类型使用 <>，而该类型没有本节所述形式的 `tag_invoke` 重载，但存在适用于 <> 的重载，那么库仍会尝试执行转换：它会调用抛异常的重载，并试图将抛出的任何异常转换为 {ref_error_code}。但请注意，这种方式的性能很可能不如专门提供的不抛异常重载。 -The opposite is also true: if there's a `tag_invoke` overload intended for <>, but not for <>, then calling <> will invoke the non-throwing overload, then construct a {ref_system_error} from the {ref_error_code} and throw it. Due to these fallbacks, it is recommended that users provide the overload from this section, rather then the other one, if they ever intend to use <>. +反之亦然：如果存在适用于<> 的 tag_invoke 重载，但没有适用于 <> 的重载，那么调用 <> 时会转而调用不抛异常的重载，随后根据返回的 {ref_error_code} 构造一个 {ref_system_error} 并抛出。由于存在上述回退机制，建议用户在计划使用 <> 时，优先提供本节所述的不抛异常重载，而非抛异常的重载。