* This utility class provides three different ways to obtain a formatter. *
* *
* This method will create a formatter based on a simple pattern of letters and symbols. * For example, {@code d MMM yyyy} will format 2011-12-03 as '3 Dec 2011'. *
* The returned formatter will use the default locale, but this can be changed * using {@link DateTimeFormatter#withLocale(Locale)}. *
* All letters 'A' to 'Z' and 'a' to 'z' are reserved as pattern letters. * The following pattern letters are defined: *
* Symbol Meaning Presentation Examples
* ------ ------- ------------ -------
* G era number/text 1; 01; AD; Anno Domini
* y year year 2004; 04
* D day-of-year number 189
* M month-of-year number/text 7; 07; Jul; July; J
* d day-of-month number 10
*
* Q quarter-of-year number/text 3; 03; Q3
* Y week-based-year year 1996; 96
* w week-of-year number 27
* W week-of-month number 27
* e localized day-of-week number 2; Tue; Tuesday; T
* E day-of-week number/text 2; Tue; Tuesday; T
* F week-of-month number 3
*
* a am-pm-of-day text PM
* h clock-hour-of-am-pm (1-12) number 12
* K hour-of-am-pm (0-11) number 0
* k clock-hour-of-am-pm (1-24) number 0
*
* H hour-of-day (0-23) number 0
* m minute-of-hour number 30
* s second-of-minute number 55
* S fraction-of-second fraction 978
* A milli-of-day number 1234
* n nano-of-second number 987654321
* N nano-of-day number 1234000000
*
* I time-zone ID zoneId America/Los_Angeles
* z time-zone name text Pacific Standard Time; PST
* Z zone-offset offset-Z +0000; -0800; -08:00;
* X zone-offset 'Z' for zero offset-X Z; -08; -0830; -08:30; -083015; -08:30:15;
*
* p pad next pad modifier 1
*
* ' escape for text delimiter
* '' single quote literal '
* [ optional section start
* ] optional section end
* {} reserved for future use
*
* * The count of pattern letters determine the format. *
* Text: The text style is determined based on the number of pattern letters used. * Less than 4 pattern letters will use the {@link TextStyle#SHORT short form}. * Exactly 4 pattern letters will use the {@link TextStyle#FULL full form}. * Exactly 5 pattern letters will use the {@link TextStyle#NARROW narrow form}. *
* Number: If the count of letters is one, then the value is printed using the minimum number * of digits and without padding as per {@link DateTimeFormatterBuilder#appendValue(java.time.temporal.TemporalField)}. * Otherwise, the count of digits is used as the width of the output field as per * {@link DateTimeFormatterBuilder#appendValue(java.time.temporal.TemporalField, int)}. *
* Number/Text: If the count of pattern letters is 3 or greater, use the Text rules above. * Otherwise use the Number rules above. *
* Fraction: Outputs the nano-of-second field as a fraction-of-second. * The nano-of-second value has nine digits, thus the count of pattern letters is from 1 to 9. * If it is less than 9, then the nano-of-second value is truncated, with only the most * significant digits being output. * When parsing in strict mode, the number of parsed digits must match the count of pattern letters. * When parsing in lenient mode, the number of parsed digits must be at least the count of pattern * letters, up to 9 digits. *
* Year: The count of letters determines the minimum field width below which padding is used. * If the count of letters is two, then a {@link DateTimeFormatterBuilder#appendValueReduced reduced} * two digit form is used. * For printing, this outputs the rightmost two digits. For parsing, this will parse using the * base value of 2000, resulting in a year within the range 2000 to 2099 inclusive. * If the count of letters is less than four (but not two), then the sign is only output for negative * years as per {@link SignStyle#NORMAL}. * Otherwise, the sign is output if the pad width is exceeded, as per {@link SignStyle#EXCEEDS_PAD} *
* ZoneId: 'I' outputs the zone ID, such as 'Europe/Paris'. *
* Offset X: This formats the offset using 'Z' when the offset is zero. * One letter outputs just the hour', such as '+01' * Two letters outputs the hour and minute, without a colon, such as '+0130'. * Three letters outputs the hour and minute, with a colon, such as '+01:30'. * Four letters outputs the hour and minute and optional second, without a colon, such as '+013015'. * Five letters outputs the hour and minute and optional second, with a colon, such as '+01:30:15'. *
* Offset Z: This formats the offset using '+0000' or '+00:00' when the offset is zero. * One or two letters outputs the hour and minute, without a colon, such as '+0130'. * Three letters outputs the hour and minute, with a colon, such as '+01:30'. *
* Zone names: Time zone names ('z') cannot be parsed. *
* Optional section: The optional section markers work exactly like calling * {@link DateTimeFormatterBuilder#optionalStart()} and {@link DateTimeFormatterBuilder#optionalEnd()}. *
* Pad modifier: Modifies the pattern that immediately follows to be padded with spaces. * The pad width is determined by the number of pattern letters. * This is the same as calling {@link DateTimeFormatterBuilder#padNext(int)}. *
* For example, 'ppH' outputs the hour-of-day padded on the left with spaces to a width of 2. *
* Any unrecognized letter is an error. * Any non-letter character, other than '[', ']', '{', '}' and the single quote will be output directly. * Despite this, it is recommended to use single quotes around all characters that you want to * output directly to ensure that future changes do not break your application. *
* The pattern string is similar, but not identical, to {@link java.text.SimpleDateFormat SimpleDateFormat}. * Pattern letters 'E' and 'u' are merged, which changes the meaning of "E" and "EE" to be numeric. * Pattern letters 'Z' and 'X' are extended. * Pattern letter 'y' and 'Y' parse years of two digits and more than 4 digits differently. * Pattern letters 'n', 'A', 'N', 'I' and 'p' are added. * Number types will reject large numbers. * The pattern string is also similar, but not identical, to that defined by the * Unicode Common Locale Data Repository (CLDR). * * @param pattern the pattern to use, not null * @return the formatter based on the pattern, not null * @throws IllegalArgumentException if the pattern is invalid * @see DateTimeFormatterBuilder#appendPattern(String) */ public static DateTimeFormatter pattern(String pattern) { return new DateTimeFormatterBuilder().appendPattern(pattern).toFormatter(); } /** * Creates a formatter using the specified pattern. *
* This method will create a formatter based on a simple pattern of letters and symbols. * For example, {@code d MMM yyyy} will format 2011-12-03 as '3 Dec 2011'. *
* See {@link #pattern(String)} for details of the pattern. *
* The returned formatter will use the specified locale, but this can be changed * using {@link DateTimeFormatter#withLocale(Locale)}. * * @param pattern the pattern to use, not null * @param locale the locale to use, not null * @return the formatter based on the pattern, not null * @throws IllegalArgumentException if the pattern is invalid * @see DateTimeFormatterBuilder#appendPattern(String) */ public static DateTimeFormatter pattern(String pattern, Locale locale) { return new DateTimeFormatterBuilder().appendPattern(pattern).toFormatter(locale); } //----------------------------------------------------------------------- /** * Returns a locale specific date format. *
* This returns a formatter that will print/parse a date. * The exact format pattern used varies by locale. *
* The locale is determined from the formatter. The formatter returned directly by * this method will use the {@link Locale#getDefault(Locale.Category) default FORMAT locale}. * The locale can be controlled using {@link DateTimeFormatter#withLocale(Locale) withLocale(Locale)} * on the result of this method. *
* Note that the localized pattern is looked up lazily. * This {@code DateTimeFormatter} holds the style required and the locale, * looking up the pattern required on demand. * * @param dateStyle the formatter style to obtain, not null * @return the date formatter, not null */ public static DateTimeFormatter localizedDate(FormatStyle dateStyle) { Objects.requireNonNull(dateStyle, "dateStyle"); return new DateTimeFormatterBuilder().appendLocalized(dateStyle, null).toFormatter(); } /** * Returns a locale specific time format. *
* This returns a formatter that will print/parse a time. * The exact format pattern used varies by locale. *
* The locale is determined from the formatter. The formatter returned directly by * this method will use the {@link Locale#getDefault(Locale.Category) default FORMAT locale}. * The locale can be controlled using {@link DateTimeFormatter#withLocale(Locale) withLocale(Locale)} * on the result of this method. *
* Note that the localized pattern is looked up lazily. * This {@code DateTimeFormatter} holds the style required and the locale, * looking up the pattern required on demand. * * @param timeStyle the formatter style to obtain, not null * @return the time formatter, not null */ public static DateTimeFormatter localizedTime(FormatStyle timeStyle) { Objects.requireNonNull(timeStyle, "timeStyle"); return new DateTimeFormatterBuilder().appendLocalized(null, timeStyle).toFormatter(); } /** * Returns a locale specific date-time format, which is typically of short length. *
* This returns a formatter that will print/parse a date-time. * The exact format pattern used varies by locale. *
* The locale is determined from the formatter. The formatter returned directly by * this method will use the {@link Locale#getDefault(Locale.Category) default FORMAT locale}. * The locale can be controlled using {@link DateTimeFormatter#withLocale(Locale) withLocale(Locale)} * on the result of this method. *
* Note that the localized pattern is looked up lazily. * This {@code DateTimeFormatter} holds the style required and the locale, * looking up the pattern required on demand. * * @param dateTimeStyle the formatter style to obtain, not null * @return the date-time formatter, not null */ public static DateTimeFormatter localizedDateTime(FormatStyle dateTimeStyle) { Objects.requireNonNull(dateTimeStyle, "dateTimeStyle"); return new DateTimeFormatterBuilder().appendLocalized(dateTimeStyle, dateTimeStyle).toFormatter(); } /** * Returns a locale specific date and time format. *
* This returns a formatter that will print/parse a date-time. * The exact format pattern used varies by locale. *
* The locale is determined from the formatter. The formatter returned directly by * this method will use the {@link Locale#getDefault() default FORMAT locale}. * The locale can be controlled using {@link DateTimeFormatter#withLocale(Locale) withLocale(Locale)} * on the result of this method. *
* Note that the localized pattern is looked up lazily. * This {@code DateTimeFormatter} holds the style required and the locale, * looking up the pattern required on demand. * * @param dateStyle the date formatter style to obtain, not null * @param timeStyle the time formatter style to obtain, not null * @return the date, time or date-time formatter, not null */ public static DateTimeFormatter localizedDateTime(FormatStyle dateStyle, FormatStyle timeStyle) { Objects.requireNonNull(dateStyle, "dateStyle"); Objects.requireNonNull(timeStyle, "timeStyle"); return new DateTimeFormatterBuilder().appendLocalized(dateStyle, timeStyle).toFormatter(); } //----------------------------------------------------------------------- /** * Returns the ISO date formatter that prints/parses a date without an offset, * such as '2011-12-03'. *
* This returns an immutable formatter capable of printing and parsing * the ISO-8601 extended local date format. * The format consists of: *
* * @return the ISO local date formatter, not null */ public static DateTimeFormatter isoLocalDate() { return ISO_LOCAL_DATE; } /** Singleton date formatter. */ private static final DateTimeFormatter ISO_LOCAL_DATE; static { ISO_LOCAL_DATE = new DateTimeFormatterBuilder() .appendValue(YEAR, 4, 10, SignStyle.EXCEEDS_PAD) .appendLiteral('-') .appendValue(MONTH_OF_YEAR, 2) .appendLiteral('-') .appendValue(DAY_OF_MONTH, 2) .toFormatter(); } //----------------------------------------------------------------------- /** * Returns the ISO date formatter that prints/parses a date with an offset, * such as '2011-12-03+01:00'. *
* This returns an immutable formatter capable of printing and parsing * the ISO-8601 extended offset date format. * The format consists of: *
* * @return the ISO offset date formatter, not null */ public static DateTimeFormatter isoOffsetDate() { return ISO_OFFSET_DATE; } /** Singleton date formatter. */ private static final DateTimeFormatter ISO_OFFSET_DATE; static { ISO_OFFSET_DATE = new DateTimeFormatterBuilder() .parseCaseInsensitive() .append(ISO_LOCAL_DATE) .appendOffsetId() .toFormatter(); } //----------------------------------------------------------------------- /** * Returns the ISO date formatter that prints/parses a date with the * offset if available, such as '2011-12-03' or '2011-12-03+01:00'. *
* This returns an immutable formatter capable of printing and parsing * the ISO-8601 extended date format. * The format consists of: *
* As this formatter has an optional element, it may be necessary to parse using * {@link DateTimeFormatter#parseBest}. * * @return the ISO date formatter, not null */ public static DateTimeFormatter isoDate() { return ISO_DATE; } /** Singleton date formatter. */ private static final DateTimeFormatter ISO_DATE; static { ISO_DATE = new DateTimeFormatterBuilder() .parseCaseInsensitive() .append(ISO_LOCAL_DATE) .optionalStart() .appendOffsetId() .toFormatter(); } //----------------------------------------------------------------------- /** * Returns the ISO time formatter that prints/parses a time without an offset, * such as '10:15' or '10:15:30'. *
* This returns an immutable formatter capable of printing and parsing * the ISO-8601 extended local time format. * The format consists of: *
* * @return the ISO local time formatter, not null */ public static DateTimeFormatter isoLocalTime() { return ISO_LOCAL_TIME; } /** Singleton date formatter. */ private static final DateTimeFormatter ISO_LOCAL_TIME; static { ISO_LOCAL_TIME = new DateTimeFormatterBuilder() .appendValue(HOUR_OF_DAY, 2) .appendLiteral(':') .appendValue(MINUTE_OF_HOUR, 2) .optionalStart() .appendLiteral(':') .appendValue(SECOND_OF_MINUTE, 2) .optionalStart() .appendFraction(NANO_OF_SECOND, 0, 9, true) .toFormatter(); } //----------------------------------------------------------------------- /** * Returns the ISO time formatter that prints/parses a time with an offset, * such as '10:15+01:00' or '10:15:30+01:00'. *
* This returns an immutable formatter capable of printing and parsing * the ISO-8601 extended offset time format. * The format consists of: *
* * @return the ISO offset time formatter, not null */ public static DateTimeFormatter isoOffsetTime() { return ISO_OFFSET_TIME; } /** Singleton date formatter. */ private static final DateTimeFormatter ISO_OFFSET_TIME; static { ISO_OFFSET_TIME = new DateTimeFormatterBuilder() .parseCaseInsensitive() .append(ISO_LOCAL_TIME) .appendOffsetId() .toFormatter(); } //----------------------------------------------------------------------- /** * Returns the ISO time formatter that prints/parses a time, with the * offset if available, such as '10:15', '10:15:30' or '10:15:30+01:00'. *
* This returns an immutable formatter capable of printing and parsing * the ISO-8601 extended offset time format. * The format consists of: *
* As this formatter has an optional element, it may be necessary to parse using * {@link DateTimeFormatter#parseBest}. * * @return the ISO time formatter, not null */ public static DateTimeFormatter isoTime() { return ISO_TIME; } /** Singleton date formatter. */ private static final DateTimeFormatter ISO_TIME; static { ISO_TIME = new DateTimeFormatterBuilder() .parseCaseInsensitive() .append(ISO_LOCAL_TIME) .optionalStart() .appendOffsetId() .toFormatter(); } //----------------------------------------------------------------------- /** * Returns the ISO date formatter that prints/parses a date-time * without an offset, such as '2011-12-03T10:15:30'. *
* This returns an immutable formatter capable of printing and parsing * the ISO-8601 extended offset date-time format. * The format consists of: *
* * @return the ISO local date-time formatter, not null */ public static DateTimeFormatter isoLocalDateTime() { return ISO_LOCAL_DATE_TIME; } /** Singleton date formatter. */ private static final DateTimeFormatter ISO_LOCAL_DATE_TIME; static { ISO_LOCAL_DATE_TIME = new DateTimeFormatterBuilder() .parseCaseInsensitive() .append(ISO_LOCAL_DATE) .appendLiteral('T') .append(ISO_LOCAL_TIME) .toFormatter(); } //----------------------------------------------------------------------- /** * Returns the ISO date formatter that prints/parses a date-time * with an offset, such as '2011-12-03T10:15:30+01:00'. *
* This returns an immutable formatter capable of printing and parsing * the ISO-8601 extended offset date-time format. * The format consists of: *
* * @return the ISO offset date-time formatter, not null */ public static DateTimeFormatter isoOffsetDateTime() { return ISO_OFFSET_DATE_TIME; } /** Singleton date formatter. */ private static final DateTimeFormatter ISO_OFFSET_DATE_TIME; static { ISO_OFFSET_DATE_TIME = new DateTimeFormatterBuilder() .parseCaseInsensitive() .append(ISO_LOCAL_DATE_TIME) .appendOffsetId() .toFormatter(); } //----------------------------------------------------------------------- /** * Returns the ISO date formatter that prints/parses a date-time with * offset and zone, such as '2011-12-03T10:15:30+01:00[Europe/Paris]'. *
* This returns an immutable formatter capable of printing and parsing * a format that extends the ISO-8601 extended offset date-time format * to add the time-zone. * The format consists of: *
* * @return the ISO zoned date-time formatter, not null */ public static DateTimeFormatter isoZonedDateTime() { return ISO_ZONED_DATE_TIME; } /** Singleton date formatter. */ private static final DateTimeFormatter ISO_ZONED_DATE_TIME; static { ISO_ZONED_DATE_TIME = new DateTimeFormatterBuilder() .append(ISO_OFFSET_DATE_TIME) .optionalStart() .appendLiteral('[') .parseCaseSensitive() .appendZoneRegionId() .appendLiteral(']') .toFormatter(); } //----------------------------------------------------------------------- /** * Returns the ISO date formatter that prints/parses a date-time * with the offset and zone if available, such as '2011-12-03T10:15:30', * '2011-12-03T10:15:30+01:00' or '2011-12-03T10:15:30+01:00[Europe/Paris]'. *
* This returns an immutable formatter capable of printing and parsing * the ISO-8601 extended offset date-time format. * The format consists of: *
* As this formatter has an optional element, it may be necessary to parse using * {@link DateTimeFormatter#parseBest}. * * @return the ISO date-time formatter, not null */ public static DateTimeFormatter isoDateTime() { return ISO_DATE_TIME; } /** Singleton date formatter. */ private static final DateTimeFormatter ISO_DATE_TIME; static { ISO_DATE_TIME = new DateTimeFormatterBuilder() .append(ISO_LOCAL_DATE_TIME) .optionalStart() .appendOffsetId() .optionalStart() .appendLiteral('[') .parseCaseSensitive() .appendZoneRegionId() .appendLiteral(']') .toFormatter(); } //----------------------------------------------------------------------- /** * Returns the ISO date formatter that prints/parses the ordinal date * without an offset, such as '2012-337'. *
* This returns an immutable formatter capable of printing and parsing * the ISO-8601 extended ordinal date format. * The format consists of: *
* As this formatter has an optional element, it may be necessary to parse using * {@link DateTimeFormatter#parseBest}. * * @return the ISO ordinal date formatter, not null */ public static DateTimeFormatter isoOrdinalDate() { return ISO_ORDINAL_DATE; } /** Singleton date formatter. */ private static final DateTimeFormatter ISO_ORDINAL_DATE; static { ISO_ORDINAL_DATE = new DateTimeFormatterBuilder() .parseCaseInsensitive() .appendValue(YEAR, 4, 10, SignStyle.EXCEEDS_PAD) .appendLiteral('-') .appendValue(DAY_OF_YEAR, 3) .optionalStart() .appendOffsetId() .toFormatter(); } //----------------------------------------------------------------------- /** * Returns the ISO date formatter that prints/parses the week-based date * without an offset, such as '2012-W48-6'. *
* This returns an immutable formatter capable of printing and parsing * the ISO-8601 extended week-based date format. * The format consists of: *
* As this formatter has an optional element, it may be necessary to parse using * {@link DateTimeFormatter#parseBest}. * * @return the ISO week-based date formatter, not null */ public static DateTimeFormatter isoWeekDate() { return ISO_WEEK_DATE; } /** Singleton date formatter. */ private static final DateTimeFormatter ISO_WEEK_DATE; static { ISO_WEEK_DATE = new DateTimeFormatterBuilder() .parseCaseInsensitive() .appendValue(ISOFields.WEEK_BASED_YEAR, 4, 10, SignStyle.EXCEEDS_PAD) .appendLiteral("-W") .appendValue(ISOFields.WEEK_OF_WEEK_BASED_YEAR, 2) .appendLiteral('-') .appendValue(DAY_OF_WEEK, 1) .optionalStart() .appendOffsetId() .toFormatter(); } //----------------------------------------------------------------------- /** * Returns the ISO instant formatter that prints/parses an instant in UTC. *
* This returns an immutable formatter capable of printing and parsing * the ISO-8601 instant format. * The format consists of: *
* * @return the ISO instant formatter, not null */ public static DateTimeFormatter isoInstant() { return ISO_INSTANT; } /** Singleton formatter. */ private static final DateTimeFormatter ISO_INSTANT; static { ISO_INSTANT = new DateTimeFormatterBuilder() .parseCaseInsensitive() .appendInstant() .toFormatter(); } //----------------------------------------------------------------------- /** * Returns the ISO date formatter that prints/parses a date without an offset, * such as '20111203'. *
* This returns an immutable formatter capable of printing and parsing * the ISO-8601 basic local date format. * The format consists of: *
* As this formatter has an optional element, it may be necessary to parse using * {@link DateTimeFormatter#parseBest}. * * @return the ISO basic local date formatter, not null */ public static DateTimeFormatter basicIsoDate() { return BASIC_ISO_DATE; } /** Singleton date formatter. */ private static final DateTimeFormatter BASIC_ISO_DATE; static { BASIC_ISO_DATE = new DateTimeFormatterBuilder() .parseCaseInsensitive() .appendValue(YEAR, 4) .appendValue(MONTH_OF_YEAR, 2) .appendValue(DAY_OF_MONTH, 2) .optionalStart() .appendOffset("+HHMMss", "Z") .toFormatter(); } //----------------------------------------------------------------------- /** * Returns the RFC-1123 date-time formatter, such as 'Tue, 3 Jun 2008 11:05:30 GMT'. *
* This returns an immutable formatter capable of printing and parsing * most of the RFC-1123 format. * RFC-1123 updates RFC-822 changing the year from two digits to four. * This implementation requires a four digit year. * This implementation also does not handle North American or military zone * names, only 'GMT' and offset amounts. *
* The format consists of: *
* Parsing is case insensitive.
*
* @return the RFC-1123 formatter, not null
*/
public static DateTimeFormatter rfc1123() {
return RFC_1123_DATE_TIME;
}
/** Singleton date formatter. */
private static final DateTimeFormatter RFC_1123_DATE_TIME;
static {
// manually code maps to ensure correct data always used
// (locale data can be changed by application code)
Map