< prev index next >

src/java.base/share/classes/java/text/SimpleDateFormat.java

Print this page




  75  *
  76  * <h3>Date and Time Patterns</h3>
  77  * <p>
  78  * Date and time formats are specified by <em>date and time pattern</em>
  79  * strings.
  80  * Within date and time pattern strings, unquoted letters from
  81  * <code>'A'</code> to <code>'Z'</code> and from <code>'a'</code> to
  82  * <code>'z'</code> are interpreted as pattern letters representing the
  83  * components of a date or time string.
  84  * Text can be quoted using single quotes (<code>'</code>) to avoid
  85  * interpretation.
  86  * <code>"''"</code> represents a single quote.
  87  * All other characters are not interpreted; they're simply copied into the
  88  * output string during formatting or matched against the input string
  89  * during parsing.
  90  * <p>
  91  * The following pattern letters are defined (all other characters from
  92  * <code>'A'</code> to <code>'Z'</code> and from <code>'a'</code> to
  93  * <code>'z'</code> are reserved):
  94  * <blockquote>
  95  * <table border=0 cellspacing=3 cellpadding=0 summary="Chart shows pattern letters, date/time component, presentation, and examples.">
  96  *     <tr style="background-color: rgb(204, 204, 255);">


  97  *         <th style="text-align:left">Letter
  98  *         <th style="text-align:left">Date or Time Component
  99  *         <th style="text-align:left">Presentation
 100  *         <th style="text-align:left">Examples


 101  *     <tr>
 102  *         <td><code>G</code>
 103  *         <td>Era designator
 104  *         <td><a href="#text">Text</a>
 105  *         <td><code>AD</code>
 106  *     <tr style="background-color: rgb(238, 238, 255);">
 107  *         <td><code>y</code>
 108  *         <td>Year
 109  *         <td><a href="#year">Year</a>
 110  *         <td><code>1996</code>; <code>96</code>
 111  *     <tr>
 112  *         <td><code>Y</code>
 113  *         <td>Week year
 114  *         <td><a href="#year">Year</a>
 115  *         <td><code>2009</code>; <code>09</code>
 116  *     <tr style="background-color: rgb(238, 238, 255);">
 117  *         <td><code>M</code>
 118  *         <td>Month in year (context sensitive)
 119  *         <td><a href="#month">Month</a>
 120  *         <td><code>July</code>; <code>Jul</code>; <code>07</code>
 121  *     <tr>
 122  *         <td><code>L</code>
 123  *         <td>Month in year (standalone form)
 124  *         <td><a href="#month">Month</a>
 125  *         <td><code>July</code>; <code>Jul</code>; <code>07</code>
 126  *     <tr style="background-color: rgb(238, 238, 255);">
 127  *         <td><code>w</code>
 128  *         <td>Week in year
 129  *         <td><a href="#number">Number</a>
 130  *         <td><code>27</code>
 131  *     <tr>
 132  *         <td><code>W</code>
 133  *         <td>Week in month
 134  *         <td><a href="#number">Number</a>
 135  *         <td><code>2</code>
 136  *     <tr style="background-color: rgb(238, 238, 255);">
 137  *         <td><code>D</code>
 138  *         <td>Day in year
 139  *         <td><a href="#number">Number</a>
 140  *         <td><code>189</code>
 141  *     <tr>
 142  *         <td><code>d</code>
 143  *         <td>Day in month
 144  *         <td><a href="#number">Number</a>
 145  *         <td><code>10</code>
 146  *     <tr style="background-color: rgb(238, 238, 255);">
 147  *         <td><code>F</code>
 148  *         <td>Day of week in month
 149  *         <td><a href="#number">Number</a>
 150  *         <td><code>2</code>
 151  *     <tr>
 152  *         <td><code>E</code>
 153  *         <td>Day name in week
 154  *         <td><a href="#text">Text</a>
 155  *         <td><code>Tuesday</code>; <code>Tue</code>
 156  *     <tr style="background-color: rgb(238, 238, 255);">
 157  *         <td><code>u</code>
 158  *         <td>Day number of week (1 = Monday, ..., 7 = Sunday)
 159  *         <td><a href="#number">Number</a>
 160  *         <td><code>1</code>
 161  *     <tr>
 162  *         <td><code>a</code>
 163  *         <td>Am/pm marker
 164  *         <td><a href="#text">Text</a>
 165  *         <td><code>PM</code>
 166  *     <tr style="background-color: rgb(238, 238, 255);">
 167  *         <td><code>H</code>
 168  *         <td>Hour in day (0-23)
 169  *         <td><a href="#number">Number</a>
 170  *         <td><code>0</code>
 171  *     <tr>
 172  *         <td><code>k</code>
 173  *         <td>Hour in day (1-24)
 174  *         <td><a href="#number">Number</a>
 175  *         <td><code>24</code>
 176  *     <tr style="background-color: rgb(238, 238, 255);">
 177  *         <td><code>K</code>
 178  *         <td>Hour in am/pm (0-11)
 179  *         <td><a href="#number">Number</a>
 180  *         <td><code>0</code>
 181  *     <tr>
 182  *         <td><code>h</code>
 183  *         <td>Hour in am/pm (1-12)
 184  *         <td><a href="#number">Number</a>
 185  *         <td><code>12</code>
 186  *     <tr style="background-color: rgb(238, 238, 255);">
 187  *         <td><code>m</code>
 188  *         <td>Minute in hour
 189  *         <td><a href="#number">Number</a>
 190  *         <td><code>30</code>
 191  *     <tr>
 192  *         <td><code>s</code>
 193  *         <td>Second in minute
 194  *         <td><a href="#number">Number</a>
 195  *         <td><code>55</code>
 196  *     <tr style="background-color: rgb(238, 238, 255);">
 197  *         <td><code>S</code>
 198  *         <td>Millisecond
 199  *         <td><a href="#number">Number</a>
 200  *         <td><code>978</code>
 201  *     <tr>
 202  *         <td><code>z</code>
 203  *         <td>Time zone
 204  *         <td><a href="#timezone">General time zone</a>
 205  *         <td><code>Pacific Standard Time</code>; <code>PST</code>; <code>GMT-08:00</code>
 206  *     <tr style="background-color: rgb(238, 238, 255);">
 207  *         <td><code>Z</code>
 208  *         <td>Time zone
 209  *         <td><a href="#rfc822timezone">RFC 822 time zone</a>
 210  *         <td><code>-0800</code>
 211  *     <tr>
 212  *         <td><code>X</code>
 213  *         <td>Time zone
 214  *         <td><a href="#iso8601timezone">ISO 8601 time zone</a>
 215  *         <td><code>-08</code>; <code>-0800</code>;  <code>-08:00</code>

 216  * </table>
 217  * </blockquote>
 218  * Pattern letters are usually repeated, as their number determines the
 219  * exact presentation:
 220  * <ul>
 221  * <li><strong><a id="text">Text:</a></strong>
 222  *     For formatting, if the number of pattern letters is 4 or more,
 223  *     the full form is used; otherwise a short or abbreviated form
 224  *     is used if available.
 225  *     For parsing, both forms are accepted, independent of the number
 226  *     of pattern letters.<br><br></li>
 227  * <li><strong><a id="number">Number:</a></strong>
 228  *     For formatting, the number of pattern letters is the minimum
 229  *     number of digits, and shorter numbers are zero-padded to this amount.
 230  *     For parsing, the number of pattern letters is ignored unless
 231  *     it's needed to separate two adjacent fields.<br><br></li>
 232  * <li><strong><a id="year">Year:</a></strong>
 233  *     If the formatter's {@link #getCalendar() Calendar} is the Gregorian
 234  *     calendar, the following rules are applied.<br>
 235  *     <ul>


 353  *     <p>For parsing, {@code "Z"} is parsed as the UTC time zone designator.
 354  *     <a href="#timezone">General time zones</a> are <em>not</em> accepted.
 355  *
 356  *     <p>If the number of pattern letters is 4 or more, {@link
 357  *     IllegalArgumentException} is thrown when constructing a {@code
 358  *     SimpleDateFormat} or {@linkplain #applyPattern(String) applying a
 359  *     pattern}.
 360  * </ul>
 361  * <code>SimpleDateFormat</code> also supports <em>localized date and time
 362  * pattern</em> strings. In these strings, the pattern letters described above
 363  * may be replaced with other, locale dependent, pattern letters.
 364  * <code>SimpleDateFormat</code> does not deal with the localization of text
 365  * other than the pattern letters; that's up to the client of the class.
 366  *
 367  * <h4>Examples</h4>
 368  *
 369  * The following examples show how date and time patterns are interpreted in
 370  * the U.S. locale. The given date and time are 2001-07-04 12:08:56 local time
 371  * in the U.S. Pacific Time time zone.
 372  * <blockquote>
 373  * <table border=0 cellspacing=3 cellpadding=0 summary="Examples of date and time patterns interpreted in the U.S. locale">
 374  *     <tr style="background-color: rgb(204, 204, 255);">


 375  *         <th style="text-align:left">Date and Time Pattern
 376  *         <th style="text-align:left">Result


 377  *     <tr>
 378  *         <td><code>"yyyy.MM.dd G 'at' HH:mm:ss z"</code>
 379  *         <td><code>2001.07.04 AD at 12:08:56 PDT</code>
 380  *     <tr style="background-color: rgb(238, 238, 255);">
 381  *         <td><code>"EEE, MMM d, ''yy"</code>
 382  *         <td><code>Wed, Jul 4, '01</code>
 383  *     <tr>
 384  *         <td><code>"h:mm a"</code>
 385  *         <td><code>12:08 PM</code>
 386  *     <tr style="background-color: rgb(238, 238, 255);">
 387  *         <td><code>"hh 'o''clock' a, zzzz"</code>
 388  *         <td><code>12 o'clock PM, Pacific Daylight Time</code>
 389  *     <tr>
 390  *         <td><code>"K:mm a, z"</code>
 391  *         <td><code>0:08 PM, PDT</code>
 392  *     <tr style="background-color: rgb(238, 238, 255);">
 393  *         <td><code>"yyyyy.MMMMM.dd GGG hh:mm aaa"</code>
 394  *         <td><code>02001.July.04 AD 12:08 PM</code>
 395  *     <tr>
 396  *         <td><code>"EEE, d MMM yyyy HH:mm:ss Z"</code>
 397  *         <td><code>Wed, 4 Jul 2001 12:08:56 -0700</code>
 398  *     <tr style="background-color: rgb(238, 238, 255);">
 399  *         <td><code>"yyMMddHHmmssZ"</code>
 400  *         <td><code>010704120856-0700</code>
 401  *     <tr>
 402  *         <td><code>"yyyy-MM-dd'T'HH:mm:ss.SSSZ"</code>
 403  *         <td><code>2001-07-04T12:08:56.235-0700</code>
 404  *     <tr style="background-color: rgb(238, 238, 255);">
 405  *         <td><code>"yyyy-MM-dd'T'HH:mm:ss.SSSXXX"</code>
 406  *         <td><code>2001-07-04T12:08:56.235-07:00</code>
 407  *     <tr>
 408  *         <td><code>"YYYY-'W'ww-u"</code>
 409  *         <td><code>2001-W27-3</code>

 410  * </table>
 411  * </blockquote>
 412  *
 413  * <h4><a id="synchronization">Synchronization</a></h4>
 414  *
 415  * <p>
 416  * Date formats are not synchronized.
 417  * It is recommended to create separate format instances for each thread.
 418  * If multiple threads access a format concurrently, it must be synchronized
 419  * externally.
 420  *
 421  * @see          <a href="http://docs.oracle.com/javase/tutorial/i18n/format/simpleDateFormat.html">Java Tutorial</a>
 422  * @see          java.util.Calendar
 423  * @see          java.util.TimeZone
 424  * @see          DateFormat
 425  * @see          DateFormatSymbols
 426  * @author       Mark Davis, Chen-Lieh Huang, Alan Liu
 427  */
 428 public class SimpleDateFormat extends DateFormat {
 429 




  75  *
  76  * <h3>Date and Time Patterns</h3>
  77  * <p>
  78  * Date and time formats are specified by <em>date and time pattern</em>
  79  * strings.
  80  * Within date and time pattern strings, unquoted letters from
  81  * <code>'A'</code> to <code>'Z'</code> and from <code>'a'</code> to
  82  * <code>'z'</code> are interpreted as pattern letters representing the
  83  * components of a date or time string.
  84  * Text can be quoted using single quotes (<code>'</code>) to avoid
  85  * interpretation.
  86  * <code>"''"</code> represents a single quote.
  87  * All other characters are not interpreted; they're simply copied into the
  88  * output string during formatting or matched against the input string
  89  * during parsing.
  90  * <p>
  91  * The following pattern letters are defined (all other characters from
  92  * <code>'A'</code> to <code>'Z'</code> and from <code>'a'</code> to
  93  * <code>'z'</code> are reserved):
  94  * <blockquote>
  95  * <table class="striped">
  96  * <caption style="display:none">Chart shows pattern letters, date/time component, presentation, and examples.</caption>
  97  * <thead>
  98  *     <tr>
  99  *         <th style="text-align:left">Letter
 100  *         <th style="text-align:left">Date or Time Component
 101  *         <th style="text-align:left">Presentation
 102  *         <th style="text-align:left">Examples
 103  * </thead>
 104  * <tbody>
 105  *     <tr>
 106  *         <td><code>G</code>
 107  *         <td>Era designator
 108  *         <td><a href="#text">Text</a>
 109  *         <td><code>AD</code>
 110  *     <tr>
 111  *         <td><code>y</code>
 112  *         <td>Year
 113  *         <td><a href="#year">Year</a>
 114  *         <td><code>1996</code>; <code>96</code>
 115  *     <tr>
 116  *         <td><code>Y</code>
 117  *         <td>Week year
 118  *         <td><a href="#year">Year</a>
 119  *         <td><code>2009</code>; <code>09</code>
 120  *     <tr>
 121  *         <td><code>M</code>
 122  *         <td>Month in year (context sensitive)
 123  *         <td><a href="#month">Month</a>
 124  *         <td><code>July</code>; <code>Jul</code>; <code>07</code>
 125  *     <tr>
 126  *         <td><code>L</code>
 127  *         <td>Month in year (standalone form)
 128  *         <td><a href="#month">Month</a>
 129  *         <td><code>July</code>; <code>Jul</code>; <code>07</code>
 130  *     <tr>
 131  *         <td><code>w</code>
 132  *         <td>Week in year
 133  *         <td><a href="#number">Number</a>
 134  *         <td><code>27</code>
 135  *     <tr>
 136  *         <td><code>W</code>
 137  *         <td>Week in month
 138  *         <td><a href="#number">Number</a>
 139  *         <td><code>2</code>
 140  *     <tr>
 141  *         <td><code>D</code>
 142  *         <td>Day in year
 143  *         <td><a href="#number">Number</a>
 144  *         <td><code>189</code>
 145  *     <tr>
 146  *         <td><code>d</code>
 147  *         <td>Day in month
 148  *         <td><a href="#number">Number</a>
 149  *         <td><code>10</code>
 150  *     <tr>
 151  *         <td><code>F</code>
 152  *         <td>Day of week in month
 153  *         <td><a href="#number">Number</a>
 154  *         <td><code>2</code>
 155  *     <tr>
 156  *         <td><code>E</code>
 157  *         <td>Day name in week
 158  *         <td><a href="#text">Text</a>
 159  *         <td><code>Tuesday</code>; <code>Tue</code>
 160  *     <tr>
 161  *         <td><code>u</code>
 162  *         <td>Day number of week (1 = Monday, ..., 7 = Sunday)
 163  *         <td><a href="#number">Number</a>
 164  *         <td><code>1</code>
 165  *     <tr>
 166  *         <td><code>a</code>
 167  *         <td>Am/pm marker
 168  *         <td><a href="#text">Text</a>
 169  *         <td><code>PM</code>
 170  *     <tr>
 171  *         <td><code>H</code>
 172  *         <td>Hour in day (0-23)
 173  *         <td><a href="#number">Number</a>
 174  *         <td><code>0</code>
 175  *     <tr>
 176  *         <td><code>k</code>
 177  *         <td>Hour in day (1-24)
 178  *         <td><a href="#number">Number</a>
 179  *         <td><code>24</code>
 180  *     <tr>
 181  *         <td><code>K</code>
 182  *         <td>Hour in am/pm (0-11)
 183  *         <td><a href="#number">Number</a>
 184  *         <td><code>0</code>
 185  *     <tr>
 186  *         <td><code>h</code>
 187  *         <td>Hour in am/pm (1-12)
 188  *         <td><a href="#number">Number</a>
 189  *         <td><code>12</code>
 190  *     <tr>
 191  *         <td><code>m</code>
 192  *         <td>Minute in hour
 193  *         <td><a href="#number">Number</a>
 194  *         <td><code>30</code>
 195  *     <tr>
 196  *         <td><code>s</code>
 197  *         <td>Second in minute
 198  *         <td><a href="#number">Number</a>
 199  *         <td><code>55</code>
 200  *     <tr>
 201  *         <td><code>S</code>
 202  *         <td>Millisecond
 203  *         <td><a href="#number">Number</a>
 204  *         <td><code>978</code>
 205  *     <tr>
 206  *         <td><code>z</code>
 207  *         <td>Time zone
 208  *         <td><a href="#timezone">General time zone</a>
 209  *         <td><code>Pacific Standard Time</code>; <code>PST</code>; <code>GMT-08:00</code>
 210  *     <tr>
 211  *         <td><code>Z</code>
 212  *         <td>Time zone
 213  *         <td><a href="#rfc822timezone">RFC 822 time zone</a>
 214  *         <td><code>-0800</code>
 215  *     <tr>
 216  *         <td><code>X</code>
 217  *         <td>Time zone
 218  *         <td><a href="#iso8601timezone">ISO 8601 time zone</a>
 219  *         <td><code>-08</code>; <code>-0800</code>;  <code>-08:00</code>
 220  * </tbody>
 221  * </table>
 222  * </blockquote>
 223  * Pattern letters are usually repeated, as their number determines the
 224  * exact presentation:
 225  * <ul>
 226  * <li><strong><a id="text">Text:</a></strong>
 227  *     For formatting, if the number of pattern letters is 4 or more,
 228  *     the full form is used; otherwise a short or abbreviated form
 229  *     is used if available.
 230  *     For parsing, both forms are accepted, independent of the number
 231  *     of pattern letters.<br><br></li>
 232  * <li><strong><a id="number">Number:</a></strong>
 233  *     For formatting, the number of pattern letters is the minimum
 234  *     number of digits, and shorter numbers are zero-padded to this amount.
 235  *     For parsing, the number of pattern letters is ignored unless
 236  *     it's needed to separate two adjacent fields.<br><br></li>
 237  * <li><strong><a id="year">Year:</a></strong>
 238  *     If the formatter's {@link #getCalendar() Calendar} is the Gregorian
 239  *     calendar, the following rules are applied.<br>
 240  *     <ul>


 358  *     <p>For parsing, {@code "Z"} is parsed as the UTC time zone designator.
 359  *     <a href="#timezone">General time zones</a> are <em>not</em> accepted.
 360  *
 361  *     <p>If the number of pattern letters is 4 or more, {@link
 362  *     IllegalArgumentException} is thrown when constructing a {@code
 363  *     SimpleDateFormat} or {@linkplain #applyPattern(String) applying a
 364  *     pattern}.
 365  * </ul>
 366  * <code>SimpleDateFormat</code> also supports <em>localized date and time
 367  * pattern</em> strings. In these strings, the pattern letters described above
 368  * may be replaced with other, locale dependent, pattern letters.
 369  * <code>SimpleDateFormat</code> does not deal with the localization of text
 370  * other than the pattern letters; that's up to the client of the class.
 371  *
 372  * <h4>Examples</h4>
 373  *
 374  * The following examples show how date and time patterns are interpreted in
 375  * the U.S. locale. The given date and time are 2001-07-04 12:08:56 local time
 376  * in the U.S. Pacific Time time zone.
 377  * <blockquote>
 378  * <table class="striped">
 379  * <caption style="display:none">Examples of date and time patterns interpreted in the U.S. locale</caption>
 380  * <thead>
 381  *     <tr>
 382  *         <th style="text-align:left">Date and Time Pattern
 383  *         <th style="text-align:left">Result
 384  * </thead>
 385  * <tbody>
 386  *     <tr>
 387  *         <td><code>"yyyy.MM.dd G 'at' HH:mm:ss z"</code>
 388  *         <td><code>2001.07.04 AD at 12:08:56 PDT</code>
 389  *     <tr>
 390  *         <td><code>"EEE, MMM d, ''yy"</code>
 391  *         <td><code>Wed, Jul 4, '01</code>
 392  *     <tr>
 393  *         <td><code>"h:mm a"</code>
 394  *         <td><code>12:08 PM</code>
 395  *     <tr>
 396  *         <td><code>"hh 'o''clock' a, zzzz"</code>
 397  *         <td><code>12 o'clock PM, Pacific Daylight Time</code>
 398  *     <tr>
 399  *         <td><code>"K:mm a, z"</code>
 400  *         <td><code>0:08 PM, PDT</code>
 401  *     <tr>
 402  *         <td><code>"yyyyy.MMMMM.dd GGG hh:mm aaa"</code>
 403  *         <td><code>02001.July.04 AD 12:08 PM</code>
 404  *     <tr>
 405  *         <td><code>"EEE, d MMM yyyy HH:mm:ss Z"</code>
 406  *         <td><code>Wed, 4 Jul 2001 12:08:56 -0700</code>
 407  *     <tr>
 408  *         <td><code>"yyMMddHHmmssZ"</code>
 409  *         <td><code>010704120856-0700</code>
 410  *     <tr>
 411  *         <td><code>"yyyy-MM-dd'T'HH:mm:ss.SSSZ"</code>
 412  *         <td><code>2001-07-04T12:08:56.235-0700</code>
 413  *     <tr>
 414  *         <td><code>"yyyy-MM-dd'T'HH:mm:ss.SSSXXX"</code>
 415  *         <td><code>2001-07-04T12:08:56.235-07:00</code>
 416  *     <tr>
 417  *         <td><code>"YYYY-'W'ww-u"</code>
 418  *         <td><code>2001-W27-3</code>
 419  * </tbody>
 420  * </table>
 421  * </blockquote>
 422  *
 423  * <h4><a id="synchronization">Synchronization</a></h4>
 424  *
 425  * <p>
 426  * Date formats are not synchronized.
 427  * It is recommended to create separate format instances for each thread.
 428  * If multiple threads access a format concurrently, it must be synchronized
 429  * externally.
 430  *
 431  * @see          <a href="http://docs.oracle.com/javase/tutorial/i18n/format/simpleDateFormat.html">Java Tutorial</a>
 432  * @see          java.util.Calendar
 433  * @see          java.util.TimeZone
 434  * @see          DateFormat
 435  * @see          DateFormatSymbols
 436  * @author       Mark Davis, Chen-Lieh Huang, Alan Liu
 437  */
 438 public class SimpleDateFormat extends DateFormat {
 439 


< prev index next >