Values and Types
Values are objects, like for example booleans, integers, or arrays. Values are typed.
Booleans
The two boolean values true
and false
have the type Bool
.
Numeric Literals
Numbers can be written in various bases. Numbers are assumed to be decimal by default. Non-decimal literals have a specific prefix.
Numeral system | Prefix | Characters |
---|---|---|
Decimal | None | one or more numbers (0 to 9 ) |
Binary | 0b | one or more zeros or ones (0 or 1 ) |
Octal | 0o | one or more numbers in the range 0 to 7 |
Hexadecimal | 0x | one or more numbers, or characters a to f , lowercase or uppercase |
Decimal numbers may contain underscores (_
) to logically separate components.
Underscores are allowed for all numeral systems.
Integers
Integers are numbers without a fractional part. They are either signed (positive, zero, or negative) or unsigned (positive or zero).
Signed integer types which check for overflow and underflow have an Int
prefix
and can represent values in the following ranges:
Int8
: -2^7 through 2^7 − 1 (-128 through 127)Int16
: -2^15 through 2^15 − 1 (-32768 through 32767)Int32
: -2^31 through 2^31 − 1 (-2147483648 through 2147483647)Int64
: -2^63 through 2^63 − 1 (-9223372036854775808 through 9223372036854775807)Int128
: -2^127 through 2^127 − 1Int256
: -2^255 through 2^255 − 1
Unsigned integer types which check for overflow and underflow have a UInt
prefix
and can represent values in the following ranges:
UInt8
: 0 through 2^8 − 1 (255)UInt16
: 0 through 2^16 − 1 (65535)UInt32
: 0 through 2^32 − 1 (4294967295)UInt64
: 0 through 2^64 − 1 (18446744073709551615)UInt128
: 0 through 2^128 − 1UInt256
: 0 through 2^256 − 1
Unsigned integer types which do not check for overflow and underflow,
i.e. wrap around, have the Word
prefix
and can represent values in the following ranges:
Word8
: 0 through 2^8 − 1 (255)Word16
: 0 through 2^16 − 1 (65535)Word32
: 0 through 2^32 − 1 (4294967295)Word64
: 0 through 2^64 − 1 (18446744073709551615)
The types are independent types, i.e. not subtypes of each other.
See the section about arithmetic operators for further information about the behavior of the different integer types.
In addition, the arbitrary precision integer type Int
is provided.
Integer literals are inferred to have type Int
,
or if the literal occurs in a position that expects an explicit type,
e.g. in a variable declaration with an explicit type annotation.
Negative integers are encoded in two's complement representation.
Integer types are not converted automatically. Types must be explicitly converted, which can be done by calling the constructor of the type with the integer type.
Integer Functions
Integers have multiple built-in functions you can use.
-
Returns the string representation of the integer.
-
Returns the byte array representation (
[UInt8]
) in big-endian order of the integer.
All integer types support the following functions:
-
Attempts to parse an integer value from a base-10 encoded string, returning
nil
if the string is invalid.For a given integer
n
of typeT
,T.fromString(n.toString())
is equivalent to wrappingn
up in an optional.Strings are invalid if:
- they contain non-digit characters
- they don't fit in the target type
For signed integer types like
Int64
, andInt
, the string may optionally begin with+
or-
sign prefix.For unsigned integer types like
Word64
,UInt64
, andUInt
, sign prefices are not allowed.Examples:
-
Attempts to parse an integer value from a byte array representation (
[UInt8]
) in big-endian order, returningnil
if the input bytes are invalid.For a given integer
n
of typeT
,T.fromBigEndianBytes(n.toBigEndianBytes())
is equivalent to wrappingn
up in an optional.The bytes are invalid if:
- length of the bytes array exceeds the number of bytes needed for the target type
- they don't fit in the target type
Examples:
Fixed-Point Numbers
🚧 Status: Currently only the 64-bit wide Fix64
and UFix64
types are available.
More fixed-point number types will be added in a future release.
Fixed-point numbers are useful for representing fractional values. They have a fixed number of digits after decimal point.
They are essentially integers which are scaled by a factor. For example, the value 1.23 can be represented as 1230 with a scaling factor of 1/1000. The scaling factor is the same for all values of the same type and stays the same during calculations.
Fixed-point numbers in Cadence have a scaling factor with a power of 10, instead of a power of 2, i.e. they are decimal, not binary.
Signed fixed-point number types have the prefix Fix
,
have the following factors, and can represent values in the following ranges:
Fix64
: Factor 1/100,000,000; -92233720368.54775808 through 92233720368.54775807
Unsigned fixed-point number types have the prefix UFix
,
have the following factors, and can represent values in the following ranges:
UFix64
: Factor 1/100,000,000; 0.0 through 184467440737.09551615
Fixed-Point Number Functions
Fixed-Point numbers have multiple built-in functions you can use.
-
Returns the string representation of the fixed-point number.
-
Returns the byte array representation (
[UInt8]
) in big-endian order of the fixed-point number.
All fixed-point types support the following functions:
-
Attempts to parse a fixed-point value from a base-10 encoded string, returning
nil
if the string is invalid.For a given fixed-point numeral
n
of typeT
,T.fromString(n.toString())
is equivalent to wrappingn
up in anoptional
.Strings are invalid if:
- they contain non-digit characters.
- they don't fit in the target type.
- they're missing a decimal or fractional component. For example, both "0." and ".1" are invalid strings, but "0.1" is accepted.
For signed types like
Fix64
, the string may optionally begin with+
or-
sign prefix.For unsigned types like
UFix64
, sign prefices are not allowed.Examples:
-
Attempts to parse an integer value from a byte array representation (
[UInt8]
) in big-endian order, returningnil
if the input bytes are invalid.For a given integer
n
of typeT
,T.fromBigEndianBytes(n.toBigEndianBytes())
is equivalent to wrappingn
up in an optional.The bytes are invalid if:
- length of the bytes array exceeds the number of bytes needed for the target type
- they don't fit in the target type
Examples:
Minimum and maximum values
The minimum and maximum values for all integer and fixed-point number types are available through the fields min
and max
.
For example:
Saturation Arithmetic
Integers and fixed-point numbers support saturation arithmetic: Arithmetic operations, such as addition or multiplications, are saturating at the numeric bounds instead of overflowing.
If the result of an operation is greater than the maximum value of the operands' type, the maximum is returned. If the result is lower than the minimum of the operands' type, the minimum is returned.
Saturating addition, subtraction, multiplication, and division are provided as functions with the prefix saturating
:
-
Int8
,Int16
,Int32
,Int64
,Int128
,Int256
,Fix64
:saturatingAdd
saturatingSubtract
saturatingMultiply
saturatingDivide
-
Int
:- none
-
UInt8
,UInt16
,UInt32
,UInt64
,UInt128
,UInt256
,UFix64
:saturatingAdd
saturatingSubtract
saturatingMultiply
-
UInt
:saturatingSubtract
Floating-Point Numbers
There is no support for floating point numbers.
Smart Contracts are not intended to work with values with error margins and therefore floating point arithmetic is not appropriate here.
Instead, consider using fixed point numbers.
Addresses
The type Address
represents an address.
Addresses are unsigned integers with a size of 64 bits (8 bytes).
Hexadecimal integer literals can be used to create address values.
Integer literals are not inferred to be an address.
Address can also be created using a byte array or string.
Address Functions
Addresses have multiple built-in functions you can use.
-
Returns the string representation of the address. The result has a
0x
prefix and is zero-padded. -
Returns the byte array representation (
[UInt8]
) of the address.
AnyStruct and AnyResource
AnyStruct
is the top type of all non-resource types,
i.e., all non-resource types are a subtype of it.
AnyResource
is the top type of all resource types.
However, using AnyStruct
and AnyResource
does not opt-out of type checking.
It is invalid to access fields and call functions on these types,
as they have no fields and functions.
AnyStruct
and AnyResource
may be used like other types,
for example, they may be the element type of arrays
or be the element type of an optional type.
AnyStruct
is also the super-type of all non-resource optional types,
and AnyResource
is the super-type of all resource optional types.
Conditional downcasting allows coercing
a value which has the type AnyStruct
or AnyResource
back to its original type.
Optionals
Optionals are values which can represent the absence of a value. Optionals have two cases: either there is a value, or there is nothing.
An optional type is declared using the ?
suffix for another type.
For example, Int
is a non-optional integer, and Int?
is an optional integer,
i.e. either nothing, or an integer.
The value representing nothing is nil
.
Optionals can be created for any value, not just for literals.
A non-optional type is a subtype of its optional type.
Optional types may be contained in other types, for example arrays or even optionals.
See the optional operators section for information on how to work with optionals.
Never
Never
is the bottom type, i.e., it is a subtype of all types.
There is no value that has type Never
.
Never
can be used as the return type for functions that never return normally.
For example, it is the return type of the function panic
.
Strings and Characters
Strings are collections of characters.
Strings have the type String
, and characters have the type Character
.
Strings can be used to work with text in a Unicode-compliant way.
Strings are immutable.
String and character literals are enclosed in double quotation marks ("
).
String literals may contain escape sequences. An escape sequence starts with a backslash (\
):
\0
: Null character\\
: Backslash\t
: Horizontal tab\n
: Line feed\r
: Carriage return\"
: Double quotation mark\'
: Single quotation mark\u
: A Unicode scalar value, written as\u{x}
, wherex
is a 1–8 digit hexadecimal number which needs to be a valid Unicode scalar value, i.e., in the range 0 to 0xD7FF and 0xE000 to 0x10FFFF inclusive
The type Character
represents a single, human-readable character.
Characters are extended grapheme clusters,
which consist of one or more Unicode scalars.
For example, the single character ü
can be represented
in several ways in Unicode.
First, it can be represented by a single Unicode scalar value ü
("LATIN SMALL LETTER U WITH DIAERESIS", code point U+00FC).
Second, the same single character can be represented
by two Unicode scalar values:
u
("LATIN SMALL LETTER U", code point U+0075),
and "COMBINING DIAERESIS" (code point U+0308).
The combining Unicode scalar value is applied to the scalar before it,
which turns a u
into a ü
.
Still, both variants represent the same human-readable character ü
.
Another example where multiple Unicode scalar values are rendered as a single, human-readable character is a flag emoji. These emojis consist of two "REGIONAL INDICATOR SYMBOL LETTER" Unicode scalar values.
String Fields and Functions
Strings have multiple built-in functions you can use:
-
Returns the number of characters in the string as an integer.
-
The byte array of the UTF-8 encoding
-
Concatenates the string
other
to the end of the original string, but does not modify the original string. This function creates a new string whose length is the sum of the lengths of the string the function is called on and the string given as a parameter. -
Returns a string slice of the characters in the given string from start index
from
up to, but not including, the end indexupTo
. This function creates a new string whose length isupTo - from
. It does not modify the original string. If either of the parameters are out of the bounds of the string, or the indices are invalid (from > upTo
), then the function will fail. -
Returns an array containing the bytes represented by the given hexadecimal string.
The given string must only contain hexadecimal characters and must have an even length. If the string is malformed, the program aborts
-
Returns a string where all upper case letters are replaced with lowercase characters
The String
type also provides the following functions:
-
Returns a hexadecimal string for the given byte array
String
s are also indexable, returning a Character
value.
-
Attempts to convert a UTF-8 encoded byte array into a
String
. This function returnsnil
if the byte array contains invalid UTF-8, such as incomplete codepoint sequences or undefined graphemes.For a given string
s
,String.fromUTF8(s.utf8)
is equivalent to wrappings
up in an optional.
Character Fields and Functions
Character
values can be converted into String
values using the toString
function:
-
Returns the string representation of the character.
-
Builds a new
String
value from an array ofCharacter
s. BecauseString
s are immutable, this operation makes a copy of the input array.
Arrays
Arrays are mutable, ordered collections of values.
Arrays may contain a value multiple times.
Array literals start with an opening square bracket [
and end with a closing square bracket ]
.
Array Types
Arrays either have a fixed size or are variably sized, i.e., elements can be added and removed.
Fixed-size array types have the form [T; N]
, where T
is the element type,
and N
is the size of the array. N
has to be statically known, meaning
that it needs to be an integer literal.
For example, a fixed-size array of 3 Int8
elements has the type [Int8; 3]
.
Variable-size array types have the form [T]
, where T
is the element type.
For example, the type [Int16]
specifies a variable-size array of elements that have type Int16
.
All values in an array must have a type which is a subtype of the array's element type (T
).
It is important to understand that arrays are value types and are only ever copied when used as an initial value for a constant or variable, when assigning to a variable, when used as function argument, or when returned from a function call.
Array types are covariant in their element types.
For example, [Int]
is a subtype of [AnyStruct]
.
This is safe because arrays are value types and not reference types.
Array Indexing
To get the element of an array at a specific index, the indexing syntax can be used:
The array is followed by an opening square bracket [
, the indexing value,
and ends with a closing square bracket ]
.
Indexes start at 0 for the first element in the array.
Accessing an element which is out of bounds results in a fatal error at run-time and aborts the program.
To set an element of an array at a specific index, the indexing syntax can be used as well.
Array Fields and Functions
Arrays have multiple built-in fields and functions that can be used to get information about and manipulate the contents of the array.
The field length
, and the functions concat
, and contains
are available for both variable-sized and fixed-sized or variable-sized arrays.
-
The number of elements in the array.
-
Concatenates the parameter
array
to the end of the array the function is called on, but does not modify that array.Both arrays must be the same type
T
.This function creates a new array whose length is the sum of the length of the array the function is called on and the length of the array given as the parameter.
-
Returns true if the given element of type
T
is in the array. -
Returns the index of the first element matching the given object in the array, nil if no match. Available if
T
is not resource-kinded and equatable. -
Returns an array slice of the elements in the given array from start index
from
up to, but not including, the end indexupTo
. This function creates a new array whose length isupTo - from
. It does not modify the original array. If either of the parameters are out of the bounds of the array, or the indices are invalid (from > upTo
), then the function will fail.
Variable-size Array Functions
The following functions can only be used on variable-sized arrays. It is invalid to use one of these functions on a fixed-sized array.
-
Adds the new element
element
of typeT
to the end of the array.The new element must be the same type as all the other elements in the array.
This function mutates the array.
-
Adds all the elements from
array
to the end of the array the function is called on.Both arrays must be the same type
T
.This function mutates the array.
-
Inserts the new element
element
of typeT
at the givenindex
of the array.The new element must be of the same type as the other elements in the array.
The
index
must be within the bounds of the array. If the index is outside the bounds, the program aborts.The existing element at the supplied index is not overwritten.
All the elements after the new inserted element are shifted to the right by one.
This function mutates the array.
-
Removes the element at the given
index
from the array and returns it.The
index
must be within the bounds of the array. If the index is outside the bounds, the program aborts.This function mutates the array.
-
Removes the first element from the array and returns it.
The array must not be empty. If the array is empty, the program aborts.
This function mutates the array.
-
Removes the last element from the array and returns it.
The array must not be empty. If the array is empty, the program aborts.
This function mutates the array.
Dictionaries
Dictionaries are mutable, unordered collections of key-value associations. Dictionaries may contain a key only once and may contain a value multiple times.
Dictionary literals start with an opening brace {
and end with a closing brace }
.
Keys are separated from values by a colon,
and key-value associations are separated by commas.
Dictionary Types
Dictionary types have the form {K: V}
,
where K
is the type of the key,
and V
is the type of the value.
For example, a dictionary with Int
keys and Bool
values has type {Int: Bool}
.
In a dictionary, all keys must have a type that is a subtype of the dictionary's key type (K
)
and all values must have a type that is a subtype of the dictionary's value type (V
).
Dictionary types are covariant in their key and value types.
For example, {Int: String}
is a subtype of {AnyStruct: String}
and also a subtype of {Int: AnyStruct}
.
This is safe because dictionaries are value types and not reference types.
Dictionary Access
To get the value for a specific key from a dictionary,
the access syntax can be used:
The dictionary is followed by an opening square bracket [
, the key,
and ends with a closing square bracket ]
.
Accessing a key returns an optional:
If the key is found in the dictionary, the value for the given key is returned,
and if the key is not found, nil
is returned.
To set the value for a key of a dictionary, the access syntax can be used as well.
Dictionary Fields and Functions
-
The number of entries in the dictionary.
-
Inserts the given value of type
V
into the dictionary under the givenkey
of typeK
.The inserted key must have the same type as the dictionary's key type, and the inserted value must have the same type as the dictionary's value type.
Returns the previous value as an optional if the dictionary contained the key, otherwise
nil
.Updates the value if the dictionary already contained the key.
This function mutates the dictionary.
-
Removes the value for the given
key
of typeK
from the dictionary.Returns the value of type
V
as an optional if the dictionary contained the key, otherwisenil
.This function mutates the dictionary.
-
Returns an array of the keys of type
K
in the dictionary. This does not modify the dictionary, just returns a copy of the keys as an array. If the dictionary is empty, this returns an empty array. The ordering of the keys is undefined. -
Returns an array of the values of type
V
in the dictionary. This does not modify the dictionary, just returns a copy of the values as an array. If the dictionary is empty, this returns an empty array.This field is not available if
V
is a resource type. -
Returns true if the given key of type
K
is in the dictionary. -
Iterate through all the keys in the dictionary, exiting early if the passed function returns false. This is more efficient than calling
.keys
and iterating over the resulting array, since an intermediate allocation is avoided. The order of key iteration is undefined, similar to.keys
.
Dictionary Keys
Dictionary keys must be hashable and equatable.
Most of the built-in types, like booleans and integers, are hashable and equatable, so can be used as keys in dictionaries.