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>
104 * This class provides the main application entry point for printing and parsing
105 * and provides common implementations of {@code DateTimeFormatter}:
106 * <ul>
107 * <li>Using predefined constants, such as {@link #ISO_LOCAL_DATE}</li>
108 * <li>Using pattern letters, such as {@code uuuu-MMM-dd}</li>
109 * <li>Using localized styles, such as {@code long} or {@code medium}</li>
110 * </ul>
111 * <p>
112 * More complex formatters are provided by
113 * {@link DateTimeFormatterBuilder DateTimeFormatterBuilder}.
114 *
115 * <p>
116 * The main date-time classes provide two methods - one for formatting,
117 * {@code format(DateTimeFormatter formatter)}, and one for parsing,
118 * {@code parse(CharSequence text, DateTimeFormatter formatter)}.
119 * <p>For example:
120 * <blockquote><pre>
121 * LocalDate date = LocalDate.now();
122 * String text = date.format(formatter);
123 * LocalDate parsedDate = LocalDate.parse(text, formatter);
124 * </pre></blockquote>
125 * <p>
126 * In addition to the format, formatters can be created with desired Locale,
127 * Chronology, ZoneId, and DecimalStyle.
128 * <p>
129 * The {@link #withLocale withLocale} method returns a new formatter that
130 * overrides the locale. The locale affects some aspects of formatting and
131 * parsing. For example, the {@link #ofLocalizedDate ofLocalizedDate} provides a
132 * formatter that uses the locale specific date format.
133 * <p>
134 * The {@link #withChronology withChronology} method returns a new formatter
135 * that overrides the chronology. If overridden, the date-time value is
136 * converted to the chronology before formatting. During parsing the date-time
137 * value is converted to the chronology before it is returned.
138 * <p>
139 * The {@link #withZone withZone} method returns a new formatter that overrides
140 * the zone. If overridden, the date-time value is converted to a ZonedDateTime
141 * with the requested ZoneId before formatting. During parsing the ZoneId is
142 * applied before the value is returned.
143 * <p>
144 * The {@link #withDecimalStyle withDecimalStyle} method returns a new formatter that
145 * overrides the {@link DecimalStyle}. The DecimalStyle symbols are used for
146 * formatting and parsing.
147 * <p>
148 * Some applications may need to use the older {@link Format java.text.Format}
149 * class for formatting. The {@link #toFormat()} method returns an
150 * implementation of {@code java.text.Format}.
151 *
152 * <h3 id="predefined">Predefined Formatters</h3>
531 private final Set<TemporalField> resolverFields;
532 /**
533 * The chronology to use for formatting, null for no override.
534 */
535 private final Chronology chrono;
536 /**
537 * The zone to use for formatting, null for no override.
538 */
539 private final ZoneId zone;
540
541 //-----------------------------------------------------------------------
542 /**
543 * Creates a formatter using the specified pattern.
544 * <p>
545 * This method will create a formatter based on a simple
546 * <a href="#patterns">pattern of letters and symbols</a>
547 * as described in the class documentation.
548 * For example, {@code d MMM uuuu} will format 2011-12-03 as '3 Dec 2011'.
549 * <p>
550 * The formatter will use the {@link Locale#getDefault(Locale.Category) default FORMAT locale}.
551 * This can be changed using {@link DateTimeFormatter#withLocale(Locale)} on the returned formatter
552 * Alternatively use the {@link #ofPattern(String, Locale)} variant of this method.
553 * <p>
554 * The returned formatter has no override chronology or zone.
555 * It uses {@link ResolverStyle#SMART SMART} resolver style.
556 *
557 * @param pattern the pattern to use, not null
558 * @return the formatter based on the pattern, not null
559 * @throws IllegalArgumentException if the pattern is invalid
560 * @see DateTimeFormatterBuilder#appendPattern(String)
561 */
562 public static DateTimeFormatter ofPattern(String pattern) {
563 return new DateTimeFormatterBuilder().appendPattern(pattern).toFormatter();
564 }
565
566 /**
567 * Creates a formatter using the specified pattern and locale.
568 * <p>
569 * This method will create a formatter based on a simple
570 * <a href="#patterns">pattern of letters and symbols</a>
571 * as described in the class documentation.
572 * For example, {@code d MMM uuuu} will format 2011-12-03 as '3 Dec 2011'.
573 * <p>
574 * The formatter will use the specified locale.
575 * This can be changed using {@link DateTimeFormatter#withLocale(Locale)} on the returned formatter
576 * <p>
577 * The returned formatter has no override chronology or zone.
578 * It uses {@link ResolverStyle#SMART SMART} resolver style.
579 *
580 * @param pattern the pattern to use, not null
581 * @param locale the locale to use, not null
582 * @return the formatter based on the pattern, not null
583 * @throws IllegalArgumentException if the pattern is invalid
584 * @see DateTimeFormatterBuilder#appendPattern(String)
585 */
586 public static DateTimeFormatter ofPattern(String pattern, Locale locale) {
587 return new DateTimeFormatterBuilder().appendPattern(pattern).toFormatter(locale);
588 }
589
590 //-----------------------------------------------------------------------
591 /**
592 * Returns a locale specific date format for the ISO chronology.
593 * <p>
594 * This returns a formatter that will format or parse a date.
595 * The exact format pattern used varies by locale.
1424 this.zone = zone;
1425 }
1426
1427 //-----------------------------------------------------------------------
1428 /**
1429 * Gets the locale to be used during formatting.
1430 * <p>
1431 * This is used to lookup any part of the formatter needing specific
1432 * localization, such as the text or localized pattern.
1433 *
1434 * @return the locale of this formatter, not null
1435 */
1436 public Locale getLocale() {
1437 return locale;
1438 }
1439
1440 /**
1441 * Returns a copy of this formatter with a new locale.
1442 * <p>
1443 * This is used to lookup any part of the formatter needing specific
1444 * localization, such as the text or localized pattern.
1445 * <p>
1446 * This instance is immutable and unaffected by this method call.
1447 *
1448 * @param locale the new locale, not null
1449 * @return a formatter based on this formatter with the requested locale, not null
1450 */
1451 public DateTimeFormatter withLocale(Locale locale) {
1452 if (this.locale.equals(locale)) {
1453 return this;
1454 }
1455 return new DateTimeFormatter(printerParser, locale, decimalStyle, resolverStyle, resolverFields, chrono, zone);
1456 }
1457
1458 //-----------------------------------------------------------------------
1459 /**
1460 * Gets the DecimalStyle to be used during formatting.
1461 *
1462 * @return the locale of this formatter, not null
1463 */
1464 public DecimalStyle getDecimalStyle() {
1465 return decimalStyle;
1466 }
1467
1468 /**
1469 * Returns a copy of this formatter with a new DecimalStyle.
1470 * <p>
1471 * This instance is immutable and unaffected by this method call.
1472 *
1473 * @param decimalStyle the new DecimalStyle, not null
1474 * @return a formatter based on this formatter with the requested DecimalStyle, not null
1475 */
|
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 import sun.util.locale.provider.TimeZoneNameUtility;
101
102 /**
103 * Formatter for printing and parsing date-time objects.
104 * <p>
105 * This class provides the main application entry point for printing and parsing
106 * and provides common implementations of {@code DateTimeFormatter}:
107 * <ul>
108 * <li>Using predefined constants, such as {@link #ISO_LOCAL_DATE}</li>
109 * <li>Using pattern letters, such as {@code uuuu-MMM-dd}</li>
110 * <li>Using localized styles, such as {@code long} or {@code medium}</li>
111 * </ul>
112 * <p>
113 * More complex formatters are provided by
114 * {@link DateTimeFormatterBuilder DateTimeFormatterBuilder}.
115 *
116 * <p>
117 * The main date-time classes provide two methods - one for formatting,
118 * {@code format(DateTimeFormatter formatter)}, and one for parsing,
119 * {@code parse(CharSequence text, DateTimeFormatter formatter)}.
120 * <p>For example:
121 * <blockquote><pre>
122 * LocalDate date = LocalDate.now();
123 * String text = date.format(formatter);
124 * LocalDate parsedDate = LocalDate.parse(text, formatter);
125 * </pre></blockquote>
126 * <p>
127 * In addition to the format, formatters can be created with desired Locale,
128 * Chronology, ZoneId, and DecimalStyle.
129 * <p>
130 * The {@link #withLocale withLocale} method returns a new formatter that
131 * overrides the locale. The locale affects some aspects of formatting and
132 * parsing. For example, the {@link #ofLocalizedDate ofLocalizedDate} provides a
133 * formatter that uses the locale specific date format. If the locale contains
134 * "ca" (calendar), "rg" (region override) and/or "tz" (timezone)
135 * <a href="../../util/Locale.html#def_locale_extension">Unicode extensions</a>,
136 * the chronology and/or the zone are also overriden. If both "ca" and "rg" are
137 * specified, the chronology from "ca" extension supersedes the implicit one
138 * from "rg" extension.
139 * <p>
140 * The {@link #withChronology withChronology} method returns a new formatter
141 * that overrides the chronology. If overridden, the date-time value is
142 * converted to the chronology before formatting. During parsing the date-time
143 * value is converted to the chronology before it is returned.
144 * <p>
145 * The {@link #withZone withZone} method returns a new formatter that overrides
146 * the zone. If overridden, the date-time value is converted to a ZonedDateTime
147 * with the requested ZoneId before formatting. During parsing the ZoneId is
148 * applied before the value is returned.
149 * <p>
150 * The {@link #withDecimalStyle withDecimalStyle} method returns a new formatter that
151 * overrides the {@link DecimalStyle}. The DecimalStyle symbols are used for
152 * formatting and parsing.
153 * <p>
154 * Some applications may need to use the older {@link Format java.text.Format}
155 * class for formatting. The {@link #toFormat()} method returns an
156 * implementation of {@code java.text.Format}.
157 *
158 * <h3 id="predefined">Predefined Formatters</h3>
537 private final Set<TemporalField> resolverFields;
538 /**
539 * The chronology to use for formatting, null for no override.
540 */
541 private final Chronology chrono;
542 /**
543 * The zone to use for formatting, null for no override.
544 */
545 private final ZoneId zone;
546
547 //-----------------------------------------------------------------------
548 /**
549 * Creates a formatter using the specified pattern.
550 * <p>
551 * This method will create a formatter based on a simple
552 * <a href="#patterns">pattern of letters and symbols</a>
553 * as described in the class documentation.
554 * For example, {@code d MMM uuuu} will format 2011-12-03 as '3 Dec 2011'.
555 * <p>
556 * The formatter will use the {@link Locale#getDefault(Locale.Category) default FORMAT locale}.
557 * This can be changed using {@link DateTimeFormatter#withLocale(Locale)} on the returned formatter.
558 * Alternatively use the {@link #ofPattern(String, Locale)} variant of this method.
559 * If the default locale contains "ca" (calendar), "rg" (region override) and/or "tz" (timezone)
560 * <a href="../../util/Locale.html#def_locale_extension">Unicode extensions</a>,
561 * the chronology and/or the zone are overriden. If both "ca" and "rg" are
562 * specified, the chronology from "ca" extension supersedes the implicit one
563 * from "rg" extension.
564 * <p>
565 * The returned formatter has no override chronology or zone.
566 * It uses {@link ResolverStyle#SMART SMART} resolver style.
567 *
568 * @param pattern the pattern to use, not null
569 * @return the formatter based on the pattern, not null
570 * @throws IllegalArgumentException if the pattern is invalid
571 * @see DateTimeFormatterBuilder#appendPattern(String)
572 */
573 public static DateTimeFormatter ofPattern(String pattern) {
574 return new DateTimeFormatterBuilder().appendPattern(pattern).toFormatter();
575 }
576
577 /**
578 * Creates a formatter using the specified pattern and locale.
579 * <p>
580 * This method will create a formatter based on a simple
581 * <a href="#patterns">pattern of letters and symbols</a>
582 * as described in the class documentation.
583 * For example, {@code d MMM uuuu} will format 2011-12-03 as '3 Dec 2011'.
584 * <p>
585 * The formatter will use the specified locale.
586 * This can be changed using {@link DateTimeFormatter#withLocale(Locale)} on the returned formatter.
587 * If the specified locale contains "ca" (calendar), "rg" (region override) and/or "tz" (timezone)
588 * <a href="../../util/Locale.html#def_locale_extension">Unicode extensions</a>,
589 * the chronology and/or the zone are overriden. If both "ca" and "rg" are
590 * specified, the chronology from "ca" extension supersedes the implicit one
591 * from "rg" extension.
592 * <p>
593 * The returned formatter has no override chronology or zone.
594 * It uses {@link ResolverStyle#SMART SMART} resolver style.
595 *
596 * @param pattern the pattern to use, not null
597 * @param locale the locale to use, not null
598 * @return the formatter based on the pattern, not null
599 * @throws IllegalArgumentException if the pattern is invalid
600 * @see DateTimeFormatterBuilder#appendPattern(String)
601 */
602 public static DateTimeFormatter ofPattern(String pattern, Locale locale) {
603 return new DateTimeFormatterBuilder().appendPattern(pattern).toFormatter(locale);
604 }
605
606 //-----------------------------------------------------------------------
607 /**
608 * Returns a locale specific date format for the ISO chronology.
609 * <p>
610 * This returns a formatter that will format or parse a date.
611 * The exact format pattern used varies by locale.
1440 this.zone = zone;
1441 }
1442
1443 //-----------------------------------------------------------------------
1444 /**
1445 * Gets the locale to be used during formatting.
1446 * <p>
1447 * This is used to lookup any part of the formatter needing specific
1448 * localization, such as the text or localized pattern.
1449 *
1450 * @return the locale of this formatter, not null
1451 */
1452 public Locale getLocale() {
1453 return locale;
1454 }
1455
1456 /**
1457 * Returns a copy of this formatter with a new locale.
1458 * <p>
1459 * This is used to lookup any part of the formatter needing specific
1460 * localization, such as the text or localized pattern. If the new
1461 * locale contains "ca" (calendar), "rg" (region override) and/or "tz" (timezone)
1462 * <a href="../../util/Locale.html#def_locale_extension">Unicode extensions</a>,
1463 * the chronology and/or the zone are also overriden. If both "ca" and "rg" are
1464 * specified, the chronology from "ca" extension supersedes the implicit one
1465 * from "rg" extension.
1466 * <p>
1467 * This instance is immutable and unaffected by this method call.
1468 *
1469 * @param locale the new locale, not null
1470 * @return a formatter based on this formatter with the requested locale, not null
1471 */
1472 public DateTimeFormatter withLocale(Locale locale) {
1473 if (this.locale.equals(locale)) {
1474 return this;
1475 }
1476
1477 // Check for chronology/timezone in locale object
1478 Chronology c = locale.getUnicodeLocaleType("ca") != null ?
1479 Chronology.ofLocale(locale) : chrono;
1480 String tzType = locale.getUnicodeLocaleType("tz");
1481 ZoneId z = tzType != null ?
1482 TimeZoneNameUtility.convertLDMLShortID(tzType)
1483 .map(ZoneId::of)
1484 .orElse(zone) :
1485 zone;
1486 return new DateTimeFormatter(printerParser, locale, decimalStyle, resolverStyle, resolverFields, c, z);
1487 }
1488
1489 //-----------------------------------------------------------------------
1490 /**
1491 * Gets the DecimalStyle to be used during formatting.
1492 *
1493 * @return the locale of this formatter, not null
1494 */
1495 public DecimalStyle getDecimalStyle() {
1496 return decimalStyle;
1497 }
1498
1499 /**
1500 * Returns a copy of this formatter with a new DecimalStyle.
1501 * <p>
1502 * This instance is immutable and unaffected by this method call.
1503 *
1504 * @param decimalStyle the new DecimalStyle, not null
1505 * @return a formatter based on this formatter with the requested DecimalStyle, not null
1506 */
|