On this page

FastDateFormat

public class org.apache.commons.lang3.time.FastDateFormat extends Format implements DateParser, DatePrinter[source]

FastDateFormat is a fast and thread-safe version of java.text.SimpleDateFormat.

To obtain an instance of FastDateFormat, use one of the static factory methods: #getInstance(String, TimeZone, Locale), #getDateInstance(int, TimeZone, Locale), #getTimeInstance(int, TimeZone, Locale), or #getDateTimeInstance(int, int, TimeZone, Locale)

Since FastDateFormat is thread safe, you can use a static member instance:

  private static final FastDateFormat DATE_FORMATTER = FastDateFormat.getDateTimeInstance(FastDateFormat.LONG, FastDateFormat.SHORT);

This class can be used as a direct replacement to SimpleDateFormat in most formatting and parsing situations. This class is especially useful in multi-threaded server environments. SimpleDateFormat is not thread-safe in any JDK version, nor will it be as Sun have closed the bug/RFE.

Note on memory retention: unlike new SimpleDateFormat(pattern), instances obtained from the static factory methods are held in a static cache keyed by (pattern, time zone, locale). The cache is bounded (it is flushed when it exceeds an internal limit) and can be flushed explicitly with #clear(), but each distinct key retains its instance for the lifetime of the JVM until then. Prefer fixed, application-defined patterns; do not pass unvalidated caller-supplied pattern, time zone, or locale values to the factory methods.

All patterns are compatible with SimpleDateFormat (except time zones and some year patterns - see below).

Since 3.2, FastDateFormat supports parsing as well as printing.

Java 1.4 introduced a new pattern letter, 'Z', to represent time zones in RFC822 format (for example, +0800 or -1100). This pattern letter can be used here (on all JDK versions).

In addition, the pattern 'ZZ' has been made to represent ISO 8601 extended format time zones (for example, +08:00 or -11:00). This introduces a minor incompatibility with Java 1.4, but at a gain of useful functionality.

Javadoc cites for the year pattern: For formatting, if the number of pattern letters is 2, the year is truncated to 2 digits; otherwise it is interpreted as a number. Starting with Java 1.7 a pattern of ‘Y’ or ‘YYY’ will be formatted as ‘2003’, while it was ‘03’ in former Java versions. FastDateFormat implements the behavior of Java 7.

Since:

2.0

Constructors

FastDateFormat(String, TimeZone, Locale)

Constructs a new FastDateFormat.

FastDateFormat(String, TimeZone, Locale, Date)

Constructs a new FastDateFormat.
protected FastDateFormat(String pattern, TimeZone timeZone, Locale locale)[source]

Constructs a new FastDateFormat.

Parameters:

  • pattern – java.text.SimpleDateFormat compatible pattern.

  • timeZone – non-null time zone to use.

  • locale – non-null locale to use.

Throws:

java.lang.NullPointerException – Thrown if pattern, timeZone, or locale is null.

protected FastDateFormat(String pattern, TimeZone timeZone, Locale locale, Date centuryStart)[source]

Constructs a new FastDateFormat.

Parameters:

  • pattern – java.text.SimpleDateFormat compatible pattern.

  • timeZone – non-null time zone to use.

  • locale – non-null locale to use.

  • centuryStart – The start of the 100-year period to use as the “default century” for 2 digit year parsing. If centuryStart is null, defaults to now - 80 years.

Throws:

java.lang.NullPointerException – Thrown if pattern, timeZone, or locale is null.

Fields and constants

FULL

FULL locale dependent date or time style.

LONG

LONG locale dependent date or time style.

MEDIUM

MEDIUM locale dependent date or time style.

SHORT

SHORT locale dependent date or time style.
public static final int FULL = 0[source]

FULL locale dependent date or time style.

public static final int LONG = 1[source]

LONG locale dependent date or time style.

public static final int MEDIUM = 2[source]

MEDIUM locale dependent date or time style.

public static final int SHORT = 3[source]

SHORT locale dependent date or time style.

Methods

applyRules(Calendar, StringBuffer)

Deprecated. Performs the formatting by applying the rules to the specified calendar.

equals(Object)

Compares two objects for equality.

format(Object, StringBuffer, FieldPosition)

Formats a Date, Calendar or Long (milliseconds) object.

format(Calendar)

Formats a Calendar object.

format(Calendar, Appendable)

Formats a Calendar object into the supplied StringBuffer.

format(Calendar, StringBuffer)

Deprecated. Formats a Calendar object into the supplied StringBuffer.

format(Date)

Formats a Date object using a GregorianCalendar.

format(Date, Appendable)

Formats a Date object into the supplied StringBuffer using a GregorianCalendar.

format(Date, StringBuffer)

Deprecated. Formats a Date object into the supplied StringBuffer using a GregorianCalendar.

format(long)

Formats a millisecond long value.

format(long, Appendable)

Formats a millisecond long value into the supplied StringBuffer.

format(long, StringBuffer)

Deprecated. Formats a millisecond long value into the supplied StringBuffer.

getDateInstance(int)

Gets a date formatter instance using the specified style in the default time zone and locale.

getDateInstance(int, Locale)

Gets a date formatter instance using the specified style and locale in the default time zone.

getDateInstance(int, TimeZone)

Gets a date formatter instance using the specified style and time zone in the default locale.

getDateInstance(int, TimeZone, Locale)

Gets a date formatter instance using the specified style, time zone and locale.

getDateTimeInstance(int, int)

Gets a date/time formatter instance using the specified style in the default time zone and locale.

getDateTimeInstance(int, int, Locale)

Gets a date/time formatter instance using the specified style and locale in the default time zone.

getDateTimeInstance(int, int, TimeZone)

Gets a date/time formatter instance using the specified style and time zone in the default locale.

getDateTimeInstance(int, int, TimeZone, Locale)

Gets a date/time formatter instance using the specified style, time zone and locale.

getInstance()

Gets a formatter instance using the default pattern in the default locale.

getInstance(String)

Gets a formatter instance using the specified pattern in the default locale and time zone.

getInstance(String, Locale)

Gets a formatter instance using the specified pattern and locale using the default time zone.

getInstance(String, TimeZone)

Gets a formatter instance using the specified pattern and time zone.

getInstance(String, TimeZone, Locale)

Gets a formatter instance using the specified pattern, time zone and locale.

getLocale()

Gets the locale used by this formatter.

getMaxLengthEstimate()

Gets an estimate for the maximum string length that the formatter will produce.

getPattern()

Gets the pattern used by this formatter.

getTimeInstance(int)

Gets a time formatter instance using the specified style in the default time zone and locale.

getTimeInstance(int, Locale)

Gets a time formatter instance using the specified style and locale in the default time zone.

getTimeInstance(int, TimeZone)

Gets a time formatter instance using the specified style and time zone in the default locale.

getTimeInstance(int, TimeZone, Locale)

Gets a time formatter instance using the specified style, time zone and locale.

getTimeZone()

Gets the time zone used by this formatter.

hashCode()

Returns a hash code compatible with equals.

parse(String)

Equivalent to DateFormat.parse(String).

parse(String, ParsePosition)

Equivalent to DateFormat.parse(String, ParsePosition).

parse(String, ParsePosition, Calendar)

Parses a formatted date string according to the format.

parseObject(String, ParsePosition)

toString()

Gets a debugging string version of this formatter.
@Deprecated protected StringBuffer applyRules(Calendar calendar, StringBuffer buf)[source]

Deprecated: Use #format(Calendar, Appendable)

Performs the formatting by applying the rules to the specified calendar.

Parameters:

  • calendar – The calendar to format.

  • buf – The buffer to format into.

Returns:

The specified string buffer.

@Override public boolean equals(Object obj)[source]

Compares two objects for equality.

Parameters:

obj – The object to compare to.

Returns:

true if equal.

@Override public StringBuffer format(Object obj, StringBuffer toAppendTo, FieldPosition pos)[source]

Formats a Date, Calendar or Long (milliseconds) object. This method is an implementation of Format#format(Object, StringBuffer, FieldPosition)

Parameters:

  • obj – The object to format.

  • toAppendTo – The buffer to append to.

  • pos – The position, ignored.

Returns:

The given buffer.

@Override public String format(Calendar calendar)[source]

Formats a Calendar object.

Parameters:

calendar – The calendar to format.

Returns:

The formatted string.

@Override public <B extends Appendable> B format(Calendar calendar, B buf)[source]

Formats a Calendar object into the supplied StringBuffer.

Parameters:

  • calendar – The calendar to format.

  • buf – The buffer to format into.

Returns:

The specified string buffer.

Since:

3.5

Type parameters:

<B> – The Appendable class type, usually StringBuilder or StringBuffer.

@Deprecated @Override public StringBuffer format(Calendar calendar, StringBuffer buf)[source]

Deprecated: Use {#format(Calendar, Appendable).

Formats a Calendar object into the supplied StringBuffer.

Parameters:

  • calendar – The calendar to format.

  • buf – The buffer to format into.

Returns:

The specified string buffer.

@Override public String format(Date date)[source]

Formats a Date object using a GregorianCalendar.

Parameters:

date – The date to format.

Returns:

The formatted string.

@Override public <B extends Appendable> B format(Date date, B buf)[source]

Formats a Date object into the supplied StringBuffer using a GregorianCalendar.

Parameters:

  • date – The date to format.

  • buf – The buffer to format into.

Returns:

The specified string buffer.

Since:

3.5

Type parameters:

<B> – The Appendable class type, usually StringBuilder or StringBuffer.

@Deprecated @Override public StringBuffer format(Date date, StringBuffer buf)[source]

Deprecated: Use {#format(Date, Appendable).

Formats a Date object into the supplied StringBuffer using a GregorianCalendar.

Parameters:

  • date – The date to format.

  • buf – The buffer to format into.

Returns:

The specified string buffer.

@Override public String format(long millis)[source]

Formats a millisecond long value.

Parameters:

millis – The millisecond value to format.

Returns:

The formatted string.

Since:

2.1

@Override public <B extends Appendable> B format(long millis, B buf)[source]

Formats a millisecond long value into the supplied StringBuffer.

Parameters:

  • millis – The millisecond value to format.

  • buf – The buffer to format into.

Returns:

The specified string buffer.

Since:

3.5

Type parameters:

<B> – The Appendable class type, usually StringBuilder or StringBuffer.

@Deprecated @Override public StringBuffer format(long millis, StringBuffer buf)[source]

Deprecated: Use {#format(long, Appendable).

Formats a millisecond long value into the supplied StringBuffer.

Parameters:

  • millis – The millisecond value to format.

  • buf – The buffer to format into.

Returns:

The specified string buffer.

Since:

2.1

public static FastDateFormat getDateInstance(int style)[source]

Gets a date formatter instance using the specified style in the default time zone and locale.

Parameters:

style – date style: #FULL, #LONG, #MEDIUM, or #SHORT.

Returns:

A localized standard date formatter.

Throws:

java.lang.IllegalArgumentException – Thrown if the Locale has no date pattern defined.

Since:

2.1

public static FastDateFormat getDateInstance(int style, Locale locale)[source]

Gets a date formatter instance using the specified style and locale in the default time zone.

Parameters:
Returns:

A localized standard date formatter.

Throws:

java.lang.IllegalArgumentException – Thrown if the Locale has no date pattern defined.

Since:

2.1

public static FastDateFormat getDateInstance(int style, TimeZone timeZone)[source]

Gets a date formatter instance using the specified style and time zone in the default locale.

Parameters:

  • style – date style: #FULL, #LONG, #MEDIUM, or #SHORT.

  • timeZone – optional time zone, overrides time zone of formatted date.

Returns:

A localized standard date formatter.

Throws:

java.lang.IllegalArgumentException – Thrown if the Locale has no date pattern defined.

Since:

2.1

public static FastDateFormat getDateInstance(int style, TimeZone timeZone, Locale locale)[source]

Gets a date formatter instance using the specified style, time zone and locale.

Parameters:

  • style – date style: #FULL, #LONG, #MEDIUM, or #SHORT.

  • timeZone – optional time zone, overrides time zone of formatted date.

  • locale – optional locale, overrides system locale.

Returns:

A localized standard date formatter.

Throws:

java.lang.IllegalArgumentException – Thrown if the Locale has no date pattern defined.

public static FastDateFormat getDateTimeInstance(int dateStyle, int timeStyle)[source]

Gets a date/time formatter instance using the specified style in the default time zone and locale.

Parameters:
Returns:

A localized standard date/time formatter.

Throws:

java.lang.IllegalArgumentException – Thrown if the Locale has no date/time pattern defined.

Since:

2.1

public static FastDateFormat getDateTimeInstance(int dateStyle, int timeStyle, Locale locale)[source]

Gets a date/time formatter instance using the specified style and locale in the default time zone.

Parameters:
Returns:

A localized standard date/time formatter.

Throws:

java.lang.IllegalArgumentException – Thrown if the Locale has no date/time pattern defined.

Since:

2.1

public static FastDateFormat getDateTimeInstance(int dateStyle, int timeStyle, TimeZone timeZone)[source]

Gets a date/time formatter instance using the specified style and time zone in the default locale.

Parameters:
Returns:

A localized standard date/time formatter.

Throws:

java.lang.IllegalArgumentException – Thrown if the Locale has no date/time pattern defined.

Since:

2.1

public static FastDateFormat getDateTimeInstance(int dateStyle, int timeStyle, TimeZone timeZone, Locale locale)[source]

Gets a date/time formatter instance using the specified style, time zone and locale.

Parameters:

  • dateStyle – date style: #FULL, #LONG, #MEDIUM, or #SHORT.

  • timeStyle – time style: #FULL, #LONG, #MEDIUM, or #SHORT.

  • timeZone – optional time zone, overrides time zone of formatted date.

  • locale – optional locale, overrides system locale.

Returns:

A localized standard date/time formatter.

Throws:

java.lang.IllegalArgumentException – Thrown if the Locale has no date/time pattern defined.

public static FastDateFormat getInstance()[source]

Gets a formatter instance using the default pattern in the default locale.

Returns:

A date/time formatter.

public static FastDateFormat getInstance(String pattern)[source]

Gets a formatter instance using the specified pattern in the default locale and time zone.

Parameters:

pattern – java.text.SimpleDateFormat compatible pattern.

Returns:

A pattern based date/time formatter.

Throws:

java.lang.IllegalArgumentException – Thrown if pattern is invalid.

public static FastDateFormat getInstance(String pattern, Locale locale)[source]

Gets a formatter instance using the specified pattern and locale using the default time zone.

Parameters:
Returns:

A pattern based date/time formatter.

Throws:

java.lang.IllegalArgumentException – Thrown if pattern is invalid.

public static FastDateFormat getInstance(String pattern, TimeZone timeZone)[source]

Gets a formatter instance using the specified pattern and time zone.

Parameters:

  • pattern – java.text.SimpleDateFormat compatible pattern.

  • timeZone – optional time zone, overrides time zone of formatted date.

Returns:

A pattern based date/time formatter.

Throws:

java.lang.IllegalArgumentException – Thrown if pattern is invalid.

public static FastDateFormat getInstance(String pattern, TimeZone timeZone, Locale locale)[source]

Gets a formatter instance using the specified pattern, time zone and locale.

Parameters:

  • pattern – java.text.SimpleDateFormat compatible pattern.

  • timeZone – optional time zone, overrides time zone of formatted date.

  • locale – optional locale, overrides system locale.

Returns:

A pattern based date/time formatter.

Throws:

java.lang.IllegalArgumentException – Thrown if pattern is invalid or null.

@Override public Locale getLocale()[source]

Gets the locale used by this formatter.

Returns:

The locale.

public int getMaxLengthEstimate()[source]

Gets an estimate for the maximum string length that the formatter will produce.

The actual formatted length will almost always be less than or equal to this amount.

Returns:

The maximum formatted length.

@Override public String getPattern()[source]

Gets the pattern used by this formatter.

Returns:

The pattern, java.text.SimpleDateFormat compatible.

public static FastDateFormat getTimeInstance(int style)[source]

Gets a time formatter instance using the specified style in the default time zone and locale.

Parameters:

style – time style: #FULL, #LONG, #MEDIUM, or #SHORT.

Returns:

A localized standard time formatter.

Throws:

java.lang.IllegalArgumentException – Thrown if the Locale has no time pattern defined.

Since:

2.1

public static FastDateFormat getTimeInstance(int style, Locale locale)[source]

Gets a time formatter instance using the specified style and locale in the default time zone.

Parameters:
Returns:

A localized standard time formatter.

Throws:

java.lang.IllegalArgumentException – Thrown if the Locale has no time pattern defined.

Since:

2.1

public static FastDateFormat getTimeInstance(int style, TimeZone timeZone)[source]

Gets a time formatter instance using the specified style and time zone in the default locale.

Parameters:

  • style – time style: #FULL, #LONG, #MEDIUM, or #SHORT.

  • timeZone – optional time zone, overrides time zone of formatted time.

Returns:

A localized standard time formatter.

Throws:

java.lang.IllegalArgumentException – Thrown if the Locale has no time pattern defined.

Since:

2.1

public static FastDateFormat getTimeInstance(int style, TimeZone timeZone, Locale locale)[source]

Gets a time formatter instance using the specified style, time zone and locale.

Parameters:

  • style – time style: #FULL, #LONG, #MEDIUM, or #SHORT.

  • timeZone – optional time zone, overrides time zone of formatted time.

  • locale – optional locale, overrides system locale.

Returns:

A localized standard time formatter.

Throws:

java.lang.IllegalArgumentException – Thrown if the Locale has no time pattern defined.

@Override public TimeZone getTimeZone()[source]

Gets the time zone used by this formatter.

This zone is always used for Date formatting.

Returns:

A copy of the time zone, changing it has no effect on this formatter.

@Override public int hashCode()[source]

Returns a hash code compatible with equals.

Returns:

A hash code compatible with equals.

@Override public Date parse(String source) throws ParseException[source]

Equivalent to DateFormat.parse(String). See java.text.DateFormat#parse(String) for more information.

Parameters:

source – A String whose beginning should be parsed.

Returns:

A Date parsed from the string.

Throws:

java.text.ParseException – Thrown if the beginning of the specified string cannot be parsed.

@Override public Date parse(String source, ParsePosition pos)[source]

Equivalent to DateFormat.parse(String, ParsePosition). See java.text.DateFormat#parse(String, ParsePosition) for more information.

Parameters:

  • source – A String, part of which should be parsed.

  • pos – A ParsePosition object with index and error index information as described above.

Returns:

A Date parsed from the string. In case of error, returns null.

@Override public boolean parse(String source, ParsePosition pos, Calendar calendar)[source]

Parses a formatted date string according to the format. Updates the Calendar with parsed fields. Upon success, the ParsePosition index is updated to indicate how much of the source text was consumed. Not all source text needs to be consumed. Upon parse failure, ParsePosition error index is updated to the offset of the source text which does not match the supplied format.

Parameters:

  • source – The text to parse.

  • pos – On input, the position in the source to start parsing, on output, updated position.

  • calendar – The calendar into which to set parsed fields.

Returns:

true, if source has been parsed (pos parsePosition is updated); otherwise false (and pos errorIndex is updated)

@Override public Object parseObject(String source, ParsePosition pos)[source]
@Override public String toString()[source]

Gets a debugging string version of this formatter.

Returns:

A debug string.