RubyGems - couchbase - Versions diffs - 3.0.0.alpha.4-x86_64-linux → 3.5.0-x86_64-linux - Mend

couchbase 3.0.0.alpha.4-x86_64-linux → 3.5.0-x86_64-linux

Files changed (2212) hide show

data/ext/third_party/json/doc/Binding-Traits.md DELETED Viewed

@@ -1,319 +0,0 @@
-# Binding Traits
-The Binding Traits facilities are used to "bind" existing [Type Traits](Type-Traits.md) together to create [Type Traits](Type-Traits.md) for new types or with new features.
-They thereby offer rather convenient ways of automatically creating Traits functions for many common use cases.
-* [Types as Arrays](#types-as-arrays)
-* [Types as Objects](#types-as-objects)
-* [Polymorphic Factory](#polymorphic-factory)
-* [Multiple Versions](#multiple-versions)
-## Types as Arrays
-The class template `binding::array` can be used to easily create Traits for types that are to be represented by Arrays.
-It takes arbitrary many template arguments that are usually created by invoking the macro `TAO_JSON_BIND_ELEMENT` with a member object pointer, i.e. a pointer to a member object of the type for which the Traits are to be created.
-For example consider the following hypothetical `my_traits` specialisation for `std::pair`, similar to the Traits defined in `tao/json/contrib/pair_traits.hpp`.
-```c++
-#include <utility>
-#include <tao/json.hpp>
-template< typename T >
-struct my_traits;
-template< typename U, typename V >
-struct my_traits< std::pair< U, V > >
-   : public tao::json::binding::array< TAO_JSON_BIND_ELEMENT( &std::pair< U, V >::first ),
-                                       TAO_JSON_BIND_ELEMENT( &std::pair< U, V >::second ) >
-{
-};
-```
-Note that variadic macros are used to correctly pass the member pointer even though the type `std::pair< U, V >` contains a comma.
-The `assign()` and `produce()` functions of these Traits for `std::pair` will always create Arrays with two elements, and conversely the `to()` and `consume()` functions will expect Arrays with two elements.
-Handling of the two member objects `first` and `second` is delegated to the Traits' specialisations for their respective types.
-The order in the serialisation will always correspond to the order of the template parameter to `binding::array` (which need not coincide with the order in the `class` or `struct`).
-### Constants
-It is also possible to add constant elements that are purely defined in the Traits.
-These constants are currently limited to boolean values, signed and unsigned integers, and strings.
-When generating an encoding, the constants behave "as if" there was a binding to a variable of the corresponding type with the predefined value.
-When parsing an encoding, the constants verify that the value read from the input is equal to their predefined value.
-Constants are added to an Array binding with the macros `TAO_JSON_BIND_ELEMENT_BOOL()`, `TAO_JSON_BIND_ELEMENT_SIGNED()`, `TAO_JSON_BIND_ELEMENT_UNSIGNED()` and `TAO_JSON_BIND_ELEMENT_STRING()`.
-```c++
-template< typename U, typename V >
-struct my_traits< std::pair< U, V > >
-   : public tao::json::binding::array< TAO_JSON_BIND_ELEMENT( &std::pair< U, V >::first ),
-                                       TAO_JSON_BIND_ELEMENT( &std::pair< U, V >::second ),
-                                       TAO_JSON_BIND_ELEMENT_UNSIGNED( 42 ), >
-                                       TAO_JSON_BIND_ELEMENT_STRING( "hallo" ) >
-{
-};
-const auto p = std::pair( 1, 2 );
-const tao::json::basic_value< my_traits > v = p;
-// v is [ 1, 2, 42, "hallo" ]
-```
-### Inheritance
-When a derived class' Array-based binding is supposed to extend the base class' binding it is possible to indicate the base class to an Array binding in order to not repeat the bindings for the inherited member objects.
-For example consider the following class that extends a pair to a triple (instead of using a `std::tuple`).
-```c++
-template< typename U, typename V, typename W >
-struct triple
-   : std::pair< U, V >
-{
-   W third;
-};
-```
-The corresponding specialisation of the hypothetical `my_traits` can then be implemented as follows.
-```c++
-template< typename U, typename V, typename W >
-struct my_traits< triple< U, V, W > >
-   : public tao::json::binding::array< tao::json::binding::inherits< my_traits< std::pair< U, V > > >,
-                                       TAO_JSON_BIND_ELEMENT( &triple< U, V, W >::third ) >
-{
-};
-```
-Note that while the example shows what is probably the most common use case with the `binding::inherits` as first template argumen to `binding::array`, it can be used anywhere, i.e. before, in the middle of, or after any occurrences of `TAO_JSON_BIND_ELEMENT`.
-### Indirect
-TODO: `element` with getter, and `element2` with getter and setter.
-## Types as Objects
-The class template `binding::object` can be used to easily create Traits for types that are to be represented by Objects.
-Compared to the Array binding explained above the Object binding has the advantages of being more expressive and flexible, and the disadvantage of being less efficient, both in terms of time and space.
-Here is an alternative implementation of Type Traits for `std::pair`, this time using `binding::object`, wherefore the `std::pair` will encode from and to Objects with two members, one called `first` and one called `second`.
-```c++
-template< typename U, typename V >
-struct my_traits< std::pair< U, V > >
-   : public tao::json::binding::object< TAO_JSON_BIND_REQUIRED( "first", &std::pair< U, V >::first ),
-                                        TAO_JSON_BIND_REQUIRED( "second", &std::pair< U, V >::second ) >
-{
-};
-```
-### Optional Members
-Unlike with `binding::array`, it is possible to make individual members optional by using the macro `TAO_JSON_BIND_OPTIONAL` instead of `TAO_JSON_BIND_REQUIRED`.
-This works particularly well when the bound member is a `std::optional< T >`, but it can also be used when the previous or default-constructed value of the member is acceptable in the absence of said member from the input.
-### Default Keys
-The following alternative forms of the binding macros use the [default key](Type-Traits.md#default-key-for-objects) instead of a string supplied to the macro.
-```c++
-TAO_JSON_BIND_REQUIRED1( &type::member1 );
-TAO_JSON_BIND_OPTIONAL1( &type::member2 );
-```
-Of course the macros with key as first argument can also be used for members whose type defines a default key.
-This is even necessary to prevent collisions when there are two occurrences of the same member type.
-### Constants
-Constants works for Objects just like for Arrays, though of course a string with the key needs to be supplied in addition to the constant value.
-Constants are added to an Object binding with the macros `TAO_JSON_BIND_REQUIRED_BOOL()`, `TAO_JSON_BIND_REQUIRED_SIGNED()`, `TAO_JSON_BIND_REQUIRED_UNSIGNED()` and `TAO_JSON_BIND_REQUIRED_STRING()`.
-There are again variants with `optional` in place of `required` that are always encoded, but are not flagged as error when missing.
-```c++
-template< typename U, typename V >
-struct my_traits< std::pair< U, V > >
-   : public tao::json::binding::object< TAO_JSON_BIND_REQUIRED( "first", &std::pair< U, V >::first ),
-                                        TAO_JSON_BIND_REQUIRED( "second", &std::pair< U, V >::second ),
-                                        TAO_JSON_BIND_REQUIRED_SIGNED( "foo", -5 ) >
-{
-};
-```
-### Inheritance
-Inheritance works for Objects just like for Arrays, though "mixing and matching" is not supported:
-Array bindings can "inherit" a base class' Array bindings, and Object bindings can "inherit" a base class' Object bindings.
-### Unknown Keys
-By default, the Object traits' `to()` and `consume()` functions will throw an exception when they encounter an unknown Object key while converting a Value, or parsing some input, respectively.
-This can be changed by using `tao::json::binding::basic_object` instead of `tao::json::binding::object`, and passing `tao::json::binding::for_unknown_key::skip` as template parameter in the appropriate place (instead of `tao::json::binding::for_unknown_key::fail`).
-With this change, unknown keys will be ignored.
-### Nothing Values
-By default, the Object traits' `assign()` and `produce()` functions will encode all variables that it knows about, including those that might be considered "nothing".
-This can be changed by again using `tao::json::binding::basic_object` instead of `tao::json::binding::object`, and passing `tao::json::binding::for_nothing_value::suppress` as template parameter in the appropriate place (instead of `tao::json::binding::for_nothing_value::ENCODE`).
-To determine whether something is to be considered "nothing", the Traits' optional `is_nothing()` function is used.
-```c++
-template<>
-class my_traits< some_type >
-{
-   template< template< typename... > class Traits >
-   static bool is_nothing( const some_type& c ) noexcept
-   {
-      return whether c is to be considered "nothing";
-   }
-};
-```
-If the Traits specialisation for the bound member variable does not implement an `is_nothing()` function then the assumption is that there is something (to encode).
-## Polymorphic Factory
-The class template `binding::factory` combines Traits for a set of derived classes to form Traits for a common base class.
-The `assign()` and `produce()` methods use RTTI to determine the dynamic type of the pointee and delegate to the approriate derived class' Traits.
-The `as()` and `consume()` methods expect an encoding as Object with a single member whose key must correspond to one of the types registered with the factory.
-Factory Traits must be used as specialisations for a pointer class like `std::shared_ptr` or `std::unique_ptr`.
-```c++
-struct base
-{
-   base( const base& ) = delete;
-   void operator=( const base& ) = delete;
-   virtual void foo() = 0;  // Need one virtual function for RTTI, and for a base class to really make sense.
-protected:
-   base() = default;
-   ~base() = default;  // Has to be public and virtual when using std::unique_ptr instead of std::shared_ptr.
-};
-struct fobble
-   : public base
-{
-   // Constructors etc.
-private:
-   void foo() override
-   {
-   }
-};
-struct fraggle
-   : public base
-{
-   // Constructors etc.
-private:
-   void foo() override
-   {
-   }
-};
-```
-Assuming that there are appropriate specialisations of `my_traits` for the classes `fobble` and `fraggle`, i.e. that they implement all functions that are required by the application, and assuming suitable Traits for `std::shared_ptr`, the actual Factory Traits are implemented as follows.
-Note that when using the Traits for `std::shared_ptr` and `std::unique_ptr` from `tao/json/contrib/shared_ptr_traits.hpp` and `tao/json/contrib/unique_ptr_traits.hpp`, possibly via `tao/json/contrib/traits.hpp`, then the Traits for a derived clas need not implement an `as()` or `to()` function when said derived class has a constructor that can create an instance from a Value.
-```c++
-template<>
-struct my_traits< std::shared_ptr< base > >
-   : public tao::json::binding::factory< TAO_JSON_FACTORY_BIND( "fobble", fobble ),
-                                         TAO_JSON_FACTORY_BIND( "fraggle", fraggle ) >
-{
-};
-```
-### Default Keys
-For types with a default key, the macro `TAO_JSON_FACTORY_BIND1` can be used instead of `TAO_JSON_FACTORY_BIND`.
-Like for Object bindings, it removes the key as argument and uses the default key instead.
-## Multiple Versions
-The class template `binding::versions` can be used when there are multiple encodings for the same type.
-A typical use case is when an old legacy encoding needs to be supported for compatibility, while a new preferred encoding already exists.
-With `binding::versions`, arbitrary many different traits can be supported simultaneously with the following behaviour:
-* For `as()` and `consume()`, all given Traits are tried, in order, until one succeeds (i.e. doesn't throw an exception).
-* All other Traits functions are taken from the **first** Traits supplied to `binding::versions`.
-Here is another Traits specialisation for `std::pair`, this time it combines both the Array-based and the Object-based version.
-Since the Object-based Traits are given first, the encodings created by `assign()` and `produce()` will be Objects.
-In the other direction both Arrays and Objects will be accepted (with Objects being attempted first).
-```c++
-template< typename U, typename V >
-using pair_array_traits = tao::json::binding::array< TAO_JSON_BIND_ELEMENT( &std::pair< U, V >::first ),
-                                                     TAO_JSON_BIND_ELEMENT( &std::pair< U, V >::second ) >;
-template< typename U, typename V >
-using pair_object_traits = tao::json::binding::object< TAO_JSON_BIND_REQUIRED( "first", &std::pair< U, V >::first ),
-                                                       TAO_JSON_BIND_REQUIRED( "second", &std::pair< U, V >::second ) >;
-template< typename U, typename V >
-struct my_traits< std::pair< U, V > >
-   : public tao::json::binding::versions< pair_object_traits,
-                                          pair_array_traits >
-{
-};
-```
-Note that `binding::versions` is a context in which using constants in Arrays or Objects can be useful in order to distinguish between different encodings without changing the definition of the type being represented.
-```c++
-struct person
-{
-   std::string name;
-   std::string number;
-};
-template<>
-struct old_person_traits
-   : public tao::json::binding::object< TAO_JSON_BIND_REQUIRED( "name", &person::name ),
-                                        TAO_JSON_BIND_OPTIONAL( "number", &person::number ) >
-{
-};
-template<>
-struct new_person_traits
-   : public tao::json::binding::object< TAO_JSON_BIND_REQUIRED_UNSIGNED( "version", 2 ),
-                                        TAO_JSON_BIND_REQUIRED( "name", &person::name ),
-                                        TAO_JSON_BIND_REQUIRED( "number", &person::number ) >
-{
-};
-template<>
-struct my_traits< person >
-   : public tao::json::binding::versions< new_person_traits,
-                                          old_person_traits >
-{
-};
-```
-Note that `binding::versions` uses the traits' `to()` method to fill-in an existing or default-constructed object, and that it does *not* clear or reset the target object between attempts!
-Copyright (c) 2018-2020 Dr. Colin Hirsch and Daniel Frey

data/ext/third_party/json/doc/Changelog.md DELETED Viewed

@@ -1,31 +0,0 @@
-# Changelog
-## 1.0.0
-**Not yet released**
-## Milestones
-Pre-1.0.0 milestones in rough reverse chronological order.
-* Change value from `union` to `std::variant`.
-* Change library to require and use C++17.
-* Direct parsing to arbitrary types.
-* Binding facilities and polymorphic factory.
-* Optional custom Base class for Values.
-* Support for Opaque Pointers in Values.
-* JAXN data model with binary data and non-finite doubles.
-* JSON Pointer and JSON Patch support.
-* Support for CBOR, UBJSON and MsgPack.
-* Support for Value Pointer in Values.
-* Events Interface for modularity and Transformers.
-* Type Traits for interoperation with C++ types.
-* 100% conformance score in [Native JSON Benchmark](https://github.com/miloyip/nativejson-benchmark).
-* Inclusion of double-conversion library.
-* Value Class with parsing and (pretty) printing.
-## History
-Development of taoJSON started in October 2015 as an experiment to combine the [PEGTL](https://github.com/taocpp/PEGTL) JSON parser with a JSON value class based on a `union` that directly embeds standard containers for arrays, objects and strings.
-Copyright (c) 2018-2020 Dr. Colin Hirsch and Daniel Frey

data/ext/third_party/json/doc/Common-Use-Cases.md DELETED Viewed

@@ -1,148 +0,0 @@
-# Common Use Cases
-* [Include the right header](#include-the-right-header)
-* [Read any JSON file](#read-any-json-file)
-* [Parse any JSON string](#parse-any-json-string)
-* [Serialise a JSON Value to a string](#serialise-a-json-value-to-a-string)
-* [Serialise with base64 strings for binary data](#serialise-with-base64-strings-for-binary-data)
-* [Serialise a JSON Value to an ostream](#serialise-a-json-value-to-an-ostream)
-* [Create a Value with a JSON object](#create-a-value-with-a-json-object)
-## Include the right header
-The convenience include `<tao/json.hpp>` will include the entire core library.
-Additionally, it might be useful to include `<tao/json/contrib/traits.hpp>` to add some commonly used Traits specialisations, mostly for containers and smart pointers.
-```c++
-#include <tao/json.hpp>
-#include <tao/json/contrib/traits.hpp>
-```
-(To improve compile times, you can choose to directly use only some of the individual headers that it includes.)
-## Read any JSON file
-```c++
-const tao::json::value v = tao::json::from_file( "filename.json" );
-```
-## Parse any JSON string
-```c++
-const tao::json::value v = tao::json::from_string( "{ \"a\": 1.0, \"b\": 2.0 }" );
-```
-## Serialise a JSON Value to a string
-We will assume that `v` is a valid JSON Value instance.
-```c++
-const std::string j = tao::json::to_string( v );
-```
-Passing a `std::size_t` as second argument enable pretty-printing mode with the given size as indent.
-Passing a `std::string` as third argument uses the given string as line ending instead of the `\n` default.
-## Serialise with base64 strings for binary data
-The JSON format does not allow for binary data.
-Binary data in Values needs to be converted into something else when serialising to JSON.
-This can be done on-the-fly with an [Events Transformer](Events-Interface.md#overview) like `tao::json::events::binary_to_base64`.
-```c++
-const std::string l = tao::json::to_string< tao::json::events::binary_to_base64 >( v );
-```
-Another similar common use case is to use a Transformer like `tao::json::events::non_finite_to_null` to convert non-finite floating-point values (not-a-number, infinity) to something that fits in the JSON data model.
-See the [Events interface](Events-Interface.md) documentation for [all available Event Transformers](Events-Interface.md#included-transformers).
-## Serialise a JSON Value to an ostream
-```c++
-tao::json::to_stream( std::cout, v );
-```
-The additional function and template arguments are just like for `to_string()`.
-```c++
-using namespace tao::json;
-to_stream< events::binary_to_base64, events::non_finite_to_null >( std::cout, v, 3, "\r\n" );
-```
-When no Events Transformers are needed the usual `operator<<` overloads can be used, too.
-```c++
-std::cout << v << std::endl;  // Compact.
-std::cout << std::setw( 2 ) << v << std::endl;  // Pretty-printed with indent 2.
-```
-## Create a Value with a JSON object
-### First possibility
-Parse a string that represents a JSON object, [see above](#parse-any-json-string).
-This works similarly with files, and with strings and files in other supported formats.
-### Second possibility
-Use the literal string operator to parse a literal string.
-```c++
-using namespace tao::json;
-const auto v = "{ \"a\": 1.0, \"b\": 2.0 }"_json;
-```
-### Third possibility
-Use the `std::initalizer_list<>` constructor.
-```c++
-const tao::json::value v = {
-   { "a", 1.0 },
-   { "b", 2.0 }
-};
-```
-### Fourth possibility
-Use the appropriate value member functions.
-```c++
-int main()
-{
-   tao::json::value v;
-   v.emplace( "a", 1.0 );
-   v.emplace( "b", 2.0 );
-   return 0;
-}
-```
-Note that `v.emplace()` will work both on values that already represent an Object *and* on values that are in state `UNINITIALIZED` or `DISCARDED`.
-### Fifth possibility
-Use an Event Consumer to feed Events to a value.
-```c++
-int main()
-{
-   tao::json::events::to_value consumer;
-   consumer.begin_object();
-   consumer.key( "a" );
-   consumer.number( 1.0 );
-   consumer.member();
-   consumer.key( "b" );
-   consumer.number( 2.0 );
-   consumer.member();
-   consumer.end_object();
-   const tao::json::value v = std::move( consumer.value );
-   return 0;
-}
-```
-Copyright (c) 2018-2020 Dr. Colin Hirsch and Daniel Frey

data/ext/third_party/json/doc/Design-Decisions.md DELETED Viewed

@@ -1,36 +0,0 @@
-# Design Decisions
-* [Require C++17](#require-c17)
-* [Initialiser Lists](#initialiser-lists)
-* [Omitted Functions](#omitted-functions)
-This library is designed for correctness and simplicity, is based on C++ standard containers, and strives for speed through minimalism (rather than complicated optimisations).
-## Require C++17
-For the first three years this library was compatible with C++11, however we changed the required standard version to C++17 before reaching version 1.0.0.
-There were two main reasons for making this change.
-1. With C++11 the library had to include and maintain implementations of `std::optional` and `std::string_view`; the latter was not a full replacement since C++11 `std::string` does not know about string views.
-2. Many places throughout the library that benefit from being able to use C++17 language features; for examples look at the flock of C++17-related commits made after the standards upgrade in October 2018.
-## Initialiser-Lists
-The Value constructor that accepts an initialiser-list as argument will always (attempt to) create a Value that is an Object, i.e. it will never attempt to create a Value that is an Array, because it is not possible for the same function to accept initialiser-lists for both Arrays and Objects without introducing ambiguities:
-* Is `{ { "hallo", 1 }, { "world", 2 } }` an Array with two Arrays as elements, or an Object with two members?
-* If `foo` has a [default key](Type-Traits.md#default-key-for-objects) in the traits, is `{ foo }` an Array with one element, or an Object with one member?
-Creating an Array from an initialiser-list is still possible with the static `tao::json::value::array()` function.
-## Omitted Functions
-Class `tao::json::value` has neither a `size()` nor an `empty()` method due to the lack of unambiguous canonical semantics.
-* Should atomic JSON Values have size `0` or size `1`, or should everything except for Null have size `1`?
-* Should special values (like `UNINITIALIZED`) have size `0`, or should they throw when checking the size?
-* Should strings use container semantics for `size()` and `empty()`, or should they behave like atomic Values?
-* Should a Value Pointer have size `1`, or should it forward `size()` and `empty()` to the pointee Value?
-* Should an Opaque Pointer have size `1`, or should it report the size of the JSON representation of the pointee?
-Copyright (c) 2018-2020 Dr. Colin Hirsch and Daniel Frey

data/ext/third_party/json/doc/Events-Interface.md DELETED Viewed

@@ -1,140 +0,0 @@
-# Events Interface
-* [Overview](#overview)
-* [Consumer Interface](#consumer-interface)
-* [Arrays and Objects](#arrays-and-objects)
-* [Reduced Interface](#reduced-interface)
-* [Batteries Included](#batteries-included)
-## Overview
-The Events Interface is a calling convention, a kind of abstract (in the conceptual, not object-oriented sense) interface that allows different parts of the library to communicate with each other.
-The Events Interface is modelled after the SAX-interface for XML and has functions like `begin_object()` and `boolean( const bool )`.
-We distinguish betwen *Event Producers* that usually take some input and generate calls to the Events Interface from it, and *Event Consumers* which implement the functions of the Events Interface to usually produce some output.
-*Event Transformers* occupy both roles, accepting calls to the Events Interface and transforming them into (other) calls to another Events Consumer.
-For example the `tao::json::events::from_value()` function is an Events Producer that takes a Value object of type `tao::json::basic_value< Traits, Base >` for any Type Traits class `Traits` and Value base class `Base` as input, and generates Events depending on the contents.
-It could be used together with the `tao::json::events::to_string()` class, an Events Consumer that generates the JSON string representation corresponding to the Events it receives.
-In order to transform binary data in the Value object into something compatible with standard JSON it might be necessary to use an Events Transformer like `tao::json::events::binary_to_hex` between the Producer and Consumer.
-Producers and Consumers can be freely coupled, it is not necessary for the beginning or the end of the chain to be a JSON Value object.
-For example an Events Producer that parses CBOR can be directly used with an Events Consumer that creates UBJSON.
-```c++
-#include <tao/json.hpp>
-std::string cbor_to_ubjson( const std::string& input )
-{
-   tao::json::ubjson::events::to_string consumer;
-   tao::json::cbor::events::from_string( consumer, input );
-   return consumer.value();
-}
-```
-A more common use case is parsing a JSON text representation into a JSON Value...
-```c++
-tao::json::value from_string( const std::string& input )
-{
-   tao::json::events::to_value consumer;
-   tao::json::events::from_string( consumer, input );
-   return std::move( consumer.value );
-}
-```
-...which is in fact so common that a (more general) convenience function `tao::json::from_string()` is included with the library.
-The tables below list all included Events Producers, Consumers, and Transformers, as well as the convenience functions where the source or destination is a Value.
-## Consumer Interface
-```c++
-struct complete_consumer
-{
-   void null();
-   void boolean( const bool );
-   void number( const double );
-   void number( const std::int64_t );
-   void number( const std::uint64_t );
-   void string( std::string && );
-   void string( const std::string & );
-   void string( const tao::string_view & );
-   void binary( std::vector< tao::byte > && );
-   void binary( const std::vector< tao::byte > & );
-   void binary( const tao::binary_view & );
-   void begin_array();
-   void begin_array( const std::size_t );
-   void element();
-   void end_array();
-   void end_array( const std::size_t );
-   void begin_object();
-   void begin_object( const std::size_t );
-   void key( std::string && );
-   void key( const std::string & );
-   void key( const tao::string_view & );
-   void member();
-   void end_object();
-   void end_object( const std::size_t );
-};
-```
-## Arrays and Objects
-For arrays and objects there are two versions of the begin and end methods, one that receives the size of the array (what `std::vector< Value >::size()` would return), or the size of the object (what `std::map< std::string, Value >::size()` would return), respectively, and one that doesn't.
-An Events producer will usually only either always call the begin/end-array/object functions with a size, or those without a size, depending on whether the size is readily available.
-Within an Array, i.e. after a call to `begin_array()` but before a call to the corresponding `end_array()`, the `element()` function is called after the function(s) for each array sub-value.
-Similarly within an Object the sequence for every object entry is `key()`, then the function(s) for the value, then `member()`.
-If the Value within an Array or Object is simple, like a string or number, it is defined by a single corresponding Events call.
-However the data model allows for Arrays and Objects to be nested, wherefore the same holds for corresponding matching calls to an Event consumer's begin/end-array/object methods.
-If a Value in an Array or Object is itself an Array or Object, then it will lead to at least the corresponding begin and end calls, with the possibility of arbitrary many sub-values, including arbitrarily nested other Arrays and Objects.
-Calls to `element()` or `member()` are naturally understood to belong to the inner-most Array or Object, i.e. to the last begin-method without end.
-An Events Producer MUST NOT generate inconsistent sequences of Event calls.
-For example pairing `begin_array()` with `end_object()`, using `member()` when the inner-most container is not an Object, must all be avoided.
-## Reduced Interface
-It will not always be necessary, desirable, or even possible, to implement all of these functions.
-For example consider a consumer that writes some representation to a stream.
-Such a consumer will not benefit from implementing the functions with movable arguments since it has no place to move the arguments to.
-If the format it writes requires the encoding of objects and arrays to start with the number of array elements or object members, respectively, then the consumer might not implement the begin/end-array/object methods without size.
-An Events Consumer that does not need the sizes of arrays and objects in the begin/end-calls, and that does not benefit from receiving movable arguments, can implement a reduced interface that - thanks to default arguments and the view-classes' implicit constructors - can still accept all function calls that the full interface can.
-```c++
-struct reduced_consumer
-{
-   void null();
-   void boolean( const bool );
-   void number( const double );
-   void number( const std::int64_t );
-   void number( const std::uint64_t );
-   void string( const tao::string_view );
-   void binary( const tao::binary_view );
-   void begin_array( const std::size_t = 0 );
-   void element();
-   void end_array( const std::size_t = 0 );
-   void begin_object( const std::size_t = 0 );
-   void key( const tao::string_view );
-   void member();
-   void end_object( const std::size_t = 0 );
-};
-```
-## Batteries Included
-* [Events Producers](Batteries-Included.md#events-producers)
-* [Events Consumers](Batteries-Included.md#events-consumers)
-* [Events Transformers](Batteries-Included.md#events-transformers)
-* [Convenience Functions](Batteries-Included.md#convenience-functions)
-Copyright (c) 2018-2020 Dr. Colin Hirsch and Daniel Frey