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";
Some built-in features are not listed in this module:
- You can create a
Blob
literal from aText
literal, provided the context expects an expression of typeBlob
. b.size() : Nat
returns the number of bytes in the blobb
.b.vals() : Iter.Iter<Nat8>
returns an iterator to enumerate the bytes of the blobb
.
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))
}
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