Class DateTimeFormat
- java.lang.Object
-
- org.joda.time.format.DateTimeFormat
-
public class DateTimeFormat extends java.lang.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 areISODateTimeFormat
andDateTimeFormatterBuilder
.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 '
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:
ISODateTimeFormat
,DateTimeFormatterBuilder
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description (package private) static class
DateTimeFormat.StyleFormatter
(package private) static class
DateTimeFormat.StyleFormatterCacheKey
-
Field Summary
Fields Modifier and Type Field Description private static java.util.concurrent.ConcurrentHashMap<java.lang.String,DateTimeFormatter>
cPatternCache
Maps patterns to formatters, patterns don't vary by locale.private static java.util.concurrent.atomic.AtomicReferenceArray<DateTimeFormatter>
cStyleCache
Maps patterns to formatters, patterns don't vary by locale.(package private) static int
DATE
Type constant for DATE only.(package private) static int
DATETIME
Type constant for DATETIME.(package private) static int
FULL
Style constant for FULL.(package private) static int
LONG
Style constant for LONG.(package private) static int
MEDIUM
Style constant for MEDIUM.(package private) static int
NONE
Style constant for NONE.private static int
PATTERN_CACHE_SIZE
Maximum size of the pattern cache.(package private) static int
SHORT
Style constant for SHORT.(package private) static int
TIME
Type constant for TIME only.
-
Constructor Summary
Constructors Modifier Constructor Description protected
DateTimeFormat()
Constructor.
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description (package private) static void
appendPatternTo(DateTimeFormatterBuilder builder, java.lang.String pattern)
Parses the given pattern and appends the rules to the given DateTimeFormatterBuilder.private static DateTimeFormatter
createDateTimeFormatter(int dateStyle, int timeStyle)
Creates a formatter for the specified style.private static DateTimeFormatter
createFormatterForPattern(java.lang.String pattern)
Select a format from a custom pattern.private static DateTimeFormatter
createFormatterForStyle(java.lang.String style)
Select a format from a two character style pattern.private static DateTimeFormatter
createFormatterForStyleIndex(int dateStyle, int timeStyle)
Gets the formatter for the specified style.static DateTimeFormatter
forPattern(java.lang.String pattern)
Factory to create a formatter from a pattern string.static DateTimeFormatter
forStyle(java.lang.String style)
Factory to create a format from a two character style pattern.static DateTimeFormatter
fullDate()
Creates a format that outputs a full date format.static DateTimeFormatter
fullDateTime()
Creates a format that outputs a full datetime format.static DateTimeFormatter
fullTime()
Creates a format that outputs a full time format.private static boolean
isNumericToken(java.lang.String token)
Returns true if token should be parsed as a numeric field.static DateTimeFormatter
longDate()
Creates a format that outputs a long date format.static DateTimeFormatter
longDateTime()
Creates a format that outputs a long datetime format.static DateTimeFormatter
longTime()
Creates a format that outputs a long time format.static DateTimeFormatter
mediumDate()
Creates a format that outputs a medium date format.static DateTimeFormatter
mediumDateTime()
Creates a format that outputs a medium datetime format.static DateTimeFormatter
mediumTime()
Creates a format that outputs a medium time format.private static void
parsePatternTo(DateTimeFormatterBuilder builder, java.lang.String pattern)
Parses the given pattern and appends the rules to the given DateTimeFormatterBuilder.private static java.lang.String
parseToken(java.lang.String pattern, int[] indexRef)
Parses an individual token.static java.lang.String
patternForStyle(java.lang.String style, java.util.Locale locale)
Returns the pattern used by a particular style and locale.private static int
selectStyle(char ch)
Gets the JDK style code from the Joda code.static DateTimeFormatter
shortDate()
Creates a format that outputs a short date format.static DateTimeFormatter
shortDateTime()
Creates a format that outputs a short datetime format.static DateTimeFormatter
shortTime()
Creates a format that outputs a short time format.
-
-
-
Field Detail
-
FULL
static final int FULL
Style constant for FULL.- See Also:
- Constant Field Values
-
LONG
static final int LONG
Style constant for LONG.- See Also:
- Constant Field Values
-
MEDIUM
static final int MEDIUM
Style constant for MEDIUM.- See Also:
- Constant Field Values
-
SHORT
static final int SHORT
Style constant for SHORT.- See Also:
- Constant Field Values
-
NONE
static final int NONE
Style constant for NONE.- See Also:
- Constant Field Values
-
DATE
static final int DATE
Type constant for DATE only.- See Also:
- Constant Field Values
-
TIME
static final int TIME
Type constant for TIME only.- See Also:
- Constant Field Values
-
DATETIME
static final int DATETIME
Type constant for DATETIME.- See Also:
- Constant Field Values
-
PATTERN_CACHE_SIZE
private static final int PATTERN_CACHE_SIZE
Maximum size of the pattern cache.- See Also:
- Constant Field Values
-
cPatternCache
private static final java.util.concurrent.ConcurrentHashMap<java.lang.String,DateTimeFormatter> cPatternCache
Maps patterns to formatters, patterns don't vary by locale. Size capped at PATTERN_CACHE_SIZE
-
cStyleCache
private static final java.util.concurrent.atomic.AtomicReferenceArray<DateTimeFormatter> cStyleCache
Maps patterns to formatters, patterns don't vary by locale.
-
-
Method Detail
-
forPattern
public static DateTimeFormatter forPattern(java.lang.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:
java.lang.IllegalArgumentException
- if the pattern is invalid
-
forStyle
public static DateTimeFormatter forStyle(java.lang.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:
java.lang.IllegalArgumentException
- if the style is invalid
-
patternForStyle
public static java.lang.String patternForStyle(java.lang.String style, java.util.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:
java.lang.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, java.lang.String pattern)
Parses the given pattern and appends the rules to the given DateTimeFormatterBuilder.- Parameters:
pattern
- pattern specification- Throws:
java.lang.IllegalArgumentException
- if the pattern is invalid
-
parsePatternTo
private static void parsePatternTo(DateTimeFormatterBuilder builder, java.lang.String pattern)
Parses the given pattern and appends the rules to the given DateTimeFormatterBuilder.- Parameters:
pattern
- pattern specification- Throws:
java.lang.IllegalArgumentException
- if the pattern is invalid- See Also:
forPattern(java.lang.String)
-
parseToken
private static java.lang.String parseToken(java.lang.String pattern, int[] indexRef)
Parses an individual token.- Parameters:
pattern
- the pattern stringindexRef
- 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(java.lang.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(java.lang.String pattern)
Select a format from a custom pattern.- Parameters:
pattern
- pattern specification- Throws:
java.lang.IllegalArgumentException
- if the pattern is invalid- See Also:
appendPatternTo(org.joda.time.format.DateTimeFormatterBuilder, java.lang.String)
-
createFormatterForStyle
private static DateTimeFormatter createFormatterForStyle(java.lang.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:
java.lang.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 styletimeStyle
- 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 styletimeStyle
- 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
-
-