TZInfo - Ruby Time Zone Library

TZInfo is a Ruby library that provides access to
time zone data and allows times to be converted using time zone rules.

Data Sources

TZInfo requires a source of time zone data. There are two options:

A zoneinfo directory containing timezone definition files. These files are
generated from the IANA Time Zone Database
using the zic utility. Most Unix-like systems include a zoneinfo directory.

The TZInfo::Data library (the tzinfo-data gem). TZInfo::Data contains a set
of Ruby modules that are also generated from the IANA Time Zone Database.

By default, TZInfo will attempt to use TZInfo::Data. If TZInfo::Data is not
available (i.e. if require 'tzinfo/data' fails), then TZInfo will search for a
zoneinfo directory instead (using the search path specified by
TZInfo::ZoneinfoDataSource::DEFAULT_SEARCH_PATH).

If no data source can be found, a TZInfo::DataSourceNotFound exception will be
raised when TZInfo is used. Further information is available
in the wiki to help resolve
TZInfo::DataSourceNotFound errors.

The default data source selection can be overridden by calling
TZInfo::DataSource.set.

Custom data sources can also be used. See the TZInfo::DataSource.set
documentation for further details.

Installation

The TZInfo gem can be installed by running gem install tzinfo or by adding
to gem 'tzinfo' to your Gemfile and running bundle install.

To use the Ruby modules as the data source, TZInfo::Data will also need to be
installed by running gem install tzinfo-data or by adding gem 'tzinfo-data'
to your Gemfile.

All TZInfo::Timezone methods that accept a time as a parameter can be used
with either instances of Time, DateTime or TZInfo::Timestamp. Arbitrary
Time-like objects that respond to both to_i and subsec and optionally
utc_offset will be treated as if they are instances of Time.

TZInfo::Timezone methods that both accept and return times will return an
object with a type matching that of the parameter (actually a
TZInfo::TimeWithOffset, TZInfo::DateTimeWithOffset or
TZInfo::TimestampWithOffset subclass when returning a local time):

In addition to local_time, which returns Time instances, the
local_datetime and local_timestamp methods can be used to construct local
DateTime and TZInfo::Timestamp instances with the appropriate offset:

The local_to_utc, local_time, local_datetime and local_timestamp methods
may raise a TZInfo::PeriodNotFound or a TZInfo::AmbiguousTime exception.
TZInfo::PeriodNotFound signals that there is no equivalent UTC time (for
example, during the transition from standard time to daylight savings time when
the clocks are moved forward and an hour is skipped). TZInfo::AmbiguousTime
signals that there is more than one equivalent UTC time (for example, during the
transition from daylight savings time to standard time where the clocks are
moved back and an hour is repeated):

tz.local_time(2018,3,11,2,30,0,0)# raises TZInfo::PeriodNotFound (2018-03-11 02:30:00 is an invalid local time.)
tz.local_time(2018,11,4,1,30,0,0)# raises TZInfo::AmbiguousTime (2018-11-04 01:30:00 is an ambiguous local time.)

TZInfo::PeriodNotFound exceptions can only be resolved by adjusting the time,
for example, by advancing an hour:

tz.local_time(2018,3,11,3,30,0,0)# => 2018-03-11 03:30:00 -0400

TZInfo::AmbiguousTime exceptions can be resolved by setting the dst
parameter and/or specifying a block to choose one of the interpretations:

For further detail, please refer to the API documentation for the
TZInfo::Timezone and TZInfo::Country classes.

Time Zone Selection

The Time Zone Database maintainers recommend that time zone identifiers are not
made visible to end-users (see Names of
timezones).

Instead of displaying a list of time zone identifiers, time zones can be
selected by the user's country. Call TZInfo::Country.all to obtain a list of
TZInfo::Country objects, each with a unique code and a name that can be
used for display purposes.

Most countries have a single time zone. When choosing such a country, the time
zone can be inferred and selected automatically.

Please note that country information available through TZInfo is intended as an
aid to help users select a time zone data appropriate for their practical needs.
It is not intended to take or endorse any position on legal or territorial
claims.

Compatibility

Thread-Safety

The TZInfo::Country and TZInfo::Timezone classes are thread-safe. It is safe
to use class and instance methods of TZInfo::Country and TZInfo::Timezone in
concurrently executing threads. Instances of both classes can be shared across
thread boundaries.