data_array

data_array

`data_array` stores raw bytes. Use it when Expr code needs binary data, image raw pixels, base64 data, or packed numeric values.

A `data_array` is cloneable. `clone()` returns a separate copy of the byte buffer.

Constructor

data_array()

Creates an empty byte array.

data = data_array();
data.size();        // 0

data_array(size)

Creates a byte array with `size` bytes initialized to zero.

Arguments:

Argument	Description
`size`	Initial byte count. Negative values are treated as 0.

data = data_array(4);
data.to_hex();      // "00000000"

Size and State

Method	Returns	Description
`size()`	number	Number of bytes.
`count()`	number	Same as `size()`.
`empty()`	boolean	`true` when the array has no bytes.
`clear()`	boolean	Removes all bytes and returns `true`.
`resize(size)`	number	Resizes the buffer and returns the new size. New bytes are zero.

data = data_array();
data.resize(3);
print(data.size());

Raw Byte Access

get(index)

Returns the byte at `index` as a number. If `index` is outside the buffer, it returns `none()`.

data = data_array();
data.add(65);
print(data.get(0));     // 65

get(index, count)

Returns a new `data_array` containing up to `count` bytes starting at `index`. If the range is outside the buffer, an empty `data_array` is returned.

data = data_array();
data.add_string("ABCDEF");
part = data.get(1, 3);
print(part.get_string(0));   // BCD

set(index, value)

Writes one byte at `index`, or writes all bytes from another `data_array`. Writing past the end grows the buffer and fills gaps with zero bytes.

Arguments:

Argument	Description
`index`	Byte position. Negative values are treated as 0.
`value`	Byte value, or another `data_array`.

data = data_array();
data.set(2, 255);
print(data.to_hex());        // 0000ff

add(value)

Appends one byte, or appends all bytes from another `data_array`.

data = data_array();
data.add(65);
data.add(66);
print(data.get_string(0));   // AB

insert(index) / insert(index, count)

Inserts zero bytes. With one argument it inserts one byte. With two arguments it inserts `count` zero bytes.

data = data_array();
data.add_string("AC");
data.insert(1);
data.set(1, 66);
print(data.get_string(0));   // ABC

erase(index) / erase(index, count)

Removes bytes. With one argument it removes one byte. With two arguments it removes up to `count` bytes.

data = data_array();
data.add_string("ABCD");
data.erase(1, 2);
print(data.get_string(0));   // AD

Strings

Method	Returns	Description
`get_string(index)`	string	Returns text from `index` to the end.
`get_string(index, count)`	string	Returns up to `count` bytes as text.
`set_string(index, text)`	boolean	Writes string bytes at `index`. Grows the buffer if needed.
`add_string(text)`	boolean	Appends string bytes.

data = data_array();
data.add_string("HELLO");
print(data.get_string(1, 3));    // ELL

Typed Numeric Access

Typed methods read, write, and append packed numeric values.

Type	Read	Write	Append	Bytes
signed 8-bit	`get_s8(index)`	`set_s8(index, value)`	`add_s8(value)`	1
unsigned 8-bit	`get_u8(index)`	`set_u8(index, value)`	`add_u8(value)`	1
signed 16-bit	`get_s16(index[, littleEndian])`	`set_s16(index, value[, littleEndian])`	`add_s16(value[, littleEndian])`	2
unsigned 16-bit	`get_u16(index[, littleEndian])`	`set_u16(index, value[, littleEndian])`	`add_u16(value[, littleEndian])`	2
signed 32-bit	`get_s32(index[, littleEndian])`	`set_s32(index, value[, littleEndian])`	`add_s32(value[, littleEndian])`	4
signed 32-bit alias	`get_s3(index[, littleEndian])`	`set_s3(index, value[, littleEndian])`	`add_s3(value[, littleEndian])`	4
unsigned 32-bit	`get_u32(index[, littleEndian])`	`set_u32(index, value[, littleEndian])`	`add_u32(value[, littleEndian])`	4
float	`get_float(index[, littleEndian])`	`set_float(index, value[, littleEndian])`	`add_float(value[, littleEndian])`	4
double	`get_double(index[, littleEndian])`	`set_double(index, value[, littleEndian])`	`add_double(value[, littleEndian])`	8

`littleEndian` defaults to `true`. If a typed read does not have enough bytes, it returns `none()`.

data = data_array();
data.add_u16(4660);       // 0x1234, little-endian by default
print(data.to_hex());     // 3412
print(data.get_u16(0));   // 4660

Encoding and Search

to_hex()

Returns the buffer as lowercase hexadecimal text.

data = data_array();
data.add_string("A");
print(data.to_hex());     // 41

to_base64()

Returns the buffer encoded as base64.

data = data_array();
data.add_string("ABC");
encoded = data.to_base64();

from_base64(text)

Replaces the buffer with decoded base64 data and returns the decoded byte count.

data = data_array();
count = data.from_base64("QUJD");
print(data.get_string(0));    // ABC

find(value)

Searches for a byte, string, or another `data_array`. Returns the first byte index, `-1` when not found, or `none()` for unsupported argument types.

data = data_array();
data.add_string("ABCDEF");
print(data.find("CD"));       // 2
print(data.find(70));         // 5

Previous: map

Next: image_data

Table of Contents