class

Quartz::TimePoint

Inherits Comparable / Reference / Object

The TimePoint data type represents points in simulated time, and is intended to be used internally.

Its main purpose is to describe event times as offsets from a common reference point. It may be perturbed by a Duration value.

It is implemented as an arbitrary-precision integer, and provides only relevant methods.

The modeller should only manipulate Duration values.

TODO:

handle sign.
one zero representation.
make immutable
transform mod operations by bit masking (e.g. (n & (BASE-1)))

Constructors

new(n : Int = 0, precision : Scale = Scale::BASE)

Creates a new TimePoint value, initialized at the given precision from the given integer n, which may or not be zero.

new(magnitude : Array(Int16), precision : Scale)

Creates a new TimePoint, whose value depends on the given *magnitude, initialized at the given precision.

The magnitude must be ordered and organized from the least-significant number to the least-signifiant number.

new(*numbers : Int, precision : Scale = Scale::BASE)

Creates a new TimePoint, whose value is given by numbers, initialized at the given precision.

The numbers must be ordered and organized from the most-significant number to the least-significant number.

Instance methods

+(duration : Duration) : TimePoint

Returns a new TimePoint to which the given Duration is added.

Doesn't truncate result to the duration precision.

-(duration : Duration) : TimePoint

Returns a new TimePoint to which the given Duration is subtracted.

Doesn't truncate result to the duration precision.

-(other : TimePoint) : Duration

Measure the difference between self and another instance of self. The difference is expressed by a Duration value.

If the exact difference between the time points cannot be represented, an infinite Duration is returned.

See also #gap.

<=>(other : TimePoint)

Comparison operator

[](scale : Scale) : Int16

Returns the integer corresponding to the indicated precision, or zero if not in bounds.

[](i : Int) : Int16

Returns the integer at the corresponding index following the little-endian representation (0 is the least significant).

Raises if the given index is not in bounds.

[]?(scale : Scale) : Int16 | Nil

Returns the integer corresponding to the indicated precision, or nil.

[]?(i : Int) : Int16 | Nil

Returns the integer at the corresponding index following the little-endian representation (0 is the least significant).

Returns nil if given index is not in bounds.

advance(by duration : Duration, truncate : Bool = true) : TimePoint

Multiscale advancement - Adds the given Duration to self.

If the advancement duration is zero, returns self. Advances according to the duration value otherwise.

If the truncate parameter is set to true, the time point is truncated at the precision level of the duration (e.g. all digits less significant are discarded). Otherwise, yields exact results.

See also #+, #-.

at(scale : Scale, &)

Returns the element at the given precision, if in bounds, otherwise executes the given block and returns its value.

at(index : Int, &block : -> Int16)

Returns the element at the given index, if in bounds, otherwise executes the given block and returns its value.

clone

Returns a copy of self with all instance variables cloned.

coarse_to!(precision : Scale)

Discards all digits less significant than given precision.

dup

Returns a shallow copy of self.

duration_from_phase(phase : Duration) : Duration

Converts a planned phase (offset from the current epoch) to a planned duration relative to self.

epoch_phase(precision : Scale) : Int64

Returns the epoch phase, which represents the number of time quanta which separates self from the beginning of the current epoch.

gap(other : TimePoint) : Duration

Measure the difference between self and another instance of self. The difference is expressed by a Duration value.

If the exact difference between the time points cannot be represented, an approximation is returned.

See also #-.

phase_from_duration(duration : Duration) : Duration

Converts a planned duration to a planned phase.

The planned phase represents an offset from the current epoch relative to self.

precision

Returns the precision associated with the least significant number.

refined_duration(duration : Duration, refined : Scale) : Duration

Refines a planned Duration to match another planned duration precision, relative to self.

Note: The implementation diverge from the paper algoithm.

size

Returns the order of magnitude of self, based on its #precision and the number of stored integers on a base-1000 scale.

to_big_i

Convert this TimePoint to a BigInt.

to_f

Convert self to a Float64. Express values in a base precision, e.g. Scale::BASE.

Note: this conversion can lose information about the overall magnitude of self.

to_i

to_i32

Convert this TimePoint to an Int32.

Note: this conversion can lose information about the overall magnitude of self as well as return a result with the opposite sign.

to_i64

Convert this TimePoint to an Int64. Express values relative to its #precision.

Note: this conversion can lose information about the overall magnitude of self as well as return a result with the opposite sign.

to_s(io)

zero?

Whether self is a zero time point value.