Uses date and time information stored in a tm structure to create a wide-character output string. The format of the output string is controlled by a format string.

Format

#include <wchar.h>

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

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

Arguments

wcs

A pointer to the resultant wide-character string.

maxsize

The maximum number of wide characters to be stored in the resultant string.

format

A pointer to the string that controls the format of the output string. For the XPG4 interface, this argument is a pointer to a constant character string. For the ISO C interface, it is a pointer to a constant wide-character string.

timeptr

A pointer to the local time structure. The tm structure is defined in the <time.h> header file.

Description

This function uses data in the structure pointed to by timeptr to create the wide-character string pointed to by wcs. A maximum of maxsize wide characters is copied to wcs.

The format string consists of zero or more conversion specifications and ordinary characters. All ordinary characters (including the terminating null character) are copied unchanged into the output string. A conversion specification defines how data in the tm structure is formatted in the output string.

A conversion specification consists of a percent (%) character followed by one or more optional characters (see Table REF-13), and ending with a conversion specifier (see Table REF-14). If any of the optional characters listed in Table REF-13 are specified, they must appear in the order shown in the table.

Table REF-13 Optional Elements of wcsftime Conversion Specifications

Element	Meaning
--	Optional with the field width to specify that the field is left-justified and padded with spaces. This cannot be used with the 0 element.
0	Optional with the field width to specify that the field is right-justified and padded with zeros. This cannot be used with the -- element.
field width	A decimal integer that specifies the maximum field width
.precision	A decimal integer that specifies the precision of data in a field. For the d, H, I, j, m, M, o, S, U, w, W, y and Y conversion specifiers, the precision specifier is the minimum number of digits to appear in the field. If the conversion specification has fewer digits than that specified by the precision, leading zeros are added. For the a, A, b, B, c, D, E, h, n, N, p, r, t, T, x, X, Z, and % conversion specifiers, the precision specifier is the maximum number of wide characters to appear in the field. If the conversion specification has more characters than that specified by the the precision, characters are truncated on the right. The default precision for the d, H, I, m, M, o, S, U, w, W, y and Y conversion specifiers is 2, and the default precision for the j conversion specifier is 3.

Note that the list of optional elements of conversion specifications from Table REF-13 are Compaq extensions to the XPG4 specification.

Table REF-14 lists the conversion specifiers. The wcsftime function uses fields in the LC_TIME category of the program's current locale to provide a value. For example, if %B is specified, the function accesses the mon field in LC_TIME to find the full month name for the month specified in the tm structure. The result of using invalid conversion specifiers is undefined.

Table REF-14 wcsftime Conversion Specifiers

Specifier	Replaced by
a	The locale's abbreviated weekday name
A	The locale's full weekday name
b	The locale's abbreviated month name
B	The locale's full month name
c	The locale's appropriate date and time representation
C	The century number (the year divided by 100 and truncated to an integer) as a decimal number (00 -- 99)
d	The day of the month as a decimal number (01 -- 31)
D	Same as %m/%d/%y
e	The day of the month as a decimal number (1 -- 31) in a 2 digit field with the leading space character fill
Ec	The locale's alternative date and time representation
EC	The name of the base year (period) in the locale's alternative representation
Ex	The locale's alternative date representation
Ey	The offset from the base year (%EC) in the locale's alternative representation
EY	The locale's full alternative year representation
h	Same as %b
H	The hour (24-hour clock) as a decimal number (00 -- 23)
I	The hour (12-hour clock) as a decimal number (01 -- 12)
j	The day of the year as a decimal number (001 -- 366)
m	The month as a decimal number (01 -- 12)
M	The minute as a decimal number (00 -- 59)
n	The newline character
Od	The day of the month using the locale's alternative numeric symbols
Oe	The date of the month using the locale's alternative numeric symbols
OH	The hour (24-hour clock) using the locale's alternative numeric symbols
OI	The hour (12-hour clock) using the locale's alternative numeric symbols
Om	The month using the locale's alternative numeric symbols
OM	The minutes using the locale's alternative numeric symbols
OS	The seconds using the locale's alternative numeric symbols
Ou	The weekday as a number in the locale's alternative representation (Monday=1)
OU	The week number of the year (Sunday as the first day of the week) using the locale's alternative numeric symbols
OV	The week number of the year (Monday as the first day of the week) as a decimal number (01 --53) using the locale's alterntative numeric symbols. If the week containing January 1 has four or more days in the new year, it is considered as week 1. Otherwise, it is considered as week 53 of the previous year, and the next week is week 1.
Ow	The weekday as a number (Sunday=0) using the locale's alternative numeric symbols
OW	The week number of the year (Monday as the first day of the week) using the locale's alternative numeric symbols
Oy	The year without the century using the locale's alternative numeric symbols
p	The locale's equivalent of the AM/PM designations associated with a 12-hour clock
r	The time in AM/PM notation
R	The time in 24-hour notation (%H:%M)
S	The second as a decimal number (00 -- 61)
t	The tab character
T	The time (%H:%M:%S)
u	The weekday as a decimal number between 1 and 7 (Monday=1)
U	The week number of the year (the first Sunday as the first day of week 1) as a decimal number (00 -- 53)
V	The week number of the year (Monday as the first day of the week) as a decimal number (00 -- 53). If the week containing January 1 has four or more days in the new year, it is considered as week 1. Otherwise, it is considered as week 53 of the previous year, and the next week is week 1.
w	The weekday as a decimal number (0 [Sunday] -- 6)
W	The week number of the year (the first Monday as the first day of week 1) as a decimal number (00 -- 53)
x	The locale's appropriate date representation
X	The locale's appropriate time representation
y	The year without century as a decimal number (00 -- 99)
Y	The year with century as a decimal number
Z	Time-zone name or abbreviation. If time-zone information is not available, no character is output.
%	%

Return Values

x	The number of wide characters placed into the array pointed to by wcs, not including the terminating null character.
0	Indicates an error occurred. The contents of the array are indeterminate.

Example

/* Exercize the wcsftime formating routine. */ /* NOTE: the format string is an "L" (or wide character) */ /* string indicating that this call is NOT in */ /* the XPG4 format, but rather in ISO C format. */ #include <stdlib.h> #include <stdio.h> #include <time.h> #include <wchar.h> #include <locale.h> #include <errno.h> #define NUM_OF_DATES 7 #define BUF_SIZE 256 /* This program formats a number of different dates, once using the */ /* C locale and then using the fr_FR.ISO8859-1 locale. Date and time */ /* formatting is done using wcsftime(). */ main() { int count, i; wchar_t buffer[BUF_SIZE]; struct tm *tm_ptr; time_t time_list[NUM_OF_DATES] = {500, 68200000, 694223999, 694224000, 704900000, 705000000, 705900000}; /* Display dates using the C locale */ printf("\nUsing the C locale:\n\n"); setlocale(LC_ALL, "C"); for (i = 0; i < NUM_OF_DATES; i++) { /* Convert to a tm structure */ tm_ptr = localtime(&time_list[i]); /* Format the date and time */ count = wcsftime(buffer, BUF_SIZE, L"Date: %A %d %B %Y%nTime: %T%n%n", tm_ptr); if (count == 0) { perror("wcsftime"); exit(EXIT_FAILURE); } /* Print the result */ printf("%S", buffer); } /* Display dates using the fr_FR.ISO8859-1 locale */ printf("\nUsing the fr_FR.ISO8859-1 locale:\n\n"); setlocale(LC_ALL, "fr_FR.ISO8859-1"); for (i = 0; i < NUM_OF_DATES; i++) { /* Convert to a tm structure */ tm_ptr = localtime(&time_list[i]); /* Format the date and time */ count = wcsftime(buffer, BUF_SIZE, L"Date: %A %d %B %Y%nTime: %T%n%n", tm_ptr); if (count == 0) { perror("wcsftime"); exit(EXIT_FAILURE); } /* Print the result */ printf("%S", buffer); } }

Running the example program produces the following result:

Using the C locale: Date: Thursday 01 January 1970 Time: 00:08:20 Date: Tuesday 29 February 1972 Time: 08:26:40 Date: Tuesday 31 December 1991 Time: 23:59:59 Date: Wednesday 01 January 1992 Time: 00:00:00 Date: Sunday 03 May 1992 Time: 13:33:20 Date: Monday 04 May 1992 Time: 17:20:00 Date: Friday 15 May 1992 Time: 03:20:00 Using the fr_FR.ISO8859-1 locale: Date: jeudi 01 janvier 1970 Time: 00:08:20 Date: mardi 29 février 1972 Time: 08:26:40 Date: mardi 31 décembre 1991 Time: 23:59:59 Date: mercredi 01 janvier 1992 Time: 00:00:00 Date: dimanche 03 mai 1992 Time: 13:33:20 Date: lundi 04 mai 1992 Time: 17:20:00 Date: vendredi 15 mai 1992 Time: 03:20:00

Returns the number of wide characters in a wide-character string. The returned length does not include the terminating null character.

Format

#include <wchar.h>

size_t wcslen (const wchar_t *wstr);

Arguments

wstr

A pointer to a null-terminated wide-character string.

Return Values

x	The length of the wide-character string, excluding the terminating null wide character.

Concatenates a counted number of wide-characters from one string to another.

Format

#include <wchar.h>

wchar_t *wcsncat (wchar_t *wstr_1, const wchar_t *wstr_2, size_t maxchar);

Arguments

wstr_1, wstr_2

Pointers to null-terminated wide-character strings.

maxchar

The maximum number of wide characters from wstr_2 that are copied to wstr_1. If maxchar is 0, no characters are copied from wstr_2.

Description

This function appends wide characters from the wide-character string wstr_2 to the end of wstr_1, up to a maximum of maxchar characters. A terminating null wide character is always appended to the result of the wcsncat function. Therefore, the maximum number of wide characters that can end up in wstr_1 is wcslen (wstr_1) + maxchar + 1).

See also wcscat in this section.

Return Values

x	The first argument, wstr_1, which is assumed to be large enough to hold the concatenated result.

Example

#include <stdlib.h> #include <stdio.h> #include <wchar.h> #include <string.h> /* This program concatenates two wide-character strings using */ /* the wcsncat function, and then manually compares the result */ /* to the expected result */ #define S1LENGTH 10 #define S2LENGTH 8 #define SIZE 3 main() { int i; wchar_t s1buf[S1LENGTH + S2LENGTH]; wchar_t s2buf[S2LENGTH]; wchar_t test1[S1LENGTH + S2LENGTH]; /* Initialize the three wide-character strings */ if (mbstowcs(s1buf, "abcmnexyz", S1LENGTH) == (size_t)-1) { perror("mbstowcs"); exit(EXIT_FAILURE); } if (mbstowcs(s2buf, " orthis", S2LENGTH) == (size_t)-1) { perror("mbstowcs"); exit(EXIT_FAILURE); } if (mbstowcs(test1, "abcmnexyz orthis", S1LENGTH + SIZE) == (size_t)-1) { perror("mbstowcs"); exit(EXIT_FAILURE); } /* Concatenate s1buf with SIZE characters from s2buf, placing the */ /* result into s1buf. Then compare s1buf with the expected result */ /* in test1. */ wcsncat(s1buf, s2buf, SIZE); for (i = 0; i <= S1LENGTH + SIZE - 2; i++) { /* Check that each character is correct */ if (test1[i] != s1buf[i]) { printf("Error in wcsncat\n"); exit(EXIT_FAILURE); } } printf("Concatenated string: <%S>\n", s1buf); }

Running the example produces the following result:

Concatenated string: <abcmnexyz or>

Compares not more than maxchar characters of two wide-character strings. It returns an integer that indicates if the strings are different, and how they differ.

Format

#include <wchar.h>

int wcsncmp (const wchar_t *wstr_1, const wchar_t *wstr_2, size_t maxchar);

Arguments

wstr_1, wstr_2

Pointers to null-terminated wide-character strings.

maxchar

The maximum number of characters to search in both wstr_1 and wstr_2. If maxchar is 0, no comparison is performed and 0 is returned (the strings are considered equal).

Description

The strings are compared until a null character is encountered, the strings differ, or maxchar is reached. If characters differ, the function returns:

• An integer less than 0 if the codepoint of the first differing character in wstr_1 is less than the codepoint of the corresponding character in wstr_2
• An integer greater than 0 if the codepoint of the first differing character in wstr_1 is greater than the codepoint of the corresponding character in wstr_2

If no differences are found after comparing maxchar characters, the function returns zero.

See also wcscmp in this section.

Return Values

< 0	Indicates that wstr_1 is less than wstr_2.
0	Indicates that wstr_1 equals wstr_2.
> 0	Indicates that wstr_1 is greater than wstr_2.