Date Functions
The Date functions provide methods for creating date objects and getting various properties of the objects. The DateAdd() and DateDiff() functions are convenient for adjusting the desired date based on a specified interval. The Now() function may also be used to get the current time in the local time of the client.
Date - DateAdd - DateDiff - Day - Hour - ISOMonth - ISOWeek - ISOWeekday - ISOYear - Millisecond - Minute - Month - Now - Second - Timestamp - Today - ToLocal - ToUTC - Weekday - Year
Date
This function has 3 signatures:
- Date( year, month, day, hour?, minute?, second?, millisecond? ) ->
Date - Date( epoch? ) ->
Date - Date( timestamp? ) ->
Date
Date( year, month, day, hour?, minute?, second?, millisecond? ) -> Date
Parses a value or set of values to a Date object. See the example snippets below to view various ways this function may be used.
| Name | Type | Description |
|---|---|---|
| year | Number | A number representing a year. |
| month | Number | The month (0-11) where 0 is January and 11 is December. |
| day | Number | The day of the month (1-31). |
| hour | Number | optional The hour of the day (0-23). |
| minute | Number | optional The minute of the hour (0-59). |
| second | Number | optional The second of the minute (0-59). |
| millisecond | Number | optional The millisecond of the second (0-999). |
Returns: Date
Example
Year, month, day
prints 'Tue Jun 02 1987 00:00:00 GMT-0700 (PDT)'
Date(1987,05,02)
With no parameters
prints the current date and time
Date()
Date( epoch? ) -> Date
Converts a Unix epoch number to a Date object.
| Name | Type | Description |
|---|---|---|
| epoch | Number | optional The number of milliseconds since January 1, 1970 UTC. |
Returns: Date
Example
Create a date with the value of a date field
returns a date object based on a field value
var recordDate = Date($feature.dateField)
Milliseconds since epoch
prints 'Thu Oct 20 2016 11:23:03 GMT-0700 (PDT)'
Date(1476987783555)
Date( timestamp? ) -> Date
Converts an ISO 8601 string to a Date object.
| Name | Type | Description |
|---|---|---|
| timestamp | Text | optional An ISO 8601 string to be converted into a date. |
Returns: Date
Example
ISO 8601 string
prints 'Thu Oct 20 2016 10:41:37 GMT-0700 (PDT)'
Date('2016-10-20T17:41:37+00:00')
DateAdd
DateAdd( date, addValue, units ) -> Date
Adds a specified amount of time in the given units to a date and returns a new date.
| Name | Type | Description |
|---|---|---|
| date | Date | The input date to which to add time. |
| addValue | Number | The value to add to the date in the given units. |
| units | Text | The units of the number to add to the date. The supported unit types include milliseconds, seconds, minutes, hours, days, months, years |
Returns: Date
Example
Adds 7 days to the date in the provided field
var startDate = Date($feature.dateField);
var oneWeekLater = DateAdd(startDate, 7, 'days');
return oneWeekLater;
DateDiff
DateDiff( date1, date2, units? ) -> Number
Subtracts two dates, and returns the difference in the specified units.
| Name | Type | Description |
|---|---|---|
| date1 | Date | The date value from which to subtract a second date. |
| date2 | Date | The date value to subtract from the first given date. |
| units | Text | optional The units in which to return the difference of the two given dates. The supported unit types include milliseconds, seconds, minutes, hours, days, months, years. The default value is milliseconds. |
Returns: Number
Example
Subtracts two dates and returns the age
var startDate = Date($feature.startDateField);
var endDate = Date($feature.endDateField);
var age = DateDiff(endDate, startDate, 'years');
return age;
Day
Day( dateValue ) -> Number
Returns the day of the month of the given date.
| Name | Type | Description |
|---|---|---|
| dateValue | Date | A date value from which to get the day of the month. |
Returns: Number
Example
Gets the day of the month of the current date
Day(Now())
Hour
Hour( dateValue ) -> Number
Returns the hour of the time in the given date (0-23).
| Name | Type | Description |
|---|---|---|
| dateValue | Date | A date value from which to get the hour of the time. |
Returns: Number
Example
Gets the hour of the current time
Hour(Now())
ISOMonth
ISOMonth( dateValue ) -> Number
Returns the month of the given date, based on the ISO 8601 standard. Values range from 1-12 where January is 1 and December is 12.
| Name | Type | Description |
|---|---|---|
| dateValue | Date | A date value from which to get the month. |
Returns: Number
Example
Gets the month of the given date, based on the ISO 8601 standard. Returns 12, for the month of December.
ISOMonth(Date(1980, 11, 31))
ISOWeek
ISOWeek( dateValue ) -> Number
Returns the week in the year of the given date, based on the ISO 8601 week date calendar. Values range from 1-53 where the first week of the year is 1 and the last week of the year is 52 or 53, depending on the year.
| Name | Type | Description |
|---|---|---|
| dateValue | Date | A date value from which to get the week. |
Returns: Number
Example
Gets the week of the given date, based on the ISO 8601 standard. Returns 1, since this date is included in the first week of the following year.
ISOWeek(Date(1980, 11, 31))
ISOWeekday
ISOWeekday( dateValue ) -> Number
Returns the day of the week of the given date, based on the ISO 8601 standard. Values range from 1-7 where Monday is 1 and Sunday is 7.
| Name | Type | Description |
|---|---|---|
| dateValue | Date | A date value from which to return the day of the week. |
Returns: Number
Example
Returns the day of the week of the given date, based on the ISO 8601 standard. Returns 3, for Wednesday.
ISOWeekday(Date(1980, 11, 31))
ISOYear
ISOYear( dateValue ) -> Number
Returns the year of the given date based on the ISO 8601 week date calendar.
| Name | Type | Description |
|---|---|---|
| dateValue | Date | A date value from which to get the year. |
Returns: Number
Example
Gets the year of the given date, based on the ISO 8601 week date calendar. Returns 1981, since this date is included in the first week of the following year.
ISOYear(Date(1980, 11, 31))
Millisecond
Millisecond( dateValue ) -> Number
Returns the millisecond of the time in the date.
| Name | Type | Description |
|---|---|---|
| dateValue | Date | A date value from which to get the millisecond of the time. |
Returns: Number
Example
Gets the millisecond of the current time
Millisecond(Now())
Minute
Minute( dateValue ) -> Number
Returns the minute of the time in the given date.
| Name | Type | Description |
|---|---|---|
| dateValue | Date | A date value from which to get the minute of the time. |
Returns: Number
Example
Gets the minute of the current time
Minute(Now())
Month
Month( dateValue ) -> Number
Returns the month of the given date. Values range from 0-11 where January is 0 and December is 11.
| Name | Type | Description |
|---|---|---|
| dateValue | Date | A date value from which to get the month. |
Returns: Number
Example
Gets the month of the given Date. Returns 11, for the month of December.
Month(Date(1980, 11, 31))
Now
Now( ) -> date
Returns the current date and time in the local time of the client.
Returns: date
Example
Returns the current date and time
e.g. Mon Oct 24 2016 12:09:34 GMT-0700 (PDT)
Now()
Second
Second( dateValue ) -> Number
Returns the second of the time in the date.
| Name | Type | Description |
|---|---|---|
| dateValue | Date | A date value from which to get the second of the time. |
Returns: Number
Example
Gets the second of the current time
Second(Now())
Timestamp
Timestamp( ) -> Date
Returns the current date and time in UTC time.
Returns: Date
Example
Returns the current date and time in UTC time
e.g. 29 Mar 2017 08:37:33 pm
Timestamp()
Today
Today( ) -> Date
Returns the current date in the local time of the client.
Returns: Date
Example
Returns the current date with time truncated
e.g. Mon Oct 24 2016 00:00:00 GMT-0700 (PDT)
Today()
ToLocal
ToLocal( utcDate ) -> Date
Converts the given UTC date to a date value in the local time of the client.
| Name | Type | Description |
|---|---|---|
| utcDate | Date | A UTC date value to convert to the local time of the client. This value is assumed to be in UTC time. |
Returns: Date
Example
Convert a UTC date to the local time of the client running the app
e.g. Mon Oct 24 2016 00:00:00 GMT-0700 (PDT)
ToLocal(Timestamp())
ToUTC
ToUTC( localDate ) -> Date
Converts the given date value from the client's local time to UTC time.
| Name | Type | Description |
|---|---|---|
| localDate | Date | A date value in local time to convert to UTC time. This value is assumed to be in local time. |
Returns: Date
Example
Returns the current date and time in UTC
e.g. 29 Mar 2017 08:37:33 pm
// 29 Mar 2017 01:37:33 pm
Now()
// 29 Mar 2017 08:37:33 pm
ToUTC(Now())
Weekday
Weekday( dateValue ) -> Number
Returns the day of the week of the given date. Values range from 0-6 where Sunday is 0 and Saturday is 6.
| Name | Type | Description |
|---|---|---|
| dateValue | Date | A date value from which to return the day of the week. |
Returns: Number
Example
Returns the day of the week of the given date. Returns 3, for Wednesday.
Weekday(Date(1980, 11, 31))
Year
Year( dateValue ) -> Number
Returns the year of the given date.
| Name | Type | Description |
|---|---|---|
| dateValue | Date | A date value from which to get the year. |
Returns: Number
Example
Gets the year of the current date
Year(Now())
Feedback on this topic?