<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <meta name="generator" content="pandoc">
  <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
  <title></title>
  <style type="text/css">code{white-space: pre;}</style>
  <style type="text/css">
div.sourceCode { overflow-x: auto; }
table.sourceCode, tr.sourceCode, td.lineNumbers, td.sourceCode {
  margin: 0; padding: 0; vertical-align: baseline; border: none; }
table.sourceCode { width: 100%; line-height: 100%; }
td.lineNumbers { text-align: right; padding-right: 4px; padding-left: 4px; color: #aaaaaa; border-right: 1px solid #aaaaaa; }
td.sourceCode { padding-left: 5px; }
code > span.kw { color: #007020; font-weight: bold; } /* Keyword */
code > span.dt { color: #902000; } /* DataType */
code > span.dv { color: #40a070; } /* DecVal */
code > span.bn { color: #40a070; } /* BaseN */
code > span.fl { color: #40a070; } /* Float */
code > span.ch { color: #4070a0; } /* Char */
code > span.st { color: #4070a0; } /* String */
code > span.co { color: #60a0b0; font-style: italic; } /* Comment */
code > span.ot { color: #007020; } /* Other */
code > span.al { color: #ff0000; font-weight: bold; } /* Alert */
code > span.fu { color: #06287e; } /* Function */
code > span.er { color: #ff0000; font-weight: bold; } /* Error */
code > span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
code > span.cn { color: #880000; } /* Constant */
code > span.sc { color: #4070a0; } /* SpecialChar */
code > span.vs { color: #4070a0; } /* VerbatimString */
code > span.ss { color: #bb6688; } /* SpecialString */
code > span.im { } /* Import */
code > span.va { color: #19177c; } /* Variable */
code > span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
code > span.op { color: #666666; } /* Operator */
code > span.bu { } /* BuiltIn */
code > span.ex { } /* Extension */
code > span.pp { color: #bc7a00; } /* Preprocessor */
code > span.at { color: #7d9029; } /* Attribute */
code > span.do { color: #ba2121; font-style: italic; } /* Documentation */
code > span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
code > span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
  </style>
  <link href="data:text/css;charset=utf-8,body%20%7B%0Apadding%2Dleft%3A%2010px%3B%0Apadding%2Dright%3A%2010%25%3B%0A%7D%0Apre%20%7B%0Abackground%2Dcolor%3A%20%23f8f8f8%3B%0Aborder%3A%201px%20solid%20darkgray%3B%0Apadding%3A%203px%3B%0A%7D%0Atable%3Afirst%2Dof%2Dtype%20thead%20%7B%0Adisplay%3A%20none%3B%0A%7D%0Atable%20%7B%0Aborder%3A%201px%20solid%20darkgray%3B%0A%7D%0Athead%20%7B%0Abackground%2Dcolor%3A%20darkgray%3B%0Acolor%3A%20white%3B%0A%7D%0Ath%2Ctd%20%7B%0Apadding%3A%202px%3B%0Apadding%2Dright%3A%2020px%3B%0A%7D%0Atr%3Anth%2Dchild%28even%29%20%7B%0Abackground%2Dcolor%3A%20%23f8f8f8%3B%0A%7D%0A" rel="stylesheet">
  <!--[if lt IE 9]>
    <script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
  <![endif]-->
</head>
<body>
<h1 id="c-standard-proposal-a-civil-time-library">C++ Standard Proposal &#8212; A Civil-Time Library</h1>
<table>
<thead>
<tr class="header">
<th style="text-align: left;">Metadata</th>
<th style="text-align: left;">Value</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">Document number:</td>
<td style="text-align: left;">P0215R0</td>
</tr>
<tr class="even">
<td style="text-align: left;">Date:</td>
<td style="text-align: left;">2016-02-11</td>
</tr>
<tr class="odd">
<td style="text-align: left;">Reply-to:</td>
<td style="text-align: left;">Greg Miller (<script type="text/javascript">
<!--
h='&#x67;&#x6f;&#x6f;&#x67;&#108;&#x65;&#46;&#x63;&#x6f;&#x6d;';a='&#64;';n='&#106;&#x67;&#x6d;';e=n+a+h;
document.write('<a h'+'ref'+'="ma'+'ilto'+':'+e+'" clas'+'s="em' + 'ail">'+e+'<\/'+'a'+'>');
// -->
</script><noscript>jgm at google dot com</noscript>), Bradley White (<script type="text/javascript">
<!--
h='&#x67;&#x6f;&#x6f;&#x67;&#108;&#x65;&#46;&#x63;&#x6f;&#x6d;';a='&#64;';n='&#98;&#x77;&#x77;';e=n+a+h;
document.write('<a h'+'ref'+'="ma'+'ilto'+':'+e+'" clas'+'s="em' + 'ail">'+e+'<\/'+'a'+'>');
// -->
</script><noscript>bww at google dot com</noscript>)</td>
</tr>
<tr class="even">
<td style="text-align: left;">Audience:</td>
<td style="text-align: left;">Library Evolution Working Group</td>
</tr>
</tbody>
</table>
<h2 id="table-of-contents">Table of Contents</h2>
<ul>
<li><a href="#introduction">Introduction</a></li>
<li><a href="#motivation-and-scope">Motivation and Scope</a></li>
<li><a href="#the-conceptual-model-and-terminology">The Conceptual Model and Terminology</a></li>
<li><a href="#impact-on-the-standard">Impact on the Standard</a></li>
<li><a href="#design-decisions">Design Decisions</a></li>
<li><a href="#technical-specification">Technical Specification</a></li>
<li><a href="#synopsis">Synopsis</a></li>
<li><a href="#examples">Examples</a></li>
<li><a href="#references">References</a></li>
</ul>
<h2 id="introduction">Introduction</h2>
<p>This document proposes a standard C++ library for computing with time that is represented by years, months, and days that follow the rules of the <a href="https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar">Proleptic Gregorian Calendar</a>, as well as 24-hour days that are divided into hours, minutes, and seconds. These six fields are how humans commonly experience time, and this time-zone-independent representation is called <em>civil time</em>.</p>
<h2 id="motivation-and-scope">Motivation and Scope</h2>
<p>Programming with time on a human scale is notoriously difficult and error prone: time zones are complicated, daylight-saving time (DST) is complicated, calendars are complicated, and leap seconds are complicated. These complexities quickly surface in code because programmers do not have a simple conceptual model with which to reason about the time-programming challenges they are facing. Furthermore, this lack of a simple conceptual model begets the lack of a simple library, leaving only complicated libraries that programmers struggle to understand and use correctly (or no libraries at all).</p>
<p>A survey of application-level code within Google that computes with civil-time fields shows that programmer confusion is a fundamental cause of overly complicated and buggy code. This is a result of the inherent complexities in this problem space as just mentioned, and the fact that there has been little progress toward hiding these complexities behind a library that presents a simpler conceptual model to programmers.</p>
<p>The Civil-Time Library proposed here addresses these problems by presenting civil time as a <em>regular</em>, time-zone-independent concept that allows programmers to ignore the above complexities when it is safe to do so. This library has been implemented and widely used within Google for the past few years. It is actively being used in real-world code by novice and expert programmers alike.</p>
<h2 id="the-conceptual-model-and-terminology">The Conceptual Model and Terminology</h2>
<p>Civil time, as described in this proposal, is just one of three concepts that comprise a complete, straightforward, and language-neutral conceptual model for reasoning about time programming: <em>absolute time</em>, <em>civil time</em>, and <em>time zone</em>.</p>
<p><em>Absolute time</em> uniquely and universally represents a specific instant in time. It has no notion of calendars, or dates, or times of day. Instead, it is a measure of the passage of real time, typically as a simple count of ticks since some epoch. Absolute times are independent of all time zones and do not suffer from human-imposed complexities such as daylight-saving time (DST). Many C++ types exist to represent absolute times, classically <code>time_t</code> and more recently <code>std::chrono::time_point</code>.</p>
<p><em>Civil time</em> is the legally recognized representation of time for ordinary affairs (cf. <a href="http://www.merriam-webster.com/dictionary/civil" class="uri">http://www.merriam-webster.com/dictionary/civil</a>). It is a human-scale representation of time that consists of the six fields &#8212; year, month, day, hour, minute, and second (sometimes shortened to &quot;YMDHMS&quot;) &#8212; and it follows the rules of the <a href="https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar">Proleptic Gregorian Calendar</a>, with 24-hour days divided into 60-minute hours and 60-second minutes. Like absolute times, civil times are also independent of all time zones and their related complexities (e.g., DST). While <code>std::tm</code> contains the six civil-time fields (YMDHMS), plus a few more, it does not have behavior to enforce the rules of civil time.</p>
<p><em>Time zones</em> are geo-political regions within which human-defined rules are shared to convert between absolute-time and civil-time domains. A time-zone's rules include things like the region's offset from the <a href="https://en.wikipedia.org/wiki/Coordinated_Universal_Time">UTC</a> time standard, daylight-saving adjustments, and short abbreviation strings. Time zones often have a history of disparate rules that apply only for certain periods, because the rules may change at the whim of a region's local government. For this reason, time-zone rules are usually compiled into data snapshots that are used at runtime to perform conversions between absolute and civil times. There is currently no C++ standard library supporting arbitrary time zones.</p>
<p>The C++ standard already has the <code>&lt;chrono&gt;</code> library, which is a good implementation of an <em>absolute-time</em> library. This paper proposes a standard <em>civil-time</em> library. A separate paper (<a href="p0216r0.html">P0216R0</a>) proposes a standard <em>Time-Zone</em> Library that bridges <code>&lt;chrono&gt;</code> and this Civil-Time Library, and will complete the three pillars of the conceptual model just described.</p>
<h2 id="impact-on-the-standard">Impact on the Standard</h2>
<p>The Civil-Time Library proposed here does not directly depend on any other standard C++ library. It is implementable using C++98, with optimizations such as <code>constexpr</code> available when compiled as C++11.</p>
<p>The current sister proposal for a standard Time-Zone Library (<a href="p0216r0.html">P0216R0</a>) depends on the existence of this Civil-Time Library.</p>
<h2 id="design-decisions">Design Decisions</h2>
<h3 id="only-the-proleptic-gregorian-calendar-is-used">Only the Proleptic Gregorian Calendar is used</h3>
<p>Many different calendaring systems exist in the world, but the most commonly used calendar is the <a href="https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar">Proleptic Gregorian Calendar</a>. Supporting rarely used calendars would add complexity to the library with little value. Additionally, international standards such as <a href="https://en.wikipedia.org/wiki/Coordinated_Universal_Time">UTC</a> rely on the Gregorian Calendar. Therefore, we've chosen not to support other calendars.</p>
<h3 id="leap-seconds-are-disregarded">Leap seconds are disregarded</h3>
<p>Unlike leap days, which are part of the <a href="https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar">Proleptic Gregorian Calendar</a>, leap seconds are unpredictable and would require time zone knowledge to properly support their use in the civil-time domain. Such time zone awareness would add substantial conceptual complexity for a rare use case. The simplicity of this Civil-Time Library stems from presenting a regularized, or idealized, human-scale time representation that is devoid of complexities and discontinuities, such as those caused by supporting DST and leap seconds. We believe it would be a mistake to expose leap second complexities in the civil-time domain. And if knowledge of leap seconds were necessary, that support should exist in a separate time zone library rather than a civil-time library.</p>
<h3 id="civil-times-are-always-valid">Civil times are always valid</h3>
<p>It is not possible to create an invalid civil-time instance. Similarly, there are no errors when constructing a civil time with field values that are out of range. This is enforced by normalizing input fields (similar to <code>mktime(3)</code>). For example, January 32 will normalize to February 1. This decision reduces the amount of boilerplate error checking, and it allows callers to do arithmetic on input field arguments without worrying about range. If normalization is undesired, callers may compare the resulting normalized fields to the input fields to signal an error.</p>
<h3 id="civil-times-do-not-have-subseconds">Civil times do not have subseconds</h3>
<p>Civil times are represented by the six fields of year, month, day, hour, minute, and second. These are the six fields that are typically considered for human-scale time. Additionally, seconds are the level of precision within time zone data files; i.e., there are no subsecond time zone transitions. While it would be possible to support subseconds in this Civil-Time Library, doing so would complicate the library for a feature with little demand.</p>
<h3 id="civil-times-are-aligned-to-a-civil-field-boundary">Civil times are aligned to a civil-field boundary</h3>
<p>One of the classic questions that arises when talking about a civil-time library (or a date library or a date/time library) is this: &quot;What happens when you add a month to January 31?&quot; This is an interesting question because there could be a number of possible answers:</p>
<ul>
<li>March 3 (or 2 if a leap year). This may make sense if the operation wants the equivalent of February 31.</li>
<li>February 28 (or 29 if a leap year). This may make sense if the operation wants the last day of January to go to the last day of February.</li>
<li>Error. The caller may get some error, an exception, an invalid date object, or maybe <code>false</code> is returned. This may make sense because there is no single unambiguously correct answer to the question.</li>
</ul>
<p>Practically speaking, any answer that is not what the programmer intended is the wrong answer.</p>
<p>The Civil-Time Library proposed here avoids this problem by making it impossible to ask such an ambiguous question. All civil-time objects are aligned to a particular civil-field boundary (such as aligned to a year, month, day, hour, minute, or second), and arithmetic operates on the field to which the object is aligned. This means that in order to &quot;add a month&quot; the object must first be aligned to a month boundary, which is equivalent to the first day of that month. See the <a href="#technical-specification">Technical Specification</a> section below for more about alignment.</p>
<p>There are indeed ways to accomplish the task of adding a month to January 31 with this Civil-Time Library, but they require the programmer to be more explicit about their intent so the answer is unsurprising. There is an example showing this later in this paper. In practice, we have found few places in Google code where programmers wanted unaligned date arithmetic, and in those few cases the more explicit code helped ensure that the programmer got the answer they expected.</p>
<h2 id="technical-specification">Technical Specification</h2>
<p>The core of the Civil-Time Library is based on the following six individual classes:</p>
<ul>
<li><code>civil_second</code></li>
<li><code>civil_minute</code></li>
<li><code>civil_hour</code></li>
<li><code>civil_day</code></li>
<li><code>civil_month</code></li>
<li><code>civil_year</code></li>
</ul>
<p>Each class is a simple value type with the same interface for construction and the same six accessors for each of the YMDHMS fields. These classes differ only in their <em>alignment</em>, which is indicated by the type name and specifies the field on which arithmetic operates.</p>
<p>Each class can be constructed by passing up to six optional integer arguments representing the YMDHMS fields (in that order) to the constructor. Omitted fields are assigned their minimum valid value. Hours, minutes, and seconds will be set to 0, month and day will be set to 1, and since there is no minimum valid year it will be set to 1970. So, a default-constructed civil-time object will have YMDHMS fields representing &quot;1970-01-01 00:00:00&quot;.</p>
<p>Each civil-time class is aligned to the civil-time field indicated in the class's name. Alignment is performed by setting all the inferior fields to their minimum valid value (as described above). The following are examples of how each of the six types would align the fields representing November 22, 2015 at 12:34:56 in the afternoon. (Note: the string format used here is not important; it's just a shorthand way of showing the six YMDHMS fields.)</p>
<table>
<thead>
<tr class="header">
<th style="text-align: left;">Class</th>
<th style="text-align: left;">Example alignment</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;"><code>civil_second</code></td>
<td style="text-align: left;"><code>2015-11-22 12:34:56</code></td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>civil_minute</code></td>
<td style="text-align: left;"><code>2015-11-22 12:34:00</code></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>civil_hour</code></td>
<td style="text-align: left;"><code>2015-11-22 12:00:00</code></td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>civil_day</code></td>
<td style="text-align: left;"><code>2015-11-22 00:00:00</code></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>civil_month</code></td>
<td style="text-align: left;"><code>2015-11-01 00:00:00</code></td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>civil_year</code></td>
<td style="text-align: left;"><code>2015-01-01 00:00:00</code></td>
</tr>
</tbody>
</table>
<p>Each civil-time type performs arithmetic on the field to which it is aligned. This means that adding 1 to a <code>civil_day</code> increments the day field (normalizing as necessary), and subtracting 7 from a <code>civil_month</code> operates on the month field (normalizing as necessary). All arithmetic produces a new value that represents a valid civil time. Difference requires two similarly aligned civil time types and returns the scalar answer in units of the given alignment. For example, the difference between two <code>civil_hour</code> objects will give an answer in hours.</p>
<p>Finally, in addition to the six civil-time types just described, there are a handful of helper functions and algorithms for performing common calculations. These are described in the <a href="#synopsis">Synopsis</a> below.</p>
<h2 id="synopsis">Synopsis</h2>
<p>The following code illustrates the public API for each of the six civil-time types described above. As an implementation choice, Google chose to write one class template that is parameterized on the alignment field as a tag struct. This class template is not a public API point, but it serves here to illustrate the API of each of the public civil-time types.</p>
<div class="sourceCode"><pre class="sourceCode cpp"><code class="sourceCode cpp"><span class="kw">namespace</span> detail {
<span class="kw">template</span> &lt;<span class="kw">typename</span> T&gt;
<span class="kw">class</span> civil_time {
 <span class="kw">public</span>:
  <span class="kw">explicit</span> <span class="kw">constexpr</span> civil_time(<span class="dt">int</span> y, <span class="dt">int</span> m = <span class="dv">1</span>, <span class="dt">int</span> d = <span class="dv">1</span>,
                                <span class="dt">int</span> hh = <span class="dv">0</span>, <span class="dt">int</span> mm = <span class="dv">0</span>, <span class="dt">int</span> ss = <span class="dv">0</span>);

  <span class="kw">constexpr</span> civil_time() : civil_time(<span class="dv">1970</span>) {}
  <span class="kw">constexpr</span> civil_time(<span class="dt">const</span> civil_time&amp;) = <span class="kw">default</span>;
  civil_time&amp; <span class="kw">operator</span>=(<span class="dt">const</span> civil_time&amp;) = <span class="kw">default</span>;

  <span class="co">// Explicit conversion between civil times of different alignment.</span>
  <span class="kw">template</span> &lt;<span class="kw">typename</span> U&gt;
  <span class="kw">explicit</span> <span class="kw">constexpr</span> civil_time(civil_time&lt;U&gt;);

  <span class="co">// Field accessors.</span>
  <span class="kw">constexpr</span> <span class="dt">int</span> year() <span class="dt">const</span>;
  <span class="kw">constexpr</span> <span class="dt">int</span> month() <span class="dt">const</span>;
  <span class="kw">constexpr</span> <span class="dt">int</span> day() <span class="dt">const</span>;
  <span class="kw">constexpr</span> <span class="dt">int</span> hour() <span class="dt">const</span>;
  <span class="kw">constexpr</span> <span class="dt">int</span> minute() <span class="dt">const</span>;
  <span class="kw">constexpr</span> <span class="dt">int</span> second() <span class="dt">const</span>;

  <span class="co">// Assigning arithmetic.</span>
  civil_time&amp; <span class="kw">operator</span>+=(<span class="dt">int</span>);
  civil_time&amp; <span class="kw">operator</span>-=(<span class="dt">int</span>);
  civil_time&amp; <span class="kw">operator</span>++();
  civil_time <span class="kw">operator</span>++(<span class="dt">int</span>);
  civil_time&amp; <span class="kw">operator</span>--();
  civil_time <span class="kw">operator</span>--(<span class="dt">int</span>);

  <span class="co">// Binary arithmetic operators.</span>
  <span class="kw">inline</span> <span class="kw">friend</span> <span class="kw">constexpr</span> civil_time <span class="kw">operator</span>+(<span class="dt">const</span> civil_time&amp;, <span class="dt">int</span>) { ... }
  <span class="kw">inline</span> <span class="kw">friend</span> <span class="kw">constexpr</span> civil_time <span class="kw">operator</span>+(<span class="dt">int</span>, <span class="dt">const</span> civil_time&amp;) { ... }
  <span class="kw">inline</span> <span class="kw">friend</span> <span class="kw">constexpr</span> civil_time <span class="kw">operator</span>-(<span class="dt">const</span> civil_time&amp;, <span class="dt">int</span>) { ... }
  <span class="kw">inline</span> <span class="kw">friend</span> <span class="kw">constexpr</span> <span class="dt">int</span> <span class="kw">operator</span>-(<span class="dt">const</span> civil_time&amp;, <span class="dt">const</span> civil_time&amp;) { ... }

 <span class="kw">private</span>:
  ....
};

<span class="co">// Relational operators that work with differently aligned objects.</span>
<span class="co">// Always compares all six YMDHMS fields.</span>
<span class="kw">template</span> &lt;<span class="kw">typename</span> T1, <span class="kw">typename</span> T2&gt;
<span class="kw">constexpr</span> <span class="dt">bool</span> <span class="kw">operator</span>&lt;(<span class="dt">const</span> civil_time&lt;T1&gt;&amp;, <span class="dt">const</span> civil_time&lt;T2&gt;&amp;);
<span class="kw">template</span> &lt;<span class="kw">typename</span> T1, <span class="kw">typename</span> T2&gt;
<span class="kw">constexpr</span> <span class="dt">bool</span> <span class="kw">operator</span>&lt;=(<span class="dt">const</span> civil_time&lt;T1&gt;&amp;, <span class="dt">const</span> civil_time&lt;T2&gt;&amp;);
<span class="kw">template</span> &lt;<span class="kw">typename</span> T1, <span class="kw">typename</span> T2&gt;
<span class="kw">constexpr</span> <span class="dt">bool</span> <span class="kw">operator</span>&gt;=(<span class="dt">const</span> civil_time&lt;T1&gt;&amp;, <span class="dt">const</span> civil_time&lt;T2&gt;&amp;);
<span class="kw">template</span> &lt;<span class="kw">typename</span> T1, <span class="kw">typename</span> T2&gt;
<span class="kw">constexpr</span> <span class="dt">bool</span> <span class="kw">operator</span>&gt;(<span class="dt">const</span> civil_time&lt;T1&gt;&amp;, <span class="dt">const</span> civil_time&lt;T2&gt;&amp;);
<span class="kw">template</span> &lt;<span class="kw">typename</span> T1, <span class="kw">typename</span> T2&gt;
<span class="kw">constexpr</span> <span class="dt">bool</span> <span class="kw">operator</span>==(<span class="dt">const</span> civil_time&lt;T1&gt;&amp;, <span class="dt">const</span> civil_time&lt;T2&gt;&amp;);
<span class="kw">template</span> &lt;<span class="kw">typename</span> T1, <span class="kw">typename</span> T2&gt;
<span class="kw">constexpr</span> <span class="dt">bool</span> <span class="kw">operator</span>!=(<span class="dt">const</span> civil_time&lt;T1&gt;&amp;, <span class="dt">const</span> civil_time&lt;T2&gt;&amp;);

<span class="kw">struct</span> year_tag {};
<span class="kw">struct</span> month_tag {};
<span class="kw">struct</span> day_tag {};
<span class="kw">struct</span> hour_tag {};
<span class="kw">struct</span> minute_tag {};
<span class="kw">struct</span> second_tag {};
}  <span class="co">// namespace detail</span>

<span class="co">// The six public civil-time types.</span>
<span class="kw">using</span> civil_year = detail::civil_time&lt;detail::year_tag&gt;;
<span class="kw">using</span> civil_month = detail::civil_time&lt;detail::month_tag&gt;;
<span class="kw">using</span> civil_day = detail::civil_time&lt;detail::day_tag&gt;;
<span class="kw">using</span> civil_hour = detail::civil_time&lt;detail::hour_tag&gt;;
<span class="kw">using</span> civil_minute = detail::civil_time&lt;detail::minute_tag&gt;;
<span class="kw">using</span> civil_second = detail::civil_time&lt;detail::second_tag&gt;;</code></pre></div>
<p>In addition to the six civil-time types defined above, the following helper functions provide help with common computations.</p>
<div class="sourceCode"><pre class="sourceCode cpp"><code class="sourceCode cpp"><span class="kw">enum</span> <span class="kw">class</span> weekday {
  monday,
  tuesday,
  wednesday,
  thursday,
  friday,
  saturday,
  sunday,
};

<span class="co">// Returns the weekday of the argument.</span>
<span class="kw">constexpr</span> weekday get_weekday(<span class="dt">const</span> civil_day&amp;);

<span class="co">// Returns the civil_day that strictly follows/precedes the argument and that</span>
<span class="co">// falls on the given weekday.</span>
<span class="kw">constexpr</span> civil_day next_weekday(<span class="dt">const</span> civil_day&amp;, weekday);
<span class="kw">constexpr</span> civil_day prev_weekday(<span class="dt">const</span> civil_day&amp;, weekday);

<span class="co">// Returns the yearday of a civil_day.</span>
<span class="kw">constexpr</span> <span class="dt">int</span> get_yearday(<span class="dt">const</span> civil_day&amp;);</code></pre></div>
<h2 id="examples">Examples</h2>
<p>The following examples show usage of the proposed Civil-Time Library, as well as illustrate interesting semantics of various API points.</p>
<p>As a shorthand in the examples below, the YMDHMS fields of a civil-time type may be shown as a string of the form <code>YYYY-MM-DD hh:mm:ss</code>. Fields omitted from the string format still exist and are assumed to have their minimum value. For example:</p>
<div class="sourceCode"><pre class="sourceCode cpp"><code class="sourceCode cpp">civil_day d(<span class="dv">2015</span>, <span class="dv">2</span>, <span class="dv">3</span>);
<span class="co">// d.year() == 2015</span>
<span class="co">// d.month() == 2</span>
<span class="co">// d.day() == 3</span>
<span class="co">// d.hour() == 0</span>
<span class="co">// d.minute() == 0</span>
<span class="co">// d.second() == 0</span>
<span class="co">// Shorthand: d == 2015-02-03</span>
<span class="co">// ...same as d == 2015-02-03 00:00:00</span></code></pre></div>
<h3 id="construction">Construction</h3>
<p>Each of the civil-time types can be constructed in two ways: by directly passing up to six (optional) integers representing YMDHMS fields to the constructor, or by copying the fields from a differently aligned civil-time type.</p>
<div class="sourceCode"><pre class="sourceCode cpp"><code class="sourceCode cpp">civil_day default_value;  <span class="co">// 1970-01-01 00:00:00</span>

civil_day a(<span class="dv">2015</span>, <span class="dv">2</span>, <span class="dv">3</span>);           <span class="co">// 2015-02-03 00:00:00</span>
civil_day b(<span class="dv">2015</span>, <span class="dv">2</span>, <span class="dv">3</span>, <span class="dv">4</span>, <span class="dv">5</span>, <span class="dv">6</span>);  <span class="co">// 2015-02-03 00:00:00</span>
civil_day c(<span class="dv">2015</span>);                 <span class="co">// 2015-01-01 00:00:00</span>

civil_second ss(<span class="dv">2015</span>, <span class="dv">2</span>, <span class="dv">3</span>, <span class="dv">4</span>, <span class="dv">5</span>, <span class="dv">6</span>);  <span class="co">// 2015-02-03 04:05:06</span>
civil_minute mm(ss);                   <span class="co">// 2015-02-03 04:05:00</span>
civil_hour hh(mm);                     <span class="co">// 2015-02-03 04:00:00</span>
civil_day d(hh);                       <span class="co">// 2015-02-03 00:00:00</span>
civil_month m(d);                      <span class="co">// 2015-02-01 00:00:00</span>
civil_year y(m);                       <span class="co">// 2015-01-01 00:00:00</span>

m = civil_month(y);     <span class="co">// 2015-01-01 00:00:00</span>
d = civil_day(m);       <span class="co">// 2015-01-01 00:00:00</span>
hh = civil_hour(d);     <span class="co">// 2015-01-01 00:00:00</span>
mm = civil_minute(hh);  <span class="co">// 2015-01-01 00:00:00</span>
ss = civil_second(mm);  <span class="co">// 2015-01-01 00:00:00</span></code></pre></div>
<h3 id="comparison">Comparison</h3>
<p>Comparison always considers all six YMDHMS fields, regardless of the type's alignment. Comparison between differently aligned civil-time types is allowed.</p>
<p>Note that comparison between differently aligned types is not a critical part of this API. It exists as a convenience, but it could be removed at the cost of requiring explicit casts between civil-time types when comparing.</p>
<div class="sourceCode"><pre class="sourceCode cpp"><code class="sourceCode cpp">civil_day feb_3(<span class="dv">2015</span>, <span class="dv">2</span>, <span class="dv">3</span>);  <span class="co">// 2015-02-03 00:00:00</span>
civil_day mar_4(<span class="dv">2015</span>, <span class="dv">3</span>, <span class="dv">4</span>);  <span class="co">// 2015-03-04 00:00:00</span>
<span class="co">// feb_3 &lt; mar_4</span>
<span class="co">// civil_year(feb_3) == civil_year(mar_4)</span>

civil_second feb_3_noon(<span class="dv">2015</span>, <span class="dv">2</span>, <span class="dv">3</span>, <span class="dv">12</span>, <span class="dv">0</span>, <span class="dv">0</span>);  <span class="co">// 2015-02-03 12:00:00</span>
<span class="co">// feb_3 &lt; feb_3_noon</span>
<span class="co">// feb_3 == civil_day(feb_3_noon)</span>

<span class="co">// Iterates all the days of February 2015.</span>
<span class="kw">for</span> (civil_day d(<span class="dv">2015</span>, <span class="dv">2</span>, <span class="dv">1</span>); d &lt; civil_month(<span class="dv">2015</span>, <span class="dv">3</span>); ++d) {
  <span class="co">// ...</span>
}</code></pre></div>
<h3 id="arithmetic">Arithmetic</h3>
<p>Civil-time types support natural arithmetic operators such as addition, subtraction, and difference. Arithmetic operates on the civil-time field indicated in the type's name. Difference requires arguments with the same alignment and returns the answer in units of the alignment.</p>
<div class="sourceCode"><pre class="sourceCode cpp"><code class="sourceCode cpp">civil_day a(<span class="dv">2015</span>, <span class="dv">2</span>, <span class="dv">3</span>);
++a;                         <span class="co">// 2015-02-04 00:00:00</span>
--a;                         <span class="co">// 2015-02-03 00:00:00</span>
civil_day b = a + <span class="dv">1</span>;         <span class="co">// 2015-02-04 00:00:00</span>
civil_day c = <span class="dv">1</span> + b;         <span class="co">// 2015-02-05 00:00:00</span>
<span class="dt">int</span> n = c - a;               <span class="co">// n = 2 (days)</span>
<span class="dt">int</span> m = c - civil_month(c);  <span class="co">// Won't compile: different types.</span></code></pre></div>
<h3 id="weekdays">Weekdays</h3>
<p>The Civil-Time Library provides the <code>prev_weekday()</code> and <code>next_weekday()</code> functions for navigating the calendar by the day of the week. Both functions accept a <code>civil_day</code> argument as well as the desired <code>weekday</code>. They both return a strictly different <code>civil_day</code> that falls on the given <code>weekday</code>, even if the argument was already on the requested weekday.</p>
<div class="sourceCode"><pre class="sourceCode cpp"><code class="sourceCode cpp"><span class="co">//     August 2015</span>
<span class="co">// Su Mo Tu We Th Fr Sa</span>
<span class="co">//                    1</span>
<span class="co">//  2  3  4  5  6  7  8</span>
<span class="co">//  9 10 11 12 13 14 15</span>
<span class="co">// 16 17 18 19 20 21 22</span>
<span class="co">// 23 24 25 26 27 28 29</span>
<span class="co">// 30 31</span>

civil_day a(<span class="dv">2015</span>, <span class="dv">8</span>, <span class="dv">13</span>);  <span class="co">// get_weekday(a) == weekday::thursday</span>
civil_day b = next_weekday(a, weekday::thursday);  <span class="co">// 2015-08-20</span>
civil_day c = prev_weekday(a, weekday::thursday);  <span class="co">// 2015-08-06</span>

civil_day d = ...
<span class="co">// Gets the following Thursday if d is not already Thursday</span>
civil_day ceil_thursday = prev_weekday(d, weekday::thursday) + <span class="dv">7</span>;
<span class="co">// Gets the previous Thursday if d is not already Thursday</span>
civil_day floor_thursday = next_weekday(d, weekday::thursday) - <span class="dv">7</span>;</code></pre></div>
<h3 id="adding-a-month-to-january-31">Adding a month to January 31</h3>
<p><a href="#design-decisions"><em>Design Decisions</em></a> explained why adding a month to January 31 presents an ambiguous question. As we've described, aligned date arithmetic makes it impossible to ask this ambiguous question directly. However, if a programmer really wants to ask this question, they need to be more explicit about the answer they expect. For example:</p>
<div class="sourceCode"><pre class="sourceCode cpp"><code class="sourceCode cpp"><span class="dt">const</span> civil_day d(<span class="dv">2015</span>, <span class="dv">1</span>, <span class="dv">31</span>);

<span class="co">// Answer 1:</span>
<span class="co">// Adds 1 to the month field in the constructor, and let normalization happen.</span>
<span class="dt">const</span> <span class="kw">auto</span> ans_normalized = civil_day(d.year(), d.month() + <span class="dv">1</span>, d.day());
<span class="co">// ans_normalized == 2015-03-03 (aka Feb 31)</span>

<span class="co">// Answer 2:</span>
<span class="co">// Adds 1 to month field, capping at the end of next month</span>
<span class="dt">const</span> <span class="kw">auto</span> last_day_of_next_month = civil_day(civil_month(d) + <span class="dv">2</span>) - <span class="dv">1</span>;
<span class="dt">const</span> <span class="kw">auto</span> ans_capped = std::min(ans_normalized, last_day_of_next_month);
<span class="co">// ans_capped == 2015-02-28</span>

<span class="co">// Answer 3:</span>
<span class="kw">if</span> (civil_month(ans_normalized) - civil_month(d) != <span class="dv">1</span>) {
  <span class="co">// error, month overflow</span>
}</code></pre></div>
<h2 id="references">References</h2>
<ul>
<li><a href="https://en.wikipedia.org/wiki/Civil_time" class="uri">https://en.wikipedia.org/wiki/Civil_time</a></li>
<li><a href="http://www.merriam-webster.com/dictionary/civil" class="uri">http://www.merriam-webster.com/dictionary/civil</a></li>
<li><a href="http://www.timeanddate.com/time/aboututc.html" class="uri">http://www.timeanddate.com/time/aboututc.html</a></li>
<li><a href="https://en.wikipedia.org/wiki/Coordinated_Universal_Time" class="uri">https://en.wikipedia.org/wiki/Coordinated_Universal_Time</a></li>
<li><a href="https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar" class="uri">https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar</a></li>
<li><a href="https://github.com/google/cctz" class="uri">https://github.com/google/cctz</a></li>
</ul>
</body>
</html>
