Date and time operators - 3 - 3.12

Data360 Analyze Server Help

Product type
Software
Portfolio
Verify
Product family
Data360
Product
Data360 Analyze
Version
3.12
Language
English
Product name
Data360 Analyze
Title
Data360 Analyze Server Help
Copyright
2023
First publish date
2016
CAUTION:
This topic relates to Data360 Analyze Script which is the language that is used in some superseded nodes. If you are looking for help configuring the Python-based nodes, please see Python scripting.

addDate

Returns a new date which is the result of adding the specified amount of units to the date parameter. The amount parameter may be negative, in which case the result date will be before the input date. The units parameter must be one of the following (case-insensitive): "days", "months", or "years". If no units are provided, units defaults to "days". Evaluates to null if the date parameter is null. Evaluates to the date parameter if the amount parameter is null. If the input date falls on the 29th February in a leap year, and years are added or subtracted such that the resulting year is not a leap year, then the returned date will be on the 1st March. Equivalent to dateAdjust.

Used in the following format, where date must be a date, amount must be an int or long and is the amount of time to add and units is the unit of the amount to add and can be "days", "months" or "year" (if no units are specified, the default is days):

addDate(date, amount[, units])

date.addDate(amount[, units])

The return value type is a date.

Examples

addDate(date(), 1) # value: tomorrow - default of "days" used. date().addDate(1) # value: tomorrow - default of "days" used.

d = date(2000, 8, 15) addDate(d, 20) # value: 2000-09-04 d.addDate(20) # value: 2000-09-04

d = date(2000, 8, 15) addDate(d, 3, "years") # value: 2003-08-15 d.addDate(3, "years") # value: 2003-08-15

d = date(2000, 8, 15) addDate(d, 3, "months") # value: 2000-11-15 d.addDate(3, "months") # value: 2000-11-15

d = date(2000, 8, 15) # The addition of 5 months results in the year incrementing. addDate(d, 5, "months") # value: 2001-01-15. d.addDate(5, "months") # value: 2001-01-15.

d = date(2000, 8, 15) # The addition of 20 days results in the month incrementing. addDate(d, 20, "days") # value: 2000-09-04. d.addDate(20, "days") # value: 2000-09-04.

d = date(2000, 8, 15) # The addition of 150 days results in both the year and the month incrementing. addDate(d, 150, "days") # value: 2001-01-12. d.addDate(150, "days") # value: 2001-01-12.

d = date(2000, 8, 15) # One month is subtracted from the specified date. addDate(d, -1, "months") # value: 2000-07-15. d.addDate(-1, "months") # value: 2000-07-15.

d = date(2000, 29, 2) # 29th February, in a leap year. # One year is subtracted. 1999 is not a leap year. # Therefore, 1st March 1999 is the result addDate(d, -1, "years") # value: 1999-03-01. d.addDate(-1, "years") # value: 1999-03-01.# One year is added. 2001 is not a leap year. # Therefore, 1st March 2001 is the result addDate(d, 1, "years") # value: 2001-03-01. d.addDate(1, "years") # value: 2001-03-01. # Four years are added. 2004 is a leap year. # Therefore, 29th February 2004 is the result addDate(d, 4, "years") # value: 2004-02-29. d.addDate(4, "years") # value: 2004-02-29.

date

Returns a new date value.

  • date() returns the current date.
  • date(datetime) returns the date component of the specified datetime argument.
  • date(year, month, day) returns a new date with the specified year, month and day. Evaluates to null if either the year, month, or day parameter is null.
  • date(flag) creates a new date, based on the specified numeric flag. If the flag parameter is:

    <0 evaluates to 0000-01-01

    =0 evaluates to current date

    >0 evaluates to 9999-12-31

    null evaluates to null

date(date-string, format) returns a new date, which is constructed by parsing the input date-string using the specified format. The following format parameters (case-sensitive) are supported for parsing the date string:

CC 2 digit century
C 1-2 digit century
YY 2 digit year
Y 1-2 digit year
MM 2 digit month
M 1-2 digit month
m 3 character month name
DD 2 digit day
D 1-2 digit day
d 3 character day name
E epoch time - the number of seconds since 12:00:00 am GMT on Jan. 1, 1970 must be used exclusively of other parameters.

All other text is literal. Evaluates to null if the date-string is null. The format parameter must not be null.

Used in the following format, where flag must be numeric, date-string must be a string representation of a date with format specified by format, format must be a valid format string, year, month and day must be an int or long and datetime must be a datetime:

date()

date(datetime)

date(year, month, day)

date(flag)

date(date-string, format)

datetime.date()

year.date(month, day)

flag.date()

date-string.date(format)

The return value type is a date.

Examples

date() # value: current date

#date(flag) overload - with zero flag. date(0) # value: current date

#date(flag) overload - with positive flag date(2) # value: 9999-12-31

#date(flag) overload - with negative flag date(-1) # value: 0000-01-01

#flag.date() overload - with negative flag flag = -1 flag.date() # value: 0000-01-01

#date(year, month, day) overload date(2000, 8, 15) # value: 2000-08-15

#year.date(month, day) overload year = 2000 year.date(8, 15) # value: 2000-08-15

#date(date-string, format) date("5.2.2002", "M.D.CY") # value: 2002-05-02

#date(date-string, format) date("03152003", "MMDDCCYY") # value: 2003-03-15

#date-string.date(format) dateString = "03152003" dateString.date("MMDDCCYY") # value: 2003-03-15

#date(datetime) date(timestamp(date(2001, 7, 15), time(12, 34, 56))) # value: 2001-07-15

#datetime.date() newDate = date(2001, 7, 15) newTime = time(12, 34,56) dt = timestamp(newDate, newTime) dt.date() # value : 2001-07-15

{{^CurrentDate^}} example

You have a the following input data:

Filmstring Showingdate
Pirates of the Caribbean 2017-05-05
Wonder Woman 2017-06-06
The Mummy 2017-06-17

You want to list only the films that are showing today (2017-06-06).

You type the following Script in a Transform (Superseded) node:

Today = date("{{^CurrentDate^}}","CCYY-MM-DD")emit *where 'Showing' == Today

In this example, only "Wonder Woman" would be listed in the output.

Tip: Note the double quotes around the CurrentDate property and format to give a string value.

dateAdjust

Returns a new date which is the result of adding the specified amount of units to the date parameter. The amount parameter may be negative, in which case the result date will be before the input date. The units parameter must be one of the following (case-insensitive): "days", "months", or "years". If no units are provided, units defaults to "days". Evaluates to null if the date parameter is null. Evaluates to the date parameter if the amount parameter is null. If the input date falls on the 29th February in a leap year, and years are added or subtracted such that the resulting year is not a leap year, then the returned date will be on the 1st March. Equivalent to addDate. To perform the same operation on datetime objects, see dateTimeAdjust.

Used in the following format, where date must be a date, amount is the amount of time to add to the date and must be an int or long, and unit is the unit of the amount to add and can be "days", "months" or "year" (if no units are specified, the default is "days"):

dateAdjust(date, amount[, units])

date.dateAdjust(amount[, units])

The return value type is a date.

Examples

dateAdjust(date(), 1) # value: tomorrow - default of "days" used. date().dateAdjust(1) # value: tomorrow - default of "days" used.

d = date(2000, 8, 15) dateAdjust(d, 5) # value: 2000-08-20 d.dateAdjust(5) # value: 2000-08-20

d = date(2000, 8, 15) dateAdjust(d, 3, "years") # value: 2003-08-15 d.dateAdjust(3, "years") # value: 2003-08-15

d = date(2000, 8, 15) dateAdjust(d, 3, "months") # value: 2000-11-15 d.dateAdjust(3, "months") # value: 2000-11-15

d = date(2000, 8, 15) # The addition of 5 months results in the year incrementing. dateAdjust(d, 5, "months") # value: 2001-01-15. d.dateAdjust(5, "months") # value: 2001-01-15.

d = date(2000, 8, 15) # The addition of 20 days results in the month incrementing. dateAdjust(d, 20, "days") # value: 2000-09-04. d.dateAdjust(20, "days") # value: 2000-09-04.

d = date(2000, 8, 15) # The addition of 150 days results in both the year and the month incrementing. dateAdjust(d, 150, "days") # value: 2001-01-12. d.dateAdjust(150, "days") # value: 2001-01-12.

d = date(2000, 8, 15) # One month is subtracted from the specified date. dateAdjust(d, -1, "months") # value: 2000-07-15. d.dateAdjust(-1, "months") # value: 2000-07-15.

d = date(2000, 29, 2) # 29th February, in a leap year. # One year is subtracted. 1999 is not a leap year. # Therefore, 1st March 1999 is the result dateAdjust(d, -1, "years") # value: 1999-03-01. d.dateAdjust(-1, "years") # value: 1999-03-01. # One year is added. 2001 is not a leap year. # Therefore, 1st March 2001 is the result dateAdjust(d, 1, "years") # value: 2001-03-01. d.dateAdjust(1, "years") # value: 2001-03-01. # Four years are added. 2004 is a leap year. # Therefore, 29th February 2004 is the result dateAdjust(d, 4, "years") # value: 2004-02-29. d.dateAdjust(4, "years") # value: 2004-02-29.

dateSubtract

Returns the difference between the two dates in the specified units. That is, where the specified units is years, then only the year part of the date is used in the calculation. Where the specified units is months, both the month and year part of the dates are used in the calculation. Where the specified units is days, then the day, month and year components are used in the calculation, and so on.

Evaluates to the number of date time units from the date2 parameter to the date1. If date2 falls after date1, the result is negative. Evaluates to null if either parameter is null. If no units parameter is provided, the default of "days" is assumed. For date types, there is no milliseconds component. If two date parameters are provided and "milliseconds" is provided as the units, then the result will be 1000 times the result produced with a "seconds" units value. To subtract a fixed amount of time (for example 1 day or 2 months) from a specified date, see the dateAdjust operator. To subtract a fixed amount of time (for example 1 day or 2 months) from a specified datetime, see the dateTimeAdjust operator.

Used in the following format, where date1 and date2 must be a date or a datetime and units must be a string, one of "years", "months", "weeks", "days", "hours", "minutes", "seconds", or "milliseconds" (if the units are not specified, the default is "days"):

dateSubtract(date1, date2[, units])

date1.dateSubtract(date2[, units])

The return value is a long integer.

Examples

dateSubtract ( dateAdjust(date(), $num), date() ) # value: $num date().dateAdjust($num).dateSubtract(date()) # value: $num

dateSubtract (date(2000, 9, 4),date(2000, 8, 15)) # value: 20 date(2000, 9, 4).dateSubtract(date(2000, 8, 15)) # value: 20

dateSubtract ( date(2000, 8, 15), date(2000, 9, 4)) # value: (long -20) date(2000, 8, 15).dateSubtract(date(2000, 9, 4)) # value: (long -20)

dt1 = timestamp(date(2000, 1, 1), time(0, 0, 0)) dt2 = timestamp(date(2001, 1, 1), time(0, 0, 0))dateSubtract(dt2, dt1, "years") # value: 1

dt1 = timestamp(date(2000, 1, 1), time(0, 0, 13)) dt2 = timestamp(date(2001, 1, 1), time(0, 0, 0))dateSubtract(dt2, dt1, "seconds") # value: 31622387

dt1 = timestamp (date(2007, 10, 22), time(0, 0, 0))dt2 – timestamp (date(2015, 3, 31), time(0, 0, 0))dateSubtract(dt2, dt1,”years”) # value: 8

dt1 = timestamp (date(2007, 2, 12), time(0, 0, 0))dt2 – timestamp (date(2015, 3, 31), time(0, 0, 0))dateSubtract(dt2, dt1,”years”) # value: 8

dt1 = timestamp (date(2000, 1, 25), time(0, 0, 0))dt2 – timestamp (date(2000, 2, 1), time(0, 0, 0))dateSubtract(dt2, dt1,”months”) # value: 1

dt1 = timestamp (date(2000, 1, 1), time(0, 0, 0))dt2 – timestamp (date(2000, 2, 15), time(0, 0, 0))dateSubtract(dt2, dt1,”months”) # value: 1

dateTime

CAUTION:
The use of the datetime operator is not recommended. It is provided only for backwards compatibility reasons. The datetime() operator returns only a long-integer representation of a date time, and as such does not actually correspond correctly to a date-time. It is recommended that the timestamp operator be used, which returns a datetime type which can be used with other Data360 Analyze Script functions. The datetime type returned by the timestamp operator also has a greater range of functionality for dealing with datetime values.

Evaluates to the epoch-time representation of the given moment. Epoch time is the number of seconds since 12:00:00 am GMT on Jan. 1, 1970. Will return 0 for any date value specified before this moment, corresponding to 1969-12-31 23:00:00. Evaluates to null if the date parameter is null. Defaults to the specified date and a time of 00:00:00 (12 am) if the time parameter is null.

Used in the following format, where date must be a date and time must be a time:

dateTime(date, time)

date.dateTime(time)

The return value type is a long integer.

Examples

#dateTime(date, time) dateTime(date(2003, 3, 17), time(0, 0, 0)) # value: (long 1079524800)

#date.dateTime(time) newDate = date(2003, 3, 17) newTime = time(0, 0, 0) newDate.dateTime(newTime) # value: (long 1079524800)

dateTimeAdjust

Returns a new datetime which is the result of adding the specified amount of units to the datetime parameter. The amount parameter may be negative, in which case the result date will be before the input date. The units parameter must be one of the following (case-insensitive): "years", "months", "weeks", "days", "hours", "minutes", "seconds" or "milliseconds" If no units are provided, units defaults to "days". Evaluates to null if the datetime parameter is null. Evaluates to the datetime parameter if the amount parameter is null. If the input date falls on the 29th February in a leap year, and years are added or subtracted such that the resulting year is not a leap year, then the returned date will be on the 28th February. To perform the same operation on date objects, see dateAdjust.

Used in the following format, where dateTime must be a dateTime, amount must be an int or long and is the amount of time to add to the datetime, and units is the unit of the amount to add and can be "years", "months", "weeks", "days", "hours", "minutes", "seconds" or "milliseconds":

dateTimeAdjust(dateTime, amount[, units])

dateTime.dateTimeAdjust(amount[, units])

The return value type is datetime.

Examples

dateTimeAdjust(timestamp(), 1) # value: tomorrow timestamp().dateTimeAdjust(1) # value: tomorrow

dt = timestamp(date(2000, 8, 15)) dateTimeAdjust(dt, 5) # value: 2000-08-20 00:00:00 dt.dateTimeAdjust(5) # value: 2000-08-20 00:00:00

dt = timestamp(date(2000, 8, 15)) dateTimeAdjust(dt, 2, "months") # value: 2000-10-15 00:00:00 dt.dateTimeAdjust(2, "months") # value: 2000-10-15 00:00:00

dt = timestamp(date(2000, 8, 15)) dateTimeAdjust(dt, -3, "years") # value: 1997-08-15 00:00:00 dt.dateTimeAdjust(-3, "years") # value: 1997-08-15 00:00:00

dt = timestamp(date(2000, 8, 15), time(1, 0, 0)) dateTimeAdjust(dt, 2, "hours") # value: 2000-08-15 03:00:00 dt.dateTimeAdjust(2, "hours") # value: 2000-08-15 03:00:00

dt = timestamp(date(2000, 8, 15)) # The addition of 5 months results in the year incrementing. dateTimeAdjust(dt, 5, "months") # value: 2001-01-15 00:00:00. dt.dateTimeAdjust(5, "months") # value: 2001-01-15 00:00:00.

dt = timestamp(date(2000, 8, 15)) # The addition of 20 days results in the month incrementing. dateTimeAdjust(dt, 20, "days") # value: 2000-09-04 00:00:00. dt.dateTimeAdjust(20, "days") # value: 2000-09-04 00:00:00.

dt = timestamp(date(2000, 8, 15)) # The addition of 150 days results in both the year and the month incrementing. dateTimeAdjust(dt, 150, "days") # value: 2001-01-12 00:00:00. dt.dateTimeAdjust(150, "days") # value: 2001-01-12 00:00:00.

d = timestamp(date(2000, 29, 2)) # 29th February, in a leap year. # One year is subtracted. 1999 is not a leap year. # Therefore, 28th February 1999 is the result dateTimeAdjust(d, -1, "years") # value: 1999-02-28 00:00:00. d.dateTimeAdjust(-1, "years") # value: 1999-02-28 00:00:00. # One year is added. 2001 is not a leap year. # Therefore, 28th February 2001 is the result dateTimeAdjust(d, 1, "years") # value: 2001-02-28 00:00:00. d.dateTimeAdjust(1, "years") # value: 2001-02-28 00:00:00. # Four years are added. 2004 is a leap year. # Therefore, 29th February 2004 is the result dateTimeAdjust(d, 4, "years") # value: 2004-02-29 00:00:00. d.dateTimeAdjust(4, "years") # value: 2004-02-29 00:00:00.

day

There are three forms: day(dateTime) Evaluates to the day of the month in the date or datetime object. Returned value Type: integer. Returned value range: 0-23. day(interval) Evaluates to the number of days in the interval. Returned value type: long. Returned value range: unbounded. day(interval, baseDateTime) Evaluates to the number of calendar days expired in the interval since the baseDateTime. Returned value type: long. Returned value range: unbounded. All forms evaluate to null if any of the parameters are null.

Used in the following format, where dateTime must be a date or datetime, interval must be a long and baseDateTime must be a datetime:

day(dateTime)

dateTime.day()

day(interval)

interval.day()

day(interval, baseDateTime)

interval.day(baseDateTime)

The return value type is an integer or long.

Examples

day(date()) # value: the current day of the current month day(timestamp()) # value: the current day of the current month

day(date(2000, 1, 5)) # value: 5

day(timestamp(date(2000, 1, 17), time(15,30,2))) # value: 17

interval = 60*60*60*long(1000) # 60 hours day(interval) # value: 2

dt1 = timestamp(date(2000, 3, 1), time(13, 0, 0)) interval = 60*60*60*long(1000) # 60 hours day(interval, dt1) # value: 3

hours

There are three forms: hours(dateTime) Evaluates to the hour of the day in the time or datetime object. Returned value Type: integer. Returned value range: 0-23. hours(interval) Evaluates to the number of hours in the interval. Returned value type: long. Returned value range: unbounded. hours(interval, baseDateTime) Evaluates to the number of calendar hours expired in the interval since the baseDateTime. Returned value type: long. Returned value range: unbounded. All forms evaluate to null if any of the parameters are null.

Used in the following format, where dateTime must be a time or a datetime, interval must be a long and baseDateTime must be a datetime:

hours(dateTime)

dateTime.hours()

hours(interval)

interval.hours()

hours(interval, baseDateTime)

interval.hours(baseDateTime)

The return value type is an integer or long.

Examples

hours(time()) # value: the current hour of the current day hours(timestamp()) # value: the current hour of the current day

hours(time(12, 34, 56)) # value: 12

hours(timestamp(date(2000, 1, 1), time(15,30,2))) # value: 15

interval = 150*60*long(1000) hours(interval) # value: 2

dt1 = timestamp(date(2000, 3, 4), time(0, 31, 0)) interval = 150*60*long(1000) hours(interval, dt1) # value: 3

milliseconds

There are three forms: milliseconds(dateTime) Evaluates to the fractional seconds in the time or datetime object. For time values this always returns 0. Value Type: integer. milliseconds(interval) Evaluates to the number of milliseconds in the interval. Value Type: long milliseconds(interval, baseDateTime) Evaluates to the number of calendar milliseconds expired in the interval since the baseDateTime. Value Type: long All forms evaluate to null if any of the parameters are null.

Used in the following format, where dateTime must be a time or a datetime, interval must be a long and baseDateTime must be a datetime:

milliseconds(dateTime)

dateTime.milliseconds()

milliseconds(interval)

interval.milliseconds()

milliseconds(interval, baseDateTime)

interval.milliseconds(baseDateTime)

The return value type is an integer or long.

Examples

milliseconds(time()) # value: 0 milliseconds(timestamp()) # value: current fractional seconds

milliseconds(time(15,30,2)) # value: 0

milliseconds(timestamp(date(2000, 1, 1), time(15,30,2))) # value: 0

dt1 = timestamp(date(2000, 3, 4), time(0, 0, 0)) dt2 = datetimeAdjust(dt1, 1234, "milliseconds") milliseconds(dt2-dt1) # value: 1234

dt1 = timestamp(date(2000, 3, 4), time(0, 0, 0)) dt2 = datetimeAdjust(dt1, 1234, "milliseconds") milliseconds(dt2-dt1, dt1) # value: 1234

minutes

There are three forms: minutes(dateTime) Evaluates to the minute of the hour in the time or datetime object. Returned value Type: integer. Returned value range: 0-59. minutes(interval) Evaluates to the number of minutes in the interval. Returned value type: long. Returned value range: unbounded. minutes(interval, baseDateTime) Evaluates to the number of calendar minutes expired in the interval since the baseDateTime. Returned value type: long. Returned value range: unbounded. All forms evaluate to null if any of the parameters are null.

Used in the following format, where dateTime must be a time or a datetime, interval must be a long and baseDateTime must be a datetime:

minutes(dateTime)

dateTime.minutes()

minutes(interval)

interval.minutes()

minutes(interval, baseDateTime)

interval.minutes(baseDateTime)

The return value type is an integer or long.

Examples

minutes(time()) # value: the current minute of the current hour minutes(timestamp()) # value: the current minute of the current hour

minutes(time(12, 34, 56)) # value: 34

minutes(timestamp(date(2000, 1, 1), time(15,30,2))) # value: 30

interval = 150*long(1000) minutes(interval) # value: 2

dt1 = timestamp(date(2000, 3, 4), time(0, 0, 31)) interval = 150*long(1000) minutes(interval, dt1) # value: 3

month

There are two forms: month(dateTime) Evaluates to the month of the year in the date or datetime object. Returned value Type: integer. Returned value range: 1-12. month(interval, baseDateTime) Evaluates to the number of calendar months expired in the interval since the baseDateTime. Returned value type: long. Returned value range: unbounded. All forms evaluate to null if any of the parameters are null.

Note: Unlike other date and time unit accessors, the single interval argument form does not exist for the month or year operators. A month or year is not a uniform unit of time and therefore cannot be calculated without a base date and time.

Used in the following format, where dateTime must be a time or a datetime, interval must be a long and baseDateTime must be a datetime:

month(dateTime)

dateTime.month()

month(interval, baseDateTime)

interval.month(baseDateTime)

The return value type is an integer or long.

Examples

month(date()) # value: the current month of the current year month(timestamp()) # value: the current month of the current year

month(date(2000, 1, 5)) # value: 1

month(timestamp(date(2000, 11, 15), time(15,30,2))) # value: 11

dt1 = timestamp(date(2000, 1, 1), time(0, 0, 0)) interval = 75*24*60*60*long(1000) # 75 days month(interval, dt1) # value: 3

seconds

There are three forms: seconds(dateTime) Evaluates to the second of minute in the time or datetime object. Returned value Type: integer. Returned value range: 0-59. seconds(interval) Evaluates to the number of seconds in the interval. Returned value type: long. Returned value range: unbounded. seconds(interval, baseDateTime) Evaluates to the number of calendar seconds expired in the interval since the baseDateTime. Returned value type: long. Returned value range: unbounded. All forms evaluate to null if any of the parameters are null.

Used in the following format, where dateTime must be a time or a datetime, interval must be a long and baseDateTime must be a datetime:

seconds(dateTime)

dateTime.seconds()

seconds(interval)

interval.seconds()

seconds(interval, baseDateTime)

interval.seconds(baseDateTime)

The return value type is an integer or long.

Examples

seconds(time()) # value: the current second of the current minute seconds(timestamp()) # value: the current second of the current minute

seconds(time(12, 34, 56)) # value: 56

seconds(timestamp(date(2000, 1, 1), time(15,30,2))) # value: 2

dt1 = timestamp(date(2000, 3, 4), time(0, 0, 0)) dt2 = datetimeAdjust(dt1, 1234, "seconds") seconds(dt2-dt1) # value: 1234

dt1 = timestamp(date(2000, 3, 4), time(0, 0, 0)) interval = long(1234) seconds(interval, dt1) # value: 1

time

Returns a new time value. With no parameters, evaluates to the current time. With a single datetime argument, the operator creates a time value whose value is the time part of the datetime. With integer hours, minutes and seconds arguments, a new time is constructed with the specified hours, minutes and seconds. Evaluates to null if either the hours, minutes, or seconds argument is null. With a single, numeric flag argument, if the flag parameter is:

<0 evaluates to 00:00:00

=0 evaluates to current time

>0 evaluates to 24:00:00

null evaluates to null

With string time-stamp and string format parameters, the time-stamp string is parsed into a time object using the specified time format . The following format parameters (case-insensitive) are supported for parsing the time string:

HH 2 digit hour
H 1-2 digit hour
MM 2 digit minutes
M 1-2 digit minutes
SS 2 digit seconds
S 1-2 digit seconds
AM "AM" or "PM" (case-insensitive)
PM "AM" or "PM" (case-insensitive)
A "A" or "P" (case-insensitive)
P "A" or "P" (case-insensitive)
: colon
whitespace any contiguous whitespace (perhaps none)
E epoch time - the number of seconds since 12:00:00 am GMT on Jan. 1, 1970 must be used exclusively of other parameters.

No other text is allowed. Evaluates to null if the time-string string is null. The format parameter must not be null.

Used in the following format, where flag must be numeric, time-string and format must be a string, hours, minutes and seconds must be an int or long and datetime must be a datetime:

time()

time(datetime)

time(hours, minutes, seconds)

time(flag)

time(time-string, format)

datetime.time()

hours.time(minutes, seconds)

flag.time()

time-string.time(format)

The return value type is a time.

Examples

time() # value: current time

#Invoking the time(flags) overload with a negative value time(-3.5) # value: 00:00:00

#Invoking the time(flags) overload with a 0 value time(0) # value: current time

#Invoking the time(flags) overload with a positive value time(2) # value: 24:00:00

#Invoking the flags.time() overload with a positive value flag = 2 flag.time() # value: 24:00:00

#Parsing the time string with 1-2 digit hours, minutes and seconds # all separated by ':' characters and an AM/PM string time("3:30:2 pm", "H:M:S AM") # value: 15:30:02 "3:30:2 pm".time("H:M:S AM") # value: 15:30:02

#Parsing the time string with: # 2 digit hours # 2 digit minutes # 2 digit seconds time("153002", "HHMMSS") # value: 15:30:02 "153002".time("HHMMSS") # value: 15:30:02

#Invoking the time(hours, minutes, seconds) overload. time(15, 30, 2) # value: 15:30:02

#Invoking the (not commonly used or recommended) #hours.time(minutes, seconds) overload. hours = 15 hours.time(30, 2) # value: 15:30:02

#Obtaining the time component of a datetime time(timestamp(date(2005, 3, 7), time(15, 30, 2))) # value: 15:30:02

#Obtaining the time component of a datetime, using infix notation newDateTime = timestamp(date(2005, 3, 7), time(15, 30, 2))newDatTime.time() # value: 15:30:02

timestamp

Creates a datetime object. The datetime object has a resolution of milliseconds and a range of 292272993-01-04 16:47:04 BCE to 292272993-01-04 07:12:55 CE. timestamp() Evaluates to a datetime value representing the current date and time timestamp(date[, time]) Evaluates to a datetime value whose date and time components are to the date and time arguments respectively. If no time component is provided, 00:00:00 is used. timestamp(epochMs) Evaluates to the datetime value represented by the number of milliseconds since the epoch, 1970-1-1 00:00:00, in the local timezone. All forms evaluate to null if the first parameter is null. For the timestamp(date[, time]) and timestamp(epochMs) forms, the corresponding infix notation can be used: date.timestamp([time]) and epochMs.timestamp()

Note: timestamp is a transitional name for the operator, until the existing datetime operator can be deprecated.

Used in the following format, where date must be a date, time must be a time and epochMs must be a long, representing milliseconds since epoch:

timestamp()

timestamp(date[, time])

timestamp(epochMs)

date.timestamp([time])

ephochMs.timestamp()

The return value type is a datetime.

Examples

#Providing the date and time dateVal = date(2003, 3, 17) timeval = time(15, 22, 35) timestamp(dateVal, timVal) # value: 2003-03-17 15:22:35 CE

#Providing the date and time using infix notation dt = date(2003, 3, 17) dt.timestamp(time(15, 22, 35)) # value: 2003-03-17 15:22:35 CE

#Providing the date only timestamp(date(2003, 3, 17)) # value: 2003-03-17 00:00:00 CE

#Providing the date only using infix notation dt = date(2003, 3, 17) dt.timestamp() # value: 2003-03-17 00:00:00 CE

#Providing a long value in ms since epoch - get the epoch. timestamp(0) # value: 1970-1-1 00:00:00 CE

#Providing a long value in ms since epoch timestamp(long(24*60*60*1000)) # value: 1970-1-2 00:00:00 CE

timestamp() # value: current date and time

timeSubtract

Evaluates to the number of seconds from the second time parameter to the first. If the first parameter falls after the second, the result is negative. Evaluates to null if either parameter is null.

Used in the following format, where time1 and time2 must be a time:

timeSubtract(time1, time2)

time1.timeSubtract(time2)

The return value type is a long integer.

Examples

timeSubtract(time(15, 30, 2), time(15, 27, 49)) # value: (long 133) time(15, 30, 2).timeSubtract(time(15, 27, 49)) # value: (long 133)

timeSubtract(time(15, 30, 2), time(17, 7, 25)) # value: (long -5843) time(15, 30, 2).timeSubtract(time(17, 7, 25)) # value: (long -5843)

week

There are three forms: week(dateTime) Evaluates to the week of the year in the date or datetime object. Returned value Type: integer. Returned value range: 1-53. week(interval) Evaluates to the number of weeks in the interval. Returned value type: long. Returned value range: unbounded. week(interval, baseDateTime) Evaluates to the number of calendar weeks expired in the interval since the baseDateTime. Returned value type: long. Returned value range: unbounded. All forms evaluate to null if any of the parameters are null.

Used in the following format, where dateTime must be a time or a datetime, interval must be a long and baseDateTime must be a datetime:

week(dateTime)

dateTime.week()

week(interval)

interval.week()

week(interval, baseDateTime)

interval.week(baseDateTime)

The return value type is an integer or long.

Examples

week(date()) # value: the current week of the current year week(timestamp()) # value: the current week of the current year

week(date(2000, 1, 5)) # value: 2

week(timestamp(date(2000, 11, 15), time(15,30,2))) # value: 47

interval = 17*24*60*60*long(1000) # 17 days week(interval) # value: 2

dt1 = timestamp(date(2000, 1, 6), time(0, 0, 0)) # 2000-1-6 was a Thu. interval = 17*24*60*60*long(1000) # 17 days week(interval, dt1) # value: 3

weekday

There is one form: weekday(dateTime) Returns a number representing the day of the week of the given date or datetime parameter. The week begins on Sunday; the weekday for Sunday is zero. Returned value Type: integer. Returned value range: 0-6. Evaluates to null if the given dateTime parameter is null.

Used int he following format, where dateTime must be a date or a datetime:

weekday(dateTime)

dateTime.weekday()

The return value type is an integer.

Examples

weekday(date()) # value: today's day of the week weekday(timestamp()) # value: today's day of the week

weekday(date(1970,1,1)) # value: 4 (Thursday)

weekday(timestamp(date(1970,1,1), time(15,30,2))) # value: 4 (Thursday)

year

There are two forms: year(dateTime) Evaluates to the year in the date or datetime object. Returned value Type: integer. Returned value range: unbounded. year(interval, baseDateTime) Evaluates to the number of calendar years expired in the interval since the baseDateTime. Returned value type: long. Returned value range: unbounded. All forms evaluate to null if any of the parameters are null.

Note: Unlike other date and time unit accessors, the single interval argument form does not exist for the month or year operators. A month or year is not a uniform unit of time and therefore cannot be calculated without a base date and time.

Used in the following format, where dateTime must be a time or a datetime, interval must be a long and baseDateTime must be a datetime:

year(dateTime)

dateTime.year()

year(interval, baseDateTime)

interval.year(baseDateTime)

The return value type is an integer or long.

Examples

year(date()) # value: the current year year(timestamp()) # value: the current year

year(date(2000, 1, 5)) # value: 2000

year(timestamp(date(2000, 11, 15), time(15,30,2))) # value: 2000

dt1 = timestamp(date(2000, 12, 31), time(0, 0, 0)) interval = 24*60*60*long(1000) # 1 day year(interval, dt1) # value: 1