role Buf
role Buf[::T = uint8] does Blob[T] is repr('VMArray') is array_type(T){ ... }
A Buf does the role of a mutable sequence of (usually unsigned) integers.
my $bĂș = Buf.new(1, 2, 3);
$bĂș[1] = 42;
say $bĂș.raku; # OUTPUT: «Buf.new(1,42,3)â€Â»
However, it's a parameterized type, and you can instantiate with several integer types:
my $bĂș = Buf[int32].new(3, -3, 0xff32, -44);
say $bĂș; # OUTPUT: «Buf[int32]:0x<03 -3 FF32 -2C>â€Â»
By default, Buf uses 8-bit unsigned integers, that is, it is
equivalent to Buf[uint8]. Some other 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 these the same way you would with Buf:
my $bĂș = buf8.new(3, 6, 254);
say $bĂș; # OUTPUT: «Buf[uint8]:0x<03 06 fe>â€Â»
There are some methods on other objects, e.g.
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 - $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:
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)â€Â»
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Ăș.raku; # 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(123, 123);
say $bĂș.raku; # OUTPUT: «Buf.new(123, 123)â€Â»
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:
my Buf $bĂș .= new(1,2,3);
subbuf-rw($bĂș,2,1) = Buf.new(42);
say $bĂș.raku; # OUTPUT: «Buf.new(1,2,42)â€Â»
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
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Ăș.raku; # OUTPUT: «Buf.new(0,1,2,3,4)â€Â»
$bĂș = Buf.new( 1..3 );
$bĂș.reallocate( 10 );
say $bĂș.raku; # OUTPUT: «Buf.new(1,2,3,0,0,0,0,0,0,0)â€Â»
method list
multi method list(Buf:D:)
Returns a List of integers.
say Buf.new(122,105,112,205).list; # OUTPUT: «(122 105 112 205)â€Â»
method push
method push( $elems )
Adds elements at the end of the buffer.
my $bĂș = Buf.new( 1, 1, 2, 3, 5 );
$bĂș.push( 8 );
say $bĂș.raku; # OUTPUT: «Buf.new(1,1,2,3,5,8)â€Â»
method pop
method pop()
Returns and removes the last element of the buffer.
my $bĂș = Buf.new( 1, 1, 2, 3, 5 );
say $bĂș.pop(); # OUTPUT: «5â€Â»
say $bĂș.raku; # OUTPUT: «Buf.new(1,1,2,3)â€Â»
method append
method append( $elems )
Appends to the end of the buffer.
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)â€Â»
method prepend
method prepend( $elems )
Inserts elements at the beginning of the buffer.
my $bĂș = Buf.new( 1, 1, 2, 3, 5 );
$bĂș.prepend( 0 );
say $bĂș.raku; # OUTPUT: «Buf.new(0,1,1,2,3,5)â€Â»
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.
my $bĂș = Buf.new( 1, 1, 2, 3, 5 );
say $bĂș.shift(); # OUTPUT: «1â€Â»
say $bĂș.raku; # OUTPUT: «Buf.new(1,2,3,5)â€Â»
method unshift
method unshift()
Inserts elements at the beginning of the buffer.
my $bĂș = Buf.new( 1, 1, 2, 3, 5 );
$bĂș.unshift( 0 );
say $bĂș.raku; # OUTPUT: «Buf.new(0,1,1,2,3,5)â€Â»
method splice
method splice( Buf:D: $start = 0, $elems?, *@replacement --> Buf)
Substitutes elements of the buffer by other elements, returning a buffer with the removed elements.
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)â€Â»
Methods on buf8 only (6.d, 2018.12 and later)
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
and big endianness). These methods always return Nil.
Endianness must be indicated by using values of the Endian
enum as the third parameter to these methods. If no endianness is
specified, NativeEndian will be assumed. Other values are
LittleEndian and BigEndian.
The buffer will be automatically resized to support any bytes being written if it is not large enough yet.
method write-uint8
method write-uint8(buf8:D: uint $pos, uint8 $value, $endian = NativeEndian --> 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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
Writes a native num64 IEEE floating point value at the given position with
the given endianness.
Methods on buf8 only (6.d, 2019.03 and later)
method write-ubits
method write-ubits(buf8:D: uint $pos, uint $bits, UInt:D $value --> 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)
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.
Methods on buf8 only (6.d, 2019.10 and later)
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
and big endianness).
These methods can also be called on the buf8 type object, in which case
a new buf8 object will be returned. Otherwise, the invocant will be
returned to allow for easier chaining of operations on the buf8 object.
The buffer will be automatically resized to support any bytes being written
if it is not large enough yet.
Endianness must be indicated by using values of the Endian
enum as the third parameter to these methods. If no endianness is
specified, NativeEndian will be assumed. Other values are
LittleEndian and BigEndian.
method write-uint8
method write-uint8(buf8: uint $pos, uint8 $value, $endian = NativeEndian --> 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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
Available as of the 2021.06 Rakudo compiler release.
Coerces the invocant into an immutable Blob object.