Changes imported from Abseil "staging" branch:

  - 06c8c67f5a564d00696e023060f05a5c34e7e164 IWYU | absl/base by Juemin Yang <jueminyang@google.com>
  - 2b1a054a09bda55843b449843b2a125741e936e7 Internal refactoring by Greg Miller <jgm@google.com>
  - f43f7f1f91bee26b5ddcd0c5bbbc47cb977aef77 Make std::hash<absl::optional<T>> to be standard compliant: by Xiaoyi Zhang <zhangxy@google.com>
  - 539bad2ebc22e610e1f292285a30a87945bc663e Update utility.h to Abseil standards by Tom Manshreck <shreck@google.com>
  - d05ec10a5f16a5d6640e0db91ecc7ab3ea971fd4 Add a test for absl::Barrier. by Derek Mauro <dmauro@google.com>
  - d707e27acb3c06f0d74c5f7ad7861e3841a5471f Run leak-checking tool over all outbound code. by Daniel Katz <katzdm@google.com>
  - 55f07f482a50422b8f99f7176374a19d0d473c5f Add alignas(16) to uint128. by Alex Strelnikov <strel@google.com>
  - 94999b7edde82308f736fb939501537ee9edbca6 Update attributes.h to Abseil standards by Tom Manshreck <shreck@google.com>
  - 321bed0061c41b53d0206ad4865528c00dd6d825 Test git merge + piper cl process by Juemin Yang <jueminyang@google.com>
  - 69920e7351a1053a7f4940bbde1768e839ce84bc Adds support for "/etc/localtime" as an embedded time zon... by Greg Miller <jgm@google.com>
  - 6839c06bf232903d3a9cbffa6eb2c960db78e67b Add copyright notices to inlined_vector code. by Greg Falcon <gfalcon@google.com>
  - 4e2714f6266263515cdfd31675c30c6ed6f98e1a Adding Apache 2.0 License by Gennadiy Civil <misterg@google.com>
  - 7402e7594016a4cd0a8b823fe6bc1bad1874bb85 IWYU | absl/utility by Juemin Yang <jueminyang@google.com>
  - 271a3812337eed97c412042738482688a80e19bd IWYU | absl/memory by Juemin Yang <jueminyang@google.com>
  - 32bda13a8098c2b06e25a5cf7bb782d6b79eb006 IWYU | absl/numeric by Juemin Yang <jueminyang@google.com>
  - 62d375cedc133108904bc06e340e303091a565df Remove "no_test"-annotations on span_test_noexceptions. by Daniel Katz <katzdm@google.com>
  - ebcbae9a55a93a7f1bb6862edc2715a6d9877206 Move CI-testing support files out of public-facing reposi... by Daniel Katz <katzdm@google.com>
  - d3f05eff4daa6030bfacb31cca0f9213fb702247 Fixes ToInt64Minutes() and ToInt64Hours() to properly sat... by Greg Miller <jgm@google.com>
  - b8dfae3facb6bb002622f083a10d14448f19e6e0 Fix typo. by Abseil Team <absl-team@google.com>
  - 150f03baa0afa231c2fc01597ea2321da586caba Update README.md by Yilei Yang <yileiyang@google.com>
  - 05276aa837dd081686518fd27bda4bd206ac4443 Adding Apache 2.0 License by Gennadiy Civil <misterg@google.com>
  - 37bf8e223e79ad06a195e28db9499e0c3d140f73 IWYU | absl/container by Juemin Yang <jueminyang@google.com>
  - 49164928f220978a32f88d16a55549bdf871daef IWYU | absl/algorithm by Juemin Yang <jueminyang@google.com>
  - a6804734e129039f9580a4fcd0f66425d0d0ac30 Move throw delegate wrappers to an internal namespace. by Greg Falcon <gfalcon@google.com>
  - ac83e73f67f593e2aff957b2be0b28e59c552a71 Fix error in comment stripping directives. by Greg Falcon <gfalcon@google.com>
  - e018a24185a984e787fb81a75fc35b74ad3a4d3d Update copyright headers all BUILD files by Gennadiy Civil <misterg@google.com>
  - a3be0990bfd76b0dec76bd85cecfa4dcec68b3ea Fix closing namespace comment typo. by Abseil Team <absl-team@google.com>
  - be3e3c4327e4f83949e0f29fd7a190d7eaa8b50b Update TODO by Abseil Team <absl-team@google.com>
  - f56a5d6f72685d92bb9c2905841b950d8177210c Add test-coverage for leak-sanitizer. by Daniel Katz <katzdm@google.com>
  - 7694bf161c7e00fdd08bfadc2aaf8e0fb09335f8 span.h: further touch up wording around the std::initiali... by Abseil Team <absl-team@google.com>
  - 3a12e081c0f8b359973e020d1e91f65356548ebc Update time.h to Abseil standards by Tom Manshreck <shreck@google.com>
  - 48d28f6468129420f4b20d451dca8e08012a7a77 Remove references to google from comments in Abseil. by Greg Falcon <gfalcon@google.com>
  - 773e34402d15fcad6370d5ed2430482d17db910d Rename the ExpectTime macro to match Abseil naming conven... by Greg Falcon <gfalcon@google.com>
  - 774d2ff1fe26c7313b301ff203e83e1aaac86627 Internal change. by Daniel Katz <katzdm@google.com>
  - 2e8a5830e95c8a1b839721bb2f1d4f5c85b9fb60 Fix typo in comment (missing '*' on a pointer). by Abseil Team <absl-team@google.com>
  - 458106feb707cf9609dd243713bde44aa9679e2a Correct capitalization: github -> GitHub by Yilei Yang <yileiyang@google.com>
  - af440725f02c2a83ca5cbaf176e1142f9e9d9b2f Update copyright headers by Gennadiy Civil <misterg@google.com>
  - 05b1118cce4ab87d23c33d48e64a96bcfec08761 Update copyright headers by Gennadiy Civil <misterg@google.com>
  - d5c6669a62d047156bb77055c5da03ee1b3c61b9 Update Abseil README to include descriptions of the inclu... by Tom Manshreck <shreck@google.com>
  - 3cd7e4663dddc840087469a6495f6cf433bfad8d Update copyright headers in //base by Tom Manshreck <shreck@google.com>
  - 7a876da657cd6698c5da2008a582d52eedc85dd1 Update strings overview with robust string library docume... by Tom Manshreck <shreck@google.com>
  - d9e3d0768d6f1c77d30992bdbef7b47ec92994bb Update copyright headers all BUILD files by Abseil Team <absl-team@google.com>
  - 6fe942728bceb0625f7c79b2840c4a6154d076b3 Make InlinedVector, FixedArray, and Span's at() throw on ... by Jon Cohen <cohenjon@google.com>
  - 5b52d5ec6cb9fbb07fc2e2fa020bd3eeb48c4953 Update clock.h to Abseil standards by Tom Manshreck <shreck@google.com>
  - c03c1ca3aee8bb7e40aa0315f6c432d31a72c30c Update //algorithm copyright headers by Tom Manshreck <shreck@google.com>
  - d46f40ddc596aaacb0459351d0e4aa6871289fa2 Temporarily prevent running mutex_test on crosstool17, wh... by Jon Cohen <cohenjon@google.com>
  - 61f11476189df68edfb9908308d677a91f03ff67 Update copyright headers in //container by Tom Manshreck <shreck@google.com>
  - 91832c00948954edf0b3dda12219c9a0202421ac Update copyright headers for //synchronization by Tom Manshreck <shreck@google.com>
  - 4e09100264b4585af6b4508ff35b9c627ac1f1ce Update copyright headers all BUILD files by Gennadiy Civil <misterg@google.com>
  - 13a0e8aebedec0f95b33750cbcd6b5548619b2a5 Update copyright headers in //memory by Tom Manshreck <shreck@google.com>
  - 63e1b9d4fdbcdf097e5276050ad1f76f0053e553 Update copyright headers for //strings (+ one from //nume... by Tom Manshreck <shreck@google.com>
  - 0108e7cfc50777a94c56d00e9c305161364df341 Convert ASSERT and EXPECT to ABSL_RAW_CHECK in helper fun... by Derek Mauro <dmauro@google.com>
  - 0122306fe47a3093248254a1b475c3a1d82abec5 Internal change by Abseil Team <absl-team@google.com>
  - 89c0c2698c98a12cd63172eeb02063b2f67e7c81 #absl Fix comment. by Abseil Team <absl-team@google.com>
  - 6621cc1ff54800e0aadb5e3071dbaa84b2077ceb Publishing contributing guidelines. by Gennadiy Civil <misterg@google.com>
  - e48c5be3c75e794b3e3827d40915b01fe1a1afc5 Avoid PRIdPTR.  Cast to long long and use %lld insted. by Abseil Team <absl-team@google.com>
  - 2640ea4a260d89b94b07a3142660327e47db33fd No algorithmic changes. by Abseil Team <absl-team@google.com>
  - 1bc6c1bad17754f5d84963bf1d0db279402a0a1d Internal change. by Derek Mauro <dmauro@google.com>
  - 6845d24733e8c95bebde825ba78a2abfd9e35bdb span.h: fix up incorrect wording around lvalues. by Abseil Team <absl-team@google.com>
  - d8f5caee721e252e5f9b1080fb996363f498ac28 Add more exaustive Mutex testing. by Derek Mauro <dmauro@google.com>
  - e8b4cb053eb98858eef10cc53280b6ed5d6815a7 Change Span::subspan to not call into a deprecated constr... by Jon Cohen <cohenjon@google.com>
  - 49c36a82b3114926390557670aaaf0ea25b5760c s/std::size_t/size_t/g by Jon Cohen <cohenjon@google.com>
  - e17487c3c4d4a99f2fd8bc3e42176fc3171614d1 Account for the case of timeval::tv_sec being smaller than by Abseil Team <absl-team@google.com>
  - ecbb89d5fb98483e777c03d97ac02d7b7b54985e Alias absl::string_view to std::string_view when C++17 st... by Xiaoyi Zhang <zhangxy@google.com>
  - 6820e5a51459cdbb6a423cbae25a0cc839c85d44 Internal cleanup. by Xiaoyi Zhang <zhangxy@google.com>
  - 6976469b76a6faaf4111a24ddb37f40211ffadae More Span constexpr by Jon Cohen <cohenjon@google.com>
  - 8521c8956eee1125b7759eb272ec4a5a86fcefc5 #absl Fix comment. by Abseil Team <absl-team@google.com>
  - 20eae7a67fde5dd809aa47e5f7de8a493701645e Embed enough zoneinfo data to make time:time_test (under ... by Abseil Team <absl-team@google.com>
  - 841f5d98ceef4a423839ea73ee06c2f47a9b9680 Clean up macros in attributes.h | ATTRIBUTE_INITIAL_EXEC by Juemin Yang <jueminyang@google.com>
  - 83d8b36656e47919b5d0bac82eece897e195697e Update any.h comments to Abseil standards by Tom Manshreck <shreck@google.com>
  - bb3fae11d3459eeae2f63bfd22e65d3193187cc8 Update type_traits.h comments to Abseil standards by Tom Manshreck <shreck@google.com>
  - 992e1b07c0dec64271f8c44f22fd8df3734d0c47 Renamespace CycleClock code. by Greg Falcon <gfalcon@google.com>
  - 08d6fb0594098493ffbc0e737405182638122e7e Eliminate more existing lint warnings by Gennadiy Rozental <rogeeff@google.com>
  - 1cc6fdc71eb777497239f8c3e9168e6c9d40ea53 Update optional.h to Abseil standards by Tom Manshreck <shreck@google.com>
  - baa91747aa55009a9eb31b6072e33db06cfce2d2 Enforce internal namespace symbol reference policy by Gennadiy Rozental <rogeeff@google.com>
  - 939251e39342ce559e5d23fe43799671581f7cf5 Add CycleClock scaling shift to mitigate a possible overf... by Derek Mauro <dmauro@google.com>
  - c6dfdeecea0c7470938bed47c99ea2b2a95889d8 Add constexpr tests for absl::make_optional(). by Xiaoyi Zhang <zhangxy@google.com>
  - 509e949b992db33041d840746fbd05cc01cb206e Alias absl::optional to std::optional when C++17 std::opt... by Xiaoyi Zhang <zhangxy@google.com>
  - a1ae6d96a8826ba75281cac8632a766b5856acaf Remove no_test_* tags from span_test to increase test cov... by Xiaoyi Zhang <zhangxy@google.com>
  - 3c2a43cc09791723c8a324836629644ac44cb9c8 Remove accidental bits of Google-internal code and short ... by Greg Falcon <gfalcon@google.com>
  - 4874d49d496ac0b6ec36f4280a14b2159e7af930 Replaces the macro-generated Duration factory functions e... by Greg Miller <jgm@google.com>
  - 90e62695e03cb4a57e137ca0c3e116b1d802db57 Fix namespacing for a couple files in base/internal, and ... by Greg Falcon <gfalcon@google.com>
  - b0e6e00e34f967924849aaf8c123bba068f093e3 Publishing contributing guidelines. by Gennadiy Civil <misterg@google.com>
  - d74eafbccc3dffa6c25f9b6a2219425a24b5a959 Internal change by Abseil Team <absl-team@google.com>
  - 27477badbbf720265f5b9509b6c0e01913dc0a9f Update escaping.h comments to Abseil standards by Tom Manshreck <shreck@google.com>
  - 67002f55738319c2875197c3b6282de215ec250d adds absl namespace to debugging/stacktrace.h by Behzad Nouri <bnouri@google.com>
  - e608018f7faa384d5b202ac0a4c7a0d5166f4d9c Update string_view.h comments to Abseil standards by Tom Manshreck <shreck@google.com>
  - e884f04d4c648e01ed7dcde2fda80c24e8452047 Exclude strings/ files we are not releasing from OSS univ... by Gennadiy Rozental <rogeeff@google.com>
  - 3f4c4032ed520f2dd10a81d58ef4f399c001c5cc Strip out eventmanager reference from release. by Gennadiy Rozental <rogeeff@google.com>
  - fb0f1c204793c3792bad101dbaa734e7c2a35887 Fix copybara strip comments by Gennadiy Rozental <rogeeff@google.com>
  - 3eaaac942f77c3d41d63d414630403bfd0f6b70c Strip out style guide waivers. by Gennadiy Rozental <rogeeff@google.com>
  - 020e045058173178b51266b99a2a5dc9ed921960 substitute_test portability | MUST_USE_RESULT cast-to-voi... by Juemin Yang <jueminyang@google.com>
  - 86c093bf81d80ff537ed5e8b89225ce75a636220 Internal change. by Derek Mauro <dmauro@google.com>
  - 330375eb952fe78276e75631a28e750d5bfdb198 Prefer absl::FixedTimeZone() over loading "Etc/GMT[-+]<N>". by Abseil Team <absl-team@google.com>
  - 2e07ebee46a8201adc0dfd2c4ddb3df76e524357 Internal change. by Derek Mauro <dmauro@google.com>
  - 1f0c8b78c8ebd66f14cdf39fcba9f4c9986dcdca ::absl -> absl by Gennadiy Rozental <rogeeff@google.com>
  - ad163566d12ea08f1da2c23931eeacfffc564139 Avoid old style loops where possible. by Gennadiy Rozental <rogeeff@google.com>
  - bce2108818fe57b5617ce0090ddd4f753808f0a1 Update comments in str_cat.h in line with recent changes. by Abseil Team <absl-team@google.com>
  - cfd593a80f4897256f2ce1ea0be55dc14e3fcad4 Copybara-out gtl aliases. by Gennadiy Rozental <rogeeff@google.com>
  - 584f1524d717993c1a16093caccd9ed2b1e5409e Fix a warning for Windows/Kokoro time_test.cc. by Daniel Katz <katzdm@google.com>
  (And 562 more changes)

GitOrigin-RevId: 06c8c67f5a564d00696e023060f05a5c34e7e164
Change-Id: I89907a6188fe7de05da400bf49ddfeba242aff8e

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)