Class: CATime::Resolution

Inherits:
Object
  • Object
show all
Defined in:
lib/carray/time.rb

Overview

A tick resolution: count ticks of a base unit. The human surface is a String ("3 hours" / "1 month"); a bare Symbol (:h) is the count-1 shorthand over the base-unit vocabulary. It names both a storage tick (= the grid a CATime is stored on) and a coarser bucket for the floor / timesteps family. Value object: frozen, value-equal, hashable.

Constant Summary collapse

WORDS =

Long / abbreviated unit words -> base unit symbol. Calendar words (ayear etc.) are intentionally dropped (standard calendar only).

{
  "year" => :Y, "years" => :Y, "yr" => :Y, "yrs" => :Y,
  "month" => :M, "months" => :M, "mon" => :M, "mons" => :M,
  "week" => :W, "weeks" => :W,
  "day" => :D, "days" => :D,
  "hour" => :h, "hours" => :h, "hr" => :h, "hrs" => :h,
  "minute" => :m, "minutes" => :m, "min" => :m, "mins" => :m,
  "second" => :s, "seconds" => :s, "sec" => :s, "secs" => :s,
  "millisecond" => :ms, "milliseconds" => :ms, "msec" => :ms, "msecs" => :ms,
  "microsecond" => :us, "microseconds" => :us, "usec" => :us, "usecs" => :us,
  "nanosecond" => :ns, "nanoseconds" => :ns,
  "picosecond" => :ps, "picoseconds" => :ps,
  "femtosecond" => :fs, "femtoseconds" => :fs,
  "attosecond" => :as, "attoseconds" => :as,
}.freeze
SYMBOLS =

Single-letter / short symbols accepted as the count-1 shorthand. These are the base-unit letters (case-sensitive: :m minute vs :M month).

i[Y M W D h m s ms us ns ps fs as].freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(count, base) ⇒ Resolution

Returns a new instance of Resolution.

Raises:

  • (ArgumentError) 


2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
 
# File 'lib/carray/time.rb', line 2159

def initialize(count, base)
  raise ArgumentError, "unit count must be >= 1 (got #{count})" if count < 1
  # Only integer multiples are well-defined (calendar Y/M bases are
  # month-ordinal linear, so a fractional multiple has no meaning).
  # Resolution.parse always hands in an Integer; a fractional count via
  # a direct `new` is not guarded here.
  @count = count
  @base  = base
  freeze
end

Instance Attribute Details

#base ⇒ Object (readonly)

Returns the value of attribute base.



2106
2107
2108
 
# File 'lib/carray/time.rb', line 2106

def base
  @base
end

#count ⇒ Object (readonly)

Returns the value of attribute count.



2106
2107
2108
 
# File 'lib/carray/time.rb', line 2106

def count
  @count
end

Class Method Details

.parse(spec) ⇒ Resolution

Coerces spec into a CATime::Resolution: a Resolution passes through, a base unit Symbol becomes count 1, and a String such as "10 minutes" is parsed.

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    when spec names no known unit.



2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
 
# File 'lib/carray/time.rb', line 2135

def self.parse(spec)
  case spec
  when Resolution then spec
  when Symbol
    unless SYMBOLS.include?(spec)
      raise ArgumentError, "invalid unit #{spec.inspect} " \
            "(one of #{SYMBOLS.map(&:inspect).join(', ')})"
    end
    new(1, spec)
  when String
    # Strict grammar: "<unit>" (count 1) or "<n> <unit>" (whitespace
    # required -- compact "3h" is rejected).
    m = spec.strip.match(/\A(?:(\d+)\s+)?([A-Za-z]+)\z/)
    unless m && WORDS.key?(m[2].downcase)
      raise ArgumentError, "invalid unit spec #{spec.inspect} " \
            "(use e.g. \"3 hours\" / \"1 month\", or a unit Symbol)"
    end
    new(m[1] ? Integer(m[1]) : 1, WORDS[m[2].downcase])
  else
    raise ArgumentError, "unit spec must be a String / Symbol / Resolution " \
          "(got #{spec.class})"
  end
end

Instance Method Details

#==(other) ⇒ Boolean Also known as: eql?

Returns whether other is the same count and base unit.

Returns:

  • (Boolean) —

    whether other is the same count and base unit.



2176
 
# File 'lib/carray/time.rb', line 2176

def ==(other) = other.is_a?(Resolution) && other.count == count && other.base == base

#hash ⇒ Integer

Returns a hash consistent with #==.

Returns:

  • (Integer) —

    a hash consistent with #==.



2179
2180
 
# File 'lib/carray/time.rb', line 2179

def hash = [count, base].hash
# @return [String] e.g. `"h"` for a count of 1, `"10 minutes"` otherwise.

#inspect ⇒ String

Returns:

  • (String) 


2183
 
# File 'lib/carray/time.rb', line 2183

def inspect = "#<CATime::Resolution #{count} #{base}>"

#tick_ratio ⇒ Object

seconds- (fixed base) or months- (calendar base) per tick (Rational).



2171
2172
2173
 
# File 'lib/carray/time.rb', line 2171

def tick_ratio
  count * CATimeUnitAlgebra.base_ratio(base)
end

#to_s ⇒ String

Returns e.g. "h" for a count of 1, "10 minutes" otherwise.

Returns:

  • (String) —

    e.g. "h" for a count of 1, "10 minutes" otherwise.



2181
2182
 
# File 'lib/carray/time.rb', line 2181

def to_s = count == 1 ? base.to_s : "#{count} #{base}"
# @return [String]