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:



499
500
501
502
 
# File 'lib/carray/time.rb', line 499

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:



509
510
511
 
# File 'lib/carray/time.rb', line 509

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.



1247
1248
1249
1250
1251
1252
 
# File 'lib/carray/time.rb', line 1247

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.



1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
 
# File 'lib/carray/time.rb', line 1195

def +(other)
  case other
  when CATimedelta
    u = _finer_duration(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.



1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
 
# File 'lib/carray/time.rb', line 1215

def -(other)
  case other
  when CATimedelta
    u = _finer_duration(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:



1238
1239
1240
 
# File 'lib/carray/time.rb', line 1238

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.



1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
 
# File 'lib/carray/time.rb', line 1261

def /(other)
  case other
  when Integer then (parent / other).timedelta(unit: unit)
  when CATimedelta
    u = _finer_duration(other.unit)
    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:



1231
1232
1233
 
# File 'lib/carray/time.rb', line 1231

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:



1466
1467
1468
1469
1470
1471
1472
1473
 
# File 'lib/carray/time.rb', line 1466

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:



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

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

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

Returns the median duration on self's unit.

Returns:



1302
1303
1304
 
# File 'lib/carray/time.rb', line 1302

def median(*args, **opts)
  _lift_reduced(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:



1381
1382
1383
1384
 
# File 'lib/carray/time.rb', line 1381

def minmax(*args, **opts)
  lo, hi = parent.minmax(*args, **opts)
  [_lift_extremum(lo), _lift_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:



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

def percentile(*args, **opts)
  _lift_reduced(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:



1319
1320
1321
 
# File 'lib/carray/time.rb', line 1319

def quantile(*args, **opts)
  _lift_reduced(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.



1442
1443
1444
1445
1446
1447
1448
1449
 
# File 'lib/carray/time.rb', line 1442

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:



1328
1329
1330
 
# File 'lib/carray/time.rb', line 1328

def stddev(*args, **opts)
  _lift_reduced(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:



1336
1337
1338
 
# File 'lib/carray/time.rb', line 1336

def stddevp(*args, **opts)
  _lift_reduced(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:



1283
1284
1285
 
# File 'lib/carray/time.rb', line 1283

def sum(*args, **opts)
  _lift_reduced(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:



1166
1167
1168
 
# File 'lib/carray/time.rb', line 1166

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.



1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
 
# File 'lib/carray/time.rb', line 1414

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 a finer grid: a new CATimedelta whose storage is self's ticks widened into unit. Accepted only when self's tick is a whole multiple of unit's (:D -> :h, "1 hour" -> "10 minutes"), so no duration changes. A coarser target raises rather than truncating silently; a calendar / fixed-length pair raises because a month has no fixed length.

Parameters:

  • unit (Resolution, Symbol, String) —

    target resolution.

Returns:

Raises:

  • (ArgumentError) —

    when self's tick is not a whole multiple of unit's.

  • (RangeError) —

    when the widened ticks overflow int64.



1182
1183
1184
1185
1186
 
# File 'lib/carray/time.rb', line 1182

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

#variance(*) ⇒ Object

min / max ride the core reduce Face gate (ORDERABLE storage descent + output re-lift, see ext/mkkernel.rb face_gate: :relift); the inherited CArray#min / #max return the Element / CATimedelta shapes directly.

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) 


1365
1366
1367
 
# File 'lib/carray/time.rb', line 1365

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) 


1372
1373
1374
 
# File 'lib/carray/time.rb', line 1372

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