CTime 类

项目
10/17/2023

表示绝对时间和日期。

语法

class CTime

成员

公共构造函数

名称	描述
CTime::CTime	以各种方式构造 `CTime` 对象。

公共方法

名称	描述
CTime::Format	将 `CTime` 对象转换为基于本地时区的带格式字符串。
CTime::FormatGmt	将 `CTime` 对象转换为基于 UTC 的带格式字符串。
CTime::GetAsDBTIMESTAMP	将存储在 `CTime` 对象中的时间信息转换为与 Win32 兼容的 DBTIMESTAMP 结构。
CTime::GetAsSystemTime	将存储在 `CTime` 对象中的时间信息转换为与 Win32 兼容的 SYSTEMTIME 结构。
CTime::GetCurrentTime	创建一个表示当前时间的 `CTime` 对象（静态成员函数）。
CTime::GetDay	返回由 `CTime` 对象表示的日期。
CTime::GetDayOfWeek	返回由 `CTime` 对象表示的星期。
CTime::GetGmtTm	将 `CTime` 对象分解为基于 UTC 的组件。
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 ==, < 等	比较运算符。

注解

CTime 没有基类。

CTime 值基于协调世界时 (UTC)。UTC 等同于格林威治标准时间 (GMT)。有关如何确定时区的信息，请参阅时间管理。

创建 CTime 对象时，请将 nDST 参数设置为 0 以指示标准时间生效，或设置为大于 0 的值以指示夏令时生效，或设置为小于零的值以让 C 运行时库代码计算标准时间或夏令时是否生效。 tm_isdst 是必填字段。如果未设置，则未定义其值，并且 mktime 的返回值不可预知。如果 timeptr 指向由先前的 asctime_s、_gmtime_s 或 localtime_s 调用返回的 tm 结构，则 tm_isdst 字段包含正确的值。

伴随类 CTimeSpan 表示时间间隔。

CTime 和 CTimeSpan 类不可派生。由于没有虚拟函数，因此 CTime 和 CTimeSpan 对象的大小正好是 8 个字节。大多数成员函数都是内联函数。

注意

日期上限为 12/31/3000。下限是 1/1/1970 12:00:00 AM GMT。

有关使用 CTime 的详细信息，请参阅“运行时库参考”中的文章日期和时间及时间管理。

注意

CTime 结构已从 MFC 7.1 更改为 MFC 8.0。如果在 MFC 8.0 或更高版本中使用 operator << 序列化 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 设置为 0：标准时间生效。
nDST 设置为大于 0 的值：夏令时生效。
nDST 设置为小于 0 的值：默认设置。自动计算标准时间或夏令时是否生效。

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

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

ft
要转换为日期/时间值并复制到新 CTime 对象中的 FILETIME 结构。

dbts
对包含当前本地时间的 DBTIMESTAMP 结构的引用。

备注

每个构造函数如下所述：

CTime(); 构造未初始化的 CTime 的对象。此构造函数允许定义 CTime 对象数组。在使用此类数组之前应使用有效时间将其初始化。
CTime( const CTime& ); 从另一个 CTime 值构造 CTime 对象。
CTime( __time64_t ); 从 __time64_t 类型构造 CTime 对象。此构造函数需要 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 基础类库的调试版本将断言一个或多个时间组件是否超出范围。必须在调用之前验证参数。此构造函数需要本地时间。
CTime( WORD, WORD ); 从指定的 MS-DOS 日期和时间值构造 CTime 对象。此构造函数需要本地时间。
CTime( const SYSTEMTIME& ); 从一个 SYSTEMTIME 结构构造 CTime 对象。此构造函数需要本地时间。
CTime( const FILETIME& ); 从一个 FILETIME 结构构造 CTime 对象。你很有可能不会直接使用 CTime FILETIME 初始化。如果你使用 CFile 对象操作文件，CFile::GetStatus 将通过使用 FILETIME 结构初始化的 CTime 对象为你检索文件时间戳。此构造函数采用基于 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
标识此格式的字符串的 ID。

返回值

包含带格式时间的 CString。

备注

如果此 CTime 对象的状态为 null，则返回值为空字符串。

如果要设置格式的日期时间值不在协调世界时 (UTC) 1970 年 1 月 1 日午夜到 3000 年 12 月 31 日的范围内，则此方法将引发异常。

示例

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
标识此格式的字符串的 ID。

返回值

包含带格式时间的 CString。

备注

时间值未转换，因此反映了 UTC。

如果要设置格式的日期时间值不在协调世界时 (UTC) 1970 年 1 月 1 日午夜到 3000 年 12 月 31 日的范围内，则此方法将引发异常。

示例

请参阅 CTime::Format 的示例。

CTime::GetAsDBTIMESTAMP

调用此成员函数可将 CTime 对象中存储的时间信息转换为与 Win32 兼容的 DBTIMESTAMP 结构。

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

参数

dbts
对包含当前本地时间的 DBTIMESTAMP 结构的引用。

返回值

如果成功，则不为 0；否则为 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

获取一个 struct tm，其中包含此 CTime 对象中的时间的组成部分。

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

参数

ptm
指向接收时间数据的缓冲区。如果此指针为 NULL，则引发异常。

返回值

指向 include 文件 TIME.H 中定义的已填充 struct tm 的指针。有关结构布局，请参阅 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

获取一个 struct tm，其中包含此 CTime 对象中的时间的组成部分。

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

参数

ptm
指向接收时间数据的缓冲区。如果此指针为 NULL，则引发异常。

返回值

指向 include 文件 TIME.H 中定义的已填充 struct tm 的指针。有关结构布局，请参阅 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 = 一月）。

备注

此函数调用 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 对象表示相对时间。前两个运算符用于将 CTimeSpan 对象与 CTime 对象相加和相减。第三个运算符用于将两个 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();

参数

span
要相加或相减的 CTimeSpan 对象。

返回值

已更新的 CTime 对象。

备注

这些运算符用于将 CTimeSpan 对象与此 CTime 对象相加和相减。

示例

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 共享类