<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
        "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
	<title>chrono fixes</title>

	<style>
	p {text-align:justify}
	li {text-align:justify}
	blockquote.note
	{
		background-color:#E0E0E0;
		padding-left: 15px;
		padding-right: 15px;
		padding-top: 1px;
		padding-bottom: 1px;
	}
	ins {color:#00A000}
	del {color:#A00000}
	code {white-space:pre;}
	table, th, td {
		border: 1px solid black;
		border-collapse: collapse;
		padding: 10px;
	}
	</style>
</head>
<body>

<address align=right>
Document number: P1466r0<br>
<br/>
<br/>
<a href="mailto:howard.hinnant@gmail.com">Howard E. Hinnant</a><br/>
2019-01-21<br/>
</address>
<hr/>
<h1 align=center>Miscellaneous minor fixes for chrono</h1>

<h2>Contents</h2>

<ul>
<li><a href="#Introduction">Introduction</a></li>
<li><a href="#Wording">Wording</a></li>
</ul>

<a name="Introduction"></a><h2>Introduction</h2>

<p>
This is a collection of minor fixes and upgrades to the <code>&lt;chrono&gt;</code>
library that have come to my attention since the acceptance of
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0355r7.html">P0355r7</a>.
</p>

<a name="Wording"></a><h2>Wording</h2>

<ol>

<!-- is_leap_second -->
<li>

<blockquote class=note>
<p>
Feedback from the field asks for a way to identify if a <code>utc_time</code> represents
a leap second.  This proposed API is the only API that has field experience in providing
that information in a way that is efficient, and provides all information the client
desires when making a query in this area.  It is used in the implementation of the
conversion between <code>utc_time</code> and <code>sys_time</code>, and in the parsing
and formatting of <code>utc_time</code>, so is likely to be present in any event.  If
we choose to specify it, it can be spelled without underscores, and be available to
clients of <code>&lt;chrono&gt;</code>.
</p>
</blockquote>

<p>
Insert new paragraphs in 26.7.2.3 Non-member functions [time.clock.utc.nonmembers]:
</p>

<blockquote>
<pre>
template &lt;class Duration&gt;
pair&lt;bool, seconds&gt;
is_leap_second(utc_time&lt;Duration&gt; const&amp; ut)
</pre>
<blockquote>
<p>
<i>Returns:</i> A <code>pair&lt;bool, seconds&gt;</code> where
<code>first</code> is true if <code>ut</code> is during a leap second insertion,
and otherwise false. <code>second</code> is the number of leap seconds between
1970-01-01 and <code>ut</code>. If <code>first</code> is true, the leap second
referred to by <code>ut</code> is included in the count.
</p>
</blockquote>
</blockquote>

</li>

<!-- %Q %q -->
<li>

<blockquote class=note>
<p>
Feedback from the field asks for a way to customize the spacing between a duration's
value and its unit (e.g. supply a space, or a Unicode custom space between the value
and the unit).  This item proposes <code>%Q</code> to represent the durations's value
and <code>%q</code> to represent the duration's unit, for formatting only.  Example:
<code>format("%Q %q", 45ms) == "45 ms"</code>.
</p>
</blockquote>

<p>
Add two new rows to  Table 87 &mdash; Meaning of <code>format</code> conversion
specifiers:
</p>

<blockquote>
<table>
<tr>
<td><code>%Q</code></td>
<td>The duration's numeric value (as if extracted via <code>.count()</code>).</td>
</tr>
<tr>
<td><code>%q</code></td>
<td>The duration's unit suffix as specified in [time.duration.io].</td>
</tr>
</table>
</blockquote>

</li>

<!-- weekday encoding controversy -->
<li>

<blockquote class=note>
<p>
About half of the clients are upset that the currently specified encoding for
<code>weekday</code> implies that Sunday is the first day of the week (consistent
with the current C and C++ specifications for <code>tm.tm_wday</code>), and the
other half of the clients will be upset if the <code>weekday</code> encoding
follows the ISO specification of [1, 7] maps to [Monday, Sunday].
</p>
<p>
This change strikes a compromise in an attempt to please everyone (a nearly
impossible task).
</p>
<ul>
<li>
<p>
The <code>weekday{unsigned}</code> constructor accepts both mappings, which means
that [0, 6] maps to [Monday, Saturday] <b>and</b> [1, 7] maps to [Monday, Sunday].
This is possible by simply accepting [0, 7] where [1, 6] maps to [Monday, Saturday]
and both 0 and 7 map to Sunday.
</p>
</li>
<li>
<p>
The explicit conversion to <code>unsigned</code> is removed from <code>weekday</code>
and named conversions are inserted in its place: <code>c_encoding()</code> and
<code>iso_encoding()</code>.  The client can choose which mapping from <code>weekday</code>
to <code>unsigned</code> he desires by choosing one of these member functions.
</p>
</li>
</ul>
</blockquote>

<p>
Modify 26.8.6.2 [time.cal.wd.members] as indicated:
</p>

<blockquote>

<pre>
constexpr explicit weekday(unsigned wd) noexcept;
</pre>
<blockquote>
<p>
<i>Effects:</i> Constructs an object of type <code>weekday</code> by
initializing <code>wd_</code> with <code>wd</code>, <ins>except if <code>wd_ == 7</code>,
stores <code>0</code></ins>. The value held is unspecified if wd is
not in the range [0, 255].
</p>
</blockquote>

<pre>
<del>constexpr explicit operator unsigned() const noexcept;</del>
</pre>
<blockquote>
<p>
<del><i>Returns:</i> <code>wd_</code>.</del>
</p>
</blockquote>

<pre>
<ins>constexpr unsigned c_encoding() const noexcept;</ins>
</pre>
<blockquote>
<p>
<ins><i>Returns:</i> <code>wd_</code>.</ins>
</p>
</blockquote>

<pre>
<ins>constexpr unsigned iso_encoding() const noexcept;</ins>
</pre>
<blockquote>
<p>
<ins><i>Returns:</i> <code>unsigned{((wd_ == 0u) ? 7u : wd_)}</code>.</ins>
</p>
</blockquote>


</blockquote>

</li>

<!-- Missing link comparison operators -->
<li>

<blockquote class=note>
<p>
<code>link</code> is missing some comparison operator definitions.  The declarations
are correctly in the synopsis.  The missing definitions should be the "usual"
formula based on <code>==</code> and <code>&lt;</code>.
</p>
</blockquote>

<p>
Add paragraphs to 26.10.9.3 Non-member functions [time.zone.link.nonmembers]:
</p>

<blockquote>
<pre>
bool operator!=(const link&amp; x, const link&amp; y) noexcept;
</pre>
<blockquote>
<p>
<i>Returns:</i> <code>!(x == y)</code>.
</p>
</blockquote>

<pre>
bool operator&gt; (const link&amp; x, const link&amp; y) noexcept;
</pre>
<blockquote>
<p>
<i>Returns:</i> <code>y &lt; x</code>.
</p>
</blockquote>

<pre>
bool operator&lt;=(const link&amp; x, const link&amp; y) noexcept;
</pre>
<blockquote>
<p>
<i>Returns:</i> <code>!(y &lt; x)</code>.
</p>
</blockquote>

<pre>
bool operator&gt;=(const link&amp; x, const link&amp; y) noexcept;
</pre>
<blockquote>
<p>
<i>Returns:</i> <code>!(x &lt; y)</code>.
</p>
</blockquote>

</blockquote>

</li>

</ol>

</body>
</html>
