role Blob

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

role Blob[::T = uint8] does Positional[T] does Stringy { }

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

However, it's a parameterized type, and you can instantiate with several integer types:

my $b = Blob[int32].new(3, -3, 0xff32, -44);
say $b; # OUTPUT: «Blob[int32]:0x<03 -3 FF32 -2C>␤»

By default, Blob uses 8-bit unsigned integers, that is, it is equivalent to Blob[uint8]. Some other types of Blobs which are used often get their own class name.


blob8	Blob[uint8]
blob16	Blob[uint16]
blob32	Blob[uint32]
blob64	Blob[uint64]

You can use these in pretty much the same way you would with Blob:

my $blob = blob8.new(3, 6, 254);
    say $blob; # OUTPUT: «Blob[uint8]:0x<03 06 FE>␤»

Methods

method new

multi method new(Blob:)
    multi method new(Blob: Blob:D $blob)
    multi method new(Blob: int @values)
    multi method new(Blob: @values)
    multi method new(Blob: *@values)

Creates an empty Blob, or a new Blob from another Blob, or from a list of integers or values (which will have to be coerced into integers):

my $blob = Blob.new([1, 2, 3]);
    say Blob.new(<1 2 3>); # OUTPUT: «Blob:0x<01 02 03>␤»

method Bool

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([1, 2, 3]);
    say $blob.Bool; # OUTPUT: «True␤»

method Capture

method Capture(Blob:D:)

Converts the object to a List which is, in turn, coerced to a Capture.

method elems

multi method elems(Blob:D:)

Returns the number of elements of the buffer.

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

method bytes

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

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

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

method chars

method chars(Blob:D:)

Throws X::Buf::AsStr with chars as payload.

method Str

multi method Str(Blob:D:)

Throws X::Buf::AsStr with Str as payload. In order to convert to a Str you need to use .decode.

method Stringy

multi method Stringy(Blob:D:)

Throws X::Buf::AsStr with Stringy as payload.

method decode

multi method decode(Blob:D: $encoding = self.encoding // "utf-8")

multi method decode(Blob:D: $encoding, Str :$replacement!,
                    Bool:D :$strict = False)

multi method decode(Blob:D: $encoding, Bool:D :$strict = False)

Applies an encoding to turn the blob into a Str; the encoding will be UTF-8 by default.

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 list

multi method list(Blob:D:)

Returns a List of integers:

say "zipi".encode("ascii").list; # OUTPUT: «(122 105 112 105)␤»

method gist

method gist(Blob:D: --> Str:D)

Returns the string containing the "gist" of the Blob, listing up to the first 100 elements, separated by space, appending an ellipsis if the Blob has more than 100 elements.

put Blob.new(1, 2, 3).gist; # OUTPUT: «Blob:0x<01 02 03>␤»
    put Blob.new(1..2000).gist;
    # OUTPUT:
    # Blob:0x<01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 10 11 12 13 14 15
    # 16 17 18 19 1A 1B 1C 1D 1E 1F 20 21 22 23 24 25 26 27 28 29 2A 2B 2C
    # 2D 2E 2F 30 31 32 33 34 35 36 37 38 39 3A 3B 3C 3D 3E 3F 40 41 42 43
    # 44 45 46 47 48 49 4A 4B 4C 4D 4E 4F 50 51 52 53 54 55 56 57 58 59 5A
    # 5B 5C 5D 5E 5F 60 61 62 63 64 ...>

method subbuf

multi method subbuf(Int $from, Int $len = self.elems --> Blob:D)
    multi method subbuf(Range $range --> Blob:D)
    multi method subbuf(Blob:D: &From)
    multi method subbuf(Blob:D: Int:D $From, &End)
    multi method subbuf(Blob:D: &From, &End)
    multi method subbuf(Blob:D: \from, Whatever)
    multi method subbuf(Blob:D: \from, Numeric \length)

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(2, 4);    # 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 allocate

multi method allocate(Blob:U: Int:D $elements)
    multi method allocate(Blob:U: Int:D $elements, int $value)
    multi method allocate(Blob:U: Int:D $elements, Int:D \value)
    multi method allocate(Blob:U: Int:D $elements, Mu:D $got)
    multi method allocate(Blob:U: Int:D $elements, int @values)
    multi method allocate(Blob:U: Int:D $elements, Blob:D $blob)
    multi method allocate(Blob:U: Int:D $elements, @values)

Returns a newly created Blob object with the given number of elements. Optionally takes a second argument that indicates the pattern with which to fill the Blob: this can be a single (possibly native) integer value, or any Iterable that generates integer values, including another Blob. The pattern will be repeated if not enough values are given to fill the entire Blob.

my Blob $b0 = Blob.allocate(10,0);
    $b0.say; # OUTPUT: «Blob:0x<00 00 00 00 00 00 00 00 00 00>␤»

If the pattern is a general Mu value, it will fail.

routine unpack

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

use experimental :pack;

multi method unpack(Blob:D: Str:D $template)
    multi method unpack(Blob:D: @template)
    multi        unpack(Blob:D \blob, Str:D $template)
    multi        unpack(Blob:D \blob, @template)

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" (BigEndian) byte order into a single integer
N Extracts four elements and combines them in "network" (BigEndian) 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;

multi pack(Str $template, *@items)
multi pack(@template, *@items)

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

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

Returns a Blob with all elements in reversed order.

say Blob.new([1, 2, 3]).reverse;    # OUTPUT: «Blob:0x<03 02 01>␤»
    say blob16.new([2]).reverse;        # OUTPUT: «Blob[uint16]:0x<02>␤»
    say blob32.new([16, 32]).reverse;   # OUTPUT: «Blob[uint32]:0x<20 10>␤»

Methods on blob8 only (6.d, 2018.12 and later)

These methods are available on the blob8 (and buf8) types only. They allow low level access to reading bytes from the underlying data and interpreting them in different ways with regards to type (integer or floating point (num)), size (8, 16, 32, 64 or 128 bits), signed or unsigned (for integer values) and endianness (native, little and big endianness). The returned values are always expanded to a 64 bit native value where possible, and to a (big) integer value if that is not possible.

Endianness must be indicated by using values of the Endian enum as the second parameter to these methods. If no endianness is specified, NativeEndian will be assumed. Other values are LittleEndian and BigEndian.

method read-uint8

method read-uint8(blob8:D: uint $pos, $endian = NativeEndian --> uint)

Returns an unsigned native integer value for the byte at the given position. The $endian parameter has no meaning, but is available for consistency.

method read-int8

method read-int8(blob8:D: uint $pos, $endian = NativeEndian --> int)

Returns a native int value for the byte at the given position. The $endian parameter has no meaning, but is available for consistency.

method read-uint16

method read-uint16(blob8:D: uint $pos, $endian = NativeEndian --> uint)

Returns a native uint value for the two bytes starting at the given position.

method read-int16

method read-int16(blob8:D: uint $pos, $endian = NativeEndian --> int)

Returns a native int value for the two bytes starting at the given position.

method read-uint32

method read-uint32(blob8:D: uint $pos, $endian = NativeEndian --> uint)

Returns a native uint value for the four bytes starting at the given position.

method read-int32

method read-int32(blob8:D: uint $pos, $endian = NativeEndian --> int)

Returns a native int value for the four bytes starting at the given position.

method read-uint64

method read-uint64(blob8:D: uint $pos, $endian = NativeEndian --> UInt:D)

Returns an unsigned integer value for the eight bytes starting at the given position.

method read-int64

method read-int64(blob8:D: uint $pos, $endian = NativeEndian --> int)

Returns a native int value for the eight bytes starting at the given position.

method read-uint128

method read-uint128(blob8:D: uint $pos, $endian = NativeEndian --> UInt:D)

Returns an unsigned integer value for the sixteen bytes starting at the given position.

method read-int128

method read-int128(blob8:D: uint $pos, $endian = NativeEndian --> Int:D)

Returns an integer value for the sixteen bytes starting at the given position.

method read-num32

method read-num32(blob8:D: uint $pos, $endian = NativeEndian --> int)

Returns a native num value for the four bytes starting at the given position.

method read-num64

method read-num64(blob8:D: uint $pos, $endian = NativeEndian --> int)

Returns a native num value for the eight bytes starting at the given position.

Methods on blob8 only (6.d, 2019.03 and later)

method read-ubits

method read-ubits(blob8:D: uint $pos, uint $bits --> UInt:D)

Returns an unsigned integer value for the bits from the given bit offset and given number of bits. The endianness of the bits is assumed to be BigEndian.

method read-bits

method read-bits(blob8:D: uint $pos, uint $bits --> Int:D)

Returns a signed integer value for the bits from the given bit offset and given number of bits. The endianness of the bits is assumed to be BigEndian.

method Buf

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

Available as of the 2021.06 Rakudo compiler release.

Coerces the invocant into a mutable Buf object.