DateTimeFormatter (ThreeTen backport 0.7.2 API)

java.lang.Object
- org.threeten.bp.format.DateTimeFormatter

```
public final class DateTimeFormatter
extends Object
```
Formatter for printing and parsing date-time objects.
This class provides the main application entry point for printing and parsing. Common instances of DateTimeFormatter are provided by DateTimeFormatters. For more complex formatters, a builder is provided.
In most cases, it is not necessary to use this class directly when formatting. The main date-time classes provide two methods - one for printing, toString(DateTimeFormatter formatter), and one for parsing, parse(CharSequence text, DateTimeFormatter formatter). For example:
```
  String text = date.toString(formatter);
  LocalDate date = LocalDate.parse(text, formatter);
 
```
Some aspects of printing and parsing are dependent on the locale. The locale can be changed using the withLocale(Locale) method which returns a new formatter in the requested locale.
Some applications may need to use the older Format class for formatting. The toFormat() method returns an implementation of the old API.
Specification for implementors
This class is immutable and thread-safe.

Method Summary

Methods
Modifier and Type	Method and Description
`Chrono<?>`	`getChrono()` Gets the overriding chronology to be used during formatting.
`Locale`	`getLocale()` Gets the locale to be used during formatting.
`DateTimeFormatSymbols`	`getSymbols()` Gets the set of symbols to be used during formatting.
`ZoneId`	`getZone()` Gets the overriding zone to be used during formatting.
`<T> T`	`parse(CharSequence text, Class<T> type)` Fully parses the text producing an object of the specified type.
`TemporalAccessor`	`parseBest(CharSequence text, Class<?>... types)` Fully parses the text producing an object of one of the specified types.
`DateTimeBuilder`	`parseToBuilder(CharSequence text)` Parses the text to a builder.
`DateTimeBuilder`	`parseToBuilder(CharSequence text, ParsePosition position)` Parses the text to a builder.
`String`	`print(TemporalAccessor temporal)` Prints a date-time object using this formatter.
`void`	`printTo(TemporalAccessor temporal, Appendable appendable)` Prints a date-time object to an `Appendable` using this formatter.
`Format`	`toFormat()` Returns this formatter as a `java.text.Format` instance.
`Format`	`toFormat(Class<?> parseType)` Returns this formatter as a `java.text.Format` instance that will parse to the specified type.
`String`	`toString()` Returns a description of the underlying formatters.
`DateTimeFormatter`	`withChrono(Chrono<?> chrono)` Returns a copy of this formatter with a new override chronology.
`DateTimeFormatter`	`withLocale(Locale locale)` Returns a copy of this formatter with a new locale.
`DateTimeFormatter`	`withSymbols(DateTimeFormatSymbols symbols)` Returns a copy of this formatter with a new set of symbols.
`DateTimeFormatter`	`withZone(ZoneId zone)` Returns a copy of this formatter with a new override zone.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Method Detail
  - getLocale
```
public Locale getLocale()
```
    Gets the locale to be used during formatting.
    This is used to lookup any part of the formatter needing specific localization, such as the text or localized pattern.
    
    Returns:
    the locale of this formatter, not null
  - withLocale
```
public DateTimeFormatter withLocale(Locale locale)
```
    Returns a copy of this formatter with a new locale.
    This is used to lookup any part of the formatter needing specific localization, such as the text or localized pattern.
    This instance is immutable and unaffected by this method call.
    
    Parameters:
    locale - the new locale, not null
    
    Returns:
    a formatter based on this formatter with the requested locale, not null
  - getSymbols
```
public DateTimeFormatSymbols getSymbols()
```
    Gets the set of symbols to be used during formatting.
    
    Returns:
    the locale of this formatter, not null
  - withSymbols
```
public DateTimeFormatter withSymbols(DateTimeFormatSymbols symbols)
```
    Returns a copy of this formatter with a new set of symbols.
    This instance is immutable and unaffected by this method call.
    
    Parameters:
    symbols - the new symbols, not null
    
    Returns:
    a formatter based on this formatter with the requested symbols, not null
  - getChrono
```
public Chrono<?> getChrono()
```
    Gets the overriding chronology to be used during formatting.
    This returns the override chronology, used to convert dates. By default, a formatter has no override chronology, returning null. See withChrono(Chrono) for more details on overriding.
    
    Returns:
    the chronology of this formatter, null if no override
  - withChrono
```
public DateTimeFormatter withChrono(Chrono<?> chrono)
```
    Returns a copy of this formatter with a new override chronology.
    This returns a formatter with similar state to this formatter but with the override chronology set. By default, a formatter has no override chronology, returning null.
    If an override is added, then any date that is printed or parsed will be affected.
    When printing, if the Temporal object contains a date then it will be converted to a date in the override chronology. Any time or zone will be retained unless overridden. The converted result will behave in a manner equivalent to an implementation of ChronoLocalDate,ChronoLocalDateTime or ChronoZonedDateTime.
    When parsing, the override chronology will be used to interpret the fields into a date unless the formatter directly parses a valid chronology.
    This instance is immutable and unaffected by this method call.
    
    Parameters:
    chrono - the new chronology, not null
    
    Returns:
    a formatter based on this formatter with the requested override chronology, not null
  - getZone
```
public ZoneId getZone()
```
    Gets the overriding zone to be used during formatting.
    This returns the override zone, used to convert instants. By default, a formatter has no override zone, returning null. See withZone(ZoneId) for more details on overriding.
    
    Returns:
    the chronology of this formatter, null if no override
  - withZone
```
public DateTimeFormatter withZone(ZoneId zone)
```
    Returns a copy of this formatter with a new override zone.
    This returns a formatter with similar state to this formatter but with the override zone set. By default, a formatter has no override zone, returning null.
    If an override is added, then any instant that is printed or parsed will be affected.
    When printing, if the Temporal object contains an instant then it will be converted to a zoned date-time using the override zone. If the input has a chronology then it will be retained unless overridden. If the input does not have a chronology, such as Instant, then the ISO chronology will be used. The converted result will behave in a manner equivalent to an implementation of ChronoZonedDateTime.
    When parsing, the override zone will be used to interpret the fields into an instant unless the formatter directly parses a valid zone.
    This instance is immutable and unaffected by this method call.
    
    Parameters:
    zone - the new override zone, not null
    
    Returns:
    a formatter based on this formatter with the requested override zone, not null
  - print
```
public String print(TemporalAccessor temporal)
```
    Prints a date-time object using this formatter.
    This prints the date-time to a String using the rules of the formatter.
    
    Parameters:
    temporal - the temporal object to print, not null
    
    Returns:
    the printed string, not null
    
    Throws:
    
    DateTimeException - if an error occurs during printing
  - printTo
```
public void printTo(TemporalAccessor temporal,
           Appendable appendable)
```
    Prints a date-time object to an Appendable using this formatter.
    This prints the date-time to the specified destination. Appendable is a general purpose interface that is implemented by all key character output classes including StringBuffer, StringBuilder, PrintStream and Writer.
    Although Appendable methods throw an IOException, this method does not. Instead, any IOException is wrapped in a runtime exception. See DateTimePrintException.rethrowIOException() for a means to extract the IOException.
    
    Parameters:
    temporal - the temporal object to print, not null
    appendable - the appendable to print to, not null
    
    Throws:
    
    DateTimeException - if an error occurs during printing
  - parse
```
public <T> T parse(CharSequence text,
          Class<T> type)
```
    Fully parses the text producing an object of the specified type.
    Most applications should use this method for parsing. It parses the entire text to produce the required date-time. For example:
```
  LocalDateTime dt = parser.parse(str, LocalDateTime.class);
 
```
    If the parse completes without reading the entire length of the text, or a problem occurs during parsing or merging, then an exception is thrown.
    Type Parameters:
    T - the type to extract
    Parameters:
    text - the text to parse, not null
    type - the type to extract, not null
    
    Returns:
    the parsed date-time, not null
    
    Throws:
    
    DateTimeParseException - if the parse fails
  - parseBest
```
public TemporalAccessor parseBest(CharSequence text,
                         Class<?>... types)
```
    Fully parses the text producing an object of one of the specified types.
    This parse method is convenient for use when the parser can handle optional elements. For example, a pattern of 'yyyy-MM[-dd[Z]]' can be fully parsed to an OffsetDate, or partially parsed to a LocalDate or a YearMonth. The types must be specified in order, starting from the best matching full-parse option and ending with the worst matching minimal parse option.
    The result is associated with the first type that successfully parses. Normally, applications will use instanceof to check the result. For example:
```
  TemporalAccessor dt = parser.parseBest(str, OffsetDate.class, LocalDate.class);
  if (dt instanceof OffsetDate) {
   ...
  } else {
   ...
  }
 
```
    If the parse completes without reading the entire length of the text, or a problem occurs during parsing or merging, then an exception is thrown.
    Parameters:
    text - the text to parse, not null
    types - the types to attempt to parse to, which must implement TemporalAccessor, not null
    
    Returns:
    the parsed date-time, not null
    
    Throws:
    
    IllegalArgumentException - if less than 2 types are specified
    
    DateTimeParseException - if the parse fails
  - parseToBuilder
```
public DateTimeBuilder parseToBuilder(CharSequence text)
```
    Parses the text to a builder.
    This parses to a DateTimeBuilder ensuring that the text is fully parsed. This method throws DateTimeParseException if unable to parse, or some other DateTimeException if another date/time problem occurs.
    
    Parameters:
    text - the text to parse, not null
    
    Returns:
    the engine representing the result of the parse, not null
    
    Throws:
    
    DateTimeParseException - if the parse fails
  - parseToBuilder
```
public DateTimeBuilder parseToBuilder(CharSequence text,
                             ParsePosition position)
```
    Parses the text to a builder.
    This parses to a DateTimeBuilder but does not require the input to be fully parsed.
    This method does not throw DateTimeParseException. Instead, errors are returned within the state of the specified parse position. Callers must check for errors before using the context.
    This method may throw some other DateTimeException if a date/time problem occurs.
    
    Parameters:
    text - the text to parse, not null
    position - the position to parse from, updated with length parsed and the index of any error, not null
    
    Returns:
    the parsed text, null only if the parse results in an error
    
    Throws:
    
    IndexOutOfBoundsException - if the position is invalid
  - toFormat
```
public Format toFormat()
```
    Returns this formatter as a java.text.Format instance.
    The returned Format instance will print any TemporalAccessor and parses to a resolved DateTimeBuilder.
    Exceptions will follow the definitions of Format, see those methods for details about IllegalArgumentException during formatting and ParseException or null during parsing. The format does not support attributing of the returned format string.
    
    Returns:
    this formatter as a classic format instance, not null
  - toFormat
```
public Format toFormat(Class<?> parseType)
```
    Returns this formatter as a java.text.Format instance that will parse to the specified type.
    The returned Format instance will print any TemporalAccessor and parses to the type specified. The type must be one that is supported by parse(java.lang.CharSequence, java.lang.Class<T>).
    Exceptions will follow the definitions of Format, see those methods for details about IllegalArgumentException during formatting and ParseException or null during parsing. The format does not support attributing of the returned format string.
    
    Parameters:
    parseType - the type to parse to, not null
    
    Returns:
    this formatter as a classic format instance, not null
  - toString
```
public String toString()
```
    Returns a description of the underlying formatters.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    a description of this formatter, not null

Class DateTimeFormatter

Specification for implementors

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getLocale

withLocale

getSymbols

withSymbols

getChrono

withChrono

getZone

withZone

print

printTo

parse

parseBest

parseToBuilder

parseToBuilder

toFormat

toFormat

toString