Class DateTimeFormatter
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.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescription(package private) class
Implements the classic Java Format API. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final CompositePrinterParser
The printer and/or parser to use, not null.private final DateTimeFormatSymbols
The symbols to use for formatting, not null. -
Constructor Summary
ConstructorsModifierConstructorDescription(package private)
DateTimeFormatter
(Locale locale, CompositePrinterParser printerParser) Constructor.private
DateTimeFormatter
(DateTimeFormatSymbols symbols, CompositePrinterParser printerParser) Constructor used by immutable copying. -
Method Summary
Modifier and TypeMethodDescription(package private) static void
checkNotNull
(Object object, String errorMessage) Validates that the input value is not null.Gets the locale to be used during formatting.boolean
Checks whether this formatter can parse.boolean
Checks whether this formatter can print.Fully parses the text returning a merger that can be used to manage the merging of separate parsed fields to a meaningful calendrical.parse
(String text, ParsePosition position) Parses the text into a Calendrical.<T> T
parse
(String text, CalendricalRule<T> rule) Fully parses the text producing an object of the type defined by the rule.print
(Calendrical calendrical) Prints the calendrical using this formatter.void
print
(Calendrical calendrical, Appendable appendable) Prints the calendrical to an Appendable using this formatter.toFormat()
Returns this formatter as ajava.text.Format
instance.(package private) CompositePrinterParser
toPrinterParser
(boolean optional) Returns the formatter as a composite printer parser.toString()
Returns a description of the underlying formatters.withLocale
(Locale locale) Returns a copy of this DateTimeFormatter with a new locale.
-
Field Details
-
symbols
The symbols to use for formatting, not null. -
printerParser
The printer and/or parser to use, not null.
-
-
Constructor Details
-
DateTimeFormatter
DateTimeFormatter(Locale locale, CompositePrinterParser printerParser) Constructor.- Parameters:
locale
- the locale to use for text formatting, not nullprinterParser
- the printer/parser to use, not null
-
DateTimeFormatter
Constructor used by immutable copying.- Parameters:
symbols
- the symbols to use for text formatting, not nullasciiNumerics
- whether to use ASCII numerics (true) or locale numerics (false)printerParser
- the printer/parser to use, not null
-
-
Method Details
-
checkNotNull
Validates that the input value is not null.- Parameters:
object
- the object to checkerrorMessage
- the error to throw- Throws:
NullPointerException
- if the object is null
-
getLocale
Gets the locale to be used during formatting.- Returns:
- the locale of this DateTimeFormatter, never null
-
withLocale
Returns a copy of this DateTimeFormatter with a new locale.This instance is immutable and unaffected by this method call.
- Parameters:
locale
- the new locale, not null- Returns:
- a new DateTimeFormatter with the same format and the new locale, never null
-
isPrintSupported
public boolean isPrintSupported()Checks whether this formatter can print.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.
- Returns:
- true if the formatter supports printing
-
print
Prints the calendrical using this formatter.This method prints the calendrical to a String.
- Parameters:
calendrical
- the calendrical to print, not null- Returns:
- the printed string, never null
- Throws:
UnsupportedOperationException
- if this formatter cannot printNullPointerException
- if the calendrical is nullCalendricalPrintException
- if an error occurs during printing
-
print
Prints the calendrical to an Appendable using this formatter.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.- Parameters:
calendrical
- the calendrical to print, not nullappendable
- the appendable to print to, not null- Throws:
UnsupportedOperationException
- if this formatter cannot printNullPointerException
- if the calendrical or appendable is nullCalendricalPrintException
- if an error occurs during printing
-
isParseSupported
public boolean isParseSupported()Checks whether this formatter can parse.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.
- Returns:
- true if the formatter supports parsing
-
parse
Fully parses the text producing an object of the type defined by the 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.- Parameters:
text
- the text to parse, not null- Returns:
- the parsed date, never null
- Throws:
UnsupportedOperationException
- if this formatter cannot parseNullPointerException
- if the text is nullCalendricalParseException
- if the parse fails
-
parse
Fully parses the text returning a merger that can be used to manage the merging of separate parsed fields to a meaningful calendrical.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());
- Parameters:
text
- the text to parse, not null- Returns:
- the parsed text, never null
- Throws:
UnsupportedOperationException
- if this formatter cannot parseNullPointerException
- if the text is nullCalendricalParseException
- if the parse fails
-
parse
Parses the text into a Calendrical.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();
- Parameters:
text
- the text to parse, not nullposition
- 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:
UnsupportedOperationException
- if this formatter cannot parseNullPointerException
- if the text or position is nullIndexOutOfBoundsException
- if the position is invalid
-
toPrinterParser
Returns the formatter as a composite printer parser.- Parameters:
optional
- whether the printer/parser should be optional- Returns:
- the printer/parser, never null
-
toFormat
Returns this formatter as ajava.text.Format
instance.The
Format
instance will print anyCalendrical
and parses to a mergedCalendricalMerger
.The format will throw
UnsupportedOperationException
andIndexOutOfBoundsException
in line with those thrown by theprint
andparse
methods.The format does not support attributing of the returned format string.
- Returns:
- this formatter as a classic format instance, never null
-
toString
Returns a description of the underlying formatters.
-