txt: ## buf.md
  role Buf
  
  Mutable buffer for binary data
  
  ```raku
  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.
  
  ```raku
  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:
  
  ```raku
  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 `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 the same way you would with `Buf`:
  
  ```raku
  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`](/type/Str#method_encode) that might return a `buf8` in some cases where it is the best representation for a particular encoding.
  
  # [Methods](#role_Buf "go to top of document")[§](#Methods "direct link")
  
  ## [method subbuf-rw](#role_Buf "go to top of document")[§](#method_subbuf-rw "direct link")
  
  ```raku
  method subbuf-rw($from = 0, $elems = self.elems - $from) is rw
  ```
  
  A mutable version of `subbuf` that returns a [`Proxy`](/type/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`:
  
  ```raku
  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:
  
  ```raku
  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:
  
  ```raku
  my Buf $bú .= new(0..5);
  $bú.subbuf-rw = Buf.new(123, 123);
  say $bú.raku;   # OUTPUT: «Buf.new(123, 123)␤»
  ```
  
  ## [routine subbuf-rw](#role_Buf "go to top of document")[§](#routine_subbuf-rw "direct link")
  
  ```raku
  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`:
  
  ```raku
  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](#role_Buf "go to top of document")[§](#method_reallocate "direct link")
  
  ```raku
  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.
  
  ```raku
  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](#role_Buf "go to top of document")[§](#method_list "direct link")
  
  ```raku
  multi method list(Buf:D:)
  ```
  
  Returns a [`List`](/type/List) of integers.
  
  ```raku
  say Buf.new(122,105,112,205).list; # OUTPUT: «(122 105 112 205)␤»
  ```
  
  ## [method push](#role_Buf "go to top of document")[§](#method_push "direct link")
  
  ```raku
  method push( $elems )
  ```
  
  Adds elements at the end of the buffer.
  
  ```raku
  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](#role_Buf "go to top of document")[§](#method_pop "direct link")
  
  ```raku
  method pop()
  ```
  
  Returns and removes the last element of the buffer.
  
  ```raku
  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](#role_Buf "go to top of document")[§](#method_append "direct link")
  
  ```raku
  method append( $elems )
  ```
  
  Appends to the end of the buffer.
  
  ```raku
  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](#role_Buf "go to top of document")[§](#method_prepend "direct link")
  
  ```raku
  method prepend( $elems )
  ```
  
  Inserts elements at the beginning of the buffer.
  
  ```raku
  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](#role_Buf "go to top of document")[§](#method_shift "direct link")
  
  ```raku
  method shift()
  ```
  
  Removes and returns the first element of the buffer.
  
  ```raku
  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](#role_Buf "go to top of document")[§](#method_unshift "direct link")
  
  ```raku
  method unshift()
  ```
  
  Inserts elements at the beginning of the buffer.
  
  ```raku
  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](#role_Buf "go to top of document")[§](#method_splice "direct link")
  
  ```raku
  method splice( Buf:D: $start = 0, $elems?, *@replacement --> Buf)
  ```
  
  Substitutes elements of the buffer by other elements, returning a buffer with the removed elements.
  
  ```raku
  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)](#role_Buf "go to top of document")[§](#Methods_on_buf8_only_(6.d,_2018.12_and_later) "direct link")
  
  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`](/type/Nil).
  
  Endianness must be indicated by using values of the [`Endian`](/type/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](#role_Buf "go to top of document")[§](#method_write-uint8 "direct link")
  
  ```raku
  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](#role_Buf "go to top of document")[§](#method_write-int8 "direct link")
  
  ```raku
  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](#role_Buf "go to top of document")[§](#method_write-uint16 "direct link")
  
  ```raku
  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](#role_Buf "go to top of document")[§](#method_write-int16 "direct link")
  
  ```raku
  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](#role_Buf "go to top of document")[§](#method_write-uint32 "direct link")
  
  ```raku
  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](#role_Buf "go to top of document")[§](#method_write-int32 "direct link")
  
  ```raku
  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](#role_Buf "go to top of document")[§](#method_write-uint64 "direct link")
  
  ```raku
  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](#role_Buf "go to top of document")[§](#method_write-int64 "direct link")
  
  ```raku
  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](#role_Buf "go to top of document")[§](#method_write-uint128 "direct link")
  
  ```raku
  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](#role_Buf "go to top of document")[§](#method_write-int128 "direct link")
  
  ```raku
  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](#role_Buf "go to top of document")[§](#method_write-num32 "direct link")
  
  ```raku
  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](#role_Buf "go to top of document")[§](#method_write-num64 "direct link")
  
  ```raku
  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)](#role_Buf "go to top of document")[§](#Methods_on_buf8_only_(6.d,_2019.03_and_later) "direct link")
  
  ## [method write-ubits](#role_Buf "go to top of document")[§](#method_write-ubits "direct link")
  
  ```raku
  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](#role_Buf "go to top of document")[§](#method_write-bits "direct link")
  
  ```raku
  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)](#role_Buf "go to top of document")[§](#Methods_on_buf8_only_(6.d,_2019.10_and_later) "direct link")
  
  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`](/type/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](#role_Buf "go to top of document")[§](#method_write-uint8_0 "direct link")
  
  ```raku
  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](#role_Buf "go to top of document")[§](#method_write-int8_0 "direct link")
  
  ```raku
  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](#role_Buf "go to top of document")[§](#method_write-uint16_0 "direct link")
  
  ```raku
  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](#role_Buf "go to top of document")[§](#method_write-int16_0 "direct link")
  
  ```raku
  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](#role_Buf "go to top of document")[§](#method_write-uint32_0 "direct link")
  
  ```raku
  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](#role_Buf "go to top of document")[§](#method_write-int32_0 "direct link")
  
  ```raku
  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](#role_Buf "go to top of document")[§](#method_write-uint64_0 "direct link")
  
  ```raku
  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](#role_Buf "go to top of document")[§](#method_write-int64_0 "direct link")
  
  ```raku
  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](#role_Buf "go to top of document")[§](#method_write-uint128_0 "direct link")
  
  ```raku
  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](#role_Buf "go to top of document")[§](#method_write-int128_0 "direct link")
  
  ```raku
  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](#role_Buf "go to top of document")[§](#method_write-num32_0 "direct link")
  
  ```raku
  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](#role_Buf "go to top of document")[§](#method_write-num64_0 "direct link")
  
  ```raku
  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](#role_Buf "go to top of document")[§](#method_write-ubits_0 "direct link")
  
  ```raku
  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](#role_Buf "go to top of document")[§](#method_write-bits_0 "direct link")
  
  ```raku
  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](#role_Buf "go to top of document")[§](#method_Blob "direct link")
  
  ```raku
  method Buf(Buf:D: --> Blob:D)
  ```
  
  Available as of the 2021.06 Rakudo compiler release.
  
  Coerces the invocant into an immutable [`Blob`](/type/Blob) object.
  
  # [Typegraph](# "go to top of document")[§](#typegraphrelations "direct link")
  
  Type relations for `Buf`
  
  
  
  raku-type-graph
  
  
  
  Buf
  Buf
  
  
  Blob
  Blob
  
  
  Buf->Blob
  
  
  
  Positional
  Positional
  
  
  Stringy
  Stringy
  
  
  Blob->Positional
  
  
  
  Blob->Stringy
  
  [Expand chart above](/assets/typegraphs/Buf.svg)
  