Skip to main content

base/Blob

Blob is an immutable, iterable sequence of bytes. Unlike [Nat8], which is less compact (using 4 bytes per logical byte), Blob provides a more efficient representation.

Blobs are not indexable and can be empty. To manipulate a Blob, convert it to [var Nat8] or Buffer<Nat8>, perform your changes, then convert it back.

Import from the base library to use this module.

import Blob "mo:base/Blob";
Additional features

Some built-in features are 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:

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))
}
Operator limitation

Comparison functions (equal, notEqual, less, lessOrEqual, greater, greaterOrEqual) are defined in this library to allow their use as function values in higher-order functions. Operators like ==, !=, <, <=, >, and >= cannot currently be passed as function values.

Type Blob​

type Blob = Prim.Types.Blob

Function fromArray​

func fromArray(bytes : [Nat8]) : Blob

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

Example:

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

Function fromArrayMut​

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

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

Example:

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

Function toArray​

func toArray(blob : Blob) : [Nat8]

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

Example:

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

Function toArrayMut​

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

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

Example:

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

Function hash​

func hash(blob : Blob) : Nat32

Returns the (non-cryptographic) hash of blob.

Example:

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

Function compare​

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:

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

Function equal​

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

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

Example:

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

Function notEqual​

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

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

Example:

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

Function less​

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

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

Example:

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

Function lessOrEqual​

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

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

Example:

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

Function greater​

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

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

Example:

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

Function greaterOrEqual​

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

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

Example:

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