Data

Tools

Indexes

Applications

Experiments

Ruby

A summary of data about the Ruby ecosystem.

https://github.com/tzinfo/tzinfo

TZInfo - Ruby Timezone Library
https://github.com/tzinfo/tzinfo

Keywords from Contributors

activejob activerecord mvc rubygems rubocop ruby-gem rspec static-code-analysis rack repl

Last synced: about 4 hours ago
JSON representation

Repository metadata

TZInfo - Ruby Timezone Library

README.md

TZInfo - Ruby Time Zone Library

RubyGems Tests

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:

  1. A zoneinfo directory containing time zone definition files. These files are
    generated from the IANA Time Zone Database
    using the zic utility. Most Unix-like systems include a zoneinfo directory,
    typically contained within a package named tzdata. Note that some
    distributions split legacy time zone definition files into a separate
    tzdata-legacy package.
  2. 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 (by checking the directories specified by
TZInfo::DataSources::ZoneinfoDataSource.search_path in turn).

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

IANA Time Zone Database

The data returned and used by TZInfo is sourced from the
IANA Time Zone Database. The
Theory and pragmatics of the tz code and data
document gives details of how the data is organized and managed.

Example Usage

To use TZInfo, it must first be required with:

require 'tzinfo'

The TZInfo::Timezone class provides access to time zone data and methods for
converting times.

The all_identifiers method returns a list of valid time zone identifiers:

identifiers = TZInfo::Timezone.all_identifiers
# => ["Africa/Abidjan", "Africa/Accra", ..., "Zulu"]

A TZInfo::Timezone instance representing an individual time zone can be
obtained with TZInfo::Timezone.get:

tz = TZInfo::Timezone.get('America/New_York')
# => #<TZInfo::DataTimezone: America/New_York>

A time can be converted to the local time of the time zone with to_local:

tz.to_local(Time.utc(2018, 2, 1, 12, 30, 0))
# => 2018-02-01 07:30:00 -0500
tz.to_local(Time.utc(2018, 7, 1, 12, 30, 0))
# => 2018-07-01 08:30:00 -0400
tz.to_local(Time.new(2018, 7, 1, 13, 30, 0, '+01:00'))
# => 2018-07-01 08:30:00 -0400

Local times with the appropriate offset for the time zone can be constructed
with local_time:

tz.local_time(2018, 2, 1, 7, 30, 0)
# => 2018-02-01 07:30:00 -0500
tz.local_time(2018, 7, 1, 8, 30, 0)
# => 2018-07-01 08:30:00 -0400

Local times can be converted to UTC by using local_time and calling utc on
the result:

tz.local_time(2018, 2, 1, 7, 30, 0).utc
# => 2018-02-01 12:30:00 UTC
tz.local_time(2018, 7, 1, 8, 30, 0).utc
# => 2018-07-01 12:30:00 UTC

The local_to_utc method can also be used to convert a time object to UTC. The
offset of the time is ignored - it is treated as if it were a local time for the
time zone:

tz.local_to_utc(Time.utc(2018, 2, 1, 7, 30, 0))
# => 2018-02-01 12:30:00 UTC
tz.local_to_utc(Time.new(2018, 2, 1, 7, 30, 0, '+01:00'))
# => 2018-02-01 12:30:00 UTC

Information about the time zone can be obtained from returned local times:

local_time = tz.to_local(Time.utc(2018, 2, 1, 12, 30, 0))
local_time.utc_offset  # => -18000
local_time.dst?        # => false
local_time.zone        # => "EST"

local_time = tz.to_local(Time.utc(2018, 7, 1, 12, 30, 0))
local_time.utc_offset  # => -14400
local_time.dst?        # => true
local_time.zone        # => "EDT"

Time zone information can be included when formatting times with strftime
using the %z and %Z directives:

tz.to_local(Time.utc(2018, 2, 1, 12, 30, 0)).strftime('%Y-%m-%d %H:%M:%S %z %Z')
# => "2018-02-01 07:30:00 -0500 EST"
tz.to_local(Time.utc(2018, 7, 1, 12, 30, 0)).strftime('%Y-%m-%d %H:%M:%S %z %Z')
# => "2018-07-01 08:30:00 -0400 EDT"

The period_for method can be used to obtain information about the observed
time zone information at a particular time as a TZInfo::TimezonePeriod object:

period = tz.period_for(Time.utc(2018, 7, 1, 12, 30, 0))
period.base_utc_offset          # => -18000
period.std_offset               # => 3600
period.observed_utc_offset      # => -14400
period.abbreviation             # => "EDT"
period.dst?                     # => true
period.local_starts_at.to_time  # => 2018-03-11 03:00:00 -0400
period.local_ends_at.to_time    # => 2018-11-04 02:00:00 -0400

A list of transitions between periods where different rules are observed can be
obtained with the transitions_up_to method. The result is returned as an
Array of TZInfo::TimezoneTransition objects:

transitions = tz.transitions_up_to(Time.utc(2019, 1, 1), Time.utc(2017, 1, 1))
transitions.map do |t|
  [t.local_end_at.to_time, t.offset.observed_utc_offset, t.offset.abbreviation]
end
# => [[2017-03-12 02:00:00 -0500, -14400, "EDT"],
#     [2017-11-05 02:00:00 -0400, -18000, "EST"],
#     [2018-03-11 02:00:00 -0500, -14400, "EDT"],
#     [2018-11-04 02:00:00 -0400, -18000, "EST"]]

A list of the unique offsets used by a time zone can be obtained with the
offsets_up_to method. The result is returned as an Array of
TZInfo::TimezoneOffset objects:

offsets = tz.offsets_up_to(Time.utc(2019, 1, 1))
offsets.map {|o| [o.observed_utc_offset, o.abbreviation] }
# => [[-17762, "LMT"],
#     [-18000, "EST"],
#     [-14400, "EDT"],
#     [-14400, "EWT"],
#     [-14400, "EPT"]]

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):

tz.to_local(Time.utc(2018, 7, 1, 12, 30, 0))
# => 2018-07-01 08:30:00 -0400
tz.to_local(DateTime.new(2018, 7, 1, 12, 30, 0))
# => #<TZInfo::DateTimeWithOffset: 2018-07-01T08:30:00-04:00 ((2458301j,45000s,0n),-14400s,2299161j)>
tz.to_local(TZInfo::Timestamp.create(2018, 7, 1, 12, 30, 0, 0, :utc))
# => #<TZInfo::TimestampWithOffset: @value=1530448200, @sub_second=0, @utc_offset=-14400, @utc=false>

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:

tz.local_time(2018, 2, 1, 7, 30, 0)
# => 2018-02-01 07:30:00 -0500
tz.local_datetime(2018, 2, 1, 7, 30, 0)
# => #<TZInfo::DateTimeWithOffset: 2018-02-01T07:30:00-05:00 ((2458151j,45000s,0n),-18000s,2299161j)>
tz.local_timestamp(2018, 2, 1, 7, 30, 0)
# => #<TZInfo::TimestampWithOffset: @value=1517488200, @sub_second=0, @utc_offset=-18000, @utc=false>

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:

tz.local_time(2018, 11, 4, 1, 30, 0, 0, true)
# => 2018-11-04 01:30:00 -0400
tz.local_time(2018, 11, 4, 1, 30, 0, 0, false)
# => 2018-11-04 01:30:00 -0500

tz.local_time(2018, 11, 4, 1, 30, 0, 0) {|p| p.first }
# => 2018-11-04 01:30:00 -0400
tz.local_time(2018, 11, 4, 1, 30, 0, 0) {|p| p.last }
# => 2018-11-04 01:30:00 -0500

The default value of the dst parameter can also be set globally:

TZInfo::Timezone.default_dst = true
tz.local_time(2018, 11, 4, 1, 30, 0, 0)
# => 2018-11-04 01:30:00 -0400
TZInfo::Timezone.default_dst = false
tz.local_time(2018, 11, 4, 1, 30, 0, 0)
# => 2018-11-04 01:30:00 -0500

TZInfo also provides information about
ISO 3166-1 countries and
their associated time zones via the TZInfo::Country class.

A list of valid ISO 3166-1 (alpha-2) country codes can be obtained by calling
TZInfo::Country.all_codes:

TZInfo::Country.all_codes
# => ["AD", "AE", ..., "ZW"]

A TZInfo::Country instance representing an individual time zone can be
obtained with TZInfo::Country.get:

c = TZInfo::Country.get('US')
# => #<TZInfo::Country: US>
c.name
# => "United States"

The zone_identifiers method returns a list of the time zone identifiers used
in a country:

c.zone_identifiers
# => ["America/New_York", "America/Detroit", ..., "Pacific/Honolulu"]

The zone_info method returns further information about the time zones used in
a country as an Array of TZInfo::CountryTimezone instances:

zi = c.zone_info.first
zi.identifier               # => "America/New_York"
zi.latitude.to_f.round(5)   # => 40.71417
zi.longitude.to_f.round(5)  # => -74.00639
zi.description              # => "Eastern (most areas)"

The zones method returns an Array of TZInfo::Timezone instances for a
country. A TZInfo::Timezone instance can be obtained from a
TZInfo::CountryTimezone using the timezone method:

zi.timezone.to_local(Time.utc(2018, 2, 1, 12, 30, 0))
# => 2018-02-01 07:30:00 -0500

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 Timezone
identifiers).

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.

croatia = TZInfo::Country.get('HR')
# => #<TZInfo::Country: HR>
croatia.zone_info.length
# => 1
croatia.zone_info[0].identifier
# => "Europe/Belgrade"

Some countries have multiple time zones. The zone_info method can be used
to obtain a list of user-friendly descriptions of the available options:

australia = TZInfo::Country.get('AU')
# => #<TZInfo::Country: AU>
australia.zone_info.length
# => 13
australia.zone_info.map {|i| [i.identifier, i.description] }
# => [["Australia/Lord_Howe", "Lord Howe Island"],
#     ["Antarctica/Macquarie", "Macquarie Island"],
#     ...
#     ["Australia/Eucla", "Western Australia (Eucla)"]]

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

TZInfo v2.0.0 requires a minimum of Ruby MRI 1.9.3 or JRuby 1.7 (in 1.9 mode or
later).

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.

Documentation

API documentation for TZInfo is available on
RubyDoc.info.

License

TZInfo is released under the MIT license, see LICENSE for details.

Source Code

Source code for TZInfo is available on
GitHub.

Issue Tracker

Please post any bugs, issues, feature requests or questions about TZInfo to the
GitHub issue tracker.

Issues with the underlying time zone data should be raised on the
Time Zone Database discussion mailing list.

Owner metadata

GitHub Events

Total
Last Year

Committers metadata

Last synced: about 4 hours ago

Total Commits: 890
Total Committers: 21
Avg Commits per committer: 42.381
Development Distribution Score (DDS): 0.03

Commits in past year: 10
Committers in past year: 1
Avg Commits per committer in past year: 10.0
Development Distribution Score (DDS) in past year: 0.0

Name Email Commits
Phil Ross p****s@g****m 863
Mike Perham m****m@g****m 3
Aaron Lasseigne a****e@g****m 2
Akira Matsuda r****e@d****p 2
NARUSE, Yui n****e@a****p 2
Nobuyoshi Nakada n****u@r****g 2
Ryuta Kamizono k****o@g****m 2
Josef Stribny j****y@r****m 1
Marshall Shen m****n@g****m 1
renaud r****y@e****i 1
Eric True e****e@s****g 1
Garry Shutler g****y@r****k 1
Guilherme Mansur g****r@s****m 1
Orien Madgwick _@o****o 1
Pedro Vereza p****a@g****m 1
Reid Beels m****l@r****m 1
SHIBATA Hiroshi s****i@g****m 1
Uģis Ozols u****s@g****m 1
Victor Shepelev z****e@g****m 1
Yuji Yaginuma y****a@g****m 1
takkanm t****m@g****m 1

Committer domains:

Issue and Pull Request metadata

Last synced: 24 days ago

Total issues: 86
Total pull requests: 29
Average time to close issues: 16 days
Average time to close pull requests: about 1 month
Total issue authors: 81
Total pull request authors: 22
Average comments per issue: 2.35
Average comments per pull request: 1.79
Merged pull request: 16
Bot issues: 0
Bot pull requests: 0

Past year issues: 5
Past year pull requests: 0
Past year average time to close issues: 18 days
Past year average time to close pull requests: N/A
Past year issue authors: 5
Past year pull request authors: 0
Past year average comments per issue: 0.8
Past year average comments per pull request: 0
Past year merged pull request: 0
Past year bot issues: 0
Past year bot pull requests: 0

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/tzinfo/tzinfo

Top Issue Authors

  • philr (3)
  • voxik (3)
  • dabrorius (2)
  • psienko (1)
  • nobu (1)
  • mattjohnsonpint (1)
  • redconfetti (1)
  • raganwald (1)
  • dblock (1)
  • ndbroadbent (1)
  • curtp (1)
  • jasnow (1)
  • slimdave (1)
  • tbem (1)
  • rhuppert (1)

Top Pull Request Authors

  • kamipo (4)
  • spazquest (2)
  • samarth23b (2)
  • nobu (2)
  • casperisfine (2)
  • Rdx31 (1)
  • takkanm (1)
  • nurse (1)
  • y-yagi (1)
  • zverok (1)
  • jmettraux (1)
  • pedrovereza (1)
  • cjmz (1)
  • rafbm (1)
  • LouisBoudreau (1)

Top Issue Labels

  • question (11)
  • invalid (7)
  • duplicate (1)
  • bug (1)
  • enhancement (1)

Top Pull Request Labels

  • invalid (1)

Package metadata

gem.coop: tzinfo

TZInfo provides access to time zone data and allows times to be converted using time zone rules.

  • Homepage: https://tzinfo.github.io
  • Documentation: http://www.rubydoc.info/gems/tzinfo/
  • Licenses: MIT
  • Latest release: 2.0.6 (published almost 3 years ago)
  • Last Synced: 2026-01-08T10:08:22.348Z (1 day ago)
  • Versions: 95
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Downloads: 1,170,295,515 Total
  • Docker Downloads: 3,669,594,710
  • Rankings:
    • Dependent repos count: 0.0%
    • Dependent packages count: 0.0%
    • Average: 0.005%
    • Downloads: 0.006%
    • Docker downloads count: 0.016%
  • Maintainers (1)
rubygems.org: tzinfo

TZInfo provides access to time zone data and allows times to be converted using time zone rules.

alpine-v3.18: ruby-tzinfo

Ruby Timezone Library

  • Homepage: https://github.com/tzinfo/tzinfo
  • Licenses: MIT
  • Latest release: 2.0.6-r0 (published over 2 years ago)
  • Last Synced: 2026-01-08T15:39:13.118Z (1 day ago)
  • Versions: 1
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Rankings:
    • Dependent repos count: 0.0%
    • Dependent packages count: 0.0%
    • Average: 6.228%
    • Forks count: 11.386%
    • Stargazers count: 13.526%
  • Maintainers (1)
proxy.golang.org: github.com/tzinfo/tzinfo

  • Homepage:
  • Documentation: https://pkg.go.dev/github.com/tzinfo/tzinfo#section-documentation
  • Licenses: mit
  • Latest release: v2.0.6+incompatible (published almost 3 years ago)
  • Last Synced: 2026-01-08T15:37:09.245Z (1 day ago)
  • Versions: 95
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Rankings:
    • Dependent packages count: 6.48%
    • Average: 6.698%
    • Dependent repos count: 6.917%
alpine-edge: ruby-tzinfo

Ruby Timezone Library

  • Homepage: https://github.com/tzinfo/tzinfo
  • Licenses: MIT
  • Latest release: 2.0.6-r2 (published 9 months ago)
  • Last Synced: 2026-01-08T15:38:04.185Z (1 day ago)
  • Versions: 4
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Rankings:
    • Dependent repos count: 0.0%
    • Average: 10.394%
    • Forks count: 12.422%
    • Stargazers count: 14.512%
    • Dependent packages count: 14.641%
  • Maintainers (1)
alpine-v3.17: ruby-tzinfo

Ruby Timezone Library

  • Homepage: https://github.com/tzinfo/tzinfo
  • Licenses: MIT
  • Latest release: 2.0.5-r0 (published about 3 years ago)
  • Last Synced: 2026-01-08T15:39:02.563Z (1 day ago)
  • Versions: 1
  • Dependent Packages: 1
  • Dependent Repositories: 0
  • Rankings:
    • Dependent repos count: 0.0%
    • Average: 10.551%
    • Forks count: 10.907%
    • Stargazers count: 12.344%
    • Dependent packages count: 18.951%
  • Maintainers (1)
conda-forge.org: rb-tzinfo

  • Homepage: https://rubygems.org/gems/tzinfo
  • Licenses: MIT
  • Latest release: 2.0.1 (published over 5 years ago)
  • Last Synced: 2026-01-08T15:35:26.596Z (1 day ago)
  • Versions: 3
  • Dependent Packages: 3
  • Dependent Repositories: 1
  • Rankings:
    • Dependent packages count: 15.649%
    • Forks count: 18.539%
    • Average: 19.838%
    • Stargazers count: 20.894%
    • Dependent repos count: 24.268%
alpine-v3.20: ruby-tzinfo

Ruby Timezone Library

  • Homepage: https://github.com/tzinfo/tzinfo
  • Licenses: MIT
  • Latest release: 2.0.6-r1 (published about 2 years ago)
  • Last Synced: 2026-01-08T15:37:59.641Z (1 day ago)
  • Versions: 1
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Rankings:
    • Dependent repos count: 0.0%
    • Dependent packages count: 0.0%
    • Average: 100%
  • Maintainers (1)
alpine-v3.22: ruby-tzinfo

Ruby Timezone Library

  • Homepage: https://github.com/tzinfo/tzinfo
  • Licenses: MIT
  • Latest release: 2.0.6-r2 (published 9 months ago)
  • Last Synced: 2026-01-08T15:34:05.123Z (1 day ago)
  • Versions: 1
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Rankings:
    • Dependent repos count: 0.0%
    • Dependent packages count: 0.0%
    • Average: 100%
  • Maintainers (1)
alpine-v3.19: ruby-tzinfo

Ruby Timezone Library

  • Homepage: https://github.com/tzinfo/tzinfo
  • Licenses: MIT
  • Latest release: 2.0.6-r0 (published over 2 years ago)
  • Last Synced: 2026-01-08T15:35:47.660Z (1 day ago)
  • Versions: 1
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Rankings:
    • Dependent repos count: 0.0%
    • Dependent packages count: 0.0%
    • Average: 100%
  • Maintainers (1)
alpine-v3.21: ruby-tzinfo

Ruby Timezone Library

  • Homepage: https://github.com/tzinfo/tzinfo
  • Licenses: MIT
  • Latest release: 2.0.6-r1 (published about 2 years ago)
  • Last Synced: 2026-01-08T15:37:48.148Z (1 day ago)
  • Versions: 1
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Rankings:
    • Dependent repos count: 0.0%
    • Dependent packages count: 0.0%
    • Average: 100%
  • Maintainers (1)

Dependencies

.github/workflows/tests.yml actions
  • actions/checkout v3 composite
  • philr/setup-ruby legacy-v1 composite
  • ruby/setup-ruby v1 composite
Gemfile rubygems
  • json < 2.5.0 development
  • json < 2.3.0 development
  • minitest ~> 5.0 development
  • simplecov ~> 0.15.1 development
tzinfo.gemspec rubygems
  • concurrent-ruby ~> 1.0

Score: 31.964958705728442