ruby/doc/timezone_specifiers.rdoc

=== Timezone Specifiers

Certain methods in class Time 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:

- 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

- 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

- 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

--
TODO:  Pull in and revise the text at the link,
then add the example class TZ from the tests.
++
- A timezone object;
  see {Timezone Argument}[rdoc-ref:Time@Timezone+Argument] for details.