Permalink
Fetching contributors…
Cannot retrieve contributors at this time
178 lines (115 sloc) 4.7 KB
=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 :preamble<my $bú>
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 :preamble<my $bú; my @φ>
$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 :preamble<my $bú>
$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 :preamble<my $bú>
$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 :preamble<my $bú>
$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 :preamble<my $bú>
$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