header file(s): z_time.h, z_stime.h, z_timeperiod.h, z_timespan.h, z_datefmt.h

synopsis.
The time group (unlike strings at the lowest layers), is focused almost entirely around a small set of powerful objects for doing operations with time. Units of Time are stored in an internal data structure called "datestuff", which maintains the earthly units century, year, month, day, hour, minute, second, and microsecond. There is an internal counter for each unit of time. This is a markedly different implementation from code that converts time into a common base unit, such as number of seconds from a specific date (for example, Unix time is measured as number of seconds from 1/1/1970).

Except for a few small functions at the lowest layer [0] for putting the program to sleep, time really begins at layer 2 with the time object (time_o). struct datestuff is defined alongside it. From there, in layer 4 is stime_o, which adds string formatting to (time_o) - you may default to using stime since it can readily print out the time as a string.

The timespan object (timespan_o, layer 3) allows you to define a span of time. With this class, you can get new times [/and dates] as if writing algebraic equations:

    stime_o t0 ("Jan 17, 1991"), t1 ("09/11/2001"), t2;
    timespan_o ts ("1 week");
    t2 = t1 + ts;          // add 1 week to 09/11/2001
    ts = t1 - t0;          // get the elapsed time from t0 to t1

classes in this group: time_o, stime_o, timespan_o, timeperiod_o

function groups: layer 00 functions group
                              layer 02 functions group
                              layer 04 functions group

description.
An integral, useful part of software and computer science is time. Various organizations measure time in different ways:

unix time: measured in seconds elapsed since January 1, 1970
julian dates are measured in number of days elapsed

The mathematics of time is an approximate science, because the units humans use are not only inexact, but they change:

• the number of seconds in a year depends on whether it's a leap year;
• the duration of a year can vary [infinatesimally?], say if the Earth's rotation slows down;
• The number of days in a month clearly varies between 28 and 31;
• sometimes the calendar is semi-arbitrarily changed for political reasons: the day after Sep 2, 1752 is Sep 14, 1752

In order to make time work the way you want it, rather than storing time in terms of "units of <xxx>", where xxx could be microseconds, seconds, days, or whatever, the Z Directory uses the structure "datestuff" that can hold any component of time from microsecond to century. "Time" in the Z Directory context includes dates. The term "date" refers to a sub-component of time, namely, days. So (outside of 'struct datestuff' and the date-format object) the word "date" is rarely found here, and nd distinction is made between time-of-day and a date.

Note that if we maintain a length of time as a number of days or seconds, we cannot use the concept of time in the traditional human measurements. For example, if we mean "2 months", how many days is that? 60? 62? 60.83? We won't be able to provide precision time/dates that way, which would render accounting software useless, as accountants want do monthly amortizations exactly at the end of each month.

note.
layer 2 has a single function - z_approx_elapsed_numsec(). This function takes to time objects and returns the number of seconds between them. This function mimicks the functionality of the timespan object. It was created because certain elements in layers under the timespan object needed to know elapsed time. According to Z Directory rules, a layer-n item cannot access a layer n+1 item, hence it exists.

warnings.
Not all OS's support microsecond precision.

limitations.
time zone management is [currently] weak.