123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216 |
- [/
- 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]
|