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) 


690
691
692
693
 
# File 'lib/carray/time.rb', line 690

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:



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

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

#-(other) ⇒ CATimedelta::Element

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

Parameters:

Returns:



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

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

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

By an Integer -> a scaled CATimedelta::Element, the quotient truncated toward zero (a duration is a magnitude, so it shrinks toward zero -- the same direction CATimedelta#/ and #to_unit take, not Ruby Integer division's floor); by another CATimedelta::Element -> their dimensionless ratio as a Rational (both brought to the finer unit; cross-group raises).

Parameters:

Returns:



704
705
706
707
708
709
710
711
712
713
 
# File 'lib/carray/time.rb', line 704

def /(other)
  case other
  when Integer then Element.new(Rational(value, other).truncate, unit)
  when Element
    u = CATimeUnitAlgebra.finer(unit, other.unit)
    Rational(duration_in(u), other.duration_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.



654
655
656
657
658
659
660
661
 
# File 'lib/carray/time.rb', line 654

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

#eql?(other) ⇒ Boolean

Returns:

  • (Boolean) 


663
664
665
 
# File 'lib/carray/time.rb', line 663

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).



668
669
670
 
# File 'lib/carray/time.rb', line 668

def hash
  [value, unit].hash
end

#inspect ⇒ String

Returns:

  • (String) 


646
647
648
 
# File 'lib/carray/time.rb', line 646

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.



641
642
643
 
# File 'lib/carray/time.rb', line 641

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.



624
625
626
627
628
629
630
631
 
# File 'lib/carray/time.rb', line 624

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.



636
637
638
 
# File 'lib/carray/time.rb', line 636

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