C++ wcsftime()

The wcsftime() function in C++ converts the given date and time from a given calendar time time to a null-terminated wide character string according to a format string.

The wcsftime() function is defined in <cwchar> header file.

wcsftime() prototype

size_t wcsftime( wchar_t* str, size_t count, const wchar_t* format, const tm* time );

The wcsftime() function takes 4 arguments: str, count, format and time.

The date and time information pointed to by time is converted to a null-terminated wide character based on the value of format and is stored in the wide array pointed to by str. At most count bytes are written.


wcsftime() Parameters

  • str: Pointer to the first element of the wide character array to store the result.
  • count: Maximum number of wide character to write.
  • format: Pointer to a null-terminated wide character string specifying the format of conversion. The format string consists of conversion specifier (beginning with % and optionally followed by E or O) and other ordinary wide characters.
    The ordinary wide characters including the terminating null wide character are copied as it is to the output wide string.
    Format specifiers for wcsftime()
    Conversion Specifier Description Used Fields
    % Writes the character %
    n Writes newline character
    t Writes horizontal tab character
    Year
    Y Writes 4 digits of year, e.g. 2011 tm_year
    EY Writes 4 digits of year in locale's alternative representation tm_year
    y Writes last 2 digits of year, range [00, 99] tm_year
    Oy Writes the last 2 digits of year in locale's alternative representation tm_year
    Ey Writes year as offset from locale's alternative calendar period %EC (locale-dependent) tm_year
    C Writes first 2 digits of year, range [00,99] tm_year
    EC Writes name of the base year (period) in the locale's alternative representation, tm_year
    G Writes ISO 8601 week-based year, i.e. the year that contains the specified week. tm_year, tm_wday, tm_yday
    g Writes last 2 digits of ISO 8601 week-based year, i.e. the year that contains the specified week (range [00,99]). tm_year, tm_wday, tm_yday
    Month
    b Writes abbreviated month name, e.g. Jan tm_mon
    h Same as b tm_mon
    B Writes full month name, e.g. January tm_mon
    m Writes month as a decimal number, range [01,12] tm_mon
    Om Writes month using the locale's alternative numeric system tm_mon
    Week
    U Writes week of the year as a decimal number from 00 to 53 (Sunday is the first day of the week) tm_year, tm_wday, tm_yday
    OU Writes week of the year as by %U using the alternative numeric system tm_year, tm_wday, tm_yday
    W Writes week of the year as a decimal number from 00 to 53 (Monday is the first day of the week) tm_year, tm_wday, tm_yday
    OW Writes week of the year as by %W using the alternative numeric system tm_year, tm_wday, tm_yday
    V Writes ISO 8601 week of the year (range [01,53]). tm_year, tm_wday, tm_yday
    OV Writes week of the year, as by %V, using the alternative numeric system tm_year, tm_wday, tm_yday
    Day of the year/month
    j Writes day of the year as a decimal number, range [001,366] tm_yday
    d Writes day of the month as a decimal number, range[01,31] tm_mday
    Od Writes day of the month, as by %d, using the alternative numeric system tm_mday
    e Writes day of the month as a decimal number, range[1,31] tm_mday
    Oe Writes day of the month, as by %e, using the alternative numeric system tm_mday
    Day of the week
    a Writes abbreviated weekday name, e.g. Fri (locale dependent) tm_wday
    A Writes full weekday name, e.g. Friday (locale dependent) tm_wday
    w Writes weekday as a decimal number, range [0-6] (Sunday is 0) tm_wday
    Ow Writes weekday as by %w, using the alternative numeric system tm_wday
    u Writes weekday as a decimal number, where Monday is 1 (ISO 8601 format), range [1-7] tm_wday
    Ou Writes weekday as by %u, using the alternative numeric system tm_wday
    Hour, minute, second
    H Writes hour as a decimal number, range [00,23] tm_hour
    OH Writes hour as by %H, using the alternative numeric system tm_hour
    I Writes hour as a decimal number, range[01,12] tm_hour
    OI Writes hour as by %I, using the alternative numeric system tm_hour
    M Writes minute as a decimal number, range [00,59] tm_min
    OM Writes minute as by %M, using the alternative numeric system tm_min
    S Writes second as a decimal number, range [00,60] tm_sec
    OS Writes second as by %S, using the alternative numeric system tm_sec
    Other
    c Writes standard date and time string, e.g. Sun Oct 17 04:41:13 2010 (locale dependent) all
    Ec Writes locale's alternative date and time string all
    x Writes localized date representation (locale dependent) all
    Ex Writes locale's alternative date representation all
    X Writes localized time representation (locale dependent) all
    EX Writes locale's alternative time representation all
    D Equivalent to "%m/%d/%y" tm_mon, tm_mday, tm_year
    F Equivalent to "%Y-%m-%d" tm_mon, tm_mday, tm_year
    r Writes localized 12-hour clock time tm_hour, tm_min, tm_sec
    R Equivalent to "%H:%M" tm_hour, tm_min
    T Equivalent to "%H:%M:%S tm_hour, tm_min, tm_sec
    P Writes localized a.m. or p.m. (locale dependent) tm_hour
    z writes offset from UTC in the ISO 8601 format (e.g. -0545), or no characters if the time zone information is not available tm_isdst
    Z Writes time zone name or abbreviation, or nothing if the time zone information is not available (locale dependent) tm_isdst
  • time: The date and time information to convert.

wcsftime() Return value

  • On success, the wcsftime() function returns the number of wide character written into the wide character array pointed to by str not including the terminating L'\0'.
  • If count was reached before the entire string could be stored, 0 is returned and the contents are undefined.

Example: How wcsftime() function works?

#include <ctime>
#include <cwchar>
#include <iostream>
using namespace std;

int main()
{
	time_t curr_time;
	tm * curr_tm;
	wchar_t date_string[100];
	wchar_t time_string[100];
	
	time(&curr_time);
	curr_tm = localtime(&curr_time);
	
	wcsftime(date_string, 50, L"Today is %B %d, %Y", curr_tm);
	wcsftime(time_string, 50, L"Current time is %T", curr_tm);
	
	wcout << date_string << endl;
	wcout << time_string << endl;
	
	return 0;
}

When you run the program, the output will be:

Today is April 21, 2017
Current time is 14:42:45