daurnimator/luatz

Time, Date and Timezone library for lua

luatz

A lua library for time and date manipulation.

Features include:

• Normalisation of broken down date objects
  • allows for complex time/date manipulation logic e.g. "What day is it in 2 days, 5 hours from now?"
• Conversion between locations (time zones) using your local zoneinfo database.
• strftime style formatting

Supported under Lua 5.1, 5.2, 5.3 and LuaJIT.

Documentation

Documentation can be found in the doc sub-directory.

An online version can be found at https://daurnimator.github.io/luatz/

Installation

via luarocks

luarocks install luatz

luatz's Issues

Support tzfile version 3

Thanks to @apaprocki for mentioning at https://news.ycombinator.com/item?id=8160314

Looks like not much has changed. From https://github.com/eggert/tz/blob/198708147f6b1fd81d76e501ef1f91b8e0bba6ea/tzfile.5#L143 :

For version-3-format time zone files, the POSIX-TZ-style string may use two minor extensions to the POSIX TZ format, as described in newtzset (3).
First, the hours part of its transition times may be signed and range from -167 through 167 instead of the POSIX-required unsigned values from 0 through 24.
Second, DST is in effect all year if it starts January 1 at 00:00 and ends December 31 at 24:00 plus the difference between daylight saving and standard time.

luatz doesn't even use the TZ string, so looks like we don't actually need to change anything.

All we have to do is accept version 3 files.

Issue with strftime

Not sure why this isn't working:

luatz.strftime.strftime("%a, %d %b %Y %H:%M:%S %Z", luatz.parse.rfc_3339("2016-10-03T07:06:31.567Z"))
/usr/local/share/lua/5.1/luatz/strftime.lua:194: bad argument #2 to 'strformat' (string expected, got nil)
stack traceback:
    [C]: in function 'strformat'
    /usr/local/share/lua/5.1/luatz/strftime.lua:194: in function </usr/local/share/lua/5.1/luatz/strftime.lua:191>
    [C]: in function 'gsub'
    /usr/local/share/lua/5.1/luatz/strftime.lua:191: in function 'strftime'
    stdin:1: in main chunk
    [C]: ?

Support locales in luatz/strftime

Certain strftime specifiers are dependant on locale specific strings:

• %a
• %A
• %b
• %B
• %c
• %p
• %r
• %x
• %X

You should be able to pass in your desired locale, and/or set the default.

Possible optimisation for normalise(...) function in timetable.lua

There is this main function that calculates year, month and day. For large days it produces large amount of iterations. You can speed it up, by calculating offset for #sec and #year.

Define new function:

function year_offset(ts)
    local year, offset
    if ts >= 1735689600 then
        year, offset = 2025, 1735689600 -- 1.1.2015

    elseif ts >= 1577836800 then
        year, offset = 2020, 1577836800 -- 1.1.2020

    elseif ts >= 1420070400 then
        year, offset = 2015, 1420070400 -- 1.1.2015

    elseif ts >= 1262304000 then
        year, offset = 2010, 1262304000 -- 1.1.2010

    elseif ts >= 946684800 then
        year, offset = 2000, 946684800 -- 1.1.2000

    elseif ts >= 631152000 then
        year, offset = 1990, 631152000 -- 1.1.1990

    elseif ts >= 315532800 then
        year, offset = 1980, 315532800 -- 1.1.1980

    else
        year, offset = 1970, 0
    end
    return year, offset
end

and call it here:

local function normalise ( year , month , day , hour , min , sec )
    year, offset = year_offset(sec)
    sec = sec - offset
    .....

In this case we are shifting #sec to know pre-calculated year and instead of starting on 1970 we start on closest year to given #sec

Time arithmetic problem

luatz = require "luatz"
x = luatz.parse.rfc_3339("2017-02-13T00:00:00.000")
x.min = x.min - 14400
x:normalise()
print(x)
2017-02-22T23:60:00.000

Incorrect RFC 3339

It's possible for the seconds in an RFC 339 timestamp to be 60.

local luatz = require "luatz"
local ts = luatz.time()
luatz.gmtime(ts):rfc_3339()

I somehow managed to get '2014-10-20T17:11:60.000'

Incompatibilities with ljsyscall

While ljsyscall provides this:
https://github.com/justincormack/ljsyscall/blob/master/syscall/rump/c.lua#L422

This line will error on it:
https://github.com/daurnimator/luatz/blob/master/luatz/gettime.lua#L7

gettime.lua:7: attempt to index field 'CLOCK' (a nil value)

all_timezones and common_timezones like in pytz

pytz has helpers for all_timezones and common_timezones:
http://pytz.sourceforge.net/#helpers

Would be nice to have this in luatz as well.

API usage docs

:)

Windows support?

Hey,

Does this work on Windows systems?

I tried to install it using luarocks install luatz an it actually did, but I can't find it anywhere.

POSIX-TZ and last transition time

I tried the following code fragment:

local luatz = require("luatz")

local sydney_ts = luatz.time_in("Australia/Sydney")
sydney = luatz.timetable.new_from_timestamp(sydney_ts)

print(sydney)
print(os.date("!%c", sydney_ts))
os.execute("env TZ=Australia/Sydney date")

and the output:

2023-03-15T15:58:08.000
Wed Mar 15 15:58:08 2023
Wed Mar 15 16:58:08 AEDT 2023

differs by an hour. Looking through the code, it seems like the TZ entry is not used "in handling instants after the last transition time stored in the file" as per the documentation for the Version 2 tzfile format:

Linux tzfile.5
NetBSD tzfile.5

I am not sure that I have read everything correctly though.

Convertion problems using more than 1GB in Luajit GC64 Mode

Hi,

There are major problems in converting dates through the LUATZ module when RAM usage exceeds 1GB using the Luajit GC64 mode.
Example: Time zone conversion resulting in dates with years added to 100.
To test it is enough to perform, for example, a loading of a large csv file containing dates and try a time zone convertion.

tzfile.lua:199 got Unsupported version error for Asia/Jerusalem

> luatz.get_tz('Asia/Jerusalem')
/usr/local/share/lua/5.1/luatz/tzfile.lua:199: Unsupported version
stack traceback:
    [C]: in function 'error'
    /usr/local/share/lua/5.1/luatz/tzfile.lua:199: in function 'read_tz'
    /usr/local/share/lua/5.1/luatz/tzfile.lua:205: in function 'read_tzfile'
    /usr/local/share/lua/5.1/luatz/tzcache.lua:24: in function 'get_tz'
    stdin:1: in main chunk
    [C]: ?
> 

Please help

thanks

Not normalizing correctly when tt.day<=0

Lua timetable {year=2017, month=12, day=0} means 2017-11-30
But luatz timetable will normalize to 2017-12-01

The same problem when day<=0.

gmtime documentation improvement

Documentation states that gmtime is As in the C standard library, but it is actually different in at least one aspect: in c it is int tm_wday; /* day of the week, range 0 - sunday to 6 - saturday */, in luatz it is within 1 - sunday to 7 - saturday, it is clearly doing +1 in the code.

I think it is a good idea to mention the difference in the documentation, as fixing it will introduce a breaking change.

Errorless "safe" version

There are some error calls. Would it make any sense to have Lua style return nil, "error reason" type API as well or some options?