timezones - Documentation for Ruby 3.2

## 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.