KanoopCommonQt 2.1.1
Kanoop foundational Qt utility library
Loading...
Searching...
No Matches
TimeSpan Class Reference

TimeSpan. More...

#include <timespan.h>

Public Types

enum  Format {
  Auto , Milliseconds , MicroSeconds , Abbreviated ,
  NoMilliseconds
}
 Output format for toString(). More...
 

Public Member Functions

 TimeSpan ()
 Default constructor — creates a zero-length time span.
 
 TimeSpan (double days, double hours, double minutes, double seconds, double milliseconds=0, double microseconds=0, double nanoseconds=0)
 Construct a TimeSpan from explicit time components.
 
 TimeSpan (const TimeSpan &other)
 Copy constructor.
 
 TimeSpan (const timespec &other)
 Construct a TimeSpan from a POSIX timespec value.
 
TimeSpanoperator= (const TimeSpan &other)
 Copy-assign from another TimeSpan.
 
TimeSpanoperator= (const timespec &other)
 Assign from a POSIX timespec.
 
TimeSpan operator+ (const TimeSpan &other) const
 Add two time spans.
 
TimeSpan operator- (const TimeSpan &other) const
 Subtract a time span.
 
TimeSpan operator* (const TimeSpan &other) const
 Multiply two time spans component-wise.
 
TimeSpan operator* (double value) const
 Scale by a scalar factor.
 
TimeSpan operator/ (const TimeSpan &other) const
 Divide two time spans component-wise.
 
TimeSpan operator/ (double value) const
 Divide by a scalar factor.
 
void operator+= (const TimeSpan &other)
 Add-assign a TimeSpan.
 
void operator-= (const TimeSpan &other)
 Subtract-assign a TimeSpan.
 
void operator*= (const TimeSpan &other)
 Multiply-assign by a TimeSpan.
 
void operator/= (const TimeSpan &other)
 Divide-assign by a TimeSpan.
 
void operator*= (double value)
 Multiply-assign by a scalar.
 
void operator/= (double value)
 Divide-assign by a scalar.
 
bool operator== (const TimeSpan &other) const
 Equality comparison.
 
bool operator!= (const TimeSpan &other) const
 Inequality comparison.
 
bool operator> (const TimeSpan &other) const
 Greater-than comparison.
 
bool operator< (const TimeSpan &other) const
 Less-than comparison.
 
bool operator>= (const TimeSpan &other) const
 Greater-than-or-equal comparison.
 
bool operator<= (const TimeSpan &other) const
 Less-than-or-equal comparison.
 
qint64 days () const
 Return the number of whole days in the days field of this TimeSpan when printed.
 
qint64 hours () const
 hours
 
qint64 minutes () const
 minutes
 
qint64 seconds () const
 seconds
 
qint64 milliseconds () const
 milliseconds
 
qint64 microseconds () const
 microseconds
 
qint64 nanoseconds () const
 nanoseconds
 
double totalSeconds () const
 totalSeconds
 
double totalMinutes () const
 totalMinutes
 
double totalHours () const
 totalHours
 
double totalDays () const
 totalDays
 
double totalMilliseconds () const
 totalMilliseconds
 
double totalMicroseconds () const
 totalMicroseconds
 
double totalNanoseconds () const
 totalNanoseconds
 
bool isZero () const
 Is this timespan zero total nanoseconds.
 
bool isNegative () const
 Return true if this time span represents a negative duration.
 
bool isPositive () const
 Return true if this time span represents a positive (non-zero) duration.
 
TimeSpan absoluteValue () const
 Return the absolute value of this time span.
 
bool isValid () const
 Return true if this time span was successfully constructed or parsed.
 
void toTimeSpec (struct timespec &timespec) const
 Populate a POSIX timespec structure from this TimeSpan.
 
QString toString (Format format, bool microseconds=false) const
 Format this TimeSpan as a string in the specified format.
 
QString toString (bool microseconds=false) const
 Format this TimeSpan as a string using the Auto format.
 
QString toAbbreviatedFormat (bool showMilliseconds=false) const
 Format this TimeSpan using the abbreviated display format (e.g.
 
QString toDumpString () const
 Format this TimeSpan as a verbose diagnostic string showing all internal fields.
 
TimeSpan addNanoseconds (double nanoseconds) const
 Return a new TimeSpan with nanoseconds added.
 
TimeSpan addMicroseconds (double microseconds) const
 Return a new TimeSpan with microseconds added.
 
TimeSpan addMilliseconds (double milliseconds) const
 Return a new TimeSpan with milliseconds added.
 
TimeSpan addSeconds (double seconds) const
 Return a new TimeSpan with seconds added.
 
TimeSpan addMinutes (double minutes) const
 Return a new TimeSpan with minutes added.
 
TimeSpan addHours (double hours) const
 Return a new TimeSpan with hours added.
 
TimeSpan addDays (double days) const
 Return a new TimeSpan with days added.
 
QVariant toVariant () const
 Wrap this TimeSpan in a QVariant for storage or signal passing.
 

Static Public Member Functions

static TimeSpan fromVariant (const QVariant &value)
 Construct a TimeSpan from a QVariant holding a TimeSpan value.
 
static TimeSpan fromNanoseconds (double nanoseconds)
 Construct a TimeSpan from a nanosecond count.
 
static TimeSpan fromMicroseconds (double microseconds)
 Construct a TimeSpan from a microsecond count.
 
static TimeSpan fromMilliseconds (double milliseconds)
 Construct a TimeSpan from a millisecond count.
 
static TimeSpan fromSeconds (double seconds)
 Construct a TimeSpan from a second count.
 
static TimeSpan fromMinutes (double minutes)
 Construct a TimeSpan from a minute count.
 
static TimeSpan fromHours (double hours)
 Construct a TimeSpan from an hour count.
 
static TimeSpan fromDays (double days)
 Construct a TimeSpan from a day count.
 
static TimeSpan fromString (const QString &timeString, bool *parsed=nullptr)
 Parse a TimeSpan from a formatted duration string.
 
static TimeSpan zero ()
 Return a zero-length TimeSpan.
 
static TimeSpan invalid ()
 Return an invalid (sentinel) TimeSpan whose isValid() returns false.
 
static TimeSpan diff (const QDateTime &now, const QDateTime &then)
 Compute the signed difference between two QDateTime values (now − then).
 
static TimeSpan diff (std::chrono::system_clock::time_point now, std::chrono::system_clock::time_point then)
 Compute the signed difference between two chrono time points (now − then).
 
static TimeSpan absDiff (const QDateTime &t1, const QDateTime &t2)
 Compute the absolute (non-negative) difference between two QDateTime values.
 
static TimeSpan absDiff (std::chrono::system_clock::time_point t1, std::chrono::system_clock::time_point t2)
 Compute the absolute difference between two chrono time points.
 
static TimeSpan max (const TimeSpan &t1, const TimeSpan &t2)
 Return the larger of two time spans.
 
static TimeSpan min (const TimeSpan &t1, const TimeSpan &t2)
 Return the smaller of two time spans.
 

Detailed Description

TimeSpan.

This class represents a span of time with nanosecond resolution, and provides an interface that is very similar to the .NET TimeSpan class.

Operators are supplied for comparison and assignment.

Conversions are supplied to convert between timespec and TimeSpan.

Use the absDiff() static method to obtain the difference between two QDateTime objects.

NOTE: The underlying representation is a signed 64-bit integer value of nanoseconds. Therefore, the largest possible value is 9,223,372,036,854,775,807 giving a maximum range of approximately 292 years.

This was re-written December 2021 to have nanosecond resolution. The interface is compatible with the previous TimeSpan object.

Stephen Punak, December 27 2021

A signed 64-bit nanosecond-resolution duration value, similar to the .NET TimeSpan class.

Provides arithmetic, comparison, and conversion operations across all common time units. The underlying storage is a signed 64-bit nanosecond count, giving a maximum range of approximately 292 years. Use the static factory methods (fromSeconds(), fromMilliseconds(), etc.) or absDiff() to construct instances conveniently.

Definition at line 41 of file timespan.h.

Member Enumeration Documentation

◆ Format

Output format for toString().

Enumerator
Auto 

Choose format automatically based on the span's magnitude.

Milliseconds 

Display with millisecond precision.

MicroSeconds 

Display with microsecond precision.

Abbreviated 

Abbreviated format (e.g. "1h 2m 3s")

NoMilliseconds 

Display without sub-second components.

Definition at line 192 of file timespan.h.

Constructor & Destructor Documentation

◆ TimeSpan() [1/4]

TimeSpan::TimeSpan ( )
inline

Default constructor — creates a zero-length time span.

Definition at line 45 of file timespan.h.

◆ TimeSpan() [2/4]

TimeSpan::TimeSpan ( double  days,
double  hours,
double  minutes,
double  seconds,
double  milliseconds = 0,
double  microseconds = 0,
double  nanoseconds = 0 
)

Construct a TimeSpan from explicit time components.

Parameters
daysNumber of days
hoursNumber of hours
minutesNumber of minutes
secondsNumber of seconds
millisecondsNumber of milliseconds (default 0)
microsecondsNumber of microseconds (default 0)
nanosecondsNumber of nanoseconds (default 0)

◆ TimeSpan() [3/4]

TimeSpan::TimeSpan ( const TimeSpan other)

Copy constructor.

Parameters
otherTimeSpan to copy

◆ TimeSpan() [4/4]

TimeSpan::TimeSpan ( const timespec &  other)

Construct a TimeSpan from a POSIX timespec value.

Parameters
othertimespec containing tv_sec and tv_nsec fields

Member Function Documentation

◆ absDiff() [1/2]

static TimeSpan TimeSpan::absDiff ( const QDateTime &  t1,
const QDateTime &  t2 
)
static

Compute the absolute (non-negative) difference between two QDateTime values.

Parameters
t1First QDateTime
t2Second QDateTime
Returns
Non-negative difference TimeSpan

Referenced by DateRange::duration().

◆ absDiff() [2/2]

static TimeSpan TimeSpan::absDiff ( std::chrono::system_clock::time_point  t1,
std::chrono::system_clock::time_point  t2 
)
static

Compute the absolute difference between two chrono time points.

Parameters
t1First time point
t2Second time point
Returns
Non-negative difference TimeSpan

◆ absoluteValue()

TimeSpan TimeSpan::absoluteValue ( ) const

Return the absolute value of this time span.

Returns
Non-negative copy of this TimeSpan

◆ addDays()

TimeSpan TimeSpan::addDays ( double  days) const

Return a new TimeSpan with days added.

Parameters
daysDays to add
Returns
Adjusted TimeSpan

◆ addHours()

TimeSpan TimeSpan::addHours ( double  hours) const

Return a new TimeSpan with hours added.

Parameters
hoursHours to add
Returns
Adjusted TimeSpan

◆ addMicroseconds()

TimeSpan TimeSpan::addMicroseconds ( double  microseconds) const

Return a new TimeSpan with microseconds added.

Parameters
microsecondsMicroseconds to add
Returns
Adjusted TimeSpan

◆ addMilliseconds()

TimeSpan TimeSpan::addMilliseconds ( double  milliseconds) const

Return a new TimeSpan with milliseconds added.

Parameters
millisecondsMilliseconds to add
Returns
Adjusted TimeSpan

◆ addMinutes()

TimeSpan TimeSpan::addMinutes ( double  minutes) const

Return a new TimeSpan with minutes added.

Parameters
minutesMinutes to add
Returns
Adjusted TimeSpan

◆ addNanoseconds()

TimeSpan TimeSpan::addNanoseconds ( double  nanoseconds) const

Return a new TimeSpan with nanoseconds added.

Parameters
nanosecondsNanoseconds to add
Returns
Adjusted TimeSpan

◆ addSeconds()

TimeSpan TimeSpan::addSeconds ( double  seconds) const

Return a new TimeSpan with seconds added.

Parameters
secondsSeconds to add
Returns
Adjusted TimeSpan

◆ days()

qint64 TimeSpan::days ( ) const

Return the number of whole days in the days field of this TimeSpan when printed.

Returns
Number of whole days

◆ diff() [1/2]

static TimeSpan TimeSpan::diff ( const QDateTime &  now,
const QDateTime &  then 
)
static

Compute the signed difference between two QDateTime values (now − then).

Parameters
nowMinuend QDateTime
thenSubtrahend QDateTime
Returns
Signed difference TimeSpan

◆ diff() [2/2]

static TimeSpan TimeSpan::diff ( std::chrono::system_clock::time_point  now,
std::chrono::system_clock::time_point  then 
)
static

Compute the signed difference between two chrono time points (now − then).

Parameters
nowMinuend time point
thenSubtrahend time point
Returns
Signed difference TimeSpan

◆ fromDays()

static TimeSpan TimeSpan::fromDays ( double  days)
static

Construct a TimeSpan from a day count.

Parameters
daysDuration in days
Returns
TimeSpan

◆ fromHours()

static TimeSpan TimeSpan::fromHours ( double  hours)
static

Construct a TimeSpan from an hour count.

Parameters
hoursDuration in hours
Returns
TimeSpan

◆ fromMicroseconds()

static TimeSpan TimeSpan::fromMicroseconds ( double  microseconds)
static

Construct a TimeSpan from a microsecond count.

Parameters
microsecondsDuration in microseconds
Returns
TimeSpan

◆ fromMilliseconds()

static TimeSpan TimeSpan::fromMilliseconds ( double  milliseconds)
static

Construct a TimeSpan from a millisecond count.

Parameters
millisecondsDuration in milliseconds
Returns
TimeSpan

◆ fromMinutes()

static TimeSpan TimeSpan::fromMinutes ( double  minutes)
static

Construct a TimeSpan from a minute count.

Parameters
minutesDuration in minutes
Returns
TimeSpan

◆ fromNanoseconds()

static TimeSpan TimeSpan::fromNanoseconds ( double  nanoseconds)
static

Construct a TimeSpan from a nanosecond count.

Parameters
nanosecondsDuration in nanoseconds
Returns
TimeSpan

◆ fromSeconds()

static TimeSpan TimeSpan::fromSeconds ( double  seconds)
static

Construct a TimeSpan from a second count.

Parameters
secondsDuration in seconds
Returns
TimeSpan

Referenced by zero().

◆ fromString()

static TimeSpan TimeSpan::fromString ( const QString &  timeString,
bool *  parsed = nullptr 
)
static

Parse a TimeSpan from a formatted duration string.

Parameters
timeStringString representation of a time span
parsedOptional output flag set to true if parsing succeeded
Returns
Parsed TimeSpan, or an invalid sentinel on failure

◆ fromVariant()

static TimeSpan TimeSpan::fromVariant ( const QVariant &  value)
inlinestatic

Construct a TimeSpan from a QVariant holding a TimeSpan value.

Parameters
valueVariant containing a TimeSpan
Returns
Extracted TimeSpan

Definition at line 399 of file timespan.h.

◆ hours()

qint64 TimeSpan::hours ( ) const

hours

Returns
Number of hours represented in the hours field of this TimeSpan when printed

◆ invalid()

static TimeSpan TimeSpan::invalid ( )
static

Return an invalid (sentinel) TimeSpan whose isValid() returns false.

Returns
Invalid TimeSpan

◆ isNegative()

bool TimeSpan::isNegative ( ) const
inline

Return true if this time span represents a negative duration.

Returns
true if negative

Definition at line 293 of file timespan.h.

◆ isPositive()

bool TimeSpan::isPositive ( ) const
inline

Return true if this time span represents a positive (non-zero) duration.

Returns
true if positive

Definition at line 298 of file timespan.h.

◆ isValid()

bool TimeSpan::isValid ( ) const
inline

Return true if this time span was successfully constructed or parsed.

Returns
true if valid

Definition at line 309 of file timespan.h.

◆ isZero()

bool TimeSpan::isZero ( ) const
inline

Is this timespan zero total nanoseconds.

Returns
true if this timespan is zero

Definition at line 288 of file timespan.h.

◆ max()

static TimeSpan TimeSpan::max ( const TimeSpan t1,
const TimeSpan t2 
)
inlinestatic

Return the larger of two time spans.

Parameters
t1First TimeSpan
t2Second TimeSpan
Returns
The greater of t1 and t2

Definition at line 514 of file timespan.h.

◆ microseconds()

qint64 TimeSpan::microseconds ( ) const

microseconds

Returns
Number of microseconds represented in the microseconds field of this TimeSpan when printed

◆ milliseconds()

qint64 TimeSpan::milliseconds ( ) const

milliseconds

Returns
Number of milliseconds represented in the miliseconds field of this TimeSpan when printed

◆ min()

static TimeSpan TimeSpan::min ( const TimeSpan t1,
const TimeSpan t2 
)
inlinestatic

Return the smaller of two time spans.

Parameters
t1First TimeSpan
t2Second TimeSpan
Returns
The lesser of t1 and t2

Definition at line 522 of file timespan.h.

◆ minutes()

qint64 TimeSpan::minutes ( ) const

minutes

Returns
Number of hours represented in the minutes field of this TimeSpan when printed

◆ nanoseconds()

qint64 TimeSpan::nanoseconds ( ) const

nanoseconds

Returns
Number of nanoseconds represented in the nanoseconds field of this TimeSpan when printed

◆ operator!=()

bool TimeSpan::operator!= ( const TimeSpan other) const

Inequality comparison.

Parameters
otherTimeSpan to compare with
Returns
true if both time spans differ

◆ operator*() [1/2]

TimeSpan TimeSpan::operator* ( const TimeSpan other) const

Multiply two time spans component-wise.

Parameters
otherTimeSpan to multiply by
Returns
Product

◆ operator*() [2/2]

TimeSpan TimeSpan::operator* ( double  value) const

Scale by a scalar factor.

Parameters
valueScalar multiplier
Returns
Scaled time span

◆ operator*=() [1/2]

void TimeSpan::operator*= ( const TimeSpan other)

Multiply-assign by a TimeSpan.

Parameters
otherTimeSpan to multiply by

◆ operator*=() [2/2]

void TimeSpan::operator*= ( double  value)

Multiply-assign by a scalar.

Parameters
valueScalar multiplier

◆ operator+()

TimeSpan TimeSpan::operator+ ( const TimeSpan other) const

Add two time spans.

Parameters
otherTimeSpan to add
Returns
Sum of both time spans

◆ operator+=()

void TimeSpan::operator+= ( const TimeSpan other)

Add-assign a TimeSpan.

Parameters
otherTimeSpan to add

◆ operator-()

TimeSpan TimeSpan::operator- ( const TimeSpan other) const

Subtract a time span.

Parameters
otherTimeSpan to subtract
Returns
Difference of both time spans

◆ operator-=()

void TimeSpan::operator-= ( const TimeSpan other)

Subtract-assign a TimeSpan.

Parameters
otherTimeSpan to subtract

◆ operator/() [1/2]

TimeSpan TimeSpan::operator/ ( const TimeSpan other) const

Divide two time spans component-wise.

Parameters
otherTimeSpan divisor
Returns
Quotient

◆ operator/() [2/2]

TimeSpan TimeSpan::operator/ ( double  value) const

Divide by a scalar factor.

Parameters
valueScalar divisor
Returns
Scaled time span

◆ operator/=() [1/2]

void TimeSpan::operator/= ( const TimeSpan other)

Divide-assign by a TimeSpan.

Parameters
otherTimeSpan divisor

◆ operator/=() [2/2]

void TimeSpan::operator/= ( double  value)

Divide-assign by a scalar.

Parameters
valueScalar divisor

◆ operator<()

bool TimeSpan::operator< ( const TimeSpan other) const

Less-than comparison.

Parameters
otherTimeSpan to compare with
Returns
true if this time span is less

◆ operator<=()

bool TimeSpan::operator<= ( const TimeSpan other) const

Less-than-or-equal comparison.

Parameters
otherTimeSpan to compare with
Returns
true if this time span is less or equal

◆ operator=() [1/2]

TimeSpan & TimeSpan::operator= ( const TimeSpan other)

Copy-assign from another TimeSpan.

Parameters
otherTimeSpan to copy
Returns
Reference to this TimeSpan

◆ operator=() [2/2]

TimeSpan & TimeSpan::operator= ( const timespec &  other)

Assign from a POSIX timespec.

Parameters
othertimespec to assign from
Returns
Reference to this TimeSpan

◆ operator==()

bool TimeSpan::operator== ( const TimeSpan other) const

Equality comparison.

Parameters
otherTimeSpan to compare with
Returns
true if both time spans are equal

◆ operator>()

bool TimeSpan::operator> ( const TimeSpan other) const

Greater-than comparison.

Parameters
otherTimeSpan to compare with
Returns
true if this time span is greater

◆ operator>=()

bool TimeSpan::operator>= ( const TimeSpan other) const

Greater-than-or-equal comparison.

Parameters
otherTimeSpan to compare with
Returns
true if this time span is greater or equal

◆ seconds()

qint64 TimeSpan::seconds ( ) const

seconds

Returns
Number of seconds represented in the seconds field of this TimeSpan when printed

◆ toAbbreviatedFormat()

QString TimeSpan::toAbbreviatedFormat ( bool  showMilliseconds = false) const

Format this TimeSpan using the abbreviated display format (e.g.

"1h 2m 3s").

Parameters
showMillisecondsIf true, append milliseconds to the output
Returns
Abbreviated duration string

◆ toDumpString()

QString TimeSpan::toDumpString ( ) const

Format this TimeSpan as a verbose diagnostic string showing all internal fields.

Returns
Diagnostic dump string

◆ toString() [1/2]

QString TimeSpan::toString ( bool  microseconds = false) const

Format this TimeSpan as a string using the Auto format.

Parameters
microsecondsIf true, include microsecond resolution
Returns
Formatted duration string

◆ toString() [2/2]

QString TimeSpan::toString ( Format  format,
bool  microseconds = false 
) const

Format this TimeSpan as a string in the specified format.

Parameters
formatDisplay format
microsecondsIf true, include microsecond resolution
Returns
Formatted duration string

◆ totalDays()

double TimeSpan::totalDays ( ) const

totalDays

Returns
The total number of days represented in the TimeSpan

◆ totalHours()

double TimeSpan::totalHours ( ) const

totalHours

Returns
The total number of hours represented in the TimeSpan

◆ totalMicroseconds()

double TimeSpan::totalMicroseconds ( ) const

totalMicroseconds

Returns
The total number of microseconds represented in the TimeSpan

◆ totalMilliseconds()

double TimeSpan::totalMilliseconds ( ) const

totalMilliseconds

Returns
The total number of milliseconds represented in the TimeSpan

Referenced by MutexEvent::wait().

◆ totalMinutes()

double TimeSpan::totalMinutes ( ) const

totalMinutes

Returns
The total number of minutes represented in the TimeSpan

◆ totalNanoseconds()

double TimeSpan::totalNanoseconds ( ) const

totalNanoseconds

Returns
The total number of nanoseconds represented in the TimeSpan

◆ totalSeconds()

double TimeSpan::totalSeconds ( ) const

totalSeconds

Returns
The total number of seconds represented in the TimeSpan

◆ toTimeSpec()

void TimeSpan::toTimeSpec ( struct timespec &  timespec) const

Populate a POSIX timespec structure from this TimeSpan.

Parameters
timespecOutput timespec to fill with tv_sec and tv_nsec

◆ toVariant()

QVariant TimeSpan::toVariant ( ) const
inline

Wrap this TimeSpan in a QVariant for storage or signal passing.

Returns
QVariant containing this TimeSpan

Definition at line 405 of file timespan.h.

◆ zero()

static TimeSpan TimeSpan::zero ( )
inlinestatic

Return a zero-length TimeSpan.

Returns
Zero-length TimeSpan

Definition at line 468 of file timespan.h.

References fromSeconds().


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