* This class provides the main application entry point for printing and parsing. * Common instances of {@code DateTimeFormatter} are provided by {@link DateTimeFormatters}. * For more complex formatters, a {@link DateTimeFormatterBuilder builder} is provided. *
* In most cases, it is not necessary to use this class directly when formatting. * The main date-time classes provide two methods - one for printing, * {@code toString(DateTimeFormatter formatter)}, and one for parsing, * {@code parse(CharSequence text, DateTimeFormatter formatter)}. * For example: *
* String text = date.toString(formatter); * LocalDate date = LocalDate.parse(text, formatter); ** Some aspects of printing and parsing are dependent on the locale. * The locale can be changed using the {@link #withLocale(Locale)} method * which returns a new formatter in the requested locale. *
* Some applications may need to use the older {@link Format} class for formatting. * The {@link #toFormat()} method returns an implementation of the old API. * *
* This is used to lookup any part of the formatter needing specific * localization, such as the text or localized pattern. * * @return the locale of this formatter, not null */ public Locale getLocale() { return locale; } /** * Returns a copy of this formatter with a new locale. *
* This is used to lookup any part of the formatter needing specific * localization, such as the text or localized pattern. *
* This instance is immutable and unaffected by this method call. * * @param locale the new locale, not null * @return a formatter based on this formatter with the requested locale, not null */ public DateTimeFormatter withLocale(Locale locale) { if (this.locale.equals(locale)) { return this; } return new DateTimeFormatter(printerParser, locale, symbols, chrono, zone); } //----------------------------------------------------------------------- /** * Gets the set of symbols to be used during formatting. * * @return the locale of this formatter, not null */ public DateTimeFormatSymbols getSymbols() { return symbols; } /** * Returns a copy of this formatter with a new set of symbols. *
* This instance is immutable and unaffected by this method call. * * @param symbols the new symbols, not null * @return a formatter based on this formatter with the requested symbols, not null */ public DateTimeFormatter withSymbols(DateTimeFormatSymbols symbols) { if (this.symbols.equals(symbols)) { return this; } return new DateTimeFormatter(printerParser, locale, symbols, chrono, zone); } //----------------------------------------------------------------------- /** * Gets the overriding chronology to be used during formatting. *
* This returns the override chronology, used to convert dates. * By default, a formatter has no override chronology, returning null. * See {@link #withChrono(Chrono)} for more details on overriding. * * @return the chronology of this formatter, null if no override */ public Chrono getChrono() { return chrono; } /** * Returns a copy of this formatter with a new override chronology. *
* This returns a formatter with similar state to this formatter but * with the override chronology set. * By default, a formatter has no override chronology, returning null. *
* If an override is added, then any date that is printed or parsed will be affected. *
* When printing, if the {@code Temporal} object contains a date then it will * be converted to a date in the override chronology. * Any time or zone will be retained unless overridden. * The converted result will behave in a manner equivalent to an implementation * of {@code ChronoLocalDate},{@code ChronoLocalDateTime} or {@code ChronoZonedDateTime}. *
* When parsing, the override chronology will be used to interpret the * {@link java.time.temporal.ChronoField fields} into a date unless the * formatter directly parses a valid chronology. *
* This instance is immutable and unaffected by this method call. * * @param chrono the new chronology, not null * @return a formatter based on this formatter with the requested override chronology, not null */ public DateTimeFormatter withChrono(Chrono chrono) { if (Objects.equals(this.chrono, chrono)) { return this; } return new DateTimeFormatter(printerParser, locale, symbols, chrono, zone); } //----------------------------------------------------------------------- /** * Gets the overriding zone to be used during formatting. *
* This returns the override zone, used to convert instants. * By default, a formatter has no override zone, returning null. * See {@link #withZone(ZoneId)} for more details on overriding. * * @return the chronology of this formatter, null if no override */ public ZoneId getZone() { return zone; } /** * Returns a copy of this formatter with a new override zone. *
* This returns a formatter with similar state to this formatter but * with the override zone set. * By default, a formatter has no override zone, returning null. *
* If an override is added, then any instant that is printed or parsed will be affected. *
* When printing, if the {@code Temporal} object contains an instant then it will * be converted to a zoned date-time using the override zone. * If the input has a chronology then it will be retained unless overridden. * If the input does not have a chronology, such as {@code Instant}, then * the ISO chronology will be used. * The converted result will behave in a manner equivalent to an implementation * of {@code ChronoZonedDateTime}. *
* When parsing, the override zone will be used to interpret the * {@link java.time.temporal.ChronoField fields} into an instant unless the * formatter directly parses a valid zone. *
* This instance is immutable and unaffected by this method call. * * @param zone the new override zone, not null * @return a formatter based on this formatter with the requested override zone, not null */ public DateTimeFormatter withZone(ZoneId zone) { if (Objects.equals(this.zone, zone)) { return this; } return new DateTimeFormatter(printerParser, locale, symbols, chrono, zone); } //----------------------------------------------------------------------- /** * Prints a date-time object using this formatter. *
* This prints the date-time to a String using the rules of the formatter. * * @param temporal the temporal object to print, not null * @return the printed string, not null * @throws DateTimeException if an error occurs during printing */ public String print(TemporalAccessor temporal) { StringBuilder buf = new StringBuilder(32); printTo(temporal, buf); return buf.toString(); } //----------------------------------------------------------------------- /** * Prints a date-time object to an {@code Appendable} using this formatter. *
* This prints the date-time to the specified destination. * {@link Appendable} is a general purpose interface that is implemented by all * key character output classes including {@code StringBuffer}, {@code StringBuilder}, * {@code PrintStream} and {@code Writer}. *
* Although {@code Appendable} methods throw an {@code IOException}, this method does not. * Instead, any {@code IOException} is wrapped in a runtime exception. * See {@link DateTimePrintException#rethrowIOException()} for a means * to extract the {@code IOException}. * * @param temporal the temporal object to print, not null * @param appendable the appendable to print to, not null * @throws DateTimeException if an error occurs during printing */ public void printTo(TemporalAccessor temporal, Appendable appendable) { Objects.requireNonNull(temporal, "temporal"); Objects.requireNonNull(appendable, "appendable"); try { DateTimePrintContext context = new DateTimePrintContext(temporal, this); if (appendable instanceof StringBuilder) { printerParser.print(context, (StringBuilder) appendable); } else { // buffer output to avoid writing to appendable in case of error StringBuilder buf = new StringBuilder(32); printerParser.print(context, buf); appendable.append(buf); } } catch (IOException ex) { throw new DateTimePrintException(ex.getMessage(), ex); } } //----------------------------------------------------------------------- /** * Fully parses the text producing an object of the specified type. *
* Most applications should use this method for parsing. * It parses the entire text to produce the required date-time. * The query is typically a method reference to a {@code from(TemporalAccessor)} method. * For example: *
* LocalDateTime dt = parser.parse(str, LocalDateTime::from);
*
* If the parse completes without reading the entire length of the text,
* or a problem occurs during parsing or merging, then an exception is thrown.
*
* @param * This parse method is convenient for use when the parser can handle optional elements. * For example, a pattern of 'yyyy-MM[-dd[Z]]' can be fully parsed to an {@code OffsetDate}, * or partially parsed to a {@code LocalDate} or a {@code YearMonth}. * The queries must be specified in order, starting from the best matching full-parse option * and ending with the worst matching minimal parse option. * The query is typically a method reference to a {@code from(TemporalAccessor)} method. *
* The result is associated with the first type that successfully parses. * Normally, applications will use {@code instanceof} to check the result. * For example: *
* TemporalAccessor dt = parser.parseBest(str, OffsetDate::from, LocalDate::from);
* if (dt instanceof OffsetDate) {
* ...
* } else {
* ...
* }
*
* If the parse completes without reading the entire length of the text,
* or a problem occurs during parsing or merging, then an exception is thrown.
*
* @param text the text to parse, not null
* @param queries the queries defining the types to attempt to parse to,
* must implement {@code TemporalAccessor}, not null
* @return the parsed date-time, not null
* @throws IllegalArgumentException if less than 2 types are specified
* @throws DateTimeException if none of the queries can be parsed from the input
* @throws DateTimeParseException if the parse fails
*/
public TemporalAccessor parseBest(CharSequence text, TemporalQuery... queries) {
Objects.requireNonNull(text, "text");
Objects.requireNonNull(queries, "queries");
if (queries.length < 2) {
throw new IllegalArgumentException("At least two queries must be specified");
}
String str = text.toString(); // parsing whole String, so this makes sense
try {
DateTimeBuilder builder = parseToBuilder(str).resolve();
for (TemporalQuery query : queries) {
try {
return (TemporalAccessor) builder.query(query);
} catch (RuntimeException ex) {
// continue
}
}
throw new DateTimeException("Unable to convert parsed text using any of the specified queries");
} catch (DateTimeParseException ex) {
throw ex;
} catch (RuntimeException ex) {
throw createError(str, ex);
}
}
private DateTimeParseException createError(String str, RuntimeException ex) {
String abbr = str;
if (abbr.length() > 64) {
abbr = abbr.substring(0, 64) + "...";
}
return new DateTimeParseException("Text '" + abbr + "' could not be parsed: " + ex.getMessage(), str, 0, ex);
}
//-----------------------------------------------------------------------
/**
* Parses the text to a builder.
* * This parses to a {@code DateTimeBuilder} ensuring that the text is fully parsed. * This method throws {@link DateTimeParseException} if unable to parse, or * some other {@code DateTimeException} if another date/time problem occurs. * * @param text the text to parse, not null * @return the engine representing the result of the parse, not null * @throws DateTimeParseException if the parse fails */ public DateTimeBuilder parseToBuilder(CharSequence text) { Objects.requireNonNull(text, "text"); String str = text.toString(); // parsing whole String, so this makes sense ParsePosition pos = new ParsePosition(0); DateTimeBuilder result = parseToBuilder(str, pos); if (result == null || pos.getErrorIndex() >= 0 || pos.getIndex() < str.length()) { String abbr = str; if (abbr.length() > 64) { abbr = abbr.substring(0, 64) + "..."; } if (pos.getErrorIndex() >= 0) { throw new DateTimeParseException("Text '" + abbr + "' could not be parsed at index " + pos.getErrorIndex(), str, pos.getErrorIndex()); } else { throw new DateTimeParseException("Text '" + abbr + "' could not be parsed, unparsed text found at index " + pos.getIndex(), str, pos.getIndex()); } } return result; } /** * Parses the text to a builder. *
* This parses to a {@code DateTimeBuilder} but does not require the input to be fully parsed. *
* This method does not throw {@link DateTimeParseException}. * Instead, errors are returned within the state of the specified parse position. * Callers must check for errors before using the context. *
* This method may throw some other {@code DateTimeException} if a date/time problem occurs. * * @param text the text to parse, not null * @param position the position to parse from, updated with length parsed * and the index of any error, not null * @return the parsed text, null only if the parse results in an error * @throws DateTimeException if some problem occurs during parsing * @throws IndexOutOfBoundsException if the position is invalid */ public DateTimeBuilder parseToBuilder(CharSequence text, ParsePosition position) { Objects.requireNonNull(text, "text"); Objects.requireNonNull(position, "position"); DateTimeParseContext context = new DateTimeParseContext(this); int pos = position.getIndex(); pos = printerParser.parse(context, text, pos); if (pos < 0) { position.setErrorIndex(~pos); return null; } position.setIndex(pos); return context.toBuilder(); } //----------------------------------------------------------------------- /** * Returns the formatter as a composite printer parser. * * @param optional whether the printer/parser should be optional * @return the printer/parser, not null */ CompositePrinterParser toPrinterParser(boolean optional) { return printerParser.withOptional(optional); } /** * Returns this formatter as a {@code java.text.Format} instance. *
* The returned {@link Format} instance will print any {@link java.time.temporal.TemporalAccessor} * and parses to a resolved {@link DateTimeBuilder}. *
* Exceptions will follow the definitions of {@code Format}, see those methods * for details about {@code IllegalArgumentException} during formatting and * {@code ParseException} or null during parsing. * The format does not support attributing of the returned format string. * * @return this formatter as a classic format instance, not null */ public Format toFormat() { return new ClassicFormat(this, null); } /** * Returns this formatter as a {@code java.text.Format} instance that will * parse using the specified query. *
* The returned {@link Format} instance will print any {@link java.time.temporal.TemporalAccessor} * and parses to the type specified. * The type must be one that is supported by {@link #parse}. *
* Exceptions will follow the definitions of {@code Format}, see those methods * for details about {@code IllegalArgumentException} during formatting and * {@code ParseException} or null during parsing. * The format does not support attributing of the returned format string. * * @param parseQuery the query defining the type to parse to, not null * @return this formatter as a classic format instance, not null */ public Format toFormat(TemporalQuery parseQuery) { Objects.requireNonNull(parseQuery, "parseQuery"); return new ClassicFormat(this, parseQuery); } //----------------------------------------------------------------------- /** * Returns a description of the underlying formatters. * * @return a description of this formatter, not null */ @Override public String toString() { String pattern = printerParser.toString(); pattern = pattern.startsWith("[") ? pattern : pattern.substring(1, pattern.length() - 1); return pattern; // TODO: Fix tests to not depend on toString() // return "DateTimeFormatter[" + locale + // (chrono != null ? "," + chrono : "") + // (zone != null ? "," + zone : "") + // pattern + "]"; } //----------------------------------------------------------------------- /** * Implements the classic Java Format API. * @serial exclude */ @SuppressWarnings("serial") // not actually serializable static class ClassicFormat extends Format { /** The formatter. */ private final DateTimeFormatter formatter; /** The type to be parsed. */ private final TemporalQuery parseType; /** Constructor. */ public ClassicFormat(DateTimeFormatter formatter, TemporalQuery parseType) { this.formatter = formatter; this.parseType = parseType; } @Override public StringBuffer format(Object obj, StringBuffer toAppendTo, FieldPosition pos) { Objects.requireNonNull(obj, "obj"); Objects.requireNonNull(toAppendTo, "toAppendTo"); Objects.requireNonNull(pos, "pos"); if (obj instanceof TemporalAccessor == false) { throw new IllegalArgumentException("Format target must implement TemporalAccessor"); } pos.setBeginIndex(0); pos.setEndIndex(0); try { formatter.printTo((TemporalAccessor) obj, toAppendTo); } catch (RuntimeException ex) { throw new IllegalArgumentException(ex.getMessage(), ex); } return toAppendTo; } @Override public Object parseObject(String text) throws ParseException { Objects.requireNonNull(text, "text"); try { if (parseType != null) { return formatter.parse(text, parseType); } return formatter.parseToBuilder(text); } catch (DateTimeParseException ex) { throw new ParseException(ex.getMessage(), ex.getErrorIndex()); } catch (RuntimeException ex) { throw (ParseException) new ParseException(ex.getMessage(), 0).initCause(ex); } } @Override public Object parseObject(String text, ParsePosition pos) { Objects.requireNonNull(text, "text"); DateTimeBuilder builder; try { builder = formatter.parseToBuilder(text, pos); } catch (IndexOutOfBoundsException ex) { if (pos.getErrorIndex() < 0) { pos.setErrorIndex(0); } return null; } if (builder == null) { if (pos.getErrorIndex() < 0) { pos.setErrorIndex(0); } return null; } if (parseType == null) { return builder; } try { return builder.resolve().query(parseType); } catch (RuntimeException ex) { pos.setErrorIndex(0); return null; } } } }