boost/json/result_for.hpp

0001 //
0002 // Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com)
0003 // Copyright (c) 2024 Dmitry Arkhipov (grisumbras@yandex.ru)
0004 //
0005 // Distributed under the Boost Software License, Version 1.0. (See accompanying
0006 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
0007 //
0008 // Official repository: https://github.com/boostorg/json
0009 //
0010
0011 #ifndef BOOST_JSON_RESULT_FOR_HPP
0012 #define BOOST_JSON_RESULT_FOR_HPP
0013
0014 #include <boost/json/detail/config.hpp>
0015 #include <boost/json/fwd.hpp>
0016 #include <boost/assert/source_location.hpp>
0017 #include <boost/system/result.hpp>
0018
0019 namespace boost {
0020 namespace json {
0021
0022 /**
0023    Helper trait that returns @ref result
0024
0025    The primary template is an incomplete type. The library provides a partial
0026    specialisation `result_for<T1, value>`, that has nested type alias `type`
0027    that aliases the type `result<T1>`.
0028
0029    The purpose of this trait is to let users provide non-throwing conversions
0030    for their types without creating a physical dependency on Boost.Json. For
0031    example:
0032
0033    @code
0034    namespace boost
0035    {
0036    namespace json
0037    {
0038
0039    template<class T>
0040    struct value_to_tag;
0041
0042    template<class T1, class T2>
0043    struct result_for;
0044    }
0045    }
0046
0047    namespace mine
0048    {
0049        class my_class;
0050        ...
0051        template<class JsonValue>
0052        boost::json::result_for<my_class, JsonValue>
0053        tag_invoke(boost::json::try_value_to_tag<my_class>, const JsonValue& jv)
0054        { ... }
0055    }
0056    @endcode
0057
0058     @see @ref try_value_to, @ref try_value_to_tag
0059 */
0060 template <class T1, class T2>
0061 struct result_for;
0062
0063 /** Create @ref result storing a portable error code
0064
0065     This function constructs a `boost::system::result<T>` that stores
0066     `boost::system::error_code` with `value()` equal to `e` and `category()`
0067     equal to `boost::system::generic_category()`. <br>
0068
0069     The main use for this function is in implementation of functions returning
0070     @ref result, without including `boost/json/system_error.hpp` or even
0071     `<system_error>`. In particular, it may be useful for customizations of
0072     @ref try_value_to without creating a physical dependency on Boost.JSON.
0073     For example:
0074
0075     @code
0076     #include <cerrno>
0077     #include <boost/assert/source_location.hpp>
0078
0079     namespace boost
0080     {
0081     namespace json
0082     {
0083
0084     class value;
0085
0086     template<class T>
0087     struct try_value_to_tag;
0088
0089     template<class T1, class T2>
0090     struct result_for;
0091
0092     template <class T>
0093     typename result_for<T, value>::type
0094     result_from_errno(int e, boost::source_location const* loc) noexcept
0095
0096     }
0097     }
0098
0099     namespace mine
0100     {
0101
0102     class my_class;
0103     ...
0104     template<class JsonValue>
0105     boost::json::result_for<my_class, JsonValue>
0106     tag_invoke(boost::json::try_value_to_tag<my_class>, const JsonValue& jv)
0107     {
0108         BOOST_STATIC_CONSTEXPR boost::source_location loc = BOOST_CURRENT_LOCATION;
0109         if( !jv.is_null() )
0110             return boost::json::result_from_errno<my_class>(EINVAL, &loc);
0111         return my_class();
0112     }
0113
0114     }
0115     @endcode
0116
0117     @par Exception Safety
0118     Does not throw exceptions.
0119
0120     @tparam T The value type of returned `result`.
0121
0122     @param e The error value.
0123
0124     @param loc The error location.
0125
0126     @returns `boost::system::error_code` with `value()` equal to `e` and
0127     `category()` equal to `boost::system::generic_category()`.
0128
0129     @see @ref try_value_to_tag, @ref try_value_to, @ref result_for,
0130     <a href="https://www.boost.org/doc/libs/develop/libs/system/doc/html/system.html#ref_generic_category">
0131         `boost::system::generic_category`</a>,
0132     <a href="https://www.boost.org/doc/libs/master/libs/assert/doc/html/assert.html#source_location_support">
0133         `boost::source_location`</a>.
0134 */
0135 template <class T>
0136 typename result_for<T, value>::type
0137 result_from_errno(int e, boost::source_location const* loc) noexcept
0138 {
0139     system::error_code ec(e, system::generic_category(), loc);
0140     return {system::in_place_error, ec};
0141 }
0142
0143 } // namespace json
0144 } // namespace boost
0145
0146 #endif // BOOST_JSON_RESULT_FOR_HPP