Package org.joda.time.format

Class DateTimeFormat

java.lang.Object
org.joda.time.format.DateTimeFormat
public class DateTimeFormat extends Object
Factory that creates instances of DateTimeFormatter from patterns and styles.

Datetime formatting is performed by the DateTimeFormatter class. Three classes provide factory methods to create formatters, and this is one. The others are ISODateTimeFormat and DateTimeFormatterBuilder.

This class provides two types of factory:

  • Pattern provides a DateTimeFormatter based on a pattern string that is mostly compatible with the JDK date patterns.
  • Style provides a DateTimeFormatter based on a two character style, representing short, medium, long and full.

For example, to use a pattern: 

 DateTime dt = new DateTime();
 DateTimeFormatter fmt = DateTimeFormat.forPattern("MMMM, yyyy");
 String str = fmt.print(dt);
The pattern syntax is mostly compatible with java.text.SimpleDateFormat - time zone names cannot be parsed and a few more symbols are supported. All ASCII letters are reserved as pattern letters, which are defined as follows: 
 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           millis        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.

Number: The minimum number of digits. Shorter numbers are zero-padded to this amount. When parsing, any number of digits are accepted.

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.

Millis: The exact number of fractional digits. If more millisecond digits are available then specified the number will be truncated, if there are fewer than specified then the number will be zero-padded to the right. When parsing, only the exact number of digits are accepted.

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.

DateTimeFormat is thread-safe and immutable, and the formatters it returns are as well.

Since:
1.0
See Also:

  • Field Details

  • Constructor Details

    • DateTimeFormat

      protected DateTimeFormat()
      Constructor.
      Since:
      1.1 (previously private)

  • Method Details

    • forPattern

      public static DateTimeFormatter forPattern(String pattern)
      Factory to create a formatter from a pattern string. The pattern string is described above in the class level javadoc. It is very similar to SimpleDateFormat patterns.

      The format may contain locale specific output, and this will change as you change the locale of the formatter. Call DateTimeFormatter.withLocale(Locale) to switch the locale. For example: 

       DateTimeFormat.forPattern(pattern).withLocale(Locale.FRANCE).print(dt);
      Parameters:
      pattern - pattern specification
      Returns:
      the formatter
      Throws:
      IllegalArgumentException - if the pattern is invalid

    • forStyle

      public static DateTimeFormatter forStyle(String style)
      Factory to create a format from a two character style pattern.

      The first character is the date style, and the second character is the time style. Specify a character of 'S' for short style, 'M' for medium, 'L' for long, and 'F' for full. A date or time may be omitted by specifying a style character '-'.

      The returned formatter will dynamically adjust to the locale that the print/parse takes place in. Thus you just call DateTimeFormatter.withLocale(Locale) and the Short/Medium/Long/Full style for that locale will be output. For example: 

       DateTimeFormat.forStyle(style).withLocale(Locale.FRANCE).print(dt);
      Parameters:
      style - two characters from the set {"S", "M", "L", "F", "-"}
      Returns:
      the formatter
      Throws:
      IllegalArgumentException - if the style is invalid

    • patternForStyle

      public static String patternForStyle(String style, Locale locale)
      Returns the pattern used by a particular style and locale.

      The first character is the date style, and the second character is the time style. Specify a character of 'S' for short style, 'M' for medium, 'L' for long, and 'F' for full. A date or time may be omitted by specifying a style character '-'.

      Parameters:
      style - two characters from the set {"S", "M", "L", "F", "-"}
      locale - locale to use, null means default
      Returns:
      the formatter
      Throws:
      IllegalArgumentException - if the style is invalid
      Since:
      1.3

    • shortDate

      public static DateTimeFormatter shortDate()
      Creates a format that outputs a short date format.

      The format will change as you change the locale of the formatter. Call DateTimeFormatter.withLocale(Locale) to switch the locale.

      Returns:
      the formatter

    • shortTime

      public static DateTimeFormatter shortTime()
      Creates a format that outputs a short time format.

      The format will change as you change the locale of the formatter. Call DateTimeFormatter.withLocale(Locale) to switch the locale.

      Returns:
      the formatter

    • shortDateTime

      public static DateTimeFormatter shortDateTime()
      Creates a format that outputs a short datetime format.

      The format will change as you change the locale of the formatter. Call DateTimeFormatter.withLocale(Locale) to switch the locale.

      Returns:
      the formatter

    • mediumDate

      public static DateTimeFormatter mediumDate()
      Creates a format that outputs a medium date format.

      The format will change as you change the locale of the formatter. Call DateTimeFormatter.withLocale(Locale) to switch the locale.

      Returns:
      the formatter

    • mediumTime

      public static DateTimeFormatter mediumTime()
      Creates a format that outputs a medium time format.

      The format will change as you change the locale of the formatter. Call DateTimeFormatter.withLocale(Locale) to switch the locale.

      Returns:
      the formatter

    • mediumDateTime

      public static DateTimeFormatter mediumDateTime()
      Creates a format that outputs a medium datetime format.

      The format will change as you change the locale of the formatter. Call DateTimeFormatter.withLocale(Locale) to switch the locale.

      Returns:
      the formatter

    • longDate

      public static DateTimeFormatter longDate()
      Creates a format that outputs a long date format.

      The format will change as you change the locale of the formatter. Call DateTimeFormatter.withLocale(Locale) to switch the locale.

      Returns:
      the formatter

    • longTime

      public static DateTimeFormatter longTime()
      Creates a format that outputs a long time format.

      The format will change as you change the locale of the formatter. Call DateTimeFormatter.withLocale(Locale) to switch the locale.

      Returns:
      the formatter

    • longDateTime

      public static DateTimeFormatter longDateTime()
      Creates a format that outputs a long datetime format.

      The format will change as you change the locale of the formatter. Call DateTimeFormatter.withLocale(Locale) to switch the locale.

      Returns:
      the formatter

    • fullDate

      public static DateTimeFormatter fullDate()
      Creates a format that outputs a full date format.

      The format will change as you change the locale of the formatter. Call DateTimeFormatter.withLocale(Locale) to switch the locale.

      Returns:
      the formatter

    • fullTime

      public static DateTimeFormatter fullTime()
      Creates a format that outputs a full time format.

      The format will change as you change the locale of the formatter. Call DateTimeFormatter.withLocale(Locale) to switch the locale.

      Returns:
      the formatter

    • fullDateTime

      public static DateTimeFormatter fullDateTime()
      Creates a format that outputs a full datetime format.

      The format will change as you change the locale of the formatter. Call DateTimeFormatter.withLocale(Locale) to switch the locale.

      Returns:
      the formatter

    • appendPatternTo

      static void appendPatternTo(DateTimeFormatterBuilder builder, String pattern)
      Parses the given pattern and appends the rules to the given DateTimeFormatterBuilder.
      Parameters:
      pattern - pattern specification
      Throws:
      IllegalArgumentException - if the pattern is invalid

    • parsePatternTo

      private static void parsePatternTo(DateTimeFormatterBuilder builder, String pattern)
      Parses the given pattern and appends the rules to the given DateTimeFormatterBuilder.
      Parameters:
      pattern - pattern specification
      Throws:
      IllegalArgumentException - if the pattern is invalid
      See Also:

    • parseToken

      private static String parseToken(String pattern, int[] indexRef)
      Parses an individual token.
      Parameters:
      pattern - the pattern string
      indexRef - a single element array, where the input is the start location and the output is the location after parsing the token
      Returns:
      the parsed token

    • isNumericToken

      private static boolean isNumericToken(String token)
      Returns true if token should be parsed as a numeric field.
      Parameters:
      token - the token to parse
      Returns:
      true if numeric field

    • createFormatterForPattern

      private static DateTimeFormatter createFormatterForPattern(String pattern)
      Select a format from a custom pattern.
      Parameters:
      pattern - pattern specification
      Throws:
      IllegalArgumentException - if the pattern is invalid
      See Also:

    • createFormatterForStyle

      private static DateTimeFormatter createFormatterForStyle(String style)
      Select a format from a two character style pattern. The first character is the date style, and the second character is the time style. Specify a character of 'S' for short style, 'M' for medium, 'L' for long, and 'F' for full. A date or time may be omitted by specifying a style character '-'.
      Parameters:
      style - two characters from the set {"S", "M", "L", "F", "-"}
      Throws:
      IllegalArgumentException - if the style is invalid

    • createFormatterForStyleIndex

      private static DateTimeFormatter createFormatterForStyleIndex(int dateStyle, int timeStyle)
      Gets the formatter for the specified style.
      Parameters:
      dateStyle - the date style
      timeStyle - the time style
      Returns:
      the formatter

    • createDateTimeFormatter

      private static DateTimeFormatter createDateTimeFormatter(int dateStyle, int timeStyle)
      Creates a formatter for the specified style.
      Parameters:
      dateStyle - the date style
      timeStyle - the time style
      Returns:
      the formatter

    • selectStyle

      private static int selectStyle(char ch)
      Gets the JDK style code from the Joda code.
      Parameters:
      ch - the Joda style code
      Returns:
      the JDK style code