document direct parsing

doc/qbk/conversion/direct.qbk

@@ -0,0 +1,40 @@
+[/
+    Copyright (c) 2023 Dmitry Arkhipov ([email protected])
+
+    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
+]
+
+[/-----------------------------------------------------------------------------]
+
+
+[section Direct parsing]
+
+For large inputs parsing into the library's containers followed by conversion
+via __value_to__ might be prohibitively expensive. For this cases the library
+provides components that allow parsing directly into 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 __value_to__, then you can get a significant
+performance boost with direct parsing.
+
+Direct parsing is performed by the __parse_into__ family of functions. The
+library provides overloads that take either __string_view__ or `std::istream`,
+and can report errors either via throwing exceptions or setting an error code.
+
+[doc_parse_into_1]
+
+Finally, if you need to combine incremental parsing with direct parsing, you
+can resort to __parser_for__. `parser_for<T>` is an instantiation of
+__basic_parser__ that parses into an object of type `T`, and is what
+__parse_into__ uses under the hood.
+
+[endsect]

doc/qbk/conversion/guidelines.qbk

@@ -21,6 +21,10 @@ 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
@@ -37,6 +41,6 @@ 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 extra functionality.
+libraries for which interoperation with Boost.JSON is only ancillary.
 
 [endsect]

doc/qbk/conversion/overview.qbk

@@ -23,6 +23,7 @@ from the standard library.
 [include alloc.qbk]
 [include context.qbk]
 [include forward.qbk]
+[include direct.qbk]
 [include guidelines.qbk]
 
 [endsect]

doc/qbk/main.qbk

@@ -73,7 +73,9 @@
 [def __monotonic_resource__     [link json.ref.boost__json__monotonic_resource `monotonic_resource`]]
 [def __object__                 [link json.ref.boost__json__object `object`]]
 [def __parse__                  [link json.ref.boost__json__parse `parse`]]
+[def __parse_into__             [link json.ref.boost__json__parse_into `parse_into`]]
 [def __parser__                 [link json.ref.boost__json__parser `parser`]]
+[def __parser_for__             [link json.ref.boost__json__parser_for `parser_for`]]
 [def __parse_options__          [link json.ref.boost__json__parse_options `parse_options`]]
 [def __polymorphic_allocator__  [link json.ref.boost__json__polymorphic_allocator `polymorphic_allocator`]]
 [def __result__                 [link json.ref.boost__json__result `result`]]

test/snippets.cpp

@@ -1122,6 +1122,16 @@ usingContextualConversions()
     }
 }
 
+void
+usingParseInto()
+{
+//[doc_parse_into_1
+    std::map< std::string, std::vector<int> > vectors;
+    string_view input = R"( { "even": [2,4,6], "odd": [1,3,5] } )";
+    parse_into(vectors, input);
+//]
+}
+
 } // namespace
 
 class snippets_test
@@ -1140,6 +1150,7 @@ class snippets_test
         usingSpecializedTrait();
         usingSetAtPointer();
         usingContextualConversions();
+        usingParseInto();
 
         BOOST_TEST_PASS();
     }