Date functions

The Date functions provide methods for creating Date values, calculating new Dates, getting various properties of Dates, and changing a Date's display properties.

ChangeTimeZone

ChangeTimeZone(dateValue, newTimeZone) -> Date

Since version 1.24

Function bundle: Core

Changes the time zone used to display the given Date value. If the input dateValue has an unknown time zone, then the output Date value will display with the same date and time as the input dateValue, but will be assigned the newTimeZone.

Parameters

• dateValue: Date - A Date value containing date and time information.

• newTimeZone: Text - The new time zone that will be used to display the given Date value. The time zone must be one of the following:

  • text representing an entry in the IANA time zone database (e.g. America/New_York)

  • text representing the hours and minutes that should be added to UTC (e.g. +07:00 or -03:00)

  • system - time zone will be set to the device or system's local time zone

  • default - the time zone of the profile's execution context

  • UTC - Coordinated Universal Time

  • unknown - removes time zone information for the given value and displays the date and time as defined in the expression.

Return value: Date

Additional resources

• IANA time zone database
• Arcade execution context
• ToLocal()
• ToUTC()

Examples

Changes the given Date's time zone from America/New_York to America/Los_Angeles

1
2
3
var inputDate = Date(2011,10,11,8,0,0,0, "America/New_York")
ChangeTimeZone(inputDate, "America/Los_Angeles");
// returns a Date representing Nov 11, 2011, 5:00:00 AM PST

Assigns a Date with an unknown time zone to a time offset of +07:00

1
2
3
var inputDate = Date(2011,10,11,8,0,0,0, "unknown")
ChangeTimeZone(inputDate, "+07:00");
// returns a Date representing Nov 11, 2011, 8:00:00 AM +07:00

Date

This function has 5 signatures:

• Since v1.0 - Date(year, month, day, hour?, minute?, second?, millisecond?, timeZone?) -> Date
• Since v1.0 - Date(epoch?) -> Date
• Since v1.0 - Date(timestamp?) -> Date
• Since v1.24 - Date(dateOnlyValue, timeValue?, timeZone?) -> Date
• Since v1.24 - Date(dateValue) -> Date

Date(year, month, day, hour?, minute?, second?, millisecond?, timeZone?) -> Date

Since version 1.0

Function bundle: Core

Creates a Date object from a set of parameters. By default, Dates are created in the time zone of the profile's execution context.

Parameters

• 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 (Optional): Number - The hour of the day (0-23).

• minute (Optional): Number - The minute of the hour (0-59).

• second (Optional): Number - The second of the minute (0-59).

• millisecond (Optional): Number - The millisecond of the second (0-999).

• timeZone (Optional): Text - Since 1.24 The time zone of the Date. If not specified, the Date will be created in the default time zone of the profile's execution context. Possible values:

  • text representing an entry in the IANA time zone database (e.g. America/New_York)

  • text representing the hours and minutes that should be added to UTC (e.g. +07:00 or -03:00)

  • system - time zone will be set to the device or system's local time zone

  • default - the time zone of the profile's execution context

  • UTC - Coordinated Universal Time

  • unknown - removes time zone information for the given value and displays the date and time as defined in the expression.

Return value: Date

Additional resources

• IANA time zone database
• Arcade execution context

Examples

Creates a Date representing the given time in the time zone of the profile's execution context running Arcade

1
2
// Date that represents Jun 02, 1987, 12:00:00 AM PST
Date(1987,05,02)

Creates a Date with time defined in a specific time zone

1
2
Date(1990, 10, 2, 2, 23, 0, 0, "America/New_York");
 // Date represents Nov 2, 1990, 2:23:00 AM EST

Date(epoch?) -> Date

Since version 1.0

Function bundle: Core

Creates a Date with the given Unix epoch number. By default, the Date will display in the time zone of the profile's execution context. If no epoch is provided, creates a Date at the current date and time in the default time zone of the profile. If a null value is provided for the epoch, it will be implicitly cast to 0 and will return the date for January 1, 1970 UTC.

Parameter

• epoch (Optional): Number - The number of milliseconds since January 1, 1970 UTC.

Return value: Date

Additional resources

• Arcade execution context
• Now()
• Timestamp()
• Today()

Examples

Milliseconds since January 1, 1970

1
Date(1476987783555) // 'Thu Oct 20 2016 11:23:03 GMT-0700 (PDT)'

Creates a Date representing the current time in the time zone of the profile's execution context running Arcade

1
2
// Date represents Jan 27, 2023, 12:41:20 PM PST
Date()

Date(timestamp?) -> Date

Since version 1.0

Function bundle: Core

Creates a Date value from an ISO 8601 text value. If a UTC offset is provided, the date will still be displayed in the time zone of the profile. If no text value is provided, creates a date at the current date and time in the time zone of the profile.

Parameter

• timestamp (Optional): Text - An ISO 8601 text value to be converted into a Date.

Return value: Date

Examples

Creates a Date from an ISO 8601 text value with a known time offset

1
Date('2016-10-20T17:41:37+00:00') // 'Thu Oct 20 2016 10:41:37 GMT-0700 (PDT)'

Creates a Date from an ISO 8601 text value with an unknown time offset

1
Date('2016-10-20T17:41:37') // 'Thu Oct 20 2016 5:41:37 PM PDT'

Date(dateOnlyValue, timeValue?, timeZone?) -> Date

Since version 1.24

Function bundle: Core

Creates a Date from a DateOnly value, with an optional Time and time zone value.

Parameters

• dateOnlyValue: DateOnly - The DateOnly value from which to create a Date value.

• timeValue (Optional): Time - The Time value for the Date. If not specified, the Date will be created with a time of 00:00:00.

• timeZone (Optional): Text - The time zone of the Date. If not specified, the Date will be created in the unknown time zone. Possible values:

  • text representing an entry in the IANA time zone database (e.g. America/New_York)

  • text representing the hours and minutes that should be added to UTC (e.g. +07:00 or -03:00)

  • system - time zone will be set to the device or system's local time zone

  • default - the time zone of the profile's execution context

  • UTC - Coordinated Universal Time

  • unknown - removes time zone information for the given value and displays the date and time as defined in the expression.

Return value: Date

Additional resources

• IANA time zone database
• Arcade execution context

Example

Creates a Date from a DateOnly and time type

1
2
Date(DateOnly(2022,10,11), Time("11:20 am"))
// returns a Date representing Nov 11, 2022, 11:20:00 AM in an unknown time zone

Date(dateValue) -> Date

Since version 1.24

Function bundle: Core

Creates a copy of the given Date.

Parameter

• dateValue: Date - The Date to copy.

Return value: Date

Example

Creates a copy of the current Date value

1
var copiedDate = Date(Now())

DateAdd

This function has 3 signatures:

• Since v1.0 - DateAdd(dateValue, addValue, units?) -> Date
• Since v1.24 - DateAdd(dateOnlyValue, addValue, units?) -> DateOnly
• Since v1.24 - DateAdd(timeValue, addValue, units?) -> Time

DateAdd(dateValue, addValue, units?) -> Date

Since version 1.0

Function bundle: Core

Adds a specified amount of time in the given units to a Date and returns a new Date. If the Date has an IANA time zone, then daylight saving and other time zone driven logic will apply.

Parameters

• dateValue: Date - The input Date to which to add time.
• addValue: Number - The value to add to the Date in the given units.
• units (Optional): Text - The units of the number to add to the Date. Default is milliseconds. The supported unit types include milliseconds, seconds, minutes, hours, days, months, years

Return value: Date

Example

Adds 7 days to the given Date

1
2
3
4
var startDate = Date(2023, 9, 1, 12, 00);
var oneWeekLater = DateAdd(startDate, 7, 'days');
return oneWeekLater;
// returns a Date representing Oct 8, 2023, 12:00:00 PM PDT

DateAdd(dateOnlyValue, addValue, units?) -> DateOnly

Since version 1.24

Function bundle: Core

Adds a specified amount of time in the given units to a DateOnly value and returns a new DateOnly value.

Parameters

• dateOnlyValue: DateOnly - The input DateOnly value to which to add time.
• addValue: Number - The value to add to the date in the given units. For DateOnly inputs, this value will be rounded down to the nearest day based on a 24-hour interval. If the value to be added is less than 24 hours, then no value will be added to the DateOnly input.
• units (Optional): Text - The units of the number to add to the date. Default is milliseconds. The supported unit types include milliseconds, seconds, minutes, hours, days, months, years

Return value: DateOnly

Examples

Adds 7 days to the Date in the provided field

1
2
3
4
var startDate = DateOnly(2023,5,4); // equivalent to 2023-06-04
var oneWeekLater = DateAdd(startDate, 7, 'days');
return oneWeekLater;
// returns 2023-06-11

Adds 12 hours to the Date in the provided field

1
2
3
4
5
var startDate = DateOnly(2023,5,4); // equivalent to 2023-06-04
var hoursLater = DateAdd(startDate, 12, 'hours');
return hoursLater;
// returns the original start date, 2023-06-04
// since 12 hours < 1 day, the DateOnly input is not changed

DateAdd(timeValue, addValue, units?) -> Time

Since version 1.24

Function bundle: Core

Adds a specified amount of time in the given units to a Time value and returns a new Time value.

Parameters

• timeValue: Time - The input Time value to which to add time.
• addValue: Number - The value to add to the time in the given units.
• units (Optional): Text - The units of the number to add to the date. Default is milliseconds. The supported unit types include milliseconds, seconds, minutes, hours

Return value: Time

Examples

Adds 7 hours to the given Time

1
2
3
4
var startTime = Time(11,30); // equivalent to 11:30:00
var hoursLater = DateAdd(startTime, 7, 'hours');
return hoursLater;
// returns 18:30:00

Adds 90 seconds to the given Time

1
2
3
4
var startTime = Time(11,30); // equivalent to 11:30:00
var secondsLater = DateAdd(startTime, 90, "seconds");
return secondsLater;
// returns 11:31:30

Adds 25 hours to the given Time

1
2
3
4
var startTime = Time(11,30); // equivalent to 11:30:00
var hoursLater = DateAdd(startTime, 25, 'hours');
return hoursLater;
// returns 12:30:00

DateDiff

This function has 3 signatures:

• Since v1.0 - DateDiff(date1, date2, units?, timeZone?) -> Number
• Since v1.24 - DateDiff(dateOnly1, dateOnly2, units?) -> Number
• Since v1.24 - DateDiff(time1, time2, units?) -> Number

DateDiff(date1, date2, units?, timeZone?) -> Number

Since version 1.0

Function bundle: Core

Subtracts two Dates, and returns the difference in the specified units.

Parameters

• 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 (Optional): Text - 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.

• timeZone (Optional): Text - Since version 1.24 The time zone to assign to input Dates with an unknown time zone. If not specified, then the following will happen: (1) If one input has a defined time zone and the other is unknown, then the value with the unknown time zone will assume a time zone that matches the other input. (2) If both inputs are unknown time zones, then the DateDiff will be calculated on both Dates as if they were defined in the same time zone. Possible values:

  • text representing an entry in the IANA time zone database (e.g. America/New_York)

  • text representing the hours and minutes that should be added to UTC (e.g. +07:00 or -03:00)

  • system - time zone will be set to the device or system's local time zone

  • default - the time zone of the profile's execution context

  • UTC - Coordinated Universal Time

  • unknown - removes time zone information for the given value and displays the date and time as defined in the expression.

Return value: Number

Additional resources

• IANA time zone database
• Arcade execution context

Examples

Subtracts two Dates and returns the age

1
2
3
4
var startDate = Date($feature.startDateField);
var endDate = Date($feature.endDateField);
var age = DateDiff(endDate, startDate, 'years');
return age;

Subtracts two Dates and returns the difference.

1
2
3
4
5
6
7
8
var startDate = Date(2022,2,23,2,23,22,0, "America/New_York"); // Mar 23, 2022, 2:23:22 AM EDT
var endDate = Date(2022,2,23,5,23,22,0, "unknown"); // Mar 23, 2022, 5:23:22 AM

DateDiff(endDate, startDate, 'hours')
// returns 3, since the Date with an unknown time zone is assumed to be New York time before the difference is calculated

DateDiff(endDate, startDate, 'hours', "America/Los_Angeles");
// returns 6, since the Date with an unknown time zone is now considered to be Los Angeles time before the difference is calculated

DateDiff(dateOnly1, dateOnly2, units?) -> Number

Since version 1.24

Function bundle: Core

Subtracts two DateOnly values, and returns the difference in the specified units.

Parameters

• dateOnly1: DateOnly - The DateOnly value from which to subtract a second DateOnly value.
• dateOnly2: DateOnly - The DateOnly value to subtract from the first given DateOnly value.
• units (Optional): Text - The units in which to return the difference of the two given DateOnly values. The supported unit types include milliseconds, seconds, minutes, hours, days, months, years. The default value is milliseconds.

Return value: Number

Example

Subtracts two DateOnly values and returns the difference in years

1
2
3
4
5
var startDate = DateOnly(1996,11,10);
var endDate = DateOnly(); // today's date
var age = DateDiff(endDate, startDate, 'years');
Floor(age); // round down
// returns 26

DateDiff(time1, time2, units?) -> Number

Since version 1.24

Function bundle: Core

Subtracts two Time values, and returns the difference in the specified units.

Parameters

• time1: Time - The Time value from which to subtract a second Time value.
• time2: Time - The Time value to subtract from the first given Time value.
• units (Optional): Text - The units in which to return the difference of the two given Time values. The supported unit types include milliseconds, seconds, minutes, hours. The default value is milliseconds.

Return value: Number

Example

Subtracts two Time values and returns the difference in hours

1
2
DateDiff(Time(23,0), Time(9,0), 'hours')
// returns 14

DateOnly

This function has 6 signatures:

• Since v1.24 - DateOnly() -> DateOnly
• Since v1.24 - DateOnly(year, month, day) -> DateOnly
• Since v1.24 - DateOnly(epoch) -> DateOnly
• Since v1.24 - DateOnly(textValue, format?) -> DateOnly
• Since v1.24 - DateOnly(dateValue) -> DateOnly
• Since v1.24 - DateOnly(dateOnlyValue) -> DateOnly

DateOnly() -> DateOnly

Since version 1.24

Function bundle: Core

Creates a DateOnly value based on the current date in the time zone of the profile's execution context.

Return value: DateOnly

Additional resources

• Arcade execution context

Example

Returns the current DateOnly (no time)

1
2
DateOnly()
// returns the current date, i.e. 2023-09-12

DateOnly(year, month, day) -> DateOnly

Since version 1.24

Function bundle: Core

Creates a DateOnly value from inputs representing the year, month, and day.

Parameters

• year: Number - A number representing a year.
• month: Number - The month (0-11) where 0 is January and 11 is December. If this value falls outside the normal range (0-11), the function will return null.
• day: Number - The day of the month (1-31). If this value falls outside the normal range (1-31), the function will return null.

Return value: DateOnly

Example

Creates a DateOnly value from inputs representing the year, month, and day

1
2
DateOnly(1996, 11, 10)
// returns 1996-12-10

DateOnly(epoch) -> DateOnly

Since version 1.24

Function bundle: Core

Creates a DateOnly date with the given Unix epoch number.

Parameter

• epoch: Number - The number of milliseconds since January 1, 1970 UTC.

Return value: DateOnly

Example

Returns the DateOnly from the number of milliseconds since January 1, 1970

1
2
DateOnly(1476987783555);
// returns 2016-10-20

DateOnly(textValue, format?) -> DateOnly

Since version 1.24

Function bundle: Core

Creates a DateOnly value from a text input representing an ISO formatted date, or another formatted text pattern.

Parameters

• textValue: Text - A text value representing a date. This should either be an ISO formatted date or another formatted text representing a date. If this value does not follow ISO format, the format parameter must be defined indicating the date's format.
• format (Optional): Text - A text value indicating the format of the dateValue input.
  Possible values:
  • D: Day of the month, not padded (1 - 31)
  • DD: Day of the month, padded (01 - 31)
  • DDD: Ordinal day of the year (1 - 365)
  • d: Day of the week (1 - 7)
  • ddd: Abbreviated day of the week (e.g. Mon)
  • dddd: Full day of the week (e.g. Monday)
  • M: Month number (1 - 12)
  • MM: Month number, padded (01 - 12)
  • MMM: Abbreviated month name (e.g. Jan)
  • MMMM: Full month name (e.g. January)
  • Y: Full year
  • YY: Two-digit year

Return value: DateOnly

Examples

Creates a DateOnly value from a text value representing the date

1
2
DateOnly("2023-05-11T13:43:18.990+01:00");
// returns 2023-05-11

Creates a DateOnly value from a text value representing the date in the given format

1
2
DateOnly("10 Jan 2022","D MMM Y")
// returns 2022-01-10

DateOnly(dateValue) -> DateOnly

Since version 1.24

Function bundle: Core

Creates a DateOnly value from a given date.

Parameter

• dateValue: Date - The date from which to create the DateOnly value.

Return value: DateOnly

Example

Returns the DateOnly from the given date

1
2
DateOnly(Date(2008,10,11,10,30));
// returns 2008-11-11

DateOnly(dateOnlyValue) -> DateOnly

Since version 1.24

Function bundle: Core

Creates a copy of a DateOnly value.

Parameter

• dateOnlyValue: DateOnly - The DateOnly value to copy.

Return value: DateOnly

Example

Creates a copy of DateOnly value

1
2
3
var originalDateOnly = DateOnly(1996,11,10)
var copiedDateOnly = DateOnly(originalDateOnly)
return copiedDateOnly;

Day

Day(dateValue) -> Number

Since version 1.0

Function bundle: Core

Returns the day of the month of the given date.

Parameter

• dateValue: Date | DateOnly - A Date value from which to get the day of the month. DateOnly values are supported starting at version 1.24.

Return value: Number

Examples

Gets the day of the month of the current date

1
Day(Now())

Returns the day of the month from a DateOnly value

1
2
Day(DateOnly(1996, 11, 10))
// returns 10

Hour

Hour(dateTimeValue) -> Number

Since version 1.0

Function bundle: Core

Returns the hour of the time in the given Date or Time value (0-23).

Parameter

• dateTimeValue: Date | Time - A Date or Time value from which to get the hour of the time. Time values are supported starting at version 1.24.

Return value: Number

Examples

Returns the hour of the current time

1
Hour(Now())

Returns the hour of the time

1
2
Hour(Date(2023, 1, 1, 12, 59, 23))
// returns 12

Returns the hour of the time

1
2
Hour(Time(2, 59, 23))
// returns 2

ISOMonth

ISOMonth(dateValue) -> Number

Since version 1.12

Function bundle: Core

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.

Parameter

• dateValue: Date | DateOnly - A Date value from which to get the month. DateOnly values are supported starting at version 1.24.

Return value: Number

Examples

Gets the month of the given date, based on the ISO 8601 standard. Returns 12, for the month of December.

1
ISOMonth(Date(1980, 11, 31))

Gets the month of the given DateOnly value, based on the ISO 8601 standard.

1
2
ISOMonth(DateOnly(1996, 0, 10))
// returns 1, for January

ISOWeek

ISOWeek(dateValue) -> Number

Since version 1.12

Function bundle: Core

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.

Parameter

• dateValue: Date | DateOnly - A Date value from which to get the week. DateOnly values are supported starting at version 1.24.

Return value: Number

Examples

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.

1
ISOWeek(Date(1980, 11, 31))

Gets the week of the given DateOnly value, based on the ISO 8601 standard.

1
2
ISOWeek(DateOnly(1996, 11, 10))
// returns 50

ISOWeekday

ISOWeekday(dateValue) -> Number

Since version 1.12

Function bundle: Core

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.

Parameter

• dateValue: Date | DateOnly - A Date value from which to return the day of the week. DateOnly values are supported starting at version 1.24.

Return value: Number

Examples

Returns the day of the week of the given date, based on the ISO 8601 standard. Returns 3, for Wednesday.

1
ISOWeekday(Date(1980, 11, 31))

Returns the day of the week of the given DateOnly value, based on the ISO 8601 standard.

1
2
ISOWeekday(DateOnly(1996, 11, 10))
// returns 2, for Tuesday

ISOYear

ISOYear(dateValue) -> Number

Since version 1.12

Function bundle: Core

Returns the year of the given date based on the ISO 8601 week date calendar.

Parameter

• dateValue: Date | DateOnly - A Date value from which to get the year. DateOnly values are supported starting at version 1.24.

Return value: Number

Examples

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.

1
ISOYear(Date(1980, 11, 31))

Gets the year of the given DateOnly value, based on the ISO 8601 week date calendar.

1
2
ISOYear(DateOnly(1996, 11, 10))
// returns 1996

Millisecond

Millisecond(dateTimeValue) -> Number

Since version 1.0

Function bundle: Core

Returns the millisecond of the time in the given Time or Date value.

Parameter

• dateTimeValue: Date | Time - A Date or Time value from which to get the millisecond of the time. Time values are supported starting at version 1.24.

Return value: Number

Examples

Returns the millisecond of the current time

1
Millisecond(Now())

Returns the millisecond of the time

1
2
Millisecond(Date(2023, 1, 1, 12, 59, 23, 999))
// returns 999

Returns the millisecond of the time

1
2
Millisecond(Time(2, 59, 23, 450))
// returns 450

Minute

Minute(dateTimeValue) -> Number

Since version 1.0

Function bundle: Core

Returns the minute of the time in the given Time or Date value.

Parameter

• dateTimeValue: Date | Time - A Date or Time value from which to get the minute of the time. Time values are supported starting at version 1.24.

Return value: Number

Examples

Returns the minute of the current time

1
Minute(Now())

Returns the minute of the time

1
2
Minute(Date(2013, 1, 1, 2, 15, 23))
// returns 15

Returns the minute of the time

1
2
Minute(Time(2, 59, 23))
// returns 59

Month

Month(dateValue) -> Number

Since version 1.0

Function bundle: Core

Returns the month of the given date. Values range from 0-11 where January is 0 and December is 11.

Parameter

• dateValue: Date | DateOnly - A Date value from which to get the month. DateOnly values are supported starting at version 1.24.

Return value: Number

Additional resources

• ISOMonth()

Examples

Gets the month of the given Date. Value can be between 0-11, where 0 represents January and 11 represents December.

1
2
Month(Date(1980, 11, 31))
// returns 11

Gets the month of the given DateOnly value.

1
2
Month(DateOnly(1996, 0, 31))
// returns 0, for the month of January

Now

Now() -> Date

Since version 1.0

Function bundle: Core

Creates a Date value representing the current date and time in the time zone of the profile's execution context.

Return value: Date

Additional resources

• Arcade execution context
• Date()
• Timestamp()
• Today()

Example

Returns the current date and time in the profile's default time zone

1
2
// Date represents Jan 27, 2023, 12:41:20 PM PST
Now()

Second

Second(dateTimeValue) -> Number

Since version 1.0

Function bundle: Core

Returns the second of the time in the given Date or Time value.

Parameter

• dateTimeValue: Date | Time - A Date or Time value from which to get the second of the time. Time values are supported starting at version 1.24.

Return value: Number

Examples

Gets the second of the current time

1
Second(Now())

Gets the second of the time

1
2
Second(Date(2023, 1, 1, 2, 59, 01))
// returns 1

Gets the second of the time

1
2
Second(Time(2, 59, 23))
// returns 23

Time

This function has 6 signatures:

• Since v1.24 - Time() -> Time
• Since v1.24 - Time(hours, minutes, seconds?, milliseconds?) -> Time
• Since v1.24 - Time(numValue) -> Time
• Since v1.24 - Time(textValue, format?) -> Time
• Since v1.24 - Time(dateValue) -> Time
• Since v1.24 - Time(timeValue) -> Time

Time() -> Time

Since version 1.24

Function bundle: Core

Creates a Time value representing the current time in the time zone of the profile's execution context.

Return value: Time

Additional resources

• Arcade execution context

Example

Returns the current time displayed using the profile's default time zone

1
2
// Time represents 12:41:20 PM
Time()

Time(hours, minutes, seconds?, milliseconds?) -> Time

Since version 1.24

Function bundle: Core

Creates a Time value from inputs representing hours, minutes, seconds, and milliseconds.

Parameters

• hours: Number - A number representing hours of the Time value (0-23). If this value falls outside the normal range (0-23), the function will return null.
• minutes: Number - A number representing the minutes of the Time value (0-59). If this value falls outside the normal range (0-59), the function will return null.
• seconds (Optional): Number - A number representing the seconds of the Time value (0-59). If this value falls outside the normal range (0-59), the function will return null.
• milliseconds (Optional): Number - A number representing the milliseconds of the Time value (0-999). If this value falls outside the normal range (0-999), the function will return null.

Return value: Time

Example

Creates a Time value from inputs representing hours, minutes, seconds, and milliseconds

1
2
3
4
5
6
7
8
Time(13, 20);
// returns a Time value of 13:20:00

Time(2, 59, 23)
// returns a Time value of 02:59:23

Time(15, 47, 0, 474)
// returns a Time value of 15:47:00.474

Time(numValue) -> Time

Since version 1.24

Function bundle: Core

Creates a Time value from a given number representing milliseconds since midnight.

Parameter

• numValue: Number - The number of milliseconds since midnight. If this value is larger than 86,400,000 (the maximum number of milliseconds in a day) or less than 0, the function will return null.

Return value: Time

Examples

Returns the Time from the number of milliseconds since midnight

1
2
Time(8119800);
// returns a Time value of 02:15:19.800

Returns the Time from the number of milliseconds since midnight

1
2
Time(86400001);
// returns null - the input value exceeds the number of milliseconds in a day

Time(textValue, format?) -> Time

Since version 1.24

Function bundle: Core

Creates a Time value from a text input representing time, with an optional input indicating the text's format.

Parameters

• textValue: Text - A text value representing a time.
• format (Optional): Text - A text value indicating the format of the timeValue input.
  Possible values:
  • h: Civilian hours, not padded (1 - 12)
  • hh: Civilian hours, padded (01 - 12)
  • H: Military hours, not padded (0 - 23)
  • HH: Military hours, padded (00 - 23)
  • m: Minutes, not padded (0 - 59)
  • mm: Minutes, padded (00 - 59)
  • s: Seconds, not padded (0 - 59)
  • ss: Seconds, padded (00 - 59)
  • A: AM/PM

Return value: Time

Examples

Creates a Time value from a text value representing the time

1
2
Time("1:20 PM");
// returns a Time value of 13:20:00

Creates a Time value from a text value representing the time and formatting

1
2
Time("12 05 04", "HH MM ss")
// returns a Time value of 12:05:04

Time(dateValue) -> Time

Since version 1.24

Function bundle: Core

Creates a Time value from a given date.

Parameter

• dateValue: Date - The date from which to get the time.

Return value: Time

Example

Returns the Time from the given date

1
2
Time(Date(2008,10,11,10,30));
// returns a Time value of 10:30:00 AM

Time(timeValue) -> Time

Since version 1.24

Function bundle: Core

Creates a copy of a Time value.

Parameter

• timeValue: Time - The Time value to copy.

Return value: Time

Example

Creates a copy of Time value

1
2
3
var originalTime = Time(23,32,00)
var copiedTime = Time(originalTime)
return copiedTime;

Timestamp

Timestamp() -> Date

Since version 1.1

Function bundle: Core

Creates a Date value representing the current date and time in UTC.

Return value: Date

Additional resources

• Date()
• Now()
• Today()

Example

Creates a Date in UTC time

1
2
// Date that represents Jan 27, 2023, 8:41:20 PM UTC
Timestamp()

TimeZone

TimeZone(dateValue) -> Text

Since version 1.24

Function bundle: Core

Returns the time zone of the given Date. The time zone will be one of the following:

• text representing an entry in the IANA time zone database (i.e. America/New_York)

• text representing the hours and minutes that should be added to UTC (i.e. +07:00 or -03:00)

• system - time zone will be based on the client or system's local time zone

• UTC - Coordinated Universal Time

• Unknown - time zone information is not defined.

Parameter

• dateValue: Date - A Date value from which to get the time zone.

Return value: Text

Additional resources

• IANA time zone database

Example

Returns the time zone of a Date

1
2
3
var natlPizzaDay = Date(2024, 1, 9, 0, 0, 0, 0, "America/Los_Angeles");
TimeZone(natlPizzaDay);
// Returns 'America/Los_Angeles'

TimeZoneOffset

TimeZoneOffset(dateValue) -> Number

Since version 1.24

Function bundle: Core

Returns the time zone offset in milliseconds from UTC for the given Date.

Parameter

• dateValue: Date - A Date value from which to get the time zone offset.

Return value: Number

Example

Returns the time zone offset in milliseconds from UTC

1
2
3
var inputDate = Date(2011, 10, 11, 8, 0, 0, 0, "America/New_York")
TimeZoneOffset(inputDate);
// returns -18000000

Today

Today() -> Date

Since version 1.0

Function bundle: Core

Returns the current Date at midnight in the time zone of the profile's execution context.

Return value: Date

Additional resources

• Arcade execution context
• DateOnly()
• Date()
• Timestamp()
• Now()

Example

Returns the current Date at midnight, e.g. Mon Oct 24 2016 00:00:00 GMT-0700 (PDT)

1
Today()

ToLocal

ToLocal(inputDate) -> Date

Since version 1.1

Function bundle: Core

Creates a new Date value matching the epoch of the input date and sets the time zone to the local or system time zone of the client.

Parameter

• inputDate: Date - A Date value to represent in the local time of the client.

Return value: Date

Additional resources

• ChangeTimeZone()

Example

Creates a date in local time at the same epoch as the input date

1
2
3
4
// Date represents Jan 27, 2023, 8:41:20 PM UTC
Timestamp()
// Date represents Jan 27, 2023, 12:41:20 PM PST
ToLocal(Timestamp())

ToUTC

ToUTC(inputDate) -> Date

Since version 1.1

Function bundle: Core

Creates a new Date value matching the epoch of the input date and sets the time zone to UTC (Coordinated Universal Time).

Parameter

• inputDate: Date - A Date value to represent in UTC time.

Return value: Date

Additional resources

• ChangeTimeZone()

Example

Creates a Date in UTC time at the same epoch as the input date.

1
2
3
4
// Date represents Jan 27, 2023, 12:41:20 PM PST
Now()
// Date represents Jan 27, 2023, 8:41:20 PM UTC
ToUTC(Now())

Week

Week(dateValue, startDay?) -> Number

Since version 1.14

Function bundle: Core

Returns the week number in the year of the given Date. Values range from 0-53 where the first week of the year is 0 and the last week of the year is 51, 52, or 53, depending on the year. The first and last weeks may not be a full seven days in length.

Parameters

• dateValue: Date | DateOnly - A Date or DateOnly value from which to get the week. DateOnly values are supported starting at version 1.24.
• startDay (Optional): Number - A number representing the start day of the week. Sunday = 0; Monday = 1; Tuesday = 2; Wednesday = 3; Thursday = 4; Friday = 5; Saturday = 6. The default is 0 (Sunday).

Return value: Number

Examples

Use the default start of the week (Sunday)

1
2
Week( Date(1974,0,3) )
// Returns 0

Set start of week to Thursday

1
2
Week( Date(1974,0,3), 4 )
// Returns 1

Set start of week to Friday

1
2
Week( Date(1974,0,3), 5 )
// Returns 0

1
2
Week( Date(1945,8,23) )
// Returns 38

1
2
Week( Date(2022,7,20) )
// Returns 33

Returns the week from the DateOnly value

1
2
Week(DateOnly(1996, 11, 10))
// returns 49

Weekday

Weekday(dateValue) -> Number

Since version 1.0

Function bundle: Core

Returns the day of the week of the given Date. Values range from 0-6 where Sunday is 0 and Saturday is 6.

Parameter

• dateValue: Date | DateOnly - A Date or DateOnly value from which to return the day of the week. DateOnly values are supported starting at version 1.24.

Return value: Number

Examples

Returns the day of the week of the given date. Returns 3, for Wednesday.

1
Weekday(Date(1980, 11, 31))

Returns the day of the week of the given DateOnly value.

1
2
Weekday(DateOnly(1996, 11, 10))
// returns 2, for Tuesday

Year

Year(dateValue) -> Number

Since version 1.0

Function bundle: Core

Returns the year of the given Date.

Parameter

• dateValue: Date | DateOnly - A Date or DateOnly value from which to get the year. DateOnly values are supported starting at version 1.24.

Return value: Number

Examples

Gets the year of the current Date

1
Year(Now())

Gets the year of the given DateOnly value

1
2
Year(DateOnly(1996, 11, 10))
// returns 1996