PoolByteArray¶

A pooled array of bytes.

Description¶

An array specifically designed to hold bytes. Optimized for memory usage, does not fragment the memory.

Note: This type is passed by value and not by reference. This means that when mutating a class property of type PoolByteArray or mutating a PoolByteArray within an Array or Dictionary, changes will be lost:

var array = [PoolByteArray()]
array[0].push_back(123)
print(array)  # [[]] (empty PoolByteArray within an Array)

Instead, the entire PoolByteArray property must be reassigned with = for it to be changed:

var array = [PoolByteArray()]
var pool_array = array[0]
pool_array.push_back(123)
array[0] = pool_array
print(array)  # [[123]] (PoolByteArray with 1 element inside an Array)

Methods¶

PoolByteArray	PoolByteArray ( Array from )
void	append ( int byte )
void	append_array ( PoolByteArray array )
void	clear ( )
PoolByteArray	compress ( int compression_mode=0 )
int	count ( int value )
PoolByteArray	decompress ( int buffer_size, int compression_mode=0 )
PoolByteArray	decompress_dynamic ( int max_output_size, int compression_mode=0 )
bool	empty ( )
void	fill ( int byte )
int	find ( int value, int from=0 )
String	get_string_from_ascii ( )
String	get_string_from_utf8 ( )
bool	has ( int value )
String	hex_encode ( )
int	insert ( int idx, int byte )
void	invert ( )
void	push_back ( int byte )
void	remove ( int idx )
void	resize ( int idx )
int	rfind ( int value, int from=-1 )
void	set ( int idx, int byte )
int	size ( )
void	sort ( )
PoolByteArray	subarray ( int from, int to )

Method Descriptions¶

PoolByteArray PoolByteArray ( Array from )

Constructs a new PoolByteArray. Optionally, you can pass in a generic Array that will be converted.

void append ( int byte )

Appends an element at the end of the array (alias of push_back).

void append_array ( PoolByteArray array )

Appends a PoolByteArray at the end of this array.

void clear ( )

Clears the array. This is equivalent to using resize with a size of 0.

PoolByteArray compress ( int compression_mode=0 )

Returns a new PoolByteArray with the data compressed. Set the compression mode using one of CompressionMode's constants.

int count ( int value )

Returns the number of times an element is in the array.

PoolByteArray decompress ( int buffer_size, int compression_mode=0 )

Returns a new PoolByteArray with the data decompressed. Set buffer_size to the size of the uncompressed data. Set the compression mode using one of CompressionMode's constants.

PoolByteArray decompress_dynamic ( int max_output_size, int compression_mode=0 )

Returns a new PoolByteArray with the data decompressed. Set the compression mode using one of CompressionMode's constants. This method only accepts gzip and deflate compression modes.

This method is potentially slower than decompress, as it may have to re-allocate its output buffer multiple times while decompressing, where as decompress knows its output buffer size from the beginning.

GZIP has a maximal compression ratio of 1032:1, meaning it's very possible for a small compressed payload to decompress to a potentially very large output. To guard against this, you may provide a maximum size this function is allowed to allocate in bytes via max_output_size. Passing -1 will allow for unbounded output. If any positive value is passed, and the decompression exceeds that amount in bytes, then an error will be returned.

bool empty ( )

Returns true if the array is empty.

void fill ( int byte )

Assigns the given value to all elements in the array. This can typically be used together with resize to create an array with a given size and initialized elements.

int find ( int value, int from=0 )

Searches the array for a value and returns its index or -1 if not found. Optionally, the initial search index can be passed. Returns -1 if from is out of bounds.

String get_string_from_ascii ( )

Returns a copy of the array's contents as String. Fast alternative to get_string_from_utf8 if the content is ASCII-only. Unlike the UTF-8 function this function maps every byte to a character in the array. Multibyte sequences will not be interpreted correctly. For parsing user input always use get_string_from_utf8.

String get_string_from_utf8 ( )

Returns a copy of the array's contents as String. Slower than get_string_from_ascii but supports UTF-8 encoded data. Use this function if you are unsure about the source of the data. For user input this function should always be preferred.

bool has ( int value )

Returns true if the array contains the given value.

Note: This is equivalent to using the in operator.

String hex_encode ( )

Returns a hexadecimal representation of this array as a String.

var array = PoolByteArray([11, 46, 255])
print(array.hex_encode()) # Prints: 0b2eff

int insert ( int idx, int byte )

Inserts a new element at a given position in the array. The position must be valid, or at the end of the array (idx == size()).

void invert ( )

Reverses the order of the elements in the array.

void push_back ( int byte )

Appends an element at the end of the array.

void remove ( int idx )

Removes an element from the array by index.

void resize ( int idx )

Sets the size of the array. If the array is grown, reserves elements at the end of the array. If the array is shrunk, truncates the array to the new size.

Note: Added elements are not automatically initialized to 0 and will contain garbage, i.e. indeterminate values.

int rfind ( int value, int from=-1 )

Searches the array in reverse order. Optionally, a start search index can be passed. If negative, the start index is considered relative to the end of the array. If the adjusted start index is out of bounds, this method searches from the end of the array.

void set ( int idx, int byte )

Changes the byte at the given index.

int size ( )

Returns the number of elements in the array.

void sort ( )

Sorts the elements of the array in ascending order.

PoolByteArray subarray ( int from, int to )

Returns the slice of the PoolByteArray between indices (inclusive) as a new PoolByteArray. Any negative index is considered to be from the end of the array.