duration

group turbo_times_duration

Functions

inline int64_t safe_int_mod(Duration num, Duration den, Duration *rem)

Divides a numerator Duration by a denominator Duration, returning the quotient and remainder.

The remainder always has the same sign as the numerator. The returned quotient and remainder respect the identity: numerator = denominator * quotient + remainder Returned quotients are capped to the range of int64_t, with the difference spilling into the remainder to uphold the above identity. This means that the remainder returned could differ from the remainder returned by Duration::operator% for huge quotients. See also the notes on infinite_duration() below regarding the behavior of division involving zero and infinite durations. Example:

constexpr turbo::Duration a = turbo::seconds(std::numeric_limits<int64_t>::max());  // big
constexpr turbo::Duration b = turbo::nanoseconds(1);       // small
turbo::Duration rem = a % b;
// rem == turbo::zero_duration()
// Here, q would overflow int64_t, so rem accounts for the difference.
int64_t q = turbo::safe_int_mod(a, b, &rem);
// q == std::numeric_limits<int64_t>::max(), rem == a - b * q

Parameters:

• num – the numerator

• den – the denominator

• rem – the remainder

Returns:

the quotient

double safe_float_mod(Duration num, Duration den)

Divides a Duration numerator into a fractional number of units of a Duration denominator.

See also the notes on infinite_duration() below regarding the behavior of division involving zero and infinite durations.

See also

turbo::safe_int_mod() for a version that returns the quotient and remainder. Example:

double d = turbo::safe_float_mod(turbo::milliseconds(1500), turbo::seconds(1));
// d == 1.5

Parameters:

• num – the numerator

• den – the denominator

Returns:

the quotient

constexpr Duration zero_duration()

Returns a zero-length duration.

This function behaves just like the default constructor, but the name helps make the semantics clear at call sites.

Returns:

inline Duration abs_duration(Duration d)

Returns the absolute value of a duration.

Parameters:

d –

Returns:

Duration trunc(Duration d, Duration unit)

Truncates a duration (toward zero) to a multiple of a non-zero unit.

Example:

turbo::Duration d = turbo::nanoseconds(123456789);
turbo::Duration a = turbo::trunc(d, turbo::microseconds(1));  // 123456us

Parameters:

• d –

• unit –

Returns:

Duration floor(Duration d, Duration unit)

Floors a duration using the passed duration unit to its largest value not greater than the duration.

Example:

turbo::Duration d = turbo::nanoseconds(123456789);
turbo::Duration b = turbo::floor(d, turbo::microseconds(1));  // 123456us

Parameters:

• d –

• unit –

Returns:

Duration ceil(Duration d, Duration unit)

Returns the ceiling of a duration using the passed duration unit to its smallest value not less than the duration.

Example:

turbo::Duration d = turbo::nanoseconds(123456789);
turbo::Duration c = turbo::ceil(d, turbo::microseconds(1));   // 123457us

Parameters:

• d –

• unit –

Returns:

constexpr Duration infinite_duration()

Returns an infinite Duration.

To get a Duration representing negative infinity, use -infinite_duration().

Duration arithmetic overflows to +/- infinity and saturates. In general, arithmetic with Duration infinities is similar to IEEE 754 infinities except where IEEE 754 NaN would be involved, in which case +/- infinite_duration() is used in place of a “nan” Duration. Examples:

constexpr turbo::Duration inf = turbo::infinite_duration();
const turbo::Duration d = ... any finite duration ...

inf == inf + inf
inf == inf + d
inf == inf - inf
-inf == d - inf

inf == d * 1e100
inf == inf / 2
0 == d / inf
INT64_MAX == inf / d

d < inf
-inf < d

// Division by zero returns infinity, or INT64_MIN/MAX where appropriate.
inf == d / 0
INT64_MAX == d / turbo::zero_duration()

Returns:

template<typename T, time_internal::EnableIfIntegral<T> = 0>
constexpr Duration nanoseconds(T n)

Factory overloads for constructing Duration values from an integral number of the unit indicated by the factory function’s name.

These functions exist for convenience, but they are not as efficient as the integral factories, which should be preferred. Example:

turbo::Duration a = turbo::seconds(60);
turbo::Duration b = turbo::minutes(1);  // b == a
auto a = turbo::seconds(1.5);        // OK
auto b = turbo::milliseconds(1500);  // BETTER

Note

no “Days()” factory function exists because “a day” is ambiguous. Civil days are not always 24 hours long, and a 24-hour duration often does not correspond with a civil day. If a 24-hour duration is needed, use turbo::hours(24). If you actually want a civil day, use turbo::CivilDay from civil_time.h.

Parameters:

n –

Returns:

int64_t to_int64_nanoseconds(Duration d)

Helper functions that convert a Duration to an integral count of the indicated unit.

These return the same results as the safe_int_mod() function, though they usually do so more efficiently; see the documentation of safe_int_mod() for details about overflow, etc.

Example:

turbo::Duration d = turbo::milliseconds(1500);
int64_t isec = turbo::to_int64_seconds(d);  // isec == 1

Parameters:

d – the duration to get from

Returns:

the integral count of the indicated unit

int64_t to_int64_microseconds(Duration d)

similar to to_int64_nanoseconds()

See also

to_int64_nanoseconds()

Parameters:

d –

Returns:

int64_t to_int64_milliseconds(Duration d)

similar to to_int64_nanoseconds()

See also

to_int64_nanoseconds()

Parameters:

d –

Returns:

int64_t to_int64_seconds(Duration d)

similar to to_int64_nanoseconds()

See also

to_int64_nanoseconds()

Parameters:

d –

Returns:

int64_t to_int64_minutes(Duration d)

similar to to_int64_nanoseconds()

See also

to_int64_nanoseconds()

Parameters:

d –

Returns:

int64_t to_int64_hours(Duration d)

similar to to_int64_nanoseconds()

See also

to_int64_nanoseconds()

Parameters:

d –

Returns:

double to_double_nanoseconds(Duration d)

Helper functions that convert a Duration to a floating point count of the indicated unit.

These functions are shorthand for the safe_float_mod() function above; see its documentation for details about overflow, etc.

Example:

turbo::Duration d = turbo::milliseconds(1500);
double dsec = turbo::to_double_seconds(d);  // dsec == 1.5

Parameters:

d –

Returns:

double to_double_microseconds(Duration d)

similar to to_double_nanoseconds()

See also

to_double_nanoseconds()

Parameters:

d –

Returns:

double to_double_milliseconds(Duration d)

similar to to_double_nanoseconds()

See also

to_double_nanoseconds()

Parameters:

d –

Returns:

double to_double_seconds(Duration d)

similar to to_double_nanoseconds()

See also

to_double_nanoseconds()

Parameters:

d –

Returns:

double to_double_minutes(Duration d)

similar to to_double_nanoseconds()

See also

to_double_nanoseconds()

Parameters:

d –

Returns:

double to_double_hours(Duration d)

similar to to_double_nanoseconds()

See also

to_double_nanoseconds()

Parameters:

d –

Returns:

constexpr Duration from_chrono(const std::chrono::nanoseconds &d)

Converts any of the pre-defined std::chrono durations to an turbo::Duration.

Example:

std::chrono::milliseconds ms(123);
turbo::Duration d = turbo::from_chrono(ms);

Parameters:

d –

Returns:

constexpr Duration from_chrono(const std::chrono::microseconds &d)

similar to from_chrono()

See also

from_chrono()

Parameters:

d –

Returns:

constexpr Duration from_chrono(const std::chrono::milliseconds &d)

similar to from_chrono()

See also

from_chrono()

Parameters:

d –

Returns:

constexpr Duration from_chrono(const std::chrono::seconds &d)

similar to from_chrono()

See also

from_chrono()

Parameters:

d –

Returns:

constexpr Duration from_chrono(const std::chrono::minutes &d)

similar to from_chrono()

See also

from_chrono()

Parameters:

d –

Returns:

constexpr Duration from_chrono(const std::chrono::hours &d)

similar to from_chrono()

See also

from_chrono()

Parameters:

d –

Returns:

std::chrono::nanoseconds to_chrono_nanoseconds(Duration d)

Converts an turbo::Duration to any of the pre-defined std::chrono durations.

If overflow would occur, the returned value will saturate at the min/max chrono duration value instead. Example:

turbo::Duration d = turbo::microseconds(123);
auto x = turbo::to_chrono_microseconds(d);
auto y = turbo::to_chrono_nanoseconds(d);  // x == y
auto z = turbo::to_chrono_seconds(turbo::infinite_duration());
// z == std::chrono::seconds::max()

Parameters:

d –

Returns:

std::chrono::microseconds to_chrono_microseconds(Duration d)

similar to to_chrono_nanoseconds()

See also

to_chrono_nanoseconds()

Parameters:

d –

Returns:

std::chrono::milliseconds to_chrono_milliseconds(Duration d)

similar to to_chrono_nanoseconds()

See also

to_chrono_nanoseconds()

Parameters:

d –

Returns:

std::chrono::seconds to_chrono_seconds(Duration d)

similar to to_chrono_nanoseconds()

See also

to_chrono_nanoseconds()

Parameters:

d –

Returns:

std::chrono::minutes to_chrono_minutes(Duration d)

similar to to_chrono_seconds()

See also

to_chrono_seconds()

Parameters:

d –

Returns:

std::chrono::hours to_chrono_hours(Duration d)

similar to to_chrono_nanoseconds()

See also

to_chrono_nanoseconds()

Parameters:

d –

Returns:

std::string format_duration(Duration d)

Returns a string representing the duration in the form “72h3m0.5s”.

Returns “inf” or “-inf” for +/- infinite_duration().

Parameters:

d –

Returns:

bool parse_duration(std::string_view dur_string, Duration *d)

Parses a duration string consisting of a possibly signed sequence of decimal numbers, each with an optional fractional part and a unit suffix.

The valid suffixes are “ns”, “us” “ms”, “s”, “m”, and “h”. Simple examples include “300ms”, “-1.5h”, and “2h45m”. Parses “0” as zero_duration(). Parses “inf” and “-inf” as +/- infinite_duration().

Parameters:

• dur_string –

• d –

Returns:

class Duration

#include <time.h>

The turbo::Duration class represents a signed, fixed-length amount of time.

A Duration is generated using a unit-specific factory function, or is the result of subtracting one turbo::Time from another. Durations behave like unit-safe integers and they support all the natural integer-like arithmetic operations. Arithmetic overflows and saturates at +/- infinity. Duration should be passed by value rather than const reference.

Factory functions nanoseconds(), microseconds(), milliseconds(), seconds(), minutes(), hours() and infinite_duration() allow for creation of constexpr Duration values

Examples:

constexpr turbo::Duration ten_ns = turbo::nanoseconds(10);
constexpr turbo::Duration min = turbo::minutes(1);
constexpr turbo::Duration hour = turbo::hours(1);
turbo::Duration dur = 60 * min;  // dur == hour
turbo::Duration half_sec = turbo::milliseconds(500);
turbo::Duration quarter_sec = 0.25 * turbo::seconds(1);

Duration values can be easily converted to an integral number of units using the division operator.

Example:

constexpr turbo::Duration dur = turbo::milliseconds(1500);
int64_t ns = dur / turbo::nanoseconds(1);   // ns == 1500000000
int64_t ms = dur / turbo::milliseconds(1);  // ms == 1500
int64_t sec = dur / turbo::seconds(1);    // sec == 1 (subseconds truncated)
int64_t min = dur / turbo::minutes(1);    // min == 0

See the safe_int_mod() and safe_float_mod() functions below for details on how to access the fractional parts of the quotient.

Alternatively, conversions can be performed using helpers such as to_int64_microseconds() and to_double_seconds().