diff options
Diffstat (limited to 'absl/utility/utility.h')
| -rw-r--r-- | absl/utility/utility.h | 106 |
1 files changed, 74 insertions, 32 deletions
diff --git a/absl/utility/utility.h b/absl/utility/utility.h index 4f4a0624d3db..732cd4c59245 100644 --- a/absl/utility/utility.h +++ b/absl/utility/utility.h @@ -12,36 +12,39 @@ // See the License for the specific language governing permissions and // limitations under the License. // - -// absl/utility:utility is an extension of the <utility> header +// This header file contains C++11 versions of standard <utility> header +// abstractions available within C++14 and C++17, and are designed to be drop-in +// replacement for code compliant with C++14 and C++17. +// +// The following abstractions are defined: // -// It provides stand-ins for C++14's std::integer_sequence and -// related utilities. They are intended to be exactly equivalent. -// - integer_sequence<T, Ints...> == std::integer_sequence<T, Ints...> -// - index_sequence<Ints...> == std::index_sequence<Ints...> -// - make_integer_sequence<T, N> == std::make_integer_sequence<T, N> -// - make_index_sequence<N> == std::make_index_sequence<N> -// - index_sequence_for<Ts...> == std::index_sequence_for<Ts...> +// * integer_sequence<T, Ints...> == std::integer_sequence<T, Ints...> +// * index_sequence<Ints...> == std::index_sequence<Ints...> +// * make_integer_sequence<T, N> == std::make_integer_sequence<T, N> +// * make_index_sequence<N> == std::make_index_sequence<N> +// * index_sequence_for<Ts...> == std::index_sequence_for<Ts...> // -// It also provides the tag types in_place_t, in_place_type_t, and -// in_place_index_t, as well as the constant in_place, and constexpr std::move -// and std::forward impolementations in C++11. +// This header file also provides the tag types `in_place_t`, `in_place_type_t`, +// and `in_place_index_t`, as well as the constant `in_place`, and +// `constexpr` `std::move()` and `std::forward()` implementations in C++11. // // References: +// // http://en.cppreference.com/w/cpp/utility/integer_sequence // http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3658.html // +// // Example: // // Unpack a tuple for use as a function call's argument list. // // template <typename F, typename Tup, size_t... Is> -// auto Impl(F f, const Tup& tup, index_sequence<Is...>) +// auto Impl(F f, const Tup& tup, absl::index_sequence<Is...>) // -> decltype(f(std::get<Is>(tup) ...)) { // return f(std::get<Is>(tup) ...); // } // // template <typename Tup> -// using TupIdxSeq = make_index_sequence<std::tuple_size<Tup>::value>; +// using TupIdxSeq = absl::make_index_sequence<std::tuple_size<Tup>::value>; // // template <typename F, typename Tup> // auto ApplyFromTuple(F f, const Tup& tup) @@ -60,23 +63,36 @@ namespace absl { -// Equivalent to std::integer_sequence. +// integer_sequence +// +// Class template representing a compile-time integer sequence. An instantiation +// of `integer_sequence<T, Ints...>` has a sequence of integers encoded in its +// type through its template arguments (which is a common need when +// working with C++11 variadic templates). `absl::integer_sequence` is designed +// to be a drop-in replacement for C++14's `std::integer_sequence`. +// +// Example: // -// Function templates can deduce compile-time integer sequences by accepting -// an argument of integer_sequence<T, Ints...>. This is a common need when -// working with C++11 variadic templates. +// template< class T, T... Ints > +// void user_function(integer_sequence<T, Ints...>); // -// T - the integer type of the sequence elements -// ...Ints - a parameter pack of T values representing the sequence +// int main() +// { +// // user_function's `T` will be deduced to `int` and `Ints...` +// // will be deduced to `0, 1, 2, 3, 4`. +// user_function(make_integer_sequence<int, 5>()); +// } template <typename T, T... Ints> struct integer_sequence { using value_type = T; static constexpr size_t size() noexcept { return sizeof...(Ints); } }; -// Equivalent to std::index_sequence. +// index_sequence // -// Alias for an integer_sequence of size_t. +// A helper template for an `integer_sequence` of `size_t`, +// `absl::index_sequence` is designed to be a drop-in replacement for C++14's +// `std::index_sequence`. template <size_t... Ints> using index_sequence = integer_sequence<size_t, Ints...>; @@ -113,21 +129,27 @@ struct Gen<T, 0> { // Compile-time sequences of integers -// Equivalent to std::make_integer_sequence. +// make_integer_sequence // -// make_integer_sequence<int, N> is integer_sequence<int, 0, 1, ..., N-1>; +// This template alias is equivalent to +// `integer_sequence<int, 0, 1, ..., N-1>`, and is designed to be a drop-in +// replacement for C++14's `std::make_integer_sequence`. template <typename T, T N> using make_integer_sequence = typename utility_internal::Gen<T, N>::type; -// Equivalent to std::make_index_sequence. +// make_index_sequence // -// make_index_sequence<N> is index_sequence<0, 1, ..., N-1>; +// This template alias is equivalent to `index_sequence<0, 1, ..., N-1>`, +// and is designed to be a drop-in replacement for C++14's +// `std::make_index_sequence`. template <size_t N> using make_index_sequence = make_integer_sequence<size_t, N>; -// Equivalent to std::index_sequence_for. +// index_sequence_for // -// Convert a typename pack into an index sequence of the same length. +// Converts a typename pack into an index sequence of the same length, and +// is designed to be a drop-in replacement for C++14's +// `std::index_sequence_for()` template <typename... Ts> using index_sequence_for = make_index_sequence<sizeof...(Ts)>; @@ -140,8 +162,11 @@ using std::in_place; #else // ABSL_HAVE_STD_OPTIONAL -// Tag type used in order to specify in-place construction, such as with -// absl::optional. +// in_place_t +// +// Tag type used to specify in-place construction, such as with +// `absl::optional`, designed to be a drop-in replacement for C++17's +// `std::in_place_t`. struct in_place_t {}; extern const in_place_t in_place; @@ -150,22 +175,39 @@ extern const in_place_t in_place; #ifdef ABSL_HAVE_STD_ANY using std::in_place_type_t; #else -// Tag types used for in-place construction when the type to construct needs to -// be specified, such as with absl::variant and absl::any. + +// in_place_type_t +// +// Tag type used for in-place construction when the type to construct needs to +// be specified, such as with `absl::any`, designed to be a drop-in replacement +// for C++17's `std::in_place_type_t`. template <typename T> struct in_place_type_t {}; #endif // ABSL_HAVE_STD_ANY +// in_place_index_t +// +// Tag type used for in-place construction when the type to construct needs to +// be specified, such as with `absl::any`, designed to be a drop-in replacement +// for C++17's `std::in_place_index_t`. template <size_t I> struct in_place_index_t {}; // Constexpr move and forward +// move() +// +// A constexpr version of `std::move()`, designed to be a drop-in replacement +// for C++14's `std::move()`. template <typename T> constexpr absl::remove_reference_t<T>&& move(T&& t) noexcept { return static_cast<absl::remove_reference_t<T>&&>(t); } +// forward() +// +// A constexpr version of `std::forward()`, designed to be a drop-in replacement +// for C++14's `std::forward()`. template <typename T> constexpr T&& forward( absl::remove_reference_t<T>& t) noexcept { // NOLINT(runtime/references) |