DateTimeFormatter

Companion object DateTimeFormatter

final class DateTimeFormatter extends AnyRef

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:

Using pattern letters, such as yyyy-MMM-dd
Using localized styles, such as long or medium
Using predefined constants, such as #ISO_LOCAL_DATE

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 formatting, format(DateTimeFormatter formatter), and one for parsing, For example:

String text = date.format(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.

Linear Supertypes

AnyRef, Any

Ordering

Alphabetic
By Inheritance

Inherited

DateTimeFormatter
AnyRef
Any

Hide All
Show All

Visibility

Public
All

Value Members

final def !=(arg0: Any): Boolean

Definition Classes
AnyRef → Any
final def ##(): Int

Definition Classes
AnyRef → Any
final def ==(arg0: Any): Boolean

Definition Classes
AnyRef → Any
final def asInstanceOf[T0]: T0

Definition Classes
Any
def clone(): AnyRef

Attributes
protected[java.lang]
Definition Classes
AnyRef
Annotations
@throws( ... )
final def eq(arg0: AnyRef): Boolean

Definition Classes
AnyRef
def equals(arg0: Any): Boolean

Definition Classes
AnyRef → Any
def finalize(): Unit

Attributes
protected[java.lang]
Definition Classes
AnyRef
Annotations
@throws( classOf[java.lang.Throwable] )
def format(temporal: TemporalAccessor): String
Formats a date-time object using this formatter.
Formats a date-time object using this formatter.
This formats the date-time to a String using the rules of the formatter.
temporal
the temporal object to print, not null
returns
the printed string, not null

Exceptions thrown
DateTimeException if an error occurs during formatting
def formatTo(temporal: TemporalAccessor, appendable: Appendable): Unit
Formats a date-time object to an Appendable using this formatter.
Formats a date-time object to an Appendable using this formatter.
This formats 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.
temporal
the temporal object to print, not null
appendable
the appendable to print to, not null

Exceptions thrown
DateTimeException if an error occurs during formatting
def getChronology: Chronology
Gets the overriding chronology to be used during formatting.
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 #withChronology(Chronology) for more details on overriding.
returns
the chronology of this formatter, null if no override
final def getClass(): Class[_]

Definition Classes
AnyRef → Any
def getDecimalStyle: DecimalStyle
Gets the decimal style to be used during formatting.
Gets the decimal style to be used during formatting.
returns
the decimal style of this formatter, not null
def getLocale: Locale
Gets the locale to be used during formatting.
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
def getResolverFields: Set[TemporalField]
Gets the resolver fields to use during parsing.
Gets the resolver fields to use during parsing.
This returns the resolver fields, used during the second phase of parsing when fields are resolved into dates and times. By default, a formatter has no resolver fields, and thus returns null. See #withResolverFields(Set) for more details.
returns
the immutable set of resolver fields of this formatter, null if no fields
def getResolverStyle: ResolverStyle
Gets the resolver style to use during parsing.
Gets the resolver style to use during parsing.
This returns the resolver style, used during the second phase of parsing when fields are resolved into dates and times. By default, a formatter has the SMART resolver style. See #withResolverStyle(ResolverStyle) for more details.
returns
the resolver style of this formatter, not null
def getZone: ZoneId
Gets the overriding zone to be used during formatting.
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
def hashCode(): Int

Definition Classes
AnyRef → Any
final def isInstanceOf[T0]: Boolean

Definition Classes
Any
final def ne(arg0: AnyRef): Boolean

Definition Classes
AnyRef
final def notify(): Unit

Definition Classes
AnyRef
final def notifyAll(): Unit

Definition Classes
AnyRef
def parse[T](text: CharSequence, type: TemporalQuery[T]): T
Fully parses the text producing an object of the specified 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.FROM);
```
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.
T
the type to extract
text
the text to parse, not null
type
the type to extract, not null
returns
the parsed date-time, not null

Exceptions thrown
DateTimeParseException if unable to parse the requested result
def parse(text: CharSequence, position: ParsePosition): TemporalAccessor
Parses the text using this formatter, providing control over the text position.
Parses the text using this formatter, providing control over the text position.
This parses the text without requiring the parse to start from the beginning of the string or finish at the end. The result of this method is TemporalAccessor which has been resolved, applying basic validation checks to help ensure a valid date-time.
The text will be parsed from the specified start ParsePosition. The entire length of the text does not have to be parsed, the ParsePosition will be updated with the index at the end of parsing.
The operation of this method is slightly different to similar methods using ParsePosition on java.text.Format. That class will return errors using the error index on the ParsePosition. By contrast, this method will throw a DateTimeParseException if an error occurs, with the exception containing the error index. This change in behavior is necessary due to the increased complexity of parsing and resolving dates/times in this API.
If the formatter parses the same field more than once with different values, the result will be an error.
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 temporal object, not null

Exceptions thrown
DateTimeParseException if unable to parse the requested result
IndexOutOfBoundsException if the position is invalid
def parse(text: CharSequence): TemporalAccessor
Fully parses the text producing a temporal object.
Fully parses the text producing a temporal object.
This parses the entire text producing a temporal object. It is typically more useful to use TemporalQuery). The result of this method is TemporalAccessor which has been resolved, applying basic validation checks to help ensure a valid date-time.
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 null
returns
the parsed temporal object, not null

Exceptions thrown
DateTimeParseException if unable to parse the requested result
def parseBest(text: CharSequence, types: TemporalQuery[_]*): TemporalAccessor
Fully parses the text producing an object of one of the specified 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]]' can be fully parsed to a LocalDate, or partially parsed to a YearMonth or a Year. 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, LocalDate.FROM, YearMonth.FROM);
if (dt instanceof LocalDate) {
...
} 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.
text
the text to parse, not null
types
the types to attempt to parse to, which must implement { @code TemporalAccessor}, not null
returns
the parsed date-time, not null

Annotations
@varargs()
Exceptions thrown
DateTimeParseException if unable to parse the requested result
IllegalArgumentException if less than 2 types are specified
def parseUnresolved(text: CharSequence, position: ParsePosition): TemporalAccessor
Parses the text using this formatter, without resolving the result, intended for advanced use cases.
Parses the text using this formatter, without resolving the result, intended for advanced use cases.
Parsing is implemented as a two-phase operation. First, the text is parsed using the layout defined by the formatter, producing a Map of field to value, a ZoneId and a Chronology. Second, the parsed data is resolved, by validating, combining and simplifying the various fields into more useful ones. This method performs the parsing stage but not the resolving stage.
The result of this method is TemporalAccessor which represents the data as seen in the input. Values are not validated, thus parsing a date string of '2012-00-65' would result in a temporal with three fields - year of '2012', month of '0' and day-of-month of '65'.
The text will be parsed from the specified start ParsePosition. The entire length of the text does not have to be parsed, the ParsePosition will be updated with the index at the end of parsing.
Errors are returned using the error index field of the ParsePosition instead of DateTimeParseException. The returned error index will be set to an index indicative of the error. Callers must check for errors before using the context.
If the formatter parses the same field more than once with different values, the result will be an error.
This method is intended for advanced use cases that need access to the internal state during parsing. Typical application code should use TemporalQuery) or the parse method on the target type.
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 if the parse results in an error

Exceptions thrown
DateTimeException if some problem occurs during parsing
IndexOutOfBoundsException if the position is invalid
final def synchronized[T0](arg0: ⇒ T0): T0

Definition Classes
AnyRef
def toFormat(query: TemporalQuery[_ <: AnyRef]): Format
Returns this formatter as a java.text.Format instance that will parse to the specified type.
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.
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.
query
the query to parse to, not null
returns
this formatter as a classic format instance, not null
def toFormat: Format
Returns this formatter as a java.text.Format instance.
Returns this formatter as a java.text.Format instance.
The returned Format instance will print any TemporalAccessor and parses to a resolved TemporalAccessor.
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
def toString(): String
Returns a description of the underlying formatters.
Returns a description of the underlying formatters.
returns
a description of this formatter, not null

Definition Classes
DateTimeFormatter → AnyRef → Any
final def wait(): Unit

Definition Classes
AnyRef
Annotations
@throws( ... )
final def wait(arg0: Long, arg1: Int): Unit

Definition Classes
AnyRef
Annotations
@throws( ... )
final def wait(arg0: Long): Unit

Definition Classes
AnyRef
Annotations
@throws( ... )
def withChronology(chrono: Chronology): DateTimeFormatter
Returns a copy of this formatter with a new override chronology.
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.
chrono
the new chronology, not null
returns
a formatter based on this formatter with the requested override chronology, not null
def withDecimalStyle(decimalStyle: DecimalStyle): DateTimeFormatter
Returns a copy of this formatter with a new decimal style.
Returns a copy of this formatter with a new decimal style.
This instance is immutable and unaffected by this method call.
decimalStyle
the new decimal style, not null
returns
a formatter based on this formatter with the requested symbols, not null
def withLocale(locale: Locale): DateTimeFormatter
Returns a copy of this formatter with a new 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.
locale
the new locale, not null
returns
a formatter based on this formatter with the requested locale, not null
def withResolverFields(resolverFields: Set[TemporalField]): DateTimeFormatter
Returns a copy of this formatter with a new set of resolver fields.
Returns a copy of this formatter with a new set of resolver fields.
This returns a formatter with similar state to this formatter but with the resolver fields set. By default, a formatter has no resolver fields.
Changing the resolver fields only has an effect during parsing. Parsing a text string occurs in two phases. Phase 1 is a basic text parse according to the fields added to the builder. Phase 2 resolves the parsed field-value pairs into date and/or time objects. The resolver fields are used to filter the field-value pairs between phase 1 and 2.
This can be used to select between two or more ways that a date or time might be resolved. For example, if the formatter consists of year, month, day-of-month and day-of-year, then there are two ways to resolve a date. Calling this method with the arguments YEAR and DAY_OF_YEAR will ensure that the date is resolved using the year and day-of-year, effectively meaning that the month and day-of-month are ignored during the resolving phase.
In a similar manner, this method can be used to ignore secondary fields that would otherwise be cross-checked. For example, if the formatter consists of year, month, day-of-month and day-of-week, then there is only one way to resolve a date, but the parsed value for day-of-week will be cross-checked against the resolved date. Calling this method with the arguments YEAR, MONTH_OF_YEAR and DAY_OF_MONTH will ensure that the date is resolved correctly, but without any cross-check for the day-of-week.
In implementation terms, this method behaves as follows. The result of the parsing phase can be considered to be a map of field to value. The behavior of this method is to cause that map to be filtered between phase 1 and 2, removing all fields other than those specified as arguments to this method.
This instance is immutable and unaffected by this method call.
resolverFields
the new set of resolver fields, null if no fields
returns
a formatter based on this formatter with the requested resolver style, not null
def withResolverFields(resolverFields: TemporalField*): DateTimeFormatter
Returns a copy of this formatter with a new set of resolver fields.
Returns a copy of this formatter with a new set of resolver fields.
This returns a formatter with similar state to this formatter but with the resolver fields set. By default, a formatter has no resolver fields.
Changing the resolver fields only has an effect during parsing. Parsing a text string occurs in two phases. Phase 1 is a basic text parse according to the fields added to the builder. Phase 2 resolves the parsed field-value pairs into date and/or time objects. The resolver fields are used to filter the field-value pairs between phase 1 and 2.
This can be used to select between two or more ways that a date or time might be resolved. For example, if the formatter consists of year, month, day-of-month and day-of-year, then there are two ways to resolve a date. Calling this method with the arguments YEAR and DAY_OF_YEAR will ensure that the date is resolved using the year and day-of-year, effectively meaning that the month and day-of-month are ignored during the resolving phase.
In a similar manner, this method can be used to ignore secondary fields that would otherwise be cross-checked. For example, if the formatter consists of year, month, day-of-month and day-of-week, then there is only one way to resolve a date, but the parsed value for day-of-week will be cross-checked against the resolved date. Calling this method with the arguments YEAR, MONTH_OF_YEAR and DAY_OF_MONTH will ensure that the date is resolved correctly, but without any cross-check for the day-of-week.
In implementation terms, this method behaves as follows. The result of the parsing phase can be considered to be a map of field to value. The behavior of this method is to cause that map to be filtered between phase 1 and 2, removing all fields other than those specified as arguments to this method.
This instance is immutable and unaffected by this method call.
resolverFields
the new set of resolver fields, null if no fields
returns
a formatter based on this formatter with the requested resolver style, not null
def withResolverStyle(resolverStyle: ResolverStyle): DateTimeFormatter
Returns a copy of this formatter with a new resolver style.
Returns a copy of this formatter with a new resolver style.
This returns a formatter with similar state to this formatter but with the resolver style set. By default, a formatter has the SMART resolver style.
Changing the resolver style only has an effect during parsing. Parsing a text string occurs in two phases. Phase 1 is a basic text parse according to the fields added to the builder. Phase 2 resolves the parsed field-value pairs into date and/or time objects. The resolver style is used to control how phase 2, resolving, happens. See ResolverStyle for more information on the options available.
This instance is immutable and unaffected by this method call.
resolverStyle
the new resolver style, not null
returns
a formatter based on this formatter with the requested resolver style, not null
def withZone(zone: ZoneId): DateTimeFormatter
Returns a copy of this formatter with a new override 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.
zone
the new override zone, not null
returns
a formatter based on this formatter with the requested override zone, not null

Packages

Dates and Times

Duration and Period

Additional value types

DateTimeFormatter

Companion object DateTimeFormatter

final class DateTimeFormatter extends AnyRef

Specification for implementors

Value Members

Inherited from AnyRef

Inherited from Any

Ungrouped

Packages

Dates and Times

Duration and Period

Additional value types

DateTimeFormatter 

Companion object DateTimeFormatter

final class DateTimeFormatter extends AnyRef

Specification for implementors

Value Members

Inherited from AnyRef

Inherited from Any

Ungrouped

DateTimeFormatter