## Date and Time Formatting Demo Guide

(Java not enabled in this browser)

Date and time formatters convert internal time data into text strings for meaningful display. The date and time formatters:

- Handle timezones and daylight savings adjustments
- Support multiple calendars
- Support European date fields such as the number of the week in the year
- Like the number formatters:
  - Support definition of formats with string patterns and can retrieve the normalized pattern
  - Can parse anything they can format

Localized Formatting and Parsing Editing Format Patterns
Date Formatting Utilities

### Localized Formatting and Parsing

The date and time formatters let you format the time according to the language, format, and time zone for a given country. The formatters also provide language-specific parsing.

The applet displays the date in two formats—the Java 1.0 representation ("1.0 Date") and the localized format generated by the date and time formatters ("New Date").

To See This... | Do This...
--- | ---

Dates localized for the language and time zones of the selected locale. (Note: Japanese is not yet displayable.)

1. | Pull down the Locale menu
2. | Try several different locales with the up and down arrow keys (on Windows) or the mouse button (on Macintosh)

The formatter can parse changes to the formatted date and reflect it in the Java date and the value in milliseconds.

1. | Select an English locale
2. | Replace the month name in the formatted date with "June"

The formatter formats correctly for different time zones within a country, for example, Pacific or Eastern time. It also switches automatically between standard time or daylight savings time based on the current date within the year.

1. | Select the U.S. locale
2. | Select the Time Format. (the formatted date will indicate Pacific Daylight time)
3. | Pull down the City menu and select different cities to see the time in different U.S. time zones

Note: The dates shown here are all based on the Gregorian calendar. The time formatting classes define an abstract calendar class that can be extended to support non-Gregorian calendars. This can be used by programmers that have no special knowledge of calendaring systems.

### Editing Format Patterns

As with the number formatters, you can easily create and modify date and time formats by specifying string patterns. You can also add new fields to the format, and create formats used for business purposes in some countries.

To See This... | Do This...
--- | ---

The format pattern supports a variety of fields, and supports both full and abbreviated formats for some fields. The month, for example, can be numeric, abbreviated, or full.

1. | Select the Date Format and the English (U.S.) locale
2. | In the Pattern field, delete an "M"—the month changes to the abbreviated format
3. | Delete another "M"—the month changes to the numeric format

You can specify formats used in business documents, such as day of the year. You can also add unformatted strings to the pattern by enclosing them in single quotes.

1. | Select the month and day fields in the pattern ("MM dd")
2. | Replace it with the string (including the single quotes) "'day' D"

### Date Formatting Utilities

The formatters also provide a number of utilities that you can use to build date and time widgets, including adding to or rolling fields.

To See This... | Do This...
--- | ---

"Rolling" a field prevents other fields from being affected by the change.

1. | Select the Date Format and the English (U.S.) locale
2. | Select Month in the Date Fields menu
3. | Click on the Roll button and click the up-arrow button until the formatted date reaches December
4. | Click again—the month rolls to January but the year does not increment

"Adding" to a field causes other fields to be affected by the change as appropriate.

1. | Click on the Add button
2. | Click on the up- or down-arrow button until the formatted date reaches January
3. | Click on the down-arrow button—the month changes to December, and the year decrements by one

Note that the formatter can handle a wide range of dates. (Note: Currently there is a bug that causes problems with dates before 1200 BC and after 5000 AD).

To See This... | Do This...
--- | ---

The formatted date changes to reflect changes in the millisecond value of the date.

1. | Select the Date Format and the English (U.S.) locale
2. | Type a "G" at the end of the pattern string to display the era
3. | Select the milliseconds field and replace it with a "1"
3. | Add zeroes until you reach the year 5000 AD (you could also start at "-1" and add zeroes to go backwards in time)

You can type in other dates in either date field or enter a completely new pattern to see different formatting behaviors. Try it out! The formatter supports many different fields you can use to create patterns. ASCII letters are reserved as pattern letters (unless enclosed in quotes), defined as the following:

        Symbol   Meaning                 Presentation        Example
        ------   -------                 ------------        -------
        G        era designator          (Text)              AD
        y        year                    (Number)            1996
        M        month in year           (Text & Number)     July & 07
        d        day in month            (Number)            10
        k        hour in day             (Number)            24
        H        hour in day, 0-based    (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
        h        hour in am/pm           (Number)            12
        K        hour in am/pm, 0-based  (Number)            0
        z        time zone               (Text)              Pacific Standard Time
        '        escape for text
        ''       single quote                                '

The source.

© Copyright 1997. All rights reserved. Taligent, Inc., IBM Corp.