6.23.38 wcsftime Function
Formats the time structure to a wide string based on the format parameter.
Include
<wchar.h>
Prototype
size_t wcsftime(wchar_t * restrict s, size_t maxsize, const wchar_t *
restrict format, const struct tm * restrict timeptr);
Arguments
s- the array of wide characters to modify
maxsize- the maximum number of wide characters to be written
format- the wide string contain format specifiers
timeptr- pointer to
tmdata structure
Return Value
Returns the number of wide characters placed into the array pointed to by s
(excluding the terminating null wide character) if that number is not more than
maxsize; otherwise the function returns 0 and the contents of the array
are indeterminate.
Remarks
The function places no more than maxsize wide characters into the array
pointed to by s as controlled by the format wide string, which consists of
zero or more conversion specifiers and ordinary wide characters. A conversion specifier
consists of a % wide character, possibly followed by an E or
O modifier wide character, followed by a wide character that determines the
behavior of the conversion specifier. All ordinary wide characters (including the terminating
null wide character) are copied unchanged into the array. If copying takes place between
objects that overlap, the behavior is undefined.
Each conversion specifier is replaced by appropriate wide characters, which are determined
using the LC_TIME category of the current locale and by the values of zero or
more members of the broken-down time structure pointed to by timeptr, as
indicated in the description. In the "C" locale, the E and
O modifiers are ignored and some specifiers are replaced by different wide
strings, which are indicated in square brackets. The %g, %G,
and %V specifiers give values according to the ISO 8601 week-based year. If
any of the specified values are outside the normal range, the characters stored are
unspecified.
| Specifier | Replacement |
|---|---|
%a |
abbreviated weekday name, derived from tm_wday
["C" locale: the first three characters of
%A] |
%A |
full weekday name, derived from tm_wday ["C"
locale: one of Sunday, Monday, ...
, Saturday] |
%b |
abbreviated month name, derived from tm_mon ["C"
locale: the first three characters of %B] |
%B |
full month name, derived from tm_mon ["C"
locale: one of January, February,
... , December. %c equivalent to
%a %b %e %T %Y] |
%c |
appropriate date and time representation [C locale: equivalent to
%a %b %e %T %Y] |
%C |
year, derived from tm_year, divided by 100 and
truncated to an integer, as a decimal number (00−99) |
%d |
day of the month as a decimal number (01-31), derived from
tm_mday |
%D |
equivalent to %m/%d/%y, derived from
tm_mon, tm_mday, and
tm_year |
%e |
day of the month, derived from tm_mday, as a
decimal number (1−31); a single digit is preceded by a space |
%F |
equivalent to %Y−%m−%d, derived from
tm_year, tm_mon, and
tm_mday |
%g |
last 2 digits of the week-based year, derived from
tm_year, tm_wday, and
tm_yday, as a decimal number (00−99) |
%G |
week-based year, derived from tm_year,
tm_wday, and tm_yday, as a
decimal number (e.g., 1997) |
%H |
equivalent to %b, derived from
tm_mon |
%H |
hour (24-hour clock), derived from tm_hour, as a
decimal number (00−23) |
%I |
hour (12-hour clock), derived from tm_hour, as a
decimal number (01−12) |
%j |
day of the year, derived from tm_yday, as a
decimal number (001−366) |
%m |
month, derived from tm_mon, as a decimal number
(01−12) |
%M |
minute, derived from tm_min, as a decimal number
(00-59) |
%n |
new-line character |
%p |
AM/PM designator, derived from tm_hour ["C"
locale" one of AM or PM] |
%r |
12-hour clock time, derived from tm_hour,
tm_min, and tm_sec ["C"
locale: equivalent to %I:%M:%S %p] |
%R |
equivalent to %H:%M, derived from
tm_hour and tm_min |
%S |
second, derived from tm_sec, as a decimal number
(00-60) |
%t |
horizontal-tab character |
%T |
equivalent to %H:%M:%S, derived from
tm_hour, tm_min, and
tm_sec ["C" locale: equivalent to
%T] |
%u |
ISO 8601 weekday, derived from tm_wday, as a
decimal number (1−7), with Monday being 1. |
%U |
week number of the year, derived from tm_year,
tm_wday, tm_yday, where Sunday
is the first day of week 1 (00-53) |
%V |
ISO 8601 week number, derived from tm_year,
tm_wday, tm_yday, as a decimal
number (01−53) |
%w |
weekday, derived from tm_wday, as a decimal
number (0−6), where Sunday is 0 |
%W |
week number of the year (the first Monday as the first day of
week 1), derived from tm_year,
tm_wday, tm_yday, as a decimal
number (00−53) |
%x |
appropriate date representation ["C" locale: equivalent to
%m/%d/%y] |
%X |
appropriate time representation[ C locale: equivalent to
%T] |
%y |
last 2 digits of the year, derived from tm_year,
as a decimal number (00−99) |
%Y |
year, derived from tm_year, as a decimal number
(e.g., 1997) |
%z |
offset from UTC in ISO 8601 format, derived from
tm_isdst, where −0430 implies 4 hours 30
minutes behind UTC, west of Greenwich; or no characters if no time
zone is determinable |
%Z |
time zone name or abbreviation, derived from
tm_isdst, or no characters if no time zone is
determinable |
%% |
percent character, % |
E or
O modifier characters to indicate an alternative format or
specification. In the "C" locale, these modifiers are ignored. If
the alternative format or specification does not exist for the current locale, the
modifier is ignored.| Modified specifier | Replacement |
|---|---|
%Ec |
locale’s alternative date and time representation |
%EC |
name of the base year (period) in the locale’s alternative representation |
%Ex |
locale’s alternative date representation |
%EX |
locale’s alternative time representation |
%Ey |
offset from %EC (year only) in the locale’s alternative representation |
%EY |
locale’s full alternative year representation |
%Od |
day of the month, using the locale’s alternative numeric symbols (filled as needed with leading zeros, or with leading spaces if there is no alternative symbol for zero) |
%Oe |
day of the month, using the locale’s alternative numeric symbols (filled as needed with leading spaces) |
%OH |
hour (24-hour clock), using the locale’s alternative numeric symbol |
%OI |
hour (12-hour clock), using the locale’s alternative numeric symbols |
%Om |
month, using the locale’s alternative numeric symbols |
%OM |
minutes, using the locale’s alternative numeric symbol |
%OS |
seconds, using the locale’s alternative numeric symbols |
%Ou |
ISO 8601 weekday as a number in the locale’s alternative representation, where Monday is 1 |
%OU |
week number, using the locale’s alternative numeric symbols |
%OV |
ISO 8601 week number, using the locale’s alternative numeric symbols |
%Ow |
weekday as a number, using the locale’s alternative numeric symbols |
%OW |
week number of the year, using the locale’s alternative numeric symbols |
%Oy |
last 2 digits of the year, using the locale’s alternative numeric symbols |
Example
See the notes at the beginning of this chapter or section for
information on using printf() or scanf()
(and other functions reading and writing the stdin or
stdout streams) in the example code.
#include <wchar.h>
#include <time.h>
int main(void)
{
time_t timer, whattime;
struct tm * newtime;
wchar_t buf[128];
timer = 1066668182; /* Mon Oct 20 16:43:02 2003 */
/* localtime allocates space for structure */
newtime = localtime(&timer);
wcsftime(buf, 128, L"It was a %A, %d days into the "
L"month of %B in the year %Y.\n", newtime);
wprintf(buf);
wcsftime(buf, 128, L"It was %W weeks into the year "
L"or %j days into the year.\n", newtime);
wprintf(buf);
}Example Output
It was a Tuesday, 21 days into the month of October in the year 2003.
It was 42 weeks into the year or 294 days into the year.