timesteps 0.9.5 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c66eb1faabea2c6a697af1b84d2b6e4b36419a7fe67f11a04d448476485697e
-  data.tar.gz: d32805b977369e85e0bacdce593275b6f5b30569be978cd74f61a355f9b4c67f
+  metadata.gz: 8ec2401e1d32acce3ddb048864c34b37de56ad5f83066fa617baeea8c65abc3a
+  data.tar.gz: '083c51a6c6fd1f295e7d2359960f5fe893ccc0847bcf014b7928f629c21e1a8e'
 SHA512:
-  metadata.gz: f3aba6dae421df42fd53fa5aaaf7b273c9aec3a99d48bd95f9ffd3c0f9b2e6b5a694cc6b8e0c59f3d87355ddb803258dec77d1830280e41e504f85a11ed3b87a
-  data.tar.gz: 835e7de674cc0dea1b51571b119bfd55922e8fe4215124048bdc0d519dfcd1ec0bcec176f3a918b844e60e4fe68105c7878b165695f6ec82e1da8e87cdb61d6e
+  metadata.gz: e242891a7aed17ea1a3c0c138e80382b55422b5d6c9cbeec0c32e0b5725d5979a1e7631b110eb136ca4942c16023b93b325390f28be30792aa15f637a736c09b
+  data.tar.gz: 4da60d62efce29eeb13b1fe93d2621cdc616c6d8fe4d421922257bbb5e28c5695504d6804806430feb1dd42adbba7870de37b41758cf3df121dae59b57c1d3bf

data/.yardopts

@@ -0,0 +1 @@
+--no-private

data/NEWS.md

@@ -0,0 +1,8 @@
+NEWS
+====
+
+0.9.8 -> 0.9.9
+--------------
+
+* [Mod] TimeStep::Range.new was modified to accept `start` and `last` argument of mixed type (Integer, DateTime, DateTimeLike, String).
+

data/Note.ja.md

@@ -1,4 +1,13 @@
 # メモ
+
+masterブランチ    -> gem リリース最新版
+developブランチ   -> 開発統合版
+topicブランチ     -> Feature開発版
+
+
+
+"XX since YYY" と since: time を同時に指定下場合は、前者が採用される (sinceオプションは無視される)。
+
 ### 時間の単位 (udunits)
     * years, year
     * months,month

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 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 a 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")
@@ -59,18 +58,15 @@ ts.index_at("2001-01-02 00:00:00")  ### => 8
 ts.time_at(0)  ### => #<DateTime 2001-01-01T00:00:00 ...>
 ts.time_at(1)  ### => #<DateTime 2001-01-01T03:00:00 ...>
 ts.time_at(8)  ### => #<DateTime 2001-01-02T00:00:00 ...>
-ts.days_at(0)  ### => 0      [Integer]
-ts.days_at(1)  ### => (1/8)  [Rational]
-ts.days_at(8)  ### => 1      [Integer] 
+ts.duration_at(0)  ### => 0      [Integer]
+ts.duration_at(1)  ### => (1/8)  [Rational]
+ts.duration_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,14 +137,14 @@ 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. 
 
 ```ruby
 DateTime.parse_timestamp("-0001-01-01") 
    # => #<DateTime: -0001-01-01T00:00:00+00:00 ...>
    # B.C. 2
 
-DateTime.parse_timestamp("-0001-01-01", bc: true) 
+DateTime.parse_timestamp("0000-01-01") 
    # => #<DateTime: 0000-01-01T00:00:00+00:00 ...>
    # B.C. 1
 
@@ -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/{parse_timestamp.rb → datetime_parse_timestamp.rb}

@@ -11,12 +11,10 @@ class DateTime
   # `DateTime._parse()` is called internally.
   #
   # @param spec [String]
-  # @option bc [Boolean]
   #
   # @return [DateTimeFixedDPY]
 
-  def self.parse_timestamp (spec, calendar: "standard", bc: false, format: nil)
-    raise "invalid option 'calendar'" if self != DateTime
+  def self.parse_timestamp (spec, format: nil, offset: nil, calendar: "standard", tz: nil)
     case calendar.downcase.intern
     when :standard, :gregorian
       klass = DateTime
@@ -39,25 +37,39 @@ 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{1,4})(\-(\d{1,2}))?(\s+(\w{3}|[+\-]\d{1,2}(:?\d{1,2})))?\z/
+        year  = $1.to_i
+        month = $3 ? $3.to_i : 1
+        mday  = 1
+        rest  = $4
+        hash = DateTime._parse("#{year}-#{month}-#{mday} 00:00:00 #{rest}")
+      else
+        hash = DateTime._parse(spec)
+      end
     end
-    year, month, day, hour, minute, second, sec_fraction, offset = 
+    year, month, day, hour, minute, second, sec_fraction, offset_ = 
            hash.values_at(:year, :mon, :mday, :hour, :min, :sec, :sec_fraction, :offset)
-    if bc and year < 0
-      year = year + 1
-    end
     hour   ||= 0
     minute ||= 0
     second ||= 0.0
     sec_fraction ||= 0.0
-    offset ||= 0
-    if hour == 24 && minute == 0 && second == 0.0
-      klass.new(year, month, day, 23, minute, second + sec_fraction, offset.quo(86400), start) + 1.quo(24)
+    if offset_ 
+      offset = offset_.quo(86400)
+    else
+      offset ||= 0
+    end
+    if tz
+      time = tz.local_datetime(year, month, day, hour, minute, second.to_i, sec_fraction.to_r)
     else
-      klass.new(year, month, day, hour, minute, second + sec_fraction, offset.quo(86400), start)
+      if hour == 24 && minute == 0 && second == 0.0
+        time = klass.new(year, month, day, 23, minute, second + sec_fraction, offset, start) + 1.quo(24)
+      else
+        time = klass.new(year, month, day, hour, minute, second + sec_fraction, offset, start)
+      end    
     end
+    return time
   end
 
 end

data/lib/timesteps/datetime_timestep.rb

@@ -0,0 +1,64 @@
+
+class DateTime
+  
+  def timestep (interval_spec, tz: nil)
+    case start
+    when Date::ITALY
+      calendar = "standard"
+    when Date::GREGORIAN
+      calendar = "proleptic_gregorian"
+    when Date::JULIAN
+      calendar = "proleptic_julian"
+    end
+    return TimeStep.new(interval_spec, since: self, calendar: calendar, tz: tz)
+  end
+
+  def timeperiod (interval_spec, tz: nil, ends: "[]")
+    case start
+    when Date::ITALY
+      calendar = "standard"
+    when Date::GREGORIAN
+      calendar = "proleptic_gregorian"
+    when Date::JULIAN
+      calendar = "proleptic_julian"
+    end
+    return TimePeriod.new(interval_spec, since: self, calendar: calendar, ends: ends, tz: tz)
+  end
+
+end
+
+class DateTime::NoLeap
+
+  def timestep (interval_spec, tz: nil)
+    return TimeStep.new(interval_spec, since: self, clanedar: "noleap", tz: tz)
+  end  
+
+  def timeperiod (interval_spec, tz: nil, ends: "[]")
+    return TimePeriod.new(interval_spec, since: self, calendar: "noleap", ends: ends, tz: tz)
+  end
+
+end
+
+class DateTime::AllLeap
+
+  def timestep (interval_spec, tz: nil)
+    return TimeStep.new(interval_spec, since: self, clanedar: "allleap", tz: tz)
+  end  
+
+  def timeperiod (interval_spec, tz: nil, ends: "[]")
+    return TimePeriod.new(interval_spec, since: self, calendar: "allleap", ends: ends, tz: tz)
+  end
+
+end
+
+class DateTime::Fixed360Day
+
+  def timestep (interval_spec, tz: nil)
+    return TimeStep.new(interval_spec, since: self, clanedar: "360day", tz: tz)
+  end  
+
+  def timeperiod (interval_spec, tz: nil, ends: "[]")
+    return TimePeriod.new(interval_spec, since: self, calendar: "360day", ends: ends, tz: tz)
+  end
+
+end

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
 
@@ -398,29 +398,18 @@ class DateTimeLike
   #
   # @return [Integer]
   def difference_in_years (other)
-    extra = 0
-    if self.year > other.year && self.compare_md(other) < 0
-      extra = -1
-    end
-    if self.year < other.year && self.compare_md(other) > 0
-      extra = 1
-    end
-    return self.year - other.year + extra
+    my    = self.new_offset(0)
+    other = other.new_offset(0)
+    return my.year - other.year + my.compare_md(other).quo(2)
   end
   
   # Calculate difference between the object and other object in months.
   #
   # @return [Integer]
   def difference_in_months (other)
-    extra = 0
-    if self.month > other.month && self.compare_d(other) < 0
-      extra = -1
-    end
-    if self.month < other.month && self.compare_d(other) > 0
-      extra = 1
-    end
-    return 12*(self.year - other.year) + self.month - other.month + extra  
+    my    = self.new_offset(0)
+    other = other.new_offset(0)
+    return 12*(my.year - other.year) + my.month - other.month + my.compare_d(other).quo(2)  
   end
-  
 end
 

data/lib/timesteps/grads.rb

@@ -1,6 +1,24 @@
-require_relative "../timesteps"
+require "timesteps"
 
-class TimeStep
+class DateTime
+  
+  def self.parse_grads_time (time_string)
+    if time_string.strip =~ /\A(((\d{2})?(:(\d{2}))?Z)?(\d{2}))?(\w{3})(\d{4})\z/i
+      hour = $3 || "00"
+      min  = $5 || "00"
+      day  = $6 || "01"
+      mon  = $7
+      year = $8
+      time = DateTime.parse("#{year}#{mon}#{day} #{hour}:#{min}:00")
+    else
+      raise "invalid time format"
+    end
+    return time
+  end
+  
+end
+
+class TimeStep::Range
 
   # @private
   REGEXP_GRADS_TDEF = /\A(?:TDEF\s+)?(\d+)\s+LINEAR\s+([^\s]*?)\s+([^\s]*?)\s*\z/i
@@ -13,8 +31,17 @@ class TimeStep
     "mo" => "months",
     "yr" => "years",
   }
-  
-  def self.parse_grads_tdef (tdef_string)
+
+  module GrADSMixin
+
+    def parse_grads_time (time_string)
+      return DateTime.parse_grads_time(time_string)
+    end
+
+  end
+    
+  def self.from_grads_tdef (tdef_string)
+
     if tdef_string.strip =~ REGEXP_GRADS_TDEF
       count = $1.to_i
       time  = $2
@@ -22,22 +49,16 @@ class TimeStep
     else
       raise "invalid grads tdef string"
     end
-    if time =~ /(((\d{2})?(:(\d{2}))?Z)?(\d{2}))?(\w{3})(\d{4})/i
-      hour = $3 || "00"
-      min  = $5 || "00"
-      day  = $6 || "01"
-      mon  = $7
-      year = $8
-      origin = DateTime.parse("#{year}#{mon}#{day} #{hour}:#{min}:00")
-    else
-      raise "invalid time format"
-    end
+
+    origin = DateTime.parse_grads_time(time)
     
     increment = increment.sub(/(mn|hr|dy|mo|yr)/i) {|s| GRADS_INCREMENT[s.downcase]}
-    
-    spec = format("%s since %s", increment, origin.strftime("%F %T"))
-    
-    return TimeStep.new(spec, count: count)
+        
+    range = TimeStep.new(increment, since: origin).range(count)
+    range.extend GrADSMixin
+
+    return range
   end
   
+  
 end

data/lib/timesteps/time.rb

@@ -0,0 +1,14 @@
+require 'date'
+
+class Time
+  def to_datetime
+    # Convert seconds + microseconds into a fractional number of seconds
+    seconds = sec + Rational(usec, 10**6)
+
+    # Convert a UTC offset measured in minutes to one measured in a
+    # fraction of a day.
+    offset = Rational(utc_offset, 60 * 60 * 24)
+
+    DateTime.new(year, month, day, hour, min, seconds, offset)
+  end
+end

data/lib/timesteps/timeperiod.rb

@@ -0,0 +1,205 @@
+
+
+class TimePeriod < TimeStep
+
+  def initialize (spec, since: nil, format: nil, offset: nil, calendar: "standard", tz: nil, ends: "[]" )
+    super(spec, since: since, format: format, offset: offset, calendar: calendar, tz: tz)
+    raise "invalid ends specification" unless ends =~ /\A[\[\(][\]\)]\z/
+    @ends = ends
+    @include_start = ( ends[0] == "[" ) ? true : false
+    @include_last  = ( ends[1] == "]" ) ? true : false 
+    @last = time_at(1)
+  end
+  
+  attr_reader :last, :ends
+
+  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
+    options = ""
+    case @calendar.name
+    when "standard", "gregorian"
+    else
+      options << " calendar='#{calendar.name}'"
+    end
+    left_paren = @include_start ? "[" : "("
+    right_paren = @include_last ? "]" : ")"
+    "#<TimePeriod '#{interval_spec}' #{left_paren}#{start.to_s}, #{last.to_s}#{right_paren} #{options}>"
+  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_end = other.include_start? ? "[" : "("
+    else
+      left = @origin
+      left_end = include_start? ? "[" : "("      
+    end
+    if ( @last < other.last ) ||
+       ( @last == other.last && ( not include_last? ) && other.include_last? )
+      right = other.last
+      right_end = other.include_last? ? "]" : ")"
+    else
+      right = @last
+      right_end = include_last? ? ")" : "]"      
+    end
+    ridx = index_at(right)
+    lidx = index_at(left)
+    numeric = (ridx - lidx) * @numeric
+    origin = left
+    interval_spec = format("%g %s", numeric, @symbol)
+    ends = left_end + right_end
+    return TimePeriod.new(interval_spec, since: origin, calendar: @calendar, ends: ends)
+  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_end = other.include_start? ? "[" : "("
+    else
+      left = @origin
+      left_end = include_start? ? "[" : "("      
+    end
+    if ( other.last < @last ) ||
+       ( other.last == @last && include_last? && ( not other.include_last? ) )
+      right = other.last
+      right_end = other.include_last? ? "]" : ")"
+    else
+      right = @last
+      right_end = include_last? ? ")" : "]"      
+    end
+    ridx = index_at(right)
+    lidx = index_at(left)
+    numeric = (ridx - lidx) * @numeric
+    origin = left
+    interval_spec = format("%g %s", numeric, @symbol)
+    ends = left_end + right_end
+    return TimePeriod.new(interval_spec, since: origin, calendar: @calendar, ends: ends)
+  end
+  
+  def split (time, ends: ")[")
+    raise "can't split period without contacted time" unless contact?(time)
+    # left
+    numeric = index_at(time) * @numeric
+    interval_spec = format("%g %s", numeric, @symbol)
+    ends   = (@include_start ? "[" : "(") + ends[0]
+    left_period  = TimePeriod.new(interval_spec, since: @origin, calendar: @calendar, ends: ends)
+    # right
+    numeric = (1 - index_at(time)) * @numeric
+    interval_spec = format("%g %s", numeric, @symbol)
+    ends   = ends[1] + (@include_last ? "]" : ")")
+    right_period  = TimePeriod.new(interval_spec, since: @origin, calendar: @calendar, ends: ends)
+    return left_period, right_period
+  end
+  
+  def next
+    return TimePeriod.new(interval_spec, since: @last, calendar: @calendar, ends: ends)    
+  end
+
+  def prev
+    origin = index_at(-1)
+    return TimePeriod.new(interval_spec, since: origin, calendar: @calendar, ends: ends)    
+  end
+
+  def shift_origin (index, with: "index")
+    case with
+    when :index, "index"
+      return TimePeriod.new(interval_spec, since: time_at(index), calendar: @calendar, ends: ends)    
+    when :duration, "duration", :days, "days"
+      time = @origin + index
+      return TimePeriod.new(interval_spec, since: time, calendar: @calendar, ends: ends)
+    end
+
+  end
+    
+end
+