about summary refs log tree commit diff
path: root/absl/utility
diff options
context:
space:
mode:
Diffstat (limited to 'absl/utility')
-rw-r--r--absl/utility/utility.h106
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)