COleDateTime 類別

發行項
07/05/2024

封裝 DATE OLE 自動化中使用的數據類型。

語法

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：:P arseDateTime	從字串讀取日期/時間值，並設定的值 `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 日午夜前的日值會變成負值，但日間值不會變成負值。例如，上午 6：00 一律以分數值 0.25 表示，不論代表當天的整數是否為正數（1899 年 12 月 30 日之後）或負值（1899 年 12 月 30 日之前）。這表示簡單的浮點比較會錯誤地將代表 12/29/1899 上午 6：00 的排序錯誤， COleDateTime 因為 比同一天上午 7：00 的比較晚 一個。

類別 COleDateTime 會處理從 100 年 1 月 1 日到 9999 年 12 月 31 日的日期。類別 COleDateTime 會使用公曆;它不支援 Julian 日期。 COleDateTime 會忽略日光節約時間。（請參閱日期和時間：自動化支援。

注意

您可以使用 %y 格式，只針對從 1900 開始的日期擷取兩位數年份。如果您在 1900 之前的日期上使用 %y 格式，程式代碼會產生 ASSERT 失敗。

此類型也可用來表示僅限日期或僅限時間的值。依照慣例，日期 0 （1899 年 12 月 30 日）用於僅限時間值，而時間 00：00 （午夜）則用於僅限日期的值。

如果您使用小於 100 的日期來建立 COleDateTime 物件，則會接受日期，但後續呼叫 GetYear、GetMonth、GetDay、、 GetHourGetMinute和 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

如果物件設定為 null，運算子 >=、 <=、 >、和 <會判斷提示 COleDateTime 。

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
現有的 VARIANT 數據結構（可能是 COleVariant 物件）要轉換成日期/時間值（VT_DATE），並複製到新的 COleDateTime 物件。

dtSrc
要複製到新 COleDateTime 物件的日期/時間（DATE）值。

timeSrc
time_t要轉換成日期/時間值的或 __time64_t 值，並複製到新的 COleDateTime 物件。

systimeSrc
SYSTEMTIME結構，要轉換成日期/時間值，並複製到新的 COleDateTime 物件中。

filetimeSrc
FILETIME結構，要轉換成日期/時間值，並複製到新的 COleDateTime 物件中。 FILETIME會使用通用國際標準時間（UTC），因此，如果您在結構中傳遞當地時間，則結果會不正確。如需詳細資訊，請參閱 Windows SDK 中的檔案時間。

nYear， nMonth， nDay， nHour， nMin， nSec
指出要複製到新 COleDateTime 物件的日期和時間值。

wDosDate、 wDosTime
要轉換成日期/時間值的 MS-DOS 日期和時間值，並複製到新的 COleDateTime 物件。

時間戳
包含目前當地時間之 DBTimeStamp 結構的參考。

備註

所有這些建構函式都會建立初始化為指定值的新 COleDateTime 物件。下表顯示每個日期與時間元件的有效範圍：

日期/時間元件	有效範圍
year	100 - 9999
month	0 - 12
天	0 - 31
hour	0 - 23
分鐘	0 - 59
second	0 - 59

請注意，日元件的實際上限會根據月份和年份元件而有所不同。如需詳細資訊，請參閱 SetDate 或 SetDateTime 成員函式。

以下是每個建構函式的簡短描述：

COleDateTime(）COleDateTime建構初始化為 0 的物件（1899 年 12 月 30 日午夜）。
COleDateTime(dateSrc ）COleDateTime從現有的 COleDateTime 物件建構物件。
COleDateTime(varSrc ）COleDateTime建構物件。嘗試將 VARIANT 結構或 COleVariant 物件轉換成日期/時間（ VT_DATE）值。如果此轉換成功，則會將轉換的值複製到新的 COleDateTime 物件中。如果不是，物件的值 COleDateTime 會設定為0（1899年12月30日午夜，1899年12月30日），其狀態為無效。
COleDateTime(dtSrc ）COleDateTime從DATE值建構物件。
COleDateTime(timeSrc ）COleDateTime從time_t值建構物件。
COleDateTime(systimeSrc ）COleDateTime從SYSTEMTIME值建構物件。
COleDateTime(filetimeSrc ）COleDateTime從FILETIME值建構物件。 . FILETIME會使用通用國際標準時間（UTC），因此，如果您在結構中傳遞當地時間，則結果會不正確。如需詳細資訊，請參閱 Windows SDK 中的檔案時間。
COleDateTime(nYear、nMonth、nDay、nHour、nMin、 nSec 、從指定的數值建構 COleDateTime 物件。
COleDateTime(wDosDate、 wDosTime COleDateTime從指定的 MS-DOS 日期和時間值建構物件。

如需數據類型的詳細資訊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
表示要用於轉換的地區設定識別碼。如需語言標識碼的詳細資訊，請參閱語言標識碼。

lpszFormat
格式字串，類似於 printf 格式化字串。每個格式化程式代碼前面加上百分比符號， %都會由對應的 COleDateTime 元件取代。格式化字串中的其他字元會保持不變地複製到傳回的字串。如需詳細資訊，請參閱運行時間函式 strftime。格式化程序代碼 Format 的值和意義如下：

%H 當日的時數
%M 目前小時內的分鐘數
%S 目前分鐘中的秒數
%% 百分比符號

nFormatID
格式控制字串的資源識別碼。

傳回值

CString，其中包含格式化的日期/時間值。

備註

如果這個 COleDateTime 物件的狀態為 Null，則傳回值是空字串。如果狀態無效，則傳回字串是由字串資源ATL_IDS_DATETIME_INVALID指定。

此函式的三種表單簡短描述如下：

Format（ dwFlags， lcid）
此窗體會使用日期和時間的語言規格（地區設定標識符）來格式化值。使用預設參數時，此窗體會列印日期和時間，除非時間部分是 0 （午夜），在此情況下，它只會列印日期，或日期部分為 0 （1899 年 12 月 30 日），在此情況下，它只會列印時間。如果日期/時間值是 0 （1899 年 12 月 30 日午夜），則具有預設參數的這個表單將會列印午夜。

Format（ lpszFormat）
此窗體會使用格式字串來格式化值，其中包含前面加上百分比符號的特殊格式代碼，如中所示 printf。格式化字串會當做參數傳遞至函式。如需格式化程式代碼的詳細資訊，請參閱 Run-Time Library 參考中的 strftime、wcsftime 。

Format（ nFormatID）
此窗體會使用格式字串來格式化值，其中包含前面加上百分比符號的特殊格式代碼，如中所示 printf。格式化字串是資源。此字串資源的識別碼會以參數的形式傳遞。如需格式化程式代碼的詳細資訊，請參閱 Run-Time Library 參考中的 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();

參數

時間戳
DBTimeStamp 結構的參考。

傳回值

如果成功則為非零；否則為 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;如果轉換失敗，或物件為 NULL 或無效， COleDateTime 則為 FALSE。

備註

GetAsSystemTime 會將產生的時間儲存在參考 的 sysTime 物件中。 SYSTEMTIME此函式初始化的數據結構會將其wMilliseconds成員設定為零。

如需物件中 COleDateTime 保留之狀態信息的詳細資訊，請參閱 GetStatus。

COleDateTime：：GetAsUDATE

呼叫這個方法，以取得物件中的 COleDateTime 時間做為 UDATE 數據結構。

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

參數

uDate
要從 COleDateTime 物件接收已轉換日期/時間值的結構參考UDATE。

傳回值

如果成功，則傳回 TRUE;如果轉換失敗，或物件為 NULL 或無效， COleDateTime 則為 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=Monday 等等。

如需查詢此 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::error值所表示的COleDateTime分鐘，如果無法取得分鐘，則為。

備註

有效的傳回值範圍介於 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 ，則會傳回有效。如果您在初始化且建構函式設為 null 的物件上COleDateTime呼叫 GetStatus ，GetStatus將會傳回 null。

備註

傳回值是由 DateTimeStatus 列舉型別所定義，該型別定義於 COleDateTime 類別內。

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，也就是說，此物件未提供任何值。（這是資料庫意義上的“null”，與C++ 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;

備註

這個數據成員的類型是列舉型 DateTimeStatus別，定義於 COleDateTime 類別內。如需詳細資訊，請參閱 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 物件代表相對時間。前兩個COleDateTimeSpanCOleDateTime運算子可讓您從值中加入和減去值。第三個運算符可讓您從另一個運算符減去一個COleDateTimeCOleDateTimeSpan值，以產生值。

如果其中一個操作數為 Null，則結果 COleDateTime 值的狀態為 Null。

如果產生的 COleDateTime 值超出可接受的值界限，該值 COleDateTime 的狀態無效。

如果任一操作數無效，另一個操作數不是 Null，則產生的 COleDateTime 值狀態無效。

如果物件設定為 null，COleDateTime和 + - 運算子將會判斷提示。如需範例，請參閱 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 成員變數。

如果物件設定為 null，COleDateTime和 += -= 運算子將會判斷提示。如需範例，請參閱 COleDateTime 關係運算符。

如需值界限COleDateTime的詳細資訊，請參閱日期和時間：自動化支援一文。

COleDateTime：：operator DATE

將 ColeDateTime 值轉換成 DATE。

operator DATE() const throw();

備註

這個運算符會傳回物件 DATE ，其值會從這個 COleDateTime 物件複製。如需物件實作DATE的詳細資訊，請參閱日期和時間：自動化支援一文。

如果物件設定為 null，COleDateTime運算符DATE會判斷提示。如需範例，請參閱 COleDateTime 關係運算符。

COleDateTime：:P arseDateTime

剖析字串以讀取日期/時間值。

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

參數

lpszDate
要剖析之 Null 終止字串的指標。如需詳細資料，請參閱＜備註＞。

dwFlags
指出地區設定和剖析的旗標。下列一或多個旗標：

LOCALE_NOUSEROVERRIDE 使用系統預設的地區設定，而不是自定義用戶設定。
VAR_TIMEVALUEONLY在剖析期間忽略日期部分。
VAR_DATEVALUEONLY忽略剖析期間的時間部分。

lcid
表示要用於轉換的地區設定識別碼。

傳回值

如果字串成功轉換成日期/時間值，則傳回 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

地區設定標識碼也會影響字串格式是否可接受轉換為日期/時間值。

在VAR_DATEVALUEONLY的情況下，時間值會設定為 time 0 或午夜。在VAR_TIMEVALUEONLY的情況下，日期值會設定為 date 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，午夜。

如需參數值的界限，請參閱下表：

參數	Bounds
nYear	100 - 9999
nMonth	1 - 12
nDay	0 - 31

如果月份的日期溢位，則會轉換成下個月的正確日期，並據以遞增月份和/或年份。 0 的日值表示前一個月的最後一天。行為與 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 物件的日期和時間元件。

傳回值

備註

如需參數值的界限，請參閱下表：

參數	Bounds
nYear	100 - 9999
nMonth	1 - 12
nDay	0 - 31
nHour	0 - 23
nMin	0 - 59
nSec	0 - 59

如果月份的日期溢位，則會轉換成下個月的正確日期，並據以遞增月份和/或年份。 0 的日值表示前一個月的最後一天。行為與 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	17 7 月 1789 日
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 參數值是由DateTimeStatus列舉型別所定義，該型別定義於 COleDateTime 類別內。如需詳細資訊，請參閱 COleDateTime：：GetStatus 。

警告

此函式適用於進階程式設計情況。此函式不會改變這個物件中的數據。它最常用來將狀態設定為 Null 或無效。指派運算子（operator =）和 SetDateTime 會根據來源值來設定物件的狀態。

範例

請參閱 GetStatus 的範例。

COleDateTime：：SetTime

設定這個 COleDateTime 物件的時間。

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

參數

nHour、 nMin、 nSec
指出要複製到這個 COleDateTime 物件的時間元件。

傳回值

備註

時間會設定為指定的值。日期設定為日期 0，表示 1899 年 12 月 30 日。

如需參數值的界限，請參閱下表：

參數	Bounds
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 共享類別

共用方式為

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 =

備註