Class DateTimeUtil
LocalDate, LocalDateTime and LocalTime from strings of unknown
layout, and converts between legacy Date/Calendar and java.time types.
Parsing is done by DateTimeScanner in a single pass over the input. ISO and RFC 3339
date-times, SQL timestamps, compact yyyyMMdd forms, numeric dates with two- or
four-digit years, localized month and weekday names, ordinal day suffixes, AM/PM markers,
offsets and zone abbreviations are all recognised. A date missing its day or its month and day,
such as 2024-03 or 2024, resolves to the first such day.
A Unix epoch is read only by tryParseEpoch(String) and
tryParseLocalDateTime(String, ZoneId), since it names an instant and so needs a zone.
In an all-numeric date, a value above 12 is taken as the day, so both 25/12/2024 and
12/25/2024 mean Christmas. When both values could be a month, the order follows the
formatting locale: 03/04/2024 is the
fourth of March in the US and the third of April in the UK. Dot-separated dates are always
day-first, because no month-first locale writes 12.02.1999. The overloads taking a
dayFirst flag replace both rules with a fixed order, dot-separated dates included.
An offset or zone in the input is accepted but never shifts the result: the returned value holds the date and time exactly as written.
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic Datestatic LocalDateparseLocalDate(String text) static LocalDateparseLocalDate(String text, boolean dayFirst) Same asparseLocalDate(String), with the order of an ambiguous all-numeric date given explicitly instead of taken from the locale.static LocalDateTimeparseLocalDateTime(String text) static LocalDateTimeparseLocalDateTime(String text, boolean dayFirst) Same asparseLocalDateTime(String), with the order of an ambiguous all-numeric date given explicitly instead of taken from the locale.static LocalTimeparseLocalTime(String text) static DatestartOfDay(Date date) static DateConvertsinstantto aDate(same instant on the time-line).static Datestatic DatetoDate(LocalDateTime localDateTime) static DatetoDate(OffsetDateTime offsetDateTime) ConvertsoffsetDateTimeto aDate(same instant on the time-line).static DatetoDate(ZonedDateTime zonedDateTime) ConvertszonedDateTimeto aDate(same instant on the time-line).static DateConvertscalendarto aDate(same instant on the time-line).static LocalDatetoLocalDate(Instant instant) static LocalDatetoLocalDate(LocalDate localDate) ReturnslocalDateunchanged (null-safe).static LocalDatetoLocalDate(LocalDateTime localDateTime) Extracts the calendar date fromlocalDateTime(date part only; no time zone).static LocalDatetoLocalDate(OffsetDateTime offsetDateTime) ConvertsoffsetDateTimetoLocalDatein the system default time zone (same instant on the time-line).static LocalDatetoLocalDate(ZonedDateTime zonedDateTime) ConvertszonedDateTimetoLocalDatein the system default time zone (same instant on the time-line).static LocalDatetoLocalDate(Calendar calendar) static LocalDatetoLocalDate(Date date) static LocalDateTimetoLocalDateTime(Instant instant) static LocalDateTimetoLocalDateTime(LocalDate localDate) ConvertslocalDatetoLocalDateTimeat the start of that calendar day in the system default time zone.static LocalDateTimetoLocalDateTime(LocalDateTime localDateTime) ReturnslocalDateTimeunchanged (null-safe).static LocalDateTimetoLocalDateTime(OffsetDateTime offsetDateTime) ConvertsoffsetDateTimetoLocalDateTimein the system default time zone (same instant on the time-line).static LocalDateTimetoLocalDateTime(ZonedDateTime zonedDateTime) ConvertszonedDateTimetoLocalDateTimein the system default time zone (same instant on the time-line).static LocalDateTimetoLocalDateTime(Calendar calendar) static LocalDateTimetoLocalDateTime(Date date) static LocalTimetoLocalTime(LocalDateTime localDateTime) Extracts the local time-of-day fromlocalDateTime.static LocalTimetoLocalTime(LocalTime localTime) ReturnslocalTimeunchanged (null-safe).static LocalTimetoLocalTime(Date date) static OffsetDateTimetoOffsetDateTime(Instant instant) static OffsetDateTimetoOffsetDateTime(Instant instant, ZoneId zone) static OffsetDateTimeInterpretsldtas local date-time in the system default time zone.static OffsetDateTimetoOffsetDateTime(LocalDateTime ldt, ZoneId zone) Interpretsldtas local date-time inzone.static OffsetDateTimeReturnsodtunchanged (identity conversion for API symmetry with othertoOffsetDateTimeoverloads).static OffsetDateTimestatic OffsetDateTimetoOffsetDateTime(Calendar calendar) Convertscalendarto anOffsetDateTimein the system default time zone (same instant on the time-line).static OffsetDateTimetoOffsetDateTime(Calendar calendar, ZoneId zone) static OffsetDateTimetoOffsetDateTime(Date date) static OffsetDateTimetoOffsetDateTime(Date date, ZoneId zone) static Datestatic Timestatic TimestamptoSqlTimestamp(Date date) static ZonedDateTimetoZonedDateTime(Instant instant) static ZonedDateTimetoZonedDateTime(Instant instant, ZoneId zone) static ZonedDateTimetoZonedDateTime(LocalDate localDate) ConvertslocalDateto start of that calendar day in the system default time zone.static ZonedDateTimetoZonedDateTime(LocalDate localDate, ZoneId zone) ConvertslocalDateto start of that calendar day inzone.static ZonedDateTimeInterpretsldtas local date-time in the system default time zone (no offset shift of the clock fields).static ZonedDateTimetoZonedDateTime(LocalDateTime ldt, ZoneId zone) Interpretsldtas local date-time inzone(no offset shift of the clock fields).static ZonedDateTimeConvertsodtto aZonedDateTimeusing the same offset asodt(seeOffsetDateTime.toZonedDateTime()).static ZonedDateTimetoZonedDateTime(OffsetDateTime odt, ZoneId zone) static ZonedDateTimeReturnszdtunchanged (identity conversion for API symmetry with othertoZonedDateTimeoverloads).static ZonedDateTimetoZonedDateTime(ZonedDateTime zdt, ZoneId zone) Convertszdtto the same instant expressed inzone.static ZonedDateTimetoZonedDateTime(Calendar calendar) Convertscalendarto aZonedDateTimein the system default time zone (same instant on the time-line).static ZonedDateTimetoZonedDateTime(Calendar calendar, ZoneId zone) static ZonedDateTimetoZonedDateTime(Date date) static ZonedDateTimetoZonedDateTime(Date date, ZoneId zone) static InstanttryParseEpoch(String text) Reads a Unix epoch written as digits only, taking the unit from how many there are: ten digits are seconds, thirteen milliseconds, sixteen microseconds and nineteen nanoseconds.static LocalDatetryParseLocalDate(String text) Same asparseLocalDate(String)without the exception on unparseable input.static LocalDatetryParseLocalDate(String text, boolean dayFirst) Same asparseLocalDate(String, boolean)without the exception on unparseable input.static LocalDateTimetryParseLocalDateTime(String text) Same asparseLocalDateTime(String)without the exception on unparseable input.static LocalDateTimetryParseLocalDateTime(String text, boolean dayFirst) Same asparseLocalDateTime(String, boolean)without the exception on unparseable input.static LocalDateTimetryParseLocalDateTime(String text, ZoneId zone) Same astryParseLocalDateTime(String), additionally reading a Unix epoch and resolving it inzone.static LocalDateTimetryParseLocalDateTime(String text, ZoneId zone, boolean dayFirst) Same astryParseLocalDateTime(String, ZoneId), with the order of an ambiguous all-numeric date given explicitly instead of taken from the locale.static LocalTimetryParseLocalTime(String text) Same asparseLocalTime(String)without the exception on unparseable input.static OffsetTimetryParseOffsetTime(String text) static ZoneIdtryParseZoneId(String text) Reads aZoneIdfromtext.static ZoneOffsettryParseZoneOffset(String text) Reads aZoneOffsetfromtext.
-
Constructor Details
-
DateTimeUtil
public DateTimeUtil()
-
-
Method Details
-
parseLocalDate
- Returns:
- parsed date; time-of-day is discarded if present, or
nulliftextis null/blank - Throws:
IllegalArgumentException- iftextcannot be parsed
-
parseLocalDateTime
- Returns:
- parsed date-time; date-only strings use start of day (00:00), or
nulliftextis null/blank - Throws:
IllegalArgumentException- iftextcannot be parsed
-
parseLocalDate
Same asparseLocalDate(String), with the order of an ambiguous all-numeric date given explicitly instead of taken from the locale.- Parameters:
dayFirst-trueto read03/04/2024as the third of April,falseas the fourth of March; a value above 12 is still always the day- Returns:
- parsed date; time-of-day is discarded if present, or
nulliftextis null/blank - Throws:
IllegalArgumentException- iftextcannot be parsed
-
parseLocalDateTime
Same asparseLocalDateTime(String), with the order of an ambiguous all-numeric date given explicitly instead of taken from the locale.- Parameters:
dayFirst-trueto read03/04/2024as the third of April,falseas the fourth of March; a value above 12 is still always the day- Returns:
- parsed date-time; date-only strings use start of day (00:00), or
nulliftextis null/blank - Throws:
IllegalArgumentException- iftextcannot be parsed
-
parseLocalTime
- Returns:
- parsed local time, or
nulliftextis null/blank - Throws:
IllegalArgumentException- iftextcannot be parsed
-
tryParseLocalDate
Same asparseLocalDate(String)without the exception on unparseable input.- Returns:
- parsed date, or
nulliftextis null/blank or unparseable
-
tryParseLocalDate
Same asparseLocalDate(String, boolean)without the exception on unparseable input.- Parameters:
dayFirst-trueto read an ambiguous all-numeric date as day-month,falseas month-day- Returns:
- parsed date, or
nulliftextis null/blank or unparseable
-
tryParseLocalDateTime
Same asparseLocalDateTime(String)without the exception on unparseable input.- Returns:
- parsed date-time, or
nulliftextis null/blank or unparseable
-
tryParseLocalDateTime
Same asparseLocalDateTime(String, boolean)without the exception on unparseable input.- Parameters:
dayFirst-trueto read an ambiguous all-numeric date as day-month,falseas month-day- Returns:
- parsed date-time, or
nulliftextis null/blank or unparseable
-
tryParseLocalTime
Same asparseLocalTime(String)without the exception on unparseable input.- Returns:
- parsed time, or
nulliftextis null/blank or unparseable
-
tryParseOffsetTime
Reads anOffsetTimefromtextwith the same recognition astryParseLocalTime(String). The result isnullwhen the input has no time, or has a time but neither an offset nor a zone.- Returns:
- the offset time, or
nulliftextis null/blank or does not carry one
-
tryParseZoneId
Reads aZoneIdfromtext. A bare zone or offset is read byZoneId.of(String). Anything else, such as a date-time that carries a zone, falls back to the scanner: a named zone wins, and an explicit offset is used when the input named no zone.- Returns:
- the zone, or
nulliftextis null/blank or carries neither a zone nor an offset
-
tryParseZoneOffset
Reads aZoneOffsetfromtext. A bare offset is read byZoneOffset.of(String). Anything else falls back to the scanner, which returns only an offset written in the input. A named zone is left alone.- Returns:
- the offset, or
nulliftextis null/blank or carries no offset
-
tryParseLocalDateTime
Same astryParseLocalDateTime(String), additionally reading a Unix epoch and resolving it inzone.An epoch names an instant rather than a wall-clock reading, which is why it takes a zone and why
tryParseLocalDateTime(String)leaves it alone: every other shape this class parses is returned exactly as written, and no result depends on the zone of the machine.- Parameters:
zone- the zone to resolve an epoch in; must not benull- Returns:
- parsed date-time, or
nulliftextis null/blank or unparseable
-
tryParseLocalDateTime
Same astryParseLocalDateTime(String, ZoneId), with the order of an ambiguous all-numeric date given explicitly instead of taken from the locale.- Parameters:
zone- the zone to resolve an epoch in; must not benulldayFirst-trueto read an ambiguous all-numeric date as day-month,falseas month-day- Returns:
- parsed date-time, or
nulliftextis null/blank or unparseable
-
tryParseEpoch
Reads a Unix epoch written as digits only, taking the unit from how many there are: ten digits are seconds, thirteen milliseconds, sixteen microseconds and nineteen nanoseconds.Eight and fourteen digits are not epochs:
tryParseLocalDate(String)reads them asyyyyMMddandyyyyMMddHHmmss, and no real epoch has either length.Based on araddon/dateparse: dateDigit, which takes the unit from the length of the string in the same way. Lengths it leaves without a result, and numbers too large for the unit, are rejected here rather than returning an epoch of zero.
- Returns:
- the instant, or
nulliftextis null/blank or is not such a number
-
toDate
- Parameters:
localDate- the local date, ornull- Returns:
java.util.Dateat start of day in the system default zone, ornulliflocalDateisnull
-
toDate
- Parameters:
localDateTime- the local date-time without zone, ornull- Returns:
- the corresponding
java.util.Date, ornulliflocalDateTimeisnull
-
toDate
Convertsinstantto aDate(same instant on the time-line).- Parameters:
instant- the instant, ornull- Returns:
- the corresponding
java.util.Date, ornullifinstantisnull
-
toDate
ConvertszonedDateTimeto aDate(same instant on the time-line).- Parameters:
zonedDateTime- the zoned date-time, ornull- Returns:
- the corresponding
java.util.Date, ornullifzonedDateTimeisnull
-
toDate
ConvertsoffsetDateTimeto aDate(same instant on the time-line).- Parameters:
offsetDateTime- the offset date-time, ornull- Returns:
- the corresponding
java.util.Date, ornullifoffsetDateTimeisnull
-
toDate
Convertscalendarto aDate(same instant on the time-line).- Parameters:
calendar- the calendar, ornull- Returns:
- the corresponding
java.util.Date, ornullifcalendarisnull
-
toLocalDateTime
ReturnslocalDateTimeunchanged (null-safe).- Parameters:
localDateTime- the local date-time, ornull- Returns:
localDateTime, ornulliflocalDateTimeisnull
-
toLocalDateTime
ConvertslocalDatetoLocalDateTimeat the start of that calendar day in the system default time zone.- Parameters:
localDate- the local date, ornull- Returns:
- start of day in the system default zone as
LocalDateTime, ornulliflocalDateisnull
-
toLocalDateTime
- Parameters:
instant- the instant, ornull- Returns:
- local date-time in the system default zone, or
nullifinstantisnull
-
toLocalDateTime
ConvertszonedDateTimetoLocalDateTimein the system default time zone (same instant on the time-line).- Parameters:
zonedDateTime- the zoned date-time, ornull- Returns:
- local date-time in the system default zone, or
nullifzonedDateTimeisnull
-
toLocalDateTime
ConvertsoffsetDateTimetoLocalDateTimein the system default time zone (same instant on the time-line).- Parameters:
offsetDateTime- the offset date-time, ornull- Returns:
- local date-time in the system default zone, or
nullifoffsetDateTimeisnull
-
toLocalDateTime
- Parameters:
date- the legacy date, ornull- Returns:
- local date-time in the system default zone, or
nullifdateisnull
-
toLocalDateTime
- Parameters:
calendar- the calendar, ornull- Returns:
- local date-time in the system default zone, or
nullifcalendarisnull
-
toLocalDate
ReturnslocalDateunchanged (null-safe).- Parameters:
localDate- the local date, ornull- Returns:
localDate, ornulliflocalDateisnull
-
toLocalDate
Extracts the calendar date fromlocalDateTime(date part only; no time zone).- Parameters:
localDateTime- the local date-time, ornull- Returns:
LocalDatepart oflocalDateTime, ornulliflocalDateTimeisnull
-
toLocalDate
- Parameters:
instant- the instant, ornull- Returns:
- the local calendar date in the system default zone, or
nullifinstantisnull
-
toLocalDate
ConvertszonedDateTimetoLocalDatein the system default time zone (same instant on the time-line).- Parameters:
zonedDateTime- the zoned date-time, ornull- Returns:
- the local calendar date in the system default zone, or
nullifzonedDateTimeisnull
-
toLocalDate
ConvertsoffsetDateTimetoLocalDatein the system default time zone (same instant on the time-line).- Parameters:
offsetDateTime- the offset date-time, ornull- Returns:
- the local calendar date in the system default zone, or
nullifoffsetDateTimeisnull
-
toLocalDate
- Parameters:
date- the legacy date, ornull- Returns:
- the local calendar date in the system default zone, or
nullifdateisnull
-
toLocalDate
- Parameters:
calendar- the calendar, ornull- Returns:
- the local calendar date in the system default zone, or
nullifcalendarisnull
-
toLocalTime
ReturnslocalTimeunchanged (null-safe).- Parameters:
localTime- the local time, ornull- Returns:
localTime, ornulliflocalTimeisnull
-
toLocalTime
Extracts the local time-of-day fromlocalDateTime.- Parameters:
localDateTime- the local date-time, ornull- Returns:
LocalTimepart oflocalDateTime, ornulliflocalDateTimeisnull
-
toLocalTime
- Parameters:
date- the legacy date, ornull- Returns:
- local time-of-day in the system default zone, or
nullifdateisnull
-
startOfDay
- Returns:
Dateat start of the local calendar day ofdatein the system default time zone
-
endOfDay
- Returns:
Dateat end of the local calendar day ofdatein the system default time zone (23:59:59.999)
-
toSqlDate
- Returns:
Datefor the local date ofdatein the system default time zone
-
toSqlTime
- Returns:
Timefor the local time-of-day ofdatein the system default time zone
-
toSqlTimestamp
- Returns:
Timestampwith the same instant asdate
-
toZonedDateTime
Returnszdtunchanged (identity conversion for API symmetry with othertoZonedDateTimeoverloads).- Parameters:
zdt- the zoned date-time, ornull- Returns:
zdt, ornullifzdtisnull
-
toZonedDateTime
Convertszdtto the same instant expressed inzone.- Parameters:
zdt- the zoned date-time, ornullzone- the target zone; must not benullwhenzdtis non-null- Returns:
zdtwith zone replaced byzone, ornullifzdtisnull
-
toZonedDateTime
Convertsodtto aZonedDateTimeusing the same offset asodt(seeOffsetDateTime.toZonedDateTime()).- Parameters:
odt- the offset date-time, ornull- Returns:
- the zoned date-time, or
nullifodtisnull
-
toZonedDateTime
- Parameters:
odt- the offset date-time, ornullzone- the target zone; must not benullwhenodtis non-null- Returns:
- zoned date-time in
zone, ornullifodtisnull
-
toZonedDateTime
- Parameters:
instant- the instant, ornull- Returns:
instantat system default zone, ornullifinstantisnull
-
toZonedDateTime
- Parameters:
instant- the instant, ornullzone- the zone; must not benullwheninstantis non-null- Returns:
instantatzone, ornullifinstantisnull
-
toZonedDateTime
- Parameters:
date- the legacy date, ornull- Returns:
- zoned date-time in system default zone, or
nullifdateisnull
-
toZonedDateTime
- Parameters:
date- the legacy date, ornullzone- the zone; must not benullwhendateis non-null- Returns:
- zoned date-time in
zone, ornullifdateisnull
-
toZonedDateTime
Convertscalendarto aZonedDateTimein the system default time zone (same instant on the time-line).- Parameters:
calendar- the calendar, ornull- Returns:
- zoned date-time in system default zone, or
nullifcalendarisnull
-
toZonedDateTime
- Parameters:
calendar- the calendar, ornullzone- the zone; must not benullwhencalendaris non-null- Returns:
- zoned date-time in
zone, ornullifcalendarisnull
-
toZonedDateTime
Interpretsldtas local date-time in the system default time zone (no offset shift of the clock fields).- Parameters:
ldt- the local date-time, ornull- Returns:
ldtat system default zone, ornullifldtisnull
-
toZonedDateTime
Interpretsldtas local date-time inzone(no offset shift of the clock fields).- Parameters:
ldt- the local date-time, ornullzone- the zone; must not benullwhenldtis non-null- Returns:
ldtatzone, ornullifldtisnull
-
toZonedDateTime
ConvertslocalDateto start of that calendar day in the system default time zone.- Parameters:
localDate- the local date, ornull- Returns:
- midnight at
localDatein system default zone, ornulliflocalDateisnull
-
toZonedDateTime
ConvertslocalDateto start of that calendar day inzone.- Parameters:
localDate- the local date, ornullzone- the zone; must not benullwhenlocalDateis non-null- Returns:
- midnight at
localDateinzone, ornulliflocalDateisnull
-
toOffsetDateTime
Returnsodtunchanged (identity conversion for API symmetry with othertoOffsetDateTimeoverloads).- Parameters:
odt- the offset date-time, ornull- Returns:
odt, ornullifodtisnull
-
toOffsetDateTime
- Parameters:
zdt- the zoned date-time, ornull- Returns:
- offset date-time at the same instant, or
nullifzdtisnull
-
toOffsetDateTime
- Parameters:
instant- the instant, ornull- Returns:
- offset date-time for
instantin system default zone, ornullifinstantisnull
-
toOffsetDateTime
Interpretsldtas local date-time in the system default time zone.- Parameters:
ldt- the local date-time, ornull- Returns:
- offset date-time in system default zone, or
nullifldtisnull
-
toOffsetDateTime
Interpretsldtas local date-time inzone.- Parameters:
ldt- the local date-time, ornullzone- the zone; must not benullwhenldtis non-null- Returns:
- offset date-time in
zone, ornullifldtisnull
-
toOffsetDateTime
- Parameters:
instant- the instant, ornullzone- the zone; must not benullwheninstantis non-null- Returns:
- offset date-time for
instantinzone, ornullifinstantisnull
-
toOffsetDateTime
- Parameters:
date- the legacy date, ornull- Returns:
- offset date-time in system default zone, or
nullifdateisnull
-
toOffsetDateTime
- Parameters:
date- the legacy date, ornullzone- the zone; must not benullwhendateis non-null- Returns:
- offset date-time in
zone, ornullifdateisnull
-
toOffsetDateTime
Convertscalendarto anOffsetDateTimein the system default time zone (same instant on the time-line).- Parameters:
calendar- the calendar, ornull- Returns:
- offset date-time in system default zone, or
nullifcalendarisnull
-
toOffsetDateTime
- Parameters:
calendar- the calendar, ornullzone- the zone; must not benullwhencalendaris non-null- Returns:
- offset date-time in
zone, ornullifcalendarisnull
-