absl::Time

An absl::Time represents a specific instant in time. Arithmetic operators are provided for naturally expressing time calculations. Instances are created using absl::Now() and the absl::From*() factory functions that accept the gamut of other time representations. Formatting and parsing functions are provided for conversion to and from strings. absl::Time is trivially destructible and should be passed by value rather than const reference.

Synopsis

Declared in <absl/time/time.h>

class Time;

Description

absl::Time assumes there are 60 seconds in a minute, which means the underlying time scales must be "smeared" to eliminate leap seconds. See https://developers.google.com/time/smear.

Even though absl::Time supports a wide range of timestamps, exercise caution when using values in the distant past. absl::Time uses the Proleptic Gregorian calendar, which extends the Gregorian calendar backward to dates before its introduction in 1582. See https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar for more information. Use the ICU calendar classes to convert a date in some other calendar (http://userguide.icu‐project.org/datetime/calendar).

Similarly, standardized time zones are a reasonably recent innovation, with the Greenwich prime meridian being established in 1884. The TZ database itself does not profess accurate offsets for timestamps prior to 1970. The breakdown of future timestamps is subject to the whim of regional governments.

The absl::Time class represents an instant in time as a count of clock ticks of some granularity (resolution) from some starting point (epoch).

absl::Time uses a resolution that is high enough to avoid loss in precision, and a range that is wide enough to avoid overflow, when converting between tick counts in most Google time scales (i.e., resolution of at least one nanosecond, and range +/‐100 billion years). Conversions between the time scales are performed by truncating (towards negative infinity) to the nearest representable point.

Examples:

absl::Time t1 = ...; absl::Time t2 = t1 + absl::Minutes(2); absl::Duration d = t2 ‐ t1; // == absl::Minutes(2)

Types

Name

Description

Breakdown [deprecated]

The calendar and wall‐clock (aka "civil time") components of an absl::Time in a certain absl::TimeZone. This struct is not intended to represent an instant in time. So, rather than passing a Time::Breakdown to a function, pass an absl::Time and an absl::TimeZone.

Member Functions

Name

Description

Time [constructor]

Constructors

operator=

Assigns a copy of another time.

In [deprecated]

Returns the breakdown of this instant in the given TimeZone.

operator+=

Advances this time by a duration.

operator‐=

Moves this time back by a duration.

Friends

Name

Description

absl::InfinitePast

Returns an absl::Time that is infinitely far in the past.

absl::InfiniteFuture

Returns an absl::Time that is infinitely far in the future.

absl::UniversalEpoch

Returns the absl::Time representing the ICU Universal Time Scale epoch.

absl::operator‐

Returns the duration between two times.

absl::operator==

Returns whether two times are equal.

absl::operator<

Returns whether one time is earlier than another.

absl::operator<=>

Three‐way‐compares two times.

absl::AbslHashValue

Combines this time into a hash state.

Non-Member Functions

Name

Description

AbslUnparseFlag

Unparses a Time value into a command‐line string representation using the format specified by absl::ParseTime().

FormatTime

Formats the given time using the RFC3339_full format in the given time zone.

FormatTime

Formats the given time using the RFC3339_full format in the local time zone.

FromChrono

Converts a std::chrono::system_clock::time_point to an absl::Time.

FromCivil

Helper for TimeZone::At(CivilSecond) that provides "order‐preserving semantics." If the civil time maps to a unique time, that time is returned. If the civil time is repeated in the given time zone, the time using the pre‐transition offset is returned. Otherwise, the civil time is skipped in the given time zone, and the transition time is returned. This means that for any two civil times, ct1 and ct2, (ct1 < ct2) => (FromCivil(ct1) <= FromCivil(ct2)), the equal case being when two non‐existent civil times map to the same transition time.

FromDateTime

A convenience wrapper for absl::ConvertDateTime() that simply returns the "pre" absl::Time. That is, the unique result, or the instant that is correct using the pre‐transition offset (as if the transition never happened).

FromTM

Converts the tm_year, tm_mon, tm_mday, tm_hour, tm_min, and tm_sec fields to an absl::Time using the given time zone. See ctime(3) for a description of the expected values of the tm fields. If the civil time is unique (see absl::TimeZone::At(absl::CivilSecond) above), the matching time instant is returned. Otherwise, the tm_isdst field is consulted to choose between the possible results. For a repeated civil time, `tm_isdst != 0` returns the matching DST instant, while tm_isdst == 0` returns the matching non‐DST instant. For a skipped civil time there is no matching instant, so `tm_isdst != 0 returns the DST instant, and tm_isdst == 0 returns the non‐DST instant, that would have matched if the transition never happened.

FromTimeT

Creates an absl::Time from a time_t value.

FromUDate

Creates an absl::Time from an ICU UDate value.

FromUniversal

Creates an absl::Time from an ICU Universal Time Scale value.

FromUnixMicros

Creates an absl::Time from a count of microseconds since the Unix epoch.

FromUnixMillis

Creates an absl::Time from a count of milliseconds since the Unix epoch.

FromUnixNanos

Creates an absl::Time from a count of nanoseconds since the Unix epoch.

FromUnixSeconds

Creates an absl::Time from a count of seconds since the Unix epoch.

Now

Returns the current time, expressed as an absl::Time absolute time value.

TimeFromTimespec

Converts a timespec to an absl::Time.

TimeFromTimeval

Converts a timeval to an absl::Time.

ToChronoTime

Converts an absl::Time to a std::chrono::system_clock::time_point. If overflow would occur, the returned value will saturate at the min/max time point value instead.

ToCivilDay

Converts an absolute time to a day‐aligned civil time in a time zone.

ToCivilHour

Converts an absolute time to an hour‐aligned civil time in a time zone.

ToCivilMinute

Converts an absolute time to a minute‐aligned civil time in a time zone.

ToCivilMonth

Converts an absolute time to a month‐aligned civil time in a time zone.

ToCivilSecond

Converts an absolute time to a second‐aligned civil time in a time zone.

ToCivilYear

Converts an absolute time to a year‐aligned civil time in a time zone.