CTimeSpan Class

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

Syntax

class CTimeSpan

Members

Public Constructors

Public Methods

Operators

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

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

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.

See also

asctime, _wasctime
_ftime, _ftime32, _ftime64
gmtime, _gmtime32, _gmtime64
localtime, _localtime32, _localtime64
strftime, wcsftime, _strftime_l, _wcsftime_l
time, _time32, _time64
Hierarchy Chart
ATL/MFC Shared Classes