Export of internal Abseil changes.

--
f4e870453d02106c2685e0461816469a4704ad25 by Abseil Team <absl-team@google.com>:

Expose TimeZone::NextTransition() and PrevTransition() now that
we have absl::CivilSecond support in time.h.  Note that these are
for informational purposes only.  General time code should not
care when offset changes occur.

PiperOrigin-RevId: 217177292

--
cfadd275c7333f7c27c4d682b9d167010d874e69 by Abseil Team <absl-team@google.com>:

Import of CCTZ from GitHub.

PiperOrigin-RevId: 217153577

--
6ff5b8c61a1239b9c0478a7c62bcd2844b310307 by Jon Cohen <cohenjon@google.com>:

Fix code examples in hash_testing.h.  Includes random clang-format changes.

PiperOrigin-RevId: 216898995

--
de124129d27f4627dabe193a10bf106a11783fba by Shaindel Schwartz <shaindel@google.com>:

Add contribution guidelines describing how we decide whether to include an API in Abseil.

PiperOrigin-RevId: 216886943
GitOrigin-RevId: f4e870453d02106c2685e0461816469a4704ad25
Change-Id: Ib9c6706f5bf931b71c0357bf1342053a3bee8ff7

1 files changed, 39 insertions, 1 deletions

diff --git a/absl/time/time.h b/absl/time/time.h
index 2858da2955f6..7d5c3fde7a61 100644
--- a/absl/time/time.h
+++ b/absl/time/time.h
@@ -886,7 +886,7 @@ class TimeZone {
   struct TimeInfo {
     enum CivilKind {
       UNIQUE,    // the civil time was singular (pre == trans == post)
-      SKIPPED,   // the civil time did not exist (pre => trans > post)
+      SKIPPED,   // the civil time did not exist (pre >= trans > post)
       REPEATED,  // the civil time was ambiguous (pre < trans <= post)
     } kind;
     Time pre;    // time calculated using the pre-transition offset
@@ -925,6 +925,44 @@ class TimeZone {
   //   // nov06.post  is 2011-11-06 01:15:00 -0800
   TimeInfo At(CivilSecond ct) const;
 
+  // TimeZone::NextTransition()
+  // TimeZone::PrevTransition()
+  //
+  // Finds the time of the next/previous offset change in this time zone.
+  //
+  // By definition, `NextTransition(t, &trans)` returns false when `t` is
+  // `InfiniteFuture()`, and `PrevTransition(t, &trans)` returns false
+  // when `t` is `InfinitePast()`. If the zone has no transitions, the
+  // result will also be false no matter what the argument.
+  //
+  // Otherwise, when `t` is `InfinitePast()`, `NextTransition(t, &trans)`
+  // returns true and sets `trans` to the first recorded transition. Chains
+  // of calls to `NextTransition()/PrevTransition()` will eventually return
+  // false, but it is unspecified exactly when `NextTransition(t, &trans)`
+  // jumps to false, or what time is set by `PrevTransition(t, &trans)` for
+  // a very distant `t`.
+  //
+  // Note: Enumeration of time-zone transitions is for informational purposes
+  // only. Modern time-related code should not care about when offset changes
+  // occur.
+  //
+  // Example:
+  //   absl::TimeZone nyc;
+  //   if (!absl::LoadTimeZone("America/New_York", &nyc)) { ... }
+  //   const auto now = absl::Now();
+  //   auto t = absl::InfinitePast();
+  //   absl::TimeZone::CivilTransition trans;
+  //   while (t <= now && nyc.NextTransition(t, &trans)) {
+  //     // transition: trans.from -> trans.to
+  //     t = nyc.At(trans.to).trans;
+  //   }
+  struct CivilTransition {
+    CivilSecond from;  // the civil time we jump from
+    CivilSecond to;    // the civil time we jump to
+  };
+  bool NextTransition(Time t, CivilTransition* trans) const;
+  bool PrevTransition(Time t, CivilTransition* trans) const;
+
   template <typename H>
   friend H AbslHashValue(H h, TimeZone tz) {
     return H::combine(std::move(h), tz.cz_);