get_time_format


template<class character>
int get_time_format(locale_identity Locale,
                    unsigned flags,
                    const system_time* time,
                    const character* format,
                    character* string,
                    int length)

This function formats a time string relative to a given locale's settings.

Parameters

locale_identity Locale

The locale identity. This identity may be formed via the function make_locale or it may be one of the predefined locales locale_system_default or locale_user_default.

If the parameter format is null, the locale is used to determine the format of the output string; otherwise, the locale is used only to determine information not specified in the format string (such as AM and PM indicators).

unsigned flags

A combination of flags from the enumeration time_format. Additionally, the flag locale_types::use_no_override may be specified, in which case, the system ANSI code page settings are utilized without making use of any locale overrides. This value is used only if the parameter Format is non-null.

const system_time* time

A pointer to a system time structure defining the time to be formatted. If this parameter is null, the current local time on the system is used.

const character* format

A pointer to a string describing the manner in which the time is formatted. If this parameter is null, the time format associated with the specified locale is used. The following table indicates how the time format may be specified (noting that case is significant in the specification).

h Hours with no leading zero (when in single figures) on a 12 hour clock.
hh Hours with leading zero (when in single figures) on a 12 hour clock.
H Hours with no leading zero (when in single figures) on a 24 hour clock.
HH Hours with leading zero (when in single figures) on a 24 hour clock.
m Minutes with no leading zero (when in single figures).
mm Minutes with leading zero (when in single figures).
s Seconds with no leading zero (when in single figures).
ss Seconds with leading zero (when in single figures).
t Time marker with single letter (such as A or P).
tt Time marker with multiple letters (such as AM or PM).

Characters that are to be contained in the output string should be enclosed in single quotes (note that spaces are also preserved in the output string). Literals that are enclosed within single quotes are reproduced exactly in the output string. An example specification is "hh':'mm':'ss tt" which would produce times that look like: 01:07:09 AM. To obtain a quote in the output string, two successive single quotes should be used to represent a literal quotation mark (e.g. "MMMM ''''yy" is capable of producing May '99. Here, within two quotes are enclosed two more quotes representing the literal quotation character.

character* string

A pointer to a buffer that is updated to hold the required time string.

int length

The size (in characters) of the buffer pointed to by the previous parameter. If zero is specified, the required buffer length is returned and the previous parameter is ignored.

Return

int

If the parameter Length is set to zero, the value returned is the number of characters required for the string to fit the buffer. If Length is non-zero, the value returned is the number of characters transferred to the buffer. If an error occurrs, zero is returned.

Notes

The date portions of the specified system_time structure are ignored. The relevant time portions of this structure are validated, and an error is flagged if any of the time portions are invalid.

If the flag locale_types::use_no_override is specified, the parameter Format should be set to null.