SyDEVS  v0.6.6
Multiscale Simulation and Systems Modeling Library
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
sydevs::time_point Class Reference

A data structure which represents a point in time as an arbitrary-precision multiple of its shortest time precision. More...

#include <time_point.h>

Public Member Functions

 time_point ()
 Constructs a zero time_point object. More...
 
 time_point (duration dt)
 Constructs a time_point object with the initial offset indicated by the duration argument. More...
 
 time_point (const time_point &)=default
 Copy constructor. More...
 
time_pointoperator= (const time_point &)=default
 Copy assignment. More...
 
 time_point (time_point &&)=default
 Move constructor. More...
 
time_pointoperator= (time_point &&)=default
 Move assignment. More...
 
 ~time_point ()=default
 Destructor. More...
 
int64 sign () const
 Returns the sign (+1 or -1) of the time_point object. More...
 
scale precision () const
 Returns the precision of the shortest non-zero digit. More...
 
int64 nscales () const
 Returns the length of the vector of digits. More...
 
int64 scale_digit (scale precision) const
 Returns the digit associated with the precision scale. More...
 
int64 scale_phase (scale precision) const
 Returns the single-scale offset from the left. More...
 
int64 epoch_phase (scale precision) const
 Returns the 5-scale (epoch) offset from the left. More...
 
time_pointadvance (duration rhs)
 Advances the time_point object by the specified duration. More...
 
time_pointoperator+= (duration rhs)
 Modifies the time_point object by adding the duration rhs. More...
 
time_pointoperator-= (duration rhs)
 Modifies the time_point object by subtracting the duration rhs. More...
 
const time_point operator+ (duration rhs) const
 Returns a new time_point with duration rhs added. More...
 
const time_point operator- (duration rhs) const
 Returns a new time_point with duration rhs subtracted. More...
 
const duration operator- (const time_point &rhs) const
 Calculates the exact difference between the time_point object and time_point rhs. More...
 
duration gap (const time_point &rhs) const
 Approximates the difference between the time_point object and time_point rhs. More...
 
bool operator== (const time_point &rhs) const
 Returns true if the time_point object equals rhs. More...
 
bool operator!= (const time_point &rhs) const
 Returns true if the time_point object does not equal rhs. More...
 
bool operator< (const time_point &rhs) const
 Returns true if the time_point object is less than rhs. More...
 
bool operator> (const time_point &rhs) const
 Returns true if the time_point object is greater than rhs. More...
 
bool operator<= (const time_point &rhs) const
 Returns true if the time_point object is at most rhs. More...
 
bool operator>= (const time_point &rhs) const
 Returns true if the time_point object is at least rhs. More...
 
bool operator== (duration rhs) const
 Returns true if the time_point object equals duration rhs. More...
 
bool operator!= (duration rhs) const
 Returns true if the time_point object does not equal duration rhs. More...
 
bool operator< (duration rhs) const
 Returns true if the time_point object is less than duration rhs. More...
 
bool operator> (duration rhs) const
 Returns true if the time_point object is greater than duration rhs. More...
 
bool operator<= (duration rhs) const
 Returns true if the time_point object is at most duration rhs. More...
 
bool operator>= (duration rhs) const
 Returns true if the time_point object is at least duration rhs. More...
 

Detailed Description

A data structure which represents a point in time as an arbitrary-precision multiple of its shortest time precision.

A time_point object represents a base-1000 duration of time, allowing for exact accumulation of finite durations with essentially no bounds on range or resolution. One either default constructs a zero time point, or constructs a time point based on an initial duration value offset. Thereafter, the time point is adjusted by adding or subtracting other durations. If these durations vary significantly in scale, the time point will grow in memory to accommodate their exact sum. Hence the main differences between duration values and time_point objects is that the former are more efficient but the latter are more precise.

Below is an example of time points in use.

auto tp = time_point();
tp += 5000388_ns;
tp += 1777_ps;
tp += 640_us;
tp -= 40109_ns;
tp -= 5_ms;
tp += 223_ps;

Internally, the time_point class stores information as a vector containing an 8-bit integer "digit" per necessary base-1000 scale value. This digit can be obtained with the scale_digit member function. The scale_phase function is similar, but gives the scale-specific quantity measured from the left (i.e. from negative infinity) rather than from zero. The precision function yields the shortest scale with a non-zero digit, while the longest sucb precision can be obtained by adding the result of nscales minus one.

Given two time_point objects, the difference between them can be obtained as a duration in one of two ways. The first is regular substraction, which yields the exact result if possible or otherwise an infinite value. The second way of obtaining a difference is the gap member function, which approximates the result if necessary. The result of gap is always accurate to one of its time precisions.

auto lhs = time_point() + 7_s + 3_ms + 5_us + 6_ns + 2_ps + 9_fs;
auto rhs = time_point() + 6_s
(lhs - rhs) == duration::inf(); // true
lhs.gap(rhs) == 1003005006002_ps; // true

Time also provide an alternative to the regular accumulation of duration values. The alternative is called "multiscale time advancement", and involves accumulation followed by truncation. The truncation is based on the time precision of the duration.

auto tp = time_point(72800444321_ns);
tp + 1150_ms; // result: time_point() + 73_s + 950_ms + 444_us + 321_ns
// (tp is not modified)
tp.advance(1150_ms); // result: time_point() + 73_s + 950_ms
// (microseconds and nanoseconds are truncated)
// (tp is modified)

Time points can be compared with other time points or with duration values, with duration values appearing on the left- or right-hand side.

A time_point object may be output or converted to a string using the operator<< overload.

Constructor & Destructor Documentation

sydevs::time_point::time_point ( )

Constructs a zero time_point object.

sydevs::time_point::time_point ( duration  dt)
explicit

Constructs a time_point object with the initial offset indicated by the duration argument.

The constructed time_point object represents the specified offset from time zero, which can then be modified using the += or -= operators or the advance member function.

Parameters
dtThe initial offset.
sydevs::time_point::time_point ( const time_point )
default

Copy constructor.

sydevs::time_point::time_point ( time_point &&  )
default

Move constructor.

sydevs::time_point::~time_point ( )
default

Destructor.

Member Function Documentation

time_point & sydevs::time_point::advance ( duration  rhs)

Advances the time_point object by the specified duration.

Adds the duration rhs to the time point, then truncates the result such that offsets of precisions shorter than rhs.precision are discarded.

Parameters
rhsThe duration to advance by.
Returns
A reference to the modified time_point object.
int64 sydevs::time_point::epoch_phase ( scale  precision) const

Returns the 5-scale (epoch) offset from the left.

duration sydevs::time_point::gap ( const time_point rhs) const

Approximates the difference between the time_point object and time_point rhs.

If a duration value lacks the precision required to represent the exact difference, then the result is rounded. The exact difference should be within one precision of the returned duration, in terms of the return value's time precision.

Parameters
rhsThe time point to subtract.
Returns
The approximate difference from rhs.
int64 sydevs::time_point::nscales ( ) const
inline

Returns the length of the vector of digits.

bool sydevs::time_point::operator!= ( const time_point rhs) const

Returns true if the time_point object does not equal rhs.

bool sydevs::time_point::operator!= ( duration  rhs) const

Returns true if the time_point object does not equal duration rhs.

const time_point sydevs::time_point::operator+ ( duration  rhs) const

Returns a new time_point with duration rhs added.

time_point & sydevs::time_point::operator+= ( duration  rhs)

Modifies the time_point object by adding the duration rhs.

const time_point sydevs::time_point::operator- ( duration  rhs) const

Returns a new time_point with duration rhs subtracted.

const duration sydevs::time_point::operator- ( const time_point rhs) const

Calculates the exact difference between the time_point object and time_point rhs.

If a duration value lacks the precision required to represent the exact difference, then the result is either positive infinity (if rhs is a lesser time point) or negative infinity (if rhs is greater).

Parameters
rhsThe time point to subtract.
Returns
The difference from rhs or an infinite duration.
time_point & sydevs::time_point::operator-= ( duration  rhs)

Modifies the time_point object by subtracting the duration rhs.

bool sydevs::time_point::operator< ( const time_point rhs) const

Returns true if the time_point object is less than rhs.

bool sydevs::time_point::operator< ( duration  rhs) const

Returns true if the time_point object is less than duration rhs.

bool sydevs::time_point::operator<= ( const time_point rhs) const

Returns true if the time_point object is at most rhs.

bool sydevs::time_point::operator<= ( duration  rhs) const

Returns true if the time_point object is at most duration rhs.

time_point& sydevs::time_point::operator= ( const time_point )
default

Copy assignment.

time_point& sydevs::time_point::operator= ( time_point &&  )
default

Move assignment.

bool sydevs::time_point::operator== ( const time_point rhs) const

Returns true if the time_point object equals rhs.

bool sydevs::time_point::operator== ( duration  rhs) const

Returns true if the time_point object equals duration rhs.

bool sydevs::time_point::operator> ( const time_point rhs) const

Returns true if the time_point object is greater than rhs.

bool sydevs::time_point::operator> ( duration  rhs) const

Returns true if the time_point object is greater than duration rhs.

bool sydevs::time_point::operator>= ( const time_point rhs) const

Returns true if the time_point object is at least rhs.

bool sydevs::time_point::operator>= ( duration  rhs) const

Returns true if the time_point object is at least duration rhs.

scale sydevs::time_point::precision ( ) const
inline

Returns the precision of the shortest non-zero digit.

int64 sydevs::time_point::scale_digit ( scale  precision) const

Returns the digit associated with the precision scale.

int64 sydevs::time_point::scale_phase ( scale  precision) const

Returns the single-scale offset from the left.

int64 sydevs::time_point::sign ( ) const
inline

Returns the sign (+1 or -1) of the time_point object.


The documentation for this class was generated from the following files: