iso8601 0.8.7 → 0.9.0

data/lib/iso8601/errors.rb

@@ -2,8 +2,11 @@ module ISO8601
   ##
   # Contains all ISO8601-specific errors.
   module Errors
+    ##
+    # Catch-all exception.
     class StandardError < ::StandardError
     end
+
     ##
     # Raised when the given pattern doesn't fit as ISO 8601 parser.
     class UnknownPattern < StandardError
@@ -11,6 +14,7 @@ module ISO8601
         super("Unknown pattern #{pattern}")
       end
     end
+
     ##
     # Raised when the given pattern contains an invalid fraction.
     class InvalidFractions < StandardError
@@ -18,6 +22,7 @@ module ISO8601
         super("Fractions are only allowed in the last component")
       end
     end
+
     ##
     # Raised when the given date is valid but out of range.
     class RangeError < StandardError
@@ -25,10 +30,17 @@ module ISO8601
         super("#{pattern} is out of range")
       end
     end
+
     ##
     # Raised when the type is unexpected
-    class TypeError < StandardError
+    class TypeError < ::ArgumentError
+    end
+
+    ##
+    # Raised when the interval is unexpected
+    class IntervalError < StandardError
     end
+
     ##
     # Raise when the base is not suitable.
     class DurationBaseError < StandardError

data/lib/iso8601/hours.rb

@@ -0,0 +1,43 @@
+# encoding: utf-8
+
+module ISO8601
+  ##
+  # The Hours atom in a {ISO8601::Duration}
+  class Hours
+    include Atomic
+
+    AVERAGE_FACTOR = 3600
+
+    ##
+    # @param [Numeric] atom The atom value
+    def initialize(atom)
+      valid_atom?(atom)
+
+      @atom = atom
+    end
+
+    ##
+    # The Week factor
+    #
+    # @return [Numeric]
+    def factor
+      AVERAGE_FACTOR
+    end
+
+    ##
+    # The amount of seconds
+    #
+    # @return [Numeric]
+    def to_seconds
+      AVERAGE_FACTOR * atom
+    end
+
+    ##
+    # The atom symbol.
+    #
+    # @return [Symbol]
+    def symbol
+      :H
+    end
+  end
+end

data/lib/iso8601/minutes.rb

@@ -0,0 +1,43 @@
+# encoding: utf-8
+
+module ISO8601
+  ##
+  # The Minutes atom in a {ISO8601::Duration}
+  class Minutes
+    include Atomic
+
+    AVERAGE_FACTOR = 60
+
+    ##
+    # @param [Numeric] atom The atom value
+    def initialize(atom)
+      valid_atom?(atom)
+
+      @atom = atom
+    end
+
+    ##
+    # The Minute factor
+    #
+    # @return [Numeric]
+    def factor
+      AVERAGE_FACTOR
+    end
+
+    ##
+    # The amount of seconds
+    #
+    # @return [Numeric]
+    def to_seconds
+      AVERAGE_FACTOR * atom
+    end
+
+    ##
+    # The atom symbol.
+    #
+    # @return [Symbol]
+    def symbol
+      :M
+    end
+  end
+end

data/lib/iso8601/months.rb

@@ -0,0 +1,98 @@
+# encoding: utf-8
+
+module ISO8601
+  ##
+  # A Months atom in a {ISO8601::Duration}
+  #
+  # A "calendar month" is the time interval resulting from the division of a
+  # "calendar year" in 12 time intervals.
+  #
+  # A "duration month" is the duration of 28, 29, 30 or 31 "calendar days"
+  # depending on the start and/or the end of the corresponding time interval
+  # within the specific "calendar month".
+  class Months
+    include Atomic
+
+    ##
+    # The "duration month" average is calculated through time intervals of 400
+    # "duration years". Each cycle of 400 "duration years" has 303 "common
+    # years" of 365 "calendar days" and 97 "leap years" of 366 "calendar days".
+    AVERAGE_FACTOR = Years::AVERAGE_FACTOR / 12
+
+    ##
+    # @param [Numeric] atom The atom value
+    def initialize(atom)
+      valid_atom?(atom)
+
+      @atom = atom
+    end
+
+    ##
+    # The Month factor
+    #
+    # @param [ISO8601::DateTime, nil] base (nil) The base datetime to compute
+    #   the month length.
+    #
+    # @return [Numeric]
+    def factor(base = nil)
+      return AVERAGE_FACTOR if base.nil?
+      return zero_calculation(base) if atom.zero?
+
+      calculation(atom, base)
+    end
+
+    ##
+    # The amount of seconds
+    #
+    # @param [ISO8601::DateTime, nil] base (nil) The base datetime to compute
+    #   the month length.
+    #
+    # @return [Numeric]
+    def to_seconds(base = nil)
+      valid_base?(base)
+
+      return (AVERAGE_FACTOR * atom) if base.nil?
+      return zero_calculation(base) if atom.zero?
+
+      calculation(atom, base) * atom
+    end
+
+    ##
+    # The atom symbol.
+    #
+    # @return [Symbol]
+    def symbol
+      :M
+    end
+
+    private
+
+    def zero_calculation(base)
+      month = (base.month <= 12) ? base.month : (base.month % 12)
+      year = base.year + ((base.month) / 12).to_i
+
+      (::Time.utc(year, month) - ::Time.utc(base.year, base.month))
+    end
+
+    def calculation(atom, base)
+      initial = base.month + atom
+      if initial <= 0
+        month = base.month + atom
+
+        if initial % 12 == 0
+          year = base.year + (initial / 12) - 1
+          month = 12
+        else
+          year = base.year + (initial / 12).floor
+          month = (12 + initial > 0) ? (12 + initial) : (12 + (initial % -12))
+        end
+      else
+        month = (initial <= 12) ? initial : (initial % 12)
+        month = 12 if month.zero?
+        year = base.year + ((base.month + atom) / 12).to_i
+      end
+
+      (::Time.utc(year, month) - ::Time.utc(base.year, base.month)) / atom
+    end
+  end
+end

data/lib/iso8601/seconds.rb

@@ -0,0 +1,47 @@
+# encoding: utf-8
+
+module ISO8601
+  ##
+  # The Seconds atom in a {ISO8601::Duration}
+  #
+  # The second is the base unit of measurement of time in the International
+  # System of Units (SI) as defined by the International Committee of Weights
+  # and Measures.
+  class Seconds
+    include Atomic
+
+    AVERAGE_FACTOR = 1
+
+    ##
+    # @param [Numeric] atom The atom value
+    def initialize(atom)
+      valid_atom?(atom)
+
+      @atom = atom
+    end
+
+    ##
+    # The Second factor
+    #
+    # @return [Numeric]
+    def factor
+      AVERAGE_FACTOR
+    end
+
+    ##
+    # The amount of seconds
+    #
+    # @return [Numeric]
+    def to_seconds
+      atom
+    end
+
+    ##
+    # The atom symbol.
+    #
+    # @return [Symbol]
+    def symbol
+      :S
+    end
+  end
+end

data/lib/iso8601/time.rb

@@ -17,12 +17,15 @@ module ISO8601
       :to_time, :to_date, :to_datetime,
       :hour, :minute, :zone
     )
+
     ##
     # The separator used in the original ISO 8601 string.
     attr_reader :separator
+
     ##
     # The second atom
     attr_reader :second
+
     ##
     # The original atoms
     attr_reader :atoms
@@ -37,6 +40,7 @@ module ISO8601
       @time = compose(@atoms, @base)
       @second = @time.second + @time.second_fraction.to_f.round(1)
     end
+
     ##
     # @param [#hash] other The contrast to compare against
     #
@@ -44,6 +48,7 @@ module ISO8601
     def ==(other)
       (hash == other.hash)
     end
+
     ##
     # @param [#hash] other The contrast to compare against
     #
@@ -51,11 +56,13 @@ module ISO8601
     def eql?(other)
       (hash == other.hash)
     end
+
     ##
     # @return [Fixnum]
     def hash
       [atoms, self.class].hash
     end
+
     ##
     # Forwards the time the given amount of seconds.
     #
@@ -68,6 +75,7 @@ module ISO8601
 
       self.class.new(moment.strftime('T%H:%M:%S.%L%:z'), base)
     end
+
     ##
     # Backwards the date the given amount of seconds.
     #
@@ -80,13 +88,15 @@ module ISO8601
 
       self.class.new(moment.strftime('T%H:%M:%S.%L%:z'), base)
     end
+
     ##
     # Converts self to a time component representation.
     def to_s
-      second_format = (second % 1).zero? ? '%02d' % second : '%04.1f' % second
+      second_format = format((second % 1).zero? ? '%02d' : '%04.1f', second)
 
-      "T%02d:%02d:#{second_format}#{zone}" % atoms
+      format("T%02d:%02d:#{second_format}#{zone}", *atoms)
     end
+
     ##
     # Converts self to an array of atoms.
     def to_a
@@ -104,30 +114,47 @@ module ISO8601
     #
     # @return [Array<Integer, Float>]
     def atomize(input)
-      _, time, zone = /^T?(.+?)(Z|[+-].+)?$/.match(input).to_a
-
-      _, hour, separator, minute, second = /^(?:
-        (\d{2})(:?)(\d{2})\2(\d{2}(?:[.,]\d+)?) |
-        (\d{2})(:?)(\d{2}) |
-        (\d{2})
-      )$/x.match(time).to_a.compact
+      _, time, zone = parse_timezone(input)
+      _, hour, separator, minute, second = parse_time(time)
 
-      fail ISO8601::Errors::UnknownPattern, @original if hour.nil?
+      fail ISO8601::Errors::UnknownPattern,
+           @original if hour.nil?
 
       @separator = separator
-      require_separator = !minute.nil?
+      require_separator = require_separator(minute)
 
       hour = hour.to_i
       minute = minute.to_i
-      second = second.nil? ? 0.0 : second.tr(',', '.').to_f
+      second = parse_second(second)
 
       atoms = [hour, minute, second, zone].compact
 
-
-      fail ISO8601::Errors::UnknownPattern, @original unless valid_zone?(zone, require_separator)
+      fail ISO8601::Errors::UnknownPattern,
+           @original unless valid_zone?(zone, require_separator)
 
       atoms
     end
+
+    def require_separator(input)
+      !input.nil?
+    end
+
+    def parse_timezone(timezone)
+      /^T?(.+?)(Z|[+-].+)?$/.match(timezone).to_a
+    end
+
+    def parse_time(time)
+      /^(?:
+        (\d{2})(:?)(\d{2})\2(\d{2}(?:[.,]\d+)?) |
+        (\d{2})(:?)(\d{2}) |
+        (\d{2})
+      )$/x.match(time).to_a.compact
+    end
+
+    def parse_second(second)
+      second.nil? ? 0.0 : second.tr(',', '.').to_f
+    end
+
     ##
     # @param [String] zone The timezone offset as Z or +-hh[:mm].
     # @param [Boolean] require_separator Flag to determine if the separator
@@ -138,12 +165,13 @@ module ISO8601
       _, offset, separator = zone_regexp.match(zone).to_a.compact
 
       wrong_pattern = !zone.nil? && offset.nil?
-      if (require_separator)
+      if require_separator
         invalid_separators = zone.to_s.match(/^[+-]\d{2}:?\d{2}$/) && (@separator != separator)
       end
 
       !(wrong_pattern || invalid_separators)
     end
+
     ##
     # Wraps ::DateNew.new to play nice with ArgumentError.
     #

data/lib/iso8601/time_interval.rb

@@ -0,0 +1,392 @@
+module ISO8601
+  ##
+  # A Time Interval representation.
+  # See https://en.wikipedia.org/wiki/ISO_8601#Time_intervals
+  #
+  # @example
+  #     ti = ISO8601::TimeInterval.parse('P1MT2H/2014-05-28T19:53Z')
+  #     ti.size # => 2635200.0
+  #     ti2 = ISO8601::TimeInterval.parse('2014-05-28T19:53Z/2014-05-28T20:53Z')
+  #     ti2.to_f # => 3600.0
+  #
+  # @example
+  #     start_time = ISO8601::DateTime.new('2014-05-28T19:53Z')
+  #     end_time = ISO8601::DateTime.new('2014-05-30T19:53Z')
+  #     ti = ISO8601::TimeInterval.from_datetimes(start_time, end_time)
+  #     ti.size # => 172800.0 (Seconds)
+  #
+  # @example
+  #     duration = ISO8601::Duration.new('P1MT2H')
+  #     end_time = ISO8601::DateTime.new('2014-05-30T19:53Z')
+  #     ti = ISO8601::TimeInterval.from_duration(duration, end_time)
+  #     ti.size # => 2635200.0 (Seconds)
+  #
+  # @example
+  #     start_time = ISO8601::DateTime.new('2014-05-30T19:53Z')
+  #     duration = ISO8601::Duration.new('P1MT2H', base)
+  #     ti = ISO8601::TimeInterval.from_duration(start_time, duration)
+  #     ti.size # => 2635200.0 (Seconds)
+  #
+  class TimeInterval
+    include Comparable
+
+    ##
+    # Initializes a time interval based on two time points.
+    #
+    # @overload from_datetimes(start_time, end_time)
+    #   @param [ISO8601::DateTime] start_time The start time point of the
+    #       interval.
+    #   @param [ISO8601::DateTime] end_time The end time point of the interaval.
+    #
+    # @raise [ISO8601::Errors::TypeError] If both params are not instances of
+    #   `ISO8601::DateTime`.
+    #
+    # @return [ISO8601::TimeInterval]
+    def self.from_datetimes(*atoms)
+      guard_from_datetimes(atoms, 'Start and end times must instances of ISO8601::DateTime')
+      new(atoms)
+    end
+
+    ##
+    # Initializes a TimeInterval based on a `ISO8601::Duration` and a
+    # `ISO8601::DateTime`.  The order of the params define the strategy to
+    # compute the interval.
+    #
+    # @overload from_duration(start_time, duration)
+    #   Equivalent to the `<start>/<duration>` pattern.
+    #   @param [ISO8601::DateTime] start_time The start time point of the
+    #       interval.
+    #   @param [ISO8601::Duration] duration The size of the interval.
+    #
+    # @overload from_duration(duration, end_time)
+    #   Equivalent to the `<duration>/<end>` pattern.
+    #   @param [ISO8601::Duration] duration The size of the interval.
+    #   @param [ISO8601::DateTime] end_time The end time point of the interaval.
+    #
+    # @raise [ISO8601::Errors::TypeError] If the params aren't a mix of
+    #   `ISO8601::DateTime` and `ISO8601::Duration`.
+    #
+    # @return [ISO8601::TimeInterval]
+    def self.from_duration(*atoms)
+      guard_from_duration(atoms, 'Expected one date time and one duration')
+      new(atoms)
+    end
+
+    ##
+    # Dispatches the constructor based on the type of the input.
+    #
+    # @overload new(pattern)
+    #   Parses a pattern.
+    #   @param [String] input A time interval pattern.
+    #
+    # @overload new([start_time, duration])
+    #   Equivalent to the `<start>/<duration>` pattern.
+    #   @param [Array<(ISO8601::DateTime, ISO8601::Duration)>] input
+    #
+    # @overload new([duration, end_time])
+    #   Equivalent to the `<duration>/<end>` pattern.
+    #   @param [Array<(ISO8601::Duration, ISO8601::DateTime)>] input
+    #
+    # @return [ISO8601::TimeInterval]
+    def initialize(input)
+      case input
+      when String
+        parse(input)
+      when Array
+        from_atoms(input)
+      else
+        fail(ISO8601::Errors::TypeError, 'The pattern must be a String or a Hash')
+      end
+    end
+
+    ##
+    # Alias of `initialize` to have a closer interface to the core `Time`,
+    # `Date` and `DateTime` interfaces.
+    def self.parse(pattern)
+      new(pattern)
+    end
+
+    ##
+    # The start time (first) of the interval.
+    #
+    # @return [ISO8601::DateTime] start time
+    attr_reader :first
+    alias_method :start_time, :first
+
+    ##
+    # The end time (last) of the interval.
+    #
+    # @return [ISO8601::DateTime] end time
+    attr_reader :last
+    alias_method :end_time, :last
+
+    ##
+    # The pattern for the interval.
+    #
+    # @return [String] The pattern of this interval
+    def pattern
+      return @pattern if @pattern
+
+      "#{@atoms.first}/#{@atoms.last}"
+    end
+    alias_method :to_s, :pattern
+
+    ##
+    # The size of the interval. If any bound is a Duration, the
+    # size of the interval is the number of seconds of the interval.
+    #
+    # @return [Float] Size of the interval in seconds
+    attr_reader :size
+    alias_method :to_f, :size
+    alias_method :length, :size
+
+    ##
+    # Checks if the interval is empty.
+    #
+    # @return [Boolean]
+    def empty?
+      first == last
+    end
+
+    ##
+    # Check if a given time is inside the current TimeInterval.
+    #
+    # @param [#to_time] other DateTime to check if it's
+    #   inside the current interval.
+    #
+    # @raise [ISO8601::Errors::TypeError] if time param is not a compatible
+    #   Object.
+    #
+    # @return [Boolean]
+    def include?(other)
+      fail(ISO8601::Errors::TypeError, 'The parameter must respond_to #to_time') \
+        unless other.respond_to?(:to_time)
+
+      (first.to_time <= other.to_time &&
+       last.to_time >= other.to_time)
+    end
+    alias_method :member?, :include?
+
+    ##
+    # Returns true if the interval is a subset of the given interval.
+    #
+    # @param [ISO8601::TimeInterval] other a time interval.
+    #
+    # @raise [ISO8601::Errors::TypeError] if time param is not a compatible
+    #   Object.
+    #
+    # @return [Boolean]
+    def subset?(other)
+      fail(ISO8601::Errors::TypeError, "The parameter must be an instance of #{self.class}") \
+        unless other.is_a?(self.class)
+
+      other.include?(first) && other.include?(last)
+    end
+
+    ##
+    # Returns true if the interval is a superset of the given interval.
+    #
+    # @param [ISO8601::TimeInterval] other a time interval.
+    #
+    # @raise [ISO8601::Errors::TypeError] if time param is not a compatible
+    #   Object.
+    #
+    # @return [Boolean]
+    def superset?(other)
+      fail(ISO8601::Errors::TypeError, "The parameter must be an instance of #{self.class}") \
+        unless other.is_a?(self.class)
+
+      include?(other.first) && include?(other.last)
+    end
+
+    ##
+    # Check if two intervarls intersect.
+    #
+    # @param [ISO8601::TimeInterval] other Another interval to check if they
+    #   intersect.
+    #
+    # @raise [ISO8601::Errors::TypeError] if the param is not a TimeInterval.
+    #
+    # @return [Boolean]
+    def intersect?(other)
+      fail(ISO8601::Errors::TypeError,
+           "The parameter must be an instance of #{self.class}") \
+        unless other.is_a?(self.class)
+
+      include?(other.first) || include?(other.last)
+    end
+
+    ##
+    # Return the intersection between two intervals.
+    #
+    # @param [ISO8601::TimeInterval] other time interval
+    #
+    # @raise [ISO8601::Errors::TypeError] if the param is not a TimeInterval.
+    #
+    # @return [Boolean]
+    def intersection(other)
+      fail(ISO8601::Errors::IntervalError, "The intervals are disjoint") \
+        if disjoint?(other) && other.disjoint?(self)
+
+      return self if subset?(other)
+      return other if other.subset?(self)
+
+      a, b = sort_pair(self, other)
+      self.class.from_datetimes(b.first, a.last)
+    end
+
+    ##
+    # Check if two intervarls have no element in common.  This method is the
+    # opposite of `#intersect?`.
+    #
+    # @param [ISO8601::TimeInterval] other Time interval.
+    #
+    # @raise [ISO8601::Errors::TypeError] if the param is not a TimeInterval.
+    #
+    # @return [Boolean]
+    def disjoint?(other)
+      !intersect?(other)
+    end
+
+    ##
+    # @param [ISO8601::TimeInterval] other
+    #
+    # @return [-1, 0, 1, nil]
+    def <=>(other)
+      return nil unless other.is_a?(self.class)
+
+      to_f <=> other.to_f
+    end
+
+    ##
+    # Equality by hash.
+    #
+    # @param [ISO8601::TimeInterval] other
+    #
+    # @return [Boolean]
+    def eql?(other)
+      (hash == other.hash)
+    end
+
+    ##
+    # @return [Fixnum]
+    def hash
+      @atoms.hash
+    end
+
+    private
+
+    # Initialize a TimeInterval ISO8601 by a pattern. If you initialize it with
+    # a duration pattern, the second argument is mandatory because you need to
+    # specify an start/end point to calculate the interval.
+    #
+    # @param [String] pattern This parameter define a full time interval. These
+    #     patterns are defined in the ISO8601:
+    #         * <start_time>/<end_time>
+    #         * <start_time>/<duration>
+    #         * <duration>/<end_time>
+    #
+    # @raise [ISO8601::Errors::UnknownPattern] If given pattern is not a valid
+    #     ISO8601 pattern.
+    def parse(pattern)
+      fail(ISO8601::Errors::UnknownPattern, pattern) unless pattern.include?('/')
+
+      @pattern = pattern
+      subpatterns = pattern.split('/')
+
+      fail(ISO8601::Errors::UnknownPattern, pattern) if subpatterns.size != 2
+
+      @atoms = subpatterns.map { |x| parse_subpattern(x) }
+      @first, @last, @size = limits(@atoms)
+    end
+
+    def sort_pair(a, b)
+      (a.first < b.first) ? [a, b] : [b, a]
+    end
+
+    ##
+    # Parses a subpattern to a correct type.
+    #
+    # @param [String] pattern
+    #
+    # @return [ISO8601::Duration, ISO8601::DateTime]
+    def parse_subpattern(pattern)
+      return ISO8601::Duration.new(pattern) if pattern.start_with?('P')
+
+      ISO8601::DateTime.new(pattern)
+    end
+
+    ##
+    # See the constructor methods.
+    #
+    # @param [Array] atoms
+    def from_atoms(atoms)
+      @atoms = atoms
+      @first, @last, @size = limits(@atoms)
+    end
+
+    ##
+    # Calculates the limits (first, last) and the size of the interval.
+    #
+    # @param [Array] atoms The atoms result of parsing the pattern.
+    #
+    # @return [Array<(ISO8601::DateTime, ISO8601::DateTime, ISO8601::Duration)>]
+    def limits(atoms)
+      valid_atoms?(atoms)
+
+      if atoms.none? { |x| x.is_a?(ISO8601::Duration) }
+        return tuple_by_both(atoms)
+      elsif atoms.first.is_a?(ISO8601::Duration)
+        return tuple_by_end(atoms)
+      else
+        return tuple_by_start(atoms)
+      end
+    end
+
+    def tuple_by_both(atoms)
+      [atoms.first,
+       atoms.last,
+       (atoms.last.to_time - atoms.first.to_time)]
+    end
+
+    def tuple_by_end(atoms)
+      seconds = atoms.first.to_seconds(atoms.last)
+      [(atoms.last - seconds),
+       atoms.last,
+       seconds]
+    end
+
+    def tuple_by_start(atoms)
+      seconds = atoms.last.to_seconds(atoms.first)
+      [atoms.first,
+       (atoms.first + seconds),
+       seconds]
+    end
+
+    def valid_atoms?(atoms)
+      fail(ISO8601::Errors::UnknownPattern,
+           "The pattern of a time interval can't be <duration>/<duration>") \
+        if atoms.all? { |x| x.is_a?(ISO8601::Duration) }
+    end
+
+    def valid_date_time?(time)
+      self.valid_date_time?(time)
+    end
+
+    def self.valid_date_time?(time, message = 'Expected a ISO8601::DateTime')
+      return true if time.is_a?(ISO8601::DateTime)
+
+      fail(ISO8601::Errors::TypeError, message)
+    end
+
+    def self.guard_from_datetimes(atoms, message)
+      atoms.all? { |x| valid_date_time?(x, message) }
+    end
+
+    def self.guard_from_duration(atoms, message)
+      fail(ISO8601::Errors::TypeError, message) \
+        unless atoms.any? { |x| x.is_a?(ISO8601::Duration) } &&
+               atoms.any? { |x| x.is_a?(ISO8601::DateTime) }
+    end
+  end
+end