GetDateFormat
The GetDateFormat
function formats a date as a date string for a specified locale. The function
formats either a specified date or the local system date.
int
GetDateFormat(
|
LCID Locale, |
// locale for which date is to be formatted |
|
DWORD dwFlags, |
// flags specifying function options |
|
CONST
SYSTEMTIME *lpDate, |
// date to be formatted |
|
LPCTSTR lpFormat, |
// date format string |
|
LPTSTR lpDateStr, |
// buffer for storing formatted string |
|
int cchDate |
// size of buffer |
|
); |
|
Parameters
Locale
Specifies the
locale for which the date string is to be formatted. If lpFormat is
NULL, the function formats the string according to the date format for this
locale. If lpFormat is not NULL, the function uses the locale only for
information not specified in the format picture string (for example, the
locale s day and month names).
This
parameter can be a locale identifier created by the MAKELCID macro, or one of the
following predefined values:
|
LOCALE_SYSTEM_DEFAULT |
Default
system locale. |
|
LOCALE_USER_DEFAULT |
Default
user locale. |
dwFlags
A set of bit
flags that specify various function options. If lpFormat is non-NULL,
this parameter must be zero.
If lpFormat
is NULL, you can specify a combination of the following flags:
|
Flag |
Meaning |
|
LOCALE_NOUSEROVERRIDE
|
If set, the
function formats the string using the system default date format for the
specified locale. If not set, the function formats the string using any user
overrides to the locale s default date format. |
|
DATE_SHORTDATE |
Use the
short date format. This is the default. Cannot be used with DATE_LONGDATE. |
|
DATE_LONGDATE |
Use the
long date format. Cannot be used with DATE_SHORTDATE. |
|
DATE_USE_ALT_CALENDAR |
Use the
alternate calendar, if one exists, to format the date string. If this flag is
set, the function uses the default format for that alternate calendar, rather
than using any user overrides. The user overrides will be used only in the
event that there is no default format for the specified alternate calendar. |
lpDate
Pointer to a SYSTEMTIME structure that contains the
date information to be formatted. If this pointer is NULL, the function uses
the current local system date.
lpFormat
Pointer to a
format picture string to use to form the date string. If lpFormat is
NULL, the function uses the date format of the specified locale.
Use the
following elements to construct a format picture string. If you use spaces to
separate the elements in the format string, these spaces will appear in the
same location in the output string. The letters must be in uppercase or
lowercase as shown in the table (for example, MM not mm ). Characters in the
format string that are enclosed in single quotation marks will appear in the
same location and unchanged in the output string.
|
Picture |
Meaning |
|
d |
Day of
month as digits with no leading zero for single-digit days. |
|
dd |
Day of
month as digits with leading zero for single-digit days. |
|
ddd |
Day of week
as a three-letter abbreviation. The function uses the LOCALE_SABBREVDAYNAME
value associated with the specified locale. |
|
dddd |
Day of week
as its full name. The function uses the LOCALE_SDAYNAME value associated with
the specified locale. |
|
M |
Month as
digits with no leading zero for single-digit months. |
|
MM |
Month as
digits with leading zero for single-digit months. |
|
MMM |
Month as a
three-letter abbreviation. The function uses the LOCALE_SABBREVMONTHNAME
value associated with the specified locale. |
|
MMMM |
Month as
its full name. The function uses the LOCALE_SMONTHNAME value associated with
the specified locale. |
|
y |
Year as
last two digits, but with no leading zero for years less than 10. |
|
yy |
Year as
last two digits, but with leading zero for years less than 10. |
|
yyyy |
Year
represented by full four digits. |
|
gg |
Period/era
string. The function uses the CAL_SERASTRING value associated with the
specified locale. This element is ignored if the date to be formatted does
not have an associated era or period string. |
For example,
to get the date string
Wed, Aug 31
94
use the
following picture string:
ddd',' MMM
dd yy
lpDateStr
Pointer to a
buffer that receives the formatted date string.
cchDate
Specifies the
size, in bytes (ANSI version) or characters (Unicode version), of the lpDateStr
buffer. If cchDate is zero, the function returns the number of bytes or
characters required to hold the formatted date string, and the buffer pointed
to by lpDateStr is not used.
Return Values
If the
function succeeds, the return value is the number of bytes (ANSI version) or
characters (Unicode version) written to the lpDateStr buffer, or if the cchDate
parameter is zero, the number of bytes or characters required to hold the
formatted date string.
If the
function fails, the return value is zero. To get extended error information,
call GetLastError.
GetLastError may return one of the following error codes:
|
ERROR_INSUFFICIENT_BUFFER |
|
ERROR_INVALID_FLAGS |
|
ERROR_INVALID_PARAMETER |
Remarks
The day name,
abbreviated day name, month name, and abbreviated month name are all localized
based on the given locale identifier.
The date
values in the SYSTEMTIME
structure pointed to by lpDate must be valid. The function checks each
of the date values: year, month, day, and day of week. If the day of the week
is incorrect, the function uses the correct value, and returns no error. If any
of the other date values are outside the correct range, the function fails, and
sets the last-error to ERROR_INVALID_PARAMETER.
The function
ignores the time portions of the SYSTEMTIME structure pointed to by lpDate:
wHour, wMinute, wSecond, and wMilliseconds.
The
DATE_SHORTDATE and DATE_LONGDATE flag options are mutually exclusive. If
neither one is specified and lpFormat is NULL, then DATE_SHORTDATE is
the default.
No errors are
returned for a bad format string. The function simply forms the best date
string that it can. For example, the only year pictures that are valid are
L yyyy and L yy (the L indicates a Unicode (16-bit characters) string). If
L y is passed in, the function assumes
L yy . If L yyy is passed in, the function assumes L yyyy . If more than 4
date (L dddd ) or 4 month (L MMMM ) pictures are passed in, then the function
defaults to L dddd or L MMMM .
Any text that
should remain in its exact form in the date string should be enclosed within
single quotation marks in the date format picture. The single quotation mark
may also be used as an escape character to allow the single quotation mark
itself to be displayed in the date string. However, the escape sequence must be
enclosed within two single quotation marks. For example, to display the date as
"May '93", the format string would be: L"MMMM ''''yy" The first and last
single quotation marks are the enclosing quotation marks. The second and third
single quotation marks are the escape sequence to allow the single quotation
mark to be displayed before the century.
See Also