civil_time.h
Go to the documentation of this file.
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 
77 
78 namespace absl {
79 
80 namespace time_internal {
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 //
322 using CivilSecond =
324 using CivilMinute =
326 using CivilHour =
328 using CivilDay =
330 using CivilMonth =
332 using CivilYear =
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 //
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 //
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 //
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 //
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::PrevWeekday(d, absl::Weekday::thursday) + 7;
411 // // Gets the previous Thursday if d is not already Thursday
412 // absl::CivilDay thurs2 = absl::NextWeekday(d, absl::Weekday::thursday) - 7;
413 //
416 }
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 //
432 inline int GetYearDay(CivilDay 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 //
455 std::string FormatCivilTime(CivilSecond c);
456 std::string FormatCivilTime(CivilMinute c);
457 std::string FormatCivilTime(CivilHour c);
458 std::string FormatCivilTime(CivilDay c);
459 std::string FormatCivilTime(CivilMonth c);
460 std::string FormatCivilTime(CivilYear c);
461 
462 namespace 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 //
474 std::ostream& operator<<(std::ostream& os, CivilYear y);
475 std::ostream& operator<<(std::ostream& os, CivilMonth m);
476 std::ostream& operator<<(std::ostream& os, CivilDay d);
477 std::ostream& operator<<(std::ostream& os, CivilHour h);
478 std::ostream& operator<<(std::ostream& os, CivilMinute m);
479 std::ostream& operator<<(std::ostream& os, CivilSecond s);
480 
481 } // namespace time_internal
482 
483 } // namespace absl
484 
485 #endif // ABSL_TIME_CIVIL_TIME_H_
CONSTEXPR_F int get_yearday(const civil_day &cd) noexcept
Weekday GetWeekday(CivilDay cd)
Definition: civil_time.h:380
time_internal::cctz::year_t civil_year_t
Definition: civil_time.h:346
time_internal::cctz::diff_t civil_diff_t
Definition: civil_time.h:359
int GetYearDay(CivilDay cd)
Definition: civil_time.h:432
CONSTEXPR_F civil_day next_weekday(civil_day cd, weekday wd) noexcept
CivilDay NextWeekday(CivilDay cd, Weekday wd)
Definition: civil_time.h:414
CONSTEXPR_F weekday get_weekday(const civil_day &cd) noexcept
Definition: algorithm.h:29
std::ostream & operator<<(std::ostream &os, CivilYear y)
Definition: civil_time.cc:62
time_internal::cctz::weekday Weekday
Definition: civil_time.h:369
CONSTEXPR_F civil_day prev_weekday(civil_day cd, weekday wd) noexcept
time_internal::cctz::detail::civil_time< time_internal::day_tag > CivilDay
Definition: civil_time.h:329
std::string FormatCivilTime(CivilSecond c)
Definition: civil_time.cc:47
CivilDay PrevWeekday(CivilDay cd, Weekday wd)
Definition: civil_time.h:417


abseil_cpp
Author(s):
autogenerated on Mon Feb 28 2022 21:31:17