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


// A decimal number
//
1234567890  // is `1234567890`
 
// A binary number
//
0b101010  // is `42`
 
// An octal number
//
0o12345670  // is `2739128`
 
// A hexadecimal number
//
0x1234567890ABCabc  // is `1311768467294898876`
 
// Invalid: unsupported prefix 0z
//
0z0
 
// A decimal number with leading zeros. Not an octal number!
00123 // is `123`
 
// A binary number with several trailing zeros.
0b001000  // is `8`

Decimal numbers may contain underscores (_) to logically separate components.


let largeNumber = 1_000_000
 
// Invalid: Value is not a number literal, but a variable.
let notNumber = _123

Underscores are allowed for all numeral systems.


let binaryNumber = 0b10_11_01

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 − 1
Int256: -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 − 1
UInt256: 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)
Word128: 0 through 2^128 − 1 (340282366920938463463374607431768211455)
Word256: 0 through 2^256 − 1 (115792089237316195423570985008687907853269984665640564039457584007913129639935)

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.


// Declare a constant that has type `UInt8` and the value 10.
let smallNumber: UInt8 = 10


// Invalid: negative literal cannot be used as an unsigned integer
//
let invalidNumber: UInt8 = -10

In addition, the arbitrary precision integer type Int is provided.


let veryLargeNumber: Int = 10000000000000000000000000000000

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.


let someNumber = 123
 
// `someNumber` has type `Int`

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.


let x: Int8 = 1
let y: Int16 = 2
 
// Invalid: the types of the operands, `Int8` and `Int16` are incompatible.
let z = x + y
 
// Explicitly convert `x` from `Int8` to `Int16`.
let a = Int16(x) + y
 
// `a` has type `Int16`
 
// Invalid: The integer literal is expected to be of type `Int8`,
// but the large integer literal does not fit in the range of `Int8`.
//
let b = x + 1000000000000000000000000

Integer Functions

Integers have multiple built-in functions you can use.


view fun toString(): String

Returns the string representation of the integer.


let answer = 42
 
answer.toString()  // is "42"


view fun toBigEndianBytes(): [UInt8]

Returns the byte array representation ([UInt8]) in big-endian order of the integer.


let largeNumber = 1234567890
 
largeNumber.toBigEndianBytes()  // is `[73, 150, 2, 210]`

All integer types support the following functions:

```
view fun T.fromString(_ input: String): T?
```
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 type T, T.fromString(n.toString()) is equivalent to wrapping n 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, and Int, the string may optionally begin with + or - sign prefix.

For unsigned integer types like Word64, UInt64, and UInt, sign prefices are not allowed.

Examples:
```
let fortyTwo: Int64? = Int64.fromString("42") // ok
 
let twenty: UInt? = UInt.fromString("20") // ok
 
let nilWord: Word8? = Word8.fromString("1024") // nil, out of bounds
 
let negTwenty: Int? = Int.fromString("-20") // ok
```


view fun T.fromBigEndianBytes(_ bytes: [UInt8]): T?

Attempts to parse an integer value from a byte array representation ([UInt8]) in big-endian order, returning nil if the input bytes are invalid.

For a given integer n of type T, T.fromBigEndianBytes(n.toBigEndianBytes()) is equivalent to wrapping n 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:


let fortyTwo: UInt32? = UInt32.fromBigEndianBytes([42]) // ok
 
let twenty: UInt? = UInt.fromBigEndianBytes([0, 0, 20]) // ok
 
let nilWord: Word8? = Word8.fromBigEndianBytes("[0, 22, 0, 0, 0, 0, 0, 0, 0]") // nil, out of bounds
 
let nilWord2: Word8? = Word8.fromBigEndianBytes("[0, 0]") // nil, size (2) exceeds number of bytes needed for Word8 (1)
 
let negativeNumber: Int64? = Int64.fromBigEndianBytes([128, 0, 0, 0, 0, 0, 0, 1]) // ok -9223372036854775807

Fixed-Point Numbers

:::warning[🚧 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.


view fun toString(): String

Returns the string representation of the fixed-point number.


let fix = 1.23
 
fix.toString()  // is "1.23000000"


view fun toBigEndianBytes(): [UInt8]

Returns the byte array representation ([UInt8]) in big-endian order of the fixed-point number.


let fix = 1.23
 
fix.toBigEndianBytes()  // is `[0, 0, 0, 0, 7, 84, 212, 192]`

All fixed-point types support the following functions:

```
view fun T.fromString(_ input: String): T?
```
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 type T, T.fromString(n.toString()) is equivalent to wrapping n up in an optional.

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:
```
let nil1: UFix64? = UFix64.fromString("0.") // nil, fractional part is required
 
let nil2: UFix64? = UFix64.fromString(".1") // nil, decimal part is required
 
let smol: UFix64? = UFix64.fromString("0.1") // ok
 
let smolString: String = "-0.1"
 
let nil3: UFix64? = UFix64.fromString(smolString) // nil, unsigned types don't allow a sign prefix
 
let smolFix64: Fix64? = Fix64.fromString(smolString) // ok
```


view fun T.fromBigEndianBytes(_ bytes: [UInt8]): T?

Attempts to parse an integer value from a byte array representation ([UInt8]) in big-endian order, returning nil if the input bytes are invalid.

For a given integer n of type T, T.fromBigEndianBytes(n.toBigEndianBytes()) is equivalent to wrapping n 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:


let fortyTwo: UFix64? = UFix64.fromBigEndianBytes([0, 0, 0, 0, 250, 86, 234, 0]) // ok, 42.0
 
let nilWord: UFix64? = UFix64.fromBigEndianBytes("[100, 22, 0, 0, 0, 0, 0, 0, 0]") // nil, out of bounds
 
let nilWord2: Fix64? = Fix64.fromBigEndianBytes("[0, 22, 0, 0, 0, 0, 0, 0, 0]") // // nil, size (9) exceeds number of bytes needed for Fix64 (8)
 
let negativeNumber: Fix64? = Fix64.fromBigEndianBytes([255, 255, 255, 255, 250, 10, 31, 0]) // ok, -1

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:


let max = UInt8.max
// `max` is 255, the maximum value of the type `UInt8`


let max = UFix64.max
// `max` is 184467440737.09551615, the maximum value of the type `UFix64`

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


let a: UInt8 = 200
let b: UInt8 = 100
let result = a.saturatingAdd(b)
// `result` is 255, the maximum value of the type `UInt8`

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.


// Declare a constant that has type `Address`.
//
let someAddress: Address = 0x436164656E636521
 
// Invalid: Initial value is not compatible with type `Address`,
// it is not a number.
//
let notAnAddress: Address = ""
 
// Invalid: Initial value is not compatible with type `Address`.
// The integer literal is valid, however, it is larger than 64 bits.
//
let alsoNotAnAddress: Address = 0x436164656E63652146757265766572

Integer literals are not inferred to be an address.


// Declare a number. Even though it happens to be a valid address,
// it is not inferred as it.
//
let aNumber = 0x436164656E636521
 
// `aNumber` has type `Int`

Address can also be created using a byte array or string.


// Declare an address with hex representation as 0x436164656E636521.
let someAddress: Address = Address.fromBytes([67, 97, 100, 101, 110, 99, 101, 33])
 
// Invalid: Provided value is not compatible with type `Address`. The function panics.
let invalidAddress: Address = Address.fromBytes([12, 34, 56, 11, 22, 33, 44, 55, 66, 77, 88, 99, 111])
 
// Declare an address with the string representation as "0x436164656E636521".
let addressFromString: Address? = Address.fromString("0x436164656E636521")
 
// Invalid: Provided value does not have the "0x" prefix. Returns Nil
let addressFromStringWithoutPrefix: Address? = Address.fromString("436164656E636521")
 
// Invalid: Provided value is an invalid hex string. Return Nil.
let invalidAddressForInvalidHex: Address? = Address.fromString("0xZZZ")
 
// Invalid: Provided value is larger than 64 bits. Return Nil.
let invalidAddressForOverflow: Address? = Address.fromString("0x436164656E63652146757265766572")

Address Functions

Addresses have multiple built-in functions you can use.


view fun toString(): String

Returns the string representation of the address. The result has a 0x prefix and is zero-padded.


let someAddress: Address = 0x436164656E636521
someAddress.toString()   // is "0x436164656E636521"
 
let shortAddress: Address = 0x1
shortAddress.toString()  // is "0x0000000000000001"


view fun toBytes(): [UInt8]

Returns the byte array representation ([UInt8]) of the address.


let someAddress: Address = 0x436164656E636521
 
someAddress.toBytes()  // is `[67, 97, 100, 101, 110, 99, 101, 33]`

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.


// Declare a variable that has the type `AnyStruct`.
// Any non-resource typed value can be assigned to it, for example an integer,
// but not resource-typed values.
//
var someStruct: AnyStruct = 1
 
// Assign a value with a different non-resource type, `Bool`.
someStruct = true
 
// Declare a structure named `TestStruct`, create an instance of it,
// and assign it to the `AnyStruct`-typed variable
//
struct TestStruct {}
 
let testStruct = TestStruct()
 
someStruct = testStruct
 
// Declare a resource named `TestResource`
 
resource TestResource {}
 
// Declare a variable that has the type `AnyResource`.
// Any resource-typed value can be assigned to it,
// but not non-resource typed values.
//
var someResource: @AnyResource <- create TestResource()
 
// Invalid: Resource-typed values can not be assigned
// to `AnyStruct`-typed variables
//
someStruct <- create TestResource()
 
// Invalid: Non-resource typed values can not be assigned
// to `AnyResource`-typed variables
//
someResource = 1

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.


// Declare a variable that has the type `AnyStruct`.
// The initial value is an integer,
// but the variable still has the explicit type `AnyStruct`.
//
let a: AnyStruct = 1
 
// Invalid: Operator cannot be used for an `AnyStruct` value (`a`, left-hand side)
// and an `Int` value (`2`, right-hand side).
//
a + 2

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.


// Declare a variable that has the type `[AnyStruct]`,
// i.e. an array of elements of any non-resource type.
//
let anyValues: [AnyStruct] = [1, "2", true]
 
// Declare a variable that has the type `AnyStruct?`,
// i.e. an optional type of any non-resource type.
//
var maybeSomething: AnyStruct? = 42
 
maybeSomething = "twenty-four"
 
maybeSomething = nil

AnyStruct is also the super-type of all non-resource optional types, and AnyResource is the super-type of all resource optional types.


let maybeInt: Int? = 1
let anything: AnyStruct = maybeInt

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.


// Declare a constant which has an optional integer type,
// with nil as its initial value.
//
let a: Int? = nil
 
// Declare a constant which has an optional integer type,
// with 42 as its initial value.
//
let b: Int? = 42
 
// Invalid: `b` has type `Int?`, which does not support arithmetic.
b + 23
 
// Invalid: Declare a constant with a non-optional integer type `Int`,
// but the initial value is `nil`, which in this context has type `Int?`.
//
let x: Int = nil

Optionals can be created for any value, not just for literals.


// Declare a constant which has a non-optional integer type,
// with 1 as its initial value.
//
let x = 1
 
// Declare a constant which has an optional integer type.
// An optional with the value of `x` is created.
//
let y: Int? = x
 
// Declare a variable which has an optional any type, i.e. the variable
// may be `nil`, or any other value.
// An optional with the value of `x` is created.
//
var z: AnyStruct? = x

A non-optional type is a subtype of its optional type.


var a: Int? = nil
let b = 2
a = b
 
// `a` is `2`

Optional types may be contained in other types, for example arrays or even optionals.


// Declare a constant which has an array type of optional integers.
let xs: [Int?] = [1, nil, 2, nil]
 
// Declare a constant which has a double optional type.
//
let doubleOptional: Int?? = nil

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.


// Declare a function named `crashAndBurn` which will never return,
// because it calls the function named `panic`, which never returns.
//
fun crashAndBurn(): Never {
    panic("An unrecoverable error occurred")
}
 
// Invalid: Declare a constant with a `Never` type, but the initial value is an integer.
//
let x: Never = 1
 
// Invalid: Declare a function which returns an invalid return value `nil`,
// which is not a value of type `Never`.
//
fun returnNever(): Never {
    return nil
}

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 (").


let someString = "Hello, world!"

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}, where x 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


// Declare a constant which contains two lines of text
// (separated by the line feed character `\n`), and ends
// with a thumbs up emoji, which has code point U+1F44D (0x1F44D).
//
let thumbsUpText =
    "This is the first line.\nThis is the second line with an emoji: \u{1F44D}"

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 ü.


let singleScalar: Character = "\u{FC}"
// `singleScalar` is `ü`
let twoScalars: Character = "\u{75}\u{308}"
// `twoScalars` is `ü`

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.


// Declare a constant for a string with a single character, the emoji
// for the Canadian flag, which consists of two Unicode scalar values:
// - REGIONAL INDICATOR SYMBOL LETTER C (U+1F1E8)
// - REGIONAL INDICATOR SYMBOL LETTER A (U+1F1E6)
//
let canadianFlag: Character = "\u{1F1E8}\u{1F1E6}"
// `canadianFlag` is `🇨🇦`

String Fields and Functions

Strings have multiple built-in functions you can use:


let length: Int

Returns the number of characters in the string as an integer.


let example = "hello"
 
// Find the number of elements of the string.
let length = example.length
// `length` is `5`


let utf8: [UInt8]

The byte array of the UTF-8 encoding


let flowers = "Flowers \u{1F490}"
let bytes = flowers.utf8
// `bytes` is `[70, 108, 111, 119, 101, 114, 115, 32, 240, 159, 146, 144]`

```
view fun concat(_ other: String): String
```
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.
```
let example = "hello"
let new = "world"
 
// Concatenate the new string onto the example string and return the new string.
let helloWorld = example.concat(new)
// `helloWorld` is now `"helloworld"`
```


view fun slice(from: Int, upTo: Int): String

Returns a string slice of the characters in the given string from start index from up to, but not including, the end index upTo. This function creates a new string whose length is upTo - 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.


let example = "helloworld"
 
// Create a new slice of part of the original string.
let slice = example.slice(from: 3, upTo: 6)
// `slice` is now `"low"`
 
// Run-time error: Out of bounds index, the program aborts.
let outOfBounds = example.slice(from: 2, upTo: 10)
 
// Run-time error: Invalid indices, the program aborts.
let invalidIndices = example.slice(from: 2, upTo: 1)

```
view fun decodeHex(): [UInt8]
```
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
```
let example = "436164656e636521"
 
example.decodeHex()  // is `[67, 97, 100, 101, 110, 99, 101, 33]`
```


view fun toLower(): String

Returns a string where all upper case letters are replaced with lowercase characters


let example = "Flowers"
 
example.toLower()  // is `flowers`

```
view fun replaceAll(of: String, with: String): String
```
Returns a string where all occurences of of are replaced with with. If of is empty, it matches at the beginning of the string and after each UTF-8 sequence, yielding k+1 replacements for a string of length k.
```
let example = "abababa"
 
example.replaceAll(of: "a", with: "o")  // is `obobobo`
```


view fun split(separator: String): [String]

Returns the variable-sized array of strings created splitting the receiver string on the separator.


let example = "hello world"
 
example.split(separator: " ")  // is `["hello", "world"]`

The String type also provides the following functions:


view fun String.encodeHex(_ data: [UInt8]): String

Returns a hexadecimal string for the given byte array


let data = [1 as UInt8, 2, 3, 0xCA, 0xDE]
 
String.encodeHex(data)  // is `"010203cade"`


view fun String.join(_ strings: [String], separator: String): String

Returns the string created by joining the array of strings with the provided separator.


let strings = ["hello", "world"]
String.join(strings, " ") // is "hello world"

Strings are also indexable, returning a Character value.


let str = "abc"
let c = str[0] // is the Character "a"

```
view fun String.fromUTF8(_ input: [UInt8]): String?
```
Attempts to convert a UTF-8 encoded byte array into a String. This function returns nil 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 wrapping s up in an optional.

Character Fields and Functions

Character values can be converted into String values using the toString function:


view fun toString(): String`

Returns the string representation of the character.


let c: Character = "x"
 
c.toString()  // is "x"


view fun String.fromCharacters(_ characters: [Character]): String

Builds a new String value from an array of Characters. Because Strings are immutable, this operation makes a copy of the input array.


let rawUwU: [Character] = ["U", "w", "U"]
let uwu: String = String.fromCharacters(rawUwU) // "UwU"


let utf8: [UInt8]

The byte array of the UTF-8 encoding


let a: Character = "a"
let a_bytes = a.utf8 // `a_bytes` is `[97]`
 
let bouquet: Character = "\u{1F490}"
let bouquet_bytes = bouquet.utf8 // `bouquet_bytes` is `[240, 159, 146, 144]`

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 ].


// An empty array
//
[]
 
// An array with integers
//
[1, 2, 3]

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.


let size = 2
// Invalid: Array-size must be an integer literal
let numbers: [Int; size] = []
 
// Declare a fixed-sized array of integers
// which always contains exactly two elements.
//
let array: [Int8; 2] = [1, 2]
 
// Declare a fixed-sized array of fixed-sized arrays of integers.
// The inner arrays always contain exactly three elements,
// the outer array always contains two elements.
//
let arrays: [[Int16; 3]; 2] = [
    [1, 2, 3],
    [4, 5, 6]
]
 
// Declare a variable length array of integers
var variableLengthArray: [Int] = []
 
// Mixing values with different types is possible
// by declaring the expected array type
// with the common supertype of all values.
//
let mixedValues: [AnyStruct] = ["some string", 42]

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.


// Declare an array of integers.
let numbers = [42, 23]
 
// Get the first number of the array.
//
numbers[0] // is `42`
 
// Get the second number of the array.
//
numbers[1] // is `23`
 
// Run-time error: Index 2 is out of bounds, the program aborts.
//
numbers[2]


// Declare an array of arrays of integers, i.e. the type is `[[Int]]`.
let arrays = [[1, 2], [3, 4]]
 
// Get the first number of the second array.
//
arrays[1][0] // is `3`

To set an element of an array at a specific index, the indexing syntax can be used as well.


// Declare an array of integers.
let numbers = [42, 23]
 
// Change the second number in the array.
//
// NOTE: The declaration `numbers` is constant, which means that
// the *name* is constant, not the *value* – the value, i.e. the array,
// is mutable and can be changed.
//
numbers[1] = 2
 
// `numbers` is `[42, 2]`

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.


let length: Int

The number of elements in the array.


// Declare an array of integers.
let numbers = [42, 23, 31, 12]
 
// Find the number of elements of the array.
let length = numbers.length
 
// `length` is `4`


access(all)
view fun concat(_ array: T): T

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.


// Declare two arrays of integers.
let numbers = [42, 23, 31, 12]
let moreNumbers = [11, 27]
 
// Concatenate the array `moreNumbers` to the array `numbers`
// and declare a new variable for the result.
//
let allNumbers = numbers.concat(moreNumbers)
 
// `allNumbers` is `[42, 23, 31, 12, 11, 27]`
// `numbers` is still `[42, 23, 31, 12]`
// `moreNumbers` is still `[11, 27]`


access(all)
view fun contains(_ element: T): Bool

Returns true if the given element of type T is in the array.


// Declare an array of integers.
let numbers = [42, 23, 31, 12]
 
// Check if the array contains 11.
let containsEleven = numbers.contains(11)
// `containsEleven` is `false`
 
// Check if the array contains 12.
let containsTwelve = numbers.contains(12)
// `containsTwelve` is `true`
 
// Invalid: Check if the array contains the string "Kitty".
// This results in a type error, as the array only contains integers.
//
let containsKitty = numbers.contains("Kitty")


access(all)
view fun firstIndex(of: T): Int?

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.


 // Declare an array of integers.
 let numbers = [42, 23, 31, 12]
 
 // Check if the array contains 31
 let index = numbers.firstIndex(of: 31)
 // `index` is 2
 
 // Check if the array contains 22
 let index = numbers.firstIndex(of: 22)
 // `index` is nil


access(all)
view fun slice(from: Int, upTo: Int): [T]

Returns an array slice of the elements in the given array from start index from up to, but not including, the end index upTo. This function creates a new array whose length is upTo - 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.


let example = [1, 2, 3, 4]
 
// Create a new slice of part of the original array.
let slice = example.slice(from: 1, upTo: 3)
// `slice` is now `[2, 3]`
 
// Run-time error: Out of bounds index, the program aborts.
let outOfBounds = example.slice(from: 2, upTo: 10)
 
// Run-time error: Invalid indices, the program aborts.
let invalidIndices = example.slice(from: 2, upTo: 1)


access(all)
view fun reverse(): [T]

Returns a new array with contents in the reversed order. Available if T is not resource-kinded.


let example = [1, 2, 3, 4]
 
// Create a new array which is the reverse of the original array.
let reversedExample = example.reverse()
// `reversedExample` is now `[4, 3, 2, 1]`


access(all)
view fun reverse(): [T; N]

Returns a new fixed-sized array of same size with contents in the reversed order.


let fixedSizedExample: [String; 3] = ["ABC", "XYZ", "PQR"]
 
// Create a new array which is the reverse of the original array.
let fixedArrayReversedExample = fixedSizedExample.reverse()
// `fixedArrayReversedExample` is now `["PQR", "XYZ", "ABC"]`


access(all)
fun map(_ f: fun(T): U): [U]

Returns a new array whose elements are produced by applying the mapper function on each element of the original array. Available if T is not resource-kinded.


let example = [1, 2, 3]
let trueForEven =
    fun (_ x: Int): Bool {
        return x % 2 == 0
    }
 
let mappedExample: [Bool] = example.map(trueForEven)
// `mappedExample` is `[False, True, False]`
// `example` still remains as `[1, 2, 3]`
 
// Invalid: Map using a function which accepts a different type.
// This results in a type error, as the array contains `Int` values while function accepts 
// `Int64`.
let functionAcceptingInt64 =
    fun (_ x: Int64): Bool {
        return x % 2 == 0
    }
let invalidMapFunctionExample = example.map(functionAcceptingInt64)

map function is also available for fixed-sized arrays:


access(all)
fun map(_ f: fun(T): U): [U; N]

Returns a new fixed-sized array whose elements are produced by applying the mapper function on each element of the original array. Available if T is not resource-kinded.


let fixedSizedExample: [String; 3] = ["ABC", "XYZYX", "PQR"]
let lengthOfString =
    fun (_ x: String): Int {
        return x.length
    }
 
let fixedArrayMappedExample = fixedSizedExample.map(lengthOfString)
// `fixedArrayMappedExample` is now `[3, 5, 3]`
// `fixedSizedExample` still remains as ["ABC", "XYZYX", "PQR"]
 
// Invalid: Map using a function which accepts a different type.
// This results in a type error, as the array contains `String` values while function accepts 
// `Bool`.
let functionAcceptingBool =
    fun (_ x: Bool): Int {
        return 0
    }
let invalidMapFunctionExample = fixedSizedExample.map(functionAcceptingBool)


access(all)
view fun filter(_ f: view fun(T): Bool): [T]

Returns a new array whose elements are filtered by applying the filter function on each element of the original array. Available if T is not resource-kinded.


let example = [1, 2, 3]
let trueForEven =
    fun (_ x: Int): Bool {
        return x % 2 == 0
    }
 
let filteredExample: [Int] = example.filter(trueForEven)
// `filteredExample` is `[2]`
// `example` still remains as `[1, 2, 3]`
 
// Invalid: Filter using a function which accepts a different type.
// This results in a type error, as the array contains `Int` values while function accepts 
// `Int64`.
let functionAcceptingInt64 =
    fun (_ x: Int64): Bool {
        return x % 2 == 0
    }
let invalidFilterFunctionExample = example.filter(functionAcceptingInt64)

filter function is also available for fixed-sized arrays:


access(all)
view fun filter(_ f: view fun(T): Bool): [T]

Returns a new variable-sized array whose elements are filtered by applying the filter function on each element of the original array. Available if T is not resource-kinded.


let fixedSizedExample: [String; 3] = ["AB", "XYZYX", "PQR"]
let lengthOfStringGreaterThanTwo =
    fun (_ x: String): Bool {
        return x.length > 2
    }
 
let fixedArrayFilteredExample = fixedSizedExample.filter(lengthOfStringGreaterThanTwo)
// `fixedArrayFilteredExample` is `["XYZYX", "PQR"]`
// `fixedSizedExample` still remains as ["AB", "XYZYX", "PQR"]
 
// Invalid: Filter using a function which accepts a different type.
// This results in a type error, as the array contains `String` values while function accepts 
// `Bool`.
let functionAcceptingBool =
    fun (_ x: Bool): Bool {
        return True
    }
let invalidFilterFunctionExample = fixedSizedExample.filter(functionAcceptingBool)

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.


access(Mutate | Insert)
fun append(_ element: T): Void

Adds the new element element of type T to the end of the array.

The new element must be the same type as all the other elements in the array.