Package org.h2.util

# Class DateTimeUtils

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

public class DateTimeUtils extends 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
Modifier and Type
Field
Description
`static final int`
`EPOCH_DATE_VALUE`
Date value for 1970-01-01.
`static final long`
`MAX_DATE_VALUE`
Maximum possible date value.
`static final long`
`MILLIS_PER_DAY`
The number of milliseconds per day.
`static final long`
`MIN_DATE_VALUE`
Minimum possible date value.
`static final long`
`NANOS_PER_DAY`
The number of nanoseconds per day.
`static final long`
`NANOS_PER_HOUR`
The number of nanoseconds per hour.
`static final long`
`NANOS_PER_MINUTE`
The number of nanoseconds per minute.
`static final long`
`NANOS_PER_SECOND`
The number of nanoseconds per second.
`static final long`
`SECONDS_PER_DAY`
The number of seconds per day.
`static final int`
`SHIFT_MONTH`
The offset of month bits in date values.
`static final int`
`SHIFT_YEAR`
The offset of year bits in date values.

## Method Summary

Modifier and Type
Method
Description
`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 StringBuilder`
`appendDate(StringBuilder builder, long dateValue)`
Append a date to the string builder.
`static StringBuilder`
`appendTime(StringBuilder builder, long nanos)`
Append a time to the string builder.
`static StringBuilder`
`appendTimeZone(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, 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(String s, int start, int end)`
Parse a date string.
`static Value`
`parseTime(String s, CastDataProvider provider, boolean withTimeZone)`
Parses time value from the specified string.
`static long`
`parseTimeNanos(String s, int start, int end)`
Parse a time string.
`static Value`
`parseTimestamp(String s, CastDataProvider provider, boolean withTimeZone)`
Parses timestamp 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 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 Details

### 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 Details

### 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, 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(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:
  `IllegalArgumentException` - if there is a problem

### parseTimeNanos

public static long parseTimeNanos(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:
  `IllegalArgumentException` - if there is a problem

### parseTimestamp

public static Value parseTimestamp(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

### parseTime

public static Value parseTime(String s, CastDataProvider provider, boolean withTimeZone)
Parses time value from the specified string.

Parameters:
  `s` - string to parse
  `provider` - the cast information provider, or `null`
  `withTimeZone` - if `true` return `ValueTimeTimeZone` instead of `ValueTime`
Returns:
  parsed time

### 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 StringBuilder appendDate(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 StringBuilder appendTime(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 StringBuilder appendTimeZone(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 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