1[/
2 / Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com)
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 /]
7
8[section:DynamicBuffer_v2 Dynamic buffer requirements (version 2)]
9
10A dynamic buffer encapsulates memory storage that may be automatically resized
11as required.
12
13A dynamic buffer type `X` shall satisfy the requirements of `CopyConstructible`
14(C++ Std, [copyconstructible]) types in addition to those listed below.
15
16In the table below, `X` denotes a dynamic buffer class, `x` denotes a value of
17type `X&`, `x1` denotes values of type `const X&`, `pos` and `n` denote values
18of type `size_t`, and `u` denotes an identifier.
19
20[table DynamicBuffer_v2 requirements
21  [[expression] [type] [assertion/note[br]pre/post-conditions]]
22  [
23    [`X::const_buffers_type`]
24    [type meeting [link boost_asio.reference.ConstBufferSequence ConstBufferSequence]
25     requirements.]
26    [This type represents the underlying memory as a sequence of @c const_buffer
27     objects.]
28  ]
29  [
30    [`X::mutable_buffers_type`]
31    [type meeting [link boost_asio.reference.MutableBufferSequence MutableBufferSequence]
32     requirements.]
33    [This type represents the underlying memory as a sequence of @c
34     mutable_buffer objects.]
35  ]
36  [
37    [`x1.size()`]
38    [`size_t`]
39    [Returns the size, in bytes, of the underlying memory.]
40  ]
41  [
42    [`x1.max_size()`]
43    [`size_t`]
44    [Returns the permitted maximum size of the underlying memory.]
45  ]
46  [
47    [`x1.capacity()`]
48    [`size_t`]
49    [Returns the maximum size to which the underlying memory can grow without
50     requiring reallocation.]
51  ]
52  [
53    [`x1.data(pos, n)`]
54    [`X::const_buffers_type`]
55    [Returns a constant buffer sequence `u` that represents the underlying
56     memory beginning at offset `pos`, and where `buffer_size(u) <= n`.]
57  ]
58  [
59    [`x.data(pos, n)`]
60    [`X::mutable_buffers_type`]
61    [Returns a mutable buffer sequence `u` that represents the underlying
62     memory beginning at offset `pos`, and where `buffer_size(u) <= n`.]
63  ]
64  [
65    [`x.grow(n)`]
66    []
67    [Requires: `size() + n <= max_size()`.[br]
68     [br]
69     Extends the underlying memory to accommodate `n` additional bytes at the
70     end. The dynamic buffer reallocates memory as required. All constant or
71     mutable buffer sequences previously obtained using `data()` are
72     invalidated.[br]
73     [br]
74     Throws: `length_error` if `size() + n > max_size()`.]
75  ]
76  [
77    [`x.shrink(n)`]
78    []
79    [Removes `n` bytes from the end of the underlying memory. If `n` is greater
80     than the size of the underlying memory, the entire underlying memory is
81     emptied. All constant or mutable buffer sequences previously obtained
82     using `data()` are invalidated.]
83  ]
84  [
85    [`x.consume(n)`]
86    []
87    [Removes `n` bytes from the beginning of the underlying memory. If `n` is
88     greater than the size of the underlying memory, the entire underlying memory
89     is emptied. All constant or mutable buffer sequences previously obtained
90     using `data()` are invalidated.]
91  ]
92]
93
94[endsect]
95