wcsftime() — Convert to Formatted Date and Time

Format

     #include <wchar.h>
     size_t wcsftime(wchar_t *wdest, size_t maxsize,
                     const wchar_t *format, const struct tm *timeptr);

Language Level

ANSI

Threadsafe

Yes

Locale Sensitive

The behavior of this function might be affected by the LC_CTYPE, LC_TIME, and LC_TOD categories of the current locale if LOCALETYPE(*LOCALE) is specified on the compilation command. The behavior of this function might also be affected by the LC_UNI_CTYPE, LC_UNI_TIME, and LC_UNI_TOD categories of the current locale if LOCALETYPE(*LOCALEUCS2) or LOCALETYPE(*LOCALEUTF) is specified on the compilation command. This function is not available when LOCALETYPE(*CLD) is specified on the compilation command. For more information, see Understanding CCSIDs and Locales.

Wide Character Function

See Wide Characters for more information.

Description

The wcsftime() function converts the time and date specification in the timeptr structure into a wide-character string. It then stores the null-ended string in the array pointed to by wdest according to the format string pointed to by format. The maxsize value specifies the maximum number of wide characters that can be copied into the array. This function is equivalent to strftime(), except that it uses wide characters.

The wcsftime() function works just like the strftime() function, except that it uses wide characters. The format string is a wide-character character string that contains:
  • Conversion-specification characters.
  • Ordinary wide characters, which are copied into the array unchanged.

This function uses the time structure pointed to by timeptr, and if the specifier is locale sensitive, then it will also use the LC_TIME category of the current locale to determine the appropriate replacement value of each valid specifier. The time structure pointed to by timeptr is usually obtained by calling the gmtime() or localtime() function.

Return Value

If the total number of wide characters in the resulting string, including the ending null wide character, does not exceed maxsize, wcsftime() returns the number of wide characters placed into wdest, not including the ending null wide character. Otherwise, the wcsftime() function returns 0 and the contents of the array are indeterminate.

If a conversion error occurs, errno may be set to ECONVERT.

Example

This example obtains the date and time using localtime(), formats the information with the wcsftime(), and prints the date and time.
#include <stdio.h>
#include <time.h>
#include <wchar.h>
 
int main(void)
{
   struct tm *timeptr;
   wchar_t   dest[100];
   time_t    temp;
   size_t    rc;
 
   temp = time(NULL);
   timeptr = localtime(&temp);
   rc = wcsftime(dest, sizeof(dest), L" Today is %A,"
                 L" %b %d.\n Time: %I:%M %p", timeptr);
   printf("%d characters placed in string to make:\n\n%ls\n", rc, dest);
   return 0;
 
   /********************************************************************
      The output should be similar to:
 
      43 characters placed in string to make:
 
       Today is Thursday, Nov 10.
       Time: 04:56 PM
   ********************************************************************/
}

Related Information