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 data functions, or allow Arcade to handle casting implicitly. The following are the implicit and explicit type conversion 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 casing functions:

Explicit number conversion

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).
TextNumberBehaves as an implicit cast if no format is provided. If format is specified but not matched, then returns NaN.
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
// Number of milliseconds since Jan. 1, 1970.
Number(now())  // returns 1661206550823

// 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 boolean conversion

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 conversion

Date(value, format?)

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

Input TypeOutput TypeResult
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.
Use dark colors for code blocksCopy
       
1
2
3
4
5
6
7
// Milliseconds since Jan. 1, 1970
Date(1476987783555)
// 'Thu Oct 20 2016 11:23:03 GMT-0700 (PDT)'

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

Explicit text conversion

Text(value, format?)

The Text function converts any value to text.

Input TypeOutput TypeResult
NumberTextNumber formatted according to format text.
DateTextISO 8601 date format, or formatted according to format text.
FeatureTextJSON representation of the feature.
DictionaryTextJSON representation of the dictionary.
GeometryTextJSON representation of the geometry.
ArrayTextSee Concatenate function.
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
// 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:m:s')  // returns 'Tuesday, October 25, 2016 @ 08:43:11'

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 text conversion

Input TypeOutput TypeResult
NumberTextDecimal representation of the number.
DateTextISO 8601 date format.
NullTextEmpty text (e.g. '').
BooleanText'true' or 'false'.
ArrayTextJSON representation of the array as text. Use See Concatenate function.
FeatureTextJSON representation of the feature as text.
DictionaryTextJSON representation of the dictionary as text.
GeometryTextJSON representation of the geometry as text.

Implicit number conversion

Input TypeOutput TypeResult
DateNumberNumber of milliseconds since Jan. 1, 1970 (i.e. the Unix epoch).
BooleanNumber0 or 1
NullNumber0
TextNumberIf decimal text, then converted to decimal number. Empty text or spaces are cast to 0. Other values are converted to NaN.
ArrayNumberNaN
FeatureNumberNaN
DictionaryNumberNaN
GeometryNumberNaN

Implicit boolean conversion

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

Implicit date conversion

Input TypeOutput TypeResult
NumberDatenull
TextDateDate if Text is ISO 8601. Otherwise null
NullDatenull
NaNDatenull
BooleanDatenull
ArrayDatenull
FeatureDatenull
DictionaryDatenull
GeometryDatenull

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 conversion.
\|\|Left and right operands must be boolean. There is no implicit type conversion.
!Argument must be boolean. There is no implicit type conversion.

Comparison statements

See Comparison operators to learn how to use logical operators.

OperatorBehavior
!=There is no implicit type conversion for this operator. The values must not be equal. Text, dates, numbers, and booleans are treated as value types. Features, dictionaries, and geometries are treated as objects.
==There is no implicit type conversion for this operator. The values must be equal. Text, dates, numbers, and booleans 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 converted to numbers.

Arithmetic statements

See Arithmetic operators to learn how to use arithmetic operators.

OperatorBehavior
/, %, *, -Left and right operands are implicitly converted to numbers.
+If either left or right operand is a text value, then both operands are implicitly converted to text. Otherwise, left and right operands are implicitly converted 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 converted to numbers.
+=If either left or right operand is text, then both operands are implicitly converted to text. Otherwise left and right operands are implicitly converted to numbers.

Unary statements

See Unary operators to learn how to use unary operators.

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

Type conversion in code structures

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

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