Time libraries like this are a basket of inscrutable bugs waiting to happen. A simply API deceiving its users into thinking they'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're never even <i>points</i>, for that matter, but explicit intervals.
* Which calendar? In modern, western times you'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 "at 3pm" but you should realize that there'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 "3pm will occur once a day" may not genuinely be true.<p>* Universal times, of which there are a few variations each dealing with leap seconds differently, UTC, UT0/1/1R/2, TAI (<a href="https://en.wikipedia.org/wiki/Universal_Time" rel="nofollow">https://en.wikipedia.org/wiki/Universal_Time</a>)<p>* Intervals of universal time, like "10 seconds" 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 "half a day" 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 "Olson" database is probably sufficient) and a reasonably exact notion of where someone is in space that they are interpreting times (go look up Indiana'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 "day" of some assumed calendar. Then you can, given that person'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've ever used in anger which handles all of this is Haskell's `time` library.<p><pre><code> https://hackage.haskell.org/package/time
http://two-wrongs.com/haskell-time-library-tutorial</code></pre>