Skip to content

Latest commit

 

History

History
102 lines (72 loc) · 3.45 KB

timezones.rdoc

File metadata and controls

102 lines (72 loc) · 3.45 KB
Raw

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 ↑

The zone value may be an object responding to certain timezone methods.

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 Marshal.dump(t) is invoked

    • Argument: none.

    • Returns: the string name of the timezone.