summaryrefslogtreecommitdiff
path: root/absl/time
diff options
context:
space:
mode:
Diffstat (limited to 'absl/time')
-rw-r--r--absl/time/time.h31
1 files changed, 25 insertions, 6 deletions
diff --git a/absl/time/time.h b/absl/time/time.h
index d29d7e9a..f2a779f4 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