role Blob

Immutable buffer for binary data ('Binary Large OBject')

role Blob[::T = uint8does Positional[Tdoes Stringy { }

The Blob role is an immutable interface to binary types, and offers a list-like interface to lists of integers, typically unsigned integers.

Methods

method new

Defined as:

method new(*@codes)

Creates a Blob from a list of integers.

my $blob = Blob.new([123]);

method Bool

Defined as:

multi method Bool(Blob:D:)

Returns False if and only if the buffer is empty.

my $blob = Blob.new();
say $blob.Bool# OUTPUT: «False␤» 
$blob = Blob.new([123]);
say $blob.Bool# OUTPUT: «True␤» 

method elems

Defined as:

multi method elems(Blob:D: --> Int:D)

Returns the number of elements of the buffer.

my $blob = Blob.new([123]);
say $blob.elems# OUTPUT: «3␤» 

method bytes

Defined as:

method bytes(Blob:D: --> Int:D)

Returns the number of bytes used by the elements in the buffer.

say Blob.new([123]).bytes;      # OUTPUT: «3␤» 
say blob16.new([123]).bytes;    # OUTPUT: «6␤» 
say blob64.new([123]).bytes;    # OUTPUT: «24␤» 

method decode

Defined as:

multi method decode(Blob:D: Str:D $encoding = 'UTF-8' --> Str:D)

Applies an encoding to turn the blob into a Str.

my Blob $blob = "string".encode('utf-8');
say $blob.decode('utf-8'); # OUTPUT: «string␤» 

On malformed utf-8 .decode will throw X::AdHoc. To handle sloppy utf-8 use utf8-c8.

method subbuf

Defined as:

multi method subbuf(Int $fromInt $len = self.elems --> Blob:D)
multi method subbuf(Range $range --> Blob:D)

Extracts a part of the invocant buffer, starting from the index with elements $from, and taking $len elements (or less if the buffer is shorter), and creates a new buffer as the result.

say Blob.new(1..10).subbuf(24);    # OUTPUT: «Blob:0x<03 04 05 06>␤» 
say Blob.new(1..10).subbuf(*-2);     # OUTPUT: «Blob:0x<09 0a>␤» 
say Blob.new(1..10).subbuf(*-5,2);   # OUTPUT: «Blob:0x<06 07>␤» 

For convenience, also allows a Range to be specified to indicate which part of the invocant buffer you would like:

say Blob.new(1..10).subbuf(2..5);    # OUTPUT: «Blob:0x<03 04 05 06>␤» 

method unpack

This method is considered experimental, in order to use it you will need to do:

use experimental :pack;

Defined as:

method unpack(Blob:D: $template --> List:D)

Extracts features from the blob according to the template string, and returns them as a list.

The template string consists of zero or more units that begin with an ASCII letter, and are optionally followed by a quantifier. The quantifier can be * (which typically stands for "use up the rest of the Blob here"), or a positive integer (without a +).

Whitespace between template units is ignored.

Examples of valid templates include "A4 C n*" and "A*".

The following letters are recognized:

Letter Meaning
A Extract a string, where each element of the Blob maps to a codepoint
a Same as A
C Extract an element from the blob as an integer
H Extracts a hex string
L Extracts four elements and returns them as a single unsigned integer
n Extracts two elements and combines them in "network" (big-endian) byte order into a single integer
N Extracts four elements and combines them in "network" (big-endian) byte order into a single integer
S Extracts two elements and returns them as a single unsigned integer
v Same as S
V Same as L
x Drop an element from the blob (that is, ignore it)
Z Same as A

Example:

use experimental :pack;
say Blob.new(1..10).unpack("C*");
# OUTPUT: «(1 2 3 4 5 6 7 8 9 10)␤» 

sub pack

This subroutine is considered experimental, in order to use it you will need to do:

use experimental :pack;
    sub pack(Str $template*@items --> Buf)

Packs the given items according to the template and returns a buffer containing the packed bytes.

The template string consists of zero or more units that begin with an ASCII letter, and are optionally followed by a quantifier. For details, see unpack.

method reverse

Defined as:

method reverse(Blob:D: --> Blob:D)

Returns a Blob with all elements in reversed order.

say Blob.new([123]).reverse;    # OUTPUT: «Blob:0x<03 02 01>␤» 
say blob16.new([2]).reverse;        # OUTPUT: «Blob[uint16]:0x<02>␤» 
say buf32.new([1632]).reverse;    # OUTPUT: «Buf[uint32]:0x<20 10>␤» 

Type graph

Type relations for Blob
perl6-type-graph Blob Blob Positional Positional Blob->Positional Stringy Stringy Blob->Stringy Buf Buf Buf->Blob

Stand-alone image: vector

Routines supplied by role Positional

Blob does role Positional, which provides the following methods:

(Positional) method of

method of()

Returns the type constraint for elements of the positional container. Defaults to Mu.