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_point &	operator= (const time_point &)=default
	Copy assignment. More...
	time_point (time_point &&)=default
	Move constructor. More...
time_point &	operator= (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_point &	advance (duration rhs)
	Advances the time_point object by the specified duration. More...
time_point &	operator+= (duration rhs)
	Modifies the time_point object by adding the duration rhs. More...
time_point &	operator-= (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

time_point() [1/4]

sydevs::time_point::time_point

(

)

Constructs a zero time_point object.

time_point() [2/4]

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

dt	The initial offset.

time_point() [3/4]

sydevs::time_point::time_point ( const time_point &  )

default

Copy constructor.

time_point() [4/4]

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

default

Move constructor.

~time_point()

sydevs::time_point::~time_point ( )

default

Destructor.

Member Function Documentation

advance()

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

rhs	The duration to advance by.

Returns

A reference to the modified time_point object.

epoch_phase()

int64 sydevs::time_point::epoch_phase

(

scale

precision

)

const

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

gap()

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

rhs	The time point to subtract.

Returns

The approximate difference from rhs.

nscales()

int64 sydevs::time_point::nscales ( ) const

inline

Returns the length of the vector of digits.

operator!=() [1/2]

bool sydevs::time_point::operator!=

(

const time_point &

rhs

)

const

Returns true if the time_point object does not equal rhs.

operator!=() [2/2]

bool sydevs::time_point::operator!=

(

duration

rhs

)

const

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

operator+()

const time_point sydevs::time_point::operator+

(

duration

rhs

)

const

Returns a new time_point with duration rhs added.

operator+=()

time_point & sydevs::time_point::operator+=

(

duration

rhs

)

Modifies the time_point object by adding the duration rhs.

operator-() [1/2]

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

rhs	The time point to subtract.

Returns

The difference from rhs or an infinite duration.

operator-() [2/2]

const time_point sydevs::time_point::operator-

(

duration

rhs

)

const

Returns a new time_point with duration rhs subtracted.

operator-=()

time_point & sydevs::time_point::operator-=

(

duration

rhs

)

Modifies the time_point object by subtracting the duration rhs.

operator<() [1/2]

bool sydevs::time_point::operator<

(

const time_point &

rhs

)

const

Returns true if the time_point object is less than rhs.

operator<() [2/2]

bool sydevs::time_point::operator<

(

duration

rhs

)

const

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

operator<=() [1/2]

bool sydevs::time_point::operator<=

(

const time_point &

rhs

)

const

Returns true if the time_point object is at most rhs.

operator<=() [2/2]

bool sydevs::time_point::operator<=

(

duration

rhs

)

const

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

operator=() [1/2]

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

default

Copy assignment.

operator=() [2/2]

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

default

Move assignment.

operator==() [1/2]

bool sydevs::time_point::operator==

(

const time_point &

rhs

)

const

Returns true if the time_point object equals rhs.

operator==() [2/2]

bool sydevs::time_point::operator==

(

duration

rhs

)

const

Returns true if the time_point object equals duration rhs.

operator>() [1/2]

bool sydevs::time_point::operator>

(

const time_point &

rhs

)

const

Returns true if the time_point object is greater than rhs.

operator>() [2/2]

bool sydevs::time_point::operator>

(

duration

rhs

)

const

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

operator>=() [1/2]

bool sydevs::time_point::operator>=

(

const time_point &

rhs

)

const

Returns true if the time_point object is at least rhs.

operator>=() [2/2]

bool sydevs::time_point::operator>=

(

duration

rhs

)

const

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

precision()

scale sydevs::time_point::precision ( ) const

inline

Returns the precision of the shortest non-zero digit.

scale_digit()

int64 sydevs::time_point::scale_digit

(

scale

precision

)

const

Returns the digit associated with the precision scale.

scale_phase()

int64 sydevs::time_point::scale_phase

(

scale

precision

)

const

Returns the single-scale offset from the left.

sign()

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:

• src/sydevs/time/time_point.h
• src/sydevs/time/time_point.cpp