Formatting Dates and Times Overview

Date and time formatters are used to convert dates and times from their internal representations to textual form and back again in a language-independent manner. The date and time formatters use UDate, which is the internal representation. Converting from the internal representation (milliseconds since midnight, January 1, 1970) to text is known as "formatting," and converting from text to milliseconds is known as "parsing."

DateFormat

DateFormat helps format and parse dates for any locale. Your code can be completely independent of the locale conventions for months, days of the week, or calendar format.

Formatting Dates

The DateFormat interface in ICU enables you to format a Date in milliseconds into a string representation of the date. It also parses the string back to the internal Date representation in milliseconds.

DateFormat* df = DateFormat::createDateInstance();
UnicodeString myString;
UDate myDateArr[] = { 0.0, 100000000.0, 2000000000.0 };
for (int32_t i = 0; i < 3; ++i) {
  myString.remove();
  cout << df->format( myDateArr[i], myString ) << endl;
}

To format a date for a different Locale, specify it in the call to:

DateFormat* df = DateFormat::createDateInstance
   ( DateFormat::SHORT, Locale::getFrance());

Parsing Dates

Use a DateFormat to parse also:

UErrorCode status = ZERO_ERROR;
UDate myDate = df->parse(myString, status);

Producing Normal Date Formats for a Locale

Use createDateInstance to produce the normal date format for that country. There are other static factory methods available. Use createTimeInstance to produce the normal time format for that country. Use createDateTimeInstance to produce a DateFormat that formats both date and time. You can pass different options to these factory methods to control the length of the result; from SHORT to MEDIUM to LONG to FULL. The exact result depends on the locale, but generally:

1. SHORT is numeric, such as 12/13/52 or 3:30pm

2. MEDIUM is longer, such as Jan. 12, 1952

3. LONG is longer, such as January 12, 1952 or 3:30:32pm

4. FULL is completely specified, such as Tuesday, April 12, 1952 AD or 3:30:42pm PST

Setting Time Zones

You can set the time zone on the format. If you want more control over the format or parsing, cast the DateFormat you get from the factory methods to a SimpleDateFormat. This works for the majority of countries.

Remember to check getDynamicClassID() before carrying out the cast.

Working with Positions

You can also use forms of the parse and format methods with ParsePosition and FieldPosition to enable you to:

1. Progressively parse through pieces of a string.

2. Align any particular field, or find out where it is for selection on the screen.

SimpleDateFormat

SimpleDateFormat is a concrete class used for formatting and parsing dates in a language-independent manner. It allows for formatting, parsing, and normalization. It formats or parses a date or time, which is the standard milliseconds since 24:00 GMT, Jan. 1, 1970.

SimpleDateFormat is the only built-in implementation of DateFormat. It provides a programmable interface that can be used to produce formatted dates and times in a wide variety of formats. The formats include almost all of the most common ones.

Create a date-time formatter using the following methods rather than constructing an instance of SimpleDateFormat. In this way, the program is guaranteed to get an appropriate formatting pattern of the locale.

1. DateFormat::getInstance()

2. getDateInstance()

3. getDateTimeInstance()

If you need a more unusual pattern, construct a SimpleDateFormat directly and give it an appropriate pattern.

Date/Time Format Syntax

A date pattern is a string of characters, where specific strings of characters are replaced with date and time data from a calendar when formatting or used to generate data for a calendar when parsing.

The Date Field Symbol Table below contains the characters used in patterns to show the appropriate formats for a given locale, such as yyyy for the year. Characters may be used multiple times. For example, if y is used for the year, 'yy' might produce '99', whereas 'yyyy' produces '1999'. For most numerical fields, the number of characters specifies the field width. For example, if h is the hour, 'h' might produce '5', but 'hh' produces '05'. For some characters, the count specifies whether an abbreviated or full form should be used, but may have other choices, as given below.

Two single quotes represents a literal single quote, either inside or outside single quotes. Text within single quotes is not interpreted in any way (except for two adjacent single quotes). Otherwise all ASCII letter from a to z and A to Z are reserved as syntax characters, and require quoting if they are to represent literal characters. In addition, certain ASCII punctuation characters may become variable in the future (eg ":" being interpreted as the time separator and '/' as a date separator, and replaced by respective locale-sensitive characters in display).

"Stand Alone" values refer to those designed to stand on their own, as opposed to being with other formatted values. "2nd quarter" would use the stand alone format (QQQQ), whereas "2nd quarter 2007" would use the regular format (qqqq yyyy).

Any characters in the pattern that are not in the ranges of ['a'..'z'] and ['A'..'Z'] will be treated as quoted text. For instance, characters like ':', '.', ' ', '#' and '@' will appear in the resulting time text even they are not enclosed within single quotes.The single quote is used to 'escape' letters. Two single quotes in a row, whether inside or outside a quoted sequence, represent a 'real' single quote.

Time Zone Display Names

ICU supports time zone display names defined by the LDML (Unicode Locale Data Markup Language ) specification. Since ICU 3.8, the vast majority of localized time zone names are no longer associated with individual time zones. Instead, a set of localized time zone names are associated with a metazone and one or more individual time zones are mapped to the same metazone. For example, metazone “America_Pacific” has its own display name data such as “PST” “PDT” “PT” “Pacific Standard Time” “Pacific Daylight Time” “Pacific Time” and these names are shared by multiple individual time zones “America/Los_Angeles”, “America/Vancouver”, “America/Tijuana” and so on. The mapping from individual time zone to metazone is not a simple 1-to-1 mapping, but it changes time to time. For example, time zone “America/Indiana/Tell_City” uses name data from metazone “America_Eastern” until April 2, 2006, but it   changes to metazone “America_Central” after the date. So the display name used for “America/Indiana/Tell_City” before the date (e.g. “Eastern Time”) differs from the one after the date (e.g. “Central Time).

Prior to ICU 3.8, a localized time zone name (except GMT format) and a time zone ID was in 1-to-1 relationship always. Therefore, a time zone name produced by DateFormat can be parsed back to the original time zone. This assumption no longer applies to ICU 3.8 and later releases for all time zone format types. If you program requires to roundtrip specific time zone ID, you must use the generic location format (“VVVV”) explained below.

There are several different display name types available in the LDML specification.

Each format type in the above table is used as a primary type or a fallback in SimpleDateFormat. The table below explains how ICU time zone format pattern work and its characteristics.

* At a transition from daylight saving time to standard time, there is a wall time interval occurs twice.

DateFormatSymbols

DateFormatSymbols is a public class for encapsulating localizable date-time formatting data, including time zone data. DateFormatSymbols is used by DateFormat and SimpleDateFormat.

DateFormatSymbols specifies the exact character strings to use for various parts of a date or time For example, the names of the months and days of the week, the strings for AM and PM and the day of the week considered to be the first day of the week (used in drawing calendar grids) are controlled by DateFormatSymbols.

Create a date-time formatter using the createTimeInstance, createDateInstance, or createDateTimeInstance methods in DateFormat. Each of these methods can return a date/time formatter initialized with a default format pattern, along with the date-time formatting data for a given or default locale. After a formatter is created, modify the format pattern using applyPattern.

If you want to create a date-time formatter with a particular format pattern and locale, use one of the SimpleDateFormat constructors:

UnicodeString aPattern("GyyyyMMddHHmmssSSZ", "");
new SimpleDateFormat(aPattern, new DateFormatSymbols(Locale::getUS())

This loads the appropriate date-time formatting data from the locale.s

Programming Examples

See date and time formatting examples .