Array<T extends NativeType> final#

Annotations: @Since.new('2.13')

A fixed-sized array of Ts.

Constructors#

Array() factory const#

Annotation to specify Array dimensions in Structs.

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.

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

Array.multi() factory const#

Annotation to specify Array dimensions in Structs.

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.

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

Array.variable() factory const#

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.

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.

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.

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

Array.variableMulti() factory const#

Annotation to a variable length Array in Structs.

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.

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

Array.variableWithVariableDimension() factory const#

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

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.

@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#

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:

@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

external Pointer<T> get address;

elements extension no setter#

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

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

elements extension no setter#

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

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

elements extension no setter#

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

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

elements extension no setter#

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

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

elements extension no setter#

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

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

elements extension no setter#

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

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

elements extension no setter#

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

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

elements extension no setter#

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

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

elements extension no setter#

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

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

elements extension no setter#

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

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

elements extension no setter#

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

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

elements extension no setter#

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

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

elements extension no setter#

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

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

elements extension no setter#

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

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

elements extension no setter#

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

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

elements extension no setter#

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

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

hashCode no setter inherited#

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.

external int get hashCode;

runtimeType no setter inherited#

A representation of the runtime type of the object.

Inherited from Object.

external Type get runtimeType;

Methods#

noSuchMethod() inherited#

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:

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:

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.

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

toString() inherited#

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.

external String toString();

Operators#

operator ==() inherited#

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.

external bool operator ==(Object other);

operator []() extension#

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

external int operator [](int index);

operator []() extension#

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

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

operator []() extension#

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

external bool operator [](int index);

operator []() extension#

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

external double operator [](int index);

operator []() extension#

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

external double operator [](int index);

operator []() extension#

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

external int operator [](int index);

operator []() extension#

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

external int operator [](int index);

operator []() extension#

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

external int operator [](int index);

operator []() extension#

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

external int operator [](int index);

operator []() extension#

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

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

operator []() extension#

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

external T operator [](int index);

operator []() extension#

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

external int operator [](int index);

operator []() extension#

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

external int operator [](int index);

operator []() extension#

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

external int operator [](int index);

operator []() extension#

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

external int operator [](int index);

operator []() extension#

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

external T operator [](int index);

operator []=() extension#

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

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

operator []=() extension#

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

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

operator []=() extension#

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

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

operator []=() extension#

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

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

operator []=() extension#

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

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

operator []=() extension#

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

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

operator []=() extension#

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

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

operator []=() extension#

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

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

operator []=() extension#

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

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

operator []=() extension#

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

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

operator []=() extension#

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

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

operator []=() extension#

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

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

operator []=() extension#

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

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

operator []=() extension#

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

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