COleDateTimeSpan 类

表示相对时间，时间跨度。

语法

class COleDateTimeSpan

成员

公共构造函数

名称	描述
COleDateTimeSpan::COleDateTimeSpan	构造 COleDateTimeSpan 对象。

公共方法

名称	描述
COleDateTimeSpan::Format	生成 COleDateTimeSpan 对象的带格式字符串表示形式。
COleDateTimeSpan::GetDays	返回此 COleDateTimeSpan 对象表示的时间范围的日部分。
COleDateTimeSpan::GetHours	返回此 COleDateTimeSpan 对象表示的时间范围的小时部分。
COleDateTimeSpan::GetMinutes	返回此 COleDateTimeSpan 对象表示的时间范围的分钟部分。
COleDateTimeSpan::GetSeconds	返回此 COleDateTimeSpan 对象表示的时间范围的秒部分。
COleDateTimeSpan::GetStatus	获取此 COleDateTimeSpan 对象的状态（有效性）。
COleDateTimeSpan::GetTotalDays	返回此 COleDateTimeSpan 对象表示的天数。
COleDateTimeSpan::GetTotalHours	返回此 COleDateTimeSpan 对象表示的小时数。
COleDateTimeSpan::GetTotalMinutes	返回此 COleDateTimeSpan 对象表示的分钟数。
COleDateTimeSpan::GetTotalSeconds	返回此 COleDateTimeSpan 对象表示的秒数。
COleDateTimeSpan::SetDateTimeSpan	设置此 COleDateTimeSpan 对象的值。
COleDateTimeSpan::SetStatus	设置此 COleDateTimeSpan 对象的状态（有效性）。

公共运算符

“属性”	描述
operator +, -	COleDateTimeSpan 值的加号、减号和更改符号。
operator +=, -=	将 COleDateTimeSpan 值与此 COleDateTimeSpan 值相加和相减。
operator =	复制 COleDateTimeSpan 值。
operator ==, <, <=	比较两个 COleDateTimeSpan 值。
operator double	将此 COleDateTimeSpan 值转换为 double。

公共数据成员

“属性”	描述
COleDateTimeSpan::m_span	包含此 COleDateTimeSpan 对象的基础 double。
COleDateTimeSpan::m_status	包含此 COleDateTimeSpan 对象的状态。

备注

COleDateTimeSpan 没有基类。

COleDateTimeSpan 以天为单位保存时间。

COleDateTimeSpan 与其伴随类 COleDateTime 一起使用。 COleDateTime 封装 OLE 自动化的 DATE 数据类型。 COleDateTime 表示绝对时间值。 所有 COleDateTime 计算都涉及 COleDateTimeSpan 值。 这些类之间的关系类似于 CTime 与 CTimeSpan 之间的关系。

有关 COleDateTime 和 COleDateTimeSpan 类的详细信息，请参阅日期和时间：自动化支持一文。

要求

标头：ATLComTime.h

COleDateTimeSpan 关系运算符

比较运算符。

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();

参数

dateSpan
要比较的 COleDateTimeSpan。

返回值

这些运算符比较两个日期/时间范围值，如果条件为 true，则返回 TRUE，否则返回 FALSE。

备注

注意

如果任一操作数无效，则会发生 ATLASSERT。

示例

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

构造 COleDateTimeSpan 对象。

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

参数

dblSpanSrc
要复制到新 COleDateTimeSpan 对象中的天数。

lDays、nHours、nMins、nSecs
指示要复制到新 COleDateTimeSpan 对象中的日和时间值。

注解

所有这些构造函数将创建初始化为指定值的新 COleDateTimeSpan 对象。 下面是其中每个构造函数的简要说明：

• COleDateTimeSpan( ) 构造一个初始化为 0 的 COleDateTimeSpan 对象。

• COleDateTimeSpan(dblSpanSrc) 从浮点值构造一个 COleDateTimeSpan 对象。

• COleDateTimeSpan(lDays,nHours,nMins,nSecs) 构造一个初始化为指定数值的 COleDateTimeSpan 对象。

新 COleDateTimeSpan 对象的状态设置为有效。

有关 COleDateTimeSpan 值的边界的详细信息，请参阅日期和时间：自动化支持一文。

示例

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

生成 COleDateTimeSpan 对象的带格式字符串表示形式。

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

参数

pFormat
类似于 printf 格式字符串的格式字符串。 每个以百分号 (%) 开头的格式设置代码将由相应的 COleDateTimeSpan 组件替换。 格式字符串中的其他字符按原样复制到返回的字符串。 Format 的格式设置代码的值和含义如下：

• %H：当前日期的小时数

• %M：当前小时的分钟数

• %S：当前分钟的秒数

• %% 百分号

Format 仅接受上面列出的四种格式代码。

-

nID
格式控制字符串的资源 ID。

返回值

一个包含带格式日期/时间范围值的 CString。

备注

调用这些函数可创建时间范围值的带格式表示形式。 如果此 COleDateTimeSpan 对象的状态为 null，则返回值为空字符串。 如果状态无效，则返回字符串由字符串资源 IDS_INVALID_DATETIMESPAN 指定。

此函数的形式的简要说明如下：

Format(pFormat)
这种形式使用包含以百分号 (%) 开头的特殊格式设置代码的格式字符串来设置值的格式，与在 printf 中一样。 格式字符串作为参数传递给函数。

Format(nID)
这种形式使用包含以百分号 (%) 开头的特殊格式设置代码的格式字符串来设置值的格式，与在 printf 中一样。 格式字符串是一种资源。 此字符串资源的 ID 作为参数传递。

示例

// 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

检索此日期/时间范围值的日部分。

LONG GetDays() const throw();

返回值

此日期/时间范围值的日部分。

备注

此函数的返回值范围大约为 -3,615,000 到 3,615,000。

有关用于查询 COleDateTimeSpan 对象值的其他函数，请参阅以下成员函数：

• GetHours

• GetMinutes

• GetSeconds

• GetTotalDays

• GetTotalHours

• GetTotalMinutes

• GetTotalSeconds

示例

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

COleDateTimeSpan::GetHours

检索此日期/时间范围值的小时部分。

LONG GetHours() const throw();

返回值

此日期/时间范围值的小时部分。

备注

此函数的返回值范围为 -23 到 23。

有关用于查询 COleDateTimeSpan 对象值的其他函数，请参阅以下成员函数：

• GetDays

• GetMinutes

• GetSeconds

• GetTotalDays

• GetTotalHours

• GetTotalMinutes

• GetTotalSeconds

示例

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

COleDateTimeSpan::GetMinutes

检索此日期/时间范围值的分钟部分。

LONG GetMinutes() const throw();

返回值

此日期/时间范围值的分钟部分。

备注

此函数的返回值范围为 -59 到 59。

有关用于查询 COleDateTimeSpan 对象值的其他函数，请参阅以下成员函数：

• GetDays

• GetHours

• GetSeconds

• GetTotalDays

• GetTotalHours

• GetTotalMinutes

• GetTotalSeconds

示例

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

COleDateTimeSpan::GetSeconds

检索此日期/时间范围值的秒部分。

LONG GetSeconds() const throw();

返回值

此日期/时间范围值的秒部分。

注解

此函数的返回值范围为 -59 到 59。

有关用于查询 COleDateTimeSpan 对象值的其他函数，请参阅以下成员函数：

• GetDays

• GetHours

• GetMinutes

• GetTotalDays

• GetTotalHours

• GetTotalMinutes

• GetTotalSeconds

示例

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

COleDateTimeSpan::GetStatus

获取此 COleDateTimeSpan 对象的状态（有效性）。

DateTimeSpanStatus GetStatus() const throw();

返回值

此 COleDateTimeSpan 值的状态。

注解

返回值由 COleDateTimeSpan 类中定义的 DateTimeSpanStatus 枚举类型定义。

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

有关这些状态值的简要说明，请参阅以下列表：

• COleDateTimeSpan::valid 指示此 COleDateTimeSpan 对象有效。

• COleDateTimeSpan::invalid 指示此 COleDateTimeSpan 对象无效；也就是说，它的值可能不正确。

• COleDateTimeSpan::null 指示此 COleDateTimeSpan 对象为 null，也就是说，未为此对象提供值。 （与 C++ NULL 不同，此处的“null”是数据库意义上的“没有值”。）

COleDateTimeSpan 对象的状态在以下情况下无效：

• 如果此对象在算术赋值运算（即 += 或 -=）期间发生溢出或下溢。

• 如果为该对象赋了无效值。

• 如果使用 SetStatus 将此对象的状态显式设置为无效。

有关可将状态设置为无效的操作的详细信息，请参阅 COleDateTimeSpan::operator +, - 和 COleDateTimeSpan::operator +=, -=。

有关 COleDateTimeSpan 值的边界的详细信息，请参阅日期和时间：自动化支持一文。

COleDateTimeSpan::GetTotalDays

检索以天表示的此日期/时间范围值。

double GetTotalDays() const throw();

返回值

以天表示的此日期/时间范围值。 虽然此函数的原型是返回双精度值，但它始终返回整数值。

备注

此函数的返回值范围大约为 -3.65e6 到 3.65e6。

有关用于查询 COleDateTimeSpan 对象值的其他函数，请参阅以下成员函数：

• GetDays

• GetHours

• GetMinutes

• GetSeconds

• GetTotalHours

• GetTotalMinutes

• GetTotalSeconds

示例

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

检索以小时表示的此日期/时间范围值。

double GetTotalHours() const throw();

返回值

以小时表示的此日期/时间范围值。 虽然此函数的原型是返回双精度值，但它始终返回整数值。

备注

此函数的返回值范围大约为 -8.77e7 到 8.77e7。

有关用于查询 COleDateTimeSpan 对象值的其他函数，请参阅以下成员函数：

• GetDays

• GetHours

• GetMinutes

• GetSeconds

• GetTotalDays

• GetTotalMinutes

• GetTotalSeconds

示例

请参阅 GetTotalDays 的示例。

COleDateTimeSpan::GetTotalMinutes

检索以分钟表示的此日期/时间范围值。

double GetTotalMinutes() const throw();

返回值

以分钟表示的此日期/时间范围值。 虽然此函数的原型是返回双精度值，但它始终返回整数值。

注解

此函数的返回值范围大约为 -5.26e9 到 5.26e9。

有关用于查询 COleDateTimeSpan 对象值的其他函数，请参阅以下成员函数：

• GetDays

• GetHours

• GetMinutes

• GetSeconds

• GetTotalDays

• GetTotalHours

• GetTotalSeconds

示例

请参阅 GetTotalDays 的示例。

COleDateTimeSpan::GetTotalSeconds

检索以秒表示的此日期/时间范围值。

double GetTotalSeconds() const throw();

返回值

以秒表示的此日期/时间范围值。 虽然此函数的原型是返回双精度值，但它始终返回整数值。

注解

此函数的返回值范围大约为 -3.16e11 到 3.16e11。

有关用于查询 COleDateTimeSpan 对象值的其他函数，请参阅以下成员函数：

• GetDays

• GetHours

• GetMinutes

• GetSeconds

• GetTotalDays

• GetTotalHours

• GetTotalMinutes

示例

请参阅 GetTotalDays 的示例。

COleDateTimeSpan::m_span

此 COleDateTime 对象的基础 double 值。

double m_span;

注解

此值以天为单位表示日期/时间范围。

注意

更改 double 数据成员中的值会更改此 COleDateTimeSpan 对象的值。 这不会更改此 COleDateTimeSpan 对象的状态。

COleDateTimeSpan::m_status

此数据成员的类型是 COleDateTimeSpan 类中定义的枚举类型 DateTimeSpanStatus。

DateTimeSpanStatus m_status;

备注

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

有关这些状态值的简要说明，请参阅以下列表：

• COleDateTimeSpan::valid 指示此 COleDateTimeSpan 对象有效。

• COleDateTimeSpan::invalid 指示此 COleDateTimeSpan 对象无效；也就是说，它的值可能不正确。

• COleDateTimeSpan::null 指示此 COleDateTimeSpan 对象为 null，也就是说，未为此对象提供值。 （与 C++ NULL 不同，此处的“null”是数据库意义上的“没有值”。）

COleDateTimeSpan 对象的状态在以下情况下无效：

• 如果此对象在算术赋值运算（即 += 或 -=）期间发生溢出或下溢。

• 如果为该对象赋了无效值。

• 如果使用 SetStatus 将此对象的状态显式设置为无效。

有关可将状态设置为无效的操作的详细信息，请参阅 COleDateTimeSpan::operator +, - 和 COleDateTimeSpan::operator +=, -=。

注意

此数据成员用于高级编程。 应使用内联成员函数 GetStatus 和 SetStatus。 请参阅 SetStatus 了解有关显式设置此数据成员的其他注意事项。

有关 COleDateTimeSpan 值的边界的详细信息，请参阅日期和时间：自动化支持一文。

COleDateTimeSpan::operator =

复制 COleDateTimeSpan 值。

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

注解

此重载赋值运算符将源日期/时间范围值复制到此 COleDateTimeSpan 对象中。

COleDateTimeSpan::operator +, -

COleDateTimeSpan 值的加号、减号和更改符号。

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

备注

前两个运算符可用于将日期/时间范围值相加和相减。 第三个运算符可用于更改日期/时间范围值的符号。

如果任一操作数为 null，则得出的 COleDateTimeSpan 值的状态为 null。

如果任一操作数无效且另一个操作数不为 null，则得出的 COleDateTimeSpan 值的状态为无效。

有关有效、无效和 null 状态值的详细信息，请参阅 m_status 成员变量。

示例

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 +=, -=

将 COleDateTimeSpan 值与此 COleDateTimeSpan 值相加和相减。

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

备注

这些运算符可用于将此 COleDateTimeSpan 对象中的日期/时间范围值相加和相减。 如果任一操作数为 null，则得出的 COleDateTimeSpan 值的状态为 null。

如果任一操作数无效且另一个操作数不为 null，则得出的 COleDateTimeSpan 值的状态为无效。

有关有效、无效和 null 状态值的详细信息，请参阅 m_status 成员变量。

示例

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

COleDateTimeSpan::operator double

将此 COleDateTimeSpan 值转换为 double。

operator double() const throw();

备注

此运算符将此 COleDateTimeSpan 的值作为浮点天数返回。

COleDateTimeSpan::SetDateTimeSpan

设置此日期/时间范围的值。

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

参数

lDays、nHours、nMins、nSecs
指示要复制到此 COleDateTimeSpan 对象中的日期范围和时间范围值。

注解

有关用于查询 COleDateTimeSpan 对象值的函数，请参阅以下成员函数：

• GetDays

• GetHours

• GetMinutes

• GetSeconds

• GetTotalDays

• GetTotalHours

• GetTotalMinutes

• GetTotalSeconds

示例

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

设置此 COleDateTimeSpan 对象的状态（有效性）。

void SetStatus(DateTimeSpanStatus status) throw();

参数

status
此 COleDateTimeSpan 对象的新状态值。

注解

Status 参数值由 COleDateTimeSpan 类中定义的 DateTimeSpanStatus 枚举类型定义。

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

有关这些状态值的简要说明，请参阅以下列表：

• COleDateTimeSpan::valid 指示此 COleDateTimeSpan 对象有效。

• COleDateTimeSpan::invalid 指示此 COleDateTimeSpan 对象无效；也就是说，它的值可能不正确。

• COleDateTimeSpan::null 指示此 COleDateTimeSpan 对象为 null，也就是说，未为此对象提供值。 （与 C++ NULL 不同，此处的“null”是数据库意义上的“没有值”。）

  注意

  此函数用于高级编程。 此函数不会更改此对象中的数据。 它最常用于将状态设置为 null 或 invalid。 请注意，赋值运算符 (operator =) 和 SetDateTimeSpan 根据源值设置对象的状态。

示例

// 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);   

另请参阅

COleDateTime 类
CTime 类
CTimeSpan 类
层次结构图
ATL/MFC 共享类