com.pervasive.datarush.functions

Class DateTime

java.lang.Object

com.pervasive.datarush.functions.DateTime

public class DateTime
extends Object

Provides implementations of common date/time functions. Unless otherwise stated, functions can be applied to any of the date/time data types:

• TokenTypeConstant.DATE
• TokenTypeConstant.TIME
• {@link TokenTypeConstant#TIMESTAMP

See Also:

ScalarValuedFunction, DeriveFields

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DateTime.DateTimeValue Definitions of date and time values that can be extracted from date and timestamp types.
static class	DateTime.Granularity The desired granularity of the output.

Method Summary

Modifier and Type	Method and Description
static ScalarValuedFunction	addTime(ScalarValuedFunction time, ScalarValuedFunction delta, DateTime.Granularity granularity) Adds a time period to the specified date/time value.
static ScalarValuedFunction	addTime(ScalarValuedFunction time, ScalarValuedFunction delta, DateTime.Granularity granularity, TimeZone tz) Adds a time period to the specified date/time value.
static ScalarValuedFunction	addTime(String timeField, String deltaField, DateTime.Granularity granularity) Adds a time period to the specified date/time value.
static ScalarValuedFunction	addTime(String timeField, String deltaField, DateTime.Granularity granularity, TimeZone tz) Adds a time period to the specified date/time value.
static ScalarValuedFunction	currentDate() Returns the current date in the time zone of the local machine.
static ScalarValuedFunction	currentDate(TimeZone tz) Returns the current date in the specified time zone.
static ScalarValuedFunction	currentTime() Returns the current time of day in the time zone of the local machine.
static ScalarValuedFunction	currentTime(TimeZone tz) Returns the current time of day in the specified time zone.
static ScalarValuedFunction	currentTimestamp() Returns the current time stamp in the time zone of the local machine.
static ScalarValuedFunction	currentTimestamp(TimeZone tz) Returns the current time stamp in the specified time zone.
static ScalarValuedFunction	getTextValue(ScalarValuedFunction expr, DateTime.DateTimeValue valueType) Create a function that will extract the wanted date or time value as text from the given function applied to a record flow.
static ScalarValuedFunction	getTextValue(ScalarValuedFunction expr, DateTime.DateTimeValue valueType, TimeZone tz) Create a function that will extract the wanted date or time value as text from the given function applied to a record flow.
static ScalarValuedFunction	getTextValue(String field, DateTime.DateTimeValue valueType) Create a function that will extract the wanted date or time value as text from the named field contained in a record flow.
static ScalarValuedFunction	getTextValue(String field, DateTime.DateTimeValue valueType, TimeZone tz) Create a function that will extract the wanted date or time value as text from the named field contained in a record flow.
static ScalarValuedFunction	getValue(ScalarValuedFunction expr, DateTime.DateTimeValue valueType) Create a function that will extract the wanted date or time value from the given function applied to a record flow.
static ScalarValuedFunction	getValue(ScalarValuedFunction expr, DateTime.DateTimeValue valueType, TimeZone tz) Create a function that will extract the wanted date or time value from the given function applied to a record flow.
static ScalarValuedFunction	getValue(String field, DateTime.DateTimeValue valueType) Create a function that will extract the wanted date or time value from the named field contained in a record flow.
static ScalarValuedFunction	getValue(String field, DateTime.DateTimeValue valueType, TimeZone tz) Create a function that will extract the wanted date or time value from the named field contained in a record flow.
static ScalarValuedFunction	subtractTime(ScalarValuedFunction time, ScalarValuedFunction delta, DateTime.Granularity granularity) Subtracts a time period from the specified date/time value.
static ScalarValuedFunction	subtractTime(ScalarValuedFunction time, ScalarValuedFunction delta, DateTime.Granularity granularity, TimeZone tz) Subtracts a time period from the specified date/time value.
static ScalarValuedFunction	subtractTime(String timeField, String deltaField, DateTime.Granularity granularity) Subtracts a time period from the specified date/time value.
static ScalarValuedFunction	subtractTime(String timeField, String deltaField, DateTime.Granularity granularity, TimeZone tz) Subtracts a time period from the specified date/time value.
static ScalarValuedFunction	timeDiff(ScalarValuedFunction startValue, ScalarValuedFunction endValue, DateTime.Granularity granularity) Builds an expression measuring the time interval between two date/time expressions using a specified time unit.
static ScalarValuedFunction	timeDiff(ScalarValuedFunction startValue, ScalarValuedFunction endValue, DateTime.Granularity granularity, int scale) Builds an expression measuring the time interval between two date/time expressions using a specified time unit and scale.
static ScalarValuedFunction	timeDiff(String startField, String endField) Builds an expression measuring the time interval between two date/time fields.
static ScalarValuedFunction	timeDiff(String startField, String endField, DateTime.Granularity granularity) Builds an expression measuring the time interval between two date/time fields using a specified time unit.
static ScalarValuedFunction	timeDiff(String startField, String endField, DateTime.Granularity granularity, int scale) Builds an expression measuring the time interval between two date/time fields using a specified time unit and scale.
static ScalarValuedFunction	toMilliseconds(ScalarValuedFunction expr) Converts the value of a date/time expression into the number of milliseconds since the epoch (January 1, 1970, 00:00:00 GMT).
static ScalarValuedFunction	toMilliseconds(String fieldName) Converts the value of a date/time field into the number of milliseconds since the epoch (January 1, 1970, 00:00:00 GMT).
static ScalarValuedFunction	useDefaultTimeZone(ScalarValuedFunction time) Adjusts a time stamp value to use the time zone of the local machine.
static ScalarValuedFunction	useDefaultTimeZone(String timeField) Adjusts a time stamp value to use the time zone of the local machine.
static ScalarValuedFunction	useTimeZone(ScalarValuedFunction time, TimeZone tz) Adjusts a time stamp value to use the specified time zone.
static ScalarValuedFunction	useTimeZone(String timeField, TimeZone tz) Adjusts a time stamp value to use the specified time zone.

Methods inherited from class java.lang.Object

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

Method Detail

getValue

public static ScalarValuedFunction getValue(String field,
                                            DateTime.DateTimeValue valueType)

Create a function that will extract the wanted date or time value from the named field contained in a record flow. Time stamp values will be interpreted in the system's default time zone.

Parameters:

field - name of the field containing a date or time stamp value

valueType - date or time value to extract

Returns:

function instance that can be applied to record flow tokens

getValue

public static ScalarValuedFunction getValue(String field,
                                            DateTime.DateTimeValue valueType,
                                            TimeZone tz)

Create a function that will extract the wanted date or time value from the named field contained in a record flow. Time stamp values will be interpreted in the specified time zone; the time zone is ignored if the field is a date or time of day value.

Parameters:

field - name of the field containing a date, time of day, or time stamp value

valueType - date or time value to extract

tz - time zone in which to interpret time stamp values. If null, the time zone of the local machine will be used. If the field value is a date or time of day, a time zone is not required, and will be ignored.

Returns:

function instance that can be applied to record flow tokens

getValue

public static ScalarValuedFunction getValue(ScalarValuedFunction expr,
                                            DateTime.DateTimeValue valueType)

Create a function that will extract the wanted date or time value from the given function applied to a record flow. Time stamp values will be interpreted in the system's default time zone.

Parameters:

expr - a function that returns a date, time of day, or time stamp value

valueType - date or time value to extract

Returns:

function instance that can be applied to record flow tokens

getValue

public static ScalarValuedFunction getValue(ScalarValuedFunction expr,
                                            DateTime.DateTimeValue valueType,
                                            TimeZone tz)

Create a function that will extract the wanted date or time value from the given function applied to a record flow. Time stamp values will be interpreted in the specified time zone; the time zone is ignored if the expression is a date or time of day value.

Parameters:

expr - a function that returns a date, time of day, or time stamp value

valueType - date or time value to extract

tz - time zone in which to interpret time stamp values. If null, the time zone of the local machine will be used. If the expression value is a date or time of day, a time zone is not required, and will be ignored.

Returns:

function instance that can be applied to record flow tokens

getTextValue

public static ScalarValuedFunction getTextValue(String field,
                                                DateTime.DateTimeValue valueType)

Create a function that will extract the wanted date or time value as text from the named field contained in a record flow. Time stamp values will be interpreted in the system's default time zone.

Parameters:

field - name of the field containing a date or time stamp value

valueType - date or time value to extract

Returns:

function instance that can be applied to record flow tokens

getTextValue

public static ScalarValuedFunction getTextValue(String field,
                                                DateTime.DateTimeValue valueType,
                                                TimeZone tz)

Create a function that will extract the wanted date or time value as text from the named field contained in a record flow. Time stamp values will be interpreted in the specified time zone; the time zone is ignored if the field is a date or time of day value.

Parameters:

field - name of the field containing a date, time of day, or time stamp value

valueType - date or time value to extract

tz - time zone in which to interpret time stamp values. If null, the time zone of the local machine will be used. If the field value is a date or time of day, a time zone is not required, and will be ignored.

Returns:

function instance that can be applied to record flow tokens

getTextValue

public static ScalarValuedFunction getTextValue(ScalarValuedFunction expr,
                                                DateTime.DateTimeValue valueType)

Create a function that will extract the wanted date or time value as text from the given function applied to a record flow. Time stamp values will be interpreted in the system's default time zone.

Parameters:

expr - a function that returns a date, time of day, or time stamp value

valueType - date or time value to extract

Returns:

function instance that can be applied to record flow tokens

getTextValue

public static ScalarValuedFunction getTextValue(ScalarValuedFunction expr,
                                                DateTime.DateTimeValue valueType,
                                                TimeZone tz)

Create a function that will extract the wanted date or time value as text from the given function applied to a record flow. Time stamp values will be interpreted in the specified time zone; the time zone is ignored if the expression is a date or time of day value.

Parameters:

expr - a function that returns a date, time of day, or time stamp value

valueType - date or time value to extract

tz - time zone in which to interpret time stamp values. If null, the time zone of the local machine will be used. If the expression value is a date or time of day, a time zone is not required, and will be ignored.

Returns:

function instance that can be applied to record flow tokens

timeDiff

public static ScalarValuedFunction timeDiff(String startField,
                                            String endField)

Builds an expression measuring the time interval between two date/time fields. The interval endpoints must be of the same type. When comparing time fields the precision is millisecond based whereas when comparing date fields the precision is day based. This means that when using date fields the difference will be based on calendar intervals versus time fields which will use the more precise astronomical time intervals.

Parameters:

startField - the field defining the start of the interval

endField - the field defining the end of the interval

Returns:

a function evaluating the expression

timeDiff

public static ScalarValuedFunction timeDiff(String startField,
                                            String endField,
                                            DateTime.Granularity granularity)

Builds an expression measuring the time interval between two date/time fields using a specified time unit. The interval endpoints must be of the same type. When comparing time fields the precision is millisecond based whereas when comparing date fields the precision is day based. This means that when using date fields the difference will be based on calendar intervals versus time fields which will use the more precise astronomical time intervals.

Parameters:

startField - the field defining the start of the interval

endField - the field defining the end of the interval

granularity - the time unit in which to measure the interval length

Returns:

a function evaluating the expression

timeDiff

public static ScalarValuedFunction timeDiff(String startField,
                                            String endField,
                                            DateTime.Granularity granularity,
                                            int scale)

Builds an expression measuring the time interval between two date/time fields using a specified time unit and scale. The interval endpoints must be of the same type. When comparing time fields the precision is millisecond based whereas when comparing date fields the precision is day based. This means that when using date fields the difference will be based on calendar intervals versus time fields which will use the more precise astronomical time intervals.

Parameters:

startField - the field defining the start of the interval

endField - the field defining the end of the interval

granularity - the time unit in which to measure the interval length

scale - fractional scale of the difference

Returns:

a function evaluating the expression

timeDiff

public static ScalarValuedFunction timeDiff(ScalarValuedFunction startValue,
                                            ScalarValuedFunction endValue,
                                            DateTime.Granularity granularity)

Builds an expression measuring the time interval between two date/time expressions using a specified time unit. The interval endpoints must be of the same type. When comparing time fields the precision is millisecond based whereas when comparing date fields the precision is day based. This means that when using date fields the difference will be based on calendar intervals versus time fields which will use the more precise astronomical time intervals.

Parameters:

startValue - an expression defining the start of the interval

endValue - an expression defining the end of the interval

granularity - the time unit in which to measure the interval length

Returns:

a function evaluating the expression

timeDiff

public static ScalarValuedFunction timeDiff(ScalarValuedFunction startValue,
                                            ScalarValuedFunction endValue,
                                            DateTime.Granularity granularity,
                                            int scale)

Builds an expression measuring the time interval between two date/time expressions using a specified time unit and scale. The interval endpoints must be of the same type. When comparing time fields the precision is millisecond based whereas when comparing date fields the precision is day based. This means that when using date fields the difference will be based on calendar intervals versus time fields which will use the more precise astronomical time intervals.

Parameters:

startValue - an expression defining the start of the interval

endValue - an expression defining the end of the interval

granularity - the time unit in which to measure the interval length

scale - fractional scale of the interval length

Returns:

a function evaluating the expression

toMilliseconds

public static ScalarValuedFunction toMilliseconds(String fieldName)

Converts the value of a date/time field into the number of milliseconds since the epoch (January 1, 1970, 00:00:00 GMT). Null input values result in null output values. As time of day values have no date portion, this will return the milliseconds since midnight. For date values, the result represents midnight of the associated day.

Parameters:

fieldName - the field containing the value to convert

Returns:

a function that converts the date, time, or time stamp value to a long

toMilliseconds

public static ScalarValuedFunction toMilliseconds(ScalarValuedFunction expr)

Converts the value of a date/time expression into the number of milliseconds since the epoch (January 1, 1970, 00:00:00 GMT). Null input values result in null output values. As time of day values have no date portion, this returns the milliseconds since midnight. For date values, the result represents midnight of the associated day.

Parameters:

expr - the expression to convert

Returns:

a function that converts the date, time, or time stamp value to a long

currentDate

public static ScalarValuedFunction currentDate()

Returns the current date in the time zone of the local machine.

Returns:

a function that returns a date value representing the current date

currentDate

public static ScalarValuedFunction currentDate(TimeZone tz)

Returns the current date in the specified time zone.

Parameters:

tz - the time zone from which to get the current date. If null, the time zone of the local machine will be used.

Returns:

a function that returns a date value representing the current date

currentTime

public static ScalarValuedFunction currentTime()

Returns the current time of day in the time zone of the local machine.

Returns:

a function that returns a time value representing the current time of day

currentTime

public static ScalarValuedFunction currentTime(TimeZone tz)

Returns the current time of day in the specified time zone.

Parameters:

tz - the time zone from which to get the current time of day. If null, the time zone of the local machine will be used.

Returns:

a function that returns a time value representing the current time of day

currentTimestamp

public static ScalarValuedFunction currentTimestamp()

Returns the current time stamp in the time zone of the local machine.

Returns:

a function that returns a time stamp value representing the current date and time

currentTimestamp

public static ScalarValuedFunction currentTimestamp(TimeZone tz)

Returns the current time stamp in the specified time zone.

Parameters:

tz - the time zone from which to get the current time stamp. If null, the time zone of the local machine will be used.

Returns:

a function that returns a time stamp value representing the current date and time

addTime

public static ScalarValuedFunction addTime(String timeField,
                                           String deltaField,
                                           DateTime.Granularity granularity)

Adds a time period to the specified date/time value. The result is of the same type as the initial value.

Computation on time stamp values is performed relative to the time zone of the local machine. Date and time of day values are processed independent of time zone.

It is an error to add units smaller than a day to a date value. Similarly, it is an error to add units larger than an hour to a time of day value.

Parameters:

timeField - the field containing the base value

deltaField - the field containing the length of the time period to add.

granularity - the units in which the time period is measured

Returns:

a function that adds a value to a date, time of day, or time stamp

addTime

public static ScalarValuedFunction addTime(String timeField,
                                           String deltaField,
                                           DateTime.Granularity granularity,
                                           TimeZone tz)

Adds a time period to the specified date/time value. The result is of the same type as the initial value.

Computation on time stamp values is performed relative to the specified time zone. Date and time of day values are processed independent of time zone.

It is an error to add units smaller than a day to a date value. Similarly, it is an error to add units larger than an hour to a time of day value.

Parameters:

timeField - the field containing the base value

deltaField - the field containing the length of the time period to add.

granularity - the units in which the time period is measured

tz - the time zone in which to perform the computation. If null, the time zone of the local machine will be used.

Returns:

a function that adds a value to a date, time of day, or time stamp

addTime

public static ScalarValuedFunction addTime(ScalarValuedFunction time,
                                           ScalarValuedFunction delta,
                                           DateTime.Granularity granularity)

Adds a time period to the specified date/time value. The result is of the same type as the initial value.

Computation on time stamp values is performed relative to the time zone of the local machine. Date and time of day values are processed independent of time zone.

It is an error to add units smaller than a day to a date value. Similarly, it is an error to add units larger than an hour to a time of day value.

Parameters:

time - the expression providing the base value

delta - the expression providing the length of the time period to add.

granularity - the units in which the time period is measured

Returns:

a function that adds a value to a date, time of day, or time stamp

addTime

public static ScalarValuedFunction addTime(ScalarValuedFunction time,
                                           ScalarValuedFunction delta,
                                           DateTime.Granularity granularity,
                                           TimeZone tz)

Adds a time period to the specified date/time value. The result is of the same type as the initial value.

Computation on time stamp values is performed relative to the specified time zone. Date and time of day values are processed independent of time zone.

It is an error to add units smaller than a day to a date value. Similarly, it is an error to add units larger than an hour to a time of day value.

Parameters:

time - the expression providing the base value

delta - the expression providing the length of the time period to add.

granularity - the units in which the time period is measured

tz - the time zone in which to perform the computation. If null, the time zone of the local machine will be used.

Returns:

a function that adds a value to a date, time of day, or time stamp

subtractTime

public static ScalarValuedFunction subtractTime(String timeField,
                                                String deltaField,
                                                DateTime.Granularity granularity)

Subtracts a time period from the specified date/time value. The result is of the same type as the initial value.

Computation on time stamp values is performed relative to the time zone of the local machine. Date and time of day values are processed independent of time zone.

It is an error to subtract units smaller than a day from a date value. Similarly, it is an error to subtract units larger than an hour from a time of day value.

Parameters:

timeField - the field containing the base value

deltaField - the field containing the length of the time period to add.

granularity - the units in which the time period is measured

granularity - the granularity of delta

Returns:

a function that subtracts a value from a date or timestamp

subtractTime

public static ScalarValuedFunction subtractTime(String timeField,
                                                String deltaField,
                                                DateTime.Granularity granularity,
                                                TimeZone tz)

Subtracts a time period from the specified date/time value. The result is of the same type as the initial value.

Computation on time stamp values is performed relative to the specified time zone. Date and time of day values are processed independent of time zone.

It is an error to subtract units smaller than a day from a date value. Similarly, it is an error to subtract units larger than an hour from a time of day value.

Parameters:

timeField - the field containing the base value

deltaField - the field containing the length of the time period to add.

granularity - the units in which the time period is measured

tz - the time zone to use for time stamp processing. If null, the time zone of the local machine will be used.

Returns:

a function that subtracts a value from a date, time, or timestamp

subtractTime

public static ScalarValuedFunction subtractTime(ScalarValuedFunction time,
                                                ScalarValuedFunction delta,
                                                DateTime.Granularity granularity)

Subtracts a time period from the specified date/time value. The result is of the same type as the initial value.

Computation on time stamp values is performed relative to the time zone of the local machine. Date and time of day values are processed independent of time zone.

It is an error to subtract units smaller than a day from a date value. Similarly, it is an error to subtract units larger than an hour from a time of day value.

Parameters:

time - the expression providing the base value

delta - the expression providing the length of the time period to add.

granularity - the units in which the time period is measured

Returns:

a function that subtracts a value from a date, time, or timestamp

subtractTime

public static ScalarValuedFunction subtractTime(ScalarValuedFunction time,
                                                ScalarValuedFunction delta,
                                                DateTime.Granularity granularity,
                                                TimeZone tz)

Subtracts a time period from the specified date/time value. The result is of the same type as the initial value.

Computation on time stamp values is performed relative to the specified time zone. Date and time of day values are processed independent of time zone.

It is an error to subtract units smaller than a day from a date value. Similarly, it is an error to subtract units larger than an hour from a time of day value.

Parameters:

time - the expression providing the base value

delta - the expression providing the length of the time period to add.

granularity - the units in which the time period is measured

tz - the time zone to use for time stamp processing. If null, the time zone of the local machine will be used.

Returns:

a function that subtracts a value from a date, time, or timestamp

useDefaultTimeZone

public static ScalarValuedFunction useDefaultTimeZone(String timeField)

Adjusts a time stamp value to use the time zone of the local machine. This does not modify the point in time represented by the time stamp; only the associated time zone offset is changed.

Parameters:

timeField - the input time stamp field

Returns:

a function that returns an input time stamp using the associated with time zone of the local machine

useDefaultTimeZone

public static ScalarValuedFunction useDefaultTimeZone(ScalarValuedFunction time)

Adjusts a time stamp value to use the time zone of the local machine. This does not modify the point in time represented by the time stamp; only the associated time zone offset is changed.

Parameters:

time - the input time stamp

Returns:

a function that returns an input time stamp associated with the time zone of the local machine

useTimeZone

public static ScalarValuedFunction useTimeZone(String timeField,
                                               TimeZone tz)

Adjusts a time stamp value to use the specified time zone. This does not modify the point in time represented by the time stamp; only the associated time zone offset is changed.

Parameters:

time - the input time stamp field

tz - the time zone of the result. If null the time zone of the local machine will be used.

Returns:

a function that returns an input time stamp associated with the specified time zone

useTimeZone

public static ScalarValuedFunction useTimeZone(ScalarValuedFunction time,
                                               TimeZone tz)

Adjusts a time stamp value to use the specified time zone. This does not modify the point in time represented by the time stamp; only the associated time zone offset is changed.

Parameters:

time - the input time stamp

tz - the time zone of the result. If null the time zone of the local machine will be used.

Returns:

a function that returns an input time stamp associated with the specified time zone