Eigenstate : libdate

Libdate is a date API designed to cover most use cases well. It will format, parse, and do basic manipulations on dates.

API Reference

    pkg date =
            /* useful constants */
            const Datetimefmt   = "%Y-%m-%d %H:%M:%S %z"
            const Timefmt   = "%h:%m:%s %z"
            const Datefmt   = "%Y-%m-%d %z"

            /* date creation */
            const utcnow    : (-> instant)
            const now   : (tz : byte[:] -> instant)
            const tozone    : (d : instant, zone : byte[:]  -> instant)
            const mkdate    : (tm : std.time, zone : byte[:]    -> instant)
            const localoff  : (tm : std.time -> delta)
            const tzoff : (tzname : byte[:], tm : std.time  -> delta)
            const isleap    : (d : instant  -> bool)

            /* date manipulation */
            const add   : (d : instant, dt : delta  -> instant)
            const sub   : (d : instant, dt : delta  -> instant)
            const delta : (a : instant, b : instant -> delta)

            const fmt   : (f : byte[:], d : instant -> byte[:])
            const bfmt  : (buf : byte[:], f : byte[:], d : instant  -> std.size)

            /* date parsing */
            const parsefmt  : (f : byte[:], s: byte[:]  -> std.option(instant))
            const parsefmtz : (f : byte[:], s: byte[:], tz : byte[:]    -> std.option(instant))

Core Concepts


An instant is a point in time. Immovable, unchanging for eternity, it is anchored in one spot through the microseconds of unix time in the UTC time zone. For the consumption of the puny mortals, it is broken up into a local representation, consisting of years, months, days, weekdays, hours, minutes, seconds, and microseconds, with a timezone attached.


A delta is a difference between two instants. Fixed in duration, it is a vagrant which may add or subtract its value from any two instants. It, however, is a stable, well behaved creature, also anchored to the fabric of reality through microseconds of unix time. It has no timezone which it can call home.


A period is another form of differece between two instants. However, a period is a flighty creature, which does not anchor itself to the world of men in any strong way. A year may be 365 or 366 days, according to the whims and vagaries of the local calendar. An hour added to a time may jump ahead by two hours, if it so desires to follow the savings of daylight. These creatures attempt to mold themselves to the irrationalities of man's mind, and eschew the divine ordering of absolute time handed down by the prophets.


A timezone is a named zone, as decreed by the mighty IANA timezone database. It may take the form of a location such as "America/New_York", a well-known abbreviation like "EST", or a special value such as "local" or "", which mean, respectively, the current zone or UTC.


The constants Datetimefmt, Timefmt, and Datefmt are there to, respectively, provide reasonable formats for datetime, time, and date.


utcnow provides the current instant in the UTC timezone. It can not fail.

now provides the current instant in the timezone requested. Passing "local" will use the system's configured time, or UTC if that is not set. Passing "" will use UTC.

tozone converts an instant in one timezone to an instant in another time zone.

mkinstant creates an instant in time, based on the unix timestamp in microseconds provided to the function. The timezones passed follow the usual rules outlined before.

localoff returns the timezone offset of the local timezone.

tzoff returns the timezone offset of the requested timezone.

isleap returns true if the current year is a leap year, false otherwise.