=begin pod

=TITLE class Buf

    class Buf does Positional { ... }

A C<Buf> (short for buffer) is a binary string, and generally returned from
low-level IO operations (C<$io.read($number-of-by)>) or from C<Str.encode>.
It can be used to for writing to IO handles as C<$io.write($buf)>.

In the abstract it is just a list of integers, so
for example indexing into a C<Buf> with C<.[$idx]> returns an C<Int>.

=head1 Methods

=head2 new

    method new(*@codes)

Creates a C<Buf> from a list of integers.

=head2  Bool

    multi method Bool(Buf:D:)

Returns C<False> if and only if the buffer is empty.

=head2 elems

    multi method elems(Buf:D:) returns Int:D

Returns the number of elements of the buffer.

=head2 decode

    multi method decode(Buf:D: Str:D $encoding = 'UTF-8') returns Str:D

Applies an encoding to turn the buffer into a C<Str>.

=head2 subbuf

    method subbuf(Int $from, Int $len = self.elems) returns Buf:D

Extracts a part of the invocant buffer, statrting from the index with
elements C<$from>, and taking C<$len> elements (or less if the buffer is
shorter), and creates a new buffer as the result.

    say Buf.new(1..10).subbuf(2, 4);    # Buf:0x<03 04 05 06>

=end pod
