September 2020 - Boost - lists.preview.boost.org

Boost.Text is looking for a (mini-)review manager
by Zach Laine 07 Dec '22

07 Dec '22

I've made all the recommended changes to Boost.Text that came up in the review. Glen, the previous review manager, recommended a mini review of Boost.Text once I'd made those changes. If you'd like to manage the mini-review, please let me know. For everyone, including potential reviewers and review managers, here are the major changes: * All the specific review feedback issues have been addressed. * The string layer is now gone. * The text layer got a major re-work. It is now a set of template-based adaptors (basic_text<>, vs. a text typedef. etc.), which lets everyone get what they want. You can change the underlying storage type (including whatever allocator you prefer), select UTF-8 or UTF-16, and change the normalization form. Glen recommended I drop this layer, but the library is way less useful without this stuff, and these changes address all the concerns raised about the text layer in the review. The updated docs can be found here: https://tzlaine.github.io/text/doc/html/index.html Oh yeah, and I added concept constraints to the whole library when you build in C++20 mode. Zach

17 46

[review][JSON] Review of JSON starts today: Sept 14 - Sept 23
by Pranam Lashkari 09 Aug '22

09 Aug '22

Boost formal review of Vinnie Falco and Krystian Stasiowski's library JSON starts today and will run for 10 days ending on 23 Sept 2020. Both of these authors have already developed a couple of libraries which are accepted in Boost(boost beast and Static String) This library focuses on a common and popular use-case for JSON. It provides a container to hold parsed and serialised JSON types. It provides more flexibility and better benchmark performance than its competitors. JSON highlights the following features in the documentation: - Fast compilation - Require only C++11 - Fast streaming parser and serializer - Easy and safe API with allocator support - Constant-time key lookup for objects - Options to allow non-standard JSON - Compile without Boost, define BOOST_JSON_STANDALONE - Optional header-only, without linking to a library (a point I would like to add in highlight: it has cool Jason logo 😝) To quickly understand and get the flavour of the library take a look at "Quick Look" <http://master.json.cpp.al/json/usage/quick_look.html> You can find the source code to be reviewed here: <https://github.com/CPPAlliance/json/tree/master> You can find the latest documentation here: <http://master.json.cpp.al/> Benchmarks are also given in the document which can be found here: <http://master.json.cpp.al/json/benchmarks.html> Some people have also given the early reviews, the thread can be found here: <https://lists.boost.org/Archives/boost/2020/09/249745.php> Please provide in your review information you think is valuable to understand your choice to ACCEPT or REJECT including JSON as a Boost library. Please be explicit about your decision (ACCEPT or REJECT). Some other questions you might want to consider answering: - What is your evaluation of the design? - What is your evaluation of the implementation? - What is your evaluation of the documentation? - What is your evaluation of the potential usefulness of the library? - Did you try to use the library? With which compiler(s)? Did you have any problems? - How much effort did you put into your evaluation? A glance? A quick reading? In-depth study? - Are you knowledgeable about the problem domain? More information about the Boost Formal Review Process can be found here: <http://www.boost.org/community/reviews.html> Thank you for your effort in the Boost community. -- Thank you, Pranam Lashkari, https://lpranam.github.io/

21 73

Adding my sorting algorithm, ska_sort, to boost, attempt 2
by Malte Skarupke 24 Nov '21

24 Nov '21

Hi everyone, I started a discussion about this in October, but at the time the maintainer of the sort library was busy, then I was busy, so now it's January... I wrote a generalized version of radix sort a couple years ago and gave a talk about it here: https://www.youtube.com/watch?v=zqs87a_7zxw I would like to get a new version of that sorting algorithm into boost. It's faster than what I showed several years ago. It's also even more general and has a new interface that should be easier to extend. I uploaded the code here: https://github.com/skarupke/sort/tree/master The documentation is also already updated with new benchmark results. Let me know what's required to get this into boost. Would you like this in the form of a pull request? One of the big things that probably needs review is the interface, since radix sorting works differently than comparison based sorting. For most normal uses you just need to provide a sort key, but more complicated cases can get more complicated. I tried very hard to make everything easy, but I'd also be curious if others can come up with better ways of doing the interface. Thanks, Malte -- Malte Skarupke malteskarupke(a)fastmail.fm

8 10

[FPR] Review of FPR starts Today: Sept 28 - Oct 7
by Benedek Thaler 16 Oct '20

16 Oct '20

The Boost formal review of the FPR (Flat Precise Reflection, ex Magic Get, ex PODs Flat Reflection) starts Today, taking place from September 28, 2020 to October 7, 2020. The library is authored by Antony Polukhin, author of Boost.DLL, Stacktrace, Type Index libraries. Documentation: http://apolukhin.github.io/magic_get/ Source: https://github.com/apolukhin/magic_get The library is meant for accessing structure elements by index and providing other std::tuple like methods for user defined types without any macro or boilerplate code. The FPR documentation summarizes the out-of-the-box added functionality for aggregate initializable structures: - comparison operators - heterogeneous comparators - hash - stream operators - access to members by index - member reflections - methods for cooperation with std::tuple - methods to visit each field of the structure If the description isn't immediately obvious for you, here's a motivating example: // requires: C++14 #include <iostream> #include <string> #include "boost/pfr/precise.hpp" struct some_person { std::string name; unsigned birth_year; }; int main() { some_person val{"Edgar Allan Poe", 1809}; std::cout << boost::pfr::get<0>(val) // No macro! << " was born in " << boost::pfr::get<1>(val); // Works with any aggregate initializables! } Please provide in your review information you think is valuable to understand your choice to ACCEPT or REJECT including FPR as a Boost library. Please be explicit about your decision (ACCEPT or REJECT). Some other questions you might want to consider answering: - What is your evaluation of the design? - What is your evaluation of the implementation? - What is your evaluation of the documentation? - What is your evaluation of the potential usefulness of the library? - Did you try to use the library? With which compiler(s)? Did you have any problems? - How much effort did you put into your evaluation? A glance? A quick reading? In-depth study? - Are you knowledgeable about the problem domain? More information about the Boost Formal Review Process can be found at: http://www.boost.org/community/reviews.html Thank you for your effort in the Boost community. Benedek - review manager of the FPR library

8 12

traits
by Gero Peterhoff 03 Oct '20

03 Oct '20

Hello Peter, I've designed a couple of traits here. Is that right so far so that they can be included in boost? But there are these problems: 1) char8_t is still missing in your is_unsigned 2) my implementations of - is_native; if the type exists natively on the platform - is_vectorisable; if the type can be vectorized on the platform (simd) - is_integer are still incomplete, as I cannot find out whether the corresponding types are available; e.g. on some platforms there is int56_t, but no int8_t (__CHAR_BIT__ > 8), etc. The specializations of is_logic and is_rational should better be done in the libs. If a concept is created, it is stored in boost::mata so that there are no naming conflicts. Similar to math::constants there is also a string::constants; maybe also makes sense. regards Gero

2 3

new type traits
by Gero Peterhoff 03 Oct '20

03 Oct '20

Hello Developers, I would like to retrofit some type-traits in boost, but I have read https://pdimov.github.io/articles/phasing_out_cxx03.html. Now I don't know how to do it best, as the boost-type-traits may be removed. Would the following procedure make sense? We get the std-traits and concepts in a namespace boost::meta, eg file boost/type_traits/meta.hpp: #ifndef BOOST_META_HPP #define BOOST_META_HPP #include <type_traits> #if defined(__cpp_concepts) #include <concepts> #endif namespace boost::meta { template <typename Type> using is_integral = std::is_integral<Type>; template <typename Type> inline constexpr bool is_integral_v = std::is_integral_v<Type>; template <typename Type> using is_pointer = std::is_pointer<Type>; template <typename Type> inline constexpr bool is_pointer_v = std::is_pointer_v<Type>; ... all other #if defined(__cpp_concepts) template <typename Type> concept integral = std::integral<Type>; template <typename Type> concept pointer = is_pointer_v<Type>; ... #endif } // boost::meta #endif // BOOST_META_HPP Then you could possibly map this in boost/type_traits.hpp to boost:: (if that makes sense): #ifndef BOOST_TYPE_TRAITS_HPP #define BOOST_TYPE_TRAITS_HPP #include <boost/type_traits/meta.hpp> remove boost implementations namespace boost { using namespace boost::meta; } // boost #endif // BOOST_TYPE_TRAITS_HPP In this way, new traits can be added in boost/type_traits/meta.hpp that are based on the std-traits, e.g. is_logic namespace boost::meta { template <typename Type> struct is_logic : std::false_type{}; template <typename Type> inline constexpr bool is_logic_v = is_logic<Type>::value; template <> struct is_logic<bool> : std::true_type{}; #if defined(__cpp_concepts) template <typename Type> concept logic = is_logic_v<Type>; #endif } // boost::meta and in this case add in boost/logic/tribool.hpp namespace boost::meta { template <> struct is_logic<boost::tribool> : std::true_type{}; } // boost::meta Or do you have a better idea? regards Gero

6 15

[PFR] The user's perspective
by Andrzej Krzemienski 02 Oct '20

02 Oct '20

Hi Everyone, I am now trying to study the PFR library, and wanted to share some thoughts and see what others think. First, thanks Antony for writing and sharing this library. I have watched your video on it, read the docs, and I find it amazing that you were able to implement such reflection in C++. This is in the spirit of the good old Boost libraries that just implemented magic. Now, to the critique. From looking at the docs and the videos, I inferred (perhaps incorrectly) that the library was created in this order: "We can do type introspection for aggregates, so let's see to what extent we can provide an interface of a reflection library." The extent is quite amazing (e.g., I really appreciate having pfr::less<> out of the box), but to the end user, I think, the library will still appear as incomplete. That is, when my type is an aggregate it will work, but when I need to add a convenience constructor it will immediately break, and I will have to switch to another library, like Peter's Describe ( https://github.com/pdimov/describe/tree/master). With Describe, I will have to type more, but I have a guarantee of a uniform experience both for aggregates and for other types. And given that I have to use Describe at some point there may be no point in also keeping PFR and forcing on myself and my colleagues two different interfaces. Describe is not a perfect solution either, because for aggregates I have to declare the mapping, which is unnecessary as PFR has demonstrated. My ideal solution would be if these two libraries (PFR and Describe) would be merged into one, so that: 1. They provide the same interface 2. A user can easily instruct the library: "this is an aggregate: figure out the mapping yourself". I am sorry if it sounds arrogant: people are devoting their private time to write and share a cool library, and all they hear back is "do more." But I thought it would also be unfair not to give this feedback. I am also not sure if the goals of the two libraries are compatible (e.g., Describe is also interested in giving names of the members) . I would be curious to see what the authors think about it. Regards, &rzej;

5 6

Cache Size
by Matt Borland 01 Oct '20

01 Oct '20

A recurring discussion in Boost.Math has been needing a cross-platform way to query the L1D cache size of a machine. I have most of a solution in a [personal repo](https://github.com/mborland/cache). It did not make sense to us to have this in Boost.Math because it would be useful outside of that scope, but we did not know where it should go. Is there an existing library where this would fit? If necessary I can roll it into a library submission that exposes the functionality of CPUID. Matt

3 3

[review][json] My review
by Gavin Lambert 30 Sep '20

30 Sep '20

- Do you think the library should be accepted as a Boost library? Yes, my vote is to ACCEPT this library. - What is your evaluation of the design? Much has been debated recently on the merits of push parsers vs. pull parsers. Boost.JSON provides both a push parser (SAX-like interface) and a DOM parser (which is somewhat pull-like but I don't think is technically either kind). It does not provide a "real" pull parser, which are sometimes more efficient for deserialisation into custom types; the SAX parser can somewhat do that but is not composable, which makes it harder to use in practice, unless I'm missing something (this is usually why I end up never using SAX parsers). If so, I'd like to see a more complete example where the handler delegates part of the parsing to a class that in turn delegates part to another class (as with reading typed sub-values). I don't think this is currently possible. So I think I can understand some of the debate around this point; while I don't think it's strictly necessary that this particular library implement that, if it doesn't then another library will end up having potentially competing types and the natural Boost.Json name will already be taken. Personally, however, I don't think this is sufficient reason to block acceptance of this library. Direct pull parsing doesn't mesh well with JSON, due to the requirement to tolerate reordered keys, so any non-defective parser would have to have something DOM-like under the hood anyway. (Some kind of cache, if not necessarily a traditional DOM.) As such it should be sufficient to use json::value itself as part of a pull-like parsing interface. Regarding the SAX parser specifically, I dislike the *_part methods in the callback interface. I feel that these should be removed and only the final form retained, called only when the complete text of the value has been determined. I don't feel it is ever sensible to call back with a partially-parsed value (unless I am misunderstanding what these are for, but there is little explanation in the docs, and I wasn't able to get them called at all in my test). I also don't see the point of supplying a size argument to on_key* and on_string, as this can be read from the string_view argument instead. The various number methods don't pass this separately. Similarly, having a bool return as well as an error_code output argument seems peculiar; one or the other should be sufficient, as is it just invites inconsistency. parser.write() is incremental but basic_parser.write() is not, which seems odd. I assume this means that parser is storing an incrementally populated buffer of the full document rather than _really_ incrementally parsing. parse/parser do not appear to support consuming only part of the supplied input as a complete JSON value (returning how much was consumed), which is useful for streams where multiple objects are concatenated without explicit separation. Regarding other aspects of design, I haven't drilled down in great detail but the basic interface seems reasonably sound, other than the concerns raised above. I have mixed feelings on the initializer-list construction method -- I like that there is some method of doing this, and it seems like idiomatic C++ (particularly regarding how key-value pairs appear), but also very non-JSON -- an array of objects ends up having three nested braces. But I don't have any specific suggestion for improvement. - What is your evaluation of the implementation? It seems unfortunate (though understandable, due to heap allocation) that you cannot declare a json::value / json::object as constexpr, for cases where you do want some kind of constant reference object (e.g. a schema description). You can somewhat work around this by declaring the JSON as a constexpr string_view and later parsing it to a non-constexpr json::value, but that seems a bit awkward (and potentially bad-perf-prone if someone parses it multiple times). Otherwise I didn't really look into the implementation at all. - What is your evaluation of the documentation? Overall, good, if perhaps a bit sparse on some aspects. One pet peeve however is that most of the examples appear to be written as if "using namespace boost::json" is in effect, which I feel both encourages bad practice and makes it harder to distinguish which types are provided by the library vs. exist only for the example. This is especially confusing in the examples for tag_invoke, but not only there -- another example of confusion are the aliases for types present in both boost and std namespaces. I strongly recommend going through and changing these to explicitly use a json:: namespace prefix on all library types (including the boost/std aliases). Brevity is useful, but not at the expense of clarity. The "Using Numbers" section of the docs appears to be entirely blank. "serializer can be used to incrementally serialize a value incrementally" (redundant words are redundant) (On a related note, an example use case for serializer is listed as "ensure a fixed amount of work is performed in each cycle", but the only means of control is the length of the provided buffer. I guess this is equating work to number of characters output, which seems dubious. But I have no specific objections.) - What is your evaluation of the potential usefulness of the library? The library seems well suited for JSON as inter-process/network data interchange, other than perhaps the omission of partial input parsing. It seems less suited for JSON as configuration file -- while it can parse such files (via common extensions such as ignoring comments and trailing commas) it lacks means to pretty-print and to round-trip the comments, which would be essential if writing back a config file intended for human use. However while supporting this use case would be nice, I don't consider it mandatory. - Did you try to use the library? With what compiler? Did you have any problems? I tried it out with MSVC 2017 in standalone header-only mode, though only with a few small examples. The basic_parser examples do not compile out of the box -- with the suggested json.hpp and src.hpp includes there are link errors with basic_parser symbols. Additionally including basic_parser.hpp resolves these but starts complaining about missing max_{key,string,array,object}_size members of the handler type, which are not documented. After these are supplied then it works as expected. I don't see why these should be needed, however. - How much effort did you put into your evaluation? A glance? A quick reading? In-depth study? Roughly four hours over a few days reviewing docs and trying some small experiments. - Are you knowledgeable about the problem domain? I have some apps that use JSON as both interchange and configuration storage formats, although most of these do not use C++. So, "somewhat".

9 23

Review Manager needed for Boost.Lambda2
by Peter Dimov 30 Sep '20

30 Sep '20

Greetings, Some time ago I wrote a blog post, https://pdimov.github.io/blog/2020/07/22/a-c14-lambda-library/, which described how a simple lambda library can be implemented in ~50 lines using the facilities already available in C++14's <functional> standard header. I turned this into a mini-library, https://github.com/pdimov/lambda2, and I'd like to submit that to Boost. I'm looking for a review manager. The library is trivial, so managing the review should be as easy as theoretically possible for a Boost review. Thanks in advance.

7 20

new macros
by Gero Peterhoff 28 Sep '20

28 Sep '20

Hello Developer, can you please provide these 2 macros: - BOOST_HAS_LIB_INT128 - BOOST_NO_INT8_T and there is another bug in boost::is_unsigned with char8_t. See https://godbolt.org/z/o8z1aq thx Gero

1 0

[review][JSON] json::value as a vocabulary type
by Andrzej Krzemienski 26 Sep '20

26 Sep '20

Hi Everyone, I have heard this claim a number of times: json::value is suitable for a vocabulary type. I am not sure what that actually means: no templates? Guarantee that layout or mangled symbol will never change? Anything else? My understanding of a "vocabulary type" is that it should be usable (not necessarily with maximum efficiency) for *any* usage. In the case of JSON that would mean that I should be able to represent any value that corresponds to a valid JSON when converted to text. I do not think that json::value can claim that without the ability to serialize arbitrarily big numbers. I understand that the goal of the library is to address the most common cases, and big numbers do not fall into this category. I am just saying that the name "vocabulary type" may not be accurate here. Regards, &rzej;

11 25

Changing virtual memory amount in Appveyor and Travis CI tests
by Edward Diener 25 Sep '20

25 Sep '20

Is it possible through .yml file for Appveyor and Travis CI to change the amount of virtual memory when running a CI test. I am running CI tests for Boost PP which heavily use the preprocessor, and some of the extended tests I am running fail on both Appveyor and Travis CI with out of memory conditions while on my own local computer, with about 32 GB of ram, the tests succeed. I think in the real world most users now have at least 32 GB of ram or more, while these virtual environments in Appveyor and/or Travis CI probably run their tests with much less overall virtual memory than an average user would have.

4 12

Re: [boost] Endorsement, review manager sought for Boost.Describe
by Peter Dimov 24 Sep '20

24 Sep '20

> Vinícius dos Santos Oliveira wrore: > > Hi Peter, > > > > could you consider using "compile-time strings" such as Hana's? I don't > > have much use for a const char* in TMP algorithms. > > The descriptor strings are "compile-time". This, for instance, works. ... Here's how you can get a Hana string: #include <boost/describe.hpp> #include <boost/mp11.hpp> #include <boost/hana.hpp> #include <cstddef> using namespace boost::describe; using namespace boost::mp11; enum E { v1 }; BOOST_DESCRIBE_ENUM(E, v1) constexpr std::size_t strlen_( char const * s ) { std::size_t n = 0; while( *s++ ) ++n; return n; } template<class D, std::size_t... I> constexpr auto to_string_impl( index_sequence<I...> ) { return boost::hana::string_c<D::name[I]...>; } template<class D> constexpr auto to_string() { return to_string_impl<D>( make_index_sequence<strlen_(D::name)>() ); } using D = mp_first< describe_enumerators<E> >; constexpr auto st = to_string<D>(); #include <typeinfo> #include <cstdio> int main() { std::printf( "%s\n", typeid(st).name() ); }

1 0

Endorsement, review manager sought for Boost.Describe
by Peter Dimov 24 Sep '20

24 Sep '20

I would like to submit a C++14 reflection library, Describe, to Boost and I'm looking for endorsements and a review manager. The library is at https://github.com/pdimov/describe and the documentation is at https://pdimov.github.io/describe/doc/html/describe.html. Some examples of what the library enables are given at https://pdimov.github.io/describe/doc/html/describe.html#examples. The purpose of Describe is to establish a standard way of annotating (describing) user-defined types (enums, structs and classes), so that types can be described once, and then their descriptions can be used from other libraries. At the moment, the practice is for each library to invent its own ad-hoc annotation/description mechanism.

7 9

[nowide] cxx11_moveable_fstreams target
by Sean Farrow 24 Sep '20

24 Sep '20

Hi All, By way of context to the following query, I am trying to update the VCPKG boost port to v1.74. I noticed that the nowide library now has a jam file that has the following import statement: import ../../config/checks/config : requires ; Due to the way VCPKG works, I'm copying the config directory to where it is expected and then changing the import statement. But I then get a message that it can't find the cxx11_moveable_fstreams target. Does the nowide build process rely on any other parts of boost config? If not, where is the cxx11_moveable_fstreams defined? I should say that I'm new to the boost build system, so any help is apreciated. Thanks, Sean.

5 9

[review][JSON] The library name...
by Andrzej Krzemienski 24 Sep '20

24 Sep '20

Hi Everyone, Looking at the reviews of Boost.JSON, a number of them fall into a distinctive pattern: reviewers are saying "you did not implement important parts of JSON parsing/serializing", and the authors' reply is "this was not the design goal". My hypothesis is that this is caused by the library name. Simple "Boost.JSON" makes a promise (at least I read it this way) "this is Boost's response to JSON-related problems". And the library does not fulfil that promise. In a sense, the name misguides the potential users who need an answer, sometimes in less than 10 seconds, to the question, "is this library going to address my need?". Maybe the library would encounter a wider consensus if it was called Boost.JSON_Value, or Boost.JSON_DOM. And if the first introductory sentence in the documentation read, "this library provides a type with Regular interface that can represent JSON contents, and provides a convenient way to serialize and then deserialize it fast and possibly in chunks." Alternatively, maybe we can consider the reviewed library as a candidate for a sub-library in a more general module of JSON. Much like Boost.Math aggregates a number of math-related components, we could treat this library as one of a number of components in a more general Boost.JSON_Toolkit library. Regards, &rzej;

1 0

Proposal for adding C++ level to the meta/libraries.json
by Edward Diener 24 Sep '20

24 Sep '20

Since we are reviewing Vinnie Falco's JSON library I thought that this would be a good time to present a proposal to add information to each Boost library's meta/libraries.json file regarding the level of C++ standard compliance for that library. This could then be added to each library's visual documentation so that end-users would instantly know the C++ standard level they would need to use in order to use a Boost library. My proposal is to add 3 fields whose data would be the same as the cxxstd allowed values from Boost Build, using the first value of each choice ( currently 03, 11, 14, 17, 20 ). standard = minimum C++ level for the library extended = same functionality in the library as the minimum C++ level but with extended use given higher C++ levels required = new functionality in the library above the minimum C++ level which requires given higher C++ levels The 'standard' field would be a single value, while the 'extended' or 'required' fields could be more than one comma separated value. If you don't like the names for 'standard', 'extended', or 'required' you can bikeshed the name, although I think the 'standard' name is pretty well apparent. The idea is to provide this information in the meta/libraries.json field for each library, so that the end-user of the library can immediately know the usability of the library with appropriate C++ standard levels of compilation. I realize that the line between the 'extended' and 'required' entries, as I have described them, could be blurred. The 'standard' field remains the most important. I have long felt that the end-user should not have to do any investigation, in code or in documentation, just to determine if a library is usable for his C++ standard level of compilation.

12 27

[review][JSON] Ruthgers' review
by Ruthger Dijt 23 Sep '20

23 Sep '20

> Do you think the library should be accepted as a Boost library? It will be a good addition to Boost if this library gets ACCEPTed > What is your evaluation of the design? It works, is straightforward and the interface feels good to use, the only pitfall is getting the right type you want; number_cast took me a second to realize it existed and the custom string class is something the will most likely be converted alot to std::string in an average users' code. > What is your evaluation of the implementation? As a casual user I cannot comment on this, but as I used it in stand alone / header only mode without problem I feel that i should be alright under the hood > What is your evaluation of the documentation? Could be better, especially in the examples department; it could use how-to basics > What is your evaluation of the potential usefulness of the library? Very useful > Did you try to use the library? With what compiler? Did you have any > problems? I have implemented it in a real project where RapidJSON was used before. No real problems found aside from getting exceptions because .as_double() is not able to get a technically integer from the json (which happens in user configs, example: { "test": 20 }) but that quickly resolved itself with number_cast, Ideally any number should be able to become a double in my opinion. Clang 10.0.1 was used. > How much effort did you put into your evaluation? A glance? A quick > reading? In-depth study? As stated above implemented in one project which took about an hour. > Are you knowledgeable about the problem domain? No, this review is coming from a pure casual user kindly, Ruthger Dijt

2 1

[json][review] JSON review
by Harshada Wighe 23 Sep '20

23 Sep '20

We vote to reject the JSON library from Boost and our review of the library and reason for rejection are below: DOCUMENTATION The documentation is very good. The usage and examples and reference are easy to understand and contain all the information we are looking for. IMPLEMENTATION The organization of source code is very messy: 1. Some files do not include all headers at the very start of the file but have some include statements at the end. For example the json/object.hpp file has 10 include statements at the start of the file before the opening namespace and then 1 include statement at the end of the file after the closing namespace. This is very confusing and not a good practice. 2. Splitting the files into HPP and IPP is also not good because it spreads the class into more files than necessary and causes compilation to be slower. Using the library in a project has a complication: 3. The library is complicated to use in a project because you cannot simply include headers in any file you want. You have to include a src.hpp file but this file must be included only once. Normal header libraries in Boost just let you include the headers without this strange requirement. The library adds a lot of size to your executable: 4. Unlike other JSON libraries which are smaller, this adds several KB to the exe size. This is possibly because of use of templates or because it contains very big lookup tables. The performance is not as fast for all use cases: 5. Compared to our in house JSON library, this library was slightly slower. We have very simple but very large JSON data. We use objects and arrays, but only integer numbers with no fractional part and very large ASCII strings, and no booleans and no nulls. In one of our standalone conversion tools we tried using this library and found it had a 4% longer runtime on a small 170 MB file. The parser allocates too much memory: 6. I think this is because the design is not optimized for the case when all the JSON content is already stored in memory. In our parser we point to the strings in the original buffer. The library duplicate code that is in the C++ compiler libraries: 7. In json/config.hpp there are implementations of move and remove_cv from the C++ standard. This introduces more duplicate of this functionality into programs. Besides these points the implementation is well written. DESIGN The allocator design is not standard: 1. The library has a different allocation system that is not the C++ standard system for allocators. We did not understand why storage_ptr was needed at first. It would be better for the library to just template on allocator just like the vector class in the C++ standard. The allocator system also uses virtual calls. The C++ standard vector class also does not have this problem when it uses the standard allocator system. Other than these points the design is ok. OVERALL We would not use this library because it does not offer anything special for JSON that we need. It also uses some designs that are not standard practice. We use JSON heavily in our historical market quote service and most of our tools deal with JSON files and we use many Boost libraries so we are hoping for a JSON library in Boost that we could use instead of having our own.

3 2

[json][review] Scott Determan review
by Scott Determan 23 Sep '20

23 Sep '20

I recommend ACCEPTING the proposed json library. - What is your evaluation of the design? Design is very good. The parser interfaces and object building interfaces meet my needs. I especially want to call out the pmr support and it's support for either sharing or transferring ownership of resources. It's unfortunate that this required a non-standard string class, but I think supporting shared ownership is worth it. I also like the use of tag_invoke for customization points. Apart from libunifex, this is the first library I've seen that uses this mechanism. I think this is the right way to do customization points. - What is your evaluation of the implementation? I looked at the value, storage_ptr, and object classes. It appears to be a very high quality implementation. However, I did this only as a sanity check, I did not spend much time looking at the implementation. The benchmarking numbers also point to a high quality implementation. - What is your evaluation of the documentation? Documentation is very good. Message for Vinnie: One minor nit caught my eye: My understanding is when implementing a tag_invoke customization point it should be a hidden friend because it improves compile times by keeping overload sets smaller. If that is best practice (and it may not be; I'm not a tag_invoke expert), then the examples in the documentation should follow this. - What is your evaluation of the potential usefulness of the library? It covers a widely useful range of json functionality and I expect this library to be widely used. If accepted I intend on using it immediately. - Did you try to use the library? With which compiler(s)? Did you have any problems? Yes: gcc 10.2 and clang 10.0.1; Linux; No problems. - How much effort did you put into your evaluation? A glance? A quick reading? In-depth study? Read the documentation, browsed the code, wrote some toy programs. Spent about half a day on it. - Are you knowledgeable about the problem domain? As a library consumer, I am familiar with nlohmann_json as well as the custom json library used in my current work project. I am not familiar with the problem domain from a library writer point of view.

2 1

[review][json] Boost.JSON review
by Ruben Perez 23 Sep '20

23 Sep '20

Hi all, My recommendation is to ACCEPT Boost.JSON into Boost. Parsing and serializing JSON using a DOM representation is a common enough task to have a specialized library for it in Boost. Most other languages provide built-in support for this task. I see Boost as the repository where I look at when the standard doesn't provide me something it should, so having a DOM JSON library in Boost is a must for me. - What is your evaluation of the design? Generally sound. I especially value its simplicity. Concretely: 1. The memory management model is extremely simple. I wonder if storage_ptr could be moved somewhere else long term so other libraries can use it. 2. Using concrete types for numbers (uint64_t/int64_t/double) may not fit everyone's needs but will definitely fit most and makes things easy. I miss some way of accessing json::value from generic code, but I understand visitation is currently in progress. As a user I would also be satisfied with generic versions of get_xxx, is_xxx and so on: ```cpp json::value val = /* ... */ val.get<json::object>() // or json::get<json::object>(val) ``` I also miss some way of determining the location (line and column) of parse errors. I don't know how this feature would interact with performance though. Nice to have but not required for me. I would have also liked `json::kind` be streamable, as it makes logging/debugging easier in some contexts. Nothing I can't live without, though. Finally, I would also appreciate `json::string` have a straightforward way to be converted to `std::string` (e.g. by having a `to_std_string()` member function). - What is your evaluation of the implementation? I have just looked at the interface. - What is your evaluation of the documentation? The documentation is very good and detailed, nice work. I would say the main point of improvement would be `basic_parser`, as I had a hard time understanding when some of the callbacks get called, especially the `on_xxx_part` ones. It would be also good to know if accessing the `basic_parser` state (e.g. `depth()`) is allowed from within the handler. And if it is, maybe passing the parser instance at the beginning of the parse could be useful (e.g. in the `on_document_begin`, or in a separate hook). Ideally I would like to see an example of `basic_parser` used to parse a custom struct, if it's not excessively complex. Also note that `basic_parser` docs say that it's defined in `<boost/json/detail/basic_parser.hpp>` and that the convenience header is `<boost/json.hpp>`. Instead, it would be good to note that the user should include `<boost/json/basic_parser.hpp>` and that `<boost/json.hpp>` is not enough (I understand for build speed reasons). I've noted that streaming a `json::string` outputs the string within double quotes. It surprised me at first, as I was working with the 'json::string equals std::string' mentality. I guess this behavior makes sense, but I would make a note in the 'Using strings' section. 'See also' section for https://master.json.cpp.al/json/ref/boost__json__value_from_tag.html renders functions without separation, looks strange. I would make a note in the Value conversion mechanism referencing P1895 on `tag_invoke` so users who don't know this paper don't stare at the name wondering 'why?' As a final note, googling 'Boost json' renders this link to an old version of the docs: http://vinniefalco.github.io/doc/json/index.html Consider removing it so users don't get confused (I did at the very beginning). - What is your evaluation of the potential usefulness of the library? I think it will be incredibly useful. Parsing to DOM and serializing from DOM are very widespread tasks, and having a simple, well designed `json::value` container makes things much better. I would have used it for my use cases if it had been available. - Did you try to use the library? With which compiler(s)? Did you have any problems? I used the library in the Boost version and separate compilation model. I built and installed the library using CMake 3.16.3 and g++ 9.3.0 on Ubuntu 20.04, with no problems. I then built several toy examples with the library's CMake `find_package` interface. No problems. - How much effort did you put into your evaluation? A glance? A quick reading? In-depth study? I spent around 10h reading the documentation and building examples. - Are you knowledgeable about the problem domain? I have used JSON as a data exchange format in the embedded, financial and web worlds, in C++ and other languages (JavaScript, Python and PHP). In C++ I have mainly used rapidJSON, and I would replace it with Boost.JSON for future developments. I have no experience writing JSON libraries myself. Thanks, Ruben.

3 3

Re: [boost] [review][json] My review
by Gavin Lambert 23 Sep '20

23 Sep '20

At 00:22 24/09/2020, Vinnie Falco wrote: >On Wed, Sep 23, 2020 at 1:40 AM Gavin Lambert wrote: >> I've walked back on that one a little bit; I now think that it's >ok for >> basic_parser to do that (to retain a zero-allocation guarantee) >but in >> that case it should treat numbers the same way (which it >currently >> doesn't), and ideally there should be a standard >slightly-higher-level >> parser that has a similar interface but does preassemble the >values, >> eliminating the _part callbacks (for people who prefer ease of >use over >> raw performance). > >I had that originally, it was called number_parser, it was a >public >interface, and it was one of the first things to go during our >3-month >journey of optimization. You can fish it out of the commit log if >you >care to see it. I didn't fish out the code, but given the class name, that sounds like the complete opposite of what I was suggesting. To restate again, my suggestion is: 1. Remove on_int64/uint64/double from basic_parser's handler type. 2. Add on_number(string_view, size_t) to basic_parser's handler type -- having exactly the same semantics as on_key/string and their _part companions. 3. Add custom_parser, which wraps a basic_parser but has internal (dynamically allocated if needed) storage for partial keys/strings/numbers so it never calls _part methods on its own handler type. It still uses on_number(string_view) but note that this (and on_key/string) have no reason to pass a size_t any more, because it can never be any different from the size() of the string_view. 4. The int64/uint64/double parsing code that used to be in basic_parser should be moved to a dedicated helper class, in turn used by parser and *optionally* used by the user's handler implementation for basic_parser/custom_parser. This design has the proper separation of concerns between the parser layers (not dictating a numeric storage format, and keeping number parsing separate from JSON structural parsing). It should not negatively impact performance of parser, and should positively affect performance of basic/custom_parser consumers who didn't want the default conversion anyway.

2 1

[review][JSON] RJanson's review
by Janson R. 22 Sep '20

22 Sep '20

This is a review from a library user standpoint. Thanks to Vinnie, Krystian, and the other contributors for their work. > Do you think the library should be accepted as a Boost library? I recommend ACCEPTING this library into Boost. > - What is your evaluation of the design? The design takes some time to get used to, but it fits well to the problem being tackled (a JSON-DOM library). Switching my codebases using RapidJSON to this library made the code more readable and it will also allow me to get rid of a significant amount of boilerplate. > - What is your evaluation of the implementation? Looks solid. Boost-quality I find. > - What is your evaluation of the documentation? Solid. A month ago I still had to read the source code to find some details, but now all I need for my use-cases is in the docs, well explained. > - What is your evaluation of the potential usefulness of the library? Very useful; to me it takes the same place as Nlohmann.JSON and RapidJSON, both very popular and widely used libraries, but brings better performance and a better API. Regardless of the outcome of this review, I will use this library for my future JSON-DOM needs in C++. > - Did you try to use the library? With which compiler(s)? All in standalone mode on Debian: GCC 9, 10 Clang 9, 10, 11 [trunk of 03 Jul 2020] > - How much effort did you put into your evaluation? Converted two of my codebases (which have different use-cases for a JSON-DOM), read through the implementation, read the docs at multiple stages of its maturation over the last couple months. Amounts to about 40h. > - Are you knowledgeable about the problem domain? I do not have much experience designing nor writing libraries, however I do use a significant number of them, both Boost and non-Boost. JSON is my primary format for configuration files and web communication; In the past I have used Nlohmann.JSON and then primarily RapidJSON for its speed, despite its (in my eyes) terribly user-unfriendly interface. I have also used JSON a lot in other languages (TypeScript, PureScript, Java). -- RJanson

2 1

[JSON[review] Andrzej's review
by Andrzej Krzemienski 22 Sep '20

22 Sep '20

Hi Everyone, I recommend to *ACCEPT* the library into Boost. It meets the standard for BI am definitely going to use it. I tried to use the library in two configurations in header-only mode: g++ 9.2.0 with -std=c++2a on MinGW on Windows, g++ 10.2.1 on Fedora with -DBOOST_JSON_STANDALONE and -std=c++20 All worked fine. I studied library docs and played with examples for about 30 hours. I am not particularly knowledgeable about the problem domain. But my programs have to consume and produce JSON files. DOCUMENTATION It is very good, and meets the highest Boost standards. I mean both the tutorial and reference sections. While doing this review I had to look at the documentation of the competing libraries, and they are really bad. This is why I can appreciate the big effort you put in making these docs. There is a section "Comparison" that compares Boost.JSON to other JSON libraries. I personally think it should also mention the documentation. Some observations: 1. Add reference to RFC 7159 (https://www.rfc-editor.org/info/rfc7159). It allows implementations to set limits on the range and precision of numbers accepted. 2. The documentation for array object and index mention "Satisfies the requirements of ContiguousContainer, ReversibleContainer, and SequenceContainer" These requirements are never defined or referenced. The user will not even know if you defined them or if they are "commonly known". Maybe add link to cppreference.com: https://en.cppreference.com/w/cpp/named_req/ReversibleContainer https://en.cppreference.com/w/cpp/named_req/ContiguousContainer https://en.cppreference.com/w/cpp/named_req/SequenceContainer 3. String has two sections "Member Functions": https://master.json.cpp.al/json/ref/boost__json__string.html 4. Documentation for value::operator= seems corrupt: https://master.json.cpp.al/json/ref/boost__json__value/operator_eq_/overloa… * it has sections with no content * It is an unconstrained template, it look like it can accept any type 5. Examples of input JSON-s contain a lot of escape characters in string literals, like in https://master.json.cpp.al/json/usage/conversion.html This makes it difficult to read. Consider using raw string literals. Instead of assert( serialize( jv ) == "{\"x\":4,\"y\":1,\"z\":4}" ); We would have assert( serialize( jv ) == R"({"x":4,"y":1,"z":4})" ); 6. Some functions (like operator== or swap(x, y)) are naturally part of class interface, even though they are not member functions. It is annoying and confusing that rather than being listed along with the class they belong to they are instead listed separately as "free functions" The docs are not uniform about this issue. For `json::value` operator== is listed as friends along with other member functions, but not 2-argument swap(). 7. In https://master.json.cpp.al/json/usage/conversion.html we read: " Given the following definition of customer::customer( const value& ) [...] Objects of type customer can be converted *to* and from value". This "to" is surprising here. How can a constructor converting from `value` to `customer` could be used to convert `customer` to `value`? 8. As discussed in another thread, documentation would benefit from the info on implementation-limits-related design choices. a. Any json::value that you can build can be serialized and then deserialized, and you are guaranteed that the resulting json::value will be equal to the original. b. JSON inputs where number values cannot be represented losslessly in uint64_t, int64_t and double, may render different values when parsed and then serialized back, and for extremely big number values can even fail to parse. c. Whatever JSON output you can produce with this library, we guarantee it can be passed by any common JSON implementation (probably also based on uint64_t+int64_t+double implementation. DESIGN Clear, sound and practical. The design decisions correspond with my expectations of a library: fast, easy to use and learn, with value semantics. The interface is very intuitive, I practically do not have to consult the documentation: every functionality (serialization, value alteration) has the interface that I would expect. I appreciate that it targets embedded environments. Some observations: 1. The handling of infinities and NaN's needs to be addressed. Currently, I can do: `json::serialize(std::numeric_limits<double>::infinity())` and t produces an invalid JSON. You cannot easily make a precondition on json::value assignment/construction because you expose the double as a mutable member: void fun(double x) // precondition x is not infinity or nan { json::value v = x; // ok v.as_double() *= 2.0; // this may produce infinity } So maybe you need a precondition in the serializer. 2. Boost.JSON provides its own string type. This begs a lot of design questions for `json::string`. Is it a better replacement for std::string? std::string provides the following capability: ``` void set(std::string& s, char v, char x, char z, char k) { if (cond) s = {v, k}; else s = {v, x, z, k}; } ``` json::string does not. How do I do a similar thing with json::string? 3. string::swap() has a strange precondition: you cannot swap an object with itself https://master.json.cpp.al/json/ref/boost__json__string/swap.html This is a really unexpected and potentially dangerous, and at minimum requires a very strong rationale. This would be the first swap function in std or Boost that has a precondition. While discussing a somewhat related issue (on the guarantees of the moved-from state) in the LEWG, someone remarked that there was at least one STL implementation that did a self-swap for convenience of implementation. Is it really necessary? IMPLEMENTATION I didn't look at it much. Just some quick points I observed. 1. Values of type `double` representing Infinity and NaN can be stored in json::value and when later serialized, they render a malformed JSON output. json::value should either validate special values of `double` or indicate as precondition that they should not be assigned. Alternatively, the serializer should either validate this or indicate as precondition. 2. tag_invoke() takes tag arguments by reference, does it have to? Passing by reference requires the constexpr variables to be instantiated and their address assigned. 3. Customization through ADL-discovered overloads can cause ODR violations. There is no superior alternative though. But maybe put a warning in the docs that the user must make sure that all translation units must see the same set of overloads. 4. I do not like the 2-state-switch mechanics of BOOST_JSON_STANDALONE. It assumes that a user either wants a no-Boost version or that she wants a package: all Boost components. But what if I am using C++14 and I want to use std::error_code and Boost-emulated memoty_resource and string_view? What If I use Boost version and C++17 and want to use std::string_view? Maybe you can additionally provide macros for turning Boost-emulation libraries one-by-one? I mean, one for string_view, one for error_code, and one for memory_resource. 5. The header only mode -- I really appreciate it. It is good for initial experiments. Finally, I would like to thank Vinnie and Krystian for writing and sharing this library. Regards, &rzej;

3 4