Date functions

Date functions perform actions on Date objects, such as obtaining the month information from a specific date or adding time to a date.

This table describes the Date functions that Transform supports. The same functions are described in the Transform API Reference (Groovydoc).

Date formats adhere to the SimpleDateFormat class in Java. For information on SimpleDateFormat class, see: http://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html.

User Function Return Data Type Description
addTime(Date attribute, Integer timeToAdd, String timeUnit) Date Adds time to a Date object. The time unit used must be one of the following constants:
  • MILLISECONDS
  • SECONDS
  • MINUTES
  • HOURS
  • DAYS
  • WEEKS
  • MONTHS
  • YEARS
diffDates(Date firstDate, Date secondDate, String timeUnit, Boolean precisionFlag) Double Calculates the difference between two dates as a long in a specific time unit. The time unit must be one of the following constants:
  • MILLISECONDS
  • SECONDS
  • MINUTES
  • HOURS
  • DAYS
  • WEEKS
  • MONTHS
  • YEARS

The precisionFlag optional parameter specifies whether to get the difference with a millisecond precision. If not used, it defaults to false.
getDayOfMonth(Date attribute, String timeZone, String locale) Integer Returns a day-of-month value for the Date. You can specify a time zone and locale as optional parameters; the defaults are null and "en", respectively.
getDayOfWeek(Date attribute, String timeZone, String locale) Integer Returns a day-of-week value for the Date. You can specify a time zone and locale as optional parameters; the defaults are null and "en", respectively.
getDayOfYear(Date attribute, String timeZone, String locale) Integer Returns a day-of-year value for the Date. You can specify a time zone and locale as optional parameters; the defaults are null and "en", respectively.
getHour(Date attribute, String timeZone, String locale) Integer Returns an hour value for the Date. You can specify a time zone and locale as optional parameters; the defaults are null and "en", respectively.
getMilliSecond(Date attribute, String timeZone, String locale) Long Returns a millisecond value for the Date, based on a time zone and locale parameters that you specify. The defaults are null and "en", respectively.
getMinute(Date attribute, String timeZone, String lcoale) Integer Returns a minute value for the Date. You can specify a time zone and locale as optional parameters; the defaults are null and "en", respectively.
getMonth(Date attribute, String timeZone, String locale) Integer Returns a month value for the Date. You can specify a time zone and locale as optional parameters; the defaults are null and "en", respectively.
getSeconds(Date attribute, String timeZone, String locale) Long Returns a seconds value for the Date. You can specify a time zone and locale as optional parameters; the defaults are null and "en", respectively.
getYear(Date attribute, String timeZone, String locale) Integer Returns a year value for the Date. You can specify a time zone and locale as optional parameters; the defaults are null and "en", respectively.
isDate(String attribute, String dateFormat) Boolean Determines whether a String is a valid Date value with a specific format.
toDate(Long epochDate) Date Converts a Long to a Date object.
toDate(String attribute, String dateFormat), String timeZone, String locale Date Converts a String to a Date object using a specific date format. You can specify a time zone and locale as optional parameters; the defaults are null and "en", respectively. Invalid date Strings return null.
today(String timeZone, String locale) Date Returns the current date. You can specify a time zone and locale as optional parameters; the defaults are null and "en", respectively.
toString(Date date, String dateFormat, String locale) String Converts a Date to a String. You must specify the Date's format and a locale, which default to DATEFORMAT_DEFAULT and "en", respectively.
truncateDate(Date date, String timeUnit) Date Truncates a Date based on a given time unit. The time unit used must be one of the following constants:
  • MILLISECONDS
  • SECONDS
  • MINUTES
  • HOURS
  • DAYS
  • WEEKS
  • MONTHS
  • YEARS

For example, truncateDate((toDate("2015/03/31 21:34:56")),MONTHS) returns 2015-03-01 00:00:00 UTC.

Date constants

Date constants define the default Date format and the time units that can be passed to Date functions.

This table describes the Date constants that Transform supports.

Constant Name Data Type Description
DATEFORMAT_DEFAULT Object Defines the default Date format: "yyyy/MM/dd HH:mm:ss"
DAYS Object Defines the constant for days: "days"
HOURS Object Defines the constant for hours: "hours"
MILLISECONDS Object Defines the constant for milliseconds: "milliseconds"
MINUTES Object Defines the constant for minutes: "minutes"
MONTHS Object Defines the constant for months: "months"
SECONDS Object Defines the constant for seconds: "seconds"
WEEKS Object Defines the constant for weeks: "weeks"
YEARS Object Defines the constant for years: "years"

Example 20-7 Date extracting example

This example pulls out the year-month. 
toString(pickup_datetime, 'yyyy-MM')

Example 20-8 Date calculation example

The following code uses the diffDates function to calculate the number of days to pickup_datetime:

diffDates(today(),pickup_datetime,DAYS,true)

today() obtains the current date, pickup_datetime is the pickup date, DAYS specifies the time unit in which to return the result, and true specifies that the difference be calculated with precision.

Example 20-9 toDate examples

This example first uses the toLong function to convert a String to a Long and then uses the result as the input to the toDate function: 
toDate(toLong("1240596879"))
The following are some sample date formats for the toDate function: 
toDate(date_String,'EEE MM/DD/YYYY hh:mm:ss a')
toDate(date_String,'EEE MM/DD/YYYY hh:mm:ss a','EST')
toDate(date_String,'EEE MM/DD/YYYY hh:mm:ss a','Etc/GMT-10')
toDate(date_String,'EEE MM/DD/YYYY hh:mm:ss a','Etc/Universal','en'))
toDate(date_String,'EEE MM/DD/YYYY hh:mm:ss a','GMT0','de'))
toDate(date_String,DATEFORMAT_DEFAULT)
toDate(date_String,DATEFORMAT_DEFAULT,'EST')
toDate(date_String,DATEFORMAT_DEFAULT,'Etc/GMT-10')