txt: ## blob.md
  role Blob
  
  Immutable buffer for binary data ('Binary Large OBject')
  
  ```raku
  role Blob[::T = uint8] does Positional[T] does Stringy { }
  ```
  
  The `Blob` role is an immutable interface to binary types, and offers a list-like interface to lists of integers, typically unsigned integers.
  
  However, it's a parameterized type, and you can instantiate with several integer types:
  
  ```raku
  my $b = Blob[int32].new(3, -3, 0xff32, -44);
  say $b; # OUTPUT: «Blob[int32]:0x<03 -3 FF32 -2C>␤»
  
  ```
  
  By default, `Blob` uses 8-bit unsigned integers, that is, it is equivalent to Blob[uint8]. Some other types of `Blob`s which are used often get their own class name.
  
  |  |  |
  | --- | --- |
  | blob8 | Blob[uint8] |
  | blob16 | Blob[uint16] |
  | blob32 | Blob[uint32] |
  | blob64 | Blob[uint64] |
  
  You can use these in pretty much the same way you would with `Blob`:
  
  ```raku
  my $blob = blob8.new(3, 6, 254);
  say $blob; # OUTPUT: «Blob[uint8]:0x<03 06 FE>␤»
  ```
  
  # [Methods](#role_Blob "go to top of document")[§](#Methods "direct link")
  
  ## [method new](#role_Blob "go to top of document")[§](#method_new "direct link")
  
  ```raku
  multi method new(Blob:)
  multi method new(Blob: Blob:D $blob)
  multi method new(Blob: int @values)
  multi method new(Blob: @values)
  multi method new(Blob: *@values)
  ```
  
  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):
  
  ```raku
  my $blob = Blob.new([1, 2, 3]);
  say Blob.new(<1 2 3>); # OUTPUT: «Blob:0x<01 02 03>␤»
  ```
  
  ## [method Bool](#role_Blob "go to top of document")[§](#method_Bool "direct link")
  
  ```raku
  multi method Bool(Blob:D:)
  ```
  
  Returns `False` if and only if the buffer is empty.
  
  ```raku
  my $blob = Blob.new();
  say $blob.Bool; # OUTPUT: «False␤»
  $blob = Blob.new([1, 2, 3]);
  say $blob.Bool; # OUTPUT: «True␤»
  ```
  
  ## [method Capture](#role_Blob "go to top of document")[§](#method_Capture "direct link")
  
  ```raku
  method Capture(Blob:D:)
  ```
  
  Converts the object to a [`List`](/type/List) which is, in turn, coerced to a [`Capture`](/type/Capture).
  
  ## [method elems](#role_Blob "go to top of document")[§](#method_elems "direct link")
  
  ```raku
  multi method elems(Blob:D:)
  ```
  
  Returns the number of elements of the buffer.
  
  ```raku
  my $blob = Blob.new([1, 2, 3]);
  say $blob.elems; # OUTPUT: «3␤»
  ```
  
  ## [method bytes](#role_Blob "go to top of document")[§](#method_bytes "direct link")
  
  ```raku
  method bytes(Blob:D: --> Int:D)
  ```
  
  Returns the number of bytes used by the elements in the buffer.
  
  ```raku
  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␤»
  ```
  
  ## [method chars](#role_Blob "go to top of document")[§](#method_chars "direct link")
  
  ```raku
  method chars(Blob:D:)
  ```
  
  Throws [`X::Buf::AsStr`](/type/X/Buf/AsStr) with `chars` as payload.
  
  ## [method Str](#role_Blob "go to top of document")[§](#method_Str "direct link")
  
  ```raku
  multi method Str(Blob:D:)
  ```
  
  Throws [`X::Buf::AsStr`](/type/X/Buf/AsStr) with [`Str`](/type/Str) as payload. In order to convert to a [`Str`](/type/Str) you need to use [`.decode`](/routine/decode).
  
  ## [method Stringy](#role_Blob "go to top of document")[§](#method_Stringy "direct link")
  
  ```raku
  multi method Stringy(Blob:D:)
  ```
  
  Throws [`X::Buf::AsStr`](/type/X/Buf/AsStr) with [`Stringy`](/type/Stringy) as payload.
  
  ## [method decode](#role_Blob "go to top of document")[§](#method_decode "direct link")
  
  ```raku
  multi method decode(Blob:D: $encoding = self.encoding // "utf-8")
  ```
  
  ```raku
  multi method decode(Blob:D: $encoding, Str :$replacement!,
                      Bool:D :$strict = False)
  
  ```
  
  ```raku
  multi method decode(Blob:D: $encoding, Bool:D :$strict = False)
  ```
  
  Applies an encoding to turn the blob into a [`Str`](/type/Str); the encoding will be UTF-8 by default.
  
  ```raku
  my Blob $blob = "string".encode('utf-8');
  say $blob.decode('utf-8'); # OUTPUT: «string␤»
  ```
  
  On malformed utf-8 `.decode` will throw X::AdHoc. To handle sloppy utf-8 use [`utf8-c8`](/language/unicode#UTF8-C8).
  
  ## [method list](#role_Blob "go to top of document")[§](#method_list "direct link")
  
  ```raku
  multi method list(Blob:D:)
  ```
  
  Returns a [`List`](/type/List) of integers:
  
  ```raku
  say "zipi".encode("ascii").list; # OUTPUT: «(122 105 112 105)␤»
  ```
  
  ## [method gist](#role_Blob "go to top of document")[§](#method_gist "direct link")
  
  ```raku
  method gist(Blob:D: --> Str:D)
  ```
  
  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.
  
  ```raku
  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 ...>
  ```
  
  ## [method subbuf](#role_Blob "go to top of document")[§](#method_subbuf "direct link")
  
  ```raku
  multi method subbuf(Int $from, Int $len = self.elems --> Blob:D)
  multi method subbuf(Range $range --> Blob:D)
  multi method subbuf(Blob:D: &From)
  multi method subbuf(Blob:D: Int:D $From, &End)
  multi method subbuf(Blob:D: &From, &End)
  multi method subbuf(Blob:D: \from, Whatever)
  multi method subbuf(Blob:D: \from, Numeric \length)
  ```
  
  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.
  
  ```raku
  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`](/type/Range) to be specified to indicate which part of the invocant buffer you would like:
  
  ```raku
  say Blob.new(1..10).subbuf(2..5);    # OUTPUT: «Blob:0x<03 04 05 06>␤»
  ```
  
  ## [method allocate](#role_Blob "go to top of document")[§](#method_allocate "direct link")
  
  ```raku
  multi method allocate(Blob:U: Int:D $elements)
  multi method allocate(Blob:U: Int:D $elements, int $value)
  multi method allocate(Blob:U: Int:D $elements, Int:D \value)
  multi method allocate(Blob:U: Int:D $elements, Mu:D $got)
  multi method allocate(Blob:U: Int:D $elements, int @values)
  multi method allocate(Blob:U: Int:D $elements, Blob:D $blob)
  multi method allocate(Blob:U: Int:D $elements, @values)
  ```
  
  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`](/type/Iterable) that generates integer values, including another `Blob`. The pattern will be repeated if not enough values are given to fill the entire `Blob`.
  
  ```raku
  my Blob $b0 = Blob.allocate(10,0);
  $b0.say; # OUTPUT: «Blob:0x<00 00 00 00 00 00 00 00 00 00>␤»
  ```
  
  If the pattern is a general [`Mu`](/type/Mu) value, it will fail.
  
  ## [routine unpack](#role_Blob "go to top of document")[§](#routine_unpack "direct link")
  
  This method is considered **experimental**, in order to use it you will need to do:
  
  ```raku
  use experimental :pack;
  
  multi method unpack(Blob:D: Str:D $template)
  multi method unpack(Blob:D: @template)
  multi        unpack(Blob:D \blob, Str:D $template)
  multi        unpack(Blob:D \blob, @template)
  ```
  
  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:
  
  ```raku
  use experimental :pack;
  say Blob.new(1..10).unpack("C*");
  # OUTPUT: «(1 2 3 4 5 6 7 8 9 10)␤»
  ```
  
  ## [sub pack](#role_Blob "go to top of document")[§](#sub_pack "direct link")
  
  This subroutine is considered **experimental**, in order to use it you will need to do:
  
  ```raku
  use experimental :pack;
  
  ```
  
  ```raku
  multi pack(Str $template, *@items)
  multi pack(@template, *@items)
  
  ```
  
  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](/routine/unpack).
  
  ## [method reverse](#role_Blob "go to top of document")[§](#method_reverse "direct link")
  
  ```raku
  method reverse(Blob:D: --> Blob:D)
  ```
  
  Returns a Blob with all elements in reversed order.
  
  ```raku
  say Blob.new([1, 2, 3]).reverse;    # OUTPUT: «Blob:0x<03 02 01>␤»
  say blob16.new([2]).reverse;        # OUTPUT: «Blob[uint16]:0x<02>␤»
  say blob32.new([16, 32]).reverse;   # OUTPUT: «Blob[uint32]:0x<20 10>␤»
  ```
  
  # [Methods on blob8 only (6.d, 2018.12 and later)](#role_Blob "go to top of document")[§](#Methods_on_blob8_only_(6.d,_2018.12_and_later) "direct link")
  
  These methods are available on the blob8 (and `buf8`) types only. They allow low level access to reading bytes from the underlying data and interpreting them 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). The returned values are always expanded to a 64 bit native value where possible, and to a (big) integer value if that is not possible.
  
  Endianness must be indicated by using values of the [`Endian`](/type/Endian) enum as the **second** parameter to these methods. If no endianness is specified, `NativeEndian` will be assumed. Other values are `LittleEndian` and `BigEndian`.
  
  ## [method read-uint8](#role_Blob "go to top of document")[§](#method_read-uint8 "direct link")
  
  ```raku
  method read-uint8(blob8:D: uint $pos, $endian = 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.
  
  ## [method read-int8](#role_Blob "go to top of document")[§](#method_read-int8 "direct link")
  
  ```raku
  method read-int8(blob8:D: uint $pos, $endian = 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.
  
  ## [method read-uint16](#role_Blob "go to top of document")[§](#method_read-uint16 "direct link")
  
  ```raku
  method read-uint16(blob8:D: uint $pos, $endian = NativeEndian --> uint)
  ```
  
  Returns a native `uint` value for the **two** bytes starting at the given position.
  
  ## [method read-int16](#role_Blob "go to top of document")[§](#method_read-int16 "direct link")
  
  ```raku
  method read-int16(blob8:D: uint $pos, $endian = NativeEndian --> int)
  ```
  
  Returns a native `int` value for the **two** bytes starting at the given position.
  
  ## [method read-uint32](#role_Blob "go to top of document")[§](#method_read-uint32 "direct link")
  
  ```raku
  method read-uint32(blob8:D: uint $pos, $endian = NativeEndian --> uint)
  ```
  
  Returns a native `uint` value for the **four** bytes starting at the given position.
  
  ## [method read-int32](#role_Blob "go to top of document")[§](#method_read-int32 "direct link")
  
  ```raku
  method read-int32(blob8:D: uint $pos, $endian = NativeEndian --> int)
  ```
  
  Returns a native `int` value for the **four** bytes starting at the given position.
  
  ## [method read-uint64](#role_Blob "go to top of document")[§](#method_read-uint64 "direct link")
  
  ```raku
  method read-uint64(blob8:D: uint $pos, $endian = NativeEndian --> UInt:D)
  ```
  
  Returns an unsigned integer value for the **eight** bytes starting at the given position.
  
  ## [method read-int64](#role_Blob "go to top of document")[§](#method_read-int64 "direct link")
  
  ```raku
  method read-int64(blob8:D: uint $pos, $endian = NativeEndian --> int)
  ```
  
  Returns a native `int` value for the **eight** bytes starting at the given position.
  
  ## [method read-uint128](#role_Blob "go to top of document")[§](#method_read-uint128 "direct link")
  
  ```raku
  method read-uint128(blob8:D: uint $pos, $endian = NativeEndian --> UInt:D)
  ```
  
  Returns an unsigned integer value for the **sixteen** bytes starting at the given position.
  
  ## [method read-int128](#role_Blob "go to top of document")[§](#method_read-int128 "direct link")
  
  ```raku
  method read-int128(blob8:D: uint $pos, $endian = NativeEndian --> Int:D)
  ```
  
  Returns an integer value for the **sixteen** bytes starting at the given position.
  
  ## [method read-num32](#role_Blob "go to top of document")[§](#method_read-num32 "direct link")
  
  ```raku
  method read-num32(blob8:D: uint $pos, $endian = NativeEndian --> int)
  ```
  
  Returns a native `num` value for the **four** bytes starting at the given position.
  
  ## [method read-num64](#role_Blob "go to top of document")[§](#method_read-num64 "direct link")
  
  ```raku
  method read-num64(blob8:D: uint $pos, $endian = NativeEndian --> int)
  ```
  
  Returns a native `num` value for the **eight** bytes starting at the given position.
  
  # [Methods on blob8 only (6.d, 2019.03 and later)](#role_Blob "go to top of document")[§](#Methods_on_blob8_only_(6.d,_2019.03_and_later) "direct link")
  
  ## [method read-ubits](#role_Blob "go to top of document")[§](#method_read-ubits "direct link")
  
  ```raku
  method read-ubits(blob8:D: uint $pos, uint $bits --> UInt:D)
  ```
  
  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`.
  
  ## [method read-bits](#role_Blob "go to top of document")[§](#method_read-bits "direct link")
  
  ```raku
  method read-bits(blob8:D: uint $pos, uint $bits --> Int:D)
  ```
  
  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`.
  
  ## [method Buf](#role_Blob "go to top of document")[§](#method_Buf "direct link")
  
  ```raku
  method Buf(Blob:D: --> Buf:D)
  ```
  
  Available as of the 2021.06 Rakudo compiler release.
  
  Coerces the invocant into a mutable [`Buf`](/type/Buf) object.
  
  # [Typegraph](# "go to top of document")[§](#typegraphrelations "direct link")
  
  Type relations for `Blob`
  
  
  
  raku-type-graph
  
  
  
  Blob
  Blob
  
  
  Positional
  Positional
  
  
  Blob->Positional
  
  
  
  Stringy
  Stringy
  
  
  Blob->Stringy
  
  
  
  Buf
  Buf
  
  
  Buf->Blob
  
  
  
  Mu
  Mu
  
  
  Any
  Any
  
  
  Any->Mu
  
  
  
  utf8
  utf8
  
  
  utf8->Blob
  
  
  
  utf8->Any
  
  [Expand chart above](/assets/typegraphs/Blob.svg)
  