COleDateTimeSpan Class

Article
12/01/2022

Represents a relative time, a time span.

Syntax

class COleDateTimeSpan

Members

Public Constructors

Name	Description
COleDateTimeSpan::COleDateTimeSpan	Constructs a `COleDateTimeSpan` object.

Public Methods

Name	Description
COleDateTimeSpan::Format	Generates a formatted string representation of a `COleDateTimeSpan` object.
COleDateTimeSpan::GetDays	Returns the day portion of the span this `COleDateTimeSpan` object represents.
COleDateTimeSpan::GetHours	Returns the hour portion of the span this `COleDateTimeSpan` object represents.
COleDateTimeSpan::GetMinutes	Returns the minute portion of the span this `COleDateTimeSpan` object represents.
COleDateTimeSpan::GetSeconds	Returns the second portion of the span this `COleDateTimeSpan` object represents.
COleDateTimeSpan::GetStatus	Gets the status (validity) of this `COleDateTimeSpan` object.
COleDateTimeSpan::GetTotalDays	Returns the number of days this `COleDateTimeSpan` object represents.
COleDateTimeSpan::GetTotalHours	Returns the number of hours this `COleDateTimeSpan` object represents.
COleDateTimeSpan::GetTotalMinutes	Returns the number of minutes this `COleDateTimeSpan` object represents.
COleDateTimeSpan::GetTotalSeconds	Returns the number of seconds this `COleDateTimeSpan` object represents.
COleDateTimeSpan::SetDateTimeSpan	Sets the value of this `COleDateTimeSpan` object.
COleDateTimeSpan::SetStatus	Sets the status (validity) of this `COleDateTimeSpan` object.

Public Operators

Name	Description
operator +, -	Add, subtract, and change sign for `COleDateTimeSpan` values.
operator +=, -=	Add and subtract a `COleDateTimeSpan` value from this `COleDateTimeSpan` value.
operator =	Copies a `COleDateTimeSpan` value.
operator ==, <, <=	Compare two `COleDateTimeSpan` values.
operator double	Converts this `COleDateTimeSpan` value to a `double`.

Public Data Members

Name	Description
COleDateTimeSpan::m_span	Contains the underlying `double` for this `COleDateTimeSpan` object.
COleDateTimeSpan::m_status	Contains the status of this `COleDateTimeSpan` object.

Remarks

COleDateTimeSpan does not have a base class.

A COleDateTimeSpan keeps time in days.

COleDateTimeSpan is used with its companion class COleDateTime. COleDateTime encapsulates the DATE data type of OLE automation. COleDateTime represents absolute time values. All COleDateTime calculations involve COleDateTimeSpan values. The relation between these classes is analogous to the one between CTime and CTimeSpan.

For more information on the COleDateTime and COleDateTimeSpan classes, see the article Date and Time: Automation Support.

Requirements

Header: ATLComTime.h

COleDateTimeSpan Relational Operators

Comparison operators.

bool operator==(const COleDateTimeSpan& dateSpan) const throw();
bool operator!=(const COleDateTimeSpan& dateSpan) const throw();
bool operator<(const COleDateTimeSpan& dateSpan) const throw();
bool operator>(const COleDateTimeSpan& dateSpan) const throw();
bool operator<=(const COleDateTimeSpan& dateSpan) const throw();
bool operator>=(const COleDateTimeSpan& dateSpan) const throw();

Parameters

dateSpan
The COleDateTimeSpan to compare.

Return Value

These operators compare two date/time-span values and return TRUE if the condition is true; otherwise FALSE.

Remarks

Note

An ATLASSERT will occur if either operand is invalid.

Example

COleDateTimeSpan spanOne(3, 12, 0, 0); // 3 days and 12 hours
COleDateTimeSpan spanTwo(spanOne);     // 3 days and 12 hours
BOOL b;
b = spanOne == spanTwo;                // TRUE
b = spanOne < spanTwo;                 // FALSE, same value
b = spanOne > spanTwo;                 // FALSE, same value
b = spanOne <= spanTwo;                // TRUE, same value
b = spanOne >= spanTwo;                // TRUE, same value   

spanTwo.SetStatus(COleDateTimeSpan::invalid);
b = spanOne == spanTwo;                // FALSE, different status
b = spanOne != spanTwo;                // TRUE, different status

COleDateTimeSpan ts1(100.0);   // one hundred days
COleDateTimeSpan ts2(110.0);   // ten more days

ASSERT((ts1 != ts2) && (ts1 < ts2) && (ts1 <= ts2));

COleDateTimeSpan::COleDateTimeSpan

Constructs a COleDateTimeSpan object.

COleDateTimeSpan() throw();
COleDateTimeSpan(double dblSpanSrc) throw();
COleDateTimeSpan(LONG lDays, int nHours, int nMins, int nSecs) throw();

Parameters

dblSpanSrc
The number of days to be copied into the new COleDateTimeSpan object.

lDays, nHours, nMins, nSecs
Indicate the day and time values to be copied into the new COleDateTimeSpan object.

Remarks

All of these constructors create new COleDateTimeSpan objects initialized to the specified value. A brief description of each of these constructors follows:

COleDateTimeSpan( ) Constructs a COleDateTimeSpan object initialized to 0.
COleDateTimeSpan( dblSpanSrc ) Constructs a COleDateTimeSpan object from a floating-point value.
COleDateTimeSpan( lDays, nHours, nMins, nSecs ) Constructs a COleDateTimeSpan object initialized to the specified numerical values.

The status of the new COleDateTimeSpan object is set to valid.

For more information about the bounds for COleDateTimeSpan values, see the article Date and Time: Automation Support.

Example

COleDateTimeSpan spanOne(2.75);          // 2 days and 18 hours
COleDateTimeSpan spanTwo(2, 18, 0, 0);   // 2 days and 18 hours
COleDateTimeSpan spanThree(3, -6, 0, 0); // 2 days and 18 hours

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

COleDateTimeSpan::Format

Generates a formatted string representation of a COleDateTimeSpan object.

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

Parameters

pFormat
A formatting string similar to the printf formatting string. Formatting codes, preceded by a percent (%) sign, are replaced by the corresponding COleDateTimeSpan 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:

%H Hours in the current day
%M Minutes in the current hour
%S Seconds in the current minute
%% Percent sign

The four format codes listed above are the only codes that Format will accept.

nID
The resource ID for the format-control string.

Return Value

A CString that contains the formatted date/time-span value.

Remarks

Call these functions to create a formatted representation of the time-span value. If the status of this COleDateTimeSpan object is null, the return value is an empty string. If the status is invalid, the return string is specified by the string resource IDS_INVALID_DATETIMESPAN.

A brief description of the forms for this function follows:

Format( pFormat )
This form formats the value using the format string that contains special formatting codes that are preceded by a percent sign (%), as in printf. The formatting string is passed as a parameter to the function.

Format( nID )
This form formats the value using the format string that contains special formatting codes that are preceded by a percent sign (%), as in printf. The formatting string is a resource. The ID of this string resource is passed as the parameter.

Example

// get the current time
COleDateTime tmStart = COleDateTime::GetCurrentTime();

// waste some time
CString str;
::Sleep(3000);

// get the current time again
COleDateTime tmFinish = COleDateTime::GetCurrentTime();

// find the difference
COleDateTimeSpan tmSpan = tmFinish - tmStart;

// tell the user
str = tmSpan.Format(_T("%S seconds elapsed"));
_tprintf_s(_T("%s\n"), (LPCTSTR) str);

COleDateTimeSpan::GetDays

Retrieves the day portion of this date/time-span value.

LONG GetDays() const throw();

Return Value

The day portion of this date/time-span value.

Remarks

The return values from this function range between approximately - 3,615,000 and 3,615,000.

For other functions that query the value of a COleDateTimeSpan object, see the following member functions:

GetHours
GetMinutes
GetSeconds
GetTotalDays
GetTotalHours
GetTotalMinutes
GetTotalSeconds

Example

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

COleDateTimeSpan::GetHours

Retrieves the hour portion of this date/time-span value.

LONG GetHours() const throw();

Return Value

The hours portion of this date/time-span value.

Remarks

The return values from this function range between - 23 and 23.

For other functions that query the value of a COleDateTimeSpan object, see the following member functions:

GetDays
GetMinutes
GetSeconds
GetTotalDays
GetTotalHours
GetTotalMinutes
GetTotalSeconds

Example

COleDateTimeSpan ts(3, 1, 5, 12); // 3 days, 1 hour, 5 min, and 12 sec
ASSERT(ts.GetHours() == 1);

COleDateTimeSpan::GetMinutes

Retrieves the minute portion of this date/time-span value.

LONG GetMinutes() const throw();

Return Value

The minutes portion of this date/time-span value.

Remarks

The return values from this function range between - 59 and 59.

For other functions that query the value of a COleDateTimeSpan object, see the following member functions:

GetDays
GetHours
GetSeconds
GetTotalDays
GetTotalHours
GetTotalMinutes
GetTotalSeconds

Example

COleDateTimeSpan ts(3, 1, 5, 12); // 3 days, 1 hour, 5 min, and 12 sec
ASSERT(ts.GetMinutes() == 5);

COleDateTimeSpan::GetSeconds

Retrieves the second portion of this date/time-span value.

LONG GetSeconds() const throw();

Return Value

The seconds portion of this date/time-span value.

Remarks

The return values from this function range between - 59 and 59.

For other functions that query the value of a COleDateTimeSpan object, see the following member functions:

GetDays
GetHours
GetMinutes
GetTotalDays
GetTotalHours
GetTotalMinutes
GetTotalSeconds

Example

COleDateTimeSpan ts(3, 1, 5, 12); // 3 days, 1 hour, 5 min, and 12 sec
ASSERT(ts.GetSeconds() == 12);

COleDateTimeSpan::GetStatus

Gets the status (validity) of this COleDateTimeSpan object.

DateTimeSpanStatus GetStatus() const throw();

Return Value

The status of this COleDateTimeSpan value.

Remarks

The return value is defined by the DateTimeSpanStatus enumerated type, which is defined within the COleDateTimeSpan class.

enum DateTimeSpanStatus{
   valid = 0,
   invalid = 1,
   null = 2,
};

For a brief description of these status values, see the following list:

COleDateTimeSpan::valid Indicates that this COleDateTimeSpan object is valid.
COleDateTimeSpan::invalid Indicates that this COleDateTimeSpan object is invalid; that is, its value may be incorrect.
COleDateTimeSpan::null Indicates that this COleDateTimeSpan object is null, that is, that no value has been supplied for this object. (This is "null" in the database sense of "having no value," as opposed to the C++ NULL.)

The status of a COleDateTimeSpan object is invalid in the following cases:

If this object has experienced an overflow or underflow during an arithmetic assignment operation, namely, += or -=.
If an invalid value was assigned to this object.
If the status of this object was explicitly set to invalid using SetStatus.

For more information about the operations that may set the status to invalid, see COleDateTimeSpan::operator +, - and COleDateTimeSpan::operator +=, -=.

For more information about the bounds for COleDateTimeSpan values, see the article Date and Time: Automation Support.

COleDateTimeSpan::GetTotalDays

Retrieves this date/time-span value expressed in days.

double GetTotalDays() const throw();

Return Value

This date/time-span value expressed in days. Although this function is prototyped to return a double, it will always return an integer value.

Remarks

The return values from this function range between approximately - 3.65e6 and 3.65e6.

For other functions that query the value of a COleDateTimeSpan object, see the following member functions:

GetDays
GetHours
GetMinutes
GetSeconds
GetTotalHours
GetTotalMinutes
GetTotalSeconds

Example

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

COleDateTimeSpan::GetTotalHours

Retrieves this date/time-span value expressed in hours.

double GetTotalHours() const throw();

Return Value

This date/time-span value expressed in hours. Although this function is prototyped to return a double, it will always return an integer value.

Remarks

The return values from this function range between approximately - 8.77e7 and 8.77e7.

For other functions that query the value of a COleDateTimeSpan object, see the following member functions:

GetDays
GetHours
GetMinutes
GetSeconds
GetTotalDays
GetTotalMinutes
GetTotalSeconds

Example

See the example for GetTotalDays.

COleDateTimeSpan::GetTotalMinutes

Retrieves this date/time-span value expressed in minutes.

double GetTotalMinutes() const throw();

Return Value

This date/time-span value expressed in minutes. Although this function is prototyped to return a double, it will always return an integer value.

Remarks

The return values from this function range between approximately - 5.26e9 and 5.26e9.

For other functions that query the value of a COleDateTimeSpan object, see the following member functions:

GetDays
GetHours
GetMinutes
GetSeconds
GetTotalDays
GetTotalHours
GetTotalSeconds

Example

See the example for GetTotalDays.

COleDateTimeSpan::GetTotalSeconds

Retrieves this date/time-span value expressed in seconds.

double GetTotalSeconds() const throw();

Return Value

This date/time-span value expressed in seconds. Although this function is prototyped to return a double, it will always return an integer value.

Remarks

The return values from this function range between approximately - 3.16e11 to 3.16e11.

For other functions that query the value of a COleDateTimeSpan object, see the following member functions:

GetDays
GetHours
GetMinutes
GetSeconds
GetTotalDays
GetTotalHours
GetTotalMinutes

Example

See the example for GetTotalDays.

COleDateTimeSpan::m_span

The underlying double value for this COleDateTime object.

double m_span;

Remarks

This value expresses the date/time-span in days.

Caution

Changing the value in the double data member will change the value of this COleDateTimeSpan object. It does not change the status of this COleDateTimeSpan object.

COleDateTimeSpan::m_status

The type for this data member is the enumerated type DateTimeSpanStatus, which is defined within the COleDateTimeSpan class.

DateTimeSpanStatus m_status;

Remarks

enum DateTimeSpanStatus{
   valid = 0,
   invalid = 1,
   null = 2,
   };

For a brief description of these status values, see the following list:

COleDateTimeSpan::valid Indicates that this COleDateTimeSpan object is valid.
COleDateTimeSpan::invalid Indicates that this COleDateTimeSpan object is invalid; that is, its value may be incorrect.
COleDateTimeSpan::null Indicates that this COleDateTimeSpan object is null, that is, that no value has been supplied for this object. (This is "null" in the database sense of "having no value," as opposed to the C++ NULL.)

The status of a COleDateTimeSpan object is invalid in the following cases:

If this object has experienced an overflow or underflow during an arithmetic assignment operation, namely, += or -=.
If an invalid value was assigned to this object.
If the status of this object was explicitly set to invalid using SetStatus.

For more information about the operations that may set the status to invalid, see COleDateTimeSpan::operator +, - and COleDateTimeSpan::operator +=, -=.

Caution

This data member is for advanced programming situations. You should use the inline member functions GetStatus and SetStatus. See SetStatus for further cautions regarding explicitly setting this data member.

For more information about the bounds for COleDateTimeSpan values, see the article Date and Time: Automation Support.

COleDateTimeSpan::operator =

Copies a COleDateTimeSpan value.

COleDateTimeSpan& operator=(double dblSpanSrc) throw();

Remarks

This overloaded assignment operator copies the source date/time-span value into this COleDateTimeSpan object.

COleDateTimeSpan::operator +, -

Add, subtract, and change sign for COleDateTimeSpan values.

COleDateTimeSpan operator+(const COleDateTimeSpan& dateSpan) const throw();
COleDateTimeSpan operator-(const COleDateTimeSpan& dateSpan) const throw();
COleDateTimeSpan operator-() const throw();

Remarks

The first two operators let you add and subtract date/time-span values. The third lets you change the sign of a date/time-span value.

If either of the operands is null, the status of the resulting COleDateTimeSpan value is null.

If either of the operands is invalid and the other is not null, the status of the resulting COleDateTimeSpan value is invalid.

For more information on the valid, invalid, and null status values, see the m_status member variable.

Example

COleDateTimeSpan ts1(3, 1, 5, 12); // 3 days, 1 hour, 5 min, and 12 sec
COleDateTimeSpan ts2(100.0 / (24 * 3600.0)); // 100 seconds
COleDateTimeSpan ts3 = ts1 + ts2;
ASSERT(ts3.GetSeconds() == 52); // 6 mins, 52 secs

COleDateTimeSpan::operator +=, -=

Add and subtract a COleDateTimeSpan value from this COleDateTimeSpan value.

COleDateTimeSpan& operator+=(const COleDateTimeSpan dateSpan) throw();
COleDateTimeSpan& operator-=(const COleDateTimeSpan dateSpan) throw();

Remarks

These operators let you add and subtract date/time-span values from this COleDateTimeSpan object. If either of the operands is null, the status of the resulting COleDateTimeSpan value is null.

If either of the operands is invalid and the other is not null, the status of the resulting COleDateTimeSpan value is invalid.

For more information on the valid, invalid, and null status values, see the m_status member variable.

Example

COleDateTimeSpan ts1(10.0); // 10 days
COleDateTimeSpan ts2(100.0); // 100 days
ts2 -= ts1;
ASSERT(ts2.GetTotalDays() == 90);

COleDateTimeSpan::operator double

Converts this COleDateTimeSpan value to a double.

operator double() const throw();

Remarks

This operator returns the value of this COleDateTimeSpan value as a floating-point number of days.

COleDateTimeSpan::SetDateTimeSpan

Sets the value of this date/time-span value.

void SetDateTimeSpan(LONG lDays, int nHours, int nMins, int nSecs) throw();

Parameters

lDays, nHours, nMins, nSecs
Indicate the date-span and time-span values to be copied into this COleDateTimeSpan object.

Remarks

For functions that query the value of a COleDateTimeSpan object, see the following member functions:

GetDays
GetHours
GetMinutes
GetSeconds
GetTotalDays
GetTotalHours
GetTotalMinutes
GetTotalSeconds

Example

COleDateTimeSpan spanOne;
COleDateTimeSpan spanTwo;
spanOne.SetDateTimeSpan(0, 2, 45, 0);  // 2 hours and 45 seconds
spanTwo.SetDateTimeSpan(0, 3, -15, 0); // 2 hours and 45 seconds

COleDateTimeSpan::SetStatus

Sets the status (validity) of this COleDateTimeSpan object.

void SetStatus(DateTimeSpanStatus status) throw();

Parameters

status
The new status value for this COleDateTimeSpan object.

Remarks

The Status parameter value is defined by the DateTimeSpanStatus enumerated type, which is defined within the COleDateTimeSpan class.

enum DateTimeSpanStatus{
   valid = 0,
   invalid = 1,
   null = 2,
   };

For a brief description of these status values, see the following list:

COleDateTimeSpan::valid Indicates that this COleDateTimeSpan object is valid.
COleDateTimeSpan::invalid Indicates that this COleDateTimeSpan object is invalid; that is, its value may be incorrect.
COleDateTimeSpan::null Indicates that this COleDateTimeSpan object is null, that is, that no value has been supplied for this object. (This is "null" in the database sense of "having no value," as opposed to the C++ NULL.)

Caution

This function is for advanced programming situations. This function does not alter the data in this object. It will most often be used to set the status to null or invalid. Note that the assignment operator (operator =) and SetDateTimeSpan do set the status of the object based on the source value(s).

Example

// if the person is not still in school, set days to graduation to null
if (!m_bStillInSchool || m_dtDateOfGraduation.GetStatus() == COleDateTime::null)
   m_dtsDaysToGraduation.SetStatus(COleDateTimeSpan::null);