zones 0.6.2 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f86231105060ba0d2a2e5de9b5d5e1a12697442eab2f53e25141ae9e364c595
-  data.tar.gz: 435fd13071ba665a0e3c8f4cca2162a804ca160ffee145ca179558a4e22f383d
+  metadata.gz: fcc3e314485f8294d9dfbfa29afc78ccd6cf9619cd67095bc5fe6b1f84616277
+  data.tar.gz: 36bea6abe134f28921a23d3a1bb9bb6e1cea7b1c9ffb6fbfc80362156e3f6895
 SHA512:
-  metadata.gz: 10f84f521cefa6e9ef0d3933338d8c6666dde86908fb18cf8d530ffe71535e95cb8c028a1537356edba17ce5d36a6fdf71a86dfc040208a178b0ea8282adfa48
-  data.tar.gz: 5929966234fda57b8b1fac23ace116f43369e3a68a994ad4413d56ed001c415efc22e850e27f2a2de9175bfb8bd6a363575d14d408a7618a69b246c18b6e3fc6
+  metadata.gz: 1c9742d8ce70f27717f435d2174c8c019529d168cf84162d0f89769f3d394eac3ddd5f150e171edd5de0d1eb2b847a997909031368f9f3038770f1ba479c1447
+  data.tar.gz: 48e62375f30a6bb5a45ef207a419f13731b06cc11c8e2b9df6a7a6c4df74235c1451956e3d69b5beb5c798d0ba64c98aa10b38bdb29c244d3bf1e3c58d0445f3

data/README.md

@@ -1,17 +1,54 @@
 # zones
 
-`zones` is a Ruby gem that makes it easy to parse time and convert it between time zones.
+A friendly Ruby gem for time parsing and time zone conversion.
+
+## API
+
+```ruby
+Time.tz(str, toz=nil, asz=nil)    # create a new Time object with a time zone
+Time.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.tz
+String#to_tz!   # calls Time.tz!
+String#to_day   # calls Date.to_day
+String#iso_date # parses and shows ISO date (YYYY-MM-DD)
+```
 
 ## Examples
 
+Parsing strings:
+
 ```ruby
-# when parsing, the "!" means to ignore the supplied time zone / offset
-x = "3 August 2017 11:43 +0415".to_tz("US/Pacific")  # 2017-08-03 00:28:00 -0700
-y = "3 August 2017 11:43 +0415".to_tz!("US/Pacific") # 2017-08-03 11:43:00 -0700
+# no argument means to parse the value as is; "!" ignores the time zone and uses UTC
+x = "3 August 2013 11:43 +0415".to_tz  # 2013-08-03 11:43:00 +0415
+y = "3 August 2013 11:43 +0415".to_tz! # 2013-08-03 11:43:00 +0000
 
-# when converting, the "!" means to only change the offset
-x.to_tz("US/Eastern")  # 2017-08-03 03:28:00 -0400
-y.to_tz!("US/Eastern") # 2017-08-03 11:43:00 -0400
+# one argument means to convert to that time zone, use "!" to ignore the original offset
+x = "3 August 2013 11:43 +0415".to_tz("US/Pacific")  # 2013-08-03 00:28:00 -0700
+y = "3 August 2013 11:43 +0415".to_tz!("US/Pacific") # 2013-08-03 11:43:00 -0700
+
+# use two arguments to indicate source and destination time zones, "!" swaps the order
+x = "3 August 2013 11:43 +0415".to_tz("US/Pacific", "America/Caracas")  # 2013-08-03 09:13:00 -0700
+y = "3 August 2013 11:43 +0415".to_tz!("US/Pacific", "America/Caracas") # 2013-08-03 14:13:00 -0430
+```
+
+Converting values:
+
+```ruby
+# '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:
+
+```ruby
+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

data/lib/zones.rb

@@ -1,49 +1,42 @@
 require "tzinfo"
 
-# ==[ Dart uses the folllowing ]==
-#
-# date             ::= yeardate time_opt timezone_opt
-# yeardate         ::= year colon_opt month colon_opt day
-# year             ::= sign_opt digit{4,6}
-# colon_opt        :: <empty> | ':'
-# sign             ::= '+' | '-'
-# sign_opt         ::= <empty> | sign
-# month            ::= digit{2}
-# day              ::= digit{2}
-# time_opt         ::= <empty> | (' ' | 'T') hour minutes_opt
-# minutes_opt      ::= <empty> | colon_opt digit{2} seconds_opt
-# seconds_opt      ::= <empty> | colon_opt digit{2} millis_opt
-# micros_opt       ::= <empty> | ('.' | ',') digit+
-# timezone_opt     ::= <empty> | space_opt timezone
-# space_opt        :: ' ' | <empty>
-# timezone         ::= 'z' | 'Z' | sign digit{2} timezonemins_opt
-# timezonemins_opt ::= <empty> | colon_opt digit{2}
-#
-# static final RegExp _parseFormat =
-#     RegExp(r'^([+-]?\d{4,6})-?(\d\d)-?(\d\d)' // Day part.
-#         r'(?:[ T](\d\d)(?::?(\d\d)(?::?(\d\d)(?:[.,](\d+))?)?)?' // Time part.
-#         r'( ?[zZ]| ?([-+])(\d\d)(?::?(\d\d))?)?)?$'); // Timezone part.
+module MonthValue
+  def month_value(str)
+    (val = str.to_i).zero? ? (@month_value ||= {
+      "jan" => 1, "january"  =>  1, "jul" =>  7, "july"      =>  7,
+      "feb" => 2, "february" =>  2, "aug" =>  8, "august"    =>  8,
+      "mar" => 3, "march"    =>  3, "sep" =>  9, "september" =>  9,
+      "apr" => 4, "april"    =>  4, "oct" => 10, "october"   => 10,
+      "may" => 5,                   "nov" => 11, "november"  => 11,
+      "jun" => 6, "june"     =>  6, "dec" => 12, "december"  => 12,
+    })[str.downcase] : val or raise "bad month: #{str}"
+  end
+end
 
 class Date
+  extend MonthValue
+
   def self.parse_str(str)
     case str
-    when %r!^((?:19|20)\d\d)(\d\d)(\d\d)(\d\d)!
+    when %r!^((?:19|20)\d\d)(\d\d)(\d\d)!
       ymd = [$1.to_i, $2.to_i, $3.to_i]
     when %r!^
-      (?:(0[1-9]|[12]\d|3[01]|[1-9][-/ ])[-/ ]? #  $1: day
-         ((?>[a-z]{3,9}))[-/ ]?                 #  $2: month
-         ((?>19|20)\d\d)                        #  $3: year
+      (?:(0[1-9]|[12]\d|3[01]|[1-9](?=\D))[-/\s]?          #  $1: day
+         (                          (?>[a-z]{3,9}))[-/\s]? #  $2: month (no digits allowed here)
+         ((?>19|20)\d\d)                                   #  $3: year
       | # or...
-         ((?>19|20)\d\d)[-/]?                   #  $4: year
-         (0[1-9]|1[012]|[1-9][-/])[-/]?         #  $5: month
-         (0[1-9]|[12]\d|3[01]|[1-9][\sT])       #  $6: day
+         ((?>19|20)\d\d)[-/\s]?                            #  $4: year
+         (0[1-9]|1[012]|[1-9](?=\D)|(?>[a-z]{3,9}))[-/\s]? #  $5: month
+         (0[1-9]|[12]\d|3[01]|[1-9]\b)                     #  $6: day
       | # or...
-         (0[1-9]|1[012]|[1-9][-/])[-/]?         #  $7: month
-         (0[1-9]|[12]\d|3[01]|[1-9][-/])[-/]?   #  $8: day
-         ((?>19|20)\d\d)                        #  $9: year
+         (0[1-9]|1[012]|[1-9](?=\D)|(?>[a-z]{3,9}))[-/\s]? #  $7: month
+         (0[1-9]|[12]\d|3[01]|[1-9](?=\D)),?[-/\s]?        #  $8: day
+         ((?>19|20)\d\d)                                   #  $9: year
       )
     !iox
-      ymd = $1 ? [$3.to_i, month_num($2), $1.to_i] : $4 ? [$4.to_i, $5.to_i, $6.to_i] : [$9.to_i, $7.to_i, $8.to_i]
+      ymd =   $1 ? [ $3.to_i, month_value($2), $1.to_i] : \
+              $4 ? [ $4.to_i, month_value($5), $6.to_i] : \
+                   [ $9.to_i, month_value($7), $8.to_i]
     else
       raise "can't parse: #{str}"
     end
@@ -58,113 +51,90 @@ class Date
 end
 
 class Time
-  def self.parse_str(str, ignore_offset=false)
+  extend MonthValue
+
+  def self.parse_str(str)
     case str
-    when %r!^((?:19|20)\d\d)(\d\d)(\d\d)(\d\d)(\d\d)(\d\d)?\.?(\d+)?([-+]\d\d:?\d\d)?!
+    when %r!^
+      ((?:19|20)\d\d)[-/\s]?(\d\d)[-/\s]?(\d\d)\s? # $1-3: year, month, day
+      (\d\d):?(\d\d):?(\d\d)?\.?(\d+)?             # $4-7: hour, min, sec, decimal
+      ([-+]\d\d:?\d\d)?                            # $8  : offset
+    !x
       ymd = [$1.to_i, $2.to_i, $3.to_i]
       hms = [$4.to_i, $5.to_i, "#{$6}.#{$7}".to_f]
-      off = $8.sub(/(\d)(\d\d)$/,'\1:\2') if $8 && !ignore_offset
+      off = $8.sub(/(\d)(\d\d)$/,'\1:\2') if $8
     when %r!^
-      (?:(0[1-9]|[12]\d|3[01]|[1-9][-/ ])[-/ ]? #  $1: day
-         ((?>[a-z]{3,9}))[-/ ]?                 #  $2: month
-         ((?>19|20)\d\d)                        #  $3: year
+      (?:(0[1-9]|[12]\d|3[01]|[1-9](?=\D))[-/\s]?          #  $1: day
+         (                          (?>[a-z]{3,9}))[-/\s]? #  $2: month (no digits allowed here)
+         ((?>19|20)\d\d)                                   #  $3: year
       | # or...
-         ((?>19|20)\d\d)[-/]?                   #  $4: year
-         (0[1-9]|1[012]|[1-9][-/])[-/]?         #  $5: month
-         (0[1-9]|[12]\d|3[01]|[1-9][\sT])       #  $6: day
+         ((?>19|20)\d\d)[-/\s]?                            #  $4: year
+         (0[1-9]|1[012]|[1-9](?=\D)|(?>[a-z]{3,9}))[-/\s]? #  $5: month
+         (0[1-9]|[12]\d|3[01]|[1-9](?=\D))                 #  $6: day
       | # or...
-         (0[1-9]|1[012]|[1-9][-/])[-/]?         #  $7: month
-         (0[1-9]|[12]\d|3[01]|[1-9][-/])[-/]?   #  $8: day
-         ((?>19|20)\d\d)                        #  $9: year
+         (0[1-9]|1[012]|[1-9](?=\D)|(?>[a-z]{3,9}))[-/\s]? #  $7: month
+         (0[1-9]|[12]\d|3[01]|[1-9](?=\D)),?[-/\s]?        #  $8: day
+         ((?>19|20)\d\d)                                   #  $9: year
       )\s?T?\s?
-      (\d\d?)?                                  # $10: hour
-      :?(\d\d)?                                 # $11: min
-      :?(\d\d)?                                 # $12: sec
-      \.?(\d+)?                                 # $13: dec
-      \s?(?:(a|p)?m)?                           # $14: am/pm
-      \s?(([-+])?(\d\d):?(\d\d)|UTC|GMT)?       # $15: offset ($16=sign, $17=hours, $18=mins)
+      (\d\d?)?                                             # $10: hour
+      :?(\d\d)?                                            # $11: min
+      :?(\d\d)?                                            # $12: sec
+      \.?(\d+)?                                            # $13: dec
+      \s?(?:(a|p)?m)?                                      # $14: am/pm
+      \s?(([-+])?(\d\d):?(\d\d)|UTC|GMT|Z)?                # $15: offset ($16=sign, $17=hours, $18=mins)
     !iox
-      ymd = $1 ? [$3.to_i, month_num($2), $1.to_i] : $4 ? [$4.to_i, $5.to_i, $6.to_i] : [$9.to_i, $7.to_i, $8.to_i]
+      ymd =   $1 ? [ $3.to_i, month_value($2), $1.to_i] : \
+              $4 ? [ $4.to_i, month_value($5), $6.to_i] : \
+                   [ $9.to_i, month_value($7), $8.to_i]
       hms = [$14 ? ($10.to_i % 12) + (($14=="P" || $14=="p") ? 12 : 0) : $10.to_i, $11.to_i, "#{$12}.#{$13}".to_f]
-      off = ($17 ? "#{$16||'+'}#{$17}:#{$18}" : "+00:00") if $15 && !ignore_offset
+      off = ($17 ? "#{$16||'+'}#{$17}:#{$18}" : "+00:00") if $15
     else
       raise "can't parse: #{str}"
     end
-    off ? [ymd, hms, off] : [ymd, hms]
-  end
-
-  # get month number
-  def self.month_num(str)
-    (@month_num ||= {
-      "jan" => 1, "january"  =>  1, "jul" =>  7, "july"      =>  7,
-      "feb" => 2, "february" =>  2, "aug" =>  8, "august"    =>  8,
-      "mar" => 3, "march"    =>  3, "sep" =>  9, "septmeber" =>  9,
-      "apr" => 4, "april"    =>  4, "oct" => 10, "october"   => 10,
-      "may" => 5,                   "nov" => 11, "november"  => 11,
-      "jun" => 6, "june"     =>  6, "dec" => 12, "december"  => 12,
-    })[str.downcase] or raise "bad month: #{str}"
+    [ymd, hms, off]
   end
 
-  # parse time and honor desired timezone
-  def self.to_tz(str, zone=nil, ignore_offset=false)
-    ymd, hms, off = parse_str(str, ignore_offset)
-    out = Time.new(*ymd, *hms, off)
-    if zone
-      if off
-        out = out.to_tz(zone)
-      else
-        utc = out.utc
-        off = TZInfo::Timezone.get(zone).utc_to_local(utc) - utc
-        out = Time.new(*ymd, *hms, off)
-      end
-    else
-      out
-    end
+  def self.tz(str, toz=nil, asz=nil)
+    ymd, hms, off = parse_str(str)
+    out = Time.new(*ymd, *hms, asz ? TZInfo::Timezone.get(asz) : off)
+    toz ? out.to(toz) : out
   end
 
-  # ignore supplied timezone, use local
-  def self.to_tz!(str, zone=nil)
-    to_tz(str, zone, true)
+  def self.tz!(str, asz="UTC", toz=nil)
+    tz(str, toz, asz)
   end
 
-  # NOTE: We can clean this up too...
-  # this 1-liner works, but returns a TZInfo::TimeWithOffset???
-  # def in_tz(zone); TZInfo::Timezone.get(zone).to_local(self); end
-
-  # same time moment, different time zone offset
-  def in_tz(zone)
+  # same time moment, different time zone (ie - change time and zone)
+  def to(zone)
     cfg = TZInfo::Timezone.get(zone)
     use = cfg.to_local(self)
     ary = use.to_a[1,5].reverse.push(strftime("%S.%6N").to_f)
     Time.new(*ary, cfg)
   end
 
-  # same time values, different time zone offset
-  def as_tz(zone)
+  # same time values, different time zone (ie - change time zone only)
+  def as(zone)
     cfg = TZInfo::Timezone.get(zone)
     use = self
     ary = use.to_a[1,5].reverse.push(strftime("%S.%6N").to_f)
     Time.new(*ary, cfg)
   end
-
-  alias_method :to_tz , :in_tz
-  alias_method :to_tz!, :as_tz
 end
 
 class String
-  def to_tz(*args)
-    Time.to_tz(self, *args)
+  def to_day
+    Date.to_day(self)
   end
 
-  def to_tz!(*args)
-    Time.to_tz!(self, *args)
+  def iso_date(fmt="%Y-%m-%d")
+    to_day.strftime(fmt)
   end
 
-  def to_day
-    Date.to_day(self)
+  def to_tz(*args)
+    Time.tz(self, *args)
   end
 
-  def to_day!(fmt="%Y-%m-%d")
-    to_day.strftime(fmt)
+  def to_tz!(*args)
+    Time.tz!(self, *args)
   end
 end

data/zones.gemspec

@@ -1,12 +1,10 @@
-# encoding: utf-8
-
 Gem::Specification.new do |s|
   s.name        = "zones"
-  s.version     = "0.6.2"
+  s.version     = "1.0.1"
   s.author      = "Steve Shreeve"
   s.email       = "steve.shreeve@gmail.com"
-  s.summary     = "Easy time parsing and conversion between time zones"
-  s.description = "This gem makes it easy to work with time zones."
+  s.summary     =
+  s.description = "A friendly Ruby gem for time parsing and time zone conversion"
   s.homepage    = "https://github.com/shreeve/zones"
   s.license     = "MIT"
   s.files       = `git ls-files`.split("\n") - %w[.gitignore]

metadata

@@ -1,16 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: zones
 version: !ruby/object:Gem::Version
-  version: 0.6.2
+  version: 1.0.1
 platform: ruby
 authors:
 - Steve Shreeve
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-06-27 00:00:00.000000000 Z
+date: 2023-06-29 00:00:00.000000000 Z
 dependencies: []
-description: This gem makes it easy to work with time zones.
+description: A friendly Ruby gem for time parsing and time zone conversion
 email: steve.shreeve@gmail.com
 executables: []
 extensions: []
@@ -43,5 +43,5 @@ requirements: []
 rubygems_version: 3.4.14
 signing_key:
 specification_version: 4
-summary: Easy time parsing and conversion between time zones
+summary: A friendly Ruby gem for time parsing and time zone conversion
 test_files: []