63
64 import static java.time.temporal.ChronoField.DAY_OF_MONTH;
65 import static java.time.temporal.ChronoField.DAY_OF_WEEK;
66 import static java.time.temporal.ChronoField.DAY_OF_YEAR;
67 import static java.time.temporal.ChronoField.HOUR_OF_DAY;
68 import static java.time.temporal.ChronoField.MINUTE_OF_HOUR;
69 import static java.time.temporal.ChronoField.MONTH_OF_YEAR;
70 import static java.time.temporal.ChronoField.NANO_OF_SECOND;
71 import static java.time.temporal.ChronoField.SECOND_OF_MINUTE;
72 import static java.time.temporal.ChronoField.YEAR;
73
74 import java.io.IOException;
75 import java.text.FieldPosition;
76 import java.text.Format;
77 import java.text.ParseException;
78 import java.text.ParsePosition;
79 import java.time.DateTimeException;
80 import java.time.Period;
81 import java.time.ZoneId;
82 import java.time.ZoneOffset;
83 import java.time.chrono.Chronology;
84 import java.time.chrono.IsoChronology;
85 import java.time.format.DateTimeFormatterBuilder.CompositePrinterParser;
86 import java.time.temporal.ChronoField;
87 import java.time.temporal.IsoFields;
88 import java.time.temporal.TemporalAccessor;
89 import java.time.temporal.TemporalField;
90 import java.time.temporal.TemporalQuery;
91 import java.util.Arrays;
92 import java.util.Collections;
93 import java.util.HashMap;
94 import java.util.HashSet;
95 import java.util.Locale;
96 import java.util.Map;
97 import java.util.Objects;
98 import java.util.Set;
99
100 /**
101 * Formatter for printing and parsing date-time objects.
102 * <p>
456 * This is achieved using {@link Chronology#resolveDate(Map, ResolverStyle)}.
457 * Documentation about field resolution is located in the implementation
458 * of {@code Chronology}.
459 * <li>The {@code ChronoField} time fields are resolved.
460 * This is documented on {@link ChronoField} and is the same for all chronologies.
461 * <li>Any fields that are not {@code ChronoField} are processed.
462 * This is achieved using {@link TemporalField#resolve(Map, TemporalAccessor, ResolverStyle)}.
463 * Documentation about field resolution is located in the implementation
464 * of {@code TemporalField}.
465 * <li>The {@code ChronoField} date and time fields are re-resolved.
466 * This allows fields in step four to produce {@code ChronoField} values
467 * and have them be processed into dates and times.
468 * <li>A {@code LocalTime} is formed if there is at least an hour-of-day available.
469 * This involves providing default values for minute, second and fraction of second.
470 * <li>Any remaining unresolved fields are cross-checked against any
471 * date and/or time that was resolved. Thus, an earlier stage would resolve
472 * (year + month + day-of-month) to a date, and this stage would check that
473 * day-of-week was valid for the date.
474 * <li>If an {@linkplain #parsedExcessDays() excess number of days}
475 * was parsed then it is added to the date if a date is available.
476 * </ol>
477 *
478 * @implSpec
479 * This class is immutable and thread-safe.
480 *
481 * @since 1.8
482 */
483 public final class DateTimeFormatter {
484
485 /**
486 * The printer and/or parser to use, not null.
487 */
488 private final CompositePrinterParser printerParser;
489 /**
490 * The locale to use for formatting, not null.
491 */
492 private final Locale locale;
493 /**
494 * The symbols to use for formatting, not null.
495 */
|
63
64 import static java.time.temporal.ChronoField.DAY_OF_MONTH;
65 import static java.time.temporal.ChronoField.DAY_OF_WEEK;
66 import static java.time.temporal.ChronoField.DAY_OF_YEAR;
67 import static java.time.temporal.ChronoField.HOUR_OF_DAY;
68 import static java.time.temporal.ChronoField.MINUTE_OF_HOUR;
69 import static java.time.temporal.ChronoField.MONTH_OF_YEAR;
70 import static java.time.temporal.ChronoField.NANO_OF_SECOND;
71 import static java.time.temporal.ChronoField.SECOND_OF_MINUTE;
72 import static java.time.temporal.ChronoField.YEAR;
73
74 import java.io.IOException;
75 import java.text.FieldPosition;
76 import java.text.Format;
77 import java.text.ParseException;
78 import java.text.ParsePosition;
79 import java.time.DateTimeException;
80 import java.time.Period;
81 import java.time.ZoneId;
82 import java.time.ZoneOffset;
83 import java.time.chrono.ChronoLocalDateTime;
84 import java.time.chrono.Chronology;
85 import java.time.chrono.IsoChronology;
86 import java.time.format.DateTimeFormatterBuilder.CompositePrinterParser;
87 import java.time.temporal.ChronoField;
88 import java.time.temporal.IsoFields;
89 import java.time.temporal.TemporalAccessor;
90 import java.time.temporal.TemporalField;
91 import java.time.temporal.TemporalQuery;
92 import java.util.Arrays;
93 import java.util.Collections;
94 import java.util.HashMap;
95 import java.util.HashSet;
96 import java.util.Locale;
97 import java.util.Map;
98 import java.util.Objects;
99 import java.util.Set;
100
101 /**
102 * Formatter for printing and parsing date-time objects.
103 * <p>
457 * This is achieved using {@link Chronology#resolveDate(Map, ResolverStyle)}.
458 * Documentation about field resolution is located in the implementation
459 * of {@code Chronology}.
460 * <li>The {@code ChronoField} time fields are resolved.
461 * This is documented on {@link ChronoField} and is the same for all chronologies.
462 * <li>Any fields that are not {@code ChronoField} are processed.
463 * This is achieved using {@link TemporalField#resolve(Map, TemporalAccessor, ResolverStyle)}.
464 * Documentation about field resolution is located in the implementation
465 * of {@code TemporalField}.
466 * <li>The {@code ChronoField} date and time fields are re-resolved.
467 * This allows fields in step four to produce {@code ChronoField} values
468 * and have them be processed into dates and times.
469 * <li>A {@code LocalTime} is formed if there is at least an hour-of-day available.
470 * This involves providing default values for minute, second and fraction of second.
471 * <li>Any remaining unresolved fields are cross-checked against any
472 * date and/or time that was resolved. Thus, an earlier stage would resolve
473 * (year + month + day-of-month) to a date, and this stage would check that
474 * day-of-week was valid for the date.
475 * <li>If an {@linkplain #parsedExcessDays() excess number of days}
476 * was parsed then it is added to the date if a date is available.
477 * <li> If a second-based field is present, but {@code LocalTime} was not parsed,
478 * then the resolver ensures that milli, micro and nano second values are
479 * available to meet the contract of {@link ChronoField}.
480 * These will be set to zero if missing.
481 * <li>If both date and time were parsed and either an offset or zone is present,
482 * the field {@link ChronoField#INSTANT_SECONDS} is created.
483 * If an offset was parsed then the offset will be combined with the
484 * {@code LocalDateTime} to form the instant, with any zone ignored.
485 * If a {@code ZoneId} was parsed without an offset then the zone will be
486 * combined with the {@code LocalDateTime} to form the instant using the rules
487 * of {@link ChronoLocalDateTime#atZone(ZoneId)}.
488 * </ol>
489 *
490 * @implSpec
491 * This class is immutable and thread-safe.
492 *
493 * @since 1.8
494 */
495 public final class DateTimeFormatter {
496
497 /**
498 * The printer and/or parser to use, not null.
499 */
500 private final CompositePrinterParser printerParser;
501 /**
502 * The locale to use for formatting, not null.
503 */
504 private final Locale locale;
505 /**
506 * The symbols to use for formatting, not null.
507 */
|