Class: CATimedelta::Element

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

Overview

A single duration: an integer tick count plus the resolution those ticks are counted in. What a scalar read of a CATimedelta returns.

Instance Method Summary collapse

Instance Method Details

#*(n) ⇒ CATimedelta::Element

Returns this duration scaled by an Integer.

Parameters:

  • n (Integer)

Returns:

Raises:

  • (TypeError) 


595
596
597
598
 
# File 'lib/carray/time.rb', line 595

def *(n)
  raise TypeError, "CATimedelta::Element * #{n.class} is not allowed (Integer only)" unless n.is_a?(Integer)
  Element.new(value * n, unit)
end

#+(other) ⇒ CATimedelta::Element

Returns the sum of two durations, promoting to the finer unit. A cross-group operand (a :M + a :s duration) has no fixed relation and raises.

Parameters:

Returns:



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

def +(other) = _combine(other, 1)

#-(other) ⇒ CATimedelta::Element

Returns the difference of two durations (finer unit; cross-group raises).

Parameters:

Returns:



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

def -(other) = _combine(other, -1)

#/(other) ⇒ CATimedelta::Element, Rational

By an Integer -> a scaled CATimedelta::Element; by another CATimedelta::Element -> their dimensionless ratio as a Rational (both brought to the finer unit; cross-group raises).

Parameters:

Returns:



606
607
608
609
610
611
612
613
614
615
 
# File 'lib/carray/time.rb', line 606

def /(other)
  case other
  when Integer then Element.new(value / other, unit)
  when Element
    u = CATimeUnitAlgebra.finer(unit, other.unit)
    Rational(_scale_in(u), other.send(:_scale_in, u))
  else
    raise TypeError, "CATimedelta::Element / #{other.class} is not allowed"
  end
end

#<=>(other) ⇒ Object

Three-way compare, reconciling a different unit by the fixed ratio. A cross-group pair (a :M vs a :s duration) has no order -- there is no fixed ratio -- so it returns nil (Comparable then makes < raise and == false). No explicit == is defined; Comparable derives it.



559
560
561
562
563
564
565
566
 
# File 'lib/carray/time.rb', line 559

def <=>(other)
  return nil unless other.is_a?(Element)
  return nil unless CATimeUnitAlgebra.same_group?(unit, other.unit)
  u = CATimeUnitAlgebra.finer(unit, other.unit)
  _scale_in(u) <=> other._scale_in(u)
rescue ArgumentError
  nil
end

#eql?(other) ⇒ Boolean

Returns:

  • (Boolean) 


568
569
570
 
# File 'lib/carray/time.rb', line 568

def eql?(other)
  other.is_a?(Element) && other.unit == unit && other.value == value
end

#hash ⇒ Integer

Returns a hash consistent with #eql? (unit-strict).

Returns:

  • (Integer) —

    a hash consistent with #eql? (unit-strict).



573
574
575
 
# File 'lib/carray/time.rb', line 573

def hash
  [value, unit].hash
end

#inspect ⇒ String

Returns:

  • (String) 


551
552
553
 
# File 'lib/carray/time.rb', line 551

def inspect
  "#<CATimedelta::Element #{to_s}>"
end

#to_s ⇒ String

Returns the value followed by its unit.

Returns:

  • (String) —

    the value followed by its unit.



546
547
548
 
# File 'lib/carray/time.rb', line 546

def to_s
  unit.count == 1 ? "#{value}#{unit.base}" : "#{value} @ #{unit}"
end

#to_seconds ⇒ Rational

Returns the exact duration in seconds. A :Y / :M duration has no exact second count (a month / year is calendar-variable), so it raises rather than silently handing back a 30.5-day approximation -- use #to_seconds_approx when an estimate is acceptable. @raise [ArgumentError] for a :Y / :M unit.

Returns:

  • (Rational) —

    the exact duration in seconds. A :Y / :M duration has no exact second count (a month / year is calendar-variable), so it raises rather than silently handing back a 30.5-day approximation -- use #to_seconds_approx when an estimate is acceptable. @raise [ArgumentError] for a :Y / :M unit.



529
530
531
532
533
534
535
536
 
# File 'lib/carray/time.rb', line 529

def to_seconds
  unless CATimeUnitAlgebra::FIXED.key?(unit.base)
    raise ArgumentError,
          "CATimedelta #{unit} has no exact seconds (a :#{unit.base} is " \
          "calendar-variable); use to_seconds_approx for an estimate"
  end
  Rational(value) * unit.tick_ratio                    # exact seconds
end

#to_seconds_approx ⇒ Float

Returns an approximate duration in seconds, using nominal lengths (a month = 30.5 days, a year = 365.25 days). The name makes the approximation explicit at the call site.

Returns:

  • (Float) —

    an approximate duration in seconds, using nominal lengths (a month = 30.5 days, a year = 365.25 days). The name makes the approximation explicit at the call site.



541
542
543
 
# File 'lib/carray/time.rb', line 541

def to_seconds_approx
  value * unit.count * (UNIT_TO_SECONDS[unit.base] || 1)
end