Deutsche Version   Deutsche Version

Motivation

In technical applications or when controlling devices, it is often necessary to work with binary data. This extension allows to maintain a binary data field (byte array).

The UDP extension can already handle byte arrays, updates to the TCP client will follow shortly.


Version history

Version Adjustments
1.0 (2021-04-02) Initial version
1.1 (2021-05-21) Bug fixing at ReadWord, ReadDWord and ToHex

Download

Usage

Reference

Properties

Methods

Example ByteArrayTest

Tools

Download

The UrsAI2ByteArray ZIP archive for download. The archive contains the source code, the compiled binary for uploading to the App Inventor and a sample application.

Usage

The byte array extension allows sequential and random access to the stored data. The index base (the index of the first element) for random access can be set using the Base property. The values 1 (as usual in App Inventor) or 0 (as usual in Java or C) are possible.

The component starts with an empty array, which means that it does not contain any elements. Elements can be added using the methods AddByte (unsigned 8-bit number [0..255]), AddWord (unsigned 16-bit number [0..65.536]) or AddDWord (unsigned 32-bit number [0..4.294.967.296]). With AddWord and AddDWord, the property MsbFirst defines the order (byte order) with which the bytes are added to the array. You can add the content of another byte array to the array using the Append method.

The Fill function fills the array with a specified number of elements with a specified value. The InsertByteAt function inserts a byte at the specified position. The other elements are moved back one position. RemoveByteAt deletes the byte at the specified position. The following bytes are shifted forward. A byte can be changed with the SetByteAt function.

The Clear function removes all elements from the byte array.

The sequential access is done using the ReadByte, ReadWord or ReadDWord functions. The MsbFirst property defines the byte order. The ReadIndex property specifies the position in the array that will be read next. In order to read at a certain element, ReadIndex can also be set accordingly. The Available property returns how many bytes can still be read.

The ToString method returns the content of the array as a sequence of two-digit hexadecimal numbers. With ToHex a byte, a word or a double word can be converted to its hexadecimal representation. The HexPrefix property specifies which character string is placed in front of the hexadecimal number. The default setting is "0x".

Reference

Properties

Available
Returns the number of bytes that can still be read sequentially.
Base
Gets or sets the index of the first item. The entries 1 (as usual in App Inventor) or 0 (as usual in Java or C) are possible. Values ​​greater than 1 are converted 1 and values ​​less than 0 are converted to 0. The default is 1
HexPrefix
Gets or sets the prefix for the hexadecimal representation (see ToString and ToHex). The default setting is "0x".
MsbFirst
Gets or sets the order in which the bytes of the AddWord and AddDWord functions are added or read with ReadWord and ReadDWord. The default is true.
ReadIndex
Gets or sets the position from which to continue reading sequentially. The default is the value of Base.
Size
Getsthe number of stored bytes.
Version
Gets the version of the extension.

Methods

AddByte (Byte)
Adds a byte (unsigned 8-bit number [0..255]) to the end of the byte array.

If the specified value is less than 0 or greater than 255, the value is not added and the Screen.ErrorOccurred event is triggered with the error number 17200 ("Value out of range.").
AddDWord (DWord)
Adds a double word (unsigned 32-bit number [0..4.294.967.296]) to the end of the byte array. The MsbFirst property defines the byte order.

If the specified value is less than 0 or greater than 4,294,967,296, the value is not added and the Screen.ErrorOccurred event is triggered with the error number 17200 ("Value out of range.").
AddWord (Word)
Adds a word (unsigned 16-bit number [0..65,536]) to the end of the byte array. The MsbFirst property defines the byte order.

If the specified value is less than 0 or greater than 65,536, the value is not added and the Screen.ErrorOccurred event is triggered with error number 17200 ("Value out of range.").
Append (Array)
Adds the content of the specified byte array. Array must be an instance of the UrsAI2ByteArray extension.

If this is not the case, it is not added and the Screen.ErrorOccurred event is triggered with the error number 17202 ("Invalid type.").
Clear ()
Removes all elements from the byte array. The ReadIndex property is reset to the value of Base.
Fill (Count, Value)
Fills the byte array with count bytes and assigns the value Value. Elements already contained are deleted beforehand (see Clear). The ReadIndex property is reset to the value of Base. Value must be an unsigned number in the range [0..255]).

If Value is less than 0 or greater than 255, the function is not executed and the creen.ErrorOccurred event is triggered with error number 17200 ("Value out of range.").
GetByteAt (Index)
Gets the value of the item at the position Index.

If the value of Index is less than Base or points behind the array, the creen.ErrorOccurred event is triggered with the error number 17201 ("Index out of range.") and the value 0 is returned
InsertByteAt (Index, Byte)
Inserts a byte at the position specified Index. The following elements are pushed back. If ReadIndex points behind the insertion point, it is also moved so that it points to the same value as before the insertion.

If the value of Index is less than Base or Base behind the array, the function is not executed and the Screen.ErrorOccurred event is triggered with the error number 17201 ("Index out of range."). Byte must be an unsigned number in the range [0..255]). If the specified value is less than 0 or greater than 255, the element will not be replaced and the Screen.ErrorOccurred event triggered with the error number 17200 ("Value out of range.").
ReadByte ()
Gets the value of the element pointed to by the ReadIndex. ReadIndex is incremented.

If no more byte is available (see Available), the Screen.ErrorOccurred event is triggered with the error number 17203 ("Read beyond end of array.") and the value 0 is returned.
ReadDWord ()
Gets the double word (4 bytes) pointed to by the ReadIndex. The MsbFirst property defines the byte order. ReadIndex is incremented.

If there are not enough bytes available (see Available), the Screen.ErrorOccurred event is triggered with the error number 17203 ("Read beyond end of array.") and the value 0 is returned.
ReadWord ()
Gets the word (2 bytes) pointed to by the ReadIndex. The MsbFirst property defines the byte order. ReadIndex is incremented.

If there are not enough bytes available (see Available), the Screen.ErrorOccurred event is triggered with the error number 17203 ("Read beyond end of array.") and the value 0 is returned.
RemoveByteAt (Index)
Removes the byte at the index position. The following elements are pushed forward. If ReadIndex points behind the deleted position, it is also moved so that it points to the same value as before the insertion.

If the value of Index is less than Base or points behind the array, the function is not executed and the Screen.ErrorOccurred event is triggered with the error number 17201 ("Index out of range.").
SetByteAt (Index, Byte)
Changes the byte at the position Index. Byte must be an unsigned number in the range [0..255]).

If the value of Index is less than Base or points behind the array, the function is not executed and the Screen.ErrorOccurred event is triggered with the error number 17201 ("Index out of range.").  If the value of Byte is less than 0 or greater than 255, the function is not executed and the Screen.ErrorOccurred event is triggered with error number 17200 ("Value out of range.").
ToHex (Value, Digits)
Konvertiert eine vorzeichenlose Zahl (8, 16, oder 32 Bit) in die Hexadezimaldarstellung. Der Hexadezimalzahl wird der Wert von HexPrefix voran gestellt. Ist Digits nicht 2, 4 oder 8 oder ist Value kleiner als 0 oder größer als 4.294.967.295 (0xFFFFFFFF), wird "--" ausgegeben.

Converts an unsigned number (8, 16, or 32 bits) to hexadecimal representation. The hexadecimal number is preceded by the value of HexPrefix. If Digits is not 2, 4 or 8 or if Value is less than 0 or greater than 4,294,967,295 (0xFFFFFFFF), "-" is returned.
ToString ()
Returns the content of the array as a sequence of two-digit hexadecimal numbers. Each hexadecimal number is preceded by the value of HexPrefix.

Example ByteArraTest

 

The example creates a byte array and then reads it out.

This is how the byte array is constructed:

That was read out again:

Tools

For developing own extensions I gathered some tips: AI2 FAQ: Develop Extensions. On the site you can find further informations.