Package org.postgresql.jdbc

# Class TimestampUtils

java.lang.Object
org.postgresql.jdbc.TimestampUtils

public class TimestampUtils extends Object
Misc utils for handling time and date values.

## Constructor Summary

Constructors
Constructor
Description
`TimestampUtils(boolean usesDouble, Provider<TimeZone> timeZoneProvider)`

## Method Summary

Modifier and Type
Method
Description
`Date`
`convertToDate(long millis, @Nullable TimeZone tz)`
Extracts the date part from a timestamp.
`Time`
`convertToTime(long millis, TimeZone tz)`
Extracts the time part from a timestamp.
`Calendar`
`getSharedCalendar(@Nullable TimeZone timeZone)`
Get a shared calendar, applying the supplied time zone or the default time zone if null.
`boolean`
`hasFastDefaultTimeZone()`
`static TimeZone`
`parseBackendTimeZone(String timeZone)`
Converts backend's TimeZone parameter to java format.
`String`
`timeToString(Date time, boolean withTimeZone)`
Returns the given time value as String matching what the current postgresql server would send in text mode.
`void`
`toBinDate(@Nullable TimeZone tz, byte[] bytes, Date value)`
Converts the SQL Date to binary representation for `Oid.DATE`.
`@PolyNull Date`
`toDate(@Nullable Calendar cal, @PolyNull String s)`
`Date`
`toDateBin(@Nullable TimeZone tz, byte[] bytes)`
Returns the SQL Date object matching the given bytes with `Oid.DATE`.
`LocalDate`
`toLocalDateBin(byte[] bytes)`
Returns the local date time object matching the given bytes with `Oid.DATE` or `Oid.TIMESTAMP`.
`@PolyNull LocalDateTime`
`toLocalDateTime(@PolyNull String s)`
Parse a string and return a LocalDateTime representing its value.
`LocalDateTime`
`toLocalDateTimeBin(byte[] bytes)`
Returns the local date time object matching the given bytes with `Oid.TIMESTAMP` or `Oid.TIMESTAMPTZ`.
`@PolyNull LocalTime`
`toLocalTime(@PolyNull String s)`
Parse a string and return a LocalTime representing its value.
`LocalTime`
`toLocalTimeBin(byte[] bytes)`
Returns the SQL Time object matching the given bytes with `Oid.TIME`.
`@PolyNull OffsetDateTime`
`toOffsetDateTime(@PolyNull String s)`
Parse a string and return a OffsetDateTime representing its value.
`OffsetDateTime`
`toOffsetDateTime(Time t)`
Deprecated.
was used internally, and not used anymore
`OffsetDateTime`
`toOffsetDateTimeBin(byte[] bytes)`
Returns the offset date time object matching the given bytes with Oid#TIMESTAMPTZ.
`@PolyNull OffsetTime`
`toOffsetTime(@PolyNull String s)`
Parse a string and return a OffsetTime representing its value.
`OffsetTime`
`toOffsetTimeBin(byte[] bytes)`
Returns the offset time object matching the given bytes with Oid#TIMETZ or Oid#TIME.
`String`
`toString(@Nullable Calendar cal, Date x)`
`String`
`toString(@Nullable Calendar cal, Date x, boolean withTimeZone)`
`String`
`toString(@Nullable Calendar cal, Time x)`
`String`
`toString(@Nullable Calendar cal, Time x, boolean withTimeZone)`
`String`
`toString(@Nullable Calendar cal, Timestamp x)`
`String`
`toString(@Nullable Calendar cal, Timestamp x, boolean withTimeZone)`
`String`
`toString(LocalDate localDate)`
`String`
`toString(LocalDateTime localDateTime)`
Formats `LocalDateTime` to be sent to the backend, thus it adds time zone.
`String`
`toString(LocalTime localTime)`
`String`
`toString(OffsetDateTime offsetDateTime)`
`String`
`toString(OffsetTime offsetTime)`
`@PolyNull Time`
`toTime(@Nullable Calendar cal, @PolyNull String s)`
`Time`
`toTimeBin(@Nullable TimeZone tz, byte[] bytes)`
Returns the SQL Time object matching the given bytes with `Oid.TIME` or `Oid.TIMETZ`.
`@PolyNull Timestamp`
`toTimestamp(@Nullable Calendar cal, @PolyNull String s)`
Parse a string and return a timestamp representing its value.
`Timestamp`
`toTimestampBin(@Nullable TimeZone tz, byte[] bytes, boolean timestamptz)`
Returns the SQL Timestamp object matching the given bytes with `Oid.TIMESTAMP` or `Oid.TIMESTAMPTZ`.

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

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

## Constructor Details

### TimestampUtils

public TimestampUtils(boolean usesDouble, Provider<TimeZone> timeZoneProvider)

## Method Details

### toTimestamp

public @PolyNull Timestamp toTimestamp(@Nullable Calendar cal, @PolyNull String s) throws SQLException
Parse a string and return a timestamp representing its value.

Parameters:
  `cal` - calendar to be used to parse the input string
  `s` - The ISO formated date string to parse.
Returns:
  null if s is null or a timestamp of the parsed string s.
Throws:
  `SQLException` - if there is a problem parsing s.

### toLocalTime

public @PolyNull LocalTime toLocalTime(@PolyNull String s) throws SQLException
Parse a string and return a LocalTime representing its value.

Parameters:
  `s` - The ISO formated time string to parse.
Returns:
  null if s is null or a LocalTime of the parsed string s.
Throws:
  `SQLException` - if there is a problem parsing s.

### toOffsetTimeBin

public OffsetTime toOffsetTimeBin(byte[] bytes) throws PSQLException
Returns the offset time object matching the given bytes with Oid#TIMETZ or Oid#TIME.

Parameters:
  `bytes` - The binary encoded TIMETZ/TIME value.
Returns:
  The parsed offset time object.
Throws:
  `PSQLException` - If binary format could not be parsed.

### toOffsetTime

public @PolyNull OffsetTime toOffsetTime(@PolyNull String s) throws SQLException
Parse a string and return a OffsetTime representing its value.

Parameters:
  `s` - The ISO formated time string to parse.
Returns:
  null if s is null or a OffsetTime of the parsed string s.
Throws:
  `SQLException` - if there is a problem parsing s.

### toLocalDateTime

public @PolyNull LocalDateTime toLocalDateTime(@PolyNull String s) throws SQLException
Parse a string and return a LocalDateTime representing its value.

Parameters:
  `s` - The ISO formated date string to parse.
Returns:
  null if s is null or a LocalDateTime of the parsed string s.
Throws:
  `SQLException` - if there is a problem parsing s.

### toOffsetDateTime

@Deprecated public OffsetDateTime toOffsetDateTime(Time t)
Deprecated.
was used internally, and not used anymore
Returns the offset date time object matching the given bytes with Oid#TIMETZ. Not used internally anymore, function is here to retain compatibility with previous versions

Parameters:
  `t` - the time value
Returns:
  the matching offset date time

### toOffsetDateTime

public @PolyNull OffsetDateTime toOffsetDateTime(@PolyNull String s) throws SQLException
Parse a string and return a OffsetDateTime representing its value.

Parameters:
  `s` - The ISO formatted date string to parse.
Returns:
  null if s is null or a OffsetDateTime of the parsed string s.
Throws:
  `SQLException` - if there is a problem parsing s.

### toOffsetDateTimeBin

public OffsetDateTime toOffsetDateTimeBin(byte[] bytes) throws PSQLException
Returns the offset date time object matching the given bytes with Oid#TIMESTAMPTZ.

Parameters:
  `bytes` - The binary encoded local date time value.
Returns:
  The parsed local date time object.
Throws:
  `PSQLException` - If binary format could not be parsed.

### toTime

public @PolyNull Time toTime(@Nullable Calendar cal, @PolyNull String s) throws SQLException

Throws:
  `SQLException`

### toDate

public @PolyNull Date toDate(@Nullable Calendar cal, @PolyNull String s) throws SQLException

Throws:
  `SQLException`

### getSharedCalendar

public Calendar getSharedCalendar(@Nullable TimeZone timeZone)
Get a shared calendar, applying the supplied time zone or the default time zone if null.

Parameters:
  `timeZone` - time zone to be set for the calendar
Returns:
  The shared calendar.

### toString

public String toString(@Nullable Calendar cal, Timestamp x)

### toString

public String toString(@Nullable Calendar cal, Timestamp x, boolean withTimeZone)

### toString

public String toString(@Nullable Calendar cal, Date x)

### toString

public String toString(@Nullable Calendar cal, Date x, boolean withTimeZone)

### toString

public String toString(@Nullable Calendar cal, Time x)

### toString

public String toString(@Nullable Calendar cal, Time x, boolean withTimeZone)

### toString

public String toString(LocalDate localDate)

### toString

public String toString(LocalTime localTime)

### toString

public String toString(OffsetTime offsetTime)

### toString

public String toString(OffsetDateTime offsetDateTime)

### toString

public String toString(LocalDateTime localDateTime)
Formats `LocalDateTime` to be sent to the backend, thus it adds time zone. Do not use this method in `ResultSet.getString(int)`

Parameters:
  `localDateTime` - The local date to format as a String
Returns:
  The formatted local date

### toDateBin

public Date toDateBin(@Nullable TimeZone tz, byte[] bytes) throws PSQLException
Returns the SQL Date object matching the given bytes with `Oid.DATE`.

Parameters:
  `tz` - The timezone used.
  `bytes` - The binary encoded date value.
Returns:
  The parsed date object.
Throws:
  `PSQLException` - If binary format could not be parsed.

### hasFastDefaultTimeZone

public boolean hasFastDefaultTimeZone()

### toTimeBin

public Time toTimeBin(@Nullable TimeZone tz, byte[] bytes) throws PSQLException
Returns the SQL Time object matching the given bytes with `Oid.TIME` or `Oid.TIMETZ`.

Parameters:
  `tz` - The timezone used when received data is `Oid.TIME`, ignored if data already contains `Oid.TIMETZ`.
  `bytes` - The binary encoded time value.
Returns:
  The parsed time object.
Throws:
  `PSQLException` - If binary format could not be parsed.

### toLocalTimeBin

public LocalTime toLocalTimeBin(byte[] bytes) throws PSQLException
Returns the SQL Time object matching the given bytes with `Oid.TIME`.

Parameters:
  `bytes` - The binary encoded time value.
Returns:
  The parsed time object.
Throws:
  `PSQLException` - If binary format could not be parsed.

### toTimestampBin

public Timestamp toTimestampBin(@Nullable TimeZone tz, byte[] bytes, boolean timestamptz) throws PSQLException
Returns the SQL Timestamp object matching the given bytes with `Oid.TIMESTAMP` or `Oid.TIMESTAMPTZ`.

Parameters:
  `tz` - The timezone used when received data is `Oid.TIMESTAMP`, ignored if data already contains `Oid.TIMESTAMPTZ`.
  `bytes` - The binary encoded timestamp value.
  `timestamptz` - True if the binary is in GMT.
Returns:
  The parsed timestamp object.
Throws:
  `PSQLException` - If binary format could not be parsed.

### toLocalDateTimeBin

public LocalDateTime toLocalDateTimeBin(byte[] bytes) throws PSQLException
Returns the local date time object matching the given bytes with `Oid.TIMESTAMP` or `Oid.TIMESTAMPTZ`.

Parameters:
  `bytes` - The binary encoded local date time value.
Returns:
  The parsed local date time object.
Throws:
  `PSQLException` - If binary format could not be parsed.

### toLocalDateBin

public LocalDate toLocalDateBin(byte[] bytes) throws PSQLException
Returns the local date time object matching the given bytes with `Oid.DATE` or `Oid.TIMESTAMP`.

Parameters:
  `bytes` - The binary encoded local date value.
Returns:
  The parsed local date object.
Throws:
  `PSQLException` - If binary format could not be parsed.

### convertToDate

public Date convertToDate(long millis, @Nullable TimeZone tz)
Extracts the date part from a timestamp.

Parameters:
  `millis` - The timestamp from which to extract the date.
  `tz` - The time zone of the date.
Returns:
  The extracted date.

### convertToTime

public Time convertToTime(long millis, TimeZone tz)
Extracts the time part from a timestamp. This method ensures the date part of output timestamp looks like 1970-01-01 in given timezone.

Parameters:
  `millis` - The timestamp from which to extract the time.
  `tz` - timezone to use.
Returns:
  The extracted time.

### timeToString

public String timeToString(Date time, boolean withTimeZone)
Returns the given time value as String matching what the current postgresql server would send in text mode.

Parameters:
  `time` - time value
  `withTimeZone` - whether timezone should be added
Returns:
  given time value as String

### toBinDate

public void toBinDate(@Nullable TimeZone tz, byte[] bytes, Date value) throws PSQLException
Converts the SQL Date to binary representation for `Oid.DATE`.

Parameters:
  `tz` - The timezone used.
  `bytes` - The binary encoded date value.
  `value` - value
Throws:
  `PSQLException` - If binary format could not be parsed.

### parseBackendTimeZone

public static TimeZone parseBackendTimeZone(String timeZone)
Converts backend's TimeZone parameter to java format. Notable difference: backend's gmt-3 is GMT+03 in Java.

Parameters:
  `timeZone` - time zone to use
Returns:
  java TimeZone