[/
    Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot com)

    Distributed under the Boost Software License, Version 1.0. (See accompanying
    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

    Official repository: https://github.com/boostorg/beast
]

[section Buffer Types]

To facilitate working with instances of the __ConstBufferSequence__ and
__MutableBufferSequence__ concepts introduced in __Asio__, Beast treats
those sequences as a special type of range. The following algorithms and
wrappers are provided which transform these ranges efficiently using lazy
evaluation. No memory allocations are used in the transformations; instead,
they create lightweight iterators over the existing, unmodified memory
buffers. Control of buffers is retained by the caller; ownership is not
transferred.

[table Buffer Algorithms and Types
[[Name][Description]]
[[
    [link beast.ref.boost__beast__buffer_bytes `buffer_bytes`]
][
    This is a more reliable version of
    [@boost:/doc/html/boost_asio/reference/buffer_size.html `net::buffer_size`]
    which is easier to use and also works for types which are convertible
    to `net::const_buffer` or `net::mutable_buffer`.
]]
[[
    [link beast.ref.boost__beast__buffers_cat `buffers_cat`]
][
    This functions returns a new buffer sequence which, when iterated,
    traverses the sequence which would be formed if all of the input buffer
    sequences were concatenated. With this routine, multiple calls to a
    stream's `write_some` function may be combined into one, eliminating
    expensive system calls.
]]
[[
    [link beast.ref.boost__beast__buffers_cat_view `buffers_cat_view`]
][
    This class represents the buffer sequence formed by concatenating
    two or more buffer sequences. This is type of object returned by
    [link beast.ref.boost__beast__buffers_cat `buffers_cat`].
]]
[[
    [link beast.ref.boost__beast__buffers_front `buffers_front`]
][
    This function returns the first buffer in a buffer sequence,
    or a buffer of size zero if the buffer sequence has no elements.
]]
[[
    [link beast.ref.boost__beast__buffers_prefix `buffers_prefix`]
][
    This function returns a new buffer or buffer sequence which represents
    a prefix of the original buffers.
]]
[[
    [link beast.ref.boost__beast__buffers_prefix_view `buffers_prefix_view`]
][
    This class represents the buffer sequence formed from a prefix of
    an existing buffer sequence. This is the type of buffer returned by
    [link beast.ref.boost__beast__buffers_prefix `buffers_prefix`].
]]
[[
    [link beast.ref.boost__beast__buffers_range `buffers_range`]
    [link beast.ref.boost__beast__buffers_range_ref `buffers_range_ref`]
][
    This function returns an iterable range representing the passed
    buffer sequence. The values obtained when iterating the range
    will always be a constant buffer, unless the underlying buffer
    sequence is mutable, in which case the value obtained when iterating
    will be a mutable buffer. It is intended as a notational convenience
    when writing a ['range-for] statement over a buffer sequence.

    The function
    [link beast.ref.boost__beast__buffers_range_ref `buffers_range`]
    maintains a copy of the buffer sequence, while
    [link beast.ref.boost__beast__buffers_range_ref `buffers_range_ref`]
    maintains a reference (in this case, the caller must ensure that
    the lifetime of the referenced buffer sequence extends until the
    range object is destroyed).
]]
[[
    [link beast.ref.boost__beast__buffers_suffix `buffers_suffix`]
][
    This class wraps the underlying memory of an existing buffer sequence
    and presents a suffix of the original sequence. The length of the suffix
    may be progressively shortened. This lets callers work with sequential
    increments of a buffer sequence.
]]
[[
    [link beast.ref.boost__beast__buffers_to_string `buffers_to_string`]
][
    This function converts a buffer sequence to a `std::string`. It can
    be used for diagnostic purposes and tests.
]]
]

The __DynamicBuffer__ concept introduced in __Asio__ models a buffer
sequence which supports an owning, resizable range. Beast provides this
set of additional implementations of the dynamic buffer concept:

[table Dynamic Buffer Implementations
[[Name][Description]]
[[
    [link beast.ref.boost__beast__buffers_adaptor `buffers_adaptor`]
][
    This wrapper adapts any __MutableBufferSequence__ into a
    __DynamicBuffer__ with an upper limit on the total size of the input and
    output areas equal to the size of the underlying mutable buffer sequence.
    The implementation does not perform heap allocations.
]]
[[
    [link beast.ref.boost__beast__flat_buffer `flat_buffer`]
    [link beast.ref.boost__beast__basic_flat_buffer `basic_flat_buffer`]
][
    Guarantees that input and output areas are buffer sequences with
    length one.
    Upon construction an optional upper limit to the total size of the
    input and output areas may be set.
    The basic container is an
    [@https://en.cppreference.com/w/cpp/named_req/AllocatorAwareContainer [*AllocatorAwareContainer]].
]]
[[
    [link beast.ref.boost__beast__multi_buffer `multi_buffer`]
    [link beast.ref.boost__beast__basic_multi_buffer `basic_multi_buffer`]
][
    Uses a sequence of one or more character arrays of varying sizes.
    Additional character array objects are appended to the sequence to
    accommodate changes in the size of the character sequence.
    The basic container is an
    [@https://en.cppreference.com/w/cpp/named_req/AllocatorAwareContainer [*AllocatorAwareContainer]].
]]
[[
    [link beast.ref.boost__beast__flat_static_buffer `flat_static_buffer`]
    [link beast.ref.boost__beast__flat_static_buffer_base `flat_static_buffer_base`]
][
    Guarantees that input and output areas are buffer sequences with
    length one.
    Provides the facilities of a dynamic buffer, subject to an upper
    limit placed on the total size of the input and output areas defined
    by a constexpr template parameter. The storage for the sequences are
    kept in the class; the implementation does not perform heap allocations.
]]
[[
    [link beast.ref.boost__beast__static_buffer `static_buffer`]
    [link beast.ref.boost__beast__static_buffer_base `static_buffer_base`]
][
    Provides the facilities of a circular dynamic buffer. subject to an
    upper limit placed on the total size of the input and output areas
    defined by a constexpr template parameter.
    The implementation never moves memory during buffer operations.
    The storage for the sequences are kept in the class; the implementation
    does not perform heap allocations.
]]
]

These two functions facilitate buffer interoperability with standard
output streams.

[table Buffer Output Streams
[[Name][Description]]
[[
    [link beast.ref.boost__beast__make_printable `make_printable`]
][
    This function wraps a __ConstBufferSequence__ so it may be
    used with `operator<<` and `std::ostream`.
]]
[[
    [link beast.ref.boost__beast__ostream `ostream`]
][
    This function returns a `std::ostream` which wraps a dynamic buffer.
    Characters sent to the stream using `operator<<` are stored in the
    dynamic buffer.
]]
]

These type traits are provided to facilitate writing compile-time
metafunctions which operate on buffers:

[table Buffer Algorithms and Types
[[Name][Description]]
[[
    [link beast.ref.boost__beast__buffers_iterator_type `buffers_iterator_type`]
][
    This metafunction is used to determine the type of iterator
    used by a particular buffer sequence.
]]
[[
    [link beast.ref.boost__beast__buffers_type `buffers_type`]
][
    This metafunction is used to determine the underlying buffer type for
    a list of buffer sequence. The equivalent type of the alias will vary
    depending on the template type argument.
]]
[[
    [link beast.ref.boost__beast__is_const_buffer_sequence `is_const_buffer_sequence`]
][
    This metafunction is used to determine if all of the specified types
    meet the requirements of __ConstBufferSequence__. This type alias
    will be `std::true_type` if each specified type meets the requirements,
    otherwise, this type alias will be `std::false_type`.
]]
[[
    [link beast.ref.boost__beast__is_mutable_buffer_sequence `is_mutable_buffer_sequence`]
][
    This metafunction is used to determine if all of the specified types
    meet the requirements of __MutableBufferSequence__. This type alias
    will be `std::true_type` if each specified type meets the requirements,
    otherwise, this type alias will be `std::false_type`.
]]
]

[endsect]