1 // Copyright 2017 The Abseil Authors.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // https://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 //
15 // This header file contains C++14 versions of standard <utility> header
16 // abstractions available within C++17, and are designed to be drop-in
17 // replacement for code compliant with C++14 and C++17.
18 //
19 // The following abstractions are defined:
20 //
21 // * apply<Functor, Tuple> == std::apply<Functor, Tuple>
22 // * exchange<T> == std::exchange<T>
23 // * make_from_tuple<T> == std::make_from_tuple<T>
24 //
25 // This header file also provides the tag types `in_place_t`, `in_place_type_t`,
26 // and `in_place_index_t`, as well as the constant `in_place`, and
27 // `constexpr` `std::move()` and `std::forward()` implementations in C++11.
28 //
29 // References:
30 //
31 // https://en.cppreference.com/w/cpp/utility/apply
32 // http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3658.html
33
34 #ifndef ABSL_UTILITY_UTILITY_H_
35 #define ABSL_UTILITY_UTILITY_H_
36
37 #include <cstddef>
38 #include <cstdlib>
39 #include <tuple>
40 #include <utility>
41
42 #include "absl/base/config.h"
43 #include "absl/base/internal/inline_variable.h"
44 #include "absl/base/internal/invoke.h"
45 #include "absl/meta/type_traits.h"
46
47 namespace absl {
48 ABSL_NAMESPACE_BEGIN
49
50 // Historical note: Abseil once provided implementations of these
51 // abstractions for platforms that had not yet provided them. Those
52 // platforms are no longer supported. New code should simply use the
53 // the ones from std directly.
54 using std::exchange;
55 using std::forward;
56 using std::index_sequence;
57 using std::index_sequence_for;
58 using std::integer_sequence;
59 using std::make_index_sequence;
60 using std::make_integer_sequence;
61 using std::move;
62
63 namespace utility_internal {
64
65 template <typename T>
66 struct InPlaceTypeTag {
67 explicit InPlaceTypeTag() = delete;
68 InPlaceTypeTag(const InPlaceTypeTag&) = delete;
69 InPlaceTypeTag& operator=(const InPlaceTypeTag&) = delete;
70 };
71
72 template <size_t I>
73 struct InPlaceIndexTag {
74 explicit InPlaceIndexTag() = delete;
75 InPlaceIndexTag(const InPlaceIndexTag&) = delete;
76 InPlaceIndexTag& operator=(const InPlaceIndexTag&) = delete;
77 };
78
79 } // namespace utility_internal
80
81 // Tag types
82
83 #ifdef ABSL_USES_STD_OPTIONAL
84
85 using std::in_place_t;
86 using std::in_place;
87
88 #else // ABSL_USES_STD_OPTIONAL
89
90 // in_place_t
91 //
92 // Tag type used to specify in-place construction, such as with
93 // `absl::optional`, designed to be a drop-in replacement for C++17's
94 // `std::in_place_t`.
95 struct in_place_t {};
96
97 ABSL_INTERNAL_INLINE_CONSTEXPR(in_place_t, in_place, {});
98
99 #endif // ABSL_USES_STD_OPTIONAL
100
101 #if defined(ABSL_USES_STD_ANY) || defined(ABSL_USES_STD_VARIANT)
102 using std::in_place_type;
103 using std::in_place_type_t;
104 #else
105
106 // in_place_type_t
107 //
108 // Tag type used for in-place construction when the type to construct needs to
109 // be specified, such as with `absl::any`, designed to be a drop-in replacement
110 // for C++17's `std::in_place_type_t`.
111 template <typename T>
112 using in_place_type_t = void (*)(utility_internal::InPlaceTypeTag<T>);
113
114 template <typename T>
in_place_type(utility_internal::InPlaceTypeTag<T>)115 void in_place_type(utility_internal::InPlaceTypeTag<T>) {}
116 #endif // ABSL_USES_STD_ANY || ABSL_USES_STD_VARIANT
117
118 #ifdef ABSL_USES_STD_VARIANT
119 using std::in_place_index;
120 using std::in_place_index_t;
121 #else
122
123 // in_place_index_t
124 //
125 // Tag type used for in-place construction when the type to construct needs to
126 // be specified, such as with `absl::any`, designed to be a drop-in replacement
127 // for C++17's `std::in_place_index_t`.
128 template <size_t I>
129 using in_place_index_t = void (*)(utility_internal::InPlaceIndexTag<I>);
130
131 template <size_t I>
in_place_index(utility_internal::InPlaceIndexTag<I>)132 void in_place_index(utility_internal::InPlaceIndexTag<I>) {}
133 #endif // ABSL_USES_STD_VARIANT
134
135 namespace utility_internal {
136 // Helper method for expanding tuple into a called method.
137 template <typename Functor, typename Tuple, std::size_t... Indexes>
138 auto apply_helper(Functor&& functor, Tuple&& t, index_sequence<Indexes...>)
139 -> decltype(absl::base_internal::invoke(
140 absl::forward<Functor>(functor),
141 std::get<Indexes>(absl::forward<Tuple>(t))...)) {
142 return absl::base_internal::invoke(
143 absl::forward<Functor>(functor),
144 std::get<Indexes>(absl::forward<Tuple>(t))...);
145 }
146
147 } // namespace utility_internal
148
149 // apply
150 //
151 // Invokes a Callable using elements of a tuple as its arguments.
152 // Each element of the tuple corresponds to an argument of the call (in order).
153 // Both the Callable argument and the tuple argument are perfect-forwarded.
154 // For member-function Callables, the first tuple element acts as the `this`
155 // pointer. `absl::apply` is designed to be a drop-in replacement for C++17's
156 // `std::apply`. Unlike C++17's `std::apply`, this is not currently `constexpr`.
157 //
158 // Example:
159 //
160 // class Foo {
161 // public:
162 // void Bar(int);
163 // };
164 // void user_function1(int, std::string);
165 // void user_function2(std::unique_ptr<Foo>);
166 // auto user_lambda = [](int, int) {};
167 //
168 // int main()
169 // {
170 // std::tuple<int, std::string> tuple1(42, "bar");
171 // // Invokes the first user function on int, std::string.
172 // absl::apply(&user_function1, tuple1);
173 //
174 // std::tuple<std::unique_ptr<Foo>> tuple2(absl::make_unique<Foo>());
175 // // Invokes the user function that takes ownership of the unique
176 // // pointer.
177 // absl::apply(&user_function2, std::move(tuple2));
178 //
179 // auto foo = absl::make_unique<Foo>();
180 // std::tuple<Foo*, int> tuple3(foo.get(), 42);
181 // // Invokes the method Bar on foo with one argument, 42.
182 // absl::apply(&Foo::Bar, tuple3);
183 //
184 // std::tuple<int, int> tuple4(8, 9);
185 // // Invokes a lambda.
186 // absl::apply(user_lambda, tuple4);
187 // }
188 template <typename Functor, typename Tuple>
189 auto apply(Functor&& functor, Tuple&& t)
190 -> decltype(utility_internal::apply_helper(
191 absl::forward<Functor>(functor), absl::forward<Tuple>(t),
192 absl::make_index_sequence<std::tuple_size<
193 typename std::remove_reference<Tuple>::type>::value>{})) {
194 return utility_internal::apply_helper(
195 absl::forward<Functor>(functor), absl::forward<Tuple>(t),
196 absl::make_index_sequence<std::tuple_size<
197 typename std::remove_reference<Tuple>::type>::value>{});
198 }
199
200 namespace utility_internal {
201 template <typename T, typename Tuple, size_t... I>
make_from_tuple_impl(Tuple && tup,absl::index_sequence<I...>)202 T make_from_tuple_impl(Tuple&& tup, absl::index_sequence<I...>) {
203 return T(std::get<I>(std::forward<Tuple>(tup))...);
204 }
205 } // namespace utility_internal
206
207 // make_from_tuple
208 //
209 // Given the template parameter type `T` and a tuple of arguments
210 // `std::tuple(arg0, arg1, ..., argN)` constructs an object of type `T` as if by
211 // calling `T(arg0, arg1, ..., argN)`.
212 //
213 // Example:
214 //
215 // std::tuple<const char*, size_t> args("hello world", 5);
216 // auto s = absl::make_from_tuple<std::string>(args);
217 // assert(s == "hello");
218 //
219 template <typename T, typename Tuple>
make_from_tuple(Tuple && tup)220 constexpr T make_from_tuple(Tuple&& tup) {
221 return utility_internal::make_from_tuple_impl<T>(
222 std::forward<Tuple>(tup),
223 absl::make_index_sequence<
224 std::tuple_size<absl::decay_t<Tuple>>::value>{});
225 }
226
227 ABSL_NAMESPACE_END
228 } // namespace absl
229
230 #endif // ABSL_UTILITY_UTILITY_H_
231