tzinfo 1.2.11 → 2.0.6

data/lib/tzinfo/transition_rule.rb

@@ -1,79 +1,96 @@
-require 'date'
+# encoding: UTF-8
+# frozen_string_literal: true
 
 module TZInfo
   # Base class for rules definining the transition between standard and daylight
   # savings time.
+  #
+  # @abstract
+  # @private
   class TransitionRule #:nodoc:
     # Returns the number of seconds after midnight local time on the day
     # identified by the rule at which the transition occurs. Can be negative to
     # denote a time on the prior day. Can be greater than or equal to 86,400 to
     # denote a time of the following day.
+    #
+    # @return [Integer] the time in seconds after midnight local time at which
+    #   the transition occurs.
     attr_reader :transition_at
 
-    # Initializes a new TransitionRule.
+    # Initializes a new {TransitionRule}.
+    #
+    # @param transition_at [Integer] the time in seconds after midnight local
+    #   time at which the transition occurs.
+    # @raise [ArgumentError] if `transition_at` is not an `Integer`.
     def initialize(transition_at)
       raise ArgumentError, 'Invalid transition_at' unless transition_at.kind_of?(Integer)
       @transition_at = transition_at
     end
 
-    # Calculates the UTC time of the transition from a given offset on a given
-    # year.
+    # Calculates the time of the transition from a given offset on a given year.
+    #
+    # @param offset [TimezoneOffset] the current offset at the time the rule
+    #   will transition.
+    # @param year [Integer] the year in which the transition occurs (local
+    #   time).
+    # @return [TimestampWithOffset] the time at which the transition occurs.
     def at(offset, year)
-      day = get_day(year)
-      day.add_with_convert(@transition_at - offset.utc_total_offset)
+      day = get_day(offset, year)
+      TimestampWithOffset.set_timezone_offset(Timestamp.for(day + @transition_at), offset)
     end
 
-    # Determines if this TransitionRule is equal to another instance.
+    # Determines if this {TransitionRule} is equal to another instance.
+    #
+    # @param r [Object] the instance to test for equality.
+    # @return [Boolean] `true` if `r` is a {TransitionRule} with the same
+    #   {transition_at} as this {TransitionRule}, otherwise `false`.
     def ==(r)
       r.kind_of?(TransitionRule) && @transition_at == r.transition_at
     end
     alias eql? ==
 
-    # Returns a hash based on hash_args (defaulting to transition_at).
+    # @return [Integer] a hash based on {hash_args} (defaulting to
+    #  {transition_at}).
     def hash
       hash_args.hash
     end
 
     protected
 
-    # Returns an Array of parameters that will influence the output of hash.
+    # @return [Array] an `Array` of parameters that will influence the output of
+    #  {hash}.
     def hash_args
       [@transition_at]
     end
-
-    def new_time_or_datetime(year, month = 1, day = 1)
-      result = if ((year >= 2039 || (year == 2038 && (month >= 2 || (month == 1 && day >= 20)))) && !RubyCoreSupport.time_supports_64bit) ||
-        (year < 1970 && !RubyCoreSupport.time_supports_negative)
-
-        # Time handles 29 February on a non-leap year as 1 March.
-        # DateTime rejects. Advance manually.
-        if month == 2 && day == 29 && !Date.gregorian_leap?(year)
-          month = 3
-          day = 1
-        end
-
-        RubyCoreSupport.datetime_new(year, month, day)
-      else
-        Time.utc(year, month, day)
-      end
-
-      TimeOrDateTime.wrap(result)
-    end
   end
+  private_constant :TransitionRule
 
   # A base class for transition rules that activate based on an integer day of
   # the year.
   #
+  # @abstract
   # @private
   class DayOfYearTransitionRule < TransitionRule #:nodoc:
-    # Initializes a new DayOfYearTransitionRule.
+    # Initializes a new {DayOfYearTransitionRule}.
+    #
+    # @param day [Integer] the day of the year on which the transition occurs.
+    #   The precise meaning is defined by subclasses.
+    # @param transition_at [Integer] the time in seconds after midnight local
+    #   time at which the transition occurs.
+    # @raise [ArgumentError] if `transition_at` is not an `Integer`.
+    # @raise [ArgumentError] if `day` is not an `Integer`.
     def initialize(day, transition_at)
       super(transition_at)
       raise ArgumentError, 'Invalid day' unless day.kind_of?(Integer)
       @seconds = day * 86400
     end
 
-    # Determines if this DayOfYearTransitionRule is equal to another instance.
+    # Determines if this {DayOfYearTransitionRule} is equal to another instance.
+    #
+    # @param r [Object] the instance to test for equality.
+    # @return [Boolean] `true` if `r` is a {DayOfYearTransitionRule} with the
+    #   same {transition_at} and day as this {DayOfYearTransitionRule},
+    #   otherwise `false`.
     def ==(r)
       super(r) && r.kind_of?(DayOfYearTransitionRule) && @seconds == r.seconds
     end
@@ -84,11 +101,12 @@ module TZInfo
     # @return [Integer] the day multipled by the number of seconds in a day.
     attr_reader :seconds
 
-    # Returns an Array of parameters that will influence the output of hash.
+    # (see TransitionRule#hash_args)
     def hash_args
       [@seconds] + super
     end
   end
+  private_constant :DayOfYearTransitionRule
 
   # Defines transitions that occur on the zero-based nth day of the year.
   #
@@ -100,25 +118,38 @@ module TZInfo
   #
   # @private
   class AbsoluteDayOfYearTransitionRule < DayOfYearTransitionRule #:nodoc:
-    # Initializes a new AbsoluteDayOfYearTransitionRule.
+    # Initializes a new {AbsoluteDayOfYearTransitionRule}.
+    #
+    # @param day [Integer] the zero-based day of the year on which the
+    #   transition occurs (0 to 365 inclusive).
+    # @param transition_at [Integer] the time in seconds after midnight local
+    #   time at which the transition occurs.
+    # @raise [ArgumentError] if `transition_at` is not an `Integer`.
+    # @raise [ArgumentError] if `day` is not an `Integer`.
+    # @raise [ArgumentError] if `day` is less than 0 or greater than 365.
     def initialize(day, transition_at = 0)
       super(day, transition_at)
       raise ArgumentError, 'Invalid day' unless day >= 0 && day <= 365
     end
 
-    # Returns true if the day specified by this transition is the first in the
-    # year (a day number of 0), otherwise false.
+    # @return [Boolean] `true` if the day specified by this transition is the
+    #   first in the year (a day number of 0), otherwise `false`.
     def is_always_first_day_of_year?
       seconds == 0
     end
 
-    # @returns false.
+    # @return [Boolean] `false`.
     def is_always_last_day_of_year?
       false
     end
 
-    # Determines if this AbsoluteDayOfYearTransitionRule is equal to another
+    # Determines if this {AbsoluteDayOfYearTransitionRule} is equal to another
     # instance.
+    #
+    # @param r [Object] the instance to test for equality.
+    # @return [Boolean] `true` if `r` is a {AbsoluteDayOfYearTransitionRule}
+    #   with the same {transition_at} and day as this
+    #   {AbsoluteDayOfYearTransitionRule}, otherwise `false`.
     def ==(r)
       super(r) && r.kind_of?(AbsoluteDayOfYearTransitionRule)
     end
@@ -126,13 +157,19 @@ module TZInfo
 
     protected
 
-    # Returns a TimeOrDateTime representing midnight local time on the day
-    # specified by the rule for the given offset and year.
-    def get_day(year)
-      new_time_or_datetime(year).add_with_convert(seconds)
+    # Returns a `Time` representing midnight local time on the day specified by
+    # the rule for the given offset and year.
+    #
+    # @param offset [TimezoneOffset] the current offset at the time of the
+    #  transition.
+    # @param year [Integer] the year in which the transition occurs.
+    # @return [Time] midnight local time on the day specified by the rule for
+    #  the given offset and year.
+    def get_day(offset, year)
+      Time.new(year, 1, 1, 0, 0, 0, offset.observed_utc_offset) + seconds
     end
 
-    # Returns an Array of parameters that will influence the output of hash.
+    # (see TransitionRule#hash_args)
     def hash_args
       [AbsoluteDayOfYearTransitionRule] + super
     end
@@ -147,30 +184,45 @@ module TZInfo
   class JulianDayOfYearTransitionRule < DayOfYearTransitionRule #:nodoc:
     # The 60 days in seconds.
     LEAP = 60 * 86400
+    private_constant :LEAP
 
     # The length of a non-leap year in seconds.
     YEAR = 365 * 86400
-
-    # Initializes a new JulianDayOfYearTransitionRule.
+    private_constant :YEAR
+
+    # Initializes a new {JulianDayOfYearTransitionRule}.
+    #
+    # @param day [Integer] the one-based Julian day of the year on which the
+    #   transition occurs (1 to 365 inclusive).
+    # @param transition_at [Integer] the time in seconds after midnight local
+    #   time at which the transition occurs.
+    # @raise [ArgumentError] if `transition_at` is not an `Integer`.
+    # @raise [ArgumentError] if `day` is not an `Integer`.
+    # @raise [ArgumentError] if `day` is less than 1 or greater than 365.
     def initialize(day, transition_at = 0)
       super(day, transition_at)
       raise ArgumentError, 'Invalid day' unless day >= 1 && day <= 365
     end
 
-    # Returns true if the day specified by this transition is the first in the
-    # year (a day number of 1), otherwise false.
+    # @return [Boolean] `true` if the day specified by this transition is the
+    #   first in the year (a day number of 1), otherwise `false`.
     def is_always_first_day_of_year?
       seconds == 86400
     end
 
-    # Returns true if the day specified by this transition is the last in the
-    # year (a day number of 365), otherwise false.
+    # @return [Boolean] `true` if the day specified by this transition is the
+    #   last in the year (a day number of 365), otherwise `false`.
     def is_always_last_day_of_year?
       seconds == YEAR
     end
 
-    # Determines if this JulianDayOfYearTransitionRule is equal to another
+    # Determines if this {JulianDayOfYearTransitionRule} is equal to another
     # instance.
+    #
+    # @param r [Object] the instance to test for equality.
+    # @return [Boolean] `true` if `r` is a {JulianDayOfYearTransitionRule} with
+    #   the same {transition_at} and day as this
+    #   {JulianDayOfYearTransitionRule}, otherwise `false`.
     def ==(r)
       super(r) && r.kind_of?(JulianDayOfYearTransitionRule)
     end
@@ -178,28 +230,47 @@ module TZInfo
 
     protected
 
-    # Returns a TimeOrDateTime representing midnight local time on the day
-    # specified by the rule for the given offset and year.
-    def get_day(year)
+    # Returns a `Time` representing midnight local time on the day specified by
+    # the rule for the given offset and year.
+    #
+    # @param offset [TimezoneOffset] the current offset at the time of the
+    #  transition.
+    # @param year [Integer] the year in which the transition occurs.
+    # @return [Time] midnight local time on the day specified by the rule for
+    #  the given offset and year.
+    def get_day(offset, year)
       # Returns 1 March on non-leap years.
-      leap = new_time_or_datetime(year, 2, 29)
+      leap = Time.new(year, 2, 29, 0, 0, 0, offset.observed_utc_offset)
       diff = seconds - LEAP
       diff += 86400 if diff >= 0 && leap.mday == 29
-      leap.add_with_convert(diff)
+      leap + diff
     end
 
-    # Returns an Array of parameters that will influence the output of hash.
+    # (see TransitionRule#hash_args)
     def hash_args
       [JulianDayOfYearTransitionRule] + super
     end
   end
+  private_constant :JulianDayOfYearTransitionRule
 
   # A base class for rules that transition on a particular day of week of a
   # given week (subclasses specify which week of the month).
   #
+  # @abstract
   # @private
   class DayOfWeekTransitionRule < TransitionRule #:nodoc:
-    # Initializes a new DayOfWeekTransitionRule.
+    # Initializes a new {DayOfWeekTransitionRule}.
+    #
+    # @param month [Integer] the month of the year when the transition occurs.
+    # @param day_of_week [Integer] the day of the week when the transition
+    #   occurs. 0 is Sunday, 6 is Saturday.
+    # @param transition_at [Integer] the time in seconds after midnight local
+    #   time at which the transition occurs.
+    # @raise [ArgumentError] if `transition_at` is not an `Integer`.
+    # @raise [ArgumentError] if `month` is not an `Integer`.
+    # @raise [ArgumentError] if `month` is less than 1 or greater than 12.
+    # @raise [ArgumentError] if `day_of_week` is not an `Integer`.
+    # @raise [ArgumentError] if `day_of_week` is less than 0 or greater than 6.
     def initialize(month, day_of_week, transition_at)
       super(transition_at)
       raise ArgumentError, 'Invalid month' unless month.kind_of?(Integer) && month >= 1 && month <= 12
@@ -208,17 +279,23 @@ module TZInfo
       @day_of_week = day_of_week
     end
 
-    # Returns false.
+    # @return [Boolean] `false`.
     def is_always_first_day_of_year?
       false
     end
 
-    # Returns false.
+    # @return [Boolean] `false`.
     def is_always_last_day_of_year?
       false
     end
 
-    # Determines if this DayOfWeekTransitionRule is equal to another instance.
+    # Determines if this {DayOfWeekTransitionRule} is equal to another
+    # instance.
+    #
+    # @param r [Object] the instance to test for equality.
+    # @return [Boolean] `true` if `r` is a {DayOfWeekTransitionRule} with the
+    #   same {transition_at}, month and day of week as this
+    #   {DayOfWeekTransitionRule}, otherwise `false`.
     def ==(r)
       super(r) && r.kind_of?(DayOfWeekTransitionRule) && @month == r.month && @day_of_week == r.day_of_week
     end
@@ -226,31 +303,53 @@ module TZInfo
 
     protected
 
-    # Returns the month of the year (1 to 12).
+    # @return [Integer] the month of the year (1 to 12).
     attr_reader :month
 
-    # Returns the day of the week (0 to 6 for Sunday to Monday).
+    # @return [Integer] the day of the week (0 to 6 for Sunday to Monday).
     attr_reader :day_of_week
 
-    # Returns an Array of parameters that will influence the output of hash.
+    # (see TransitionRule#hash_args)
     def hash_args
       [@month, @day_of_week] + super
     end
   end
+  private_constant :DayOfWeekTransitionRule
 
   # A rule that transitions on the nth occurrence of a particular day of week
   # of a calendar month.
   #
   # @private
   class DayOfMonthTransitionRule < DayOfWeekTransitionRule #:nodoc:
-    # Initializes a new DayOfMonthTransitionRule.
+    # Initializes a new {DayOfMonthTransitionRule}.
+    #
+    # @param month [Integer] the month of the year when the transition occurs.
+    # @param week [Integer] the week of the month when the transition occurs (1
+    #   to 4).
+    # @param day_of_week [Integer] the day of the week when the transition
+    #   occurs. 0 is Sunday, 6 is Saturday.
+    # @param transition_at [Integer] the time in seconds after midnight local
+    #   time at which the transition occurs.
+    # @raise [ArgumentError] if `transition_at` is not an `Integer`.
+    # @raise [ArgumentError] if `month` is not an `Integer`.
+    # @raise [ArgumentError] if `month` is less than 1 or greater than 12.
+    # @raise [ArgumentError] if `week` is not an `Integer`.
+    # @raise [ArgumentError] if `week` is less than 1 or greater than 4.
+    # @raise [ArgumentError] if `day_of_week` is not an `Integer`.
+    # @raise [ArgumentError] if `day_of_week` is less than 0 or greater than 6.
     def initialize(month, week, day_of_week, transition_at = 0)
       super(month, day_of_week, transition_at)
       raise ArgumentError, 'Invalid week' unless week.kind_of?(Integer) && week >= 1 && week <= 4
       @offset_start = (week - 1) * 7 + 1
     end
 
-    # Determines if this DayOfMonthTransitionRule is equal to another instance.
+    # Determines if this {DayOfMonthTransitionRule} is equal to another
+    # instance.
+    #
+    # @param r [Object] the instance to test for equality.
+    # @return [Boolean] `true` if `r` is a {DayOfMonthTransitionRule} with the
+    #   same {transition_at}, month, week and day of week as this
+    #   {DayOfMonthTransitionRule}, otherwise `false`.
     def ==(r)
       super(r) && r.kind_of?(DayOfMonthTransitionRule) && @offset_start == r.offset_start
     end
@@ -258,42 +357,66 @@ module TZInfo
 
     protected
 
-    # Returns the day the week starts on for a month starting on a Sunday.
+    # @return [Integer] the day the week starts on for a month starting on a
+    #   Sunday.
     attr_reader :offset_start
 
-    # Returns a TimeOrDateTime representing midnight local time on the day
-    # specified by the rule for the given offset and year.
-    def get_day(year)
-      candidate = new_time_or_datetime(year, month, @offset_start)
+    # Returns a `Time` representing midnight local time on the day specified by
+    # the rule for the given offset and year.
+    #
+    # @param offset [TimezoneOffset] the current offset at the time of the
+    #  transition.
+    # @param year [Integer] the year in which the transition occurs.
+    # @return [Time] midnight local time on the day specified by the rule for
+    #  the given offset and year.
+    def get_day(offset, year)
+      candidate = Time.new(year, month, @offset_start, 0, 0, 0, offset.observed_utc_offset)
       diff = day_of_week - candidate.wday
 
       if diff < 0
-        candidate.add_with_convert((7 + diff) * 86400)
+        candidate + (7 + diff) * 86400
       elsif diff > 0
-        candidate.add_with_convert(diff * 86400)
+        candidate + diff * 86400
       else
         candidate
       end
     end
 
-    # Returns an Array of parameters that will influence the output of hash.
+    # (see TransitionRule#hash_args)
     def hash_args
       [@offset_start] + super
     end
   end
+  private_constant :DayOfMonthTransitionRule
 
   # A rule that transitions on the last occurrence of a particular day of week
   # of a calendar month.
   #
   # @private
   class LastDayOfMonthTransitionRule < DayOfWeekTransitionRule #:nodoc:
-    # Initializes a new LastDayOfMonthTransitionRule.
+    # Initializes a new {LastDayOfMonthTransitionRule}.
+    #
+    # @param month [Integer] the month of the year when the transition occurs.
+    # @param day_of_week [Integer] the day of the week when the transition
+    #   occurs. 0 is Sunday, 6 is Saturday.
+    # @param transition_at [Integer] the time in seconds after midnight local
+    #   time at which the transition occurs.
+    # @raise [ArgumentError] if `transition_at` is not an `Integer`.
+    # @raise [ArgumentError] if `month` is not an `Integer`.
+    # @raise [ArgumentError] if `month` is less than 1 or greater than 12.
+    # @raise [ArgumentError] if `day_of_week` is not an `Integer`.
+    # @raise [ArgumentError] if `day_of_week` is less than 0 or greater than 6.
     def initialize(month, day_of_week, transition_at = 0)
       super(month, day_of_week, transition_at)
     end
 
-    # Determines if this LastDayOfMonthTransitionRule is equal to another
+    # Determines if this {LastDayOfMonthTransitionRule} is equal to another
     # instance.
+    #
+    # @param r [Object] the instance to test for equality.
+    # @return [Boolean] `true` if `r` is a {LastDayOfMonthTransitionRule} with
+    #   the same {transition_at}, month and day of week as this
+    #   {LastDayOfMonthTransitionRule}, otherwise `false`.
     def ==(r)
       super(r) && r.kind_of?(LastDayOfMonthTransitionRule)
     end
@@ -301,16 +424,22 @@ module TZInfo
 
     protected
 
-    # Returns a TimeOrDateTime representing midnight local time on the day
-    # specified by the rule for the given offset and year.
-    def get_day(year)
+    # Returns a `Time` representing midnight local time on the day specified by
+    # the rule for the given offset and year.
+    #
+    # @param offset [TimezoneOffset] the current offset at the time of the
+    #  transition.
+    # @param year [Integer] the year in which the transition occurs.
+    # @return [Time] midnight local time on the day specified by the rule for
+    #  the given offset and year.
+    def get_day(offset, year)
       next_month = month + 1
       if next_month == 13
         year += 1
         next_month = 1
       end
 
-      candidate = new_time_or_datetime(year, next_month).add_with_convert(-86400)
+      candidate = Time.new(year, next_month, 1, 0, 0, 0, offset.observed_utc_offset) - 86400
       diff = candidate.wday - day_of_week
 
       if diff < 0
@@ -322,4 +451,5 @@ module TZInfo
       end
     end
   end
+  private_constant :LastDayOfMonthTransitionRule
 end

data/lib/tzinfo/transitions_timezone_period.rb

@@ -0,0 +1,63 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module TZInfo
+  # Represents a period of time in a time zone where the same offset from UTC
+  # applies. The period of time is bounded at at least one end, either having a
+  # start transition, end transition or both start and end transitions.
+  class TransitionsTimezonePeriod < TimezonePeriod
+    # @return [TimezoneTransition] the transition that defines the start of this
+    #   {TimezonePeriod} (`nil` if the start is unbounded).
+    attr_reader :start_transition
+
+    # @return [TimezoneTransition] the transition that defines the end of this
+    #   {TimezonePeriod} (`nil` if the end is unbounded).
+    attr_reader :end_transition
+
+    # Initializes a {TransitionsTimezonePeriod}.
+    #
+    # At least one of `start_transition` and `end_transition` must be specified.
+    #
+    # @param start_transition [TimezoneTransition] the transition that defines
+    #   the start of the period, or `nil` if the start is unbounded.
+    # @param end_transition [TimezoneTransition] the transition that defines the
+    #   end of the period, or `nil` if the end is unbounded.
+    # @raise [ArgumentError] if both `start_transition` and `end_transition` are
+    #   `nil`.
+    def initialize(start_transition, end_transition)
+      if start_transition
+        super(start_transition.offset)
+      elsif end_transition
+        super(end_transition.previous_offset)
+      else
+        raise ArgumentError, 'At least one of start_transition and end_transition must be specified'
+      end
+
+      @start_transition = start_transition
+      @end_transition = end_transition
+    end
+
+    # Determines if this {TransitionsTimezonePeriod} is equal to another
+    # instance.
+    #
+    # @param p [Object] the instance to test for equality.
+    # @return [Boolean] `true` if `p` is a {TransitionsTimezonePeriod} with the
+    #   same {offset}, {start_transition} and {end_transition}, otherwise
+    #   `false`.
+    def ==(p)
+      p.kind_of?(TransitionsTimezonePeriod) && start_transition == p.start_transition && end_transition == p.end_transition
+    end
+    alias eql? ==
+
+    # @return [Integer] a hash based on {start_transition} and {end_transition}.
+    def hash
+      [@start_transition, @end_transition].hash
+    end
+
+    # @return [String] the internal object state as a programmer-readable
+    #   `String`.
+    def inspect
+      "#<#{self.class}: @start_transition=#{@start_transition.inspect}, @end_transition=#{@end_transition.inspect}>"
+    end
+  end
+end

data/lib/tzinfo/version.rb

@@ -0,0 +1,7 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module TZInfo
+  # The TZInfo version number.
+  VERSION = '2.0.6'
+end

data/lib/tzinfo/with_offset.rb

@@ -0,0 +1,61 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module TZInfo
+  # The {WithOffset} module is included in {TimeWithOffset},
+  # {DateTimeWithOffset} and {TimestampWithOffset}. It provides an override for
+  # the {strftime} method that handles expanding the `%Z` directive according to
+  # the {TimezoneOffset#abbreviation abbreviation} of the {TimezoneOffset}
+  # associated with a local time.
+  module WithOffset
+    # Overrides the `Time`, `DateTime` or {Timestamp} version of `strftime`,
+    # replacing `%Z` with the {TimezoneOffset#abbreviation abbreviation} of the
+    # associated {TimezoneOffset}. If there is no associated offset, `%Z` is
+    # expanded by the base class instead.
+    #
+    # All the format directives handled by the base class are supported.
+    #
+    # @param format [String] the format string.
+    # @return [String] the formatted time.
+    # @raise [ArgumentError] if `format` is `nil`.
+    def strftime(format)
+      raise ArgumentError, 'format must be specified' unless format
+
+      if_timezone_offset do |o|
+        abbreviation = nil
+
+        format = format.gsub(/%(%*)Z/) do
+          if $1.length.odd?
+            # Return %%Z so the real strftime treats it as a literal %Z too.
+            "#$1%Z"
+          else
+            "#$1#{abbreviation ||= o.abbreviation.gsub(/%/, '%%')}"
+          end
+        end
+      end
+
+      super
+    end
+
+    protected
+
+    # Performs a calculation if there is an associated {TimezoneOffset}.
+    #
+    # @param result [Object] a result value that can be manipulated by the block
+    #   if there is an associated {TimezoneOffset}.
+    # @yield [period, result] if there is an associated {TimezoneOffset}, the
+    #   block is yielded to in order to calculate the method result.
+    # @yieldparam period [TimezoneOffset] the associated {TimezoneOffset}.
+    # @yieldparam result [Object] the `result` parameter.
+    # @yieldreturn [Object] the result of the calculation performed if there is
+    #   an associated {TimezoneOffset}.
+    # @return [Object] the result of the block if there is an associated
+    #   {TimezoneOffset}, otherwise the `result` parameter.
+    #
+    # @private
+    def if_timezone_offset(result = nil) #:nodoc:
+      to = timezone_offset
+      to ? yield(to, result) : result
+    end
+  end
+end