////
Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com)
Copyright (c) 2025 Dmitry Arkhipov (grisumbras@yandex.ru)

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
////

[#comparison,pagelevels=1,toclevels=1]
= Comparison to Other Libraries

:icon_good: pass:q[[.green]##&#10004##]
:icon_bad:  pass:q[[.red]##&#10008##]

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

== Comparison to nlohmann JSON

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

[source]
----
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.

* {icon_bad} `basic_json` is a class template. Libraries must agree on the
  choices of template parameters to be interoperable.

* {icon_bad} Too much customization. We struggle to see a use case for making
  `BooleanType` anything other than `bool`.

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

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

* {icon_bad} No incremental parsing, no incremental serialization.

* {icon_bad} Slow parsing and serialization performance.

* {icon_good} Full-featured, including JSON Pointer, CBOR, and others.

== Comparison to RapidJSON

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

[source]
----
template <typename Encoding, typename Allocator = MemoryPoolAllocator<> >
class GenericValue;

template <bool Const, typename ValueT>
class GenericArray;

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

* {icon_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.

* {icon_bad} Object types have no hash table or index to reduce the cost of
  lookups.

* {icon_bad} Allocators have reference semantics. Problems with lifetime are
  easily encountered.

* {icon_bad} The interface of the array and object types are considerably
  different from their standard library equivalents, and not idiomatic.

* {icon_bad} No incremental parsing, no incremental serialization.

* {icon_good} Parsing and serialization performance is better than most other
  libraries.

=== Comparison to SIMD JSON

[source]
----
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.

* {icon_bad} Sequential access only, via `ParsedJson::BasicIterator`

* {icon_bad} Read-only, can only be populated by the provided SIMD JSON parser.

* {icon_good} The fastest available JSON parser.
