org.h2.util

## Class DateTimeUtils

- java.lang.Object
- - org.h2.util.DateTimeUtils

    public class DateTimeUtils
    extends java.lang.Object

This utility class contains time conversion functions.

Date value: a bit field with bits for the year, month, and day. Absolute day: the day number (0 means 1970-01-01).

### Field Summary

Fields
`static int` `EPOCH_DATE_VALUE` Date value for 1970-01-01.
`static long` `MAX_DATE_VALUE` Maximum possible date value.
`static long` `MILLIS_PER_DAY` The number of milliseconds per day.
`static long` `MIN_DATE_VALUE` Minimum possible date value.
`static long` `NANOS_PER_DAY` The number of nanoseconds per day.
`static long` `NANOS_PER_HOUR` The number of nanoseconds per hour.
`static long` `NANOS_PER_MINUTE` The number of nanoseconds per minute.
`static long` `NANOS_PER_SECOND` The number of nanoseconds per second.
`static long` `SECONDS_PER_DAY` The number of seconds per day.
`static int` `SHIFT_MONTH` The offset of month bits in date values.
`static int` `SHIFT_YEAR` The offset of year bits in date values.

### Method Summary

All Methods Static Methods Concrete Methods
`static long` `absoluteDayFromDateValue(long dateValue)` Calculate the absolute day from an encoded date value.
`static long` `absoluteDayFromYear(long year)` Calculate the absolute day for a January, 1 of the specified year.
`static java.lang.StringBuilder` `appendDate(java.lang.StringBuilder builder, long dateValue)` Append a date to the string builder.
`static java.lang.StringBuilder` `appendTime(java.lang.StringBuilder builder, long nanos)` Append a time to the string builder.
`static java.lang.StringBuilder` `appendTimeZone(java.lang.StringBuilder builder, int tz)` Append a time zone to the string builder.
`static long` `convertScale(long nanosOfDay, int scale, long range)` Converts scale of nanoseconds.
`static ValueTimestampTimeZone` `currentTimestamp(TimeZoneProvider timeZone)` Returns current timestamp.
`static ValueTimestampTimeZone` `currentTimestamp(TimeZoneProvider timeZone, java.time.Instant now)` Returns current timestamp using the specified instant for its value.
`static long[]` `dateAndTimeFromValue(Value value, CastDataProvider provider)` Extracts date value and nanos of day from the specified value.
`static Value` `dateTimeToValue(Value original, long dateValue, long timeNanos)` Creates a new date-time value with the same type as original value.
`static long` `dateValue(long year, int month, int day)` Get the date value from a given date.
`static long` `dateValueFromAbsoluteDay(long absoluteDay)` Calculate the encoded date value from an absolute day.
`static long` `dateValueFromDenormalizedDate(long year, long month, int day)` Get the date value from a given denormalized date with possible out of range values of month and/or day.
`static long` `dateValueFromLocalSeconds(long localSeconds)` Convert a local seconds to an encoded date.
`static int` `dayFromDateValue(long x)` Get the day of month from a date value.
`static long` `decrementDateValue(long dateValue)` Return the previous date value.
`static int` `getDayOfWeek(long dateValue, int firstDayOfWeek)` Returns day of week.
`static int` `getDayOfWeekFromAbsolute(long absoluteValue, int firstDayOfWeek)` Get the day of the week from the absolute day value.
`static int` `getDayOfYear(long dateValue)` Returns number of day in year.
`static int` `getDaysInMonth(int year, int month)` Returns number of days in month.
`static long` `getEpochSeconds(long dateValue, long timeNanos, int offsetSeconds)` Calculates the seconds since epoch for the specified date value, nanoseconds since midnight, and time zone offset.
`static int` `getIsoDayOfWeek(long dateValue)` Returns ISO day of week.
`static int` `getIsoWeekOfYear(long dateValue)` Returns ISO number of week in year.
`static int` `getIsoWeekYear(long dateValue)` Returns ISO week year.
`static int` `getSundayDayOfWeek(long dateValue)` Returns day of week with Sunday as 1.
`static TimeZoneProvider` `getTimeZone()` Get the time zone provider for the default time zone.
`static int` `getWeekOfYear(long dateValue, int firstDayOfWeek, int minimalDaysInFirstWeek)` Returns number of week in year.
`static int` `getWeekYear(long dateValue, int firstDayOfWeek, int minimalDaysInFirstWeek)` Returns week year.
`static long` `getWeekYearAbsoluteStart(int weekYear, int firstDayOfWeek, int minimalDaysInFirstWeek)` Get absolute day of the first day in the week year.
`static long` `incrementDateValue(long dateValue)` Return the next date value.
`static boolean` `isValidDate(int year, int month, int day)` Verify if the specified date is valid.
`static int` `monthFromDateValue(long x)` Get the month from a date value.
`static long` `nanosFromLocalSeconds(long localSeconds)` Convert a time in seconds in local time to the nanoseconds since midnight.
`static long` `normalizeNanosOfDay(long nanos)` Calculate the normalized nanos of day.
`static long` `parseDateValue(java.lang.String s, int start, int end)` Parse a date string.
`static long` `parseTimeNanos(java.lang.String s, int start, int end)` Parse a time string.
`static Value` `parseTimestamp(java.lang.String s, CastDataProvider provider, boolean withTimeZone)` Parses timestamp value from the specified string.
`static ValueTimeTimeZone` `parseTimeWithTimeZone(java.lang.String s, CastDataProvider provider)` Parses TIME WITH TIME ZONE value from the specified string.
`static void` `resetCalendar()` Reset the cached calendar for default timezone, for example after changing the default timezone.
`static ValueTimestampTimeZone` `timestampTimeZoneAtOffset(long dateValue, long timeNanos, int oldOffset, int newOffset)` Moves timestamp with time zone to a new time zone.
`static java.lang.String` `timeZoneNameFromOffsetSeconds(int offsetSeconds)` Generates time zone name for the specified offset in seconds.
`static int` `yearFromDateValue(long x)` Get the year from a date value.

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

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

### Field Detail

#### MILLIS_PER_DAY

    public static final long MILLIS_PER_DAY

The number of milliseconds per day.

See Also:
  Constant Field Values

#### SECONDS_PER_DAY

    public static final long SECONDS_PER_DAY

The number of seconds per day.

See Also:
  Constant Field Values

#### NANOS_PER_SECOND

    public static final long NANOS_PER_SECOND

The number of nanoseconds per second.

See Also:
  Constant Field Values

#### NANOS_PER_MINUTE

    public static final long NANOS_PER_MINUTE

The number of nanoseconds per minute.

See Also:
  Constant Field Values

#### NANOS_PER_HOUR

    public static final long NANOS_PER_HOUR

The number of nanoseconds per hour.

See Also:
  Constant Field Values

#### NANOS_PER_DAY

    public static final long NANOS_PER_DAY

The number of nanoseconds per day.

See Also:
  Constant Field Values

#### SHIFT_YEAR

    public static final int SHIFT_YEAR

The offset of year bits in date values.

See Also:
  Constant Field Values

#### SHIFT_MONTH

    public static final int SHIFT_MONTH

The offset of month bits in date values.

See Also:
  Constant Field Values

#### EPOCH_DATE_VALUE

    public static final int EPOCH_DATE_VALUE

Date value for 1970-01-01.

See Also:
  Constant Field Values

#### MIN_DATE_VALUE

    public static final long MIN_DATE_VALUE

Minimum possible date value.

See Also:
  Constant Field Values

#### MAX_DATE_VALUE

    public static final long MAX_DATE_VALUE

Maximum possible date value.

See Also:
  Constant Field Values

### Method Detail

#### resetCalendar

    public static void resetCalendar()

Reset the cached calendar for default timezone, for example after changing the default timezone.

#### getTimeZone

    public static TimeZoneProvider getTimeZone()

Get the time zone provider for the default time zone.

Returns:
  the time zone provider for the default time zone

#### currentTimestamp

    public static ValueTimestampTimeZone currentTimestamp(TimeZoneProvider timeZone)

Returns current timestamp.

Parameters:
  `timeZone` - the time zone
Returns:
  current timestamp

#### currentTimestamp

    public static ValueTimestampTimeZone currentTimestamp(TimeZoneProvider timeZone,
                                                          java.time.Instant now)

Returns current timestamp using the specified instant for its value.

Parameters:
  `timeZone` - the time zone
  `now` - timestamp source, must be greater than or equal to 1970-01-01T00:00:00Z
Returns:
  current timestamp

#### parseDateValue

    public static long parseDateValue(java.lang.String s,
                                      int start,
                                      int end)

Parse a date string. The format is: [+|-]year-month-day or [+|-]yyyyMMdd.

Parameters:
  `s` - the string to parse
  `start` - the parse index start
  `end` - the parse index end
Returns:
  the date value
Throws:
  `java.lang.IllegalArgumentException` - if there is a problem

#### parseTimeNanos

    public static long parseTimeNanos(java.lang.String s,
                                      int start,
                                      int end)

Parse a time string. The format is: hour:minute[:second[.nanos]], hhmm[ss[.nanos]], or hour.minute.second[.nanos].

Parameters:
  `s` - the string to parse
  `start` - the parse index start
  `end` - the parse index end
Returns:
  the time in nanoseconds
Throws:
  `java.lang.IllegalArgumentException` - if there is a problem

#### parseTimestamp

    public static Value parseTimestamp(java.lang.String s,
                                       CastDataProvider provider,
                                       boolean withTimeZone)

Parses timestamp value from the specified string.

Parameters:
  `s` - string to parse
  `provider` - the cast information provider, may be `null` for Standard-compliant literals
  `withTimeZone` - if `true` return `ValueTimestampTimeZone` instead of `ValueTimestamp`
Returns:
  parsed timestamp

#### parseTimeWithTimeZone

    public static ValueTimeTimeZone parseTimeWithTimeZone(java.lang.String s,
                                                          CastDataProvider provider)

Parses TIME WITH TIME ZONE value from the specified string.

Parameters:
  `s` - string to parse
  `provider` - the cast information provider, or `null`
Returns:
  parsed time with time zone

#### getEpochSeconds

    public static long getEpochSeconds(long dateValue,
                                       long timeNanos,
                                       int offsetSeconds)

Calculates the seconds since epoch for the specified date value, nanoseconds since midnight, and time zone offset.

Parameters:
  `dateValue` - date value
  `timeNanos` - nanoseconds since midnight
  `offsetSeconds` - time zone offset in seconds
Returns:
  seconds since epoch in UTC

#### dateAndTimeFromValue

    public static long[] dateAndTimeFromValue(Value value,
                                              CastDataProvider provider)

Extracts date value and nanos of day from the specified value.

Parameters:
  `value` - value to extract fields from
  `provider` - the cast information provider
Returns:
  array with date value and nanos of day

#### dateTimeToValue

    public static Value dateTimeToValue(Value original,
                                        long dateValue,
                                        long timeNanos)

Creates a new date-time value with the same type as original value. If original value is a ValueTimestampTimeZone or ValueTimeTimeZone, returned value will have the same time zone offset as original value.

Parameters:
  `original` - original value
  `dateValue` - date value for the returned value
  `timeNanos` - nanos of day for the returned value
Returns:
  new value with specified date value and nanos of day

#### getDayOfWeek

    public static int getDayOfWeek(long dateValue,
                                   int firstDayOfWeek)

Returns day of week.

Parameters:
  `dateValue` - the date value
  `firstDayOfWeek` - first day of week, Monday as 1, Sunday as 7 or 0
Returns:
  day of week
See Also:
  `getIsoDayOfWeek(long)`

#### getDayOfWeekFromAbsolute

    public static int getDayOfWeekFromAbsolute(long absoluteValue,
                                               int firstDayOfWeek)

Get the day of the week from the absolute day value.

Parameters:
  `absoluteValue` - the absolute day
  `firstDayOfWeek` - the first day of the week
Returns:
  the day of week

#### getDayOfYear

    public static int getDayOfYear(long dateValue)

Returns number of day in year.

Parameters:
  `dateValue` - the date value
Returns:
  number of day in year

#### getIsoDayOfWeek

    public static int getIsoDayOfWeek(long dateValue)

Returns ISO day of week.

Parameters:
  `dateValue` - the date value
Returns:
  ISO day of week, Monday as 1 to Sunday as 7
See Also:
  `getSundayDayOfWeek(long)`

#### getIsoWeekOfYear

    public static int getIsoWeekOfYear(long dateValue)

Returns ISO number of week in year.

Parameters:
  `dateValue` - the date value
Returns:
  number of week in year
See Also:
  `getIsoWeekYear(long)`, `getWeekOfYear(long, int, int)`

#### getIsoWeekYear

    public static int getIsoWeekYear(long dateValue)

Returns ISO week year.

Parameters:
  `dateValue` - the date value
Returns:
  ISO week year
See Also:
  `getIsoWeekOfYear(long)`, `getWeekYear(long, int, int)`

#### getSundayDayOfWeek

    public static int getSundayDayOfWeek(long dateValue)

Returns day of week with Sunday as 1.

Parameters:
  `dateValue` - the date value
Returns:
  day of week, Sunday as 1 to Monday as 7
See Also:
  `getIsoDayOfWeek(long)`

#### getWeekOfYear

    public static int getWeekOfYear(long dateValue,
                                    int firstDayOfWeek,
                                    int minimalDaysInFirstWeek)

Returns number of week in year.

Parameters:
  `dateValue` - the date value
  `firstDayOfWeek` - first day of week, Monday as 1, Sunday as 7 or 0
  `minimalDaysInFirstWeek` - minimal days in first week of year
Returns:
  number of week in year
See Also:
  `getIsoWeekOfYear(long)`

#### getWeekYearAbsoluteStart

    public static long getWeekYearAbsoluteStart(int weekYear,
                                                int firstDayOfWeek,
                                                int minimalDaysInFirstWeek)

Get absolute day of the first day in the week year.

Parameters:
  `weekYear` - the week year
  `firstDayOfWeek` - first day of week, Monday as 1, Sunday as 7 or 0
  `minimalDaysInFirstWeek` - minimal days in first week of year
Returns:
  absolute day of the first day in the week year

#### getWeekYear

    public static int getWeekYear(long dateValue,
                                  int firstDayOfWeek,
                                  int minimalDaysInFirstWeek)

Returns week year.

Parameters:
  `dateValue` - the date value
  `firstDayOfWeek` - first day of week, Monday as 1, Sunday as 7 or 0
  `minimalDaysInFirstWeek` - minimal days in first week of year
Returns:
  week year
See Also:
  `getIsoWeekYear(long)`

#### getDaysInMonth

    public static int getDaysInMonth(int year,
                                     int month)

Returns number of days in month.

Parameters:
  `year` - the year
  `month` - the month
Returns:
  number of days in the specified month

#### isValidDate

    public static boolean isValidDate(int year,
                                      int month,
                                      int day)

Verify if the specified date is valid.

Parameters:
  `year` - the year
  `month` - the month (January is 1)
  `day` - the day (1 is the first of the month)
Returns:
  true if it is valid

#### yearFromDateValue

    public static int yearFromDateValue(long x)

Get the year from a date value.

Parameters:
  `x` - the date value
Returns:
  the year

#### monthFromDateValue

    public static int monthFromDateValue(long x)

Get the month from a date value.

Parameters:
  `x` - the date value
Returns:
  the month (1..12)

#### dayFromDateValue

    public static int dayFromDateValue(long x)

Get the day of month from a date value.

Parameters:
  `x` - the date value
Returns:
  the day (1..31)

#### dateValue

    public static long dateValue(long year,
                                 int month,
                                 int day)

Get the date value from a given date.

Parameters:
  `year` - the year
  `month` - the month (1..12)
  `day` - the day (1..31)
Returns:
  the date value

#### dateValueFromDenormalizedDate

    public static long dateValueFromDenormalizedDate(long year,
                                                     long month,
                                                     int day)

Get the date value from a given denormalized date with possible out of range values of month and/or day. Used after addition or subtraction month or years to (from) it to get a valid date.

Parameters:
  `year` - the year
  `month` - the month, if out of range month and year will be normalized
  `day` - the day of the month, if out of range it will be saturated
Returns:
  the date value

#### dateValueFromLocalSeconds

    public static long dateValueFromLocalSeconds(long localSeconds)

Convert a local seconds to an encoded date.

Parameters:
  `localSeconds` - the seconds since 1970-01-01
Returns:
  the date value

#### nanosFromLocalSeconds

    public static long nanosFromLocalSeconds(long localSeconds)

Convert a time in seconds in local time to the nanoseconds since midnight.

Parameters:
  `localSeconds` - the seconds since 1970-01-01
Returns:
  the nanoseconds

#### normalizeNanosOfDay

    public static long normalizeNanosOfDay(long nanos)

Calculate the normalized nanos of day.

Parameters:
  `nanos` - the nanoseconds (may be negative or larger than one day)
Returns:
  the nanos of day within a day

#### absoluteDayFromYear

    public static long absoluteDayFromYear(long year)

Calculate the absolute day for a January, 1 of the specified year.

Parameters:
  `year` - the year
Returns:
  the absolute day

#### absoluteDayFromDateValue

    public static long absoluteDayFromDateValue(long dateValue)

Calculate the absolute day from an encoded date value.

Parameters:
  `dateValue` - the date value
Returns:
  the absolute day

#### dateValueFromAbsoluteDay

    public static long dateValueFromAbsoluteDay(long absoluteDay)

Calculate the encoded date value from an absolute day.

Parameters:
  `absoluteDay` - the absolute day
Returns:
  the date value

#### incrementDateValue

    public static long incrementDateValue(long dateValue)

Return the next date value.

Parameters:
  `dateValue` - the date value
Returns:
  the next date value

#### decrementDateValue

    public static long decrementDateValue(long dateValue)

Return the previous date value.

Parameters:
  `dateValue` - the date value
Returns:
  the previous date value

#### appendDate

    public static java.lang.StringBuilder appendDate(java.lang.StringBuilder builder,
                                                     long dateValue)

Append a date to the string builder.

Parameters:
  `builder` - the target string builder
  `dateValue` - the date value
Returns:
  the specified string builder

#### appendTime

    public static java.lang.StringBuilder appendTime(java.lang.StringBuilder builder,
                                                     long nanos)

Append a time to the string builder.

Parameters:
  `builder` - the target string builder
  `nanos` - the time in nanoseconds
Returns:
  the specified string builder

#### appendTimeZone

    public static java.lang.StringBuilder appendTimeZone(java.lang.StringBuilder builder,
                                                         int tz)

Append a time zone to the string builder.

Parameters:
  `builder` - the target string builder
  `tz` - the time zone offset in seconds
Returns:
  the specified string builder

#### timeZoneNameFromOffsetSeconds

    public static java.lang.String timeZoneNameFromOffsetSeconds(int offsetSeconds)

Generates time zone name for the specified offset in seconds.

Parameters:
  `offsetSeconds` - time zone offset in seconds
Returns:
  time zone name

#### convertScale

    public static long convertScale(long nanosOfDay,
                                    int scale,
                                    long range)

Converts scale of nanoseconds.

Parameters:
  `nanosOfDay` - nanoseconds of day
  `scale` - fractional seconds precision
  `range` - the allowed range of values (0..range-1)
Returns:
  scaled value

#### timestampTimeZoneAtOffset

    public static ValueTimestampTimeZone timestampTimeZoneAtOffset(long dateValue,
                                                                   long timeNanos,
                                                                   int oldOffset,
                                                                   int newOffset)

Moves timestamp with time zone to a new time zone.

Parameters:
  `dateValue` - the date value
  `timeNanos` - the nanoseconds since midnight
  `oldOffset` - old offset
  `newOffset` - new offset
Returns:
  timestamp with time zone with new offset