Dart API

Appearance

dart:ffi›Classes›Array<T extends NativeType>

Array<T extends NativeType> final ​

final class Array<T extends NativeType> extends _Compound implements NativeType

Annotations: @Since.new('2.13')

A fixed-sized array of Ts.

Implemented types

Available Extensions

Constructors ​

Array() factory const ​

const factory Array(
  int dimension1, [
  int dimension2,
  int dimension3,
  int dimension4,
  int dimension5,
])

Annotation to specify Array dimensions in Structs.

dart
final class MyStruct extends Struct {
  @Array(8)
  external Array<Uint8> inlineArray;

  @Array(2, 2, 2)
  external Array<Array<Array<Uint8>>> threeDimensionalInlineArray;
}

Do not invoke in normal code.

Implementation
dart
const factory Array(
  int dimension1, [
  int dimension2,
  int dimension3,
  int dimension4,
  int dimension5,
]) = _ArraySize<T>;

Array.multi() factory const ​

const factory Array.multi(List<int> dimensions)

Annotation to specify Array dimensions in Structs.

dart
final class MyStruct extends Struct {
  @Array.multi([2, 2, 2])
  external Array<Array<Array<Uint8>>> threeDimensionalInlineArray;

  @Array.multi([2, 2, 2, 2, 2, 2, 2, 2])
  external Array<Array<Array<Array<Array<Array<Array<Array<Uint8>>>>>>>> eightDimensionalInlineArray;
}

Do not invoke in normal code.

Implementation
dart
const factory Array.multi(List<int> dimensions) = _ArraySize<T>.multi;

Array.variable() factory const ​

const factory Array.variable([
  int dimension2,
  int dimension3,
  int dimension4,
  int dimension5,
])

Annotation to specify a variable length Array in Structs.

Can only be used on the last field of a struct. The last field of the struct is not taken into account in sizeOf. Using an AllocatorAlloc.call will not allocate any backing storage for the variable length array. Instead use Allocator.allocate and calculate the required number of bytes manually.

dart
import 'dart:ffi';
import 'package:ffi/ffi.dart';

final class MyStruct extends Struct {
  @Size()
  external int length;

  @Array.variable()
  external Array<Uint8> inlineArray;

  static Pointer<MyStruct> allocate(Allocator allocator, int length) {
    final lengthInBytes = sizeOf<MyStruct>() + sizeOf<Uint8>() * length;
    final result = allocator.allocate<MyStruct>(lengthInBytes);
    result.ref.length = length;
    return result;
  }
}

void main() {
  final myStruct = MyStruct.allocate(calloc, 10);
}

The variable length is always the outermost dimension of the array.

dart
import 'dart:ffi';
import 'package:ffi/ffi.dart';

final class MyStruct extends Struct {
  @Size()
  external int length;

  @Array.variable(10, 10)
  external Array<Array<Array<Uint8>>> inlineArray;

  static Pointer<MyStruct> allocate(Allocator allocator, int length) {
    final lengthInBytes = sizeOf<MyStruct>() + sizeOf<Uint8>() * length * 100;
    final result = allocator.allocate<MyStruct>(lengthInBytes);
    result.ref.length = length;
    return result;
  }
}

Accessing variable length inline arrays of structs passed by value in FFI calls and callbacks is undefined behavior. Accessing variable length inline arrays in structs passed by value is undefined behavior in C.

For more information about variable length inline arrays in C, please refer to: https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html.

Do not invoke in normal code.

Implementation
dart
@Since('3.6')
const factory Array.variable([
  int dimension2,
  int dimension3,
  int dimension4,
  int dimension5,
]) = _ArraySize<T>.variable;

Array.variableMulti() factory const ​

const factory Array.variableMulti(List<int> dimensions, {int variableDimension})

Annotation to a variable length Array in Structs.

dart
final class MyStruct extends Struct {
  @Array.variableMulti([2, 2])
  external Array<Array<Array<Uint8>>> threeDimensionalInlineArray;
}

final class MyStruct2 extends Struct {
  @Array.variableMulti(variableDimension: 1, [2, 2, 2])
  external Array<Array<Array<Array<Uint8>>>> fourDimensionalInlineArray;
}

final class MyStruct3 extends Struct {
  @Array.variableMulti([2, 2, 2, 2, 2, 2, 2])
  external Array<Array<Array<Array<Array<Array<Array<Array<Uint8>>>>>>>> eightDimensionalInlineArray;
}

The variable length is always the outermost dimension of the array.

variableDimension is the outermost dimension of the variable length array (defaults to zero (0)). When variableDimension is set to a value greater than zero (0), the last field of the struct is taken into account in sizeOf and AllocatorAlloc.call.

Do not invoke in normal code.

Implementation
dart
@Since('3.6')
const factory Array.variableMulti(
  List<int> dimensions, {
  @Since('3.7') int variableDimension,
}) = _ArraySize<T>.variableMulti;

Array.variableWithVariableDimension() factory const ​

const factory Array.variableWithVariableDimension([
  int dimension1,
  int dimension2,
  int dimension3,
  int dimension4,
  int dimension5,
])

Annotation to specify a variable length Array with a configurable variable dimension (dimension1) in Structs.

Can only be used on the last field of a struct. When dimension1 is set to a value greater than zero (0), the last field of the struct is taken into account in sizeOf and AllocatorAlloc.call. This is particularly useful when working with Windows APIs, where most structs with variable length arrays are defined to have an initial dimension of one (1).

dart
import 'dart:ffi';
import 'package:ffi/ffi.dart';

final class MyStruct extends Struct {
  @Size()
  external int length;

  @Array.variableWithVariableDimension(1)
  external Array<Uint8> inlineArray;

  static Pointer<MyStruct> allocate(Allocator allocator, int length) {
    final lengthInBytes = sizeOf<MyStruct>() + sizeOf<Uint8>() * (length - 1);
    final result = allocator.allocate<MyStruct>(lengthInBytes);
    result.ref.length = length;
    return result;
  }
}

void main() {
  final myStruct = MyStruct.allocate(calloc, 10);
}

The variable length is always the outermost dimension of the array.

Do not invoke in normal code.

Implementation
dart
@Since('3.7')
const factory Array.variableWithVariableDimension([
  int dimension1,
  int dimension2,
  int dimension3,
  int dimension4,
  int dimension5,
]) = _ArraySize<T>.variableWithVariableDimension;

Properties ​

address extension no setter ​

Pointer<T> get address

The memory address of the underlying data.

An expression of the form expression.address denoting this address can only occurr as an entire argument expression in the invocation of a leaf Native external function.

Example:

dart
@Native<Void Function(Pointer<Int8>)>(isLeaf: true)
external void myFunction(Pointer<Int8> pointer);

final class MyStruct extends Struct {
  @Array(10)
  external Array<Int8> array;
}

void main() {
  final array = Struct.create<MyStruct>().array;
  myFunction(array.address);
}

The expression before .address is evaluated like the left-hand-side of an assignment, to something that gives access to the storage behind the expression, which can be used both for reading and writing. The .address then gives a native pointer to that storage.

The .address is evaluated just before calling into native code when invoking a leaf Native external function. This ensures the Dart garbage collector will not move the object that the address points in to.

Available on Array<T extends NativeType>, provided by the ArrayAddress<T extends NativeType> extension

Implementation
dart
external Pointer<T> get address;

elements extension no setter ​

List<int> get elements

A list view of the bytes of this array.

Has the same length and elements (as accessed using the index operator) as this array, and writes to either the list or this arrary are visible in both.

Available on Array<T extends NativeType>, provided by the AbiSpecificIntegerArray<T extends AbiSpecificInteger> extension

Implementation
dart
@Since('3.8')
external List<int> get elements;

elements extension no setter ​

List<Array<T>> get elements

A list view of the bytes of this array.

Has the same length and elements (as accessed using the index operator) as this array, and writes to either the list or this arrary are visible in both.

Available on Array<T extends NativeType>, provided by the ArrayArray<T extends NativeType> extension

Implementation
dart
@Since('3.8')
external List<Array<T>> get elements;

elements extension no setter ​

List<bool> get elements

A list view of the bytes of this array.

Has the same length and elements (as accessed using the index operator) as this array, and writes to either the list or this arrary are visible in both.

Available on Array<T extends NativeType>, provided by the BoolArray extension

Implementation
dart
@Since('3.8')
external List<bool> get elements;

elements extension no setter ​

Float64List get elements

A list view of the bytes of this array.

Has the same length and elements (as accessed using the index operator) as this array, and writes to either the list or this arrary are visible in both.

Available on Array<T extends NativeType>, provided by the DoubleArray extension

Implementation
dart
@Since('3.8')
external Float64List get elements;

elements extension no setter ​

Float32List get elements

A list view of the bytes of this array.

Has the same length and elements (as accessed using the index operator) as this array, and writes to either the list or this arrary are visible in both.

Available on Array<T extends NativeType>, provided by the FloatArray extension

Implementation
dart
@Since('3.8')
external Float32List get elements;

elements extension no setter ​

Int8List get elements

A list view of the bytes of this array.

Has the same length and elements (as accessed using the index operator) as this array, and writes to either the list or this arrary are visible in both.

Available on Array<T extends NativeType>, provided by the Int8Array extension

Implementation
dart
@Since('3.8')
external Int8List get elements;

elements extension no setter ​

Int16List get elements

A list view of the bytes of this array.

Has the same length and elements (as accessed using the index operator) as this array, and writes to either the list or this arrary are visible in both.

Available on Array<T extends NativeType>, provided by the Int16Array extension

Implementation
dart
@Since('3.8')
external Int16List get elements;

elements extension no setter ​

Int32List get elements

A list view of the bytes of this array.

Has the same length and elements (as accessed using the index operator) as this array, and writes to either the list or this arrary are visible in both.

Available on Array<T extends NativeType>, provided by the Int32Array extension

Implementation
dart
@Since('3.8')
external Int32List get elements;

elements extension no setter ​

Int64List get elements

A list view of the bytes of this array.

Has the same length and elements (as accessed using the index operator) as this array, and writes to either the list or this arrary are visible in both.

Available on Array<T extends NativeType>, provided by the Int64Array extension

Implementation
dart
@Since('3.8')
external Int64List get elements;

elements extension no setter ​

List<Pointer<T>> get elements

A list view of the bytes of this array.

Has the same length and elements (as accessed using the index operator) as this array, and writes to either the list or this arrary are visible in both.

Available on Array<T extends NativeType>, provided by the PointerArray<T extends NativeType> extension

Implementation
dart
@Since('3.8')
external List<Pointer<T>> get elements;

elements extension no setter ​

List<T> get elements

A list view of the bytes of this array.

Has the same length and elements (as accessed using the index operator) as this array.

Available on Array<T extends NativeType>, provided by the StructArray<T extends Struct> extension

Implementation
dart
@Since('3.8')
external List<T> get elements;

elements extension no setter ​

Uint8List get elements

A list view of the bytes of this array.

Has the same length and elements (as accessed using the index operator) as this array, and writes to either the list or this arrary are visible in both.

Available on Array<T extends NativeType>, provided by the Uint8Array extension

Implementation
dart
@Since('3.8')
external Uint8List get elements;

elements extension no setter ​

Uint16List get elements

A list view of the bytes of this array.

Has the same length and elements (as accessed using the index operator) as this array, and writes to either the list or this arrary are visible in both.

Available on Array<T extends NativeType>, provided by the Uint16Array extension

Implementation
dart
@Since('3.8')
external Uint16List get elements;

elements extension no setter ​

Uint32List get elements

A list view of the bytes of this array.

Has the same length and elements (as accessed using the index operator) as this array, and writes to either the list or this arrary are visible in both.

Available on Array<T extends NativeType>, provided by the Uint32Array extension

Implementation
dart
@Since('3.8')
external Uint32List get elements;

elements extension no setter ​

Uint64List get elements

A list view of the bytes of this array.

Has the same length and elements (as accessed using the index operator) as this array, and writes to either the list or this arrary are visible in both.

Available on Array<T extends NativeType>, provided by the Uint64Array extension

Implementation
dart
@Since('3.8')
external Uint64List get elements;

elements extension no setter ​

List<T> get elements

A list view of the bytes of this array.

Has the same length and elements (as accessed using the index operator) as this array.

Available on Array<T extends NativeType>, provided by the UnionArray<T extends Union> extension

Implementation
dart
@Since('3.8')
external List<T> get elements;

hashCode no setter inherited ​

int get hashCode

The hash code for this object.

A hash code is a single integer which represents the state of the object that affects operator == comparisons.

All objects have hash codes. The default hash code implemented by Object represents only the identity of the object, the same way as the default operator == implementation only considers objects equal if they are identical (see identityHashCode).

If operator == is overridden to use the object state instead, the hash code must also be changed to represent that state, otherwise the object cannot be used in hash based data structures like the default Set and Map implementations.

Hash codes must be the same for objects that are equal to each other according to operator ==. The hash code of an object should only change if the object changes in a way that affects equality. There are no further requirements for the hash codes. They need not be consistent between executions of the same program and there are no distribution guarantees.

Objects that are not equal are allowed to have the same hash code. It is even technically allowed that all instances have the same hash code, but if clashes happen too often, it may reduce the efficiency of hash-based data structures like HashSet or HashMap.

If a subclass overrides hashCode, it should override the operator == operator as well to maintain consistency.

Inherited from Object.

Implementation
dart
external int get hashCode;

runtimeType no setter inherited ​

Type get runtimeType

A representation of the runtime type of the object.

Inherited from Object.

Implementation
dart
external Type get runtimeType;

Methods ​

noSuchMethod() inherited ​

dynamic noSuchMethod(Invocation invocation)

Invoked when a nonexistent method or property is accessed.

A dynamic member invocation can attempt to call a member which doesn't exist on the receiving object. Example:

dart
dynamic object = 1;
object.add(42); // Statically allowed, run-time error

This invalid code will invoke the noSuchMethod method of the integer 1 with an Invocation representing the .add(42) call and arguments (which then throws).

Classes can override noSuchMethod to provide custom behavior for such invalid dynamic invocations.

A class with a non-default noSuchMethod invocation can also omit implementations for members of its interface. Example:

dart
class MockList<T> implements List<T> {
  noSuchMethod(Invocation invocation) {
    log(invocation);
    super.noSuchMethod(invocation); // Will throw.
  }
}
void main() {
  MockList().add(42);
}

This code has no compile-time warnings or errors even though the MockList class has no concrete implementation of any of the List interface methods. Calls to List methods are forwarded to noSuchMethod, so this code will log an invocation similar to Invocation.method(#add, [42]) and then throw.

If a value is returned from noSuchMethod, it becomes the result of the original invocation. If the value is not of a type that can be returned by the original invocation, a type error occurs at the invocation.

The default behavior is to throw a NoSuchMethodError.

Inherited from Object.

Implementation
dart
@pragma("vm:entry-point")
@pragma("wasm:entry-point")
external dynamic noSuchMethod(Invocation invocation);

toString() inherited ​

String toString()

A string representation of this object.

Some classes have a default textual representation, often paired with a static parse function (like int.parse). These classes will provide the textual representation as their string representation.

Other classes have no meaningful textual representation that a program will care about. Such classes will typically override toString to provide useful information when inspecting the object, mainly for debugging or logging.

Inherited from Object.

Implementation
dart
external String toString();

Operators ​

operator ==() inherited ​

bool operator ==(Object other)

The equality operator.

The default behavior for all Objects is to return true if and only if this object and other are the same object.

Override this method to specify a different equality relation on a class. The overriding method must still be an equivalence relation. That is, it must be:

  • Total: It must return a boolean for all arguments. It should never throw.

  • Reflexive: For all objects o, o == o must be true.

  • Symmetric: For all objects o1 and o2, o1 == o2 and o2 == o1 must either both be true, or both be false.

  • Transitive: For all objects o1, o2, and o3, if o1 == o2 and o2 == o3 are true, then o1 == o3 must be true.

The method should also be consistent over time, so whether two objects are equal should only change if at least one of the objects was modified.

If a subclass overrides the equality operator, it should override the hashCode method as well to maintain consistency.

Inherited from Object.

Implementation
dart
external bool operator ==(Object other);

operator extension ​

int operator [](int index)

Loads a Dart value from this array at index.

This extension method must be invoked on a receiver of type Array<T> where T is a compile-time constant type.

Available on Array<T extends NativeType>, provided by the AbiSpecificIntegerArray<T extends AbiSpecificInteger> extension

Implementation
dart
external int operator [](int index);

operator extension ​

Array<T> operator [](int index)

Available on Array<T extends NativeType>, provided by the ArrayArray<T extends NativeType> extension

Implementation
dart
external Array<T> operator [](int index);

operator extension ​

bool operator [](int index)

Loads a Dart value from this array at index.

This extension method must be invoked on a receiver of type Array<T> where T is a compile-time constant type.

Available on Array<T extends NativeType>, provided by the BoolArray extension

Implementation
dart
external bool operator [](int index);

operator extension ​

double operator [](int index)

Loads a Dart value from this array at index.

This extension method must be invoked on a receiver of type Array<T> where T is a compile-time constant type.

Available on Array<T extends NativeType>, provided by the DoubleArray extension

Implementation
dart
external double operator [](int index);

operator extension ​

double operator [](int index)

Loads a Dart value from this array at index.

This extension method must be invoked on a receiver of type Array<T> where T is a compile-time constant type.

Available on Array<T extends NativeType>, provided by the FloatArray extension

Implementation
dart
external double operator [](int index);

operator extension ​

int operator [](int index)

Loads a Dart value from this array at index.

This extension method must be invoked on a receiver of type Array<T> where T is a compile-time constant type.

Available on Array<T extends NativeType>, provided by the Int8Array extension

Implementation
dart
external int operator [](int index);

operator extension ​

int operator [](int index)

Loads a Dart value from this array at index.

This extension method must be invoked on a receiver of type Array<T> where T is a compile-time constant type.

Available on Array<T extends NativeType>, provided by the Int16Array extension

Implementation
dart
external int operator [](int index);

operator extension ​

int operator [](int index)

Loads a Dart value from this array at index.

This extension method must be invoked on a receiver of type Array<T> where T is a compile-time constant type.

Available on Array<T extends NativeType>, provided by the Int32Array extension

Implementation
dart
external int operator [](int index);

operator extension ​

int operator [](int index)

Loads a Dart value from this array at index.

This extension method must be invoked on a receiver of type Array<T> where T is a compile-time constant type.

Available on Array<T extends NativeType>, provided by the Int64Array extension

Implementation
dart
external int operator [](int index);

operator extension ​

Pointer<T> operator [](int index)

Loads a Dart value from this array at index.

This extension method must be invoked on a receiver of type Array<T> where T is a compile-time constant type.

Available on Array<T extends NativeType>, provided by the PointerArray<T extends NativeType> extension

Implementation
dart
external Pointer<T> operator [](int index);

operator extension ​

T operator [](int index)

This extension method must be invoked on a receiver of type Pointer<T> where T is a compile-time constant type.

Available on Array<T extends NativeType>, provided by the StructArray<T extends Struct> extension

Implementation
dart
external T operator [](int index);

operator extension ​

int operator [](int index)

Loads a Dart value from this array at index.

This extension method must be invoked on a receiver of type Array<T> where T is a compile-time constant type.

Available on Array<T extends NativeType>, provided by the Uint8Array extension

Implementation
dart
external int operator [](int index);

operator extension ​

int operator [](int index)

Loads a Dart value from this array at index.

This extension method must be invoked on a receiver of type Array<T> where T is a compile-time constant type.

Available on Array<T extends NativeType>, provided by the Uint16Array extension

Implementation
dart
external int operator [](int index);

operator extension ​

int operator [](int index)

Loads a Dart value from this array at index.

This extension method must be invoked on a receiver of type Array<T> where T is a compile-time constant type.

Available on Array<T extends NativeType>, provided by the Uint32Array extension

Implementation
dart
external int operator [](int index);

operator extension ​

int operator [](int index)

Loads a Dart value from this array at index.

This extension method must be invoked on a receiver of type Array<T> where T is a compile-time constant type.

Available on Array<T extends NativeType>, provided by the Uint64Array extension

Implementation
dart
external int operator [](int index);

operator extension ​

T operator [](int index)

This extension method must be invoked on a receiver of type Pointer<T> where T is a compile-time constant type.

Available on Array<T extends NativeType>, provided by the UnionArray<T extends Union> extension

Implementation
dart
external T operator [](int index);

operator []=() extension ​

void operator []=(int index, int value)

Stores a Dart value in this array at index.

This extension method must be invoked on a receiver of type Array<T> where T is a compile-time constant type.

Available on Array<T extends NativeType>, provided by the AbiSpecificIntegerArray<T extends AbiSpecificInteger> extension

Implementation
dart
external void operator []=(int index, int value);

operator []=() extension ​

void operator []=(int index, Array<T> value)

Available on Array<T extends NativeType>, provided by the ArrayArray<T extends NativeType> extension

Implementation
dart
external void operator []=(int index, Array<T> value);

operator []=() extension ​

void operator []=(int index, bool value)

Stores a Dart value in this array at index.

This extension method must be invoked on a receiver of type Array<T> where T is a compile-time constant type.

Available on Array<T extends NativeType>, provided by the BoolArray extension

Implementation
dart
external void operator []=(int index, bool value);

operator []=() extension ​

void operator []=(int index, double value)

Stores a Dart value in this array at index.

This extension method must be invoked on a receiver of type Array<T> where T is a compile-time constant type.

Available on Array<T extends NativeType>, provided by the DoubleArray extension

Implementation
dart
external void operator []=(int index, double value);

operator []=() extension ​

void operator []=(int index, double value)

Stores a Dart value in this array at index.

This extension method must be invoked on a receiver of type Array<T> where T is a compile-time constant type.

Available on Array<T extends NativeType>, provided by the FloatArray extension

Implementation
dart
external void operator []=(int index, double value);

operator []=() extension ​

void operator []=(int index, int value)

Stores a Dart value in this array at index.

This extension method must be invoked on a receiver of type Array<T> where T is a compile-time constant type.

Available on Array<T extends NativeType>, provided by the Int8Array extension

Implementation
dart
external void operator []=(int index, int value);

operator []=() extension ​

void operator []=(int index, int value)

Stores a Dart value in this array at index.

This extension method must be invoked on a receiver of type Array<T> where T is a compile-time constant type.

Available on Array<T extends NativeType>, provided by the Int16Array extension

Implementation
dart
external void operator []=(int index, int value);

operator []=() extension ​

void operator []=(int index, int value)

Stores a Dart value in this array at index.

This extension method must be invoked on a receiver of type Array<T> where T is a compile-time constant type.

Available on Array<T extends NativeType>, provided by the Int32Array extension

Implementation
dart
external void operator []=(int index, int value);

operator []=() extension ​

void operator []=(int index, int value)

Stores a Dart value in this array at index.

This extension method must be invoked on a receiver of type Array<T> where T is a compile-time constant type.

Available on Array<T extends NativeType>, provided by the Int64Array extension

Implementation
dart
external void operator []=(int index, int value);

operator []=() extension ​

void operator []=(int index, Pointer<T> value)

Stores a Dart value in this array at index.

This extension method must be invoked on a receiver of type Array<T> where T is a compile-time constant type.

Available on Array<T extends NativeType>, provided by the PointerArray<T extends NativeType> extension

Implementation
dart
external void operator []=(int index, Pointer<T> value);

operator []=() extension ​

void operator []=(int index, int value)

Stores a Dart value in this array at index.

This extension method must be invoked on a receiver of type Array<T> where T is a compile-time constant type.

Available on Array<T extends NativeType>, provided by the Uint8Array extension

Implementation
dart
external void operator []=(int index, int value);

operator []=() extension ​

void operator []=(int index, int value)

Stores a Dart value in this array at index.

This extension method must be invoked on a receiver of type Array<T> where T is a compile-time constant type.

Available on Array<T extends NativeType>, provided by the Uint16Array extension

Implementation
dart
external void operator []=(int index, int value);

operator []=() extension ​

void operator []=(int index, int value)

Stores a Dart value in this array at index.

This extension method must be invoked on a receiver of type Array<T> where T is a compile-time constant type.

Available on Array<T extends NativeType>, provided by the Uint32Array extension

Implementation
dart
external void operator []=(int index, int value);

operator []=() extension ​

void operator []=(int index, int value)

Stores a Dart value in this array at index.

This extension method must be invoked on a receiver of type Array<T> where T is a compile-time constant type.

Available on Array<T extends NativeType>, provided by the Uint64Array extension

Implementation
dart
external void operator []=(int index, int value);