Ruby/TZFile

Timezone dependent time library using tzfile.

Usage example

TZFile.create generate a class which is similar to the Time class.

TokyoTime = TZFile.create("Asia/Tokyo")
p TokyoTime.now
p TokyoTime.local(2001,4,19)
p TokyoTime.utc(2000,3,20)

Portability

Since this library uses tzfile format, it doesn't work on platforms which doesn't provide timezone information by tzfile format. The format is primarily supported by tzcode/tzdata package <URL:ftp://elsie.nci.nih.gov/pub/> and the Theory file in tzcode says:

This package is already part of many POSIX-compliant hosts,
including BSD, HP, Linux, Network Appliance, SCO, SGI, and Sun.

Limitation

Since 32bit signed integer is used to specify a number of seconds from the Epoch (1970/01/01 00:00:00 UTC) in the format, tzfile can provide timezone information only between December 1901 and January 2038. Thanks to Ruby's Bignum and object oriented polymorphism, this library doesn't cause overflow exception even if a time is out of the range. This library uses first timezone information for before 1901 and last timezone information for after 2038. But this means results may incorrect. For example, if January 2038 is in DST (daylight saving time) - remember that January is summer in the south half of the globe -, DST is applied forever after 2038. So, don't use this library under such condition.

TZFile module

module methods:

TZFile.create(path)

Creates a timezone class by timezone file specified by "path". If "path" is relative, it is interpreted as a relative path from platform dependent timezone directory.

The generated class behaves like Time class.

TZFile.zoneinfo_directory: Returns platform dependent zoneinfo directory such as "/usr/share/zoneinfo".

TZFile.each([directory]) {|name, tzfile| ...}: Evaluate the block for each timezone file under "directory". If the directory is not specified, platform dependent directory such as /usr/share/zoneinfo is used. "name" is a relative path from the directory and "tzfile" is a timezone object.

methods:

Following methods can be used as class methods of a class generated by TZFile.create because TZFile extends the class.

at(time)

utc(year[, mon[, mday[, hour[, min[, sec]]]]])
utc(sec, min, hour, mday, mon, year, wday, yday, isdst, zone)
gm(year[, mon[, mday[, hour[, min[, sec]]]]])
gm(sec, min, hour, mday, mon, year, wday, yday, isdst, zone): These methods interpret given broken-down time as UTC and instantiate an object. Since the internal representation is a number of seconds from the Epoch and leapseconds information is supplied by tzfile, internal representation may be different for each different tzfile even with same broken-down time.

local(year[, mon[, mday[, hour[, min[, sec]]]]])
local(sec, min, hour, mday, mon, year, wday, yday, isdst, zone)
mktime(year[, mon[, mday[, hour[, min[, sec]]]]])
mktime(sec, min, hour, mday, mon, year, wday, yday, isdst, zone): These methods interpret given broken-down time as localtime defined by tzfile and instantiate an object.

now: Creates a new object corresponding to a current time. The current time is taken from Time.now.gmtime.to_a.

each_range {|time1, timetype, time2| ...}

Evaluate the block for each time range. "time1" is a beginning of the time range. "time2" is a beginning of the next time range. "timetype" is a time type applied between "time1" and "time2".

For first time range, time1 is true. For last time range, time2 is false.

each_transition {|timetype1, time, timetype2| ...}: Evaluate the block for each trantision time. "timetype1" is a time type before "time" exclusive. "timetype2" is a time type after "time" inclusive.

each_closed_range {|time1, timetype, time2| ...}: Like each_range but first and last time range is not yielded. So "time1" and "time2" is always TZTime::Time.

each_timetype {|timetype| ...}: Evaluate the block for each time type.

count_leapseconds(time[, direction])

uncount_leapseconds(time)

Convert an integer "time" to an array which has three elements: [t, s, d]. "t" corresponds to "time" but leapseconds are not counted. "s" specifies the type of the previous leapsecond: -1, 1, 0 for deletion, insertion, not exists. "d" is a number of seconds from the previous leapsecond. If the previous leapsecond is not exists, "d" is -1.

If "time" points an inserted leapsecond, "t" corresponds to "time-1", "s" is 1 and "d" is 0.

If "time" is just after a deleted leapsecond, "d" is 1.