timerage 1.8.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a516908d80d7444bc7558fe488fe546aba2d123f
-  data.tar.gz: d3ca42c6b1190a24c9030f6e91cebb5844447c05
+  metadata.gz: f82bbd7083065080ca7d80bf905a6f77d8bf2e7f
+  data.tar.gz: fbbcc51556bbdcf68e000937cb0d219c78f942e1
 SHA512:
-  metadata.gz: aca0bf8520121da781d8e28a0f80974d619feba6f1e1a2f6b15055ff83e09489fc138a8dabfb47b594b43b738650294ed63ad089f9c2630e17a4467fc3c874d4
-  data.tar.gz: b73c86c3d951f1cd9571b63015647e67635d45a1cef8bec33d2794a213e08154765a0ea74575c7399a4e0dfd3522f5b0e651ef660b90624d0560233a25bfd6ba
+  metadata.gz: 0f3d81194d057830e4fe1743df1b8fe65c79af78ebf71f406792d1d26f513aac2f42321dea5cc58633c9733aa043321b091f96e6fc6244d99952b9bc81c8ea66
+  data.tar.gz: 04d3101baf65ab9eef0b4ffd3ccd7b6081016debe211e69cdf40c7f26395809f2efb29e66fbd785cbb94749da93fb5d2ae7a8cdcd9ec79f67b6865a1f9edb3d2

data/README.md

@@ -1,6 +1,6 @@
 # Timerage
 
-Simple refinement to make Time Ranges work a little.
+Time Ranges that are actually useful.
 
 ## Installation
 
@@ -20,15 +20,66 @@ Or install it yourself as:
 
 ```ruby
 require 'timerage'
+```
+
+### Coercion to Time (related) objects
+
+``` ruby
+a_time = Timerage("2016-01-18T22:25:37Z")
+# => 2016-01-18 22:25:37 +0000
+
+Timerage(a_time)
+# => 2016-01-18 22:25:37 +0000
+
+Timerage("2016-01-18T21:25:37+00:00/2016-01-18T22:25:37+00:00")
+# => 2016-01-18 21:25:37 +0000...2016-01-18 22:25:37 +0000
+
+interval = Timerage((a_time-3600)...a_time)
+# => 2016-01-18 21:25:37 +0000...2016-01-18 22:25:37 +0000
+```
 
-class MyClass
-  using Timerage
+### Stepping over a time inteval
+
+```ruby
+interval.step(30*60).map { |time| time }
+# => [2016-01-18 21:25:37 +0000, 2016-01-18 21:55:37 +0000]
+```
+
+### Slicing a time interval
+
+```ruby
+interval.slice(30*60).map { |time| time }
+# => [2016-01-18 21:25:37 UTC...2016-01-18 21:55:37 UTC, 2016-01-18 21:55:37 UTC...2016-01-18 22:25:37 UTC]
+```
 
-  # Step over these two times in 10 second steps
-  def my_method(time1, time2)
-    (time1..time2).step(10) { |time| puts time}
-  end
-end
+### ISO 8601 output
+
+```ruby
+interval.iso8601
+# => "2016-01-18T21:25:37+00:00/2016-01-18T22:25:37+00:00"
+```
+
+### Comparisons
+
+Supports most range/set comparisons
+
+* `#overlap?`
+* `#cover?`
+* `#adjacent_to?`
+* `#==`
+
+### Concatenation
+
+```ruby
+interval + Timerage("2016-01-18T20:25:37+00:00/2016-01-18T21:25:37+00:00")
+# => 2016-01-18 20:25:37 UTC..2016-01-18 22:25:37 UTC
+```
+
+### Duration
+
+```ruby
+interval.duration
+# => 3600.0
 ```
 
 ## Gotchas

data/lib/timerage.rb

@@ -10,8 +10,8 @@ module Timerage
   # --
   #
   # Currently this only supports `<begin>/<end>` style time intervals.
-  def self.parse_iso8601(str)
-    TimeInterval.iso8601(str)
+  def self.parse_iso8601(str, exclusive_end: true)
+    TimeInterval.iso8601(str, exclusive_end: exclusive_end)
   rescue ArgumentError
     Time.iso8601(str)
   end
@@ -30,3 +30,27 @@ module Timerage
     end
   end
 end
+
+module Kernel
+  def Timerage(time_or_time_interval_ish)
+    thing = time_or_time_interval_ish
+
+    case thing
+    when ->(x) { x.respond_to? :to_time_interval }
+      thing
+
+    when ->(x) { x.respond_to? :exclude_end? }
+      Timerage::TimeInterval.new(thing)
+
+    when ->(x) { x.respond_to? :to_str }
+      Timerage.parse_iso8601(thing.to_str)
+
+    when ->(x) { x.respond_to? :to_time }
+      thing.to_time
+
+    else
+      fail TypeError, "unable to coerce #{thing} to a time or interval"
+
+    end
+  end
+end

data/lib/timerage/time_interval.rb

@@ -13,6 +13,10 @@ module Timerage
       super rng
     end
 
+    def to_time_interval
+      self
+    end
+
     alias_method :to_time, :begin
 
     # Returns number of seconds in this interval
@@ -53,37 +57,41 @@ module Timerage
       "#{self.begin.iso8601(*args)}/#{self.end.iso8601(*args)}"
     end
 
+    def getutc
+      return self if self.begin.utc? && self.end.utc?
+      self.class.new(self.begin.getutc, self.end.getutc, self.exclude_end?)
+    end
+
     def adjacent_to?(other)
       other.begin == self.end || other.end == self.begin
     end
 
     def cover?(time_or_interval)
-      return super unless rangeish?(time_or_interval)
-
       other = time_or_interval
+      return super unless rangeish?(other)
+      return false unless overlap?(other)
 
-      self.begin <= other.begin &&
-        if self.exclude_end? && other.exclude_end?
-          self.end > other.begin && self.begin < other.end && other.end <= self.end
-
-        elsif self.exclude_end?
-          self.end > other.begin && self.begin <= other.end && other.end < self.end
-
-        elsif other.exclude_end?
-          self.end >= other.begin && self.begin < other.end && other.end <= self.end
-
+      self_end, other_end = self.end, other.end
+      other.begin >= self.begin &&
+        if !self.exclude_end? || other.exclude_end?
+          other_end <= self_end
         else
-          self.end >= other.begin && self.begin <= other.end && other.end <= self.end
+          other_end < self_end
         end
     end
 
     def overlap?(other)
-      cover?(other) ||
-        other.cover?(self) ||
-        cover?(other.begin) ||
-        other.cover?(self.begin) ||
-        cover?(other.end) && (!other.exclude_end? || other.end != self.begin) ||
-        other.cover?(self.end) && (!self.exclude_end? || other.begin != self.end)
+      earliest, latest = if self.begin <= other.begin
+                           [self, other]
+                         else
+                           [other, self]
+                         end
+
+      latest_begin, earliest_end = latest.begin, earliest.end
+      return true  if latest_begin < earliest_end
+      return false if earliest_end < latest_begin
+
+      !earliest.exclude_end?
     end
 
     def <=>(other)
@@ -159,11 +167,12 @@ module Timerage
     # --
     #
     # Currently this only supports `<begin>/<end>` style time intervals.
-    def self.iso8601(str)
-      new *str.split("/").map{|s| Time.iso8601(s)}
+    def self.iso8601(str, exclusive_end: true)
+      new *str.split("/", 2).map{|s| Time.iso8601(s)}, exclusive_end
 
     rescue ArgumentError
       raise ArgumentError, "Invalid iso8601 interval: #{str.inspect}"
     end
   end
+
 end

data/lib/timerage/version.rb

@@ -1,3 +1,3 @@
 module Timerage
-  VERSION = "1.8.0"
+  VERSION = "2.0.0"
 end

data/spec/timerage/time_interval_spec.rb

@@ -19,6 +19,24 @@ describe Timerage::TimeInterval do
                 .to raise_error ArgumentError }
   end
 
+  describe "#getutc" do
+    subject(:interval_utc) { described_class.new(now-duration, now).getutc }
+    specify { expect(interval_utc).to be_kind_of described_class }
+
+    context "interval not in utc" do
+      specify { expect(now).not_to be_utc }
+      specify { expect(interval_utc.begin).to be_utc }
+      specify { expect(interval_utc.end).to be_utc }
+    end
+
+    context "interval already in utc" do
+      let(:now) { Time.now.getutc }
+      specify { expect(now).to be_utc }
+      specify { expect(interval_utc.begin).to be_utc }
+      specify { expect(interval_utc.end).to be_utc }
+    end
+  end
+
   subject(:interval) { described_class.new(now-duration, now) }
 
   it { is_expected.to behave_like_a Range }

data/spec/timerage_spec.rb

@@ -9,7 +9,7 @@ describe Timerage do
     specify { expect(range.to_time_interval).to be_kind_of Timerage::TimeInterval }
     specify { expect{|b| range.step(1200, &b) }.to yield_control.at_least(:once) }
 
-    describe ".iso8601" do
+    describe ".parse_iso8601" do
       specify { expect(described_class
                         .parse_iso8601("2001-01-01T00:00:00Z/2001-01-02T00:00:00-06:00"))
                 .to be_kind_of Timerage::TimeInterval }
@@ -30,7 +30,23 @@ describe Timerage do
           .to yield_successive_args now-duration, now-(duration-1200), now-(duration-2400) }
     end
 
-    let(:now) { Time.now }
+    describe "Kernel.Timerage" do
+      specify { expect( Timerage(a_time) ).to eq a_time }
+
+      specify { expect( Timerage(a_time_interval) ).to eq a_time_interval }
+      specify { expect( Timerage(a_range_of_times) ).to eq a_time_interval }
+
+      specify { expect( Timerage(a_time.iso8601(20)) ).to eq a_time }
+      specify { expect( Timerage(a_time_interval.iso8601(20)) ).to eq a_time_interval }
+
+      specify { expect{ Timerage(nil) }.to raise_error TypeError }
+      specify { expect{ Timerage(42) }.to raise_error TypeError }
+    end
+
+    let(:now) { Time.now.getutc }
+    let(:a_time) { now }
+    let(:a_time_interval) { Timerage::TimeInterval.new(now, now+duration, true) }
+    let(:a_range_of_times) { a_time_interval.begin...a_time_interval.end }
     let(:duration) { 3600 }
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: timerage
 version: !ruby/object:Gem::Version
-  version: 1.8.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Peter Williams
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-09-03 00:00:00.000000000 Z
+date: 2016-01-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -98,7 +98,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.4.5
 signing_key: 
 specification_version: 4
 summary: Simple refinement to Range to allow Time or Date as arguments
@@ -106,4 +106,3 @@ test_files:
 - spec/spec_helper.rb
 - spec/timerage/time_interval_spec.rb
 - spec/timerage_spec.rb
-has_rdoc: