COleDateTime 类

封装 OLE 自动化中使用的 DATE 数据类型。

语法

class COleDateTime

成员

公共构造函数

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

公共方法

名称 描述
COleDateTime::Format 生成 COleDateTime 对象的带格式字符串表示形式。
COleDateTime::GetAsDBTIMESTAMP 调用此方法可获取 COleDateTime 对象中的、DBTIMESTAMP 数据结构形式的时间。
COleDateTime::GetAsSystemTime 调用此方法可获取 COleDateTime 对象中的、SYSTEMTIME 数据结构形式的时间。
COleDateTime::GetAsUDATE 调用此方法可获取 COleDateTime 中的、UDATE 数据结构形式的时间。
COleDateTime::GetCurrentTime 创建一个表示当前时间的 COleDateTime 对象(静态成员函数)。
COleDateTime::GetDay 返回此 COleDateTime 对象表示的月份日期 (1 - 31)。
COleDateTime::GetDayOfWeek 返回此 COleDateTime 对象表示的星期(星期日 = 1)。
COleDateTime::GetDayOfYear 返回此 COleDateTime 对象表示的一年中日期(1 月 1 日 = 1)。
COleDateTime::GetHour 返回此 COleDateTime 对象表示的小时 (0 - 23)。
COleDateTime::GetMinute 返回此 COleDateTime 对象表示的分钟 (0 - 59)。
COleDateTime::GetMonth 返回此 COleDateTime 对象表示的月份 (1 - 12)。
COleDateTime::GetSecond 返回此 COleDateTime 对象表示的秒 (0 - 59)。
COleDateTime::GetStatus 获取此 COleDateTime 对象的状态(有效性)。
COleDateTime::GetYear 返回此 COleDateTime 对象表示的年份。
COleDateTime::ParseDateTime 从字符串中读取日期/时间值并设置 COleDateTime 的值。
COleDateTime::SetDate 将此 COleDateTime 对象的值设置为指定的仅限日期值。
COleDateTime::SetDateTime 将此 COleDateTime 对象的值设置为指定的日期/时间值。
COleDateTime::SetStatus 设置此 COleDateTime 对象的状态(有效性)。
COleDateTime::SetTime 将此 COleDateTime 对象的值设置为指定的仅限时间值。

公共运算符

“属性” 描述
COleDateTime::operator ==, COleDateTime::operator < 等 比较两个 COleDateTime 值。
COleDateTime::operator +, COleDateTime::operator - COleDateTime 值相加和相减。
COleDateTime::operator +=, COleDateTime::operator -= 在此 COleDateTime 对象中加减 COleDateTime 值。
COleDateTime::operator = 复制 COleDateTime 值。
COleDateTime::operator DATE, COleDateTime::operator Date* COleDateTime 值转换为 DATEDATE*

公共数据成员

“属性” 描述
COleDateTime::m_dt 包含此 COleDateTime 对象的基础 DATE
COleDateTime::m_status 包含此 COleDateTime 对象的状态。

备注

COleDateTime 没有基类。

它是 OLE 自动化的 VARIANT 数据类型的可能类型之一。 COleDateTime 值表示绝对日期和时间值。

DATE 类型实现为浮点值。 天数从 1899 年 12 月 30 日午夜开始计量。 下表显示了一些日期及其关联值:

Date
1899 年 12 月 29 日午夜 -1.0
1899 年 12 月 29 日上午 6 点 -1.25
1899 年 12 月 30 日午夜 0.0
1899 年 12 月 31 日午夜 1.0
1900 年 1 月 1 日上午 6 点 2.25

注意

在上表中,虽然日期值在 1899 年 12 月 30 日午夜之前变为负数,但时间值不会。 例如,无论表示日期的整数是正数(1899 年 12 月 30 日之后)还是负数(1899 年 12 月 30 日之前),上午 6:00 始终由小数值 0.25 表示。 这意味着,简单的浮点比较会错误地将表示 1899 年 12 月 29 日上午 6:00 的 COleDateTime 排序在表示同一日上午 7:00 的相应类的后面

COleDateTime 类处理从 100 年 1 月 1 日到 9999 年 12 月 31 日的日期。 COleDateTime 类使用公历;它不支持儒略历日期。 COleDateTime 忽略夏令时。 (请参阅日期和时间:自动化支持。)

注意

可以使用 %y 格式来仅检索从 1900 开始的日期的两位数年份。 如果对 1900 年之前的日期使用 %y 格式,则代码会生成 ASSERT 失败。

此类型还用于表示仅限日期或仅限时间的值。 按照惯例,日期 0(1899 年 12 月 30 日)用于仅限时间的值,时间 00:00(午夜)用于仅限日期的值。

如果使用小于 100 的日期创建 COleDateTime 对象,则会接受该日期,但对 GetYearGetMonthGetDayGetHourGetMinuteGetSecond 的后续调用将会失败并返回 -1。 以前,你可以使用两位数日期,但在 MFC 4.2 和更高版本中,日期必须为 100 或更大。

为了避免出现问题,请指定四位数日期。 例如:

COleDateTime mytime(1996, 1, 1, 0, 0, 0); 

COleDateTime 值的基本算术运算使用伴随类 COleDateTimeSpanCOleDateTimeSpan 值定义时间间隔。 这些类之间的关系类似于 CTimeCTimeSpan 之间的关系。

有关 COleDateTimeCOleDateTimeSpan 类的详细信息,请参阅日期和时间:自动化支持一文。

要求

标头:ATLComTime.h

COleDateTime 关系运算符

比较运算符。

bool operator==(const COleDateTime& date) const throw();
bool operator!=(const COleDateTime& date) const throw();
bool operator<(const COleDateTime& date) const throw();
bool operator>(const COleDateTime& date) const throw();
bool operator<=(const COleDateTime& date) const throw();
bool operator>=(const COleDateTime& date) const throw();

参数

date
要比较的 COleDateTime 对象。

备注

注意

如果两个操作数中的任何一个无效,则会发生 ATLASSERT。

示例

COleDateTime dateOne(1995, 3, 15, 12, 0, 0); // 15 March 1995 12 noon
COleDateTime dateTwo(dateOne);             // 15 March 1995 12 noon
BOOL b;
b = dateOne == dateTwo;                    // TRUE
b = dateOne < dateTwo;                     // FALSE, same value
b = dateOne > dateTwo;                     // FALSE, same value
b = dateOne <= dateTwo;                    // TRUE, same value
b = dateOne >= dateTwo;                    // TRUE, same value   

dateTwo.SetStatus(COleDateTime::invalid);
b = dateOne == dateTwo;                    // FALSE, different status
b = dateOne != dateTwo;                    // TRUE, different status

运算符 >=、<=、>< 将断言 COleDateTime 对象是否设置为 null

VARIANT v = {};
v.vt = VT_NULL;
COleDateTime t1(v);
COleDateTime t2(v);
t1 = t1 + t2;

COleDateTime::COleDateTime

构造 COleDateTime 对象。

COleDateTime() throw();
COleDateTime(const VARIANT& varSrc) throw();
COleDateTime(DATE dtSrc) throw();
COleDateTime(time_t timeSrc) throw();
COleDateTime(__time64_t timeSrc) throw();
COleDateTime(const SYSTEMTIME& systimeSrc) throw();
COleDateTime(const FILETIME& filetimeSrc) throw();

COleDateTime(int nYear,
    int nMonth,
    int nDay,
    int nHour,
    int nMin,
    int nSec) throw();

COleDateTime(WORD wDosDate,
    WORD wDosTime) throw();
COleDateTime(const DBTIMESTAMP& timeStamp) throw();

参数

dateSrc
要复制到新 COleDateTime 对象中的现有 COleDateTime 对象。

varSrc
要转换为日期/时间值 (VT_DATE) 并复制到新 COleDateTime 对象中的现有 VARIANT 数据结构(可能是 COleVariant 对象)。

dtSrc
要复制到新 COleDateTime 对象中的日期/时间 (DATE) 值。

timeSrc
要转换为日期/时间值并复制到新 COleDateTime 对象中的 time_t__time64_t 值。

systimeSrc
要转换为日期/时间值并复制到新 COleDateTime 对象中的 SYSTEMTIME 结构。

filetimeSrc
要转换为日期/时间值并复制到新 COleDateTime 对象中的 FILETIME 结构。 FILETIME 使用协调世界时 (UTC),因此如果在结构中传递本地时间,结果将不正确。 有关详细信息,请参阅 Windows SDK 中的文件时间

nYear、nMonth、nDay、nHour、nMin、nSec
指示要复制到新 COleDateTime 对象中的日期和时间值。

wDosDate、wDosTime
要转换为日期/时间值并复制到新 COleDateTime 对象中的 MS-DOS 日期和时间值。

timeStamp
对包含当前本地时间的 DBTimeStamp 结构的引用。

备注

所有这些构造函数将创建初始化为指定值的新 COleDateTime 对象。 下表显示了每个日期和时间组件的有效范围:

日期/时间组件 有效范围
year 100 - 9999
0 - 12
day 0 - 31
hour 0 - 23
minute 0 - 59
second 0 - 59

请注意,日组件的实际上限因月和年组件而异。 有关详细信息,请参阅 SetDateSetDateTime 成员函数。

下面是每个构造函数的简要说明:

  • COleDateTime(COleDateTime构造初始化为 0 的对象(1899 年 12 月 30 日午夜)。

  • COleDateTime(dateSrc COleDateTime从现有COleDateTime对象构造对象。

  • COleDateTime(varSrc 构造对象COleDateTime。 尝试将 VARIANT 结构或 COleVariant 对象转换为日期/时间 (VT_DATE) 值。 如果这种转换成功,则转换后的值将复制到新的 COleDateTime 对象中。 否则,COleDateTime 对象的值将设置为 0(1899 年 12 月 30 日午夜),并且其状态将设置为无效。

  • COleDateTime(dtSrc COleDateTimeDATE值构造对象。

  • COleDateTime(timeSrc COleDateTimetime_t值构造对象。

  • COleDateTime(systimeSrc COleDateTimeSYSTEMTIME值构造对象。

  • COleDateTime(filetimeSrc COleDateTimeFILETIME值构造对象。 。 FILETIME 使用协调世界时 (UTC),因此如果在结构中传递本地时间,结果将不正确。 有关详细信息,请参阅 Windows SDK 中的文件时间

  • COleDateTime(nYear、、nMonthnHournDaynMin、 ) nSec 从指定的数值构造对象。COleDateTime

  • COleDateTime(wDosDatewDosTime 从指定的 MS-DOS 日期和时间值构造对象COleDateTime

有关 time_t 数据类型的详细信息,请参阅运行时库参考中的 time 函数。

有关详细信息,请参阅 Windows SDK 中的 SYSTEMTIMEFILETIME 结构。

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

注意

仅当包含 OLEDB.h 时,使用 DBTIMESTAMP 参数的构造函数才可用。

示例

time_t osBinaryTime;   // C run-time time (defined in <time.h>)
time(&osBinaryTime);   // Get the current time from the 
                     // operating system.

COleDateTime time1;   // initialized to 00:00am, 30 December 1899
                     // (and m_nStatus is valid!)

COleDateTime time2 = time1; // Copy constructor
COleDateTime time3(osBinaryTime);   // from time_t
COleDateTime time4(1999, 3, 19, 22, 15, 0); // 10:15PM March 19, 1999

SYSTEMTIME sysTime;   // Win32 time information
GetSystemTime(&sysTime);

COleDateTime time5(sysTime);    

COleDateTime::Format

创建日期/时间值的带格式表示形式。

CString Format(DWORD dwFlags = 0,  LCID lcid = LANG_USER_DEFAULT) const;
CString Format(LPCTSTR lpszFormat) const;
CString Format(UINT nFormatID) const;

参数

dwFlags
指示以下区域设置标志之一:

  • LOCALE_NOUSEROVERRIDE:使用系统默认区域设置,而不是自定义的用户设置。

  • VAR_TIMEVALUEONLY:在分析期间忽略日期部分。

  • VAR_DATEVALUEONLY:在分析期间忽略时间部分。

lcid
指示用于转换的区域设置 ID。 有关语言标识符的详细信息,请参阅语言标识符

lpszFormat
类似于 printf 格式字符串的格式字符串。 每个以百分号 (%) 开头的格式设置代码将由相应的 COleDateTime 组件替换。 格式字符串中的其他字符按原样复制到返回的字符串。 有关详细信息,请参阅运行时函数 strftimeFormat 的格式设置代码的值和含义如下:

  • %H 当前日期的小时数

  • %M 当前小时的分钟数

  • %S 当前分钟的秒数

  • %% 百分号

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

返回值

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

注解

如果此 COleDateTime 对象的状态为 null,则返回值为空字符串。 如果状态无效,则返回字符串由字符串资源 ATL_IDS_DATETIME_INVALID 指定。

此函数的三种形式的简要说明如下:

Format(dwFlags, lcid)
这种形式使用日期和时间的语言规范(区域设置 ID)来设置值的格式。 这种形式使用默认参数输出日期和时间,除非:时间部分是 0(午夜),在这种情况下,它只输出日期;日期部分是 0(1899 年 12 月 30 日),在这种情况下,它只输出时间。 如果日期/时间值为 0(1899 年 12 月 30 日午夜),则这种使用默认参数的形式将输出午夜。

Format(lpszFormat)
这种形式使用包含以百分号 (%) 开头的特殊格式设置代码的格式字符串来设置值的格式,与在 printf 中一样。 格式字符串作为参数传递给函数。 有关格式设置代码的详细信息,请参阅运行时库参考中的 strftime、wcsftime

Format(nFormatID)
这种形式使用包含以百分号 (%) 开头的特殊格式设置代码的格式字符串来设置值的格式,与在 printf 中一样。 格式字符串是一种资源。 此字符串资源的 ID 作为参数传递。 有关格式设置代码的详细信息,请参阅运行时库参考中的 strftime、wcsftime

示例

COleDateTime t(1999, 3, 19, 22, 15, 0);

CString str = t.Format(_T("%A, %B %d, %Y"));
ASSERT(str == _T("Friday, March 19, 1999"));   

COleDateTime::GetAsDBTIMESTAMP

调用此方法可获取 COleDateTime 对象中的、DBTIMESTAMP 数据结构形式的时间。

bool GetAsDBTIMESTAMP(DBTIMESTAMP& timeStamp) const throw();

参数

timeStamp
DBTimeStamp 结构的引用。

返回值

如果成功,则不为 0;否则为 0。

注解

将得到的时间存储在被引用的 timeStamp 结构中。 此函数初始化的 DBTIMESTAMP 数据结构的 fraction 成员设置为零。

示例

COleDateTime t = COleDateTime::GetCurrentTime();
DBTIMESTAMP ts;
t.GetAsDBTIMESTAMP(ts); // retrieves the time in t into the ts structure

COleDateTime::GetAsSystemTime

调用此方法可获取 COleDateTime 对象中的、SYSTEMTIME 数据结构形式的时间。

bool GetAsSystemTime(SYSTEMTIME& sysTime) const throw();

参数

sysTime
SYSTEMTIME 结构的引用,用于从 COleDateTime 对象中接收转换后的日期/时间值。

返回值

如果成功,则返回 TRUE;如果转换失败,或者 COleDateTime 对象为 NULL 或无效,则返回 FALSE。

备注

GetAsSystemTime 将得到的时间存储在被引用的 sysTime 对象中。 此函数初始化的 SYSTEMTIME 数据结构的 wMilliseconds 成员设置为零。

有关 COleDateTime 对象中保存的状态信息的详细信息,请参阅 GetStatus

COleDateTime::GetAsUDATE

调用此方法可获取 COleDateTime 对象中的、UDATE 数据结构形式的时间。

bool GetAsUDATE(UDATE& uDate) const throw();

参数

uDate
UDATE 结构的引用,用于从 COleDateTime 对象中接收转换后的日期/时间值。

返回值

如果成功,则返回 TRUE;如果转换失败,或者 COleDateTime 对象为 NULL 或无效,则返回 FALSE。

注解

UDATE 结构表示“解包”日期。

COleDateTime::GetCurrentTime

调用此静态成员函数可返回当前日期/时间值。

static COleDateTime WINAPI GetCurrentTime() throw();

示例

// example for COleDateTime::GetCurrentTime
COleDateTime dateTest;
   // dateTest value = midnight 30 December 1899

dateTest = COleDateTime::GetCurrentTime();
   // dateTest value = current date and time

// a second example for COleDateTime::GetCurrentTime
// Since GetCurrentTime() is a static member, you can use it in
// a constructor:

COleDateTime t1 = COleDateTime::GetCurrentTime();
COleDateTime t2(COleDateTime::GetCurrentTime());

// Or in a normal assignment operator

COleDateTime t3;
t3 = COleDateTime::GetCurrentTime();

// or even in an expression

 if (COleDateTime::GetCurrentTime().GetDayOfWeek() == 6)
    _tprintf(_T("Thank Goodness it is Friday!\n\n"));   

COleDateTime::GetDay

获取此日期/时间值表示的月份日期。

int GetDay() const throw();

返回值

返回此 COleDateTime 对象的值表示的月份日期;如果无法获取日期,则返回 COleDateTime::error

注解

有效的返回值范围为 1 到 31。

有关用于查询此 COleDateTime 对象的值的其他成员函数的信息,请参阅以下成员函数:

示例

COleDateTime t(1999, 3, 19, 22, 15, 0);  // 10:15PM March 19, 1999
ASSERT(t.GetDay() == 19);
ASSERT(t.GetMonth() == 3);
ASSERT(t.GetYear() == 1999);   

COleDateTime::GetDayOfWeek

获取此日期/时间值表示的星期。

int GetDayOfWeek() const throw();

返回值

返回此 COleDateTime 对象的值表示的星期;如果无法获取星期,则返回 COleDateTime::error

备注

有效的返回值范围为 1 到 7,其中 1 = 星期日,2 = 星期一,依此类推。

有关用于查询此 COleDateTime 对象的值的其他成员函数的信息,请参阅以下成员函数:

示例

COleDateTime t(1999, 3, 19, 22, 15, 0); // 10:15PM March 19, 1999
ASSERT(t.GetDayOfWeek() == 6);          // it's a Friday   

COleDateTime::GetDayOfYear

获取此日期/时间值表示的年份日期。

int GetDayOfYear() const throw();

返回值

返回此 COleDateTime 对象的值表示的年份日期;如果无法获取年份日期,则返回 COleDateTime::error

备注

有效的返回值范围为 1 到 366,其中 1 月 1 日 = 1。

有关用于查询此 COleDateTime 对象的值的其他成员函数的信息,请参阅以下成员函数:

示例

COleDateTime t(1999, 3, 19, 22, 15, 0); // 10:15PM March 19, 1999
ASSERT(t.GetDayOfYear() == 78);         // 78th day of that year   

COleDateTime::GetHour

获取此日期/时间值表示的小时。

int GetHour() const throw();

返回值

返回此 COleDateTime 对象的值表示的小时;如果无法获取小时,则返回 COleDateTime::error

备注

有效的返回值范围为 0 到 23。

有关用于查询此 COleDateTime 对象的值的其他成员函数的信息,请参阅以下成员函数:

示例

COleDateTime t(1999, 3, 19, 22, 15, 0);  // 10:15PM March 19, 1999
ASSERT(t.GetSecond() == 0);
ASSERT(t.GetMinute() == 15);
ASSERT(t.GetHour() == 22);   

COleDateTime::GetMinute

获取此日期/时间值表示的分钟。

int GetMinute() const throw();

返回值

返回此 COleDateTime 对象的值表示的分钟;如果无法获取分钟,则返回 COleDateTime::error

注解

有效的返回值范围为 0 到 59。

有关用于查询此 COleDateTime 对象的值的其他成员函数的信息,请参阅以下成员函数:

示例

请参阅 GetHour 的示例。

COleDateTime::GetMonth

获取此日期/时间值表示的月份。

int GetMonth() const throw();

返回值

返回此 COleDateTime 对象的值表示的月份;如果无法获取月份,则返回 COleDateTime::error

注解

有效的返回值范围为 1 到 12。

有关用于查询此 COleDateTime 对象的值的其他成员函数的信息,请参阅以下成员函数:

示例

请参阅 GetDay 的示例。

COleDateTime::GetSecond

获取此日期/时间值表示的秒。

int GetSecond() const throw();

返回值

返回此 COleDateTime 对象的值表示的秒;如果无法获取秒,则返回 COleDateTime::error

备注

有效的返回值范围为 0 到 59。

注意

COleDateTime 类不支持闰秒。

有关 COleDateTime 的实现的详细信息,请参阅日期和时间:自动化支持一文。

有关用于查询此 COleDateTime 对象的值的其他成员函数的信息,请参阅以下成员函数:

示例

请参阅 GetHour 的示例。

COleDateTime::GetStatus

获取给定 COleDateTime 对象的状态(有效性)。

DateTimeStatus GetStatus() const throw();

返回值

返回此 COleDateTime 值的状态。 如果对使用默认值构造的 COleDateTime 对象调用 GetStatus,它将返回 valid。 如果对使用设置为 null 的构造函数初始化的 COleDateTime 对象调用 GetStatus,则 GetStatus 将返回 null。

注解

返回值由 COleDateTime 类中定义的 DateTimeStatus 枚举类型定义。

enum DateTimeStatus
{
   error = -1,
   valid = 0,
   invalid = 1,    // Invalid date (out of range, etc.)
   null = 2,       // Literally has no value
};

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

  • COleDateTime::error 指示尝试获取日期/时间值部分时出错。

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

  • COleDateTime::invalid 指示此 COleDateTime 对象无效;也就是说,它的值可能不正确。

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

COleDateTime 对象的状态在以下情况下无效:

  • 如果其值是从无法转换为日期/时间值的 VARIANTCOleVariant 值设置的。

  • 如果其值是从无法转换为有效日期/时间值的 time_tSYSTEMTIMEFILETIME 值设置的。

  • 如果其值是由 SetDateTime 使用无效参数值设置的。

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

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

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

有关可能将状态设置为无效的运算的详细信息,请参阅以下成员函数:

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

示例

COleDateTime t;

// this one is a leap year
t.SetDateTime(2000, 2, 29, 5, 0, 0);
ASSERT(t.GetStatus() == COleDateTime::valid);

// this date isn't valid
t.SetDateTime(1925, 2, 30, 5, 0, 0);
ASSERT(t.GetStatus() == COleDateTime::invalid);

// the only way to set null is to set null!
t.SetStatus(COleDateTime::null);
ASSERT(t.GetStatus() == COleDateTime::null);   

COleDateTime::GetYear

获取此日期/时间值表示的年份。

int GetYear() const throw();

返回值

返回此 COleDateTime 对象的值表示的年份;如果无法获取年份,则返回 COleDateTime::error

备注

有效的返回值范围为 100 到 9999,包括世纪。

有关用于查询此 COleDateTime 对象的值的其他成员函数的信息,请参阅以下成员函数:

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

示例

请参阅 GetDay 的示例。

COleDateTime::m_dt

COleDateTime 对象的基础 DATE 结构。

DATE m_dt;

注解

注意

更改此函数返回的指针所访问的 DATE 对象中的值会更改此 COleDateTime 对象的值。 这不会更改此 COleDateTime 对象的状态。

有关 DATE 对象的实现的详细信息,请参阅日期和时间:自动化支持一文。

COleDateTime::m_status

包含此 COleDateTime 对象的状态。

DateTimeStatus m_status;

备注

此数据成员的类型是 COleDateTime 类中定义的枚举类型 DateTimeStatus。 有关详细信息,请参阅 COleDateTime::GetStatus

注意

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

COleDateTime::operator =

复制 COleDateTime 值。

COleDateTime& operator=(const VARIANT& varSrc) throw();
COleDateTime& operator=(DATE dtSrc) throw();
COleDateTime& operator=(const time_t& timeSrc) throw();
COleDateTime& operator=(const __time64_t& timeSrc) throw();
COleDateTime& operator=(const SYSTEMTIME& systimeSrc) throw();
COleDateTime& operator=(const FILETIME& filetimeSrc) throw();
COleDateTime& operator=(const UDATE& uDate) throw();

注解

这些重载的赋值运算符将源日期/时间值复制到此 COleDateTime 对象中。 其中每个重载的赋值运算符的简要说明如下:

  • 运算符 =( dateSrc 操作数的值和状态将复制到此 COleDateTime 对象中。

  • 运算符 =(varSrc 如果 VARIANT 值(或 COleVariant 对象)转换为日期/时间(VT_DATE)成功,则转换后的值将复制到此COleDateTime对象中,其状态设置为有效。 如果转换失败,则此对象的值将设置为零(1899 年 12 月 30 日午夜),并且其状态将设置为无效。

  • operator =( dtSrc DATE 复制到此 COleDateTime 对象中,其状态设置为有效。

  • 运算符 =( timeSrc 转换 time_t__time64_t 值并将其复制到此 COleDateTime 对象中。 如果转换成功,则此对象的状态将设置为有效;如果失败,则设置为无效。

  • 运算符 =(systimeSrc SYSTEMTIME 值将转换并复制到此COleDateTime对象中。 如果转换成功,则此对象的状态将设置为有效;如果失败,则设置为无效。

  • 运算符 =( uDate UDATE 将转换并复制到此 COleDateTime 对象中。 如果转换成功,则此对象的状态将设置为有效;如果失败,则设置为无效。 UDATE 结构表示“解包”日期。 有关详细信息,请参阅函数 VarDateFromUdate

  • 运算符 =( filetimeSrc FILETIME 值将转换并复制到此 COleDateTime 对象中。 如果转换成功,则此对象的状态将设置为有效;否则设置为无效。 FILETIME 使用协调世界时 (UTC),因此如果在结构中传递 UTC 时间,则结果将从 UTC 时间转换为本地时间,并存储为变体时间。 此行为与 Visual C++ 6.0 和 Visual C++.NET 2003 SP2 中相同。 有关详细信息,请参阅 Windows SDK 中的文件时间

有关详细信息,请参阅 Windows SDK 中的 VARIANT 条目。

有关 time_t 数据类型的详细信息,请参阅运行时库参考中的 time 函数。

有关详细信息,请参阅 Windows SDK 中的 SYSTEMTIMEFILETIME 结构。

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

COleDateTime::operator +, -

ColeDateTime 值相加和相减。

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

备注

COleDateTime 对象表示绝对时间。 COleDateTimeSpan 对象表示相对时间。 前两个运算符用于将 COleDateTimeSpan 值与 COleDateTime 值相加或相减。 第三个运算符用于将两个 COleDateTime 值相减以得出一个 COleDateTimeSpan 值。

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

如果得出的 COleDateTime 值超出可接受值的边界,则该 COleDateTime 值的状态为无效。

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

+- 运算符将断言 COleDateTime 对象是否设置为 null。 有关示例,请参阅 COleDateTime 关系运算符

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

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

示例

COleDateTime t1(1999, 3, 19, 22, 15, 0); // 10:15PM March 19, 1999
COleDateTime t2(1999, 3, 20, 22, 15, 0); // 10:15PM March 20, 1999

// Subtract 2 COleDateTimes
COleDateTimeSpan ts = t2 - t1;

// one day is 24 * 60 * 60 == 86400 seconds
ASSERT(ts.GetTotalSeconds() == 86400L);

// Add a COleDateTimeSpan to a COleDateTime.
ASSERT((t1 + ts) == t2);

// Subtract a COleDateTimeSpan from a COleDateTime.
ASSERT((t2 - ts) == t1);   

COleDateTime::operator +=, -=

在此 COleDateTime 对象中加减 ColeDateTime 值。

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

备注

这些运算符用于将 COleDateTimeSpan 值与此 COleDateTime 相加和相减。 如果任一操作数为 null,则得出的 COleDateTime 值的状态为 null。

如果得出的 COleDateTime 值超出可接受值的边界,则此 COleDateTime 值的状态将设置为无效。

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

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

+=-= 运算符将断言 COleDateTime 对象是否设置为 null。 有关示例,请参阅 COleDateTime 关系运算符

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

COleDateTime::operator DATE

ColeDateTime 值转换为 DATE

operator DATE() const throw();

注解

此运算符返回一个 DATE 对象,其值是从此 COleDateTime 对象复制的。 有关 DATE 对象的实现的详细信息,请参阅日期和时间:自动化支持一文。

DATE 运算符将断言 COleDateTime 对象是否设置为 null。 有关示例,请参阅 COleDateTime 关系运算符

COleDateTime::ParseDateTime

分析字符串以读取日期/时间值。

bool ParseDateTime(
    LPCTSTR lpszDate,
    DWORD dwFlags = 0,
    LCID lcid = LANG_USER_DEFAULT) throw();

参数

lpszDate
指向要分析的以 null 结尾的字符串的指针。 有关详细信息,请参阅“备注”。

dwFlags
指示区域设置和分析的标志。 以下一个或多个标志:

  • LOCALE_NOUSEROVERRIDE:使用系统默认区域设置,而不是自定义的用户设置。

  • VAR_TIMEVALUEONLY:在分析期间忽略日期部分。

  • VAR_DATEVALUEONLY:在分析期间忽略时间部分。

lcid
指示用于转换的区域设置 ID。

返回值

如果字符串已成功转换为日期/时间值,则返回 TRUE,否则返回 FALSE。

备注

如果字符串已成功转换为日期/时间值,则此 COleDateTime 对象的值将设置为该转换值,并且其状态为有效。

注意

年份值必须介于 100 和 9999 之间(含)。

lpszDate 参数可以采用多种格式。 例如,以下字符串包含可接受的日期/时间格式:

"25 January 1996"

"8:30:00"

"20:30:00"

"January 25, 1996 8:30:00"

"8:30:00 Jan. 25, 1996"

"1/25/1996 8:30:00" // always specify the full year, even in a 'short date' format

区域设置 ID 还会影响是否可以接受将字符串格式转换为日期/时间值。

使用 VAR_DATEVALUEONLY 时,时间值将设置为时间 0 或午夜。 使用 VAR_TIMEVALUEONLY 时,日期值将设置为日期 0,即 1899 年 12 月 30 日。

如果字符串无法转换为日期/时间值或发生数字溢出,则此 COleDateTime 对象的状态为无效。

有关 COleDateTime 值的边界和实现的详细信息,请参阅日期和时间:自动化支持一文。

COleDateTime::SetDate

设置此 COleDateTime 对象的日期。

int SetDate(
    int nYear,
    int nMonth,
    int nDay) throw();

参数

nYear
指示要复制到此 COleDateTime 对象中的年。

nMonth
指示要复制到此 COleDateTime 对象中的月。

nDay
指示要复制到此 COleDateTime 对象中的日。

返回值

如果已成功设置此 COleDateTime 对象的值,则返回零;否则返回 1。 此返回值基于 DateTimeStatus 枚举类型。 有关详细信息,请参阅 SetStatus 成员函数。

备注

日期设置为指定的值。 时间设置为时间 0,即午夜。

有关参数值的边界,请参阅下表:

参数 边界
nYear 100 - 9999
nMonth 1 - 12
nDay 0 - 31

如果月中的日溢出,则会将其转换为下个月的正确日,并相应地递增月和/或年。 日值零表示上个月的最后一日。 行为与 SystemTimeToVariantTime 相同。

如果参数指定的日期值无效,则此对象的状态将设置为 COleDateTime::invalid。 应使用 GetStatus 检查 DATE 值的有效性,并且不应假设 m_dt 的值保持不变。

下面是日期值的一些示例:

nYear nMonth nDay
2000 2 29 2000 年 2 月 29 日
1776 7 4 1776 年 7 月 4 日
1925 4 35 1925 年 4 月 35 日(无效日期)
10000 1 1 10000 年 1 月 1 日(无效日期)

若要同时设置日期和时间,请参阅 COleDateTime::SetDateTime

有关用于查询此 COleDateTime 对象的值的成员函数的信息,请参阅以下成员函数:

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

示例

// set only the date, time set to midnight
dt.SetDate(1999, 3, 19);
ASSERT(dt.GetYear() == 1999);
ASSERT(dt.GetDay() == 19);
ASSERT(dt.GetMonth() == 3);
ASSERT(dt.GetHour() == 0);
ASSERT(dt.GetMinute() == 0);
ASSERT(dt.GetSecond() == 0);

// setting the time only resets the date to 1899!
dt.SetTime(22, 15, 0);
ASSERT(dt.GetYear() == 1899);
ASSERT(dt.GetDay() == 30);
ASSERT(dt.GetMonth() == 12);
ASSERT(dt.GetHour() == 22);
ASSERT(dt.GetMinute() == 15);
ASSERT(dt.GetSecond() == 0);   

COleDateTime::SetDateTime

设置此 COleDateTime 对象的日期和时间。

int SetDateTime(
    int nYear,
    int nMonth,
    int nDay,
    int nHour,
    int nMin,
    int nSec) throw();

参数

nYear、nMonth、nDay、nHour、nMin、nSec
指示要复制到此 COleDateTime 对象中的日期和时间组件。

返回值

如果已成功设置此 COleDateTime 对象的值,则返回零;否则返回 1。 此返回值基于 DateTimeStatus 枚举类型。 有关详细信息,请参阅 SetStatus 成员函数。

注解

有关参数值的边界,请参阅下表:

参数 边界
nYear 100 - 9999
nMonth 1 - 12
nDay 0 - 31
nHour 0 - 23
nMin 0 - 59
nSec 0 - 59

如果月中的日溢出,则会将其转换为下个月的正确日,并相应地递增月和/或年。 日值零表示上个月的最后一日。 行为与 SystemTimeToVariantTime 相同。

如果参数指定的日期或时间值无效,则此对象的状态将设置为无效,并且此对象的值不会更改。

下面是时间值的一些示例:

nHour nMin nSec
1 3 3 01:03:03
23 45 0 23:45:00
25 30 0 无效
9 60 0 无效

下面是日期值的一些示例:

nYear nMonth nDay
1995 4 15 1995 年 4 月 15 日
1789 7 14 1789 年 7 月 17 日
1925 2 30 无效
10000 1 1 无效

若要仅设置日期,请参阅 COleDateTime::SetDate。 若要仅设置时间,请参阅 COleDateTime::SetTime

有关用于查询此 COleDateTime 对象的值的成员函数的信息,请参阅以下成员函数:

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

示例

参阅 GetStatus 的示例。

COleDateTime::SetStatus

设置此 COleDateTime 对象的状态。

void SetStatus(DateTimeStatus status) throw();

参数

status
COleDateTime 对象的新状态值。

备注

status 参数值由 COleDateTime 类中定义的 DateTimeStatus 枚举类型定义。 有关详细信息,请参阅 COleDateTime::GetStatus

注意

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

示例

参阅 GetStatus 的示例。

COleDateTime::SetTime

设置此 COleDateTime 对象的时间。

int SetTime(
    int nHour,
    int nMin,
    int nSec) throw();

参数

nHour、nMin、nSec
指示要复制到此 COleDateTime 对象中的时间组件。

返回值

如果已成功设置此 COleDateTime 对象的值,则返回零;否则返回 1。 此返回值基于 DateTimeStatus 枚举类型。 有关详细信息,请参阅 SetStatus 成员函数。

备注

时间设置为指定的值。 日期设置为日期 0,即 1899 年 12 月 30 日。

有关参数值的边界,请参阅下表:

参数 边界
nHour 0 - 23
nMin 0 - 59
nSec 0 - 59

如果参数指定的时间值无效,则此对象的状态将设置为无效,并且此对象的值不会更改。

下面是时间值的一些示例:

nHour nMin nSec
1 3 3 01:03:03
23 45 0 23:45:00
25 30 0 无效
9 60 0 无效

若要同时设置日期和时间,请参阅 COleDateTime::SetDateTime

有关用于查询此 COleDateTime 对象的值的成员函数的信息,请参阅以下成员函数:

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

示例

参阅 SetDate 的示例。

另请参阅

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