timesteps 0.9.5 → 0.9.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c66eb1faabea2c6a697af1b84d2b6e4b36419a7fe67f11a04d448476485697e
-  data.tar.gz: d32805b977369e85e0bacdce593275b6f5b30569be978cd74f61a355f9b4c67f
+  metadata.gz: 0feffe90d4bd2fdd8c478624bc78b67e3a7ab1c5905e236767c7734ba8c6b098
+  data.tar.gz: 4e924fa6b145f2b7cb06836d408b05e8bb34e8133797a3b7702ba29033af4400
 SHA512:
-  metadata.gz: f3aba6dae421df42fd53fa5aaaf7b273c9aec3a99d48bd95f9ffd3c0f9b2e6b5a694cc6b8e0c59f3d87355ddb803258dec77d1830280e41e504f85a11ed3b87a
-  data.tar.gz: 835e7de674cc0dea1b51571b119bfd55922e8fe4215124048bdc0d519dfcd1ec0bcec176f3a918b844e60e4fe68105c7878b165695f6ec82e1da8e87cdb61d6e
+  metadata.gz: 52773368aa3a11f6ac7e6e2e71b56e8ebb84f78b2c6807ac509f77a8342566cae41fb4b93a1c0c03f4fd1fbed07ae698144fb208f433b5a663a08cbf80ff83cb
+  data.tar.gz: 61d67459512fa64a4e7b8967b7300af0c9719b61c2bf4f66c478b5c08a064c38d889f0d2830bb7399d81ba02c516b194ccaab85406855a688204c06347cd6117

data/README.md

@@ -2,16 +2,16 @@ timesteps
 ================
 
 A library for handling discrete time series in constant increments.
-The main purpose of this library is to describe the time axis 
+The primary purpose of this library is to describe the time axis 
 when dealing with time series of observational data and climate data.
 
 Features
 --------
 
-* TimeStep consists of a pair of origin time and a time interval.
+* TimeStep holds an origin time and an unit time interval.
 * Parsing a time step expression like "hours since 2001-01-01 00:00:00" (originate from udunits library)
-* Obtaining time value for index value (0 for the origin time)
-* Obtaining index value for time value
+* Obtaining time value for the index value (0 for the origin time)
+* Obtaining index value for the time value
 * Treating non-standard calendar-type such as 'noleap', 'allleap', and '360_day'
 * Comparing the index values between different time step definitions
 
@@ -29,27 +29,26 @@ require "timesteps"
 Description
 -----------
 
-This library was created for time conversion and intercomparison of multiple time series data in the case of handling time series data of the type that specifies the time using indexes of time steps since origin time. 
+This library is for time conversion and time index comparison of multiple time series. This library treats the time series data of the type that specifies the time using indexes of time steps since origin time. 
 
 #### Time steps
 
-The main class of this library is the TimeStep class, which holds the origin time and the interval representing the unit time step. When the TimeStep class is initialized, the following notation is used.
+The main class of this library is the TimeStep class, which holds the origin time and the interval representing the unit time step. For the initialization of the TimeStep object, the following notation is used.
 
   * "second since 1970-01-01 00:00:00 +00:00" 
   * "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" 
 
-This is a notation used as a time unit in Unidata's [UDUNITS](https://www.unidata.ucar.edu/software/udunits/) library, and is also used as a unit of time axis in [CF conventions](http://cfconventions.org) of NetCDF (this notation is borrowed from the UDUnit library, but it should be noted that there are many differences).
+These notations are imported from Unidata's [UDUNITS](https://www.unidata.ucar.edu/software/udunits/) library. These are also used in [CF conventions](http://cfconventions.org) of NetCDF. However, note that there are some differences between our library and the udunits library about the date-time expressions.
 
-In this library, the elapsed time from the origin is expressed as an index value. For the case of "3 hours since 2001-01-01 00:00:00", the index values
-are expressed as, 
+In this library, the elapsed time from the origin is expressed as an index value. For the case of "3 hours since 2001-01-01 00:00:00", the index values are expressed as, 
 
   * "2001-01-01 00:00:00" => 0  (0 / 3 hours) (    0 days)
   * "2001-01-01 03:00:00" => 1  (1 / 3 hours) ((1/8) days)
   * "2001-01-02 00:00:00" => 8  (8 / 3 hours) (    1 days)
 
-This is expressed as a Ruby script.
+These are expressed as a Ruby script.
 
 ```ruby
 ts = TimeStep.new("3 hours since 2001-01-01 00:00:00")
@@ -67,10 +66,7 @@ ts.days_at(8)  ### => 1      [Integer]
 #### Treatment of year and month units
 
 The time units like day, hour, minute, second have constant intervals,
-but the time units like years and months are not. So, the year and 
-month units are given special treatment in this library. 
-One year is counted at the same month and day as the origin time, and
-one month is counted at the same day as the origin time.
+but the time units like years and months are not. So, the year and month units are given special treatment in this library. One year is counted at the same month and day as the origin time, and one month is counted on the same day as the origin time.
 
 ```ruby
 ts = TimeStep.new("year since 2000-01-15 00:00:00")
@@ -106,7 +102,7 @@ The following calendars, including non-standard calendars, can be handled.
   * allleap, 366_day         
   * 360_day                  
 
-You can find the description for these calendar at the document of CF-Convensions ([4.4.1 Calendar](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#calendar)).
+You can find the description for these calendars at the document of CF-Conventions ([4.4.1 Calendar](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#calendar)).
 
 ```ruby
 ts = TimeStep.new("day since 2000-01-01", calendar: "standard")
@@ -119,13 +115,11 @@ ts = TimeStep.new("day since 2000-01-01", calendar: "360_day")
 ts.time_at(59)  ### => #<DateTime::Fixed360Day: 2000-02-30T00:00:00+00:00 ...>
 ```
 
-In this library, DateTime class is adopted as the object that represents date and time (not Time class). Non-standard calendars ("proleptic_gregorian", "Julian") can be handled by the DateTime class, with appropriate use of the start parameter. But, other non-standard calendars ("noleap", "allleap", "360_day") can not. So, DateTimeLike class and its subclasses DateTime::NoLeap, DateTime::AllLeap, DateTime::Fixed360Day are introduced. Since many (not all) of methods in DateTime class are also implemented in DateTimeLike class, users don't need to be too aware of these class differences.
+In this library, the DateTime class is adopted as the object that represents date and time (not Time class). Non-standard calendars ("proleptic_gregorian", "julian") can be handled by the DateTime class, with appropriate use of the start parameter. But, other non-standard calendars ("noleap", "allleap", "360_day") can not. So, DateTimeLike class and its subclasses DateTime::NoLeap, DateTime::AllLeap, DateTime::Fixed360Day are introduced. Since many (not all) of methods in the DateTime class are also implemented in DateTimeLike class, users don't need to be too aware of these class differences.
 
 #### Parsing datetime string
 
-In `standard` calendar, use DateTime.parse as usual.
-In other calendar, you can use DateTime.parse_timestamp, which is 
-special method to parse date time string with specification of calendar.
+In `standard` calendar, use DateTime.parse as usual. In other calendars, you can use DateTime.parse_timestamp, which is a particular method to parse a date-time string with a specification of the calendar.
 
 ```ruby
 DateTime.parse_timestamp("1200-01-01") ### "standard"
@@ -143,7 +137,7 @@ ts = TimeStep.new("days since 2001-01-01", calendar: "allleap")
 ts.parse("2001-02-29") ### => #<DateTime::AllLeap 2001-02-29T ...>
 ```
 
-In the UDUNITS library, negative years are treated as BCs and A.D. 0 is treated as non-existent. This is different from how it is handled in Ruby's DateTime class. To parse date time string of UDUNITS type, `bc` option for `Date.parse_timestamp` method.
+In the UDUNITS library, negative years are treated as BCs, and A.D. 0 is treated as non-existent. This is different from how it is handled in Ruby's DateTime class. To parse date-time string of UDUNITS type, `bc` option for `Date.parse_timestamp` method.
 
 ```ruby
 DateTime.parse_timestamp("-0001-01-01") 
@@ -159,12 +153,9 @@ DateTime.parse_timestamp("BC 0001-01-01")
    # B.C. 1
 ```
 
-#### Comparing two time series
+#### Comparing multiple time series
 
-TimeStep::Pair is a class to compare indices of two time series,
-which is initialized by two time step object. It is possible to 
-compute the other index corresponding to the time represented 
-by one of the indices using TimeStep::Pair.
+TimeStep::Pair is a class to compare indices of two time series, which is initialized by two time step object. It is possible to compute the other index corresponding to the time represented by one of the indices using TimeStep::Pair.
 
 
 ```ruby

data/lib/timesteps.rb

@@ -1,13 +1,14 @@
 
 require "date"
 require "timesteps/datetimelike"
+require "timesteps/datetimelike_format"
 require "timesteps/datetime_noleap"
 require "timesteps/datetime_allleap"
 require "timesteps/datetime_360day"
-require "timesteps/parse_timestamp"
-require "timesteps/format"
+require "timesteps/datetime_parse_timestamp"
 require "timesteps/timestep_datetime_ext"
-require "timesteps/calendar"
+require "timesteps/timestep_calendar"
 require "timesteps/timestep"
 require "timesteps/timestep_pair"
 require "timesteps/timestep_converter"
+require "timesteps/timeperiod"

data/lib/timesteps/{parse_timestamp.rb → datetime_parse_timestamp.rb}

@@ -16,7 +16,6 @@ class DateTime
   # @return [DateTimeFixedDPY]
 
   def self.parse_timestamp (spec, calendar: "standard", bc: false, format: nil)
-    raise "invalid option 'calendar'" if self != DateTime
     case calendar.downcase.intern
     when :standard, :gregorian
       klass = DateTime
@@ -39,9 +38,13 @@ class DateTime
     end
     if format
       hash = DateTime._strptime(spec, format)
-      raise "timestring doesn't match with format" unless hash
+      raise "date-time string '#{spec}' doesn't match with the given format '#{format}'" unless hash
     else
-      hash = DateTime._parse(spec)
+      if spec =~ /\A([+\-]?\d{4})(\-(\d{1,2}))?\z/
+        hash = { year: $1.to_i, mon: $3 ? $3.to_i : 1, mday: 1 }
+      else
+        hash = DateTime._parse(spec)
+      end
     end
     year, month, day, hour, minute, second, sec_fraction, offset = 
            hash.values_at(:year, :mon, :mday, :hour, :min, :sec, :sec_fraction, :offset)

data/lib/timesteps/datetimelike.rb

@@ -75,16 +75,16 @@ class DateTimeLike
     
   def check_valid_datetime
     unless valid_date?
-      raise "invalid date"
+      raise "invalid date for #{self.class} [year: #{@year}, month: #{@month}, day: #{@day}]"
     end
     unless valid_time?
-      raise "invalid time"
-    end    
+      raise "invalid time for #{self.class} [hour: #{@hour}, minute: #{@minute}, second: #{@second}]"
+    end
   end
 
   def valid_time?
     begin
-      DateTime.new(2001,1,1,@hour,@minute,@second)
+      DateTime.new(2001, 1, 1, @hour, @minute, @second)
       true
     rescue
       false
@@ -199,7 +199,7 @@ class DateTimeLike
   end
 
   # Returns the difference between the two dates 
-  # if the other is a date object. 
+  # if the other is a datetime object. 
   # If the other is a numeric value, 
   # returns a date object pointing other days before self. 
   def - (other_or_days)
@@ -209,7 +209,7 @@ class DateTimeLike
     when self.class
       return self.jd - other_or_days.jd
     else
-      raise "invalid object for other"
+      raise "other shoud be date-time object or numeric value"
     end
   end
 

data/lib/timesteps/timeperiod.rb

@@ -0,0 +1,202 @@
+
+class TimePeriod < TimeStep
+  
+  def initialize (spec, since: nil, format: nil, calendar: "standard", bc: false, boundary: "[)" )
+    super(spec, since: since, format: format, count: 1, calendar: calendar, bc: bc)
+    raise "invalid boundary specification" unless boundary =~ /\A[\[\(][\]\)]\z/
+    @boundary      = boundary
+    @include_start = ( boundary[0] == "[" ) ? true : false
+    @include_last  = ( boundary[1] == "]" ) ? true : false 
+    @last = time_at(1)
+  end
+  
+  attr_reader :last
+
+  def start
+    return @origin
+  end
+  
+  def include_start?
+    return @include_start
+  end
+
+  def include_last?
+    return @include_last
+  end
+
+  # Returns the value as a string for inspection.
+  #
+  def inspect
+    left_paren = @include_start ? "[" : "("
+    right_paren = @include_last ? "]" : ")"
+    "#<TimePeriod '#{interval_spec}' #{left_paren}#{start.to_s}, #{last.to_s}#{right_paren} calendar='#{calendar.name}'>"
+  end
+
+  def boundary
+    left_paren = @include_start ? "[" : "("
+    right_paren = @include_last ? "]" : ")"
+    return left_paren + right_paren
+  end
+
+  def include? (other)
+    case other
+    when TimePeriod
+      if ( other.origin < @origin ) ||
+         ( other.origin == @origin && ( not include_start? ) && other.include_start? )
+        left = false
+      else
+        left = true
+      end
+      if ( @last < other.last ) ||
+         ( @last == other.last && ( not include_last? ) && other.include_last? )
+        right = false
+      else
+        right = true        
+      end        
+      return left & right
+    else
+      if include_start?
+        left = @origin <= other
+      else
+        left = @origin < other
+      end
+      if include_last?
+        right = other <= @last
+      else
+        right = other < @last
+      end
+      return left & right
+    end
+  end
+  
+  def overlap? (other)
+    case other
+    when TimePeriod
+      if ( @origin < other.last ) ||
+         ( @origin == other.last && include_start? && other.include_last?  )
+         left = true
+       else
+         left = false
+      end
+      if ( other.origin < @last ) ||
+         ( other.origin == @last && include_last? && other.include_start?  )
+         right = true
+       else
+         right = false
+      end
+      return left && right
+    else
+      return include?(other)
+    end    
+  end
+
+  def contact? (other)
+    case other
+    when TimePeriod
+      if @origin <= other.last
+         left = true
+       else
+         left = false
+      end
+      if other.origin <= @last 
+         right = true
+       else
+         right = false
+      end
+      return left && right
+    else
+      left  = @origin <= other
+      right = other <= @last
+      return left & right
+    end    
+  end
+  
+  def merge (other)
+    raise "can't merge period without contacted period" unless contact?(other)
+    if ( other.origin < @origin ) ||
+       ( other.origin == @origin && ( not include_start? ) && other.include_start? )
+      left = other.origin
+      left_boundary = other.include_start? ? "[" : "("
+    else
+      left = @origin
+      left_boundary = include_start? ? "[" : "("      
+    end
+    if ( @last < other.last ) ||
+       ( @last == other.last && ( not include_last? ) && other.include_last? )
+      right = other.last
+      right_boundary = other.include_last? ? "]" : ")"
+    else
+      right = @last
+      right_boundary = include_last? ? ")" : "]"      
+    end
+    ridx = index_at(right)
+    lidx = index_at(left)
+    numeric = (ridx - lidx) * @numeric
+    origin = left
+    interval_spec = format("%g %s", numeric, @symbol)
+    boundary = left_boundary + right_boundary
+    return TimePeriod.new(interval_spec, since: origin, calendar: @calendar.name, bc: @bc, boundary: boundary)
+  end
+
+  def clip (other)
+    raise "can't clip period without contacted period" unless contact?(other)
+    if ( @origin < other.origin ) ||
+       ( @origin == other.origin && include_start? && ( not other.include_start? ) )
+      left = other.origin
+      left_boundary = other.include_start? ? "[" : "("
+    else
+      left = @origin
+      left_boundary = include_start? ? "[" : "("      
+    end
+    if ( other.last < @last ) ||
+       ( other.last == @last && include_last? && ( not other.include_last? ) )
+      right = other.last
+      right_boundary = other.include_last? ? "]" : ")"
+    else
+      right = @last
+      right_boundary = include_last? ? ")" : "]"      
+    end
+    ridx = index_at(right)
+    lidx = index_at(left)
+    numeric = (ridx - lidx) * @numeric
+    origin = left
+    interval_spec = format("%g %s", numeric, @symbol)
+    bndry = left_boundary + right_boundary
+    return TimePeriod.new(interval_spec, since: origin, calendar: @calendar.name, bc: @bc, boundary: bndry)
+  end
+  
+  def split (time, boundary: ")[")
+    raise "can't split period without contacted time" unless contact?(time)
+    # left
+    numeric = index_at(time) * @numeric
+    interval_spec = format("%g %s", numeric, @symbol)
+    bndry   = (@include_start ? "[" : "(") + boundary[0]
+    left_period  = TimePeriod.new(interval_spec, since: @origin, calendar: @calendar.name, bc: @bc, boundary: bndry)
+    # right
+    numeric = (1 - index_at(time)) * @numeric
+    interval_spec = format("%g %s", numeric, @symbol)
+    bndry   = boundary[1] + (@include_last ? "]" : ")")
+    right_period  = TimePeriod.new(interval_spec, since: @origin, calendar: @calendar.name, bc: @bc, boundary: bndry)
+    return left_period, right_period
+  end
+  
+  def next
+    return TimePeriod.new(interval_spec, since: @last, calendar: @calendar.name, bc: @bc, boundary: boundary)    
+  end
+
+  def prev
+    origin = index_at(-1)
+    return TimePeriod.new(interval_spec, since: origin, calendar: @calendar.name, bc: @bc, boundary: boundary)    
+  end
+
+  def shift (index)
+    return TimePeriod.new(interval_spec, since: time_at(index), calendar: @calendar.name, bc: @bc, boundary: boundary)    
+  end
+
+  def shift_with_duration (duration)
+    time = @origin + duration
+    return TimePeriod.new(interval_spec, since: time, calendar: @calendar.name, bc: @calendar.bc?, boundary: boundary)
+  end
+  
+end
+

data/lib/timesteps/timestep.rb

@@ -21,22 +21,22 @@ class TimeStep
   #   * minutes, minute, mins, min
   #   * seconds, second, secs, sec, s
   #   * milliseconds, millisecond, msecs, msec, ms
-  #   * microseconds, microsecond, 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 `calendar` specifies the calendar for datetime calculation,
-  #   * standard, gregorian      -> DateTime with Date::ITALY as start
-  #   * proleptic_gregorian      -> DateTime with Date::GREGORIAN as start
-  #   * proleptic_julian, julian -> DateTime with Date::JULIAN as start
-  #   * 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.
   # The option count specifies the number of time steps, which is hint for 
   # some methods (#each etc).
+  # 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
+  #   * "proleptic_julian", "julian" -> DateTime with Date::JULIAN as start
+  #   * "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]
@@ -46,32 +46,38 @@ class TimeStep
   # @option count [Integer] number of time steps (as hint for some methods)
   # 
   def initialize (spec, since: nil, format: nil, count: nil, calendar: "standard", bc: false)
-    case calendar
-    when String
-      @calendar = Calendar.new(calendar, bc: bc)
-    else
-      @calendar = calendar
-    end
+    @calendar = Calendar.new(calendar, bc: bc)
     if since
       parse_interval(spec)
       case since
       when String
         @origin = @calendar.parse(since, format: format)
       else
-        raise "mismatch time object with calendar" unless @calendar.valid_datetime_type?(since)
+        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
       end
     else
-      intervalspec, originspec = spec.split(/\s+since\s+/)
-      parse_interval(intervalspec)
-      @origin = @calendar.parse(originspec)
+      spec1, spec2 = spec.split(/\s+since\s+/)
+      parse_interval(spec1)
+      @origin = @calendar.parse(spec2)
     end
-    @intervalspec = format("%g %s", @numeric, @symbol)
-    @originspec   = @origin.strftime("%Y-%m-%d %H:%M:%S.%N %:z")
-    @definition   = format("%s since %s", @intervalspec, @originspec)
     @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)
+  end
+
   # @private
   PATTERN_NUMERIC = '[\+\-]?\d*(?:\.\d+)?(?:[eE][\+\-]?\d+)?'
   # @private
@@ -86,7 +92,7 @@ class TimeStep
       end
       symbol = $2
     else
-      raise "invalid interval specification"
+      raise "the interval specification '#{spec}' is invalid."
     end
     @interval = @numeric
     case symbol
@@ -128,10 +134,7 @@ class TimeStep
   
   private :parse_interval
 
-  attr_reader :definition, 
-              :intervalspec, 
-              :originspec, 
-              :numeric, 
+  attr_reader :numeric, 
               :symbol, 
               :interval, 
               :origin, 
@@ -155,13 +158,15 @@ class TimeStep
   # @return [DateTime, nil]
   def limit= (time)
     if time
-      @count = (prev_index_of(time) + 1).to_i
+      @count = next_index_of(time).to_i
     else
       @count = nil
     end
     return limit
   end
   
+  # Sets count by giving maximum time.
+  # 
   def set_limit (time, format: nil)
     case time
     when String
@@ -193,9 +198,9 @@ class TimeStep
 
   def debug_info
     return {
-      "definition"   => @definition.clone,
-      "intervalspec" => @intervalspec.clone,
-      "originspec"   => @originspec.clone,
+      "definition"   => definition,
+      "interval_spec" => interval_spec,
+      "origin_spec"   => origin_spec,
       "calendar"     => @calendar.name,
       "numeric"      => @numeric,
       "symbol"       => @symbol.to_s,
@@ -219,7 +224,7 @@ class TimeStep
   #
   # @return [Boolean]
   def == (other)
-    return @definition == other.definition && @calendar == other.calendar 
+    return definition == other.definition && @calendar == other.calendar 
   end
 
   def user_to_days (index)
@@ -240,17 +245,16 @@ class TimeStep
   def time_at (*indices)
     if indices.size == 1
       index = indices.first
-      raise ArgumentError, "index should be numeric" unless index.is_a?(Numeric)
-      index = index.to_r
+      raise ArgumentError, "index argument should be a numeric" unless index.is_a?(Numeric)
       case @symbol
       when :years
         unless index.denominator == 1
-          raise "index for years should be an integer"
+          raise ArgumentError, "index argument should be an integer for years"
         end
         return @origin.next_year(index*@numeric)
       when :months
         unless index.denominator == 1
-          raise "index for years should be an integer"
+          raise ArgumentError, "index argument should be an integer for months"
         end
         return @origin.next_month(index*@numeric)
       else
@@ -264,22 +268,22 @@ class TimeStep
     end
   end
     
-  # Calculate the time difference in days from origin at the index.
+  # Calculate the duration in days since origin time at the given index.
   #
   # @param indices [Array]
   # @return [DateTime, Array<DateTime>]
-  def days_at (*indices)
+  def duration_at (*indices)
     if indices.size == 1
       index = indices.first
       case @symbol
       when :years
         unless index.denominator == 1
-          raise "index for years should be an integer"
+          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 "index for years should be an integer"
+          raise ArgumentError, "index argument should be an integer for months"
         end
         days = @origin.next_month(@numeric*index) - @origin
       else
@@ -288,7 +292,7 @@ class TimeStep
       days = days.to_i if days.denominator == 1
       return days
     else
-      return indices.map{ |index| days_at(index) }            
+      return indices.map{ |index| duration_at(index) }            
     end
   end
   
@@ -319,55 +323,7 @@ class TimeStep
       return times.map{|time| index_at(time, format: format) }      
     end
   end
-  
-  def range (ge: nil, gt: nil, lt: nil, le: nil)
-    raise "lower limit is not given" if ge.nil? and gt.nil?
-    raise "upper limit is not given" if lt.nil? and le.nil?
-    raise "lower limits are duplicated" if ge and gt
-    raise "upper limits are duplicated" if lt and le
-    if ge
-      case ge
-      when Numeric
-        min = ge.floor
-      else
-        min = prev_index_of(ge)
-      end
-    end
-    if gt
-      case gt
-      when Numeric
-        if lt.to_r.denominator == 1
-          min = gt.to_i + 1
-        else
-          min = gt.ceil
-        end
-      else
-        min = next_index_of(gt)
-      end
-    end
-    if lt
-      case lt
-      when Numeric
-        if lt.to_r.denominator == 1
-          max = lt.to_i - 1
-        else
-          max = lt.floor
-        end
-      else
-        max = prev_index_of(lt)
-      end
-    end
-    if le
-      case le
-      when Numeric
-        max = le.ceil
-      else
-        max = next_index_of(le)
-      end
-    end
-    return (min..max).to_a
-  end
-
+    
   # Returns TimeStep object which has origin time determined 
   # by the given `index`.
   #
@@ -376,12 +332,12 @@ class TimeStep
   # @return [TimeStep]
   def shift_origin (index)
     time = time_at(index)
-    return TimeStep.new(@intervalspec, since: time, calendar: @calendar)
+    return TimeStep.new(interval_spec, since: time, calendar: @calendar.name, bc: @calendar.bc?)
   end
 
-  def shift_origin_with_days (days)
-    time = @origin + days
-    return TimeStep.new(@intervalspec, since: time, calendar: @calendar)
+  def shift_origin_with_duration (duration)
+    time = @origin + duration
+    return TimeStep.new(interval_spec, since: time, calendar: @calendar.name, bc: @calendar.bc?)
   end
 
   # Returns TimeStep object which has origin time specified 
@@ -395,14 +351,14 @@ class TimeStep
     when String
       time = @calendar.parse(time)
     end
-    return TimeStep.new(@intervalspec + " since " + time.strftime("%Y-%m-%d %H:%M:%S.%N %:z"), calendar: @calendar)
+    return TimeStep.new(interval_spec, since: time, calendar: @calendar.name, bc: @calendar.bc?)
   end
 
   include Enumerable
   
   def each (limit = nil, incr = 1, &block)
     if limit.nil? 
-      raise "step method require count" unless @count
+      raise "count (or limit) is required by #step" unless @count
       limit = @count - 1
     end
     if block
@@ -419,7 +375,7 @@ class TimeStep
   end
   
   def times (&block)
-    raise "step method require count" unless @count
+    raise "count (or limit) is required by #step" unless @count
     (0...@count).each(&block)
   end
   
@@ -427,15 +383,16 @@ class TimeStep
   #
   #
   def in (unit)
-    return TimeStep::Pair.new(self, format("%s since %s", unit, @originspec), calendar: @calendar)
+    return TimeStep::Pair.new(self, format("%s since %s", unit, origin_spec), calendar: @calendar.name, bc: @calendar.bc?)
   end
   
+  # Returns next integer index of the given time
   def next_index_of (time)
     case time
     when String
       time = @calendar.parse(time)
     end
-    index = index_at(time).to_r
+    index = index_at(time)
     if index.denominator == 1
       return index.to_i + 1
     else
@@ -443,21 +400,70 @@ class TimeStep
     end
   end
 
+  # Returns previous integer index of the given time
   def prev_index_of (time)
-    return next_index_of(time) - 1
+    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
   end
 
+  # Returns next time of the given time
   def next_time_of (time)
     return time_at(next_index_of(time))
   end
 
+  # Returns previous time of the given time
   def prev_time_of (time)
     return time_at(prev_index_of(time))  
   end
 
+  # Parses date-time string with appropreate calendar
+  #
+  # @option format [String]
   def parse (time, format: nil)
     return @calendar.parse(time, format: format)
   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
+  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
+    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)    
+  end
+
+
 end
 

data/lib/timesteps/{calendar.rb → timestep_calendar.rb}

@@ -21,7 +21,12 @@ class TimeStep
       SYM_360_day => DateTime::Fixed360Day,
     }
 
+    # Construct the object
+    #
     def initialize (calendar = "standard", bc: false)
+      unless calendar.is_a?(String)
+        raise ArgumentError, "argument calendar '#{calendar}' should be string" 
+      end
       @name = calendar
       @bc   = bc
       case @name.downcase.intern

data/lib/timesteps/timestep_converter.rb

@@ -11,7 +11,7 @@ class TimeStep::Converter
     when TimeStep
       @reference = reference
     else
-      raise "first argument should be TimeStep or string"
+      raise ArgumentError, "reference argument '#{reference}' should be time-step or string"
     end
     @pair = {}
     @target = {}

data/lib/timesteps/timestep_pair.rb

@@ -26,7 +26,7 @@ class TimeStep::Pair
     when TimeStep
       @from = from
     else
-      raise "first argument should be TimeStep or string"
+      raise ArgumentError, "from argument '#{from}' should be a time-step or a string"
     end
             
     case to
@@ -35,7 +35,7 @@ class TimeStep::Pair
     when TimeStep
       @to = to
     else
-      raise "second argument should be TimeStep or string"
+      raise ArgumentError, "to argument '#{to}' should be a time-step or a string"
     end
 
     @from_origin = @from.origin

data/lib/timesteps/timestep_query.rb

@@ -0,0 +1,49 @@
+require "timesteps"
+
+class TimeStep::Query
+  
+  def initialize (timestep, format: nil)
+    @timestep = timestep
+    @format   = foramt
+  end
+
+  def __format__ (time)
+    return ( @template.nil? ) ? time : time.strftime(@template)
+  end
+  
+  private :__format__
+
+  def just_time? (time)
+    return @timestep.index_at(time).denominator == 1
+  end
+
+  def just_before_time_of (time)
+    idx = @timestep.index_at(time)
+    if idx.denomiator == 1
+      time0 = time
+    else
+      time0 = @timestep.time_at(idx.floor)
+    end
+    return __format__(time0)
+  end
+
+  def just_after_time_of (time)
+    idx = @timestep.index_at(time)
+    if idx.denomiator == 1
+      time0 = time
+    else
+      time0 = @timestep.time_at(idx.ceil)
+    end
+    return __format__(time0)
+  end
+
+  def prev_time_of (time)
+    return __format__(@timestep.prev_time_of(time))
+  end
+
+  def next_time_of (time)
+    return __format__(@timestep.next_time_of(time))
+  end
+  
+end
+

data/spec/timestep_spec.rb

@@ -231,7 +231,7 @@ describe "TimeStep#time_at" do
       is_asserted_by { ts.time_at(-366) == ts.origin.prev_month(366) }
 
       # months timestep don't permit fractional index
-      expect { ts.time_at(1.5) }.to raise_error(RuntimeError)
+      expect { ts.time_at(1.5) }.to raise_error(ArgumentError)
 
     end
     
@@ -250,7 +250,7 @@ describe "TimeStep#time_at" do
       is_asserted_by { ts.time_at(-366) == ts.origin.prev_year(366) }
 
       # years timestep don't permit fractional index
-      expect { ts.time_at(1.5) }.to raise_error(RuntimeError)
+      expect { ts.time_at(1.5) }.to raise_error(ArgumentError)
 
     end
     
@@ -339,7 +339,7 @@ describe "TimeStep#index_at" do
 
 end
 
-describe "TimeStep#days_at" do
+describe "TimeStep#duration_at" do
 
   example 'seconds' do 
 
@@ -347,25 +347,25 @@ describe "TimeStep#days_at" do
 
       ts = TimeStep.new("1 seconds since 2001-02-03 04:05:06 +07:00", calendar: calendar)
 
-      is_asserted_by { ts.days_at( 1 ) == 1.quo(86400) }
-      is_asserted_by { ts.days_at( 100 ) == 100.quo(86400) }
-      is_asserted_by { ts.days_at( 0.5 ) ==  0.5.to_r.quo(86400) }
-      is_asserted_by { ts.days_at( -0.5 ) == -0.5.to_r.quo(86400) }
+      is_asserted_by { ts.duration_at( 1 ) == 1.quo(86400) }
+      is_asserted_by { ts.duration_at( 100 ) == 100.quo(86400) }
+      is_asserted_by { ts.duration_at( 0.5 ) ==  0.5.to_r.quo(86400) }
+      is_asserted_by { ts.duration_at( -0.5 ) == -0.5.to_r.quo(86400) }
 
     end
     
   end
 
-  example 'days' do 
+  example 'duration' do 
 
     CALENDAR_NAMES.each do |calendar|
 
       ts = TimeStep.new("1 days since 2001-02-03 04:05:06 +07:00", calendar: calendar)
 
-      is_asserted_by { ts.days_at( 1 ) == 1 }
-      is_asserted_by { ts.days_at( 100 ) == 100 }
-      is_asserted_by { ts.days_at( 0.5 ) == 0.5 }
-      is_asserted_by { ts.days_at( -0.5 ) == -0.5 }
+      is_asserted_by { ts.duration_at( 1 ) == 1 }
+      is_asserted_by { ts.duration_at( 100 ) == 100 }
+      is_asserted_by { ts.duration_at( 0.5 ) == 0.5 }
+      is_asserted_by { ts.duration_at( -0.5 ) == -0.5 }
 
     end
     
@@ -377,10 +377,10 @@ describe "TimeStep#days_at" do
 
       ts = TimeStep.new("1 months since 2001-02-03 04:05:06 +07:00", calendar: calendar)
 
-      is_asserted_by { ts.days_at( 1 ) == ts.origin.next_month - ts.origin }
-      is_asserted_by { ts.days_at( 100 ) == ts.origin.next_month(100) - ts.origin }
-      is_asserted_by { ts.days_at( -1 ) == ts.origin.prev_month - ts.origin }
-      is_asserted_by { ts.days_at( -100 ) == ts.origin.prev_month(100) - ts.origin }
+      is_asserted_by { ts.duration_at( 1 ) == ts.origin.next_month - ts.origin }
+      is_asserted_by { ts.duration_at( 100 ) == ts.origin.next_month(100) - ts.origin }
+      is_asserted_by { ts.duration_at( -1 ) == ts.origin.prev_month - ts.origin }
+      is_asserted_by { ts.duration_at( -100 ) == ts.origin.prev_month(100) - ts.origin }
 
     end
     
@@ -392,10 +392,10 @@ describe "TimeStep#days_at" do
 
       ts = TimeStep.new("1 years since 2001-02-03 04:05:06 +07:00", calendar: calendar)
 
-      is_asserted_by { ts.days_at( 1 ) == ts.origin.next_year - ts.origin }
-      is_asserted_by { ts.days_at( 100 ) == ts.origin.next_year(100) - ts.origin }
-      is_asserted_by { ts.days_at( -1 ) == ts.origin.prev_year - ts.origin }
-      is_asserted_by { ts.days_at( -100 ) == ts.origin.prev_year(100) - ts.origin }
+      is_asserted_by { ts.duration_at( 1 ) == ts.origin.next_year - ts.origin }
+      is_asserted_by { ts.duration_at( 100 ) == ts.origin.next_year(100) - ts.origin }
+      is_asserted_by { ts.duration_at( -1 ) == ts.origin.prev_year - ts.origin }
+      is_asserted_by { ts.duration_at( -100 ) == ts.origin.prev_year(100) - ts.origin }
 
     end
     

data/spec/timesteppair_spec.rb

@@ -63,7 +63,7 @@ describe "TimeStep::Pair#forward" do
     is_asserted_by { pair.forward(1) == 4 }
     is_asserted_by { pair.forward(10) == 31 }
 
-    expect { pair.forward(1.5) }.to raise_error(RuntimeError)
+    expect { pair.forward(1.5) }.to raise_error(ArgumentError)
   end
 
   example "different years" do 
@@ -77,7 +77,7 @@ describe "TimeStep::Pair#forward" do
     is_asserted_by { pair.forward(1) == 4 }
     is_asserted_by { pair.forward(10) == 31 }
 
-    expect { pair.forward(1.5) }.to raise_error(RuntimeError)
+    expect { pair.forward(1.5) }.to raise_error(ArgumentError)
 
   end
 

data/timesteps.gemspec

@@ -1,6 +1,6 @@
 
 Gem::Specification::new do |s|
-  version = "0.9.5"
+  version = "0.9.6"
 
   files = Dir.glob("**/*") - [ 
                                Dir.glob("timesteps-*.gem"), 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: timesteps
 version: !ruby/object:Gem::Version
-  version: 0.9.5
+  version: 0.9.6
 platform: ruby
 authors:
 - Hiroki Motoyoshi
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-05-08 00:00:00.000000000 Z
+date: 2020-05-13 00:00:00.000000000 Z
 dependencies: []
 description: "  A library for time conversion and intercomparison of multiple time
   series data \n  in the case of handling time series data of the type that specifies
@@ -27,18 +27,20 @@ files:
 - README.md
 - Rakefile
 - lib/timesteps.rb
-- lib/timesteps/calendar.rb
 - lib/timesteps/datetime_360day.rb
 - lib/timesteps/datetime_allleap.rb
 - lib/timesteps/datetime_noleap.rb
+- lib/timesteps/datetime_parse_timestamp.rb
 - lib/timesteps/datetimelike.rb
-- lib/timesteps/format.rb
+- lib/timesteps/datetimelike_format.rb
 - lib/timesteps/grads.rb
-- lib/timesteps/parse_timestamp.rb
+- lib/timesteps/timeperiod.rb
 - lib/timesteps/timestep.rb
+- lib/timesteps/timestep_calendar.rb
 - lib/timesteps/timestep_converter.rb
 - lib/timesteps/timestep_datetime_ext.rb
 - lib/timesteps/timestep_pair.rb
+- lib/timesteps/timestep_query.rb
 - spec/allleap_spec.rb
 - spec/fixed360day_spec.rb
 - spec/noleap_spec.rb