Buf.pod6

=begin pod

=TITLE role Buf

=SUBTITLE Mutable buffer for binary data

    role Buf[::T] does Blob[T] { ... }

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

    my $b = Buf.new(1, 2, 3);
    $b[1] = 42;

Some types of C<Buf>s which are used often get their own class name.

X<|buf8>X<|buf16>X<|buf32>X<|buf64>
=begin table
buf8 | Buf[uint8]
buf16 | Buf[uint16]
buf32 | Buf[uint32]
buf64 | Buf[uint64]
=end table

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

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

Plus there are some object methods, like
L<C<encode>|/type/Str#method_encode> that might return a C<buf8> in some
cases where it is the best representation for a particular encoding.

=head1 Methods

=head2 method subbuf-rw

    method subbuf-rw($from = 0, $elems = self.elems - $from) is rw

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

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

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


In the case the C<$elems> argument is not specified, the substitution
happens at the specified index C<$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 C<$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(123, 123);
    say $b.perl;   # OUTPUT: «Buf.new(123, 123)␤»

=head2 routine subbuf-rw

Declared as

    multi sub subbuf-rw(Buf:D \b) is rw
    multi sub subbuf-rw(Buf:D \b, Int() $from) is rw
    multi sub subbuf-rw(Buf:D \b, $from, $elems) is rw

Returns a writable reference to a part of a buffer.
Invokes the C<subbuf-rw> method on the specified C<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)␤»

=head2 method reallocate

    method reallocate($elems)

Change the number of elements of the C<Buf>, returning the changed
C<Buf>. The size of C<Buf> will be adapted depending on the number of
C<$elems> specified: if it is smaller than the actual size of the C<Buf>
the resulting C<Buf> will be shrunk down, otherwise it will be enlarged
to fit the number of C<$elems>. In the case the C<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.new( 1..3 );
    $b.reallocate( 10 );
    $b.perl.say; # OUTPUT: «Buf.new(1,2,3,0,0,0,0,0,0,0)␤»

=head2 method push

    method push( $elems )

Adds elements at the end of the buffer

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

=head2 method pop

    method pop()

Extracts the last element of the buffer

    =for code :skip-test
    say $bú.pop(); # OUTPUT: «8»
    say $bú.perl; # OUTPUT: «Buf.new(1,1,2,3,5)»

=head2 method append

    method append( $elems )

Appends at the end of the buffer

    =for code :skip-test
    $bú.append( @φ[5..10] );
    say $bú.perl; # OUTPUT: «Buf.new(1,1,2,3,5,8,13,21,34,55,89)»

=head2 method prepend

    method prepend( $elems )

Adds elements at the beginning of the buffer

    =for code :skip-test
    $bú.prepend( 0 );
    say $bú.perl; # OUTPUT: «Buf.new(0,1,1,2,3,5,8,13,21,34,55,89)»

=head2 method shift

    method shift()

Takes out the first element of the buffer

    =for code :skip-test
    $bú.shift();
    say $bú.perl; # OUTPUT: «Buf.new(1,1,2,3,5,8,13,21,34,55,89)»

=head2 method unshift

    method unshift()

Adds elements at the beginning of the buffer

    =for code :skip-test
    $bú.unshift( 0 );
    say $bú.perl; # OUTPUT: «Buf.new(0,1,1,2,3,5,8,13,21,34,55,89)»

=head2 method splice

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

Substitutes elements of the buffer by other elements

    =for code :skip-test
    $bú.splice:  0, 3, <3 2 1>;
    say $bú.perl; # OUTPUT: «Buf.new(3,2,1,2,3,5,8,13,21,34,55,89)»

=end pod

# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6