Skip to content

Latest commit

 

History

History
393 lines (242 loc) · 12.1 KB

ctimespan-class.md

File metadata and controls

393 lines (242 loc) · 12.1 KB
description title ms.date f1_keywords helpviewer_keywords
Learn more about: CTimeSpan Class
CTimeSpan Class
10/18/2018
CTimeSpan
ATLTIME/ATL::CTimeSpan
ATLTIME/ATL::CTimeSpan::CTimeSpan
ATLTIME/ATL::CTimeSpan::Format
ATLTIME/ATL::CTimeSpan::GetDays
ATLTIME/ATL::CTimeSpan::GetHours
ATLTIME/ATL::CTimeSpan::GetMinutes
ATLTIME/ATL::CTimeSpan::GetSeconds
ATLTIME/ATL::CTimeSpan::GetTimeSpan
ATLTIME/ATL::CTimeSpan::GetTotalHours
ATLTIME/ATL::CTimeSpan::GetTotalMinutes
ATLTIME/ATL::CTimeSpan::GetTotalSeconds
ATLTIME/ATL::CTimeSpan::Serialize64
elapsed time, CTimeSpan object
timespan
time span
CTimeSpan class
shared classes, CTimeSpan
time, elapsed

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

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

[!code-cppNVC_ATLMFC_Utilities#169]

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

[!code-cppNVC_ATLMFC_Utilities#162]

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

[!code-cppNVC_ATLMFC_Utilities#163]

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

[!code-cppNVC_ATLMFC_Utilities#164]

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

[!code-cppNVC_ATLMFC_Utilities#165]

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

[!code-cppNVC_ATLMFC_Utilities#166]

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

[!code-cppNVC_ATLMFC_Utilities#167]

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

[!code-cppNVC_ATLMFC_Utilities#168]

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.

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