CTime 类
表示绝对时间和日期。
语法
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参数的构造函数才可用。
有关详细信息，请参阅 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 共享类
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈