tzinfo 1.2.10 → 2.0.6

data/lib/tzinfo/timestamp.rb

@@ -0,0 +1,552 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module TZInfo
+  # A time represented as an `Integer` number of seconds since 1970-01-01
+  # 00:00:00 UTC (ignoring leap seconds and using the proleptic Gregorian
+  # calendar), the fraction through the second (sub_second as a `Rational`) and
+  # an optional UTC offset. Like Ruby's `Time` class, {Timestamp} can
+  # distinguish between a local time with a zero offset and a time specified
+  # explicitly as UTC.
+  class Timestamp
+    include Comparable
+
+    # The Unix epoch (1970-01-01 00:00:00 UTC) as a chronological Julian day
+    # number.
+    JD_EPOCH = 2440588
+    private_constant :JD_EPOCH
+
+    class << self
+      # Returns a new {Timestamp} representing the (proleptic Gregorian
+      # calendar) date and time specified by the supplied parameters.
+      #
+      # If `utc_offset` is `nil`, `:utc` or 0, the date and time parameters will
+      # be interpreted as representing a UTC date and time. Otherwise the date
+      # and time parameters will be interpreted as a local date and time with
+      # the given offset.
+      #
+      # @param year [Integer] the year.
+      # @param month [Integer] the month (1-12).
+      # @param day [Integer] the day of the month (1-31).
+      # @param hour [Integer] the hour (0-23).
+      # @param minute [Integer] the minute (0-59).
+      # @param second [Integer] the second (0-59).
+      # @param sub_second [Numeric] the fractional part of the second as either
+      #   a `Rational` that is greater than or equal to 0 and less than 1, or
+      #   the `Integer` 0.
+      # @param utc_offset [Object] either `nil` for a {Timestamp} without a
+      #   specified offset, an offset from UTC specified as an `Integer` number
+      #   of seconds or the `Symbol` `:utc`).
+      # @return [Timestamp] a new {Timestamp} representing the specified
+      #   (proleptic Gregorian calendar) date and time.
+      # @raise [ArgumentError] if either of `year`, `month`, `day`, `hour`,
+      #   `minute`, or `second` is not an `Integer`.
+      # @raise [ArgumentError] if `sub_second` is not a `Rational`, or the
+      #   `Integer` 0.
+      # @raise [ArgumentError] if `utc_offset` is not `nil`, not an `Integer`
+      #   and not the `Symbol` `:utc`.
+      # @raise [RangeError] if `month` is not between 1 and 12.
+      # @raise [RangeError] if `day` is not between 1 and 31.
+      # @raise [RangeError] if `hour` is not between 0 and 23.
+      # @raise [RangeError] if `minute` is not between 0 and 59.
+      # @raise [RangeError] if `second` is not between 0 and 59.
+      # @raise [RangeError] if `sub_second` is a `Rational` but that is less
+      #   than 0 or greater than or equal to 1.
+      def create(year, month = 1, day = 1, hour = 0, minute = 0, second = 0, sub_second = 0, utc_offset = nil)
+        raise ArgumentError, 'year must be an Integer' unless year.kind_of?(Integer)
+        raise ArgumentError, 'month must be an Integer' unless month.kind_of?(Integer)
+        raise ArgumentError, 'day must be an Integer' unless day.kind_of?(Integer)
+        raise ArgumentError, 'hour must be an Integer' unless hour.kind_of?(Integer)
+        raise ArgumentError, 'minute must be an Integer' unless minute.kind_of?(Integer)
+        raise ArgumentError, 'second must be an Integer' unless second.kind_of?(Integer)
+        raise RangeError, 'month must be between 1 and 12' if month < 1 || month > 12
+        raise RangeError, 'day must be between 1 and 31' if day < 1 || day > 31
+        raise RangeError, 'hour must be between 0 and 23' if hour < 0 || hour > 23
+        raise RangeError, 'minute must be between 0 and 59' if minute < 0 || minute > 59
+        raise RangeError, 'second must be between 0 and 59' if second < 0 || second > 59
+
+        # Based on days_from_civil from https://howardhinnant.github.io/date_algorithms.html#days_from_civil
+        after_february = month > 2
+        year -= 1 unless after_february
+        era = year / 400
+        year_of_era = year - era * 400
+        day_of_year = (153 * (month + (after_february ? -3 : 9)) + 2) / 5 + day - 1
+        day_of_era = year_of_era * 365 + year_of_era / 4 - year_of_era / 100 + day_of_year
+        days_since_epoch = era * 146097 + day_of_era - 719468
+        value = ((days_since_epoch * 24 + hour) * 60 + minute) * 60 + second
+        value -= utc_offset if utc_offset.kind_of?(Integer)
+
+        new(value, sub_second, utc_offset)
+      end
+
+      # When used without a block, returns a {Timestamp} representation of a
+      # given `Time`, `DateTime` or {Timestamp}.
+      #
+      # When called with a block, the {Timestamp} representation of `value` is
+      # passed to the block. The block must then return a {Timestamp}, which
+      # will be converted back to the type of the initial value. If the initial
+      # value was a {Timestamp}, the block result will be returned. If the
+      # initial value was a `DateTime`, a Gregorian `DateTime` will be returned.
+      #
+      # The UTC offset of `value` can either be preserved (the {Timestamp}
+      # representation will have the same UTC offset as `value`), ignored (the
+      # {Timestamp} representation will have no defined UTC offset), or treated
+      # as though it were UTC (the {Timestamp} representation will have a
+      # {utc_offset} of 0 and {utc?} will return `true`).
+      #
+      # @param value [Object] a `Time`, `DateTime` or {Timestamp}.
+      # @param offset [Symbol] either `:preserve` to preserve the offset of
+      #   `value`, `:ignore` to ignore the offset of `value` and create a
+      #   {Timestamp} with an unspecified offset, or `:treat_as_utc` to treat
+      #   the offset of `value` as though it were UTC and create a UTC
+      #   {Timestamp}.
+      # @yield [timestamp] if a block is provided, the {Timestamp}
+      #   representation is passed to the block.
+      # @yieldparam timestamp [Timestamp] the {Timestamp} representation of
+      #   `value`.
+      # @yieldreturn [Timestamp] a {Timestamp} to be converted back to the type
+      #   of `value`.
+      # @return [Object] if called without a block, the {Timestamp}
+      #   representation of `value`, otherwise the result of the block,
+      #   converted back to the type of `value`.
+      def for(value, offset = :preserve)
+        raise ArgumentError, 'value must be specified' unless value
+
+        case offset
+          when :ignore
+            ignore_offset = true
+            target_utc_offset = nil
+          when :treat_as_utc
+            ignore_offset = true
+            target_utc_offset = :utc
+          when :preserve
+            ignore_offset = false
+            target_utc_offset = nil
+          else
+            raise ArgumentError, 'offset must be :preserve, :ignore or :treat_as_utc'
+        end
+
+        time_like = false
+        timestamp = case value
+          when Time
+            for_time(value, ignore_offset, target_utc_offset)
+          when DateTime
+            for_datetime(value, ignore_offset, target_utc_offset)
+          when Timestamp
+            for_timestamp(value, ignore_offset, target_utc_offset)
+          else
+            raise ArgumentError, "#{value.class} values are not supported" unless is_time_like?(value)
+            time_like = true
+            for_time_like(value, ignore_offset, target_utc_offset)
+        end
+
+        if block_given?
+          result = yield timestamp
+          raise ArgumentError, 'block must return a Timestamp' unless result.kind_of?(Timestamp)
+
+          case value
+            when Time
+              result.to_time
+            when DateTime
+              result.to_datetime
+            else # A Time-like value or a Timestamp
+              time_like ? result.to_time : result
+          end
+        else
+          timestamp
+        end
+      end
+
+      # Creates a new UTC {Timestamp}.
+      #
+      # @param value [Integer] the number of seconds since 1970-01-01 00:00:00
+      #   UTC ignoring leap seconds.
+      # @param sub_second [Numeric] the fractional part of the second as either
+      #   a `Rational` that is greater than or equal to 0 and less than 1, or
+      #   the `Integer` 0.
+      # @raise [ArgumentError] if `value` is not an `Integer`.
+      # @raise [ArgumentError] if `sub_second` is not a `Rational`, or the
+      #   `Integer` 0.
+      # @raise [RangeError] if `sub_second` is a `Rational` but that is less
+      #   than 0 or greater than or equal to 1.
+      def utc(value, sub_second = 0)
+        new(value, sub_second, :utc)
+      end
+
+      private
+
+      # Constructs a new instance of `self` (i.e. {Timestamp} or a subclass of
+      # {Timestamp}) without validating the parameters. This method is used
+      # internally within {Timestamp} to avoid the overhead of checking
+      # parameters.
+      #
+      # @param value [Integer] the number of seconds since 1970-01-01 00:00:00
+      #   UTC ignoring leap seconds.
+      # @param sub_second [Numeric] the fractional part of the second as either
+      #   a `Rational` that is greater than or equal to 0 and less than 1, or
+      #   the `Integer` 0.
+      # @param utc_offset [Object] either `nil` for a {Timestamp} without a
+      #   specified offset, an offset from UTC specified as an `Integer` number
+      #   of seconds or the `Symbol` `:utc`).
+      # @return [Timestamp] a new instance of `self`.
+      def new!(value, sub_second = 0, utc_offset = nil)
+        result = allocate
+        result.send(:initialize!, value, sub_second, utc_offset)
+        result
+      end
+
+      # Creates a {Timestamp} that represents a given `Time`, optionally
+      # ignoring the offset.
+      #
+      # @param time [Time] a `Time`.
+      # @param ignore_offset [Boolean] whether to ignore the offset of `time`.
+      # @param target_utc_offset [Object] if `ignore_offset` is `true`, the UTC
+      #   offset of the result (`:utc`, `nil` or an `Integer`).
+      # @return [Timestamp] the {Timestamp} representation of `time`.
+      def for_time(time, ignore_offset, target_utc_offset)
+        value = time.to_i
+        sub_second = time.subsec
+
+        if ignore_offset
+          utc_offset = target_utc_offset
+          value += time.utc_offset
+        elsif time.utc?
+          utc_offset = :utc
+        else
+          utc_offset = time.utc_offset
+        end
+
+        new!(value, sub_second, utc_offset)
+      end
+
+      # Creates a {Timestamp} that represents a given `DateTime`, optionally
+      # ignoring the offset.
+      #
+      # @param datetime [DateTime] a `DateTime`.
+      # @param ignore_offset [Boolean] whether to ignore the offset of
+      #   `datetime`.
+      # @param target_utc_offset [Object] if `ignore_offset` is `true`, the UTC
+      #   offset of the result (`:utc`, `nil` or an `Integer`).
+      # @return [Timestamp] the {Timestamp} representation of `datetime`.
+      def for_datetime(datetime, ignore_offset, target_utc_offset)
+        value = (datetime.jd - JD_EPOCH) * 86400 + datetime.sec + datetime.min * 60 + datetime.hour * 3600
+        sub_second = datetime.sec_fraction
+
+        if ignore_offset
+          utc_offset = target_utc_offset
+        else
+          utc_offset = (datetime.offset * 86400).to_i
+          value -= utc_offset
+        end
+
+        new!(value, sub_second, utc_offset)
+      end
+
+      # Returns a {Timestamp} that represents another {Timestamp}, optionally
+      # ignoring the offset. If the result would be identical to `value`, the
+      # same instance is returned. If the passed in value is an instance of a
+      # subclass of {Timestamp}, then a new {Timestamp} will always be returned.
+      #
+      # @param timestamp [Timestamp] a {Timestamp}.
+      # @param ignore_offset [Boolean] whether to ignore the offset of
+      #   `timestamp`.
+      # @param target_utc_offset [Object] if `ignore_offset` is `true`, the UTC
+      #   offset of the result (`:utc`, `nil` or an `Integer`).
+      # @return [Timestamp] a [Timestamp] representation of `timestamp`.
+      def for_timestamp(timestamp, ignore_offset, target_utc_offset)
+        if ignore_offset
+          if target_utc_offset
+            unless target_utc_offset == :utc && timestamp.utc? || timestamp.utc_offset == target_utc_offset
+              return new!(timestamp.value + (timestamp.utc_offset || 0), timestamp.sub_second, target_utc_offset)
+            end
+          elsif timestamp.utc_offset
+            return new!(timestamp.value + timestamp.utc_offset, timestamp.sub_second)
+          end
+        end
+
+        unless timestamp.instance_of?(Timestamp)
+          # timestamp is identical in value, sub_second and utc_offset but is a
+          # subclass (i.e. TimestampWithOffset). Return a new Timestamp
+          # instance.
+          return new!(timestamp.value, timestamp.sub_second, timestamp.utc? ? :utc : timestamp.utc_offset)
+        end
+
+        timestamp
+      end
+
+      # Determines if an object is like a `Time` (for the purposes of converting
+      # to a {Timestamp} with {for}), responding to `to_i` and `subsec`.
+      #
+      # @param value [Object] an object to test.
+      # @return [Boolean] `true` if the object is `Time`-like, otherwise
+      #   `false`.
+      def is_time_like?(value)
+        value.respond_to?(:to_i) && value.respond_to?(:subsec)
+      end
+
+      # Creates a {Timestamp} that represents a given `Time`-like object,
+      # optionally ignoring the offset (if the `time_like` responds to
+      # `utc_offset`).
+      #
+      # @param time_like [Object] a `Time`-like object.
+      # @param ignore_offset [Boolean] whether to ignore the offset of `time`.
+      # @param target_utc_offset [Object] if `ignore_offset` is `true`, the UTC
+      #   offset of the result (`:utc`, `nil` or an `Integer`).
+      # @return [Timestamp] the {Timestamp} representation of `time_like`.
+      def for_time_like(time_like, ignore_offset, target_utc_offset)
+        value = time_like.to_i
+        sub_second = time_like.subsec.to_r
+
+        if ignore_offset
+          utc_offset = target_utc_offset
+          value += time_like.utc_offset.to_i if time_like.respond_to?(:utc_offset)
+        elsif time_like.respond_to?(:utc_offset)
+          utc_offset = time_like.utc_offset.to_i
+        else
+          utc_offset = 0
+        end
+
+        new(value, sub_second, utc_offset)
+      end
+    end
+
+    # @return [Integer] the number of seconds since 1970-01-01 00:00:00 UTC
+    #   ignoring leap seconds (i.e. each day is treated as if it were 86,400
+    #   seconds long).
+    attr_reader :value
+
+    # @return [Numeric] the fraction of a second elapsed since timestamp as
+    #   either a `Rational` or the `Integer` 0. Always greater than or equal to
+    #   0 and less than 1.
+    attr_reader :sub_second
+
+    # @return [Integer] the offset from UTC in seconds or `nil` if the
+    #   {Timestamp} doesn't have a specified offset.
+    attr_reader :utc_offset
+
+    # Initializes a new {Timestamp}.
+    #
+    # @param value [Integer] the number of seconds since 1970-01-01 00:00:00 UTC
+    #   ignoring leap seconds.
+    # @param sub_second [Numeric] the fractional part of the second as either a
+    #   `Rational` that is greater than or equal to 0 and less than 1, or
+    #   the `Integer` 0.
+    # @param utc_offset [Object] either `nil` for a {Timestamp} without a
+    #   specified offset, an offset from UTC specified as an `Integer` number of
+    #   seconds or the `Symbol` `:utc`).
+    # @raise [ArgumentError] if `value` is not an `Integer`.
+    # @raise [ArgumentError] if `sub_second` is not a `Rational`, or the
+    #   `Integer` 0.
+    # @raise [RangeError] if `sub_second` is a `Rational` but that is less
+    #   than 0 or greater than or equal to 1.
+    # @raise [ArgumentError] if `utc_offset` is not `nil`, not an `Integer` and
+    #   not the `Symbol` `:utc`.
+    def initialize(value, sub_second = 0, utc_offset = nil)
+      raise ArgumentError, 'value must be an Integer' unless value.kind_of?(Integer)
+      raise ArgumentError, 'sub_second must be a Rational or the Integer 0' unless (sub_second.kind_of?(Integer) && sub_second == 0) || sub_second.kind_of?(Rational)
+      raise RangeError, 'sub_second must be >= 0 and < 1' if sub_second < 0 || sub_second >= 1
+      raise ArgumentError, 'utc_offset must be an Integer, :utc or nil' if utc_offset && utc_offset != :utc && !utc_offset.kind_of?(Integer)
+      initialize!(value, sub_second, utc_offset)
+    end
+
+    # @return [Boolean] `true` if this {Timestamp} represents UTC, `false` if
+    #   the {Timestamp} wasn't specified as UTC or `nil` if the {Timestamp} has
+    #   no specified offset.
+    def utc?
+      @utc
+    end
+
+    # Adds a number of seconds to the {Timestamp} value, setting the UTC offset
+    # of the result.
+    #
+    # @param seconds [Integer] the number of seconds to be added.
+    # @param utc_offset [Object] either `nil` for a {Timestamp} without a
+    #   specified offset, an offset from UTC specified as an `Integer` number of
+    #   seconds or the `Symbol` `:utc`).
+    # @return [Timestamp] the result of adding `seconds` to the
+    #   {Timestamp} value as a new {Timestamp} instance with the chosen
+    #   `utc_offset`.
+    # @raise [ArgumentError] if `seconds` is not an `Integer`.
+    # @raise [ArgumentError] if `utc_offset` is not `nil`, not an `Integer` and
+    #   not the `Symbol` `:utc`.
+    def add_and_set_utc_offset(seconds, utc_offset)
+      raise ArgumentError, 'seconds must be an Integer' unless seconds.kind_of?(Integer)
+      raise ArgumentError, 'utc_offset must be an Integer, :utc or nil' if utc_offset && utc_offset != :utc && !utc_offset.kind_of?(Integer)
+      return self if seconds == 0 && utc_offset == (@utc ? :utc : @utc_offset)
+      Timestamp.send(:new!, @value + seconds, @sub_second, utc_offset)
+    end
+
+    # @return [Timestamp] a UTC {Timestamp} equivalent to this instance. Returns
+    #   `self` if {#utc? self.utc?} is `true`.
+    def utc
+      return self if @utc
+      Timestamp.send(:new!, @value, @sub_second, :utc)
+    end
+
+    # Converts this {Timestamp} to a `Time`.
+    #
+    # @return [Time] a `Time` representation of this {Timestamp}. If the UTC
+    #   offset of this {Timestamp} is not specified, a UTC `Time` will be
+    #   returned.
+    def to_time
+      time = new_time
+
+      if @utc_offset && !@utc
+        time.localtime(@utc_offset)
+      else
+        time.utc
+      end
+    end
+
+    # Converts this {Timestamp} to a Gregorian `DateTime`.
+    #
+    # @return [DateTime] a Gregorian `DateTime` representation of this
+    #   {Timestamp}. If the UTC offset of this {Timestamp} is not specified, a
+    #   UTC `DateTime` will be returned.
+    def to_datetime
+      new_datetime
+    end
+
+    # Converts this {Timestamp} to an `Integer` number of seconds since
+    # 1970-01-01 00:00:00 UTC (ignoring leap seconds).
+    #
+    # @return [Integer] an `Integer` representation of this {Timestamp} (the
+    #   number of seconds since 1970-01-01 00:00:00 UTC ignoring leap seconds).
+    def to_i
+      value
+    end
+
+    # Formats this {Timestamp} according to the directives in the given format
+    # string.
+    #
+    # @param format [String] the format string. Please refer to `Time#strftime`
+    #   for a list of supported format directives.
+    # @return [String] the formatted {Timestamp}.
+    # @raise [ArgumentError] if `format` is not specified.
+    def strftime(format)
+      raise ArgumentError, 'format must be specified' unless format
+      to_time.strftime(format)
+    end
+
+    # @return [String] a `String` representation of this {Timestamp}.
+    def to_s
+      return value_and_sub_second_to_s unless @utc_offset
+      return "#{value_and_sub_second_to_s} UTC" if @utc
+
+      sign = @utc_offset >= 0 ? '+' : '-'
+      min, sec = @utc_offset.abs.divmod(60)
+      hour, min = min.divmod(60)
+
+      "#{value_and_sub_second_to_s(@utc_offset)} #{sign}#{'%02d' % hour}:#{'%02d' % min}#{sec > 0 ? ':%02d' % sec : nil}#{@utc_offset != 0 ? " (#{value_and_sub_second_to_s} UTC)" : nil}"
+    end
+
+    # Compares this {Timestamp} with another.
+    #
+    # {Timestamp} instances without a defined UTC offset are not comparable with
+    # {Timestamp} instances that have a defined UTC offset.
+    #
+    # @param t [Timestamp] the {Timestamp} to compare this instance with.
+    # @return [Integer] -1, 0 or 1 depending if this instance is earlier, equal
+    #   or later than `t` respectively. Returns `nil` when comparing a
+    #   {Timestamp} that does not have a defined UTC offset with a {Timestamp}
+    #   that does have a defined UTC offset. Returns `nil` if `t` is not a
+    #   {Timestamp}.
+    def <=>(t)
+      return nil unless t.kind_of?(Timestamp)
+      return nil if utc_offset && !t.utc_offset
+      return nil if !utc_offset && t.utc_offset
+
+      result = value <=> t.value
+      result = sub_second <=> t.sub_second if result == 0
+      result
+    end
+
+    alias eql? ==
+
+    # @return [Integer] a hash based on the value, sub-second and whether there
+    #   is a defined UTC offset.
+    def hash
+      [@value, @sub_second, !!@utc_offset].hash
+    end
+
+    # @return [String] the internal object state as a programmer-readable
+    #   `String`.
+    def inspect
+      "#<#{self.class}: @value=#{@value}, @sub_second=#{@sub_second}, @utc_offset=#{@utc_offset.inspect}, @utc=#{@utc.inspect}>"
+    end
+
+    protected
+
+    # Creates a new instance of a `Time` or `Time`-like class matching the
+    # {value} and {sub_second} of this {Timestamp}, but not setting the offset.
+    #
+    # @param klass [Class] the class to instantiate.
+    #
+    # @private
+    def new_time(klass = Time)
+      klass.at(@value, @sub_second * 1_000_000)
+    end
+
+    # Constructs a new instance of a `DateTime` or `DateTime`-like class with
+    # the same {value}, {sub_second} and {utc_offset} as this {Timestamp}.
+    #
+    # @param klass [Class] the class to instantiate.
+    #
+    # @private
+    def new_datetime(klass = DateTime)
+      # Can't specify the start parameter unless the jd parameter is an exact number of days.
+      # Use #gregorian instead.
+      datetime = klass.jd(JD_EPOCH + ((@value.to_r + @sub_second) / 86400)).gregorian
+      @utc_offset && @utc_offset != 0 ? datetime.new_offset(Rational(@utc_offset, 86400)) : datetime
+    end
+
+    private
+
+    # Converts the value and sub-seconds to a `String`, adding on the given
+    # offset.
+    #
+    # @param offset [Integer] the offset to add to the value.
+    # @return [String] the value and sub-seconds.
+    def value_and_sub_second_to_s(offset = 0)
+      "#{@value + offset}#{sub_second_to_s}"
+    end
+
+    # Converts the {sub_second} value to a `String` suitable for appending to
+    # the `String` representation of a {Timestamp}.
+    #
+    # @return [String] a `String` representation of {sub_second}.
+    def sub_second_to_s
+      if @sub_second == 0
+        ''
+      else
+        " #{@sub_second.numerator}/#{@sub_second.denominator}"
+      end
+    end
+
+    # Initializes a new {Timestamp} without validating the parameters. This
+    # method is used internally within {Timestamp} to avoid the overhead of
+    # checking parameters.
+    #
+    # @param value [Integer] the number of seconds since 1970-01-01 00:00:00 UTC
+    #   ignoring leap seconds.
+    # @param sub_second [Numeric] the fractional part of the second as either a
+    #   `Rational` that is greater than or equal to 0 and less than 1, or the
+    #   `Integer` 0.
+    # @param utc_offset [Object] either `nil` for a {Timestamp} without a
+    #   specified offset, an offset from UTC specified as an `Integer` number of
+    #   seconds or the `Symbol` `:utc`).
+    def initialize!(value, sub_second = 0, utc_offset = nil)
+      @value = value
+
+      # Convert Rational(0,1) to 0.
+      @sub_second = sub_second == 0 ? 0 : sub_second
+
+      if utc_offset
+        @utc = utc_offset == :utc
+        @utc_offset = @utc ? 0 : utc_offset
+      else
+        @utc = @utc_offset = nil
+      end
+    end
+  end
+end

data/lib/tzinfo/timestamp_with_offset.rb

@@ -0,0 +1,85 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module TZInfo
+  # A subclass of {Timestamp} used to represent local times.
+  # {TimestampWithOffset} holds a reference to the related {TimezoneOffset} and
+  # overrides various methods to return results appropriate for the
+  # {TimezoneOffset}. Certain operations will clear the associated
+  # {TimezoneOffset} (if the {TimezoneOffset} would not necessarily be valid for
+  # the result). Once the {TimezoneOffset} has been cleared,
+  # {TimestampWithOffset} behaves identically to {Timestamp}.
+  class TimestampWithOffset < Timestamp
+    include WithOffset
+
+    # @return [TimezoneOffset] the {TimezoneOffset} associated with this
+    #   instance.
+    attr_reader :timezone_offset
+
+    # Creates a new {TimestampWithOffset} from a given {Timestamp} and
+    # {TimezoneOffset}.
+    #
+    # @param timestamp [Timestamp] a {Timestamp}.
+    # @param timezone_offset [TimezoneOffset] a {TimezoneOffset} valid at the
+    # time of `timestamp`.
+    # @return [TimestampWithOffset] a {TimestampWithOffset} that has the same
+    #   {value value} and {sub_second sub_second} as the `timestamp` parameter,
+    #   a {utc_offset utc_offset} equal to the
+    #   {TimezoneOffset#observed_utc_offset observed_utc_offset} of the
+    #   `timezone_offset` parameter and {timezone_offset timezone_offset} set to
+    #   the `timezone_offset` parameter.
+    # @raise [ArgumentError] if `timestamp` or `timezone_offset` is `nil`.
+    def self.set_timezone_offset(timestamp, timezone_offset)
+      raise ArgumentError, 'timestamp must be specified' unless timestamp
+      raise ArgumentError, 'timezone_offset must be specified' unless timezone_offset
+      new!(timestamp.value, timestamp.sub_second, timezone_offset.observed_utc_offset).set_timezone_offset(timezone_offset)
+    end
+
+    # Sets the associated {TimezoneOffset} of this {TimestampWithOffset}.
+    #
+    # @param timezone_offset [TimezoneOffset] a {TimezoneOffset} valid at the time
+    #   and for the offset of this {TimestampWithOffset}.
+    # @return [TimestampWithOffset] `self`.
+    # @raise [ArgumentError] if `timezone_offset` is `nil`.
+    # @raise [ArgumentError] if {utc? self.utc?} is `true`.
+    # @raise [ArgumentError] if `timezone_offset.observed_utc_offset` does not equal
+    #   `self.utc_offset`.
+    def set_timezone_offset(timezone_offset)
+      raise ArgumentError, 'timezone_offset must be specified' unless timezone_offset
+      raise ArgumentError, 'timezone_offset.observed_utc_offset does not match self.utc_offset' if utc? || utc_offset != timezone_offset.observed_utc_offset
+      @timezone_offset = timezone_offset
+      self
+    end
+
+    # An overridden version of {Timestamp#to_time} that, if there is an
+    # associated {TimezoneOffset}, returns a {TimeWithOffset} with that offset.
+    #
+    # @return [Time] if there is an associated {TimezoneOffset}, a
+    #   {TimeWithOffset} representation of this {TimestampWithOffset}, otherwise
+    #   a `Time` representation.
+    def to_time
+      to = timezone_offset
+      if to
+        new_time(TimeWithOffset).set_timezone_offset(to)
+      else
+        super
+      end
+    end
+
+    # An overridden version of {Timestamp#to_datetime}, if there is an
+    # associated {TimezoneOffset}, returns a {DateTimeWithOffset} with that
+    # offset.
+    #
+    # @return [DateTime] if there is an associated {TimezoneOffset}, a
+    #   {DateTimeWithOffset} representation of this {TimestampWithOffset},
+    #   otherwise a `DateTime` representation.
+    def to_datetime
+      to = timezone_offset
+      if to
+        new_datetime(DateTimeWithOffset).set_timezone_offset(to)
+      else
+        super
+      end
+    end
+  end
+end