Languages Around The World

Formatting Dates and Times

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."

ICU has three formatting classes for creating dates and times that are easily localizable:

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:

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.

NoteRemember 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:

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.

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

Date/Time Format Syntax

The date/time format is specified by means of a string time pattern. The count of pattern letters determines the format. In this pattern, letters are reserved as pattern letters:

Symbol Meaning Presentation Example
G era designator (Text) AD
y year (Number) 1996
M month in year (Text and Number) July and 07
d day in month (Number) 10
h hour in am/pm (1~12) (Number) 12
H hour in day (0~23) (Number) 0
m minute in hour (Number) 30
s second in minute (Number) 55
S millisecond (Number) 978
E day in week (Text) Tuesday
D day in year (Number) 189
F day of week in month (Number) 2 (2nd Wed in July)
w week in year (Number) 27
W week in month (Number) 2
a am/pm marker (Text) pm
k hour in day (1~24) (Number) 24
K hour in am/pm (0~11) (Number) 0
Z time zone (Text) Pacific Standard Time
' escape for text
'' single quote '

Text

Number

Text and Number

NoteAny 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.
A pattern containing any invalid pattern letter results in a failing UErrorCode result during formatting or parsing.

Format Pattern Result
"yyyy.MM.dd G 'at' HH:mm:ss Z" 1996.07.10 AD at 15:08:56 PDT
"EEE, MMM d, ''yy" Wed, July 10, '96
"h:mm a" 8:08 PM
"hh 'o''clock' a, ZZZZ" 09 o'clock AM. Eastern Standard Time
"K:mm a, Z" 9:34 AM, PST
"yyyyy.MMMMM.dd GGG hh:mm aaa" 1996.July.10 AD 12:08 PM

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.

Programming Examples

Programming for date and time formatting in C and C++.



Copyright (c) 2000 - 2004 IBM and Others - PDF Version - Feedback: icu-issues@oss.software.ibm.com

User Guide for ICU v3.2 Generated 2004-11-22.