Table of Contents

bytes

`bytes` is a mutable byte buffer.

Use it when Expr code needs binary data, image raw pixels, base64 data, packed numeric values, or serial/crypto payloads. Use `array()` for normal Expr values.

Constructor

bytes()

Creates an empty byte buffer.

Item Description
Syntax `bytes()`
Arguments none
Returns bytes object

Example: 

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

bytes(size)

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

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

Returns: bytes object.

Example: 

data = bytes(4);
data.to_hex();               // '00000000'

Properties

`bytes` has no object-specific properties.

Use methods such as `get(index)`, `set(index, value)`, `size()`, `to_hex()`, and typed numeric methods to work with the byte buffer.

Common Object Methods

to_string()

Returns a display string for the object.

Item Description
Syntax `value.to_string()`
Arguments none
Returns string

Example: 

text = value.to_string();

clone()

Returns a new bytes object with a separate copy of the byte buffer.

Item Description
Syntax `bytes.clone()`
Arguments none
Returns bytes object

Example: 

data = bytes();
data.add_string('ABC');
copy = data.clone();

Methods

size()

Returns the number of bytes in the buffer.

Item Description
Syntax `bytes.size()`
Arguments none
Returns number

Example: 

bytes(3).size();             // 3

count()

Alias for `size()`.

Item Description
Syntax `bytes.count()`
Arguments none
Returns number

Example: 

data = bytes(2);
data.count();                // 2

empty()

Returns true when the buffer has no bytes.

Item Description
Syntax `bytes.empty()`
Arguments none
Returns boolean-style number

Example: 

data = bytes();
data.empty();                // true

clear()

Removes all bytes from the buffer.

Item Description
Syntax `bytes.clear()`
Arguments none
Returns boolean-style number

Example: 

data = bytes(4);
data.clear();
data.size();                 // 0

resize(size)

Resizes the buffer. New bytes are initialized to zero.

Argument Type Description
`size` number New byte count. Negative values are treated as `0`.

Returns: new byte count.

Example: 

data = bytes();
data.resize(3);
data.to_hex();               // '000000'

get(index)

Returns one byte as a number.

Argument Type Description
`index` number Byte index. Negative indexes are treated as `0`.

Returns: byte value, or `none()` when index is outside the buffer.

Example: 

data = bytes();
data.add(65);
data.get(0);                 // 65

get(index, count)

Returns a new `bytes` object containing up to `count` bytes from `index`.

Argument Type Description
`index` number Start byte index. Negative indexes are treated as `0`.
`count` number Maximum number of bytes to copy.

Returns: bytes object.

Example: 

data = bytes();
data.add_string('ABCDEF');
part = data.get(1, 3);
part.get_string(0);           // 'BCD'

set(index, value)

Writes one byte, or writes all bytes from another `bytes` object.

Argument Type Description
`index` number Byte index. Negative indexes are treated as `0`.
`value` number or bytes Byte value, or bytes object to copy.

Returns: boolean-style number.

Writing past the end grows the buffer and fills gaps with zero bytes.

Example: 

data = bytes();
data.set(2, 255);
data.to_hex();               // '0000ff'

add(value)

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

Argument Type Description
`value` number or bytes Byte value, or bytes object to append.

Returns: boolean-style number.

Example: 

data = bytes();
data.add(65);
data.add(66);
data.get_string(0);           // 'AB'

insert(index)

Inserts one zero byte before `index`.

Argument Type Description
`index` number Insert position. Negative indexes are treated as `0`. Values beyond the end insert at the end.

Returns: boolean-style number.

Example: 

data = bytes();
data.add_string('AC');
data.insert(1);
data.set(1, 66);
data.get_string(0);           // 'ABC'

insert(index, count)

Inserts `count` zero bytes before `index`.

Argument Type Description
`index` number Insert position. Negative indexes are treated as `0`. Values beyond the end insert at the end.
`count` number Number of zero bytes to insert.

Returns: boolean-style number.

Example: 

data = bytes();
data.add_string('AD');
data.insert(1, 2);
data.to_hex();               // '41000044'

erase(index)

Removes one byte at `index`.

Argument Type Description
`index` number Byte index. Negative indexes are treated as `0`.

Returns: boolean-style number.

Example: 

data = bytes();
data.add_string('ABC');
data.erase(1);
data.get_string(0);           // 'AC'

erase(index, count)

Removes up to `count` bytes starting at `index`.

Argument Type Description
`index` number Start byte index. Negative indexes are treated as `0`.
`count` number Maximum number of bytes to remove.

Returns: boolean-style number.

Example: 

data = bytes();
data.add_string('ABCD');
data.erase(1, 2);
data.get_string(0);           // 'AD'

get_string(index)

Returns text from `index` to the end of the buffer.

Argument Type Description
`index` number Start byte index.

Returns: string. If `index` is outside the buffer, returns an empty string.

Example: 

data = bytes();
data.add_string('ABC');
data.get_string(1);           // 'BC'

get_string(index, count)

Returns up to `count` bytes as text.

Argument Type Description
`index` number Start byte index.
`count` number Maximum number of bytes to read.

Returns: string.

Example: 

data = bytes();
data.add_string('ABCDE');
data.get_string(1, 3);        // 'BCD'

set_string(index, text)

Writes string bytes at `index`.

Argument Type Description
`index` number Start byte index.
`text` string Text to write as bytes.

Returns: boolean-style number.

Example: 

data = bytes();
data.set_string(2, 'HI');
data.to_hex();               // '00004849'

add_string(text)

Appends string bytes.

Argument Type Description
`text` string Text to append as bytes.

Returns: boolean-style number.

Example: 

data = bytes();
data.add_string('ABC');
data.to_hex();               // '414243'

get_s8(index)

Reads a signed 8-bit integer.

Argument Type Description
`index` number Start byte index.

Returns: number, or `none()` when there are not enough bytes.

Example: 

data = bytes();
data.add_s8(-1);
data.get_s8(0);              // -1

get_u8(index)

Reads an unsigned 8-bit integer.

Argument Type Description
`index` number Start byte index.

Returns: number, or `none()` when there are not enough bytes.

Example: 

data = bytes();
data.add_u8(255);
data.get_u8(0);              // 255

get_s16(index[, littleEndian])

Reads a signed 16-bit integer.

Argument Type Description
`index` number Start byte index.
`littleEndian` boolean Optional byte order flag. Defaults to `true`.

Returns: number, or `none()` when there are not enough bytes.

Example: 

data = bytes();
data.add_s16(-2, true);
data.get_s16(0, true);       // -2

get_u16(index[, littleEndian])

Reads an unsigned 16-bit integer.

Argument Type Description
`index` number Start byte index.
`littleEndian` boolean Optional byte order flag. Defaults to `true`.

Returns: number, or `none()` when there are not enough bytes.

Example: 

data = bytes();
data.add_u16(4660, true);
data.get_u16(0, true);       // 4660

get_s32(index[, littleEndian])

Reads a signed 32-bit integer.

Argument Type Description
`index` number Start byte index.
`littleEndian` boolean Optional byte order flag. Defaults to `true`.

Returns: number, or `none()` when there are not enough bytes.

Example: 

data = bytes();
data.add_s32(-123456, true);
data.get_s32(0, true);       // -123456

get_s3(index[, littleEndian])

Alias for `get_s32(index[, littleEndian])`.

Example: 

data = bytes();
data.add_s3(-123456, true);
data.get_s3(0, true);        // -123456

get_u32(index[, littleEndian])

Reads an unsigned 32-bit integer.

Argument Type Description
`index` number Start byte index.
`littleEndian` boolean Optional byte order flag. Defaults to `true`.

Returns: number, or `none()` when there are not enough bytes.

Example: 

data = bytes();
data.add_u32(2864434397, true);
data.get_u32(0, true);       // 2864434397

get_float(index[, littleEndian])

Reads a 32-bit floating-point value.

Argument Type Description
`index` number Start byte index.
`littleEndian` boolean Optional byte order flag. Defaults to `true`.

Returns: number, or `none()` when there are not enough bytes.

Example: 

data = bytes();
data.add_float(1.5, true);
data.get_float(0, true);     // 1.5

get_double(index[, littleEndian])

Reads a 64-bit floating-point value.

Argument Type Description
`index` number Start byte index.
`littleEndian` boolean Optional byte order flag. Defaults to `true`.

Returns: number, or `none()` when there are not enough bytes.

Example: 

data = bytes();
data.add_double(3.25, true);
data.get_double(0, true);    // 3.25

set_s8(index, value)

Writes a signed 8-bit integer.

Argument Type Description
`index` number Start byte index.
`value` number Value to write.

Returns: boolean-style number.

Example: 

data = bytes();
data.set_s8(0, -1);
data.get_s8(0);              // -1

set_u8(index, value)

Writes an unsigned 8-bit integer.

Argument Type Description
`index` number Start byte index.
`value` number Value to write.

Returns: boolean-style number.

Example: 

data = bytes();
data.set_u8(0, 255);
data.get_u8(0);              // 255

set_s16(index, value[, littleEndian])

Writes a signed 16-bit integer.

Argument Type Description
`index` number Start byte index.
`value` number Value to write.
`littleEndian` boolean Optional byte order flag. Defaults to `true`.

Returns: boolean-style number.

Example: 

data = bytes();
data.set_s16(0, -2, true);
data.get_s16(0, true);       // -2

set_u16(index, value[, littleEndian])

Writes an unsigned 16-bit integer.

Argument Type Description
`index` number Start byte index.
`value` number Value to write.
`littleEndian` boolean Optional byte order flag. Defaults to `true`.

Returns: boolean-style number.

Example: 

data = bytes();
data.set_u16(0, 4660, true);
data.to_hex();               // '3412'

set_s32(index, value[, littleEndian])

Writes a signed 32-bit integer.

Argument Type Description
`index` number Start byte index.
`value` number Value to write.
`littleEndian` boolean Optional byte order flag. Defaults to `true`.

Returns: boolean-style number.

Example: 

data = bytes();
data.set_s32(0, -123456, true);
data.get_s32(0, true);       // -123456

set_s3(index, value[, littleEndian])

Alias for `set_s32(index, value[, littleEndian])`.

Example: 

data = bytes();
data.set_s3(0, -123456, true);
data.get_s3(0, true);        // -123456

set_u32(index, value[, littleEndian])

Writes an unsigned 32-bit integer.

Argument Type Description
`index` number Start byte index.
`value` number Value to write.
`littleEndian` boolean Optional byte order flag. Defaults to `true`.

Returns: boolean-style number.

Example: 

data = bytes();
data.set_u32(0, 2864434397, true);
data.get_u32(0, true);       // 2864434397

set_float(index, value[, littleEndian])

Writes a 32-bit floating-point value.

Argument Type Description
`index` number Start byte index.
`value` number Value to write.
`littleEndian` boolean Optional byte order flag. Defaults to `true`.

Returns: boolean-style number.

Example: 

data = bytes();
data.set_float(0, 1.5, true);
data.get_float(0, true);     // 1.5

set_double(index, value[, littleEndian])

Writes a 64-bit floating-point value.

Argument Type Description
`index` number Start byte index.
`value` number Value to write.
`littleEndian` boolean Optional byte order flag. Defaults to `true`.

Returns: boolean-style number.

Example: 

data = bytes();
data.set_double(0, 3.25, true);
data.get_double(0, true);    // 3.25

add_s8(value)

Appends a signed 8-bit integer.

Argument Type Description
`value` number Value to append.

Returns: boolean-style number.

Example: 

data = bytes();
data.add_s8(-1);
data.get_s8(0);              // -1

add_u8(value)

Appends an unsigned 8-bit integer.

Argument Type Description
`value` number Value to append.

Returns: boolean-style number.

Example: 

data = bytes();
data.add_u8(255);
data.get_u8(0);              // 255

add_s16(value[, littleEndian])

Appends a signed 16-bit integer.

Argument Type Description
`value` number Value to append.
`littleEndian` boolean Optional byte order flag. Defaults to `true`.

Returns: boolean-style number.

Example: 

data = bytes();
data.add_s16(-2, true);
data.get_s16(0, true);       // -2

add_u16(value[, littleEndian])

Appends an unsigned 16-bit integer.

Argument Type Description
`value` number Value to append.
`littleEndian` boolean Optional byte order flag. Defaults to `true`.

Returns: boolean-style number.

Example: 

data = bytes();
data.add_u16(4660, true);
data.to_hex();               // '3412'

add_s32(value[, littleEndian])

Appends a signed 32-bit integer.

Argument Type Description
`value` number Value to append.
`littleEndian` boolean Optional byte order flag. Defaults to `true`.

Returns: boolean-style number.

Example: 

data = bytes();
data.add_s32(-123456, true);
data.get_s32(0, true);       // -123456

add_s3(value[, littleEndian])

Alias for `add_s32(value[, littleEndian])`.

Example: 

data = bytes();
data.add_s3(-123456, true);
data.get_s3(0, true);        // -123456

add_u32(value[, littleEndian])

Appends an unsigned 32-bit integer.

Argument Type Description
`value` number Value to append.
`littleEndian` boolean Optional byte order flag. Defaults to `true`.

Returns: boolean-style number.

Example: 

data = bytes();
data.add_u32(2864434397, true);
data.get_u32(0, true);       // 2864434397

add_float(value[, littleEndian])

Appends a 32-bit floating-point value.

Argument Type Description
`value` number Value to append.
`littleEndian` boolean Optional byte order flag. Defaults to `true`.

Returns: boolean-style number.

Example: 

data = bytes();
data.add_float(1.5, true);
data.get_float(0, true);     // 1.5

add_double(value[, littleEndian])

Appends a 64-bit floating-point value.

Argument Type Description
`value` number Value to append.
`littleEndian` boolean Optional byte order flag. Defaults to `true`.

Returns: boolean-style number.

Example: 

data = bytes();
data.add_double(3.25, true);
data.get_double(0, true);    // 3.25

to_hex()

Returns the buffer as lowercase hexadecimal text.

Item Description
Syntax `bytes.to_hex()`
Arguments none
Returns string

Example: 

data = bytes();
data.add_string('A');
data.to_hex();               // '41'

to_base64()

Returns the buffer encoded as base64 text.

Item Description
Syntax `bytes.to_base64()`
Arguments none
Returns string

Example: 

data = bytes();
data.add_string('ABC');
data.to_base64();            // 'QUJD'

from_base64(text)

Replaces the buffer with decoded base64 data.

Argument Type Description
`text` string Base64 text to decode.

Returns: decoded byte count.

Example: 

data = bytes();
data.from_base64('QUJD');
data.get_string(0);          // 'ABC'

find(value)

Searches for a byte, string, or another `bytes` object.

Argument Type Description
`value` number, string, or bytes Value to find.

Returns: first byte index, `-1` when not found, or `none()` for unsupported argument types.

Example: 

data = bytes();
data.add_string('ABCDEF');
data.find('CD');             // 2
data.find(70);               // 5

Previous: map

Next: File Format I/O