Toit
Libraries
bignum
binary
bitmap
ble
bytes
core
crypto
device
encoding
esp32
expect
fixed-point
flash
font
gpio
i2c
i2s
icons
io
line-wrap
log
math
monitor
net
pulse-counter
reader
reader-writer
rmt
serial
spi
statistics
system
tls
uart
uuid
writer
zlib

Interface ByteArray

extends Data implements Data
A container specialized for bytes.
A byte array can only contain (non-null) integers in the range 0-255. When storing other integer values, they are automatically truncated.
Byte arrays can be created using the ByteArray constructors, or by using the byte array literal syntax: #[1, 2, 3]. If the latter only contains constants, it is compiled such that access to the byte array doesn't need the dynamic creation of the byte array. On many platforms this requires less memory. These literals are still mutable and will copy their content into memory the first time they are modified ("Copy on Write").
Examples

bytes := #[1, 2, 3]
bytes[0] = 22
print bytes  // => [22, 2, 3]

bytes += #[4, 5]
print bytes  // => [22, 2, 3, 4, 5]

bytes := ByteArray 4: it
print bytes  // => [0, 1, 2, 3]

Interface summary

constructor size/int --filler/int
Creates a new byte array of the given size.
constructor size/int --initial/int=
Creates a new byte array of the given size.
constructor size/int [initializer]
Creates a new byte array of the given size and initializes the elements using the provided initializer.

Constructors

constructor size/int --filler/int
Creates a new byte array of the given size.
All elements are initialized to the filler, which defaults to 0.
Deprecated. Use constructor size --initial instead.
constructor size/int --initial/int=0
Creates a new byte array of the given size.
All elements are initialized to the initial value, which defaults to 0.
constructor size/int [initializer]
Creates a new byte array of the given size and initializes the elements using the provided initializer.
The initializer is invoked for each element, receiving the index as argument.

Statics

external size/int -> ByteArray
Constructs a byte array where the data is not on the Toit heap.
The byte array's backing store is allocated using 'malloc' and is thus not located on the Toit heap. This has the following consequences:
  • The garbage collector can't move the data, which can lead to fragmentation.
  • External byte arrays can be handed over to the system. The system would
  • then "neuter" the byte array, rendering it unusable in Toit. This can
  • be useful for performance reasons, as can sometimes avoid copying the data.
  • Only few functions neuter byte arrays and typically only on request.
External byte arrays are not automatically faster than normal byte arrays. Unless you know what you are doing or have a specific use-case in mind, you should use normal byte arrays.
Note: bigger byte arrays are always external, even if allocated using the normal constructor size.
from bytes/Data from/int=0 to/int=bytes.byte-size -> ByteArray
Creates a new byte array from the given bytes.

Methods

any [predicate] -> bool
Whether there is at least one byte that satisfies the given predicate.
Returns false, if the byte array is empty.
byte-at index/int -> int
Returns the byte at the given index.
byte-size -> int
The amount of bytes that can be produced.
byte-slice from/int to/int -> Data
Returns a slice of this data.
copy from/int=0 to/int=size -> ByteArray
Creates a copy of a slice of this instance.
The arguments from and to must satisfy: 0 <= from <= to <= size.
do [block] -> none
Invokes the given block on each byte of this instance.
do --reversed/True [block] -> none
Iterates over all bytes in reverse order and invokes the given block on each of them.
every [predicate] -> bool
Whether all bytes satisfy the given predicate.
Returns true, if the byte array is empty.
fill --from/int=0 --to/int=size value/any -> any
Fills value into list elements [from..to[.
fill --from/int=0 --to/int=size [block] -> any
Fills values, computed by evaluating block, into list elements [from..to[.
first -> int
The first element of this instance.
The byte array must not be empty.
hash-code -> int
Returns a hash code that depends on the content of this ByteArray.
index-of byte/int --from/int=0 --to/int=size -> int
Returns the index of the first occurrence of the byte.
Returns -1 otherwise.
is-empty -> bool
Whether this instance is empty.
is-valid-string-content from/int=0 to/int=size -> bool
Whether this instance has a valid UTF-8 string content in the range from-to.
last -> int
The last element of this instance.
The byte array must not be empty.
operator [..] --from/int=0 --to/int=size -> ByteArray
Returns a slice of this byte array.
Slices are views on the underlying object. As such they see and modify the object they come from.
The parameter from is inclusive.
The parameter to is exclusive.
Advanced
Slices keep the whole underlying object alive. This can lead to memory waste if the underlying object is not used otherwise. In some cases it might thus make sense to call copy on the slice.
At the call-site the arguments from and to are passed in with the slice syntax: list[from..to]. Since both arguments are optional (as they have default values), it is valid to omit from or to.
Examples

bytes := #[1, 2, 3, 4, 5]
sub := bytes[1..3] // A view into [2, 3]
sub[0] = 22
print bytes  // => [1, 22, 3, 4, 5]
operator [] n/int -> int
Returns the n'th byte.
operator []= n/int value/int -> int
Sets the n'th byte to value.
The value is truncated to byte size if necessary, only using the least-significant 8 bits.
operator + other/ByteArray -> ByteArray
Concatenates this instance with other.
operator == other/any -> bool
Compares this instance to other.
Returns whether the other instance is a ByteArray with the same content.
replace index/int source/Data from/int=0 to/int=source.size -> none
Replaces this[index..index+(to-from)[ with source[from..to[
reverse --in-place/True -> none
Reverses the order of the bytes in this instance.
reverse -> ByteArray
Returns a copy of this instance with the order of the bytes reversed.
size -> int
The number of bytes in this instance.
to-float from/int --big-endian/bool=true -> float
Deprecated. Use io.ByteOrder.float64 instead.
to-string from/int=0 to/int=size -> string
Converts this instance to a string, interpreting its bytes as UTF-8.
to-string-non-throwing from/any=0 to/any=size -> string
Converts the UTF-8 byte array to a string.
Invalid UTF-8 sequences are replaced with the Unicode replacement character, \uFFFD.
write-to-byte-array byte-array/ByteArray --at/int from/int to/int -> none