1//
2// Copyright (c) 2022 Klemens D. Morgenstern (klemens dot morgenstern at gmx dot net)
3//
4// Distributed under the Boost Software License, Version 1.0. (See accompanying
5// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
6#ifndef BOOST_BEAST_BUFFER_REF_HPP
7#define BOOST_BEAST_BUFFER_REF_HPP
8
9#include <cstddef>
10
11namespace boost {
12namespace beast {
13
14#if !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1)
15
16/** The buffer ref provides a wrapper around beast buffers
17 * to make them usable with asio dynamic_buffer v1.
18 *
19 * v2 is current not supported, so that
20 * `BOOST_ASIO_NO_DYNAMIC_BUFFER_V1` mustn't be defined.
21 *
22 * @par Example
23 *
24 * @code
25 *
26 * asio::tcp::socket sock;
27 * beast::flat_buffer fb;
28 * asio::read_until(sock, ref(fb) '\n');
29 *
30 * @endcode
31 *
32 * @tparam Buffer The underlying buffer
33 */
34template<typename Buffer>
35struct buffer_ref
36{
37 /// The ConstBufferSequence used to represent the readable bytes.
38 using const_buffers_type = typename Buffer::const_buffers_type;
39
40 /// The MutableBufferSequence used to represent the writable bytes.
41 using mutable_buffers_type = typename Buffer::mutable_buffers_type;
42
43 /// Returns the number of readable bytes.
44 std::size_t
45 size() const noexcept
46 {
47 return buffer_.size();
48 }
49
50 /// Return the maximum number of bytes, both readable and writable, that can ever be held.
51 std::size_t
52 max_size() const noexcept
53 {
54 return buffer_.max_size();
55 }
56
57 /// Return the maximum number of bytes, both readable and writable, that can be held without requiring an allocation.
58 std::size_t
59 capacity() const noexcept
60 {
61 return buffer_.capacity();
62 }
63
64 /// Returns a constant buffer sequence representing the readable bytes
65 const_buffers_type
66 data() const noexcept
67 {
68 return buffer_.data();
69 }
70
71 /// Get a list of buffers that represents the output
72 /// sequence, with the given size.
73 /**
74 * Ensures that the output sequence can accommodate @c n bytes, resizing the
75 * vector object as necessary.
76 *
77 * @returns An object of type @c mutable_buffers_type that satisfies
78 * MutableBufferSequence requirements, representing vector memory at the
79 * start of the output sequence of size @c n.
80 *
81 * @throws std::length_error If <tt>size() + n > max_size()</tt>.
82 *
83 * @note The returned object is invalidated by any @c dynamic_vector_buffer
84 * or @c vector member function that modifies the input sequence or output
85 * sequence.
86 */
87 mutable_buffers_type prepare(std::size_t n)
88 {
89 return buffer_.prepare(n);
90 }
91
92 /// Move bytes from the output sequence to the input
93 /// sequence.
94 /**
95 * @param n The number of bytes to append from the start of the output
96 * sequence to the end of the input sequence. The remainder of the output
97 * sequence is discarded.
98 *
99 * Requires a preceding call <tt>prepare(x)</tt> where <tt>x >= n</tt>, and
100 * no intervening operations that modify the input or output sequence.
101 *
102 * @note If @c n is greater than the size of the output sequence, the entire
103 * output sequence is moved to the input sequence and no error is issued.
104 */
105 void commit(std::size_t n)
106 {
107 return buffer_.commit(n);
108 }
109
110 /// Remove `n` bytes from the readable byte sequence.
111 /**
112 * @b DynamicBuffer_v1: Removes @c n characters from the beginning of the
113 * input sequence. @note If @c n is greater than the size of the input
114 * sequence, the entire input sequence is consumed and no error is issued.
115 */
116 void consume(std::size_t n)
117 {
118 return buffer_.consume(n);
119 }
120
121 /// The type of the underlying buffer.
122 using buffer_type = Buffer;
123
124 /// Create a buffer reference around @c buffer.
125 buffer_ref(Buffer & buffer) : buffer_(buffer) {}
126
127 /// Copy the reference.
128 buffer_ref(const buffer_ref& buffer) = default;
129
130private:
131 Buffer &buffer_;
132};
133
134
135template<class Allocator>
136class basic_flat_buffer;
137template<std::size_t N>
138class flat_static_buffer;
139template<class Allocator>
140class basic_multi_buffer;
141template<std::size_t N>
142class static_buffer;
143
144/// Create a buffer_ref for basic_flat_buffer.
145template<class Allocator>
146inline buffer_ref<basic_flat_buffer<Allocator>> ref(basic_flat_buffer<Allocator> & buf)
147{
148 return buffer_ref<basic_flat_buffer<Allocator>>(buf);
149}
150
151/// Create a buffer_ref for flat_static_buffer.
152template<std::size_t N>
153inline buffer_ref<flat_static_buffer<N>> ref(flat_static_buffer<N> & buf)
154{
155 return buffer_ref<flat_static_buffer<N>>(buf);
156}
157
158/// Create a buffer_ref for basic_multi_buffer.
159template<class Allocator>
160inline buffer_ref<basic_multi_buffer<Allocator>> ref(basic_multi_buffer<Allocator> & buf)
161{
162 return buffer_ref<basic_multi_buffer<Allocator>>(buf);
163}
164
165/// Create a buffer_ref for static_buffer.
166template<std::size_t N>
167inline buffer_ref<static_buffer<N>> ref(static_buffer<N> & buf)
168{
169 return buffer_ref<static_buffer<N>>(buf);
170}
171
172#endif // !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1)
173
174}
175}
176
177#endif //BOOST_BEAST_BUFFER_REF_HPP
178

source code of boost/libs/beast/include/boost/beast/core/buffer_ref.hpp