[#absl-Time]
= xref:absl.adoc[absl]::Time
:relfileprefix: ../
:mrdocs:

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>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
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

[cols="1,4"]
|===
| Name| Description
| xref:absl/Time/Breakdown.adoc[`Breakdown`]  [.small]#[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

[cols="1,4"]
|===
| Name| Description
| xref:absl/Time/2constructor-0b.adoc[`Time`]         [.small]#[constructor]#
| Constructors
| xref:absl/Time/operator_assign.adoc[`operator=`] 
| Assigns a copy of another time.
| xref:absl/Time/In.adoc[`In`]  [.small]#[deprecated]#
| Returns the breakdown of this instant in the given TimeZone.
| xref:absl/Time/operator_plus_eq.adoc[`operator+=`] 
| Advances this time by a duration.
| xref:absl/Time/operator_minus_eq.adoc[`operator‐=`] 
| Moves this time back by a duration.
|===


== Friends

[cols="1,4"]
|===
| Name| Description
| `xref:absl/InfinitePast.adoc[absl::InfinitePast]`
| Returns an `absl::Time` that is infinitely far in the past.
| `xref:absl/InfiniteFuture.adoc[absl::InfiniteFuture]`
| Returns an `absl::Time` that is infinitely far in the future.
| `xref:absl/UniversalEpoch.adoc[absl::UniversalEpoch]`
| Returns the `absl::Time` representing the ICU Universal Time Scale epoch.
| `xref:absl/operator_minus-0b.adoc[absl::operator‐]`
| Returns the duration between two times.
| `xref:absl/operator_eq-08d3.adoc[absl::operator==]`
| Returns whether two times are equal.
| `xref:absl/operator_lt-0e7.adoc[absl::operator<]`
| Returns whether one time is earlier than another.
| `xref:absl/operator_3way-0d.adoc[absl::operator<=>]`
| Three‐way‐compares two times.
| `xref:absl/AbslHashValue-0f3.adoc[absl::AbslHashValue]`
| Combines this time into a hash state.
|===

== Non-Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:absl/AbslUnparseFlag-03.adoc[`AbslUnparseFlag`]
| Unparses a Time value into a command‐line string representation using the format specified by `absl::ParseTime()`.
| xref:absl/FormatTime-01.adoc[`FormatTime`]
| Formats the given time using the RFC3339_full format in the given time zone.
| xref:absl/FormatTime-0a.adoc[`FormatTime`]
| Formats the given time using the RFC3339_full format in the local time zone.
| xref:absl/FromChrono-0d6.adoc[`FromChrono`]
| Converts a std::chrono::system_clock::time_point to an absl::Time.
| xref:absl/FromCivil.adoc[`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.
| xref:absl/FromDateTime.adoc[`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).
| xref:absl/FromTM.adoc[`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.
| xref:absl/FromTimeT.adoc[`FromTimeT`]
| Creates an `absl::Time` from a `time_t` value.
| xref:absl/FromUDate.adoc[`FromUDate`]
| Creates an `absl::Time` from an ICU UDate value.
| xref:absl/FromUniversal.adoc[`FromUniversal`]
| Creates an `absl::Time` from an ICU Universal Time Scale value.
| xref:absl/FromUnixMicros.adoc[`FromUnixMicros`]
| Creates an `absl::Time` from a count of microseconds since the Unix epoch.
| xref:absl/FromUnixMillis.adoc[`FromUnixMillis`]
| Creates an `absl::Time` from a count of milliseconds since the Unix epoch.
| xref:absl/FromUnixNanos.adoc[`FromUnixNanos`]
| Creates an `absl::Time` from a count of nanoseconds since the Unix epoch.
| xref:absl/FromUnixSeconds.adoc[`FromUnixSeconds`]
| Creates an `absl::Time` from a count of seconds since the Unix epoch.
| xref:absl/Now.adoc[`Now`]
| Returns the current time, expressed as an `absl::Time` absolute time value.
| xref:absl/TimeFromTimespec.adoc[`TimeFromTimespec`]
| Converts a `timespec` to an `absl::Time`.
| xref:absl/TimeFromTimeval.adoc[`TimeFromTimeval`]
| Converts a `timeval` to an `absl::Time`.
| xref:absl/ToChronoTime.adoc[`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.
| xref:absl/ToCivilDay.adoc[`ToCivilDay`]
| Converts an absolute time to a day‐aligned civil time in a time zone.
| xref:absl/ToCivilHour.adoc[`ToCivilHour`]
| Converts an absolute time to an hour‐aligned civil time in a time zone.
| xref:absl/ToCivilMinute.adoc[`ToCivilMinute`]
| Converts an absolute time to a minute‐aligned civil time in a time zone.
| xref:absl/ToCivilMonth.adoc[`ToCivilMonth`]
| Converts an absolute time to a month‐aligned civil time in a time zone.
| xref:absl/ToCivilSecond.adoc[`ToCivilSecond`]
| Converts an absolute time to a second‐aligned civil time in a time zone.
| xref:absl/ToCivilYear.adoc[`ToCivilYear`]
| Converts an absolute time to a year‐aligned civil time in a time zone.
| xref:absl/ToTM.adoc[`ToTM`]
| Converts the given `absl::Time` to a struct tm using the given time zone. See ctime(3) for a description of the values of the tm fields.
| xref:absl/ToTimeT.adoc[`ToTimeT`]
| Converts an `absl::Time` to a `time_t` value.
| xref:absl/ToTimespec-09.adoc[`ToTimespec`]
| Converts an `absl::Time` to a `timespec`.
| xref:absl/ToTimeval-0d.adoc[`ToTimeval`]
| Converts an `absl::Time` to a `timeval`.
| xref:absl/ToUDate.adoc[`ToUDate`]
| Converts an `absl::Time` to an ICU UDate value.
| xref:absl/ToUniversal.adoc[`ToUniversal`]
| Converts an `absl::Time` to an ICU Universal Time Scale value.
| xref:absl/ToUnixMicros.adoc[`ToUnixMicros`]
| Converts an `absl::Time` to a count of microseconds since the Unix epoch.
| xref:absl/ToUnixMillis.adoc[`ToUnixMillis`]
| Converts an `absl::Time` to a count of milliseconds since the Unix epoch.
| xref:absl/ToUnixNanos.adoc[`ToUnixNanos`]
| Converts an `absl::Time` to a count of nanoseconds since the Unix epoch.
| xref:absl/ToUnixSeconds.adoc[`ToUnixSeconds`]
| Converts an `absl::Time` to a count of seconds since the Unix epoch.
| xref:absl/UnixEpoch.adoc[`UnixEpoch`]
| Returns the `absl::Time` representing "1970‐01‐01 00:00:00.0 +0000".
| xref:absl/operator_not_eq-052.adoc[`operator!=`]
| Returns whether two times are unequal.
| xref:absl/operator_plus-04.adoc[`operator+`]
| Returns the time obtained by advancing a time by a duration.
| xref:absl/operator_plus-0b.adoc[`operator+`]
| Returns the time obtained by advancing a time by a duration.
| xref:absl/operator_minus-0ea.adoc[`operator‐`]
| Returns the time obtained by moving a time back by a duration.
| xref:absl/operator_le-090.adoc[`operator<=`]
| Returns whether one time is earlier than or equal to another.
| xref:absl/operator_gt-0e.adoc[`operator>`]
| Returns whether one time is later than another.
| xref:absl/operator_ge-00.adoc[`operator>=`]
| Returns whether one time is later than or equal to another.
|===


[.small]#Created with https://www.mrdocs.com[MrDocs]#