# time.h design issues

Sat Aug 28 02:30:04 UTC 1999

```I hope this is within the scope of this mailing list, if
not please let me know where is a good place to discuss this.

"D. J. Bernstein" wrote:
>
> Paul Eggert writes:
> > http://www.twinsun.com/tz/timeapi.html
>
> I don't understand what problems you're trying to solve here.
>
> Time libraries should be designed to support the features that real
> programs need. For example:

Your examples where perfectly good, but you left out some of the real
fun
calendar calculations.

* scheduling programs that deal with humans need to be able to
specify and calculate various relative moments in time. Examples
include: the beginning next week, start of next month,
two days before the beginning of the last month of the year,
the last Thursday in November, exactly 60 days from now,
exactly two months before now, the first day of this year,
the beginning of the third month of this year etc.

> Evidently there are four basic objects here:
>
>    * Calendar dates: year-month-day.
>    * Civil times: year-month-day, hour-minute-second, zone.
>    * Date intervals, expressed as a number of days.
>    * Time intervals, expressed as a number of seconds.

But also there are sometimes needs for:

* Time intervals, expressed as combinations of unspecified years,
months, days, weeks, hours etc.

Plus those folks who happen to calculate better than seconds need.

* time intervals, expressed in units smaller
than seconds (many systems use milliseconds).

We can convert delta milliseconds only to everything up to and including
hours without knowledge of when the interval occurs, because everything
larger has a variable length, therefore not all useful intervals
can be specified in just milliseconds.

> Arithmetic on intervals is trivial. To support arithmetic on calendar
> dates and civil times we can set epochs and provide a few fundamental
> conversions:

Just calculating one of milliseconds, seconds or days since epoch and
then performing arithmetic on these intervals is not sufficient.

Given an answer of 6.5 days between two times, is the later time
the same week as the earlier?

Is a time 24 hours from now always in the next civil day?  It might NOT
be on the day DLS springs forward, i.e. a 24 hour day.

I hope you can see from the above that not all date calculations are
just
the same as arithmetic on intervals expressed in small enough units.

>    * Convert seconds-since-epoch to a civil time in the local time zone.
>    * Convert any civil time to seconds-since-epoch.
>    * Convert days-since-epoch to a calendar date.
>    * Convert a calendar date to days-since-epoch.

What can often get you most of the answers to the above examples
is the ability to:

* Convert a calendar date or time to whole months, hours, weeks,
years, quarters, moons, pay periods :-) etc. since epoch with
or without considering TZ.

related cousin

* Convert a time to the another time that represents the beginning
of the period; i.e. beginning of year, month, week,
day etc. with or without considering TZ.

I think many of the people who are suggesting changes are considering
some of the possibilities I have mentioned, but it seems ti me you may
have simplified the problem somewhat and overlooked some of the
interesting challenges of relative date calculations, comparisons and
specification.

-Paul

```