iso8601 0.2 → 0.4.0

data/README.md

@@ -6,10 +6,27 @@ times) standard.
 
 ## Comments
 
-Because Durations and DateTime has substract method, Durations has sign to represent a negative value:
+### Duration sign
 
-  * `(ISO8601::Duration.new("PT10S") - ISO8601::Duration.new("PT12S")).to_s #=> "-PT2S"`
-  * `(ISO8601::Duration.new("-PT10S") + ISO8601::Duration.new("PT12S")).to_s #=> "PT2S"`
+Because Durations and DateTime has a substraction method, Durations has sign to be able to represent a negative value:
+
+    (ISO8601::Duration.new('PT10S') - ISO8601::Duration.new('PT12S')).to_s #=> '-PT2S'
+    (ISO8601::Duration.new('-PT10S') + ISO8601::Duration.new('PT12S')).to_s #=> 'PT2S'
+
+### Separators
+
+Although, the spec allows three separator types: period (.), comma (,), and raised period (·) by now I keep just the period option.
+
+### Century treatment
+
+The specification says that you can express a reduced precision year
+just giving the century (i.e. '20' to refer the inclusive range 2000-2999).
+
+This implementation expands the century to the first value for its range
+so:
+
+    ISO8601::DateTime.new('20').century # => 20
+    ISO8601::DateTime.new('20').year # => 2000
 
 
 ## TODO
@@ -18,12 +35,16 @@ Because Durations and DateTime has substract method, Durations has sign to repre
 * Recurring time intervals
 * Ordinal date pattern (YYYY-DDD)
 * Week date pattern (YYYY-Www-D)
+* Treat the `201005` as `2000-10-05` instead of `2010-05`
 
 ## Contributors
 
 * [Nick Lynch](https://github.com/njlynch)
 * [Pelle Braendgaard](https://github.com/pelle)
 * [Takahiro Noda](https://github.com/tnoda)
+* [Porras](https://github.com/porras)
+
+## License
+
+Arnau Siches under the [MIT License](https://github.com/arnau/ISO8601/blob/master/LICENSE)
 
-## Credits
-Arnau Siches under [LGPL](http://www.gnu.org/licenses/lgpl.html) license. LICENSE file for details.

data/Rakefile

@@ -1 +1,2 @@
-require "bundler/gem_tasks"
+#!/usr/bin/env rake
+require 'bundler/gem_tasks'

data/iso8601.gemspec

@@ -1,26 +1,30 @@
-# -*- encoding: utf-8 -*-
-$:.push File.expand_path("../lib", __FILE__)
-require "iso8601"
+# encoding: utf-8
+
+$:.push File.expand_path('../lib', __FILE__)
+require 'iso8601'
 
 Gem::Specification.new do |s|
-  s.name        = "iso8601"
-  s.version     = ISO8601::VERSION
-  s.authors     = ["Arnau Siches"]
-  s.email       = ["arnau.siches@gmail.com"]
-  s.homepage    = "https://github.com/arnau/ISO8601"
-  s.summary     = %q{Ruby parser to work with ISO8601 dateTimes and durations - http://en.wikipedia.org/wiki/ISO_8601}
-  s.description = %q{ISO8601 is a simple implementation of the ISO 8601 (Data elements and
-  interchange formats - Information interchange - Representation of dates and
-  times) standard.}
+  s.name = 'iso8601'
+  s.version = ISO8601::VERSION
+  s.date = Time.now.strftime('%Y-%m-%d')
+  s.authors = ['Arnau Siches']
+  s.email = 'arnau.siches@gmail.com'
+  s.homepage = 'https://github.com/arnau/ISO8601'
+  s.summary = "Ruby parser to work with ISO 8601 dateTimes and durations - http://en.wikipedia.org/wiki/ISO_8601"
+  s.description = <<-EOD
+    ISO8601 is a simple implementation in Ruby of the ISO 8601 (Data elements and 
+    interchange formats - Information interchange - Representation of dates 
+    and times) standard.
+  EOD
+  s.license = 'MIT'
+  s.rubyforge_project = 'iso8601'
 
-  s.rubyforge_project = "iso8601"
+  s.files = `git ls-files`.split("\n")
+  s.test_files = s.files.grep(%r{^(spec|features)/})
+  s.require_paths = ['lib']
 
-  s.files         = `git ls-files`.split("\n")
-  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
-  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
-  s.require_paths = ["lib"]
+  s.has_rdoc = 'yard'
 
-  # specify any dependencies here; for example:
-  # s.add_development_dependency "rspec"
-  # s.add_runtime_dependency "rest-client"
+  s.add_development_dependency 'rspec', '~> 2.0'
+  s.add_development_dependency 'ZenTest', '~> 4.8'
 end

data/lib/iso8601.rb

@@ -1,10 +1,12 @@
+# encoding: utf-8
+
 module ISO8601
-  VERSION = "0.2"
+  VERSION = '0.4.0'
 end
 
-require "time"
+require 'time'
 
-require "iso8601/errors"
-require "iso8601/atoms"
-require "iso8601/dateTime"
-require "iso8601/duration"
+require 'iso8601/errors'
+require 'iso8601/atoms'
+require 'iso8601/dateTime'
+require 'iso8601/duration'

data/lib/iso8601/atoms.rb

@@ -1,35 +1,51 @@
-module ISO8601
+# encoding: utf-8
 
-  # Represents a generic atom in a +ISO8601::Duration+.
+module ISO8601
+  ##
+  # A generic atom in a {ISO8601::Duration}
+  #
+  # @abstract
   class Atom
+    ##
+    # @param [Numeric] atom The atom value
+    # @param [ISO8601::DateTime, nil] base (nil) The base datetime to
+    #   compute the atom factor.
     def initialize(atom, base=nil)
-      is_number?(atom, "First argument for #{self.inspect} must be an Integer or a Float.")
+      raise TypeError, "The atom argument for #{self.inspect} should be a Numeric value." unless atom.kind_of? Numeric
+      raise TypeError, "The base argument for #{self.inspect} should be a ISO8601::DateTime instance or nil." unless base.kind_of? ISO8601::DateTime or base.nil?
       @atom = atom
       @base = base
     end
-
+    ##
+    # The integer representation of the atom
     def to_i
-      @atom
+      @atom.to_i
     end
+    ##
+    # The amount of seconds of the atom
     def to_seconds
       @atom * self.factor
     end
-
-    private
-      def is_number?(arg, error_message=nil)
-        raise TypeError, error_message unless (arg.is_a? Integer or arg.is_a? Float)
-      end
+    ##
+    # The atom factor to compute the amount of seconds for the atom
+    def factor
+      raise NotImplementedError, "The #factor method should be implemented for each subclass"
+    end
   end
-
+  ##
+  # A Years atom in a {ISO8601::Duration}
+  #
   # A “calendar year” is the cyclic time interval in a calendar which is
   # required for one revolution of the Earth around the Sun and approximated to
   # an integral number of “calendar days”.
-
-  #A “duration year” is the duration of 365 or 366 “calendar days” depending on
+  #
+  # A “duration year” is the duration of 365 or 366 “calendar days” depending on
   # the start and/or the end of the corresponding time interval within the
   # specific “calendar year”.
   class Years < ISO8601::Atom
-
+    ##
+    # The Year factor
+    #
     # The “duration year” 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”.
@@ -37,22 +53,27 @@ module ISO8601
       if @base.nil?
         ((365 * 303 + 366 * 97) / 400) * 86400
       elsif @atom == 0
-        0
+        year = (@base.year).to_i
+        (Time.utc(year) - Time.utc(@base.year))
       else
         year = (@base.year + @atom).to_i
         (Time.utc(year) - Time.utc(@base.year)) / @atom
       end
     end
   end
-
+  ##
+  # 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 < ISO8601::Atom
-
+    ##
+    # The Month factor
+    #
     # 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”.
@@ -60,7 +81,9 @@ module ISO8601
       if @base.nil?
         (((365 * 303 + 366 * 97) / 400) * 86400) / 12
       elsif @atom == 0
-        0
+        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))
       else
         month = (@base.month + @atom <= 12) ? (@base.month + @atom) : ((@base.month + @atom) % 12)
         year = @base.year + ((@base.month + @atom) / 12).to_i
@@ -68,47 +91,57 @@ module ISO8601
       end
     end
   end
-
+  ##
+  # A Weeks atom in a {ISO8601::Duration}
   class Weeks < ISO8601::Atom
-
-    # A week is equal to 604800 seconds.
+    ##
+    # The Week factor
     def factor
       604800
     end
   end
-
+  ##
+  # The Days atom in a {ISO8601::Duration}
+  #
   # A “calendar day” is the time interval which starts at a certain time of day
   # at a certain “calendar day” and ends at the same time of day at the next
   # “calendar day”.
   class Days < ISO8601::Atom
-
-    # A day is equal to 86400 seconds.
+    ##
+    # The Day factor
     def factor
       86400
     end
   end
-
+  ##
+  # The Hours atom in a {ISO8601::Duration}
   class Hours < ISO8601::Atom
-
-    # An hour is equal to 3600 seconds.
+    ##
+    # The Hour factor
     def factor
       3600
     end
   end
+  ##
+  # The Minutes atom in a {ISO8601::Duration}
   class Minutes < ISO8601::Atom
-
-    # A minute is equal to 60 seconds.
+    ##
+    # The Minute factor
     def factor
       60
     end
   end
-
+  ##
+  # 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 (CIPM, i.e. Comité International des Poids et Mesures)
   class Seconds < ISO8601::Atom
+    ##
+    # The Second factor
     def factor
       1
     end
   end
-end
+end

data/lib/iso8601/dateTime.rb

@@ -1,32 +1,42 @@
+# encoding: utf-8
+
 module ISO8601
+  ##
+  # A DateTime representation
+  #
+  # @todo Review the pattern `201005`. It has to be `20-10-05` instead of `2010-05`.
+  #   The specification doesn't allow a YYYYMM. It should be always
+  #   YYYY-MM.
   class DateTime
-    attr_reader :date_time, :century, :year, :month, :day, :hour, :minute, :second, :timezone
+    attr_reader :century, :year, :month, :day, :hour, :minute, :second, :timezone
+    ##
+    # @param [String] date_time The datetime pattern
     def initialize(date_time)
       @dt = /^(?:
-                (\d{2})(\d{2})?
+                (\d{2})(\d{2})? # Year. It can be either two digits (the century) or four digits (the full year)
                 (?:
                   (-)?(\d{2})
-                )?
+                )? # Month with an optional separator
                 (?:
-                  (\3)?(\d{2})
+                  (\3)?(\d{2}) # Day with an optional separator which is the same for the Month
                 )?
-              )?
+              )? # Date
               (?:
-                T(\d{2})
+                T(\d{2}) # Hour
                 (?:
-                  (:)?(\d{2})
+                  (:)?(\d{2}) # Minute with an optional separator
                 )?
                 (?:
-                  (\8)?(\d{2})
-                )?
+                  (\8)?(\d{2}) # Second with an optional separator which is the same that for the Minute
+                )? # Time
                 (
                   Z|([+-])
-                    (\d{2})
+                    (\d{2}) # Timezone hour
                     (?:
-                      (\8)?
-                      (\d{2})
+                      (\8)? # Separator which should be the same that for the Minute
+                      (\d{2}) # Timezone minute
                     )?
-                )?
+                )? # Timezone
               )?
             $/x.match(date_time) or raise ISO8601::Errors::UnknownPattern.new(date_time)
 
@@ -52,12 +62,21 @@ module ISO8601
         :full => @dt[12].nil? ? (Time.now.gmt_offset / 3600) : (@dt[12] == "Z" ? 0 : @dt[12]),
         :sign => @dt[13],
         :hour => @dt[12].nil? ? (Time.now.gmt_offset / 3600) : (@dt[12] == "Z" ? 0 : @dt[14].to_i),
-        :minute => (@dt[12].nil? or @dt[12] == "Z") ? 0 : @dt[14].to_i
+        :minute => (@dt[12].nil? or @dt[12] == "Z") ? 0 : @dt[13].to_i
       }
 
       valid_pattern?
       valid_range?
     end
+    ##
+    # Returns the datetime string representation
+    def to_s
+      @date_time
+    end
+    ##
+    # Converts the object to a Time instance
+    #
+    # @return [Time] The object converted
     def to_time
       raise RangeError if @year.nil?
       if @month.nil?
@@ -69,17 +88,21 @@ module ISO8601
         Time.parse(@date_time).getutc
       end
     end
+    ##
+    # Addition
+    #
+    # @param [ISO8601::DateTime] The seconds to add
     def +(d)
-      raise TypeError unless (d.is_a? Float or d.is_a? Integer)
-      Time.utc(@year, @month, @day, @hour, @minute, @second) + d
+      raise TypeError unless d.kind_of? Numeric
+      ISO8601::DateTime.new((Time.utc(@year, @month, @day, @hour, @minute, @second) + d).iso8601)
     end
+    ##
+    # Substraction
+    #
+    # @param [ISO8601::DateTime] The seconds to substract
     def -(d)
-      raise TypeError unless (d.is_a? Float or d.is_a? Integer or d.is_a? ISO8601::DateTime)
-      if (d.is_a? ISO8601::DateTime)
-        Time.utc(@year, @month, @day, @hour, @minute, @second) - Time.utc(d.year, d.month, d.day, d.hour, d.minute, d.second)
-      else
-        Time.utc(@year, @month, @day, @hour, @minute, @second) - d
-      end
+      raise TypeError unless d.kind_of? Numeric
+      ISO8601::DateTime.new((Time.utc(@year, @month, @day, @hour, @minute, @second) - d).iso8601)
     end
     private
       def valid_pattern?

data/lib/iso8601/duration.rb

@@ -1,11 +1,37 @@
-module ISO8601
+# encoding: utf-8
 
+module ISO8601
+  ##
   # Represents a duration in ISO 8601 format
+  #
+  # @todo Support fraction values for years, months, days, weeks, hours
+  #   and minutes
   class Duration
     attr_reader :base, :atoms
-    def initialize(duration, base = nil)
-      @duration = /^(\+|-)?P(((\d+Y)?(\d+M)?(\d+D)?(T(\d+H)?(\d+M)?(\d+(?:\.\d+)?S)?)?)|(\d+W))$/.match(duration)
-      @base = base #date base for duration calculations
+    ##
+    # @param [String, Numeric] pattern The duration pattern
+    # @param [ISO8601::DateTime, nil] base (nil) The base datetime to
+    #   calculate the duration properly
+    def initialize(pattern, base = nil)
+      # we got seconds instead of an ISO8601 duration
+      pattern = "PT#{pattern}S" if (pattern.kind_of? Numeric)
+      @duration = /^(\+|-)? # Sign
+                   P(
+                      (
+                        (\d+Y)? # Years
+                        (\d+M)? # Months
+                        (\d+D)? # Days
+                        (T
+                          (\d+H)? # Hours
+                          (\d+M)? # Minutes
+                          (\d+(?:\.\d+)?S)? # Seconds
+                        )? # Time
+                      )
+                      |(\d+W) # Weeks
+                    ) # Duration
+                  $/x.match(pattern) or raise ISO8601::Errors::UnknownPattern.new(pattern)
+
+      @base = base
       valid_pattern?
       valid_base?
       @atoms = {
@@ -18,86 +44,117 @@ module ISO8601
         :seconds => @duration[10].nil? ? 0 : @duration[10].chop.to_f * sign
       }
     end
-
+    ##
+    # Assigns a new base datetime
+    #
+    # @return [ISO8601::DateTime, nil]
     def base=(value)
       @base = value
+      valid_base?
       return @base
     end
-
-    # Returns the original string of the duration
+    ##
+    # @return [String] The string representation of the duration
     def to_s
       @duration[0]
     end
-
-    # Returns the years of the duration
+    ##
+    # @return [ISO8601::Years] The years of the duration
     def years
       ISO8601::Years.new(@atoms[:years], @base)
     end
-
-    # Returns the months of the duration
+    ##
+    # @return [ISO8601::Months] The months of the duration
     def months
-      base = @base.nil? ? nil : @base + self.years.to_seconds # prevent computing duplicated time
+      # Changes the base to compute the months for the right base year
+      base = @base.nil? ? nil : @base + self.years.to_seconds
       ISO8601::Months.new(@atoms[:months], base)
     end
-
-    # Returns the weeks of the duration
+    ##
+    # @return [ISO8601::Weeks] The weeks of the duration
     def weeks
       ISO8601::Weeks.new(@atoms[:weeks], @base)
     end
-
-    # Returns the days of the duration
+    ##
+    # @return [ISO8601::Days] The days of the duration
     def days
       ISO8601::Days.new(@atoms[:days], @base)
     end
-
-    # Returns the hours of the duration
+    ##
+    # @return [ISO8601::Hours] The hours of the duration
     def hours
       ISO8601::Hours.new(@atoms[:hours], @base)
     end
-
-    # Returns the minutes of the duration
+    ##
+    # @return [ISO8601::Minutes] The minutes of the duration
     def minutes
       ISO8601::Minutes.new(@atoms[:minutes], @base)
     end
-
-    # Returns the seconds of the duration
+    ##
+    # @return [ISO8601::Seconds] The seconds of the duration
     def seconds
       ISO8601::Seconds.new(@atoms[:seconds], @base)
     end
-
-    # Returns the duration in seconds
+    ##
+    # @return [Numeric] The duration in seconds
     def to_seconds
       years, months, weeks, days, hours, minutes, seconds = self.years.to_seconds, self.months.to_seconds, self.weeks.to_seconds, self.days.to_seconds, self.hours.to_seconds, self.minutes.to_seconds, self.seconds.to_seconds
       return years + months + weeks + days + hours + minutes + seconds
     end
-
-    # Returns the absolute value of duration
+    ##
+    # @return [ISO8601::Duration] The absolute representation of the duration
     def abs
-      return self.to_s.sub!(/^[-+]/, "")
-    end
-
+      absolute = self.to_s.sub(/^[-+]/, '')
+      return ISO8601::Duration.new(absolute)
+    end
+    ##
+    # Addition
+    #
+    # @param [ISO8601::Duration] duration The duration to add
+    #
+    # @raise [ISO8601::Errors::DurationBaseError] If bases doesn't match
+    # @return [ISO8601::Duration]
     def +(duration)
-      raise ISO8601::Errors::DurationBaseError.new(duration) if self.base != duration.base
-      d1 = self.to_seconds
+      raise ISO8601::Errors::DurationBaseError.new(duration) if @base.to_s != duration.base.to_s
+      d1 = to_seconds
       d2 = duration.to_seconds
-      return self.seconds_to_iso(d1 + d2)
-    end
+      return seconds_to_iso(d1 + d2)
+    end
+    ##
+    # Substraction
+    #
+    # @param [ISO8601::Duration] duration The duration to substract
+    #
+    # @raise [ISO8601::Errors::DurationBaseError] If bases doesn't match
+    # @return [ISO8601::Duration]
     def -(duration)
-      raise ISO8601::Errors::DurationBaseError.new(duration) if self.base != duration.base
-      d1 = self.to_seconds
+      raise ISO8601::Errors::DurationBaseError.new(duration) if @base.to_s != duration.base.to_s
+      d1 = to_seconds
       d2 = duration.to_seconds
-      return self.seconds_to_iso(d1 - d2)
-      # return d1 - d2
+      duration = d1 - d2
+      if duration == 0
+        return ISO8601::Duration.new('PT0S')
+      else
+        return seconds_to_iso(duration)
+      end
     end
-
-    # Convenience method to turn instance method (which can take into
-    # account a base time or duration) into a simple class method.
-    def self.seconds_to_iso(duration)
-      return ISO8601::Duration.new('P0Y').seconds_to_iso(duration)
+    ##
+    # @param [ISO8601::Duration] duration The duration to compare
+    #
+    # @raise [ISO8601::Errors::DurationBaseError] If bases doesn't match
+    # @return [Boolean]
+    def ==(duration)
+      raise ISO8601::Errors::DurationBaseError.new(duration) if @base.to_s != duration.base.to_s
+      (self.to_seconds == duration.to_seconds)
     end
 
+    private
+    ##
+    # @param [Numeric] duration The seconds to promote
+    #
+    # @return [ISO8601::Duration]
     def seconds_to_iso(duration)
-      sign = "-" if (duration < 0)
+      sign = '-' if (duration < 0)
       duration = duration.abs
       years, y_mod = (duration / self.years.factor).to_i, (duration % self.years.factor)
       months, m_mod = (y_mod / self.months.factor).to_i, (y_mod % self.months.factor)
@@ -119,22 +176,21 @@ module ISO8601
       return ISO8601::Duration.new(date_time)
     end
 
-    private
-      def sign
-        (@duration[1].nil? or @duration[1] == "+") ? 1 : -1
-      end
-      def valid_base?
-        if !(@base.is_a? NilClass or @base.is_a? ISO8601::DateTime)
-          raise TypeError
-        end
+    def sign
+      (@duration[1].nil? or @duration[1] == "+") ? 1 : -1
+    end
+    def valid_base?
+      if !(@base.nil? or @base.kind_of? ISO8601::DateTime)
+        raise TypeError
       end
-      def valid_pattern?
-        if @duration.nil? or
-           (@duration[4].nil? and @duration[5].nil? and @duration[6].nil? and @duration[7].nil? and @duration[11].nil?) or
-           (!@duration[7].nil? and @duration[8].nil? and @duration[9].nil? and @duration[10].nil? and @duration[11].nil?)
+    end
+    def valid_pattern?
+      if @duration.nil? or
+         (@duration[4].nil? and @duration[5].nil? and @duration[6].nil? and @duration[7].nil? and @duration[11].nil?) or
+         (!@duration[7].nil? and @duration[8].nil? and @duration[9].nil? and @duration[10].nil? and @duration[11].nil?)
 
-          raise ISO8601::Errors::UnknownPattern.new(@duration)
-        end
+        raise ISO8601::Errors::UnknownPattern.new(@duration)
       end
+    end
   end
 end