timesteps 0.9.6 → 0.9.7

data/lib/timesteps/timestep.rb

@@ -1,8 +1,104 @@
 
+# TimeStep class
+#
+#
 class TimeStep
 
   using DateTimeExt
 
+  # @private
+  CALENDARS = {}
+
+  [
+    "standard", 
+    "gregorian",
+    "proleptic_gregorian",
+    "proleptic_julian",
+    "julian",
+    "noleap",
+    "365_day",
+    "allleap",
+    "366_day",
+    "360_day",
+  ].each do |calendar|
+    CALENDARS[calendar] = Calendar.new(calendar)
+  end
+
+  # @private
+  PATTERN_NUMERIC = '[\+\-]?\d*(?:\.\d+)?(?:[eE][\+\-]?\d+)?'
+
+  # @private
+  PATTERN_UNITS   = [
+    'years?',
+    'months?',
+    'days?',
+    'hours?',
+    'minutes?',
+    'seconds?',
+    'd',
+    'hrs?',
+    'h',
+    'mins?',
+    'secs?',
+    's',
+    'milliseconds?',
+    'msecs?',
+    'ms',
+    'microseconds?', 
+    '(?:weeks?|w)(?:\-(?:sun|mon|tue|wed|thu|fri|sat))?',
+    'sundays?',
+    'mondays?',
+    'tuesdays?',
+    'wednesdays?',
+    'thursdays?',
+    'fridays?',
+    'saturdays?',
+    'ayears?',
+  ].join("|")
+
+  # @private
+  WDAY = {
+    sun: 0, mon: 1, tue: 2, wed: 3, thu: 4, fri: 5, sat: 6,
+  }
+
+  # @private
+  WDAY_NAME = {
+    sun: "sundays",
+    mon: "mondays",
+    tue: "tuesdays",
+    wed: "wednesdays",
+    thu: "thursdays",
+    fri: "fridays",
+    sat: "saturdays",
+  }
+
+  # Extracts numeric part and symbol part from the given interval specification.
+  #
+  # @example
+  #   TimeStep.split_interval_spec("12 months")
+  #   # => [12, "months"]
+  #
+  #   TimeStep.split_interval_spec("month-end")
+  #   # => [1, "month-end"]
+  #
+  # @param [String] interval specification (ex. "12 months", "3 hours", "year")
+  # @return [Array(Numeric, String)] A pair of `numeric` and `symbol` 
+  #
+  def self.split_interval_spec (spec)
+    if spec.strip =~ /\A(#{PATTERN_NUMERIC}|)\s*((?:#{PATTERN_UNITS}).*)\z/i
+      numeric = if $1 == ""
+                  1
+                else
+                  Float($1)
+                end
+      numeric = numeric.to_i if numeric.denominator == 1
+      symbol = $2
+    else
+      raise "the interval specification '#{spec}' is invalid."
+    end
+    return numeric, symbol
+  end
+
   # Constructs the object.
   #
   # The argument `spec` specifies the time step definition, which has the form,
@@ -12,6 +108,7 @@ class TimeStep
   #   * "hour since 2001-01-01 00:00:00 JST" 
   #   * "3 days since 2001-01-01 00:00:00 +00:00" 
   #   * "10 years since 1901-01-01 00:00:00 +00:00" 
+  #
   # The symbol for time unit symbols should be one of
   #   * ayears, ayear (astronomical year: 365.242198781 day)
   #   * years, year
@@ -22,12 +119,16 @@ class TimeStep
   #   * seconds, second, secs, sec, s
   #   * milliseconds, millisecond, msecs, msec, ms
   #   * microseconds, microsecond
+  #
   # If you have already origin time object or general date string, 
   # you can use `since` option,
   #     TimeStep.new("3 hours", since: time)
   #     TimeStep.new("3 hours", since: "2001010121", format: '%Y%m%d%H')
-  # The option count specifies the number of time steps, which is hint for 
-  # some methods (#each etc).
+  # When origin time is specified in both 'spec' and 'since' option, 
+  # the origin time in 'spec' has priority.
+  # If origin time is not specified in neither 'spec' and 'since' option,
+  # the default value is set to the origin time ("0000-01-01 00:00:00" for date and "1970-01-01 00:00:00" for time).
+  # The time offset from UTC can be set by 'offset' option. 
   # The option `calendar` specifies the name of calendar for datetime calculation,
   #   * "standard", "gregorian"      -> DateTime with Date::ITALY as start
   #   * "proleptic_gregorian"        -> DateTime with Date::GREGORIAN as start
@@ -35,100 +136,125 @@ class TimeStep
   #   * "noleap", "365_day"          -> DateTimeNoLeap
   #   * "allleap", "366_day"         -> DateTimeAllLeap
   #   * "360_day"                    -> DateTimeFixed360Day
-  # The option `bc` is a flag whether AD/BC or EC when parsing timestamp for
-  # negative year.
-  #
-  # @param spec [String]
-  # @option since [DateTime, DateTimeLike, String]
-  # @option format [String]
-  # @option calendar [String, TimeStep::Calendar]
-  # @option bc [Boolean]
-  # @option count [Integer] number of time steps (as hint for some methods)
+  #
+  # @param  spec [String] timestep specification
+  # @param since [DateTime, String]  
+  # @param offset [Numeric, String] offset in origin time
+  # @param format [String] template string for strptime for parsing time
+  # @param calendar [String, TimeStep::Calendar] 
   # 
-  def initialize (spec, since: nil, format: nil, count: nil, calendar: "standard", bc: false)
-    @calendar = Calendar.new(calendar, bc: bc)
-    if since
-      parse_interval(spec)
-      case since
-      when String
-        @origin = @calendar.parse(since, format: format)
+  def initialize (spec, since: nil, offset: nil, format: nil, calendar: "standard", tz: nil)
+
+    case calendar
+    when String
+      if tz
+        raise "tz option can be used only with 'standard' calendar type" if calendar != "standard"
+        @calendar = Calendar.new(calendar, tz: tz) 
       else
-        unless @calendar.valid_datetime_type?(since)
-          raise "calendar of the given date-time object doesn't match with the given calendar in option" 
-        end
-        @origin = since
+        @calendar = CALENDARS[calendar]
+        raise "specified calendar type '#{calendar}' is invalid" unless @calendar
       end
+    when TimeStep::Calendar
+      @calendar = calendar
     else
-      spec1, spec2 = spec.split(/\s+since\s+/)
-      parse_interval(spec1)
-      @origin = @calendar.parse(spec2)
+      raise "invalid object for option 'calendar'" 
     end
-    @count = count
-  end
-
-  def interval_spec
-    return format("%g %s", @numeric, @symbol)
-  end
-
-  def origin_spec
-    return @origin.strftime("%Y-%m-%d %H:%M:%S.%N %:z")
-  end
 
-  def definition
-    format("%s since %s", interval_spec, origin_spec)
+    if spec =~ /\s+since\s+/
+      interval_spec, time_spec = $~.pre_match, $~.post_match
+      parse_interval(interval_spec)
+      @origin = @calendar.parse(time_spec, offset: offset)
+    else
+      parse_interval(spec)
+      @origin = case since
+                when nil
+                  case @symbol
+                  when :hours, :minutes, :seconds
+                    @calendar.parse("1970-1-1", offset: offset)          
+                  else
+                    @calendar.parse("0000-1-1", offset: offset)          
+                  end
+                when String
+                  @calendar.parse(since, format: format, offset: offset)
+                when Time
+                  since.to_datetime
+                else
+                  raise "datetime mismatched with calendar type" unless @calendar.valid_datetime_type?(since)
+                  since
+                end
+    end
+    
+    if @wday
+      origin = @origin - @origin.wday + WDAY[@wday]
+      origin -= 7 unless @origin >= origin
+      @origin = origin
+    end
+    
   end
 
   # @private
-  PATTERN_NUMERIC = '[\+\-]?\d*(?:\.\d+)?(?:[eE][\+\-]?\d+)?'
-  # @private
-  PATTERN_UNITS   = 'ayears?|years?|months?|days?|hours?|minutes?|seconds?|d|hrs?|hrs?|h|mins?|secs?|s|milliseconds?|msecs?|ms|microseconds?'
-
   def parse_interval (spec)
-    if spec.strip =~ /(#{PATTERN_NUMERIC}|)\s*(#{PATTERN_UNITS})/
-      if $1 == ""
-        @numeric = 1.to_r
-      else
-        @numeric = Float($1).to_r
-      end
+    if spec.strip =~ /\A(#{PATTERN_NUMERIC}|)\s*(#{PATTERN_UNITS})\z/i
+      @numeric = if $1 == ""
+                   1.to_r
+                 else
+                   Float($1).to_r
+                 end
       symbol = $2
     else
       raise "the interval specification '#{spec}' is invalid."
     end
     @interval = @numeric
     case symbol
-    when /\Aayears?/
-      @symbol = :days
-      @numeric *= 365.242198781.to_r
-      @interval = @numeric * 86400
-    when /\Ayears?/
+    when /\Ayears?\z/i
       unless numeric.denominator == 1
         raise "numeric factor for year should be an integer"
       end
       @symbol = :years
       @interval *= 356.242*86400
-    when /\Amonths?/
+    when /\Amonths?\z/i
       unless numeric.denominator == 1
         raise "numeric factor for month should be an integer"
       end
       @symbol = :months
       @interval *= 30.4368*86400
-    when /\A(days?|d)/
+    when /\A(days?|d)\z/i
       @symbol = :days
       @interval *= 86400
-    when /\A(hours?|hrs?|h)/
+    when /\A(hours?|hrs?|h)\z/i
       @symbol = :hours
       @interval *= 3600
-    when /\A(minutes?|mins?)/
+    when /\A(minutes?|mins?)\z/i
       @symbol = :minutes
       @interval *= 60
-    when /\A(seconds?|secs?|s)/
+    when /\A(seconds?|secs?|s)\z/i
       @symbol = :seconds
-    when /\A(milliseconds?|msecs?|ms)/
+    when /\A(milliseconds?|msecs?|ms)\z/i
       @symbol = :seconds
       @interval *= 1.quo(1000)
-    when /\Amicroseconds?/
+    when /\Amicroseconds?\z/i
       @symbol = :seconds
       @interval *= 1.quo(1000000)
+    when /\A(weeks?|w)\-(sun|mon|tue|wed|thu|fri|sat)\z/i
+      symbol =~ /\A(weeks?|w)\-(\w{3})/i
+      @wday   = $2.downcase.intern
+      @symbol = WDAY_NAME[@wday].intern ### :sundays, :mondays, ...
+      @interval *= 7*86400
+    when /\A(weeks?|w)\z/i
+      @symbol = :weeks
+      @interval *= 7*86400
+    when /\Asundays?|mondays?|tuesdays?|wednesdays?|thursday?|fridays?|saturdays?\z/i
+      symbol =~ /\A(\w{3})/i
+      @wday   = $1.downcase.intern
+      @symbol = WDAY_NAME[@wday].intern ### :sundays, :mondays, ...
+      @interval *= 7*86400
+    when /\Aayears?\z/i
+      @symbol = :days
+      @numeric *= 365.242198781.to_r
+      @interval = @numeric * 86400
+    end
+    if @numeric.denominator == 1
+      @numeric = @numeric.to_i
     end
   end
   
@@ -140,120 +266,119 @@ class TimeStep
               :origin, 
               :calendar
 
-  attr_accessor :count
-
-  # Returns limit time if the object has `count`, otherwise returns nil.
-  #
-  # @return [DateTime, nil]
-  def limit
-    if @count
-      return time_at(@count - 1)
+  # Returns a string expression for interval section in timestem spec.
+  # 
+  # @return [String]
+  def interval_spec
+    if @wday
+      return format("%g %s", @numeric, WDAY_NAME[@wday])      
     else
-      return nil
+      return format("%g %s", @numeric, @symbol)
     end
   end
 
-  # Sets count by giving maximum time.
-  # 
-  # @return [DateTime, nil]
-  def limit= (time)
-    if time
-      @count = next_index_of(time).to_i
+  # Returns a string expression for origin time section in timestep spec.
+  #
+  # @return [String]
+  def origin_spec
+    if @calendar.tz
+      return @origin.strftime("%Y-%m-%d %H:%M:%S.%N %:z %Z")
     else
-      @count = nil
+      return @origin.strftime("%Y-%m-%d %H:%M:%S.%N %:z")
     end
-    return limit
-  end
-  
-  # Sets count by giving maximum time.
-  # 
-  def set_limit (time, format: nil)
-    case time
-    when String
-      time = @calendar.parse(time, format: format)
-    end
-    self.limit = time
   end
 
-  def valid? (*indices)
-    if @count
-      if indices.size == 1
-        index = indices.first
-        if index >= 0 and index < @count 
-          return true
-        else
-          return false
-        end
-      else
-        return indices.map{|index| valid?(index) }
-      end
-    else
-      if indices.size == 1
-        return true
-      else
-        return indices.map{|index| true }
-      end
-    end
+  # Returns a string expression of definition of timestep.
+  # The return value can be used for constructs other TimeStep object.
+  #
+  # @return [String]
+  def definition
+    format("%s since %s", interval_spec, origin_spec)
   end
 
-  def debug_info
-    return {
-      "definition"   => definition,
-      "interval_spec" => interval_spec,
-      "origin_spec"   => origin_spec,
-      "calendar"     => @calendar.name,
-      "numeric"      => @numeric,
-      "symbol"       => @symbol.to_s,
-      "interval"     => @interval,
-      "origin"       => @origin.clone,
-      "count"        => @count,
-      "bc"           => @calendar.bc?,
-    }
+  # Returns the time offset of origin time.
+  #
+  # @return [Rational]
+  def offset
+    return @origin.offset
   end
 
-  private :debug_info
+  # Parses datetime string and return datetime object.
+  # In the parsing, the calendar of the object is used.
+  # If `format` option is given, `strptime` method is 
+  # used for the parsing. Otherwise, the `parse` is used.
+  #
+  # @param time [String] string to be parsed
+  # @param format [String] template string for strptime for parsing time
+  #
+  # @return [DateTime]
+  def parse (time, format: nil)
+    return @calendar.parse(time, format: format, offset: @origin.offset)
+  end
 
-  # Returns the value as a string for inspection.
+  # Returns a string for inspection.
   #
+  # @return [String]
   def inspect
-    "#<TimeStep definition='#{definition}' calendar='#{calendar.name}'>"
+    options = ""
+    case @calendar.name
+    when "standard", "gregorian"
+    else
+      options << " calendar='#{calendar.name}'"
+    end
+    "#<TimeStep definition='#{definition}'#{options}>"      
   end
 
   # Returns true if other has same contents of `definition` and `calendar` 
   # as self has.
   #
+  # @param other [TimeStep]
+  # 
   # @return [Boolean]
   def == (other)
     return definition == other.definition && @calendar == other.calendar 
   end
 
+  # @private
   def user_to_days (index)
     return ( @interval * index.to_r ).quo(86400)
   end
 
+  # @private
   def days_to_user (index)
-    return ( 86400 * index.to_r ).quo(@interval)
+    if @interval == 0
+      return 0
+    else
+      return ( 86400 * index.to_r ).quo(@interval)
+    end
   end
 
   private :user_to_days, :days_to_user
 
-  # Returns the time represented by the given amount as DateTime object
+  # Returns the datetime object (array) for the given index (indices).
   #
-  # @param indices [Numeric,Array<Numeric>]
+  # @example
+  #   ts = TimeStep.new("days since 2001-01-01 00:00:00")
+  #   ts.time_at(0)
+  #   # => #<DateTime: 2001-01-01T00:00:00+00:00 ...>
+  #   ts.time_at(14)
+  #   # => #<DateTime: 2001-01-15T00:00:00+00:00 ...>
   #
-  # @return [DateTime]
+  # @param indices [Array<Numeric>]
+  #
+  # @return [DateTime, Array<DateTime>]
   def time_at (*indices)
     if indices.size == 1
       index = indices.first
       raise ArgumentError, "index argument should be a numeric" unless index.is_a?(Numeric)
       case @symbol
       when :years
-        unless index.denominator == 1
+        unless (index*@numeric).denominator == 1
           raise ArgumentError, "index argument should be an integer for years"
         end
         return @origin.next_year(index*@numeric)
       when :months
-        unless index.denominator == 1
+        unless (index*@numeric).denominator == 1
           raise ArgumentError, "index argument should be an integer for months"
         end
         return @origin.next_month(index*@numeric)
@@ -268,27 +393,39 @@ class TimeStep
     end
   end
     
-  # Calculate the duration in days since origin time at the given index.
+  alias [] time_at
+  
+  # Calculate the duration (array) in day unit since origin time at the given index (indices).
+  #
+  # @example
+  #   ts = TimeStep.new("hours since 2001-01-01 00:00:00")
+  #   ts.duration_at(0)
+  #   # => 0                   ### 0 days
+  #   ts.duration_at(12)
+  #   # => (1/2)               ### half of a day
+  #   ts.duration_at(14*24)
+  #   # => 14                  ### 14 days
+  #
+  # @param indices [Array<Numeric>]
   #
-  # @param indices [Array]
   # @return [DateTime, Array<DateTime>]
   def duration_at (*indices)
     if indices.size == 1
       index = indices.first
-      case @symbol
-      when :years
-        unless index.denominator == 1
-          raise ArgumentError, "index argument should be an integer for years"
-        end
-        days = @origin.next_year(@numeric*index) - @origin
-      when :months
-        unless index.denominator == 1
-          raise ArgumentError, "index argument should be an integer for months"
-        end
-        days = @origin.next_month(@numeric*index) - @origin
-      else
-        days = user_to_days(index)
-      end
+      days = case @symbol
+             when :years
+               unless (index*@numeric).denominator == 1
+                 raise ArgumentError, "index argument should be an integer for years"
+               end
+               @origin.next_year(@numeric*index) - @origin
+             when :months
+               unless (index*@numeric).denominator == 1
+                 raise ArgumentError, "index argument should be an integer for months"
+               end
+               @origin.next_month(@numeric*index) - @origin
+             else
+               user_to_days(index)
+             end
       days = days.to_i if days.denominator == 1
       return days
     else
@@ -296,20 +433,34 @@ class TimeStep
     end
   end
   
-  # Returns the index for the given time in the unit represented by the object
+  # Returns the index (indices) for the given time (array).
   #
-  # @param times [DateTime] time object
+  # @example
+  #   ts = TimeStep.new("days since 2001-01-01 00:00:00")
+  #   ts.index_at(ts.parse("2001-01-01 00:00:00"))
+  #   # => 0 
+  #   ts.index_at("2001-01-15 00:00:00")
+  #   # => 14
+  #   ts.index_at("2002")
+  #   # => 365
   #
-  # @return [Numeric]
+  # @param times [Array<DateTime>] 
+  # @param format [String] template string for strptime for parsing time
+  #
+  # @return [Numeric, Array<Numeric>]
   def index_at (*times, format: nil)
     if times.size == 1
       time = times.first
-      time = @calendar.parse(time, format: format) if time.is_a?(String)
+      time = @calendar.parse(time, format: format, offset: @origin.offset) if time.is_a?(String)
       case @symbol
       when :years
-        index = time.difference_in_years(@origin).quo(@numeric.to_i)
+        diff = time.difference_in_years(@origin)
+        frac = diff - diff.floor
+        index = diff.floor.quo(@numeric.to_i) + frac
       when :months
-        index = time.difference_in_months(@origin).quo(@numeric.to_i)
+        diff = time.difference_in_months(@origin)
+        frac = diff - diff.floor
+        index = diff.floor.quo(@numeric.to_i) + frac
       else
         jday  = @calendar.date2jday(time.year, time.month, time.day)
       	fday  = time.fraction 
@@ -324,146 +475,225 @@ class TimeStep
     end
   end
     
-  # Returns TimeStep object which has origin time determined 
-  # by the given `index`.
+  # Returns new timestep object which has new origin time specified by `index`.
+  #
+  # @example
+  #   ts = TimeStep.new("days since 2001-01-01 00:00:00")
+  #   # => #<TimeStep definition='1 days since 2001-01-01 00:00:00.000000000 +00:00'>
+  #   ts.shift_origin(14)
+  #   # => #<TimeStep definition='1 days since 2001-01-15 00:00:00.000000000 +00:00'>
+  #   ts.shift_origin(365)
+  #   # => #<TimeStep definition='1 days since 2002-01-01 00:00:00.000000000 +00:00'>
   #
   # @param index [Numeric]
+  # @param with [String, Symbol] "index" : shift by index , "duration" : shift by duration
   #
   # @return [TimeStep]
-  def shift_origin (index)
-    time = time_at(index)
-    return TimeStep.new(interval_spec, since: time, calendar: @calendar.name, bc: @calendar.bc?)
-  end
-
-  def shift_origin_with_duration (duration)
-    time = @origin + duration
-    return TimeStep.new(interval_spec, since: time, calendar: @calendar.name, bc: @calendar.bc?)
+  def shift_origin (index, with: "index")
+    case with
+    when :index, "index"
+      time = time_at(index)
+      return TimeStep.new(interval_spec, since: time, calendar: @calendar)
+    when :duration, "duration", :days, "days"
+      time = @origin + index
+      return TimeStep.new(interval_spec, since: time, calendar: @calendar)
+    end
   end
 
-  # Returns TimeStep object which has origin time specified 
-  # by the given `time`.
+  # Returns new timestep object which holds the given time as origin.
   #
-  # @param time [DateTime]
+  # @example
+  #   ts = TimeStep.new("days since 2001-01-01 00:00:00")
+  #   # => #<TimeStep definition='1 days since 2001-01-01 00:00:00.000000000 +00:00'>
+  #   ts.new_origin(ts.parse("2001-01-15"))
+  #   # => #<TimeStep definition='1 days since 2001-01-15 00:00:00.000000000 +00:00'>
+  #   ts.new_origin("2001-01-15")
+  #   # => #<TimeStep definition='1 days since 2001-01-15 00:00:00.000000000 +00:00'>
+  #   ts.new_origin("2002")
+  #   # => #<TimeStep definition='1 days since 2002-01-01 00:00:00.000000000 +00:00'>
+  #
+  # @param time [DateTime, String]
   #
   # @return [TimeStep]
   def new_origin (time)
-    case time
-    when String
-      time = @calendar.parse(time)
+    time = @calendar.parse(time, offset: @origin.offset) if time.is_a?(String)
+    if @wday
+      origin = time - time.wday + WDAY[@wday]
+      origin -= 7 unless time >= origin
+      time = origin
     end
-    return TimeStep.new(interval_spec, since: time, calendar: @calendar.name, bc: @calendar.bc?)
+    return TimeStep.new(interval_spec, since: time, calendar: @calendar)
   end
 
-  include Enumerable
-  
-  def each (limit = nil, incr = 1, &block)
-    if limit.nil? 
-      raise "count (or limit) is required by #step" unless @count
-      limit = @count - 1
-    end
-    if block
-      0.step(limit, incr) do |k|
-        block.call(time_at(k))
-      end
-    else
-      return Enumerator.new {|y|
-        0.step(limit, incr) do |k|
-          y << time_at(k)
-        end      
-      }
-    end
-  end
-  
-  def times (&block)
-    raise "count (or limit) is required by #step" unless @count
-    (0...@count).each(&block)
-  end
-  
-  # Creates TimeStep::Pair 
+  # Truncate the given datetime to the unit of the object.
   #
+  # @example
+  #   hours = TimeStep.new("hours since 2001-01-01 00:00:00")
+  #   hours.truncate("2001-01-15 12:35:00")
+  #   # => #<DateTime: 2001-01-15T12:00:00+00:00 ...>
   #
-  def in (unit)
-    return TimeStep::Pair.new(self, format("%s since %s", unit, origin_spec), calendar: @calendar.name, bc: @calendar.bc?)
+  #   days = TimeStep.new("days since 2001-01-01 00:00:00")
+  #   days.truncate("2001-01-15 12:00:00")
+  #   # => #<DateTime: 2001-01-15T00:00:00+00:00 ...>
+  #
+  #   months = TimeStep.new("months since 2001-01-01 00:00:00")
+  #   months.truncate("2001-05-15 12:00:00")
+  #   # => #<DateTime: 2001-05-01T00:00:00+00:00 ...>
+  #
+  # @param time [DateTime, String]
+  #
+  # @return [DateTime]
+  def truncate (time)
+    return time_at(index_at(time).floor)
   end
-  
+
   # Returns next integer index of the given time
+  #
+  # @example
+  #   ts = TimeStep.new("days since 2001-01-01 00:00:00")
+  #   ts.next_index_of("2001-01-14 12:00:00")
+  #   #=> 14
+  #   ts.next_index_of("2001-01-15 00:00:00")
+  #   #=> 15
+  #
+  # @param time [DateTime, String]
+  #
+  # @return [Numeric]
   def next_index_of (time)
-    case time
-    when String
-      time = @calendar.parse(time)
-    end
-    index = index_at(time)
-    if index.denominator == 1
-      return index.to_i + 1
-    else
-      return index.ceil
-    end
+    time = @calendar.parse(time, offset: @origin.offset) if time.is_a?(String)
+    return index_at(time).floor + 1
   end
 
   # Returns previous integer index of the given time
+  #
+  # @example
+  #   ts = TimeStep.new("days since 2001-01-01 00:00:00")
+  #   ts.prev_index_of("2001-01-14 12:00:00")
+  #   #=> 13
+  #   ts.prev_index_of("2001-01-15 00:00:00")
+  #   #=> 13
+  #
+  # @param time [DateTime, String]
+  #
+  # @return [Numeric]
   def prev_index_of (time)
-    case time
-    when String
-      time = @calendar.parse(time)
-    end
-    index = index_at(time)
-    if index.denominator == 1
-      return index.to_i - 1
-    else
-      return index.floor
-    end
+    time = @calendar.parse(time, offset: @origin.offset) if time.is_a?(String)
+    return index_at(time).ceil - 1
   end
 
   # Returns next time of the given time
+  #
+  # @example
+  #   ts = TimeStep.new("days since 2001-01-01 00:00:00")
+  #   ts.next_time_of("2001-01-14 12:00:00")
+  #   #=> #<DateTime: 2001-01-15T00:00:00+00:00 ...>
+  #   ts.next_time_of("2001-01-15 00:00:00")
+  #   #=> #<DateTime: 2001-01-16T00:00:00+00:00 ...>
+  #
+  # @param time [DateTime, String]
+  #
+  # @return [DateTime]
   def next_time_of (time)
     return time_at(next_index_of(time))
   end
 
   # Returns previous time of the given time
+  #
+  # @example
+  #   ts = TimeStep.new("days since 2001-01-01 00:00:00")
+  #   ts.prev_time_of("2001-01-14 12:00:00")
+  #   #=> #<DateTime: 2001-01-14T00:00:00+00:00 ...>
+  #   ts.prev_time_of("2001-01-15 00:00:00")
+  #   #=> #<DateTime: 2001-01-14T00:00:00+00:00 ...>
+  #
+  # @param time [String, DateTime]
+  #
+  # @return [DateTime]
   def prev_time_of (time)
     return time_at(prev_index_of(time))  
   end
 
-  # Parses date-time string with appropreate calendar
+  # Creates new timestep pair object which refers `other` as other unit 
   #
-  # @option format [String]
-  def parse (time, format: nil)
-    return @calendar.parse(time, format: format)
+  # @example
+  #   days = TimeStep.new("days since 2001-01-01 00:00:00")
+  #   pair = days.in("hours")
+  #   pair.forward(1)
+  #   # => 24
+  #
+  # @param other [String, TimeStep]
+  #
+  # @return [TimeStep::Pair]
+  def in (unit)
+    other = TimeStep.new(unit, since: @origin, calendar: @calendar)
+   return Pair.new(self, other)
   end
-
-  def index_for_period (period)
-    if period.include_start?
-      idx1 = index_at(period.origin).ceil
-    else
-      idx1 = next_index_of(period.origin)
-    end
-    if period.include_last?
-      idx2 = index_at(period.last).floor
-    else
-      idx2 = prev_index_of(period.last)
-    end
-    return (idx1..idx2).to_a
+  
+  # Creates new timestep pair object which refers `other` from `self`
+  #
+  # @example
+  #   days = TimeStep.new("days since 2001-01-01 00:00:00")
+  #   hours = TimeStep.new("hours since 2001-01-01 00:00:00")
+  #   pair = days.to(hours)
+  #   pair.forward(1)
+  #   # => 24
+  #
+  # @param other [String, TimeStep]
+  #
+  # @return [TimeStep::Pair]
+  def to (other)
+    return Pair.new(self, other)
   end
 
-  def period (start, last, boundary: "[)")
-    case start
-    when Numeric
-      idx1 = start
-    else
-      idx1 = index_at(start)
-    end
-    case last
-    when Numeric
-      idx2 = last      
-    else
-      idx2 = index_at(last)
-    end
+  # Creates new timeperiod object corresponding given time or index for 
+  # start and last.
+  #
+  # @example
+  #   ts = TimeStep.new("days since 2001-01-01 00:00:00")
+  #   ts.period(0, 1)
+  #   #=> #<TimePeriod '1 days' [2001-01-01T00:00:00+00:00, 2001-01-02T00:00:00+00:00] >
+  #   ts.period("2001", "2002", ends: "[)")
+  #   #=> #<TimePeriod '365 days' [2001-01-01T00:00:00+00:00, 2002-01-01T00:00:00+00:00) >
+  #
+  # @param start [Numeric, DateTime]
+  # @param last [Numeric, DateTime]
+  # @param ends [String] one of "[]", "()", "[)", "(]"
+  #
+  # @return [TimePeriod]
+  def period (start, last, ends: "[]")
+    idx1 = if start.kind_of?(Numeric)
+             start
+           else
+             index_at(start)
+           end
+    idx2 = if last.kind_of?(Numeric)
+             last      
+           else
+             index_at(last)
+           end
     origin  = time_at(idx1)
     numeric = (idx2 - idx1) * @numeric
     interval_spec = format("%g %s", numeric, @symbol)
-    return TimePeriod.new(interval_spec, since: origin, calendar: @calendar.name, bc: @bc, boundary: boundary)    
+    return TimePeriod.new(interval_spec, since: origin, calendar: @calendar, ends: ends)    
   end
 
-
+  # Creates new timestep range object.
+  #
+  # @example
+  #   ts = TimeStep.new("days since 2001-01-01 00:00:00")
+  #   ts.range(0, 1)
+  #   ts.range("2001", "2002", ends: "[)")
+  #   ts.range("2001", 1)
+  #
+  # @param start [Numeric, DateTime]
+  # @param last  [Numeric, DateTime]
+  # @param count [Integer]
+  # @param ends [String] one of "[]", "()", "[)", "(]"
+  #
+  # @return [TimeStep::Range]
+  def range (start, last = nil, count: nil, ends: "[]")
+    return TimeStep::Range.new(self, start, last, count: count, ends: ends)
+  end
+    
 end