Rules / Types, classes & roles / composite

Buf Reference

Mutable buffer for binary data

What it is #

enum as the B<third> parameter to these methods.  If no endianness is

Routines #

Signatures are reproduced from the documentation, including their declared return types. A routine listed here is part of the type's published interface; whether Raku++ implements it is a separate question, answered by the examples below.

method subbuf-rw #

method subbuf-rw($from = 0, $elems = self.elems - $from) is 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: In the case the $elems argument is not specified, the substitution

routine subbuf-rw #

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

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

method reallocate #

method reallocate(Buf:D: Int:D $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

method list #

multi method list(Buf:D:)

Returns a List of integers.

method push #

method push( $elems )

Adds elements at the end of the buffer.

method pop #

method pop()

Returns and removes the last element of the buffer.

method append #

method append( $elems )

Appends to the end of the buffer.

method prepend #

method prepend( $elems )

Inserts elements at the beginning of the buffer. Duplicated from Array.prepend The difference from method unshift is that if you prepend a single array or list argument, prepend will flatten that array / list, whereas unshift prepends the list / array as just a single element.

method shift #

method shift()

Removes and returns the first element of the buffer.

method unshift #

method unshift()

Inserts elements at the beginning of the buffer.

method splice #

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

Returns Buf.

Substitutes elements of the buffer by other elements, returning a buffer with the removed elements. These methods are available on the buf8 type only. They allow low level access to writing bytes to the underlying data and 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

method write-uint8 #

method write-uint8(buf8:D: uint $pos, uint8 $value, $endian = NativeEndian --> Nil)

Returns Nil.

Writes an unsigned 8-bit integer value at the given position. The $endian parameter has no meaning, but is available for consistency.

method write-int8 #

method write-int8(buf8:D: uint $pos, int8 $value, $endian = NativeEndian --> Nil)

Returns Nil.

Writes a signed 8-bit integer value at the given position. The $endian parameter has no meaning, but is available for consistency.

method write-uint16 #

method write-uint16(buf8:D: uint $pos, uint16 $value, $endian = NativeEndian --> Nil)

Returns Nil.

Writes an unsigned 16-bit integer value at the given position with the given endianness.

method write-int16 #

method write-int16(buf8:D: uint $pos, int16 $value, $endian = NativeEndian --> Nil)

Returns Nil.

Writes a signed 16-bit integer value at the given position with the given endianness.

method write-uint32 #

method write-uint32(buf8:D: uint $pos, uint32 $value, $endian = NativeEndian --> Nil)

Returns Nil.

Writes an unsigned 32-bit integer value at the given position with the given endianness.

method write-int32 #

method write-int32(buf8:D: uint $pos, int32 $value, $endian = NativeEndian --> Nil)

Returns Nil.

Writes a signed 32-bit integer value at the given position with the given endianness.

method write-uint64 #

method write-uint64(buf8:D: uint $pos, uint64 $value, $endian = NativeEndian --> Nil)

Returns Nil.

Writes an unsigned 64-bit integer value at the given position with the given endianness.

method write-int64 #

method write-int64(buf8:D: uint $pos, Int:D $value, $endian = NativeEndian --> Nil)

Returns Nil.

Writes a signed 64-bit integer value at the given position with the given endianness.

method write-uint128 #

method write-uint128(buf8:D: uint $pos, UInt:D $value, $endian = NativeEndian --> Nil)

Returns Nil.

Writes an unsigned 128-bit integer value at the given position with the given endianness.

method write-int128 #

method write-int128(buf8:D: uint $pos, Int:D $value, $endian = NativeEndian --> Nil)

Returns Nil.

Writes a signed 128-bit integer value at the given position with the given endianness.

method write-num32 #

method write-num32(buf8:D: uint $pos, num32 $value, $endian = NativeEndian --> Nil)

Returns Nil.

Writes a native num32 IEEE floating point value at the given position with the given endianness.

method write-num64 #

method write-num64(buf8:D: uint $pos, num64 $value, $endian = NativeEndian --> Nil)

Returns Nil.

Writes a native num64 IEEE floating point value at the given position with the given endianness.

method write-ubits #

method write-ubits(buf8:D: uint $pos, uint $bits, UInt:D $value --> Nil)

Returns Nil.

Writes an unsigned integer value to the bits from the given bit offset and given number of bits. The endianness of the bits is assumed to be BigEndian. Always returns Nil.

method write-bits #

method write-bits(buf8:D: uint $pos, uint $bits, Int:D $value --> Nil)

Returns Nil.

Writes 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. Always returns Nil. These methods are available on the buf8 type only. They allow low level access to writing bytes to the underlying data and in different ways with regards to type (integer or floating point (num)), size (8, 16, 32, 64 or 128

method write-uint8 #

method write-uint8(buf8: uint $pos, uint8 $value, $endian = NativeEndian --> buf8:D)

Returns buf8:D.

Writes an unsigned 8-bit integer value at the given position. The $endian parameter has no meaning, but is available for consistency.

method write-int8 #

method write-int8(buf8: uint $pos, int8 $value, $endian = NativeEndian --> buf8:D)

Returns buf8:D.

Writes a signed 8-bit integer value at the given position. The $endian parameter has no meaning, but is available for consistency.

method write-uint16 #

method write-uint16(buf8: uint $pos, uint16 $value, $endian = NativeEndian --> buf8:D)

Returns buf8:D.

Writes an unsigned 16-bit integer value at the given position with the given endianness.

method write-int16 #

method write-int16(buf8: uint $pos, int16 $value, $endian = NativeEndian --> buf8:D)

Returns buf8:D.

Writes a signed 16-bit integer value at the given position with the given endianness.

method write-uint32 #

method write-uint32(buf8: uint $pos, uint32 $value, $endian = NativeEndian --> buf8:D)

Returns buf8:D.

Writes an unsigned 32-bit integer value at the given position with the given endianness.

method write-int32 #

method write-int32(buf8: uint $pos, int32 $value, $endian = NativeEndian --> buf8:D)

Returns buf8:D.

Writes a signed 32-bit integer value at the given position with the given endianness.

method write-uint64 #

method write-uint64(buf8: uint $pos, uint64 $value, $endian = NativeEndian --> buf8:D)

Returns buf8:D.

Writes an unsigned 64-bit integer value at the given position with the given endianness.

method write-int64 #

method write-int64(buf8: uint $pos, Int:D $value, $endian = NativeEndian --> buf8:D)

Returns buf8:D.

Writes a signed 64-bit integer value at the given position with the given endianness.

method write-uint128 #

method write-uint128(buf8: uint $pos, UInt:D $value, $endian = NativeEndian --> buf8:D)

Returns buf8:D.

Writes an unsigned 128-bit integer value at the given position with the given endianness.

method write-int128 #

method write-int128(buf8: uint $pos, Int:D $value, $endian = NativeEndian --> buf8:D)

Returns buf8:D.

Writes a signed 128-bit integer value at the given position with the given endianness.

method write-num32 #

method write-num32(buf8: uint $pos, num32 $value, $endian = NativeEndian --> buf8:D)

Returns buf8:D.

Writes a native num32 IEEE floating point value at the given position with the given endianness.

method write-num64 #

method write-num64(buf8: uint $pos, num64 $value, $endian = NativeEndian --> buf8:D)

Returns buf8:D.

Writes a native num64 IEEE floating point value at the given position with the given endianness.

method write-ubits #

method write-ubits(buf8: uint $pos, uint $bits, UInt:D $value --> buf8:D)

Returns buf8:D.

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

method write-bits #

method write-bits(buf8: uint $pos, uint $bits, Int:D $value --> buf8:D)

Returns buf8:D.

Writes 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 Blob #

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

Returns Blob:D.

Available as of the 2021.06 Rakudo compiler release. Coerces the invocant into an immutable Blob object.

Examples, run three ways #

Every example below comes from the official documentation, together with the output that documentation asserts. Each was then executed by Rakudo and by Raku++ when this page was built. Where the three agree, one result is shown; where they do not, all three are — because which of them is wrong is exactly the information worth having.

1 all-differ · 2 doc-drift · 1 no-output · 1 not-runnable · 11 ok · 2 rakupp-differs

role Buf[::T = uint8] does Blob[T] is repr('VMArray') is array_type(T){ ... }

Not executed: the documentation states no expected output for this example.

my $bú = Buf.new(1, 2, 3);
$bú[1] = 42;
say $bú.raku; # OUTPUT: «Buf.new(1,42,3)␤»
Documentation
Buf.new(1,42,3)
Rakudo
Buf.new(1,42,3)
Raku++
[Any, 42]

Raku++ disagrees with both the documentation and Rakudo — a defect.

my $bú = Buf[int32].new(3, -3, 0xff32, -44);
say $bú; # OUTPUT: «Buf[int32]:0x<03 -3 FF32 -2C>␤»
Documentation
Buf[int32]:0x<03 -3 FF32 -2C>
Rakudo
Buf[int32]:0x<00000003 FFFFFFFD 0000FF32 FFFFFFD4>
Raku++
Buf[uint32]:0x<00000003 FFFFFFFD 0000FF32 FFFFFFD4>

All three differ. Needs a human.

Not yet examined. Which of these is correct has not been established — do not treat either engine as settled here.

my $bú = buf8.new(3, 6, 254);
say $bú; # OUTPUT: «Buf[uint8]:0x<03 06 fe>␤»
Documentation
Buf[uint8]:0x<03 06 fe>
Rakudo
Buf[uint8]:0x<03 06 FE>
Raku++
Buf[uint8]:0x<03 06 FE>

Both engines agree; the documentation states something else. Trust the engines.

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

Documentation, Rakudo and Raku++ all agree.

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

Documentation, Rakudo and Raku++ all agree.

my Buf $bú .= new(0..5);
$bú.subbuf-rw = Buf.new(123, 123);
say $bú.raku;   # OUTPUT: «Buf.new(123, 123)␤»
Documentation
Buf.new(123, 123)
Rakudo
Buf.new(123,123)
Raku++
Buf.new(123,123)

Both engines agree; the documentation states something else. Trust the engines.

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

Documentation, Rakudo and Raku++ all agree.

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

Documentation, Rakudo and Raku++ all agree.

$bú = Buf.new( 1..3 );
$bú.reallocate( 10 );
say $bú.raku; # OUTPUT: «Buf.new(1,2,3,0,0,0,0,0,0,0)␤»

Neither engine can run this in isolation — the example depends on context from the surrounding text.

say Buf.new(122,105,112,205).list; # OUTPUT: «(122 105 112 205)␤»
Output
(122 105 112 205)

Documentation, Rakudo and Raku++ all agree.

 my $bú = Buf.new( 1, 1, 2, 3, 5 );
 $bú.push( 8 );
 say $bú.raku; # OUTPUT: «Buf.new(1,1,2,3,5,8)␤»
Output
Buf.new(1,1,2,3,5,8)

Documentation, Rakudo and Raku++ all agree.

 my $bú = Buf.new( 1, 1, 2, 3, 5 );
 say $bú.pop(); # OUTPUT: «5␤»
 say $bú.raku;  # OUTPUT: «Buf.new(1,1,2,3)␤»
Output
5
Buf.new(1,1,2,3)

Documentation, Rakudo and Raku++ all agree.

 my $bú = Buf.new( 1, 1, 2, 3, 5 );
 $bú.append(9, 8, 7, 6);
 say $bú.raku; # OUTPUT: «Buf.new(1,1,2,3,5,9,8,7,6)␤»
Output
Buf.new(1,1,2,3,5,9,8,7,6)

Documentation, Rakudo and Raku++ all agree.

my $bú = Buf.new( 1, 1, 2, 3, 5 );
$bú.prepend( 0 );
say $bú.raku; # OUTPUT: «Buf.new(0,1,1,2,3,5)␤»
Output
Buf.new(0,1,1,2,3,5)

Documentation, Rakudo and Raku++ all agree.

my $bú = Buf.new( 1, 1, 2, 3, 5 );
say $bú.shift(); # OUTPUT: «1␤»
say $bú.raku;    # OUTPUT: «Buf.new(1,2,3,5)␤»
Output
1
Buf.new(1,2,3,5)

Documentation, Rakudo and Raku++ all agree.

my $bú = Buf.new( 1, 1, 2, 3, 5 );
$bú.unshift( 0 );
say $bú.raku; # OUTPUT: «Buf.new(0,1,1,2,3,5)␤»
Output
Buf.new(0,1,1,2,3,5)

Documentation, Rakudo and Raku++ all agree.

my $bú = Buf.new( 1, 1, 2, 3, 5 );
say $bú.splice:  0, 3, <3 2 1>;  # OUTPUT: «Buf:0x<01 01 02>␤»
say $bú.raku;                    # OUTPUT: «Buf.new(3,2,1,3,5)␤»
Documentation
Buf:0x<01 01 02>
Buf.new(3,2,1,3,5)
Rakudo
Buf:0x<01 01 02>
Buf.new(3,2,1,3,5)
Raku++

Raku++ disagrees with both the documentation and Rakudo — a defect.