Default Formatters for Date and Time Values – Localization
By Gigi Rosen / March 24, 2022 / No Comments / Creating Resource Bundles, Oracle Certifications
Default Formatters for Date and Time Values
Default formatters rely on the toString() method of the individual temporal classes for creating a text representation of a temporal object. The default formatter used by the toString() method applies the formatting rules defined by the ISO standard.
In the following code, the result of formatting a LocalTime object is shown at (1):
LocalTime time = LocalTime.of(12, 30, 15, 99);
String strTime = time.toString(); // (1) 12:30:15.000000099
LocalTime parsedTime = LocalTime.parse(strTime); // (2)
System.out.println(time.toString().equals(parsedTime.toString())); // true
Each temporal class provides a static method parse(CharSequence text) that parses a character sequence using a default formatter that complies with the ISO standard. In the preceding code, the text representation created at (1) is parsed at (2) to obtain a new LocalTime object. Not surprisingly, the text representations of the two LocalTime objects referred to by the references time and parsedTime are equal.
The line of code below shows that the argument string passed to the parse() method is not in accordance with the ISO standard, resulting in a runtime exception:
LocalTime badTime = LocalTime.parse(“12.30.15”); // DateTimeParseException
The examples in this section make heavy use of the toString() method to format temporal objects according to the ISO standard.
Predefined Formatters for Date and Time Values
The DateTimeFormatter class provides a myriad of predefined formatters for temporal objects, the majority of which comply with the ISO standard. Table 18.11 shows selected ISO-based predefined formatters from this class. We have also indicated in the last column which temporal classes a formatter can be used with for formatting and parsing.
For example, the row for the ISO_LOCAL_DATE formatter in Table 18.11 indicates that this formatter can be used for formatting a LocalDate and for formatting the date part of a LocalDateTime or a ZonedDateTime. It can parse the text representation of a LocalDate. In contrast, the row for the ISO_LOCAL_DATE_TIME formatter indicates that this formatter can be used for formatting a LocalDateTime and for formatting the date-time part of a ZonedDateTime. It can parse the text representation of a Local-DateTime. In addition, the text representation of a LocalDateTime can be parsed by this formatter to a LocalTime or a LocalDate by the parse(text, formatter) method of the appropriate class.
An example of using an ISO-based predefined formatter is given next. Note that the formatter obtained at (1) is a formatter for date fields. It can be used only with temporal objects that have date fields—in other words, the LocalDate, LocalDateTime, and ZonedDateTime classes. This formatter is passed at (2) to the format() method, to create a text representation of a date. The resulting string is parsed at (3) by the parse() method that uses the same formatter. The resulting date is also formatted using the same formatter at (4). It is hardly surprising that the text representations of both dates are equal.
DateTimeFormatter df = DateTimeFormatter.ISO_LOCAL_DATE; // (1)
LocalDate date = LocalDate.of(1935, 1, 8);
String strDate = date.format(df); // (2) 1935-01-08
LocalDate parsedDate = LocalDate.parse(strDate, df); // (3)
System.out.println(strDate + “|” +
parsedDate.format(df)); // (4) 1935-01-08|1935-01-08
As this code shows, a formatter can be reused, both for formatting and for parsing. The code at (4) in the code below applies the formatter from (1) in the preceding code snippet to format a LocalDateTime object. It should not come as a surprise that the resulting text representation of the LocalDateTime object pertains to only date fields in the temporal object; the time fields of the LocalDateTime object are ignored. Parsing this text representation back with the same formatter at (5) will yield only a LocalDate object.
LocalDateTime dateTime = LocalDateTime.of(1935, 1, 8, 12, 45);
String strDate2 = dateTime.format(df); // (4) 1935-01-08
LocalDate parsedDate2 = LocalDate.parse(strDate2, df); // (5) LocalDate
To summarize, the DateTimeFormatter.ISO_LOCAL_DATE can be used to format and parse a LocalDate, but can only format the date part of a LocalDateTime object (or a ZonedDateTime object).
Using this date formatter with a LocalTime object is courting disaster, as shown by the following code. Formatting with this formatter results in an unchecked java.time.temporal.UnsupportedTemporalTypeException, and parsing results in an unchecked java.time.format.DateTimeParseException.
String timeStr2 = LocalTime.NOON.format(df); // UnsupportedTemporalTypeException
LocalTime time2 = LocalTime.parse(“12:00”, df);// DateTimeParseException
The DateTimeFormatter.ISO_INSTANT predefined formatter shown in Table 18.11 is implicitly used by the parse(text) and toString() methods of the Instant class.