`CTimeSpan` Class

Article
09/16/2022

An amount of time, which is internally stored as the number of seconds in the time span.

Syntax

class CTimeSpan

Members

Public Constructors

Name	Description
`CTimeSpan::CTimeSpan`	Constructs `CTimeSpan` objects in various ways.

Public Methods

Name	Description
`CTimeSpan::Format`	Converts a `CTimeSpan` into a formatted string.
`CTimeSpan::GetDays`	Returns a value that represents the number of complete days in this `CTimeSpan`.
`CTimeSpan::GetHours`	Returns a value that represents the number of hours in the current day (-23 through 23).
`CTimeSpan::GetMinutes`	Returns a value that represents the number of minutes in the current hour (-59 through 59).
`CTimeSpan::GetSeconds`	Returns a value that represents the number of seconds in the current minute (-59 through 59).
`CTimeSpan::GetTimeSpan`	Returns the value of the `CTimeSpan` object.
`CTimeSpan::GetTotalHours`	Returns a value that represents the total number of complete hours in this `CTimeSpan`.
`CTimeSpan::GetTotalMinutes`	Returns a value that represents the total number of complete minutes in this `CTimeSpan`.
`CTimeSpan::GetTotalSeconds`	Returns a value that represents the total number of complete seconds in this `CTimeSpan`.
`CTimeSpan::Serialize64`	Serializes data to or from an archive.

Operators

Name	Description
`operator + -`	Adds and subtracts `CTimeSpan` objects.
`operator += -=`	Adds and subtracts a `CTimeSpan` object to and from this `CTimeSpan`.
`operator == < etc.`	Compares two relative time values.

Remarks

CTimeSpan doesn't have a base class.

CTimeSpan functions convert seconds to various combinations of days, hours, minutes, and seconds.

The CTimeSpan object is stored in a __time64_t structure, which is 8 bytes.

A companion class, CTime, represents an absolute time.

The CTime and CTimeSpan classes aren't designed for derivation. Because there are no virtual functions, the size of both CTime and CTimeSpan objects is exactly 8 bytes. Most member functions are inline.

For more information on using CTimeSpan, see the articles Date and Time, and Time Management in the Run-Time Library Reference.

Requirements

Header: atltime.h

`CTimeSpan` Comparison Operators

Comparison operators.

bool operator==(CTimeSpan span) const throw();
bool operator!=(CTimeSpan span) const throw();
bool operator<(CTimeSpan span) const throw();
bool operator>(CTimeSpan span) const throw();
bool operator<=(CTimeSpan span) const throw();
bool operator>=(CTimeSpan span) const throw();

Parameters

span
The object to compare.

Return Value

These operators compare two relative time values. They return TRUE if the condition is true; otherwise FALSE.

Example

CTimeSpan ts1(100);
CTimeSpan ts2(110);
ATLASSERT((ts1 != ts2) && (ts1 < ts2) && (ts1 <= ts2));

`CTimeSpan::CTimeSpan`

Constructs CTimeSpan objects in various ways.

CTimeSpan() throw();
CTimeSpan(__time64_t time) throw();

CTimeSpan(
    LONG lDays,
    int nHours,
    int nMins,
    int nSecs) throw();

Parameters

timeSpanSrc
A CTimeSpan object that already exists.

time
A __time64_t time value, which is the number of seconds in the time span.

lDays, nHours, nMins, nSecs
Days, hours, minutes, and seconds, respectively.

Remarks

All these constructors create a new CTimeSpan object initialized with the specified relative time. Each constructor is described below:

CTimeSpan( ); Constructs an uninitialized CTimeSpan object.
CTimeSpan( const CTimeSpan& ); Constructs a CTimeSpan object from another CTimeSpan value.
CTimeSpan( __time64_t ); Constructs a CTimeSpan object from a __time64_t type.
CTimeSpan( LONG, int, int, int ); Constructs a CTimeSpan object from components with each component constrained to the following ranges:

Component Range

lDays 0-25,000 (approximately)

nHours 0-23

nMins 0-59

nSecs 0-59

Component	Range
lDays	0-25,000 (approximately)
nHours	0-23
nMins	0-59
nSecs	0-59

Note that the Debug version of the Microsoft Foundation Class Library asserts if one or more of the time-day components is out of range. It is your responsibility to validate the arguments prior to calling.

Example

CTimeSpan ts1;  // Uninitialized time value
CTimeSpan ts2a(ts1); // Copy constructor
CTimeSpan ts2b = ts1; // Copy constructor again
CTimeSpan ts3(100); // 100 seconds
CTimeSpan ts4(0, 1, 5, 12);    // 1 hour, 5 minutes, and 12 seconds

`CTimeSpan::Format`

Generates a formatted string that corresponds to this CTimeSpan.

CString Format(LPCSTR pFormat) const;
CString Format(LPCTSTR pszFormat) const;
CString Format(UINT nID) const;

Parameters

pFormat, pszFormat
A formatting string similar to the printf formatting string. Formatting codes, preceded by a percent (%) sign, are replaced by the corresponding CTimeSpan component. Other characters in the formatting string are copied unchanged to the returned string. The value and meaning of the formatting codes for Format are listed below:

%D Total days in this CTimeSpan
%H Hours in the current day
%M Minutes in the current hour
%S Seconds in the current minute
%% Percent sign

nID
The ID of the string that identifies this format.

Return Value

A CString object that contains the formatted time.

Remarks

The Debug version of the library checks the formatting codes and asserts if the code isn't in the list above.

Example

CTimeSpan ts(3, 1, 5, 12); // 3 days, 1 hour, 5 min, and 12 sec
CString s = ts.Format(_T("Total days: %D, hours: %H, mins: %M, secs: %S"));
ATLASSERT(s == _T("Total days: 3, hours: 01, mins: 05, secs: 12"));

`CTimeSpan::GetDays`

Returns a value that represents the number of complete days in this CTimeSpan.

LONGLONG GetDays() const throw();

Return Value

Returns the number of complete 24-hour days in the time span. This value may be negative if the time span is negative.

Remarks

Note that Daylight Savings Time (DST) can cause GetDays to return a potentially surprising result. For example, when DST is in effect, GetDays reports the number of days between April 1 and May 1 as 29, not 30, because one day in April is shortened by an hour and therefore doesn't count as a complete day.

Example

CTimeSpan ts(3, 1, 5, 12); // 3 days, 1 hour, 5 min, and 12 sec
ATLASSERT(ts.GetDays() == 3);

`CTimeSpan::GetHours`

Returns a value that represents the number of hours in the current day (-23 through 23).

LONG GetHours() const throw();

Return Value

Returns the number of hours in the current day. The range is -23 through 23.

Example

CTimeSpan ts(3, 1, 5, 12); // 3 days, 1 hour, 5 min, and 12 sec
ATLASSERT(ts.GetHours() == 1);
ATLASSERT(ts.GetMinutes() == 5);
ATLASSERT(ts.GetSeconds() == 12);

`CTimeSpan::GetMinutes`

Returns a value that represents the number of minutes in the current hour (-59 through 59).

LONG GetMinutes() const throw();

Return Value

Returns the number of minutes in the current hour. The range is -59 through 59.

Example

See the example for GetHours.

`CTimeSpan::GetSeconds`

Returns a value that represents the number of seconds in the current minute (-59 through 59).

LONG GetSeconds() const throw();

Return Value

Returns the number of seconds in the current minute. The range is -59 through 59.

Example

See the example for GetHours.

`CTimeSpan::GetTimeSpan`

Returns the value of the CTimeSpan object.

__ time64_t GetTimeSpan() const throw();

Return Value

Returns the current value of the CTimeSpan object.

`CTimeSpan::GetTotalHours`

Returns a value that represents the total number of complete hours in this CTimeSpan.

LONGLONG GetTotalHours() const throw();

Return Value

Returns the total number of complete hours in this CTimeSpan.

Example

CTimeSpan ts(3, 1, 5, 12); // 3 days, 1 hour, 5 min, and 12 sec
ATLASSERT(ts.GetTotalHours() == 73);
ATLASSERT(ts.GetTotalMinutes() == 4385);
ATLASSERT(ts.GetTotalSeconds() == 263112);

`CTimeSpan::GetTotalMinutes`

Returns a value that represents the total number of complete minutes in this CTimeSpan.

LONGLONG GetTotalMinutes() const throw();

Return Value

Returns the total number of complete minutes in this CTimeSpan.

Example

See the example for GetTotalHours.

`CTimeSpan::GetTotalSeconds`

Returns a value that represents the total number of complete seconds in this CTimeSpan.

LONGLONG GetTotalSeconds() const throw();

Return Value

Returns the total number of complete seconds in this CTimeSpan.

Example

See the example for GetTotalHours.

`CTimeSpan::operator +`, `CTimeSpan::operator -`

Adds and subtracts CTimeSpan objects.

CTimeSpan operator+(CTimeSpan span) const throw();
CTimeSpan operator-(CTimeSpan span) const throw();

Parameters

span
The value to add to the CTimeSpan object.

Return Value

A CTimeSpan object representing the result of the operation.

Remarks

These two operators allow you to add and subtract CTimeSpan objects to and from each other.

Example

CTimeSpan ts1(3, 1, 5, 12); // 3 days, 1 hour, 5 min, and 12 sec
CTimeSpan ts2(100); // 100 seconds
CTimeSpan ts3 = ts1 + ts2;
ATLASSERT(ts3.GetSeconds() == 52); // 6 mins, 52 secs

`CTimeSpan::operator +=`, `CTimeSpan::operator -=`

Adds and subtracts a CTimeSpan object to and from this CTimeSpan.

CTimeSpan& operator+=(CTimeSpan span) throw();
CTimeSpan& operator-=(CTimeSpan span) throw();

Parameters

span
The value to add to the CTimeSpan object.

Return Value

The updated CTimeSpan object.

Remarks

These operators allow you to add and subtract a CTimeSpan object to and from this CTimeSpan.

Example

CTimeSpan ts1(10); // 10 seconds
CTimeSpan ts2(100); // 100 seconds
ts2 -= ts1;
ATLASSERT(ts2.GetTotalSeconds() == 90);

`CTimeSpan::Serialize64`

Note

This method is only available in MFC projects.

Serializes the data associated with the member variable to or from an archive.

CArchive& Serialize64(CArchive& ar);

Parameters

ar
The CArchive object that you want to update.

Return Value

The updated CArchive object.

CTimeSpan Class

Syntax

Members

Public Constructors

Public Methods

Operators

Remarks

Requirements

CTimeSpan Comparison Operators

Parameters

Return Value

Example

CTimeSpan::CTimeSpan

Parameters

Remarks

Example

CTimeSpan::Format

Parameters

Return Value

Remarks

Example

CTimeSpan::GetDays

Return Value

Remarks

Example

CTimeSpan::GetHours

Return Value

Example

CTimeSpan::GetMinutes

Return Value

Example

CTimeSpan::GetSeconds

Return Value

Example

CTimeSpan::GetTimeSpan

Return Value

CTimeSpan::GetTotalHours

Return Value

Example

CTimeSpan::GetTotalMinutes

Return Value

Example

CTimeSpan::GetTotalSeconds

Return Value

Example

CTimeSpan::operator +, CTimeSpan::operator -

Parameters

Return Value

Remarks

Example

CTimeSpan::operator +=, CTimeSpan::operator -=

Parameters

Return Value

Remarks

Example

CTimeSpan::Serialize64

Parameters

Return Value

See also

Feedback

Feedback

Additional resources

`CTimeSpan` Class

`CTimeSpan` Comparison Operators

`CTimeSpan::CTimeSpan`

`CTimeSpan::Format`

`CTimeSpan::GetDays`

`CTimeSpan::GetHours`

`CTimeSpan::GetMinutes`

`CTimeSpan::GetSeconds`

`CTimeSpan::GetTimeSpan`

`CTimeSpan::GetTotalHours`

`CTimeSpan::GetTotalMinutes`

`CTimeSpan::GetTotalSeconds`

`CTimeSpan::operator +`, `CTimeSpan::operator -`

`CTimeSpan::operator +=`, `CTimeSpan::operator -=`

`CTimeSpan::Serialize64`