intlFormatDate

Formats a date in a localized manner.

Synopsis

int32 intlFormatDate(Item locItem,DateSpec spec,const GregorianDate *date,unichar *result, uint32 resultSize);

Description

This function formats a date according to a template and to the rules specified by the locale item provided. The formatting string works in a manner similar to the way printf() formatting strings are handled, but uses some specialized format commands tailored to date generation. The following format commands are supported:

%D - day of month

%H - hour using 24-hour style

%h - hour using 12-hour style

%M - minutes

%N - month name

%n - abbreviated month name

%O - month number

%P - AM or PM strings

%S - seconds

%W - weekday name

%w - abbreviated weekday name

%Y - year

In addition to straight format commands, the formatting string can also specify a field width, a field limit, and a field pad character. This is done in a manner identical to the way printf() formatting strings specify these values. That is

%[flags][width][.limit]command

where flags can be "-" or "0", width is a positive numeric value, limit is a positive numeric value, and command is one of the format commands mentioned above. Refer to documentation on the standard C printf() function for more information on how these numbers and flags interact.

A difference with standard printf() processing is that the limit value is applied starting from the rightmost digits, instead of the leftmost. For example;

%.2Y

Prints the rightmost two digits of the current year.

Arguments

locItem: A locale item, as obtained from intlOpenLocale().

spec: The formatting template describing the date layout. This value is typically taken from the locale structure (loc_Date, loc_ShortDate, loc_Time, loc_ShortTime), but it can also be built up by the title for custom formatting.

date: The date to convert into a string.

result: Where the result of the formatting is put.

resultSize: The number of bytes available in the result buffer. This limits the number of bytes that are put into the buffer.

Return Value

If positive, then the number of characters in the result buffer. If negative, then an error code. The string copied into the result buffer is guaranteed to be NULL-terminated.

> = 0: Number of characters copied.

INTL_ERR_BADRESULTBUFFER

The result buffer pointer was NULL or wasn't invalid writable memory.

INTL_ERR_BUFFERTOOSMALL

There was not enough room in the result buffer.

INTL_ERR_BADDATESPEC: The pointer to the DateSpec array was bad.

INTL_ERR_BADITEM: locItem was not an existing locale item.

INTL_ERR_BADDATE: The date specified in the GregorianDate structure is not a valid date. For example, the gd_Month is greater than 12.

Implementation

Folio call implemented in international folio V24.

Associated Files

intl.h