< prev index next >

src/java.base/share/classes/java/time/format/DateTimeFormatterBuilder.java

Print this page


   1 /*
   2  * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any


  73 import static java.time.temporal.ChronoField.ERA;
  74 
  75 import java.lang.ref.SoftReference;
  76 import java.math.BigDecimal;
  77 import java.math.BigInteger;
  78 import java.math.RoundingMode;
  79 import java.text.ParsePosition;
  80 import java.time.DateTimeException;
  81 import java.time.Instant;
  82 import java.time.LocalDate;
  83 import java.time.LocalDateTime;
  84 import java.time.ZoneId;
  85 import java.time.ZoneOffset;
  86 import java.time.chrono.ChronoLocalDate;
  87 import java.time.chrono.Chronology;
  88 import java.time.chrono.Era;
  89 import java.time.chrono.IsoChronology;
  90 import java.time.format.DateTimeTextProvider.LocaleStore;
  91 import java.time.temporal.ChronoField;
  92 import java.time.temporal.IsoFields;

  93 import java.time.temporal.TemporalAccessor;
  94 import java.time.temporal.TemporalField;
  95 import java.time.temporal.TemporalQueries;
  96 import java.time.temporal.TemporalQuery;
  97 import java.time.temporal.ValueRange;
  98 import java.time.temporal.WeekFields;
  99 import java.time.zone.ZoneRulesProvider;
 100 import java.util.AbstractMap.SimpleImmutableEntry;
 101 import java.util.ArrayList;
 102 import java.util.Arrays;
 103 import java.util.Collections;
 104 import java.util.Comparator;
 105 import java.util.HashMap;
 106 import java.util.HashSet;
 107 import java.util.Iterator;
 108 import java.util.LinkedHashMap;
 109 import java.util.List;
 110 import java.util.Locale;
 111 import java.util.Map;
 112 import java.util.Map.Entry;


1351         return this;
1352     }
1353 
1354     //-----------------------------------------------------------------------
1355     /**
1356      * Appends the elements defined by the specified pattern to the builder.
1357      * <p>
1358      * All letters 'A' to 'Z' and 'a' to 'z' are reserved as pattern letters.
1359      * The characters '#', '{' and '}' are reserved for future use.
1360      * The characters '[' and ']' indicate optional patterns.
1361      * The following pattern letters are defined:
1362      * <pre>
1363      *  Symbol  Meaning                     Presentation      Examples
1364      *  ------  -------                     ------------      -------
1365      *   G       era                         text              AD; Anno Domini; A
1366      *   u       year                        year              2004; 04
1367      *   y       year-of-era                 year              2004; 04
1368      *   D       day-of-year                 number            189
1369      *   M/L     month-of-year               number/text       7; 07; Jul; July; J
1370      *   d       day-of-month                number            10

1371      *
1372      *   Q/q     quarter-of-year             number/text       3; 03; Q3; 3rd quarter
1373      *   Y       week-based-year             year              1996; 96
1374      *   w       week-of-week-based-year     number            27
1375      *   W       week-of-month               number            4
1376      *   E       day-of-week                 text              Tue; Tuesday; T
1377      *   e/c     localized day-of-week       number/text       2; 02; Tue; Tuesday; T
1378      *   F       week-of-month               number            3
1379      *
1380      *   a       am-pm-of-day                text              PM
1381      *   h       clock-hour-of-am-pm (1-12)  number            12
1382      *   K       hour-of-am-pm (0-11)        number            0
1383      *   k       clock-hour-of-am-pm (1-24)  number            0
1384      *
1385      *   H       hour-of-day (0-23)          number            0
1386      *   m       minute-of-hour              number            30
1387      *   s       second-of-minute            number            55
1388      *   S       fraction-of-second          fraction          978
1389      *   A       milli-of-day                number            1234
1390      *   n       nano-of-second              number            987654321
1391      *   N       nano-of-day                 number            1234000000
1392      *
1393      *   V       time-zone ID                zone-id           America/Los_Angeles; Z; -08:30
1394      *   z       time-zone name              zone-name         Pacific Standard Time; PST
1395      *   O       localized zone-offset       offset-O          GMT+8; GMT+08:00; UTC-08:00;
1396      *   X       zone-offset 'Z' for zero    offset-X          Z; -08; -0830; -08:30; -083015; -08:30:15;
1397      *   x       zone-offset                 offset-x          +0000; -08; -0830; -08:30; -083015; -08:30:15;
1398      *   Z       zone-offset                 offset-Z          +0000; -0800; -08:00;
1399      *
1400      *   p       pad next                    pad modifier      1
1401      *
1402      *   '       escape for text             delimiter
1403      *   ''      single quote                literal           '
1404      *   [       optional section start
1405      *   ]       optional section end
1406      *   #       reserved for future use
1407      *   {       reserved for future use
1408      *   }       reserved for future use
1409      * </pre>
1410      * <p>
1411      * The count of pattern letters determine the format.
1412      * See <a href="DateTimeFormatter.html#patterns">DateTimeFormatter</a> for a user-focused description of the patterns.
1413      * The following tables define how the pattern letters map to the builder.
1414      * <p>
1415      * <b>Date fields</b>: Pattern letters to output a date.
1416      * <pre>
1417      *  Pattern  Count  Equivalent builder methods
1418      *  -------  -----  --------------------------
1419      *    G       1      appendText(ChronoField.ERA, TextStyle.SHORT)
1420      *    GG      2      appendText(ChronoField.ERA, TextStyle.SHORT)
1421      *    GGG     3      appendText(ChronoField.ERA, TextStyle.SHORT)
1422      *    GGGG    4      appendText(ChronoField.ERA, TextStyle.FULL)
1423      *    GGGGG   5      appendText(ChronoField.ERA, TextStyle.NARROW)
1424      *
1425      *    u       1      appendValue(ChronoField.YEAR, 1, 19, SignStyle.NORMAL);
1426      *    uu      2      appendValueReduced(ChronoField.YEAR, 2, 2000);
1427      *    uuu     3      appendValue(ChronoField.YEAR, 3, 19, SignStyle.NORMAL);
1428      *    u..u    4..n   appendValue(ChronoField.YEAR, n, 19, SignStyle.EXCEEDS_PAD);
1429      *    y       1      appendValue(ChronoField.YEAR_OF_ERA, 1, 19, SignStyle.NORMAL);
1430      *    yy      2      appendValueReduced(ChronoField.YEAR_OF_ERA, 2, 2000);
1431      *    yyy     3      appendValue(ChronoField.YEAR_OF_ERA, 3, 19, SignStyle.NORMAL);
1432      *    y..y    4..n   appendValue(ChronoField.YEAR_OF_ERA, n, 19, SignStyle.EXCEEDS_PAD);
1433      *    Y       1      append special localized WeekFields element for numeric week-based-year
1434      *    YY      2      append special localized WeekFields element for reduced numeric week-based-year 2 digits;
1435      *    YYY     3      append special localized WeekFields element for numeric week-based-year (3, 19, SignStyle.NORMAL);
1436      *    Y..Y    4..n   append special localized WeekFields element for numeric week-based-year (n, 19, SignStyle.EXCEEDS_PAD);
1437      *
1438      *    Q       1      appendValue(IsoFields.QUARTER_OF_YEAR);
1439      *    QQ      2      appendValue(IsoFields.QUARTER_OF_YEAR, 2);
1440      *    QQQ     3      appendText(IsoFields.QUARTER_OF_YEAR, TextStyle.SHORT)
1441      *    QQQQ    4      appendText(IsoFields.QUARTER_OF_YEAR, TextStyle.FULL)
1442      *    QQQQQ   5      appendText(IsoFields.QUARTER_OF_YEAR, TextStyle.NARROW)
1443      *    q       1      appendValue(IsoFields.QUARTER_OF_YEAR);
1444      *    qq      2      appendValue(IsoFields.QUARTER_OF_YEAR, 2);
1445      *    qqq     3      appendText(IsoFields.QUARTER_OF_YEAR, TextStyle.SHORT_STANDALONE)
1446      *    qqqq    4      appendText(IsoFields.QUARTER_OF_YEAR, TextStyle.FULL_STANDALONE)
1447      *    qqqqq   5      appendText(IsoFields.QUARTER_OF_YEAR, TextStyle.NARROW_STANDALONE)
1448      *
1449      *    M       1      appendValue(ChronoField.MONTH_OF_YEAR);
1450      *    MM      2      appendValue(ChronoField.MONTH_OF_YEAR, 2);
1451      *    MMM     3      appendText(ChronoField.MONTH_OF_YEAR, TextStyle.SHORT)
1452      *    MMMM    4      appendText(ChronoField.MONTH_OF_YEAR, TextStyle.FULL)
1453      *    MMMMM   5      appendText(ChronoField.MONTH_OF_YEAR, TextStyle.NARROW)
1454      *    L       1      appendValue(ChronoField.MONTH_OF_YEAR);
1455      *    LL      2      appendValue(ChronoField.MONTH_OF_YEAR, 2);
1456      *    LLL     3      appendText(ChronoField.MONTH_OF_YEAR, TextStyle.SHORT_STANDALONE)
1457      *    LLLL    4      appendText(ChronoField.MONTH_OF_YEAR, TextStyle.FULL_STANDALONE)
1458      *    LLLLL   5      appendText(ChronoField.MONTH_OF_YEAR, TextStyle.NARROW_STANDALONE)
1459      *
1460      *    w       1      append special localized WeekFields element for numeric week-of-year
1461      *    ww      2      append special localized WeekFields element for numeric week-of-year, zero-padded
1462      *    W       1      append special localized WeekFields element for numeric week-of-month
1463      *    d       1      appendValue(ChronoField.DAY_OF_MONTH)
1464      *    dd      2      appendValue(ChronoField.DAY_OF_MONTH, 2)
1465      *    D       1      appendValue(ChronoField.DAY_OF_YEAR)
1466      *    DD      2      appendValue(ChronoField.DAY_OF_YEAR, 2)
1467      *    DDD     3      appendValue(ChronoField.DAY_OF_YEAR, 3)
1468      *    F       1      appendValue(ChronoField.ALIGNED_DAY_OF_WEEK_IN_MONTH)

1469      *    E       1      appendText(ChronoField.DAY_OF_WEEK, TextStyle.SHORT)
1470      *    EE      2      appendText(ChronoField.DAY_OF_WEEK, TextStyle.SHORT)
1471      *    EEE     3      appendText(ChronoField.DAY_OF_WEEK, TextStyle.SHORT)
1472      *    EEEE    4      appendText(ChronoField.DAY_OF_WEEK, TextStyle.FULL)
1473      *    EEEEE   5      appendText(ChronoField.DAY_OF_WEEK, TextStyle.NARROW)
1474      *    e       1      append special localized WeekFields element for numeric day-of-week
1475      *    ee      2      append special localized WeekFields element for numeric day-of-week, zero-padded
1476      *    eee     3      appendText(ChronoField.DAY_OF_WEEK, TextStyle.SHORT)
1477      *    eeee    4      appendText(ChronoField.DAY_OF_WEEK, TextStyle.FULL)
1478      *    eeeee   5      appendText(ChronoField.DAY_OF_WEEK, TextStyle.NARROW)
1479      *    c       1      append special localized WeekFields element for numeric day-of-week
1480      *    ccc     3      appendText(ChronoField.DAY_OF_WEEK, TextStyle.SHORT_STANDALONE)
1481      *    cccc    4      appendText(ChronoField.DAY_OF_WEEK, TextStyle.FULL_STANDALONE)
1482      *    ccccc   5      appendText(ChronoField.DAY_OF_WEEK, TextStyle.NARROW_STANDALONE)
1483      * </pre>
1484      * <p>
1485      * <b>Time fields</b>: Pattern letters to output a time.
1486      * <pre>
1487      *  Pattern  Count  Equivalent builder methods
1488      *  -------  -----  --------------------------


1507      *    n..n    2..n   appendValue(ChronoField.NANO_OF_SECOND, n)
1508      *    N       1      appendValue(ChronoField.NANO_OF_DAY)
1509      *    N..N    2..n   appendValue(ChronoField.NANO_OF_DAY, n)
1510      * </pre>
1511      * <p>
1512      * <b>Zone ID</b>: Pattern letters to output {@code ZoneId}.
1513      * <pre>
1514      *  Pattern  Count  Equivalent builder methods
1515      *  -------  -----  --------------------------
1516      *    VV      2      appendZoneId()
1517      *    z       1      appendZoneText(TextStyle.SHORT)
1518      *    zz      2      appendZoneText(TextStyle.SHORT)
1519      *    zzz     3      appendZoneText(TextStyle.SHORT)
1520      *    zzzz    4      appendZoneText(TextStyle.FULL)
1521      * </pre>
1522      * <p>
1523      * <b>Zone offset</b>: Pattern letters to output {@code ZoneOffset}.
1524      * <pre>
1525      *  Pattern  Count  Equivalent builder methods
1526      *  -------  -----  --------------------------
1527      *    O       1      appendLocalizedOffsetPrefixed(TextStyle.SHORT);
1528      *    OOOO    4      appendLocalizedOffsetPrefixed(TextStyle.FULL);
1529      *    X       1      appendOffset("+HHmm","Z")
1530      *    XX      2      appendOffset("+HHMM","Z")
1531      *    XXX     3      appendOffset("+HH:MM","Z")
1532      *    XXXX    4      appendOffset("+HHMMss","Z")
1533      *    XXXXX   5      appendOffset("+HH:MM:ss","Z")
1534      *    x       1      appendOffset("+HHmm","+00")
1535      *    xx      2      appendOffset("+HHMM","+0000")
1536      *    xxx     3      appendOffset("+HH:MM","+00:00")
1537      *    xxxx    4      appendOffset("+HHMMss","+0000")
1538      *    xxxxx   5      appendOffset("+HH:MM:ss","+00:00")
1539      *    Z       1      appendOffset("+HHMM","+0000")
1540      *    ZZ      2      appendOffset("+HHMM","+0000")
1541      *    ZZZ     3      appendOffset("+HHMM","+0000")
1542      *    ZZZZ    4      appendLocalizedOffset(TextStyle.FULL);
1543      *    ZZZZZ   5      appendOffset("+HH:MM:ss","Z")
1544      * </pre>
1545      * <p>
1546      * <b>Modifiers</b>: Pattern letters that modify the rest of the pattern:
1547      * <pre>
1548      *  Pattern  Count  Equivalent builder methods
1549      *  -------  -----  --------------------------
1550      *    [       1      optionalStart()
1551      *    ]       1      optionalEnd()
1552      *    p..p    1..n   padNext(n)
1553      * </pre>
1554      * <p>
1555      * Any sequence of letters not specified above, unrecognized letter or
1556      * reserved character will throw an exception.
1557      * Future versions may add to the set of patterns.
1558      * It is recommended to use single quotes around all characters that you want
1559      * to output directly to ensure that future changes do not break your application.
1560      * <p>
1561      * Note that the pattern string is similar, but not identical, to
1562      * {@link java.text.SimpleDateFormat SimpleDateFormat}.


1804             case 'K':
1805             case 'm':
1806             case 's':
1807                 if (count == 1) {
1808                     appendValue(field);
1809                 } else if (count == 2) {
1810                     appendValue(field, count);
1811                 } else {
1812                     throw new IllegalArgumentException("Too many pattern letters: " + cur);
1813                 }
1814                 break;
1815             case 'D':
1816                 if (count == 1) {
1817                     appendValue(field);
1818                 } else if (count <= 3) {
1819                     appendValue(field, count);
1820                 } else {
1821                     throw new IllegalArgumentException("Too many pattern letters: " + cur);
1822                 }
1823                 break;



1824             default:
1825                 if (count == 1) {
1826                     appendValue(field);
1827                 } else {
1828                     appendValue(field, count);
1829                 }
1830                 break;
1831         }
1832     }
1833 
1834     /** Map of letters to fields. */
1835     private static final Map<Character, TemporalField> FIELD_MAP = new HashMap<>();
1836     static {
1837         // SDF = SimpleDateFormat
1838         FIELD_MAP.put('G', ChronoField.ERA);                       // SDF, LDML (different to both for 1/2 chars)
1839         FIELD_MAP.put('y', ChronoField.YEAR_OF_ERA);               // SDF, LDML
1840         FIELD_MAP.put('u', ChronoField.YEAR);                      // LDML (different in SDF)
1841         FIELD_MAP.put('Q', IsoFields.QUARTER_OF_YEAR);             // LDML (removed quarter from 310)
1842         FIELD_MAP.put('q', IsoFields.QUARTER_OF_YEAR);             // LDML (stand-alone)
1843         FIELD_MAP.put('M', ChronoField.MONTH_OF_YEAR);             // SDF, LDML
1844         FIELD_MAP.put('L', ChronoField.MONTH_OF_YEAR);             // SDF, LDML (stand-alone)
1845         FIELD_MAP.put('D', ChronoField.DAY_OF_YEAR);               // SDF, LDML
1846         FIELD_MAP.put('d', ChronoField.DAY_OF_MONTH);              // SDF, LDML
1847         FIELD_MAP.put('F', ChronoField.ALIGNED_DAY_OF_WEEK_IN_MONTH);  // SDF, LDML
1848         FIELD_MAP.put('E', ChronoField.DAY_OF_WEEK);               // SDF, LDML (different to both for 1/2 chars)
1849         FIELD_MAP.put('c', ChronoField.DAY_OF_WEEK);               // LDML (stand-alone)
1850         FIELD_MAP.put('e', ChronoField.DAY_OF_WEEK);               // LDML (needs localized week number)
1851         FIELD_MAP.put('a', ChronoField.AMPM_OF_DAY);               // SDF, LDML
1852         FIELD_MAP.put('H', ChronoField.HOUR_OF_DAY);               // SDF, LDML
1853         FIELD_MAP.put('k', ChronoField.CLOCK_HOUR_OF_DAY);         // SDF, LDML
1854         FIELD_MAP.put('K', ChronoField.HOUR_OF_AMPM);              // SDF, LDML
1855         FIELD_MAP.put('h', ChronoField.CLOCK_HOUR_OF_AMPM);        // SDF, LDML
1856         FIELD_MAP.put('m', ChronoField.MINUTE_OF_HOUR);            // SDF, LDML
1857         FIELD_MAP.put('s', ChronoField.SECOND_OF_MINUTE);          // SDF, LDML
1858         FIELD_MAP.put('S', ChronoField.NANO_OF_SECOND);            // LDML (SDF uses milli-of-second number)
1859         FIELD_MAP.put('A', ChronoField.MILLI_OF_DAY);              // LDML
1860         FIELD_MAP.put('n', ChronoField.NANO_OF_SECOND);            // 310 (proposed for LDML)
1861         FIELD_MAP.put('N', ChronoField.NANO_OF_DAY);               // 310 (proposed for LDML)

1862         // 310 - z - time-zone names, matches LDML and SimpleDateFormat 1 to 4
1863         // 310 - Z - matches SimpleDateFormat and LDML
1864         // 310 - V - time-zone id, matches LDML
1865         // 310 - p - prefix for padding
1866         // 310 - X - matches LDML, almost matches SDF for 1, exact match 2&3, extended 4&5
1867         // 310 - x - matches LDML
1868         // 310 - w, W, and Y are localized forms matching LDML
1869         // LDML - U - cycle year name, not supported by 310 yet
1870         // LDML - l - deprecated
1871         // LDML - j - not relevant
1872         // LDML - g - modified-julian-day
1873         // LDML - v,V - extended time-zone names
1874     }
1875 
1876     //-----------------------------------------------------------------------
1877     /**
1878      * Causes the next added printer/parser to pad to a fixed width using a space.
1879      * <p>
1880      * This padding will pad to a fixed width using spaces.
1881      * <p>
1882      * During formatting, the decorated element will be output and then padded
1883      * to the specified width. An exception will be thrown during formatting if
1884      * the pad width is exceeded.
1885      * <p>
1886      * During parsing, the padding and decorated element are parsed.
1887      * If parsing is lenient, then the pad width is treated as a maximum.
1888      * The padding is parsed greedily. Thus, if the decorated element starts with
1889      * the pad character, it will not be parsed.
1890      *
1891      * @param padWidth  the pad width, 1 or greater
1892      * @return this, for chaining, not null


   1 /*
   2  * Copyright (c) 2012, 2016, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any


  73 import static java.time.temporal.ChronoField.ERA;
  74 
  75 import java.lang.ref.SoftReference;
  76 import java.math.BigDecimal;
  77 import java.math.BigInteger;
  78 import java.math.RoundingMode;
  79 import java.text.ParsePosition;
  80 import java.time.DateTimeException;
  81 import java.time.Instant;
  82 import java.time.LocalDate;
  83 import java.time.LocalDateTime;
  84 import java.time.ZoneId;
  85 import java.time.ZoneOffset;
  86 import java.time.chrono.ChronoLocalDate;
  87 import java.time.chrono.Chronology;
  88 import java.time.chrono.Era;
  89 import java.time.chrono.IsoChronology;
  90 import java.time.format.DateTimeTextProvider.LocaleStore;
  91 import java.time.temporal.ChronoField;
  92 import java.time.temporal.IsoFields;
  93 import java.time.temporal.JulianFields;
  94 import java.time.temporal.TemporalAccessor;
  95 import java.time.temporal.TemporalField;
  96 import java.time.temporal.TemporalQueries;
  97 import java.time.temporal.TemporalQuery;
  98 import java.time.temporal.ValueRange;
  99 import java.time.temporal.WeekFields;
 100 import java.time.zone.ZoneRulesProvider;
 101 import java.util.AbstractMap.SimpleImmutableEntry;
 102 import java.util.ArrayList;
 103 import java.util.Arrays;
 104 import java.util.Collections;
 105 import java.util.Comparator;
 106 import java.util.HashMap;
 107 import java.util.HashSet;
 108 import java.util.Iterator;
 109 import java.util.LinkedHashMap;
 110 import java.util.List;
 111 import java.util.Locale;
 112 import java.util.Map;
 113 import java.util.Map.Entry;


1352         return this;
1353     }
1354 
1355     //-----------------------------------------------------------------------
1356     /**
1357      * Appends the elements defined by the specified pattern to the builder.
1358      * <p>
1359      * All letters 'A' to 'Z' and 'a' to 'z' are reserved as pattern letters.
1360      * The characters '#', '{' and '}' are reserved for future use.
1361      * The characters '[' and ']' indicate optional patterns.
1362      * The following pattern letters are defined:
1363      * <pre>
1364      *  Symbol  Meaning                     Presentation      Examples
1365      *  ------  -------                     ------------      -------
1366      *   G       era                         text              AD; Anno Domini; A
1367      *   u       year                        year              2004; 04
1368      *   y       year-of-era                 year              2004; 04
1369      *   D       day-of-year                 number            189
1370      *   M/L     month-of-year               number/text       7; 07; Jul; July; J
1371      *   d       day-of-month                number            10
1372      *   g       modified-julian-day         number            2451334
1373      *
1374      *   Q/q     quarter-of-year             number/text       3; 03; Q3; 3rd quarter
1375      *   Y       week-based-year             year              1996; 96
1376      *   w       week-of-week-based-year     number            27
1377      *   W       week-of-month               number            4
1378      *   E       day-of-week                 text              Tue; Tuesday; T
1379      *   e/c     localized day-of-week       number/text       2; 02; Tue; Tuesday; T
1380      *   F       week-of-month               number            3
1381      *
1382      *   a       am-pm-of-day                text              PM
1383      *   h       clock-hour-of-am-pm (1-12)  number            12
1384      *   K       hour-of-am-pm (0-11)        number            0
1385      *   k       clock-hour-of-am-pm (1-24)  number            0
1386      *
1387      *   H       hour-of-day (0-23)          number            0
1388      *   m       minute-of-hour              number            30
1389      *   s       second-of-minute            number            55
1390      *   S       fraction-of-second          fraction          978
1391      *   A       milli-of-day                number            1234
1392      *   n       nano-of-second              number            987654321
1393      *   N       nano-of-day                 number            1234000000
1394      *
1395      *   V       time-zone ID                zone-id           America/Los_Angeles; Z; -08:30
1396      *   z       time-zone name              zone-name         Pacific Standard Time; PST
1397      *   O       localized zone-offset       offset-O          GMT+8; GMT+08:00; UTC-08:00;
1398      *   X       zone-offset 'Z' for zero    offset-X          Z; -08; -0830; -08:30; -083015; -08:30:15
1399      *   x       zone-offset                 offset-x          +0000; -08; -0830; -08:30; -083015; -08:30:15
1400      *   Z       zone-offset                 offset-Z          +0000; -0800; -08:00
1401      *
1402      *   p       pad next                    pad modifier      1
1403      *
1404      *   '       escape for text             delimiter
1405      *   ''      single quote                literal           '
1406      *   [       optional section start
1407      *   ]       optional section end
1408      *   #       reserved for future use
1409      *   {       reserved for future use
1410      *   }       reserved for future use
1411      * </pre>
1412      * <p>
1413      * The count of pattern letters determine the format.
1414      * See <a href="DateTimeFormatter.html#patterns">DateTimeFormatter</a> for a user-focused description of the patterns.
1415      * The following tables define how the pattern letters map to the builder.
1416      * <p>
1417      * <b>Date fields</b>: Pattern letters to output a date.
1418      * <pre>
1419      *  Pattern  Count  Equivalent builder methods
1420      *  -------  -----  --------------------------
1421      *    G       1      appendText(ChronoField.ERA, TextStyle.SHORT)
1422      *    GG      2      appendText(ChronoField.ERA, TextStyle.SHORT)
1423      *    GGG     3      appendText(ChronoField.ERA, TextStyle.SHORT)
1424      *    GGGG    4      appendText(ChronoField.ERA, TextStyle.FULL)
1425      *    GGGGG   5      appendText(ChronoField.ERA, TextStyle.NARROW)
1426      *
1427      *    u       1      appendValue(ChronoField.YEAR, 1, 19, SignStyle.NORMAL)
1428      *    uu      2      appendValueReduced(ChronoField.YEAR, 2, 2000)
1429      *    uuu     3      appendValue(ChronoField.YEAR, 3, 19, SignStyle.NORMAL)
1430      *    u..u    4..n   appendValue(ChronoField.YEAR, n, 19, SignStyle.EXCEEDS_PAD)
1431      *    y       1      appendValue(ChronoField.YEAR_OF_ERA, 1, 19, SignStyle.NORMAL)
1432      *    yy      2      appendValueReduced(ChronoField.YEAR_OF_ERA, 2, 2000)
1433      *    yyy     3      appendValue(ChronoField.YEAR_OF_ERA, 3, 19, SignStyle.NORMAL)
1434      *    y..y    4..n   appendValue(ChronoField.YEAR_OF_ERA, n, 19, SignStyle.EXCEEDS_PAD)
1435      *    Y       1      append special localized WeekFields element for numeric week-based-year
1436      *    YY      2      append special localized WeekFields element for reduced numeric week-based-year 2 digits
1437      *    YYY     3      append special localized WeekFields element for numeric week-based-year (3, 19, SignStyle.NORMAL)
1438      *    Y..Y    4..n   append special localized WeekFields element for numeric week-based-year (n, 19, SignStyle.EXCEEDS_PAD)
1439      *
1440      *    Q       1      appendValue(IsoFields.QUARTER_OF_YEAR)
1441      *    QQ      2      appendValue(IsoFields.QUARTER_OF_YEAR, 2)
1442      *    QQQ     3      appendText(IsoFields.QUARTER_OF_YEAR, TextStyle.SHORT)
1443      *    QQQQ    4      appendText(IsoFields.QUARTER_OF_YEAR, TextStyle.FULL)
1444      *    QQQQQ   5      appendText(IsoFields.QUARTER_OF_YEAR, TextStyle.NARROW)
1445      *    q       1      appendValue(IsoFields.QUARTER_OF_YEAR)
1446      *    qq      2      appendValue(IsoFields.QUARTER_OF_YEAR, 2)
1447      *    qqq     3      appendText(IsoFields.QUARTER_OF_YEAR, TextStyle.SHORT_STANDALONE)
1448      *    qqqq    4      appendText(IsoFields.QUARTER_OF_YEAR, TextStyle.FULL_STANDALONE)
1449      *    qqqqq   5      appendText(IsoFields.QUARTER_OF_YEAR, TextStyle.NARROW_STANDALONE)
1450      *
1451      *    M       1      appendValue(ChronoField.MONTH_OF_YEAR)
1452      *    MM      2      appendValue(ChronoField.MONTH_OF_YEAR, 2)
1453      *    MMM     3      appendText(ChronoField.MONTH_OF_YEAR, TextStyle.SHORT)
1454      *    MMMM    4      appendText(ChronoField.MONTH_OF_YEAR, TextStyle.FULL)
1455      *    MMMMM   5      appendText(ChronoField.MONTH_OF_YEAR, TextStyle.NARROW)
1456      *    L       1      appendValue(ChronoField.MONTH_OF_YEAR)
1457      *    LL      2      appendValue(ChronoField.MONTH_OF_YEAR, 2)
1458      *    LLL     3      appendText(ChronoField.MONTH_OF_YEAR, TextStyle.SHORT_STANDALONE)
1459      *    LLLL    4      appendText(ChronoField.MONTH_OF_YEAR, TextStyle.FULL_STANDALONE)
1460      *    LLLLL   5      appendText(ChronoField.MONTH_OF_YEAR, TextStyle.NARROW_STANDALONE)
1461      *
1462      *    w       1      append special localized WeekFields element for numeric week-of-year
1463      *    ww      2      append special localized WeekFields element for numeric week-of-year, zero-padded
1464      *    W       1      append special localized WeekFields element for numeric week-of-month
1465      *    d       1      appendValue(ChronoField.DAY_OF_MONTH)
1466      *    dd      2      appendValue(ChronoField.DAY_OF_MONTH, 2)
1467      *    D       1      appendValue(ChronoField.DAY_OF_YEAR)
1468      *    DD      2      appendValue(ChronoField.DAY_OF_YEAR, 2)
1469      *    DDD     3      appendValue(ChronoField.DAY_OF_YEAR, 3)
1470      *    F       1      appendValue(ChronoField.ALIGNED_DAY_OF_WEEK_IN_MONTH)
1471      *    g..g    1..n   appendValue(JulianFields.MODIFIED_JULIAN_DAY, n, 19, SignStyle.NORMAL)
1472      *    E       1      appendText(ChronoField.DAY_OF_WEEK, TextStyle.SHORT)
1473      *    EE      2      appendText(ChronoField.DAY_OF_WEEK, TextStyle.SHORT)
1474      *    EEE     3      appendText(ChronoField.DAY_OF_WEEK, TextStyle.SHORT)
1475      *    EEEE    4      appendText(ChronoField.DAY_OF_WEEK, TextStyle.FULL)
1476      *    EEEEE   5      appendText(ChronoField.DAY_OF_WEEK, TextStyle.NARROW)
1477      *    e       1      append special localized WeekFields element for numeric day-of-week
1478      *    ee      2      append special localized WeekFields element for numeric day-of-week, zero-padded
1479      *    eee     3      appendText(ChronoField.DAY_OF_WEEK, TextStyle.SHORT)
1480      *    eeee    4      appendText(ChronoField.DAY_OF_WEEK, TextStyle.FULL)
1481      *    eeeee   5      appendText(ChronoField.DAY_OF_WEEK, TextStyle.NARROW)
1482      *    c       1      append special localized WeekFields element for numeric day-of-week
1483      *    ccc     3      appendText(ChronoField.DAY_OF_WEEK, TextStyle.SHORT_STANDALONE)
1484      *    cccc    4      appendText(ChronoField.DAY_OF_WEEK, TextStyle.FULL_STANDALONE)
1485      *    ccccc   5      appendText(ChronoField.DAY_OF_WEEK, TextStyle.NARROW_STANDALONE)
1486      * </pre>
1487      * <p>
1488      * <b>Time fields</b>: Pattern letters to output a time.
1489      * <pre>
1490      *  Pattern  Count  Equivalent builder methods
1491      *  -------  -----  --------------------------


1510      *    n..n    2..n   appendValue(ChronoField.NANO_OF_SECOND, n)
1511      *    N       1      appendValue(ChronoField.NANO_OF_DAY)
1512      *    N..N    2..n   appendValue(ChronoField.NANO_OF_DAY, n)
1513      * </pre>
1514      * <p>
1515      * <b>Zone ID</b>: Pattern letters to output {@code ZoneId}.
1516      * <pre>
1517      *  Pattern  Count  Equivalent builder methods
1518      *  -------  -----  --------------------------
1519      *    VV      2      appendZoneId()
1520      *    z       1      appendZoneText(TextStyle.SHORT)
1521      *    zz      2      appendZoneText(TextStyle.SHORT)
1522      *    zzz     3      appendZoneText(TextStyle.SHORT)
1523      *    zzzz    4      appendZoneText(TextStyle.FULL)
1524      * </pre>
1525      * <p>
1526      * <b>Zone offset</b>: Pattern letters to output {@code ZoneOffset}.
1527      * <pre>
1528      *  Pattern  Count  Equivalent builder methods
1529      *  -------  -----  --------------------------
1530      *    O       1      appendLocalizedOffsetPrefixed(TextStyle.SHORT)
1531      *    OOOO    4      appendLocalizedOffsetPrefixed(TextStyle.FULL)
1532      *    X       1      appendOffset("+HHmm","Z")
1533      *    XX      2      appendOffset("+HHMM","Z")
1534      *    XXX     3      appendOffset("+HH:MM","Z")
1535      *    XXXX    4      appendOffset("+HHMMss","Z")
1536      *    XXXXX   5      appendOffset("+HH:MM:ss","Z")
1537      *    x       1      appendOffset("+HHmm","+00")
1538      *    xx      2      appendOffset("+HHMM","+0000")
1539      *    xxx     3      appendOffset("+HH:MM","+00:00")
1540      *    xxxx    4      appendOffset("+HHMMss","+0000")
1541      *    xxxxx   5      appendOffset("+HH:MM:ss","+00:00")
1542      *    Z       1      appendOffset("+HHMM","+0000")
1543      *    ZZ      2      appendOffset("+HHMM","+0000")
1544      *    ZZZ     3      appendOffset("+HHMM","+0000")
1545      *    ZZZZ    4      appendLocalizedOffset(TextStyle.FULL)
1546      *    ZZZZZ   5      appendOffset("+HH:MM:ss","Z")
1547      * </pre>
1548      * <p>
1549      * <b>Modifiers</b>: Pattern letters that modify the rest of the pattern:
1550      * <pre>
1551      *  Pattern  Count  Equivalent builder methods
1552      *  -------  -----  --------------------------
1553      *    [       1      optionalStart()
1554      *    ]       1      optionalEnd()
1555      *    p..p    1..n   padNext(n)
1556      * </pre>
1557      * <p>
1558      * Any sequence of letters not specified above, unrecognized letter or
1559      * reserved character will throw an exception.
1560      * Future versions may add to the set of patterns.
1561      * It is recommended to use single quotes around all characters that you want
1562      * to output directly to ensure that future changes do not break your application.
1563      * <p>
1564      * Note that the pattern string is similar, but not identical, to
1565      * {@link java.text.SimpleDateFormat SimpleDateFormat}.


1807             case 'K':
1808             case 'm':
1809             case 's':
1810                 if (count == 1) {
1811                     appendValue(field);
1812                 } else if (count == 2) {
1813                     appendValue(field, count);
1814                 } else {
1815                     throw new IllegalArgumentException("Too many pattern letters: " + cur);
1816                 }
1817                 break;
1818             case 'D':
1819                 if (count == 1) {
1820                     appendValue(field);
1821                 } else if (count <= 3) {
1822                     appendValue(field, count);
1823                 } else {
1824                     throw new IllegalArgumentException("Too many pattern letters: " + cur);
1825                 }
1826                 break;
1827             case 'g':
1828                 appendValue(field, count, 19, SignStyle.NORMAL);
1829                 break;
1830             default:
1831                 if (count == 1) {
1832                     appendValue(field);
1833                 } else {
1834                     appendValue(field, count);
1835                 }
1836                 break;
1837         }
1838     }
1839 
1840     /** Map of letters to fields. */
1841     private static final Map<Character, TemporalField> FIELD_MAP = new HashMap<>();
1842     static {
1843         // SDF = SimpleDateFormat
1844         FIELD_MAP.put('G', ChronoField.ERA);                       // SDF, LDML (different to both for 1/2 chars)
1845         FIELD_MAP.put('y', ChronoField.YEAR_OF_ERA);               // SDF, LDML
1846         FIELD_MAP.put('u', ChronoField.YEAR);                      // LDML (different in SDF)
1847         FIELD_MAP.put('Q', IsoFields.QUARTER_OF_YEAR);             // LDML (removed quarter from 310)
1848         FIELD_MAP.put('q', IsoFields.QUARTER_OF_YEAR);             // LDML (stand-alone)
1849         FIELD_MAP.put('M', ChronoField.MONTH_OF_YEAR);             // SDF, LDML
1850         FIELD_MAP.put('L', ChronoField.MONTH_OF_YEAR);             // SDF, LDML (stand-alone)
1851         FIELD_MAP.put('D', ChronoField.DAY_OF_YEAR);               // SDF, LDML
1852         FIELD_MAP.put('d', ChronoField.DAY_OF_MONTH);              // SDF, LDML
1853         FIELD_MAP.put('F', ChronoField.ALIGNED_DAY_OF_WEEK_IN_MONTH);  // SDF, LDML
1854         FIELD_MAP.put('E', ChronoField.DAY_OF_WEEK);               // SDF, LDML (different to both for 1/2 chars)
1855         FIELD_MAP.put('c', ChronoField.DAY_OF_WEEK);               // LDML (stand-alone)
1856         FIELD_MAP.put('e', ChronoField.DAY_OF_WEEK);               // LDML (needs localized week number)
1857         FIELD_MAP.put('a', ChronoField.AMPM_OF_DAY);               // SDF, LDML
1858         FIELD_MAP.put('H', ChronoField.HOUR_OF_DAY);               // SDF, LDML
1859         FIELD_MAP.put('k', ChronoField.CLOCK_HOUR_OF_DAY);         // SDF, LDML
1860         FIELD_MAP.put('K', ChronoField.HOUR_OF_AMPM);              // SDF, LDML
1861         FIELD_MAP.put('h', ChronoField.CLOCK_HOUR_OF_AMPM);        // SDF, LDML
1862         FIELD_MAP.put('m', ChronoField.MINUTE_OF_HOUR);            // SDF, LDML
1863         FIELD_MAP.put('s', ChronoField.SECOND_OF_MINUTE);          // SDF, LDML
1864         FIELD_MAP.put('S', ChronoField.NANO_OF_SECOND);            // LDML (SDF uses milli-of-second number)
1865         FIELD_MAP.put('A', ChronoField.MILLI_OF_DAY);              // LDML
1866         FIELD_MAP.put('n', ChronoField.NANO_OF_SECOND);            // 310 (proposed for LDML)
1867         FIELD_MAP.put('N', ChronoField.NANO_OF_DAY);               // 310 (proposed for LDML)
1868         FIELD_MAP.put('g', JulianFields.MODIFIED_JULIAN_DAY);
1869         // 310 - z - time-zone names, matches LDML and SimpleDateFormat 1 to 4
1870         // 310 - Z - matches SimpleDateFormat and LDML
1871         // 310 - V - time-zone id, matches LDML
1872         // 310 - p - prefix for padding
1873         // 310 - X - matches LDML, almost matches SDF for 1, exact match 2&3, extended 4&5
1874         // 310 - x - matches LDML
1875         // 310 - w, W, and Y are localized forms matching LDML
1876         // LDML - U - cycle year name, not supported by 310 yet
1877         // LDML - l - deprecated
1878         // LDML - j - not relevant

1879         // LDML - v,V - extended time-zone names
1880     }
1881 
1882     //-----------------------------------------------------------------------
1883     /**
1884      * Causes the next added printer/parser to pad to a fixed width using a space.
1885      * <p>
1886      * This padding will pad to a fixed width using spaces.
1887      * <p>
1888      * During formatting, the decorated element will be output and then padded
1889      * to the specified width. An exception will be thrown during formatting if
1890      * the pad width is exceeded.
1891      * <p>
1892      * During parsing, the padding and decorated element are parsed.
1893      * If parsing is lenient, then the pad width is treated as a maximum.
1894      * The padding is parsed greedily. Thus, if the decorated element starts with
1895      * the pad character, it will not be parsed.
1896      *
1897      * @param padWidth  the pad width, 1 or greater
1898      * @return this, for chaining, not null


< prev index next >