luatz

A lua library for time and date manipulation

Daurnimator quae@daurnimator.com

luatz

Requiring the base luatz module will give you a table of commonly used functions and submodules.

The table includes the following sub modules, which have their own documentation:

time()

Returns the current unix timestamp using the most precise source available. See gettime for more information.

now()

Returns the current time as a timetable object See timetable for more information

get_tz([timezone_name])

Returns a timezone object (see tzinfo documentation) for the given timezone_name. If timezone_name is nil then the local timezone is used. If timezone_name is an absolute path, then that tzinfo file is used

This uses the local zoneinfo database; names are usually of the form Country/Largest_City e.g. “America/New_York”. Check wikipedia for an example list.

time_in(timezone_name[, utc_ts])

Returns the current time in seconds since 1970-01-01 0:00:00 in the given timezone as a string, (same semantics as get_tz) at the given UTC time (defaults to now).

gmtime(ts)

As in the C standard library

localtime(ts)

As in the C standard library

ctime(ts)

As in the C standard library

luatz.gettime

A module to get the current time.

Uses the most precise method available (in order:)

source

The library/function currently in use by gettime().

resolution

The smallest time resolution (in seconds) available from gettime().

gettime()

Returns the number of seconds since unix epoch (1970-01-01T00:00:00Z) as a lua number

luatz.parse

Provides parsers for common time and date formats.

Functions take the source string and an optional initial postition.

rfc_3339(string[, init])

If the string is a valid RFC-3339 timestamp, returns a luatz timetable and the (optional) time zone offset in seconds.

Otherwise returns nil and an error message

luatz.timetable

Provides an class to represent a time and date. Objects have no concept of timezone or utc offset.

The fields are intentionally compatible with the lua standard library’s os.date and os.time. Objects have fields:

timetable components may be outside of their standard range (e.g. a month component of 14) to facilitate arithmetic operations on date components. :normalise() can be called to modify components to return to their standard range.

Equality and comparisons should work between timetable objects.

new(year, month, day, hour, min, sec[, yday[, [wday]])

Returns a new timetable with the given contents.

new_from_timestamp(timestamp)

Returns a new (normalised) timetable, given a timestamp in seconds since the unix epoch of 1970-01-01.

timetable:clone()

Returns a new independent instance of an existing timetable object.

timetable:normalise()

Mutates the current object’s time and date components so that are integers within ‘normal’ ranges e.g. month is 1-12; min is 0-59

First, fractional parts are propagated down.
e.g. .month=6.5 .day=1 (which could be read as “the first day after the middle of June”) normalises to .month=2 .day=16

Second, any fields outside of their normal ranges are propagated up
e.g. .hour=10 .min=100 (100 minutes past 10am) normalises to .hour=11 .min=40

timetable:rfc_3339()

Returns the timetable formatted as an rfc-3339 style string. The timezone offset (or Z) is not appended. The ranges of components are not checked, if you want a valid timestamp, :normalise() should be called first.

This function is also the __tostring metamethod for timetable objects

timetable:timestamp()

Returns the timetable as the number of seconds since unix epoch (1970-01-01) as a lua number.

timetable:unpack()

Unpacks the timetable object; returns year, month, day, hour, min, sec, yday, wday

luatz.tzinfo

Provides a metatable for the timezone class.

Created in luatz.tzfile and managed by luatz.tzcache; a timezone object contains information about a timezone. These objects are based on the information available in a “zoneinfo” file.

Timezone objects should be considered opaque and immutable; so the following details can be skipped over.

The table contains a sequence of tables that describe the timezone at a given point using a transition_time: the unix timestamp (in UTC) that this definition starts, and a tt_info object.

A tt_info object contains information about a time offset; and contains the following fields:

tzinfo:find_current(utc_ts)

Returns the relevant tt_info object for the given UTC timestamp in the timezone.

tzinfo:localise(utc_ts) and tzinfo:localize(utc_ts)

Convert the given UTC timestamp to the timezone. Returns the number of seconds since unix epoch in the given timezone.

tzinfo:utctime(local_ts)

Convert the given local timestamp (seconds since unix epoch in the time zone) to a UTC timestamp. This may result in ambigous results, in which case multiple values are returned.

e.g. consider that when daylight savings rewinds your local clock from 3am to 2am there will be two 2:30ams.