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`