zones 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fcc3e314485f8294d9dfbfa29afc78ccd6cf9619cd67095bc5fe6b1f84616277
-  data.tar.gz: 36bea6abe134f28921a23d3a1bb9bb6e1cea7b1c9ffb6fbfc80362156e3f6895
+  metadata.gz: 68effb6f43a7c0bc15f336624569d9f39c549cacd0b4afb319f4f40af29bd35b
+  data.tar.gz: 5eaa777bd12704f63a3d76b09dd6957f6e7896213c710377c8acdf7e7499b7bb
 SHA512:
-  metadata.gz: 1c9742d8ce70f27717f435d2174c8c019529d168cf84162d0f89769f3d394eac3ddd5f150e171edd5de0d1eb2b847a997909031368f9f3038770f1ba479c1447
-  data.tar.gz: 48e62375f30a6bb5a45ef207a419f13731b06cc11c8e2b9df6a7a6c4df74235c1451956e3d69b5beb5c798d0ba64c98aa10b38bdb29c244d3bf1e3c58d0445f3
+  metadata.gz: ef064dda2c373fd9faf62866e381432c76d72ed6735b0c1f1e544f21a8a0c4f7c909c8aabfc2756294e54862408012e63025b24da4d9693344ede3ba8ead648c
+  data.tar.gz: e7871c5dac1315da804bccf33c8a42f78196d1a13ff5dfbbca537a7d1cdfc8728f9a4f0126eb07c3a912389ce9bd403b4da5ff1f9c6bda360b04815806110580

data/README.md

@@ -5,13 +5,13 @@ 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_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.tz
-String#to_tz!   # calls Time.tz!
+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)
 ```
@@ -21,17 +21,55 @@ String#iso_date # parses and shows ISO date (YYYY-MM-DD)
 Parsing strings:
 
 ```ruby
-# 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
+# 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 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
+# 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
 
-# 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
+# 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`:
+
+```ruby
+# 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`:
+
+```ruby
+# 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:

data/lib/zones.rb

@@ -94,17 +94,19 @@ class Time
     [ymd, hms, off]
   end
 
-  def self.tz(str, toz=nil, asz=nil)
+  # read values of time in asz, stated, or local timezone, optionally convert to toz timezone
+  def self.to_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
 
-  def self.tz!(str, asz="UTC", toz=nil)
-    tz(str, toz, asz)
+  # swap the order of to_tz and default asz to UTC
+  def self.as_tz(str, asz="UTC", toz=nil)
+    to_tz(str, toz, asz)
   end
 
-  # same time moment, different time zone (ie - change time and zone)
+  # same moment in time, different time zone (ie - change time and zone)
   def to(zone)
     cfg = TZInfo::Timezone.get(zone)
     use = cfg.to_local(self)
@@ -112,7 +114,7 @@ class Time
     Time.new(*ary, cfg)
   end
 
-  # same time values, different time zone (ie - change time zone only)
+  # same values of time, different time zone (ie - change time zone only)
   def as(zone)
     cfg = TZInfo::Timezone.get(zone)
     use = self
@@ -131,10 +133,10 @@ class String
   end
 
   def to_tz(*args)
-    Time.tz(self, *args)
+    Time.to_tz(self, *args)
   end
 
-  def to_tz!(*args)
-    Time.tz!(self, *args)
+  def as_tz(*args)
+    Time.as_tz(self, *args)
   end
 end

data/zones.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name        = "zones"
-  s.version     = "1.0.1"
+  s.version     = "1.1.0"
   s.author      = "Steve Shreeve"
   s.email       = "steve.shreeve@gmail.com"
   s.summary     =

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zones
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Steve Shreeve
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-06-29 00:00:00.000000000 Z
+date: 2023-07-14 00:00:00.000000000 Z
 dependencies: []
 description: A friendly Ruby gem for time parsing and time zone conversion
 email: steve.shreeve@gmail.com
@@ -40,7 +40,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.14
+rubygems_version: 3.4.16
 signing_key:
 specification_version: 4
 summary: A friendly Ruby gem for time parsing and time zone conversion