Class DateTimeUtil

java.lang.Object
io.github.connellite.util.DateTimeUtil

public class DateTimeUtil extends Object
Parses 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 Details

    • DateTimeUtil

      public DateTimeUtil()
  • Method Details

    • parseLocalDate

      public static LocalDate parseLocalDate(String text)
      Returns:
      parsed date; time-of-day is discarded if present, or null if text is null/blank
      Throws:
      IllegalArgumentException - if text cannot be parsed
    • parseLocalDateTime

      public static LocalDateTime parseLocalDateTime(String text)
      Returns:
      parsed date-time; date-only strings use start of day (00:00), or null if text is null/blank
      Throws:
      IllegalArgumentException - if text cannot be parsed
    • parseLocalDate

      public static LocalDate parseLocalDate(String text, boolean dayFirst)
      Same as parseLocalDate(String), with the order of an ambiguous all-numeric date given explicitly instead of taken from the locale.
      Parameters:
      dayFirst - true to read 03/04/2024 as the third of April, false as the fourth of March; a value above 12 is still always the day
      Returns:
      parsed date; time-of-day is discarded if present, or null if text is null/blank
      Throws:
      IllegalArgumentException - if text cannot be parsed
    • parseLocalDateTime

      public static LocalDateTime parseLocalDateTime(String text, boolean dayFirst)
      Same as parseLocalDateTime(String), with the order of an ambiguous all-numeric date given explicitly instead of taken from the locale.
      Parameters:
      dayFirst - true to read 03/04/2024 as the third of April, false as 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 null if text is null/blank
      Throws:
      IllegalArgumentException - if text cannot be parsed
    • parseLocalTime

      public static LocalTime parseLocalTime(String text)
      Returns:
      parsed local time, or null if text is null/blank
      Throws:
      IllegalArgumentException - if text cannot be parsed
    • tryParseLocalDate

      public static LocalDate tryParseLocalDate(String text)
      Same as parseLocalDate(String) without the exception on unparseable input.
      Returns:
      parsed date, or null if text is null/blank or unparseable
    • tryParseLocalDate

      public static LocalDate tryParseLocalDate(String text, boolean dayFirst)
      Same as parseLocalDate(String, boolean) without the exception on unparseable input.
      Parameters:
      dayFirst - true to read an ambiguous all-numeric date as day-month, false as month-day
      Returns:
      parsed date, or null if text is null/blank or unparseable
    • tryParseLocalDateTime

      public static LocalDateTime tryParseLocalDateTime(String text)
      Same as parseLocalDateTime(String) without the exception on unparseable input.
      Returns:
      parsed date-time, or null if text is null/blank or unparseable
    • tryParseLocalDateTime

      public static LocalDateTime tryParseLocalDateTime(String text, boolean dayFirst)
      Same as parseLocalDateTime(String, boolean) without the exception on unparseable input.
      Parameters:
      dayFirst - true to read an ambiguous all-numeric date as day-month, false as month-day
      Returns:
      parsed date-time, or null if text is null/blank or unparseable
    • tryParseLocalTime

      public static LocalTime tryParseLocalTime(String text)
      Same as parseLocalTime(String) without the exception on unparseable input.
      Returns:
      parsed time, or null if text is null/blank or unparseable
    • tryParseOffsetTime

      public static OffsetTime tryParseOffsetTime(String text)
      Reads an OffsetTime from text with the same recognition as tryParseLocalTime(String). The result is null when the input has no time, or has a time but neither an offset nor a zone.
      Returns:
      the offset time, or null if text is null/blank or does not carry one
    • tryParseZoneId

      public static ZoneId tryParseZoneId(String text)
      Reads a ZoneId from text. A bare zone or offset is read by ZoneId.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 null if text is null/blank or carries neither a zone nor an offset
    • tryParseZoneOffset

      public static ZoneOffset tryParseZoneOffset(String text)
      Reads a ZoneOffset from text. A bare offset is read by ZoneOffset.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 null if text is null/blank or carries no offset
    • tryParseLocalDateTime

      public static LocalDateTime tryParseLocalDateTime(String text, ZoneId zone)
      Same as tryParseLocalDateTime(String), additionally reading a Unix epoch and resolving it in zone.

      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 be null
      Returns:
      parsed date-time, or null if text is null/blank or unparseable
    • tryParseLocalDateTime

      public static LocalDateTime tryParseLocalDateTime(String text, ZoneId zone, boolean dayFirst)
      Same as tryParseLocalDateTime(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 be null
      dayFirst - true to read an ambiguous all-numeric date as day-month, false as month-day
      Returns:
      parsed date-time, or null if text is null/blank or unparseable
    • tryParseEpoch

      public static Instant tryParseEpoch(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.

      Eight and fourteen digits are not epochs: tryParseLocalDate(String) reads them as yyyyMMdd and yyyyMMddHHmmss, 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 null if text is null/blank or is not such a number
    • toDate

      public static Date toDate(LocalDate localDate)
      Converts localDate to a Date at the start of that calendar day in the system default time zone.
      Parameters:
      localDate - the local date, or null
      Returns:
      java.util.Date at start of day in the system default zone, or null if localDate is null
    • toDate

      public static Date toDate(LocalDateTime localDateTime)
      Converts localDateTime to a Date by placing localDateTime in the system default time zone.
      Parameters:
      localDateTime - the local date-time without zone, or null
      Returns:
      the corresponding java.util.Date, or null if localDateTime is null
    • toDate

      public static Date toDate(Instant instant)
      Converts instant to a Date (same instant on the time-line).
      Parameters:
      instant - the instant, or null
      Returns:
      the corresponding java.util.Date, or null if instant is null
    • toDate

      public static Date toDate(ZonedDateTime zonedDateTime)
      Converts zonedDateTime to a Date (same instant on the time-line).
      Parameters:
      zonedDateTime - the zoned date-time, or null
      Returns:
      the corresponding java.util.Date, or null if zonedDateTime is null
    • toDate

      public static Date toDate(OffsetDateTime offsetDateTime)
      Converts offsetDateTime to a Date (same instant on the time-line).
      Parameters:
      offsetDateTime - the offset date-time, or null
      Returns:
      the corresponding java.util.Date, or null if offsetDateTime is null
    • toDate

      public static Date toDate(Calendar calendar)
      Converts calendar to a Date (same instant on the time-line).
      Parameters:
      calendar - the calendar, or null
      Returns:
      the corresponding java.util.Date, or null if calendar is null
    • toLocalDateTime

      public static LocalDateTime toLocalDateTime(LocalDateTime localDateTime)
      Returns localDateTime unchanged (null-safe).
      Parameters:
      localDateTime - the local date-time, or null
      Returns:
      localDateTime, or null if localDateTime is null
    • toLocalDateTime

      public static LocalDateTime toLocalDateTime(LocalDate localDate)
      Converts localDate to LocalDateTime at the start of that calendar day in the system default time zone.
      Parameters:
      localDate - the local date, or null
      Returns:
      start of day in the system default zone as LocalDateTime, or null if localDate is null
    • toLocalDateTime

      public static LocalDateTime toLocalDateTime(Instant instant)
      Converts instant to LocalDateTime in the system default time zone.
      Parameters:
      instant - the instant, or null
      Returns:
      local date-time in the system default zone, or null if instant is null
    • toLocalDateTime

      public static LocalDateTime toLocalDateTime(ZonedDateTime zonedDateTime)
      Converts zonedDateTime to LocalDateTime in the system default time zone (same instant on the time-line).
      Parameters:
      zonedDateTime - the zoned date-time, or null
      Returns:
      local date-time in the system default zone, or null if zonedDateTime is null
    • toLocalDateTime

      public static LocalDateTime toLocalDateTime(OffsetDateTime offsetDateTime)
      Converts offsetDateTime to LocalDateTime in the system default time zone (same instant on the time-line).
      Parameters:
      offsetDateTime - the offset date-time, or null
      Returns:
      local date-time in the system default zone, or null if offsetDateTime is null
    • toLocalDateTime

      public static LocalDateTime toLocalDateTime(Date date)
      Converts date to LocalDateTime in the system default time zone.
      Parameters:
      date - the legacy date, or null
      Returns:
      local date-time in the system default zone, or null if date is null
    • toLocalDateTime

      public static LocalDateTime toLocalDateTime(Calendar calendar)
      Converts calendar to LocalDateTime in the system default time zone.
      Parameters:
      calendar - the calendar, or null
      Returns:
      local date-time in the system default zone, or null if calendar is null
    • toLocalDate

      public static LocalDate toLocalDate(LocalDate localDate)
      Returns localDate unchanged (null-safe).
      Parameters:
      localDate - the local date, or null
      Returns:
      localDate, or null if localDate is null
    • toLocalDate

      public static LocalDate toLocalDate(LocalDateTime localDateTime)
      Extracts the calendar date from localDateTime (date part only; no time zone).
      Parameters:
      localDateTime - the local date-time, or null
      Returns:
      LocalDate part of localDateTime, or null if localDateTime is null
    • toLocalDate

      public static LocalDate toLocalDate(Instant instant)
      Converts instant to LocalDate in the system default time zone.
      Parameters:
      instant - the instant, or null
      Returns:
      the local calendar date in the system default zone, or null if instant is null
    • toLocalDate

      public static LocalDate toLocalDate(ZonedDateTime zonedDateTime)
      Converts zonedDateTime to LocalDate in the system default time zone (same instant on the time-line).
      Parameters:
      zonedDateTime - the zoned date-time, or null
      Returns:
      the local calendar date in the system default zone, or null if zonedDateTime is null
    • toLocalDate

      public static LocalDate toLocalDate(OffsetDateTime offsetDateTime)
      Converts offsetDateTime to LocalDate in the system default time zone (same instant on the time-line).
      Parameters:
      offsetDateTime - the offset date-time, or null
      Returns:
      the local calendar date in the system default zone, or null if offsetDateTime is null
    • toLocalDate

      public static LocalDate toLocalDate(Date date)
      Converts date to LocalDate in the system default time zone.
      Parameters:
      date - the legacy date, or null
      Returns:
      the local calendar date in the system default zone, or null if date is null
    • toLocalDate

      public static LocalDate toLocalDate(Calendar calendar)
      Converts calendar to LocalDate in the system default time zone.
      Parameters:
      calendar - the calendar, or null
      Returns:
      the local calendar date in the system default zone, or null if calendar is null
    • toLocalTime

      public static LocalTime toLocalTime(LocalTime localTime)
      Returns localTime unchanged (null-safe).
      Parameters:
      localTime - the local time, or null
      Returns:
      localTime, or null if localTime is null
    • toLocalTime

      public static LocalTime toLocalTime(LocalDateTime localDateTime)
      Extracts the local time-of-day from localDateTime.
      Parameters:
      localDateTime - the local date-time, or null
      Returns:
      LocalTime part of localDateTime, or null if localDateTime is null
    • toLocalTime

      public static LocalTime toLocalTime(Date date)
      Converts date to LocalTime in the system default time zone.
      Parameters:
      date - the legacy date, or null
      Returns:
      local time-of-day in the system default zone, or null if date is null
    • startOfDay

      public static Date startOfDay(Date date)
      Returns:
      Date at start of the local calendar day of date in the system default time zone
    • endOfDay

      public static Date endOfDay(Date date)
      Returns:
      Date at end of the local calendar day of date in the system default time zone (23:59:59.999)
    • toSqlDate

      public static Date toSqlDate(Date date)
      Returns:
      Date for the local date of date in the system default time zone
    • toSqlTime

      public static Time toSqlTime(Date date)
      Returns:
      Time for the local time-of-day of date in the system default time zone
    • toSqlTimestamp

      public static Timestamp toSqlTimestamp(Date date)
      Returns:
      Timestamp with the same instant as date
    • toZonedDateTime

      public static ZonedDateTime toZonedDateTime(ZonedDateTime zdt)
      Returns zdt unchanged (identity conversion for API symmetry with other toZonedDateTime overloads).
      Parameters:
      zdt - the zoned date-time, or null
      Returns:
      zdt, or null if zdt is null
    • toZonedDateTime

      public static ZonedDateTime toZonedDateTime(ZonedDateTime zdt, ZoneId zone)
      Converts zdt to the same instant expressed in zone.
      Parameters:
      zdt - the zoned date-time, or null
      zone - the target zone; must not be null when zdt is non-null
      Returns:
      zdt with zone replaced by zone, or null if zdt is null
    • toZonedDateTime

      public static ZonedDateTime toZonedDateTime(OffsetDateTime odt)
      Converts odt to a ZonedDateTime using the same offset as odt (see OffsetDateTime.toZonedDateTime()).
      Parameters:
      odt - the offset date-time, or null
      Returns:
      the zoned date-time, or null if odt is null
    • toZonedDateTime

      public static ZonedDateTime toZonedDateTime(OffsetDateTime odt, ZoneId zone)
      Converts odt to a ZonedDateTime at the same instant in zone.
      Parameters:
      odt - the offset date-time, or null
      zone - the target zone; must not be null when odt is non-null
      Returns:
      zoned date-time in zone, or null if odt is null
    • toZonedDateTime

      public static ZonedDateTime toZonedDateTime(Instant instant)
      Converts instant to a ZonedDateTime in the system default time zone.
      Parameters:
      instant - the instant, or null
      Returns:
      instant at system default zone, or null if instant is null
    • toZonedDateTime

      public static ZonedDateTime toZonedDateTime(Instant instant, ZoneId zone)
      Converts instant to a ZonedDateTime in zone.
      Parameters:
      instant - the instant, or null
      zone - the zone; must not be null when instant is non-null
      Returns:
      instant at zone, or null if instant is null
    • toZonedDateTime

      public static ZonedDateTime toZonedDateTime(Date date)
      Converts date to a ZonedDateTime in the system default time zone (same instant on the time-line).
      Parameters:
      date - the legacy date, or null
      Returns:
      zoned date-time in system default zone, or null if date is null
    • toZonedDateTime

      public static ZonedDateTime toZonedDateTime(Date date, ZoneId zone)
      Converts date to a ZonedDateTime in zone (same instant on the time-line).
      Parameters:
      date - the legacy date, or null
      zone - the zone; must not be null when date is non-null
      Returns:
      zoned date-time in zone, or null if date is null
    • toZonedDateTime

      public static ZonedDateTime toZonedDateTime(Calendar calendar)
      Converts calendar to a ZonedDateTime in the system default time zone (same instant on the time-line).
      Parameters:
      calendar - the calendar, or null
      Returns:
      zoned date-time in system default zone, or null if calendar is null
    • toZonedDateTime

      public static ZonedDateTime toZonedDateTime(Calendar calendar, ZoneId zone)
      Converts calendar to a ZonedDateTime in zone (same instant on the time-line).
      Parameters:
      calendar - the calendar, or null
      zone - the zone; must not be null when calendar is non-null
      Returns:
      zoned date-time in zone, or null if calendar is null
    • toZonedDateTime

      public static ZonedDateTime toZonedDateTime(LocalDateTime ldt)
      Interprets ldt as local date-time in the system default time zone (no offset shift of the clock fields).
      Parameters:
      ldt - the local date-time, or null
      Returns:
      ldt at system default zone, or null if ldt is null
    • toZonedDateTime

      public static ZonedDateTime toZonedDateTime(LocalDateTime ldt, ZoneId zone)
      Interprets ldt as local date-time in zone (no offset shift of the clock fields).
      Parameters:
      ldt - the local date-time, or null
      zone - the zone; must not be null when ldt is non-null
      Returns:
      ldt at zone, or null if ldt is null
    • toZonedDateTime

      public static ZonedDateTime toZonedDateTime(LocalDate localDate)
      Converts localDate to start of that calendar day in the system default time zone.
      Parameters:
      localDate - the local date, or null
      Returns:
      midnight at localDate in system default zone, or null if localDate is null
    • toZonedDateTime

      public static ZonedDateTime toZonedDateTime(LocalDate localDate, ZoneId zone)
      Converts localDate to start of that calendar day in zone.
      Parameters:
      localDate - the local date, or null
      zone - the zone; must not be null when localDate is non-null
      Returns:
      midnight at localDate in zone, or null if localDate is null
    • toOffsetDateTime

      public static OffsetDateTime toOffsetDateTime(OffsetDateTime odt)
      Returns odt unchanged (identity conversion for API symmetry with other toOffsetDateTime overloads).
      Parameters:
      odt - the offset date-time, or null
      Returns:
      odt, or null if odt is null
    • toOffsetDateTime

      public static OffsetDateTime toOffsetDateTime(ZonedDateTime zdt)
      Converts zdt to an OffsetDateTime preserving the same instant and effective offset of zdt.
      Parameters:
      zdt - the zoned date-time, or null
      Returns:
      offset date-time at the same instant, or null if zdt is null
    • toOffsetDateTime

      public static OffsetDateTime toOffsetDateTime(Instant instant)
      Converts instant to an OffsetDateTime in the system default time zone.
      Parameters:
      instant - the instant, or null
      Returns:
      offset date-time for instant in system default zone, or null if instant is null
    • toOffsetDateTime

      public static OffsetDateTime toOffsetDateTime(LocalDateTime ldt)
      Interprets ldt as local date-time in the system default time zone.
      Parameters:
      ldt - the local date-time, or null
      Returns:
      offset date-time in system default zone, or null if ldt is null
    • toOffsetDateTime

      public static OffsetDateTime toOffsetDateTime(LocalDateTime ldt, ZoneId zone)
      Interprets ldt as local date-time in zone.
      Parameters:
      ldt - the local date-time, or null
      zone - the zone; must not be null when ldt is non-null
      Returns:
      offset date-time in zone, or null if ldt is null
    • toOffsetDateTime

      public static OffsetDateTime toOffsetDateTime(Instant instant, ZoneId zone)
      Converts instant to an OffsetDateTime in zone.
      Parameters:
      instant - the instant, or null
      zone - the zone; must not be null when instant is non-null
      Returns:
      offset date-time for instant in zone, or null if instant is null
    • toOffsetDateTime

      public static OffsetDateTime toOffsetDateTime(Date date)
      Converts date to an OffsetDateTime in the system default time zone (same instant on the time-line).
      Parameters:
      date - the legacy date, or null
      Returns:
      offset date-time in system default zone, or null if date is null
    • toOffsetDateTime

      public static OffsetDateTime toOffsetDateTime(Date date, ZoneId zone)
      Converts date to an OffsetDateTime in zone (same instant on the time-line).
      Parameters:
      date - the legacy date, or null
      zone - the zone; must not be null when date is non-null
      Returns:
      offset date-time in zone, or null if date is null
    • toOffsetDateTime

      public static OffsetDateTime toOffsetDateTime(Calendar calendar)
      Converts calendar to an OffsetDateTime in the system default time zone (same instant on the time-line).
      Parameters:
      calendar - the calendar, or null
      Returns:
      offset date-time in system default zone, or null if calendar is null
    • toOffsetDateTime

      public static OffsetDateTime toOffsetDateTime(Calendar calendar, ZoneId zone)
      Converts calendar to an OffsetDateTime in zone (same instant on the time-line).
      Parameters:
      calendar - the calendar, or null
      zone - the zone; must not be null when calendar is non-null
      Returns:
      offset date-time in zone, or null if calendar is null