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 `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 + 
   {
 
36 + 
   namespace json
 
37 + 
   {
36  
38  
37   
   template<class T>
39   
   template<class T>
38   
   struct value_to_tag;
40   
   struct value_to_tag;
39  
41  
40   
   template<class T1, class T2>
42   
   template<class T1, class T2>
41   
   struct result_for;
43   
   struct result_for;
42   
   }
44   
   }
43   
   }
45   
   }
44  
46  
45   
   namespace mine
47   
   namespace mine
46   
   {
48   
   {
47   
       class my_class;
49   
       class my_class;
48   
       ...
50   
       ...
49   
       template<class JsonValue>
51   
       template<class JsonValue>
50   
       boost::json::result_for<my_class, JsonValue>
52   
       boost::json::result_for<my_class, JsonValue>
51   
       tag_invoke(boost::json::try_value_to_tag<my_class>, const JsonValue& jv)
53   
       tag_invoke(boost::json::try_value_to_tag<my_class>, const JsonValue& jv)
52   
       { ... }
54   
       { ... }
53   
   }
55   
   }
54   
   @endcode
56   
   @endcode
55  
57  
56 - 
   @see @ref try_value_to, @ref try_value_to_tag
58 + 
    @see @ref try_value_to, @ref try_value_to_tag
57   
*/
59   
*/
58   
template <class T1, class T2>
60   
template <class T1, class T2>
59   
struct result_for;
61   
struct result_for;
60  
62  
61 - 
/** Create @ref boost::system::result containing a portable error code.
63 + 
/** Create `boost::system::result` storing a portable error code
62  
64  
63   
    This function constructs a `boost::system::result<T>` that stores
65   
    This function constructs a `boost::system::result<T>` that stores
64 - 
    `error_code` with `value()` equal to `e` and `category()` equal to
66 + 
    `boost::system::error_code` with `value()` equal to `e` and `category()`
65 - 
    @ref boost::system::generic_category().
67 + 
    equal to `boost::system::generic_category()`. <br>
66  
68  
67   
    The main use for this function is in implementation of functions returning
69   
    The main use for this function is in implementation of functions returning
68   
    `boost::system::result`, without including `boost/json/system_error.hpp` or
70   
    `boost::system::result`, without including `boost/json/system_error.hpp` or
69   
    even `<system_error>`. In particular, it may be useful for customizations
71   
    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.
72   
    of @ref try_value_to without creating a physical dependency on Boost.JSON.
71   
    For example:
73   
    For example:
72  
74  
73   
    @code
75   
    @code
74   
    #include <cerrno>
76   
    #include <cerrno>
75   
    #include <boost/assert/source_location.hpp>
77   
    #include <boost/assert/source_location.hpp>
76  
78  
77 - 
    namespace boost {
79 + 
    namespace boost
78 - 
    namespace json {
80 + 
    {
 
81 + 
    namespace json
 
82 + 
    {
79  
83  
80   
    class value;
84   
    class value;
81  
85  
82   
    template<class T>
86   
    template<class T>
83   
    struct try_value_to_tag;
87   
    struct try_value_to_tag;
84  
88  
85   
    template<class T1, class T2>
89   
    template<class T1, class T2>
86   
    struct result_for;
90   
    struct result_for;
87  
91  
88   
    template <class T>
92   
    template <class T>
89   
    typename result_for<T, value>::type
93   
    typename result_for<T, value>::type
90   
    result_from_errno(int e, boost::source_location const* loc) noexcept
94   
    result_from_errno(int e, boost::source_location const* loc) noexcept
91  
95  
92   
    }
96   
    }
93   
    }
97   
    }
94  
98  
95 - 
    namespace mine {
99 + 
    namespace mine
 
100 + 
    {
96  
101  
97   
    class my_class;
102   
    class my_class;
98   
    ...
103   
    ...
99   
    template<class JsonValue>
104   
    template<class JsonValue>
100   
    boost::json::result_for<my_class, JsonValue>
105   
    boost::json::result_for<my_class, JsonValue>
101   
    tag_invoke(boost::json::try_value_to_tag<my_class>, const JsonValue& jv)
106   
    tag_invoke(boost::json::try_value_to_tag<my_class>, const JsonValue& jv)
102   
    {
107   
    {
103   
        BOOST_STATIC_CONSTEXPR boost::source_location loc = BOOST_CURRENT_LOCATION;
108   
        BOOST_STATIC_CONSTEXPR boost::source_location loc = BOOST_CURRENT_LOCATION;
104   
        if( !jv.is_null() )
109   
        if( !jv.is_null() )
105   
            return boost::json::result_from_errno<my_class>(EINVAL, &loc);
110   
            return boost::json::result_from_errno<my_class>(EINVAL, &loc);
106   
        return my_class();
111   
        return my_class();
107   
    }
112   
    }
108  
113  
109   
    }
114   
    }
110   
    @endcode
115   
    @endcode
111  
116  
112   
    @par Exception Safety
117   
    @par Exception Safety
113   
    Does not throw exceptions.
118   
    Does not throw exceptions.
114  
119  
115   
    @tparam T The value type of returned `result`.
120   
    @tparam T The value type of returned `result`.
 
121 +
116   
    @param e The error value.
122   
    @param e The error value.
 
123 +
117   
    @param loc The error location.
124   
    @param loc The error location.
118  
125  
119 - 
    @returns A @ref boost::system::result containing an error.
126 + 
    @returns `boost::system::error_code` with `value()` equal to `e` and
 
127 + 
    `category()` equal to `boost::system::generic_category()`.
120  
128  
121 - 
    @see @ref try_value_to_tag, @ref try_value_to, @ref result_for.
129 + 
    @see @ref try_value_to_tag, @ref try_value_to, @ref result_for,
 
130 + 
    <a href="https://www.boost.org/doc/libs/develop/libs/system/doc/html/system.html#ref_generic_category">
 
131 + 
        `boost::system::generic_category`</a>,
 
132 + 
    <a href="https://www.boost.org/doc/libs/master/libs/assert/doc/html/assert.html#source_location_support">
 
133 + 
        `boost::source_location`</a>.
122   
*/
134   
*/
123   
template <class T>
135   
template <class T>
124   
typename result_for<T, value>::type
136   
typename result_for<T, value>::type
125   
result_from_errno(int e, boost::source_location const* loc) noexcept
137   
result_from_errno(int e, boost::source_location const* loc) noexcept
126   
{
138   
{
127   
    system::error_code ec(e, system::generic_category(), loc);
139   
    system::error_code ec(e, system::generic_category(), loc);
128   
    return {system::in_place_error, ec};
140   
    return {system::in_place_error, ec};
129   
}
141   
}
130  
142  
131   
} // namespace json
143   
} // namespace json
132   
} // namespace boost
144   
} // namespace boost
133  
145  
134   
#endif // BOOST_JSON_RESULT_FOR_HPP
146   
#endif // BOOST_JSON_RESULT_FOR_HPP