Feature/parse into

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`]]

doc/qbk/quickref.xml

@@ -50,6 +50,7 @@
           <member><link linkend="json.ref.boost__json__get_null_resource">get_null_resource</link></member>
           <member><link linkend="json.ref.boost__json__make_shared_resource">make_shared_resource</link></member>
           <member><link linkend="json.ref.boost__json__parse">parse</link></member>
+          <member><link linkend="json.ref.boost__json__parse_into">parse_into</link></member>
           <member><link linkend="json.ref.boost__json__result_from_errno">result_from_errno</link></member>
           <member><link linkend="json.ref.boost__json__serialize">serialize</link></member>
           <member><link linkend="json.ref.boost__json__to_string">to_string</link></member>
@@ -109,6 +110,7 @@
           <member><link linkend="json.ref.boost__json__error_code">error_code</link></member>
           <member><link linkend="json.ref.boost__json__error_condition">error_condition</link></member>
           <member><link linkend="json.ref.boost__json__memory_resource">memory_resource</link></member>
+          <member><link linkend="json.ref.boost__json__parser_for">parser_for</link></member>
           <member><link linkend="json.ref.boost__json__polymorphic_allocator">polymorphic_allocator</link></member>
           <member><link linkend="json.ref.boost__json__result">result</link></member>
           <member><link linkend="json.ref.boost__json__string_view">string_view</link></member>

example/CMakeLists.txt

@@ -9,6 +9,9 @@
 
 source_group("" FILES
     file.hpp
+    parse_into.cpp
+    parse_into_canada.cpp
+    parse_into_citm_catalog.cpp
     path.cpp
     pretty.cpp
     proxy.cpp
@@ -17,6 +20,26 @@ source_group("" FILES
 
 #
 
+add_executable(parse_into
+    parse_into.cpp
+)
+set_property(TARGET parse_into PROPERTY FOLDER "example")
+target_link_libraries(parse_into PRIVATE Boost::json)
+
+add_executable(parse_into_canada
+    parse_into_canada.cpp
+)
+set_property(TARGET parse_into_canada PROPERTY FOLDER "example")
+target_link_libraries(parse_into_canada PRIVATE Boost::json)
+
+add_executable(parse_into_citm_catalog
+    parse_into_citm_catalog.cpp
+)
+set_property(TARGET parse_into_citm_catalog PROPERTY FOLDER "example")
+target_link_libraries(parse_into_citm_catalog PRIVATE Boost::json)
+
+#
+
 add_executable(path
     path.cpp
 )

example/Jamfile

@@ -11,6 +11,12 @@ project : requirements <library>/boost/json//boost_json ;
 
 exe path : path.cpp ;
 
+exe parse_into : parse_into.cpp ;
+
+exe parse_into_canada : parse_into_canada.cpp ;
+
+exe parse_into_citm_catalog : parse_into_citm_catalog.cpp ;
+
 exe pretty : pretty.cpp ;
 
 exe proxy : proxy.cpp ;

example/parse_into.cpp

@@ -0,0 +1,235 @@
+//
+// Copyright (c) 2021 Peter Dimov
+//
+// 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
+//
+
+//
+// An example that compares the performance of json::parse and
+// json::parse_into, using https://github.com/kostya/benchmarks#json
+//
+// Typical results:
+//
+// 1.json: 115075437 bytes
+// boost::json::parse: 721 ms
+//   x: -5.00335e-30, y: 5.00428e+30, z: 0.499722: 121 ms
+// parse_into coordinates: 398 ms
+//   x: -5.00335e-30, y: 5.00428e+30, z: 0.499722: 3 ms
+// parse_into coordinates2: 326 ms
+//   x: -5.00335e-30, y: 5.00428e+30, z: 0.499722: 0 ms
+//
+
+#include <boost/json.hpp>
+#include <iostream>
+
+#if !defined(BOOST_DESCRIBE_CXX14)
+
+#include <boost/config/pragma_message.hpp>
+
+BOOST_PRAGMA_MESSAGE( "This example requires C++14" )
+
+int main() {}
+
+#else
+
+#include <boost/describe.hpp>
+
+#include <chrono>
+#include <fstream>
+#include <iterator>
+#include <map>
+#include <vector>
+
+// An std::map<std::string, std::pair<int, bool>> replacement
+// We don't need to store the options
+
+struct options
+{
+    using mapped_type = std::pair<int, bool>;
+    using value_type = std::pair<std::string, mapped_type>;
+    using iterator = value_type*;
+
+    std::pair<iterator, bool>
+    emplace( value_type const& );
+
+    void
+    emplace( std::string const&, mapped_type const& )
+    {
+    }
+
+    iterator
+    begin();
+
+    iterator
+    end();
+
+    void
+    clear()
+    { }
+};
+
+struct coordinate
+{
+    double x{}, y{}, z{};
+    std::string name;
+    options opts;
+};
+
+BOOST_DESCRIBE_STRUCT(coordinate, (), (x, y, z, name, opts))
+
+struct coordinates1
+{
+    std::vector<coordinate> coordinates;
+    std::string info;
+};
+
+BOOST_DESCRIBE_STRUCT(coordinates1, (), (coordinates, info))
+
+// std::vector<coordinate> replacement that just
+// keeps a running sum
+
+struct accumulator
+{
+    using value_type = coordinate;
+    using iterator = coordinate*;
+
+    std::size_t len = 0;
+
+    double x = 0;
+    double y = 0;
+    double z = 0;
+
+    void push_back( coordinate const& v )
+    {
+        x += v.x;
+        y += v.y;
+        z += v.z;
+
+        ++len;
+    }
+
+    iterator
+    begin() { return nullptr; }
+
+    iterator
+    end() { return nullptr; }
+
+    void
+    clear()
+    { }
+};
+
+struct coordinates2
+{
+    accumulator coordinates;
+    std::string info;
+};
+
+BOOST_DESCRIBE_STRUCT(coordinates2, (), (coordinates, info))
+
+using namespace std::chrono_literals;
+
+int main()
+{
+    // https://github.com/kostya/benchmarks/blob/master/json/generate_json.rb
+    std::ifstream is( "/tmp/1.json" );
+    std::string json( std::istreambuf_iterator<char>( is ), std::istreambuf_iterator<char>{} );
+
+    std::cout << "1.json: " << json.size() << " bytes\n";
+
+    // https://github.com/kostya/benchmarks/blob/master/json/test_boost_json.cpp
+    {
+        auto tp1 = std::chrono::steady_clock::now();
+
+        boost::json::value jv = boost::json::parse( json );
+
+        auto tp2 = std::chrono::steady_clock::now();
+        std::cout << "boost::json::parse: " << (tp2 - tp1) / 1ms << " ms\n";
+
+        auto x = 0.0, y = 0.0, z = 0.0;
+        auto len = 0;
+
+        auto &obj = jv.get_object();
+
+        for( auto& v: obj["coordinates"].get_array() )
+        {
+            ++len;
+            auto& coord = v.get_object();
+            x += coord["x"].get_double();
+            y += coord["y"].get_double();
+            z += coord["z"].get_double();
+        }
+
+        x /= len;
+        y /= len;
+        z /= len;
+
+        auto tp3 = std::chrono::steady_clock::now();
+        std::cout << "  x: " << x << ", y: " << y << ", z: " << z << ": " << (tp3 - tp2) / 1ms << " ms\n";
+    }
+
+    {
+        auto tp1 = std::chrono::steady_clock::now();
+
+        coordinates1 w;
+
+        boost::json::error_code ec;
+        boost::json::parse_into( w, json, ec );
+
+        if( ec.failed() )
+        {
+            std::cout << "Error: " << ec.what() << std::endl;
+        }
+
+        auto tp2 = std::chrono::steady_clock::now();
+        std::cout << "parse_into coordinates: " << (tp2 - tp1) / 1ms << " ms\n";
+
+        auto x = 0.0, y = 0.0, z = 0.0;
+        auto len = 0;
+
+        for( auto const& v: w.coordinates )
+        {
+            x += v.x;
+            y += v.y;
+            z += v.z;
+
+            ++len;
+        }
+
+        x /= len;
+        y /= len;
+        z /= len;
+
+        auto tp3 = std::chrono::steady_clock::now();
+        std::cout << "  x: " << x << ", y: " << y << ", z: " << z << ": " << (tp3 - tp2) / 1ms << " ms\n";
+    }
+
+    {
+        auto tp1 = std::chrono::steady_clock::now();
+
+        coordinates2 w;
+
+        boost::json::error_code ec;
+        boost::json::parse_into( w, json, ec );
+
+        if( ec.failed() )
+        {
+            std::cout << "Error: " << ec.what() << std::endl;
+        }
+
+        auto tp2 = std::chrono::steady_clock::now();
+        std::cout << "parse_into coordinates2: " << (tp2 - tp1) / 1ms << " ms\n";
+
+        double x = w.coordinates.x / w.coordinates.len;
+        double y = w.coordinates.y / w.coordinates.len;
+        double z = w.coordinates.z / w.coordinates.len;
+
+        auto tp3 = std::chrono::steady_clock::now();
+        std::cout << "  x: " << x << ", y: " << y << ", z: " << z << ": " << (tp3 - tp2) / 1ms << " ms\n";
+    }
+}
+
+#endif