The Binary Data plugin allows raw access to an allocated section of memory (often referred to as a buffer). For example it could allocate 16 bytes of memory, and read and write anywhere in that buffer as individual bytes, 32-bit integers, floating point numbers, text, and so on.
A comprehensive description of how binary data/computer memory storage works is out of the scope of this manual. However there is lots of information on the Internet that covers it, and most computer science or computing courses will also cover it. The Binary Data object is also useful even if you do not access its contents: it integrates with other plugins like AJAX and Local Storage, allowing binary data such as images to be stored or transferred in useful ways. Despite the name, Binary Data can also store text, using the Set from text action and GetAllText expression, which can be useful with other plugins such as Cryptography.
Scripting
When using JavaScript or TypeScript coding, the features of this object can be accessed via the IBinaryDataInstance script interface. (JavaScript and TypeScript have support for binary data built-in, but this allows for interacting with binary data used in event sheets.)
Binary Data properties
- Endian
- The default endian to use when reading and writing binary values.
Binary Data conditions
- Compare length
- Compare the length of the data buffer, in bytes.
- Compare value
- Read a value of a given data type at an offset in the data buffer, and then compare that value to another number.
Binary Data actions
- Copy
- Copy data from another (or the same) Binary Data object. This does not change the size of the buffer. The Start and Length specify the range of data in the source Binary Data object to copy, defaulting to copying the entire buffer. The Target is a byte offset to write the copy at.
- Fill
- Fill a range of the buffer with copies of the same value. For example this can be used to fill an entire range of the buffer with zero bytes. The Offset and Length can be used to specify a byte range to fill, but they default to covering the entire buffer.
- Set endian
- Change the endian used when reading and writing values.
- Set from base64
- Set the contents of the Binary Data object from the contents of a base64-encoded string. This decodes the base64 string to binary and changes the buffer size to fit it.
- Set from Binary Data
- Set the contents of the Binary Data object to a copy of another Binary Data object. This changes the size of the buffer to be the same as the other object.
- Set from text
- Set the contents of the Binary Data object to a text string encoded as UTF-8. This changes the size of the buffer to fit.
- Set length
- Set the size of the memory buffer in bytes. Note Binary Data initially has a zero sized buffer, so this must be used first before any reads or writes can complete. The existing data is preserved when changing the size; if the new size is smaller, data is truncated, and if the new size is larger, zero bytes are added.
- Set value
- Write a value of a given data type at a byte offset in the memory buffer. The entire value must be within the bounds of the buffer, otherwise the write is ignored. For example a 4-byte Uint32 value cannot be written anywhere in a 3-byte buffer, because all four bytes must be inside the buffer.
- Compress
- Decompress
- Use a compression algorithm to compress or decompress the data stored in the Binary Data object. The supported compression algorithms are GZIP and DEFLATE. The same algorithm as used for compression must be used for decompression. Compression algorithms work by identifying and eliminating repeating patterns in data and can significantly shrink the amount of data. However the effectiveness depends on the size and type of data. Small amounts of data, or highly unpredictable data, generally does not compress well; large amounts of highly repetitive data generally compresses very well. See the Compression example for a demonstration.
Binary Data expressions
- ByteLength
- Return the current length of the buffer in bytes.
- GetBase64
- Return the entire contents of the data buffer encoded as a base64 string. This is useful when binary data must be stored in a text-based format like JSON.
- GetURL
- Return a URL that can be used locally to load the binary data. For example if the Binary Data represents an image, this URL can be passed the Sprite object's Load image from URL action to load the image from the Binary Data object.
- GetUint8(byteOffset)
- GetInt8(byteOffset)
- GetUint16(byteOffset)
- GetInt16(byteOffset)
- GetUint32(byteOffset)
- GetInt32(byteOffset)
- GetFloat32(byteOffset)
- GetFloat64(byteOffset)
- Read a value of the corresponding type from the buffer at a byte offset. The entire value must be within the bounds of the buffer, otherwise it returns 0. For example a 4-byte Uint32 value cannot be read from a 3-byte buffer, because all four bytes must be inside the buffer.
- GetText(byteOffset, length)
- Decode text in the UTF-8 encoding in a range of the buffer in bytes, and return the string. If the UTF-8 encoding is invalid, or any part of the range is outside the buffer, an empty string is returned.
- GetAllText
- Decode all the data in the Binary Data object as text in the UTF-8 encoding. This is the same as using the GetText expression with a range that specifies all the data.