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++11 versions of standard <utility> header
16// abstractions available within C++14 and 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// * integer_sequence<T, Ints...> == std::integer_sequence<T, Ints...>
22// * index_sequence<Ints...> == std::index_sequence<Ints...>
23// * make_integer_sequence<T, N> == std::make_integer_sequence<T, N>
24// * make_index_sequence<N> == std::make_index_sequence<N>
25// * index_sequence_for<Ts...> == std::index_sequence_for<Ts...>
26// * apply<Functor, Tuple> == std::apply<Functor, Tuple>
27// * exchange<T> == std::exchange<T>
28// * make_from_tuple<T> == std::make_from_tuple<T>
29//
30// This header file also provides the tag types `in_place_t`, `in_place_type_t`,
31// and `in_place_index_t`, as well as the constant `in_place`, and
32// `constexpr` `std::move()` and `std::forward()` implementations in C++11.
33//
34// References:
35//
36// https://en.cppreference.com/w/cpp/utility/integer_sequence
37// https://en.cppreference.com/w/cpp/utility/apply
38// http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3658.html
39
40#ifndef ABSL_UTILITY_UTILITY_H_
41#define ABSL_UTILITY_UTILITY_H_
42
43#include <cstddef>
44#include <cstdlib>
45#include <tuple>
46#include <utility>
47
48#include "absl/base/config.h"
49#include "absl/base/internal/inline_variable.h"
50#include "absl/base/internal/invoke.h"
51#include "absl/meta/type_traits.h"
52
53namespace absl {
54
55// integer_sequence
56//
57// Class template representing a compile-time integer sequence. An instantiation
58// of `integer_sequence<T, Ints...>` has a sequence of integers encoded in its
59// type through its template arguments (which is a common need when
60// working with C++11 variadic templates). `absl::integer_sequence` is designed
61// to be a drop-in replacement for C++14's `std::integer_sequence`.
62//
63// Example:
64//
65// template< class T, T... Ints >
66// void user_function(integer_sequence<T, Ints...>);
67//
68// int main()
69// {
70// // user_function's `T` will be deduced to `int` and `Ints...`
71// // will be deduced to `0, 1, 2, 3, 4`.
72// user_function(make_integer_sequence<int, 5>());
73// }
74template <typename T, T... Ints>
75struct integer_sequence {
76 using value_type = T;
77 static constexpr size_t size() noexcept { return sizeof...(Ints); }
78};
79
80// index_sequence
81//
82// A helper template for an `integer_sequence` of `size_t`,
83// `absl::index_sequence` is designed to be a drop-in replacement for C++14's
84// `std::index_sequence`.
85template <size_t... Ints>
86using index_sequence = integer_sequence<size_t, Ints...>;
87
88namespace utility_internal {
89
90template <typename Seq, size_t SeqSize, size_t Rem>
91struct Extend;
92
93// Note that SeqSize == sizeof...(Ints). It's passed explicitly for efficiency.
94template <typename T, T... Ints, size_t SeqSize>
95struct Extend<integer_sequence<T, Ints...>, SeqSize, 0> {
96 using type = integer_sequence<T, Ints..., (Ints + SeqSize)...>;
97};
98
99template <typename T, T... Ints, size_t SeqSize>
100struct Extend<integer_sequence<T, Ints...>, SeqSize, 1> {
101 using type = integer_sequence<T, Ints..., (Ints + SeqSize)..., 2 * SeqSize>;
102};
103
104// Recursion helper for 'make_integer_sequence<T, N>'.
105// 'Gen<T, N>::type' is an alias for 'integer_sequence<T, 0, 1, ... N-1>'.
106template <typename T, size_t N>
107struct Gen {
108 using type =
109 typename Extend<typename Gen<T, N / 2>::type, N / 2, N % 2>::type;
110};
111
112template <typename T>
113struct Gen<T, 0> {
114 using type = integer_sequence<T>;
115};
116
117template <typename T>
118struct InPlaceTypeTag {
119 explicit InPlaceTypeTag() = delete;
120 InPlaceTypeTag(const InPlaceTypeTag&) = delete;
121 InPlaceTypeTag& operator=(const InPlaceTypeTag&) = delete;
122};
123
124template <size_t I>
125struct InPlaceIndexTag {
126 explicit InPlaceIndexTag() = delete;
127 InPlaceIndexTag(const InPlaceIndexTag&) = delete;
128 InPlaceIndexTag& operator=(const InPlaceIndexTag&) = delete;
129};
130
131} // namespace utility_internal
132
133// Compile-time sequences of integers
134
135// make_integer_sequence
136//
137// This template alias is equivalent to
138// `integer_sequence<int, 0, 1, ..., N-1>`, and is designed to be a drop-in
139// replacement for C++14's `std::make_integer_sequence`.
140template <typename T, T N>
141using make_integer_sequence = typename utility_internal::Gen<T, N>::type;
142
143// make_index_sequence
144//
145// This template alias is equivalent to `index_sequence<0, 1, ..., N-1>`,
146// and is designed to be a drop-in replacement for C++14's
147// `std::make_index_sequence`.
148template <size_t N>
149using make_index_sequence = make_integer_sequence<size_t, N>;
150
151// index_sequence_for
152//
153// Converts a typename pack into an index sequence of the same length, and
154// is designed to be a drop-in replacement for C++14's
155// `std::index_sequence_for()`
156template <typename... Ts>
157using index_sequence_for = make_index_sequence<sizeof...(Ts)>;
158
159// Tag types
160
161#ifdef ABSL_HAVE_STD_OPTIONAL
162
163using std::in_place_t;
164using std::in_place;
165
166#else // ABSL_HAVE_STD_OPTIONAL
167
168// in_place_t
169//
170// Tag type used to specify in-place construction, such as with
171// `absl::optional`, designed to be a drop-in replacement for C++17's
172// `std::in_place_t`.
173struct in_place_t {};
174
175ABSL_INTERNAL_INLINE_CONSTEXPR(in_place_t, in_place, {});
176
177#endif // ABSL_HAVE_STD_OPTIONAL
178
179#if defined(ABSL_HAVE_STD_ANY) || defined(ABSL_HAVE_STD_VARIANT)
180using std::in_place_type;
181using std::in_place_type_t;
182#else
183
184// in_place_type_t
185//
186// Tag type used for in-place construction when the type to construct needs to
187// be specified, such as with `absl::any`, designed to be a drop-in replacement
188// for C++17's `std::in_place_type_t`.
189template <typename T>
190using in_place_type_t = void (*)(utility_internal::InPlaceTypeTag<T>);
191
192template <typename T>
193void in_place_type(utility_internal::InPlaceTypeTag<T>) {}
194#endif // ABSL_HAVE_STD_ANY || ABSL_HAVE_STD_VARIANT
195
196#ifdef ABSL_HAVE_STD_VARIANT
197using std::in_place_index;
198using std::in_place_index_t;
199#else
200
201// in_place_index_t
202//
203// Tag type used for in-place construction when the type to construct needs to
204// be specified, such as with `absl::any`, designed to be a drop-in replacement
205// for C++17's `std::in_place_index_t`.
206template <size_t I>
207using in_place_index_t = void (*)(utility_internal::InPlaceIndexTag<I>);
208
209template <size_t I>
210void in_place_index(utility_internal::InPlaceIndexTag<I>) {}
211#endif // ABSL_HAVE_STD_VARIANT
212
213// Constexpr move and forward
214
215// move()
216//
217// A constexpr version of `std::move()`, designed to be a drop-in replacement
218// for C++14's `std::move()`.
219template <typename T>
220constexpr absl::remove_reference_t<T>&& move(T&& t) noexcept {
221 return static_cast<absl::remove_reference_t<T>&&>(t);
222}
223
224// forward()
225//
226// A constexpr version of `std::forward()`, designed to be a drop-in replacement
227// for C++14's `std::forward()`.
228template <typename T>
229constexpr T&& forward(
230 absl::remove_reference_t<T>& t) noexcept { // NOLINT(runtime/references)
231 return static_cast<T&&>(t);
232}
233
234namespace utility_internal {
235// Helper method for expanding tuple into a called method.
236template <typename Functor, typename Tuple, std::size_t... Indexes>
237auto apply_helper(Functor&& functor, Tuple&& t, index_sequence<Indexes...>)
238 -> decltype(absl::base_internal::Invoke(
239 absl::forward<Functor>(functor),
240 std::get<Indexes>(absl::forward<Tuple>(t))...)) {
241 return absl::base_internal::Invoke(
242 absl::forward<Functor>(functor),
243 std::get<Indexes>(absl::forward<Tuple>(t))...);
244}
245
246} // namespace utility_internal
247
248// apply
249//
250// Invokes a Callable using elements of a tuple as its arguments.
251// Each element of the tuple corresponds to an argument of the call (in order).
252// Both the Callable argument and the tuple argument are perfect-forwarded.
253// For member-function Callables, the first tuple element acts as the `this`
254// pointer. `absl::apply` is designed to be a drop-in replacement for C++17's
255// `std::apply`. Unlike C++17's `std::apply`, this is not currently `constexpr`.
256//
257// Example:
258//
259// class Foo {
260// public:
261// void Bar(int);
262// };
263// void user_function1(int, std::string);
264// void user_function2(std::unique_ptr<Foo>);
265// auto user_lambda = [](int, int) {};
266//
267// int main()
268// {
269// std::tuple<int, std::string> tuple1(42, "bar");
270// // Invokes the first user function on int, std::string.
271// absl::apply(&user_function1, tuple1);
272//
273// std::tuple<std::unique_ptr<Foo>> tuple2(absl::make_unique<Foo>());
274// // Invokes the user function that takes ownership of the unique
275// // pointer.
276// absl::apply(&user_function2, std::move(tuple2));
277//
278// auto foo = absl::make_unique<Foo>();
279// std::tuple<Foo*, int> tuple3(foo.get(), 42);
280// // Invokes the method Bar on foo with one argument, 42.
281// absl::apply(&Foo::Bar, tuple3);
282//
283// std::tuple<int, int> tuple4(8, 9);
284// // Invokes a lambda.
285// absl::apply(user_lambda, tuple4);
286// }
287template <typename Functor, typename Tuple>
288auto apply(Functor&& functor, Tuple&& t)
289 -> decltype(utility_internal::apply_helper(
290 absl::forward<Functor>(functor), absl::forward<Tuple>(t),
291 absl::make_index_sequence<std::tuple_size<
292 typename std::remove_reference<Tuple>::type>::value>{})) {
293 return utility_internal::apply_helper(
294 absl::forward<Functor>(functor), absl::forward<Tuple>(t),
295 absl::make_index_sequence<std::tuple_size<
296 typename std::remove_reference<Tuple>::type>::value>{});
297}
298
299// exchange
300//
301// Replaces the value of `obj` with `new_value` and returns the old value of
302// `obj`. `absl::exchange` is designed to be a drop-in replacement for C++14's
303// `std::exchange`.
304//
305// Example:
306//
307// Foo& operator=(Foo&& other) {
308// ptr1_ = absl::exchange(other.ptr1_, nullptr);
309// int1_ = absl::exchange(other.int1_, -1);
310// return *this;
311// }
312template <typename T, typename U = T>
313T exchange(T& obj, U&& new_value) {
314 T old_value = absl::move(obj);
315 obj = absl::forward<U>(new_value);
316 return old_value;
317}
318
319namespace utility_internal {
320template <typename T, typename Tuple, size_t... I>
321T make_from_tuple_impl(Tuple&& tup, absl::index_sequence<I...>) {
322 return T(std::get<I>(std::forward<Tuple>(tup))...);
323}
324} // namespace utility_internal
325
326// make_from_tuple
327//
328// Given the template parameter type `T` and a tuple of arguments
329// `std::tuple(arg0, arg1, ..., argN)` constructs an object of type `T` as if by
330// calling `T(arg0, arg1, ..., argN)`.
331//
332// Example:
333//
334// std::tuple<const char*, size_t> args("hello world", 5);
335// auto s = absl::make_from_tuple<std::string>(args);
336// assert(s == "hello");
337//
338template <typename T, typename Tuple>
339constexpr T make_from_tuple(Tuple&& tup) {
340 return utility_internal::make_from_tuple_impl<T>(
341 std::forward<Tuple>(tup),
342 absl::make_index_sequence<
343 std::tuple_size<absl::decay_t<Tuple>>::value>{});
344}
345
346} // namespace absl
347
348#endif // ABSL_UTILITY_UTILITY_H_
349