DateTimeFormatter (ThreeTen Date and Time API)

java.lang.Object
- javax.time.format.DateTimeFormatter

```
public final class DateTimeFormatter
extends java.lang.Object
```
Formatter for printing and parsing date-time objects.
This class provides the main application entry point for printing and parsing. Instances of DateTimeFormatter are constructed using DateTimeFormatterBuilder or by using one of the predefined constants on DateTimeFormatters.
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.
Implementation notes
This class is immutable and thread-safe.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`java.util.Locale`	`getLocale()` Gets the locale to be used during formatting.
`DateTimeFormatSymbols`	`getSymbols()` Gets the set of symbols to be used during formatting.
`<T> T`	`parse(java.lang.CharSequence text, java.lang.Class<T> type)` Fully parses the text producing an object of the specified type.
`TemporalAccessor`	`parseBest(java.lang.CharSequence text, java.lang.Class<?>... types)` Fully parses the text producing an object of one of the specified types.
`DateTimeBuilder`	`parseToBuilder(java.lang.CharSequence text)` Parses the text to a builder.
`DateTimeBuilder`	`parseToBuilder(java.lang.CharSequence text, java.text.ParsePosition position)` Parses the text to a builder.
`java.lang.String`	`print(TemporalAccessor temporal)` Prints a date-time object using this formatter.
`void`	`printTo(TemporalAccessor temporal, java.lang.Appendable appendable)` Prints a date-time object to an `Appendable` using this formatter.
`java.text.Format`	`toFormat()` Returns this formatter as a `java.text.Format` instance.
`java.text.Format`	`toFormat(java.lang.Class<?> parseType)` Returns this formatter as a `java.text.Format` instance that will parse to the specified type.
`java.lang.String`	`toString()` Returns a description of the underlying formatters.
`DateTimeFormatter`	`withLocale(java.util.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.

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

- Method Detail
  - getLocale
```
public java.util.Locale getLocale()
```
    Gets the locale to be used during formatting.
    
    Returns:
    the locale of this formatter, not null
  - withLocale
```
public DateTimeFormatter withLocale(java.util.Locale locale)
```
    Returns a copy of this formatter with a new locale.
    This instance is immutable and unaffected by this method call.
    
    Parameters:
    locale - the new locale, not null
    
    Returns:
    a DateTimeFormatter based on this one 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 DateTimeFormatter based on this one with the requested symbols, not null
  - print
```
public java.lang.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,
           java.lang.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(java.lang.CharSequence text,
          java.lang.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(java.lang.CharSequence text,
                         java.lang.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:
    
    java.lang.IllegalArgumentException - if less than 2 types are specified
    
    DateTimeParseException - if the parse fails
  - parseToBuilder
```
public DateTimeBuilder parseToBuilder(java.lang.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(java.lang.CharSequence text,
                             java.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:
    
    java.lang.IndexOutOfBoundsException - if the position is invalid
  - toFormat
```
public java.text.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 java.text.Format toFormat(java.lang.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(CharSequence, Class).
    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
  - toString
```
public java.lang.String toString()
```
    Returns a description of the underlying formatters.
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    the pattern that will be used, not null

Class DateTimeFormatter

Implementation notes

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getLocale

withLocale

getSymbols

withSymbols

print

printTo

parse

parseBest

parseToBuilder

parseToBuilder

toFormat

toFormat

toString