Type casting

Arcade allows you to cast a value of one data type to another type. You can do this explicitly using any of the casting functions, or allow Arcade to handle casting implicitly. The following are the implicit and explicit type casting rules in Arcade.

Explicit casting

Explicit casting refers to the practice of using a function to convert a value of one data type to another. The expression author is intentionally making a decision to cast the type. These are the casting functions:

Explicit Boolean casting

Boolean(value)

The Boolean function converts a number or text value to a boolean. Any number, except zero, will return true. Only the text "true" will return true. All other scenarios return false.

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
Boolean('true')
// returns true

Boolean(0)
// returns false

Boolean(1)
// returns true

Boolean('hello')
// returns false

Explicit Date casting

Date(value, format?)

The Date function converts a number or text value to a date.

Input TypeOutput TypeResult
DateOnlyDateCreates a new date value with year, month, and day values matching the input DateOnly value. The output value will include time information set to 00:00:00 AM.
NumberDateCreates a new date based on the number of milliseconds since Jan. 1, 1970.
TextDateCreates a new date if text is ISO 8601. Otherwise, the date value will depend on format text. Returns null if no there's no match.
TimeDatenull
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
// Milliseconds since Jan. 1, 1970
Date(1476987783555)
// returns a date representing Oct 10, 2016 14:23:03.555 PDT

// ISO 8601 text
Date('2016-10-20T17:41:37+00:00')
// returns a date representing Oct 10, 2016 13:41:37 PDT

// Converts a DateOnly value to a Date value
Date(DateOnly(2022, 1, 2));
// returns a date representing Feb 2, 2022 00:00:00 PDT

Explicit DateOnly casting

DateOnly(value, format?)

The DateOnly function converts a number, date, or text value to a DateOnly type.

Input TypeOutput TypeResult
BooleanDateOnly"1970-01-01"
DateDateOnlyCreates a new DateOnly value based on an input date value. The output will exclude time and time zone information.
NumberDateOnlyCreates a new DateOnly value based on the number of milliseconds since Jan. 1, 1970.
TextDateOnlyCreates a new DateOnly value if text is ISO 8601. Otherwise, the date value will depend on format text. Returns null if no there's no match.
TimeDateOnlynull
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
DateOnly(true)
// '1970-01-01'

DateOnly(Date(2016, 10, 20, 17, 41, 37, 0, "UTC"))
// '2016-11-20'

// Milliseconds since Jan. 1, 1970
DateOnly(1476987783555)
// '2016-10-20'

// ISO 8601 text
DateOnly('2016-10-20T17:41:37+00:00')
// '2016-10-20'

DateOnly(Time(17, 41, 37))
// null

Explicit Number casting

Number(value, format?)

The Number function converts a date or a text value to a number.

Input TypeOutput TypeResult
BooleanNumberValue of true casts to 1; false casts to 0.
DateNumberNumber of milliseconds since Jan. 1, 1970 (i.e. the Unix epoch).
DateOnlyNumberNumber of milliseconds since Jan. 1, 1970 (i.e. the Unix epoch) excluding the time information.
TextNumberBehaves as an implicit cast if no format is provided. If format is specified but not matched, then returns NaN.
TimeNumberNumber of milliseconds since the start of the day.
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
// Number of milliseconds since Jan. 1, 1970.
Number(now())  // 1661206550823

Number(DateOnly(2022, 1, 1));  // returns 1643673600000

Number(Time(12,30,59));  // returns 45059000

// Parses a number using a grouping separator based on the locale
Number('1,365', ',###') // returns 1365

// Removes text from number
Number('abc10def', 'abc##def') // returns 10

// Specifies minimum digits past 0 as two and maximum digits past 0 as 4
Number('10.456','00.00##') // returns 10.456

// Specifies minimum digits past 0 as two and maximum digits past 0 as 4.
// The left and right side of the function must match or NaN is returned.
Number('10.4','00.00##') // returns NaN

// Indicates the size of the repeated group and the final group size of the input value
Number('12,12,456', ',##,###') // returns 1212456

// If there is a negative sub-pattern, it serves only to specify the negative prefix and suffix.
Number('-12,23,345', ',##,###;-,##,###') // returns -1223345

// Divide by 100. Maximum of three decimal places can be input.
Number('99.99%', '#.##%') // 0.9999

Explicit Text casting

Text(value, format?)

The Text function converts any value to text.

Input TypeOutput TypeResult
ArrayTextSee Concatenate function.
BooleanTextValue of true casts to "true"; false casts to "false".
DateTextISO 8601 date format, or formatted according to format text.
DateOnlyTextStandard DateOnly format (e.g. "YYYY-MM-DD"), or formatted according to format text.
DictionaryTextJSON representation of the dictionary.
FeatureTextJSON representation of the feature.
GeometryTextJSON representation of the geometry.
NumberTextNumber formatted according to format text.
TimeTextStandard Time format (e.g. "hh:mm:ss"), or formatted according to format text.
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
// Pad the number to the left of the decimal
Text(123, '0000') // returns '0123'

// Restrict the number to the left of the decimal
Text(123, '00') // returns '23'

// Group the number by thousands
Text(1234, '#,###') // returns '1,234'

// Round the number to two decimal places
Text(12345678.123, '#,###.00') // returns '12,345,678.12'

// Format number as currency
Text(1234.55, '$#,###.00') // returns '$1,234.55'

// Round the number to two decimal places
Text(1.236, '#.00') // returns '1.24'

// Maintain significant digits and group by thousands
Text(1234.5678, '#,##0.00#') // returns '1,234.568'

// Format the number and format positive/negative
// if there is a negative sub-pattern, it serves only to specify the negative prefix and suffix
Text(-2, 'Floor #;Basement #') // returns 'Basement 2'
Text(2, 'Floor #;Basement #') // returns 'Floor 2'

// Multiply by 100 and format as percentage
Text(0.3, '#%') // returns '30%'

// Format date and time at the moment
Text(Now(), 'dddd, MMMM D, Y @ h:mm:ss')  // returns 'Tuesday, October 25, 2016 @ 08:43:11'

// Format DateOnly
Text(DateOnly(2016, 9, 25), 'dddd, MMMM D, Y')  // returns 'Tuesday, October 25, 2016'

// Format time
Text(Time(14,43,11), 'h:mm:ss A')  // returns '2:43:11 AM'

Explicit Time casting

Time(value, format?)

The Time function converts a Number, Date, DateOnly, or Text value to a Time type.

Input TypeOutput TypeResult
BooleanTimeValue of true casts to "00:00:00.001". Value of false casts to "00:00:00".
DateTimeCreates a new Time value matching the time information for the input Date value. The output will exclude time zone information.
DateOnlyTime"00:00:00"
NumberTimeCreates a new Time value based on the number of milliseconds since the start of a day. If the number exceeds 86400000, then the value will be null.
TextTimeCreates a new Time value based on various formats until one matches, unless a preferred text format pattern is provided. Returns null if no there's no match.
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
Time(true)
// '00:00:00.001'

Time(Date(2016, 10, 20, 17, 41, 37, 00, 'UTC'))
// '17:41:37'

Time(DateOnly(2020, 2, 22))
// '00:00:00'

// Milliseconds since start of the day
Time(60000)
// '00:01:00'

// One more millisecond than fits in one day
Time(86400001)
// null

Time('12:34')
// '12:34:00'

Implicit casting

Implicit casting occurs when the Arcade language automatically casts data values from one type to another on behalf of the script author. This can happen in logical statements, function parameters, and values returned from expressions.

The following are the rules for implicit type casting in Arcade.

Implicit Boolean casting

Input TypeOutput TypeResult
ArrayBooleanfalse
DateBooleanfalse
DateOnlyBooleanfalse
DictionaryBooleanfalse
FeatureBooleanfalse
GeometryBooleanfalse
NumberBooleantrue, unless the number is 0, which casts to false.
NaNBooleanfalse
NullBooleanfalse
TextBooleanIf lower case text value of 'true' then casts to true. All other text casts to false.
TimeBooleanfalse

Implicit Date casting

Input TypeOutput TypeResult
ArrayDatenull
BooleanDatenull
DateOnlyDateDate with matching date values and time set to 00:00:00 AM
DictionaryDatenull
FeatureDatenull
GeometryDatenull
NaNDatenull
NullDatenull
NumberDatenull
TextDateDate if Text is ISO 8601. Otherwise null
TimeDatenull

Implicit Text casting

Input TypeOutput TypeResult
ArrayTextJSON representation of the array as text. Use See Concatenate function.
BooleanText'true' or 'false'.
DateTextISO 8601 date format.
DateOnlyTextStandard DateOnly format (e.g. "YYYY-MM-DD").
DictionaryTextJSON representation of the dictionary as text.
FeatureTextJSON representation of the feature as text.
GeometryTextJSON representation of the geometry as text.
NaNText'NaN'
NullTextEmpty text (e.g. '').
NumberTextDecimal representation of the number.
TimeTextStandard Time format (e.g. "hh:mm:ss").

Implicit Number casting

Input TypeOutput TypeResult
ArrayNumberNaN
BooleanNumber0 or 1
DateNumberNaN
DateOnlyNumberNaN
DictionaryNumberNaN
FeatureNumberNaN
GeometryNumberNaN
NaNNumberNaN
NullNumber0
TextNumberIf decimal text, then cast to decimal number. Empty text or spaces are cast to 0. Other values are cast to NaN.
TimeNumberNaN

Logical statements

See Logical operators to learn how to use logical operators.

OperatorBehavior
&&Left and right operands must be boolean. There is no implicit type casting.
||Left and right operands must be boolean. There is no implicit type casting.
!Argument must be boolean. There is no implicit type casting.

Comparison statements

See Comparison operators to learn how to use logical operators.

OperatorBehavior
!=There is no implicit type casting for this operator. The values must not be equal. Text, date/time, numbers, and boolean types are treated as value types. Features, dictionaries, and geometries are treated as objects.
==There is no implicit type casting for this operator. The values must be equal. Text, date/time, numbers, and boolean types are treated as value types. Features, dictionaries, and geometries are treated as objects.
<, >, <=, >=Object types (i.e. Arrays, Features, Dictionaries, Geometry) will always return false, unless checking equality (e.g. ==). In this case, true will be returned if they are the same object. If both operands are different types, then they will implicitly be cast to numbers.

Arithmetic statements

See Arithmetic operators to learn how to use arithmetic operators.

OperatorBehavior
/, %, *, -Left and right operands are implicitly cast to numbers.
+If either left or right operand is a text value, then both operands are implicitly cast to text. Otherwise, left and right operands are implicitly cast to numbers.
++, --The operand must be a number. No implicit casting occurs. If it is not a number, the result will be NaN.

Assignment statements

See Assignment operators to learn how to use assignment operators.

OperatorBehavior
/=, %=, *=, -=Left and right operands are implicitly cast to numbers.
+=If either left or right operand is text, then both operands are implicitly cast to text. Otherwise left and right operands are implicitly cast to numbers.

Unary statements

See Unary operators to learn how to use unary operators.

OperatorBehavior
+, -The argument is implicitly cast to a number.

Type casting in code structures

  • When calling functions, the parameters will be cast using implicit type casting rules. If the function is overloaded, the overload will be determined before implicit casting.
  • For loop conditions must be boolean. There is no implicit type casting.
  • If conditions must be boolean. There is no implicit type casting.

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.