1	// Copyright 2017 The Abseil Authors.
2	//
3	// Licensed under the Apache License, Version 2.0 (the "License");
4	// you may not use this file except in compliance with the License.
5	// You may obtain a copy of the License at
6	//
7	// https://www.apache.org/licenses/LICENSE-2.0
8	//
9	// Unless required by applicable law or agreed to in writing, software
10	// distributed under the License is distributed on an "AS IS" BASIS,
11	// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12	// See the License for the specific language governing permissions and
13	// limitations under the License.
14	//
15	// -----------------------------------------------------------------------------
16	// File: time.h
17	// -----------------------------------------------------------------------------
18	//
19	// This header file defines abstractions for computing with absolute points
20	// in time, durations of time, and formatting and parsing time within a given
21	// time zone. The following abstractions are defined:
22	//
23	// * `absl::Time` defines an absolute, specific instance in time
24	// * `absl::Duration` defines a signed, fixed-length span of time
25	// * `absl::TimeZone` defines geopolitical time zone regions (as collected
26	// within the IANA Time Zone database (https://www.iana.org/time-zones)).
27	//
28	// Note: Absolute times are distinct from civil times, which refer to the
29	// human-scale time commonly represented by `YYYY-MM-DD hh:mm:ss`. The mapping
30	// between absolute and civil times can be specified by use of time zones
31	// (`absl::TimeZone` within this API). That is:
32	//
33	// Civil Time = F(Absolute Time, Time Zone)
34	// Absolute Time = G(Civil Time, Time Zone)
35	//
36	// See civil_time.h for abstractions related to constructing and manipulating
37	// civil time.
38	//
39	// Example:
40	//
41	// absl::TimeZone nyc;
42	// // LoadTimeZone() may fail so it's always better to check for success.
43	// if (!absl::LoadTimeZone("America/New_York", &nyc)) {
44	// // handle error case
45	// }
46	//
47	// // My flight leaves NYC on Jan 2, 2017 at 03:04:05
48	// absl::CivilSecond cs(2017, 1, 2, 3, 4, 5);
49	// absl::Time takeoff = absl::FromCivil(cs, nyc);
50	//
51	// absl::Duration flight_duration = absl::Hours(21) + absl::Minutes(35);
52	// absl::Time landing = takeoff + flight_duration;
53	//
54	// absl::TimeZone syd;
55	// if (!absl::LoadTimeZone("Australia/Sydney", &syd)) {
56	// // handle error case
57	// }
58	// std::string s = absl::FormatTime(
59	// "My flight will land in Sydney on %Y-%m-%d at %H:%M:%S",
60	// landing, syd);
61
62	#ifndef ABSL_TIME_TIME_H_
63	#define ABSL_TIME_TIME_H_
64
65	#if !defined(_MSC_VER)
66	#include <sys/time.h>
67	#else
68	// We don't include `winsock2.h` because it drags in `windows.h` and friends,
69	// and they define conflicting macros like OPAQUE, ERROR, and more. This has the
70	// potential to break Abseil users.
71	//
72	// Instead we only forward declare `timeval` and require Windows users include
73	// `winsock2.h` themselves. This is both inconsistent and troublesome, but so is
74	// including 'windows.h' so we are picking the lesser of two evils here.
75	struct timeval;
76	#endif
77	#include <chrono> // NOLINT(build/c++11)
78	#include <cmath>
79	#include <cstdint>
80	#include <ctime>
81	#include <ostream>
82	#include <string>
83	#include <type_traits>
84	#include <utility>
85
86	#include "absl/base/macros.h"
87	#include "absl/strings/string_view.h"
88	#include "absl/time/civil_time.h"
89	#include "absl/time/internal/cctz/include/cctz/time_zone.h"
90
91	namespace absl {
92	ABSL_NAMESPACE_BEGIN
93
94	class Duration; // Defined below
95	class Time; // Defined below
96	class TimeZone; // Defined below
97
98	namespace time_internal {
99	int64_t IDivDuration(bool satq, Duration num, Duration den, Duration* rem);
100	constexpr Time FromUnixDuration(Duration d);
101	constexpr Duration ToUnixDuration(Time t);
102	constexpr int64_t GetRepHi(Duration d);
103	constexpr uint32_t GetRepLo(Duration d);
104	constexpr Duration MakeDuration(int64_t hi, uint32_t lo);
105	constexpr Duration MakeDuration(int64_t hi, int64_t lo);
106	inline Duration MakePosDoubleDuration(double n);
107	constexpr int64_t kTicksPerNanosecond = 4;
108	constexpr int64_t kTicksPerSecond = 1000 * 1000 * 1000 * kTicksPerNanosecond;
109	template <std::intmax_t N>
110	constexpr Duration FromInt64(int64_t v, std::ratio<1, N>);
111	constexpr Duration FromInt64(int64_t v, std::ratio<60>);
112	constexpr Duration FromInt64(int64_t v, std::ratio<3600>);
113	template <typename T>
114	using EnableIfIntegral = typename std::enable_if<
115	std::is_integral<T>::value || std::is_enum<T>::value, int>::type;
116	template <typename T>
117	using EnableIfFloat =
118	typename std::enable_if<std::is_floating_point<T>::value, int>::type;
119	} // namespace time_internal
120
121	// Duration
122	//
123	// The `absl::Duration` class represents a signed, fixed-length amount of time.
124	// A `Duration` is generated using a unit-specific factory function, or is
125	// the result of subtracting one `absl::Time` from another. Durations behave
126	// like unit-safe integers and they support all the natural integer-like
127	// arithmetic operations. Arithmetic overflows and saturates at +/- infinity.
128	// `Duration` should be passed by value rather than const reference.
129	//
130	// Factory functions `Nanoseconds()`, `Microseconds()`, `Milliseconds()`,
131	// `Seconds()`, `Minutes()`, `Hours()` and `InfiniteDuration()` allow for
132	// creation of constexpr `Duration` values
133	//
134	// Examples:
135	//
136	// constexpr absl::Duration ten_ns = absl::Nanoseconds(10);
137	// constexpr absl::Duration min = absl::Minutes(1);
138	// constexpr absl::Duration hour = absl::Hours(1);
139	// absl::Duration dur = 60 * min; // dur == hour
140	// absl::Duration half_sec = absl::Milliseconds(500);
141	// absl::Duration quarter_sec = 0.25 * absl::Seconds(1);
142	//
143	// `Duration` values can be easily converted to an integral number of units
144	// using the division operator.
145	//
146	// Example:
147	//
148	// constexpr absl::Duration dur = absl::Milliseconds(1500);
149	// int64_t ns = dur / absl::Nanoseconds(1); // ns == 1500000000
150	// int64_t ms = dur / absl::Milliseconds(1); // ms == 1500
151	// int64_t sec = dur / absl::Seconds(1); // sec == 1 (subseconds truncated)
152	// int64_t min = dur / absl::Minutes(1); // min == 0
153	//
154	// See the `IDivDuration()` and `FDivDuration()` functions below for details on
155	// how to access the fractional parts of the quotient.
156	//
157	// Alternatively, conversions can be performed using helpers such as
158	// `ToInt64Microseconds()` and `ToDoubleSeconds()`.
159	class Duration {
160	public:
161	// Value semantics.
162	constexpr Duration() : rep_hi_(0), rep_lo_(0) {} // zero-length duration
163
164	// Copyable.
165	#if !defined(__clang__) && defined(_MSC_VER) && _MSC_VER < 1930
166	// Explicitly defining the constexpr copy constructor avoids an MSVC bug.
167	constexpr Duration(const Duration& d)
168	: rep_hi_(d.rep_hi_), rep_lo_(d.rep_lo_) {}
169	#else
170	constexpr Duration(const Duration& d) = default;
171	#endif
172	Duration& operator=(const Duration& d) = default;
173
174	// Compound assignment operators.
175	Duration& operator+=(Duration d);
176	Duration& operator-=(Duration d);
177	Duration& operator*=(int64_t r);
178	Duration& operator*=(double r);
179	Duration& operator/=(int64_t r);
180	Duration& operator/=(double r);
181	Duration& operator%=(Duration rhs);
182
183	// Overloads that forward to either the int64_t or double overloads above.
184	// Integer operands must be representable as int64_t.
185	template <typename T, time_internal::EnableIfIntegral<T> = 0>
186	Duration& operator*=(T r) {
187	int64_t x = r;
188	return *this *= x;
189	}
190
191	template <typename T, time_internal::EnableIfIntegral<T> = 0>
192	Duration& operator/=(T r) {
193	int64_t x = r;
194	return *this /= x;
195	}
196
197	template <typename T, time_internal::EnableIfFloat<T> = 0>
198	Duration& operator*=(T r) {
199	double x = r;
200	return *this *= x;
201	}
202
203	template <typename T, time_internal::EnableIfFloat<T> = 0>
204	Duration& operator/=(T r) {
205	double x = r;
206	return *this /= x;
207	}
208
209	template <typename H>
210	friend H AbslHashValue(H h, Duration d) {
211	return H::combine(std::move(h), d.rep_hi_, d.rep_lo_);
212	}
213
214	private:
215	friend constexpr int64_t time_internal::GetRepHi(Duration d);
216	friend constexpr uint32_t time_internal::GetRepLo(Duration d);
217	friend constexpr Duration time_internal::MakeDuration(int64_t hi,
218	uint32_t lo);
219	constexpr Duration(int64_t hi, uint32_t lo) : rep_hi_(hi), rep_lo_(lo) {}
220	int64_t rep_hi_;
221	uint32_t rep_lo_;
222	};
223
224	// Relational Operators
225	constexpr bool operator<(Duration lhs, Duration rhs);
226	constexpr bool operator>(Duration lhs, Duration rhs) { return rhs < lhs; }
227	constexpr bool operator>=(Duration lhs, Duration rhs) { return !(lhs < rhs); }
228	constexpr bool operator<=(Duration lhs, Duration rhs) { return !(rhs < lhs); }
229	constexpr bool operator==(Duration lhs, Duration rhs);
230	constexpr bool operator!=(Duration lhs, Duration rhs) { return !(lhs == rhs); }
231
232	// Additive Operators
233	constexpr Duration operator-(Duration d);
234	inline Duration operator+(Duration lhs, Duration rhs) { return lhs += rhs; }
235	inline Duration operator-(Duration lhs, Duration rhs) { return lhs -= rhs; }
236
237	// Multiplicative Operators
238	// Integer operands must be representable as int64_t.
239	template <typename T>
240	Duration operator*(Duration lhs, T rhs) {
241	return lhs *= rhs;
242	}
243	template <typename T>
244	Duration operator*(T lhs, Duration rhs) {
245	return rhs *= lhs;
246	}
247	template <typename T>
248	Duration operator/(Duration lhs, T rhs) {
249	return lhs /= rhs;
250	}
251	inline int64_t operator/(Duration lhs, Duration rhs) {
252	return time_internal::IDivDuration(satq: true, num: lhs, den: rhs,
253	rem: &lhs); // trunc towards zero
254	}
255	inline Duration operator%(Duration lhs, Duration rhs) { return lhs %= rhs; }
256
257	// IDivDuration()
258	//
259	// Divides a numerator `Duration` by a denominator `Duration`, returning the
260	// quotient and remainder. The remainder always has the same sign as the
261	// numerator. The returned quotient and remainder respect the identity:
262	//
263	// numerator = denominator * quotient + remainder
264	//
265	// Returned quotients are capped to the range of `int64_t`, with the difference
266	// spilling into the remainder to uphold the above identity. This means that the
267	// remainder returned could differ from the remainder returned by
268	// `Duration::operator%` for huge quotients.
269	//
270	// See also the notes on `InfiniteDuration()` below regarding the behavior of
271	// division involving zero and infinite durations.
272	//
273	// Example:
274	//
275	// constexpr absl::Duration a =
276	// absl::Seconds(std::numeric_limits<int64_t>::max()); // big
277	// constexpr absl::Duration b = absl::Nanoseconds(1); // small
278	//
279	// absl::Duration rem = a % b;
280	// // rem == absl::ZeroDuration()
281	//
282	// // Here, q would overflow int64_t, so rem accounts for the difference.
283	// int64_t q = absl::IDivDuration(a, b, &rem);
284	// // q == std::numeric_limits<int64_t>::max(), rem == a - b * q
285	inline int64_t IDivDuration(Duration num, Duration den, Duration* rem) {
286	return time_internal::IDivDuration(satq: true, num, den,
287	rem); // trunc towards zero
288	}
289
290	// FDivDuration()
291	//
292	// Divides a `Duration` numerator into a fractional number of units of a
293	// `Duration` denominator.
294	//
295	// See also the notes on `InfiniteDuration()` below regarding the behavior of
296	// division involving zero and infinite durations.
297	//
298	// Example:
299	//
300	// double d = absl::FDivDuration(absl::Milliseconds(1500), absl::Seconds(1));
301	// // d == 1.5
302	double FDivDuration(Duration num, Duration den);
303
304	// ZeroDuration()
305	//
306	// Returns a zero-length duration. This function behaves just like the default
307	// constructor, but the name helps make the semantics clear at call sites.
308	constexpr Duration ZeroDuration() { return Duration(); }
309
310	// AbsDuration()
311	//
312	// Returns the absolute value of a duration.
313	inline Duration AbsDuration(Duration d) {
314	return (d < ZeroDuration()) ? -d : d;
315	}
316
317	// Trunc()
318	//
319	// Truncates a duration (toward zero) to a multiple of a non-zero unit.
320	//
321	// Example:
322	//
323	// absl::Duration d = absl::Nanoseconds(123456789);
324	// absl::Duration a = absl::Trunc(d, absl::Microseconds(1)); // 123456us
325	Duration Trunc(Duration d, Duration unit);
326
327	// Floor()
328	//
329	// Floors a duration using the passed duration unit to its largest value not
330	// greater than the duration.
331	//
332	// Example:
333	//
334	// absl::Duration d = absl::Nanoseconds(123456789);
335	// absl::Duration b = absl::Floor(d, absl::Microseconds(1)); // 123456us
336	Duration Floor(Duration d, Duration unit);
337
338	// Ceil()
339	//
340	// Returns the ceiling of a duration using the passed duration unit to its
341	// smallest value not less than the duration.
342	//
343	// Example:
344	//
345	// absl::Duration d = absl::Nanoseconds(123456789);
346	// absl::Duration c = absl::Ceil(d, absl::Microseconds(1)); // 123457us
347	Duration Ceil(Duration d, Duration unit);
348
349	// InfiniteDuration()
350	//
351	// Returns an infinite `Duration`. To get a `Duration` representing negative
352	// infinity, use `-InfiniteDuration()`.
353	//
354	// Duration arithmetic overflows to +/- infinity and saturates. In general,
355	// arithmetic with `Duration` infinities is similar to IEEE 754 infinities
356	// except where IEEE 754 NaN would be involved, in which case +/-
357	// `InfiniteDuration()` is used in place of a "nan" Duration.
358	//
359	// Examples:
360	//
361	// constexpr absl::Duration inf = absl::InfiniteDuration();
362	// const absl::Duration d = ... any finite duration ...
363	//
364	// inf == inf + inf
365	// inf == inf + d
366	// inf == inf - inf
367	// -inf == d - inf
368	//
369	// inf == d * 1e100
370	// inf == inf / 2
371	// 0 == d / inf
372	// INT64_MAX == inf / d
373	//
374	// d < inf
375	// -inf < d
376	//
377	// // Division by zero returns infinity, or INT64_MIN/MAX where appropriate.
378	// inf == d / 0
379	// INT64_MAX == d / absl::ZeroDuration()
380	//
381	// The examples involving the `/` operator above also apply to `IDivDuration()`
382	// and `FDivDuration()`.
383	constexpr Duration InfiniteDuration();
384
385	// Nanoseconds()
386	// Microseconds()
387	// Milliseconds()
388	// Seconds()
389	// Minutes()
390	// Hours()
391	//
392	// Factory functions for constructing `Duration` values from an integral number
393	// of the unit indicated by the factory function's name. The number must be
394	// representable as int64_t.
395	//
396	// NOTE: no "Days()" factory function exists because "a day" is ambiguous.
397	// Civil days are not always 24 hours long, and a 24-hour duration often does
398	// not correspond with a civil day. If a 24-hour duration is needed, use
399	// `absl::Hours(24)`. If you actually want a civil day, use absl::CivilDay
400	// from civil_time.h.
401	//
402	// Example:
403	//
404	// absl::Duration a = absl::Seconds(60);
405	// absl::Duration b = absl::Minutes(1); // b == a
406	template <typename T, time_internal::EnableIfIntegral<T> = 0>
407	constexpr Duration Nanoseconds(T n) {
408	return time_internal::FromInt64(n, std::nano{});
409	}
410	template <typename T, time_internal::EnableIfIntegral<T> = 0>
411	constexpr Duration Microseconds(T n) {
412	return time_internal::FromInt64(n, std::micro{});
413	}
414	template <typename T, time_internal::EnableIfIntegral<T> = 0>
415	constexpr Duration Milliseconds(T n) {
416	return time_internal::FromInt64(n, std::milli{});
417	}
418	template <typename T, time_internal::EnableIfIntegral<T> = 0>
419	constexpr Duration Seconds(T n) {
420	return time_internal::FromInt64(n, std::ratio<1>{});
421	}
422	template <typename T, time_internal::EnableIfIntegral<T> = 0>
423	constexpr Duration Minutes(T n) {
424	return time_internal::FromInt64(n, std::ratio<60>{});
425	}
426	template <typename T, time_internal::EnableIfIntegral<T> = 0>
427	constexpr Duration Hours(T n) {
428	return time_internal::FromInt64(n, std::ratio<3600>{});
429	}
430
431	// Factory overloads for constructing `Duration` values from a floating-point
432	// number of the unit indicated by the factory function's name. These functions
433	// exist for convenience, but they are not as efficient as the integral
434	// factories, which should be preferred.
435	//
436	// Example:
437	//
438	// auto a = absl::Seconds(1.5); // OK
439	// auto b = absl::Milliseconds(1500); // BETTER
440	template <typename T, time_internal::EnableIfFloat<T> = 0>
441	Duration Nanoseconds(T n) {
442	return n * Nanoseconds(n: 1);
443	}
444	template <typename T, time_internal::EnableIfFloat<T> = 0>
445	Duration Microseconds(T n) {
446	return n * Microseconds(n: 1);
447	}
448	template <typename T, time_internal::EnableIfFloat<T> = 0>
449	Duration Milliseconds(T n) {
450	return n * Milliseconds(n: 1);
451	}
452	template <typename T, time_internal::EnableIfFloat<T> = 0>
453	Duration Seconds(T n) {
454	if (n >= 0) { // Note: `NaN >= 0` is false.
455	if (n >= static_cast<T>((std::numeric_limits<int64_t>::max)())) {
456	return InfiniteDuration();
457	}
458	return time_internal::MakePosDoubleDuration(n);
459	} else {
460	if (std::isnan(n))
461	return std::signbit(n) ? -InfiniteDuration() : InfiniteDuration();
462	if (n <= (std::numeric_limits<int64_t>::min)()) return -InfiniteDuration();
463	return -time_internal::MakePosDoubleDuration(n: -n);
464	}
465	}
466	template <typename T, time_internal::EnableIfFloat<T> = 0>
467	Duration Minutes(T n) {
468	return n * Minutes(n: 1);
469	}
470	template <typename T, time_internal::EnableIfFloat<T> = 0>
471	Duration Hours(T n) {
472	return n * Hours(n: 1);
473	}
474
475	// ToInt64Nanoseconds()
476	// ToInt64Microseconds()
477	// ToInt64Milliseconds()
478	// ToInt64Seconds()
479	// ToInt64Minutes()
480	// ToInt64Hours()
481	//
482	// Helper functions that convert a Duration to an integral count of the
483	// indicated unit. These return the same results as the `IDivDuration()`
484	// function, though they usually do so more efficiently; see the
485	// documentation of `IDivDuration()` for details about overflow, etc.
486	//
487	// Example:
488	//
489	// absl::Duration d = absl::Milliseconds(1500);
490	// int64_t isec = absl::ToInt64Seconds(d); // isec == 1
491	ABSL_ATTRIBUTE_PURE_FUNCTION int64_t ToInt64Nanoseconds(Duration d);
492	ABSL_ATTRIBUTE_PURE_FUNCTION int64_t ToInt64Microseconds(Duration d);
493	ABSL_ATTRIBUTE_PURE_FUNCTION int64_t ToInt64Milliseconds(Duration d);
494	ABSL_ATTRIBUTE_PURE_FUNCTION int64_t ToInt64Seconds(Duration d);
495	ABSL_ATTRIBUTE_PURE_FUNCTION int64_t ToInt64Minutes(Duration d);
496	ABSL_ATTRIBUTE_PURE_FUNCTION int64_t ToInt64Hours(Duration d);
497
498	// ToDoubleNanoSeconds()
499	// ToDoubleMicroseconds()
500	// ToDoubleMilliseconds()
501	// ToDoubleSeconds()
502	// ToDoubleMinutes()
503	// ToDoubleHours()
504	//
505	// Helper functions that convert a Duration to a floating point count of the
506	// indicated unit. These functions are shorthand for the `FDivDuration()`
507	// function above; see its documentation for details about overflow, etc.
508	//
509	// Example:
510	//
511	// absl::Duration d = absl::Milliseconds(1500);
512	// double dsec = absl::ToDoubleSeconds(d); // dsec == 1.5
513	ABSL_ATTRIBUTE_PURE_FUNCTION double ToDoubleNanoseconds(Duration d);
514	ABSL_ATTRIBUTE_PURE_FUNCTION double ToDoubleMicroseconds(Duration d);
515	ABSL_ATTRIBUTE_PURE_FUNCTION double ToDoubleMilliseconds(Duration d);
516	ABSL_ATTRIBUTE_PURE_FUNCTION double ToDoubleSeconds(Duration d);
517	ABSL_ATTRIBUTE_PURE_FUNCTION double ToDoubleMinutes(Duration d);
518	ABSL_ATTRIBUTE_PURE_FUNCTION double ToDoubleHours(Duration d);
519
520	// FromChrono()
521	//
522	// Converts any of the pre-defined std::chrono durations to an absl::Duration.
523	//
524	// Example:
525	//
526	// std::chrono::milliseconds ms(123);
527	// absl::Duration d = absl::FromChrono(ms);
528	constexpr Duration FromChrono(const std::chrono::nanoseconds& d);
529	constexpr Duration FromChrono(const std::chrono::microseconds& d);
530	constexpr Duration FromChrono(const std::chrono::milliseconds& d);
531	constexpr Duration FromChrono(const std::chrono::seconds& d);
532	constexpr Duration FromChrono(const std::chrono::minutes& d);
533	constexpr Duration FromChrono(const std::chrono::hours& d);
534
535	// ToChronoNanoseconds()
536	// ToChronoMicroseconds()
537	// ToChronoMilliseconds()
538	// ToChronoSeconds()
539	// ToChronoMinutes()
540	// ToChronoHours()
541	//
542	// Converts an absl::Duration to any of the pre-defined std::chrono durations.
543	// If overflow would occur, the returned value will saturate at the min/max
544	// chrono duration value instead.
545	//
546	// Example:
547	//
548	// absl::Duration d = absl::Microseconds(123);
549	// auto x = absl::ToChronoMicroseconds(d);
550	// auto y = absl::ToChronoNanoseconds(d); // x == y
551	// auto z = absl::ToChronoSeconds(absl::InfiniteDuration());
552	// // z == std::chrono::seconds::max()
553	std::chrono::nanoseconds ToChronoNanoseconds(Duration d);
554	std::chrono::microseconds ToChronoMicroseconds(Duration d);
555	std::chrono::milliseconds ToChronoMilliseconds(Duration d);
556	std::chrono::seconds ToChronoSeconds(Duration d);
557	std::chrono::minutes ToChronoMinutes(Duration d);
558	std::chrono::hours ToChronoHours(Duration d);
559
560	// FormatDuration()
561	//
562	// Returns a string representing the duration in the form "72h3m0.5s".
563	// Returns "inf" or "-inf" for +/- `InfiniteDuration()`.
564	std::string FormatDuration(Duration d);
565
566	// Output stream operator.
567	inline std::ostream& operator<<(std::ostream& os, Duration d) {
568	return os << FormatDuration(d);
569	}
570
571	// ParseDuration()
572	//
573	// Parses a duration string consisting of a possibly signed sequence of
574	// decimal numbers, each with an optional fractional part and a unit
575	// suffix. The valid suffixes are "ns", "us" "ms", "s", "m", and "h".
576	// Simple examples include "300ms", "-1.5h", and "2h45m". Parses "0" as
577	// `ZeroDuration()`. Parses "inf" and "-inf" as +/- `InfiniteDuration()`.
578	bool ParseDuration(absl::string_view dur_string, Duration* d);
579
580	// AbslParseFlag()
581	//
582	// Parses a command-line flag string representation `text` into a Duration
583	// value. Duration flags must be specified in a format that is valid input for
584	// `absl::ParseDuration()`.
585	bool AbslParseFlag(absl::string_view text, Duration* dst, std::string* error);
586
587
588	// AbslUnparseFlag()
589	//
590	// Unparses a Duration value into a command-line string representation using
591	// the format specified by `absl::ParseDuration()`.
592	std::string AbslUnparseFlag(Duration d);
593
594	ABSL_DEPRECATED("Use AbslParseFlag() instead.")
595	bool ParseFlag(const std::string& text, Duration* dst, std::string* error);
596	ABSL_DEPRECATED("Use AbslUnparseFlag() instead.")
597	std::string UnparseFlag(Duration d);
598
599	// Time
600	//
601	// An `absl::Time` represents a specific instant in time. Arithmetic operators
602	// are provided for naturally expressing time calculations. Instances are
603	// created using `absl::Now()` and the `absl::From*()` factory functions that
604	// accept the gamut of other time representations. Formatting and parsing
605	// functions are provided for conversion to and from strings. `absl::Time`
606	// should be passed by value rather than const reference.
607	//
608	// `absl::Time` assumes there are 60 seconds in a minute, which means the
609	// underlying time scales must be "smeared" to eliminate leap seconds.
610	// See https://developers.google.com/time/smear.
611	//
612	// Even though `absl::Time` supports a wide range of timestamps, exercise
613	// caution when using values in the distant past. `absl::Time` uses the
614	// Proleptic Gregorian calendar, which extends the Gregorian calendar backward
615	// to dates before its introduction in 1582.
616	// See https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar
617	// for more information. Use the ICU calendar classes to convert a date in
618	// some other calendar (http://userguide.icu-project.org/datetime/calendar).
619	//
620	// Similarly, standardized time zones are a reasonably recent innovation, with
621	// the Greenwich prime meridian being established in 1884. The TZ database
622	// itself does not profess accurate offsets for timestamps prior to 1970. The
623	// breakdown of future timestamps is subject to the whim of regional
624	// governments.
625	//
626	// The `absl::Time` class represents an instant in time as a count of clock
627	// ticks of some granularity (resolution) from some starting point (epoch).
628	//
629	// `absl::Time` uses a resolution that is high enough to avoid loss in
630	// precision, and a range that is wide enough to avoid overflow, when
631	// converting between tick counts in most Google time scales (i.e., resolution
632	// of at least one nanosecond, and range +/-100 billion years). Conversions
633	// between the time scales are performed by truncating (towards negative
634	// infinity) to the nearest representable point.
635	//
636	// Examples:
637	//
638	// absl::Time t1 = ...;
639	// absl::Time t2 = t1 + absl::Minutes(2);
640	// absl::Duration d = t2 - t1; // == absl::Minutes(2)
641	//
642	class Time {
643	public:
644	// Value semantics.
645
646	// Returns the Unix epoch. However, those reading your code may not know
647	// or expect the Unix epoch as the default value, so make your code more
648	// readable by explicitly initializing all instances before use.
649	//
650	// Example:
651	// absl::Time t = absl::UnixEpoch();
652	// absl::Time t = absl::Now();
653	// absl::Time t = absl::TimeFromTimeval(tv);
654	// absl::Time t = absl::InfinitePast();
655	constexpr Time() = default;
656
657	// Copyable.
658	constexpr Time(const Time& t) = default;
659	Time& operator=(const Time& t) = default;
660
661	// Assignment operators.
662	Time& operator+=(Duration d) {
663	rep_ += d;
664	return *this;
665	}
666	Time& operator-=(Duration d) {
667	rep_ -= d;
668	return *this;
669	}
670
671	// Time::Breakdown
672	//
673	// The calendar and wall-clock (aka "civil time") components of an
674	// `absl::Time` in a certain `absl::TimeZone`. This struct is not
675	// intended to represent an instant in time. So, rather than passing
676	// a `Time::Breakdown` to a function, pass an `absl::Time` and an
677	// `absl::TimeZone`.
678	//
679	// Deprecated. Use `absl::TimeZone::CivilInfo`.
680	struct
681	Breakdown {
682	int64_t year; // year (e.g., 2013)
683	int month; // month of year [1:12]
684	int day; // day of month [1:31]
685	int hour; // hour of day [0:23]
686	int minute; // minute of hour [0:59]
687	int second; // second of minute [0:59]
688	Duration subsecond; // [Seconds(0):Seconds(1)) if finite
689	int weekday; // 1==Mon, ..., 7=Sun
690	int yearday; // day of year [1:366]
691
692	// Note: The following fields exist for backward compatibility
693	// with older APIs. Accessing these fields directly is a sign of
694	// imprudent logic in the calling code. Modern time-related code
695	// should only access this data indirectly by way of FormatTime().
696	// These fields are undefined for InfiniteFuture() and InfinitePast().
697	int offset; // seconds east of UTC
698	bool is_dst; // is offset non-standard?
699	const char* zone_abbr; // time-zone abbreviation (e.g., "PST")
700	};
701
702	// Time::In()
703	//
704	// Returns the breakdown of this instant in the given TimeZone.
705	//
706	// Deprecated. Use `absl::TimeZone::At(Time)`.
707	Breakdown In(TimeZone tz) const;
708
709	template <typename H>
710	friend H AbslHashValue(H h, Time t) {
711	return H::combine(std::move(h), t.rep_);
712	}
713
714	private:
715	friend constexpr Time time_internal::FromUnixDuration(Duration d);
716	friend constexpr Duration time_internal::ToUnixDuration(Time t);
717	friend constexpr bool operator<(Time lhs, Time rhs);
718	friend constexpr bool operator==(Time lhs, Time rhs);
719	friend Duration operator-(Time lhs, Time rhs);
720	friend constexpr Time UniversalEpoch();
721	friend constexpr Time InfiniteFuture();
722	friend constexpr Time InfinitePast();
723	constexpr explicit Time(Duration rep) : rep_(rep) {}
724	Duration rep_;
725	};
726
727	// Relational Operators
728	constexpr bool operator<(Time lhs, Time rhs) { return lhs.rep_ < rhs.rep_; }
729	constexpr bool operator>(Time lhs, Time rhs) { return rhs < lhs; }
730	constexpr bool operator>=(Time lhs, Time rhs) { return !(lhs < rhs); }
731	constexpr bool operator<=(Time lhs, Time rhs) { return !(rhs < lhs); }
732	constexpr bool operator==(Time lhs, Time rhs) { return lhs.rep_ == rhs.rep_; }
733	constexpr bool operator!=(Time lhs, Time rhs) { return !(lhs == rhs); }
734
735	// Additive Operators
736	inline Time operator+(Time lhs, Duration rhs) { return lhs += rhs; }
737	inline Time operator+(Duration lhs, Time rhs) { return rhs += lhs; }
738	inline Time operator-(Time lhs, Duration rhs) { return lhs -= rhs; }
739	inline Duration operator-(Time lhs, Time rhs) { return lhs.rep_ - rhs.rep_; }
740
741	// UnixEpoch()
742	//
743	// Returns the `absl::Time` representing "1970-01-01 00:00:00.0 +0000".
744	constexpr Time UnixEpoch() { return Time(); }
745
746	// UniversalEpoch()
747	//
748	// Returns the `absl::Time` representing "0001-01-01 00:00:00.0 +0000", the
749	// epoch of the ICU Universal Time Scale.
750	constexpr Time UniversalEpoch() {
751	// 719162 is the number of days from 0001-01-01 to 1970-01-01,
752	// assuming the Gregorian calendar.
753	return Time(
754	time_internal::MakeDuration(hi: -24 * 719162 * int64_t{3600}, lo: uint32_t{0}));
755	}
756
757	// InfiniteFuture()
758	//
759	// Returns an `absl::Time` that is infinitely far in the future.
760	constexpr Time InfiniteFuture() {
761	return Time(time_internal::MakeDuration(hi: (std::numeric_limits<int64_t>::max)(),
762	lo: ~uint32_t{0}));
763	}
764
765	// InfinitePast()
766	//
767	// Returns an `absl::Time` that is infinitely far in the past.
768	constexpr Time InfinitePast() {
769	return Time(time_internal::MakeDuration(hi: (std::numeric_limits<int64_t>::min)(),
770	lo: ~uint32_t{0}));
771	}
772
773	// FromUnixNanos()
774	// FromUnixMicros()
775	// FromUnixMillis()
776	// FromUnixSeconds()
777	// FromTimeT()
778	// FromUDate()
779	// FromUniversal()
780	//
781	// Creates an `absl::Time` from a variety of other representations.
782	constexpr Time FromUnixNanos(int64_t ns);
783	constexpr Time FromUnixMicros(int64_t us);
784	constexpr Time FromUnixMillis(int64_t ms);
785	constexpr Time FromUnixSeconds(int64_t s);
786	constexpr Time FromTimeT(time_t t);
787	Time FromUDate(double udate);
788	Time FromUniversal(int64_t universal);
789
790	// ToUnixNanos()
791	// ToUnixMicros()
792	// ToUnixMillis()
793	// ToUnixSeconds()
794	// ToTimeT()
795	// ToUDate()
796	// ToUniversal()
797	//
798	// Converts an `absl::Time` to a variety of other representations. Note that
799	// these operations round down toward negative infinity where necessary to
800	// adjust to the resolution of the result type. Beware of possible time_t
801	// over/underflow in ToTime{T,val,spec}() on 32-bit platforms.
802	int64_t ToUnixNanos(Time t);
803	int64_t ToUnixMicros(Time t);
804	int64_t ToUnixMillis(Time t);
805	int64_t ToUnixSeconds(Time t);
806	time_t ToTimeT(Time t);
807	double ToUDate(Time t);
808	int64_t ToUniversal(Time t);
809
810	// DurationFromTimespec()
811	// DurationFromTimeval()
812	// ToTimespec()
813	// ToTimeval()
814	// TimeFromTimespec()
815	// TimeFromTimeval()
816	// ToTimespec()
817	// ToTimeval()
818	//
819	// Some APIs use a timespec or a timeval as a Duration (e.g., nanosleep(2)
820	// and select(2)), while others use them as a Time (e.g. clock_gettime(2)
821	// and gettimeofday(2)), so conversion functions are provided for both cases.
822	// The "to timespec/val" direction is easily handled via overloading, but
823	// for "from timespec/val" the desired type is part of the function name.
824	Duration DurationFromTimespec(timespec ts);
825	Duration DurationFromTimeval(timeval tv);
826	timespec ToTimespec(Duration d);
827	timeval ToTimeval(Duration d);
828	Time TimeFromTimespec(timespec ts);
829	Time TimeFromTimeval(timeval tv);
830	timespec ToTimespec(Time t);
831	timeval ToTimeval(Time t);
832
833	// FromChrono()
834	//
835	// Converts a std::chrono::system_clock::time_point to an absl::Time.
836	//
837	// Example:
838	//
839	// auto tp = std::chrono::system_clock::from_time_t(123);
840	// absl::Time t = absl::FromChrono(tp);
841	// // t == absl::FromTimeT(123)
842	Time FromChrono(const std::chrono::system_clock::time_point& tp);
843
844	// ToChronoTime()
845	//
846	// Converts an absl::Time to a std::chrono::system_clock::time_point. If
847	// overflow would occur, the returned value will saturate at the min/max time
848	// point value instead.
849	//
850	// Example:
851	//
852	// absl::Time t = absl::FromTimeT(123);
853	// auto tp = absl::ToChronoTime(t);
854	// // tp == std::chrono::system_clock::from_time_t(123);
855	std::chrono::system_clock::time_point ToChronoTime(Time);
856
857	// AbslParseFlag()
858	//
859	// Parses the command-line flag string representation `text` into a Time value.
860	// Time flags must be specified in a format that matches absl::RFC3339_full.
861	//
862	// For example:
863	//
864	// --start_time=2016-01-02T03:04:05.678+08:00
865	//
866	// Note: A UTC offset (or 'Z' indicating a zero-offset from UTC) is required.
867	//
868	// Additionally, if you'd like to specify a time as a count of
869	// seconds/milliseconds/etc from the Unix epoch, use an absl::Duration flag
870	// and add that duration to absl::UnixEpoch() to get an absl::Time.
871	bool AbslParseFlag(absl::string_view text, Time* t, std::string* error);
872
873	// AbslUnparseFlag()
874	//
875	// Unparses a Time value into a command-line string representation using
876	// the format specified by `absl::ParseTime()`.
877	std::string AbslUnparseFlag(Time t);
878
879	ABSL_DEPRECATED("Use AbslParseFlag() instead.")
880	bool ParseFlag(const std::string& text, Time* t, std::string* error);
881	ABSL_DEPRECATED("Use AbslUnparseFlag() instead.")
882	std::string UnparseFlag(Time t);
883
884	// TimeZone
885	//
886	// The `absl::TimeZone` is an opaque, small, value-type class representing a
887	// geo-political region within which particular rules are used for converting
888	// between absolute and civil times (see https://git.io/v59Ly). `absl::TimeZone`
889	// values are named using the TZ identifiers from the IANA Time Zone Database,
890	// such as "America/Los_Angeles" or "Australia/Sydney". `absl::TimeZone` values
891	// are created from factory functions such as `absl::LoadTimeZone()`. Note:
892	// strings like "PST" and "EDT" are not valid TZ identifiers. Prefer to pass by
893	// value rather than const reference.
894	//
895	// For more on the fundamental concepts of time zones, absolute times, and civil
896	// times, see https://github.com/google/cctz#fundamental-concepts
897	//
898	// Examples:
899	//
900	// absl::TimeZone utc = absl::UTCTimeZone();
901	// absl::TimeZone pst = absl::FixedTimeZone(-8 * 60 * 60);
902	// absl::TimeZone loc = absl::LocalTimeZone();
903	// absl::TimeZone lax;
904	// if (!absl::LoadTimeZone("America/Los_Angeles", &lax)) {
905	// // handle error case
906	// }
907	//
908	// See also:
909	// - https://github.com/google/cctz
910	// - https://www.iana.org/time-zones
911	// - https://en.wikipedia.org/wiki/Zoneinfo
912	class TimeZone {
913	public:
914	explicit TimeZone(time_internal::cctz::time_zone tz) : cz_(tz) {}
915	TimeZone() = default; // UTC, but prefer UTCTimeZone() to be explicit.
916
917	// Copyable.
918	TimeZone(const TimeZone&) = default;
919	TimeZone& operator=(const TimeZone&) = default;
920
921	explicit operator time_internal::cctz::time_zone() const { return cz_; }
922
923	std::string name() const { return cz_.name(); }
924
925	// TimeZone::CivilInfo
926	//
927	// Information about the civil time corresponding to an absolute time.
928	// This struct is not intended to represent an instant in time. So, rather
929	// than passing a `TimeZone::CivilInfo` to a function, pass an `absl::Time`
930	// and an `absl::TimeZone`.
931	struct CivilInfo {
932	CivilSecond cs;
933	Duration subsecond;
934
935	// Note: The following fields exist for backward compatibility
936	// with older APIs. Accessing these fields directly is a sign of
937	// imprudent logic in the calling code. Modern time-related code
938	// should only access this data indirectly by way of FormatTime().
939	// These fields are undefined for InfiniteFuture() and InfinitePast().
940	int offset; // seconds east of UTC
941	bool is_dst; // is offset non-standard?
942	const char* zone_abbr; // time-zone abbreviation (e.g., "PST")
943	};
944
945	// TimeZone::At(Time)
946	//
947	// Returns the civil time for this TimeZone at a certain `absl::Time`.
948	// If the input time is infinite, the output civil second will be set to
949	// CivilSecond::max() or min(), and the subsecond will be infinite.
950	//
951	// Example:
952	//
953	// const auto epoch = lax.At(absl::UnixEpoch());
954	// // epoch.cs == 1969-12-31 16:00:00
955	// // epoch.subsecond == absl::ZeroDuration()
956	// // epoch.offset == -28800
957	// // epoch.is_dst == false
958	// // epoch.abbr == "PST"
959	CivilInfo At(Time t) const;
960
961	// TimeZone::TimeInfo
962	//
963	// Information about the absolute times corresponding to a civil time.
964	// (Subseconds must be handled separately.)
965	//
966	// It is possible for a caller to pass a civil-time value that does
967	// not represent an actual or unique instant in time (due to a shift
968	// in UTC offset in the TimeZone, which results in a discontinuity in
969	// the civil-time components). For example, a daylight-saving-time
970	// transition skips or repeats civil times---in the United States,
971	// March 13, 2011 02:15 never occurred, while November 6, 2011 01:15
972	// occurred twice---so requests for such times are not well-defined.
973	// To account for these possibilities, `absl::TimeZone::TimeInfo` is
974	// richer than just a single `absl::Time`.
975	struct TimeInfo {
976	enum CivilKind {
977	UNIQUE, // the civil time was singular (pre == trans == post)
978	SKIPPED, // the civil time did not exist (pre >= trans > post)
979	REPEATED, // the civil time was ambiguous (pre < trans <= post)
980	} kind;
981	Time pre; // time calculated using the pre-transition offset
982	Time trans; // when the civil-time discontinuity occurred
983	Time post; // time calculated using the post-transition offset
984	};
985
986	// TimeZone::At(CivilSecond)
987	//
988	// Returns an `absl::TimeInfo` containing the absolute time(s) for this
989	// TimeZone at an `absl::CivilSecond`. When the civil time is skipped or
990	// repeated, returns times calculated using the pre-transition and post-
991	// transition UTC offsets, plus the transition time itself.
992	//
993	// Examples:
994	//
995	// // A unique civil time
996	// const auto jan01 = lax.At(absl::CivilSecond(2011, 1, 1, 0, 0, 0));
997	// // jan01.kind == TimeZone::TimeInfo::UNIQUE
998	// // jan01.pre is 2011-01-01 00:00:00 -0800
999	// // jan01.trans is 2011-01-01 00:00:00 -0800
1000	// // jan01.post is 2011-01-01 00:00:00 -0800
1001	//
1002	// // A Spring DST transition, when there is a gap in civil time
1003	// const auto mar13 = lax.At(absl::CivilSecond(2011, 3, 13, 2, 15, 0));
1004	// // mar13.kind == TimeZone::TimeInfo::SKIPPED
1005	// // mar13.pre is 2011-03-13 03:15:00 -0700
1006	// // mar13.trans is 2011-03-13 03:00:00 -0700
1007	// // mar13.post is 2011-03-13 01:15:00 -0800
1008	//
1009	// // A Fall DST transition, when civil times are repeated
1010	// const auto nov06 = lax.At(absl::CivilSecond(2011, 11, 6, 1, 15, 0));
1011	// // nov06.kind == TimeZone::TimeInfo::REPEATED
1012	// // nov06.pre is 2011-11-06 01:15:00 -0700
1013	// // nov06.trans is 2011-11-06 01:00:00 -0800
1014	// // nov06.post is 2011-11-06 01:15:00 -0800
1015	TimeInfo At(CivilSecond ct) const;
1016
1017	// TimeZone::NextTransition()
1018	// TimeZone::PrevTransition()
1019	//
1020	// Finds the time of the next/previous offset change in this time zone.
1021	//
1022	// By definition, `NextTransition(t, &trans)` returns false when `t` is
1023	// `InfiniteFuture()`, and `PrevTransition(t, &trans)` returns false
1024	// when `t` is `InfinitePast()`. If the zone has no transitions, the
1025	// result will also be false no matter what the argument.
1026	//
1027	// Otherwise, when `t` is `InfinitePast()`, `NextTransition(t, &trans)`
1028	// returns true and sets `trans` to the first recorded transition. Chains
1029	// of calls to `NextTransition()/PrevTransition()` will eventually return
1030	// false, but it is unspecified exactly when `NextTransition(t, &trans)`
1031	// jumps to false, or what time is set by `PrevTransition(t, &trans)` for
1032	// a very distant `t`.
1033	//
1034	// Note: Enumeration of time-zone transitions is for informational purposes
1035	// only. Modern time-related code should not care about when offset changes
1036	// occur.
1037	//
1038	// Example:
1039	// absl::TimeZone nyc;
1040	// if (!absl::LoadTimeZone("America/New_York", &nyc)) { ... }
1041	// const auto now = absl::Now();
1042	// auto t = absl::InfinitePast();
1043	// absl::TimeZone::CivilTransition trans;
1044	// while (t <= now && nyc.NextTransition(t, &trans)) {
1045	// // transition: trans.from -> trans.to
1046	// t = nyc.At(trans.to).trans;
1047	// }
1048	struct CivilTransition {
1049	CivilSecond from; // the civil time we jump from
1050	CivilSecond to; // the civil time we jump to
1051	};
1052	bool NextTransition(Time t, CivilTransition* trans) const;
1053	bool PrevTransition(Time t, CivilTransition* trans) const;
1054
1055	template <typename H>
1056	friend H AbslHashValue(H h, TimeZone tz) {
1057	return H::combine(std::move(h), tz.cz_);
1058	}
1059
1060	private:
1061	friend bool operator==(TimeZone a, TimeZone b) { return a.cz_ == b.cz_; }
1062	friend bool operator!=(TimeZone a, TimeZone b) { return a.cz_ != b.cz_; }
1063	friend std::ostream& operator<<(std::ostream& os, TimeZone tz) {
1064	return os << tz.name();
1065	}
1066
1067	time_internal::cctz::time_zone cz_;
1068	};
1069
1070	// LoadTimeZone()
1071	//
1072	// Loads the named zone. May perform I/O on the initial load of the named
1073	// zone. If the name is invalid, or some other kind of error occurs, returns
1074	// `false` and `*tz` is set to the UTC time zone.
1075	inline bool LoadTimeZone(absl::string_view name, TimeZone* tz) {
1076	if (name == "localtime") {
1077	*tz = TimeZone(time_internal::cctz::local_time_zone());
1078	return true;
1079	}
1080	time_internal::cctz::time_zone cz;
1081	const bool b = time_internal::cctz::load_time_zone(name: std::string(name), tz: &cz);
1082	*tz = TimeZone(cz);
1083	return b;
1084	}
1085
1086	// FixedTimeZone()
1087	//
1088	// Returns a TimeZone that is a fixed offset (seconds east) from UTC.
1089	// Note: If the absolute value of the offset is greater than 24 hours
1090	// you'll get UTC (i.e., no offset) instead.
1091	inline TimeZone FixedTimeZone(int seconds) {
1092	return TimeZone(
1093	time_internal::cctz::fixed_time_zone(offset: std::chrono::seconds(seconds)));
1094	}
1095
1096	// UTCTimeZone()
1097	//
1098	// Convenience method returning the UTC time zone.
1099	inline TimeZone UTCTimeZone() {
1100	return TimeZone(time_internal::cctz::utc_time_zone());
1101	}
1102
1103	// LocalTimeZone()
1104	//
1105	// Convenience method returning the local time zone, or UTC if there is
1106	// no configured local zone. Warning: Be wary of using LocalTimeZone(),
1107	// and particularly so in a server process, as the zone configured for the
1108	// local machine should be irrelevant. Prefer an explicit zone name.
1109	inline TimeZone LocalTimeZone() {
1110	return TimeZone(time_internal::cctz::local_time_zone());
1111	}
1112
1113	// ToCivilSecond()
1114	// ToCivilMinute()
1115	// ToCivilHour()
1116	// ToCivilDay()
1117	// ToCivilMonth()
1118	// ToCivilYear()
1119	//
1120	// Helpers for TimeZone::At(Time) to return particularly aligned civil times.
1121	//
1122	// Example:
1123	//
1124	// absl::Time t = ...;
1125	// absl::TimeZone tz = ...;
1126	// const auto cd = absl::ToCivilDay(t, tz);
1127	inline CivilSecond ToCivilSecond(Time t, TimeZone tz) {
1128	return tz.At(t).cs; // already a CivilSecond
1129	}
1130	inline CivilMinute ToCivilMinute(Time t, TimeZone tz) {
1131	return CivilMinute(tz.At(t).cs);
1132	}
1133	inline CivilHour ToCivilHour(Time t, TimeZone tz) {
1134	return CivilHour(tz.At(t).cs);
1135	}
1136	inline CivilDay ToCivilDay(Time t, TimeZone tz) {
1137	return CivilDay(tz.At(t).cs);
1138	}
1139	inline CivilMonth ToCivilMonth(Time t, TimeZone tz) {
1140	return CivilMonth(tz.At(t).cs);
1141	}
1142	inline CivilYear ToCivilYear(Time t, TimeZone tz) {
1143	return CivilYear(tz.At(t).cs);
1144	}
1145
1146	// FromCivil()
1147	//
1148	// Helper for TimeZone::At(CivilSecond) that provides "order-preserving
1149	// semantics." If the civil time maps to a unique time, that time is
1150	// returned. If the civil time is repeated in the given time zone, the
1151	// time using the pre-transition offset is returned. Otherwise, the
1152	// civil time is skipped in the given time zone, and the transition time
1153	// is returned. This means that for any two civil times, ct1 and ct2,
1154	// (ct1 < ct2) => (FromCivil(ct1) <= FromCivil(ct2)), the equal case
1155	// being when two non-existent civil times map to the same transition time.
1156	//
1157	// Note: Accepts civil times of any alignment.
1158	inline Time FromCivil(CivilSecond ct, TimeZone tz) {
1159	const auto ti = tz.At(ct);
1160	if (ti.kind == TimeZone::TimeInfo::SKIPPED) return ti.trans;
1161	return ti.pre;
1162	}
1163
1164	// TimeConversion
1165	//
1166	// An `absl::TimeConversion` represents the conversion of year, month, day,
1167	// hour, minute, and second values (i.e., a civil time), in a particular
1168	// `absl::TimeZone`, to a time instant (an absolute time), as returned by
1169	// `absl::ConvertDateTime()`. Legacy version of `absl::TimeZone::TimeInfo`.
1170	//
1171	// Deprecated. Use `absl::TimeZone::TimeInfo`.
1172	struct
1173	TimeConversion {
1174	Time pre; // time calculated using the pre-transition offset
1175	Time trans; // when the civil-time discontinuity occurred
1176	Time post; // time calculated using the post-transition offset
1177
1178	enum Kind {
1179	UNIQUE, // the civil time was singular (pre == trans == post)
1180	SKIPPED, // the civil time did not exist
1181	REPEATED, // the civil time was ambiguous
1182	};
1183	Kind kind;
1184
1185	bool normalized; // input values were outside their valid ranges
1186	};
1187
1188	// ConvertDateTime()
1189	//
1190	// Legacy version of `absl::TimeZone::At(absl::CivilSecond)` that takes
1191	// the civil time as six, separate values (YMDHMS).
1192	//
1193	// The input month, day, hour, minute, and second values can be outside
1194	// of their valid ranges, in which case they will be "normalized" during
1195	// the conversion.
1196	//
1197	// Example:
1198	//
1199	// // "October 32" normalizes to "November 1".
1200	// absl::TimeConversion tc =
1201	// absl::ConvertDateTime(2013, 10, 32, 8, 30, 0, lax);
1202	// // tc.kind == TimeConversion::UNIQUE && tc.normalized == true
1203	// // absl::ToCivilDay(tc.pre, tz).month() == 11
1204	// // absl::ToCivilDay(tc.pre, tz).day() == 1
1205	//
1206	// Deprecated. Use `absl::TimeZone::At(CivilSecond)`.
1207	TimeConversion ConvertDateTime(int64_t year, int mon, int day, int hour,
1208	int min, int sec, TimeZone tz);
1209
1210	// FromDateTime()
1211	//
1212	// A convenience wrapper for `absl::ConvertDateTime()` that simply returns
1213	// the "pre" `absl::Time`. That is, the unique result, or the instant that
1214	// is correct using the pre-transition offset (as if the transition never
1215	// happened).
1216	//
1217	// Example:
1218	//
1219	// absl::Time t = absl::FromDateTime(2017, 9, 26, 9, 30, 0, lax);
1220	// // t = 2017-09-26 09:30:00 -0700
1221	//
1222	// Deprecated. Use `absl::FromCivil(CivilSecond, TimeZone)`. Note that the
1223	// behavior of `FromCivil()` differs from `FromDateTime()` for skipped civil
1224	// times. If you care about that see `absl::TimeZone::At(absl::CivilSecond)`.
1225	inline Time FromDateTime(int64_t year, int mon, int day, int hour,
1226	int min, int sec, TimeZone tz) {
1227	return ConvertDateTime(year, mon, day, hour, min, sec, tz).pre;
1228	}
1229
1230	// FromTM()
1231	//
1232	// Converts the `tm_year`, `tm_mon`, `tm_mday`, `tm_hour`, `tm_min`, and
1233	// `tm_sec` fields to an `absl::Time` using the given time zone. See ctime(3)
1234	// for a description of the expected values of the tm fields. If the civil time
1235	// is unique (see `absl::TimeZone::At(absl::CivilSecond)` above), the matching
1236	// time instant is returned. Otherwise, the `tm_isdst` field is consulted to
1237	// choose between the possible results. For a repeated civil time, `tm_isdst !=
1238	// 0` returns the matching DST instant, while `tm_isdst == 0` returns the
1239	// matching non-DST instant. For a skipped civil time there is no matching
1240	// instant, so `tm_isdst != 0` returns the DST instant, and `tm_isdst == 0`
1241	// returns the non-DST instant, that would have matched if the transition never
1242	// happened.
1243	Time FromTM(const struct tm& tm, TimeZone tz);
1244
1245	// ToTM()
1246	//
1247	// Converts the given `absl::Time` to a struct tm using the given time zone.
1248	// See ctime(3) for a description of the values of the tm fields.
1249	struct tm ToTM(Time t, TimeZone tz);
1250
1251	// RFC3339_full
1252	// RFC3339_sec
1253	//
1254	// FormatTime()/ParseTime() format specifiers for RFC3339 date/time strings,
1255	// with trailing zeros trimmed or with fractional seconds omitted altogether.
1256	//
1257	// Note that RFC3339_sec[] matches an ISO 8601 extended format for date and
1258	// time with UTC offset. Also note the use of "%Y": RFC3339 mandates that
1259	// years have exactly four digits, but we allow them to take their natural
1260	// width.
1261	ABSL_DLL extern const char RFC3339_full[]; // %Y-%m-%d%ET%H:%M:%E*S%Ez
1262	ABSL_DLL extern const char RFC3339_sec[]; // %Y-%m-%d%ET%H:%M:%S%Ez
1263
1264	// RFC1123_full
1265	// RFC1123_no_wday
1266	//
1267	// FormatTime()/ParseTime() format specifiers for RFC1123 date/time strings.
1268	ABSL_DLL extern const char RFC1123_full[]; // %a, %d %b %E4Y %H:%M:%S %z
1269	ABSL_DLL extern const char RFC1123_no_wday[]; // %d %b %E4Y %H:%M:%S %z
1270
1271	// FormatTime()
1272	//
1273	// Formats the given `absl::Time` in the `absl::TimeZone` according to the
1274	// provided format string. Uses strftime()-like formatting options, with
1275	// the following extensions:
1276	//
1277	// - %Ez - RFC3339-compatible numeric UTC offset (+hh:mm or -hh:mm)
1278	// - %E*z - Full-resolution numeric UTC offset (+hh:mm:ss or -hh:mm:ss)
1279	// - %E#S - Seconds with # digits of fractional precision
1280	// - %E*S - Seconds with full fractional precision (a literal '*')
1281	// - %E#f - Fractional seconds with # digits of precision
1282	// - %E*f - Fractional seconds with full precision (a literal '*')
1283	// - %E4Y - Four-character years (-999 ... -001, 0000, 0001 ... 9999)
1284	// - %ET - The RFC3339 "date-time" separator "T"
1285	//
1286	// Note that %E0S behaves like %S, and %E0f produces no characters. In
1287	// contrast %E*f always produces at least one digit, which may be '0'.
1288	//
1289	// Note that %Y produces as many characters as it takes to fully render the
1290	// year. A year outside of [-999:9999] when formatted with %E4Y will produce
1291	// more than four characters, just like %Y.
1292	//
1293	// We recommend that format strings include the UTC offset (%z, %Ez, or %E*z)
1294	// so that the result uniquely identifies a time instant.
1295	//
1296	// Example:
1297	//
1298	// absl::CivilSecond cs(2013, 1, 2, 3, 4, 5);
1299	// absl::Time t = absl::FromCivil(cs, lax);
1300	// std::string f = absl::FormatTime("%H:%M:%S", t, lax); // "03:04:05"
1301	// f = absl::FormatTime("%H:%M:%E3S", t, lax); // "03:04:05.000"
1302	//
1303	// Note: If the given `absl::Time` is `absl::InfiniteFuture()`, the returned
1304	// string will be exactly "infinite-future". If the given `absl::Time` is
1305	// `absl::InfinitePast()`, the returned string will be exactly "infinite-past".
1306	// In both cases the given format string and `absl::TimeZone` are ignored.
1307	//
1308	std::string FormatTime(absl::string_view format, Time t, TimeZone tz);
1309
1310	// Convenience functions that format the given time using the RFC3339_full
1311	// format. The first overload uses the provided TimeZone, while the second
1312	// uses LocalTimeZone().
1313	std::string FormatTime(Time t, TimeZone tz);
1314	std::string FormatTime(Time t);
1315
1316	// Output stream operator.
1317	inline std::ostream& operator<<(std::ostream& os, Time t) {
1318	return os << FormatTime(t);
1319	}
1320
1321	// ParseTime()
1322	//
1323	// Parses an input string according to the provided format string and
1324	// returns the corresponding `absl::Time`. Uses strftime()-like formatting
1325	// options, with the same extensions as FormatTime(), but with the
1326	// exceptions that %E#S is interpreted as %E*S, and %E#f as %E*f. %Ez
1327	// and %E*z also accept the same inputs, which (along with %z) includes
1328	// 'z' and 'Z' as synonyms for +00:00. %ET accepts either 'T' or 't'.
1329	//
1330	// %Y consumes as many numeric characters as it can, so the matching data
1331	// should always be terminated with a non-numeric. %E4Y always consumes
1332	// exactly four characters, including any sign.
1333	//
1334	// Unspecified fields are taken from the default date and time of ...
1335	//
1336	// "1970-01-01 00:00:00.0 +0000"
1337	//
1338	// For example, parsing a string of "15:45" (%H:%M) will return an absl::Time
1339	// that represents "1970-01-01 15:45:00.0 +0000".
1340	//
1341	// Note that since ParseTime() returns time instants, it makes the most sense
1342	// to parse fully-specified date/time strings that include a UTC offset (%z,
1343	// %Ez, or %E*z).
1344	//
1345	// Note also that `absl::ParseTime()` only heeds the fields year, month, day,
1346	// hour, minute, (fractional) second, and UTC offset. Other fields, like
1347	// weekday (%a or %A), while parsed for syntactic validity, are ignored
1348	// in the conversion.
1349	//
1350	// Date and time fields that are out-of-range will be treated as errors
1351	// rather than normalizing them like `absl::CivilSecond` does. For example,
1352	// it is an error to parse the date "Oct 32, 2013" because 32 is out of range.
1353	//
1354	// A leap second of ":60" is normalized to ":00" of the following minute
1355	// with fractional seconds discarded. The following table shows how the
1356	// given seconds and subseconds will be parsed:
1357	//
1358	// "59.x" -> 59.x // exact
1359	// "60.x" -> 00.0 // normalized
1360	// "00.x" -> 00.x // exact
1361	//
1362	// Errors are indicated by returning false and assigning an error message
1363	// to the "err" out param if it is non-null.
1364	//
1365	// Note: If the input string is exactly "infinite-future", the returned
1366	// `absl::Time` will be `absl::InfiniteFuture()` and `true` will be returned.
1367	// If the input string is "infinite-past", the returned `absl::Time` will be
1368	// `absl::InfinitePast()` and `true` will be returned.
1369	//
1370	bool ParseTime(absl::string_view format, absl::string_view input, Time* time,
1371	std::string* err);
1372
1373	// Like ParseTime() above, but if the format string does not contain a UTC
1374	// offset specification (%z/%Ez/%E*z) then the input is interpreted in the
1375	// given TimeZone. This means that the input, by itself, does not identify a
1376	// unique instant. Being time-zone dependent, it also admits the possibility
1377	// of ambiguity or non-existence, in which case the "pre" time (as defined
1378	// by TimeZone::TimeInfo) is returned. For these reasons we recommend that
1379	// all date/time strings include a UTC offset so they're context independent.
1380	bool ParseTime(absl::string_view format, absl::string_view input, TimeZone tz,
1381	Time* time, std::string* err);
1382
1383	// ============================================================================
1384	// Implementation Details Follow
1385	// ============================================================================
1386
1387	namespace time_internal {
1388
1389	// Creates a Duration with a given representation.
1390	// REQUIRES: hi,lo is a valid representation of a Duration as specified
1391	// in time/duration.cc.
1392	constexpr Duration MakeDuration(int64_t hi, uint32_t lo = 0) {
1393	return Duration(hi, lo);
1394	}
1395
1396	constexpr Duration MakeDuration(int64_t hi, int64_t lo) {
1397	return MakeDuration(hi, lo: static_cast<uint32_t>(lo));
1398	}
1399
1400	// Make a Duration value from a floating-point number, as long as that number
1401	// is in the range [ 0 .. numeric_limits<int64_t>::max ), that is, as long as
1402	// it's positive and can be converted to int64_t without risk of UB.
1403	inline Duration MakePosDoubleDuration(double n) {
1404	const int64_t int_secs = static_cast<int64_t>(n);
1405	const uint32_t ticks = static_cast<uint32_t>(
1406	std::round(x: (n - static_cast<double>(int_secs)) * kTicksPerSecond));
1407	return ticks < kTicksPerSecond
1408	? MakeDuration(hi: int_secs, lo: ticks)
1409	: MakeDuration(hi: int_secs + 1, lo: ticks - kTicksPerSecond);
1410	}
1411
1412	// Creates a normalized Duration from an almost-normalized (sec,ticks)
1413	// pair. sec may be positive or negative. ticks must be in the range
1414	// -kTicksPerSecond < *ticks < kTicksPerSecond. If ticks is negative it
1415	// will be normalized to a positive value in the resulting Duration.
1416	constexpr Duration MakeNormalizedDuration(int64_t sec, int64_t ticks) {
1417	return (ticks < 0) ? MakeDuration(hi: sec - 1, lo: ticks + kTicksPerSecond)
1418	: MakeDuration(hi: sec, lo: ticks);
1419	}
1420
1421	// Provide access to the Duration representation.
1422	constexpr int64_t GetRepHi(Duration d) { return d.rep_hi_; }
1423	constexpr uint32_t GetRepLo(Duration d) { return d.rep_lo_; }
1424
1425	// Returns true iff d is positive or negative infinity.
1426	constexpr bool IsInfiniteDuration(Duration d) {
1427	return GetRepLo(d) == ~uint32_t{0};
1428	}
1429
1430	// Returns an infinite Duration with the opposite sign.
1431	// REQUIRES: IsInfiniteDuration(d)
1432	constexpr Duration OppositeInfinity(Duration d) {
1433	return GetRepHi(d) < 0
1434	? MakeDuration(hi: (std::numeric_limits<int64_t>::max)(), lo: ~uint32_t{0})
1435	: MakeDuration(hi: (std::numeric_limits<int64_t>::min)(),
1436	lo: ~uint32_t{0});
1437	}
1438
1439	// Returns (-n)-1 (equivalently -(n+1)) without avoidable overflow.
1440	constexpr int64_t NegateAndSubtractOne(int64_t n) {
1441	// Note: Good compilers will optimize this expression to ~n when using
1442	// a two's-complement representation (which is required for int64_t).
1443	return (n < 0) ? -(n + 1) : (-n) - 1;
1444	}
1445
1446	// Map between a Time and a Duration since the Unix epoch. Note that these
1447	// functions depend on the above mentioned choice of the Unix epoch for the
1448	// Time representation (and both need to be Time friends). Without this
1449	// knowledge, we would need to add-in/subtract-out UnixEpoch() respectively.
1450	constexpr Time FromUnixDuration(Duration d) { return Time(d); }
1451	constexpr Duration ToUnixDuration(Time t) { return t.rep_; }
1452
1453	template <std::intmax_t N>
1454	constexpr Duration FromInt64(int64_t v, std::ratio<1, N>) {
1455	static_assert(0 < N && N <= 1000 * 1000 * 1000, "Unsupported ratio");
1456	// Subsecond ratios cannot overflow.
1457	return MakeNormalizedDuration(
1458	sec: v / N, ticks: v % N * kTicksPerNanosecond * 1000 * 1000 * 1000 / N);
1459	}
1460	constexpr Duration FromInt64(int64_t v, std::ratio<60>) {
1461	return (v <= (std::numeric_limits<int64_t>::max)() / 60 &&
1462	v >= (std::numeric_limits<int64_t>::min)() / 60)
1463	? MakeDuration(hi: v * 60)
1464	: v > 0 ? InfiniteDuration() : -InfiniteDuration();
1465	}
1466	constexpr Duration FromInt64(int64_t v, std::ratio<3600>) {
1467	return (v <= (std::numeric_limits<int64_t>::max)() / 3600 &&
1468	v >= (std::numeric_limits<int64_t>::min)() / 3600)
1469	? MakeDuration(hi: v * 3600)
1470	: v > 0 ? InfiniteDuration() : -InfiniteDuration();
1471	}
1472
1473	// IsValidRep64<T>(0) is true if the expression `int64_t{std::declval<T>()}` is
1474	// valid. That is, if a T can be assigned to an int64_t without narrowing.
1475	template <typename T>
1476	constexpr auto IsValidRep64(int) -> decltype(int64_t{std::declval<T>()} == 0) {
1477	return true;
1478	}
1479	template <typename T>
1480	constexpr auto IsValidRep64(char) -> bool {
1481	return false;
1482	}
1483
1484	// Converts a std::chrono::duration to an absl::Duration.
1485	template <typename Rep, typename Period>
1486	constexpr Duration FromChrono(const std::chrono::duration<Rep, Period>& d) {
1487	static_assert(IsValidRep64<Rep>(0), "duration::rep is invalid");
1488	return FromInt64(int64_t{d.count()}, Period{});
1489	}
1490
1491	template <typename Ratio>
1492	int64_t ToInt64(Duration d, Ratio) {
1493	// Note: This may be used on MSVC, which may have a system_clock period of
1494	// std::ratio<1, 10 * 1000 * 1000>
1495	return ToInt64Seconds(d * Ratio::den / Ratio::num);
1496	}
1497	// Fastpath implementations for the 6 common duration units.
1498	inline int64_t ToInt64(Duration d, std::nano) {
1499	return ToInt64Nanoseconds(d);
1500	}
1501	inline int64_t ToInt64(Duration d, std::micro) {
1502	return ToInt64Microseconds(d);
1503	}
1504	inline int64_t ToInt64(Duration d, std::milli) {
1505	return ToInt64Milliseconds(d);
1506	}
1507	inline int64_t ToInt64(Duration d, std::ratio<1>) {
1508	return ToInt64Seconds(d);
1509	}
1510	inline int64_t ToInt64(Duration d, std::ratio<60>) {
1511	return ToInt64Minutes(d);
1512	}
1513	inline int64_t ToInt64(Duration d, std::ratio<3600>) {
1514	return ToInt64Hours(d);
1515	}
1516
1517	// Converts an absl::Duration to a chrono duration of type T.
1518	template <typename T>
1519	T ToChronoDuration(Duration d) {
1520	using Rep = typename T::rep;
1521	using Period = typename T::period;
1522	static_assert(IsValidRep64<Rep>(0), "duration::rep is invalid");
1523	if (time_internal::IsInfiniteDuration(d))
1524	return d < ZeroDuration() ? (T::min)() : (T::max)();
1525	const auto v = ToInt64(d, Period{});
1526	if (v > (std::numeric_limits<Rep>::max)()) return (T::max)();
1527	if (v < (std::numeric_limits<Rep>::min)()) return (T::min)();
1528	return T{v};
1529	}
1530
1531	} // namespace time_internal
1532
1533	constexpr bool operator<(Duration lhs, Duration rhs) {
1534	return time_internal::GetRepHi(d: lhs) != time_internal::GetRepHi(d: rhs)
1535	? time_internal::GetRepHi(d: lhs) < time_internal::GetRepHi(d: rhs)
1536	: time_internal::GetRepHi(d: lhs) == (std::numeric_limits<int64_t>::min)()
1537	? time_internal::GetRepLo(d: lhs) + 1 <
1538	time_internal::GetRepLo(d: rhs) + 1
1539	: time_internal::GetRepLo(d: lhs) < time_internal::GetRepLo(d: rhs);
1540	}
1541
1542	constexpr bool operator==(Duration lhs, Duration rhs) {
1543	return time_internal::GetRepHi(d: lhs) == time_internal::GetRepHi(d: rhs) &&
1544	time_internal::GetRepLo(d: lhs) == time_internal::GetRepLo(d: rhs);
1545	}
1546
1547	constexpr Duration operator-(Duration d) {
1548	// This is a little interesting because of the special cases.
1549	//
1550	// If rep_lo_ is zero, we have it easy; it's safe to negate rep_hi_, we're
1551	// dealing with an integral number of seconds, and the only special case is
1552	// the maximum negative finite duration, which can't be negated.
1553	//
1554	// Infinities stay infinite, and just change direction.
1555	//
1556	// Finally we're in the case where rep_lo_ is non-zero, and we can borrow
1557	// a second's worth of ticks and avoid overflow (as negating int64_t-min + 1
1558	// is safe).
1559	return time_internal::GetRepLo(d) == 0
1560	? time_internal::GetRepHi(d) ==
1561	(std::numeric_limits<int64_t>::min)()
1562	? InfiniteDuration()
1563	: time_internal::MakeDuration(hi: -time_internal::GetRepHi(d))
1564	: time_internal::IsInfiniteDuration(d)
1565	? time_internal::OppositeInfinity(d)
1566	: time_internal::MakeDuration(
1567	hi: time_internal::NegateAndSubtractOne(
1568	n: time_internal::GetRepHi(d)),
1569	lo: time_internal::kTicksPerSecond -
1570	time_internal::GetRepLo(d));
1571	}
1572
1573	constexpr Duration InfiniteDuration() {
1574	return time_internal::MakeDuration(hi: (std::numeric_limits<int64_t>::max)(),
1575	lo: ~uint32_t{0});
1576	}
1577
1578	constexpr Duration FromChrono(const std::chrono::nanoseconds& d) {
1579	return time_internal::FromChrono(d);
1580	}
1581	constexpr Duration FromChrono(const std::chrono::microseconds& d) {
1582	return time_internal::FromChrono(d);
1583	}
1584	constexpr Duration FromChrono(const std::chrono::milliseconds& d) {
1585	return time_internal::FromChrono(d);
1586	}
1587	constexpr Duration FromChrono(const std::chrono::seconds& d) {
1588	return time_internal::FromChrono(d);
1589	}
1590	constexpr Duration FromChrono(const std::chrono::minutes& d) {
1591	return time_internal::FromChrono(d);
1592	}
1593	constexpr Duration FromChrono(const std::chrono::hours& d) {
1594	return time_internal::FromChrono(d);
1595	}
1596
1597	constexpr Time FromUnixNanos(int64_t ns) {
1598	return time_internal::FromUnixDuration(d: Nanoseconds(n: ns));
1599	}
1600
1601	constexpr Time FromUnixMicros(int64_t us) {
1602	return time_internal::FromUnixDuration(d: Microseconds(n: us));
1603	}
1604
1605	constexpr Time FromUnixMillis(int64_t ms) {
1606	return time_internal::FromUnixDuration(d: Milliseconds(n: ms));
1607	}
1608
1609	constexpr Time FromUnixSeconds(int64_t s) {
1610	return time_internal::FromUnixDuration(d: Seconds(n: s));
1611	}
1612
1613	constexpr Time FromTimeT(time_t t) {
1614	return time_internal::FromUnixDuration(d: Seconds(n: t));
1615	}
1616
1617	ABSL_NAMESPACE_END
1618	} // namespace absl
1619
1620	#endif // ABSL_TIME_TIME_H_
1621