role Buf
Mutable buffer for binary data
[::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 = Buf.new(1, 2, 3);[1] = 42;
However, it's a parameterized type, and you can instantiate with several integer types:
my = Buf[int32].new( 3, -3, 0xff32, -44)# 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 Buf
s 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 in pretty much the same way you would with Buf
:
my = buf8.new(3,6, 254);say ; # 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( = 0, = self.elems - ) 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 .= new(0..5);.subbuf-rw(3,1) = Buf.new(100, 101);say .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 .= new(0..5);.subbuf-rw(3) = Buf.new(200);say .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 .= new(0..5);.subbuf-rw = Buf.new(123, 123);say .perl; # OUTPUT: «Buf.new(123, 123)»
routine subbuf-rw
Declared as
multi sub subbuf-rw(Buf \b) is rwmulti sub subbuf-rw(Buf \b, Int() ) is rwmulti sub subbuf-rw(Buf \b, , ) is rw
Returns a writable reference to a part of a buffer. Invokes the subbuf-rw
method on the specified Buf
:
my Buf .= new(1,2,3);subbuf-rw(,2,1) = Buf.new(42);say .perl; # OUTPUT: «Buf.new(1,2,42)»
method reallocate
method reallocate()
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 .= new(^10);.reallocate(5);say .perl; # OUTPUT: «Buf.new(0,1,2,3,4)»= Buf.new( 1..3 );.reallocate( 10 );.perl.say; # OUTPUT: «Buf.new(1,2,3,0,0,0,0,0,0,0)»
method list
Defined as:
multi method list(Buf:)
Returns a Seq
of codepoints.
say Buf.new(122,105,112,205).list; # OUTPUT: «(122 105 112 205)»
method push
method push( )
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( )
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( )
Adds elements at the beginning of the buffer
.prepend( 0 );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
.unshift( 0 );say .perl; # OUTPUT: «Buf.new(0,1,1,2,3,5,8,13,21,34,55,89)»
method splice
method splice( Buf: = 0, ?, * --> Buf)
Substitutes elements of the buffer by other elements
.splice: 0, 3, <3 2 1>;say .perl; # OUTPUT: «Buf.new(3,2,1,2,3,5,8,13,21,34,55,89)»
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
Defined as:
method write-uint8(buf8: uint , uint8 , = 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
Defined as:
method write-int8(buf8: uint , int8 , = 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
Defined as:
method write-uint16(buf8: uint , uint16 , = NativeEndian --> Nil)
Writes an unsigned 16-bit integer value at the given position with the given endianness.
method write-int16
Defined as:
method write-int16(buf8: uint , int16 , = NativeEndian --> Nil)
Writes a signed 16-bit integer value at the given position with the given endianness.
method write-uint32
Defined as:
method write-uint32(buf8: uint , uint32 , = NativeEndian --> Nil)
Writes an unsigned 32-bit integer value at the given position with the given endianness.
method write-int32
Defined as:
method write-int32(buf8: uint , int32 , = NativeEndian --> Nil)
Writes a signed 32-bit integer value at the given position with the given endianness.
method write-uint64
Defined as:
method write-uint64(buf8: uint , uint64 , = NativeEndian --> Nil)
Writes an unsigned 64-bit integer value at the given position with the given endianness.
method write-int64
Defined as:
method write-int64(buf8: uint , Int , = NativeEndian --> Nil)
Writes a signed 64-bit integer value at the given position with the given endianness.
method write-uint128
Defined as:
method write-uint128(buf8: uint , UInt , = NativeEndian --> Nil)
Writes an unsigned 128-bit integer value at the given position with the given endianness.
method write-int128
Defined as:
method write-int128(buf8: uint , Int , = NativeEndian --> Nil)
Writes a signed 128-bit integer value at the given position with the given endianness.
method write-num32
Defined as:
method write-num32(buf8: uint , num32 , = NativeEndian --> Nil)
Writes a native num32
IEEE floating point value at the given position with the given endianness.
method write-num64
Defined as:
method write-num64(buf8: uint , num64 , = 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
Defined as:
method write-ubits(buf8: uint , uint , UInt --> 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
Defined as:
method write-bits(buf8: uint , uint , Int --> 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
Defined as:
method write-uint8(buf8: uint , uint8 , = NativeEndian --> buf8)
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
Defined as:
method write-int8(buf8: uint , int8 , = NativeEndian --> buf8)
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
Defined as:
method write-uint16(buf8: uint , uint16 , = NativeEndian --> buf8)
Writes an unsigned 16-bit integer value at the given position with the given endianness.
method write-int16
Defined as:
method write-int16(buf8: uint , int16 , = NativeEndian --> buf8)
Writes a signed 16-bit integer value at the given position with the given endianness.
method write-uint32
Defined as:
method write-uint32(buf8: uint , uint32 , = NativeEndian --> buf8)
Writes an unsigned 32-bit integer value at the given position with the given endianness.
method write-int32
Defined as:
method write-int32(buf8: uint , int32 , = NativeEndian --> buf8)
Writes a signed 32-bit integer value at the given position with the given endianness.
method write-uint64
Defined as:
method write-uint64(buf8: uint , uint64 , = NativeEndian --> buf8)
Writes an unsigned 64-bit integer value at the given position with the given endianness.
method write-int64
Defined as:
method write-int64(buf8: uint , Int , = NativeEndian --> buf8)
Writes a signed 64-bit integer value at the given position with the given endianness.
method write-uint128
Defined as:
method write-uint128(buf8: uint , UInt , = NativeEndian --> buf8)
Writes an unsigned 128-bit integer value at the given position with the given endianness.
method write-int128
Defined as:
method write-int128(buf8: uint , Int , = NativeEndian --> buf8)
Writes a signed 128-bit integer value at the given position with the given endianness.
method write-num32
Defined as:
method write-num32(buf8: uint , num32 , = NativeEndian --> buf8)
Writes a native num32
IEEE floating point value at the given position with the given endianness.
method write-num64
Defined as:
method write-num64(buf8: uint , num64 , = NativeEndian --> buf8)
Writes a native num64
IEEE floating point value at the given position with the given endianness.
method write-ubits
Defined as:
method write-ubits(buf8: uint , uint , UInt --> buf8)
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
Defined as:
method write-bits(buf8: uint , uint , Int --> buf8)
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
.
Type Graph
Routines supplied by role Blob
Buf does role Blob, which provides the following routines:
(Blob) method new
Defined as:
multi method new(Blob:)multi method new(Blob: Blob )multi method new(Blob: int )multi method new(Blob: )multi method new(Blob: *)
Creates an empty Blob
, or a new Blob
from another Blob
, or from a list of integers or values (which will have to be coerced into integers):
my = Blob.new([1, 2, 3]);say Blob.new(<1 2 3>); # OUTPUT: «Blob:0x<01 02 03>»
(Blob) method Bool
Defined as:
multi method Bool(Blob:)
Returns False
if and only if the buffer is empty.
my = Blob.new();say .Bool; # OUTPUT: «False»= Blob.new([1, 2, 3]);say .Bool; # OUTPUT: «True»
(Blob) method Capture
Defined as:
method Capture(Blob)
Equivalent to calling .List.Capture
on the invocant.
(Blob) method elems
Defined as:
multi method elems(Blob:)multi method elems(Blob: --> 1)
Returns the number of elements of the buffer.
my = Blob.new([1, 2, 3]);say .elems; # OUTPUT: «3»
It will also return 1 on the class object.
(Blob) method bytes
Defined as:
method bytes(Blob: --> Int)
Returns the number of bytes used by the elements in the buffer.
say Blob.new([1, 2, 3]).bytes; # OUTPUT: «3»say blob16.new([1, 2, 3]).bytes; # OUTPUT: «6»say blob64.new([1, 2, 3]).bytes; # OUTPUT: «24»
(Blob) method chars
Defined as:
method chars(Blob:)
Throws X::Buf::AsStr
with chars
as payload.
(Blob) method Str
Defined as:
multi method Str(Blob:)
Throws X::Buf::AsStr
with Str
as payload. In order to convert to a Str
you need to use .decode
.
(Blob) method Stringy
Defined as:
multi method Stringy(Blob:)
Throws X::Buf::AsStr
with Stringy
as payload.
(Blob) method decode
Defined as:
multi method decode(Blob: = self.encoding // "utf-8")
multi method decode(Blob: , Str :!,Bool : = False)
multi method decode(Blob: , Bool : = False)
Applies an encoding to turn the blob into a Str; the encoding will be UTF-8 by default.
my Blob = "string".encode('utf-8');say .decode('utf-8'); # OUTPUT: «string»
On malformed utf-8 .decode
will throw X::AdHoc. To handle sloppy utf-8 use utf8-c8
.
(Blob) method list
Defined as:
multi method list(Blob:)
Returns the list of codepoints:
say "zipi".encode("ascii").list; # OUTPUT: «(122 105 112 105)»
(Blob) method gist
Defined as:
method gist(Blob: --> Str)
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(1, 2, 3).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 , Int = self.elems --> Blob)multi method subbuf(Range --> Blob)
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(2, 4); # 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(Blob: Int )multi method allocate(Blob: Int , int )multi method allocate(Blob: Int , Int \value)multi method allocate(Blob: Int , Mu )multi method allocate(Blob: Int , int )multi method allocate(Blob: Int , Blob )multi method allocate(Blob: Int , )
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 (possibly native) 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 = Blob.allocate(10,0);.say; # OUTPUT: «Blob:0x<00 00 00 00 00 00 00 00 00 00>»
If the pattern is a general Mu
value, it will fail.
(Blob) method unpack
This method is considered experimental, in order to use it you will need to do:
use experimental :pack;
Defined as:
multi method unpack(Blob: Str )multi method unpack(Blob: )multi sub unpack(Blob \blob, Str )multi sub unpack(Blob \blob, )
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" (BigEndian) byte order into a single integer |
N | Extracts four elements and combines them in "network" (BigEndian) 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;
multi sub pack(Str , *)multi sub pack(, *)
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: --> Blob)
Returns a Blob with all elements in reversed order.
say Blob.new([1, 2, 3]).reverse; # OUTPUT: «Blob:0x<03 02 01>»say blob16.new([2]).reverse; # OUTPUT: «Blob[uint16]:0x<02>»say buf32.new([16, 32]).reverse; # OUTPUT: «Buf[uint32]:0x<20 10>»
(Blob) method read-uint8
Defined as:
method read-uint8(blob8: uint , = NativeEndian --> uint)
Returns an unsigned native integer value for the byte at the given position. The $endian
parameter has no meaning, but is available for consistency.
(Blob) method read-int8
Defined as:
method read-int8(blob8: uint , = NativeEndian --> int)
Returns a native int
value for the byte at the given position. The $endian
parameter has no meaning, but is available for consistency.
(Blob) method read-uint16
Defined as:
method read-uint16(blob8: uint , = NativeEndian --> uint)
Returns a native uint
value for the two bytes starting at the given position.
(Blob) method read-int16
Defined as:
method read-int16(blob8: uint , = NativeEndian --> int)
Returns a native int
value for the two bytes starting at the given position.
(Blob) method read-uint32
Defined as:
method read-uint32(blob8: uint , = NativeEndian --> uint)
Returns a native uint
value for the four bytes starting at the given position.
(Blob) method read-int32
Defined as:
method read-int32(blob8: uint , = NativeEndian --> int)
Returns a native int
value for the four bytes starting at the given position.
(Blob) method read-uint64
Defined as:
method read-uint64(blob8: uint , = NativeEndian --> UInt)
Returns an unsigned integer value for the eight bytes starting at the given position.
(Blob) method read-int64
Defined as:
method read-int64(blob8: uint , = NativeEndian --> int)
Returns a native int
value for the eight bytes starting at the given position.
(Blob) method read-uint128
Defined as:
method read-uint128(blob8: uint , = NativeEndian --> UInt)
Returns an unsigned integer value for the sixteen bytes starting at the given position.
(Blob) method read-int128
Defined as:
method read-int128(blob8: uint , = NativeEndian --> Int)
Returns an integer value for the sixteen bytes starting at the given position.
(Blob) method read-num32
Defined as:
method read-num32(blob8: uint , = NativeEndian --> int)
Returns a native num
value for the four bytes starting at the given position.
(Blob) method read-num64
Defined as:
method read-num64(blob8: uint , = NativeEndian --> int)
Returns a native num
value for the eight bytes starting at the given position.
(Blob) method read-ubits
Defined as:
method read-ubits(blob8: uint , uint --> UInt)
Returns an unsigned 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
.
(Blob) method read-bits
Defined as:
method read-bits(blob8: uint , uint --> Int)
Returns 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
.
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, :)
This method should only be supplied if you want to support the:
my 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.