timesteps 0.9.3

data/lib/timesteps/format.rb

@@ -0,0 +1,251 @@
+#
+# format.rb is modified version of date/format.rb distributed in Ruby 1.8.7.
+#
+# format.rb: Written by Tadayoshi Funaba 1999-2008
+# $Id: format.rb,v 2.43 2008-01-17 20:16:31+09 tadf Exp $
+
+
+#
+#
+#
+class DateTimeLike
+
+  # @private
+  MILLISECONDS_IN_DAY    = Rational(1, 86400*10**3) 
+
+  # @private
+  MILLISECONDS_IN_SECOND = Rational(1, 10**3) 
+
+  # @private
+  NANOSECONDS_IN_DAY     = Rational(1, 86400*10**9) 
+
+  # @private
+  NANOSECONDS_IN_SECOND  = Rational(1, 10**9) 
+
+  # @private
+  SECONDS_IN_DAY         = Rational(1, 86400) 
+
+  # @private
+  # Full month names, in English.  Months count from 1 to 12; a
+  # month's numerical representation indexed into this array
+  # gives the name of that month (hence the first element is nil).
+  MONTHNAMES = [nil] + %w(January February March April May June July
+			  August September October November December)
+
+  # @private
+  # Full names of days of the week, in English.  Days of the week
+  # count from 0 to 6 (except in the commercial week); a day's numerical
+  # representation indexed into this array gives the name of that day.
+  DAYNAMES = %w(Sunday Monday Tuesday Wednesday Thursday Friday Saturday)
+
+  # @private
+  # Abbreviated month names, in English.
+  ABBR_MONTHNAMES = [nil] + %w(Jan Feb Mar Apr May Jun
+			       Jul Aug Sep Oct Nov Dec)
+
+  # @private
+  # Abbreviated day names, in English.
+  ABBR_DAYNAMES = %w(Sun Mon Tue Wed Thu Fri Sat)
+
+  [MONTHNAMES, DAYNAMES, ABBR_MONTHNAMES, ABBR_DAYNAMES].each do |xs|
+    xs.each{|x| x.freeze unless x.nil?}.freeze
+  end
+
+  def emit(e, f) # :nodoc:
+    case e
+    when Numeric
+      sign = %w(+ + -)[e <=> 0]
+      e = e.abs
+    end
+
+    s = e.to_s
+
+    if f[:s] && f[:p] == '0'
+      f[:w] -= 1
+    end
+
+    if f[:s] && f[:p] == "\s"
+      s[0,0] = sign
+    end
+
+    if f[:p] != '-'
+      s = s.rjust(f[:w], f[:p])
+    end
+
+    if f[:s] && f[:p] != "\s"
+      s[0,0] = sign
+    end
+
+    s = s.upcase if f[:u]
+    s = s.downcase if f[:d]
+    s
+  end
+
+  def emit_w(e, w, f) # :nodoc:
+    f[:w] = [f[:w], w].compact.max
+    emit(e, f)
+  end
+
+  def emit_n(e, w, f) # :nodoc:
+    f[:p] ||= '0'
+    emit_w(e, w, f)
+  end
+
+  def emit_sn(e, w, f) # :nodoc:
+    if e < 0
+      w += 1
+      f[:s] = true
+    end
+    emit_n(e, w, f)
+  end
+
+  def emit_z(e, w, f) # :nodoc:
+    w += 1
+    f[:s] = true
+    emit_n(e, w, f)
+  end
+
+  def emit_a(e, w, f) # :nodoc:
+    f[:p] ||= "\s"
+    emit_w(e, w, f)
+  end
+
+  def emit_ad(e, w, f) # :nodoc:
+    if f[:x]
+      f[:u] = true
+      f[:d] = false
+    end
+    emit_a(e, w, f)
+  end
+
+  def emit_au(e, w, f) # :nodoc:
+    if f[:x]
+      f[:u] = false
+      f[:d] = true
+    end
+    emit_a(e, w, f)
+  end
+
+  private :emit, :emit_w, :emit_n, :emit_sn, :emit_z,
+          :emit_a, :emit_ad, :emit_au
+
+  def strftime(fmt='%F')
+    
+    fmt.gsub(/%([-_0^#]+)?(\d+)?([EO]?(?::{1,3}z|.))/m) do |m|
+      f = {}
+      a = $&
+      s, w, c = $1, $2, $3
+      if s
+        s.scan(/./) do |k|
+          case k
+          when '-'; f[:p] = '-'
+          when '_'; f[:p] = "\s"
+          when '0'; f[:p] = '0'
+          when '^'; f[:u] = true
+          when '#'; f[:x] = true
+          end
+        end
+      end
+      if w
+        f[:w] = w.to_i
+      end
+      case c
+      when 'A'; emit_ad(DAYNAMES[wday], 0, f)
+      when 'a'; emit_ad(ABBR_DAYNAMES[wday], 0, f)
+      when 'B'; emit_ad(MONTHNAMES[month], 0, f)
+      when 'b'; emit_ad(ABBR_MONTHNAMES[month], 0, f)
+      when 'C', 'EC'; emit_sn((year / 100).floor, 2, f)
+      when 'c', 'Ec'; emit_a(strftime('%a %b %e %H:%M:%S %Y'), 0, f)
+      when 'D'; emit_a(strftime('%m/%d/%y'), 0, f)
+      when 'd', 'Od'; emit_n(day, 2, f)
+      when 'e', 'Oe'; emit_a(day, 2, f)
+      when 'F'
+        if m == '%F'
+          format('%.4d-%02d-%02d', year, month, day) # 4p
+        else
+          emit_a(strftime('%Y-%m-%d'), 0, f)
+        end
+      when 'G'; emit_sn(cwyear, 4, f)
+      when 'g'; emit_n(cwyear % 100, 2, f)
+      when 'H', 'OH'; emit_n(hour, 2, f)
+      when 'h'; emit_ad(strftime('%b'), 0, f)
+      when 'I', 'OI'; emit_n((hour % 12).nonzero? || 12, 2, f)
+      when 'j'; emit_n(yday, 3, f)
+      when 'k'; emit_a(hour, 2, f)
+      when 'L'
+        emit_n((sec_fraction / MILLISECONDS_IN_SECOND).round, 3, f)
+      when 'l'; emit_a((hour % 12).nonzero? || 12, 2, f)
+      when 'M', 'OM'; emit_n(minute, 2, f)
+      when 'm', 'Om'; emit_n(month, 2, f)
+      when 'N'
+        emit_n((sec_fraction / NANOSECONDS_IN_SECOND).round, 9, f)
+      when 'n'; "\n"
+      when 'P'; emit_ad(strftime('%p').downcase, 0, f)
+      when 'p'; emit_au(if hour < 12 then 'AM' else 'PM' end, 0, f)
+      when 'Q'
+        s = ((ajd - self::class::UNIX_EPOCH_IN_AJD) / MILLISECONDS_IN_DAY).round
+        emit_sn(s, 1, f)
+      when 'R'; emit_a(strftime('%H:%M'), 0, f)
+      when 'r'; emit_a(strftime('%I:%M:%S %p'), 0, f)
+      when 'S', 'OS'; emit_n(second.floor, 2, f)
+      when 's'
+        s = ((ajd - self::class::UNIX_EPOCH_IN_AJD) / SECONDS_IN_DAY).round
+        emit_sn(s, 1, f)
+      when 'T'
+        if m == '%T'
+          format('%02d:%02d:%02d', hour, minute, second) # 4p
+        else
+          emit_a(strftime('%H:%M:%S'), 0, f)
+        end
+      when 't'; "\t"
+      when 'U', 'W', 'OU', 'OW'
+        emit_n(if c[-1,1] == 'U' then wnum0 else wnum1 end, 2, f)
+      when 'u', 'Ou'; emit_n(cwday, 1, f)
+      when 'V', 'OV'; emit_n(cweek, 2, f)
+      when 'v'; emit_a(strftime('%e-%b-%Y'), 0, f)
+      when 'w', 'Ow'; emit_n(wday, 1, f)
+      when 'X', 'EX'; emit_a(strftime('%H:%M:%S'), 0, f)
+      when 'x', 'Ex'; emit_a(strftime('%m/%d/%y'), 0, f)
+      when 'Y', 'EY'; emit_sn(year, 4, f)
+      when 'y', 'Ey', 'Oy'; emit_n(year % 100, 2, f)
+      when 'Z'; emit_au(strftime('%:z'), 0, f)
+      when /\A(:{0,3})z/
+        t = $1.size
+        sign = if offset < 0 then -1 else +1 end
+        fr = offset.abs
+        ss = fr.div(SECONDS_IN_DAY) # 4p
+        hh, ss = ss.divmod(3600)
+        mm, ss = ss.divmod(60)
+        if t == 3
+          if    ss.nonzero? then t =  2
+          elsif mm.nonzero? then t =  1
+          else                   t = -1
+          end
+        end
+        case t
+        when -1
+          tail = []
+          sep = ''
+        when 0
+          f[:w] -= 2 if f[:w]
+          tail = ['%02d' % mm]
+          sep = ''
+        when 1
+          f[:w] -= 3 if f[:w]
+          tail = ['%02d' % mm]
+          sep = ':'
+        when 2
+          f[:w] -= 6 if f[:w]
+          tail = ['%02d' % mm, '%02d' % ss]
+          sep = ':'
+        end
+        ([emit_z(sign * hh, 2, f)] + tail).join(sep)
+      when '%'; emit_a('%', 0, f)
+      when '+'; emit_a(strftime('%a %b %e %H:%M:%S %Z %Y'), 0, f)
+      else
+        a
+      end
+    end
+  end
+
+end

data/lib/timesteps/grads.rb

@@ -0,0 +1,43 @@
+require_relative "../timesteps"
+
+class TimeStep
+
+  # @private
+  REGEXP_GRADS_TDEF = /\A(?:TDEF\s+)?(\d+)\s+LINEAR\s+([^\s]*?)\s+([^\s]*?)\s*\z/i
+  
+  # @private
+  GRADS_INCREMENT = {
+    "mn" => "minutes",
+    "hr" => "hours",
+    "dy" => "days",
+    "mo" => "months",
+    "yr" => "years",
+  }
+  
+  def self.parse_grads_tdef (tdef_string)
+    if tdef_string.strip =~ REGEXP_GRADS_TDEF
+      count = $1.to_i
+      time  = $2
+      increment = $3
+    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
+    
+    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)
+  end
+  
+end

data/lib/timesteps/parse_timestamp.rb

@@ -0,0 +1,48 @@
+class DateTime
+
+  module ParseTimeStampExtension
+
+    # Parses the given datetime expression and creates an instance.
+    # `DateTime._parse()` is called internally.
+    #
+    # @param spec [String]
+    # @option bc [Boolean]
+    #
+    # @return [DateTimeFixedDPY]
+
+    def parse_timestamp (spec, start=Date::ITALY, bc: false)
+      hash = DateTime._parse(spec)
+      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
+        self.new(year, month, day, 23, minute, second + sec_fraction, offset.quo(86400), start) + 1.quo(24)
+      else
+        self.new(year, month, day, hour, minute, second + sec_fraction, offset.quo(86400), start)
+      end
+    end
+
+  end
+
+  extend ParseTimeStampExtension
+
+  class NoLeap < DateTimeLike
+    extend ParseTimeStampExtension
+  end
+
+  class AllLeap < DateTimeLike
+    extend ParseTimeStampExtension
+  end
+
+  class Fixed360Day < DateTimeLike
+    extend ParseTimeStampExtension
+  end
+
+end

data/lib/timesteps/timestep.rb

@@ -0,0 +1,362 @@
+
+class TimeStep
+
+  using DateTimeExt
+
+  # Constructs the object.
+  #
+  # The argument `spec` specifies the time step definition, which has the form,
+  #   "<INTERVAL> since <TIME>"
+  # For example, 
+  #   * "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" 
+  # The symbol for time unit symbols should be one of
+  #   * years, year
+  #   * months, month
+  #   * days, day, d
+  #   * hours, hr, h
+  #   * minutes, minute, min
+  #   * seconds, second, sec, s
+  # 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).
+  #
+  # @param spec [String]
+  # @option calendar [String, TimeStep::Calendar]
+  # @option bc [Boolean]
+  # @option count [Integer] number of time steps (as hint for some methods)
+  # 
+  def initialize (spec, calendar: "standard", bc: false, count: nil)
+    case calendar
+    when String
+      @calendar = Calendar.new(calendar, bc: bc)
+    else
+      @calendar = calendar
+    end
+    intervalspec, timespec = spec.split(/\s+since\s+/)
+    parse_interval(intervalspec)
+    @origin       = @calendar.parse(timespec)
+    @intervalspec = format("%g %s", @numeric, symbol)
+    @timespec     = @origin.strftime("%Y-%m-%d %H:%M:%S.%N %:z")
+    @definition   = format("%s since %s", @intervalspec, @timespec)
+    @count = count
+  end
+
+  # @private
+  PATTERN_NUMERIC = '[\+\-]?\d*(?:\.\d+)?(?:[eE][\+\-]?\d+)?'
+  # @private
+  PATTERN_UNITS   = 'years?|months?|days?|hours?|minutes?|seconds?|d|hr|h|min|sec|s'
+
+  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
+      symbol = $2
+    else
+      raise "invalid interval specification"
+    end
+    @interval = @numeric
+    case symbol
+    when "years", "year"
+      unless numeric.denominator == 1
+        raise "numeric factor for year should be an integer"
+      end
+      @symbol = :years
+      @interval *= 356.242*86400
+    when "months", "month"
+      unless numeric.denominator == 1
+        raise "numeric factor for month should be an integer"
+      end
+      @symbol = :months
+      @interval *= 30.4368*86400
+    when "days", "day", "d"
+      @symbol = :days
+      @interval *= 86400
+    when "hours", "hour", "hr", "h"
+      @symbol = :hours
+      @interval *= 3600
+    when "minutes", "minute", "min"
+      @symbol = :minutes
+      @interval *= 60
+    when "seconds", "second", "sec", "s"
+      @symbol = :seconds
+    end
+  end
+  
+  private :parse_interval
+
+  attr_reader :definition, 
+              :intervalspec, 
+              :timespec, 
+              :numeric, 
+              :symbol, 
+              :interval, 
+              :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)
+    else
+      return nil
+    end
+  end
+
+  # Sets count by giving maximum time.
+  # 
+  # @return [DateTime, nil]
+  def limit= (time)
+    if time
+      @count = (prev_index_of(time) + 1).to_i
+    else
+      @count = nil
+    end
+    return limit
+  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
+  end
+
+  def info
+    return {
+      "definition"   => @definition.clone,
+      "intervalspec" => @intervalspec.clone,
+      "timespec"     => @timespec.clone,
+      "calendar"     => @calendar.name,
+      "numeric"      => @numeric,
+      "symbol"       => @symbol.to_s,
+      "interval"     => @interval,
+      "origin"       => @origin.clone,
+      "count"        => @count,
+      "bc"           => @calendar.bc?,
+    }
+  end
+
+  def inspect
+    "#<TimeStep definition='#{definition}' calendar='#{calendar.name}'>"
+  end
+
+  # Returns true if other has same contents of `definition` and `calendar` 
+  # as self has.
+  #
+  # @return [Boolean]
+  def == (other)
+    return @definition == other.definition && @calendar == other.calendar 
+  end
+
+  def user_to_days (index)
+    return ( @interval * index.to_r ).quo(86400)
+  end
+
+  def days_to_user (index)
+    return ( 86400 * index.to_r ).quo(@interval)
+  end
+
+  # Returns the time represented by the given amount as DateTime object
+  #
+  # @param indices [Numeric,Array<Numeric>]
+  #
+  # @return [DateTime]
+  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
+      case @symbol
+      when :years
+        unless index.denominator == 1
+          raise "index for years should be an integer"
+        end
+        return @origin.next_year(index*@numeric)
+      when :months
+        unless index.denominator == 1
+          raise "index for years should be an integer"
+        end
+        return @origin.next_month(index*@numeric)
+      else
+        days = user_to_days(index) + @origin.jd + @origin.fraction - @origin.offset
+        jday = days.floor
+        fday = days - days.floor
+        return (@calendar.jday2date(jday) + fday).new_offset(@origin.offset)
+      end
+    else
+      return indices.map{|index| time_at(index) }      
+    end
+  end
+    
+  # Returns the index for the given time in the unit represented by the object
+  #
+  # @param times [DateTime] time object
+  #
+  # @return [Numeric]
+  def index_at (*times)
+    if times.size == 1
+      time = times.first
+      time = @calendar.parse(time) if time.is_a?(String)
+      case @symbol
+      when :years
+        return time.difference_in_years(@origin).quo(@numeric.to_i)
+      when :months
+        return time.difference_in_months(@origin).quo(@numeric.to_i)
+      else
+        jday  = @calendar.date2jday(time.year, time.month, time.day)
+      	fday  = time.fraction
+      	udays = days_to_user(jday - @origin.jd)
+      	utime = days_to_user(fday - @origin.fraction)
+      	return udays + utime
+      end
+    else
+      return times.map{|time| index_at(time) }      
+    end
+  end
+  
+  # Calculate the time difference in days from origin at the index.
+  #
+  # @param indices [Array]
+  # @return [DateTime, Array<DateTime>]
+  def days_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"
+        end
+        return @origin.next_year(@numeric*index) - @origin
+      when :months
+        unless index.denominator == 1
+          raise "index for years should be an integer"
+        end
+        return @origin.next_month(@numeric*index) - @origin
+      else
+        return user_to_days(index)
+      end
+    else
+      return indices.map{ |index| days_at(index) }            
+    end
+  end
+  
+  # Returns TimeStep object which has origin time determined 
+  # by the given `index`.
+  #
+  # @param index [Numeric]
+  #
+  # @return [TimeStep]
+  def shift_origin (index)
+    time = time_at(index)
+    return TimeStep.new(@intervalspec + " since " + time.strftime("%Y-%m-%d %H:%M:%S.%N %:z"), calendar: @calendar)
+  end
+
+  # Returns TimeStep object which has origin time specified 
+  # by the given `time`.
+  #
+  # @param time [DateTime]
+  #
+  # @return [TimeStep]
+  def new_origin (time)
+    case time
+    when String
+      time = @calendar.parse(time)
+    end
+    return TimeStep.new(@intervalspec + " since " + time.strftime("%Y-%m-%d %H:%M:%S.%N %:z"), calendar: @calendar)
+  end
+
+  include Enumerable
+  
+  def each (limit = nil, incr = 1, &block)
+    if limit.nil? 
+      raise "step method require count" 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 "step method require count" unless @count
+    (0...@count).each(&block)
+  end
+  
+  # Creates TimeStep::Pair 
+  #
+  #
+  def in (unit)
+    return TimeStep::Pair.new(self, format("%s since %s", unit, @timespec), calendar: @calendar)
+  end
+  
+  def next_index_of (time)
+    case time
+    when String
+      time = @calendar.parse(time)
+    end
+    index = index_at(time).to_r
+    if index.denominator == 1
+      return index + 1
+    else
+      return index.ceil
+    end
+  end
+
+  def prev_index_of (time)
+    return next_index_of(time) - 1
+  end
+
+  def next_time_of (time)
+    return time_at(next_index_of(time))
+  end
+
+  def prev_time_of (time)
+    return time_at(prev_index_of(time))  
+  end
+
+  def parse (time)
+    return @calendar.parse(time)
+  end
+
+end
+