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>
153 * <table class="striped">
154 * <caption>Predefined Formatters</caption>
155 * <thead>
156 * <tr>
157 * <th scope="col" style="text-align:left">Formatter</th>
158 * <th scope="col" style="text-align:left">Description</th>
159 * <th scope="col" style="text-align:left">Example</th>
160 * </tr>
161 * </thead>
162 * <tbody>
163 * <tr>
164 * <th scope="row">{@link #ofLocalizedDate ofLocalizedDate(dateStyle)} </th>
165 * <td> Formatter with date style from the locale </td>
166 * <td> '2011-12-03'</td>
167 * </tr>
168 * <tr>
169 * <th scope="row"> {@link #ofLocalizedTime ofLocalizedTime(timeStyle)} </th>
170 * <td> Formatter with time style from the locale </td>
171 * <td> '10:15:30'</td>
172 * </tr>
173 * <tr>
174 * <th scope="row"> {@link #ofLocalizedDateTime ofLocalizedDateTime(dateTimeStyle)} </th>
175 * <td> Formatter with a style for date and time from the locale</td>
176 * <td> '3 Jun 2008 11:05:30'</td>
177 * </tr>
178 * <tr>
179 * <th scope="row"> {@link #ofLocalizedDateTime ofLocalizedDateTime(dateStyle,timeStyle)}
259 *
260 * <h3 id="patterns">Patterns for Formatting and Parsing</h3>
261 * Patterns are based on a simple sequence of letters and symbols.
262 * A pattern is used to create a Formatter using the
263 * {@link #ofPattern(String)} and {@link #ofPattern(String, Locale)} methods.
264 * For example,
265 * {@code "d MMM uuuu"} will format 2011-12-03 as '3 Dec 2011'.
266 * A formatter created from a pattern can be used as many times as necessary,
267 * it is immutable and is thread-safe.
268 * <p>
269 * For example:
270 * <blockquote><pre>
271 * LocalDate date = LocalDate.now();
272 * DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy MM dd");
273 * String text = date.format(formatter);
274 * LocalDate parsedDate = LocalDate.parse(text, formatter);
275 * </pre></blockquote>
276 * <p>
277 * All letters 'A' to 'Z' and 'a' to 'z' are reserved as pattern letters. The
278 * following pattern letters are defined:
279 * <pre>
280 * Symbol Meaning Presentation Examples
281 * ------ ------- ------------ -------
282 * G era text AD; Anno Domini; A
283 * u year year 2004; 04
284 * y year-of-era year 2004; 04
285 * D day-of-year number 189
286 * M/L month-of-year number/text 7; 07; Jul; July; J
287 * d day-of-month number 10
288 * g modified-julian-day number 2451334
289 *
290 * Q/q quarter-of-year number/text 3; 03; Q3; 3rd quarter
291 * Y week-based-year year 1996; 96
292 * w week-of-week-based-year number 27
293 * W week-of-month number 4
294 * E day-of-week text Tue; Tuesday; T
295 * e/c localized day-of-week number/text 2; 02; Tue; Tuesday; T
296 * F day-of-week-in-month number 3
297 *
298 * a am-pm-of-day text PM
299 * h clock-hour-of-am-pm (1-12) number 12
300 * K hour-of-am-pm (0-11) number 0
301 * k clock-hour-of-day (1-24) number 24
302 *
303 * H hour-of-day (0-23) number 0
304 * m minute-of-hour number 30
305 * s second-of-minute number 55
306 * S fraction-of-second fraction 978
307 * A milli-of-day number 1234
308 * n nano-of-second number 987654321
309 * N nano-of-day number 1234000000
310 *
311 * V time-zone ID zone-id America/Los_Angeles; Z; -08:30
312 * v generic time-zone name zone-name Pacific Time; PT
313 * z time-zone name zone-name Pacific Standard Time; PST
314 * O localized zone-offset offset-O GMT+8; GMT+08:00; UTC-08:00
315 * X zone-offset 'Z' for zero offset-X Z; -08; -0830; -08:30; -083015; -08:30:15
316 * x zone-offset offset-x +0000; -08; -0830; -08:30; -083015; -08:30:15
317 * Z zone-offset offset-Z +0000; -0800; -08:00
318 *
319 * p pad next pad modifier 1
320 *
321 * ' escape for text delimiter
322 * '' single quote literal '
323 * [ optional section start
324 * ] optional section end
325 * # reserved for future use
326 * { reserved for future use
327 * } reserved for future use
328 * </pre>
329 * <p>
330 * The count of pattern letters determines the format.
331 * <p>
332 * <b>Text</b>: The text style is determined based on the number of pattern
333 * letters used. Less than 4 pattern letters will use the
334 * {@link TextStyle#SHORT short form}. Exactly 4 pattern letters will use the
335 * {@link TextStyle#FULL full form}. Exactly 5 pattern letters will use the
336 * {@link TextStyle#NARROW narrow form}.
337 * Pattern letters 'L', 'c', and 'q' specify the stand-alone form of the text styles.
338 * <p>
339 * <b>Number</b>: If the count of letters is one, then the value is output using
340 * the minimum number of digits and without padding. Otherwise, the count of digits
341 * is used as the width of the output field, with the value zero-padded as necessary.
342 * The following pattern letters have constraints on the count of letters.
343 * Only one letter of 'c' and 'F' can be specified.
344 * Up to two letters of 'd', 'H', 'h', 'K', 'k', 'm', and 's' can be specified.
345 * Up to three letters of 'D' can be specified.
346 * <p>
347 * <b>Number/Text</b>: If the count of pattern letters is 3 or greater, use the
348 * Text rules above. Otherwise use the Number rules above.
|
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>
153 * <table class="striped" style="text-align:left">
154 * <caption>Predefined Formatters</caption>
155 * <thead>
156 * <tr>
157 * <th scope="col">Formatter</th>
158 * <th scope="col">Description</th>
159 * <th scope="col">Example</th>
160 * </tr>
161 * </thead>
162 * <tbody>
163 * <tr>
164 * <th scope="row">{@link #ofLocalizedDate ofLocalizedDate(dateStyle)} </th>
165 * <td> Formatter with date style from the locale </td>
166 * <td> '2011-12-03'</td>
167 * </tr>
168 * <tr>
169 * <th scope="row"> {@link #ofLocalizedTime ofLocalizedTime(timeStyle)} </th>
170 * <td> Formatter with time style from the locale </td>
171 * <td> '10:15:30'</td>
172 * </tr>
173 * <tr>
174 * <th scope="row"> {@link #ofLocalizedDateTime ofLocalizedDateTime(dateTimeStyle)} </th>
175 * <td> Formatter with a style for date and time from the locale</td>
176 * <td> '3 Jun 2008 11:05:30'</td>
177 * </tr>
178 * <tr>
179 * <th scope="row"> {@link #ofLocalizedDateTime ofLocalizedDateTime(dateStyle,timeStyle)}
259 *
260 * <h3 id="patterns">Patterns for Formatting and Parsing</h3>
261 * Patterns are based on a simple sequence of letters and symbols.
262 * A pattern is used to create a Formatter using the
263 * {@link #ofPattern(String)} and {@link #ofPattern(String, Locale)} methods.
264 * For example,
265 * {@code "d MMM uuuu"} will format 2011-12-03 as '3 Dec 2011'.
266 * A formatter created from a pattern can be used as many times as necessary,
267 * it is immutable and is thread-safe.
268 * <p>
269 * For example:
270 * <blockquote><pre>
271 * LocalDate date = LocalDate.now();
272 * DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy MM dd");
273 * String text = date.format(formatter);
274 * LocalDate parsedDate = LocalDate.parse(text, formatter);
275 * </pre></blockquote>
276 * <p>
277 * All letters 'A' to 'Z' and 'a' to 'z' are reserved as pattern letters. The
278 * following pattern letters are defined:
279 * <table class="striped">
280 * <caption>Pattern Letters and Symbols</caption>
281 * <thead>
282 * <tr><th scope="col">Symbol</th> <th scope="col">Meaning</th> <th scope="col">Presentation</th> <th scope="col">Examples</th>
283 * </thead>
284 * <tbody>
285 * <tr><th scope="row">G</th> <td>era</td> <td>text</td> <td>AD; Anno Domini; A</td>
286 * <tr><th scope="row">u</th> <td>year</td> <td>year</td> <td>2004; 04</td>
287 * <tr><th scope="row">y</th> <td>year-of-era</td> <td>year</td> <td>2004; 04</td>
288 * <tr><th scope="row">D</th> <td>day-of-year</td> <td>number</td> <td>189</td>
289 * <tr><th scope="row">M/L</th> <td>month-of-year</td> <td>number/text</td> <td>7; 07; Jul; July; J</td>
290 * <tr><th scope="row">d</th> <td>day-of-month</td> <td>number</td> <td>10</td>
291 * <tr><th scope="row">g</th> <td>modified-julian-day</td> <td>number</td> <td>2451334</td>
292 *
293 * <tr><th scope="row">Q/q</th> <td>quarter-of-year</td> <td>number/text</td> <td>3; 03; Q3; 3rd quarter</td>
294 * <tr><th scope="row">Y</th> <td>week-based-year</td> <td>year</td> <td>1996; 96</td>
295 * <tr><th scope="row">w</th> <td>week-of-week-based-year</td> <td>number</td> <td>27</td>
296 * <tr><th scope="row">W</th> <td>week-of-month</td> <td>number</td> <td>4</td>
297 * <tr><th scope="row">E</th> <td>day-of-week</td> <td>text</td> <td>Tue; Tuesday; T</td>
298 * <tr><th scope="row">e/c</th> <td>localized day-of-week</td> <td>number/text</td> <td>2; 02; Tue; Tuesday; T</td>
299 * <tr><th scope="row">F</th> <td>day-of-week-in-month</td> <td>number</td> <td>3</td>
300 *
301 * <tr><th scope="row">a</th> <td>am-pm-of-day</td> <td>text</td> <td>PM</td>
302 * <tr><th scope="row">h</th> <td>clock-hour-of-am-pm (1-12)</td> <td>number</td> <td>12</td>
303 * <tr><th scope="row">K</th> <td>hour-of-am-pm (0-11)</td> <td>number</td> <td>0</td>
304 * <tr><th scope="row">k</th> <td>clock-hour-of-day (1-24)</td> <td>number</td> <td>24</td>
305 *
306 * <tr><th scope="row">H</th> <td>hour-of-day (0-23)</td> <td>number</td> <td>0</td>
307 * <tr><th scope="row">m</th> <td>minute-of-hour</td> <td>number</td> <td>30</td>
308 * <tr><th scope="row">s</th> <td>second-of-minute</td> <td>number</td> <td>55</td>
309 * <tr><th scope="row">S</th> <td>fraction-of-second</td> <td>fraction</td> <td>978</td>
310 * <tr><th scope="row">A</th> <td>milli-of-day</td> <td>number</td> <td>1234</td>
311 * <tr><th scope="row">n</th> <td>nano-of-second</td> <td>number</td> <td>987654321</td>
312 * <tr><th scope="row">N</th> <td>nano-of-day</td> <td>number</td> <td>1234000000</td>
313 *
314 * <tr><th scope="row">V</th> <td>time-zone ID</td> <td>zone-id</td> <td>America/Los_Angeles; Z; -08:30</td>
315 * <tr><th scope="row">v</th> <td>generic time-zone name</td> <td>zone-name</td> <td>Pacific Time; PT</td>
316 * <tr><th scope="row">z</th> <td>time-zone name</td> <td>zone-name</td> <td>Pacific Standard Time; PST</td>
317 * <tr><th scope="row">O</th> <td>localized zone-offset</td> <td>offset-O</td> <td>GMT+8; GMT+08:00; UTC-08:00</td>
318 * <tr><th scope="row">X</th> <td>zone-offset 'Z' for zero</td> <td>offset-X</td> <td>Z; -08; -0830; -08:30; -083015; -08:30:15</td>
319 * <tr><th scope="row">x</th> <td>zone-offset</td> <td>offset-x</td> <td>+0000; -08; -0830; -08:30; -083015; -08:30:15</td>
320 * <tr><th scope="row">Z</th> <td>zone-offset</td> <td>offset-Z</td> <td>+0000; -0800; -08:00</td>
321 *
322 * <tr><th scope="row">p</th> <td>pad next</td> <td>pad modifier</td> <td>1</td>
323 *
324 * <tr><th scope="row">'</th> <td>escape for text</td> <td>delimiter</td> <td></td>
325 * <tr><th scope="row">''</th> <td>single quote</td> <td>literal</td> <td>'</td>
326 * <tr><th scope="row">[</th> <td>optional section start</td> <td></td> <td></td>
327 * <tr><th scope="row">]</th> <td>optional section end</td> <td></td> <td></td>
328 * <tr><th scope="row">#</th> <td>reserved for future use</td> <td></td> <td></td>
329 * <tr><th scope="row">{</th> <td>reserved for future use</td> <td></td> <td></td>
330 * <tr><th scope="row">}</th> <td>reserved for future use</td> <td></td> <td></td>
331 * </tbody>
332 * </table>
333 * <p>
334 * The count of pattern letters determines the format.
335 * <p>
336 * <b>Text</b>: The text style is determined based on the number of pattern
337 * letters used. Less than 4 pattern letters will use the
338 * {@link TextStyle#SHORT short form}. Exactly 4 pattern letters will use the
339 * {@link TextStyle#FULL full form}. Exactly 5 pattern letters will use the
340 * {@link TextStyle#NARROW narrow form}.
341 * Pattern letters 'L', 'c', and 'q' specify the stand-alone form of the text styles.
342 * <p>
343 * <b>Number</b>: If the count of letters is one, then the value is output using
344 * the minimum number of digits and without padding. Otherwise, the count of digits
345 * is used as the width of the output field, with the value zero-padded as necessary.
346 * The following pattern letters have constraints on the count of letters.
347 * Only one letter of 'c' and 'F' can be specified.
348 * Up to two letters of 'd', 'H', 'h', 'K', 'k', 'm', and 's' can be specified.
349 * Up to three letters of 'D' can be specified.
350 * <p>
351 * <b>Number/Text</b>: If the count of pattern letters is 3 or greater, use the
352 * Text rules above. Otherwise use the Number rules above.
|