Module org.firebirdsql.jaybird
Package org.firebirdsql.jaybird.util

# Class FbDatetimeConversion

java.lang.Object
org.firebirdsql.jaybird.util.FbDatetimeConversion

public final class FbDatetimeConversion extends Object
Helpers and classes for Firebird/Jaybird datetime handling.

Since:
  6
Author:
  Mark Rotteveel

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final TemporalField`
  `FB_TIME_FIELD`
  Field for Firebird time.
  `static final TemporalUnit`
  `FB_TIME_UNIT`
  The Firebird unit of time, i.e.
  `static final long`
  `MICROS_PER_UNIT`
  Number of microseconds per Firebird unit of time (i.e.
  `static final long`
  `NANOS_PER_UNIT`
  Number of nanoseconds per Firebird unit of time (i.e.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static @Nullable String`
  `formatSqlDate(@Nullable LocalDate localDate)`
  Formats a local date as a SQL date value (`yyyy-mm-dd`).
  `static @Nullable String`
  `formatSqlTime(@Nullable LocalTime localTime)`
  Formats a local time as a SQL time value (`hh:mm:ss[.f...]`).
  `static @Nullable String`
  `formatSqlTimestamp(@Nullable LocalDateTime localDateTime)`
  Formats a local date time as a SQL timestamp value (`yyyy-mm-dd hh:mm:ss[.f...]`).
  `static LocalTime`
  `fromFbTimeUnits(int timeUnits)`
  Converts Firebird time units (a.k.a.
  `static LocalDate`
  `fromModifiedJulianDate(int mjd)`
  Converts a Modified Julian Date to the corresponding `LocalDate`.
  `static @Nullable LocalDateTime`
  `parseIsoOrSqlTimestamp(@Nullable String datetimeString)`
  Parse a string as a ISO 8601 datetime (yyyy-mm-dd{T|t}hh:mm[:ss[.f...]] or as a SQL timestamp value (see `parseSqlTimestamp(String)`).
  `static @Nullable LocalDate`
  `parseSqlDate(@Nullable String dateString)`
  Parse a string as a SQL date value (`yyyy-[m]m-[d]d`).
  `static @Nullable LocalTime`
  `parseSqlTime(@Nullable String timeString)`
  Parse a string as a SQL time value (`hh:mm[:ss[.f...]]`).
  `static @Nullable LocalDateTime`
  `parseSqlTimestamp(@Nullable String datetimeString)`
  Parse a string as a SQL timestamp value (`yyyy-[m]m-[d]d hh:mm[:ss[.f...]]`).
  `static int`
  `toFbTimeUnits(LocalTime localTime)`
  Converts a local time to Firebird time units (a.k.a.
  `static int`
  `toModifiedJulianDate(LocalDate localDate)`
  Converts a local date to a Modified Julian Date.
  `static <R extends Temporal>
  R`
  `updateFbTimeUnits(R datetime, int timeUnits)`
  Returns a copy of `datetime`, updated so its time is now set to the value corresponding to the Firebird time units (`timeUnits)`.
  `static <R extends Temporal>
  R`
  `updateModifiedJulianDate(R datetime, int mjd)`
  Returns a copy of `datetime`, updated so its date is now set to the value corresponding to the Modified Julian Date `mjd`.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### FB_TIME_UNIT

    public static final TemporalUnit FB_TIME_UNIT
    The Firebird unit of time, i.e. 100 microseconds.

  - ### FB_TIME_FIELD

    public static final TemporalField FB_TIME_FIELD
    Field for Firebird time.

  - ### MICROS_PER_UNIT

    public static final long MICROS_PER_UNIT
    Number of microseconds per Firebird unit of time (i.e. 100 microseconds).
    See Also:
      - Constant Field Values

  - ### NANOS_PER_UNIT

    public static final long NANOS_PER_UNIT
    Number of nanoseconds per Firebird unit of time (i.e. 100 microseconds, or 100,000 nanoseconds).
    See Also:
      - Constant Field Values

- ## Method Details

  - ### toModifiedJulianDate

    public static int toModifiedJulianDate(LocalDate localDate)
    Converts a local date to a Modified Julian Date.

    Firebird's `DATE` type uses Modified Julian Date to store dates. Current Firebird versions only support values in the range [0001-01-01, 9999-12-31] or [-678575, 2973483]; this method does not enforce this range. We leave that to the server to enforce, in case it changes in the future.

    Parameters:
      `localDate` - local date value
    Returns:
      Modified Julian Date value
    Throws:
      `ArithmeticException` - if the resulting Modified Julian Date is out of range of an `int`
    See Also:
      - `toModifiedJulianDate(LocalDate)`
      - `updateModifiedJulianDate(Temporal, int)`

  - ### fromModifiedJulianDate

    public static LocalDate fromModifiedJulianDate(int mjd)
    Converts a Modified Julian Date to the corresponding `LocalDate`.

    A Modified Julian Date is the number of days since 17 November 1858.

    Parameters:
      `mjd` - Modified Julian Date value
    Returns:
      local date corresponding to `mjd`
    See Also:
      - `toModifiedJulianDate(LocalDate)`
      - `updateModifiedJulianDate(Temporal, int)`

  - ### updateModifiedJulianDate

    public static <R extends Temporal> R updateModifiedJulianDate(R datetime, int mjd)
    Returns a copy of `datetime`, updated so its date is now set to the value corresponding to the Modified Julian Date `mjd`.
    Type Parameters:
      `R` - type of `datetime`
    Parameters:
      `datetime` - datetime value to modify
      `mjd` - Modified Julian Date value
    Returns:
      copy of the same type as `datetime`, with the date changed to match `mjd`
    See Also:
      - `fromModifiedJulianDate(int)`
      - `toModifiedJulianDate(LocalDate)`

  - ### toFbTimeUnits

    public static int toFbTimeUnits(LocalTime localTime)
    Converts a local time to Firebird time units (a.k.a. fractions, or 100 microseconds).
    Parameters:
      `localTime` - local time value
    Returns:
      number of 100 microseconds to represent `localTime`
    See Also:
      - `fromFbTimeUnits(int)`
      - `updateFbTimeUnits(Temporal, int)`

  - ### fromFbTimeUnits

    public static LocalTime fromFbTimeUnits(int timeUnits)
    Converts Firebird time units (a.k.a. fractions, or 100 microseconds) to a local time.
    Parameters:
      `timeUnits` - number of 100 microseconds
    Returns:
      local time
    See Also:
      - `toFbTimeUnits(LocalTime)`
      - `updateFbTimeUnits(Temporal, int)`

  - ### updateFbTimeUnits

    public static <R extends Temporal> R updateFbTimeUnits(R datetime, int timeUnits)
    Returns a copy of `datetime`, updated so its time is now set to the value corresponding to the Firebird time units (`timeUnits)`.
    Type Parameters:
      `R` - type of `datetime`
    Parameters:
      `datetime` - datetime value to modify
      `timeUnits` - number of 100 microseconds
    Returns:
      copy of the same type as `datetime`, with the time changed to match `timeUnits`
    See Also:
      - `fromFbTimeUnits(int)`
      - `toFbTimeUnits(LocalTime)`

  - ### parseIsoOrSqlTimestamp

    public static @Nullable LocalDateTime parseIsoOrSqlTimestamp(@Nullable String datetimeString)
    Parse a string as a ISO 8601 datetime (yyyy-mm-dd{T|t}hh:mm[:ss[.f...]] or as a SQL timestamp value (see `parseSqlTimestamp(String)`).
    Parameters:
      `datetimeString` - datetime value to parse
    Returns:
      local date time value, or `null` if `datetimeString` is `null`
    Throws:
      `DateTimeParseException` - if `datetimeString` cannot be parsed
    See Also:
      - `parseSqlTimestamp(String)`

  - ### parseSqlTimestamp

    public static @Nullable LocalDateTime parseSqlTimestamp(@Nullable String datetimeString)
    Parse a string as a SQL timestamp value (`yyyy-[m]m-[d]d hh:mm[:ss[.f...]]`).
    Parameters:
      `datetimeString` - datetime value to parse
    Returns:
      local date time value, or `null` if `datetimeString` is `null`
    Throws:
      `DateTimeParseException` - if `datetimeString` cannot be parsed
    See Also:
      - `parseIsoOrSqlTimestamp(String)`
      - `Timestamp.valueOf(String)`

  - ### formatSqlTimestamp

    public static @Nullable String formatSqlTimestamp(@Nullable LocalDateTime localDateTime)
    Formats a local date time as a SQL timestamp value (`yyyy-mm-dd hh:mm:ss[.f...]`).
    Parameters:
      `localDateTime` - local date time
    Returns:
      formatted string, or `null` if `localDateTime` is `null`

  - ### parseSqlTime

    public static @Nullable LocalTime parseSqlTime(@Nullable String timeString)
    Parse a string as a SQL time value (`hh:mm[:ss[.f...]]`).

    Contrary to `Time`, fractional seconds are supported.

    Parameters:
      `timeString` - time value to parse
    Returns:
      local time value, or `null` if `timeString` is `null`
    Throws:
      `DateTimeParseException` - if `timeString` cannot be parsed
    See Also:
      - `Time.valueOf(String)`

  - ### formatSqlTime

    public static @Nullable String formatSqlTime(@Nullable LocalTime localTime)
    Formats a local time as a SQL time value (`hh:mm:ss[.f...]`).
    Parameters:
      `localTime` - local time
    Returns:
      formatted string, or `null` if `localTime` is `null`

  - ### parseSqlDate

    public static @Nullable LocalDate parseSqlDate(@Nullable String dateString)
    Parse a string as a SQL date value (`yyyy-[m]m-[d]d`).
    Parameters:
      `dateString` - date value to parse
    Returns:
      local date value, or `null` if `dateString` is `null`
    Throws:
      `DateTimeParseException` - if `dateString` cannot be parsed
    See Also:
      - `Date.valueOf(String)`

  - ### formatSqlDate

    public static @Nullable String formatSqlDate(@Nullable LocalDate localDate)
    Formats a local date as a SQL date value (`yyyy-mm-dd`).
    Parameters:
      `localDate` - local date
    Returns:
      formatted string, or `null` if `localDate` is `null`