public final class DateTimeFormatter extends Object
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.
Not all formatters can print and parse. Some can only print, while others can only parse.
The isPrintSupported()
and isParseSupported()
methods determine
which operations are available.
Some applications may need to use the older Format
class for formatting.
The toFormat()
method returns an implementation of the old API.
DateTimeFormatter is immutable and thread-safe.
Modifier and Type | Method and Description |
---|---|
Locale |
getLocale()
Gets the locale to be used during formatting.
|
boolean |
isParseSupported()
Checks whether this formatter can parse.
|
boolean |
isPrintSupported()
Checks whether this formatter can print.
|
CalendricalMerger |
parse(String text)
Fully parses the text returning a merger that can be used to manage the
merging of separate parsed fields to a meaningful calendrical.
|
<T> T |
parse(String text,
CalendricalRule<T> rule)
Fully parses the text producing an object of the type defined by the rule.
|
DateTimeParseContext |
parse(String text,
ParsePosition position)
Parses the text into a Calendrical.
|
String |
print(Calendrical calendrical)
Prints the calendrical using this formatter.
|
void |
print(Calendrical calendrical,
Appendable appendable)
Prints the calendrical to an Appendable using this formatter.
|
Format |
toFormat()
Returns this formatter as a
java.text.Format instance. |
String |
toString()
Returns a description of the underlying formatters.
|
DateTimeFormatter |
withLocale(Locale locale)
Returns a copy of this DateTimeFormatter with a new locale.
|
public Locale getLocale()
public DateTimeFormatter withLocale(Locale locale)
This instance is immutable and unaffected by this method call.
locale
- the new locale, not nullpublic boolean isPrintSupported()
Depending on how this formatter is initialized, it may not be possible for it to print at all. This method allows the caller to check whether the print methods will throw UnsupportedOperationException or not.
public String print(Calendrical calendrical)
This method prints the calendrical to a String.
calendrical
- the calendrical to print, not nullUnsupportedOperationException
- if this formatter cannot printNullPointerException
- if the calendrical is nullCalendricalPrintException
- if an error occurs during printingpublic void print(Calendrical calendrical, Appendable appendable)
This method prints the calendrical to the specified Appendable. 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 CalendricalPrintException.rethrowIOException()
for a means
to extract the IOException.
calendrical
- the calendrical to print, not nullappendable
- the appendable to print to, not nullUnsupportedOperationException
- if this formatter cannot printNullPointerException
- if the calendrical or appendable is nullCalendricalPrintException
- if an error occurs during printingpublic boolean isParseSupported()
Depending on how this formatter is initialized, it may not be possible for it to parse at all. This method allows the caller to check whether the parse methods will throw UnsupportedOperationException or not.
public <T> T parse(String text, CalendricalRule<T> rule)
This parses the entire text to produce the required calendrical value. For example:
LocalDateTime dt = parser.parse(str, LocalDateTime.rule());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.
text
- the text to parse, not nullUnsupportedOperationException
- if this formatter cannot parseNullPointerException
- if the text is nullCalendricalParseException
- if the parse failspublic CalendricalMerger parse(String text)
If the parse completes without reading the entire length of the text, or a problem occurs during parsing, then an exception is thrown.
The result may be invalid including out of range values such as a month of 65. The methods on the calendrical allow you to handle the invalid input. For example:
LocalDateTime dt = parser.parse(str).merge().get(LocalDateTime.rule());
text
- the text to parse, not nullUnsupportedOperationException
- if this formatter cannot parseNullPointerException
- if the text is nullCalendricalParseException
- if the parse failspublic DateTimeParseContext parse(String text, ParsePosition position)
The result may be invalid including out of range values such as a month of 65. The methods on the calendrical allow you to handle the invalid input. For example:
LocalDateTime dt = parser.parse(str).mergeStrict().toLocalDateTime();
text
- the text to parse, not nullposition
- the position to parse from, updated with length parsed
and the index of any error, not nullUnsupportedOperationException
- if this formatter cannot parseNullPointerException
- if the text or position is nullIndexOutOfBoundsException
- if the position is invalidpublic Format toFormat()
java.text.Format
instance.
The Format
instance will print any Calendrical
and parses to a merged CalendricalMerger
.
The format will throw UnsupportedOperationException
and
IndexOutOfBoundsException
in line with those thrown by the
print
and
parse
methods.
The format does not support attributing of the returned format string.
Copyright © 2014. All rights reserved.