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