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

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

dt	The 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

rhs	The 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

rhs	The 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

rhs	The 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:

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

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation