Class: Toybox.Lang.ByteArray

Inherits:

Toybox.Lang.Object

• Toybox.Lang.Object
• Toybox.Lang.ByteArray

Overview

ByteArray objects are fixed size, numerically indexed, single dimensional, and take Numbers with a value >= -128 and <= 255 as members.

Since:

API Level 3.0.0

Instance Method Summary

• add(byte as Lang.Number or Lang.Char) as Lang.ByteArray

  Add a byte to the end of a ByteArray.

• addAll(array as Lang.Array or Lang.ByteArray) as Lang.ByteArray

  Add a ByteArray or an Array of bytes to the end of a ByteArray.

• decodeNumber(format as Lang.NumberFormat, options as { :offset as Lang.Number, :endianness as Lang.Endian }) as Lang.Numeric

  Decodes a portion of the array to a number based on a specified format.

• encodeNumber(value as Lang.Numeric, format as Lang.NumberFormat, options as { :offset as Lang.Number, :endianness as Lang.Endian }) as Lang.ByteArray

  Encodes a number into the byte array.

• equals(other as Lang.Object or Null) as Lang.Boolean

  Test if an Object instance is equal to another instance of an Object.

• hashCode() as Lang.Number

  Get a hash code value for a ByteArray.

• indexOf(byte as Lang.Number or Lang.Char) as Lang.Number

  Get the index of a byte within the ByteArray.

• remove(byte as Lang.Number or Lang.Char) as Lang.Boolean

  Remove a byte from a ByteArray.

• removeAll(byte as Lang.Number or Lang.Char) as Lang.Boolean

  Remove bytes from a ByteArray.

• reverse() as Lang.ByteArray

  Return a new ByteArray that contains the elements of a source ByteArray in reverse order.

• size() as Lang.Number

  Get the size of a ByteArray.

• slice(startIndex as Lang.Number or Null, endIndex as Lang.Number or Null) as Lang.ByteArray

  Get a new ByteArray containing a portion of an existing ByteArray.

• toString() as Lang.String

  Convert a ByteArray to a String.

Instance Method Details

add(byte as Lang.Number or Lang.Char) as Lang.ByteArray

Add a byte to the end of a ByteArray.

When adding a byte, the ByteArray size is increased and new bytes are inserted at the end.

Parameters:

• byte — (Lang.Number, Lang.Char) —

  The Number or Char byte to be added

Returns:

• Lang.ByteArray —

  A ByteArray composed of the original ByteArray plus the added byte

Since:

API Level 3.0.0

Throws:

• (Lang.UnexpectedTypeException) —

  Thrown if a type other than Number or Char is provided

• (Lang.ValueOutOfBoundsException) —

  Thrown if a Number greater than 255 or less than -128 is provided, or if a Char with a code point greater than 127 is provided. Negative numbers added are interpreted as the positive 8-bit unsigned equivalent once added to the ByteArray.

addAll(array as Lang.Array or Lang.ByteArray) as Lang.ByteArray

Add a ByteArray or an Array of bytes to the end of a ByteArray.

When adding an array of bytes, the ByteArray is expanded by the size of the provided ByteArray or Array, and all of the new elements are inserted starting at the new index.

Parameters:

• array — (Lang.ByteArray, Lang.Array) —

  The ByteArray or Array of bytes to be added to the ByteArray

Returns:

• Lang.ByteArray —

  A ByteArray composed of the original ByteArray plus the added byte(s)

Since:

API Level 3.0.0

Throws:

• (Lang.UnexpectedTypeException) —

  Thrown if a type other than ByteArray or an Array of bytes is provided

decodeNumber(format as Lang.NumberFormat, options as { :offset as Lang.Number, :endianness as Lang.Endian }) as Lang.Numeric

Decodes a portion of the array to a number based on a specified format

Parameters:

• format — (Lang.NumberFormat) —

  A Lang.NUMBER_FORMAT_* value representing the number format to decode.

• options — (Lang.Dictionary) —

  A Dictionary containing conversion options

  • :offset — (Lang.Number) —

    The 0 based offset in the array to begin decode. Default value is 0.

  • :endianness — (Lang.Endian) —

    A Lang.ENDIAN_* value representing the endianness of the number to decode. Default value is Lang.ENDIAN_LITTLE.

Returns:

• Lang.Number, Lang.Long, Lang.Float —

  Converted Number.

Since:

API Level 3.1.0

Throws:

• (Lang.InvalidOptionsException) —

  Indicates that one of the options provided is not valid.

encodeNumber(value as Lang.Numeric, format as Lang.NumberFormat, options as { :offset as Lang.Number, :endianness as Lang.Endian }) as Lang.ByteArray

Encodes a number into the byte array

Parameters:

• value — (Lang.Object) —

  The value to encode

• format — (Lang.NumberFormat) —

  A Lang.NUMBER_FORMAT_* value representing the number format to encode.

• options — (Lang.Dictionary) —

  A Dictionary containing conversion options

  • :offset — (Lang.Number) —

    The 0 based offset in the array to begin encoding. Default value is 0.

  • :endianness — (Lang.Endian) —

    A Lang.ENDIAN_* value representing the endianness of the number to encode. Default value is Lang.ENDIAN_LITTLE.

Since:

API Level 3.1.0

Throws:

• (Lang.InvalidOptionsException) —

  Indicates that one of the options provided is not valid.

equals(other as Lang.Object or Null) as Lang.Boolean

Test if an Object instance is equal to another instance of an Object.

Parameters:

• other — (Lang.Object) —

  The Object to test against

Example:

var a = [ 1, 2 ]b;
var b = [ 1, 2 ]b;
var c = [ 1, 2 ];
a.equals(b); // returns true
a.equals(c); // returns false

Returns:

• Lang.Boolean —

  true if Objects are equal, otherwise false

Since:

API Level 3.0.0

hashCode() as Lang.Number

Get a hash code value for a ByteArray.

Returns:

• Lang.Number —

  The hash code for the ByteArray

Since:

API Level 3.0.0

indexOf(byte as Lang.Number or Lang.Char) as Lang.Number

Get the index of a byte within the ByteArray.

Parameters:

• byte — (Lang.Number, Lang.Char) —

  The byte whose index is to be found

Returns:

• Lang.Number —

  The index of the first instance of the provided byte in the ByteArray. If the byte is not found, -1 is returned.

Since:

API Level 3.0.0

Throws:

• (Lang.UnexpectedTypeException) —

  Thrown if a type other than Number or Char is provided

• (Lang.ValueOutOfBoundsException) —

  Thrown if a Number greater than 255 or less than -128 is provided, or if a Char with a code point greater than 127 is provided. Negative numbers provided are interpreted as the positive 8-bit unsigned equivalent when searching the ByteArray.

remove(byte as Lang.Number or Lang.Char) as Lang.Boolean

Remove a byte from a ByteArray.

If the passed byte is found, the ByteArray size is decreased by one and elements beyond it are shifted to the next lower index. If the ByteArray has multiple matches, the matching byte at the lowest index will be removed but the other matching bytes will not be removed.

If no byte is provided as an argument, the ByteArray will remain unchanged and remove() will return false.

Parameters:

• byte — (Lang.Number, Lang.Char) —

  The byte to remove from the ByteArray

Returns:

• Lang.Boolean —

  Returns true if instances of the byte are found, otherwise false

Since:

API Level 3.0.0

Throws:

• (Lang.UnexpectedTypeException) —

  Thrown if a type other than Number or Char is provided

• (Lang.ValueOutOfBoundsException) —

  Thrown if a Number greater than 255 or less than -128 is provided, or if a Char with a code point greater than 127 is provided. Negative numbers provided are interpreted as the positive 8-bit unsigned equivalent when searching the ByteArray.

removeAll(byte as Lang.Number or Lang.Char) as Lang.Boolean

Remove bytes from a ByteArray.

For each instance of the byte that is found, the ByteArray size is decreased by one and elements beyond it are shifted to the next lower index.

If no byte is given as an argument, the ByteArray will remain unchanged and removeAll() will return false.

Parameters:

• byte — (Lang.Number, Lang.Char) —

  The byte to remove from the ByteArray

Returns:

• Lang.Boolean —

  Returns true if instances of the byte are found, otherwise false.

Since:

API Level 3.0.0

Throws:

• (Lang.UnexpectedTypeException) —

  Thrown if a type other than Number or Char is provided

• (Lang.ValueOutOfBoundsException) —

  Thrown if a Number greater than 255 or less than -128 is provided, or if a Char with a code point greater than 127 is provided. Negative numbers provided are interpreted as the positive 8-bit unsigned equivalent when searching the ByteArray.

reverse() as Lang.ByteArray

Return a new ByteArray that contains the elements of a source ByteArray in reverse order.

Returns:

• Lang.ByteArray —

  A new ByteArray with elements in reversed order

Since:

API Level 3.0.0

size() as Lang.Number

Get the size of a ByteArray.

Returns:

• Lang.Number —

  The number of elements in the ByteArray.

Since:

API Level 3.0.0

slice(startIndex as Lang.Number or Null, endIndex as Lang.Number or Null) as Lang.ByteArray

Get a new ByteArray containing a portion of an existing ByteArray.

Parameters:

• startIndex — (Lang.Number, null) —

  A zero-based index of the start of the new ByteArray. If a negative startIndex is provided, it will offset from the end of the ByteArray. If the startIndex is null, the slice will begin at 0. An out-of-bounds index will be truncated to the ByteArray limits.

• endIndex — (Lang.Number, null) —

  A zero-based index of the end of the new ByteArray. Items are included up to, but not including endIndex. If a negative endIndex is provided, it will offset from the end of the ByteArray. If endIndex is null, the slice will end at the last element. An out-of-bounds index is truncated to the ByteArray limits.

Returns:

• Lang.ByteArray —

  A new ByteArray containing the elements from startIndex to endIndex

Since:

API Level 3.0.0

toString() as Lang.String

Convert a ByteArray to a String.

This does not convert the elements of the ByteArray into Strings, but transforms the entire ByteArray into a String.

Returns:

• Lang.String —

  A String representation of the ByteArray

Since:

API Level 3.0.0