Package org.apache.calcite.avatica.util

Class DateTimeUtils

  • public class DateTimeUtils
extends java.lang.Object
    Utility functions for datetime types: date, time, timestamp.

    Used by the JDBC driver.

    TODO: review methods for performance. Due to allocations required, it may be preferable to introduce a "formatter" with the required state.

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private DateTimeUtils()  

    • Method Summary

      All Methods Static Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      static int addMonths​(int date, int m)
      Adds a given number of months to a date, represented as the number of days since the epoch.
      static long addMonths​(long timestamp, int m)
      Adds a given number of months to a timestamp, represented as the number of milliseconds since the epoch.
      static java.util.Calendar calendar()
      Creates an instance of Calendar in the root locale and UTC time zone.
      static void checkDateFormat​(java.lang.String pattern)
      Checks if the date/time format is valid
      static int dateStringToUnixDate​(java.lang.String s)  
      static int digitCount​(int v)  
      private static long firstMondayOfFirstWeek​(int year)
      Returns the first day of the first week of a year.
      static long floorDiv​(long x, long y)
      Divide, rounding towards negative infinity.
      static long floorMod​(long x, long y)
      Modulo, always returning a non-negative result.
      private static void fraction​(java.lang.StringBuilder buf, int scale, long ms)  
      private static int getIso8601WeekNumber​(int julian, int year, int month, int day)
      Returns the ISO-8601 week number based on year, month, day.
      static java.util.TimeZone getTimeZone​(java.util.Calendar cal)
      Gets the active time zone based on a Calendar argument
      private static void int2​(java.lang.StringBuilder buf, int i)  
      private static void int4​(java.lang.StringBuilder buf, int i)  
      static java.lang.String intervalDayTimeToString​(long v, TimeUnitRange range, int scale)  
      static java.lang.String intervalYearMonthToString​(int v, TimeUnitRange range)  
      static boolean isOffsetDateTime​(java.lang.Object o)
      Returns whether a value is an OffsetDateTime.
      private static int julianDateFloor​(TimeUnitRange range, int julian, boolean floor)  
      private static int julianExtract​(TimeUnitRange range, int julian)  
      private static void julianToString​(java.lang.StringBuilder buf, int julian)  
      private static int lastDay​(int y, int m)  
      static java.text.SimpleDateFormat newDateFormat​(java.lang.String format)
      Creates a new date formatter with Farrago specific options.
      static java.lang.StringBuilder number​(java.lang.StringBuilder buf, int v, int n)  
      static java.lang.String offsetDateTimeValue​(java.lang.Object o)
      Returns the value of a OffsetDateTime as a string.
      static java.util.Calendar parseDateFormat​(java.lang.String s, java.lang.String pattern, java.util.TimeZone tz)
      Deprecated.
      static java.util.Calendar parseDateFormat​(java.lang.String s, java.text.DateFormat dateFormat, java.util.TimeZone tz)
      Parses a string using SimpleDateFormat and a given pattern.
      private static java.util.Calendar parseDateFormat​(java.lang.String s, java.text.DateFormat dateFormat, java.util.TimeZone tz, java.text.ParsePosition pp)
      Parses a string using SimpleDateFormat and a given pattern.
      private static int parseFraction​(java.lang.String v, int multiplier)
      Parses a fraction, multiplying the first character by multiplier, the second character by multiplier / 10, the third character by multiplier / 100, and so forth.
      static DateTimeUtils.PrecisionTime parsePrecisionDateTimeLiteral​(java.lang.String s, java.lang.String pattern, java.util.TimeZone tz)
      Deprecated.
      static DateTimeUtils.PrecisionTime parsePrecisionDateTimeLiteral​(java.lang.String s, java.text.DateFormat dateFormat, java.util.TimeZone tz, int maxPrecision)
      Parses a string using SimpleDateFormat and a given pattern, and if present, parses a fractional seconds component.
      static long powerX​(long a, long b)
      Cheap, unsafe, long power.
      static long resetDate​(long timestamp)
      Resets to epoch (1970-01-01) the "date" part of a timestamp.
      static long resetTime​(long timestamp)
      Resets to zero the "time" part of a timestamp.
      private static int roundUp​(int dividend, int divisor)  
      private static long roundUp​(long dividend, long divisor)
      Rounds a dividend to the nearest divisor.
      static int subtractMonths​(int date0, int date1)
      Finds the number of months between two dates, each represented as the number of days since the epoch.
      static int subtractMonths​(long t0, long t1)  
      static long timestampStringToUnixDate​(java.lang.String s)  
      static int timeStringToUnixDate​(java.lang.String v)  
      static int timeStringToUnixDate​(java.lang.String v, int start)  
      static long unixDateCeil​(TimeUnitRange range, long date)  
      static long unixDateExtract​(TimeUnitRange range, long date)  
      static long unixDateFloor​(TimeUnitRange range, long date)  
      static java.lang.String unixDateToString​(int date)
      Helper for CAST({date} AS VARCHAR(n)).
      private static void unixDateToString​(java.lang.StringBuilder buf, int date)  
      static int unixTimeExtract​(TimeUnitRange range, int time)
      Extracts a time unit from a time value (milliseconds since midnight).
      static long unixTimestamp​(int year, int month, int day, int hour, int minute, int second)  
      static long unixTimestampCeil​(TimeUnitRange range, long timestamp)  
      static int unixTimestampExtract​(TimeUnitRange range, long timestamp)
      Extracts a time unit from a UNIX date (milliseconds since epoch).
      static long unixTimestampFloor​(TimeUnitRange range, long timestamp)  
      static java.lang.String unixTimestampToString​(long timestamp)
      Helper for CAST({timestamp} AS VARCHAR(n)).
      static java.lang.String unixTimestampToString​(long timestamp, int precision)  
      static java.lang.String unixTimeToString​(int time)
      Helper for CAST({timestamp} AS VARCHAR(n)).
      static java.lang.String unixTimeToString​(int time, int precision)  
      private static void unixTimeToString​(java.lang.StringBuilder buf, int time, int precision)  
      static int ymdToJulian​(int year, int month, int day)  
      static int ymdToUnixDate​(int year, int month, int day)  

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • EPOCH_JULIAN

        public static final int EPOCH_JULIAN
        The julian date of the epoch, 1970-01-01.
        See Also:
        Constant Field Values

      • DATE_FORMAT_STRING

        public static final java.lang.String DATE_FORMAT_STRING
        The SimpleDateFormat string for ISO dates, "yyyy-MM-dd".
        See Also:
        Constant Field Values

      • TIME_FORMAT_STRING

        public static final java.lang.String TIME_FORMAT_STRING
        The SimpleDateFormat string for ISO times, "HH:mm:ss".
        See Also:
        Constant Field Values

      • TIMESTAMP_FORMAT_STRING

        public static final java.lang.String TIMESTAMP_FORMAT_STRING
        The SimpleDateFormat string for ISO timestamps, "yyyy-MM-dd HH:mm:ss".
        See Also:
        Constant Field Values

      • GMT_ZONE

        @Deprecated
public static final java.util.TimeZone GMT_ZONE
        Deprecated.
        Use UTC_ZONE
        The GMT time zone.

      • UTC_ZONE

        public static final java.util.TimeZone UTC_ZONE
        The UTC time zone.

      • DEFAULT_ZONE

        public static final java.util.TimeZone DEFAULT_ZONE
        The Java default time zone.

      • MILLIS_PER_SECOND

        public static final long MILLIS_PER_SECOND
        The number of milliseconds in a second.
        See Also:
        Constant Field Values

      • MILLIS_PER_MINUTE

        public static final long MILLIS_PER_MINUTE
        The number of milliseconds in a minute.
        See Also:
        Constant Field Values

      • MILLIS_PER_HOUR

        public static final long MILLIS_PER_HOUR
        The number of milliseconds in an hour.
        See Also:
        Constant Field Values

      • MILLIS_PER_DAY

        public static final long MILLIS_PER_DAY
        The number of milliseconds in a day.

        This is the modulo 'mask' used when converting TIMESTAMP values to DATE and TIME values.

        See Also:
        Constant Field Values

      • SECONDS_PER_DAY

        public static final long SECONDS_PER_DAY
        The number of seconds in a day.
        See Also:
        Constant Field Values

      • ZERO_CALENDAR

        public static final java.util.Calendar ZERO_CALENDAR
        Calendar set to the epoch (1970-01-01 00:00:00 UTC). Useful for initializing other values. Calendars are not immutable, so be careful not to screw up this object for everyone else.

    • Constructor Detail

      • DateTimeUtils

        private DateTimeUtils()

    • Method Detail

      • parseDateFormat

        private static java.util.Calendar parseDateFormat​(java.lang.String s,
                                                  java.text.DateFormat dateFormat,
                                                  java.util.TimeZone tz,
                                                  java.text.ParsePosition pp)
        Parses a string using SimpleDateFormat and a given pattern. This method parses a string at the specified parse position and if successful, updates the parse position to the index after the last character used. The parsing is strict and requires months to be less than 12, days to be less than 31, etc.
        Parameters:
        s - string to be parsed
        dateFormat - Date format
        tz - time zone in which to interpret string. Defaults to the Java default time zone
        pp - position to start parsing from
        Returns:
        a Calendar initialized with the parsed value, or null if parsing failed. If returned, the Calendar is configured to the GMT time zone.

      • parseDateFormat

        @Deprecated
public static java.util.Calendar parseDateFormat​(java.lang.String s,
                                                 java.lang.String pattern,
                                                 java.util.TimeZone tz)
        Deprecated.

      • parseDateFormat

        public static java.util.Calendar parseDateFormat​(java.lang.String s,
                                                 java.text.DateFormat dateFormat,
                                                 java.util.TimeZone tz)
        Parses a string using SimpleDateFormat and a given pattern. The entire string must match the pattern specified.
        Parameters:
        s - string to be parsed
        dateFormat - Date format
        tz - time zone in which to interpret string. Defaults to the Java default time zone
        Returns:
        a Calendar initialized with the parsed value, or null if parsing failed. If returned, the Calendar is configured to the UTC time zone.

      • parsePrecisionDateTimeLiteral

        @Deprecated
public static DateTimeUtils.PrecisionTime parsePrecisionDateTimeLiteral​(java.lang.String s,
                                                                        java.lang.String pattern,
                                                                        java.util.TimeZone tz)
        Deprecated.

      • parsePrecisionDateTimeLiteral

        public static DateTimeUtils.PrecisionTime parsePrecisionDateTimeLiteral​(java.lang.String s,
                                                                        java.text.DateFormat dateFormat,
                                                                        java.util.TimeZone tz,
                                                                        int maxPrecision)
        Parses a string using SimpleDateFormat and a given pattern, and if present, parses a fractional seconds component. The fractional seconds component must begin with a decimal point ('.') followed by numeric digits. The precision is rounded to a maximum of 3 digits of fractional seconds precision (to obtain milliseconds).
        Parameters:
        s - string to be parsed
        dateFormat - Date format
        tz - time zone in which to interpret string. Defaults to the local time zone
        Returns:
        a PrecisionTime initialized with the parsed value, or null if parsing failed. The PrecisionTime contains a GMT Calendar and a precision.

      • getTimeZone

        public static java.util.TimeZone getTimeZone​(java.util.Calendar cal)
        Gets the active time zone based on a Calendar argument

      • checkDateFormat

        public static void checkDateFormat​(java.lang.String pattern)
        Checks if the date/time format is valid
        Parameters:
        pattern - SimpleDateFormat pattern
        Throws:
        java.lang.IllegalArgumentException - if the given pattern is invalid

      • newDateFormat

        public static java.text.SimpleDateFormat newDateFormat​(java.lang.String format)
        Creates a new date formatter with Farrago specific options. Farrago parsing is strict and does not allow values such as day 0, month 13, etc.
        Parameters:
        format - SimpleDateFormat pattern

      • unixTimestampToString

        public static java.lang.String unixTimestampToString​(long timestamp)
        Helper for CAST({timestamp} AS VARCHAR(n)).

      • unixTimestampToString

        public static java.lang.String unixTimestampToString​(long timestamp,
                                                     int precision)

      • unixTimeToString

        public static java.lang.String unixTimeToString​(int time)
        Helper for CAST({timestamp} AS VARCHAR(n)).

      • unixTimeToString

        public static java.lang.String unixTimeToString​(int time,
                                                int precision)

      • unixTimeToString

        private static void unixTimeToString​(java.lang.StringBuilder buf,
                                     int time,
                                     int precision)

      • int2

        private static void int2​(java.lang.StringBuilder buf,
                         int i)

      • int4

        private static void int4​(java.lang.StringBuilder buf,
                         int i)

      • unixDateToString

        public static java.lang.String unixDateToString​(int date)
        Helper for CAST({date} AS VARCHAR(n)).

      • unixDateToString

        private static void unixDateToString​(java.lang.StringBuilder buf,
                                     int date)

      • julianToString

        private static void julianToString​(java.lang.StringBuilder buf,
                                   int julian)

      • intervalYearMonthToString

        public static java.lang.String intervalYearMonthToString​(int v,
                                                         TimeUnitRange range)

      • number

        public static java.lang.StringBuilder number​(java.lang.StringBuilder buf,
                                             int v,
                                             int n)

      • digitCount

        public static int digitCount​(int v)

      • roundUp

        private static int roundUp​(int dividend,
                           int divisor)

      • powerX

        public static long powerX​(long a,
                          long b)
        Cheap, unsafe, long power. power(2, 3) returns 8.

      • intervalDayTimeToString

        public static java.lang.String intervalDayTimeToString​(long v,
                                                       TimeUnitRange range,
                                                       int scale)

      • roundUp

        private static long roundUp​(long dividend,
                            long divisor)
        Rounds a dividend to the nearest divisor. For example roundUp(31, 10) yields 30; roundUp(37, 10) yields 40.
        Parameters:
        dividend - Number to be divided
        divisor - Number to divide by
        Returns:
        Rounded dividend

      • fraction

        private static void fraction​(java.lang.StringBuilder buf,
                             int scale,
                             long ms)

      • dateStringToUnixDate

        public static int dateStringToUnixDate​(java.lang.String s)

      • timeStringToUnixDate

        public static int timeStringToUnixDate​(java.lang.String v)

      • timeStringToUnixDate

        public static int timeStringToUnixDate​(java.lang.String v,
                                       int start)

      • parseFraction

        private static int parseFraction​(java.lang.String v,
                                 int multiplier)
        Parses a fraction, multiplying the first character by multiplier, the second character by multiplier / 10, the third character by multiplier / 100, and so forth.

        For example, parseFraction("1234", 100) yields 123.

      • timestampStringToUnixDate

        public static long timestampStringToUnixDate​(java.lang.String s)

      • unixDateExtract

        public static long unixDateExtract​(TimeUnitRange range,
                                   long date)

      • julianExtract

        private static int julianExtract​(TimeUnitRange range,
                                 int julian)

      • firstMondayOfFirstWeek

        private static long firstMondayOfFirstWeek​(int year)
        Returns the first day of the first week of a year. Per ISO-8601 it is the Monday of the week that contains Jan 4, or equivalently, it is a Monday between Dec 29 and Jan 4. Sometimes it is in the year before the given year.

      • getIso8601WeekNumber

        private static int getIso8601WeekNumber​(int julian,
                                        int year,
                                        int month,
                                        int day)
        Returns the ISO-8601 week number based on year, month, day. Per ISO-8601 it is the Monday of the week that contains Jan 4, or equivalently, it is a Monday between Dec 29 and Jan 4. Sometimes it is in the year before the given year, sometimes after.

      • unixTimestampExtract

        public static int unixTimestampExtract​(TimeUnitRange range,
                                       long timestamp)
        Extracts a time unit from a UNIX date (milliseconds since epoch).

      • unixTimeExtract

        public static int unixTimeExtract​(TimeUnitRange range,
                                  int time)
        Extracts a time unit from a time value (milliseconds since midnight).

      • resetTime

        public static long resetTime​(long timestamp)
        Resets to zero the "time" part of a timestamp.

      • resetDate

        public static long resetDate​(long timestamp)
        Resets to epoch (1970-01-01) the "date" part of a timestamp.

      • unixTimestampFloor

        public static long unixTimestampFloor​(TimeUnitRange range,
                                      long timestamp)

      • unixDateFloor

        public static long unixDateFloor​(TimeUnitRange range,
                                 long date)

      • unixTimestampCeil

        public static long unixTimestampCeil​(TimeUnitRange range,
                                     long timestamp)

      • unixDateCeil

        public static long unixDateCeil​(TimeUnitRange range,
                                long date)

      • julianDateFloor

        private static int julianDateFloor​(TimeUnitRange range,
                                   int julian,
                                   boolean floor)

      • ymdToUnixDate

        public static int ymdToUnixDate​(int year,
                                int month,
                                int day)

      • ymdToJulian

        public static int ymdToJulian​(int year,
                              int month,
                              int day)

      • unixTimestamp

        public static long unixTimestamp​(int year,
                                 int month,
                                 int day,
                                 int hour,
                                 int minute,
                                 int second)

      • addMonths

        public static long addMonths​(long timestamp,
                             int m)
        Adds a given number of months to a timestamp, represented as the number of milliseconds since the epoch.

      • addMonths

        public static int addMonths​(int date,
                            int m)
        Adds a given number of months to a date, represented as the number of days since the epoch.

      • lastDay

        private static int lastDay​(int y,
                           int m)

      • subtractMonths

        public static int subtractMonths​(int date0,
                                 int date1)
        Finds the number of months between two dates, each represented as the number of days since the epoch.

      • subtractMonths

        public static int subtractMonths​(long t0,
                                 long t1)

      • floorDiv

        public static long floorDiv​(long x,
                            long y)
        Divide, rounding towards negative infinity.

      • floorMod

        public static long floorMod​(long x,
                            long y)
        Modulo, always returning a non-negative result.

      • calendar

        public static java.util.Calendar calendar()
        Creates an instance of Calendar in the root locale and UTC time zone.

      • isOffsetDateTime

        public static boolean isOffsetDateTime​(java.lang.Object o)
        Returns whether a value is an OffsetDateTime.

      • offsetDateTimeValue

        public static java.lang.String offsetDateTimeValue​(java.lang.Object o)
        Returns the value of a OffsetDateTime as a string.