CTime 類別

發行項
10/12/2023

表示絕對時間和日期。

語法

class CTime

成員

公用建構函式

名稱	描述
CTime：：CTime	`CTime`以各種方式建構物件。

公用方法

名稱	描述
CTime：：Format	`CTime`根據當地時區，將物件轉換成格式化字串。
CTime：：FormatGmt	根據 UTC，將 `CTime` 物件轉換成格式化字串。
CTime：：GetAsDBTIMESTAMP	將儲存在物件中的 `CTime` 時間資訊轉換為 Win32 相容的 DBTIMESTAMP 結構。
CTime：：GetAsSystemTime	將儲存在物件中的 `CTime` 時間資訊轉換為 Win32 相容的 SYSTEMTIME 結構。
CTime：：GetCurrentTime	`CTime`建立物件，表示目前時間（靜態成員函式）。
CTime：：GetDay	傳回物件所代表的 `CTime` 日期。
CTime：：GetDayOfWeek	傳回物件所代表的星期天 `CTime` 。
CTime：：GetGmtTm	根據 UTC，將 `CTime` 物件細分為元件。
CTime：：GetHour	傳回物件所代表的 `CTime` 小時。
CTime：：GetLocalTm	根據當地時區，將物件細分 `CTime` 為元件。
CTime：：GetMinute	傳回物件所表示的 `CTime` 分鐘。
CTime：：GetMonth	傳回物件所代表的 `CTime` 月份。
CTime：：GetSecond	傳回物件所表示的第 `CTime` 二個。
CTime：：GetTime	傳回指定 `CTime` 物件的__time64_t 值。
CTime：：GetYear	傳回物件所代表的 `CTime` 年份。
CTime：：Serialize64	將資料序列化至封存或從封存。

操作員

名稱	描述
operator + -	這些運算子會加入和減去 `CTimeSpan` 和 `CTime` 物件。
operator +=， -=	這些運算子會將物件新增和減去 `CTimeSpan` 到這個 `CTime` 物件。
operator =	指派運算子。
operator ==、 < 、 etc.	比較運算子。

備註

CTime 沒有基類。

CTime 值是以國際標準時間（UTC）為基礎，相當於國際標準時間（格林威治標準時間，GMT）。如需如何決定時區的相關資訊，請參閱時間管理。

當您建立 CTime 物件時，請將 nDST 參數設定為 0，表示標準時間生效，或設定為大於 0 的值，表示日光節約時間有效，或設定小於零的值，讓 C 執行時間程式庫程式碼計算標準時間或日光節約時間是否有效。 tm_isdst 是必要的欄位。如果未設定，則其值未定義，而且 mktime 的傳回值無法預測。如果 timeptr 指向先前呼叫 asctime_s 、 _gmtime_s 或 localtime_s 所傳回的 tm 結構，則 tm_isdst 欄位會包含正確的值。

隨附類別 CTimeSpan 代表時間間隔。

CTime和 CTimeSpan 類別不是針對衍生所設計。因為沒有虛擬函式，因此和 CTimeSpan 物件的大小 CTime 正好是 8 個位元組。大部分成員函式都是內嵌的。

注意

上限為 12/31/3000。下限為 1/1/1970 上午 12：00：00 GMT。

如需使用 CTime 的詳細資訊，請參閱執行時間程式庫中的日期和時間管理文章。

注意

結構 CTime 已從 MFC 7.1 變更為 MFC 8.0。如果您使用 MFC 8.0 或更新版本的運算子 << 來序列化 CTime 結構 ，則較舊版本的 MFC 將無法讀取產生的檔案。

需求

標頭： atltime.h

CTime 比較運算子

比較運算子。

bool operator==(CTime time) const throw();
bool operator!=(CTime time) const throw();
bool operator<(CTime time) const throw();
bool operator>(CTime time) const throw();
bool operator<=(CTime time) const throw();
bool operator>=(CTime time) const throw();

參數

time
要比較的 CTime 物件。

傳回值

如果條件為 true，這些運算子會比較兩個絕對時間，並傳回 TRUE;否則為 FALSE。

範例

CTime t1 = CTime::GetCurrentTime();
CTime t2 = t1 + CTimeSpan(0, 1, 0, 0);    // 1 hour later
ATLASSERT(t1 != t2);
ATLASSERT(t1 < t2);
ATLASSERT(t1 <= t2);

CTime：：CTime

建立以指定時間初始化的新 CTime 物件。

CTime() throw();
CTime(__time64_t time) throw();
CTime(int nYear, int nMonth, int nDay,
      int nHour, int nMin, int nSec, int nDST = -1);
CTime(WORD wDosDate, WORD wDosTime, int nDST = -1);
CTime(const SYSTEMTIME& st, int nDST = - 1) throw();
CTime(const FILETIME& ft, int nDST = - 1);
CTime(const DBTIMESTAMP& dbts, int nDST = -1) throw();

參數

timeSrc
表示 CTime 已經存在的物件。

time
時間 __time64_t 值，這是 1970 年 1 月 1 日 UTC 之後的秒數。請注意，這會調整為您的當地時間。例如，如果您位於紐約，並藉由傳遞 0 的參數來建立 CTime 物件， CTime：：GetMonth 會傳回 12。

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

nDST
指出日光節約時間是否有效。可以有三個值之一：

nDST 設定為 0Standard 時間生效。
nDST 設定為大於 0Daylight 節省時間的值生效。
nDST 設定為小於 0 的值預設值。自動計算標準時間或日光節約時間是否有效。

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

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

英尺
要轉換成日期/時間值的 FILETIME 結構，並複製到新的 CTime 物件中。

dbts
包含目前當地時間之 DBTIMESTAMP 結構的參考。

備註

每個建構函式如下所述：

CTime(); 建構未初始化 CTime 的物件。此建構函式可讓您定義 CTime 物件陣列。您應該先使用有效時間初始化這類陣列，再使用。
CTime( const CTime& ); 從另一個 CTimeCTime 值建構物件。
CTime( __time64_t );CTime從 __time64_t 型別建構物件。此建構函式需要 UTC 時間，並將結果轉換成本地時間，再儲存結果。
CTime( int, int, ...);CTime從本地時間元件建構物件，每個元件受限於下列範圍：

元件範圍

nYear 1970-3000

nMonth 1-12

nDay 1-31

nHour 0-23

nMin 0-59

nSec 0-59

此建構函式會將適當的轉換為 UTC。如果一或多個時間元件超出範圍，Microsoft Foundation Class Library 的偵錯版本會判斷提示。您必須先驗證引數，才能呼叫。此建構函式需要當地時間。
CTime( WORD, WORD );CTime從指定的 MS-DOS 日期和時間值建構物件。此建構函式需要當地時間。
CTime( const SYSTEMTIME& );CTime從 SYSTEMTIME 結構建構物件。此建構函式需要當地時間。
CTime( const FILETIME& );CTime從 FILETIME 結構建構物件。您最有可能不會直接使用 CTime FILETIME 初始化。如果您使用 CFile 物件來操作檔案，請 CFile::GetStatus 透過 CTime 以 FILETIME 結構初始化的物件擷取檔案時間戳記。此建構函式假設時間是以 UTC 為基礎，並在儲存結果之前自動將值轉換成當地時間。

注意

只有在包含 OLEDB.h 時，才能使用參數 DBTIMESTAMP 的建構函式。

元件	範圍
nYear	1970-3000
nMonth	1-12
nDay	1-31
nHour	0-23
nMin	0-59
nSec	0-59

如需詳細資訊，請參閱 Windows SDK 中的 SYSTEMTIME 和 FILETIME 結構。另請參閱 Windows SDK 中的 MS-DOS 日期和時間專案。

範例

time_t osBinaryTime;  // C run-time time (defined in <time.h>)
time(&osBinaryTime) ;  // Get the current time from the 
                         // operating system.
CTime time1; // Empty CTime. (0 is illegal time value.)
CTime time2 = time1; // Copy constructor.
CTime time3(osBinaryTime);  // CTime from C run-time time
CTime time4(1999, 3, 19, 22, 15, 0); // 10:15PM March 19, 1999

CTime：：Format

呼叫這個成員函式，以建立日期時間值的格式化標記法。

CString Format(LPCTSTR pszFormat) const;
CString Format(UINT nFormatID) const;

參數

pszFormat
格式字串，類似于 printf 格式化字串。格式化程式碼前面加上百分比（ % ）符號，會由對應的 CTime 元件取代。格式化字串中的其他字元會保持不變地複製到傳回的字串。如需格式化程式碼的清單，請參閱執行時間函式 strftime 。

nFormatID
識別此格式之字串的識別碼。

傳回值

包含格式化時間的 CString 。

備註

如果這個 CTime 物件的狀態為 Null，則傳回值是空字串。

如果要格式化的日期時間值從 1970 年 1 月 1 日午夜到 3000 年 12 月 31 日通用國際標準時間（UTC）之間，這個方法會擲回例外狀況。

範例

CTime t(1999, 3, 19, 22, 15, 0); 
// 10:15 PM March 19, 1999
CString s = t.Format(_T("%A, %B %d, %Y"));
ATLASSERT(s == _T("Friday, March 19, 1999"));

CTime：：FormatGmt

產生對應至這個 CTime 物件的格式化字串。

CString FormatGmt(LPCTSTR pszFormat) const;
CString FormatGmt(UINT nFormatID) const;

參數

pszFormat
指定與格式化字串類似的 printf 格式字串。如需詳細資訊，請參閱執行時間函式 strftime 。

nFormatID
識別此格式之字串的識別碼。

傳回值

包含格式化時間的 CString 。

備註

時間值不會轉換，因此會反映 UTC。

如果要格式化的日期時間值從 1970 年 1 月 1 日午夜到 3000 年 12 月 31 日通用國際標準時間（UTC）之間，這個方法會擲回例外狀況。

範例

請參閱 CTime：：Format 的範例。

CTime：：GetAsDBTIMESTAMP

呼叫這個成員函式，將儲存在物件中的 CTime 時間資訊轉換為 Win32 相容的 DBTIMESTAMP 結構。

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

參數

dbts
包含目前當地時間之 DBTIMESTAMP 結構的參考。

傳回值

如果成功則為非零；否則為 0。

備註

將產生的時間儲存在參考的 dbts 結構中。 DBTIMESTAMP此函式初始化的資料結構會將其 fraction 成員設定為零。

範例

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

CTime：：GetAsSystemTime

呼叫這個成員函式，將儲存在物件中的 CTime 時間資訊轉換為 Win32 相容的 SYSTEMTIME 結構。

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

參數

timeDest
SYSTEMTIME 結構的參考，這個結構會保存物件的轉換日期/時間值 CTime 。

傳回值

如果成功，則為 TRUE，否則為 FALSE。

備註

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

範例

// Convert CTime to FILETIME
CTime time(CTime::GetCurrentTime());
SYSTEMTIME timeDest;
time.GetAsSystemTime(timeDest);
FILETIME fileTime;
::SystemTimeToFileTime(&timeDest, &fileTime);

CTime：：GetCurrentTime

CTime傳回物件，表示目前的時間。

static CTime WINAPI GetCurrentTime() throw();

備註

傳回國際標準時間（UTC）中的目前系統日期和時間。

範例

CTime t = CTime::GetCurrentTime();

CTime：：GetDay

傳回物件所代表的 CTime 日期。

int GetDay() const throw();

傳回值

根據當地時間，傳回範圍 1 到 31 的月份日期。

備註

此函式會呼叫 GetLocalTm ，它會使用內部、靜態配置的緩衝區。因為呼叫其他 CTime 成員函式，因此會覆寫此緩衝區中的資料。

範例

// Example for CTime::GetDay, CTime::GetMonth, and CTime::GetYear
CTime t(1999, 3, 19, 22, 15, 0); // 10:15 PM March 19, 1999
ATLASSERT(t.GetDay() == 19);
ATLASSERT(t.GetMonth() == 3);
ATLASSERT(t.GetYear() == 1999);

CTime：：GetDayOfWeek

傳回物件所代表的星期天 CTime 。

int GetDayOfWeek() const throw();

傳回值

根據當地時間傳回一周中的日期;1 = 星期日，2 = 星期一，至 7 = 星期六。

備註

此函式會呼叫 GetLocalTm ，它會使用內部靜態配置的緩衝區。因為呼叫其他 CTime 成員函式，因此會覆寫此緩衝區中的資料。

範例

// Print out the day of the week using localized day name
UINT DayOfWeek[] = {
   LOCALE_SDAYNAME7,   // Sunday
   LOCALE_SDAYNAME1,   
   LOCALE_SDAYNAME2,
   LOCALE_SDAYNAME3,
   LOCALE_SDAYNAME4, 
   LOCALE_SDAYNAME5, 
   LOCALE_SDAYNAME6   // Saturday
};
TCHAR strWeekday[256];
CTime time(CTime::GetCurrentTime());   // Initialize CTime with current time
::GetLocaleInfo(LOCALE_USER_DEFAULT,   // Get string for day of the week from system
   DayOfWeek[time.GetDayOfWeek()-1],   // Get day of week from CTime
   strWeekday, sizeof(strWeekday) / sizeof(strWeekday[0]));
ATLTRACE(_T("%s\n"), strWeekday);               // Print out day of the week

CTime：：GetGmtTm

取得結構 tm ，其中包含這個 CTime 物件中包含的時間分解。

struct tm* GetGmtTm(struct tm* ptm) const;

參數

ptm
指向將接收時間資料的緩衝區。如果此指標為 Null，則會擲回例外狀況。

傳回值

填入 結構 tm 的指標，如 include 檔案 TIME.H 中所定義。如需結構配置，請參閱 gmtime、_gmtime32 _gmtime64 。

備註

GetGmtTm 會傳回 UTC。

ptm 不可以是 Null。如果您想要還原為舊的行為，其中 ptm 可以是 Null， 表示應該使用內部、靜態配置的緩衝區，然後取消定義_SECURE_ATL。

範例

// Compute difference between local time and GMT
CTime time(CTime::GetCurrentTime());
tm t1, t2;
time.GetLocalTm(&t1);
time.GetGmtTm(&t2);

ATLTRACE(_T("Difference between local time and GMT is %d hours.\n"), 
   t1.tm_hour - t2.tm_hour);

CTime：：GetHour

傳回物件所代表的 CTime 小時。

int GetHour() const throw();

傳回值

根據當地時間傳回範圍 0 到 23 中的小時。

備註

此函式會呼叫 GetLocalTm ，它會使用內部靜態配置的緩衝區。因為呼叫其他 CTime 成員函式，因此會覆寫此緩衝區中的資料。

範例

// Example for CTime::GetHour, CTime::GetMinute, and CTime::GetSecond
CTime t(1999, 3, 19, 22, 15, 0); // 10:15 PM March 19, 1999
ATLASSERT(t.GetSecond() == 0);
ATLASSERT(t.GetMinute() == 15);
ATLASSERT(t.GetHour() == 22);

CTime：：GetLocalTm

取得結構 tm ，其中包含這個 CTime 物件中包含的時間分解。

struct tm* GetLocalTm(struct tm* ptm) const;

參數

ptm
指向將接收時間資料的緩衝區。如果此指標為 Null，則會擲回例外狀況。

傳回值

填入 結構 tm 的指標，如 include 檔案 TIME.H 中所定義。如需結構配置，請參閱 gmtime、_gmtime32 _gmtime64 。

備註

GetLocalTm 會傳回當地時間。

ptm 不可以是 Null。如果您想要還原為舊的行為，其中 ptm 可以是 Null， 表示應該使用內部、靜態配置的緩衝區，然後取消定義_SECURE_ATL。

範例

CTime t(1999, 3, 19, 22, 15, 0); // 10:15PM March 19, 1999
tm osTime;  // A structure containing time elements.
t.GetLocalTm(&osTime);
ATLASSERT(osTime.tm_mon == 2); // Note zero-based month!

CTime：：GetMinute

傳回物件所表示的 CTime 分鐘。

int GetMinute() const throw();

傳回值

根據當地時間，傳回範圍 0 到 59 中的分鐘。

備註

此函式會呼叫 GetLocalTm ，它會使用內部靜態配置的緩衝區。因為呼叫其他 CTime 成員函式，因此會覆寫此緩衝區中的資料。

範例

請參閱 GetHour 的範例。

CTime：：GetMonth

傳回物件所代表的 CTime 月份。

int GetMonth() const throw();

傳回值

根據當地時間傳回月份，範圍 1 到 12（1 = 1 月）。

備註

此函式會呼叫 GetLocalTm ，它會使用內部靜態配置的緩衝區。因為呼叫其他 CTime 成員函式，因此會覆寫此緩衝區中的資料。

範例

請參閱 GetDay 的範例。

CTime：：GetSecond

傳回物件所表示的第 CTime 二個。

int GetSecond() const throw();

傳回值

根據當地時間，傳回範圍 0 到 59 中的第二個。

備註

此函式會呼叫 GetLocalTm ，它會使用內部靜態配置的緩衝區。因為呼叫其他 CTime 成員函式，因此會覆寫此緩衝區中的資料。

範例

請參閱 GetHour 的範例。

CTime：：GetTime

傳 回指定 CTime 物件的__time64_t 值。

__time64_t GetTime() const throw();

傳回值

GetTime 會傳回目前 CTime 物件與 1970 年 1 月 1 日之間的秒數。

範例

CTime t(2005, 10, 20, 23, 50, 0); // 11:50 PM October 20, 2005
time_t osBinaryTime = t.GetTime();  // time_t defined in <time.h>

_tprintf_s(_T("time_t = %ld\n"), osBinaryTime);

CTime：：GetYear

傳回物件所代表的 CTime 年份。

int GetYear();

傳回值

根據當地時間傳回 1970 年 1 月 1 日至 2038 年 1 月 18 日（含）。

備註

此函式會呼叫 GetLocalTm ，它會使用內部靜態配置的緩衝區。因為呼叫其他 CTime 成員函式，因此會覆寫此緩衝區中的資料。

範例

請參閱 GetDay 的範例。

CTime：：operator =

指派運算子。

CTime& operator=(__time64_t time) throw();

參數

time
新的日期/時間值。

傳回值

更新 CTime 的物件。

備註

這個多載指派運算子會將來源時間複製到這個 CTime 物件中。物件中的 CTime 內部時間儲存區與時區無關。指派期間不需要時區轉換。

CTime：：operator +， -

這些運算子會加入和減去 CTimeSpan 和 CTime 物件。

CTime operator+(CTimeSpan timeSpan) const throw();
CTime operator-(CTimeSpan timeSpan) const throw();
CTimeSpan operator-(CTime time) const throw();

參數

timeSpan
CTimeSpan要加入或減去的物件。

time
CTime要減去的物件。

傳回值

CTime或 CTimeSpan 物件，表示作業的結果。

備註

CTime 物件代表絕對時間， CTimeSpan 物件代表相對時間。前兩個運算子可讓您在物件中 CTime 加入和減去 CTimeSpan 物件。第三個運算子可讓您從另一個物件減去一個 CTime 物件，以產生 CTimeSpan 物件。

範例

CTime t1(1999, 3, 19, 22, 15, 0); // 10:15 PM March 19, 1999
CTime t2(1999, 3, 20, 22, 15, 0); // 10:15 PM March 20, 1999
CTimeSpan ts = t2 - t1;             // Subtract 2 CTimes
ATLASSERT(ts.GetTotalSeconds() == 86400L);
ATLASSERT((t1 + ts) == t2);       // Add a CTimeSpan to a CTime.
ATLASSERT((t2 - ts) == t1);       // Subtract a CTimeSpan from a CTime.

CTime：：operator +=， -=

這些運算子會將物件新增和減去 CTimeSpan 到這個 CTime 物件。

CTime& operator+=(CTimeSpan span) throw();
CTime& operator-=(CTimeSpan span) throw();

參數

跨度
CTimeSpan要加入或減去的物件。

傳回值

更新 CTime 的物件。

備註

這些運算子可讓您在這個物件中加入 CTime 和減去 CTimeSpan 物件。

範例

CTime t(1999, 3, 19, 22, 15, 0); // 10:15 PM March 19, 1999
t += CTimeSpan(0, 1, 0, 0);      // 1 hour exactly
ATLASSERT(t.GetHour() == 23);

CTime：：Serialize64

注意

這個方法只能在 MFC 專案中使用。

序列化與封存中成員變數相關聯的資料。

CArchive& Serialize64(CArchive& ar);

參數

Ar
CArchive您要更新的物件。

傳回值

更新 CArchive 的物件。

另請參閱

asctime_s、_wasctime_s
_ftime_s、_ftime32_s、_ftime64_s
gmtime_s、_gmtime32_s、_gmtime64_s
localtime_s、_localtime32_s、_localtime64_s
strftime、wcsftime、_strftime_l、_wcsftime_l
time、_time32、_time64
CTimeSpan 類別
 階層架構圖表
 ATL/MFC 共用類別

共用方式為

CTime 類別

語法

成員

公用建構函式

公用方法

操作員

備註

需求

CTime 比較運算子

參數

傳回值

範例

CTime：：CTime

參數

備註

範例

CTime：：Format

參數

傳回值

備註

範例

CTime：：FormatGmt

參數

傳回值

備註

範例

CTime：：GetAsDBTIMESTAMP

參數

傳回值

備註

範例

CTime：：GetAsSystemTime

參數

傳回值

備註

範例

CTime：：GetCurrentTime

備註

範例

CTime：：GetDay

傳回值

備註

範例

CTime：：GetDayOfWeek

傳回值

備註

範例

CTime：：GetGmtTm

參數

傳回值

備註

範例

CTime：：GetHour

傳回值

備註

範例

CTime：：GetLocalTm

參數

傳回值

備註

範例

CTime：：GetMinute

傳回值

備註

範例

CTime：：GetMonth

傳回值

備註

範例

CTime：：GetSecond

傳回值

備註

範例

CTime：：GetTime

傳回值

範例

CTime：：GetYear

傳回值

備註