Formatting

Joda-Time provides a comprehensive formatting system. There are two layers:

  • High level - pre-packaged constant formatters
  • Mid level - pattern-based, like SimpleDateFormat
  • Low level - builder

Constant and Localized formatting

The class ISODateTimeFormat contains a large number of pre-defined formatters based on the ISO-8601 specification (although not all are fully compatible). These handle many common cases.

The class DateTimeFormat contains an additional set of pre-defined formatters based on Locale. These "style-based" formatters handle the case where the application needs to format a date-time in a manner appropriate to a particular global location.

Pattern-based formatting

The class DateTimeFormat provides a single method forPattern(String) that supports formatting by pattern. These "pattern-based" formatters provide a similar approach to that of SimpleDateFormat.

For example:

LocalDate date = LocalDate.now();
DateTimeFormatter fmt = DateTimeFormat.forPattern("d MMMM, yyyy");
String str = date.toString(fmt);
// might output "6 October, 2013"

The pattern letters are:

Symbol  Meaning                      Presentation  Examples
------  -------                      ------------  -------
 G       era                          text          AD
 C       century of era (>=0)         number        20
 Y       year of era (>=0)            year          1996

 x       weekyear                     year          1996
 w       week of weekyear             number        27
 e       day of week                  number        2
 E       day of week                  text          Tuesday; Tue

 y       year                         year          1996
 D       day of year                  number        189
 M       month of year                month         July; Jul; 07
 d       day of month                 number        10

 a       halfday of day               text          PM
 K       hour of halfday (0~11)       number        0
 h       clockhour of halfday (1~12)  number        12

 H       hour of day (0~23)           number        0
 k       clockhour of day (1~24)      number        24
 m       minute of hour               number        30
 s       second of minute             number        55
 S       fraction of second           number        978

 z       time zone                    text          Pacific Standard Time; PST
 Z       time zone offset/id          zone          -0800; -08:00; America/Los_Angeles

 '       escape for text              delimiter
 ''      single quote                 literal       '

The count of pattern letters determine the format.

Text: If the number of pattern letters is 4 or more, the full form is used; otherwise a short or abbreviated form is used if available. Thus, "EEEE" might output "Monday" whereas "E" might output "Mon" (the short form of Monday).

Number: The minimum number of digits. Shorter numbers are zero-padded to this amount. Thus, "HH" might output "09" whereas "H" might output "9" (for the hour-of-day of 9 in the morning).

Year: Numeric presentation for year and weekyear fields are handled specially. For example, if the count of 'y' is 2, the year will be displayed as the zero-based year of the century, which is two digits.

Month: 3 or over, use text, otherwise use number. Thus, "MM" might output "03" whereas "MMM" might output "Mar" (the short form of March) and "MMMM" might output "March".

Zone: 'Z' outputs offset without a colon, 'ZZ' outputs the offset with a colon, 'ZZZ' or more outputs the zone id.

Zone names: Time zone names ('z') cannot be parsed.

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 embraced within single quotes.

Builder

All formatting is ultimately built using DateTimeFormatterBuilder. The builder allows a format pattern to be built up step by step, consisting of literal, text, numeric, pattern and localized elements in any order. Some facilities are only available via the builder.

For example, this will build a formatter consisting of the month and year:

DateTimeFormatter monthAndYear = new DateTimeFormatterBuilder()
     .appendMonthOfYearText()
     .appendLiteral(' ')
     .appendYear(4, 4)
     .toFormatter();


Back to top

Version: 2.6. Last Published: 2014-12-02.

Reflow Maven skin by Andrius Velykis.