- * 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. + * This class provides the main application entry point for printing and parsing + * and provides common implementations of {@code DateTimeFormatter}: + *
- * In most cases, it is not necessary to use this class directly when formatting. + * In most cases, provided formatters will be sufficient. + * For more complex formatters, a {@link DateTimeFormatterBuilder builder} is provided. * 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)}. @@ -91,7 +112,7 @@ * String text = date.toString(formatter); * LocalDate date = LocalDate.parse(text, formatter); * - * Some aspects of printing and parsing are dependent on the locale. + * Some aspects of formatting 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. *
@@ -120,12 +141,781 @@ /** * The chronology to use for formatting, null for no override. */ - private final Chrono chrono; + private final Chronology chrono; /** * The zone to use for formatting, null for no override. */ private final ZoneId zone; + //----------------------------------------------------------------------- + /** + * 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'. + *
+ * 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 text A; 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
+ *
+ * V time-zone ID zone-id America/Los_Angeles; Z; -08:30
+ * z time-zone name zone-name Pacific Standard Time; PST
+ * X zone-offset 'Z' for zero offset-X Z; -08; -0830; -08:30; -083015; -08:30:15;
+ * x zone-offset offset-x +0000; -08; -0830; -08:30; -083015; -08:30:15;
+ * Z zone-offset offset-Z +0000; -0800; -08:00;
+ *
+ * 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 output 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: This outputs the time-zone ID, such as 'Europe/Paris'. + * If the count of letters is two, then the time-zone ID is output. + * Any other count of letters throws {@code IllegalArgumentException}. + *
+ * Zone names: This outputs the display name of the time-zone ID. + * If the count of letters is one, two or three, then the short name is output. + * If the count of letters is four, then the full name is output. + * Five or more letters throws {@code IllegalArgumentException}. + *
+ * Offset X and x: This formats the offset based on the number of pattern letters. + * One letter outputs just the hour', such as '+01', unless the minute is non-zero + * in which case the minute is also output, such as '+0130'. + * 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'. + * Six or more letters throws {@code IllegalArgumentException}. + * Pattern letter 'X' (upper case) will output 'Z' when the offset to be output would be zero, + * whereas pattern letter 'x' (lower case) will output '+00', '+0000', or '+00:00'. + *
+ * Offset Z: This formats the offset based on the number of pattern letters. + * One, two or three letters outputs the hour and minute, without a colon, such as '+0130'. + * Four or more letters throws {@code IllegalArgumentException}. + * The output will be '+0000' when the offset is zero. + *
+ * 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. + * + * @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 ofPattern(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 #ofPattern(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 ofPattern(String pattern, Locale locale) { + return new DateTimeFormatterBuilder().appendPattern(pattern).toFormatter(locale); + } + + //----------------------------------------------------------------------- + /** + * Returns a locale specific date format. + *
+ * This returns a formatter that will format or 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 ofLocalizedDate(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 format or 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 ofLocalizedTime(FormatStyle timeStyle) { + Objects.requireNonNull(timeStyle, "timeStyle"); + return new DateTimeFormatterBuilder().appendLocalized(null, timeStyle).toFormatter(); + } + + /** + * Returns a locale specific date-time formatter, which is typically of short length. + *
+ * This returns a formatter that will format or 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 ofLocalizedDateTime(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 format or 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 ofLocalizedDateTime(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 formats or parses a date without an offset, + * such as '2011-12-03'. + *
+ * This returns an immutable formatter capable of formatting and parsing + * the ISO-8601 extended local date format. + * The format consists of: + *
+ * This returns an immutable formatter capable of formatting and parsing + * the ISO-8601 extended offset date format. + * The format consists of: + *
+ * This returns an immutable formatter capable of formatting 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}. + */ + public static final DateTimeFormatter ISO_DATE; + static { + ISO_DATE = new DateTimeFormatterBuilder() + .parseCaseInsensitive() + .append(ISO_LOCAL_DATE) + .optionalStart() + .appendOffsetId() + .toFormatter(); + } + + //----------------------------------------------------------------------- + /** + * Returns the ISO time formatter that formats or parses a time without an offset, + * such as '10:15' or '10:15:30'. + *
+ * This returns an immutable formatter capable of formatting and parsing + * the ISO-8601 extended local time format. + * The format consists of: + *
+ * This returns an immutable formatter capable of formatting and parsing + * the ISO-8601 extended offset time format. + * The format consists of: + *
+ * This returns an immutable formatter capable of formatting 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}. + */ + public static final DateTimeFormatter ISO_TIME; + static { + ISO_TIME = new DateTimeFormatterBuilder() + .parseCaseInsensitive() + .append(ISO_LOCAL_TIME) + .optionalStart() + .appendOffsetId() + .toFormatter(); + } + + //----------------------------------------------------------------------- + /** + * Returns the ISO date formatter that formats or parses a date-time + * without an offset, such as '2011-12-03T10:15:30'. + *
+ * This returns an immutable formatter capable of formatting and parsing + * the ISO-8601 extended offset date-time format. + * The format consists of: + *
+ * This returns an immutable formatter capable of formatting and parsing + * the ISO-8601 extended offset date-time format. + * The format consists of: + *
+ * This returns an immutable formatter capable of formatting and parsing + * a format that extends the ISO-8601 extended offset date-time format + * to add the time-zone. + * The format consists of: + *
+ * This returns an immutable formatter capable of formatting 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}. + */ + public 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 formats or parses the ordinal date + * without an offset, such as '2012-337'. + *
+ * This returns an immutable formatter capable of formatting 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}. + */ + public 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 formats or parses the week-based date + * without an offset, such as '2012-W48-6'. + *
+ * This returns an immutable formatter capable of formatting 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}. + */ + public 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 formats or parses an instant in UTC. + *
+ * This returns an immutable formatter capable of formatting and parsing + * the ISO-8601 instant format. + * The format consists of: + *
+ * This returns an immutable formatter capable of formatting 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}. + */ + public 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(); + } + + //----------------------------------------------------------------------- + /** + * The RFC-1123 date-time formatter, such as 'Tue, 3 Jun 2008 11:05:30 GMT'. + *
+ * This returns an immutable formatter capable of formatting 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.
+ */
+ public 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
* 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.
+ * See {@link #withChronology(Chronology)} for more details on overriding.
*
* @return the chronology of this formatter, null if no override
*/
- public Chrono getChrono() {
+ public Chronology getChronology() {
return chrono;
}
@@ -221,9 +1011,9 @@
* 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.
+ * If an override is added, then any date that is formatted or parsed will be affected.
*
- * When printing, if the {@code Temporal} object contains a date then it will
+ * When formatting, 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
@@ -238,7 +1028,7 @@
* @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) {
+ public DateTimeFormatter withChronology(Chronology chrono) {
if (Objects.equals(this.chrono, chrono)) {
return this;
}
@@ -266,9 +1056,9 @@
* 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.
+ * If an override is added, then any instant that is formatted or parsed will be affected.
*
- * When printing, if the {@code Temporal} object contains an instant then it will
+ * When formatting, 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
@@ -294,53 +1084,120 @@
//-----------------------------------------------------------------------
/**
- * Prints a date-time object using this formatter.
+ * Formats a date-time object using this formatter.
*
- * This prints the date-time to a String using the rules of the formatter.
+ * This formats 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
+ * @param temporal the temporal object to format, not null
+ * @return the formatted string, not null
+ * @throws DateTimeException if an error occurs during formatting
*/
- public String print(TemporalAccessor temporal) {
+ public String format(TemporalAccessor temporal) {
StringBuilder buf = new StringBuilder(32);
- printTo(temporal, buf);
+ formatTo(temporal, buf);
return buf.toString();
}
//-----------------------------------------------------------------------
/**
- * Prints a date-time object to an {@code Appendable} using this formatter.
+ * Formats a date-time object to an {@code Appendable} using this formatter.
*
- * This prints the date-time to the specified destination.
+ * This outputs the formatted 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
+ * @param temporal the temporal object to format, not null
+ * @param appendable the appendable to format to, not null
+ * @throws DateTimeException if an error occurs during formatting
*/
- public void printTo(TemporalAccessor temporal, Appendable appendable) {
+ public void formatTo(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);
+ printerParser.format(context, (StringBuilder) appendable);
} else {
// buffer output to avoid writing to appendable in case of error
StringBuilder buf = new StringBuilder(32);
- printerParser.print(context, buf);
+ printerParser.format(context, buf);
appendable.append(buf);
}
} catch (IOException ex) {
- throw new DateTimePrintException(ex.getMessage(), ex);
+ throw new DateTimeException(ex.getMessage(), ex);
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Fully parses the text producing a temporal object.
+ *
+ * This parses the entire text producing a temporal object.
+ * It is typically more useful to use {@link #parse(CharSequence, TemporalQuery)}.
+ * The result of this method is {@code TemporalAccessor} which has been resolved,
+ * applying basic validation checks to help ensure a valid date-time.
+ *
+ * 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
+ * @return the parsed temporal object, not null
+ * @throws DateTimeParseException if unable to parse the requested result
+ */
+ public TemporalAccessor parse(CharSequence text) {
+ Objects.requireNonNull(text, "text");
+ try {
+ return parseToBuilder(text, null).resolve();
+ } catch (DateTimeParseException ex) {
+ throw ex;
+ } catch (RuntimeException ex) {
+ throw createError(text, ex);
+ }
+ }
+
+ /**
+ * Parses the text using this formatter, providing control over the text position.
+ *
+ * This parses the text without requiring the parse to start from the beginning
+ * of the string or finish at the end.
+ * The result of this method is {@code TemporalAccessor} which has been resolved,
+ * applying basic validation checks to help ensure a valid date-time.
+ *
+ * The text will be parsed from the specified start {@code ParsePosition}.
+ * The entire length of the text does not have to be parsed, the {@code ParsePosition}
+ * will be updated with the index at the end of parsing.
+ *
+ * The operation of this method is slightly different to similar methods using
+ * {@code ParsePosition} on {@code java.text.Format}. That class will return
+ * errors using the error index on the {@code ParsePosition}. By contrast, this
+ * method will throw a {@link DateTimeParseException} if an error occurs, with
+ * the exception containing the error index.
+ * This change in behavior is necessary due to the increased complexity of
+ * parsing and resolving dates/times in this API.
+ *
+ * If the formatter parses the same field more than once with different values,
+ * the result will be an error.
+ *
+ * @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 temporal object, not null
+ * @throws DateTimeParseException if unable to parse the requested result
+ * @throws IndexOutOfBoundsException if the position is invalid
+ */
+ public TemporalAccessor parse(CharSequence text, ParsePosition position) {
+ Objects.requireNonNull(text, "text");
+ Objects.requireNonNull(position, "position");
+ try {
+ return parseToBuilder(text, position).resolve();
+ } catch (DateTimeParseException | IndexOutOfBoundsException ex) {
+ throw ex;
+ } catch (RuntimeException ex) {
+ throw createError(text, ex);
}
}
@@ -362,19 +1219,18 @@
* @param text the text to parse, not null
* @param query the query defining the type to parse to, not null
* @return the parsed date-time, not null
- * @throws DateTimeParseException if the parse fails
+ * @throws DateTimeParseException if unable to parse the requested result
*/
public
* 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}.
+ * For example, a pattern of 'yyyy-MM-dd HH.mm[Z]]' can be fully parsed to a {@code ZonedDateTime},
+ * or partially parsed to a {@code LocalDateTime}.
* 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.
@@ -392,8 +1248,8 @@
* Normally, applications will use {@code instanceof} to check the result.
* For example:
*
+ * Parsing is implemented as a two-phase operation.
+ * First, the text is parsed using the layout defined by the formatter, producing
+ * a {@code Map} of field to value, a {@code ZoneId} and a {@code Chronology}.
+ * Second, the parsed data is resolved, by validating, combining and
+ * simplifying the various fields into more useful ones.
+ * This method performs the parsing stage but not the resolving stage.
+ *
+ * The result of this method is {@code TemporalAccessor} which represents the
+ * data as seen in the input. Values are not validated, thus parsing a date string
+ * of '2012-00-65' would result in a temporal with three fields - year of '2012',
+ * month of '0' and day-of-month of '65'.
*
- * This parses to a {@code DateTimeBuilder} but does not require the input to be fully parsed.
+ * The text will be parsed from the specified start {@code ParsePosition}.
+ * The entire length of the text does not have to be parsed, the {@code ParsePosition}
+ * will be updated with the index at the end of parsing.
*
- * This method does not throw {@link DateTimeParseException}.
- * Instead, errors are returned within the state of the specified parse position.
+ * Errors are returned using the error index field of the {@code ParsePosition}
+ * instead of {@code DateTimeParseException}.
+ * The returned error index will be set to an index indicative of the error.
* Callers must check for errors before using the context.
*
- * This method may throw some other {@code DateTimeException} if a date/time problem occurs.
+ * If the formatter parses the same field more than once with different values,
+ * the result will be an error.
+ *
+ * This method is intended for advanced use cases that need access to the
+ * internal state during parsing. Typical application code should use
+ * {@link #parse(CharSequence, TemporalQuery)} or the parse method on the target type.
*
* @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
+ * @return the parsed text, null 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) {
+ public TemporalAccessor parseUnresolved(CharSequence text, ParsePosition position) {
+ return parseUnresolved0(text, position);
+ }
+
+ private DateTimeParseContext parseUnresolved0(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);
+ position.setErrorIndex(~pos); // index not updated from input
return null;
}
- position.setIndex(pos);
- return context.toBuilder();
+ position.setIndex(pos); // errorIndex not updated from input
+ return context;
}
//-----------------------------------------------------------------------
@@ -521,8 +1404,8 @@
/**
* 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}.
+ * The returned {@link Format} instance will format any {@link TemporalAccessor}
+ * and parses to a resolved {@link TemporalAccessor}.
*
* Exceptions will follow the definitions of {@code Format}, see those methods
* for details about {@code IllegalArgumentException} during formatting and
@@ -539,7 +1422,7 @@
* 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}
+ * The returned {@link Format} instance will format any {@link TemporalAccessor}
* and parses to the type specified.
* The type must be one that is supported by {@link #parse}.
*
@@ -602,7 +1485,7 @@
pos.setBeginIndex(0);
pos.setEndIndex(0);
try {
- formatter.printTo((TemporalAccessor) obj, toAppendTo);
+ formatter.formatTo((TemporalAccessor) obj, toAppendTo);
} catch (RuntimeException ex) {
throw new IllegalArgumentException(ex.getMessage(), ex);
}
@@ -612,10 +1495,10 @@
public Object parseObject(String text) throws ParseException {
Objects.requireNonNull(text, "text");
try {
- if (parseType != null) {
- return formatter.parse(text, parseType);
+ if (parseType == null) {
+ return formatter.parseToBuilder(text, null).resolve();
}
- return formatter.parseToBuilder(text);
+ return formatter.parse(text, parseType);
} catch (DateTimeParseException ex) {
throw new ParseException(ex.getMessage(), ex.getErrorIndex());
} catch (RuntimeException ex) {
@@ -625,26 +1508,27 @@
@Override
public Object parseObject(String text, ParsePosition pos) {
Objects.requireNonNull(text, "text");
- DateTimeBuilder builder;
+ DateTimeParseContext unresolved;
try {
- builder = formatter.parseToBuilder(text, pos);
+ unresolved = formatter.parseUnresolved0(text, pos);
} catch (IndexOutOfBoundsException ex) {
if (pos.getErrorIndex() < 0) {
pos.setErrorIndex(0);
}
return null;
}
- if (builder == null) {
+ if (unresolved == null) {
if (pos.getErrorIndex() < 0) {
pos.setErrorIndex(0);
}
return null;
}
- if (parseType == null) {
- return builder;
- }
try {
- return builder.resolve().query(parseType);
+ DateTimeBuilder builder = unresolved.resolveFields().toBuilder().resolve();
+ if (parseType == null) {
+ return builder;
+ }
+ return builder.query(parseType);
} catch (RuntimeException ex) {
pos.setErrorIndex(0);
return null;
- * TemporalAccessor dt = parser.parseBest(str, OffsetDate::from, LocalDate::from);
- * if (dt instanceof OffsetDate) {
+ * TemporalAccessor dt = parser.parseBest(str, ZonedDateTime::from, LocalDateTime::from);
+ * if (dt instanceof ZonedDateTime) {
* ...
* } else {
* ...
@@ -407,8 +1263,7 @@
* 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
+ * @throws DateTimeParseException if unable to parse the requested result
*/
public TemporalAccessor parseBest(CharSequence text, TemporalQuery... queries) {
Objects.requireNonNull(text, "text");
@@ -416,9 +1271,8 @@
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();
+ DateTimeBuilder builder = parseToBuilder(text, null).resolve();
for (TemporalQuery query : queries) {
try {
return (TemporalAccessor) builder.query(query);
@@ -430,16 +1284,18 @@
} catch (DateTimeParseException ex) {
throw ex;
} catch (RuntimeException ex) {
- throw createError(str, ex);
+ throw createError(text, ex);
}
}
- private DateTimeParseException createError(String str, RuntimeException ex) {
- String abbr = str;
- if (abbr.length() > 64) {
- abbr = abbr.substring(0, 64) + "...";
+ private DateTimeParseException createError(CharSequence text, RuntimeException ex) {
+ String abbr = "";
+ if (text.length() > 64) {
+ abbr = text.subSequence(0, 64).toString() + "...";
+ } else {
+ abbr = text.toString();
}
- return new DateTimeParseException("Text '" + abbr + "' could not be parsed: " + ex.getMessage(), str, 0, ex);
+ return new DateTimeParseException("Text '" + abbr + "' could not be parsed: " + ex.getMessage(), text, 0, ex);
}
//-----------------------------------------------------------------------
@@ -451,60 +1307,87 @@
* some other {@code DateTimeException} if another 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, null if parsing whole string
* @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) + "...";
+ private DateTimeBuilder parseToBuilder(final CharSequence text, final ParsePosition position) {
+ ParsePosition pos = (position != null ? position : new ParsePosition(0));
+ DateTimeParseContext result = parseUnresolved0(text, pos);
+ if (result == null || pos.getErrorIndex() >= 0 || (position == null && pos.getIndex() < text.length())) {
+ String abbr = "";
+ if (text.length() > 64) {
+ abbr = text.subSequence(0, 64).toString() + "...";
+ } else {
+ abbr = text.toString();
}
if (pos.getErrorIndex() >= 0) {
throw new DateTimeParseException("Text '" + abbr + "' could not be parsed at index " +
- pos.getErrorIndex(), str, pos.getErrorIndex());
+ pos.getErrorIndex(), text, pos.getErrorIndex());
} else {
throw new DateTimeParseException("Text '" + abbr + "' could not be parsed, unparsed text found at index " +
- pos.getIndex(), str, pos.getIndex());
+ pos.getIndex(), text, pos.getIndex());
}
}
- return result;
+ return result.resolveFields().toBuilder();
}
/**
- * Parses the text to a builder.
+ * Parses the text using this formatter, without resolving the result, intended
+ * for advanced use cases.
+ *