COleDateTime 类

项目
04/03/2023

封装 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` 值转换为 `DATE` 或 `DATE*`。

公共数据成员

“属性”	描述
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 对象，则会接受该日期，但对 GetYear、GetMonth、GetDay、GetHour、GetMinute 和 GetSecond 的后续调用将会失败并返回 -1。以前，你可以使用两位数日期，但在 MFC 4.2 和更高版本中，日期必须为 100 或更大。

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

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

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

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

要求

标头：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

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

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

COleDateTime() 构造一个初始化为 0 的 COleDateTime 对象（1899 年 12 月 30 日午夜）。
COleDateTime(dateSrc) 从现有 COleDateTime 对象构造 COleDateTime 对象。
COleDateTime(varSrc) 构造 COleDateTime 对象。尝试将 VARIANT 结构或 COleVariant 对象转换为日期/时间 (VT_DATE) 值。如果这种转换成功，则转换后的值将复制到新的 COleDateTime 对象中。否则，COleDateTime 对象的值将设置为 0（1899 年 12 月 30 日午夜），并且其状态将设置为无效。
COleDateTime(dtSrc) 从 DATE 值构造 COleDateTime 对象。
COleDateTime(timeSrc) 从 time_t 值构造 COleDateTime 对象。
COleDateTime(systimeSrc) 从 SYSTEMTIME 值构造 COleDateTime 对象。
COleDateTime(filetimeSrc) 从 FILETIME 值构造 COleDateTime 对象。。 FILETIME 使用协调世界时 (UTC)，因此如果在结构中传递本地时间，结果将不正确。有关详细信息，请参阅 Windows SDK 中的文件时间。
COleDateTime(nYear、nMonth、nDay、nHour、nMin、nSec) 从指定的数值构造 COleDateTime 对象。
COleDateTime(wDosDate, wDosTime) 从指定的 MS-DOS 日期和时间值构造 COleDateTime 对象。

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

有关详细信息，请参阅 Windows SDK 中的 SYSTEMTIME 和 FILETIME 结构。

有关 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 组件替换。格式字符串中的其他字符按原样复制到返回的字符串。有关详细信息，请参阅运行时函数 strftime。 Format 的格式设置代码的值和含义如下：

%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 对象的值的其他成员函数的信息，请参阅以下成员函数：

GetMonth
GetYear
GetHour
GetMinute
GetSecond
GetDayOfWeek
GetDayOfYear

示例

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 对象的值的其他成员函数的信息，请参阅以下成员函数：

GetDay
GetMonth
GetYear
GetHour
GetMinute
GetSecond
GetDayOfYear

示例

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 对象的值的其他成员函数的信息，请参阅以下成员函数：

GetDay
GetMonth
GetYear
GetHour
GetMinute
GetSecond
GetDayOfWeek

示例

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 对象的值的其他成员函数的信息，请参阅以下成员函数：

GetDay
GetMonth
GetYear
GetMinute
GetSecond
GetDayOfWeek
GetDayOfYear

示例

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 对象的值的其他成员函数的信息，请参阅以下成员函数：

GetDay
GetMonth
GetYear
GetHour
GetSecond
GetDayOfWeek
GetDayOfYear

示例

请参阅 GetHour 的示例。

COleDateTime::GetMonth

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

int GetMonth() const throw();

返回值

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

注解

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

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

GetDay
GetYear
GetHour
GetMinute
GetSecond
GetDayOfWeek
GetDayOfYear

示例

请参阅 GetDay 的示例。

COleDateTime::GetSecond

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

int GetSecond() const throw();

返回值

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

备注

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

注意

COleDateTime 类不支持闰秒。

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

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

GetDay
GetMonth
GetYear
GetHour
GetMinute
GetDayOfWeek
GetDayOfYear

示例

请参阅 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 对象的状态在以下情况下无效：

如果其值是从无法转换为日期/时间值的 VARIANT 或 COleVariant 值设置的。
如果其值是从无法转换为有效日期/时间值的 time_t、SYSTEMTIME 或 FILETIME 值设置的。
如果其值是由 SetDateTime 使用无效参数值设置的。
如果此对象在算术赋值运算（即 += 或 -=）期间发生溢出或下溢。
如果为该对象赋了无效值。
如果使用 SetStatus 将此对象的状态显式设置为无效。

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

COleDateTime
SetDateTime
operator +, -
operator +=, -=

有关 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 对象的值的其他成员函数的信息，请参阅以下成员函数：

GetDay
GetMonth
GetHour
GetMinute
GetSecond
GetDayOfWeek
GetDayOfYear

有关 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。

注意

此数据成员用于高级编程。应使用内联成员函数 GetStatus 和 SetStatus。请参阅 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 对象中。其中每个重载的赋值运算符的简要说明如下：

operator =(dateSrc) 操作数的值和状态将复制到此 COleDateTime 对象中。
operator =(varSrc) 如果将 VARIANT 值（或 COleVariant 对象）转换为日期/时间 (VT_DATE) 成功，则转换后的值将复制到此 COleDateTime 对象中，并且其状态将设置为有效。如果转换失败，则此对象的值将设置为零（1899 年 12 月 30 日午夜），并且其状态将设置为无效。
operator =(dtSrc)DATE 值将复制到此 COleDateTime 对象中，并且其状态将设置为有效。
operator =(timeSrc)time_t 或 __time64_t 值将被转换并复制到此 COleDateTime 对象中。如果转换成功，则此对象的状态将设置为有效；如果失败，则设置为无效。
operator =(systimeSrc)SYSTEMTIME 值将被转换并复制到此 COleDateTime 对象中。如果转换成功，则此对象的状态将设置为有效；如果失败，则设置为无效。
operator =(uDate)UDATE 值将被转换并复制到此 COleDateTime 对象中。如果转换成功，则此对象的状态将设置为有效；如果失败，则设置为无效。 UDATE 结构表示“解包”日期。有关详细信息，请参阅函数 VarDateFromUdate。
operator =(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 中的 SYSTEMTIME 和 FILETIME 结构。

有关 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 对象的值的成员函数的信息，请参阅以下成员函数：

GetDay
GetMonth
GetYear
GetHour
GetMinute
GetSecond
GetDayOfWeek
GetDayOfYear

有关 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 对象的值的成员函数的信息，请参阅以下成员函数：

GetDay
GetMonth
GetYear
GetHour
GetMinute
GetSecond
GetDayOfWeek
GetDayOfYear

有关 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 对象的值的成员函数的信息，请参阅以下成员函数：

GetDay
GetMonth
GetYear
GetHour
GetMinute
GetSecond
GetDayOfWeek
GetDayOfYear

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

示例

参阅 SetDate 的示例。

另请参阅

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

Share via

COleDateTime 类

语法

成员

公共构造函数

公共方法

公共运算符

公共数据成员

注解

要求

COleDateTime 关系运算符

参数

备注

示例

COleDateTime::COleDateTime

参数

备注

示例

COleDateTime::Format

参数

返回值

注解

示例

COleDateTime::GetAsDBTIMESTAMP

参数

返回值

注解

示例

COleDateTime::GetAsSystemTime

参数

返回值

备注

COleDateTime::GetAsUDATE

参数

返回值

注解

COleDateTime::GetCurrentTime

示例

COleDateTime::GetDay

返回值

注解

示例

COleDateTime::GetDayOfWeek

返回值

备注

示例

COleDateTime::GetDayOfYear

返回值

备注

示例

COleDateTime::GetHour

返回值

备注

示例

COleDateTime::GetMinute

返回值

注解

示例

COleDateTime::GetMonth

返回值

注解

示例

COleDateTime::GetSecond

返回值

备注

示例

COleDateTime::GetStatus

返回值

注解

示例

COleDateTime::GetYear

返回值

备注

示例

COleDateTime::m_dt

注解

COleDateTime::m_status

备注

COleDateTime::operator =

注解