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
47namespace absl {
48ABSL_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.
54using std::index_sequence;
55using std::index_sequence_for;
56using std::integer_sequence;
57using std::make_index_sequence;
58using std::make_integer_sequence;
59
60namespace utility_internal {
61
62template <typename T>
63struct InPlaceTypeTag {
64 explicit InPlaceTypeTag() = delete;
65 InPlaceTypeTag(const InPlaceTypeTag&) = delete;
66 InPlaceTypeTag& operator=(const InPlaceTypeTag&) = delete;
67};
68
69template <size_t I>
70struct InPlaceIndexTag {
71 explicit InPlaceIndexTag() = delete;
72 InPlaceIndexTag(const InPlaceIndexTag&) = delete;
73 InPlaceIndexTag& operator=(const InPlaceIndexTag&) = delete;
74};
75
76} // namespace utility_internal
77
78// Tag types
79
80#ifdef ABSL_USES_STD_OPTIONAL
81
82using std::in_place_t;
83using std::in_place;
84
85#else // ABSL_USES_STD_OPTIONAL
86
87// in_place_t
88//
89// Tag type used to specify in-place construction, such as with
90// `absl::optional`, designed to be a drop-in replacement for C++17's
91// `std::in_place_t`.
92struct in_place_t {};
93
94ABSL_INTERNAL_INLINE_CONSTEXPR(in_place_t, in_place, {});
95
96#endif // ABSL_USES_STD_OPTIONAL
97
98#if defined(ABSL_USES_STD_ANY) || defined(ABSL_USES_STD_VARIANT)
99using std::in_place_type;
100using std::in_place_type_t;
101#else
102
103// in_place_type_t
104//
105// Tag type used for in-place construction when the type to construct needs to
106// be specified, such as with `absl::any`, designed to be a drop-in replacement
107// for C++17's `std::in_place_type_t`.
108template <typename T>
109using in_place_type_t = void (*)(utility_internal::InPlaceTypeTag<T>);
110
111template <typename T>
112void in_place_type(utility_internal::InPlaceTypeTag<T>) {}
113#endif // ABSL_USES_STD_ANY || ABSL_USES_STD_VARIANT
114
115#ifdef ABSL_USES_STD_VARIANT
116using std::in_place_index;
117using std::in_place_index_t;
118#else
119
120// in_place_index_t
121//
122// Tag type used for in-place construction when the type to construct needs to
123// be specified, such as with `absl::any`, designed to be a drop-in replacement
124// for C++17's `std::in_place_index_t`.
125template <size_t I>
126using in_place_index_t = void (*)(utility_internal::InPlaceIndexTag<I>);
127
128template <size_t I>
129void in_place_index(utility_internal::InPlaceIndexTag<I>) {}
130#endif // ABSL_USES_STD_VARIANT
131
132// Constexpr move and forward
133
134// move()
135//
136// A constexpr version of `std::move()`, designed to be a drop-in replacement
137// for C++14's `std::move()`.
138template <typename T>
139constexpr absl::remove_reference_t<T>&& move(T&& t) noexcept {
140 return static_cast<absl::remove_reference_t<T>&&>(t);
141}
142
143// forward()
144//
145// A constexpr version of `std::forward()`, designed to be a drop-in replacement
146// for C++14's `std::forward()`.
147template <typename T>
148constexpr T&& forward(
149 absl::remove_reference_t<T>& t) noexcept { // NOLINT(runtime/references)
150 return static_cast<T&&>(t);
151}
152
153namespace utility_internal {
154// Helper method for expanding tuple into a called method.
155template <typename Functor, typename Tuple, std::size_t... Indexes>
156auto apply_helper(Functor&& functor, Tuple&& t, index_sequence<Indexes...>)
157 -> decltype(absl::base_internal::invoke(
158 absl::forward<Functor>(functor),
159 std::get<Indexes>(absl::forward<Tuple>(t))...)) {
160 return absl::base_internal::invoke(
161 absl::forward<Functor>(functor),
162 std::get<Indexes>(absl::forward<Tuple>(t))...);
163}
164
165} // namespace utility_internal
166
167// apply
168//
169// Invokes a Callable using elements of a tuple as its arguments.
170// Each element of the tuple corresponds to an argument of the call (in order).
171// Both the Callable argument and the tuple argument are perfect-forwarded.
172// For member-function Callables, the first tuple element acts as the `this`
173// pointer. `absl::apply` is designed to be a drop-in replacement for C++17's
174// `std::apply`. Unlike C++17's `std::apply`, this is not currently `constexpr`.
175//
176// Example:
177//
178// class Foo {
179// public:
180// void Bar(int);
181// };
182// void user_function1(int, std::string);
183// void user_function2(std::unique_ptr<Foo>);
184// auto user_lambda = [](int, int) {};
185//
186// int main()
187// {
188// std::tuple<int, std::string> tuple1(42, "bar");
189// // Invokes the first user function on int, std::string.
190// absl::apply(&user_function1, tuple1);
191//
192// std::tuple<std::unique_ptr<Foo>> tuple2(absl::make_unique<Foo>());
193// // Invokes the user function that takes ownership of the unique
194// // pointer.
195// absl::apply(&user_function2, std::move(tuple2));
196//
197// auto foo = absl::make_unique<Foo>();
198// std::tuple<Foo*, int> tuple3(foo.get(), 42);
199// // Invokes the method Bar on foo with one argument, 42.
200// absl::apply(&Foo::Bar, tuple3);
201//
202// std::tuple<int, int> tuple4(8, 9);
203// // Invokes a lambda.
204// absl::apply(user_lambda, tuple4);
205// }
206template <typename Functor, typename Tuple>
207auto apply(Functor&& functor, Tuple&& t)
208 -> decltype(utility_internal::apply_helper(
209 absl::forward<Functor>(functor), absl::forward<Tuple>(t),
210 absl::make_index_sequence<std::tuple_size<
211 typename std::remove_reference<Tuple>::type>::value>{})) {
212 return utility_internal::apply_helper(
213 absl::forward<Functor>(functor), absl::forward<Tuple>(t),
214 absl::make_index_sequence<std::tuple_size<
215 typename std::remove_reference<Tuple>::type>::value>{});
216}
217
218// exchange
219//
220// Replaces the value of `obj` with `new_value` and returns the old value of
221// `obj`. `absl::exchange` is designed to be a drop-in replacement for C++14's
222// `std::exchange`.
223//
224// Example:
225//
226// Foo& operator=(Foo&& other) {
227// ptr1_ = absl::exchange(other.ptr1_, nullptr);
228// int1_ = absl::exchange(other.int1_, -1);
229// return *this;
230// }
231template <typename T, typename U = T>
232T exchange(T& obj, U&& new_value) {
233 T old_value = absl::move(obj);
234 obj = absl::forward<U>(new_value);
235 return old_value;
236}
237
238namespace utility_internal {
239template <typename T, typename Tuple, size_t... I>
240T make_from_tuple_impl(Tuple&& tup, absl::index_sequence<I...>) {
241 return T(std::get<I>(std::forward<Tuple>(tup))...);
242}
243} // namespace utility_internal
244
245// make_from_tuple
246//
247// Given the template parameter type `T` and a tuple of arguments
248// `std::tuple(arg0, arg1, ..., argN)` constructs an object of type `T` as if by
249// calling `T(arg0, arg1, ..., argN)`.
250//
251// Example:
252//
253// std::tuple<const char*, size_t> args("hello world", 5);
254// auto s = absl::make_from_tuple<std::string>(args);
255// assert(s == "hello");
256//
257template <typename T, typename Tuple>
258constexpr T make_from_tuple(Tuple&& tup) {
259 return utility_internal::make_from_tuple_impl<T>(
260 std::forward<Tuple>(tup),
261 absl::make_index_sequence<
262 std::tuple_size<absl::decay_t<Tuple>>::value>{});
263}
264
265ABSL_NAMESPACE_END
266} // namespace absl
267
268#endif // ABSL_UTILITY_UTILITY_H_
269