Timezones

Timezone Specifiers

Certain Time methods accept arguments that specify timezones:

• Time.at: keyword argument in:.

• Time.new: positional argument zone or keyword argument in:.

• Time.now: keyword argument in:.

• Time#getlocal: positional argument zone.

• Time#localtime: positional argument zone.

The value given with any of these must be one of the following (each detailed below):

• Hours/minutes offset.

• Single-letter offset.

• Integer offset.

• Timezone object.

Hours/Minutes Offsets

The zone value may be a string offset from UTC in the form '+HH:MM' or '-HH:MM', where:

• HH is the 2-digit hour in the range 0..23.

• MM is the 2-digit minute in the range 0..59.

Examples:

t = Time.utc(2000, 1, 1, 20, 15, 1) # => 2000-01-01 20:15:01 UTC
Time.at(t, in: '-23:59')            # => 1999-12-31 20:16:01 -2359
Time.at(t, in: '+23:59')            # => 2000-01-02 20:14:01 +2359

Single-Letter Offsets

The zone value may be a letter in the range 'A'..'I' or 'K'..'Z'; see List of military time zones:

t = Time.utc(2000, 1, 1, 20, 15, 1) # => 2000-01-01 20:15:01 UTC
Time.at(t, in: 'A')                 # => 2000-01-01 21:15:01 +0100
Time.at(t, in: 'I')                 # => 2000-01-02 05:15:01 +0900
Time.at(t, in: 'K')                 # => 2000-01-02 06:15:01 +1000
Time.at(t, in: 'Y')                 # => 2000-01-01 08:15:01 -1200
Time.at(t, in: 'Z')                 # => 2000-01-01 20:15:01 UTC

Integer Offsets

The zone value may be an integer number of seconds in the range -86399..86399:

t = Time.utc(2000, 1, 1, 20, 15, 1) # => 2000-01-01 20:15:01 UTC
Time.at(t, in: -86399)              # => 1999-12-31 20:15:02 -235959
Time.at(t, in: 86399)               # => 2000-01-02 20:15:00 +235959

Timezone Objects

In most cases, the zone value may be an object responding to certain timezone methods.

Exceptions (timezone object not allowed):

• Time.new with positional argument zone.

• Time.now with keyword argument in:.

The timezone methods are:

• local_to_utc:

  • Called when Time.new is invoked with tz as the value of positional argument zone or keyword argument in:.

  • Argument: a Time::tm object.

  • Returns: a Time-like object in the UTC timezone.

• utc_to_local:

  • Called when Time.at or Time.now is invoked with tz as the value for keyword argument in:, and when Time#getlocal or Time#localtime is called with tz as the value for positional argument zone.

  • Argument: a Time::tm object.

  • Returns: a Time-like object in the local timezone.

A custom timezone class may have these instance methods, which will be called if defined:

• abbr:

  • Called when Time#strftime is invoked with a format involving %Z.

  • Argument: a Time::tm object.

  • Returns: a string abbreviation for the timezone name.

• dst?:

  • Called when Time.at or Time.now is invoked with tz as the value for keyword argument in:, and when Time#getlocal or Time#localtime is called with tz as the value for positional argument zone.

  • Argument: a Time::tm object.

  • Returns: whether the time is daylight saving time.

• name:

  • Called when <tt>Marshal.dump(t) is invoked

  • Argument: none.

  • Returns: the string name of the timezone.