Package org.h2.util

Class 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).

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private DateTimeUtils()  
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      (package private) static long absoluteDay​(long y, int m, int d)
      Calculate the absolute day.
      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.
      (package private) static java.lang.StringBuilder appendNanos​(java.lang.StringBuilder builder, int nanos)
      Append nanoseconds of time, if any.
      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.
      (package private) static int parseNanos​(java.lang.String s, int start, int end)
      Parse nanoseconds.
      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
      • NORMAL_DAYS_PER_MONTH

        private static final int[] NORMAL_DAYS_PER_MONTH
    • Constructor Detail

      • DateTimeUtils

        private DateTimeUtils()
    • 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
      • parseNanos

        static int parseNanos​(java.lang.String s,
                              int start,
                              int end)
        Parse nanoseconds.
        Parameters:
        s - String to parse.
        start - Begin position at the string to read.
        end - End position at the string to read.
        Returns:
        Parsed nanoseconds.
      • 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)
      • 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
      • absoluteDay

        static long absoluteDay​(long y,
                                int m,
                                int d)
        Calculate the absolute day.
        Parameters:
        y - year
        m - month
        d - day
        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
      • appendNanos

        static java.lang.StringBuilder appendNanos​(java.lang.StringBuilder builder,
                                                   int nanos)
        Append nanoseconds of time, if any.
        Parameters:
        builder - string builder to append to
        nanos - nanoseconds of second
        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