# 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

### See Also

``intlOpenLocale`(), IntlFormatNumber()`