ruby--ruby/doc/timezones.rdoc

== 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}[rdoc-ref:timezones.rdoc@Hours-2FMinutes+Offsets].
- {Single-letter offset}[rdoc-ref:timezones.rdoc@Single-Letter+Offsets].
- {Integer offset}[rdoc-ref:timezones.rdoc@Integer+Offsets].
- {Timezone object}[rdoc-ref:timezones.rdoc@Timezone+Objects].

==== Hours/Minutes Offsets

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

- +HH+ is the 2-digit hour in the range <tt>0..23</tt>.
- +MM+ is the 2-digit minute in the range <tt>0..59</tt>.

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 <tt>'A'..'I'</tt>
or <tt>'K'..'Z'</tt>;
see {List of military time zones}[https://en.wikipedia.org/wiki/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 <tt>-86399..86399</tt>:

  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 <tt>Time::tm</tt> 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 <tt>Time::tm</tt> 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 <tt>%Z</tt>.
  - Argument: a <tt>Time::tm</tt> 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 <tt>Time::tm</tt> 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.