wcsftime(), wcsftime_l()

convert time specification to wide character string 

Function

SYNOPSIS

#include <wchar.h>

size_t wcsftime(wchar_t *wcs, size_t maxsize, const wchar_t *format, const struct tm *timeptr);

#include <wchar.h>

#include <locale.h>

size_t wcsftime(wchar_t *wcs, size_t maxsize, const wchar_t *format, const struct tm *timeptr, locale_t locale);

DESCRIPTION

The wcsftime() and wcsftime_l() functions converts a time specification to a string, controlled by a format specification. The format string contains zero or more conversion specifications and ordinary characters. A conversion specification consists of a % character and one or more characters that determine the behavior. All ordinary characters (including the terminating null byte) are copied unchanged into the array. If copying takes place between objects that overlap, the behavior is undefined. Each conversion specification is replaced by appropriate characters as described in the following list. The appropriate characters are determined by the program's locale and by the values contained in specified time structure. Local time zone information is used as though wcsftime() or wcsftime_l() had called tzset().

%a  

is replaced by the locale's abbreviated weekday name.

%A  

is replaced by the locale's full weekday name.

%b  

is replaced by the locale's abbreviated month name.

%B  

is replaced by the locale's full month name.

%c  

is replaced by the locale's appropriate date and time representation.

%C  

is replaced by the century number (the year divided by 100 and truncated to an integer) as a decimal number [00,99].

%d  

is replaced by the day of month as a decimal number [01,31].

%D  

is the same as %m/%d/%y.

%e  

is replaced by the day of the month as a decimal number [1,31]; a single digit is preceded by a space.

%h  

is the same as %b.

%H  

is replaced by the hour in 24-hour format [00,23].

%I  

is replaced by the hour in 12-hour format [01,12].

%j  

is replaced by the day of year as a decimal number [001,366].

%k  

is replaced by the hour in 24-hour format as a decimal number [0,23]]; a single digit is preceded by a space.

%l  

is replaced by the hour in 12-hour format as a decimal number [1,12]; a single digit is preceded by a space.

%m  

is replaced by the month as a decimal number [01,12].

%M  

is replaced by the minute as a decimal number [00,59].

%n  

is replaced by a newline character.

%p  

is replaced by the locale's equivalent of either A.M./P.M. indicator for 12-hour clock.

%r  

is replaced by the time in A.M. and P.M. notation; in the POSIX locale, this is equivalent to %I:%M:%S %p.

%R  

is replaced by the time in 24 hour notation (%H:%M).

%s  

is replaced by the time in seconds since the epoch as a decimal number.

%S  

is replaced by the second as a decimal number [00,59].

%t  

is replaced by a tab character.

%T  

is replaced by the time (%H:%M:%S).

%u  

is replaced by the weekday as a decimal number [1,7], with 1 representing Monday.

%U  

is replaced by the week of the year as a decimal number, with Sunday as first day of week [00,53].

%V  

is replaced by the week of the year as a decimal number, with Monday as the first day of the week (01 - 53). If the week containing January 1st has four or more days in the new year, then it is considered week 1. Otherwise, it is week 53 of the previous year, and the next week is week 1.

%w  

is replaced by the weekday as a decimal number [0,6]; Sunday is 0.

%W  

is replaced by the week of the year as a decimal number, with Monday as first day of week [00,53]. All days in a new year preceding the first Monday are considered to be in week 0.

%x  

is replaced by the locale's appropriate date representation.

%X  

is replaced by the locale's appropriate time representation.

%y  

is replaced by the year without century, as a decimal number [00,99].

%Y  

is replaced by the year with century, as a decimal number.

%z, %Z  

is replaced by the time zone name or abbreviation, or by no characters if no time zone information exists.

%%  

is replaced by %.

Some conversion specifiers can be modified by the E or O modifier characters to indicate that an alternative format of specification should be used rather that the one normally used by the unmodified conversion specifier. If the alternative format or specification does not exist for he current locale, the behavior is as if the unmodified conversion specification were used. It is an error to specify the E or O modifier with any conversion specification not listed here.

%Ec  

is replaced by the locale's alternative appropriate date and time representation.

%EC  

is replaced by the name of the base year (period) in the locale's alternative representation.

%Ex  

is replaced by the locale's alternative date representation.

%EX  

is replaced by the locale's alternative time representation.

%Ey  

is replaced by the offset from %EC (year only) in the locale's alternative representation.

%EY  

is replaced by the full alternative year representation.

%Od  

is replaced by the day of the month, using the locale's alternative numeric symbols, filled as needed with leading zeros if there is any alternative symbol for zero, otherwise with leading spaces.

%Oe  

is replaced by the day of the month, using the locale's alternative numerical symbols, filled as needed with leading spaces.

%OH  

is replaced by the hour in 24-hour format using the locale's alternative numeric symbols.

%OI  

is replaced by the hour in 12-hour format using the locale's alternative numeric symbols.

%Om  

is replaced by the month using the locale's alternative numeric symbols

%OM  

is replaced by the minutes using the locale's alternative numeric symbols.

%OS  

is replaced by the seconds using the locale's alternative numeric symbols.

%Ou  

is replaced by the weekday as a number using the locale's alternative representation, with 1 representing Monday.

%OU  

is replaced by the week number of the year (Sunday as the first day of the week, rules corresponding to %U) using the locale's alternative numeric symbols.

%OV  

is replaced by the week number of the year (Monday as the first day of the week, rules corresponding to %V) using the locale's alternative numeric symbols.

%Ow  

is replaced by the number of the weekday using the locale's alternative numeric symbols, with 0 representing Sunday.

%OW  

is replaced by the week number of the year (Monday as the first day of the week) using the locale's alternative numeric symbols.

%Oy  

is replaced by the year (offset from %C) using the locale's alternative numeric symbols.

The # character may be used with any conversion specifier. In that case, the meaning of the format code is changed as follows (if an alternate representation is not listed, the modifier is ignored for that conversion specifier):

%#c  

is replaced by the locale's appropriate date and time representation, in long format (that is, using the full rather than abbreviated weekday and month names).

%#x  

is replaced by the locale's appropriate date representation, in long format (that is, using the full rather than the abbreviated weekday and month names).

%#d, %#H, %#I, %#j, %#m, %#M, %#S, %#U, %#w, %#W, %#y, %#Y  

are replaced as described earlier, with any leading zeros removed.

PARAMETERS

wcs 

Is the wide character buffer into which the converted time is placed.

maxsize 

Is the maximum number of wide characters that are stored in s.

format 

Is the wide character format specification for the conversion.

timeptr 

Is the time to convert to a string.

locale 

Is a locale_t perhaps returned by newlocale() or LC_GLOBAL_LOCALE or 0 for the current thread locale set with uselocale().

RETURN VALUES

If the total number of resulting characters, including the terminating null character, is not more than maxsize, the wcsftime() and wcsftime_l() functions return the number of wide characters placed into the array pointed to by wcs, excluding the terminating null character. Otherwise, wcsftime() and wcsftime_l() return zero and the contents of the array are indeterminate.

CONFORMANCE

wcsftime() conforms to UNIX 98, with exceptions.

wcsftime_l() conforms to IEEE Std 1003.1-2008 'POSIX.1'.

MULTITHREAD SAFETY LEVEL

MT-Safe, with exceptions.

The function wcsftime() is MT-Safe as long as no thread calls setlocale() while this function is executing.

The function wcsftime_l() is MT-Safe as long as no thread calls freelocale() on locale while this function is executing.

PORTING ISSUES

NuTCRACKER Platform locale conversions are based on the native Windows implementations. The Windows locale databases do not provide alternative time representations. Hence the E and O modifiers are always ignored. The # modifier is provided for compatibility with the Visual C++ runtime library implementation of strftime(). Refer to tzset() for details on setting time zone information.

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

SEE ALSO

Functions:
asctime(), asctime_r(), clock(), ctime(), ctime_r(), difftime(), gettimeofday(), gmtime(), gmtime_r(), localtime(), localtime_r(), mktime(), newlocale(), offtime(), setlocale(), strftime(), strftime_l(), time(), tzset(), utime()

PTC MKS Toolkit 10.4 Documentation Build 39.