Blob

Module for working with Blobs: immutable sequence of bytes.

Blobs represent sequences of bytes. They are immutable, iterable, but not indexable and can be empty.

Byte sequences are also often represented as [Nat8], i.e. an array of bytes, but this representation is currently much less compact than Blob, taking 4 physical bytes to represent each logical byte in the sequence. If you would like to manipulate Blobs, it is recommended that you convert Blobs to [var Nat8] or Buffer<Nat8>, do the manipulation, then convert back.

Import from the base library to use this module.

motoko name=import
import Blob "mo:base/Blob";

Some built in features not listed in this module:

You can create a Blob literal from a Text literal, provided the context expects an expression of type Blob.
b.size() : Nat returns the number of bytes in the blob b;
b.vals() : Iter.Iter<Nat8> returns an iterator to enumerate the bytes of the blob b.

For example:

motoko include=import
import Debug "mo:base/Debug";
import Nat8 "mo:base/Nat8";

let blob = "\00\00\00\ff" : Blob; // blob literals, where each byte is delimited by a back-slash and represented in hex
let blob2 = "charsもあり" : Blob; // you can also use characters in the literals
let numBytes = blob.size(); // => 4 (returns the number of bytes in the Blob)
for (byte : Nat8 in blob.vals()) { // iterator over the Blob
  Debug.print(Nat8.toText(byte))
}

type Blob = Prim.Types.Blob

`public func fromArray(bytes : [Nat8]) : Blob`

Creates a Blob from an array of bytes ([Nat8]), by copying each element.

Example:

motoko include=import
let bytes : [Nat8] = [0, 255, 0];
let blob = Blob.fromArray(bytes); // => "\00\FF\00"

`public func fromArrayMut(bytes : [var Nat8]) : Blob`

Creates a Blob from a mutable array of bytes ([var Nat8]), by copying each element.

Example:

motoko include=import
let bytes : [var Nat8] = [var 0, 255, 0];
let blob = Blob.fromArrayMut(bytes); // => "\00\FF\00"

`public func toArray(blob : Blob) : [Nat8]`

Converts a Blob to an array of bytes ([Nat8]), by copying each element.

Example:

motoko include=import
let blob = "\00\FF\00" : Blob;
let bytes = Blob.toArray(blob); // => [0, 255, 0]

`public func toArrayMut(blob : Blob) : [var Nat8]`

Converts a Blob to a mutable array of bytes ([var Nat8]), by copying each element.

Example:

motoko include=import
let blob = "\00\FF\00" : Blob;
let bytes = Blob.toArrayMut(blob); // => [var 0, 255, 0]

`public func hash(blob : Blob) : Nat32`

Returns the (non-cryptographic) hash of blob.

Example:

motoko include=import
let blob = "\00\FF\00" : Blob;
Blob.hash(blob) // => 1_818_567_776

`public func compare(b1 : Blob, b2 : Blob) : {#less; #equal; #greater}`

General purpose comparison function for Blob by comparing the value of the bytes. Returns the Order (either #less, #equal, or #greater) by comparing blob1 with blob2.

Example:

motoko include=import
let blob1 = "\00\00\00" : Blob;
let blob2 = "\00\FF\00" : Blob;
Blob.compare(blob1, blob2) // => #less

`public func equal(blob1 : Blob, blob2 : Blob) : Bool`

Equality function for Blob types. This is equivalent to blob1 == blob2.

Example:

motoko include=import
let blob1 = "\00\FF\00" : Blob;
let blob2 = "\00\FF\00" : Blob;
ignore Blob.equal(blob1, blob2);
blob1 == blob2 // => true

Note: The reason why this function is defined in this library (in addition to the existing == operator) is so that you can use it as a function value to pass to a higher order function. It is not possible to use == as a function value at the moment.

Example:

motoko include=import
import Buffer "mo:base/Buffer";

let buffer1 = Buffer.Buffer<Blob>(3);
let buffer2 = Buffer.Buffer<Blob>(3);
Buffer.equal(buffer1, buffer2, Blob.equal) // => true

`public func notEqual(blob1 : Blob, blob2 : Blob) : Bool`

Inequality function for Blob types. This is equivalent to blob1 != blob2.

Example:

motoko include=import
let blob1 = "\00\AA\AA" : Blob;
let blob2 = "\00\FF\00" : Blob;
ignore Blob.notEqual(blob1, blob2);
blob1 != blob2 // => true

Note: The reason why this function is defined in this library (in addition to the existing != operator) is so that you can use it as a function value to pass to a higher order function. It is not possible to use != as a function value at the moment.

`public func less(blob1 : Blob, blob2 : Blob) : Bool`

"Less than" function for Blob types. This is equivalent to blob1 < blob2.

Example:

motoko include=import
let blob1 = "\00\AA\AA" : Blob;
let blob2 = "\00\FF\00" : Blob;
ignore Blob.less(blob1, blob2);
blob1 < blob2 // => true

Note: The reason why this function is defined in this library (in addition to the existing < operator) is so that you can use it as a function value to pass to a higher order function. It is not possible to use < as a function value at the moment.

`public func lessOrEqual(blob1 : Blob, blob2 : Blob) : Bool`

"Less than or equal to" function for Blob types. This is equivalent to blob1 <= blob2.

Example:

motoko include=import
let blob1 = "\00\AA\AA" : Blob;
let blob2 = "\00\FF\00" : Blob;
ignore Blob.lessOrEqual(blob1, blob2);
blob1 <= blob2 // => true

Note: The reason why this function is defined in this library (in addition to the existing <= operator) is so that you can use it as a function value to pass to a higher order function. It is not possible to use <= as a function value at the moment.

`public func greater(blob1 : Blob, blob2 : Blob) : Bool`

"Greater than" function for Blob types. This is equivalent to blob1 > blob2.

Example:

motoko include=import
let blob1 = "\BB\AA\AA" : Blob;
let blob2 = "\00\00\00" : Blob;
ignore Blob.greater(blob1, blob2);
blob1 > blob2 // => true

Note: The reason why this function is defined in this library (in addition to the existing > operator) is so that you can use it as a function value to pass to a higher order function. It is not possible to use > as a function value at the moment.

`public func greaterOrEqual(blob1 : Blob, blob2 : Blob) : Bool`

"Greater than or equal to" function for Blob types. This is equivalent to blob1 >= blob2.

Example:

motoko include=import
let blob1 = "\BB\AA\AA" : Blob;
let blob2 = "\00\00\00" : Blob;
ignore Blob.greaterOrEqual(blob1, blob2);
blob1 >= blob2 // => true

Note: The reason why this function is defined in this library (in addition to the existing >= operator) is so that you can use it as a function value to pass to a higher order function. It is not possible to use >= as a function value at the moment.