[/
    Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com)

    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:comparison Comparison to Other Libraries]
[block'''<?dbhtml stop-chunking?>''']

There exist many C++ JSON libraries, but two are particularly noteworthy
for the purpose of comparison:
[@https://rapidjson.org/ RapidJSON]
and
[@https://nlohmann.github.io/json/ JSON for Modern C++]
(referred to herein as nlohmann's JSON, or nlohmann).

[/-----------------------------------------------------------------------------]

[heading Comparison to nlohmann JSON]

* Value Type: [@https://github.com/nlohmann/json/blob/00cb98a3d170161711ab912ae6acefba31f29f75/include/nlohmann/json.hpp#L165 `nlohmann::basic_json`]

```
template<
    template<typename, typename, typename...> class ObjectType,
    template<typename, typename...> class ArrayType,
    class StringType,
    class BooleanType,
    class NumberIntegerType,
    class NumberUnsignedType,
    class NumberFloatType,
    template<typename> class AllocatorType,
    template<typename, typename = void> class JSONSerializer
    >
class basic_json
{
  private:
    ....
    friend ::nlohmann::detail::parser<basic_json>;
    friend ::nlohmann::detail::serializer<basic_json>;
...

```

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.

* __bad__ `basic_json` is a class template. Libraries must agree on
  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`.

* __bad__ Poor separation of concerns. The `basic_json` container
  declaration needlessly conflates parsing and serialization APIs.

* __bad__ Limited allocator support. Only stateless allocators are
  allowed, which rules out the most important type of allocator, a
  local arena-based implementation.

* __bad__ No incremental parsing, no incremental serialization.

* __bad__ Slow parsing and serialization performance.

* __good__ Full-featured, including JSON Pointer, CBOR, and others.

[/-----------------------------------------------------------------------------]

[heading Comparison to RapidJSON]

* Value Type: [@https://github.com/Tencent/rapidjson/blob/bb5f966b9939d6cdfbac3462a0410e185099b3af/include/rapidjson/document.h#L608 `rapidjson::GenericValue`]

```
template <typename Encoding, typename Allocator = MemoryPoolAllocator<> >
class GenericValue;

template <bool Const, typename ValueT>
class GenericArray;

template <bool Const, typename ValueT>
class GenericObject;
```

* __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.

* __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 and serialization performance is better than most other libraries.

[/-----------------------------------------------------------------------------]

[heading Comparison to SIMD JSON]

[@https://github.com/lemire/simdjson https://github.com/lemire/simdjson]

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

* __bad__ Sequential access only, via `ParsedJson::BasicIterator`

* __bad__ Read-only, can only be populated by the provided SIMD JSON parser.

* __good__ The fastest available JSON parser.

[/-----------------------------------------------------------------------------]

[endsect]