TLA  Line data    Source code

       1                 : //
       2                 : // Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com)
       3                 : // Copyright (c) 2024 Dmitry Arkhipov (grisumbras@yandex.ru)
       4                 : //
       5                 : // Distributed under the Boost Software License, Version 1.0. (See accompanying
       6                 : // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
       7                 : //
       8                 : // Official repository: https://github.com/boostorg/json
       9                 : //
      10                 : 
      11                 : #ifndef BOOST_JSON_RESULT_FOR_HPP
      12                 : #define BOOST_JSON_RESULT_FOR_HPP
      13                 : 
      14                 : #include <boost/json/detail/config.hpp>
      15                 : #include <boost/json/fwd.hpp>
      16                 : #include <boost/assert/source_location.hpp>
      17                 : #include <boost/system/result.hpp>
      18                 : 
      19                 : namespace boost {
      20                 : namespace json {
      21                 : 
      22                 : /**
      23                 :    Helper trait that returns @ref boost::system::result.
      24                 : 
      25                 :    The primary template is an incomplete type. The library provides a partial
      26                 :    specialisation `result_for<T1, value>`, that has nested type alias `type`
      27                 :    that aliases the type `result<T1>`.
      28                 : 
      29                 :    The purpose of this trait is to let users provide non-throwing conversions
      30                 :    for their types without creating a physical dependency on Boost.Json. For
      31                 :    example:
      32                 : 
      33                 :    @code
      34                 :    namespace boost {
      35                 :    namespace json {
      36                 : 
      37                 :    template<class T>
      38                 :    struct value_to_tag;
      39                 : 
      40                 :    template<class T1, class T2>
      41                 :    struct result_for;
      42                 :    }
      43                 :    }
      44                 : 
      45                 :    namespace mine
      46                 :    {
      47                 :        class my_class;
      48                 :        ...
      49                 :        template<class JsonValue>
      50                 :        boost::json::result_for<my_class, JsonValue>
      51                 :        tag_invoke(boost::json::try_value_to_tag<my_class>, const JsonValue& jv)
      52                 :        { ... }
      53                 :    }
      54                 :    @endcode
      55                 : 
      56                 :    @see @ref try_value_to, @ref try_value_to_tag
      57                 : */
      58                 : template <class T1, class T2>
      59                 : struct result_for;
      60                 : 
      61                 : /** Create @ref boost::system::result containing a portable error code.
      62                 : 
      63                 :     This function constructs a `boost::system::result<T>` that stores
      64                 :     `error_code` with `value()` equal to `e` and `category()` equal to
      65                 :     @ref boost::system::generic_category().
      66                 : 
      67                 :     The main use for this function is in implementation of functions returning
      68                 :     `boost::system::result`, without including `boost/json/system_error.hpp` or
      69                 :     even `<system_error>`. In particular, it may be useful for customizations
      70                 :     of @ref try_value_to without creating a physical dependency on Boost.JSON.
      71                 :     For example:
      72                 : 
      73                 :     @code
      74                 :     #include <cerrno>
      75                 :     #include <boost/assert/source_location.hpp>
      76                 : 
      77                 :     namespace boost {
      78                 :     namespace json {
      79                 : 
      80                 :     class value;
      81                 : 
      82                 :     template<class T>
      83                 :     struct try_value_to_tag;
      84                 : 
      85                 :     template<class T1, class T2>
      86                 :     struct result_for;
      87                 : 
      88                 :     template <class T>
      89                 :     typename result_for<T, value>::type
      90                 :     result_from_errno(int e, boost::source_location const* loc) noexcept
      91                 : 
      92                 :     }
      93                 :     }
      94                 : 
      95                 :     namespace mine {
      96                 : 
      97                 :     class my_class;
      98                 :     ...
      99                 :     template<class JsonValue>
     100                 :     boost::json::result_for<my_class, JsonValue>
     101                 :     tag_invoke(boost::json::try_value_to_tag<my_class>, const JsonValue& jv)
     102                 :     {
     103                 :         BOOST_STATIC_CONSTEXPR boost::source_location loc = BOOST_CURRENT_LOCATION;
     104                 :         if( !jv.is_null() )
     105                 :             return boost::json::result_from_errno<my_class>(EINVAL, &loc);
     106                 :         return my_class();
     107                 :     }
     108                 : 
     109                 :     }
     110                 :     @endcode
     111                 : 
     112                 :     @par Exception Safety
     113                 :     Does not throw exceptions.
     114                 : 
     115                 :     @tparam T The value type of returned `result`.
     116                 :     @param e The error value.
     117                 :     @param loc The error location.
     118                 : 
     119                 :     @returns A @ref boost::system::result containing an error.
     120                 : 
     121                 :     @see @ref try_value_to_tag, @ref try_value_to, @ref result_for.
     122                 : */
     123                 : template <class T>
     124                 : typename result_for<T, value>::type
     125 HIT          56 : result_from_errno(int e, boost::source_location const* loc) noexcept
     126                 : {
     127              56 :     system::error_code ec(e, system::generic_category(), loc);
     128              56 :     return {system::in_place_error, ec};
     129                 : }
     130                 : 
     131                 : } // namespace json
     132                 : } // namespace boost
     133                 : 
     134                 : #endif // BOOST_JSON_RESULT_FOR_HPP