Timespec structure using int64_t for its components in analogy to struct timespec_t on 64-bit platforms. More...

#include <fraction_type.hpp>

Collaboration diagram for jau::fraction_timespec:

Public Member Functions
constexpr	fraction_timespec () noexcept
	Constructs a zero fraction_timespec instance.

constexpr	fraction_timespec (const double seconds) noexcept
	Constructs a fraction_timespec instance with given floating point seconds, normalized.

constexpr	fraction_timespec (const fraction_i64 &r, bool *overflow_ptr=nullptr) noexcept
	Conversion constructor of fraction_timespec for a fraction_i64 value.

constexpr	fraction_timespec (const int64_t s, const int64_t ns) noexcept
	Constructs a fraction_timespec instance with given components, normalized.

constexpr void	clear () noexcept

constexpr bool	isZero () noexcept

constexpr fraction_timespec &	normalize () noexcept
	Normalize tv_nsec with its absolute range [0..1'000'000'000[ or [0..1'000'000'000) and having same sign as tv_sec.

constexpr fraction_timespec &	operator*= (const int64_t rhs) noexcept
	Compound product (multiplication)

constexpr fraction_timespec &	operator+= (const fraction_timespec &rhs) noexcept
	Compound assignment (addition)

constexpr fraction_timespec &	operator-= (const fraction_timespec &rhs) noexcept
	Negative compound assignment (subtraction)

constexpr fraction_timespec &	operator/= (const int64_t rhs) noexcept
	Compound fraction (division)

constexpr std::strong_ordering	operator<=> (const fraction_timespec &rhs) const noexcept
	Three way std::strong_ordering comparison operator.

constexpr bool	operator== (const fraction_timespec &rhs) const noexcept
	Two way comparison operator.

constexpr double	to_double () const noexcept
	Returns time in fractions of seconds of type double.

constexpr fraction_i64	to_fraction_i64 () const noexcept
	Returns the sum of both components.

std::string	to_iso8601_string (bool space_separator=false, bool muteTime=false) const noexcept
	Convenience string conversion interpreted since Unix Epoch in UTC to ISO 8601 `YYYY-mm-ddTHH:MM:SS.ssZ`, e.g.

constexpr uint64_t	to_ms () const noexcept
	Returns time in milliseconds.

std::string	to_string () const noexcept
	Return simple string representation in seconds and nanoseconds.

constexpr struct timespec	to_timespec () const noexcept
	Return conversion to POSIX `struct timespec`, potentially narrowing the components if underlying system is not using 64-bit signed integer.

constexpr uint64_t	to_us () const noexcept
	Returns time in microseconds.

Static Public Member Functions
static fraction_timespec	from (const std::string_view datestr, Bool addUTCOffset=Bool::False) noexcept
	Conversion constructor from an ISO8601 time string, as produced via to_iso8601_string().

static fraction_timespec	from (const std::string_view datestr, int64_t &utcOffsetSec, size_t &consumedChars) noexcept
	Conversion constructor from an ISO8601 time string, as produced via to_iso8601_string().

static fraction_timespec	from (int year, unsigned month, unsigned day, unsigned hour=0, unsigned minute=0, unsigned seconds=0, uint64_t nano_seconds=0) noexcept
	Conversion constructor from broken down values assuming UTC.

Public Attributes
int64_t	tv_nsec
	Nanoseconds component with its absolute value in range [0..1'000'000'000[ or [0..1'000'000'000).

int64_t	tv_sec
	Seconds component, with its absolute value in range [0..inf[ or [0..inf).

Detailed Description

Timespec structure using int64_t for its components in analogy to struct timespec_t on 64-bit platforms.

fraction_timespec covers an almost infinite range of time while maintaining high precision like struct timespec_t on 64-bit platforms.

If used as an absolute time-point, zero is time since Unix Epoch 00:00:00 UTC on 1970-01-01.

Note-1: Counting nanoseconds in int64_t only lasts until 2262-04-12, since INT64_MAX is 9'223'372'036'854'775'807 for 9'223'372'036 seconds or 292 years.

Note-2: Limitations of struct timespec on 32-bit platforms

to_timespec() conversion to struct timespec
32-bit signed integer only last for 68 years or until year 2038, starting from 1970 Unix Epoch
System call conversion for year 2038
test/test_fractions_01.cpp struct timespec type validation Test 03.00

See also: to_timespec(); to_fraction_i64(); sleep_until(); sleep_for(); wait_until(); wait_for(); getMonotonicTime(); getWallClockTime()

Definition at line 867 of file fraction_type.hpp.

Constructor & Destructor Documentation

◆ fraction_timespec() [1/4]

jau::fraction_timespec::fraction_timespec ( )

inlineconstexprnoexcept

Constructs a zero fraction_timespec instance.

Definition at line 881 of file fraction_type.hpp.

Here is the caller graph for this function:

◆ fraction_timespec() [2/4]

jau::fraction_timespec::fraction_timespec	(	const int64_t	s,
		const int64_t	ns )

inlineconstexprnoexcept

Constructs a fraction_timespec instance with given components, normalized.

Definition at line 887 of file fraction_type.hpp.

◆ fraction_timespec() [3/4]

jau::fraction_timespec::fraction_timespec ( const double seconds )

inlineexplicitconstexprnoexcept

Constructs a fraction_timespec instance with given floating point seconds, normalized.

Definition at line 893 of file fraction_type.hpp.

◆ fraction_timespec() [4/4]

jau::fraction_timespec::fraction_timespec	(	const fraction_i64 &	r,
		bool *	overflow_ptr = nullptr )

inlineconstexprnoexcept

Conversion constructor of fraction_timespec for a fraction_i64 value.

If overflow_ptr is not nullptr, true is stored if an overflow occurred, otherwise false.

In case of an overflow, tv_sec and tv_nsec will also be set to INT64_MAX

Example without overflow check and implicit fraction_i64 conversion to fraction_timespec:

 fraction_i64 duration = 10_ms;
 const fraction_timespec timeout_time = getMonotonicTime() + duration;

Example with overflow check for potential durations > 292 years and explicit fraction_i64 conversion to fraction_timespec:

 fraction_i64 duration = 10_ms;
 bool overflow = false;
 const fraction_timespec timeout_time = getMonotonicTime() + fraction_timespec(duration, &overflow);
 if( overflow ) {
     return; // bail out
 }

Parameters

r	the conversion input
overflow_ptr	optional pointer to overflow result, defaults to nullptr

Definition at line 922 of file fraction_type.hpp.

Member Function Documentation

◆ from() [1/3]

fraction_timespec fraction_timespec::from	(	const std::string_view	datestr,
		int64_t &	utcOffsetSec,
		size_t &	consumedChars )

staticnoexcept

Conversion constructor from an ISO8601 time string, as produced via to_iso8601_string().

Implementation allows having space instead of specified delimiters like T and Z.

Parameters

datestr	the ISO8601 time string to parse
utcOffsetSec	storage for UTC offset in seconds
consumedChars	number of consumed chars successfully parsed
returns	the fraction_timespec in UTC

Definition at line 179 of file basic_types.cpp.

Here is the caller graph for this function:

◆ from() [2/3]

fraction_timespec fraction_timespec::from	(	const std::string_view	datestr,
		Bool	addUTCOffset = Bool::False )

staticnoexcept

Conversion constructor from an ISO8601 time string, as produced via to_iso8601_string().

Implementation allows having space instead of specified delimiters like T and Z.

Parameters

datestr	the ISO8601 time string to parse
addUTCOffset	if true, add UTC offset to the resulting time, otherwise return UTC only

Definition at line 168 of file basic_types.cpp.

◆ from() [3/3]

fraction_timespec fraction_timespec::from	(	int	year,
		unsigned	month,
		unsigned	day,
		unsigned	hour = 0,
		unsigned	minute = 0,
		unsigned	seconds = 0,
		uint64_t	nano_seconds = 0 )

staticnoexcept

Conversion constructor from broken down values assuming UTC.

Parameters

year	year number, 0 as 0 A.D.
month	month number [1-12]
day	day of the month [1-31]
hour	hours since midnight [0-23]
minute	minutes after the hour [0-59]
seconds	seconds after the minute including one leap second [0-60]
nano_seconds	nanoseconds [0, 1'000'000'000)

Definition at line 144 of file basic_types.cpp.

◆ to_fraction_i64()

fraction_i64 jau::fraction_timespec::to_fraction_i64 ( ) const

inlineconstexprnoexcept

Returns the sum of both components.

If applied to relative duration, i.e. difference of two time points, its range is good for 292 years and exceeds that of an int64_t nanoseconds timepoint-difference greatly.

  fraction_timespec t0 = getMonotonicTime();
  // do something

  // Exact duration
  fraction_timespec td_1 = getMonotonicTime() - t0;

  // or for durations <= 292 years
  fraction_i64 td_2 = (getMonotonicTime() - t0).to_fraction_i64();

See also: getMonotonicTime()

Definition at line 996 of file fraction_type.hpp.

Here is the caller graph for this function:

◆ normalize()

fraction_timespec & jau::fraction_timespec::normalize ( )

inlineconstexprnoexcept

Normalize tv_nsec with its absolute range [0..1'000'000'000[ or [0..1'000'000'000) and having same sign as tv_sec.

Used after arithmetic operations.

Returns: reference to this instance

Definition at line 1008 of file fraction_type.hpp.

Here is the caller graph for this function:

◆ isZero()

bool jau::fraction_timespec::isZero ( )

inlineconstexprnoexcept

Definition at line 1027 of file fraction_type.hpp.

Here is the caller graph for this function:

◆ clear()

void jau::fraction_timespec::clear ( )

inlineconstexprnoexcept

Definition at line 1028 of file fraction_type.hpp.

◆ operator==()

bool jau::fraction_timespec::operator== ( const fraction_timespec & rhs ) const

inlineconstexprnoexcept

Two way comparison operator.

Definition at line 1031 of file fraction_type.hpp.

◆ operator<=>()

std::strong_ordering jau::fraction_timespec::operator<=> ( const fraction_timespec & rhs ) const

inlineconstexprnoexcept

Three way std::strong_ordering comparison operator.

Definition at line 1036 of file fraction_type.hpp.

◆ operator+=()

fraction_timespec & jau::fraction_timespec::operator+= ( const fraction_timespec & rhs )

inlineconstexprnoexcept

Compound assignment (addition)

Parameters

rhs	the other fraction_timespec

Returns: reference to this instance, normalized

Definition at line 1051 of file fraction_type.hpp.

◆ operator-=()

fraction_timespec & jau::fraction_timespec::operator-= ( const fraction_timespec & rhs )

inlineconstexprnoexcept

Negative compound assignment (subtraction)

Parameters

rhs	the other fraction_timespec

Returns: reference to this instance, normalized

Definition at line 1063 of file fraction_type.hpp.

◆ operator*=()

fraction_timespec & jau::fraction_timespec::operator*= ( const int64_t rhs )

inlineconstexprnoexcept

Compound product (multiplication)

Parameters

rhs a scalar

Returns: reference to this instance, normalized

Definition at line 1075 of file fraction_type.hpp.

◆ operator/=()

fraction_timespec & jau::fraction_timespec::operator/= ( const int64_t rhs )

inlineconstexprnoexcept

Compound fraction (division)

Parameters

rhs a scalar

Returns: reference to this instance, normalized

Definition at line 1087 of file fraction_type.hpp.

◆ to_timespec()

struct timespec jau::fraction_timespec::to_timespec ( ) const

inlinenoexcept

Return conversion to POSIX struct timespec, potentially narrowing the components if underlying system is not using 64-bit signed integer.

Note-2: Limitations of struct timespec on 32-bit platforms

32-bit signed integer only last for 68 years or until year 2038, starting from 1970 Unix Epoch
System call conversion for year 2038
test/test_fractions_01.cpp struct timespec type validation Test 03.00

Definition at line 1112 of file fraction_type.hpp.

Here is the caller graph for this function:

◆ to_ms()

uint64_t jau::fraction_timespec::to_ms ( ) const

inlineconstexprnoexcept

Returns time in milliseconds.

If either tv_sec or tv_nsec is negative, method return 0.

In case of overflow tv_sec >= UINT64_MAX / 1'000, method returns UINT64_MAX.

Definition at line 1124 of file fraction_type.hpp.

◆ to_us()

uint64_t jau::fraction_timespec::to_us ( ) const

inlineconstexprnoexcept

Returns time in microseconds.

If either tv_sec or tv_nsec is negative, method return 0.

In case of overflow tv_sec >= UINT64_MAX / 1'000'000, method returns UINT64_MAX.

Definition at line 1141 of file fraction_type.hpp.

◆ to_double()

double jau::fraction_timespec::to_double ( ) const

inlineconstexprnoexcept

Returns time in fractions of seconds of type double.

Definition at line 1152 of file fraction_type.hpp.

Here is the caller graph for this function:

◆ to_string()

std::string fraction_timespec::to_string ( ) const

noexcept

Return simple string representation in seconds and nanoseconds.

Definition at line 93 of file basic_types.cpp.

Here is the caller graph for this function:

◆ to_iso8601_string()

std::string fraction_timespec::to_iso8601_string	(	bool	space_separator = false,
		bool	muteTime = false ) const

noexcept

Convenience string conversion interpreted since Unix Epoch in UTC to ISO 8601 YYYY-mm-ddTHH:MM:SS.ssZ, e.g.

'2022-06-23T14:34:10Zor '2022-06-23T14:34:10.228978909Z.

Implementation uses strftime() with format Y-m-dTH:M:S and adds 9 digits nanoseconds as fractions of seconds if not zero and the final Z.

Time will be dropped if hours, minutes, seconds and fractions of a seconds are all zero.

Parameters

space_separator	if true, use simple space separator instead of `T` and drop `Z`, otherwise use ISO 8601 as described above. Defaults to `false`.
muteTime	if true, always mute time

Definition at line 97 of file basic_types.cpp.

Here is the caller graph for this function:

Member Data Documentation

◆ tv_sec

int64_t jau::fraction_timespec::tv_sec

Seconds component, with its absolute value in range [0..inf[ or [0..inf).

Definition at line 871 of file fraction_type.hpp.

◆ tv_nsec

int64_t jau::fraction_timespec::tv_nsec

Nanoseconds component with its absolute value in range [0..1'000'000'000[ or [0..1'000'000'000).

Definition at line 876 of file fraction_type.hpp.

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

include/jau/fraction_type.hpp
src/basic_types.cpp

Public Member Functions

Static Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ fraction_timespec() [1/4]

◆ fraction_timespec() [2/4]

◆ fraction_timespec() [3/4]

◆ fraction_timespec() [4/4]

Member Function Documentation

◆ from() [1/3]

◆ from() [2/3]

◆ from() [3/3]

◆ to_fraction_i64()

◆ normalize()

◆ isZero()

◆ clear()

◆ operator==()

◆ operator<=>()

◆ operator+=()

◆ operator-=()

◆ operator*=()

◆ operator/=()

◆ to_timespec()

◆ to_ms()

◆ to_us()

◆ to_double()

◆ to_string()

◆ to_iso8601_string()

Member Data Documentation

◆ tv_sec

◆ tv_nsec