/zones

Ruby gem to make it easy to work with time zones

Primary LanguageRubyMIT LicenseMIT

zones

A friendly Ruby gem for time parsing and time zone conversion.

API

Time.to_tz(str, toz=nil, asz=nil)   # create a new Time object with a time zone
Time.as_tz(str, asz="UTC", toz=nil) # overrides original time zone and swaps params
Time#to(zone) # converts a time to a new time zone
Time#as(zone) # keeps the time, but changes the time zone

String#to_tz    # calls Time.to_tz
String#as_tz    # calls Time.as_tz
String#to_day   # calls Date.to_day
String#iso_date # parses and shows ISO date (YYYY-MM-DD)

Examples

Parsing strings:

# no argument means to parse the value as is; 'as' ignores the time zone and defaults to UTC
"3 August 2013 11:43 +0415".to_tz # 2013-08-03 11:43:00 +0415
"3 August 2013 11:43 +0415".as_tz # 2013-08-03 11:43:00 +0000

# one argument for `to_tz` means to parse naturally and then convert to that time zone
"3 August 2013 11:43 +0415".to_tz("US/Pacific") # 2013-08-03 00:28:00 -0700
"3 August 2013 11:43 +0415".to_tz("America/Caracas") # 2013-08-03 02:58:00 -0430

# one argument for `as_tz` means to ignore offset and use the parameter passed in
"3 August 2013 11:43 +0415".as_tz("US/Pacific") # 2013-08-03 11:43:00 -0700
"3 August 2013 11:43 +0415".as_tz("America/Caracas") # 2013-08-03 11:43:00 -0430

# use two arguments to indicate destination and source time zones, 'as' swaps the order
"3 August 2013 11:43 +0415".to_tz("US/Pacific", "America/Caracas") # 2013-08-03 09:13:00 -0700
"3 August 2013 11:43 +0415".as_tz("US/Pacific", "America/Caracas") # 2013-08-03 14:13:00 -0430

# the same as above, swapping functions and parameter order gives same results
"3 August 2013 11:43 +0415".to_tz("America/Caracas", "US/Pacific") # 2013-08-03 14:13:00 -0430
"3 August 2013 11:43 +0415".as_tz("America/Caracas", "US/Pacific") # 2013-08-03 09:13:00 -0700

Parsing strings using to_tz:

# no args means to parse the value as is
"3 August 2013 11:43 +0415".to_tz # 2013-08-03 11:43:00 +0415

# one arg will then convert to that time zone
"3 August 2013 11:43 +0415".to_tz("US/Pacific") # 2013-08-03 00:28:00 -0700
"3 August 2013 11:43 +0415".to_tz("America/Caracas") # 2013-08-03 02:58:00 -0430

# two args forces the second arg as the initial time zone
"3 August 2013 11:43 +0415".to_tz("US/Pacific", "America/Caracas") # 2013-08-03 09:13:00 -0700
"3 August 2013 11:43 +0415".to_tz("America/Caracas", "US/Pacific") # 2013-08-03 14:13:00 -0430

Parsing strings using as_tz:

# no args forces the timezone to be UTC
"3 August 2013 11:43 +0415".as_tz # 2013-08-03 11:43:00 +0000

# one arg ignore offset and forces the time zone as the arg
"3 August 2013 11:43 +0415".as_tz("US/Pacific") # 2013-08-03 11:43:00 -0700
"3 August 2013 11:43 +0415".as_tz("America/Caracas") # 2013-08-03 11:43:00 -0430

# two args forces the second arg as the initial time zone
"3 August 2013 11:43 +0415".as_tz("US/Pacific", "America/Caracas") # 2013-08-03 14:13:00 -0430
"3 August 2013 11:43 +0415".as_tz("America/Caracas", "US/Pacific") # 2013-08-03 09:13:00 -0700

Converting values:

# 'as' keeps the time but changes the time zone, 'to' converts to a new time zone
x = "May 29, 2023 6:15pm -06:00".to_tz # 2023-05-29 18:15:00 -0600
x.as("US/Eastern")                     # 2023-05-29 18:15:00 -0400
x.to("US/Eastern")                     # 2023-05-29 20:15:00 -0400

Sample formats:

x = "4/13/1971 19:25 -0700".to_tz # 1971-04-13 19:25:00 -0700
x = "13 May 2022 11:20PM".to_tz   # 2022-05-13 23:20:00 -0600
x = "September 24, 2008".iso_date # 2008-09-24

License

This software is licensed under terms of the MIT License.