role Buf

Mutable buffer for binary data

role Buf[::Tdoes Blob[T{ ... }

A Buf is a mutable sequence of (usually unsigned) integers.

my $b = Buf.new(123);
$b[1= 42;

Some types of Bufs which are used often get their own class name.

buf8 Buf[uint8]
buf16 Buf[uint16]
buf32 Buf[uint32]
buf64 Buf[uint64]

You can use this in pretty much the same way you would with Buf:

my $buf = buf8.new(3,6254);
say $buf# OUTPUT: «Buf[uint8]:0x<03 06 fe>␤» 

Plus there are some object methods, like encode that might return a buf8 in some cases where it is the best representation for a particular encoding.

Methods

method subbuf-rw

method subbuf-rw($from = 0$elems = self.elems - $fromis rw

A mutable version of subbuf that returns a Proxy functioning as a writable reference to a part of a buffer. Its first argument, $from specifies the index in the buffer from which a substitution should occur, and its last argument, $elems specifies how many elements are to be replaced.

For example, to replace one element at index 3 with two elements, 100 and 101:

my Buf $b .= new(0..5);
$b.subbuf-rw(3,1= Buf.new(100101);
say $b.perl;   # OUTPUT: «Buf.new(0,1,2,100,101,4,5)␤» 

In the case the $elems argument is not specified, the substitution happens at the specified index $from removing all trailing elements:

my Buf $b .= new(0..5);
$b.subbuf-rw(3= Buf.new(200);
say $b.perl;   # OUTPUT: «Buf.new(0,1,2,200)␤» 

In the case the $from argument is not specified, the substitution happens from the very beginning of the buffer:

my Buf $b .= new(0..5);
$b.subbuf-rw = Buf.new(123123);
say $b.perl;   # OUTPUT: «Buf.new(123, 123)␤» 

routine subbuf-rw

Declared as

multi sub subbuf-rw(Buf:D \bis rw
multi sub subbuf-rw(Buf:D \bInt() $fromis rw
multi sub subbuf-rw(Buf:D \b$from$elemsis rw

Returns a writable reference to a part of a buffer. Invokes the subbuf-rw method on the specified Buf:

my Buf $b .= new(1,2,3);
subbuf-rw($b,2,1= Buf.new(42);
say $b.perl;   # OUTPUT: «Buf.new(1,2,42)␤» 

method reallocate

method reallocate($elems)

Change the number of elements of the Buf, returning the changed Buf. The size of Buf will be adapted depending on the number of $elems specified: if it is smaller than the actual size of the Buf the resulting Buf will be shrunk down, otherwise it will be enlarged to fit the number of $elems. In the case the Buf is enlarged, newly created items will be assigned a Virtual Machine specific null value, therefore you should not rely upon their value since it could be inconsistent across different virtual machines.

my Buf $b .= new(^10);
$b.reallocate(5);
say $b.perl;  # OUTPUT: «Buf.new(0,1,2,3,4)␤» 
 
$b = Buf.new1..3 );
$b.reallocate10 );
$b.perl.say# OUTPUT: «Buf.new(1,2,3,0,0,0,0,0,0,0)␤» 

method push

method push$elems )

Adds elements at the end of the buffer

my @φ =  1,1* + * … ∞;
my $ = Buf.new@φ[^5] );
$.push@φ[5] );
say $.perl# OUTPUT: «Buf.new(1,1,2,3,5,8)» 

method pop

method pop()

Extracts the last element of the buffer

    say $.pop(); # OUTPUT: «8» 
    say $.perl# OUTPUT: «Buf.new(1,1,2,3,5)» 

method append

method append$elems )

Appends at the end of the buffer

    $.append@φ[5..10] );
    say $.perl# OUTPUT: «Buf.new(1,1,2,3,5,8,13,21,34,55,89)» 

method prepend

method prepend$elems )

Adds elements at the beginning of the buffer

    $.prepend0 );
    say $.perl# OUTPUT: «Buf.new(0,1,1,2,3,5,8,13,21,34,55,89)» 

method shift

method shift()

Takes out the first element of the buffer

    $.shift();
    say $.perl# OUTPUT: «Buf.new(1,1,2,3,5,8,13,21,34,55,89)» 

method unshift

method unshift()

Adds elements at the beginning of the buffer

    $.unshift0 );
    say $.perl# OUTPUT: «Buf.new(0,1,1,2,3,5,8,13,21,34,55,89)» 

method splice

method spliceBuf:D: $start = 0$elems?*@replacement --> Buf)

Substitutes elements of the buffer by other elements

    $.splice:  03, <3 2 1>;
    say $.perl# OUTPUT: «Buf.new(3,2,1,2,3,5,8,13,21,34,55,89)» 

Type Graph

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

Expand above chart

Routines supplied by role Blob

Buf does role Blob, which provides the following routines:

(Blob) method new

Defined as:

method new(*@codes)

Creates a Blob from a list of integers.

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

(Blob) 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␤» 

(Blob) method Capture

Defined as:

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

Equivalent to calling .List.Capture on the invocant.

(Blob) 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␤» 

(Blob) 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␤» 

(Blob) 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.

(Blob) method gist

Defined as:

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(123).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 ...> 

(Blob) 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>␤» 

(Blob) method allocate

Defined as:

multi method allocate($elems --> Blob:D)
multi method allocate($elems$pattern --> Blob:D)

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 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>␤» 

(Blob) 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)␤» 

(Blob) 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.

(Blob) 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>␤» 

Routines supplied by role Positional

Buf does role Positional, which provides the following routines:

(Positional) method of

method of()

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

(Positional) method elems

method elems()

Should return the number of available elements in the instantiated object.

(Positional) method AT-POS

method AT-POS(\position)

Should return the value / container at the given position.

(Positional) method EXISTS-POS

method EXISTS-POS(\position)

Should return a Bool indicating whether the given position actually has a value.

(Positional) method STORE

method STORE(\values:$initialize)

This method should only be supplied if you want to support the:

    my @a is Foo = 1,2,3;

syntax for binding your implementation of the Positional role.

Should accept the values to (re-)initialize the object with. The optional named parameter will contain a True value when the method is called on the object for the first time. Should return the invocant.