GetDateFormat函数将日期格式指定为指定区域设置的日期字符串。该函数格式化指定的日期或本地系统日期。
int GetDateFormat(
LCID 【语言环境】, | //要格式化哪个日期的区域设置 |
DWORD 【dwFlags中】, | //标志指定功能选项 |
CONST SYSTEMTIME【// date to be formatted】, | //要格式化的日期 |
LPCTSTR 【lpFormat】, | //日期格式字符串 |
LPTSTR 【lpDateStr】, | //存储格式化字符串的缓冲区 |
INT 【Specifies the locale for which the date string is to be formatted.】 | //缓冲区大小 |
); |
参数
【语言环境】
指定要格式化日期字符串的区域设置。如果【lpFormat】为NULL,则该函数根据该语言环境的日期格式对该字符串进行格式化。如果【lpFormat】不为NULL,则该函数仅对格式图片字符串中未指定的信息(例如,语言环境的日期和月份名称)使用语言环境。
此参数可以是由MAKELCID宏或以下预定义值之一创建的区域设置标识符:
LOCALE_SYSTEM_DEFAULT | 默认系统区域设置。 |
LOCALE_USER_DEFAULT | 默认用户区域设置。 |
【dwFlags中】
一组位标志,指定各种功能选项。如果【lpFormat】非NULL,则此参数必须为0。
如果【lpFormat】为NULL,则可以指定以下标志的组合:
旗 | 含义 |
LOCALE_NOUSEROVERRIDE | 如果设置,该函数使用系统默认日期格式为指定的区域设置格式化字符串。如果未设置,则该函数使用任何用户替换为语言环境的默认日期格式来格式化该字符串。 |
DATE_SHORTDATE | 使用短日期格式。这是默认值。不能与DATE_LONGDATE一起使用。 |
DATE_LONGDATE | 使用长日期格式。不能与DATE_SHORTDATE一起使用。 |
DATE_USE_ALT_CALENDAR | 使用备用日历(如果存在)来格式化日期字符串。如果设置了此标志,该函数将使用该备用日历的默认格式,而不是使用任何用户覆盖。只有在没有指定备用日历的默认格式的情况下,才会使用用户覆盖。 |
【The function checks each of the date values: year, month, day, and day of week.】
指向SYSTEMTIME结构的指针,其中包含要格式化的日期信息。如果此指针为NULL,则该函数使用当前本地系统日期。
【lpFormat】
指向要用于形成日期字符串的格式图片字符串。如果【lpFormat】为NULL,则该函数使用指定区域设置的日期格式。
使用以下元素构建格式图片字符串。如果使用空格分隔格式字符串中的元素,则这些空格将显示在输出字符串中的相同位置。字母必须为大写或小写,如表所示(例如,“MM”不是“mm”)。包含在单引号中的格式字符串中的字符将显示在输出字符串中的相同位置和不变。
图片 | 含义 |
d | 一个月的日数为一位数,而无单位数的天数为零。 |
dd | 一个月的数字为单位数的前导零。 |
DDD | 星期几为三个字母的缩写。该函数使用与指定语言环境相关联的LOCALE_SABBREVDAYNAME值。 |
DDDD | 星期几作为其全名。该函数使用与指定语言环境相关联的LOCALE_SDAYNAME值。 |
M | 月数字为单位数月份无前导零。 |
MM | 月份为单位数月份前导零的数字。 |
MMM | 月份为三个字母的缩写。该函数使用与指定语言环境相关联的LOCALE_SABBREVMONTHNAME值。 |
MMMM | 月份作为其全名。该函数使用与指定语言环境相关联的LOCALE_SMONTHNAME值。 |
y | 年份为最后两位数字,但年份不超过10位则无前提。 |
yy | 年份为最后两位数,但领先零年为少于10岁。 |
YYYY | 年份由四位数字代表。 |
gg | 期间/时代字符串。该函数使用与指定语言环境相关联的CAL_SERASTRING值。如果要格式化的日期没有关联的时代或句点字符串,则忽略该元素。 |
例如,获取日期字符串
“周三,8月31日94”
使用以下图片字符串:
“ddd”,“MMM dd yy”
【lpDateStr】
指向接收格式化日期字符串的缓冲区的指针。
【Specifies the locale for which the date string is to be formatted.】
指定【lpDateStr】缓冲区的大小(以字节为单位)(ANSI版本)或字符(Unicode版本)。如果【Specifies the locale for which the date string is to be formatted.】为零,则该函数返回保存格式化日期字符串所需的字节数或字符数,不使用【lpDateStr】指向的缓冲区。
返回值
如果函数成功,则返回值是写入【lpDateStr】缓冲区的字节数(ANSI版本)或字符(Unicode版本),或【Specifies the locale for which the date string is to be formatted.】参数为零时,要保存的字节数或字符数格式化的日期字符串。
如果函数失败,返回值为零。要获取扩展错误信息,请调用GetLastError.GetLastError可能会返回以下错误代码之一:
ERROR_INSUFFICIENT_BUFFER |
ERROR_INVALID_FLAGS |
ERROR_INVALID_PARAMETER |
备注
日期名称,缩写日期名称,月份名称和缩写月份名称都基于给定的区域设置标识符进行本地化。
【The function checks each of the date values: year, month, day, and day of week.】指向的SYSTEMTIME结构中的日期值必须有效。该函数检查每个日期值:年,月,日和星期几。如果星期几不正确,则该函数使用正确的值,并且不返回错误。如果任何其他日期值超出了正确的范围,该函数将失败,并将最后一个错误设置为ERROR_INVALID_PARAMETER。
该函数忽略【The function checks each of the date values: year, month, day, and day of week.】指向的SYSTEMTIME结构的时间部分:wHour,wMinute,wSecond和wMilliseconds.
DATE_SHORTDATE和DATE_LONGDATE标志选项是互斥的。如果没有指定,并且【lpFormat】为NULL,则DATE_SHORTDATE是默认值。
对于错误的格式字符串不会返回错误。该函数只需形成最佳的日期字符串即可。例如,唯一的有效年份图片是L“yyyy”和L“yy”(“L”表示Unicode(16位字符)字符串)。如果传入L“y”,则函数假定为L“yy”。如果L“yyy”被传入,则该函数假定为“yyyy”。如果超过4个日期(L“dddd”)或4个月(L“MMMM”)图像,则该函数默认为L“dddd”或L“MMMM”。
应在日期字符串中保留其确切形式的任何文本都应包含在日期格式图片中的单引号内。单引号也可以用作转义字符,以允许单引号本身显示在日期字符串中。但是,转义序列必须包含在两个单引号内。例如,要将日期显示为“May '93”,格式字符串将为:L“MMMM”“yy”第一个和最后一个单引号是封闭的引号。第二个和第三个单引号是允许在本世纪前显示单引号的转义序列。
也可以看看