org.apache.calcite.avatica.util

## Class DateTimeUtils

- java.lang.Object
- - org.apache.calcite.avatica.util.DateTimeUtils

    public class DateTimeUtils
    extends 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.

### Nested Class Summary

Nested Classes
`static class` `DateTimeUtils.PrecisionTime` Helper class for `parsePrecisionDateTimeLiteral(java.lang.String, java.lang.String, java.util.TimeZone)`

### Field Summary

Fields
`static String` `DATE_FORMAT_STRING` The SimpleDateFormat string for ISO dates, "yyyy-MM-dd".
`static TimeZone` `DEFAULT_ZONE` The Java default time zone.
`static int` `EPOCH_JULIAN` The julian date of the epoch, 1970-01-01.
`static TimeZone` `GMT_ZONE` The GMT time zone.
`private static Calendar` `LOCAL_CALENDAR` Calendar set to local time.
`static long` `MILLIS_PER_DAY` The number of milliseconds in a day.
`static long` `MILLIS_PER_HOUR` The number of milliseconds in an hour.
`static long` `MILLIS_PER_MINUTE` The number of milliseconds in a minute.
`static long` `MILLIS_PER_SECOND` The number of milliseconds in a second.
`static String` `TIME_FORMAT_STRING` The SimpleDateFormat string for ISO times, "HH:mm:ss".
`static String` `TIMESTAMP_FORMAT_STRING` The SimpleDateFormat string for ISO timestamps, "yyyy-MM-dd HH:mm:ss".
`static Calendar` `ZERO_CALENDAR` Calendar set to the epoch (1970-01-01 00:00:00 UTC).

### Constructor Summary

Constructors
`private` `DateTimeUtils()`

### Method Summary

Methods
`static void` `checkDateFormat(String pattern)` Checks if the date/time format is valid
`static int` `dateStringToUnixDate(String s)`
`static int` `digitCount(int v)`
`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(StringBuilder buf, int scale, long ms)`
`static TimeZone` `getTimeZone(Calendar cal)` Gets the active time zone based on a Calendar argument
`private static void` `int2(StringBuilder buf, int i)`
`private static void` `int4(StringBuilder buf, int i)`
`static String` `intervalDayTimeToString(long v, TimeUnitRange range, int scale)`
`static String` `intervalYearMonthToString(int v, TimeUnitRange range)`
`private static int` `julianDateFloor(TimeUnitRange range, int julian, boolean floor)`
`private static int` `julianExtract(TimeUnitRange range, int julian)`
`private static void` `julianToString(StringBuilder buf, int julian)`
`static SimpleDateFormat` `newDateFormat(String format)` Creates a new date formatter with Farrago specific options.
`static StringBuilder` `number(StringBuilder buf, int v, int n)`
`static Calendar` `parseDateFormat(String s, String pattern, TimeZone tz)` Parses a string using `SimpleDateFormat` and a given pattern.
`private static Calendar` `parseDateFormat(String s, String pattern, TimeZone tz, ParsePosition pp)` Parses a string using `SimpleDateFormat` and a given pattern.
`static DateTimeUtils.PrecisionTime` `parsePrecisionDateTimeLiteral(String s, String pattern, TimeZone tz)` 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 long` `timestampStringToUnixDate(String s)`
`static int` `timeStringToUnixDate(String v)`
`static int` `timeStringToUnixDate(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 String` `unixDateToString(int date)` Helper for CAST({date} AS VARCHAR(n)).
`private static void` `unixDateToString(StringBuilder buf, int date)`
`static long` `unixTimestamp(int year, int month, int day, int hour, int minute, int second)`
`static long` `unixTimestampCeil(TimeUnitRange range, long timestamp)`
`static long` `unixTimestampFloor(TimeUnitRange range, long timestamp)`
`static String` `unixTimestampToString(long timestamp)` Helper for CAST({timestamp} AS VARCHAR(n)).
`static String` `unixTimeToString(int time)` Helper for CAST({timestamp} AS VARCHAR(n)).
`private static void` `unixTimeToString(StringBuilder buf, int time)`
`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 String DATE_FORMAT_STRING

The SimpleDateFormat string for ISO dates, "yyyy-MM-dd".

See Also:
  Constant Field Values

#### TIME_FORMAT_STRING

    public static final String TIME_FORMAT_STRING

The SimpleDateFormat string for ISO times, "HH:mm:ss".

See Also:
  Constant Field Values

#### TIMESTAMP_FORMAT_STRING

    public static final String TIMESTAMP_FORMAT_STRING

The SimpleDateFormat string for ISO timestamps, "yyyy-MM-dd HH:mm:ss".

See Also:
  Constant Field Values

#### GMT_ZONE

    public static final TimeZone GMT_ZONE

The GMT time zone.

#### DEFAULT_ZONE

    public static final 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

#### ZERO_CALENDAR

    public static final 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.

#### LOCAL_CALENDAR

    private static final Calendar LOCAL_CALENDAR

Calendar set to local time.

### Constructor Detail

#### DateTimeUtils

    private DateTimeUtils()

### Method Detail

#### parseDateFormat

    private static Calendar parseDateFormat(String s,
                           String pattern,
                           TimeZone tz,
                           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
  `pattern` - `SimpleDateFormat` pattern (not null)
  `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

    public static Calendar parseDateFormat(String s,
                           String pattern,
                           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
  `pattern` - `SimpleDateFormat` pattern
  `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 GMT time zone.

#### parsePrecisionDateTimeLiteral

    public static DateTimeUtils.PrecisionTime parsePrecisionDateTimeLiteral(String s,
                                                            String pattern,
                                                            TimeZone tz)

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
  `pattern` - `SimpleDateFormat` pattern
  `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 TimeZone getTimeZone(Calendar cal)

Gets the active time zone based on a Calendar argument

#### checkDateFormat

    public static void checkDateFormat(String pattern)

Checks if the date/time format is valid

Parameters:
  `pattern` - `SimpleDateFormat` pattern
Throws:
  `IllegalArgumentException` - if the given pattern is invalid

#### newDateFormat

    public static SimpleDateFormat newDateFormat(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 String unixTimestampToString(long timestamp)

Helper for CAST({timestamp} AS VARCHAR(n)).

#### unixTimeToString

    public static String unixTimeToString(int time)

Helper for CAST({timestamp} AS VARCHAR(n)).

#### unixTimeToString

    private static void unixTimeToString(StringBuilder buf,
                        int time)

#### int2

    private static void int2(StringBuilder buf,
            int i)

#### int4

    private static void int4(StringBuilder buf,
            int i)

#### unixDateToString

    public static String unixDateToString(int date)

Helper for CAST({date} AS VARCHAR(n)).

#### unixDateToString

    private static void unixDateToString(StringBuilder buf,
                        int date)

#### julianToString

    private static void julianToString(StringBuilder buf,
                      int julian)

#### intervalYearMonthToString

    public static String intervalYearMonthToString(int v,
                                   TimeUnitRange range)

#### number

    public static StringBuilder number(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 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(StringBuilder buf,
                int scale,
                long ms)

#### dateStringToUnixDate

    public static int dateStringToUnixDate(String s)

#### timeStringToUnixDate

    public static int timeStringToUnixDate(String v)

#### timeStringToUnixDate

    public static int timeStringToUnixDate(String v,
                           int start)

#### timestampStringToUnixDate

    public static long timestampStringToUnixDate(String s)

#### unixDateExtract

    public static long unixDateExtract(TimeUnitRange range,
                       long date)

#### julianExtract

    private static int julianExtract(TimeUnitRange range,
                    int julian)

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

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