ByteData abstract final

abstract final class ByteData implements TypedData

A fixed-length, random-access sequence of bytes that also provides random and unaligned access to the fixed-width integers and floating point numbers represented by those bytes.

ByteData may be used to pack and unpack data from external sources (such as networks or files systems), and to process large quantities of numerical data more efficiently than would be possible with ordinary List implementations. ByteData can save space, by eliminating the need for object headers, and time, by eliminating the need for data copies.

If data comes in as bytes, they can be converted to ByteData by sharing the same buffer.

Uint8List bytes = ...;
var blob = ByteData.sublistView(bytes);
if (blob.getUint32(0, Endian.little) == 0x04034b50) { // Zip file marker
  ...
}

Finally, ByteData may be used to intentionally reinterpret the bytes representing one arithmetic type as another. For example this code fragment determine what 32-bit signed integer is represented by the bytes of a 32-bit floating point number (both stored as big endian):

var bdata = ByteData(8);
bdata.setFloat32(0, 3.04);
int huh = bdata.getInt32(0); // 0x40428f5c

It is a compile-time error for a class to attempt to extend or implement ByteData.

Implemented types

• TypedData

Available Extensions

• ByteDataToJSDataView

Constructors

ByteData() factory

factory ByteData(int length)

Creates a ByteData of the specified length (in elements), all of whose bytes are initially zero.

Implementation

@pragma("vm:entry-point")
external factory ByteData(int length);

ByteData.sublistView() factory

factory ByteData.sublistView(TypedData data, [int start = 0, int? end])

Creates a ByteData view on a range of elements of data.

Creates a view on the range of data.buffer which corresponds to the elements of data from start until end. If data is a typed data list, like Uint16List, then the view is on the bytes of the elements with indices from start until end. If data is a ByteData, it's treated like a list of bytes.

If provided, start and end must satisfy

0 ≤ start ≤ end ≤ elementCount

where elementCount is the number of elements in data, which is the same as the List.length of a typed data list.

If omitted, start defaults to zero and end to elementCount.

Implementation

factory ByteData.sublistView(TypedData data, [int start = 0, int? end]) {
  int elementSize = data.elementSizeInBytes;
  end = RangeError.checkValidRange(
    start,
    end,
    data.lengthInBytes ~/ elementSize,
  );
  return data.buffer.asByteData(
    data.offsetInBytes + start * elementSize,
    (end - start) * elementSize,
  );
}

ByteData.view() factory

factory ByteData.view(ByteBuffer buffer, [int offsetInBytes = 0, int? length])

Creates an ByteData view of the specified region in buffer.

Changes in the ByteData will be visible in the byte buffer and vice versa. If the offsetInBytes index of the region is not specified, it defaults to zero (the first byte in the byte buffer). If the length is not provided, the view extends to the end of the byte buffer.

The offsetInBytes and length must be non-negative, and offsetInBytes + length must be less than or equal to the length of buffer.

Note that when creating a view from a TypedData list or byte data, that list or byte data may itself be a view on a larger buffer with a TypedData.offsetInBytes greater than zero. Merely doing ByteData.view(other.buffer, 0, count) may not point to the bytes you intended. Instead you may need to do:

ByteData.view(other.buffer, other.offsetInBytes, count)

Alternatively, use ByteData.sublistView which includes this computation:

ByteData.sublistView(other, 0, count);

(The third argument is an end index rather than a length, so if you start from a position greater than zero, you need not reduce the count correspondingly).

Implementation

factory ByteData.view(
  ByteBuffer buffer, [
  int offsetInBytes = 0,
  int? length,
]) {
  return buffer.asByteData(offsetInBytes, length);
}

Properties

buffer no setter inherited

ByteBuffer get buffer

The byte buffer associated with this object.

Inherited from TypedData.

Implementation

ByteBuffer get buffer;

elementSizeInBytes no setter inherited

int get elementSizeInBytes

The number of bytes in the representation of each element in this list.

Inherited from TypedData.

Implementation

int get elementSizeInBytes;

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

external int get hashCode;

lengthInBytes no setter inherited

int get lengthInBytes

The length of this view, in bytes.

Inherited from TypedData.

Implementation

int get lengthInBytes;

offsetInBytes no setter inherited

int get offsetInBytes

The offset of this view into the underlying byte buffer, in bytes.

Inherited from TypedData.

Implementation

int get offsetInBytes;

runtimeType no setter inherited

Type get runtimeType

A representation of the runtime type of the object.

Inherited from Object.

Implementation

external Type get runtimeType;

toJS extension no setter

JSDataView get toJS

Converts this ByteData to a JSDataView by either casting, unwrapping, or cloning the ByteData.

INFO

Depending on whether code is compiled to JavaScript or Wasm, this conversion will have different semantics.

When compiling to JavaScript, all typed lists are the equivalent JavaScript typed arrays, and therefore this getter simply casts.

When compiling to Wasm, this ByteData is a wrapper around a DataView if it was converted via JSDataViewToByteData.toDart. If it is a wrapper, this getter unwraps it and returns the DataView. If it's instantiated in Dart, this getter clones this ByteData's values into a new JSDataView.

Avoid assuming that modifications to this ByteData will affect the returned JSDataView and vice versa on all compilers unless it was first converted via JSDataViewToByteData.toDart.

Available on ByteData, provided by the ByteDataToJSDataView extension

Implementation

external JSDataView get toJS;

Methods

asUnmodifiableView()

ByteData asUnmodifiableView()

A read-only view of this ByteData.

Implementation

@Since("3.3")
ByteData asUnmodifiableView();

getFloat32()

double getFloat32(int byteOffset, [Endian endian = Endian.big])

The floating point number represented by the four bytes at the specified byteOffset in this object, in IEEE 754 single-precision binary floating-point format (binary32).

The byteOffset must be non-negative, and byteOffset + 4 must be less than or equal to the length of this object.

Implementation

double getFloat32(int byteOffset, [Endian endian = Endian.big]);

getFloat64()

double getFloat64(int byteOffset, [Endian endian = Endian.big])

The floating point number represented by the eight bytes at the specified byteOffset in this object, in IEEE 754 double-precision binary floating-point format (binary64).

The byteOffset must be non-negative, and byteOffset + 8 must be less than or equal to the length of this object.

Implementation

double getFloat64(int byteOffset, [Endian endian = Endian.big]);

getInt16()

int getInt16(int byteOffset, [Endian endian = Endian.big])

The (possibly negative) integer represented by the two bytes at the specified byteOffset in this object, in two's complement binary form.

The return value will be between -2¹⁵ and 2¹⁵ - 1, inclusive.

The byteOffset must be non-negative, and byteOffset + 2 must be less than or equal to the length of this object.

Implementation

int getInt16(int byteOffset, [Endian endian = Endian.big]);

getInt32()

int getInt32(int byteOffset, [Endian endian = Endian.big])

The (possibly negative) integer represented by the four bytes at the specified byteOffset in this object, in two's complement binary form.

The return value will be between -2³¹ and 2³¹ - 1, inclusive.

The byteOffset must be non-negative, and byteOffset + 4 must be less than or equal to the length of this object.

Implementation

int getInt32(int byteOffset, [Endian endian = Endian.big]);

getInt64()

int getInt64(int byteOffset, [Endian endian = Endian.big])

The (possibly negative) integer represented by the eight bytes at the specified byteOffset in this object, in two's complement binary form.

The return value will be between -2⁶³ and 2⁶³ - 1, inclusive.

The byteOffset must be non-negative, and byteOffset + 8 must be less than or equal to the length of this object.

Implementation

int getInt64(int byteOffset, [Endian endian = Endian.big]);

getInt8()

int getInt8(int byteOffset)

The (possibly negative) integer represented by the byte at the specified byteOffset in this object, in two's complement binary representation.

The return value will be between -128 and 127, inclusive.

The byteOffset must be non-negative, and less than the length of this object.

Implementation

int getInt8(int byteOffset);

getUint16()

int getUint16(int byteOffset, [Endian endian = Endian.big])

The positive integer represented by the two bytes starting at the specified byteOffset in this object, in unsigned binary form.

The return value will be between 0 and 2¹⁶ - 1, inclusive.

The byteOffset must be non-negative, and byteOffset + 2 must be less than or equal to the length of this object.

Implementation

int getUint16(int byteOffset, [Endian endian = Endian.big]);

getUint32()

int getUint32(int byteOffset, [Endian endian = Endian.big])

The positive integer represented by the four bytes starting at the specified byteOffset in this object, in unsigned binary form.

The return value will be between 0 and 2³² - 1, inclusive.

The byteOffset must be non-negative, and byteOffset + 4 must be less than or equal to the length of this object.

Implementation

int getUint32(int byteOffset, [Endian endian = Endian.big]);

getUint64()

int getUint64(int byteOffset, [Endian endian = Endian.big])

The positive integer represented by the eight bytes starting at the specified byteOffset in this object, in unsigned binary form.

The return value will be between 0 and 2⁶⁴ - 1, inclusive.

The byteOffset must be non-negative, and byteOffset + 8 must be less than or equal to the length of this object.

Implementation

int getUint64(int byteOffset, [Endian endian = Endian.big]);

getUint8()

int getUint8(int byteOffset)

The positive integer represented by the byte at the specified byteOffset in this object, in unsigned binary form.

The return value will be between 0 and 255, inclusive.

The byteOffset must be non-negative, and less than the length of this object.

Implementation

int getUint8(int byteOffset);

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:

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.

Implementation

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

setFloat32()

void setFloat32(int byteOffset, double value, [Endian endian = Endian.big])

Sets the four bytes starting at the specified byteOffset in this object to the IEEE 754 single-precision binary floating-point (binary32) representation of the specified value.

Note that this method can lose precision. The input value is a 64-bit floating point value, which will be converted to 32-bit floating point value by IEEE 754 rounding rules before it is stored. If value cannot be represented exactly as a binary32, it will be converted to the nearest binary32 value. If two binary32 values are equally close, the one whose least significant bit is zero will be used. Note that finite (but large) values can be converted to infinity, and small non-zero values can be converted to zero.

The byteOffset must be non-negative, and byteOffset + 4 must be less than or equal to the length of this object.

Implementation

void setFloat32(int byteOffset, double value, [Endian endian = Endian.big]);

setFloat64()

void setFloat64(int byteOffset, double value, [Endian endian = Endian.big])

Sets the eight bytes starting at the specified byteOffset in this object to the IEEE 754 double-precision binary floating-point (binary64) representation of the specified value.

The byteOffset must be non-negative, and byteOffset + 8 must be less than or equal to the length of this object.

Implementation

void setFloat64(int byteOffset, double value, [Endian endian = Endian.big]);

setInt16()

void setInt16(int byteOffset, int value, [Endian endian = Endian.big])

Sets the two bytes starting at the specified byteOffset in this object to the two's complement binary representation of the specified value, which must fit in two bytes.

In other words, value must lie between -2¹⁵ and 2¹⁵ - 1, inclusive.

The byteOffset must be non-negative, and byteOffset + 2 must be less than or equal to the length of this object.

Implementation

void setInt16(int byteOffset, int value, [Endian endian = Endian.big]);

setInt32()

void setInt32(int byteOffset, int value, [Endian endian = Endian.big])

Sets the four bytes starting at the specified byteOffset in this object to the two's complement binary representation of the specified value, which must fit in four bytes.

In other words, value must lie between -2³¹ and 2³¹ - 1, inclusive.

The byteOffset must be non-negative, and byteOffset + 4 must be less than or equal to the length of this object.

Implementation

void setInt32(int byteOffset, int value, [Endian endian = Endian.big]);

setInt64()

void setInt64(int byteOffset, int value, [Endian endian = Endian.big])

Sets the eight bytes starting at the specified byteOffset in this object to the two's complement binary representation of the specified value, which must fit in eight bytes.

In other words, value must lie between -2⁶³ and 2⁶³ - 1, inclusive.

The byteOffset must be non-negative, and byteOffset + 8 must be less than or equal to the length of this object.

Implementation

void setInt64(int byteOffset, int value, [Endian endian = Endian.big]);

setInt8()

void setInt8(int byteOffset, int value)

Sets the byte at the specified byteOffset in this object to the two's complement binary representation of the specified value, which must fit in a single byte.

In other words, value must be between -128 and 127, inclusive.

The byteOffset must be non-negative, and less than the length of this object.

Implementation

void setInt8(int byteOffset, int value);

setUint16()

void setUint16(int byteOffset, int value, [Endian endian = Endian.big])

Sets the two bytes starting at the specified byteOffset in this object to the unsigned binary representation of the specified value, which must fit in two bytes.

In other words, value must be between 0 and 2¹⁶ - 1, inclusive.

The byteOffset must be non-negative, and byteOffset + 2 must be less than or equal to the length of this object.

Implementation

void setUint16(int byteOffset, int value, [Endian endian = Endian.big]);

setUint32()

void setUint32(int byteOffset, int value, [Endian endian = Endian.big])

Sets the four bytes starting at the specified byteOffset in this object to the unsigned binary representation of the specified value, which must fit in four bytes.

In other words, value must be between 0 and 2³² - 1, inclusive.

The byteOffset must be non-negative, and byteOffset + 4 must be less than or equal to the length of this object.

Implementation

void setUint32(int byteOffset, int value, [Endian endian = Endian.big]);

setUint64()

void setUint64(int byteOffset, int value, [Endian endian = Endian.big])

Sets the eight bytes starting at the specified byteOffset in this object to the unsigned binary representation of the specified value, which must fit in eight bytes.

In other words, value must be between 0 and 2⁶⁴ - 1, inclusive.

The byteOffset must be non-negative, and byteOffset + 8 must be less than or equal to the length of this object.

Implementation

void setUint64(int byteOffset, int value, [Endian endian = Endian.big]);

setUint8()

void setUint8(int byteOffset, int value)

Sets the byte at the specified byteOffset in this object to the unsigned binary representation of the specified value, which must fit in a single byte.

In other words, value must be between 0 and 255, inclusive.

The byteOffset must be non-negative, and less than the length of this object.

Implementation

void setUint8(int byteOffset, int value);

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

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

external bool operator ==(Object other);