boost_beast/doc/concept/DynamicBuffer.qbk

[/
    Copyright (c) 2013-2017 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)
]

[section:DynamicBuffer DynamicBuffer]

A dynamic buffer encapsulates memory storage that may be automatically resized
as required, where the memory is divided into an input sequence followed by an
output sequence. These memory regions are internal to the dynamic buffer, but
direct access to the elements is provided to permit them to be efficiently used
with I/O operations, such as the send or receive operations of a socket. Data
written to the output sequence of a dynamic buffer object is appended to the
input sequence of the same object.

The interface to this concept is intended to permit the following
implementation strategies:

* A single contiguous octet array, which is reallocated as necessary to
  accommodate changes in the size of the octet sequence. This is the
  implementation approach currently offered by __flat_buffer__.

* A sequence of one or more octet arrays, where each array is of the same
  size. Additional octet array objects are appended to the sequence to
  accommodate changes in the size of the octet sequence.

* A sequence of one or more octet arrays of varying sizes. Additional octet
  array objects are appended to the sequence to accommodate changes in the
  size of the character sequence. This is the implementation approach
  currently offered by __multi_buffer__.

In this table:

* `X` denotes a dynamic buffer class.
* `a` denotes a value of type `X`.
* `c` denotes a (possibly const) value of type `X`.
* `n` denotes a value of type `std::size_t`.
* `T` denotes a type meeting the requirements for __ConstBufferSequence__.
* `U` denotes a type meeting the requirements for __MutableBufferSequence__.

[table DynamicBuffer requirements
[[expression] [type] [semantics, pre/post-conditions]]
[
    [`X::const_buffers_type`]
    [`T`]
    [
        This type represents the memory associated with the input sequence.
    ]
]
[
    [`X::mutable_buffers_type`]
    [`U`]
    [
        This type represents the memory associated with the output sequence.
    ]
]
[
    [`c.size()`]
    [`std::size_t`]
    [
        Returns the size, in bytes, of the input sequence.
    ]
]
[
    [`c.max_size()`]
    [`std::size_t`]
    [
        Returns the permitted maximum of the sum of the sizes of the input
        sequence and output sequence.
    ]
]
[
    [`c.capacity()`]
    [`std::size_t`]
    [
        Returns the maximum sum of the sizes of the input sequence and output
        sequence that the dynamic buffer can hold without requiring reallocation.
    ]
]
[
    [`c.data()`]
    [`X::const_buffers_type`]
    [
        Returns a constant buffer sequence u that represents the memory
        associated with the input sequence, and where `buffer_size(u) == size()`.
    ]
]
[
    [`a.prepare(n)`]
    [`X::mutable_buffers_type`]
    [
        Returns a mutable buffer sequence u representing the output sequence,
        and where `buffer_size(u) == n`. The dynamic buffer reallocates memory
        as required. All constant or mutable buffer sequences previously
        obtained using `data()` or `prepare()` are invalidated.

        Throws: `length_error` if `size() + n` exceeds `max_size()`.
    ]
]
[
    [`a.commit(n)`]
    [ ]
    [
        Appends `n` bytes from the start of the output sequence to the end of
        the input sequence. The remainder of the output sequence is discarded.
        If `n` is greater than the size of the output sequence, the entire
        output sequence is appended to the input sequence. All constant or
        mutable buffer sequences previously obtained using `data()` or
        `prepare()` are invalidated.
    ]
]
[
    [`a.consume(n)`]
    [ ]
    [
        Removes `n` bytes from beginning of the input sequence. If `n` is
        greater than the size of the input sequence, the entire input sequence
        is removed. All constant or mutable buffer sequences previously
        obtained using `data()` or `prepare()` are invalidated.
    ]
]
]

[endsect]