Skip to main content
Version: 11.x

Class: CairoArray

Defined in: src/utils/cairoDataTypes/array.ts:30

A Cairo dynamic array : any number of values, all of the same type.

Its abi type is core::array::Array::<T> or core::array::Span::<T>, and both are handled the same way. Unlike a tuple, whose size is in its type, an array carries its length on the wire : the felts start with how many elements follow.

Text is accepted where the elements are felt252 or bytes31, and is split into the 31-character chunks each of those holds — which is how a long string reaches a contract that takes an array of felts.

Example​

const array = new CairoArray([1, 2, 3], 'core::array::Array::<core::integer::u8>', cairoTypeStrategy);
array.toApiRequest(); //                 ["3", "1", "2", "3"]     length first
array.decompose(cairoTypeStrategy); //   [1n, 2n, 3n]

Constructors​

Constructor​

new CairoArray(content, arrayType, parsingStrategy): CairoArray

Defined in: src/utils/cairoDataTypes/array.ts:96

Build an array, from values a caller passed or from the felts of a response.

Elements are accepted raw, or already built and taken as they stand. An object is read by its values, and text is split into chunks where the element type holds text.

Parameters​

content​

unknown

the elements, as an array, an object, text, or the response iterator

arrayType​

string

the abi type, core::array::Array::<T> or Span::<T>

parsingStrategy​

AllowArray<CairoTypeStrategy>

how to build each element

Returns​

CairoArray

Throws​

when the type is not an array, or when its element type no strategy knows

Example​

const fromArray = new CairoArray([1, 2], 'core::array::Array::<core::integer::u8>', cairoTypeStrategy);
fromArray.toApiRequest(); // ["2", "1", "2"]

const fromResponse = new CairoArray(
  ['0x2', '0x1', '0x2'].values(),
  'core::array::Array::<core::integer::u8>',
  cairoTypeStrategy
);
fromResponse.toApiRequest(); // ["2", "1", "2"]

Properties​

dynamicSelector​

static dynamicSelector: "CairoArray"

Defined in: src/utils/cairoDataTypes/array.ts:39

The name this class is registered under in a strategy's dynamicSelectors.

Example​

const result = CairoArray.dynamicSelector;
// result = "CairoArray"

dynamicSelector​

readonly dynamicSelector: "CairoArray" = CairoArray.dynamicSelector

Defined in: src/utils/cairoDataTypes/array.ts:50

The selector on the instance, which is how a composite holding it knows what built it.

Example​

const array = new CairoArray([1], 'core::array::Array::<core::integer::u8>', cairoTypeStrategy);
const result = array.dynamicSelector;
// result = "CairoArray"

content​

readonly content: CairoType[]

Defined in: src/utils/cairoDataTypes/array.ts:61

The elements, each already built as the type the array declares.

Example​

const array = new CairoArray([1, 2, 3], 'core::array::Array::<core::integer::u8>', cairoTypeStrategy);
const result = array.content.length;
// result = 3

arrayType​

readonly arrayType: string

Defined in: src/utils/cairoDataTypes/array.ts:72

The abi type this array was built for.

Example​

const array = new CairoArray([1], 'core::array::Span::<core::integer::u8>', cairoTypeStrategy);
const result = array.arrayType;
// result = "core::array::Span::<core::integer::u8>"

Methods​

getArrayElementType()​

static getArrayElementType(type): string

Defined in: src/utils/cairoDataTypes/array.ts:217

The type of the elements an array holds.

Parameters​

type​

string

the abi type to read

Returns​

string

the element type

Example​

const result = CairoArray.getArrayElementType('core::array::Array::<core::integer::u32>');
// result = "core::integer::u32"
const result2 = CairoArray.getArrayElementType('core::array::Span::<core::integer::u8>');
// result2 = "core::integer::u8"

validate()​

static validate(input, type): void

Defined in: src/utils/cairoDataTypes/array.ts:238

Throw unless this input can be read as an array of this type.

Only the shape is checked : an array type, and elements given as a list or an object. How many there are is not, since an array declares no length — that is the whole difference with a tuple.

Parameters​

input​

unknown

the elements to check

type​

string

the abi type they are meant for

Returns​

void

Throws​

when the type is not an array, or the input is neither an array nor an object

Example​

CairoArray.validate([1, 2], 'core::array::Array::<core::integer::u8>'); // passes
CairoArray.validate([1, 2], 'core::integer::u8');
// throws Error("The type core::integer::u8 is not a Cairo dynamic array. Needs
//               core::array::Array::<T> or core::array::Span::<T>.")

is()​

static is(input, type): boolean

Defined in: src/utils/cairoDataTypes/array.ts:264

Can this input be read as an array of this type?

The non-throwing form of CairoArray.validate.

Parameters​

input​

unknown

the elements to test

type​

string

the abi type they are meant for

Returns​

boolean

true when the shape fits

Example​

const result = CairoArray.is([1, 2], 'core::array::Array::<core::integer::u8>');
// result = true
const result2 = CairoArray.is('nope', 'core::array::Array::<core::integer::u8>');
// result2 = false

isAbiType()​

static isAbiType(type): boolean

Defined in: src/utils/cairoDataTypes/array.ts:287

Is this abi type a dynamic array?

Parameters​

type​

string

the abi type to test

Returns​

boolean

true for core::array::Array::<T> and core::array::Span::<T>

Example​

const result = CairoArray.isAbiType('core::array::Array::<core::integer::u32>');
// result = true
const result2 = CairoArray.isAbiType('core::array::Span::<core::integer::u8>');
// result2 = true
const result3 = CairoArray.isAbiType('[core::integer::u32; 8]');
// result3 = false     (a fixed array declares its length in its type)

toApiRequest()​

toApiRequest(): string[]

Defined in: src/utils/cairoDataTypes/array.ts:304

Serialize to the felts a contract call carries.

The count comes first, then the elements. A nested array carries its own count in turn, which is what lets the whole of it be read back from one flat list.

Returns​

string[]

the length then the elements' felts, flagged as compiled

Example​

const array = new CairoArray([1, 2, 3], 'core::array::Array::<core::integer::u8>', cairoTypeStrategy);
const result = array.toApiRequest();
// result = ["3", "1", "2", "3"]

decompose()​

decompose(strategyDecompose): any[]

Defined in: src/utils/cairoDataTypes/array.ts:326

Read the array back as the plain values a caller reads.

Each element is handed to the strategy entry for its type — or for what built it, when that is a composite, which is what its dynamicSelector says.

Parameters​

strategyDecompose​

AllowArray<CairoTypeStrategy>

how to read each element back

Returns​

any[]

the elements' values, in order

Throws​

when no strategy can read an element back

Example​

const array = new CairoArray([1, 2, 3], 'core::array::Array::<core::integer::u8>', cairoTypeStrategy);
const result = array.decompose(cairoTypeStrategy);
// result = [1n, 2n, 3n]