Class: CATimedelta

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

Overview

============================================================================

Ruby surface operators (CATimedelta)

Defined Under Namespace

Classes: Element

Reductions collapse

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.new(*shape, unit: :ns) ⇒ CATimedelta

Allocates a new int64 storage CArray of the given shape and wraps it as a CATimedelta Face with the given unit.

Parameters:

  • shape (Array<Integer>) —

    shape of the new CATimedelta.

  • unit (Symbol) (defaults to: :ns) —

    duration unit.

Returns:



611
612
613
614
 
# File 'lib/carray/time.rb', line 611

def self.new(*shape, unit: :ns)
  raw = CArray.int64(*shape)
  wrap(raw, unit: unit)
end

.wrap(raw, unit: :ns) ⇒ CATimedelta

Zero-copy Face wrap of an existing int64 CArray as a duration.

Parameters:

Returns:



621
622
623
 
# File 'lib/carray/time.rb', line 621

def self.wrap(raw, unit: :ns)
  __wrap__(raw, unit)
end

Instance Method Details

#*(other) ⇒ CATimedelta

Returns self scaled by an Integer.

Parameters:

  • other (Integer)

Returns:

Raises:

  • (TypeError) —

    when other is not an Integer.



1376
1377
1378
1379
1380
1381
 
# File 'lib/carray/time.rb', line 1376

def *(other)
  case other
  when Integer then (parent * other).timedelta(unit: unit)
  else raise TypeError, "CATimedelta * #{other.class} is not allowed (Integer only)"
  end
end

#+(other) ⇒ CATimedelta, CATime

Returns self + other. A CATimedelta operand yields a CATimedelta; a CATime operand delegates to CATime#+ (commutative).

Parameters:

Returns:

Raises:

  • (TypeError) —

    on incompatible operands.



1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
 
# File 'lib/carray/time.rb', line 1324

def +(other)
  case other
  when CATimedelta
    u = common_duration_unit(other.unit)
    a = CATimeUnitAlgebra.convert_scale!(parent, unit, u)
    b = CATimeUnitAlgebra.convert_scale!(other.parent, other.unit, u)
    (a + b).timedelta(unit: u)
  when CATime
    other + self  # commutative -> time's unit
  else
    raise TypeError, "CATimedelta + #{other.class} is not allowed"
  end
end

#-(other) ⇒ CATimedelta

Returns the difference of two CATimedelta at the finer of the two units (a cross-group pair raises).

Parameters:

Returns:

Raises:

  • (TypeError) —

    on a non-timedelta operand.



1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
 
# File 'lib/carray/time.rb', line 1344

def -(other)
  case other
  when CATimedelta
    u = common_duration_unit(other.unit)
    a = CATimeUnitAlgebra.convert_scale!(parent, unit, u)
    b = CATimeUnitAlgebra.convert_scale!(other.parent, other.unit, u)
    (a - b).timedelta(unit: u)
  else
    raise TypeError, "CATimedelta - #{other.class} is not allowed"
  end
end

#-@ ⇒ CATimedelta

Returns each duration with its sign reversed, on the same unit.

Returns:



1367
1368
1369
 
# File 'lib/carray/time.rb', line 1367

def -@
  (-parent).timedelta(unit: unit)
end

#/(other) ⇒ CATimedelta, CArray

Returns element-wise division: by Integer yields a CATimedelta, by another CATimedelta with matching unit yields a dimensionless CArray.

Parameters:

Returns:

Raises:

  • (TypeError) —

    on incompatible operands.



1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
 
# File 'lib/carray/time.rb', line 1390

def /(other)
  case other
  when Integer
    CATimeUnitAlgebra.trunc_divide(parent, other).timedelta(unit: unit)
  when CATimedelta
    u = common_duration_unit(other.unit)
    CATimeUnitAlgebra.trunc_divide(
      CATimeUnitAlgebra.convert_scale!(parent, unit, u),
      CATimeUnitAlgebra.convert_scale!(other.parent, other.unit, u))
  else raise TypeError, "CATimedelta / #{other.class} is not allowed"
  end
end

#abs ⇒ CATimedelta

Returns the magnitude of each duration as a CATimedelta on the same unit.

Returns:



1360
1361
1362
 
# File 'lib/carray/time.rb', line 1360

def abs
  parent.abs.timedelta(unit: unit)
end

#linear_fetch(addr, axis: nil) ⇒ Element, CATimedelta

Returns the duration at the fractional position addr on this array's grid, interpolating between the two bracketing durations. Keeps self's unit and rounds to it (widen the grid with #to_unit first when the interpolation needs finer resolution), which matches #mean / #sum -- a duration reduction stays on the grid too. An out-of-range addr yields UNDEF; see CATime#linear_fetch for the full contract.

Parameters:

  • addr (Float, CArray) —

    fractional position(s) into self.

  • axis (Integer, nil) (defaults to: nil)

Returns:



1590
1591
1592
1593
1594
1595
1596
1597
 
# File 'lib/carray/time.rb', line 1590

def linear_fetch (addr, **opts)
  r = parent.float64.linear_fetch(addr, **opts)
  case r
  when CArray  then r.mask_invalid.round.int64.timedelta(unit: unit)
  when Numeric then r.to_f.nan? ? nil : Element.new(r.round, unit)
  else r
  end
end

#mean(axis: nil, **opts) ⇒ Element, CATimedelta

Returns the mean duration rounded to the nearest unit count.

Returns:



1421
1422
1423
 
# File 'lib/carray/time.rb', line 1421

def mean(*args, **opts)
  round_and_relift(parent.mean(*args, **opts))
end

#median(axis: nil, **opts) ⇒ Element, CATimedelta

Returns the median duration on self's unit.

Returns:



1433
1434
1435
 
# File 'lib/carray/time.rb', line 1433

def median(*args, **opts)
  round_and_relift(parent.median(*args, **opts))
end

#minmax(*axes, **opts) ⇒ Array(Element, Element), Array(CATimedelta, CATimedelta)

Returns the shortest and longest duration as a [min, max] pair.

Returns:



1505
1506
1507
1508
 
# File 'lib/carray/time.rb', line 1505

def minmax(*args, **opts)
  lo, hi = parent.minmax(*args, **opts)
  [relift_extremum(lo), relift_extremum(hi)]
end

#percentile(*p, axis: nil, **opts) ⇒ Element, ...

Returns the percentile durations on self's unit, in the shapes the plain CArray#percentile uses (one p reduces to a single value, two or more give an Array).

Returns:



1442
1443
1444
 
# File 'lib/carray/time.rb', line 1442

def percentile(*args, **opts)
  round_and_relift(parent.percentile(*args, **opts))
end

#quantile(axis: nil, **opts) ⇒ Array<Element>, Array<CATimedelta>

Returns the five quartile durations [p0, p25, p50, p75, p100] on self's unit.

Returns:



1450
1451
1452
 
# File 'lib/carray/time.rb', line 1450

def quantile(*args, **opts)
  round_and_relift(parent.quantile(*args, **opts))
end

#scalar_to_storage(surface) ⇒ Integer, Object

Write-direction counterpart of storage_to_scalar: brings a surface value object into this Face's int64 storage (count in self's unit) so a scalar store round-trips with a fetch. A Element is reconciled to self's unit via #to_comparable (lossless discipline; a Time / DateTime is an absolute instant, not a duration, so it raises there). A bare Integer (the .parent raw-storage escape) and a String pass through unchanged.

Parameters:

  • surface (Element, Integer, String)

Returns:

  • (Integer, Object) —

    the storage-domain value, or surface unchanged for a pass-through type.

Raises:

  • (TypeError, ArgumentError) —

    on an unreconcilable surface / unit.



1566
1567
1568
1569
1570
1571
1572
1573
 
# File 'lib/carray/time.rb', line 1566

def scalar_to_storage (surface)
  case surface
  when Integer, String
    surface
  else
    to_comparable(surface).parent[0]
  end
end

#stddev(axis: nil, **opts) ⇒ Element, CATimedelta

Returns the spread of the durations on self's unit. A spread is not a lattice point, so on a coarse unit use td.to_unit(:h).stddev when the precision matters.

Returns:



1459
1460
1461
 
# File 'lib/carray/time.rb', line 1459

def stddev(*args, **opts)
  round_and_relift(parent.stddev(*args, **opts))
end

#stddevp(axis: nil, **opts) ⇒ Element, CATimedelta

Returns the population spread on self's unit, in the same shapes as #stddev.

Returns:



1467
1468
1469
 
# File 'lib/carray/time.rb', line 1467

def stddevp(*args, **opts)
  round_and_relift(parent.stddevp(*args, **opts))
end

#sum(*args, **opts) ⇒ Element, CATimedelta

Returns the sum of durations as a Element for full reduction or as a CATimedelta view for per-axis reduction.

Returns:



1414
1415
1416
 
# File 'lib/carray/time.rb', line 1414

def sum(*args, **opts)
  round_and_relift(parent.sum(*args, **opts))
end

#ticks ⇒ CArray

Returns the underlying int64 CArray of tick counts — the duration measured in this array's resolution (see CATime#ticks).

Returns:



1291
1292
1293
 
# File 'lib/carray/time.rb', line 1291

def ticks
  parent
end

#to_comparable(operand) ⇒ CATimedelta

Brings operand into self's unit space for a direct storage comparison (see CATime#to_comparable for the reference-side contract). self is the reference Face and class-dispatches the operand. Coverage is deliberately narrower than CATime: only another CATimedelta (unit-rescaled to self) and a Element (lifted to a length-1 CATimedelta) are accepted. Time / DateTime are absolute instants, not durations, so they raise -- a Face owns its own coverage. Auto-casts to self's unit when lossless (coarser->finer always; finer->coarser only when every value is exact), otherwise raises.

Parameters:

Returns:

Raises:

  • (TypeError, ArgumentError) —

    on an unreconcilable operand / unit.



1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
 
# File 'lib/carray/time.rb', line 1538

def to_comparable (operand)
  case operand
  when CATimedelta
    return operand if operand.unit == unit
    CATimeUnitAlgebra.convert_scale!(operand.parent, operand.unit, unit)
                         .timedelta(unit: unit)
  when CATimedelta::Element
    lifted = CATimedelta.wrap(CA_INT64([operand.value]), unit: operand.unit)
    to_comparable(lifted)
  else
    raise TypeError,
          "CATimedelta cannot reconcile #{operand.class} " \
          "(use ca.parent to compare the raw int64 storage directly)"
  end
end

#to_unit(unit) ⇒ CATimedelta

Returns the same durations re-expressed on the unit grid: a new CATimedelta whose storage resolution is unit. A finer target is exact (:D -> :h); a coarser one drops the sub-unit remainder toward zero (+30 h -> +1 D, -30 h -> -1 D), the same truncation dt + td already applies.

The direction differs from CATime#to_unit on purpose: a time is a point on an axis, so it floors toward the past; a duration is a magnitude, so it shrinks toward zero.

A calendar / fixed-length pair always raises -- unlike an instant, a duration of one month has no length in days.

Parameters:

  • unit (Resolution, Symbol, String) —

    target resolution.

Returns:

Raises:

  • (ArgumentError) —

    on a calendar / fixed-length pair.

  • (RangeError) —

    when the widened ticks overflow int64.



1312
1313
1314
1315
 
# File 'lib/carray/time.rb', line 1312

def to_unit(unit)
  to = CATime::Resolution.parse(unit)
  CATimeUnitAlgebra.convert_scale_trunc(parent, self.unit, to).timedelta(unit: to)
end

#variance(*) ⇒ Object

Not supported: the variance of durations has squared-time units, which no type represents -- the same reason CATime#variance refuses. Use #stddev for the spread as a duration.

Raises:

  • (TypeError) —

    always.

Raises:

  • (TypeError) 


1486
1487
1488
 
# File 'lib/carray/time.rb', line 1486

def variance(*)
  raise TypeError, "CATimedelta#variance is ill-defined (squared-time units); use stddev"
end

#variancep(*) ⇒ Object

Not supported, for the same reason as #variance. Use #stddevp.

Raises:

  • (TypeError) —

    always.

Raises:

  • (TypeError) 


1493
1494
1495
 
# File 'lib/carray/time.rb', line 1493

def variancep(*)
  raise TypeError, "CATimedelta#variancep is ill-defined (squared-time units); use stddevp"
end