BLOB’s

BLOB’s (Binary Large OBjects), used to hold packed arrays of bytes, have built-in support in Rhai.

A BLOB has no literal representation, but is created via the blob function, or simply returned as the result of a function call (e.g. generate_thumbnail_image that generates a thumbnail version of a large image as a BLOB).

All items stored in a BLOB are bytes (i.e. u8) and the BLOB can freely grow or shrink with bytes added or removed.

type_of() a BLOB returns "blob".

Element Access Syntax

From beginning

Like arrays, BLOB’s are accessed with zero-based, non-negative integer indices:

blob [ index position from 0 to length−1 ]

From end

A negative position accesses an element in the BLOB counting from the end, with −1 being the last element.

blob [ index position from −1 to −length ]

The value of a particular byte in a BLOB is mapped to an integer.

Only the lowest 8 bits are significant, all other bits are ignored.

Create a BLOB

The function blob allows creating an empty BLOB, optionally filling it to a required size with a particular value (default zero).

let x = blob();             // empty BLOB

let x = blob(10);           // BLOB with ten zeros

let x = blob(50, 42);       // BLOB with 50x 42's

To quickly initialize a BLOB with a particular byte stream, the `write_be` method can be used to
write eight bytes at a time (four under 32-bit) in big-endian byte order.

If fewer than eight bytes are needed, remember to right-pad the number as big-endian byte order is used.

~~~rust
let buf = blob(12, 0);      // BLOB with 12x zeros

// Write eight bytes at a time, in big-endian order
buf.write_be(0, 8, 0xab_cd_ef_12_34_56_78_90);
buf.write_be(8, 8, 0x0a_0b_0c_0d_00_00_00_00);
                            //   ^^^^^^^^^^^ remember to pad unused bytes

print(buf);                 // prints "[abcdef1234567890 0a0b0c0d]"

buf[3] == 0x12;
buf[10] == 0x0c;

// Under 'only_i32', write four bytes at a time:
buf.write_be(0, 4, 0xab_cd_ef_12);
buf.write_be(4, 4, 0x34_56_78_90);
buf.write_be(8, 4, 0x0a_0b_0c_0d);
~~~

Writing ASCII Bytes

Non-ASCII characters (i.e. characters not within 1-127) are ignored.

For many embedded applications, it is necessary to encode an ASCII string as a byte stream.

Use the write_ascii method to write ASCII strings into any specific range within a BLOB.

The following is an example of a building a 16-byte command to send to an embedded device.

// Assume the following 16-byte command for an embedded device:
// ┌─────────┬───────────────┬──────────────────────────────────┬───────┐
// │    0    │       1       │              2-13                │ 14-15 │
// ├─────────┼───────────────┼──────────────────────────────────┼───────┤
// │ command │ string length │ ASCII string, max. 12 characters │  CRC  │
// └─────────┴───────────────┴──────────────────────────────────┴───────┘

let buf = blob(16, 0);      // initialize command buffer

let text = "foo & bar";     // text string to send to device

buf[0] = 0x42;              // command code
buf[1] = s.len();           // length of string

buf.write_ascii(2..14, text);   // write the string

let crc = buf.calc_crc();   // calculate CRC

buf.write_le(14, 2, crc);   // write CRC

print(buf);                 // prints "[4209666f6f202620 626172000000abcd]"
                            //          ^^ command code              ^^^^ CRC
                            //            ^^ string length
                            //              ^^^^^^^^^^^^^^^^^^^ foo & bar

device.send(buf);           // send command to device

The `write_utf8` function writes a string in UTF-8 encoding.

UTF-8, however, is not very common for embedded applications.

Built-in Functions

The following functions operate on BLOB’s.