From 5e7d459eeca7bc53deab0ee9634601386b53d7c0 Mon Sep 17 00:00:00 2001 From: Abseil Team Date: Thu, 23 Aug 2018 10:41:14 -0700 Subject: Export of internal Abseil changes. -- 2dcf3ec79f961d2962cdad33ac4bfbcb14126dad by Abseil Team : Consolidate implementations of CountLeadingZeros and add new ones for CountTrailingZeros. Internal APIs only. PiperOrigin-RevId: 209961247 -- 4f3ac87c6928dab26faff962bb18aade9383f184 by Jorg Brown : Fix absl::CUnescape not to write to const_cast(str->data()), which does the wrong thing if the string type is copy-on-write PiperOrigin-RevId: 209957656 -- c5103067be19dc88a4c32e5306154e5e3bba4673 by Tom Manshreck : Update comments in time library header files. PiperOrigin-RevId: 209829588 -- fe36f9b6150243d2ac88e2a892d84c565c18cd2f by Abseil Team : Clarifying the sample use of absl::LoadTimeZone function in the documentation. PiperOrigin-RevId: 209782218 GitOrigin-RevId: 2dcf3ec79f961d2962cdad33ac4bfbcb14126dad Change-Id: I3e2f87a8c543599b81eada58409a9bddc0b51ab8 --- absl/time/time.h | 31 +++++++++++++++++++++++++------ 1 file changed, 25 insertions(+), 6 deletions(-) (limited to 'absl/time/time.h') diff --git a/absl/time/time.h b/absl/time/time.h index d29d7e9a2061..f2a779f4edfa 100644 --- a/absl/time/time.h +++ b/absl/time/time.h @@ -25,11 +25,22 @@ // * `absl::TimeZone` defines geopolitical time zone regions (as collected // within the IANA Time Zone database (https://www.iana.org/time-zones)). // +// Note: Absolute times are distinct from civil times, which refer to the +// human-scale time commonly represented by `YYYY-MM-DD hh:mm:ss`. The mapping +// between absolute and civil times can be specified by use of time zones +// (`absl::TimeZone` within this API). That is: +// +// Civil Time = F(Absolute Time, Time Zone) +// Absolute Time = F(Civil Time, Time Zone) +// +// See civil_time.h for abstractions related to constructing and manipulating +// civil time. +// // Example: // // absl::TimeZone nyc; // -// // LoadTimeZone may fail so it's always better to check for success. +// // LoadTimeZone() may fail so it's always better to check for success. // if (!absl::LoadTimeZone("America/New_York", &nyc)) { // // handle error case // } @@ -496,7 +507,7 @@ inline std::ostream& operator<<(std::ostream& os, Duration d) { // decimal numbers, each with an optional fractional part and a unit // suffix. The valid suffixes are "ns", "us" "ms", "s", "m", and "h". // Simple examples include "300ms", "-1.5h", and "2h45m". Parses "0" as -// `ZeroDuration()`. Parses "inf" and "-inf" as +/- `InfiniteDuration()`. +// `ZeroDuration()`. Parses "inf" and "-inf" as +/- `InfiniteDuration()`. bool ParseDuration(const std::string& dur_string, Duration* d); // Support for flag values of type Duration. Duration flags must be specified @@ -689,7 +700,9 @@ constexpr Time InfinitePast() { // Examples: // // absl::TimeZone lax; -// if (!absl::LoadTimeZone("America/Los_Angeles", &lax)) { ... } +// if (!absl::LoadTimeZone("America/Los_Angeles", &lax)) { +// // handle error case +// } // // // A unique civil time // absl::TimeConversion jan01 = @@ -759,7 +772,9 @@ TimeConversion ConvertDateTime(int64_t year, int mon, int day, int hour, // Example: // // absl::TimeZone seattle; -// if (!absl::LoadTimeZone("America/Los_Angeles", &seattle)) { ... } +// if (!absl::LoadTimeZone("America/Los_Angeles", &seattle)) { +// // handle error case +// } // absl::Time t = absl::FromDateTime(2017, 9, 26, 9, 30, 0, seattle); Time FromDateTime(int64_t year, int mon, int day, int hour, int min, int sec, TimeZone tz); @@ -910,7 +925,9 @@ extern const char RFC1123_no_wday[]; // %d %b %E4Y %H:%M:%S %z // Example: // // absl::TimeZone lax; -// if (!absl::LoadTimeZone("America/Los_Angeles", &lax)) { ... } +// if (!absl::LoadTimeZone("America/Los_Angeles", &lax)) { +// // handle error case +// } // absl::Time t = absl::FromDateTime(2013, 1, 2, 3, 4, 5, lax); // // string f = absl::FormatTime("%H:%M:%S", t, lax); // "03:04:05" @@ -1028,7 +1045,9 @@ std::string UnparseFlag(Time t); // absl::TimeZone pst = absl::FixedTimeZone(-8 * 60 * 60); // absl::TimeZone loc = absl::LocalTimeZone(); // absl::TimeZone lax; -// if (!absl::LoadTimeZone("America/Los_Angeles", &lax)) { ... } +// if (!absl::LoadTimeZone("America/Los_Angeles", &lax)) { +// // handle error case +// } // // See also: // - https://github.com/google/cctz -- cgit 1.4.1