File: faq.html

package info (click to toggle)
r-cran-clock 0.7.2-1
links: PTS, VCS
area: main
in suites: forky, sid, trixie
size: 3,856 kB
sloc: cpp: 19,564; sh: 17; makefile: 2
file content (874 lines) | stat: -rw-r--r-- 62,808 bytes
<!DOCTYPE html>

<html>

<head>

<meta charset="utf-8" />
<meta name="generator" content="pandoc" />
<meta http-equiv="X-UA-Compatible" content="IE=EDGE" />

<meta name="viewport" content="width=device-width, initial-scale=1" />



<title>Frequently Asked Questions</title>

<script>// Pandoc 2.9 adds attributes on both header and div. We remove the former (to
// be compatible with the behavior of Pandoc < 2.8).
document.addEventListener('DOMContentLoaded', function(e) {
  var hs = document.querySelectorAll("div.section[class*='level'] > :first-child");
  var i, h, a;
  for (i = 0; i < hs.length; i++) {
    h = hs[i];
    if (!/^h[1-6]$/i.test(h.tagName)) continue;  // it should be a header h1-h6
    a = h.attributes;
    while (a.length > 0) h.removeAttribute(a[0].name);
  }
});
</script>

<style type="text/css">
code{white-space: pre-wrap;}
span.smallcaps{font-variant: small-caps;}
span.underline{text-decoration: underline;}
div.column{display: inline-block; vertical-align: top; width: 50%;}
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
ul.task-list{list-style: none;}
</style>



<style type="text/css">
code {
white-space: pre;
}
.sourceCode {
overflow: visible;
}
</style>
<style type="text/css" data-origin="pandoc">
pre > code.sourceCode { white-space: pre; position: relative; }
pre > code.sourceCode > span { line-height: 1.25; }
pre > code.sourceCode > span:empty { height: 1.2em; }
.sourceCode { overflow: visible; }
code.sourceCode > span { color: inherit; text-decoration: inherit; }
div.sourceCode { margin: 1em 0; }
pre.sourceCode { margin: 0; }
@media screen {
div.sourceCode { overflow: auto; }
}
@media print {
pre > code.sourceCode { white-space: pre-wrap; }
pre > code.sourceCode > span { display: inline-block; text-indent: -5em; padding-left: 5em; }
}
pre.numberSource code
{ counter-reset: source-line 0; }
pre.numberSource code > span
{ position: relative; left: -4em; counter-increment: source-line; }
pre.numberSource code > span > a:first-child::before
{ content: counter(source-line);
position: relative; left: -1em; text-align: right; vertical-align: baseline;
border: none; display: inline-block;
-webkit-touch-callout: none; -webkit-user-select: none;
-khtml-user-select: none; -moz-user-select: none;
-ms-user-select: none; user-select: none;
padding: 0 4px; width: 4em;
color: #aaaaaa;
}
pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; }
div.sourceCode
{ }
@media screen {
pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; }
}
code span.al { color: #ff0000; font-weight: bold; } 
code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } 
code span.at { color: #7d9029; } 
code span.bn { color: #40a070; } 
code span.bu { color: #008000; } 
code span.cf { color: #007020; font-weight: bold; } 
code span.ch { color: #4070a0; } 
code span.cn { color: #880000; } 
code span.co { color: #60a0b0; font-style: italic; } 
code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } 
code span.do { color: #ba2121; font-style: italic; } 
code span.dt { color: #902000; } 
code span.dv { color: #40a070; } 
code span.er { color: #ff0000; font-weight: bold; } 
code span.ex { } 
code span.fl { color: #40a070; } 
code span.fu { color: #06287e; } 
code span.im { color: #008000; font-weight: bold; } 
code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } 
code span.kw { color: #007020; font-weight: bold; } 
code span.op { color: #666666; } 
code span.ot { color: #007020; } 
code span.pp { color: #bc7a00; } 
code span.sc { color: #4070a0; } 
code span.ss { color: #bb6688; } 
code span.st { color: #4070a0; } 
code span.va { color: #19177c; } 
code span.vs { color: #4070a0; } 
code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } 
</style>
<script>
// apply pandoc div.sourceCode style to pre.sourceCode instead
(function() {
  var sheets = document.styleSheets;
  for (var i = 0; i < sheets.length; i++) {
    if (sheets[i].ownerNode.dataset["origin"] !== "pandoc") continue;
    try { var rules = sheets[i].cssRules; } catch (e) { continue; }
    var j = 0;
    while (j < rules.length) {
      var rule = rules[j];
      // check if there is a div.sourceCode rule
      if (rule.type !== rule.STYLE_RULE || rule.selectorText !== "div.sourceCode") {
        j++;
        continue;
      }
      var style = rule.style.cssText;
      // check if color or background-color is set
      if (rule.style.color === '' && rule.style.backgroundColor === '') {
        j++;
        continue;
      }
      // replace div.sourceCode by a pre.sourceCode rule
      sheets[i].deleteRule(j);
      sheets[i].insertRule('pre.sourceCode{' + style + '}', j);
    }
  }
})();
</script>




<style type="text/css">body {
background-color: #fff;
margin: 1em auto;
max-width: 700px;
overflow: visible;
padding-left: 2em;
padding-right: 2em;
font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
font-size: 14px;
line-height: 1.35;
}
#TOC {
clear: both;
margin: 0 0 10px 10px;
padding: 4px;
width: 400px;
border: 1px solid #CCCCCC;
border-radius: 5px;
background-color: #f6f6f6;
font-size: 13px;
line-height: 1.3;
}
#TOC .toctitle {
font-weight: bold;
font-size: 15px;
margin-left: 5px;
}
#TOC ul {
padding-left: 40px;
margin-left: -1.5em;
margin-top: 5px;
margin-bottom: 5px;
}
#TOC ul ul {
margin-left: -2em;
}
#TOC li {
line-height: 16px;
}
table {
margin: 1em auto;
border-width: 1px;
border-color: #DDDDDD;
border-style: outset;
border-collapse: collapse;
}
table th {
border-width: 2px;
padding: 5px;
border-style: inset;
}
table td {
border-width: 1px;
border-style: inset;
line-height: 18px;
padding: 5px 5px;
}
table, table th, table td {
border-left-style: none;
border-right-style: none;
}
table thead, table tr.even {
background-color: #f7f7f7;
}
p {
margin: 0.5em 0;
}
blockquote {
background-color: #f6f6f6;
padding: 0.25em 0.75em;
}
hr {
border-style: solid;
border: none;
border-top: 1px solid #777;
margin: 28px 0;
}
dl {
margin-left: 0;
}
dl dd {
margin-bottom: 13px;
margin-left: 13px;
}
dl dt {
font-weight: bold;
}
ul {
margin-top: 0;
}
ul li {
list-style: circle outside;
}
ul ul {
margin-bottom: 0;
}
pre, code {
background-color: #f7f7f7;
border-radius: 3px;
color: #333;
white-space: pre-wrap; 
}
pre {
border-radius: 3px;
margin: 5px 0px 10px 0px;
padding: 10px;
}
pre:not([class]) {
background-color: #f7f7f7;
}
code {
font-family: Consolas, Monaco, 'Courier New', monospace;
font-size: 85%;
}
p > code, li > code {
padding: 2px 0px;
}
div.figure {
text-align: center;
}
img {
background-color: #FFFFFF;
padding: 2px;
border: 1px solid #DDDDDD;
border-radius: 3px;
border: 1px solid #CCCCCC;
margin: 0 5px;
}
h1 {
margin-top: 0;
font-size: 35px;
line-height: 40px;
}
h2 {
border-bottom: 4px solid #f7f7f7;
padding-top: 10px;
padding-bottom: 2px;
font-size: 145%;
}
h3 {
border-bottom: 2px solid #f7f7f7;
padding-top: 10px;
font-size: 120%;
}
h4 {
border-bottom: 1px solid #f7f7f7;
margin-left: 8px;
font-size: 105%;
}
h5, h6 {
border-bottom: 1px solid #ccc;
font-size: 105%;
}
a {
color: #0033dd;
text-decoration: none;
}
a:hover {
color: #6666ff; }
a:visited {
color: #800080; }
a:visited:hover {
color: #BB00BB; }
a[href^="http:"] {
text-decoration: underline; }
a[href^="https:"] {
text-decoration: underline; }

code > span.kw { color: #555; font-weight: bold; } 
code > span.dt { color: #902000; } 
code > span.dv { color: #40a070; } 
code > span.bn { color: #d14; } 
code > span.fl { color: #d14; } 
code > span.ch { color: #d14; } 
code > span.st { color: #d14; } 
code > span.co { color: #888888; font-style: italic; } 
code > span.ot { color: #007020; } 
code > span.al { color: #ff0000; font-weight: bold; } 
code > span.fu { color: #900; font-weight: bold; } 
code > span.er { color: #a61717; background-color: #e3d2d2; } 
</style>




</head>

<body>




<h1 class="title toc-ignore">Frequently Asked Questions</h1>



<div class="sourceCode" id="cb1"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb1-1"><a href="#cb1-1" tabindex="-1"></a><span class="fu">library</span>(clock)</span>
<span id="cb1-2"><a href="#cb1-2" tabindex="-1"></a><span class="fu">library</span>(magrittr)</span></code></pre></div>
<div id="why-cant-i-do-day-arithmetic-on-a-year-month-day" class="section level2">
<h2>Why can’t I do day arithmetic on a year-month-day?</h2>
<p>It might seem intuitive that since you can do:</p>
<div class="sourceCode" id="cb2"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb2-1"><a href="#cb2-1" tabindex="-1"></a>x <span class="ot">&lt;-</span> <span class="fu">year_month_day</span>(<span class="dv">2019</span>, <span class="dv">1</span>, <span class="dv">5</span>)</span>
<span id="cb2-2"><a href="#cb2-2" tabindex="-1"></a></span>
<span id="cb2-3"><a href="#cb2-3" tabindex="-1"></a><span class="fu">add_months</span>(x, <span class="dv">1</span>)</span>
<span id="cb2-4"><a href="#cb2-4" tabindex="-1"></a><span class="co">#&gt; &lt;year_month_day&lt;day&gt;[1]&gt;</span></span>
<span id="cb2-5"><a href="#cb2-5" tabindex="-1"></a><span class="co">#&gt; [1] &quot;2019-02-05&quot;</span></span></code></pre></div>
<p>That you should also be able to do:</p>
<div class="sourceCode" id="cb3"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb3-1"><a href="#cb3-1" tabindex="-1"></a><span class="fu">add_days</span>(x, <span class="dv">1</span>)</span>
<span id="cb3-2"><a href="#cb3-2" tabindex="-1"></a><span class="co">#&gt; Error in `add_days()`:</span></span>
<span id="cb3-3"><a href="#cb3-3" tabindex="-1"></a><span class="co">#&gt; ! Can&#39;t perform this operation on a &lt;clock_year_month_day&gt;.</span></span>
<span id="cb3-4"><a href="#cb3-4" tabindex="-1"></a><span class="co">#&gt; ℹ Do you need to convert to a time point first?</span></span>
<span id="cb3-5"><a href="#cb3-5" tabindex="-1"></a><span class="co">#&gt; ℹ Use `as_naive_time()` or `as_sys_time()` to convert to a time point.</span></span></code></pre></div>
<p>Generally, calendars don’t support day based arithmetic, nor do they
support arithmetic at more precise precisions than day. Instead, you
have to convert to a time point, do the arithmetic there, and then
convert back (if you still need a year-month-day after that).</p>
<div class="sourceCode" id="cb4"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb4-1"><a href="#cb4-1" tabindex="-1"></a>x <span class="sc">%&gt;%</span></span>
<span id="cb4-2"><a href="#cb4-2" tabindex="-1"></a>  <span class="fu">as_naive_time</span>() <span class="sc">%&gt;%</span></span>
<span id="cb4-3"><a href="#cb4-3" tabindex="-1"></a>  <span class="fu">add_days</span>(<span class="dv">1</span>) <span class="sc">%&gt;%</span></span>
<span id="cb4-4"><a href="#cb4-4" tabindex="-1"></a>  <span class="fu">as_year_month_day</span>()</span>
<span id="cb4-5"><a href="#cb4-5" tabindex="-1"></a><span class="co">#&gt; &lt;year_month_day&lt;day&gt;[1]&gt;</span></span>
<span id="cb4-6"><a href="#cb4-6" tabindex="-1"></a><span class="co">#&gt; [1] &quot;2019-01-06&quot;</span></span></code></pre></div>
<p>The first reason for this is performance. A year-month-day is a
<em>field</em> type, implemented as multiple parallel vectors holding
the year, month, day, and all other components separately. There are two
ways that day based arithmetic could be implemented for this:</p>
<ul>
<li><p>Increment the day field, then check the year and month field to
see if they need to be incremented, accounting for months having a
differing number of days, and leap years.</p></li>
<li><p>Convert to naive-time, add days, convert back.</p></li>
</ul>
<p>Both approaches are relatively expensive. One of the goals of the
low-level API of clock is to make these expensive operations explicit.
This helps make it apparent that when you need to chain together
multiple operations, you should try and do all of your
<em>calendrical</em> arithmetic steps first, then convert to a time
point (i.e. the second bullet point from above) to do all of your
<em>chronological</em> arithmetic.</p>
<p>The second reason for this has to do with invalid dates, such as the
three in this vector:</p>
<div class="sourceCode" id="cb5"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb5-1"><a href="#cb5-1" tabindex="-1"></a>odd_dates <span class="ot">&lt;-</span> <span class="fu">year_month_day</span>(<span class="dv">2019</span>, <span class="dv">2</span>, <span class="dv">28</span><span class="sc">:</span><span class="dv">31</span>)</span>
<span id="cb5-2"><a href="#cb5-2" tabindex="-1"></a>odd_dates</span>
<span id="cb5-3"><a href="#cb5-3" tabindex="-1"></a><span class="co">#&gt; &lt;year_month_day&lt;day&gt;[4]&gt;</span></span>
<span id="cb5-4"><a href="#cb5-4" tabindex="-1"></a><span class="co">#&gt; [1] &quot;2019-02-28&quot; &quot;2019-02-29&quot; &quot;2019-02-30&quot; &quot;2019-02-31&quot;</span></span></code></pre></div>
<p>What does it mean to “add 1 day” to these? There is no obvious answer
to this question. Since clock requires that you first convert to a time
point to do day based arithmetic, you’ll be forced to call
<code>invalid_resolve()</code> to handle these invalid dates first.
After resolving them manually, then day based arithmetic again makes
sense.</p>
<div class="sourceCode" id="cb6"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb6-1"><a href="#cb6-1" tabindex="-1"></a>odd_dates <span class="sc">%&gt;%</span></span>
<span id="cb6-2"><a href="#cb6-2" tabindex="-1"></a>  <span class="fu">invalid_resolve</span>(<span class="at">invalid =</span> <span class="st">&quot;next&quot;</span>)</span>
<span id="cb6-3"><a href="#cb6-3" tabindex="-1"></a><span class="co">#&gt; &lt;year_month_day&lt;day&gt;[4]&gt;</span></span>
<span id="cb6-4"><a href="#cb6-4" tabindex="-1"></a><span class="co">#&gt; [1] &quot;2019-02-28&quot; &quot;2019-03-01&quot; &quot;2019-03-01&quot; &quot;2019-03-01&quot;</span></span>
<span id="cb6-5"><a href="#cb6-5" tabindex="-1"></a></span>
<span id="cb6-6"><a href="#cb6-6" tabindex="-1"></a>odd_dates <span class="sc">%&gt;%</span></span>
<span id="cb6-7"><a href="#cb6-7" tabindex="-1"></a>  <span class="fu">invalid_resolve</span>(<span class="at">invalid =</span> <span class="st">&quot;next&quot;</span>) <span class="sc">%&gt;%</span></span>
<span id="cb6-8"><a href="#cb6-8" tabindex="-1"></a>  <span class="fu">as_naive_time</span>() <span class="sc">%&gt;%</span></span>
<span id="cb6-9"><a href="#cb6-9" tabindex="-1"></a>  <span class="fu">add_days</span>(<span class="dv">2</span>)</span>
<span id="cb6-10"><a href="#cb6-10" tabindex="-1"></a><span class="co">#&gt; &lt;naive_time&lt;day&gt;[4]&gt;</span></span>
<span id="cb6-11"><a href="#cb6-11" tabindex="-1"></a><span class="co">#&gt; [1] &quot;2019-03-02&quot; &quot;2019-03-03&quot; &quot;2019-03-03&quot; &quot;2019-03-03&quot;</span></span>
<span id="cb6-12"><a href="#cb6-12" tabindex="-1"></a></span>
<span id="cb6-13"><a href="#cb6-13" tabindex="-1"></a>odd_dates <span class="sc">%&gt;%</span></span>
<span id="cb6-14"><a href="#cb6-14" tabindex="-1"></a>  <span class="fu">invalid_resolve</span>(<span class="at">invalid =</span> <span class="st">&quot;overflow&quot;</span>)</span>
<span id="cb6-15"><a href="#cb6-15" tabindex="-1"></a><span class="co">#&gt; &lt;year_month_day&lt;day&gt;[4]&gt;</span></span>
<span id="cb6-16"><a href="#cb6-16" tabindex="-1"></a><span class="co">#&gt; [1] &quot;2019-02-28&quot; &quot;2019-03-01&quot; &quot;2019-03-02&quot; &quot;2019-03-03&quot;</span></span>
<span id="cb6-17"><a href="#cb6-17" tabindex="-1"></a></span>
<span id="cb6-18"><a href="#cb6-18" tabindex="-1"></a>odd_dates <span class="sc">%&gt;%</span></span>
<span id="cb6-19"><a href="#cb6-19" tabindex="-1"></a>  <span class="fu">invalid_resolve</span>(<span class="at">invalid =</span> <span class="st">&quot;overflow&quot;</span>) <span class="sc">%&gt;%</span></span>
<span id="cb6-20"><a href="#cb6-20" tabindex="-1"></a>  <span class="fu">as_naive_time</span>() <span class="sc">%&gt;%</span></span>
<span id="cb6-21"><a href="#cb6-21" tabindex="-1"></a>  <span class="fu">add_days</span>(<span class="dv">2</span>)</span>
<span id="cb6-22"><a href="#cb6-22" tabindex="-1"></a><span class="co">#&gt; &lt;naive_time&lt;day&gt;[4]&gt;</span></span>
<span id="cb6-23"><a href="#cb6-23" tabindex="-1"></a><span class="co">#&gt; [1] &quot;2019-03-02&quot; &quot;2019-03-03&quot; &quot;2019-03-04&quot; &quot;2019-03-05&quot;</span></span></code></pre></div>
</div>
<div id="why-cant-i-add-time-to-a-zoned-time" class="section level2">
<h2>Why can’t I add time to a zoned-time?</h2>
<p>If you have a zoned-time, such as:</p>
<div class="sourceCode" id="cb7"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb7-1"><a href="#cb7-1" tabindex="-1"></a>x <span class="ot">&lt;-</span> <span class="fu">zoned_time_parse_complete</span>(<span class="st">&quot;1970-04-26T01:30:00-05:00[America/New_York]&quot;</span>)</span>
<span id="cb7-2"><a href="#cb7-2" tabindex="-1"></a>x</span>
<span id="cb7-3"><a href="#cb7-3" tabindex="-1"></a><span class="co">#&gt; &lt;zoned_time&lt;second&gt;&lt;America/New_York&gt;[1]&gt;</span></span>
<span id="cb7-4"><a href="#cb7-4" tabindex="-1"></a><span class="co">#&gt; [1] &quot;1970-04-26T01:30:00-05:00&quot;</span></span></code></pre></div>
<p>You might wonder why you can’t add any units of time to it:</p>
<div class="sourceCode" id="cb8"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb8-1"><a href="#cb8-1" tabindex="-1"></a><span class="fu">add_days</span>(x, <span class="dv">1</span>)</span>
<span id="cb8-2"><a href="#cb8-2" tabindex="-1"></a><span class="co">#&gt; Error in `add_days()`:</span></span>
<span id="cb8-3"><a href="#cb8-3" tabindex="-1"></a><span class="co">#&gt; ! Can&#39;t perform this operation on a &lt;clock_zoned_time&gt;.</span></span>
<span id="cb8-4"><a href="#cb8-4" tabindex="-1"></a><span class="co">#&gt; ℹ Do you need to convert to a time point first?</span></span>
<span id="cb8-5"><a href="#cb8-5" tabindex="-1"></a><span class="co">#&gt; ℹ Use `as_naive_time()` or `as_sys_time()` to convert to a time point.</span></span>
<span id="cb8-6"><a href="#cb8-6" tabindex="-1"></a></span>
<span id="cb8-7"><a href="#cb8-7" tabindex="-1"></a><span class="fu">add_seconds</span>(x, <span class="dv">1</span>)</span>
<span id="cb8-8"><a href="#cb8-8" tabindex="-1"></a><span class="co">#&gt; Error in `add_seconds()`:</span></span>
<span id="cb8-9"><a href="#cb8-9" tabindex="-1"></a><span class="co">#&gt; ! Can&#39;t perform this operation on a &lt;clock_zoned_time&gt;.</span></span>
<span id="cb8-10"><a href="#cb8-10" tabindex="-1"></a><span class="co">#&gt; ℹ Do you need to convert to a time point first?</span></span>
<span id="cb8-11"><a href="#cb8-11" tabindex="-1"></a><span class="co">#&gt; ℹ Use `as_naive_time()` or `as_sys_time()` to convert to a time point.</span></span></code></pre></div>
<p>In clock, you can’t do much with zoned-times directly. The best way
to understand this is to think of a zoned-time as containing 3 things: a
sys-time, a naive-time, and a time zone name. You can access those
things with:</p>
<div class="sourceCode" id="cb9"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb9-1"><a href="#cb9-1" tabindex="-1"></a>x</span>
<span id="cb9-2"><a href="#cb9-2" tabindex="-1"></a><span class="co">#&gt; &lt;zoned_time&lt;second&gt;&lt;America/New_York&gt;[1]&gt;</span></span>
<span id="cb9-3"><a href="#cb9-3" tabindex="-1"></a><span class="co">#&gt; [1] &quot;1970-04-26T01:30:00-05:00&quot;</span></span>
<span id="cb9-4"><a href="#cb9-4" tabindex="-1"></a></span>
<span id="cb9-5"><a href="#cb9-5" tabindex="-1"></a><span class="co"># The printed time with no time zone info</span></span>
<span id="cb9-6"><a href="#cb9-6" tabindex="-1"></a><span class="fu">as_naive_time</span>(x)</span>
<span id="cb9-7"><a href="#cb9-7" tabindex="-1"></a><span class="co">#&gt; &lt;naive_time&lt;second&gt;[1]&gt;</span></span>
<span id="cb9-8"><a href="#cb9-8" tabindex="-1"></a><span class="co">#&gt; [1] &quot;1970-04-26T01:30:00&quot;</span></span>
<span id="cb9-9"><a href="#cb9-9" tabindex="-1"></a></span>
<span id="cb9-10"><a href="#cb9-10" tabindex="-1"></a><span class="co"># The equivalent time in UTC</span></span>
<span id="cb9-11"><a href="#cb9-11" tabindex="-1"></a><span class="fu">as_sys_time</span>(x)</span>
<span id="cb9-12"><a href="#cb9-12" tabindex="-1"></a><span class="co">#&gt; &lt;sys_time&lt;second&gt;[1]&gt;</span></span>
<span id="cb9-13"><a href="#cb9-13" tabindex="-1"></a><span class="co">#&gt; [1] &quot;1970-04-26T06:30:00&quot;</span></span>
<span id="cb9-14"><a href="#cb9-14" tabindex="-1"></a></span>
<span id="cb9-15"><a href="#cb9-15" tabindex="-1"></a><span class="fu">zoned_time_zone</span>(x)</span>
<span id="cb9-16"><a href="#cb9-16" tabindex="-1"></a><span class="co">#&gt; [1] &quot;America/New_York&quot;</span></span></code></pre></div>
<p>Calling <code>add_days()</code> on a zoned-time is then an ambiguous
operation. Should we add to the sys-time or the naive-time that is
contained in the zoned-time? The answer changes depending on the
scenario.</p>
<p>Because of this, you have to extract out the relevant time point that
you care about, operate on that, and then convert back to zoned-time.
This often produces the same result:</p>
<div class="sourceCode" id="cb10"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb10-1"><a href="#cb10-1" tabindex="-1"></a>x <span class="sc">%&gt;%</span></span>
<span id="cb10-2"><a href="#cb10-2" tabindex="-1"></a>  <span class="fu">as_naive_time</span>() <span class="sc">%&gt;%</span></span>
<span id="cb10-3"><a href="#cb10-3" tabindex="-1"></a>  <span class="fu">add_seconds</span>(<span class="dv">1</span>) <span class="sc">%&gt;%</span></span>
<span id="cb10-4"><a href="#cb10-4" tabindex="-1"></a>  <span class="fu">as_zoned_time</span>(<span class="fu">zoned_time_zone</span>(x))</span>
<span id="cb10-5"><a href="#cb10-5" tabindex="-1"></a><span class="co">#&gt; &lt;zoned_time&lt;second&gt;&lt;America/New_York&gt;[1]&gt;</span></span>
<span id="cb10-6"><a href="#cb10-6" tabindex="-1"></a><span class="co">#&gt; [1] &quot;1970-04-26T01:30:01-05:00&quot;</span></span>
<span id="cb10-7"><a href="#cb10-7" tabindex="-1"></a></span>
<span id="cb10-8"><a href="#cb10-8" tabindex="-1"></a>x <span class="sc">%&gt;%</span></span>
<span id="cb10-9"><a href="#cb10-9" tabindex="-1"></a>  <span class="fu">as_sys_time</span>() <span class="sc">%&gt;%</span></span>
<span id="cb10-10"><a href="#cb10-10" tabindex="-1"></a>  <span class="fu">add_seconds</span>(<span class="dv">1</span>) <span class="sc">%&gt;%</span></span>
<span id="cb10-11"><a href="#cb10-11" tabindex="-1"></a>  <span class="fu">as_zoned_time</span>(<span class="fu">zoned_time_zone</span>(x))</span>
<span id="cb10-12"><a href="#cb10-12" tabindex="-1"></a><span class="co">#&gt; &lt;zoned_time&lt;second&gt;&lt;America/New_York&gt;[1]&gt;</span></span>
<span id="cb10-13"><a href="#cb10-13" tabindex="-1"></a><span class="co">#&gt; [1] &quot;1970-04-26T01:30:01-05:00&quot;</span></span></code></pre></div>
<p>But not always! When daylight saving time is involved, the choice of
sys-time or naive-time matters. Let’s try adding 30 minutes:</p>
<div class="sourceCode" id="cb11"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb11-1"><a href="#cb11-1" tabindex="-1"></a><span class="co"># There is a DST gap 1 second after 01:59:59,</span></span>
<span id="cb11-2"><a href="#cb11-2" tabindex="-1"></a><span class="co"># which jumps us straight to 03:00:00,</span></span>
<span id="cb11-3"><a href="#cb11-3" tabindex="-1"></a><span class="co"># skipping the 2 o&#39;clock hour entirely</span></span>
<span id="cb11-4"><a href="#cb11-4" tabindex="-1"></a></span>
<span id="cb11-5"><a href="#cb11-5" tabindex="-1"></a>x <span class="sc">%&gt;%</span></span>
<span id="cb11-6"><a href="#cb11-6" tabindex="-1"></a>  <span class="fu">as_naive_time</span>() <span class="sc">%&gt;%</span></span>
<span id="cb11-7"><a href="#cb11-7" tabindex="-1"></a>  <span class="fu">add_minutes</span>(<span class="dv">30</span>) <span class="sc">%&gt;%</span></span>
<span id="cb11-8"><a href="#cb11-8" tabindex="-1"></a>  <span class="fu">as_zoned_time</span>(<span class="fu">zoned_time_zone</span>(x))</span>
<span id="cb11-9"><a href="#cb11-9" tabindex="-1"></a><span class="co">#&gt; Error in `as_zoned_time()`:</span></span>
<span id="cb11-10"><a href="#cb11-10" tabindex="-1"></a><span class="co">#&gt; ! Nonexistent time due to daylight saving time at location 1.</span></span>
<span id="cb11-11"><a href="#cb11-11" tabindex="-1"></a><span class="co">#&gt; ℹ Resolve nonexistent time issues by specifying the `nonexistent` argument.</span></span>
<span id="cb11-12"><a href="#cb11-12" tabindex="-1"></a></span>
<span id="cb11-13"><a href="#cb11-13" tabindex="-1"></a>x <span class="sc">%&gt;%</span></span>
<span id="cb11-14"><a href="#cb11-14" tabindex="-1"></a>  <span class="fu">as_sys_time</span>() <span class="sc">%&gt;%</span></span>
<span id="cb11-15"><a href="#cb11-15" tabindex="-1"></a>  <span class="fu">add_minutes</span>(<span class="dv">30</span>) <span class="sc">%&gt;%</span></span>
<span id="cb11-16"><a href="#cb11-16" tabindex="-1"></a>  <span class="fu">as_zoned_time</span>(<span class="fu">zoned_time_zone</span>(x))</span>
<span id="cb11-17"><a href="#cb11-17" tabindex="-1"></a><span class="co">#&gt; &lt;zoned_time&lt;second&gt;&lt;America/New_York&gt;[1]&gt;</span></span>
<span id="cb11-18"><a href="#cb11-18" tabindex="-1"></a><span class="co">#&gt; [1] &quot;1970-04-26T03:00:00-04:00&quot;</span></span></code></pre></div>
<p>When adding to the naive-time, we got an error. With the sys-time,
everything seems okay. What happened?</p>
<p>The sys-time scenario is easy to explain. Technically this converts
to UTC, adds the time there, then converts back to your time zone. An
easier way to think about this is that you sat in front of your computer
for exactly 30 minutes (1800 seconds), then looked at the clock.
Assuming that that clock automatically changes itself correctly for
daylight saving time, it should read 3 o’clock.</p>
<p>The naive-time scenario makes more sense if you break down the steps.
First, we convert to naive-time, dropping all time zone information but
keeping the printed time:</p>
<div class="sourceCode" id="cb12"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb12-1"><a href="#cb12-1" tabindex="-1"></a>x</span>
<span id="cb12-2"><a href="#cb12-2" tabindex="-1"></a><span class="co">#&gt; &lt;zoned_time&lt;second&gt;&lt;America/New_York&gt;[1]&gt;</span></span>
<span id="cb12-3"><a href="#cb12-3" tabindex="-1"></a><span class="co">#&gt; [1] &quot;1970-04-26T01:30:00-05:00&quot;</span></span>
<span id="cb12-4"><a href="#cb12-4" tabindex="-1"></a></span>
<span id="cb12-5"><a href="#cb12-5" tabindex="-1"></a>x <span class="sc">%&gt;%</span></span>
<span id="cb12-6"><a href="#cb12-6" tabindex="-1"></a>  <span class="fu">as_naive_time</span>()</span>
<span id="cb12-7"><a href="#cb12-7" tabindex="-1"></a><span class="co">#&gt; &lt;naive_time&lt;second&gt;[1]&gt;</span></span>
<span id="cb12-8"><a href="#cb12-8" tabindex="-1"></a><span class="co">#&gt; [1] &quot;1970-04-26T01:30:00&quot;</span></span></code></pre></div>
<p>We add 30 minutes to this. Because we don’t have any time zone
information, this lands us at 2 o’clock, which isn’t an issue when
working with naive-time:</p>
<div class="sourceCode" id="cb13"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb13-1"><a href="#cb13-1" tabindex="-1"></a>x <span class="sc">%&gt;%</span></span>
<span id="cb13-2"><a href="#cb13-2" tabindex="-1"></a>  <span class="fu">as_naive_time</span>() <span class="sc">%&gt;%</span></span>
<span id="cb13-3"><a href="#cb13-3" tabindex="-1"></a>  <span class="fu">add_minutes</span>(<span class="dv">30</span>)</span>
<span id="cb13-4"><a href="#cb13-4" tabindex="-1"></a><span class="co">#&gt; &lt;naive_time&lt;second&gt;[1]&gt;</span></span>
<span id="cb13-5"><a href="#cb13-5" tabindex="-1"></a><span class="co">#&gt; [1] &quot;1970-04-26T02:00:00&quot;</span></span></code></pre></div>
<p>Finally, we convert back to zoned-time. If possible, this tries to
keep the printed time, and just attaches the relevant time zone onto it.
However, in this case that isn’t possible, since 2 o’clock didn’t exist
in this time zone! This <em>nonexistent time</em> must be handled
explicitly by setting the <code>nonexistent</code> argument of
<code>as_zoned_time()</code>. We can choose from a variety of strategies
to handle nonexistent times, but here we just roll forward to the next
valid moment in time.</p>
<div class="sourceCode" id="cb14"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb14-1"><a href="#cb14-1" tabindex="-1"></a>x <span class="sc">%&gt;%</span></span>
<span id="cb14-2"><a href="#cb14-2" tabindex="-1"></a>  <span class="fu">as_naive_time</span>() <span class="sc">%&gt;%</span></span>
<span id="cb14-3"><a href="#cb14-3" tabindex="-1"></a>  <span class="fu">add_minutes</span>(<span class="dv">30</span>) <span class="sc">%&gt;%</span></span>
<span id="cb14-4"><a href="#cb14-4" tabindex="-1"></a>  <span class="fu">as_zoned_time</span>(<span class="fu">zoned_time_zone</span>(x), <span class="at">nonexistent =</span> <span class="st">&quot;roll-forward&quot;</span>)</span>
<span id="cb14-5"><a href="#cb14-5" tabindex="-1"></a><span class="co">#&gt; &lt;zoned_time&lt;second&gt;&lt;America/New_York&gt;[1]&gt;</span></span>
<span id="cb14-6"><a href="#cb14-6" tabindex="-1"></a><span class="co">#&gt; [1] &quot;1970-04-26T03:00:00-04:00&quot;</span></span></code></pre></div>
<p>As a general rule, it often makes the most sense to add:</p>
<ul>
<li><p>Years, quarters, and months to a <em>calendar</em>.</p></li>
<li><p>Weeks and days to a <em>naive time</em>.</p></li>
<li><p>Hours, minutes, seconds, and subseconds to a <em>sys
time</em>.</p></li>
</ul>
<p>This is what the high-level API for POSIXct does. However, this isn’t
always what you want, so the low-level API requires you to be more
explicit.</p>
</div>
<div id="where-did-my-posixct-subseconds-go" class="section level2">
<h2>Where did my POSIXct subseconds go?</h2>
<div class="sourceCode" id="cb15"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb15-1"><a href="#cb15-1" tabindex="-1"></a>old <span class="ot">&lt;-</span> <span class="fu">options</span>(<span class="at">digits.secs =</span> <span class="dv">6</span>, <span class="at">digits =</span> <span class="dv">22</span>)</span></code></pre></div>
<p>Consider the following POSIXct:</p>
<div class="sourceCode" id="cb16"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb16-1"><a href="#cb16-1" tabindex="-1"></a>x <span class="ot">&lt;-</span> <span class="fu">as.POSIXct</span>(<span class="st">&quot;2019-01-01 01:00:00.2&quot;</span>, <span class="st">&quot;America/New_York&quot;</span>)</span>
<span id="cb16-2"><a href="#cb16-2" tabindex="-1"></a>x</span>
<span id="cb16-3"><a href="#cb16-3" tabindex="-1"></a><span class="co">#&gt; [1] &quot;2019-01-01 01:00:00.2 EST&quot;</span></span></code></pre></div>
<p>It looks like there is some fractional second information here, but
converting it to naive-time drops it:</p>
<div class="sourceCode" id="cb17"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb17-1"><a href="#cb17-1" tabindex="-1"></a><span class="fu">as_naive_time</span>(x)</span>
<span id="cb17-2"><a href="#cb17-2" tabindex="-1"></a><span class="co">#&gt; &lt;naive_time&lt;second&gt;[1]&gt;</span></span>
<span id="cb17-3"><a href="#cb17-3" tabindex="-1"></a><span class="co">#&gt; [1] &quot;2019-01-01T01:00:00&quot;</span></span></code></pre></div>
<p>This is purposeful. clock treats POSIXct as a <em>second
precision</em> data type. The reason for this has to do with the fact
that POSIXct is implemented as a vector of doubles, which have a limit
to how precisely they can store information. For example, try parsing a
slightly smaller or larger fractional second:</p>
<div class="sourceCode" id="cb18"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb18-1"><a href="#cb18-1" tabindex="-1"></a>y <span class="ot">&lt;-</span> <span class="fu">as.POSIXct</span>(</span>
<span id="cb18-2"><a href="#cb18-2" tabindex="-1"></a>  <span class="fu">c</span>(<span class="st">&quot;2019-01-01 01:00:00.1&quot;</span>, <span class="st">&quot;2019-01-01 01:00:00.3&quot;</span>), </span>
<span id="cb18-3"><a href="#cb18-3" tabindex="-1"></a>  <span class="st">&quot;America/New_York&quot;</span></span>
<span id="cb18-4"><a href="#cb18-4" tabindex="-1"></a>)</span>
<span id="cb18-5"><a href="#cb18-5" tabindex="-1"></a></span>
<span id="cb18-6"><a href="#cb18-6" tabindex="-1"></a><span class="co"># Oh dear!</span></span>
<span id="cb18-7"><a href="#cb18-7" tabindex="-1"></a>y</span>
<span id="cb18-8"><a href="#cb18-8" tabindex="-1"></a><span class="co">#&gt; [1] &quot;2019-01-01 01:00:00.0 EST&quot; &quot;2019-01-01 01:00:00.2 EST&quot;</span></span></code></pre></div>
<p>It isn’t printing correctly, at the very least. Let’s look under the
hood:</p>
<div class="sourceCode" id="cb19"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb19-1"><a href="#cb19-1" tabindex="-1"></a><span class="fu">unclass</span>(y)</span>
<span id="cb19-2"><a href="#cb19-2" tabindex="-1"></a><span class="co">#&gt; [1] 1546322400.099999904633 1546322400.299999952316</span></span>
<span id="cb19-3"><a href="#cb19-3" tabindex="-1"></a><span class="co">#&gt; attr(,&quot;tzone&quot;)</span></span>
<span id="cb19-4"><a href="#cb19-4" tabindex="-1"></a><span class="co">#&gt; [1] &quot;America/New_York&quot;</span></span></code></pre></div>
<p>Double vectors have a limit to how much precision they can represent,
and this is bumping up against that limit. So our <code>.1</code>
seconds is instead represented as <code>.099999etc</code>.</p>
<p>This precision loss gets worse the farther we get from the epoch,
1970-01-01, represented as <code>0</code> under the hood. For example,
here we’ll use a number of seconds that represents the year 2050, and
add 5 microseconds to it:</p>
<div class="sourceCode" id="cb20"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb20-1"><a href="#cb20-1" tabindex="-1"></a>new_utc <span class="ot">&lt;-</span> <span class="cf">function</span>(x) {</span>
<span id="cb20-2"><a href="#cb20-2" tabindex="-1"></a>  <span class="fu">class</span>(x) <span class="ot">&lt;-</span> <span class="fu">c</span>(<span class="st">&quot;POSIXct&quot;</span>, <span class="st">&quot;POSIXt&quot;</span>)</span>
<span id="cb20-3"><a href="#cb20-3" tabindex="-1"></a>  <span class="fu">attr</span>(x, <span class="st">&quot;tzone&quot;</span>) <span class="ot">&lt;-</span> <span class="st">&quot;UTC&quot;</span></span>
<span id="cb20-4"><a href="#cb20-4" tabindex="-1"></a>  x</span>
<span id="cb20-5"><a href="#cb20-5" tabindex="-1"></a>}</span>
<span id="cb20-6"><a href="#cb20-6" tabindex="-1"></a></span>
<span id="cb20-7"><a href="#cb20-7" tabindex="-1"></a>year_2050 <span class="ot">&lt;-</span> <span class="dv">2524608000</span></span>
<span id="cb20-8"><a href="#cb20-8" tabindex="-1"></a>five_microseconds <span class="ot">&lt;-</span> <span class="fl">0.000005</span></span>
<span id="cb20-9"><a href="#cb20-9" tabindex="-1"></a></span>
<span id="cb20-10"><a href="#cb20-10" tabindex="-1"></a><span class="fu">new_utc</span>(year_2050)</span>
<span id="cb20-11"><a href="#cb20-11" tabindex="-1"></a><span class="co">#&gt; [1] &quot;2050-01-01 UTC&quot;</span></span>
<span id="cb20-12"><a href="#cb20-12" tabindex="-1"></a></span>
<span id="cb20-13"><a href="#cb20-13" tabindex="-1"></a><span class="co"># Oh no!</span></span>
<span id="cb20-14"><a href="#cb20-14" tabindex="-1"></a><span class="fu">new_utc</span>(year_2050 <span class="sc">+</span> five_microseconds)</span>
<span id="cb20-15"><a href="#cb20-15" tabindex="-1"></a><span class="co">#&gt; [1] &quot;2050-01-01 00:00:00.000004 UTC&quot;</span></span>
<span id="cb20-16"><a href="#cb20-16" tabindex="-1"></a></span>
<span id="cb20-17"><a href="#cb20-17" tabindex="-1"></a><span class="co"># Represented internally as:</span></span>
<span id="cb20-18"><a href="#cb20-18" tabindex="-1"></a>year_2050 <span class="sc">+</span> five_microseconds</span>
<span id="cb20-19"><a href="#cb20-19" tabindex="-1"></a><span class="co">#&gt; [1] 2524608000.000004768372</span></span></code></pre></div>
<p>Because of these issues, clock treats POSIXct as a second precision
data type, dropping all other information. Instead, you should parse
directly into a subsecond clock type:</p>
<div class="sourceCode" id="cb21"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb21-1"><a href="#cb21-1" tabindex="-1"></a><span class="fu">naive_time_parse</span>(</span>
<span id="cb21-2"><a href="#cb21-2" tabindex="-1"></a>  <span class="fu">c</span>(<span class="st">&quot;2019-01-01T01:00:00.1&quot;</span>, <span class="st">&quot;2019-01-01T01:00:00.3&quot;</span>), </span>
<span id="cb21-3"><a href="#cb21-3" tabindex="-1"></a>  <span class="at">precision =</span> <span class="st">&quot;millisecond&quot;</span></span>
<span id="cb21-4"><a href="#cb21-4" tabindex="-1"></a>) <span class="sc">%&gt;%</span></span>
<span id="cb21-5"><a href="#cb21-5" tabindex="-1"></a>  <span class="fu">as_zoned_time</span>(<span class="st">&quot;America/New_York&quot;</span>)</span>
<span id="cb21-6"><a href="#cb21-6" tabindex="-1"></a><span class="co">#&gt; &lt;zoned_time&lt;millisecond&gt;&lt;America/New_York&gt;[2]&gt;</span></span>
<span id="cb21-7"><a href="#cb21-7" tabindex="-1"></a><span class="co">#&gt; [1] &quot;2019-01-01T01:00:00.100-05:00&quot; &quot;2019-01-01T01:00:00.300-05:00&quot;</span></span></code></pre></div>
<div class="sourceCode" id="cb22"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb22-1"><a href="#cb22-1" tabindex="-1"></a><span class="co"># Reset old options</span></span>
<span id="cb22-2"><a href="#cb22-2" tabindex="-1"></a><span class="fu">options</span>(old)</span></code></pre></div>
</div>
<div id="what-is-the-time-zone-of-date" class="section level2">
<h2>What is the time zone of Date?</h2>
<p>In clock, R’s native Date type is actually assumed to be
<em>naive</em>, i.e. clock assumes that there is a yet-to-be-specified
time zone, like with a naive-time. The other possibility is to assume
that Date is UTC (like sys-time), but it is often more intuitive for
Dates to be naive when manipulating them and converting them to
zoned-time or POSIXct.</p>
<p>R does not consistently treat Dates as naive or UTC. Instead it
switches between them, depending on the function.</p>
<p>For example, the Date method of <code>as.POSIXct()</code> does not
expose a <code>tz</code> argument. Instead, it assumes that Date is UTC,
and that the result should be shown in local time (as defined by
<code>Sys.timezone()</code>). This often results in confusing behavior,
such as:</p>
<div class="sourceCode" id="cb23"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb23-1"><a href="#cb23-1" tabindex="-1"></a>x <span class="ot">&lt;-</span> <span class="fu">as.Date</span>(<span class="st">&quot;2019-01-01&quot;</span>)</span>
<span id="cb23-2"><a href="#cb23-2" tabindex="-1"></a>x</span>
<span id="cb23-3"><a href="#cb23-3" tabindex="-1"></a><span class="co">#&gt; [1] &quot;2019-01-01&quot;</span></span>
<span id="cb23-4"><a href="#cb23-4" tabindex="-1"></a></span>
<span id="cb23-5"><a href="#cb23-5" tabindex="-1"></a>withr<span class="sc">::</span><span class="fu">with_timezone</span>(<span class="st">&quot;America/New_York&quot;</span>, {</span>
<span id="cb23-6"><a href="#cb23-6" tabindex="-1"></a>  <span class="fu">print</span>(<span class="fu">as.POSIXct</span>(x))</span>
<span id="cb23-7"><a href="#cb23-7" tabindex="-1"></a>})</span>
<span id="cb23-8"><a href="#cb23-8" tabindex="-1"></a><span class="co">#&gt; [1] &quot;2019-01-01 UTC&quot;</span></span></code></pre></div>
<p>With clock, converting to zoned-time from Date will always assume
that Date is naive, which will keep the printed date (if possible) and
show it in the <code>zone</code> you specified.</p>
<div class="sourceCode" id="cb24"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb24-1"><a href="#cb24-1" tabindex="-1"></a><span class="fu">as_zoned_time</span>(x, <span class="st">&quot;UTC&quot;</span>)</span>
<span id="cb24-2"><a href="#cb24-2" tabindex="-1"></a><span class="co">#&gt; &lt;zoned_time&lt;second&gt;&lt;UTC&gt;[1]&gt;</span></span>
<span id="cb24-3"><a href="#cb24-3" tabindex="-1"></a><span class="co">#&gt; [1] &quot;2019-01-01T00:00:00+00:00&quot;</span></span>
<span id="cb24-4"><a href="#cb24-4" tabindex="-1"></a></span>
<span id="cb24-5"><a href="#cb24-5" tabindex="-1"></a><span class="fu">as_zoned_time</span>(x, <span class="st">&quot;America/New_York&quot;</span>)</span>
<span id="cb24-6"><a href="#cb24-6" tabindex="-1"></a><span class="co">#&gt; &lt;zoned_time&lt;second&gt;&lt;America/New_York&gt;[1]&gt;</span></span>
<span id="cb24-7"><a href="#cb24-7" tabindex="-1"></a><span class="co">#&gt; [1] &quot;2019-01-01T00:00:00-05:00&quot;</span></span>
<span id="cb24-8"><a href="#cb24-8" tabindex="-1"></a></span>
<span id="cb24-9"><a href="#cb24-9" tabindex="-1"></a><span class="fu">as_zoned_time</span>(x, <span class="st">&quot;Europe/London&quot;</span>)</span>
<span id="cb24-10"><a href="#cb24-10" tabindex="-1"></a><span class="co">#&gt; &lt;zoned_time&lt;second&gt;&lt;Europe/London&gt;[1]&gt;</span></span>
<span id="cb24-11"><a href="#cb24-11" tabindex="-1"></a><span class="co">#&gt; [1] &quot;2019-01-01T00:00:00+00:00&quot;</span></span></code></pre></div>
<p>On the other hand, the POSIXct method for <code>as.Date()</code>
treats Date as a naive type. This is probably what you want, and this
example just shows the inconsistency. It is a bit hard to see this,
because the <code>tz</code> argument of the method defaults to
<code>&quot;UTC&quot;</code>, but if you set the <code>tz</code> argument to the
zone of your input, it becomes clear:</p>
<div class="sourceCode" id="cb25"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb25-1"><a href="#cb25-1" tabindex="-1"></a>x <span class="ot">&lt;-</span> <span class="fu">as.POSIXct</span>(<span class="st">&quot;2019-01-01 23:00:00&quot;</span>, <span class="st">&quot;America/New_York&quot;</span>)</span>
<span id="cb25-2"><a href="#cb25-2" tabindex="-1"></a></span>
<span id="cb25-3"><a href="#cb25-3" tabindex="-1"></a><span class="fu">as.Date</span>(x, <span class="at">tz =</span> <span class="fu">date_time_zone</span>(x))</span>
<span id="cb25-4"><a href="#cb25-4" tabindex="-1"></a><span class="co">#&gt; [1] &quot;2019-01-01&quot;</span></span></code></pre></div>
<p>If this assumed that Date was UTC, then it would have resulted in
something like:</p>
<div class="sourceCode" id="cb26"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb26-1"><a href="#cb26-1" tabindex="-1"></a>utc <span class="ot">&lt;-</span> <span class="fu">date_time_set_zone</span>(x, <span class="st">&quot;UTC&quot;</span>)</span>
<span id="cb26-2"><a href="#cb26-2" tabindex="-1"></a>utc</span>
<span id="cb26-3"><a href="#cb26-3" tabindex="-1"></a><span class="co">#&gt; [1] &quot;2019-01-02 04:00:00 UTC&quot;</span></span>
<span id="cb26-4"><a href="#cb26-4" tabindex="-1"></a></span>
<span id="cb26-5"><a href="#cb26-5" tabindex="-1"></a><span class="fu">as.Date</span>(utc, <span class="at">tz =</span> <span class="fu">date_time_zone</span>(utc))</span>
<span id="cb26-6"><a href="#cb26-6" tabindex="-1"></a><span class="co">#&gt; [1] &quot;2019-01-02&quot;</span></span></code></pre></div>
</div>
<div id="what-does-clock-do-with-leap-seconds" class="section level2">
<h2>What does clock do with leap seconds?</h2>
<p>clock currently handles leap seconds in the same way that base R’s
date-time (POSIXct) class does - it ignores them entirely. While
<code>strptime()</code> has some very simple capabilities for parsing
leap seconds, clock doesn’t allow them at all:</p>
<div class="sourceCode" id="cb27"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb27-1"><a href="#cb27-1" tabindex="-1"></a>raw <span class="ot">&lt;-</span> <span class="fu">c</span>(</span>
<span id="cb27-2"><a href="#cb27-2" tabindex="-1"></a>  <span class="st">&quot;2015-12-31T23:59:59&quot;</span>, </span>
<span id="cb27-3"><a href="#cb27-3" tabindex="-1"></a>  <span class="st">&quot;2015-12-31T23:59:60&quot;</span>, <span class="co"># A real leap second!</span></span>
<span id="cb27-4"><a href="#cb27-4" tabindex="-1"></a>  <span class="st">&quot;2016-01-01T00:00:00&quot;</span></span>
<span id="cb27-5"><a href="#cb27-5" tabindex="-1"></a>)</span>
<span id="cb27-6"><a href="#cb27-6" tabindex="-1"></a></span>
<span id="cb27-7"><a href="#cb27-7" tabindex="-1"></a>x <span class="ot">&lt;-</span> <span class="fu">sys_time_parse</span>(raw)</span>
<span id="cb27-8"><a href="#cb27-8" tabindex="-1"></a><span class="co">#&gt; Warning: Failed to parse 1 string at location 2. Returning `NA` at that</span></span>
<span id="cb27-9"><a href="#cb27-9" tabindex="-1"></a><span class="co">#&gt; location.</span></span>
<span id="cb27-10"><a href="#cb27-10" tabindex="-1"></a></span>
<span id="cb27-11"><a href="#cb27-11" tabindex="-1"></a>x</span>
<span id="cb27-12"><a href="#cb27-12" tabindex="-1"></a><span class="co">#&gt; &lt;sys_time&lt;second&gt;[3]&gt;</span></span>
<span id="cb27-13"><a href="#cb27-13" tabindex="-1"></a><span class="co">#&gt; [1] &quot;2015-12-31T23:59:59&quot; NA                    &quot;2016-01-01T00:00:00&quot;</span></span></code></pre></div>
<div class="sourceCode" id="cb28"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb28-1"><a href="#cb28-1" tabindex="-1"></a><span class="co"># Reported as exactly 1 second apart.</span></span>
<span id="cb28-2"><a href="#cb28-2" tabindex="-1"></a><span class="co"># In real life these are 2 seconds apart because of the leap second.</span></span>
<span id="cb28-3"><a href="#cb28-3" tabindex="-1"></a>x[[<span class="dv">3</span>]] <span class="sc">-</span> x[[<span class="dv">1</span>]]</span>
<span id="cb28-4"><a href="#cb28-4" tabindex="-1"></a><span class="co">#&gt; &lt;duration&lt;second&gt;[1]&gt;</span></span>
<span id="cb28-5"><a href="#cb28-5" tabindex="-1"></a><span class="co">#&gt; [1] 1</span></span></code></pre></div>
<p>Because none of the clock types handle leap seconds, clock currently
doesn’t offer a way to parse them. Your current best option if you
<em>really</em> need to parse leap seconds is to use
<code>strptime()</code>:</p>
<div class="sourceCode" id="cb29"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb29-1"><a href="#cb29-1" tabindex="-1"></a><span class="co"># This returns a POSIXlt, which can handle the special 60s field</span></span>
<span id="cb29-2"><a href="#cb29-2" tabindex="-1"></a>x <span class="ot">&lt;-</span> <span class="fu">strptime</span>(raw, <span class="at">format =</span> <span class="st">&quot;%Y-%m-%dT%H:%M:%S&quot;</span>, <span class="at">tz =</span> <span class="st">&quot;UTC&quot;</span>)</span>
<span id="cb29-3"><a href="#cb29-3" tabindex="-1"></a>x</span>
<span id="cb29-4"><a href="#cb29-4" tabindex="-1"></a><span class="co">#&gt; [1] &quot;2015-12-31 23:59:59 UTC&quot; &quot;2015-12-31 23:59:60 UTC&quot;</span></span>
<span id="cb29-5"><a href="#cb29-5" tabindex="-1"></a><span class="co">#&gt; [3] &quot;2016-01-01 00:00:00 UTC&quot;</span></span>
<span id="cb29-6"><a href="#cb29-6" tabindex="-1"></a></span>
<span id="cb29-7"><a href="#cb29-7" tabindex="-1"></a><span class="co"># On conversion to POSIXct, it &quot;rolls&quot; forward</span></span>
<span id="cb29-8"><a href="#cb29-8" tabindex="-1"></a><span class="fu">as.POSIXct</span>(x)</span>
<span id="cb29-9"><a href="#cb29-9" tabindex="-1"></a><span class="co">#&gt; [1] &quot;2015-12-31 23:59:59 UTC&quot; &quot;2016-01-01 00:00:00 UTC&quot;</span></span>
<span id="cb29-10"><a href="#cb29-10" tabindex="-1"></a><span class="co">#&gt; [3] &quot;2016-01-01 00:00:00 UTC&quot;</span></span></code></pre></div>
<p><code>strptime()</code> isn’t a great solution though, because the
parsing is fairly simple. If you try to use a “fake” leap second, it
will still accept it, even though it isn’t a real time:</p>
<div class="sourceCode" id="cb30"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb30-1"><a href="#cb30-1" tabindex="-1"></a><span class="co"># 2016-12-31 wasn&#39;t a leap second date, but it still tries to parse this fake time</span></span>
<span id="cb30-2"><a href="#cb30-2" tabindex="-1"></a><span class="fu">strptime</span>(<span class="st">&quot;2016-12-31T23:59:60&quot;</span>, <span class="at">format =</span> <span class="st">&quot;%Y-%m-%dT%H:%M:%S&quot;</span>, <span class="at">tz =</span> <span class="st">&quot;UTC&quot;</span>)</span>
<span id="cb30-3"><a href="#cb30-3" tabindex="-1"></a><span class="co">#&gt; [1] &quot;2016-12-31 23:59:60 UTC&quot;</span></span></code></pre></div>
<p>A true solution would check this against a database of actual leap
seconds, and would only successfully parse it if it matched a real leap
second. The C++ library that powers clock does have this capability,
through a <code>utc_clock</code> class, and we may expose this in a
limited form in the future, with conversion to and from sys-time and
naive-time.</p>
</div>
<div id="why-doesnt-this-work-with-data.table" class="section level2">
<h2>Why doesn’t this work with data.table?</h2>
<p>While the entire high-level API for R’s native date (Date) and
date-time (POSIXct) types will work fine with data.table, if you try to
put any of the major clock types into a data.table, you will probably
see this error message:</p>
<div class="sourceCode" id="cb31"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb31-1"><a href="#cb31-1" tabindex="-1"></a><span class="fu">library</span>(data.table)</span>
<span id="cb31-2"><a href="#cb31-2" tabindex="-1"></a></span>
<span id="cb31-3"><a href="#cb31-3" tabindex="-1"></a><span class="fu">data.table</span>(<span class="at">x =</span> <span class="fu">year_month_day</span>(<span class="dv">2019</span>, <span class="dv">1</span>, <span class="dv">1</span>))</span>
<span id="cb31-4"><a href="#cb31-4" tabindex="-1"></a><span class="co">#&gt; Error in dimnames(x) &lt;- dn : </span></span>
<span id="cb31-5"><a href="#cb31-5" tabindex="-1"></a><span class="co">#&gt;   length of &#39;dimnames&#39; [1] not equal to array extent</span></span></code></pre></div>
<p>You won’t see this issue when working with data.frames or
tibbles.</p>
<p>As of now, data.table doesn’t support the concept of <em>record
types</em>. These are implemented as a list of vectors of equal length,
that together represent a single idea. The <code>length()</code> of
these types should be taken from the length of the vectors, not the
length of the list. If you unclass any of the clock types, you’ll see
that they are implemented in this way:</p>
<div class="sourceCode" id="cb32"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb32-1"><a href="#cb32-1" tabindex="-1"></a>ymdh <span class="ot">&lt;-</span> <span class="fu">year_month_day</span>(<span class="dv">2019</span>, <span class="dv">1</span>, <span class="dv">1</span><span class="sc">:</span><span class="dv">2</span>, <span class="dv">1</span>)</span>
<span id="cb32-2"><a href="#cb32-2" tabindex="-1"></a></span>
<span id="cb32-3"><a href="#cb32-3" tabindex="-1"></a><span class="fu">unclass</span>(ymdh)</span>
<span id="cb32-4"><a href="#cb32-4" tabindex="-1"></a><span class="co">#&gt; $year</span></span>
<span id="cb32-5"><a href="#cb32-5" tabindex="-1"></a><span class="co">#&gt; [1] 2019 2019</span></span>
<span id="cb32-6"><a href="#cb32-6" tabindex="-1"></a><span class="co">#&gt; </span></span>
<span id="cb32-7"><a href="#cb32-7" tabindex="-1"></a><span class="co">#&gt; $month</span></span>
<span id="cb32-8"><a href="#cb32-8" tabindex="-1"></a><span class="co">#&gt; [1] 1 1</span></span>
<span id="cb32-9"><a href="#cb32-9" tabindex="-1"></a><span class="co">#&gt; </span></span>
<span id="cb32-10"><a href="#cb32-10" tabindex="-1"></a><span class="co">#&gt; $day</span></span>
<span id="cb32-11"><a href="#cb32-11" tabindex="-1"></a><span class="co">#&gt; [1] 1 2</span></span>
<span id="cb32-12"><a href="#cb32-12" tabindex="-1"></a><span class="co">#&gt; </span></span>
<span id="cb32-13"><a href="#cb32-13" tabindex="-1"></a><span class="co">#&gt; $hour</span></span>
<span id="cb32-14"><a href="#cb32-14" tabindex="-1"></a><span class="co">#&gt; [1] 1 1</span></span>
<span id="cb32-15"><a href="#cb32-15" tabindex="-1"></a><span class="co">#&gt; </span></span>
<span id="cb32-16"><a href="#cb32-16" tabindex="-1"></a><span class="co">#&gt; attr(,&quot;precision&quot;)</span></span>
<span id="cb32-17"><a href="#cb32-17" tabindex="-1"></a><span class="co">#&gt; [1] 5</span></span>
<span id="cb32-18"><a href="#cb32-18" tabindex="-1"></a></span>
<span id="cb32-19"><a href="#cb32-19" tabindex="-1"></a><span class="fu">unclass</span>(<span class="fu">as_naive_time</span>(ymdh))</span>
<span id="cb32-20"><a href="#cb32-20" tabindex="-1"></a><span class="co">#&gt; $lower</span></span>
<span id="cb32-21"><a href="#cb32-21" tabindex="-1"></a><span class="co">#&gt; [1] 2147483648 2147483648</span></span>
<span id="cb32-22"><a href="#cb32-22" tabindex="-1"></a><span class="co">#&gt; </span></span>
<span id="cb32-23"><a href="#cb32-23" tabindex="-1"></a><span class="co">#&gt; $upper</span></span>
<span id="cb32-24"><a href="#cb32-24" tabindex="-1"></a><span class="co">#&gt; [1] 429529 429553</span></span>
<span id="cb32-25"><a href="#cb32-25" tabindex="-1"></a><span class="co">#&gt; </span></span>
<span id="cb32-26"><a href="#cb32-26" tabindex="-1"></a><span class="co">#&gt; attr(,&quot;precision&quot;)</span></span>
<span id="cb32-27"><a href="#cb32-27" tabindex="-1"></a><span class="co">#&gt; [1] 5</span></span>
<span id="cb32-28"><a href="#cb32-28" tabindex="-1"></a><span class="co">#&gt; attr(,&quot;clock&quot;)</span></span>
<span id="cb32-29"><a href="#cb32-29" tabindex="-1"></a><span class="co">#&gt; [1] 1</span></span></code></pre></div>
<p>I find that record types are extremely useful data structures for
building upon R’s basic atomic types in ways that otherwise couldn’t be
done. They allow calendar types to hold information about each
component, enabling instant access for retrieval, modification, and
grouping. They also allow calendars to represent invalid dates, such as
<code>2019-02-31</code>, without any issues. Time points use them to
store up to nanosecond precision date-times, which are really C++
<code>int64_t</code> types that don’t nicely fit into any R atomic type
(I am aware of the bit64 package, and made a conscious decision to
implement as a record type instead. This partly had to do with how
missing values are handled, and how that integrates with vctrs).</p>
<p>The idea of a record type actually isn’t new. R’s own POSIXlt type is
a record type:</p>
<div class="sourceCode" id="cb33"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb33-1"><a href="#cb33-1" tabindex="-1"></a>x <span class="ot">&lt;-</span> <span class="fu">as.POSIXct</span>(<span class="st">&quot;2019-01-01&quot;</span>, <span class="st">&quot;America/New_York&quot;</span>)</span>
<span id="cb33-2"><a href="#cb33-2" tabindex="-1"></a></span>
<span id="cb33-3"><a href="#cb33-3" tabindex="-1"></a><span class="co"># POSIXct is implemented as a double</span></span>
<span id="cb33-4"><a href="#cb33-4" tabindex="-1"></a><span class="fu">unclass</span>(x)</span>
<span id="cb33-5"><a href="#cb33-5" tabindex="-1"></a><span class="co">#&gt; [1] 1546318800</span></span>
<span id="cb33-6"><a href="#cb33-6" tabindex="-1"></a><span class="co">#&gt; attr(,&quot;tzone&quot;)</span></span>
<span id="cb33-7"><a href="#cb33-7" tabindex="-1"></a><span class="co">#&gt; [1] &quot;America/New_York&quot;</span></span>
<span id="cb33-8"><a href="#cb33-8" tabindex="-1"></a></span>
<span id="cb33-9"><a href="#cb33-9" tabindex="-1"></a><span class="co"># POSIXlt is a record type</span></span>
<span id="cb33-10"><a href="#cb33-10" tabindex="-1"></a><span class="fu">unclass</span>(<span class="fu">as.POSIXlt</span>(x))</span>
<span id="cb33-11"><a href="#cb33-11" tabindex="-1"></a><span class="co">#&gt; $sec</span></span>
<span id="cb33-12"><a href="#cb33-12" tabindex="-1"></a><span class="co">#&gt; [1] 0</span></span>
<span id="cb33-13"><a href="#cb33-13" tabindex="-1"></a><span class="co">#&gt; </span></span>
<span id="cb33-14"><a href="#cb33-14" tabindex="-1"></a><span class="co">#&gt; $min</span></span>
<span id="cb33-15"><a href="#cb33-15" tabindex="-1"></a><span class="co">#&gt; [1] 0</span></span>
<span id="cb33-16"><a href="#cb33-16" tabindex="-1"></a><span class="co">#&gt; </span></span>
<span id="cb33-17"><a href="#cb33-17" tabindex="-1"></a><span class="co">#&gt; $hour</span></span>
<span id="cb33-18"><a href="#cb33-18" tabindex="-1"></a><span class="co">#&gt; [1] 0</span></span>
<span id="cb33-19"><a href="#cb33-19" tabindex="-1"></a><span class="co">#&gt; </span></span>
<span id="cb33-20"><a href="#cb33-20" tabindex="-1"></a><span class="co">#&gt; $mday</span></span>
<span id="cb33-21"><a href="#cb33-21" tabindex="-1"></a><span class="co">#&gt; [1] 1</span></span>
<span id="cb33-22"><a href="#cb33-22" tabindex="-1"></a><span class="co">#&gt; </span></span>
<span id="cb33-23"><a href="#cb33-23" tabindex="-1"></a><span class="co">#&gt; $mon</span></span>
<span id="cb33-24"><a href="#cb33-24" tabindex="-1"></a><span class="co">#&gt; [1] 0</span></span>
<span id="cb33-25"><a href="#cb33-25" tabindex="-1"></a><span class="co">#&gt; </span></span>
<span id="cb33-26"><a href="#cb33-26" tabindex="-1"></a><span class="co">#&gt; $year</span></span>
<span id="cb33-27"><a href="#cb33-27" tabindex="-1"></a><span class="co">#&gt; [1] 119</span></span>
<span id="cb33-28"><a href="#cb33-28" tabindex="-1"></a><span class="co">#&gt; </span></span>
<span id="cb33-29"><a href="#cb33-29" tabindex="-1"></a><span class="co">#&gt; $wday</span></span>
<span id="cb33-30"><a href="#cb33-30" tabindex="-1"></a><span class="co">#&gt; [1] 2</span></span>
<span id="cb33-31"><a href="#cb33-31" tabindex="-1"></a><span class="co">#&gt; </span></span>
<span id="cb33-32"><a href="#cb33-32" tabindex="-1"></a><span class="co">#&gt; $yday</span></span>
<span id="cb33-33"><a href="#cb33-33" tabindex="-1"></a><span class="co">#&gt; [1] 0</span></span>
<span id="cb33-34"><a href="#cb33-34" tabindex="-1"></a><span class="co">#&gt; </span></span>
<span id="cb33-35"><a href="#cb33-35" tabindex="-1"></a><span class="co">#&gt; $isdst</span></span>
<span id="cb33-36"><a href="#cb33-36" tabindex="-1"></a><span class="co">#&gt; [1] 0</span></span>
<span id="cb33-37"><a href="#cb33-37" tabindex="-1"></a><span class="co">#&gt; </span></span>
<span id="cb33-38"><a href="#cb33-38" tabindex="-1"></a><span class="co">#&gt; $zone</span></span>
<span id="cb33-39"><a href="#cb33-39" tabindex="-1"></a><span class="co">#&gt; [1] &quot;EST&quot;</span></span>
<span id="cb33-40"><a href="#cb33-40" tabindex="-1"></a><span class="co">#&gt; </span></span>
<span id="cb33-41"><a href="#cb33-41" tabindex="-1"></a><span class="co">#&gt; $gmtoff</span></span>
<span id="cb33-42"><a href="#cb33-42" tabindex="-1"></a><span class="co">#&gt; [1] -18000</span></span>
<span id="cb33-43"><a href="#cb33-43" tabindex="-1"></a><span class="co">#&gt; </span></span>
<span id="cb33-44"><a href="#cb33-44" tabindex="-1"></a><span class="co">#&gt; attr(,&quot;tzone&quot;)</span></span>
<span id="cb33-45"><a href="#cb33-45" tabindex="-1"></a><span class="co">#&gt; [1] &quot;America/New_York&quot; &quot;EST&quot;              &quot;EDT&quot;             </span></span>
<span id="cb33-46"><a href="#cb33-46" tabindex="-1"></a><span class="co">#&gt; attr(,&quot;balanced&quot;)</span></span>
<span id="cb33-47"><a href="#cb33-47" tabindex="-1"></a><span class="co">#&gt; [1] TRUE</span></span></code></pre></div>
<p>data.table doesn’t truly support POSIXlt either. Instead, you get a
warning about them converting it to a POSIXct. This is pretty reasonable
considering their focus on performance.</p>
<div class="sourceCode" id="cb34"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb34-1"><a href="#cb34-1" tabindex="-1"></a><span class="fu">data.table</span>(<span class="at">x =</span> <span class="fu">as.POSIXlt</span>(<span class="st">&quot;2019-01-01&quot;</span>, <span class="st">&quot;America/New_York&quot;</span>))</span>
<span id="cb34-2"><a href="#cb34-2" tabindex="-1"></a><span class="co">#&gt;             x</span></span>
<span id="cb34-3"><a href="#cb34-3" tabindex="-1"></a><span class="co">#&gt; 1: 2019-01-01</span></span>
<span id="cb34-4"><a href="#cb34-4" tabindex="-1"></a><span class="co">#&gt; Warning message:</span></span>
<span id="cb34-5"><a href="#cb34-5" tabindex="-1"></a><span class="co">#&gt; In as.data.table.list(x, keep.rownames = keep.rownames, check.names = check.names,  :</span></span>
<span id="cb34-6"><a href="#cb34-6" tabindex="-1"></a><span class="co">#&gt;   POSIXlt column type detected and converted to POSIXct. We do not recommend use of POSIXlt at all because it uses 40 bytes to store one date.</span></span></code></pre></div>
<p>It was previously a bit difficult to create record types in R because
there were few examples and no resources to build on. In vctrs, we’ve
added a <code>vctrs_rcrd</code> type that serves as a base to build new
record types on. Many S3 methods have been written for
<code>vctrs_rcrd</code>s in a way that should work for any type that
builds on top of it, giving you a lot of scaffolding for free.</p>
<p>I am hopeful that as more record types make their way into the R
ecosystem built on this common foundation, it might be possible for
data.table to enable this as an approved type in their package.</p>
</div>



<!-- code folding -->


<!-- dynamically load mathjax for compatibility with self-contained -->
<script>
  (function () {
    var script = document.createElement("script");
    script.type = "text/javascript";
    script.src  = "https://mathjax.rstudio.com/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML";
    document.getElementsByTagName("head")[0].appendChild(script);
  })();
</script>

</body>
</html>