robot/include/boost/json/conversion.hpp

//
// Copyright (c) 2022 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
//

#ifndef BOOST_JSON_CONVERSION_HPP
#define BOOST_JSON_CONVERSION_HPP

#include <boost/json/detail/config.hpp>
#include <boost/json/fwd.hpp>

#include <type_traits>

namespace boost {
namespace json {

namespace detail {

template< class Ctx, class T, class Dir >
struct supported_context;

} // namespace detail

/** Customization point tag.

    This tag type is used by the function
    @ref value_from to select overloads
    of `tag_invoke`.

    @note This type is empty; it has no members.

    @see @ref value_from, @ref value_to, @ref value_to_tag,
    <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1895r0.pdf">
        tag_invoke: A general pattern for supporting customisable functions</a>
*/
struct value_from_tag { };

/** Customization point tag type.

    This tag type is used by the function
    @ref value_to to select overloads
    of `tag_invoke`.

    @note This type is empty; it has no members.

    @see @ref value_from, @ref value_from_tag, @ref value_to,
    <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1895r0.pdf">
        tag_invoke: A general pattern for supporting customisable functions</a>
*/
template<class T>
struct value_to_tag { };

/** Customization point tag type.

    This tag type is used by the function
    @ref try_value_to to select overloads
    of `tag_invoke`.

    @note This type is empty; it has no members.

    @see @ref value_to, @ref value_to_tag
    <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1895r0.pdf">
        tag_invoke: A general pattern for supporting customisable functions</a>
*/
template<class T>
struct try_value_to_tag { };

/** Determine if `T` can be treated like a string during conversions.

    Provides the member constant `value` that is equal to `true`, if `T` is
    convertible to @ref string_view. Otherwise, `value` is equal to `false`.
    <br>

    Users can specialize the trait for their own types if they don't want them
    to be treated like strings. For example:

    @code
    namespace boost {
    namespace json {

    template <>
    struct is_string_like<your::string> : std::false_type
    { };

    } // namespace boost
    } // namespace json
    @endcode

    @par Types satisfying the trait

    @ref string,
    @ref string_view,
    <a href="https://en.cppreference.com/w/cpp/string/basic_string"><tt>std::string</tt></a>,
    <a href="https://en.cppreference.com/w/cpp/string/basic_string_view"><tt>std::string_view</tt></a>.

    @see @ref value_from, @ref value_to
*/
template<class T>
struct is_string_like;

/** Determine if `T` can be treated like `std::filesystem::path` during conversions.

    Given `t`, a glvalue of type `T`, if

    @li given `It`, the type denoted by `decltype(std::begin(t))`,
        <tt>std::iterator_traits<It>::iterator_category</tt> is well-formed and
        denotes a type; and

    @li <tt>std::iterator_traits<It>::value_type</tt> is `T`; and

    @li `T::value_type` is well-formed and denotes a type; and

    @li `T::string_type` is well-formed, denotes a type, and is an alias for
    `std::basic_string< T::value_type >`;

    then the trait provides the member constant `value` that is equal to
    `true`. Otherwise, `value` is equal to `false`.<br>

    Users can specialize the trait for their own types if they don't want them
    to be treated like filesystem paths. For example:

    @code
    namespace boost {
    namespace json {

    template <>
    struct is_path_like<your::path> : std::false_type
    { };

    } // namespace boost
    } // namespace json
    @endcode


    @par Types satisfying the trait

    `std::filesystem::path`, `boost::filesystem::path`.

    @see @ref value_from, @ref value_to
*/
template<class T>
struct is_path_like;

/** Determine if `T` can be treated like a sequence during conversions.

    Given `t`, a glvalue of type `T`, if

    @li given `It`, the type denoted by `decltype(std::begin(t))`,
        <tt>std::iterator_traits<It>::iterator_category</tt> is well-formed and
        denotes a type; and

    @li `decltype(std::end(t))` also denotes the type `It`; and

    @li <tt>std::iterator_traits<It>::value_type</tt> is not `T`; and

    then the trait provides the member constant `value` that is equal to
    `true`. Otherwise, `value` is equal to `false`.<br>

    Users can specialize the trait for their own types if they don't want them
    to be treated like sequences. For example:

    @code
    namespace boost {
    namespace json {

    template <>
    struct is_sequence_like<your::container> : std::false_type
    { };

    } // namespace boost
    } // namespace json
    @endcode


    @par Types satisfying the trait

    Any <a href="https://en.cppreference.com/w/cpp/named_req/SequenceContainer"><em>SequenceContainer</em></a>,
    array types.

    @see @ref value_from, @ref value_to
*/
template<class T>
struct is_sequence_like;

/** Determine if `T` can be treated like a 1-to-1 mapping during
    conversions.

    Given `t`, a glvalue of type `T`, if

    @li <tt>is_sequence_like<T>::value</tt> is `true`; and

    @li given type `It` denoting `decltype(std::begin(t))`, and types `K`
        and `M`,  <tt>std::iterator_traits<It>::value_type</tt> denotes
        `std::pair<K, M>`; and

    @li <tt>std::is_string_like<K>::value</tt> is `true`; and

    @li given `v`, a glvalue of type `V`, and `E`, the type denoted by
        `decltype(t.emplace(v))`,
        <tt>std::is_tuple_like<E>::value</tt> is `true`;

    then the trait provides the member constant `value`
    that is equal to `true`. Otherwise, `value` is equal to `false`.<br>

    Users can specialize the trait for their own types if they don't want them
    to be treated like mappings. For example:

    @code
    namespace boost {
    namespace json {

    template <>
    struct is_map_like<your::map> : std::false_type
    { };

    } // namespace boost
    } // namespace json
    @endcode


    @note

    The restriction for `t.emplace()` return type ensures that the container
    does not accept duplicate keys.

    @par Types satisfying the trait

    <a href="https://en.cppreference.com/w/cpp/container/map"><tt>std::map</tt></a>,
    <a href="https://en.cppreference.com/w/cpp/container/unordered_map"><tt>std::unordered_map</tt></a>.

    @see @ref value_from, @ref value_to
*/
template<class T>
struct is_map_like;

/** Determine if `T` can be treated like a tuple during conversions.

    Provides the member constant `value` that is equal to `true`, if
    <tt>std::tuple_size<T>::value</tt> is a positive number. Otherwise, `value`
    is equal to `false`.<br>

    Users can specialize the trait for their own types if they don't want them
    to be treated like tuples. For example:

    @code
    namespace boost {
    namespace json {

    template <>
    struct is_tuple_like<your::tuple> : std::false_type
    { };

    } // namespace boost
    } // namespace json
    @endcode


    @par Types satisfying the trait

    <a href="https://en.cppreference.com/w/cpp/utility/tuple"><tt>std::tuple</tt></a>,
    <a href="https://en.cppreference.com/w/cpp/utility/pair"><tt>std::pair</tt></a>.

    @see @ref value_from, @ref value_to
*/
template<class T>
struct is_tuple_like;

/** Determine if `T` can be treated like null during conversions.

    Primary template instantiations provide the member constant `value` that is
    equal to `false`. Users can specialize the trait for their own types if
    they **do** want them to be treated as nulls. For example:

    @code
    namespace boost {
    namespace json {

    template <>
    struct is_null_like<your::null_type> : std::true_type
    { };

    } // namespace boost
    } // namespace json
    @endcode


    @par Types satisfying the trait

    <a href="https://en.cppreference.com/w/cpp/types/nullptr_t"><tt>std::nullptr_t</tt></a>.

    @see @ref value_from, @ref value_to
*/
template<class T>
struct is_null_like
    : std::false_type
{ };

/** Determine if `T` should be treated as a described class

    Described classes are serialised as objects with an element for each
    described data member. A described class should not have described
    bases or non-public members.<br>

    Or more formally, given `L`, a class template
    of the form `template<class...> struct L {};`, if

    @li <tt>boost::describe::has_members<T, boost::describe::mod_public>::value</tt> is `true`; and

    @li `boost::describe::describe_members<T, boost::describe::mod_private | boost::describe::mod_protected>` denotes `L<>`; and

    @li `boost::describe::describe_bases<T, boost::describe::mod_any_access>` denotes `L<>`; and

    @li <tt>std::is_union<T>::value</tt> is `false`;

    then the trait provides the member constant `value`
    that is equal to `true`. Otherwise, `value` is equal to `false`.<br>

    Users can specialize the trait for their own types if they don't want them
    to be treated as described classes. For example:

    @code
    namespace boost {
    namespace json {

    template <>
    struct is_described_class<your::described_class> : std::false_type
    { };

    } // namespace boost
    } // namespace json
    @endcode

    Users can also specialize the trait for their own types _with_ described
    bases or described non-public data members to enable this conversion
    implementation. In this case the class will be serialized in a flattened
    way, that is members of bases will be serialized as direct elements of the
    object, and no nested objects will be created for bases.

    @see <a href="https://www.boost.org/doc/libs/develop/libs/describe/doc/html/describe.html">Boost.Describe</a>.
*/
template<class T>
struct is_described_class;

/** Determine if `T` should be treated as a described enum

    Described enums are serialised as strings when their value equals to a
    described enumerator, and as integers otherwise. The reverse operation
    does not convert numbers to enums values, though, and instead produces
    an error.<br>

    If <tt>boost::describe::has_describe_enumerators<T>::value</tt> is `true`,
    then the trait provides the member constant `value`
    that is equal to `true`. Otherwise, `value` is equal to `false`.<br>

    Users can specialize the trait for their own enums if they don't want them
    to be treated as described enums. For example:

    @code
    namespace boost {
    namespace json {

    template <>
    struct is_described_enum<your::described_enum> : std::false_type
    { };

    } // namespace boost
    } // namespace json
    @endcode

    @see <a href="https://www.boost.org/doc/libs/develop/libs/describe/doc/html/describe.html">Boost.Describe</a>.
*/
template<class T>
struct is_described_enum;

/** Determine if `T` should be treated as a variant

    Variants are serialised the same way their active alternative is
    serialised. The opposite conversion selects the first alternative for which
    conversion succeeds.<br>

    Given `t`, a glvalue of type ` const T`, if
    <tt>t.valueless_by_exception()</tt> is well-formed, then the trait provides
    the member constant `value` that is equal to `true`. Otherwise, `value` is
    equal to `false`.<br>

    Users can specialize the trait for their own types if they don't want them
    to be treated as variants. For example:

    @code
    namespace boost {
    namespace json {

    template <>
    struct is_variant_like<your::variant> : std::false_type
    { };

    } // namespace boost
    } // namespace json
    @endcode
*/
template<class T>
struct is_variant_like;

/** Determine if `T` should be treated as an optional

    Optionals are serialised as `null` if empty, or as the stored type
    otherwise.<br>

    Given `t`, a glvalue of type `T`, if

    @li <tt>decltype( t.value() )</tt> is well-formed and isn't a void type; and

    @li <tt>t.reset()</tt> is well-formed;

    then the trait provides the member constant `value`
    that is equal to `true`. Otherwise, `value` is equal to `false`.<br>

    Users can specialize the trait for their own types if they don't want them
    to be treated as optionals. For example:

    @code
    namespace boost {
    namespace json {

    template <>
    struct is_optional_like<your::optional> : std::false_type
    { };

    } // namespace boost
    } // namespace json
    @endcode
*/
template<class T>
struct is_optional_like;

} // namespace json
} // namespace boost

#include <boost/json/impl/conversion.hpp>

#endif // BOOST_JSON_CONVERSION_HPP