Time libraries like this are a basket of inscrutable bugs waiting to happen. A simply API deceiving its users into thinking they&#x27;re dealing with a simple subject. Time is anything but.<p>There are a few notions of time, each wildly different from the other, which we as humans transparently conflate but which will throw computers into wild undecipherable loops:<p>* Dates, specifically delimited by days, which are logical items of a calendar, not absolute points in time. They&#x27;re never even <i>points</i>, for that matter, but explicit intervals.
   * Which calendar? In modern, western times you&#x27;re okay with just one, but historical, international, and especially historical international dates you will fail.<p>* Wall times or local times, e.g. what a human being might think the local time is. This is what we tend to mean when something ought to happen &quot;at 3pm&quot; but you should realize that there&#x27;s no way to treat this uniformly: it holds <i>on a particular day</i>, <i>in a particular location</i>. Even simple ideas like &quot;3pm will occur once a day&quot; may not genuinely be true.<p>* Universal times, of which there are a few variations each dealing with leap seconds differently, UTC, UT0&#x2F;1&#x2F;1R&#x2F;2, TAI (<a href="https:&#x2F;&#x2F;en.wikipedia.org&#x2F;wiki&#x2F;Universal_Time" rel="nofollow">https:&#x2F;&#x2F;en.wikipedia.org&#x2F;wiki&#x2F;Universal_Time</a>)<p>* Intervals of universal time, like &quot;10 seconds&quot; which are the only things which behave sanely from a physical point of view. This is why CPU time or Epoch time is nice. Adding two universal time intervals produces an interval twice as long. Adding a universal time interval to a universal time point produces a new universal time point which, subject to leap seconds, may or may not appear to be the proper number of seconds away. Adding a universal time interval to anything else is nonsense.<p>* Intervals of wall-times like &quot;half a day&quot; which can be added meaningfully to combinations of wall-time and dates in a given calendar, useful for setting up human-interpretable re-occurrences.<p>* Intervals of dates which can be added to dates within a calendar<p>Other caveats apply, mostly having to do with the need to have an accurate geopolitical rundown of time disputes (the &quot;Olson&quot; database is probably sufficient) and a reasonably exact notion of where someone is in space that they are interpreting times (go look up Indiana&#x27;s time zone and then throw away your standard US 4-tz notion).<p>Generally, the idea is that when dealing with humans you want to think of time as being arranged into approximately 24-hour chunks (possibly longer or shorter and then overlapping or with weird gaps which should be smoothed out) assigned to each &quot;day&quot; of some assumed calendar. Then you can, given that person&#x27;s exact point in space, convert points in this notion of time into a universal one using the Olson database. Converting intervals is harder and must be done by converting both ends and then subtracting in universal time, handling leap seconds if you care.<p>The only time library I&#x27;ve ever used in anger which handles all of this is Haskell&#x27;s `time` library.<p><pre><code>    https:&#x2F;&#x2F;hackage.haskell.org&#x2F;package&#x2F;time
    http:&#x2F;&#x2F;two-wrongs.com&#x2F;haskell-time-library-tutorial</code></pre>