Simple abstraction of a timezone offset
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
spec
.gitignore
.rspec
.rubocop.yml
.travis.yml
.yardopts
CHANGELOG.md
Gemfile
README.md
Rakefile
tz_offset.gemspec

README.md

TZOffset

Gem Version Dependency Status Build Status

Ever tried to convert your distant friend's or colleague's phrase "OK, let's connect tomorrow at 6 pm my time (GMT+8)" into easily calculatable Ruby code? E.g. what time it would be in your timezone at 18:00 GMT+8? What is your favorite solution? Now it should be that:

TZOffset.parse('GMT+8').local(2016, 10, 20, 18).localtime
# => 2016-10-20 13:00:00 +0300

# or just
TZOffset.parse('+8').local(2016, 10, 20, 18).localtime
# => 2016-10-20 13:00:00 +0300

# Also works with most common timezone abbreviations
TZOffset.parse('CEST').local(2016, 10, 20, 18).localtime
# => 2016-10-20 19:00:00 +0300

In other words, TZOffset is simple, no-magic, incapsulated abstraction of "time offset".

Features and problems

  • Easy-to-use, intuitive, dead simple, OS independent;
  • No brains included: no huge and comprehensive database of historical times, no automatic DST conversion; you just know offset you need, and have it as a near-to-mathematical value;
  • Simple value objects, easily converted to/from YAML (so you can save them to databases, pass to delayed jobs and so on);
  • Knows about all common timezone abbreviations (got them from Wikipedia list);
  • For ambiguous abbreviations, just returns list of all of them:
TZOffset.parse('EET')
# => #<TZOffset +02:00 (EET)>
TZOffset.parse('CDT')
# => [#<TZOffset -05:00 (CDT)>, #<TZOffset -04:00 (CDT)>]
  • For symbolic timezones, provides a description, if available:
TZOffset.parse('CDT').map(&:description)
# => ["Central Daylight Time (North America)", "Cuba Daylight Time"]
TZOffset.parse('CDT').map(&:region)
# => ["Central", "Cuba"]

# NB: Just "Central", "Eastern" and so on is related to North America in timezones nomenclature
  • for DST and non-DST timezones provides dst-flag and counterpart timezone, if available:
eet = TZOffset.parse('EET')
# => #<TZOffset +02:00 (EET)>
eet.dst?
# => false
eet.opposite
# => #<TZOffset +03:00 (EEST)>
[eet.description, eet.opposite.description]
# => ["Eastern European Time", "Eastern European Summer Time"]

Installation

Do your usual routine with gem named tz_offset (e.g. gem install tz_offset or add gem "tz_offset to your Gemfile).

Usage

Most of it is already shown above!

require 'tz_offset'

off = TZOffset.parse('-02:30')
# => #<TZOffset -02:30>
off.now
# => 2016-10-25 16:07:55 -0230
off.local(2016, 10, 1)
# => 2016-10-01 00:00:00 -0230

eet = TZOffset.parse('EET')
# => #<TZOffset +02:00 (EET)>
eet.now
# => 2016-10-25 20:29:03 +0200
eet.description
# => "Eastern European Time"
eet.region
# => "Eastern European"
eet.opposite
# => #<TZOffset +03:00 (EEST)>
eet.opposite.now
# => 2016-10-25 21:39:26 +0300

# Parsing time string into desired timezone
off = TZOffset.parse('-02:30')
off.parse('2014-10-01 12:30')
# => 2014-10-01 12:30:00 -0230
off.parse('12:30')
# => 2016-10-26 12:30:00 -0230

Author

Victor Shepelev -- extracted from reality project.

License

MIT.