DateTimeUtils (Apache Calcite Avatica 1.12.0 API)

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
Modifier and Type	Class and Description
`private static class`	`DateTimeUtils.NoopOffsetDateTimeHandler` Implementation of `OffsetDateTimeHandler` for environments where no instances are possible.
`private static interface`	`DateTimeUtils.OffsetDateTimeHandler` Deals with values of `java.time.OffsetDateTime` without introducing a compile-time dependency (because `OffsetDateTime` is only JDK 8 and higher).
`static class`	`DateTimeUtils.PrecisionTime` Helper class for `parsePrecisionDateTimeLiteral(java.lang.String, java.lang.String, java.util.TimeZone)`
`private static class`	`DateTimeUtils.ReflectiveOffsetDateTimeHandler` Implementation of `OffsetDateTimeHandler` for environments where no instances are possible.

Field Summary

Fields
Modifier and Type	Field and Description
`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.
`private static DateTimeUtils.OffsetDateTimeHandler`	`OFFSET_DATE_TIME_HANDLER`
`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).

Constructor Summary

Constructors
Modifier Constructor and Description

private DateTimeUtils()

Constructors
Modifier	Constructor and Description
`private`	`DateTimeUtils()`

Method Summary

All Methods Static Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and 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 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)`
`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(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 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)`
`static boolean`	`isOffsetDateTime(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(StringBuilder buf, int julian)`
`private static int`	`lastDay(int y, int m)`
`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.
`private static Calendar`	`parseDateFormat(String s, DateFormat dateFormat, TimeZone tz, ParsePosition pp)` Parses a string using `SimpleDateFormat` and a given pattern.
`static Calendar`	`parseDateFormat(String s, String pattern, TimeZone tz)` Deprecated.
`private static int`	`parseFraction(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(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.
`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(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 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)`
`private static void`	`unixTimeToString(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 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.
- OFFSET_DATE_TIME_HANDLER
```
private static final DateTimeUtils.OffsetDateTimeHandler OFFSET_DATE_TIME_HANDLER
```

Constructor Detail
- DateTimeUtils
```
private DateTimeUtils()
```

Method Detail

parseDateFormat
```
private static Calendar parseDateFormat(String s,
                                        DateFormat dateFormat,
                                        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

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

unixTimeToString

private static void unixTimeToString(StringBuilder buf,
                                     int time,
                                     int precision)

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)

parseFraction
```
private static int parseFraction(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(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 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.

Class DateTimeUtils

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

EPOCH_JULIAN

DATE_FORMAT_STRING

TIME_FORMAT_STRING

TIMESTAMP_FORMAT_STRING

GMT_ZONE

UTC_ZONE

DEFAULT_ZONE

MILLIS_PER_SECOND

MILLIS_PER_MINUTE

MILLIS_PER_HOUR

MILLIS_PER_DAY

SECONDS_PER_DAY

ZERO_CALENDAR

OFFSET_DATE_TIME_HANDLER

Constructor Detail

DateTimeUtils

Method Detail

parseDateFormat

parseDateFormat

parseDateFormat

parsePrecisionDateTimeLiteral

parsePrecisionDateTimeLiteral

getTimeZone

checkDateFormat

newDateFormat

unixTimestampToString

unixTimestampToString

unixTimeToString

unixTimeToString

unixTimeToString

int2

int4

unixDateToString

unixDateToString

julianToString

intervalYearMonthToString

number

digitCount

roundUp

powerX

intervalDayTimeToString

roundUp

fraction

dateStringToUnixDate

timeStringToUnixDate

timeStringToUnixDate

parseFraction

timestampStringToUnixDate

unixDateExtract

julianExtract

firstMondayOfFirstWeek

getIso8601WeekNumber

unixTimestampExtract

unixTimeExtract

resetTime

resetDate

unixTimestampFloor

unixDateFloor

unixTimestampCeil

unixDateCeil

julianDateFloor

ymdToUnixDate

ymdToJulian

unixTimestamp

addMonths

addMonths

lastDay

subtractMonths

subtractMonths

floorDiv

floorMod

calendar

isOffsetDateTime