1// Copyright 2018 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: civil_time.h
17// -----------------------------------------------------------------------------
18//
19// This header file defines abstractions for computing with "civil time".
20// The term "civil time" refers to the legally recognized human-scale time
21// that is represented by the six fields `YYYY-MM-DD hh:mm:ss`. A "date"
22// is perhaps the most common example of a civil time (represented here as
23// an `absl::CivilDay`).
24//
25// Modern-day civil time follows the Gregorian Calendar and is a
26// time-zone-independent concept: a civil time of "2015-06-01 12:00:00", for
27// example, is not tied to a time zone. Put another way, a civil time does not
28// map to a unique point in time; a civil time must be mapped to an absolute
29// time *through* a time zone.
30//
31// Because a civil time is what most people think of as "time," it is common to
32// map absolute times to civil times to present to users.
33//
34// Time zones define the relationship between absolute and civil times. Given an
35// absolute or civil time and a time zone, you can compute the other time:
36//
37// Civil Time = F(Absolute Time, Time Zone)
38// Absolute Time = G(Civil Time, Time Zone)
39//
40// The Abseil time library allows you to construct such civil times from
41// absolute times; consult time.h for such functionality.
42//
43// This library provides six classes for constructing civil-time objects, and
44// provides several helper functions for rounding, iterating, and performing
45// arithmetic on civil-time objects, while avoiding complications like
46// daylight-saving time (DST):
47//
48// * `absl::CivilSecond`
49// * `absl::CivilMinute`
50// * `absl::CivilHour`
51// * `absl::CivilDay`
52// * `absl::CivilMonth`
53// * `absl::CivilYear`
54//
55// Example:
56//
57// // Construct a civil-time object for a specific day
58// const absl::CivilDay cd(1969, 07, 20);
59//
60// // Construct a civil-time object for a specific second
61// const absl::CivilSecond cd(2018, 8, 1, 12, 0, 1);
62//
63// Note: In C++14 and later, this library is usable in a constexpr context.
64//
65// Example:
66//
67// // Valid in C++14
68// constexpr absl::CivilDay cd(1969, 07, 20);
69
70#ifndef ABSL_TIME_CIVIL_TIME_H_
71#define ABSL_TIME_CIVIL_TIME_H_
72
73#include <string>
74
75#include "absl/strings/string_view.h"
76#include "absl/time/internal/cctz/include/cctz/civil_time.h"
77
78namespace absl {
79
80namespace time_internal {
81struct second_tag : cctz::detail::second_tag {};
82struct minute_tag : second_tag, cctz::detail::minute_tag {};
83struct hour_tag : minute_tag, cctz::detail::hour_tag {};
84struct day_tag : hour_tag, cctz::detail::day_tag {};
85struct month_tag : day_tag, cctz::detail::month_tag {};
86struct year_tag : month_tag, cctz::detail::year_tag {};
87} // namespace time_internal
88
89// -----------------------------------------------------------------------------
90// CivilSecond, CivilMinute, CivilHour, CivilDay, CivilMonth, CivilYear
91// -----------------------------------------------------------------------------
92//
93// Each of these civil-time types is a simple value type with the same
94// interface for construction and the same six accessors for each of the civil
95// time fields (year, month, day, hour, minute, and second, aka YMDHMS). These
96// classes differ only in their alignment, which is indicated by the type name
97// and specifies the field on which arithmetic operates.
98//
99// CONSTRUCTION
100//
101// Each of the civil-time types can be constructed in two ways: by directly
102// passing to the constructor up to six integers representing the YMDHMS fields,
103// or by copying the YMDHMS fields from a differently aligned civil-time type.
104// Omitted fields are assigned their minimum valid value. Hours, minutes, and
105// seconds will be set to 0, month and day will be set to 1. Since there is no
106// minimum year, the default is 1970.
107//
108// Examples:
109//
110// absl::CivilDay default_value; // 1970-01-01 00:00:00
111//
112// absl::CivilDay a(2015, 2, 3); // 2015-02-03 00:00:00
113// absl::CivilDay b(2015, 2, 3, 4, 5, 6); // 2015-02-03 00:00:00
114// absl::CivilDay c(2015); // 2015-01-01 00:00:00
115//
116// absl::CivilSecond ss(2015, 2, 3, 4, 5, 6); // 2015-02-03 04:05:06
117// absl::CivilMinute mm(ss); // 2015-02-03 04:05:00
118// absl::CivilHour hh(mm); // 2015-02-03 04:00:00
119// absl::CivilDay d(hh); // 2015-02-03 00:00:00
120// absl::CivilMonth m(d); // 2015-02-01 00:00:00
121// absl::CivilYear y(m); // 2015-01-01 00:00:00
122//
123// m = absl::CivilMonth(y); // 2015-01-01 00:00:00
124// d = absl::CivilDay(m); // 2015-01-01 00:00:00
125// hh = absl::CivilHour(d); // 2015-01-01 00:00:00
126// mm = absl::CivilMinute(hh); // 2015-01-01 00:00:00
127// ss = absl::CivilSecond(mm); // 2015-01-01 00:00:00
128//
129// Each civil-time class is aligned to the civil-time field indicated in the
130// class's name after normalization. Alignment is performed by setting all the
131// inferior fields to their minimum valid value (as described above). The
132// following are examples of how each of the six types would align the fields
133// representing November 22, 2015 at 12:34:56 in the afternoon. (Note: the
134// string format used here is not important; it's just a shorthand way of
135// showing the six YMDHMS fields.)
136//
137// absl::CivilSecond : 2015-11-22 12:34:56
138// absl::CivilMinute : 2015-11-22 12:34:00
139// absl::CivilHour : 2015-11-22 12:00:00
140// absl::CivilDay : 2015-11-22 00:00:00
141// absl::CivilMonth : 2015-11-01 00:00:00
142// absl::CivilYear : 2015-01-01 00:00:00
143//
144// Each civil-time type performs arithmetic on the field to which it is
145// aligned. This means that adding 1 to an absl::CivilDay increments the day
146// field (normalizing as necessary), and subtracting 7 from an absl::CivilMonth
147// operates on the month field (normalizing as necessary). All arithmetic
148// produces a valid civil time. Difference requires two similarly aligned
149// civil-time objects and returns the scalar answer in units of the objects'
150// alignment. For example, the difference between two absl::CivilHour objects
151// will give an answer in units of civil hours.
152//
153// ALIGNMENT CONVERSION
154//
155// The alignment of a civil-time object cannot change, but the object may be
156// used to construct a new object with a different alignment. This is referred
157// to as "realigning". When realigning to a type with the same or more
158// precision (e.g., absl::CivilDay -> absl::CivilSecond), the conversion may be
159// performed implicitly since no information is lost. However, if information
160// could be discarded (e.g., CivilSecond -> CivilDay), the conversion must
161// be explicit at the call site.
162//
163// Examples:
164//
165// void UseDay(absl::CivilDay day);
166//
167// absl::CivilSecond cs;
168// UseDay(cs); // Won't compile because data may be discarded
169// UseDay(absl::CivilDay(cs)); // OK: explicit conversion
170//
171// absl::CivilDay cd;
172// UseDay(cd); // OK: no conversion needed
173//
174// absl::CivilMonth cm;
175// UseDay(cm); // OK: implicit conversion to absl::CivilDay
176//
177// NORMALIZATION
178//
179// Normalization takes invalid values and adjusts them to produce valid values.
180// Within the civil-time library, integer arguments passed to the Civil*
181// constructors may be out-of-range, in which case they are normalized by
182// carrying overflow into a field of courser granularity to produce valid
183// civil-time objects. This normalization enables natural arithmetic on
184// constructor arguments without worrying about the field's range.
185//
186// Examples:
187//
188// // Out-of-range; normalized to 2016-11-01
189// absl::CivilDay d(2016, 10, 32);
190// // Out-of-range, negative: normalized to 2016-10-30T23
191// absl::CivilHour h1(2016, 10, 31, -1);
192// // Normalization is cumulative: normalized to 2016-10-30T23
193// absl::CivilHour h2(2016, 10, 32, -25);
194//
195// Note: If normalization is undesired, you can signal an error by comparing
196// the constructor arguments to the normalized values returned by the YMDHMS
197// properties.
198//
199// COMPARISON
200//
201// Comparison between civil-time objects considers all six YMDHMS fields,
202// regardless of the type's alignment. Comparison between differently aligned
203// civil-time types is allowed.
204//
205// Examples:
206//
207// absl::CivilDay feb_3(2015, 2, 3); // 2015-02-03 00:00:00
208// absl::CivilDay mar_4(2015, 3, 4); // 2015-03-04 00:00:00
209// // feb_3 < mar_4
210// // absl::CivilYear(feb_3) == absl::CivilYear(mar_4)
211//
212// absl::CivilSecond feb_3_noon(2015, 2, 3, 12, 0, 0); // 2015-02-03 12:00:00
213// // feb_3 < feb_3_noon
214// // feb_3 == absl::CivilDay(feb_3_noon)
215//
216// // Iterates all the days of February 2015.
217// for (absl::CivilDay d(2015, 2, 1); d < absl::CivilMonth(2015, 3); ++d) {
218// // ...
219// }
220//
221// ARITHMETIC
222//
223// Civil-time types support natural arithmetic operators such as addition,
224// subtraction, and difference. Arithmetic operates on the civil-time field
225// indicated in the type's name. Difference operators require arguments with
226// the same alignment and return the answer in units of the alignment.
227//
228// Example:
229//
230// absl::CivilDay a(2015, 2, 3);
231// ++a; // 2015-02-04 00:00:00
232// --a; // 2015-02-03 00:00:00
233// absl::CivilDay b = a + 1; // 2015-02-04 00:00:00
234// absl::CivilDay c = 1 + b; // 2015-02-05 00:00:00
235// int n = c - a; // n = 2 (civil days)
236// int m = c - absl::CivilMonth(c); // Won't compile: different types.
237//
238// ACCESSORS
239//
240// Each civil-time type has accessors for all six of the civil-time fields:
241// year, month, day, hour, minute, and second.
242//
243// civil_year_t year()
244// int month()
245// int day()
246// int hour()
247// int minute()
248// int second()
249//
250// Recall that fields inferior to the type's aligment will be set to their
251// minimum valid value.
252//
253// Example:
254//
255// absl::CivilDay d(2015, 6, 28);
256// // d.year() == 2015
257// // d.month() == 6
258// // d.day() == 28
259// // d.hour() == 0
260// // d.minute() == 0
261// // d.second() == 0
262//
263// CASE STUDY: Adding a month to January 31.
264//
265// One of the classic questions that arises when considering a civil time
266// library (or a date library or a date/time library) is this:
267// "What is the result of adding a month to January 31?"
268// This is an interesting question because it is unclear what is meant by a
269// "month", and several different answers are possible, depending on context:
270//
271// 1. March 3 (or 2 if a leap year), if "add a month" means to add a month to
272// the current month, and adjust the date to overflow the extra days into
273// March. In this case the result of "February 31" would be normalized as
274// within the civil-time library.
275// 2. February 28 (or 29 if a leap year), if "add a month" means to add a
276// month, and adjust the date while holding the resulting month constant.
277// In this case, the result of "February 31" would be truncated to the last
278// day in February.
279// 3. An error. The caller may get some error, an exception, an invalid date
280// object, or perhaps return `false`. This may make sense because there is
281// no single unambiguously correct answer to the question.
282//
283// Practically speaking, any answer that is not what the programmer intended
284// is the wrong answer.
285//
286// The Abseil time library avoids this problem by making it impossible to
287// ask ambiguous questions. All civil-time objects are aligned to a particular
288// civil-field boundary (such as aligned to a year, month, day, hour, minute,
289// or second), and arithmetic operates on the field to which the object is
290// aligned. This means that in order to "add a month" the object must first be
291// aligned to a month boundary, which is equivalent to the first day of that
292// month.
293//
294// Of course, there are ways to compute an answer the question at hand using
295// this Abseil time library, but they require the programmer to be explicit
296// about the answer they expect. To illustrate, let's see how to compute all
297// three of the above possible answers to the question of "Jan 31 plus 1
298// month":
299//
300// Example:
301//
302// const absl::CivilDay d(2015, 1, 31);
303//
304// // Answer 1:
305// // Add 1 to the month field in the constructor, and rely on normalization.
306// const auto normalized = absl::CivilDay(d.year(), d.month() + 1, d.day());
307// // normalized == 2015-03-03 (aka Feb 31)
308//
309// // Answer 2:
310// // Add 1 to month field, capping to the end of next month.
311// const auto next_month = absl::CivilMonth(d) + 1;
312// const auto last_day_of_next_month = absl::CivilDay(next_month + 1) - 1;
313// const auto capped = std::min(normalized, last_day_of_next_month);
314// // capped == 2015-02-28
315//
316// // Answer 3:
317// // Signal an error if the normalized answer is not in next month.
318// if (absl::CivilMonth(normalized) != next_month) {
319// // error, month overflow
320// }
321//
322using CivilSecond =
323 time_internal::cctz::detail::civil_time<time_internal::second_tag>;
324using CivilMinute =
325 time_internal::cctz::detail::civil_time<time_internal::minute_tag>;
326using CivilHour =
327 time_internal::cctz::detail::civil_time<time_internal::hour_tag>;
328using CivilDay =
329 time_internal::cctz::detail::civil_time<time_internal::day_tag>;
330using CivilMonth =
331 time_internal::cctz::detail::civil_time<time_internal::month_tag>;
332using CivilYear =
333 time_internal::cctz::detail::civil_time<time_internal::year_tag>;
334
335// civil_year_t
336//
337// Type alias of a civil-time year value. This type is guaranteed to (at least)
338// support any year value supported by `time_t`.
339//
340// Example:
341//
342// absl::CivilSecond cs = ...;
343// absl::civil_year_t y = cs.year();
344// cs = absl::CivilSecond(y, 1, 1, 0, 0, 0); // CivilSecond(CivilYear(cs))
345//
346using civil_year_t = time_internal::cctz::year_t;
347
348// civil_diff_t
349//
350// Type alias of the difference between two civil-time values.
351// This type is used to indicate arguments that are not
352// normalized (such as parameters to the civil-time constructors), the results
353// of civil-time subtraction, or the operand to civil-time addition.
354//
355// Example:
356//
357// absl::civil_diff_t n_sec = cs1 - cs2; // cs1 == cs2 + n_sec;
358//
359using civil_diff_t = time_internal::cctz::diff_t;
360
361// Weekday::monday, Weekday::tuesday, Weekday::wednesday, Weekday::thursday,
362// Weekday::friday, Weekday::saturday, Weekday::sunday
363//
364// The Weekday enum class represents the civil-time concept of a "weekday" with
365// members for all days of the week.
366//
367// absl::Weekday wd = absl::Weekday::thursday;
368//
369using Weekday = time_internal::cctz::weekday;
370
371// GetWeekday()
372//
373// Returns the absl::Weekday for the given absl::CivilDay.
374//
375// Example:
376//
377// absl::CivilDay a(2015, 8, 13);
378// absl::Weekday wd = absl::GetWeekday(a); // wd == absl::Weekday::thursday
379//
380inline Weekday GetWeekday(CivilDay cd) {
381 return time_internal::cctz::get_weekday(cd);
382}
383
384// NextWeekday()
385// PrevWeekday()
386//
387// Returns the absl::CivilDay that strictly follows or precedes a given
388// absl::CivilDay, and that falls on the given absl::Weekday.
389//
390// Example, given the following month:
391//
392// August 2015
393// Su Mo Tu We Th Fr Sa
394// 1
395// 2 3 4 5 6 7 8
396// 9 10 11 12 13 14 15
397// 16 17 18 19 20 21 22
398// 23 24 25 26 27 28 29
399// 30 31
400//
401// absl::CivilDay a(2015, 8, 13);
402// // absl::GetWeekday(a) == absl::Weekday::thursday
403// absl::CivilDay b = absl::NextWeekday(a, absl::Weekday::thursday);
404// // b = 2015-08-20
405// absl::CivilDay c = absl::PrevWeekday(a, absl::Weekday::thursday);
406// // c = 2015-08-06
407//
408// absl::CivilDay d = ...
409// // Gets the following Thursday if d is not already Thursday
410// absl::CivilDay thurs1 = absl::NextWeekday(d - 1, absl::Weekday::thursday);
411// // Gets the previous Thursday if d is not already Thursday
412// absl::CivilDay thurs2 = absl::PrevWeekday(d + 1, absl::Weekday::thursday);
413//
414inline CivilDay NextWeekday(CivilDay cd, Weekday wd) {
415 return CivilDay(time_internal::cctz::next_weekday(cd, wd));
416}
417inline CivilDay PrevWeekday(CivilDay cd, Weekday wd) {
418 return CivilDay(time_internal::cctz::prev_weekday(cd, wd));
419}
420
421// GetYearDay()
422//
423// Returns the day-of-year for the given absl::CivilDay.
424//
425// Example:
426//
427// absl::CivilDay a(2015, 1, 1);
428// int yd_jan_1 = absl::GetYearDay(a); // yd_jan_1 = 1
429// absl::CivilDay b(2015, 12, 31);
430// int yd_dec_31 = absl::GetYearDay(b); // yd_dec_31 = 365
431//
432inline int GetYearDay(CivilDay cd) {
433 return time_internal::cctz::get_yearday(cd);
434}
435
436// FormatCivilTime()
437//
438// Formats the given civil-time value into a string value of the following
439// format:
440//
441// Type | Format
442// ---------------------------------
443// CivilSecond | YYYY-MM-DDTHH:MM:SS
444// CivilMinute | YYYY-MM-DDTHH:MM
445// CivilHour | YYYY-MM-DDTHH
446// CivilDay | YYYY-MM-DD
447// CivilMonth | YYYY-MM
448// CivilYear | YYYY
449//
450// Example:
451//
452// absl::CivilDay d = absl::CivilDay(1969, 7, 20);
453// std::string day_string = absl::FormatCivilTime(d); // "1969-07-20"
454//
455std::string FormatCivilTime(CivilSecond c);
456std::string FormatCivilTime(CivilMinute c);
457std::string FormatCivilTime(CivilHour c);
458std::string FormatCivilTime(CivilDay c);
459std::string FormatCivilTime(CivilMonth c);
460std::string FormatCivilTime(CivilYear c);
461
462namespace time_internal { // For functions found via ADL on civil-time tags.
463
464// Streaming Operators
465//
466// Each civil-time type may be sent to an output stream using operator<<().
467// The result matches the string produced by `FormatCivilTime()`.
468//
469// Example:
470//
471// absl::CivilDay d = absl::CivilDay("1969-07-20");
472// std::cout << "Date is: " << d << "\n";
473//
474std::ostream& operator<<(std::ostream& os, CivilYear y);
475std::ostream& operator<<(std::ostream& os, CivilMonth m);
476std::ostream& operator<<(std::ostream& os, CivilDay d);
477std::ostream& operator<<(std::ostream& os, CivilHour h);
478std::ostream& operator<<(std::ostream& os, CivilMinute m);
479std::ostream& operator<<(std::ostream& os, CivilSecond s);
480
481} // namespace time_internal
482
483} // namespace absl
484
485#endif // ABSL_TIME_CIVIL_TIME_H_
486