diff --git a/doc/qbk/comparison.qbk b/doc/qbk/comparison.qbk index 5ed80b5b..71ef1af2 100644 --- a/doc/qbk/comparison.qbk +++ b/doc/qbk/comparison.qbk @@ -10,14 +10,6 @@ [section:comparison Comparison to Other Libraries] [block''''''] -We use these criteria for evaluating a library's JSON container (the -"value type") for suitability as a vocabulary type: - -* The value type declaration is completely decoupled - from other facilities such as parsing and serialization. - -* The value type is not a class template - [/-----------------------------------------------------------------------------] [heading Comparison to nlohmann JSON] @@ -46,8 +38,16 @@ class basic_json ``` +This library adopts a "kitchen sink" approach. It contains a great many +features, even those which have 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. + * __bad__ `basic_json` is a class template. Libraries must agree on - all the template parameters to be fully interoperable. + the choices of template parameters to be interoperable. * __bad__ Too much customization. We struggle to see a use case for making `BooleanType` anything other than `bool`. @@ -61,7 +61,7 @@ class basic_json * __bad__ No incremental parsing, no incremental serialization. -* __bad__ Mediocre parsing performance. +* __bad__ Slow parsing and serialization performance. * __good__ Full-featured, including JSON Pointer, CBOR, and others. @@ -82,84 +82,20 @@ template class GenericObject; ``` -* __bad__ The value type is a class template. +* __bad__ The value type is not regular. -* __bad__ The value type is not __CopyConstructible__ +* __bad__ Object types have no hash table or index to reduce + the cost of lookups. + +* __bad__ Allocators have reference semantics. Problems with + lifetime are easily encountered. * __bad__ The interface of the array and object types are considerably different from their standard library equivalents, and not idiomatic. * __bad__ No incremental parsing, no incremental serialization. -* __good__ Parsing performance is excellent. - -[/-----------------------------------------------------------------------------] - -[heading Comparison to TaoCPP JSON] - -* Value Type: [@https://github.com/taocpp/json/blob/e0944b3b2686a6b9749c16dd06f72445bf7eef0a/include/tao/json/basic_value.hpp#L38 `tao::json::basic_value`] - -*https://github.com/taocpp/json - -``` -template< template< typename... > class Traits > -class basic_value -{ - ... -public: - using array_t = std::vector< basic_value >; - using object_t = std::map< std::string, basic_value, std::less<> >; -... -``` - -The `basic_value` type uses the `Traits` as a template parameter, where the -traits provide specializations to convert each supported native or user defined -type to and from JSON. This makes the value type unsuitable as a vocabulary -type because the traits for a `basic_value` exported by two different -libraries which each has added support for their own types, are not the same. - -* __bad__ C++17 or later is required. - -* __bad__ No allocator support. - -* __bad__ The value type is a class template. - -* __bad__ The array and object container interfaces change - depending on which version of the standard C++ library is used. - -* __bad__ The performance of the library changes significantly - depending on which version of the standard library is used. - -* __bad__ Parsing performance is the worst surveyed, by a large margin. - -* __bad__ No incremental parsing, no incremental serialization. - -[/-----------------------------------------------------------------------------] - -[heading Comparison to JSONCPP] - -* Value Type: [@https://github.com/open-source-parsers/jsoncpp/blob/41ffff01d39085222280791a23451d3e852b06c2/include/json/value.h#L188 `Json::Value`] - -[/-----------------------------------------------------------------------------] - -[heading Comparison to Ciere Labs json_spirit] - -* Value Type: [@https://github.com/cierelabs/json_spirit/blob/e885dc55054bf0e6ef250322923396aed4c3ece7/ciere/json/value.hpp#L72 `ciere::json::value`] - - -``` - typedef std::string string_t; - typedef std::map object_t; - typedef std::pair object_member_t; - typedef boost::container::stable_vector array_t; - - class value : public boost::spirit::extended_variant< - null_t, bool_t, string_t, int_t, double_t, object_t, array_t> - { ... }; - -``` - -* No allocator support. +* __good__ Parsing and serialization performance is best-in-class. [/-----------------------------------------------------------------------------] @@ -176,38 +112,11 @@ 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. -* Read-only -* Sequential access only, via `ParsedJson::BasicIterator` -* Can only be realistically populated by the provided SIMD JSON parser. +* __bad__ Sequential access only, via `ParsedJson::BasicIterator` -[/-----------------------------------------------------------------------------] +* __bad__ Read-only, can only be populated by the provided SIMD JSON parser. -[heading Comparison to trial.protocol] - -https://github.com/breese/trial.protocol - -``` -template