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` Deprecated. Use `UTC_ZONE`
`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 long` `SECONDS_PER_DAY` The number of seconds in a day.
`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 TimeZone` `UTC_ZONE` The UTC time zone.
`static Calendar` `ZERO_CALENDAR` Calendar set to the epoch (1970-01-01 00:00:00 UTC).

### Method Summary

All Methods Static Methods Concrete Methods Deprecated Methods
`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 Calendar` `calendar()` Creates an instance of `Calendar` in the root locale and UTC time zone.
`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.
`static TimeZone` `getTimeZone(Calendar cal)` Gets the active time zone based on a Calendar argument
`static String` `intervalDayTimeToString(long v, TimeUnitRange range, int scale)`
`static String` `intervalYearMonthToString(int v, TimeUnitRange range)`
`static boolean` `isOffsetDateTime(Object o)` Returns whether a value is an `OffsetDateTime`.
`static SimpleDateFormat` `newDateFormat(String format)` Creates a new date formatter with Farrago specific options.
`static StringBuilder` `number(StringBuilder buf, int v, int n)`
`static String` `offsetDateTimeValue(Object o)` Returns the value of a `OffsetDateTime` as a string.
`static Calendar` `parseDateFormat(String s, DateFormat dateFormat, TimeZone tz)` Parses a string using `SimpleDateFormat` and a given pattern.
`static Calendar` `parseDateFormat(String s, String pattern, TimeZone tz)` Deprecated.
`static DateTimeUtils.PrecisionTime` `parsePrecisionDateTimeLiteral(String s, DateFormat dateFormat, TimeZone tz, int maxPrecision)` Parses a string using `SimpleDateFormat` and a given pattern, and if present, parses a fractional seconds component.
`static DateTimeUtils.PrecisionTime` `parsePrecisionDateTimeLiteral(String s, String pattern, TimeZone tz)` Deprecated.
`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.
`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(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)).
`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 String` `unixTimestampToString(long timestamp)` Helper for CAST({timestamp} AS VARCHAR(n)).
`static String` `unixTimestampToString(long timestamp, int precision)`
`static String` `unixTimeToString(int time)` Helper for CAST({timestamp} AS VARCHAR(n)).
`static String` `unixTimeToString(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 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

    @Deprecated
    public static final TimeZone GMT_ZONE

Deprecated. Use `UTC_ZONE`
The GMT time zone.

#### UTC_ZONE

    public static final TimeZone UTC_ZONE

The UTC 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

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

### Method Detail

#### parseDateFormat

    @Deprecated
    public static Calendar parseDateFormat(String s,
                                                       String pattern,
                                                       TimeZone tz)

Deprecated.

#### parseDateFormat

    public static Calendar parseDateFormat(String s,
                                           DateFormat dateFormat,
                                           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(String s,
                                                                                        String pattern,
                                                                                        TimeZone tz)

Deprecated.

#### parsePrecisionDateTimeLiteral

    public static DateTimeUtils.PrecisionTime parsePrecisionDateTimeLiteral(String s,
                                                                            DateFormat dateFormat,
                                                                            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 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)).

#### unixTimestampToString

    public static String unixTimestampToString(long timestamp,
                                               int precision)

#### unixTimeToString

    public static String unixTimeToString(int time)

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

#### unixTimeToString

    public static String unixTimeToString(int time,
                                          int precision)

#### unixDateToString

    public static String unixDateToString(int date)

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

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

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

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

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

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

#### 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 Calendar calendar()

Creates an instance of `Calendar` in the root locale and UTC time zone.

#### isOffsetDateTime

    public static boolean isOffsetDateTime(Object o)

Returns whether a value is an `OffsetDateTime`.

#### offsetDateTimeValue

    public static String offsetDateTimeValue(Object o)

Returns the value of a `OffsetDateTime` as a string.