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 overridden. If both "ca" and "rg" are
137 * specified, the chronology from the "ca" extension supersedes the implicit one
138 * from the "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 overridden. If both "ca" and "rg" are
562 * specified, the chronology from the "ca" extension supersedes the implicit one
563 * from the "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 overridden. If both "ca" and "rg" are
590 * specified, the chronology from the "ca" extension supersedes the implicit one
591 * from the "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 overridden. If both "ca" and "rg" are
1464 * specified, the chronology from the "ca" extension supersedes the implicit one
1465 * from the "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,
1487 resolverStyle, resolverFields, c, z);
1488 }
1489
1490 //-----------------------------------------------------------------------
1491 /**
1492 * Gets the DecimalStyle to be used during formatting.
1493 *
1494 * @return the locale of this formatter, not null
1495 */
1496 public DecimalStyle getDecimalStyle() {
1497 return decimalStyle;
1498 }
1499
1500 /**
1501 * Returns a copy of this formatter with a new DecimalStyle.
1502 * <p>
1503 * This instance is immutable and unaffected by this method call.
1504 *
1505 * @param decimalStyle the new DecimalStyle, not null
1506 * @return a formatter based on this formatter with the requested DecimalStyle, not null
1507 */
|
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.
134 * <p>
135 * The {@link #withChronology withChronology} method returns a new formatter
136 * that overrides the chronology. If overridden, the date-time value is
137 * converted to the chronology before formatting. During parsing the date-time
138 * value is converted to the chronology before it is returned.
139 * <p>
140 * The {@link #withZone withZone} method returns a new formatter that overrides
141 * the zone. If overridden, the date-time value is converted to a ZonedDateTime
142 * with the requested ZoneId before formatting. During parsing the ZoneId is
143 * applied before the value is returned.
144 * <p>
145 * The {@link #withDecimalStyle withDecimalStyle} method returns a new formatter that
146 * overrides the {@link DecimalStyle}. The DecimalStyle symbols are used for
147 * formatting and parsing.
148 * <p>
149 * Some applications may need to use the older {@link Format java.text.Format}
150 * class for formatting. The {@link #toFormat()} method returns an
151 * implementation of {@code java.text.Format}.
152 *
153 * <h3 id="predefined">Predefined Formatters</h3>
532 private final Set<TemporalField> resolverFields;
533 /**
534 * The chronology to use for formatting, null for no override.
535 */
536 private final Chronology chrono;
537 /**
538 * The zone to use for formatting, null for no override.
539 */
540 private final ZoneId zone;
541
542 //-----------------------------------------------------------------------
543 /**
544 * Creates a formatter using the specified pattern.
545 * <p>
546 * This method will create a formatter based on a simple
547 * <a href="#patterns">pattern of letters and symbols</a>
548 * as described in the class documentation.
549 * For example, {@code d MMM uuuu} will format 2011-12-03 as '3 Dec 2011'.
550 * <p>
551 * The formatter will use the {@link Locale#getDefault(Locale.Category) default FORMAT locale}.
552 * This can be changed using {@link DateTimeFormatter#withLocale(Locale)} on the returned formatter
553 * Alternatively use the {@link #ofPattern(String, Locale)} variant of this method.
554 * <p>
555 * The returned formatter has no override chronology or zone.
556 * It uses {@link ResolverStyle#SMART SMART} resolver style.
557 *
558 * @param pattern the pattern to use, not null
559 * @return the formatter based on the pattern, not null
560 * @throws IllegalArgumentException if the pattern is invalid
561 * @see DateTimeFormatterBuilder#appendPattern(String)
562 */
563 public static DateTimeFormatter ofPattern(String pattern) {
564 return new DateTimeFormatterBuilder().appendPattern(pattern).toFormatter();
565 }
566
567 /**
568 * Creates a formatter using the specified pattern and locale.
569 * <p>
570 * This method will create a formatter based on a simple
571 * <a href="#patterns">pattern of letters and symbols</a>
572 * as described in the class documentation.
573 * For example, {@code d MMM uuuu} will format 2011-12-03 as '3 Dec 2011'.
574 * <p>
575 * The formatter will use the specified locale.
576 * This can be changed using {@link DateTimeFormatter#withLocale(Locale)} on the returned formatter
577 * <p>
578 * The returned formatter has no override chronology or zone.
579 * It uses {@link ResolverStyle#SMART SMART} resolver style.
580 *
581 * @param pattern the pattern to use, not null
582 * @param locale the locale to use, not null
583 * @return the formatter based on the pattern, not null
584 * @throws IllegalArgumentException if the pattern is invalid
585 * @see DateTimeFormatterBuilder#appendPattern(String)
586 */
587 public static DateTimeFormatter ofPattern(String pattern, Locale locale) {
588 return new DateTimeFormatterBuilder().appendPattern(pattern).toFormatter(locale);
589 }
590
591 //-----------------------------------------------------------------------
592 /**
593 * Returns a locale specific date format for the ISO chronology.
594 * <p>
595 * This returns a formatter that will format or parse a date.
596 * The exact format pattern used varies by locale.
1425 this.zone = zone;
1426 }
1427
1428 //-----------------------------------------------------------------------
1429 /**
1430 * Gets the locale to be used during formatting.
1431 * <p>
1432 * This is used to lookup any part of the formatter needing specific
1433 * localization, such as the text or localized pattern.
1434 *
1435 * @return the locale of this formatter, not null
1436 */
1437 public Locale getLocale() {
1438 return locale;
1439 }
1440
1441 /**
1442 * Returns a copy of this formatter with a new locale.
1443 * <p>
1444 * This is used to lookup any part of the formatter needing specific
1445 * localization, such as the text or localized pattern.
1446 * <p>
1447 * The locale is stored as passed in, without further processing.
1448 * If the locale has unicode extensions, they may be used later in text
1449 * processing. To set the chronology, time-zone and decimal style from
1450 * unicode extensions, see {@link #localizedBy localizedBy()}.
1451 * <p>
1452 * This instance is immutable and unaffected by this method call.
1453 *
1454 * @param locale the new locale, not null
1455 * @return a formatter based on this formatter with the requested locale, not null
1456 * @see #localizedBy(Locale)
1457 */
1458 public DateTimeFormatter withLocale(Locale locale) {
1459 if (this.locale.equals(locale)) {
1460 return this;
1461 }
1462 return new DateTimeFormatter(printerParser, locale, decimalStyle, resolverStyle, resolverFields, chrono, zone);
1463 }
1464
1465 /**
1466 * Returns a copy of this formatter with localized values of the locale,
1467 * calendar, region, decimal style and/or timezone, that supercede values in
1468 * this formatter.
1469 * <p>
1470 * This is used to lookup any part of the formatter needing specific
1471 * localization, such as the text or localized pattern. If the locale contains the
1472 * "ca" (calendar), "nu" (numbering system), "rg" (region override), and/or
1473 * "tz" (timezone)
1474 * <a href="../../util/Locale.html#def_locale_extension">Unicode extensions</a>,
1475 * the chronology, numbering system and/or the zone are overridden. If both "ca"
1476 * and "rg" are specified, the chronology from the "ca" extension supersedes the
1477 * implicit one from the "rg" extension. Same is true for the "nu" extension.
1478 * <p>
1479 * Unlike the {@link #withLocale withLocale} method, the call to this method may
1480 * produce a different formatter depending on the order of method chaining with
1481 * other withXXXX() methods.
1482 * <p>
1483 * This instance is immutable and unaffected by this method call.
1484 *
1485 * @param locale the locale, not null
1486 * @return a formatter based on this formatter with localized values of
1487 * the calendar, decimal style and/or timezone, that supercede values in this
1488 * formatter.
1489 * @see #withLocale(Locale)
1490 * @since 10
1491 */
1492 public DateTimeFormatter localizedBy(Locale locale) {
1493 if (this.locale.equals(locale)) {
1494 return this;
1495 }
1496
1497 // Check for decimalStyle/chronology/timezone in locale object
1498 Chronology c = locale.getUnicodeLocaleType("ca") != null ?
1499 Chronology.ofLocale(locale) : chrono;
1500 DecimalStyle ds = locale.getUnicodeLocaleType("nu") != null ?
1501 DecimalStyle.of(locale) : decimalStyle;
1502 String tzType = locale.getUnicodeLocaleType("tz");
1503 ZoneId z = tzType != null ?
1504 TimeZoneNameUtility.convertLDMLShortID(tzType)
1505 .map(ZoneId::of)
1506 .orElse(zone) :
1507 zone;
1508 return withLocale(locale)
1509 .withChronology(c)
1510 .withDecimalStyle(ds)
1511 .withZone(z);
1512 }
1513
1514 //-----------------------------------------------------------------------
1515 /**
1516 * Gets the DecimalStyle to be used during formatting.
1517 *
1518 * @return the locale of this formatter, not null
1519 */
1520 public DecimalStyle getDecimalStyle() {
1521 return decimalStyle;
1522 }
1523
1524 /**
1525 * Returns a copy of this formatter with a new DecimalStyle.
1526 * <p>
1527 * This instance is immutable and unaffected by this method call.
1528 *
1529 * @param decimalStyle the new DecimalStyle, not null
1530 * @return a formatter based on this formatter with the requested DecimalStyle, not null
1531 */
|