teasy 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 53f5f0b964d3834bca1c2b758e319f63d51f9d1b
-  data.tar.gz: e29dd57251904a1ad26ce7d122fe66a87f54aac0
+  metadata.gz: 273a6716f2320256d8894fc5d59cdb5db6d199ab
+  data.tar.gz: 5a8b907999251a222f9bd474306c30293ed80b97
 SHA512:
-  metadata.gz: d481cbb6b0966e20565b745b446d0703e19b6cf0238ea10b71994756167c84e68b3e158f1ce0f9d9841ce2c7e5cb1fbcbf7b7a1bca9d469b042bcad0d43be689
-  data.tar.gz: 6de90fda2fea2a0dc8e95ed89e0711303e3c697082a2459ddde8971e79c8b1b731c2370df63e2ac2af58f589db2aa2c0b9f5843dc0d8b54cf7ec4caf61df2f74
+  metadata.gz: 2c371ca880d7a52a2a4bc5866744c17908e838e593b43e041e5d92a8c7826ea11ee45823731673a25a9403a198c945f1a4895065ab47bc68f3f950bd595f1195
+  data.tar.gz: d127720d95b025f5acbf27c147a63f31bc40248c52ed8457bd7be955268845e1cf21ef5ee83fc22be2766ebec029edbca5eff0e3dd042c939a809ef826becfdc

data/README.md

@@ -96,6 +96,75 @@ calcutta_time == Time.utc(2042) # -> true
 calcutta_time.eql? Time.utc(2042) # -> false
 ```
 
+#### Handling Period Not Found
+
+Some periods do not exist. This is a problem you do not have to worry about as soon as you have successfully constructed a `Teasy::TimeWithZone` object, since all operations on existing `TimeWithZone` objects are safe in that way.
+However, construction may fail when you choose invalid parameters. E.g., `Teasy::TimeWithZone.new(2014, 3, 30, 2, 30, 0, 0, 'Europe/Berlin')` does not exist since time advanced from 2 a.m. to 3 a.m. local time in the CET time zone on March the 30th, 2014 and thus no 2:30 a.m. exists.
+
+By default we will raise a `TZInfo::PeriodNotFound` exception in this case. However, you may want to change this behaviour by defining a different period not found handler.
+
+```ruby
+# the default handler
+Teasy.period_not_found_handler = :raise
+Teasy::TimeWithZone.new(2014, 3, 30, 2, 30, 0, 0, 'Europe/Berlin')
+# => TZInfo::PeriodNotFound: TZInfo::PeriodNotFound
+
+# tell teasy to default to the previous period
+Teasy.period_not_found_handler = :next_period
+Teasy::TimeWithZone.new(2014, 3, 30, 2, 30, 0, 0, 'Europe/Berlin')
+# => 2014-03-30 03:00:00 +0200
+
+# tell teasy to default to the previous period
+Teasy.period_not_found_handler = :previous_period
+Teasy::TimeWithZone.new(2014, 3, 30, 2, 30, 0, 0, 'Europe/Berlin')
+# => 2014-03-30 02:00:00 +0100
+
+# or define a custom handler, it has to be callable and will receive a time object without
+# zone information (it says UTC but it's not!) and the zone information object
+Teasy.period_not_found_handler = lambda do |time, zone|
+  warn "#{time} does not exist for #{zone}"
+  Teasy::TimeWithZone.new(time.year)
+end
+```
+
+If you want to change the behaviour for just one piece of code, the you can use the `Teasy::with_period_not_found_handler` method with a block.
+
+#### Handling Ambiguous Time
+
+Similarly to how some periods do not exist, sometimes time is ambiguous. Missing periods are the result from forward shifts in time, ambiguous time is due to backward shifts in time. E.g., `Teasy::TimeWithZone.new(2014, 10, 26, 2, 0, 0, 0, 'Europe/Berlin')` is ambiguous since the daylight savings time ended at 3 a.m. local time in central europe and the clocks were turned back to 2 a.m. Therefore it could be either CET (+1) or CEST (+2), you just cannot know.
+
+By default we will raise a `TZInfo::AmbiguousTime` exception when this happens. However, you may, again, change the default behaviour in general or for a specific piece of code, like this:
+
+```ruby
+# the default handler
+Teasy.ambiguous_time_handler = :raise
+Teasy::TimeWithZone.new(2014, 10, 26, 2, 0, 0, 0, 'Europe/Berlin')
+# => TZInfo::AmbiguousTime: 2014-10-26 02:00:00 UTC is an ambiguous local time
+
+# tell teasy to default to the daylight savings time
+Teasy.ambiguous_time_handler = :daylight_savings_time
+Teasy::TimeWithZone.new(2014, 10, 26, 2, 0, 0, 0, 'Europe/Berlin')
+# => 2014-10-26 02:00:00 +0200
+
+# conversely tell teasy to default to the standard time
+Teasy.ambiguous_time_handler = :standard_time
+Teasy::TimeWithZone.new(2014, 10, 26, 2, 0, 0, 0, 'Europe/Berlin')
+# => 2014-10-26 02:00:00 +0100
+
+# or define a custom handler, it has to be callable and will receive a time object without
+# zone information (it says UTC but it's not!) and the candidate periods. The periods are
+# sorted by time and the block has to return a single period to resolve the ambiguity.
+Teasy.ambiguous_time_handler = lambda do |time, periods|
+  if time.minute < 30
+    periods.first
+  else
+    periods.last
+  end
+end
+```
+
+Of course there's also a `Teasy::with_ambiguous_time_handler` methods that accepts a block and will reset the handler after the block.
+
 ### FloatingTime
 #### Create a FloatingTime object
 ```ruby
@@ -136,6 +205,10 @@ floating_time == other_ny_time # -> false
 [Time.utc(2042), ny_time, other_ny_time].any? { |time| floating_time.eql? time } # -> false
 ```
 
+#### Convert to a TimeWithZone
+
+Simply call `in_time_zone` with a specific timezone to convert a floating time into a time with a zone, if the time exists in the given timezone, you shall get a `TimeWithZone` object.
+
 ## Contributing
 
 1. Fork it ( https://github.com/kaikuchn/teasy/fork )

data/lib/teasy.rb

@@ -3,21 +3,28 @@
 require 'teasy/version'
 require 'teasy/time_with_zone'
 require 'teasy/floating_time'
+require 'teasy/ambiguous_time_handling'
+require 'teasy/period_not_found_handling'
 
 module Teasy
-  def self.default_zone
-    Thread.current[:teasy_default_zone] ||= 'UTC'
-  end
+  include AmbiguousTimeHandling
+  include PeriodNotFoundHandling
 
-  def self.default_zone=(zone)
-    Thread.current[:teasy_default_zone] = zone
-  end
+  class << self
+    def default_zone
+      Thread.current[:teasy_default_zone] ||= 'UTC'
+    end
+
+    def default_zone=(zone)
+      Thread.current[:teasy_default_zone] = zone
+    end
 
-  def self.with_zone(zone)
-    old_zone = Thread.current[:teasy_default_zone]
-    Thread.current[:teasy_default_zone] = zone
-    yield
-  ensure
-    Thread.current[:teasy_default_zone] = old_zone
+    def with_zone(zone)
+      old_zone = default_zone
+      self.default_zone = zone
+      yield
+    ensure
+      self.default_zone = old_zone
+    end
   end
 end

data/lib/teasy/ambiguous_time_handling.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Teasy
+  module AmbiguousTimeHandling
+    UnknownAmbiguousTimeHandler = Class.new(StandardError)
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def ambiguous_time_handler
+        Thread.current[:teasy_ambiguous_time_handler] ||= HANDLER[:raise]
+      end
+
+      def ambiguous_time_handler=(name_or_callable)
+        if name_or_callable.respond_to?(:call)
+          Thread.current[:teasy_ambiguous_time_handler] = name_or_callable
+        else
+          Thread.current[:teasy_ambiguous_time_handler] = HANDLER.fetch(
+            name_or_callable.to_sym
+          ) do |key|
+            raise UnknownAmbiguousTimeHandler,
+                  "Don't know an ambiguous time handler `#{key}`."
+          end
+        end
+      end
+
+      def with_ambiguous_time_handler(handler)
+        old_handler = ambiguous_time_handler
+        self.ambiguous_time_handler = handler
+        yield
+      ensure
+        self.ambiguous_time_handler = old_handler
+      end
+
+      HANDLER = {
+        # By returning nil TZInfo will raise TZInfo::AmbigousTime. It'd be
+        # better to raise our own error, but that would break the API that's out
+        # there. So that will have to wait for a 1.x release.
+        raise:                 ->(_time, _periods) {},
+        daylight_savings_time: ->(_time, periods)  { periods.select(&:dst?) },
+        standard_time:         ->(_time, periods)  { periods.reject(&:dst?) }
+      }.freeze
+    end
+  end
+end

data/lib/teasy/floating_time.rb

@@ -25,6 +25,10 @@ module Teasy
           time.hour, time.min, time.sec, time.nsec / 1_000.0)
     end
 
+    def in_time_zone(zone)
+      Teasy.with_zone(zone) { TimeWithZone.from_time(self) }
+    end
+
     def round!(*args)
       @time = time.round(*args)
       self

data/lib/teasy/period_not_found_handling.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Teasy
+  module PeriodNotFoundHandling
+    UnknownPeriodNotFoundHandler = Class.new(StandardError)
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def period_not_found_handler
+        Thread.current[:teasy_period_not_found_handler] ||= HANDLER[:raise]
+      end
+
+      def period_not_found_handler=(name_or_callable)
+        if name_or_callable.respond_to?(:call)
+          Thread.current[:teasy_period_not_found_handler] = name_or_callable
+        else
+          Thread.current[:teasy_period_not_found_handler] = HANDLER.fetch(
+            name_or_callable.to_sym
+          ) do |key|
+            raise UnknownPeriodNotFoundHandler,
+                  "Don't know a PeriodNotFound handler `#{key}`."
+          end
+        end
+      end
+
+      def with_period_not_found_handler(handler)
+        old_handler = period_not_found_handler
+        self.period_not_found_handler = handler
+        yield
+      ensure
+        self.period_not_found_handler = old_handler
+      end
+
+      HANDLER = {
+        raise:           ->(_time, _zone) { raise },
+        # the biggest change in offsets known to me is when Samoa went from -11
+        # to +13 (a full day!) so hopefully we're sure to leave the unknown
+        # period by adding/subtracting 3 days
+        next_period:     lambda do |time, zone|
+          period = zone.period_for_local(time + 3 * 86_400)
+          [period, period.start_transition.time + period.utc_total_offset]
+        end,
+        previous_period: lambda do |time, zone|
+          period = zone.period_for_local(time - 3 * 86_400)
+          [period, period.end_transition.time + period.utc_total_offset]
+        end
+      }.freeze
+    end
+  end
+end

data/lib/teasy/time_with_zone.rb

@@ -24,7 +24,7 @@ module Teasy
                    zone = Teasy.default_zone)
       @zone = TZInfo::Timezone.get(zone)
       @time = Time.utc(year, month, day, hour, minute, second, usec_with_frac)
-      @period = @zone.period_for_local(@time)
+      @period = determine_period(@time, @zone)
     end
     # rubocop:enable Metrics/ParameterLists
 
@@ -148,6 +148,16 @@ module Teasy
 
     private
 
+    def determine_period(time, zone = Teasy.default_zone)
+      zone.period_for_local(time) do |results|
+        Teasy.ambiguous_time_handler.call(time, results)
+      end
+    rescue TZInfo::PeriodNotFound
+      period, time = Teasy.period_not_found_handler.call(time, zone)
+      @time = time
+      period
+    end
+
     def utc_time
       @utc_time ||= @zone.local_to_utc(@time)
     end

data/lib/teasy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Teasy
-  VERSION = '0.1.3'
+  VERSION = '0.2.0'.freeze
 end

data/test/teasy/floating_time_test.rb

@@ -23,6 +23,20 @@ class FloatingTimeTest < Minitest::Test
     assert_equal 0, timestamp.hour
   end
 
+  def test_in_time_zone
+    time = Teasy::FloatingTime.new(2014, 1, 1, 12)
+    assert_equal Time.utc(2014, 1, 1, 11), time.in_time_zone('Europe/Berlin')
+    assert_equal Time.utc(2014, 1, 1, 12), time.in_time_zone('Europe/London')
+    assert_equal Time.utc(2014, 1, 1, 6, 30), time.in_time_zone('Asia/Calcutta')
+    assert_equal Time.utc(2014, 1, 1, 17), time.in_time_zone('America/New_York')
+    assert_raises(TZInfo::AmbiguousTime) do
+      Teasy::FloatingTime.new(2014, 10, 26, 2).in_time_zone('Europe/Berlin')
+    end
+    assert_raises(TZInfo::PeriodNotFound) do
+      Teasy::FloatingTime.new(2014, 3, 30, 2, 30).in_time_zone('Europe/Berlin')
+    end
+  end
+
   def test_addition
     assert_equal 45, @timestamp.sec
     @timestamp += 5

data/test/teasy/time_with_zone_test.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'test_helper'
 
 class TimeWithZoneTest < Minitest::Test
@@ -76,17 +78,49 @@ class TimeWithZoneTest < Minitest::Test
     assert dst_start.dst?
   end
 
-  def test_raises_on_ambiguous_time
+  def test_call_ambiguous_time_handler_on_ambiguous_time
     dst_end = [2014, 10, 26, 2, 0, 0, 0, 'Europe/Berlin']
+    # raise is default
     assert_raises(TZInfo::AmbiguousTime) do
       Teasy::TimeWithZone.new(*dst_end)
     end
+
+    Teasy.with_ambiguous_time_handler(:daylight_savings_time) do
+      time = Teasy::TimeWithZone.new(*dst_end)
+      assert time.dst?
+      assert_equal 2, time.hour
+    end
+
+    Teasy.with_ambiguous_time_handler(:standard_time) do
+      time = Teasy::TimeWithZone.new(*dst_end)
+      refute time.dst?
+      assert_equal 2, time.hour
+    end
   end
 
-  def test_raises_when_period_does_not_exist
-    dst_start = [2014, 3, 30, 2, 30, 0, 0, 'Europe/Berlin']
-    assert_raises(TZInfo::PeriodNotFound) do
-      Teasy::TimeWithZone.new(*dst_start)
+  def test_call_period_not_found_handler_when_period_does_not_exist
+    Teasy.with_zone('Europe/Berlin') do
+      dst_start = [2014, 3, 30, 2, 30, 0, 0]
+      # raise is default
+      assert_raises(TZInfo::PeriodNotFound) do
+        Teasy::TimeWithZone.new(*dst_start)
+      end
+
+      Teasy.with_period_not_found_handler(:next_period) do
+        time = Teasy::TimeWithZone.new(*dst_start)
+        assert time.dst?
+        assert_equal(
+          Teasy::TimeWithZone.new(2014, 3, 30, 3), time
+        )
+      end
+
+      Teasy.with_period_not_found_handler(:previous_period) do
+        time = Teasy::TimeWithZone.new(*dst_start)
+        refute time.dst?
+        assert_equal(
+          Teasy::TimeWithZone.new(2014, 3, 30, 2), time
+        )
+      end
     end
   end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: teasy
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
 platform: ruby
 authors:
 - Kai Kuchenbecker
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-05-31 00:00:00.000000000 Z
+date: 2017-06-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: tzinfo
@@ -127,7 +127,9 @@ files:
 - README.md
 - Rakefile
 - lib/teasy.rb
+- lib/teasy/ambiguous_time_handling.rb
 - lib/teasy/floating_time.rb
+- lib/teasy/period_not_found_handling.rb
 - lib/teasy/time_with_zone.rb
 - lib/teasy/version.rb
 - teasy.gemspec