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:



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

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:



604
605
606
 
# File 'lib/carray/time.rb', line 604

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.



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

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.



1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
 
# File 'lib/carray/time.rb', line 1307

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.



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

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:



1350
1351
1352
 
# File 'lib/carray/time.rb', line 1350

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.



1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
 
# File 'lib/carray/time.rb', line 1373

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:



1343
1344
1345
 
# File 'lib/carray/time.rb', line 1343

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:



1573
1574
1575
1576
1577
1578
1579
1580
 
# File 'lib/carray/time.rb', line 1573

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:



1404
1405
1406
 
# File 'lib/carray/time.rb', line 1404

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:



1416
1417
1418
 
# File 'lib/carray/time.rb', line 1416

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:



1488
1489
1490
1491
 
# File 'lib/carray/time.rb', line 1488

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:



1425
1426
1427
 
# File 'lib/carray/time.rb', line 1425

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:



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

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.



1549
1550
1551
1552
1553
1554
1555
1556
 
# File 'lib/carray/time.rb', line 1549

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:



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

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:



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

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:



1397
1398
1399
 
# File 'lib/carray/time.rb', line 1397

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:



1274
1275
1276
 
# File 'lib/carray/time.rb', line 1274

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.



1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
 
# File 'lib/carray/time.rb', line 1521

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.



1295
1296
1297
1298
 
# File 'lib/carray/time.rb', line 1295

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) 


1469
1470
1471
 
# File 'lib/carray/time.rb', line 1469

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) 


1476
1477
1478
 
# File 'lib/carray/time.rb', line 1476

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