Rename buffer "navigation" functions

[akrzemi1]

Rename begin and end to buffer_begin and buffer_end. They do a different thing than std::begin/std::end; they should not suggest otherwise.

Rename buffer_size to buffer_byte_count (or buffer_total_bytes). The current name incorrectly implies the value of std::distance(capy::buffer_begin(B), std::buffer_end(B)). Alternatively, only if users express interest in the feature, reintroduce it as buffer_sequence_size.

Remove buffer_length. It is never used and easily implemented with std::distance(capy::buffer_begin(B), std::buffer_end(B)). According to the authors, it only exists to suggest what buffer_size is not doing.

[vinniefalco]

buffer_bytes ?

[akrzemi1]

Example from @pdimov:

for this type

struct my_buf
{
    unsigned char data[ 4 ];

    operator mutable_buffer() noexcept { return { data, 4 }; }
    operator const_buffer const noexcept { return { data, 4 } };

    unsigned char* begin() noexcept { return data; }
    unsigned char* end() noexcept { return data + 4; }

    // etc
};

std::begin(buf) returns buf.begin(), whereas capy::begin(buf) returns &buf.
This difference in behavior is undesirable and the function should be named differently.

[akrzemi1]

Here is the proposed renaming.

before	after
capy::begin	capy::buffers_begin
capy::end	capy::buffers_end
capy::buffer_length	capy::buffers_count
capy::buffer_size	capy::bytes_count
capy::buffer_empty	capy::bytes_empty
capy::buffer_copy	capy::bytes_copy
capy::buffer_slice	capy::buffers_slice
capy::consuming_buffers	capy::buffers_cursor

The idea is that operations that only see the flat sequence of bytes are prefixed with bytes_ whereas those that see ranges of buffers are prefixed with buffers_.

[akrzemi1]

I sugest the plural form buffers because the object of these operations is the buffer sequence.