1<?xml version="1.0" standalone="yes"?> 2<library-reference id="boost_circular_buffer_c___reference"><title>Boost.Circular_buffer C++ Reference</title><header name="boost/circular_buffer.hpp"> 3<para>Includes <boost/circular_buffer/base.hpp> </para><macro name="BOOST_CB_ENABLE_DEBUG"><description><para>Debug support control. </para></description></macro> 4</header> 5<header name="boost/circular_buffer/base.hpp"> 6<namespace name="boost"> 7<class name="circular_buffer"><template> 8 <template-type-parameter name="T"><purpose><para>The type of the elements stored in the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </para></purpose></template-type-parameter> 9 <template-type-parameter name="Alloc"><purpose><para>The allocator type used for all internal memory management. </para></purpose></template-type-parameter> 10 </template><inherit access="private">empty_value< Alloc ></inherit><purpose>Circular buffer - a STL compliant container. </purpose><description><para> 11<formalpara><title>Type Requirements T</title><para>The <computeroutput>T</computeroutput> has to be <ulink url="https://www.boost.org/sgi/stl/Assignable.html">SGIAssignable</ulink> (SGI STL defined combination of <ulink url="../../../utility/Assignable.html">Assignable</ulink> and <ulink url="../../../utility/CopyConstructible.html">CopyConstructible</ulink>). Moreover <computeroutput>T</computeroutput> has to be <ulink url="https://www.boost.org/sgi/stl/DefaultConstructible.html">DefaultConstructible</ulink> if supplied as a default parameter when invoking some of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>'s methods e.g. <computeroutput>insert(iterator pos, const value_type& item = value_type())</computeroutput>. And <ulink url="https://www.boost.org/sgi/stl/EqualityComparable.html">EqualityComparable</ulink> and/or <ulink url="../../../utility/LessThanComparable.html">LessThanComparable</ulink> if the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> will be compared with another container. </para> 12</formalpara> 13 14<formalpara><title>Type Requirements Alloc</title><para>The <computeroutput>Alloc</computeroutput> has to meet the allocator requirements imposed by STL. </para> 15</formalpara> 16<formalpara><title>Default Alloc</title><para>std::allocator<T></para> 17</formalpara> 18For detailed documentation of the <classname alt="boost::circular_buffer">circular_buffer</classname> visit: <ulink url="http://www.boost.org/libs/circular_buffer/doc/circular_buffer.html">http://www.boost.org/libs/circular_buffer/doc/circular_buffer.html</ulink> </para></description><typedef name="this_type"><purpose>The type of this <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </purpose><type><classname>circular_buffer</classname>< T, Alloc ></type></typedef> 19<typedef name="value_type"><purpose>The type of elements stored in the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </purpose><type>Alloc::value_type</type></typedef> 20<typedef name="pointer"><purpose>A pointer to an element. </purpose><type>allocator_pointer< Alloc >::type</type></typedef> 21<typedef name="const_pointer"><purpose>A const pointer to the element. </purpose><type>allocator_const_pointer< Alloc >::type</type></typedef> 22<typedef name="reference"><purpose>A reference to an element. </purpose><type>value_type &</type></typedef> 23<typedef name="const_reference"><purpose>A const reference to an element. </purpose><type>const value_type &</type></typedef> 24<typedef name="difference_type"><purpose>The distance type. </purpose><description><para>(A signed integral type used to represent the distance between two iterators.) </para></description><type>allocator_difference_type< Alloc >::type</type></typedef> 25<typedef name="size_type"><purpose>The size type. </purpose><description><para>(An unsigned integral type that can represent any non-negative value of the container's distance type.) </para></description><type>allocator_size_type< Alloc >::type</type></typedef> 26<typedef name="allocator_type"><purpose>The type of an allocator used in the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </purpose><type>Alloc</type></typedef> 27<typedef name="const_iterator"><purpose>A const (random access) iterator used to iterate through the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </purpose><type>cb_details::iterator< <classname>circular_buffer</classname>< T, Alloc >, cb_details::const_traits< Alloc > ></type></typedef> 28<typedef name="iterator"><purpose>A (random access) iterator used to iterate through the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </purpose><type>cb_details::iterator< <classname>circular_buffer</classname>< T, Alloc >, cb_details::nonconst_traits< Alloc > ></type></typedef> 29<typedef name="const_reverse_iterator"><purpose>A const iterator used to iterate backwards through a <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </purpose><type>std::reverse_iterator< const_iterator ></type></typedef> 30<typedef name="reverse_iterator"><purpose>An iterator used to iterate backwards through a <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </purpose><type>std::reverse_iterator< iterator ></type></typedef> 31<typedef name="array_range"><purpose>An array range. </purpose><description><para>(A typedef for the <ulink url="https://www.boost.org/sgi/stl/pair.html"><computeroutput>std::pair</computeroutput></ulink> where its first element is a pointer to a beginning of an array and its second element represents a size of the array.) </para></description><type>std::pair< pointer, size_type ></type></typedef> 32<typedef name="const_array_range"><purpose>A range of a const array. </purpose><description><para>(A typedef for the <ulink url="https://www.boost.org/sgi/stl/pair.html"><computeroutput>std::pair</computeroutput></ulink> where its first element is a pointer to a beginning of a const array and its second element represents a size of the const array.) </para></description><type>std::pair< const_pointer, size_type ></type></typedef> 33<typedef name="capacity_type"><purpose>The capacity type. </purpose><description><para>(Same as <computeroutput>size_type</computeroutput> - defined for consistency with the __cbso class. </para></description><type>size_type</type></typedef> 34<typedef name="param_value_type"><purpose>A type representing the "best" way to pass the value_type to a method. </purpose><type>const value_type &</type></typedef> 35<typedef name="rvalue_type"><description><para>A type representing rvalue from param type. On compilers without rvalue references support this type is the Boost.Moves type used for emulation. </para></description><type>value_type &&</type></typedef> 36<method-group name="public member functions"> 37<method name="get_allocator" cv="const noexcept"><type>allocator_type</type><purpose>Get the allocator. </purpose><description><para> 38 39<formalpara><title>Exception Safety</title><para>No-throw. </para> 40</formalpara> 41<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators. </para> 42</formalpara> 43<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>). </para> 44</formalpara> 45<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>get_allocator()</computeroutput> for obtaining an allocator reference. </para> 46</para> 47</para></description><returns><para>The allocator. </para> 48</returns><throws><simpara><classname>Nothing.</classname> </simpara></throws></method> 49<method name="get_allocator" cv="noexcept"><type>allocator_type &</type><purpose>Get the allocator reference. </purpose><description><para> 50 51<formalpara><title>Exception Safety</title><para>No-throw. </para> 52</formalpara> 53<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators. </para> 54</formalpara> 55<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>). </para> 56</formalpara> 57<note><para>This method was added in order to optimize obtaining of the allocator with a state, although use of stateful allocators in STL is discouraged. </para> 58</note> 59<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>get_allocator() const</computeroutput> </para> 60</para> 61</para></description><returns><para>A reference to the allocator. </para> 62</returns><throws><simpara><classname>Nothing.</classname> </simpara></throws></method> 63<method name="begin" cv="noexcept"><type>iterator</type><purpose>Get the iterator pointing to the beginning of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </purpose><description><para> 64 65<formalpara><title>Exception Safety</title><para>No-throw. </para> 66</formalpara> 67<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators. </para> 68</formalpara> 69<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>). </para> 70</formalpara> 71<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>end()</computeroutput>, <computeroutput>rbegin()</computeroutput>, <computeroutput>rend()</computeroutput> </para> 72</para> 73</para></description><returns><para>A random access iterator pointing to the first element of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. If the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> is empty it returns an iterator equal to the one returned by <computeroutput>end()</computeroutput>. </para> 74</returns><throws><simpara><classname>Nothing.</classname> </simpara></throws></method> 75<method name="end" cv="noexcept"><type>iterator</type><purpose>Get the iterator pointing to the end of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </purpose><description><para> 76 77<formalpara><title>Exception Safety</title><para>No-throw. </para> 78</formalpara> 79<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators. </para> 80</formalpara> 81<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>). </para> 82</formalpara> 83<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>begin()</computeroutput>, <computeroutput>rbegin()</computeroutput>, <computeroutput>rend()</computeroutput> </para> 84</para> 85</para></description><returns><para>A random access iterator pointing to the element "one behind" the last element of the <computeroutput> <classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. If the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> is empty it returns an iterator equal to the one returned by <computeroutput>begin()</computeroutput>. </para> 86</returns><throws><simpara><classname>Nothing.</classname> </simpara></throws></method> 87<method name="begin" cv="const noexcept"><type>const_iterator</type><purpose>Get the const iterator pointing to the beginning of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </purpose><description><para> 88 89<formalpara><title>Exception Safety</title><para>No-throw. </para> 90</formalpara> 91<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators. </para> 92</formalpara> 93<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>). </para> 94</formalpara> 95<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>end() const</computeroutput>, <computeroutput>rbegin() const</computeroutput>, <computeroutput>rend() const</computeroutput> </para> 96</para> 97</para></description><returns><para>A const random access iterator pointing to the first element of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. If the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> is empty it returns an iterator equal to the one returned by <computeroutput>end() const</computeroutput>. </para> 98</returns><throws><simpara><classname>Nothing.</classname> </simpara></throws></method> 99<method name="cbegin" cv="const noexcept"><type>const_iterator</type></method> 100<method name="end" cv="const noexcept"><type>const_iterator</type><purpose>Get the const iterator pointing to the end of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </purpose><description><para> 101 102<formalpara><title>Exception Safety</title><para>No-throw. </para> 103</formalpara> 104<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators. </para> 105</formalpara> 106<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>). </para> 107</formalpara> 108<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>begin() const</computeroutput>, <computeroutput>rbegin() const</computeroutput>, <computeroutput>rend() const</computeroutput> </para> 109</para> 110</para></description><returns><para>A const random access iterator pointing to the element "one behind" the last element of the <computeroutput> <classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. If the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> is empty it returns an iterator equal to the one returned by <computeroutput>begin() const</computeroutput> const. </para> 111</returns><throws><simpara><classname>Nothing.</classname> </simpara></throws></method> 112<method name="cend" cv="const noexcept"><type>const_iterator</type></method> 113<method name="rbegin" cv="noexcept"><type>reverse_iterator</type><purpose>Get the iterator pointing to the beginning of the "reversed" <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </purpose><description><para> 114 115<formalpara><title>Exception Safety</title><para>No-throw. </para> 116</formalpara> 117<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators. </para> 118</formalpara> 119<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>). </para> 120</formalpara> 121<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>rend()</computeroutput>, <computeroutput>begin()</computeroutput>, <computeroutput>end()</computeroutput> </para> 122</para> 123</para></description><returns><para>A reverse random access iterator pointing to the last element of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. If the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> is empty it returns an iterator equal to the one returned by <computeroutput>rend()</computeroutput>. </para> 124</returns><throws><simpara><classname>Nothing.</classname> </simpara></throws></method> 125<method name="rend" cv="noexcept"><type>reverse_iterator</type><purpose>Get the iterator pointing to the end of the "reversed" <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </purpose><description><para> 126 127<formalpara><title>Exception Safety</title><para>No-throw. </para> 128</formalpara> 129<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators. </para> 130</formalpara> 131<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>). </para> 132</formalpara> 133<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>rbegin()</computeroutput>, <computeroutput>begin()</computeroutput>, <computeroutput>end()</computeroutput> </para> 134</para> 135</para></description><returns><para>A reverse random access iterator pointing to the element "one before" the first element of the <computeroutput> <classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. If the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> is empty it returns an iterator equal to the one returned by <computeroutput>rbegin()</computeroutput>. </para> 136</returns><throws><simpara><classname>Nothing.</classname> </simpara></throws></method> 137<method name="rbegin" cv="const noexcept"><type>const_reverse_iterator</type><purpose>Get the const iterator pointing to the beginning of the "reversed" <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </purpose><description><para> 138 139<formalpara><title>Exception Safety</title><para>No-throw. </para> 140</formalpara> 141<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators. </para> 142</formalpara> 143<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>). </para> 144</formalpara> 145<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>rend() const</computeroutput>, <computeroutput>begin() const</computeroutput>, <computeroutput>end() const</computeroutput> </para> 146</para> 147</para></description><returns><para>A const reverse random access iterator pointing to the last element of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. If the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> is empty it returns an iterator equal to the one returned by <computeroutput>rend() const</computeroutput>. </para> 148</returns><throws><simpara><classname>Nothing.</classname> </simpara></throws></method> 149<method name="rend" cv="const noexcept"><type>const_reverse_iterator</type><purpose>Get the const iterator pointing to the end of the "reversed" <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </purpose><description><para> 150 151<formalpara><title>Exception Safety</title><para>No-throw. </para> 152</formalpara> 153<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators. </para> 154</formalpara> 155<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>). </para> 156</formalpara> 157<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>rbegin() const</computeroutput>, <computeroutput>begin() const</computeroutput>, <computeroutput>end() const</computeroutput> </para> 158</para> 159</para></description><returns><para>A const reverse random access iterator pointing to the element "one before" the first element of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. If the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> is empty it returns an iterator equal to the one returned by <computeroutput>rbegin() const</computeroutput>. </para> 160</returns><throws><simpara><classname>Nothing.</classname> </simpara></throws></method> 161<method name="operator []"><type>reference</type><parameter name="index"><paramtype>size_type</paramtype><description><para>The position of the element. </para></description></parameter><purpose>Get the element at the <computeroutput>index</computeroutput> position. </purpose><description><para> 162 163 164 165<formalpara><title>Exception Safety</title><para>No-throw. </para> 166</formalpara> 167<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators. </para> 168</formalpara> 169<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>). </para> 170</formalpara> 171<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>at()</computeroutput> </para> 172</para> 173</para></description><requires><para><computeroutput>0 <= index && index < size()</computeroutput> </para> 174</requires><returns><para>A reference to the element at the <computeroutput>index</computeroutput> position. </para> 175</returns><throws><simpara><classname>Nothing.</classname> </simpara></throws></method> 176<method name="operator []" cv="const"><type>const_reference</type><parameter name="index"><paramtype>size_type</paramtype><description><para>The position of the element. </para></description></parameter><purpose>Get the element at the <computeroutput>index</computeroutput> position. </purpose><description><para> 177 178 179 180<formalpara><title>Exception Safety</title><para>No-throw. </para> 181</formalpara> 182<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators. </para> 183</formalpara> 184<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>). </para> 185</formalpara> 186<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>at() const </computeroutput> </para> 187</para> 188</para></description><requires><para><computeroutput>0 <= index && index < size()</computeroutput> </para> 189</requires><returns><para>A const reference to the element at the <computeroutput>index</computeroutput> position. </para> 190</returns><throws><simpara><classname>Nothing.</classname> </simpara></throws></method> 191<method name="at"><type>reference</type><parameter name="index"><paramtype>size_type</paramtype><description><para>The position of the element. </para></description></parameter><purpose>Get the element at the <computeroutput>index</computeroutput> position. </purpose><description><para> 192 193 194<formalpara><title>Exception Safety</title><para>Strong. </para> 195</formalpara> 196<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators. </para> 197</formalpara> 198<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>). </para> 199</formalpara> 200<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>operator[] </computeroutput> </para> 201</para> 202</para></description><returns><para>A reference to the element at the <computeroutput>index</computeroutput> position. </para> 203</returns><throws><simpara><classname><code>std::out_of_range</code></classname> when the <computeroutput>index</computeroutput> is invalid (when <computeroutput>index >= size()</computeroutput>). </simpara></throws></method> 204<method name="at" cv="const"><type>const_reference</type><parameter name="index"><paramtype>size_type</paramtype><description><para>The position of the element. </para></description></parameter><purpose>Get the element at the <computeroutput>index</computeroutput> position. </purpose><description><para> 205 206 207<formalpara><title>Exception Safety</title><para>Strong. </para> 208</formalpara> 209<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators. </para> 210</formalpara> 211<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>). </para> 212</formalpara> 213<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>operator[] const </computeroutput> </para> 214</para> 215</para></description><returns><para>A const reference to the element at the <computeroutput>index</computeroutput> position. </para> 216</returns><throws><simpara><classname><code>std::out_of_range</code></classname> when the <computeroutput>index</computeroutput> is invalid (when <computeroutput>index >= size()</computeroutput>). </simpara></throws></method> 217<method name="front"><type>reference</type><purpose>Get the first element. </purpose><description><para> 218 219 220<formalpara><title>Exception Safety</title><para>No-throw. </para> 221</formalpara> 222<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators. </para> 223</formalpara> 224<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>). </para> 225</formalpara> 226<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>back()</computeroutput> </para> 227</para> 228</para></description><requires><para><computeroutput>!empty()</computeroutput> </para> 229</requires><returns><para>A reference to the first element of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </para> 230</returns><throws><simpara><classname>Nothing.</classname> </simpara></throws></method> 231<method name="back"><type>reference</type><purpose>Get the last element. </purpose><description><para> 232 233 234<formalpara><title>Exception Safety</title><para>No-throw. </para> 235</formalpara> 236<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators. </para> 237</formalpara> 238<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>). </para> 239</formalpara> 240<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>front()</computeroutput> </para> 241</para> 242</para></description><requires><para><computeroutput>!empty()</computeroutput> </para> 243</requires><returns><para>A reference to the last element of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </para> 244</returns><throws><simpara><classname>Nothing.</classname> </simpara></throws></method> 245<method name="front" cv="const"><type>const_reference</type><purpose>Get the first element. </purpose><description><para> 246 247 248<formalpara><title>Exception Safety</title><para>No-throw. </para> 249</formalpara> 250<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators. </para> 251</formalpara> 252<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>). </para> 253</formalpara> 254<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>back() const</computeroutput> </para> 255</para> 256</para></description><requires><para><computeroutput>!empty()</computeroutput> </para> 257</requires><returns><para>A const reference to the first element of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </para> 258</returns><throws><simpara><classname>Nothing.</classname> </simpara></throws></method> 259<method name="back" cv="const"><type>const_reference</type><purpose>Get the last element. </purpose><description><para> 260 261 262<formalpara><title>Exception Safety</title><para>No-throw. </para> 263</formalpara> 264<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators. </para> 265</formalpara> 266<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>). </para> 267</formalpara> 268<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>front() const</computeroutput> </para> 269</para> 270</para></description><requires><para><computeroutput>!empty()</computeroutput> </para> 271</requires><returns><para>A const reference to the last element of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </para> 272</returns><throws><simpara><classname>Nothing.</classname> </simpara></throws></method> 273<method name="array_one"><type>array_range</type><purpose>Get the first continuous array of the internal buffer. </purpose><description><para>This method in combination with <computeroutput>array_two()</computeroutput> can be useful when passing the stored data into a legacy C API as an array. Suppose there is a <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> of capacity 10, containing 7 characters <computeroutput>'a', 'b', ..., 'g'</computeroutput> where <computeroutput>buff[0] == 'a'</computeroutput>, <computeroutput>buff[1] == 'b'</computeroutput>, ... and <computeroutput>buff[6] == 'g'</computeroutput>:<sbr/> 274<sbr/> 275 <computeroutput>circular_buffer<char> buff(10);</computeroutput><sbr/> 276<sbr/> 277 The internal representation is often not linear and the state of the internal buffer may look like this:<sbr/> 278 <sbr/> 279<computeroutput> |e|f|g| | | |a|b|c|d|<sbr/> 280 end ___^<sbr/> 281 begin _______^</computeroutput><sbr/> 282<sbr/> 283</para><para>where <computeroutput>|a|b|c|d|</computeroutput> represents the "array one", <computeroutput>|e|f|g|</computeroutput> represents the "array two" and <computeroutput>| | | |</computeroutput> is a free space.<sbr/> 284 Now consider a typical C style function for writing data into a file:<sbr/> 285<sbr/> 286 <computeroutput>int write(int file_desc, char* buff, int num_bytes);</computeroutput><sbr/> 287<sbr/> 288 There are two ways how to write the content of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> into a file. Either relying on <computeroutput>array_one()</computeroutput> and <computeroutput>array_two()</computeroutput> methods and calling the write function twice:<sbr/> 289<sbr/> 290 <computeroutput>array_range ar = buff.array_one();<sbr/> 291 write(file_desc, ar.first, ar.second);<sbr/> 292 ar = buff.array_two();<sbr/> 293 write(file_desc, ar.first, ar.second);</computeroutput><sbr/> 294<sbr/> 295 Or relying on the <computeroutput>linearize()</computeroutput> method:<sbr/> 296<sbr/> 297<computeroutput> write(file_desc, buff.linearize(), buff.size());</computeroutput><sbr/> 298<sbr/> 299 Since the complexity of <computeroutput>array_one()</computeroutput> and <computeroutput>array_two()</computeroutput> methods is constant the first option is suitable when calling the write method is "cheap". On the other hand the second option is more suitable when calling the write method is more "expensive" than calling the <computeroutput>linearize()</computeroutput> method whose complexity is linear. 300 301<formalpara><title>Exception Safety</title><para>No-throw. </para> 302</formalpara> 303<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators. </para> 304</formalpara> 305<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>). </para> 306</formalpara> 307<warning><para>In general invoking any method which modifies the internal state of the <classname alt="boost::circular_buffer">circular_buffer</classname> may delinearize the internal buffer and invalidate the array ranges returned by <computeroutput>array_one()</computeroutput> and <computeroutput>array_two()</computeroutput> (and their const versions). </para> 308</warning> 309<note><para>In the case the internal buffer is linear e.g. <computeroutput>|a|b|c|d|e|f|g| | | |</computeroutput> the "array one" is represented by <computeroutput>|a|b|c|d|e|f|g|</computeroutput> and the "array two" does not exist (the <computeroutput>array_two()</computeroutput> method returns an array with the size <computeroutput>0</computeroutput>). </para> 310</note> 311<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>array_two()</computeroutput>, <computeroutput>linearize()</computeroutput> </para> 312</para> 313</para></description><returns><para>The array range of the first continuous array of the internal buffer. In the case the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> is empty the size of the returned array is <computeroutput>0</computeroutput>. </para> 314</returns><throws><simpara><classname>Nothing.</classname> </simpara></throws></method> 315<method name="array_two"><type>array_range</type><purpose>Get the second continuous array of the internal buffer. </purpose><description><para>This method in combination with <computeroutput>array_one()</computeroutput> can be useful when passing the stored data into a legacy C API as an array. 316 317<formalpara><title>Exception Safety</title><para>No-throw. </para> 318</formalpara> 319<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators. </para> 320</formalpara> 321<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>). </para> 322</formalpara> 323<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>array_one()</computeroutput> </para> 324</para> 325</para></description><returns><para>The array range of the second continuous array of the internal buffer. In the case the internal buffer is linear or the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> is empty the size of the returned array is <computeroutput>0</computeroutput>. </para> 326</returns><throws><simpara><classname>Nothing.</classname> </simpara></throws></method> 327<method name="array_one" cv="const"><type>const_array_range</type><purpose>Get the first continuous array of the internal buffer. </purpose><description><para>This method in combination with <computeroutput>array_two() const</computeroutput> can be useful when passing the stored data into a legacy C API as an array. 328 329<formalpara><title>Exception Safety</title><para>No-throw. </para> 330</formalpara> 331<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators. </para> 332</formalpara> 333<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>). </para> 334</formalpara> 335<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>array_two() const</computeroutput>; <computeroutput>array_one()</computeroutput> for more details how to pass data into a legacy C API. </para> 336</para> 337</para></description><returns><para>The array range of the first continuous array of the internal buffer. In the case the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> is empty the size of the returned array is <computeroutput>0</computeroutput>. </para> 338</returns><throws><simpara><classname>Nothing.</classname> </simpara></throws></method> 339<method name="array_two" cv="const"><type>const_array_range</type><purpose>Get the second continuous array of the internal buffer. </purpose><description><para>This method in combination with <computeroutput>array_one() const</computeroutput> can be useful when passing the stored data into a legacy C API as an array. 340 341<formalpara><title>Exception Safety</title><para>No-throw. </para> 342</formalpara> 343<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators. </para> 344</formalpara> 345<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>). </para> 346</formalpara> 347<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>array_one() const</computeroutput> </para> 348</para> 349</para></description><returns><para>The array range of the second continuous array of the internal buffer. In the case the internal buffer is linear or the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> is empty the size of the returned array is <computeroutput>0</computeroutput>. </para> 350</returns><throws><simpara><classname>Nothing.</classname> </simpara></throws></method> 351<method name="linearize"><type>pointer</type><purpose>Linearize the internal buffer into a continuous array. </purpose><description><para>This method can be useful when passing the stored data into a legacy C API as an array. 352 353 354<formalpara><title>Exception Safety</title><para>Basic; no-throw if the operations in the <emphasis>Throws</emphasis> section do not throw anything. </para> 355</formalpara> 356<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>); does not invalidate any iterators if the postcondition (the <emphasis>Effect</emphasis>) is already met prior calling this method. </para> 357</formalpara> 358<formalpara><title>Complexity</title><para>Linear (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>); constant if the postcondition (the <emphasis>Effect</emphasis>) is already met. </para> 359</formalpara> 360<warning><para>In general invoking any method which modifies the internal state of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> may delinearize the internal buffer and invalidate the returned pointer. </para> 361</warning> 362<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>array_one()</computeroutput> and <computeroutput>array_two()</computeroutput> for the other option how to pass data into a legacy C API; <computeroutput>is_linearized()</computeroutput>, <computeroutput>rotate(const_iterator)</computeroutput> </para> 363</para> 364</para></description><postconditions><para><computeroutput>&(*this)[0] < &(*this)[1] < ... < &(*this)[size() - 1]</computeroutput> </para> 365</postconditions><returns><para>A pointer to the beginning of the array or <computeroutput>0</computeroutput> if empty. </para> 366</returns><throws><simpara><classname><a</classname> href="circular_buffer/implementation.html#circular_buffer.implementation.exceptions_of_move_if_noexcept_t">Exceptions of move_if_noexcept(T&). </simpara></throws></method> 367<method name="is_linearized" cv="const noexcept"><type>bool</type><purpose>Is the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> linearized? </purpose><description><para> 368 369<formalpara><title>Exception Safety</title><para>No-throw. </para> 370</formalpara> 371<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators. </para> 372</formalpara> 373<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>). </para> 374</formalpara> 375<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>linearize()</computeroutput>, <computeroutput>array_one()</computeroutput>, <computeroutput>array_two()</computeroutput> </para> 376</para> 377</para></description><returns><para><computeroutput>true</computeroutput> if the internal buffer is linearized into a continuous array (i.e. the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> meets a condition <computeroutput>&(*this)[0] < &(*this)[1] < ... < &(*this)[size() - 1]</computeroutput>); <computeroutput>false</computeroutput> otherwise. </para> 378</returns><throws><simpara><classname>Nothing.</classname> </simpara></throws></method> 379<method name="rotate"><type>void</type><parameter name="new_begin"><paramtype>const_iterator</paramtype><description><para>The new beginning. </para></description></parameter><purpose>Rotate elements in the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </purpose><description><para>A more effective implementation of <computeroutput><ulink url="https://www.boost.org/sgi/stl/rotate.html">std::rotate</ulink></computeroutput>. 380 381 382 383<formalpara><title>Exception Safety</title><para>Basic; no-throw if the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> is full or <computeroutput>new_begin</computeroutput> points to <computeroutput>begin()</computeroutput> or if the operations in the <emphasis>Throws</emphasis> section do not throw anything. </para> 384</formalpara> 385<formalpara><title>Iterator Invalidation</title><para>If <computeroutput>m < n</computeroutput> invalidates iterators pointing to the last <computeroutput>m</computeroutput> elements (<emphasis role="bold">including</emphasis> <computeroutput>new_begin</computeroutput>, but not iterators equal to <computeroutput>end()</computeroutput>) else invalidates iterators pointing to the first <computeroutput>n</computeroutput> elements; does not invalidate any iterators if the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> is full. </para> 386</formalpara> 387<formalpara><title>Complexity</title><para>Linear (in <computeroutput>(std::min)(m, n)</computeroutput>); constant if the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> is full. </para> 388</formalpara> 389<para><emphasis role="bold">See Also:</emphasis><para><computeroutput><ulink url="https://www.boost.org/sgi/stl/rotate.html">std::rotate</ulink></computeroutput> </para> 390</para> 391</para></description><requires><para><computeroutput>new_begin</computeroutput> is a valid iterator pointing to the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> <emphasis role="bold">except</emphasis> its end. </para> 392</requires><postconditions><para>Before calling the method suppose:<sbr/> 393<sbr/> 394 <computeroutput>m == std::distance(new_begin, end())</computeroutput><sbr/> 395<computeroutput>n == std::distance(begin(), new_begin)</computeroutput> <sbr/> 396<computeroutput>val_0 == *new_begin, val_1 == *(new_begin + 1), ... val_m == *(new_begin + m)</computeroutput><sbr/> 397 <computeroutput>val_r1 == *(new_begin - 1), val_r2 == *(new_begin - 2), ... val_rn == *(new_begin - n)</computeroutput><sbr/> 398 <sbr/> 399then after call to the method:<sbr/> 400<sbr/> 401 <computeroutput>val_0 == (*this)[0] && val_1 == (*this)[1] && ... && val_m == (*this)[m - 1] && val_r1 == (*this)[m + n - 1] && val_r2 == (*this)[m + n - 2] && ... && val_rn == (*this)[m]</computeroutput> </para> 402</postconditions><throws><simpara><classname>See</classname> <ulink url="circular_buffer/implementation.html#circular_buffer.implementation.exceptions_of_move_if_noexcept_t">Exceptions of move_if_noexcept(T&)</ulink>. </simpara></throws></method> 403<method name="size" cv="const noexcept"><type>size_type</type><purpose>Get the number of elements currently stored in the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </purpose><description><para> 404 405<formalpara><title>Exception Safety</title><para>No-throw. </para> 406</formalpara> 407<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators. </para> 408</formalpara> 409<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>). </para> 410</formalpara> 411<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>capacity()</computeroutput>, <computeroutput>max_size()</computeroutput>, <computeroutput>reserve()</computeroutput>, <computeroutput>resize(size_type, const_reference)</computeroutput> </para> 412</para> 413</para></description><returns><para>The number of elements stored in the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </para> 414</returns><throws><simpara><classname>Nothing.</classname> </simpara></throws></method> 415<method name="max_size" cv="const noexcept"><type>size_type</type><purpose>Get the largest possible size or capacity of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. (It depends on allocator's max_size()). </purpose><description><para> 416 417<formalpara><title>Exception Safety</title><para>No-throw. </para> 418</formalpara> 419<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators. </para> 420</formalpara> 421<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>). </para> 422</formalpara> 423<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>size()</computeroutput>, <computeroutput>capacity()</computeroutput>, <computeroutput>reserve()</computeroutput> </para> 424</para> 425</para></description><returns><para>The maximum size/capacity the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> can be set to. </para> 426</returns><throws><simpara><classname>Nothing.</classname> </simpara></throws></method> 427<method name="empty" cv="const noexcept"><type>bool</type><purpose>Is the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> empty? </purpose><description><para> 428 429<formalpara><title>Exception Safety</title><para>No-throw. </para> 430</formalpara> 431<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators. </para> 432</formalpara> 433<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>). </para> 434</formalpara> 435<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>full()</computeroutput> </para> 436</para> 437</para></description><returns><para><computeroutput>true</computeroutput> if there are no elements stored in the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>; <computeroutput>false</computeroutput> otherwise. </para> 438</returns><throws><simpara><classname>Nothing.</classname> </simpara></throws></method> 439<method name="full" cv="const noexcept"><type>bool</type><purpose>Is the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> full? </purpose><description><para> 440 441<formalpara><title>Exception Safety</title><para>No-throw. </para> 442</formalpara> 443<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators. </para> 444</formalpara> 445<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>). </para> 446</formalpara> 447<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>empty()</computeroutput> </para> 448</para> 449</para></description><returns><para><computeroutput>true</computeroutput> if the number of elements stored in the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> equals the capacity of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>; <computeroutput>false</computeroutput> otherwise. </para> 450</returns><throws><simpara><classname>Nothing.</classname> </simpara></throws></method> 451<method name="reserve" cv="const noexcept"><type>size_type</type><purpose>Get the maximum number of elements which can be inserted into the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> without overwriting any of already stored elements. </purpose><description><para> 452 453<formalpara><title>Exception Safety</title><para>No-throw. </para> 454</formalpara> 455<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators. </para> 456</formalpara> 457<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>). </para> 458</formalpara> 459<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>capacity()</computeroutput>, <computeroutput>size()</computeroutput>, <computeroutput>max_size()</computeroutput> </para> 460</para> 461</para></description><returns><para><computeroutput>capacity() - size()</computeroutput> </para> 462</returns><throws><simpara><classname>Nothing.</classname> </simpara></throws></method> 463<method name="capacity" cv="const noexcept"><type>capacity_type</type><purpose>Get the capacity of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </purpose><description><para> 464 465<formalpara><title>Exception Safety</title><para>No-throw. </para> 466</formalpara> 467<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators. </para> 468</formalpara> 469<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>). </para> 470</formalpara> 471<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>reserve()</computeroutput>, <computeroutput>size()</computeroutput>, <computeroutput>max_size()</computeroutput>, <computeroutput>set_capacity(capacity_type)</computeroutput> </para> 472</para> 473</para></description><returns><para>The maximum number of elements which can be stored in the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </para> 474</returns><throws><simpara><classname>Nothing.</classname> </simpara></throws></method> 475<method name="set_capacity"><type>void</type><parameter name="new_capacity"><paramtype>capacity_type</paramtype><description><para>The new capacity. </para></description></parameter><purpose>Change the capacity of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </purpose><description><para> 476 477 478 479<formalpara><title>Exception Safety</title><para>Strong. </para> 480</formalpara> 481<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>) if the new capacity is different from the original. </para> 482</formalpara> 483<formalpara><title>Complexity</title><para>Linear (in <computeroutput>min[size(), new_capacity]</computeroutput>). </para> 484</formalpara> 485<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>rset_capacity(capacity_type)</computeroutput>, <computeroutput>resize(size_type, const_reference)</computeroutput> </para> 486</para> 487</para></description><requires><para>If <computeroutput>T</computeroutput> is a move only type, then compiler shall support <computeroutput>noexcept</computeroutput> modifiers and move constructor of <computeroutput>T</computeroutput> must be marked with it (must not throw exceptions). </para> 488</requires><postconditions><para><computeroutput>capacity() == new_capacity && size() <= new_capacity</computeroutput><sbr/> 489<sbr/> 490 If the current number of elements stored in the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> is greater than the desired new capacity then number of <computeroutput>[size() - new_capacity]</computeroutput> <emphasis role="bold">last</emphasis> elements will be removed and the new size will be equal to <computeroutput>new_capacity</computeroutput>. </para> 491</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted, (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T(const T&)</computeroutput> throws or nothing if <computeroutput>T::T(T&&)</computeroutput> is noexcept. </simpara></throws></method> 492<method name="resize"><type>void</type><parameter name="new_size"><paramtype>size_type</paramtype><description><para>The new size. </para></description></parameter><parameter name="item"><paramtype>param_value_type</paramtype><default>value_type()</default><description><para>The element the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> will be filled with in order to gain the requested size. (See the <emphasis>Effect</emphasis>.) </para></description></parameter><purpose>Change the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </purpose><description><para> 493 494 495<formalpara><title>Exception Safety</title><para>Basic. </para> 496</formalpara> 497<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>) if the new size is greater than the current capacity. Invalidates iterators pointing to the removed elements if the new size is lower that the original size. Otherwise it does not invalidate any iterator. </para> 498</formalpara> 499<formalpara><title>Complexity</title><para>Linear (in the new size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>). </para> 500</formalpara> 501<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>rresize(size_type, const_reference)</computeroutput>, <computeroutput>set_capacity(capacity_type)</computeroutput> </para> 502</para> 503</para></description><postconditions><para><computeroutput>size() == new_size && capacity() >= new_size</computeroutput><sbr/> 504<sbr/> 505 If the new size is greater than the current size, copies of <computeroutput>item</computeroutput> will be inserted at the <emphasis role="bold">back</emphasis> of the of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> in order to achieve the desired size. In the case the resulting size exceeds the current capacity the capacity will be set to <computeroutput>new_size</computeroutput>.<sbr/> 506 If the current number of elements stored in the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> is greater than the desired new size then number of <computeroutput>[size() - new_size]</computeroutput> <emphasis role="bold">last</emphasis> elements will be removed. (The capacity will remain unchanged.) </para> 507</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T(const T&)</computeroutput> throws or nothing if <computeroutput>T::T(T&&)</computeroutput> is noexcept. </simpara></throws></method> 508<method name="rset_capacity"><type>void</type><parameter name="new_capacity"><paramtype>capacity_type</paramtype><description><para>The new capacity. </para></description></parameter><purpose>Change the capacity of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </purpose><description><para> 509 510 511 512<formalpara><title>Exception Safety</title><para>Strong. </para> 513</formalpara> 514<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>) if the new capacity is different from the original. </para> 515</formalpara> 516<formalpara><title>Complexity</title><para>Linear (in <computeroutput>min[size(), new_capacity]</computeroutput>). </para> 517</formalpara> 518<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>set_capacity(capacity_type)</computeroutput>, <computeroutput>rresize(size_type, const_reference)</computeroutput> </para> 519</para> 520</para></description><requires><para>If <computeroutput>T</computeroutput> is a move only type, then compiler shall support <computeroutput>noexcept</computeroutput> modifiers and move constructor of <computeroutput>T</computeroutput> must be marked with it (must not throw exceptions). </para> 521</requires><postconditions><para><computeroutput>capacity() == new_capacity && size() <= new_capacity</computeroutput><sbr/> 522<sbr/> 523 If the current number of elements stored in the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> is greater than the desired new capacity then number of <computeroutput>[size() - new_capacity]</computeroutput> <emphasis role="bold">first</emphasis> elements will be removed and the new size will be equal to <computeroutput>new_capacity</computeroutput>. </para> 524</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T(const T&)</computeroutput> throws or nothing if <computeroutput>T::T(T&&)</computeroutput> is noexcept. </simpara></throws></method> 525<method name="rresize"><type>void</type><parameter name="new_size"><paramtype>size_type</paramtype><description><para>The new size. </para></description></parameter><parameter name="item"><paramtype>param_value_type</paramtype><default>value_type()</default><description><para>The element the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> will be filled with in order to gain the requested size. (See the <emphasis>Effect</emphasis>.) </para></description></parameter><purpose>Change the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </purpose><description><para> 526 527 528<formalpara><title>Exception Safety</title><para>Basic. </para> 529</formalpara> 530<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>) if the new size is greater than the current capacity. Invalidates iterators pointing to the removed elements if the new size is lower that the original size. Otherwise it does not invalidate any iterator. </para> 531</formalpara> 532<formalpara><title>Complexity</title><para>Linear (in the new size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>). </para> 533</formalpara> 534<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>resize(size_type, const_reference)</computeroutput>, <computeroutput>rset_capacity(capacity_type)</computeroutput> </para> 535</para> 536</para></description><postconditions><para><computeroutput>size() == new_size && capacity() >= new_size</computeroutput><sbr/> 537<sbr/> 538 If the new size is greater than the current size, copies of <computeroutput>item</computeroutput> will be inserted at the <emphasis role="bold">front</emphasis> of the of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> in order to achieve the desired size. In the case the resulting size exceeds the current capacity the capacity will be set to <computeroutput>new_size</computeroutput>.<sbr/> 539 If the current number of elements stored in the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> is greater than the desired new size then number of <computeroutput>[size() - new_size]</computeroutput> <emphasis role="bold">first</emphasis> elements will be removed. (The capacity will remain unchanged.) </para> 540</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T(const T&)</computeroutput> throws or nothing if <computeroutput>T::T(T&&)</computeroutput> is noexcept. </simpara></throws></method> 541<method name="assign"><type>void</type><parameter name="n"><paramtype>size_type</paramtype><description><para>The number of elements the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> will be filled with. </para></description></parameter><parameter name="item"><paramtype>param_value_type</paramtype><description><para>The element the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> will be filled with. </para></description></parameter><purpose>Assign <computeroutput>n</computeroutput> items into the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </purpose><description><para>The content of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> will be removed and replaced with <computeroutput>n</computeroutput> copies of the <computeroutput>item</computeroutput>. 542 543 544<formalpara><title>Exception Safety</title><para>Basic. </para> 545</formalpara> 546<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>). </para> 547</formalpara> 548<formalpara><title>Complexity</title><para>Linear (in the <computeroutput>n</computeroutput>). </para> 549</formalpara> 550<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>operator=</computeroutput>, <computeroutput>assign(capacity_type, size_type, const_reference)</computeroutput>, <computeroutput>assign(InputIterator, InputIterator)</computeroutput>, <computeroutput>assign(capacity_type, InputIterator, InputIterator)</computeroutput> </para> 551</para> 552</para></description><postconditions><para><computeroutput>capacity() == n && size() == n && (*this)[0] == item && (*this)[1] == item && ... && (*this) [n - 1] == item</computeroutput> </para> 553</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T(const T&)</computeroutput> throws. </simpara></throws></method> 554<method name="assign"><type>void</type><parameter name="buffer_capacity"><paramtype>capacity_type</paramtype><description><para>The new capacity. </para></description></parameter><parameter name="n"><paramtype>size_type</paramtype><description><para>The number of elements the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> will be filled with. </para></description></parameter><parameter name="item"><paramtype>param_value_type</paramtype><description><para>The element the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> will be filled with. </para></description></parameter><purpose>Assign <computeroutput>n</computeroutput> items into the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> specifying the capacity. </purpose><description><para>The capacity of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> will be set to the specified value and the content of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> will be removed and replaced with <computeroutput>n</computeroutput> copies of the <computeroutput>item</computeroutput>. 555 556 557 558<formalpara><title>Exception Safety</title><para>Basic. </para> 559</formalpara> 560<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>). </para> 561</formalpara> 562<formalpara><title>Complexity</title><para>Linear (in the <computeroutput>n</computeroutput>). </para> 563</formalpara> 564<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>operator=</computeroutput>, <computeroutput>assign(size_type, const_reference)</computeroutput>, <computeroutput>assign(InputIterator, InputIterator)</computeroutput>, <computeroutput>assign(capacity_type, InputIterator, InputIterator)</computeroutput> </para> 565</para> 566</para></description><requires><para><computeroutput>capacity >= n</computeroutput> </para> 567</requires><postconditions><para><computeroutput>capacity() == buffer_capacity && size() == n && (*this)[0] == item && (*this)[1] == item && ... && (*this) [n - 1] == item </computeroutput> </para> 568</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T(const T&)</computeroutput> throws. </simpara></throws></method> 569<method name="assign"><type>void</type><template> 570 <template-type-parameter name="InputIterator"/> 571 </template><parameter name="first"><paramtype>InputIterator</paramtype><description><para>The beginning of the range to be copied. </para></description></parameter><parameter name="last"><paramtype>InputIterator</paramtype><description><para>The end of the range to be copied. </para></description></parameter><purpose>Assign a copy of the range into the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </purpose><description><para>The content of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> will be removed and replaced with copies of elements from the specified range. 572 573 574 575<formalpara><title>Exception Safety</title><para>Basic. </para> 576</formalpara> 577<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>). </para> 578</formalpara> 579<formalpara><title>Complexity</title><para>Linear (in the <computeroutput>std::distance(first, last)</computeroutput>). </para> 580</formalpara> 581<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>operator=</computeroutput>, <computeroutput>assign(size_type, const_reference)</computeroutput>, <computeroutput>assign(capacity_type, size_type, const_reference)</computeroutput>, <computeroutput>assign(capacity_type, InputIterator, InputIterator)</computeroutput> </para> 582</para> 583</para></description><requires><para>Valid range <computeroutput>[first, last)</computeroutput>.<sbr/> 584 <computeroutput>first</computeroutput> and <computeroutput>last</computeroutput> have to meet the requirements of <ulink url="https://www.boost.org/sgi/stl/InputIterator.html">InputIterator</ulink>. </para> 585</requires><postconditions><para><computeroutput>capacity() == std::distance(first, last) && size() == std::distance(first, last) && (*this)[0]== *first && (*this)[1] == *(first + 1) && ... && (*this)[std::distance(first, last) - 1] == *(last - 1)</computeroutput> </para> 586</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T(const T&)</computeroutput> throws. </simpara></throws></method> 587<method name="assign"><type>void</type><template> 588 <template-type-parameter name="InputIterator"/> 589 </template><parameter name="buffer_capacity"><paramtype>capacity_type</paramtype><description><para>The new capacity. </para></description></parameter><parameter name="first"><paramtype>InputIterator</paramtype><description><para>The beginning of the range to be copied. </para></description></parameter><parameter name="last"><paramtype>InputIterator</paramtype><description><para>The end of the range to be copied. </para></description></parameter><purpose>Assign a copy of the range into the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> specifying the capacity. </purpose><description><para>The capacity of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> will be set to the specified value and the content of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> will be removed and replaced with copies of elements from the specified range. 590 591 592 593<formalpara><title>Exception Safety</title><para>Basic. </para> 594</formalpara> 595<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>). </para> 596</formalpara> 597<formalpara><title>Complexity</title><para>Linear (in <computeroutput>std::distance(first, last)</computeroutput>; in <computeroutput>min[capacity, std::distance(first, last)]</computeroutput> if the <computeroutput>InputIterator</computeroutput> is a <ulink url="https://www.boost.org/sgi/stl/RandomAccessIterator.html">RandomAccessIterator</ulink>). </para> 598</formalpara> 599<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>operator=</computeroutput>, <computeroutput>assign(size_type, const_reference)</computeroutput>, <computeroutput>assign(capacity_type, size_type, const_reference)</computeroutput>, <computeroutput>assign(InputIterator, InputIterator)</computeroutput> </para> 600</para> 601</para></description><requires><para>Valid range <computeroutput>[first, last)</computeroutput>.<sbr/> 602 <computeroutput>first</computeroutput> and <computeroutput>last</computeroutput> have to meet the requirements of <ulink url="https://www.boost.org/sgi/stl/InputIterator.html">InputIterator</ulink>. </para> 603</requires><postconditions><para><computeroutput>capacity() == buffer_capacity && size() <= std::distance(first, last) && (*this)[0]== *(last - buffer_capacity) && (*this)[1] == *(last - buffer_capacity + 1) && ... && (*this)[buffer_capacity - 1] == *(last - 1)</computeroutput><sbr/> 604<sbr/> 605 If the number of items to be copied from the range <computeroutput>[first, last)</computeroutput> is greater than the specified <computeroutput>buffer_capacity</computeroutput> then only elements from the range <computeroutput>[last - buffer_capacity, last)</computeroutput> will be copied. </para> 606</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T(const T&)</computeroutput> throws. </simpara></throws></method> 607<method name="swap" cv="noexcept"><type>void</type><parameter name="cb"><paramtype><classname>circular_buffer</classname>< T, Alloc > &</paramtype><description><para>The <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> whose content will be swapped. </para></description></parameter><purpose>Swap the contents of two <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>s. </purpose><description><para> 608 609 610<formalpara><title>Exception Safety</title><para>No-throw. </para> 611</formalpara> 612<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators of both <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>s. (On the other hand the iterators still point to the same elements but within another container. If you want to rely on this feature you have to turn the <ulink url="#debug">Debug Support</ulink> off otherwise an assertion will report an error if such invalidated iterator is used.) </para> 613</formalpara> 614<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>). </para> 615</formalpara> 616<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>swap(circular_buffer<T, Alloc>&, circular_buffer<T, Alloc>&)</computeroutput> </para> 617</para> 618</para></description><postconditions><para><computeroutput>this</computeroutput> contains elements of <computeroutput>cb</computeroutput> and vice versa; the capacity of <computeroutput>this</computeroutput> equals to the capacity of <computeroutput>cb</computeroutput> and vice versa. </para> 619</postconditions><throws><simpara><classname>Nothing.</classname> </simpara></throws></method> 620<method name="push_back"><type>void</type><parameter name="item"><paramtype>param_value_type</paramtype><description><para>The element to be inserted. </para></description></parameter><purpose>Insert a new element at the end of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </purpose><description><para> 621 622 623<formalpara><title>Exception Safety</title><para>Basic; no-throw if the operation in the <emphasis>Throws</emphasis> section does not throw anything. </para> 624</formalpara> 625<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators with the exception of iterators pointing to the overwritten element. </para> 626</formalpara> 627<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>). </para> 628</formalpara> 629<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>push_front(const_reference)</computeroutput>, <computeroutput>pop_back()</computeroutput>, <computeroutput>pop_front()</computeroutput> </para> 630</para> 631</para></description><postconditions><para>if <computeroutput>capacity() > 0</computeroutput> then <computeroutput>back() == item</computeroutput><sbr/> 632 If the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> is full, the first element will be removed. If the capacity is <computeroutput>0</computeroutput>, nothing will be inserted. </para> 633</postconditions><throws><simpara><classname>Whatever</classname> <computeroutput>T::T(const T&)</computeroutput> throws. Whatever <computeroutput>T::operator = (const T&)</computeroutput> throws. </simpara></throws></method> 634<method name="push_back"><type>void</type><parameter name="item"><paramtype>rvalue_type</paramtype><description><para>The element to be inserted. </para></description></parameter><purpose>Insert a new element at the end of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> using rvalue references or rvalues references emulation. </purpose><description><para> 635 636 637<formalpara><title>Exception Safety</title><para>Basic; no-throw if the operation in the <emphasis>Throws</emphasis> section does not throw anything. </para> 638</formalpara> 639<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators with the exception of iterators pointing to the overwritten element. </para> 640</formalpara> 641<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>). </para> 642</formalpara> 643<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>push_front(const_reference)</computeroutput>, <computeroutput>pop_back()</computeroutput>, <computeroutput>pop_front()</computeroutput> </para> 644</para> 645</para></description><postconditions><para>if <computeroutput>capacity() > 0</computeroutput> then <computeroutput>back() == item</computeroutput><sbr/> 646 If the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> is full, the first element will be removed. If the capacity is <computeroutput>0</computeroutput>, nothing will be inserted. </para> 647</postconditions><throws><simpara><classname>Whatever</classname> <computeroutput>T::T(T&&)</computeroutput> throws. Whatever <computeroutput>T::operator = (T&&)</computeroutput> throws. </simpara></throws></method> 648<method name="push_back"><type>void</type><purpose>Insert a new default-constructed element at the end of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </purpose><description><para> 649 650<formalpara><title>Exception Safety</title><para>Basic; no-throw if the operation in the <emphasis>Throws</emphasis> section does not throw anything. </para> 651</formalpara> 652<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators with the exception of iterators pointing to the overwritten element. </para> 653</formalpara> 654<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>). </para> 655</formalpara> 656<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>push_front(const_reference)</computeroutput>, <computeroutput>pop_back()</computeroutput>, <computeroutput>pop_front()</computeroutput> </para> 657</para> 658</para></description><postconditions><para>if <computeroutput>capacity() > 0</computeroutput> then <computeroutput>back() == item</computeroutput><sbr/> 659 If the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> is full, the first element will be removed. If the capacity is <computeroutput>0</computeroutput>, nothing will be inserted. </para> 660</postconditions><throws><simpara><classname>Whatever</classname> <computeroutput>T::T()</computeroutput> throws. Whatever <computeroutput>T::T(T&&)</computeroutput> throws. Whatever <computeroutput>T::operator = (T&&)</computeroutput> throws. </simpara></throws></method> 661<method name="push_front"><type>void</type><parameter name="item"><paramtype>param_value_type</paramtype><description><para>The element to be inserted. </para></description></parameter><purpose>Insert a new element at the beginning of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </purpose><description><para> 662 663 664<formalpara><title>Exception Safety</title><para>Basic; no-throw if the operation in the <emphasis>Throws</emphasis> section does not throw anything. </para> 665</formalpara> 666<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators with the exception of iterators pointing to the overwritten element. </para> 667</formalpara> 668<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>). </para> 669</formalpara> 670<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>push_back(const_reference)</computeroutput>, <computeroutput>pop_back()</computeroutput>, <computeroutput>pop_front()</computeroutput> </para> 671</para> 672</para></description><postconditions><para>if <computeroutput>capacity() > 0</computeroutput> then <computeroutput>front() == item</computeroutput><sbr/> 673 If the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> is full, the last element will be removed. If the capacity is <computeroutput>0</computeroutput>, nothing will be inserted. </para> 674</postconditions><throws><simpara><classname>Whatever</classname> <computeroutput>T::T(const T&)</computeroutput> throws. Whatever <computeroutput>T::operator = (const T&)</computeroutput> throws. </simpara></throws></method> 675<method name="push_front"><type>void</type><parameter name="item"><paramtype>rvalue_type</paramtype><description><para>The element to be inserted. </para></description></parameter><purpose>Insert a new element at the beginning of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> using rvalue references or rvalues references emulation. </purpose><description><para> 676 677 678<formalpara><title>Exception Safety</title><para>Basic; no-throw if the operation in the <emphasis>Throws</emphasis> section does not throw anything. </para> 679</formalpara> 680<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators with the exception of iterators pointing to the overwritten element. </para> 681</formalpara> 682<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>). </para> 683</formalpara> 684<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>push_back(const_reference)</computeroutput>, <computeroutput>pop_back()</computeroutput>, <computeroutput>pop_front()</computeroutput> </para> 685</para> 686</para></description><postconditions><para>if <computeroutput>capacity() > 0</computeroutput> then <computeroutput>front() == item</computeroutput><sbr/> 687 If the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> is full, the last element will be removed. If the capacity is <computeroutput>0</computeroutput>, nothing will be inserted. </para> 688</postconditions><throws><simpara><classname>Whatever</classname> <computeroutput>T::T(T&&)</computeroutput> throws. Whatever <computeroutput>T::operator = (T&&)</computeroutput> throws. </simpara></throws></method> 689<method name="push_front"><type>void</type><purpose>Insert a new default-constructed element at the beginning of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </purpose><description><para> 690 691<formalpara><title>Exception Safety</title><para>Basic; no-throw if the operation in the <emphasis>Throws</emphasis> section does not throw anything. </para> 692</formalpara> 693<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators with the exception of iterators pointing to the overwritten element. </para> 694</formalpara> 695<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>). </para> 696</formalpara> 697<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>push_back(const_reference)</computeroutput>, <computeroutput>pop_back()</computeroutput>, <computeroutput>pop_front()</computeroutput> </para> 698</para> 699</para></description><postconditions><para>if <computeroutput>capacity() > 0</computeroutput> then <computeroutput>front() == item</computeroutput><sbr/> 700 If the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> is full, the last element will be removed. If the capacity is <computeroutput>0</computeroutput>, nothing will be inserted. </para> 701</postconditions><throws><simpara><classname>Whatever</classname> <computeroutput>T::T()</computeroutput> throws. Whatever <computeroutput>T::T(T&&)</computeroutput> throws. Whatever <computeroutput>T::operator = (T&&)</computeroutput> throws. </simpara></throws></method> 702<method name="pop_back"><type>void</type><purpose>Remove the last element from the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </purpose><description><para> 703 704 705<formalpara><title>Exception Safety</title><para>No-throw. </para> 706</formalpara> 707<formalpara><title>Iterator Invalidation</title><para>Invalidates only iterators pointing to the removed element. </para> 708</formalpara> 709<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>). </para> 710</formalpara> 711<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>pop_front()</computeroutput>, <computeroutput>push_back(const_reference)</computeroutput>, <computeroutput>push_front(const_reference)</computeroutput> </para> 712</para> 713</para></description><requires><para><computeroutput>!empty()</computeroutput> </para> 714</requires><postconditions><para>The last element is removed from the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </para> 715</postconditions><throws><simpara><classname>Nothing.</classname> </simpara></throws></method> 716<method name="pop_front"><type>void</type><purpose>Remove the first element from the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </purpose><description><para> 717 718 719<formalpara><title>Exception Safety</title><para>No-throw. </para> 720</formalpara> 721<formalpara><title>Iterator Invalidation</title><para>Invalidates only iterators pointing to the removed element. </para> 722</formalpara> 723<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>). </para> 724</formalpara> 725<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>pop_back()</computeroutput>, <computeroutput>push_back(const_reference)</computeroutput>, <computeroutput>push_front(const_reference)</computeroutput> </para> 726</para> 727</para></description><requires><para><computeroutput>!empty()</computeroutput> </para> 728</requires><postconditions><para>The first element is removed from the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </para> 729</postconditions><throws><simpara><classname>Nothing.</classname> </simpara></throws></method> 730<method name="insert"><type>iterator</type><parameter name="pos"><paramtype>iterator</paramtype><description><para>An iterator specifying the position where the <computeroutput>item</computeroutput> will be inserted. </para></description></parameter><parameter name="item"><paramtype>param_value_type</paramtype><description><para>The element to be inserted. </para></description></parameter><purpose>Insert an element at the specified position. </purpose><description><para> 731 732 733 734 735<formalpara><title>Exception Safety</title><para>Basic; no-throw if the operation in the <emphasis>Throws</emphasis> section does not throw anything. </para> 736</formalpara> 737<formalpara><title>Iterator Invalidation</title><para>Invalidates iterators pointing to the elements at the insertion point (including <computeroutput>pos</computeroutput>) and iterators behind the insertion point (towards the end; except iterators equal to <computeroutput>end()</computeroutput>). It also invalidates iterators pointing to the overwritten element. </para> 738</formalpara> 739<formalpara><title>Complexity</title><para>Linear (in <computeroutput>std::distance(pos, end())</computeroutput>). </para> 740</formalpara> 741<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>insert(iterator, size_type, value_type)</computeroutput>, <computeroutput>insert(iterator, InputIterator, InputIterator)</computeroutput>, <computeroutput>rinsert(iterator, value_type)</computeroutput>, <computeroutput>rinsert(iterator, size_type, value_type)</computeroutput>, <computeroutput>rinsert(iterator, InputIterator, InputIterator)</computeroutput> </para> 742</para> 743</para></description><requires><para><computeroutput>pos</computeroutput> is a valid iterator pointing to the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> or its end. </para> 744</requires><postconditions><para>The <computeroutput>item</computeroutput> will be inserted at the position <computeroutput>pos</computeroutput>.<sbr/> 745 If the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> is full, the first element will be overwritten. If the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> is full and the <computeroutput>pos</computeroutput> points to <computeroutput>begin()</computeroutput>, then the <computeroutput>item</computeroutput> will not be inserted. If the capacity is <computeroutput>0</computeroutput>, nothing will be inserted. </para> 746</postconditions><returns><para>Iterator to the inserted element or <computeroutput>begin()</computeroutput> if the <computeroutput>item</computeroutput> is not inserted. (See the <emphasis>Effect</emphasis>.) </para> 747</returns><throws><simpara><classname>Whatever</classname> <computeroutput>T::T(const T&)</computeroutput> throws. Whatever <computeroutput>T::operator = (const T&)</computeroutput> throws. <ulink url="circular_buffer/implementation.html#circular_buffer.implementation.exceptions_of_move_if_noexcept_t">Exceptions of move_if_noexcept(T&)</ulink>.</simpara></throws></method> 748<method name="insert"><type>iterator</type><parameter name="pos"><paramtype>iterator</paramtype><description><para>An iterator specifying the position where the <computeroutput>item</computeroutput> will be inserted. </para></description></parameter><parameter name="item"><paramtype>rvalue_type</paramtype><description><para>The element to be inserted. </para></description></parameter><purpose>Insert an element at the specified position. </purpose><description><para> 749 750 751 752 753<formalpara><title>Exception Safety</title><para>Basic; no-throw if the operation in the <emphasis>Throws</emphasis> section does not throw anything. </para> 754</formalpara> 755<formalpara><title>Iterator Invalidation</title><para>Invalidates iterators pointing to the elements at the insertion point (including <computeroutput>pos</computeroutput>) and iterators behind the insertion point (towards the end; except iterators equal to <computeroutput>end()</computeroutput>). It also invalidates iterators pointing to the overwritten element. </para> 756</formalpara> 757<formalpara><title>Complexity</title><para>Linear (in <computeroutput>std::distance(pos, end())</computeroutput>). </para> 758</formalpara> 759<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>insert(iterator, size_type, value_type)</computeroutput>, <computeroutput>insert(iterator, InputIterator, InputIterator)</computeroutput>, <computeroutput>rinsert(iterator, value_type)</computeroutput>, <computeroutput>rinsert(iterator, size_type, value_type)</computeroutput>, <computeroutput>rinsert(iterator, InputIterator, InputIterator)</computeroutput> </para> 760</para> 761</para></description><requires><para><computeroutput>pos</computeroutput> is a valid iterator pointing to the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> or its end. </para> 762</requires><postconditions><para>The <computeroutput>item</computeroutput> will be inserted at the position <computeroutput>pos</computeroutput>.<sbr/> 763 If the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> is full, the first element will be overwritten. If the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> is full and the <computeroutput>pos</computeroutput> points to <computeroutput>begin()</computeroutput>, then the <computeroutput>item</computeroutput> will not be inserted. If the capacity is <computeroutput>0</computeroutput>, nothing will be inserted. </para> 764</postconditions><returns><para>Iterator to the inserted element or <computeroutput>begin()</computeroutput> if the <computeroutput>item</computeroutput> is not inserted. (See the <emphasis>Effect</emphasis>.) </para> 765</returns><throws><simpara><classname>Whatever</classname> <computeroutput>T::T(T&&)</computeroutput> throws. Whatever <computeroutput>T::operator = (T&&)</computeroutput> throws. <ulink url="circular_buffer/implementation.html#circular_buffer.implementation.exceptions_of_move_if_noexcept_t">Exceptions of move_if_noexcept(T&)</ulink>. </simpara></throws></method> 766<method name="insert"><type>iterator</type><parameter name="pos"><paramtype>iterator</paramtype><description><para>An iterator specifying the position where the <computeroutput>item</computeroutput> will be inserted. </para></description></parameter><purpose>Insert a default-constructed element at the specified position. </purpose><description><para> 767 768 769 770 771<formalpara><title>Exception Safety</title><para>Basic; no-throw if the operation in the <emphasis>Throws</emphasis> section does not throw anything. </para> 772</formalpara> 773<formalpara><title>Iterator Invalidation</title><para>Invalidates iterators pointing to the elements at the insertion point (including <computeroutput>pos</computeroutput>) and iterators behind the insertion point (towards the end; except iterators equal to <computeroutput>end()</computeroutput>). It also invalidates iterators pointing to the overwritten element. </para> 774</formalpara> 775<formalpara><title>Complexity</title><para>Linear (in <computeroutput>std::distance(pos, end())</computeroutput>). </para> 776</formalpara> 777<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>insert(iterator, size_type, value_type)</computeroutput>, <computeroutput>insert(iterator, InputIterator, InputIterator)</computeroutput>, <computeroutput>rinsert(iterator, value_type)</computeroutput>, <computeroutput>rinsert(iterator, size_type, value_type)</computeroutput>, <computeroutput>rinsert(iterator, InputIterator, InputIterator)</computeroutput> </para> 778</para> 779</para></description><requires><para><computeroutput>pos</computeroutput> is a valid iterator pointing to the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> or its end. </para> 780</requires><postconditions><para>The <computeroutput>item</computeroutput> will be inserted at the position <computeroutput>pos</computeroutput>.<sbr/> 781 If the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> is full, the first element will be overwritten. If the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> is full and the <computeroutput>pos</computeroutput> points to <computeroutput>begin()</computeroutput>, then the <computeroutput>item</computeroutput> will not be inserted. If the capacity is <computeroutput>0</computeroutput>, nothing will be inserted. </para> 782</postconditions><returns><para>Iterator to the inserted element or <computeroutput>begin()</computeroutput> if the <computeroutput>item</computeroutput> is not inserted. (See the <emphasis>Effect</emphasis>.) </para> 783</returns><throws><simpara><classname>Whatever</classname> <computeroutput>T::T()</computeroutput> throws. Whatever <computeroutput>T::T(T&&)</computeroutput> throws. Whatever <computeroutput>T::operator = (T&&)</computeroutput> throws. <ulink url="circular_buffer/implementation.html#circular_buffer.implementation.exceptions_of_move_if_noexcept_t">Exceptions of move_if_noexcept(T&)</ulink>. </simpara></throws></method> 784<method name="insert"><type>void</type><parameter name="pos"><paramtype>iterator</paramtype><description><para>An iterator specifying the position where the <computeroutput>item</computeroutput>s will be inserted. </para></description></parameter><parameter name="n"><paramtype>size_type</paramtype><description><para>The number of <computeroutput>item</computeroutput>s the to be inserted. </para></description></parameter><parameter name="item"><paramtype>param_value_type</paramtype><description><para>The element whose copies will be inserted. </para></description></parameter><purpose>Insert <computeroutput>n</computeroutput> copies of the <computeroutput>item</computeroutput> at the specified position. </purpose><description><para> 785 786 787 788<formalpara><title>Exception Safety</title><para>Basic; no-throw if the operations in the <emphasis>Throws</emphasis> section do not throw anything. </para> 789</formalpara> 790<formalpara><title>Iterator Invalidation</title><para>Invalidates iterators pointing to the elements at the insertion point (including <computeroutput>pos</computeroutput>) and iterators behind the insertion point (towards the end; except iterators equal to <computeroutput>end()</computeroutput>). It also invalidates iterators pointing to the overwritten elements. </para> 791</formalpara> 792<formalpara><title>Complexity</title><para>Linear (in <computeroutput>min[capacity(), std::distance(pos, end()) + n]</computeroutput>). </para> 793</formalpara> 794<formalpara><title>Example</title><para>Consider a <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> with the capacity of 6 and the size of 4. Its internal buffer may look like the one below.<sbr/> 795<sbr/> 796 <computeroutput>|1|2|3|4| | |</computeroutput><sbr/> 797 <computeroutput>p ___^</computeroutput><sbr/> 798<sbr/> 799After inserting 5 elements at the position <computeroutput>p</computeroutput>:<sbr/> 800<sbr/> 801 <computeroutput>insert(p, (size_t)5, 0);</computeroutput><sbr/> 802<sbr/> 803actually only 4 elements get inserted and elements <computeroutput>1</computeroutput> and <computeroutput>2</computeroutput> are overwritten. This is due to the fact the insert operation preserves the capacity. After insertion the internal buffer looks like this:<sbr/> 804<sbr/> 805<computeroutput>|0|0|0|0|3|4|</computeroutput><sbr/> 806 <sbr/> 807For comparison if the capacity would not be preserved the internal buffer would then result in <computeroutput>|1|2|0|0|0|0|0|3|4|</computeroutput>. </para> 808</formalpara> 809<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>insert(iterator, value_type)</computeroutput>, <computeroutput>insert(iterator, InputIterator, InputIterator)</computeroutput>, <computeroutput>rinsert(iterator, value_type)</computeroutput>, <computeroutput>rinsert(iterator, size_type, value_type)</computeroutput>, <computeroutput>rinsert(iterator, InputIterator, InputIterator)</computeroutput> </para> 810</para> 811</para></description><requires><para><computeroutput>pos</computeroutput> is a valid iterator pointing to the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> or its end. </para> 812</requires><postconditions><para>The number of <computeroutput>min[n, (pos - begin()) + reserve()]</computeroutput> elements will be inserted at the position <computeroutput>pos</computeroutput>.<sbr/> 813The number of <computeroutput>min[pos - begin(), max[0, n - reserve()]]</computeroutput> elements will be overwritten at the beginning of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>.<sbr/> 814(See <emphasis>Example</emphasis> for the explanation.) </para> 815</postconditions><throws><simpara><classname>Whatever</classname> <computeroutput>T::T(const T&)</computeroutput> throws. Whatever <computeroutput>T::operator = (const T&)</computeroutput> throws. <ulink url="circular_buffer/implementation.html#circular_buffer.implementation.exceptions_of_move_if_noexcept_t">Exceptions of move_if_noexcept(T&)</ulink>. </simpara></throws></method> 816<method name="insert"><type>void</type><template> 817 <template-type-parameter name="InputIterator"/> 818 </template><parameter name="pos"><paramtype>iterator</paramtype><description><para>An iterator specifying the position where the range will be inserted. </para></description></parameter><parameter name="first"><paramtype>InputIterator</paramtype><description><para>The beginning of the range to be inserted. </para></description></parameter><parameter name="last"><paramtype>InputIterator</paramtype><description><para>The end of the range to be inserted. </para></description></parameter><purpose>Insert the range <computeroutput>[first, last)</computeroutput> at the specified position. </purpose><description><para> 819 820 821 822<formalpara><title>Exception Safety</title><para>Basic; no-throw if the operations in the <emphasis>Throws</emphasis> section do not throw anything. </para> 823</formalpara> 824<formalpara><title>Iterator Invalidation</title><para>Invalidates iterators pointing to the elements at the insertion point (including <computeroutput>pos</computeroutput>) and iterators behind the insertion point (towards the end; except iterators equal to <computeroutput>end()</computeroutput>). It also invalidates iterators pointing to the overwritten elements. </para> 825</formalpara> 826<formalpara><title>Complexity</title><para>Linear (in <computeroutput>[std::distance(pos, end()) + std::distance(first, last)]</computeroutput>; in <computeroutput>min[capacity(), std::distance(pos, end()) + std::distance(first, last)]</computeroutput> if the <computeroutput>InputIterator</computeroutput> is a <ulink url="https://www.boost.org/sgi/stl/RandomAccessIterator.html">RandomAccessIterator</ulink>). </para> 827</formalpara> 828<formalpara><title>Example</title><para>Consider a <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> with the capacity of 6 and the size of 4. Its internal buffer may look like the one below.<sbr/> 829<sbr/> 830 <computeroutput>|1|2|3|4| | |</computeroutput><sbr/> 831 <computeroutput>p ___^</computeroutput><sbr/> 832<sbr/> 833After inserting a range of elements at the position <computeroutput>p</computeroutput>:<sbr/> 834<sbr/> 835 <computeroutput>int array[] = { 5, 6, 7, 8, 9 };</computeroutput><sbr/> 836<computeroutput>insert(p, array, array + 5);</computeroutput><sbr/> 837<sbr/> 838 actually only elements <computeroutput>6</computeroutput>, <computeroutput>7</computeroutput>, <computeroutput>8</computeroutput> and <computeroutput>9</computeroutput> from the specified range get inserted and elements <computeroutput>1</computeroutput> and <computeroutput>2</computeroutput> are overwritten. This is due to the fact the insert operation preserves the capacity. After insertion the internal buffer looks like this:<sbr/> 839<sbr/> 840<computeroutput>|6|7|8|9|3|4|</computeroutput><sbr/> 841<sbr/> 842For comparison if the capacity would not be preserved the internal buffer would then result in <computeroutput>|1|2|5|6|7|8|9|3|4|</computeroutput>. </para> 843</formalpara> 844<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>insert(iterator, value_type)</computeroutput>, <computeroutput>insert(iterator, size_type, value_type)</computeroutput>, <computeroutput>rinsert(iterator, value_type)</computeroutput>, <computeroutput>rinsert(iterator, size_type, value_type)</computeroutput>, <computeroutput>rinsert(iterator, InputIterator, InputIterator)</computeroutput> </para> 845</para> 846</para></description><requires><para><computeroutput>pos</computeroutput> is a valid iterator pointing to the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> or its end.<sbr/> 847 Valid range <computeroutput>[first, last)</computeroutput> where <computeroutput>first</computeroutput> and <computeroutput>last</computeroutput> meet the requirements of an <ulink url="https://www.boost.org/sgi/stl/InputIterator.html">InputIterator</ulink>. </para> 848</requires><postconditions><para>Elements from the range <computeroutput>[first + max[0, distance(first, last) - (pos - begin()) - reserve()], last)</computeroutput> will be inserted at the position <computeroutput>pos</computeroutput>.<sbr/> 849The number of <computeroutput>min[pos - begin(), max[0, distance(first, last) - reserve()]]</computeroutput> elements will be overwritten at the beginning of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>.<sbr/> 850(See <emphasis>Example</emphasis> for the explanation.) </para> 851</postconditions><throws><simpara><classname>Whatever</classname> <computeroutput>T::T(const T&)</computeroutput> throws if the <computeroutput>InputIterator</computeroutput> is not a move iterator. Whatever <computeroutput>T::operator = (const T&)</computeroutput> throws if the <computeroutput>InputIterator</computeroutput> is not a move iterator. Whatever <computeroutput>T::T(T&&)</computeroutput> throws if the <computeroutput>InputIterator</computeroutput> is a move iterator. Whatever <computeroutput>T::operator = (T&&)</computeroutput> throws if the <computeroutput>InputIterator</computeroutput> is a move iterator. </simpara></throws></method> 852<method name="rinsert"><type>iterator</type><parameter name="pos"><paramtype>iterator</paramtype><description><para>An iterator specifying the position before which the <computeroutput>item</computeroutput> will be inserted. </para></description></parameter><parameter name="item"><paramtype>param_value_type</paramtype><description><para>The element to be inserted. </para></description></parameter><purpose>Insert an element before the specified position. </purpose><description><para> 853 854 855 856 857<formalpara><title>Exception Safety</title><para>Basic; no-throw if the operations in the <emphasis>Throws</emphasis> section do not throw anything. </para> 858</formalpara> 859<formalpara><title>Iterator Invalidation</title><para>Invalidates iterators pointing to the elements before the insertion point (towards the beginning and excluding <computeroutput>pos</computeroutput>). It also invalidates iterators pointing to the overwritten element. </para> 860</formalpara> 861<formalpara><title>Complexity</title><para>Linear (in <computeroutput>std::distance(begin(), pos)</computeroutput>). </para> 862</formalpara> 863<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>rinsert(iterator, size_type, value_type)</computeroutput>, <computeroutput>rinsert(iterator, InputIterator, InputIterator)</computeroutput>, <computeroutput>insert(iterator, value_type)</computeroutput>, <computeroutput>insert(iterator, size_type, value_type)</computeroutput>, <computeroutput>insert(iterator, InputIterator, InputIterator)</computeroutput> </para> 864</para> 865</para></description><requires><para><computeroutput>pos</computeroutput> is a valid iterator pointing to the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> or its end. </para> 866</requires><postconditions><para>The <computeroutput>item</computeroutput> will be inserted before the position <computeroutput>pos</computeroutput>.<sbr/> 867 If the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> is full, the last element will be overwritten. If the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> is full and the <computeroutput>pos</computeroutput> points to <computeroutput>end()</computeroutput>, then the <computeroutput>item</computeroutput> will not be inserted. If the capacity is <computeroutput>0</computeroutput>, nothing will be inserted. </para> 868</postconditions><returns><para>Iterator to the inserted element or <computeroutput>end()</computeroutput> if the <computeroutput>item</computeroutput> is not inserted. (See the <emphasis>Effect</emphasis>.) </para> 869</returns><throws><simpara><classname>Whatever</classname> <computeroutput>T::T(const T&)</computeroutput> throws. Whatever <computeroutput>T::operator = (const T&)</computeroutput> throws. <ulink url="circular_buffer/implementation.html#circular_buffer.implementation.exceptions_of_move_if_noexcept_t">Exceptions of move_if_noexcept(T&)</ulink>. </simpara></throws></method> 870<method name="rinsert"><type>iterator</type><parameter name="pos"><paramtype>iterator</paramtype><description><para>An iterator specifying the position before which the <computeroutput>item</computeroutput> will be inserted. </para></description></parameter><parameter name="item"><paramtype>rvalue_type</paramtype><description><para>The element to be inserted. </para></description></parameter><purpose>Insert an element before the specified position. </purpose><description><para> 871 872 873 874 875<formalpara><title>Exception Safety</title><para>Basic; no-throw if the operations in the <emphasis>Throws</emphasis> section do not throw anything. </para> 876</formalpara> 877<formalpara><title>Iterator Invalidation</title><para>Invalidates iterators pointing to the elements before the insertion point (towards the beginning and excluding <computeroutput>pos</computeroutput>). It also invalidates iterators pointing to the overwritten element. </para> 878</formalpara> 879<formalpara><title>Complexity</title><para>Linear (in <computeroutput>std::distance(begin(), pos)</computeroutput>). </para> 880</formalpara> 881<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>rinsert(iterator, size_type, value_type)</computeroutput>, <computeroutput>rinsert(iterator, InputIterator, InputIterator)</computeroutput>, <computeroutput>insert(iterator, value_type)</computeroutput>, <computeroutput>insert(iterator, size_type, value_type)</computeroutput>, <computeroutput>insert(iterator, InputIterator, InputIterator)</computeroutput> </para> 882</para> 883</para></description><requires><para><computeroutput>pos</computeroutput> is a valid iterator pointing to the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> or its end. </para> 884</requires><postconditions><para>The <computeroutput>item</computeroutput> will be inserted before the position <computeroutput>pos</computeroutput>.<sbr/> 885 If the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> is full, the last element will be overwritten. If the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> is full and the <computeroutput>pos</computeroutput> points to <computeroutput>end()</computeroutput>, then the <computeroutput>item</computeroutput> will not be inserted. If the capacity is <computeroutput>0</computeroutput>, nothing will be inserted. </para> 886</postconditions><returns><para>Iterator to the inserted element or <computeroutput>end()</computeroutput> if the <computeroutput>item</computeroutput> is not inserted. (See the <emphasis>Effect</emphasis>.) </para> 887</returns><throws><simpara><classname>Whatever</classname> <computeroutput>T::T(T&&)</computeroutput> throws. Whatever <computeroutput>T::operator = (T&&)</computeroutput> throws. <ulink url="circular_buffer/implementation.html#circular_buffer.implementation.exceptions_of_move_if_noexcept_t">Exceptions of move_if_noexcept(T&)</ulink>. </simpara></throws></method> 888<method name="rinsert"><type>iterator</type><parameter name="pos"><paramtype>iterator</paramtype><description><para>An iterator specifying the position before which the <computeroutput>item</computeroutput> will be inserted. </para></description></parameter><purpose>Insert an element before the specified position. </purpose><description><para> 889 890 891 892 893<formalpara><title>Exception Safety</title><para>Basic; no-throw if the operations in the <emphasis>Throws</emphasis> section do not throw anything. </para> 894</formalpara> 895<formalpara><title>Iterator Invalidation</title><para>Invalidates iterators pointing to the elements before the insertion point (towards the beginning and excluding <computeroutput>pos</computeroutput>). It also invalidates iterators pointing to the overwritten element. </para> 896</formalpara> 897<formalpara><title>Complexity</title><para>Linear (in <computeroutput>std::distance(begin(), pos)</computeroutput>). </para> 898</formalpara> 899<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>rinsert(iterator, size_type, value_type)</computeroutput>, <computeroutput>rinsert(iterator, InputIterator, InputIterator)</computeroutput>, <computeroutput>insert(iterator, value_type)</computeroutput>, <computeroutput>insert(iterator, size_type, value_type)</computeroutput>, <computeroutput>insert(iterator, InputIterator, InputIterator)</computeroutput> </para> 900</para> 901</para></description><requires><para><computeroutput>pos</computeroutput> is a valid iterator pointing to the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> or its end. </para> 902</requires><postconditions><para>The <computeroutput>item</computeroutput> will be inserted before the position <computeroutput>pos</computeroutput>.<sbr/> 903 If the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> is full, the last element will be overwritten. If the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> is full and the <computeroutput>pos</computeroutput> points to <computeroutput>end()</computeroutput>, then the <computeroutput>item</computeroutput> will not be inserted. If the capacity is <computeroutput>0</computeroutput>, nothing will be inserted. </para> 904</postconditions><returns><para>Iterator to the inserted element or <computeroutput>end()</computeroutput> if the <computeroutput>item</computeroutput> is not inserted. (See the <emphasis>Effect</emphasis>.) </para> 905</returns><throws><simpara><classname>Whatever</classname> <computeroutput>T::T()</computeroutput> throws. Whatever <computeroutput>T::T(T&&)</computeroutput> throws. Whatever <computeroutput>T::operator = (T&&)</computeroutput> throws. <ulink url="circular_buffer/implementation.html#circular_buffer.implementation.exceptions_of_move_if_noexcept_t">Exceptions of move_if_noexcept(T&)</ulink>. </simpara></throws></method> 906<method name="rinsert"><type>void</type><parameter name="pos"><paramtype>iterator</paramtype><description><para>An iterator specifying the position where the <computeroutput>item</computeroutput>s will be inserted. </para></description></parameter><parameter name="n"><paramtype>size_type</paramtype><description><para>The number of <computeroutput>item</computeroutput>s the to be inserted. </para></description></parameter><parameter name="item"><paramtype>param_value_type</paramtype><description><para>The element whose copies will be inserted. </para></description></parameter><purpose>Insert <computeroutput>n</computeroutput> copies of the <computeroutput>item</computeroutput> before the specified position. </purpose><description><para> 907 908 909 910<formalpara><title>Exception Safety</title><para>Basic; no-throw if the operations in the <emphasis>Throws</emphasis> section do not throw anything. </para> 911</formalpara> 912<formalpara><title>Iterator Invalidation</title><para>Invalidates iterators pointing to the elements before the insertion point (towards the beginning and excluding <computeroutput>pos</computeroutput>). It also invalidates iterators pointing to the overwritten elements. </para> 913</formalpara> 914<formalpara><title>Complexity</title><para>Linear (in <computeroutput>min[capacity(), std::distance(begin(), pos) + n]</computeroutput>). </para> 915</formalpara> 916<formalpara><title>Example</title><para>Consider a <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> with the capacity of 6 and the size of 4. Its internal buffer may look like the one below.<sbr/> 917<sbr/> 918 <computeroutput>|1|2|3|4| | |</computeroutput><sbr/> 919 <computeroutput>p ___^</computeroutput><sbr/> 920<sbr/> 921After inserting 5 elements before the position <computeroutput>p</computeroutput>:<sbr/> 922<sbr/> 923 <computeroutput>rinsert(p, (size_t)5, 0);</computeroutput><sbr/> 924<sbr/> 925actually only 4 elements get inserted and elements <computeroutput>3</computeroutput> and <computeroutput>4</computeroutput> are overwritten. This is due to the fact the rinsert operation preserves the capacity. After insertion the internal buffer looks like this:<sbr/> 926<sbr/> 927<computeroutput>|1|2|0|0|0|0|</computeroutput><sbr/> 928 <sbr/> 929For comparison if the capacity would not be preserved the internal buffer would then result in <computeroutput>|1|2|0|0|0|0|0|3|4|</computeroutput>. </para> 930</formalpara> 931<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>rinsert(iterator, value_type)</computeroutput>, <computeroutput>rinsert(iterator, InputIterator, InputIterator)</computeroutput>, <computeroutput>insert(iterator, value_type)</computeroutput>, <computeroutput>insert(iterator, size_type, value_type)</computeroutput>, <computeroutput>insert(iterator, InputIterator, InputIterator)</computeroutput> </para> 932</para> 933</para></description><requires><para><computeroutput>pos</computeroutput> is a valid iterator pointing to the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> or its end. </para> 934</requires><postconditions><para>The number of <computeroutput>min[n, (end() - pos) + reserve()]</computeroutput> elements will be inserted before the position <computeroutput>pos</computeroutput>.<sbr/> 935The number of <computeroutput>min[end() - pos, max[0, n - reserve()]]</computeroutput> elements will be overwritten at the end of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>.<sbr/> 936(See <emphasis>Example</emphasis> for the explanation.) </para> 937</postconditions><throws><simpara><classname>Whatever</classname> <computeroutput>T::T(const T&)</computeroutput> throws. Whatever <computeroutput>T::operator = (const T&)</computeroutput> throws. <ulink url="circular_buffer/implementation.html#circular_buffer.implementation.exceptions_of_move_if_noexcept_t">Exceptions of move_if_noexcept(T&)</ulink>. </simpara></throws></method> 938<method name="rinsert"><type>void</type><template> 939 <template-type-parameter name="InputIterator"/> 940 </template><parameter name="pos"><paramtype>iterator</paramtype><description><para>An iterator specifying the position where the range will be inserted. </para></description></parameter><parameter name="first"><paramtype>InputIterator</paramtype><description><para>The beginning of the range to be inserted. </para></description></parameter><parameter name="last"><paramtype>InputIterator</paramtype><description><para>The end of the range to be inserted. </para></description></parameter><purpose>Insert the range <computeroutput>[first, last)</computeroutput> before the specified position. </purpose><description><para> 941 942 943 944<formalpara><title>Exception Safety</title><para>Basic; no-throw if the operations in the <emphasis>Throws</emphasis> section do not throw anything. </para> 945</formalpara> 946<formalpara><title>Iterator Invalidation</title><para>Invalidates iterators pointing to the elements before the insertion point (towards the beginning and excluding <computeroutput>pos</computeroutput>). It also invalidates iterators pointing to the overwritten elements. </para> 947</formalpara> 948<formalpara><title>Complexity</title><para>Linear (in <computeroutput>[std::distance(begin(), pos) + std::distance(first, last)]</computeroutput>; in <computeroutput>min[capacity(), std::distance(begin(), pos) + std::distance(first, last)]</computeroutput> if the <computeroutput>InputIterator</computeroutput> is a <ulink url="https://www.boost.org/sgi/stl/RandomAccessIterator.html">RandomAccessIterator</ulink>). </para> 949</formalpara> 950<formalpara><title>Example</title><para>Consider a <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> with the capacity of 6 and the size of 4. Its internal buffer may look like the one below.<sbr/> 951<sbr/> 952 <computeroutput>|1|2|3|4| | |</computeroutput><sbr/> 953 <computeroutput>p ___^</computeroutput><sbr/> 954<sbr/> 955After inserting a range of elements before the position <computeroutput>p</computeroutput>:<sbr/> 956<sbr/> 957 <computeroutput>int array[] = { 5, 6, 7, 8, 9 };</computeroutput><sbr/> 958<computeroutput>insert(p, array, array + 5);</computeroutput><sbr/> 959<sbr/> 960 actually only elements <computeroutput>5</computeroutput>, <computeroutput>6</computeroutput>, <computeroutput>7</computeroutput> and <computeroutput>8</computeroutput> from the specified range get inserted and elements <computeroutput>3</computeroutput> and <computeroutput>4</computeroutput> are overwritten. This is due to the fact the rinsert operation preserves the capacity. After insertion the internal buffer looks like this:<sbr/> 961<sbr/> 962<computeroutput>|1|2|5|6|7|8|</computeroutput><sbr/> 963<sbr/> 964For comparison if the capacity would not be preserved the internal buffer would then result in <computeroutput>|1|2|5|6|7|8|9|3|4|</computeroutput>. </para> 965</formalpara> 966<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>rinsert(iterator, value_type)</computeroutput>, <computeroutput>rinsert(iterator, size_type, value_type)</computeroutput>, <computeroutput>insert(iterator, value_type)</computeroutput>, <computeroutput>insert(iterator, size_type, value_type)</computeroutput>, <computeroutput>insert(iterator, InputIterator, InputIterator)</computeroutput> </para> 967</para> 968</para></description><requires><para><computeroutput>pos</computeroutput> is a valid iterator pointing to the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> or its end.<sbr/> 969 Valid range <computeroutput>[first, last)</computeroutput> where <computeroutput>first</computeroutput> and <computeroutput>last</computeroutput> meet the requirements of an <ulink url="https://www.boost.org/sgi/stl/InputIterator.html">InputIterator</ulink>. </para> 970</requires><postconditions><para>Elements from the range <computeroutput>[first, last - max[0, distance(first, last) - (end() - pos) - reserve()])</computeroutput> will be inserted before the position <computeroutput>pos</computeroutput>.<sbr/> 971The number of <computeroutput>min[end() - pos, max[0, distance(first, last) - reserve()]]</computeroutput> elements will be overwritten at the end of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>.<sbr/> 972(See <emphasis>Example</emphasis> for the explanation.) </para> 973</postconditions><throws><simpara><classname>Whatever</classname> <computeroutput>T::T(const T&)</computeroutput> throws if the <computeroutput>InputIterator</computeroutput> is not a move iterator. Whatever <computeroutput>T::operator = (const T&)</computeroutput> throws if the <computeroutput>InputIterator</computeroutput> is not a move iterator. Whatever <computeroutput>T::T(T&&)</computeroutput> throws if the <computeroutput>InputIterator</computeroutput> is a move iterator. Whatever <computeroutput>T::operator = (T&&)</computeroutput> throws if the <computeroutput>InputIterator</computeroutput> is a move iterator. </simpara></throws></method> 974<method name="erase"><type>iterator</type><parameter name="pos"><paramtype>iterator</paramtype><description><para>An iterator pointing at the element to be removed. </para></description></parameter><purpose>Remove an element at the specified position. </purpose><description><para> 975 976 977 978 979<formalpara><title>Exception Safety</title><para>Basic; no-throw if the operation in the <emphasis>Throws</emphasis> section does not throw anything. </para> 980</formalpara> 981<formalpara><title>Iterator Invalidation</title><para>Invalidates iterators pointing to the erased element and iterators pointing to the elements behind the erased element (towards the end; except iterators equal to <computeroutput>end()</computeroutput>). </para> 982</formalpara> 983<formalpara><title>Complexity</title><para>Linear (in <computeroutput>std::distance(pos, end())</computeroutput>). </para> 984</formalpara> 985<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>erase(iterator, iterator)</computeroutput>, <computeroutput>rerase(iterator)</computeroutput>, <computeroutput>rerase(iterator, iterator)</computeroutput>, <computeroutput>erase_begin(size_type)</computeroutput>, <computeroutput>erase_end(size_type)</computeroutput>, <computeroutput>clear()</computeroutput> </para> 986</para> 987</para></description><requires><para><computeroutput>pos</computeroutput> is a valid iterator pointing to the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> (but not an <computeroutput>end()</computeroutput>). </para> 988</requires><postconditions><para>The element at the position <computeroutput>pos</computeroutput> is removed. </para> 989</postconditions><returns><para>Iterator to the first element remaining beyond the removed element or <computeroutput>end()</computeroutput> if no such element exists. </para> 990</returns><throws><simpara><classname><a</classname> href="circular_buffer/implementation.html#circular_buffer.implementation.exceptions_of_move_if_noexcept_t">Exceptions of move_if_noexcept(T&). </simpara></throws></method> 991<method name="erase"><type>iterator</type><parameter name="first"><paramtype>iterator</paramtype><description><para>The beginning of the range to be removed. </para></description></parameter><parameter name="last"><paramtype>iterator</paramtype><description><para>The end of the range to be removed. </para></description></parameter><purpose>Erase the range <computeroutput>[first, last)</computeroutput>. </purpose><description><para> 992 993 994 995 996<formalpara><title>Exception Safety</title><para>Basic; no-throw if the operation in the <emphasis>Throws</emphasis> section does not throw anything. </para> 997</formalpara> 998<formalpara><title>Iterator Invalidation</title><para>Invalidates iterators pointing to the erased elements and iterators pointing to the elements behind the erased range (towards the end; except iterators equal to <computeroutput>end()</computeroutput>). </para> 999</formalpara> 1000<formalpara><title>Complexity</title><para>Linear (in <computeroutput>std::distance(first, end())</computeroutput>). </para> 1001</formalpara> 1002<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>erase(iterator)</computeroutput>, <computeroutput>rerase(iterator)</computeroutput>, <computeroutput>rerase(iterator, iterator)</computeroutput>, <computeroutput>erase_begin(size_type)</computeroutput>, <computeroutput>erase_end(size_type)</computeroutput>, <computeroutput>clear()</computeroutput> </para> 1003</para> 1004</para></description><requires><para>Valid range <computeroutput>[first, last)</computeroutput>. </para> 1005</requires><postconditions><para>The elements from the range <computeroutput>[first, last)</computeroutput> are removed. (If <computeroutput>first == last</computeroutput> nothing is removed.) </para> 1006</postconditions><returns><para>Iterator to the first element remaining beyond the removed elements or <computeroutput>end()</computeroutput> if no such element exists. </para> 1007</returns><throws><simpara><classname><a</classname> href="circular_buffer/implementation.html#circular_buffer.implementation.exceptions_of_move_if_noexcept_t">Exceptions of move_if_noexcept(T&). </simpara></throws></method> 1008<method name="rerase"><type>iterator</type><parameter name="pos"><paramtype>iterator</paramtype><description><para>An iterator pointing at the element to be removed. </para></description></parameter><purpose>Remove an element at the specified position. </purpose><description><para> 1009 1010 1011 1012 1013<formalpara><title>Exception Safety</title><para>Basic; no-throw if the operation in the <emphasis>Throws</emphasis> section does not throw anything. </para> 1014</formalpara> 1015<formalpara><title>Iterator Invalidation</title><para>Invalidates iterators pointing to the erased element and iterators pointing to the elements in front of the erased element (towards the beginning). </para> 1016</formalpara> 1017<formalpara><title>Complexity</title><para>Linear (in <computeroutput>std::distance(begin(), pos)</computeroutput>). </para> 1018</formalpara> 1019<note><para>This method is symmetric to the <computeroutput>erase(iterator)</computeroutput> method and is more effective than <computeroutput>erase(iterator)</computeroutput> if the iterator <computeroutput>pos</computeroutput> is close to the beginning of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. (See the <emphasis>Complexity</emphasis>.) </para> 1020</note> 1021<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>erase(iterator)</computeroutput>, <computeroutput>erase(iterator, iterator)</computeroutput>, <computeroutput>rerase(iterator, iterator)</computeroutput>, <computeroutput>erase_begin(size_type)</computeroutput>, <computeroutput>erase_end(size_type)</computeroutput>, <computeroutput>clear()</computeroutput> </para> 1022</para> 1023</para></description><requires><para><computeroutput>pos</computeroutput> is a valid iterator pointing to the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> (but not an <computeroutput>end()</computeroutput>). </para> 1024</requires><postconditions><para>The element at the position <computeroutput>pos</computeroutput> is removed. </para> 1025</postconditions><returns><para>Iterator to the first element remaining in front of the removed element or <computeroutput>begin()</computeroutput> if no such element exists. </para> 1026</returns><throws><simpara><classname><a</classname> href="circular_buffer/implementation.html#circular_buffer.implementation.exceptions_of_move_if_noexcept_t">Exceptions of move_if_noexcept(T&). </simpara></throws></method> 1027<method name="rerase"><type>iterator</type><parameter name="first"><paramtype>iterator</paramtype><description><para>The beginning of the range to be removed. </para></description></parameter><parameter name="last"><paramtype>iterator</paramtype><description><para>The end of the range to be removed. </para></description></parameter><purpose>Erase the range <computeroutput>[first, last)</computeroutput>. </purpose><description><para> 1028 1029 1030 1031 1032<formalpara><title>Exception Safety</title><para>Basic; no-throw if the operation in the <emphasis>Throws</emphasis> section does not throw anything. </para> 1033</formalpara> 1034<formalpara><title>Iterator Invalidation</title><para>Invalidates iterators pointing to the erased elements and iterators pointing to the elements in front of the erased range (towards the beginning). </para> 1035</formalpara> 1036<formalpara><title>Complexity</title><para>Linear (in <computeroutput>std::distance(begin(), last)</computeroutput>). </para> 1037</formalpara> 1038<note><para>This method is symmetric to the <computeroutput>erase(iterator, iterator)</computeroutput> method and is more effective than <computeroutput>erase(iterator, iterator)</computeroutput> if <computeroutput>std::distance(begin(), first)</computeroutput> is lower that <computeroutput>std::distance(last, end())</computeroutput>. </para> 1039</note> 1040<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>erase(iterator)</computeroutput>, <computeroutput>erase(iterator, iterator)</computeroutput>, <computeroutput>rerase(iterator)</computeroutput>, <computeroutput>erase_begin(size_type)</computeroutput>, <computeroutput>erase_end(size_type)</computeroutput>, <computeroutput>clear()</computeroutput> </para> 1041</para> 1042</para></description><requires><para>Valid range <computeroutput>[first, last)</computeroutput>. </para> 1043</requires><postconditions><para>The elements from the range <computeroutput>[first, last)</computeroutput> are removed. (If <computeroutput>first == last</computeroutput> nothing is removed.) </para> 1044</postconditions><returns><para>Iterator to the first element remaining in front of the removed elements or <computeroutput>begin()</computeroutput> if no such element exists. </para> 1045</returns><throws><simpara><classname><a</classname> href="circular_buffer/implementation.html#circular_buffer.implementation.exceptions_of_move_if_noexcept_t">Exceptions of move_if_noexcept(T&). </simpara></throws></method> 1046<method name="erase_begin"><type>void</type><parameter name="n"><paramtype>size_type</paramtype><description><para>The number of elements to be removed. </para></description></parameter><purpose>Remove first <computeroutput>n</computeroutput> elements (with constant complexity for scalar types). </purpose><description><para> 1047 1048 1049 1050<formalpara><title>Exception Safety</title><para>Basic; no-throw if the operation in the <emphasis>Throws</emphasis> section does not throw anything. (I.e. no throw in case of scalars.) </para> 1051</formalpara> 1052<formalpara><title>Iterator Invalidation</title><para>Invalidates iterators pointing to the first <computeroutput>n</computeroutput> erased elements. </para> 1053</formalpara> 1054<formalpara><title>Complexity</title><para>Constant (in <computeroutput>n</computeroutput>) for scalar types; linear for other types. </para> 1055</formalpara> 1056<note><para>This method has been specially designed for types which do not require an explicit destructruction (e.g. integer, float or a pointer). For these scalar types a call to a destructor is not required which makes it possible to implement the "erase from beginning" operation with a constant complexity. For non-sacalar types the complexity is linear (hence the explicit destruction is needed) and the implementation is actually equivalent to <computeroutput>rerase(begin(), begin() + n)</computeroutput>. </para> 1057</note> 1058<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>erase(iterator)</computeroutput>, <computeroutput>erase(iterator, iterator)</computeroutput>, <computeroutput>rerase(iterator)</computeroutput>, <computeroutput>rerase(iterator, iterator)</computeroutput>, <computeroutput>erase_end(size_type)</computeroutput>, <computeroutput>clear()</computeroutput> </para> 1059</para> 1060</para></description><requires><para><computeroutput>n <= size()</computeroutput> </para> 1061</requires><postconditions><para>The <computeroutput>n</computeroutput> elements at the beginning of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> will be removed. </para> 1062</postconditions><throws><simpara><classname><a</classname> href="circular_buffer/implementation.html#circular_buffer.implementation.exceptions_of_move_if_noexcept_t">Exceptions of move_if_noexcept(T&). </simpara></throws></method> 1063<method name="erase_end"><type>void</type><parameter name="n"><paramtype>size_type</paramtype><description><para>The number of elements to be removed. </para></description></parameter><purpose>Remove last <computeroutput>n</computeroutput> elements (with constant complexity for scalar types). </purpose><description><para> 1064 1065 1066 1067<formalpara><title>Exception Safety</title><para>Basic; no-throw if the operation in the <emphasis>Throws</emphasis> section does not throw anything. (I.e. no throw in case of scalars.) </para> 1068</formalpara> 1069<formalpara><title>Iterator Invalidation</title><para>Invalidates iterators pointing to the last <computeroutput>n</computeroutput> erased elements. </para> 1070</formalpara> 1071<formalpara><title>Complexity</title><para>Constant (in <computeroutput>n</computeroutput>) for scalar types; linear for other types. </para> 1072</formalpara> 1073<note><para>This method has been specially designed for types which do not require an explicit destructruction (e.g. integer, float or a pointer). For these scalar types a call to a destructor is not required which makes it possible to implement the "erase from end" operation with a constant complexity. For non-sacalar types the complexity is linear (hence the explicit destruction is needed) and the implementation is actually equivalent to <computeroutput>erase(end() - n, end())</computeroutput>. </para> 1074</note> 1075<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>erase(iterator)</computeroutput>, <computeroutput>erase(iterator, iterator)</computeroutput>, <computeroutput>rerase(iterator)</computeroutput>, <computeroutput>rerase(iterator, iterator)</computeroutput>, <computeroutput>erase_begin(size_type)</computeroutput>, <computeroutput>clear()</computeroutput> </para> 1076</para> 1077</para></description><requires><para><computeroutput>n <= size()</computeroutput> </para> 1078</requires><postconditions><para>The <computeroutput>n</computeroutput> elements at the end of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> will be removed. </para> 1079</postconditions><throws><simpara><classname><a</classname> href="circular_buffer/implementation.html#circular_buffer.implementation.exceptions_of_move_if_noexcept_t">Exceptions of move_if_noexcept(T&). </simpara></throws></method> 1080<method name="clear" cv="noexcept"><type>void</type><purpose>Remove all stored elements from the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </purpose><description><para> 1081 1082<formalpara><title>Exception Safety</title><para>No-throw. </para> 1083</formalpara> 1084<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>). </para> 1085</formalpara> 1086<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>) for scalar types; linear for other types. </para> 1087</formalpara> 1088<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>~circular_buffer()</computeroutput>, <computeroutput>erase(iterator)</computeroutput>, <computeroutput>erase(iterator, iterator)</computeroutput>, <computeroutput>rerase(iterator)</computeroutput>, <computeroutput>rerase(iterator, iterator)</computeroutput>, <computeroutput>erase_begin(size_type)</computeroutput>, <computeroutput>erase_end(size_type)</computeroutput> </para> 1089</para> 1090</para></description><postconditions><para><computeroutput>size() == 0</computeroutput> </para> 1091</postconditions><throws><simpara><classname>Nothing.</classname> </simpara></throws></method> 1092</method-group> 1093<constructor specifiers="explicit" cv="noexcept"><parameter name="alloc"><paramtype>const allocator_type &</paramtype><default>allocator_type()</default><description><para>The allocator. </para></description></parameter><purpose>Create an empty <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> with zero capacity. </purpose><description><para> 1094 1095 1096<formalpara><title>Complexity</title><para>Constant. </para> 1097</formalpara> 1098<warning><para>Since Boost version 1.36 the behaviour of this constructor has changed. Now the constructor does not allocate any memory and both capacity and size are set to zero. Also note when inserting an element into a <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> with zero capacity (e.g. by <computeroutput>push_back(const_reference)</computeroutput> or <computeroutput>insert(iterator, value_type)</computeroutput>) nothing will be inserted and the size (as well as capacity) remains zero. </para> 1099</warning> 1100<note><para>You can explicitly set the capacity by calling the <computeroutput>set_capacity(capacity_type)</computeroutput> method or you can use the other constructor with the capacity specified. </para> 1101</note> 1102<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>circular_buffer(capacity_type, const allocator_type& alloc)</computeroutput>, <computeroutput>set_capacity(capacity_type)</computeroutput> </para> 1103</para> 1104</para></description><postconditions><para><computeroutput>capacity() == 0 && size() == 0</computeroutput> </para> 1105</postconditions><throws><simpara><classname>Nothing.</classname> </simpara></throws></constructor> 1106<constructor specifiers="explicit"><parameter name="buffer_capacity"><paramtype>capacity_type</paramtype><description><para>The maximum number of elements which can be stored in the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </para></description></parameter><parameter name="alloc"><paramtype>const allocator_type &</paramtype><default>allocator_type()</default><description><para>The allocator. </para></description></parameter><purpose>Create an empty <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> with the specified capacity. </purpose><description><para> 1107 1108 1109<formalpara><title>Complexity</title><para>Constant. </para> 1110</formalpara> 1111</para></description><postconditions><para><computeroutput>capacity() == buffer_capacity && size() == 0</computeroutput> </para> 1112</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). </simpara></throws></constructor> 1113<constructor><parameter name="n"><paramtype>size_type</paramtype><description><para>The number of elements the created <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> will be filled with. </para></description></parameter><parameter name="item"><paramtype>param_value_type</paramtype><description><para>The element the created <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> will be filled with. </para></description></parameter><parameter name="alloc"><paramtype>const allocator_type &</paramtype><default>allocator_type()</default><description><para>The allocator. </para></description></parameter><purpose>Create a full <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> with the specified capacity and filled with <computeroutput>n</computeroutput> copies of <computeroutput>item</computeroutput>. </purpose><description><para> 1114 1115 1116<formalpara><title>Complexity</title><para>Linear (in the <computeroutput>n</computeroutput>). </para> 1117</formalpara> 1118</para></description><postconditions><para><computeroutput>capacity() == n && full() && (*this)[0] == item && (*this)[1] == item && ... && (*this)[n - 1] == item </computeroutput> </para> 1119</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T(const T&)</computeroutput> throws. </simpara></throws></constructor> 1120<constructor><parameter name="buffer_capacity"><paramtype>capacity_type</paramtype><description><para>The capacity of the created <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </para></description></parameter><parameter name="n"><paramtype>size_type</paramtype><description><para>The number of elements the created <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> will be filled with. </para></description></parameter><parameter name="item"><paramtype>param_value_type</paramtype><description><para>The element the created <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> will be filled with. </para></description></parameter><parameter name="alloc"><paramtype>const allocator_type &</paramtype><default>allocator_type()</default><description><para>The allocator. </para></description></parameter><purpose>Create a <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> with the specified capacity and filled with <computeroutput>n</computeroutput> copies of <computeroutput>item</computeroutput>. </purpose><description><para> 1121 1122 1123 1124<formalpara><title>Complexity</title><para>Linear (in the <computeroutput>n</computeroutput>). </para> 1125</formalpara> 1126</para></description><requires><para><computeroutput>buffer_capacity >= n</computeroutput> </para> 1127</requires><postconditions><para><computeroutput>capacity() == buffer_capacity && size() == n && (*this)[0] == item && (*this)[1] == item && ... && (*this)[n - 1] == item</computeroutput> </para> 1128</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T(const T&)</computeroutput> throws. </simpara></throws></constructor> 1129<constructor><parameter name="cb"><paramtype>const <classname>circular_buffer</classname>< T, Alloc > &</paramtype><description><para>The <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> to be copied. </para></description></parameter><purpose>The copy constructor. </purpose><description><para>Creates a copy of the specified <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. 1130 1131 1132<formalpara><title>Complexity</title><para>Linear (in the size of <computeroutput>cb</computeroutput>). </para> 1133</formalpara> 1134</para></description><postconditions><para><computeroutput>*this == cb</computeroutput> </para> 1135</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T(const T&)</computeroutput> throws. </simpara></throws></constructor> 1136<constructor cv="noexcept"><parameter name="cb"><paramtype><classname>circular_buffer</classname>< T, Alloc > &&</paramtype><description><para><computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> to 'steal' value from. </para></description></parameter><purpose>The move constructor. </purpose><description><para>Move constructs a <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> from <computeroutput>cb</computeroutput>, leaving <computeroutput>cb</computeroutput> empty. 1137 1138 1139 1140<formalpara><title>Constant.</title><para/> 1141</formalpara> 1142</para></description><requires><para>C++ compiler with rvalue references support. </para> 1143</requires><postconditions><para><computeroutput>cb.empty()</computeroutput> </para> 1144</postconditions><throws><simpara><classname>Nothing.</classname> </simpara></throws></constructor> 1145<constructor><template> 1146 <template-type-parameter name="InputIterator"/> 1147 </template><parameter name="first"><paramtype>InputIterator</paramtype><description><para>The beginning of the range to be copied. </para></description></parameter><parameter name="last"><paramtype>InputIterator</paramtype><description><para>The end of the range to be copied. </para></description></parameter><parameter name="alloc"><paramtype>const allocator_type &</paramtype><default>allocator_type()</default><description><para>The allocator. </para></description></parameter><purpose>Create a full <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> filled with a copy of the range. </purpose><description><para> 1148 1149 1150 1151<formalpara><title>Complexity</title><para>Linear (in the <computeroutput>std::distance(first, last)</computeroutput>). </para> 1152</formalpara> 1153</para></description><requires><para>Valid range <computeroutput>[first, last)</computeroutput>.<sbr/> 1154 <computeroutput>first</computeroutput> and <computeroutput>last</computeroutput> have to meet the requirements of <ulink url="https://www.boost.org/sgi/stl/InputIterator.html">InputIterator</ulink>. </para> 1155</requires><postconditions><para><computeroutput>capacity() == std::distance(first, last) && full() && (*this)[0]== *first && (*this)[1] == *(first + 1) && ... && (*this)[std::distance(first, last) - 1] == *(last - 1)</computeroutput> </para> 1156</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T(const T&)</computeroutput> throws. </simpara></throws></constructor> 1157<constructor><template> 1158 <template-type-parameter name="InputIterator"/> 1159 </template><parameter name="buffer_capacity"><paramtype>capacity_type</paramtype><description><para>The capacity of the created <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </para></description></parameter><parameter name="first"><paramtype>InputIterator</paramtype><description><para>The beginning of the range to be copied. </para></description></parameter><parameter name="last"><paramtype>InputIterator</paramtype><description><para>The end of the range to be copied. </para></description></parameter><parameter name="alloc"><paramtype>const allocator_type &</paramtype><default>allocator_type()</default><description><para>The allocator. </para></description></parameter><purpose>Create a <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> with the specified capacity and filled with a copy of the range. </purpose><description><para> 1160 1161 1162 1163<formalpara><title>Complexity</title><para>Linear (in <computeroutput>std::distance(first, last)</computeroutput>; in <computeroutput>min[capacity, std::distance(first, last)]</computeroutput> if the <computeroutput>InputIterator</computeroutput> is a <ulink url="https://www.boost.org/sgi/stl/RandomAccessIterator.html">RandomAccessIterator</ulink>). </para> 1164</formalpara> 1165</para></description><requires><para>Valid range <computeroutput>[first, last)</computeroutput>.<sbr/> 1166 <computeroutput>first</computeroutput> and <computeroutput>last</computeroutput> have to meet the requirements of <ulink url="https://www.boost.org/sgi/stl/InputIterator.html">InputIterator</ulink>. </para> 1167</requires><postconditions><para><computeroutput>capacity() == buffer_capacity && size() <= std::distance(first, last) && (*this)[0]== *(last - buffer_capacity) && (*this)[1] == *(last - buffer_capacity + 1) && ... && (*this)[buffer_capacity - 1] == *(last - 1)</computeroutput><sbr/> 1168<sbr/> 1169 If the number of items to be copied from the range <computeroutput>[first, last)</computeroutput> is greater than the specified <computeroutput>buffer_capacity</computeroutput> then only elements from the range <computeroutput>[last - buffer_capacity, last)</computeroutput> will be copied. </para> 1170</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T(const T&)</computeroutput> throws. </simpara></throws></constructor> 1171<destructor><purpose>The destructor. </purpose><description><para>Destroys the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. 1172<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> (including iterators equal to <computeroutput>end()</computeroutput>). </para> 1173</formalpara> 1174<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>) for scalar types; linear for other types. </para> 1175</formalpara> 1176<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>clear()</computeroutput> </para> 1177</para> 1178</para></description><throws><simpara><classname>Nothing.</classname> </simpara></throws></destructor> 1179<copy-assignment><type><classname>circular_buffer</classname>< T, Alloc > &</type><parameter name="cb"><paramtype>const <classname>circular_buffer</classname>< T, Alloc > &</paramtype><description><para>The <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> to be copied. </para></description></parameter><purpose>The assign operator. </purpose><description><para>Makes this <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> to become a copy of the specified <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. 1180 1181 1182<formalpara><title>Exception Safety</title><para>Strong. </para> 1183</formalpara> 1184<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to this <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>). </para> 1185</formalpara> 1186<formalpara><title>Complexity</title><para>Linear (in the size of <computeroutput>cb</computeroutput>). </para> 1187</formalpara> 1188<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>assign(size_type, const_reference)</computeroutput>, <computeroutput>assign(capacity_type, size_type, const_reference)</computeroutput>, <computeroutput>assign(InputIterator, InputIterator)</computeroutput>, <computeroutput>assign(capacity_type, InputIterator, InputIterator)</computeroutput> </para> 1189</para> 1190</para></description><postconditions><para><computeroutput>*this == cb</computeroutput> </para> 1191</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T(const T&)</computeroutput> throws. </simpara></throws></copy-assignment> 1192<copy-assignment cv="noexcept"><type><classname>circular_buffer</classname>< T, Alloc > &</type><parameter name="cb"><paramtype><classname>circular_buffer</classname>< T, Alloc > &&</paramtype><description><para><computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> to 'steal' value from. </para></description></parameter><purpose>Move assigns content of <computeroutput>cb</computeroutput> to <computeroutput>*this</computeroutput>, leaving <computeroutput>cb</computeroutput> empty. </purpose><description><para> 1193 1194 1195 1196<formalpara><title>Complexity</title><para>Constant. </para> 1197</formalpara> 1198</para></description><requires><para>C++ compiler with rvalue references support. </para> 1199</requires><postconditions><para><computeroutput>cb.empty()</computeroutput> </para> 1200</postconditions><throws><simpara><classname>Nothing.</classname> </simpara></throws></copy-assignment> 1201</class><function name="operator=="><type>bool</type><template> 1202 <template-type-parameter name="T"/> 1203 <template-type-parameter name="Alloc"/> 1204 </template><parameter name="lhs"><paramtype>const <classname>circular_buffer</classname>< T, Alloc > &</paramtype><description><para>The <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> to compare. </para></description></parameter><parameter name="rhs"><paramtype>const <classname>circular_buffer</classname>< T, Alloc > &</paramtype><description><para>The <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> to compare. </para></description></parameter><purpose>Compare two <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>s element-by-element to determine if they are equal. </purpose><description><para> 1205 1206 1207<formalpara><title>Complexity</title><para>Linear (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>s). </para> 1208</formalpara> 1209<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators. </para> 1210</formalpara> 1211</para></description><returns><para><computeroutput>lhs.size() == rhs.size() && <ulink url="https://www.boost.org/sgi/stl/equal.html">std::equal</ulink>(lhs.begin(), lhs.end(), rhs.begin())</computeroutput> </para> 1212</returns><throws><simpara><classname>Nothing.</classname> </simpara></throws></function> 1213<function name="operator<"><type>bool</type><template> 1214 <template-type-parameter name="T"/> 1215 <template-type-parameter name="Alloc"/> 1216 </template><parameter name="lhs"><paramtype>const <classname>circular_buffer</classname>< T, Alloc > &</paramtype><description><para>The <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> to compare. </para></description></parameter><parameter name="rhs"><paramtype>const <classname>circular_buffer</classname>< T, Alloc > &</paramtype><description><para>The <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> to compare. </para></description></parameter><purpose>Compare two <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>s element-by-element to determine if the left one is lesser than the right one. </purpose><description><para> 1217 1218 1219<formalpara><title>Complexity</title><para>Linear (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>s). </para> 1220</formalpara> 1221<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators. </para> 1222</formalpara> 1223</para></description><returns><para><computeroutput><ulink url="https://www.boost.org/sgi/stl/lexicographical_compare.html">std::lexicographical_compare</ulink>(lhs.begin(), lhs.end(), rhs.begin(), rhs.end())</computeroutput> </para> 1224</returns><throws><simpara><classname>Nothing.</classname> </simpara></throws></function> 1225<function name="operator!="><type>bool</type><template> 1226 <template-type-parameter name="T"/> 1227 <template-type-parameter name="Alloc"/> 1228 </template><parameter name="lhs"><paramtype>const <classname>circular_buffer</classname>< T, Alloc > &</paramtype><description><para>The <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> to compare. </para></description></parameter><parameter name="rhs"><paramtype>const <classname>circular_buffer</classname>< T, Alloc > &</paramtype><description><para>The <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> to compare. </para></description></parameter><purpose>Compare two <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>s element-by-element to determine if they are non-equal. </purpose><description><para> 1229 1230 1231<formalpara><title>Complexity</title><para>Linear (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>s). </para> 1232</formalpara> 1233<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators. </para> 1234</formalpara> 1235<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>operator==(const circular_buffer<T,Alloc>&, const circular_buffer<T,Alloc>&)</computeroutput> </para> 1236</para> 1237</para></description><returns><para><computeroutput>!(lhs == rhs)</computeroutput> </para> 1238</returns><throws><simpara><classname>Nothing.</classname> </simpara></throws></function> 1239<function name="operator>"><type>bool</type><template> 1240 <template-type-parameter name="T"/> 1241 <template-type-parameter name="Alloc"/> 1242 </template><parameter name="lhs"><paramtype>const <classname>circular_buffer</classname>< T, Alloc > &</paramtype><description><para>The <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> to compare. </para></description></parameter><parameter name="rhs"><paramtype>const <classname>circular_buffer</classname>< T, Alloc > &</paramtype><description><para>The <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> to compare. </para></description></parameter><purpose>Compare two <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>s element-by-element to determine if the left one is greater than the right one. </purpose><description><para> 1243 1244 1245<formalpara><title>Complexity</title><para>Linear (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>s). </para> 1246</formalpara> 1247<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators. </para> 1248</formalpara> 1249<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>operator<(const circular_buffer<T,Alloc>&, const circular_buffer<T,Alloc>&)</computeroutput> </para> 1250</para> 1251</para></description><returns><para><computeroutput>rhs < lhs</computeroutput> </para> 1252</returns><throws><simpara><classname>Nothing.</classname> </simpara></throws></function> 1253<function name="operator<="><type>bool</type><template> 1254 <template-type-parameter name="T"/> 1255 <template-type-parameter name="Alloc"/> 1256 </template><parameter name="lhs"><paramtype>const <classname>circular_buffer</classname>< T, Alloc > &</paramtype><description><para>The <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> to compare. </para></description></parameter><parameter name="rhs"><paramtype>const <classname>circular_buffer</classname>< T, Alloc > &</paramtype><description><para>The <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> to compare. </para></description></parameter><purpose>Compare two <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>s element-by-element to determine if the left one is lesser or equal to the right one. </purpose><description><para> 1257 1258 1259<formalpara><title>Complexity</title><para>Linear (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>s). </para> 1260</formalpara> 1261<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators. </para> 1262</formalpara> 1263<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>operator<(const circular_buffer<T,Alloc>&, const circular_buffer<T,Alloc>&)</computeroutput> </para> 1264</para> 1265</para></description><returns><para><computeroutput>!(rhs < lhs)</computeroutput> </para> 1266</returns><throws><simpara><classname>Nothing.</classname> </simpara></throws></function> 1267<function name="operator>="><type>bool</type><template> 1268 <template-type-parameter name="T"/> 1269 <template-type-parameter name="Alloc"/> 1270 </template><parameter name="lhs"><paramtype>const <classname>circular_buffer</classname>< T, Alloc > &</paramtype><description><para>The <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> to compare. </para></description></parameter><parameter name="rhs"><paramtype>const <classname>circular_buffer</classname>< T, Alloc > &</paramtype><description><para>The <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> to compare. </para></description></parameter><purpose>Compare two <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>s element-by-element to determine if the left one is greater or equal to the right one. </purpose><description><para> 1271 1272 1273<formalpara><title>Complexity</title><para>Linear (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>s). </para> 1274</formalpara> 1275<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators. </para> 1276</formalpara> 1277<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>operator<(const circular_buffer<T,Alloc>&, const circular_buffer<T,Alloc>&)</computeroutput> </para> 1278</para> 1279</para></description><returns><para><computeroutput>!(lhs < rhs)</computeroutput> </para> 1280</returns><throws><simpara><classname>Nothing.</classname> </simpara></throws></function> 1281<function name="swap"><type>void</type><template> 1282 <template-type-parameter name="T"/> 1283 <template-type-parameter name="Alloc"/> 1284 </template><parameter name="lhs"><paramtype><classname>circular_buffer</classname>< T, Alloc > &</paramtype><description><para>The <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> whose content will be swapped with <computeroutput>rhs</computeroutput>. </para></description></parameter><parameter name="rhs"><paramtype><classname>circular_buffer</classname>< T, Alloc > &</paramtype><description><para>The <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> whose content will be swapped with <computeroutput>lhs</computeroutput>. </para></description></parameter><purpose>Swap the contents of two <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>s. </purpose><description><para> 1285 1286 1287<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>s). </para> 1288</formalpara> 1289<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators of both <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>s. (On the other hand the iterators still point to the same elements but within another container. If you want to rely on this feature you have to turn the <ulink url="#debug">Debug Support</ulink> off otherwise an assertion will report an error if such invalidated iterator is used.) </para> 1290</formalpara> 1291<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>swap(circular_buffer<T, Alloc>&)</computeroutput> </para> 1292</para> 1293</para></description><postconditions><para><computeroutput>lhs</computeroutput> contains elements of <computeroutput>rhs</computeroutput> and vice versa. </para> 1294</postconditions><throws><simpara><classname>Nothing.</classname> </simpara></throws></function> 1295 1296 1297 1298 1299 1300 1301 1302</namespace> 1303</header> 1304<header name="boost/circular_buffer/space_optimized.hpp"> 1305<namespace name="boost"> 1306<class name="circular_buffer_space_optimized"><template> 1307 <template-type-parameter name="T"/> 1308 <template-type-parameter name="Alloc"/> 1309 </template><inherit access="private">boost::circular_buffer< T, Alloc ></inherit><purpose>Space optimized circular buffer container adaptor. <computeroutput>T</computeroutput> must be a copyable class or must have an noexcept move constructor and move assignment operator. </purpose><typedef name="value_type"><type><classname>circular_buffer</classname>< T, Alloc >::value_type</type></typedef> 1310<typedef name="pointer"><type><classname>circular_buffer</classname>< T, Alloc >::pointer</type></typedef> 1311<typedef name="const_pointer"><type><classname>circular_buffer</classname>< T, Alloc >::const_pointer</type></typedef> 1312<typedef name="reference"><type><classname>circular_buffer</classname>< T, Alloc >::reference</type></typedef> 1313<typedef name="const_reference"><type><classname>circular_buffer</classname>< T, Alloc >::const_reference</type></typedef> 1314<typedef name="size_type"><type><classname>circular_buffer</classname>< T, Alloc >::size_type</type></typedef> 1315<typedef name="difference_type"><type><classname>circular_buffer</classname>< T, Alloc >::difference_type</type></typedef> 1316<typedef name="allocator_type"><type><classname>circular_buffer</classname>< T, Alloc >::allocator_type</type></typedef> 1317<typedef name="const_iterator"><type><classname>circular_buffer</classname>< T, Alloc >::const_iterator</type></typedef> 1318<typedef name="iterator"><type><classname>circular_buffer</classname>< T, Alloc >::iterator</type></typedef> 1319<typedef name="const_reverse_iterator"><type><classname>circular_buffer</classname>< T, Alloc >::const_reverse_iterator</type></typedef> 1320<typedef name="reverse_iterator"><type><classname>circular_buffer</classname>< T, Alloc >::reverse_iterator</type></typedef> 1321<typedef name="array_range"><type><classname>circular_buffer</classname>< T, Alloc >::array_range</type></typedef> 1322<typedef name="const_array_range"><type><classname>circular_buffer</classname>< T, Alloc >::const_array_range</type></typedef> 1323<typedef name="param_value_type"><type><classname>circular_buffer</classname>< T, Alloc >::param_value_type</type></typedef> 1324<typedef name="rvalue_type"><type><classname>circular_buffer</classname>< T, Alloc >::rvalue_type</type></typedef> 1325<typedef name="capacity_type"><description><para>Capacity controller of the space optimized circular buffer.</para><para><para><emphasis role="bold">See Also:</emphasis><para>capacity_control in details.hpp. </para> 1326</para> 1327<computeroutput> class capacity_control<sbr/> 1328 {<sbr/> 1329 size_type m_capacity; // Available capacity.<sbr/> 1330 size_type m_min_capacity; // Minimum capacity.<sbr/> 1331 public:<sbr/> 1332 capacity_control(size_type capacity, size_type min_capacity = 0)<sbr/> 1333 : m_capacity(capacity), m_min_capacity(min_capacity)<sbr/> 1334 {};<sbr/> 1335 size_type capacity() const { return m_capacity; }<sbr/> 1336 size_type min_capacity() const { return m_min_capacity; }<sbr/> 1337 operator size_type() const { return m_capacity; }<sbr/> 1338 };<sbr/> 1339 </computeroutput> </para><para>Always <computeroutput>capacity >= min_capacity</computeroutput>. </para><para>The <computeroutput>capacity()</computeroutput> represents the capacity of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> and the <computeroutput>min_capacity()</computeroutput> determines the minimal allocated size of its internal buffer. </para><para>The converting constructor of the <computeroutput>capacity_control</computeroutput> allows implicit conversion from <computeroutput>size_type</computeroutput>-like types which ensures compatibility of creating an instance of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> with other STL containers.</para><para>On the other hand the operator <computeroutput>size_type()</computeroutput> provides implicit conversion to the <computeroutput>size_type</computeroutput> which allows to treat the capacity of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> the same way as in the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </para></description><type>cb_details::capacity_control< size_type ></type></typedef> 1340<method-group name="public member functions"> 1341<method name="full" cv="const noexcept"><type>bool</type><purpose>Is the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> full? </purpose><description><para> 1342 1343<formalpara><title>Exception Safety</title><para>No-throw. </para> 1344</formalpara> 1345<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators. </para> 1346</formalpara> 1347<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput>). </para> 1348</formalpara> 1349<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>empty()</computeroutput> </para> 1350</para> 1351</para></description><returns><para><computeroutput>true</computeroutput> if the number of elements stored in the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> equals the capacity of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput>; <computeroutput>false</computeroutput> otherwise. </para> 1352</returns><throws><simpara><classname>Nothing.</classname> </simpara></throws></method> 1353<method name="reserve" cv="const noexcept"><type>size_type</type><purpose>Get the maximum number of elements which can be inserted into the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> without overwriting any of already stored elements. </purpose><description><para> 1354 1355<formalpara><title>Exception Safety</title><para>No-throw. </para> 1356</formalpara> 1357<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators. </para> 1358</formalpara> 1359<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput>). </para> 1360</formalpara> 1361<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>capacity()</computeroutput>, <computeroutput>size()</computeroutput>, <computeroutput>max_size()</computeroutput> </para> 1362</para> 1363</para></description><returns><para><computeroutput>capacity().capacity() - size()</computeroutput> </para> 1364</returns><throws><simpara><classname>Nothing.</classname> </simpara></throws></method> 1365<method name="capacity" cv="const noexcept"><type>const capacity_type &</type><purpose>Get the capacity of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput>. </purpose><description><para> 1366 1367<formalpara><title>Exception Safety</title><para>No-throw. </para> 1368</formalpara> 1369<formalpara><title>Iterator Invalidation</title><para>Does not invalidate any iterators. </para> 1370</formalpara> 1371<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput>). </para> 1372</formalpara> 1373<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>reserve()</computeroutput>, <computeroutput>size()</computeroutput>, <computeroutput>max_size()</computeroutput>, <computeroutput>set_capacity(const capacity_type&)</computeroutput> </para> 1374</para> 1375</para></description><returns><para>The capacity controller representing the maximum number of elements which can be stored in the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> and the minimal allocated size of the internal buffer. </para> 1376</returns><throws><simpara><classname>Nothing.</classname> </simpara></throws></method> 1377<method name="set_capacity"><type>void</type><parameter name="capacity_ctrl"><paramtype>const capacity_type &</paramtype><description><para>The new capacity controller. </para></description></parameter><purpose>Change the capacity (and the minimal guaranteed amount of allocated memory) of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput>. </purpose><description><para> 1378 1379 1380<formalpara><title>Exception Safety</title><para>Strong. </para> 1381</formalpara> 1382<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>). </para> 1383</formalpara> 1384<formalpara><title>Complexity</title><para>Linear (in <computeroutput>min[size(), capacity_ctrl.capacity()]</computeroutput>). </para> 1385</formalpara> 1386<note><para>To explicitly clear the extra allocated memory use the <emphasis role="bold">shrink-to-fit</emphasis> technique:<sbr/> 1387<sbr/> 1388 <computeroutput>boost::circular_buffer_space_optimized<int> cb(1000);<sbr/> 1389 ...<sbr/> 1390 boost::circular_buffer_space_optimized<int>(cb).swap(cb);</computeroutput><sbr/> 1391<sbr/> 1392 For more information about the shrink-to-fit technique in STL see <ulink url="http://www.gotw.ca/gotw/054.htm">http://www.gotw.ca/gotw/054.htm</ulink>. </para> 1393</note> 1394<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>rset_capacity(const capacity_type&)</computeroutput>, <computeroutput>resize(size_type, const_reference)</computeroutput> </para> 1395</para> 1396</para></description><postconditions><para><computeroutput>capacity() == capacity_ctrl && size() <= capacity_ctrl.capacity()</computeroutput><sbr/> 1397<sbr/> 1398 If the current number of elements stored in the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> is greater than the desired new capacity then number of <computeroutput>[size() - capacity_ctrl.capacity()]</computeroutput> <emphasis role="bold">last</emphasis> elements will be removed and the new size will be equal to <computeroutput>capacity_ctrl.capacity()</computeroutput>.<sbr/> 1399<sbr/> 1400 If the current number of elements stored in the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> is lower than the new capacity then the amount of allocated memory in the internal buffer may be accommodated as necessary but it will never drop below <computeroutput>capacity_ctrl.min_capacity()</computeroutput>. </para> 1401</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted, (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T(const T&)</computeroutput> throws or nothing if <computeroutput>T::T(T&&)</computeroutput> is noexcept. </simpara></throws></method> 1402<method name="resize"><type>void</type><parameter name="new_size"><paramtype>size_type</paramtype><description><para>The new size. </para></description></parameter><parameter name="item"><paramtype>param_value_type</paramtype><default>value_type()</default><description><para>The element the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> will be filled with in order to gain the requested size. (See the <emphasis>Effect</emphasis>.) </para></description></parameter><purpose>Change the size of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput>. </purpose><description><para> 1403 1404 1405<formalpara><title>Exception Safety</title><para>Basic. </para> 1406</formalpara> 1407<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>). </para> 1408</formalpara> 1409<formalpara><title>Complexity</title><para>Linear (in the new size of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput>). </para> 1410</formalpara> 1411<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>rresize(size_type, const_reference)</computeroutput>, <computeroutput>set_capacity(const capacity_type&)</computeroutput> </para> 1412</para> 1413</para></description><postconditions><para><computeroutput>size() == new_size && capacity().capacity() >= new_size</computeroutput><sbr/> 1414<sbr/> 1415 If the new size is greater than the current size, copies of <computeroutput>item</computeroutput> will be inserted at the <emphasis role="bold">back</emphasis> of the of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> in order to achieve the desired size. In the case the resulting size exceeds the current capacity the capacity will be set to <computeroutput>new_size</computeroutput>.<sbr/> 1416<sbr/> 1417 If the current number of elements stored in the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> is greater than the desired new size then number of <computeroutput>[size() - new_size]</computeroutput> <emphasis role="bold">last</emphasis> elements will be removed. (The capacity will remain unchanged.)<sbr/> 1418<sbr/> 1419 The amount of allocated memory in the internal buffer may be accommodated as necessary. </para> 1420</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T(const T&)</computeroutput> throws. </simpara></throws></method> 1421<method name="rset_capacity"><type>void</type><parameter name="capacity_ctrl"><paramtype>const capacity_type &</paramtype><description><para>The new capacity controller. </para></description></parameter><purpose>Change the capacity (and the minimal guaranteed amount of allocated memory) of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput>. </purpose><description><para> 1422 1423 1424<formalpara><title>Exception Safety</title><para>Strong. </para> 1425</formalpara> 1426<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>). </para> 1427</formalpara> 1428<formalpara><title>Complexity</title><para>Linear (in <computeroutput>min[size(), capacity_ctrl.capacity()]</computeroutput>). </para> 1429</formalpara> 1430<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>set_capacity(const capacity_type&)</computeroutput>, <computeroutput>rresize(size_type, const_reference)</computeroutput> </para> 1431</para> 1432</para></description><postconditions><para><computeroutput>capacity() == capacity_ctrl && size() <= capacity_ctrl</computeroutput><sbr/> 1433<sbr/> 1434 If the current number of elements stored in the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> is greater than the desired new capacity then number of <computeroutput>[size() - capacity_ctrl.capacity()]</computeroutput> <emphasis role="bold">first</emphasis> elements will be removed and the new size will be equal to <computeroutput>capacity_ctrl.capacity()</computeroutput>.<sbr/> 1435<sbr/> 1436 If the current number of elements stored in the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> is lower than the new capacity then the amount of allocated memory in the internal buffer may be accommodated as necessary but it will never drop below <computeroutput>capacity_ctrl.min_capacity()</computeroutput>. </para> 1437</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T(const T&)</computeroutput> throws or nothing if <computeroutput>T::T(T&&)</computeroutput> is noexcept. </simpara></throws></method> 1438<method name="rresize"><type>void</type><parameter name="new_size"><paramtype>size_type</paramtype><description><para>The new size. </para></description></parameter><parameter name="item"><paramtype>param_value_type</paramtype><default>value_type()</default><description><para>The element the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> will be filled with in order to gain the requested size. (See the <emphasis>Effect</emphasis>.) </para></description></parameter><purpose>Change the size of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput>. </purpose><description><para> 1439 1440 1441<formalpara><title>Exception Safety</title><para>Basic. </para> 1442</formalpara> 1443<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>). </para> 1444</formalpara> 1445<formalpara><title>Complexity</title><para>Linear (in the new size of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput>). </para> 1446</formalpara> 1447<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>resize(size_type, const_reference)</computeroutput>, <computeroutput>rset_capacity(const capacity_type&)</computeroutput> </para> 1448</para> 1449</para></description><postconditions><para><computeroutput>size() == new_size && capacity().capacity() >= new_size</computeroutput><sbr/> 1450<sbr/> 1451 If the new size is greater than the current size, copies of <computeroutput>item</computeroutput> will be inserted at the <emphasis role="bold">front</emphasis> of the of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> in order to achieve the desired size. In the case the resulting size exceeds the current capacity the capacity will be set to <computeroutput>new_size</computeroutput>.<sbr/> 1452<sbr/> 1453 If the current number of elements stored in the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> is greater than the desired new size then number of <computeroutput>[size() - new_size]</computeroutput> <emphasis role="bold">first</emphasis> elements will be removed. (The capacity will remain unchanged.)<sbr/> 1454<sbr/> 1455 The amount of allocated memory in the internal buffer may be accommodated as necessary. </para> 1456</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T(const T&)</computeroutput> throws. </simpara></throws></method> 1457<method name="assign"><type>void</type><parameter name="n"><paramtype>size_type</paramtype><description><para>The number of elements the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> will be filled with. </para></description></parameter><parameter name="item"><paramtype>param_value_type</paramtype><description><para>The element the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> will be filled with. </para></description></parameter><purpose>Assign <computeroutput>n</computeroutput> items into the space optimized circular buffer. </purpose><description><para>The content of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> will be removed and replaced with <computeroutput>n</computeroutput> copies of the <computeroutput>item</computeroutput>. 1458 1459 1460<formalpara><title>Exception Safety</title><para>Basic. </para> 1461</formalpara> 1462<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>). </para> 1463</formalpara> 1464<formalpara><title>Complexity</title><para>Linear (in the <computeroutput>n</computeroutput>). </para> 1465</formalpara> 1466<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>operator=</computeroutput>, <computeroutput>assign(capacity_type, size_type, const_reference)</computeroutput>, <computeroutput>assign(InputIterator, InputIterator)</computeroutput>, <computeroutput>assign(capacity_type, InputIterator, InputIterator)</computeroutput> </para> 1467</para> 1468</para></description><postconditions><para><computeroutput>capacity().capacity() == n && capacity().min_capacity() == 0 && size() == n && (*this)[0] == item && (*this)[1] == item && ... && (*this) [n - 1] == item</computeroutput><sbr/> 1469<sbr/> 1470 The amount of allocated memory in the internal buffer is <computeroutput>n</computeroutput>. </para> 1471</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T(const T&)</computeroutput> throws. </simpara></throws></method> 1472<method name="assign"><type>void</type><parameter name="capacity_ctrl"><paramtype>capacity_type</paramtype><description><para>The new capacity controller. </para></description></parameter><parameter name="n"><paramtype>size_type</paramtype><description><para>The number of elements the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> will be filled with. </para></description></parameter><parameter name="item"><paramtype>param_value_type</paramtype><description><para>The element the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> will be filled with. </para></description></parameter><purpose>Assign <computeroutput>n</computeroutput> items into the space optimized circular buffer specifying the capacity. </purpose><description><para>The capacity of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> will be set to the specified value and the content of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> will be removed and replaced with <computeroutput>n</computeroutput> copies of the <computeroutput>item</computeroutput>. 1473 1474 1475 1476<formalpara><title>Exception Safety</title><para>Basic. </para> 1477</formalpara> 1478<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>). </para> 1479</formalpara> 1480<formalpara><title>Complexity</title><para>Linear (in the <computeroutput>n</computeroutput>). </para> 1481</formalpara> 1482<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>operator=</computeroutput>, <computeroutput>assign(size_type, const_reference)</computeroutput>, <computeroutput>assign(InputIterator, InputIterator)</computeroutput>, <computeroutput>assign(capacity_type, InputIterator, InputIterator)</computeroutput> </para> 1483</para> 1484</para></description><requires><para><computeroutput>capacity_ctrl.capacity() >= n</computeroutput> </para> 1485</requires><postconditions><para><computeroutput>capacity() == capacity_ctrl && size() == n && (*this)[0] == item && (*this)[1] == item && ... && (*this) [n - 1] == item </computeroutput><sbr/> 1486<sbr/> 1487 The amount of allocated memory will be <computeroutput>max[n, capacity_ctrl.min_capacity()]</computeroutput>. </para> 1488</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T(const T&)</computeroutput> throws. </simpara></throws></method> 1489<method name="assign"><type>void</type><template> 1490 <template-type-parameter name="InputIterator"/> 1491 </template><parameter name="first"><paramtype>InputIterator</paramtype><description><para>The beginning of the range to be copied. </para></description></parameter><parameter name="last"><paramtype>InputIterator</paramtype><description><para>The end of the range to be copied. </para></description></parameter><purpose>Assign a copy of the range into the space optimized circular buffer. </purpose><description><para>The content of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> will be removed and replaced with copies of elements from the specified range. 1492 1493 1494 1495<formalpara><title>Exception Safety</title><para>Basic. </para> 1496</formalpara> 1497<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>). </para> 1498</formalpara> 1499<formalpara><title>Complexity</title><para>Linear (in the <computeroutput>std::distance(first, last)</computeroutput>). </para> 1500</formalpara> 1501<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>operator=</computeroutput>, <computeroutput>assign(size_type, const_reference)</computeroutput>, <computeroutput>assign(capacity_type, size_type, const_reference)</computeroutput>, <computeroutput>assign(capacity_type, InputIterator, InputIterator)</computeroutput> </para> 1502</para> 1503</para></description><requires><para>Valid range <computeroutput>[first, last)</computeroutput>.<sbr/> 1504 <computeroutput>first</computeroutput> and <computeroutput>last</computeroutput> have to meet the requirements of <ulink url="https://www.boost.org/sgi/stl/InputIterator.html">InputIterator</ulink>. </para> 1505</requires><postconditions><para><computeroutput>capacity().capacity() == std::distance(first, last) && capacity().min_capacity() == 0 && size() == std::distance(first, last) && (*this)[0]== *first && (*this)[1] == *(first + 1) && ... && (*this)[std::distance(first, last) - 1] == *(last - 1)</computeroutput><sbr/> 1506<sbr/> 1507 The amount of allocated memory in the internal buffer is <computeroutput>std::distance(first, last)</computeroutput>. </para> 1508</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T(const T&)</computeroutput> throws or nothing if <computeroutput>T::T(T&&)</computeroutput> is noexcept and <computeroutput>InputIterator</computeroutput> is a move iterator. </simpara></throws></method> 1509<method name="assign"><type>void</type><template> 1510 <template-type-parameter name="InputIterator"/> 1511 </template><parameter name="capacity_ctrl"><paramtype>capacity_type</paramtype><description><para>The new capacity controller. </para></description></parameter><parameter name="first"><paramtype>InputIterator</paramtype><description><para>The beginning of the range to be copied. </para></description></parameter><parameter name="last"><paramtype>InputIterator</paramtype><description><para>The end of the range to be copied. </para></description></parameter><purpose>Assign a copy of the range into the space optimized circular buffer specifying the capacity. </purpose><description><para>The capacity of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> will be set to the specified value and the content of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> will be removed and replaced with copies of elements from the specified range. 1512 1513 1514 1515<formalpara><title>Exception Safety</title><para>Basic. </para> 1516</formalpara> 1517<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>). </para> 1518</formalpara> 1519<formalpara><title>Complexity</title><para>Linear (in <computeroutput>std::distance(first, last)</computeroutput>; in <computeroutput>min[capacity_ctrl.capacity(), std::distance(first, last)]</computeroutput> if the <computeroutput>InputIterator</computeroutput> is a <ulink url="https://www.boost.org/sgi/stl/RandomAccessIterator.html">RandomAccessIterator</ulink>). </para> 1520</formalpara> 1521<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>operator=</computeroutput>, <computeroutput>assign(size_type, const_reference)</computeroutput>, <computeroutput>assign(capacity_type, size_type, const_reference)</computeroutput>, <computeroutput>assign(InputIterator, InputIterator)</computeroutput> </para> 1522</para> 1523</para></description><requires><para>Valid range <computeroutput>[first, last)</computeroutput>.<sbr/> 1524 <computeroutput>first</computeroutput> and <computeroutput>last</computeroutput> have to meet the requirements of <ulink url="https://www.boost.org/sgi/stl/InputIterator.html">InputIterator</ulink>. </para> 1525</requires><postconditions><para><computeroutput>capacity() == capacity_ctrl && size() <= std::distance(first, last) && (*this)[0]== *(last - capacity) && (*this)[1] == *(last - capacity + 1) && ... && (*this)[capacity - 1] == *(last - 1)</computeroutput><sbr/> 1526<sbr/> 1527 If the number of items to be copied from the range <computeroutput>[first, last)</computeroutput> is greater than the specified <computeroutput>capacity</computeroutput> then only elements from the range <computeroutput>[last - capacity, last)</computeroutput> will be copied.<sbr/> 1528<sbr/> 1529 The amount of allocated memory in the internal buffer is <computeroutput>max[std::distance(first, last), capacity_ctrl.min_capacity()]</computeroutput>. </para> 1530</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T(const T&)</computeroutput> throws or nothing if <computeroutput>T::T(T&&)</computeroutput> is noexcept and <computeroutput>InputIterator</computeroutput> is a move iterator. </simpara></throws></method> 1531<method name="swap" cv="noexcept"><type>void</type><parameter name="cb"><paramtype><classname>circular_buffer_space_optimized</classname>< T, Alloc > &</paramtype><description><para>The <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> whose content will be swapped. </para></description></parameter><purpose>Swap the contents of two space-optimized circular-buffers. </purpose><description><para> 1532 1533 1534<formalpara><title>Exception Safety</title><para>No-throw. </para> 1535</formalpara> 1536<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators of both <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> containers. (On the other hand the iterators still point to the same elements but within another container. If you want to rely on this feature you have to turn the __debug_support off, otherwise an assertion will report an error if such invalidated iterator is used.) </para> 1537</formalpara> 1538<formalpara><title>Complexity</title><para>Constant (in the size of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput>). </para> 1539</formalpara> 1540<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>swap(circular_buffer<T, Alloc>&, circular_buffer<T, Alloc>&)</computeroutput>, <computeroutput>swap(circular_buffer_space_optimized<T, Alloc>&, circular_buffer_space_optimized<T, Alloc>&)</computeroutput> </para> 1541</para> 1542</para></description><postconditions><para><computeroutput>this</computeroutput> contains elements of <computeroutput>cb</computeroutput> and vice versa; the capacity and the amount of allocated memory in the internal buffer of <computeroutput>this</computeroutput> equal to the capacity and the amount of allocated memory of <computeroutput>cb</computeroutput> and vice versa. </para> 1543</postconditions><throws><simpara><classname>Nothing.</classname> </simpara></throws></method> 1544<method name="push_back"><type>void</type><parameter name="item"><paramtype>param_value_type</paramtype><description><para>The element to be inserted. </para></description></parameter><purpose>Insert a new element at the end of the space optimized circular buffer. </purpose><description><para> 1545 1546 1547<formalpara><title>Exception Safety</title><para>Basic. </para> 1548</formalpara> 1549<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>). </para> 1550</formalpara> 1551<formalpara><title>Complexity</title><para>Linear (in the size of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput>). </para> 1552</formalpara> 1553<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>push_front(const_reference)</computeroutput>, <computeroutput>pop_back()</computeroutput>, <computeroutput>pop_front()</computeroutput> </para> 1554</para> 1555</para></description><postconditions><para>if <computeroutput>capacity().capacity() > 0</computeroutput> then <computeroutput>back() == item</computeroutput><sbr/> 1556 If the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> is full, the first element will be removed. If the capacity is <computeroutput>0</computeroutput>, nothing will be inserted.<sbr/> 1557<sbr/> 1558 The amount of allocated memory in the internal buffer may be predictively increased. </para> 1559</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T(const T&)</computeroutput> throws. </simpara></throws></method> 1560<method name="push_back"><type>void</type><parameter name="item"><paramtype>rvalue_type</paramtype><description><para>The element to be inserted. </para></description></parameter><purpose>Insert a new element at the end of the space optimized circular buffer. </purpose><description><para> 1561 1562 1563<formalpara><title>Exception Safety</title><para>Basic. </para> 1564</formalpara> 1565<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>). </para> 1566</formalpara> 1567<formalpara><title>Complexity</title><para>Linear (in the size of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput>). </para> 1568</formalpara> 1569<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>push_front(const_reference)</computeroutput>, <computeroutput>pop_back()</computeroutput>, <computeroutput>pop_front()</computeroutput> </para> 1570</para> 1571</para></description><postconditions><para>if <computeroutput>capacity().capacity() > 0</computeroutput> then <computeroutput>back() == item</computeroutput><sbr/> 1572 If the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> is full, the first element will be removed. If the capacity is <computeroutput>0</computeroutput>, nothing will be inserted.<sbr/> 1573<sbr/> 1574 The amount of allocated memory in the internal buffer may be predictively increased. </para> 1575</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). </simpara></throws></method> 1576<method name="push_back"><type>void</type><purpose>Insert a new element at the end of the space optimized circular buffer. </purpose><description><para> 1577 1578<formalpara><title>Exception Safety</title><para>Basic. </para> 1579</formalpara> 1580<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>). </para> 1581</formalpara> 1582<formalpara><title>Complexity</title><para>Linear (in the size of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput>). </para> 1583</formalpara> 1584<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>push_front(const_reference)</computeroutput>, <computeroutput>pop_back()</computeroutput>, <computeroutput>pop_front()</computeroutput> </para> 1585</para> 1586</para></description><postconditions><para>if <computeroutput>capacity().capacity() > 0</computeroutput> then <computeroutput>back() == item</computeroutput><sbr/> 1587 If the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> is full, the first element will be removed. If the capacity is <computeroutput>0</computeroutput>, nothing will be inserted.<sbr/> 1588<sbr/> 1589 The amount of allocated memory in the internal buffer may be predictively increased. </para> 1590</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T()</computeroutput> throws. Whatever <computeroutput>T::T(const T&)</computeroutput> throws or nothing if <computeroutput>T::T(T&&)</computeroutput> is noexcept. </simpara></throws></method> 1591<method name="push_front"><type>void</type><parameter name="item"><paramtype>param_value_type</paramtype><description><para>The element to be inserted. </para></description></parameter><purpose>Insert a new element at the beginning of the space optimized circular buffer. </purpose><description><para> 1592 1593 1594<formalpara><title>Exception Safety</title><para>Basic. </para> 1595</formalpara> 1596<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>). </para> 1597</formalpara> 1598<formalpara><title>Complexity</title><para>Linear (in the size of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput>). </para> 1599</formalpara> 1600<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>push_back(const_reference)</computeroutput>, <computeroutput>pop_back()</computeroutput>, <computeroutput>pop_front()</computeroutput> </para> 1601</para> 1602</para></description><postconditions><para>if <computeroutput>capacity().capacity() > 0</computeroutput> then <computeroutput>front() == item</computeroutput><sbr/> 1603 If the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> is full, the last element will be removed. If the capacity is <computeroutput>0</computeroutput>, nothing will be inserted.<sbr/> 1604<sbr/> 1605 The amount of allocated memory in the internal buffer may be predictively increased. </para> 1606</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T(const T&)</computeroutput> throws. </simpara></throws></method> 1607<method name="push_front"><type>void</type><parameter name="item"><paramtype>rvalue_type</paramtype><description><para>The element to be inserted. </para></description></parameter><purpose>Insert a new element at the beginning of the space optimized circular buffer. </purpose><description><para> 1608 1609 1610<formalpara><title>Exception Safety</title><para>Basic. </para> 1611</formalpara> 1612<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>). </para> 1613</formalpara> 1614<formalpara><title>Complexity</title><para>Linear (in the size of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput>). </para> 1615</formalpara> 1616<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>push_back(const_reference)</computeroutput>, <computeroutput>pop_back()</computeroutput>, <computeroutput>pop_front()</computeroutput> </para> 1617</para> 1618</para></description><postconditions><para>if <computeroutput>capacity().capacity() > 0</computeroutput> then <computeroutput>front() == item</computeroutput><sbr/> 1619 If the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> is full, the last element will be removed. If the capacity is <computeroutput>0</computeroutput>, nothing will be inserted.<sbr/> 1620<sbr/> 1621 The amount of allocated memory in the internal buffer may be predictively increased. </para> 1622</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T(const T&)</computeroutput> throws or nothing if <computeroutput>T::T(T&&)</computeroutput> is noexcept. </simpara></throws></method> 1623<method name="push_front"><type>void</type><purpose>Insert a new element at the beginning of the space optimized circular buffer. </purpose><description><para> 1624 1625<formalpara><title>Exception Safety</title><para>Basic. </para> 1626</formalpara> 1627<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>). </para> 1628</formalpara> 1629<formalpara><title>Complexity</title><para>Linear (in the size of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput>). </para> 1630</formalpara> 1631<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>push_back(const_reference)</computeroutput>, <computeroutput>pop_back()</computeroutput>, <computeroutput>pop_front()</computeroutput> </para> 1632</para> 1633</para></description><postconditions><para>if <computeroutput>capacity().capacity() > 0</computeroutput> then <computeroutput>front() == item</computeroutput><sbr/> 1634 If the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> is full, the last element will be removed. If the capacity is <computeroutput>0</computeroutput>, nothing will be inserted.<sbr/> 1635<sbr/> 1636 The amount of allocated memory in the internal buffer may be predictively increased. </para> 1637</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T()</computeroutput> throws. Whatever <computeroutput>T::T(const T&)</computeroutput> throws or nothing if <computeroutput>T::T(T&&)</computeroutput> is noexcept. </simpara></throws></method> 1638<method name="pop_back"><type>void</type><purpose>Remove the last element from the space optimized circular buffer. </purpose><description><para> 1639 1640 1641<formalpara><title>Exception Safety</title><para>Basic. </para> 1642</formalpara> 1643<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>). </para> 1644</formalpara> 1645<formalpara><title>Complexity</title><para>Linear (in the size of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput>). </para> 1646</formalpara> 1647<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>pop_front()</computeroutput>, <computeroutput>push_back(const_reference)</computeroutput>, <computeroutput>push_front(const_reference)</computeroutput> </para> 1648</para> 1649</para></description><requires><para><computeroutput>!empty()</computeroutput> </para> 1650</requires><postconditions><para>The last element is removed from the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput>.<sbr/> 1651<sbr/> 1652 The amount of allocated memory in the internal buffer may be predictively decreased. </para> 1653</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). </simpara></throws></method> 1654<method name="pop_front"><type>void</type><purpose>Remove the first element from the space optimized circular buffer. </purpose><description><para> 1655 1656 1657<formalpara><title>Exception Safety</title><para>Basic. </para> 1658</formalpara> 1659<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>). </para> 1660</formalpara> 1661<formalpara><title>Complexity</title><para>Linear (in the size of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput>). </para> 1662</formalpara> 1663<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>pop_back()</computeroutput>, <computeroutput>push_back(const_reference)</computeroutput>, <computeroutput>push_front(const_reference)</computeroutput> </para> 1664</para> 1665</para></description><requires><para><computeroutput>!empty()</computeroutput> </para> 1666</requires><postconditions><para>The first element is removed from the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput>.<sbr/> 1667<sbr/> 1668 The amount of allocated memory in the internal buffer may be predictively decreased. </para> 1669</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). </simpara></throws></method> 1670<method name="insert"><type>iterator</type><parameter name="pos"><paramtype>iterator</paramtype><description><para>An iterator specifying the position where the <computeroutput>item</computeroutput> will be inserted. </para></description></parameter><parameter name="item"><paramtype>param_value_type</paramtype><description><para>The element to be inserted. </para></description></parameter><purpose>Insert an element at the specified position. </purpose><description><para> 1671 1672 1673 1674 1675<formalpara><title>Exception Safety</title><para>Basic. </para> 1676</formalpara> 1677<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>). </para> 1678</formalpara> 1679<formalpara><title>Complexity</title><para>Linear (in the size of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput>). </para> 1680</formalpara> 1681<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>insert(iterator, size_type, value_type)</computeroutput>, <computeroutput>insert(iterator, InputIterator, InputIterator)</computeroutput>, <computeroutput>rinsert(iterator, value_type)</computeroutput>, <computeroutput>rinsert(iterator, size_type, value_type)</computeroutput>, <computeroutput>rinsert(iterator, InputIterator, InputIterator)</computeroutput> </para> 1682</para> 1683</para></description><requires><para><computeroutput>pos</computeroutput> is a valid iterator pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> or its end. </para> 1684</requires><postconditions><para>The <computeroutput>item</computeroutput> will be inserted at the position <computeroutput>pos</computeroutput>.<sbr/> 1685 If the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> is full, the first element will be overwritten. If the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> is full and the <computeroutput>pos</computeroutput> points to <computeroutput>begin()</computeroutput>, then the <computeroutput>item</computeroutput> will not be inserted. If the capacity is <computeroutput>0</computeroutput>, nothing will be inserted.<sbr/> 1686<sbr/> 1687 The amount of allocated memory in the internal buffer may be predictively increased. </para> 1688</postconditions><returns><para>Iterator to the inserted element or <computeroutput>begin()</computeroutput> if the <computeroutput>item</computeroutput> is not inserted. (See the <emphasis>Effect</emphasis>.) </para> 1689</returns><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T(const T&)</computeroutput> throws. Whatever <computeroutput>T::operator = (const T&)</computeroutput> throws. </simpara></throws></method> 1690<method name="insert"><type>iterator</type><parameter name="pos"><paramtype>iterator</paramtype><description><para>An iterator specifying the position where the <computeroutput>item</computeroutput> will be inserted. </para></description></parameter><parameter name="item"><paramtype>rvalue_type</paramtype><description><para>The element to be inserted. </para></description></parameter><purpose>Insert an element at the specified position. </purpose><description><para> 1691 1692 1693 1694 1695<formalpara><title>Exception Safety</title><para>Basic. </para> 1696</formalpara> 1697<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>). </para> 1698</formalpara> 1699<formalpara><title>Complexity</title><para>Linear (in the size of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput>). </para> 1700</formalpara> 1701<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>insert(iterator, size_type, value_type)</computeroutput>, <computeroutput>insert(iterator, InputIterator, InputIterator)</computeroutput>, <computeroutput>rinsert(iterator, value_type)</computeroutput>, <computeroutput>rinsert(iterator, size_type, value_type)</computeroutput>, <computeroutput>rinsert(iterator, InputIterator, InputIterator)</computeroutput> </para> 1702</para> 1703</para></description><requires><para><computeroutput>pos</computeroutput> is a valid iterator pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> or its end. </para> 1704</requires><postconditions><para>The <computeroutput>item</computeroutput> will be inserted at the position <computeroutput>pos</computeroutput>.<sbr/> 1705 If the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> is full, the first element will be overwritten. If the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> is full and the <computeroutput>pos</computeroutput> points to <computeroutput>begin()</computeroutput>, then the <computeroutput>item</computeroutput> will not be inserted. If the capacity is <computeroutput>0</computeroutput>, nothing will be inserted.<sbr/> 1706<sbr/> 1707 The amount of allocated memory in the internal buffer may be predictively increased. </para> 1708</postconditions><returns><para>Iterator to the inserted element or <computeroutput>begin()</computeroutput> if the <computeroutput>item</computeroutput> is not inserted. (See the <emphasis>Effect</emphasis>.) </para> 1709</returns><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T(const T&)</computeroutput> throws or nothing if <computeroutput>T::T(T&&)</computeroutput> is noexcept. </simpara></throws></method> 1710<method name="insert"><type>iterator</type><parameter name="pos"><paramtype>iterator</paramtype><description><para>An iterator specifying the position where the <computeroutput>item</computeroutput> will be inserted. </para></description></parameter><purpose>Insert an element at the specified position. </purpose><description><para> 1711 1712 1713 1714 1715<formalpara><title>Exception Safety</title><para>Basic. </para> 1716</formalpara> 1717<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>). </para> 1718</formalpara> 1719<formalpara><title>Complexity</title><para>Linear (in the size of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput>). </para> 1720</formalpara> 1721<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>insert(iterator, size_type, value_type)</computeroutput>, <computeroutput>insert(iterator, InputIterator, InputIterator)</computeroutput>, <computeroutput>rinsert(iterator, value_type)</computeroutput>, <computeroutput>rinsert(iterator, size_type, value_type)</computeroutput>, <computeroutput>rinsert(iterator, InputIterator, InputIterator)</computeroutput> </para> 1722</para> 1723</para></description><requires><para><computeroutput>pos</computeroutput> is a valid iterator pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> or its end. </para> 1724</requires><postconditions><para>The <computeroutput>item</computeroutput> will be inserted at the position <computeroutput>pos</computeroutput>.<sbr/> 1725 If the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> is full, the first element will be overwritten. If the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> is full and the <computeroutput>pos</computeroutput> points to <computeroutput>begin()</computeroutput>, then the <computeroutput>item</computeroutput> will not be inserted. If the capacity is <computeroutput>0</computeroutput>, nothing will be inserted.<sbr/> 1726<sbr/> 1727 The amount of allocated memory in the internal buffer may be predictively increased. </para> 1728</postconditions><returns><para>Iterator to the inserted element or <computeroutput>begin()</computeroutput> if the <computeroutput>item</computeroutput> is not inserted. (See the <emphasis>Effect</emphasis>.) </para> 1729</returns><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T()</computeroutput> throws. Whatever <computeroutput>T::T(const T&)</computeroutput> throws or nothing if <computeroutput>T::T(T&&)</computeroutput> is noexcept. </simpara></throws></method> 1730<method name="insert"><type>void</type><parameter name="pos"><paramtype>iterator</paramtype><description><para>An iterator specifying the position where the <computeroutput>item</computeroutput>s will be inserted. </para></description></parameter><parameter name="n"><paramtype>size_type</paramtype><description><para>The number of <computeroutput>item</computeroutput>s the to be inserted. </para></description></parameter><parameter name="item"><paramtype>param_value_type</paramtype><description><para>The element whose copies will be inserted. </para></description></parameter><purpose>Insert <computeroutput>n</computeroutput> copies of the <computeroutput>item</computeroutput> at the specified position. </purpose><description><para> 1731 1732 1733 1734<formalpara><title>Exception Safety</title><para>Basic. </para> 1735</formalpara> 1736<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>). </para> 1737</formalpara> 1738<formalpara><title>Complexity</title><para>Linear (in <computeroutput>min[capacity().capacity(), size() + n]</computeroutput>). </para> 1739</formalpara> 1740<formalpara><title>Example</title><para>Consider a <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> with the capacity of 6 and the size of 4. Its internal buffer may look like the one below.<sbr/> 1741<sbr/> 1742 <computeroutput>|1|2|3|4| | |</computeroutput><sbr/> 1743 <computeroutput>p ___^</computeroutput><sbr/> 1744<sbr/> 1745After inserting 5 elements at the position <computeroutput>p</computeroutput>:<sbr/> 1746<sbr/> 1747 <computeroutput>insert(p, (size_t)5, 0);</computeroutput><sbr/> 1748<sbr/> 1749actually only 4 elements get inserted and elements <computeroutput>1</computeroutput> and <computeroutput>2</computeroutput> are overwritten. This is due to the fact the insert operation preserves the capacity. After insertion the internal buffer looks like this:<sbr/> 1750<sbr/> 1751<computeroutput>|0|0|0|0|3|4|</computeroutput><sbr/> 1752 <sbr/> 1753For comparison if the capacity would not be preserved the internal buffer would then result in <computeroutput>|1|2|0|0|0|0|0|3|4|</computeroutput>. </para> 1754</formalpara> 1755<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>insert(iterator, value_type)</computeroutput>, <computeroutput>insert(iterator, InputIterator, InputIterator)</computeroutput>, <computeroutput>rinsert(iterator, value_type)</computeroutput>, <computeroutput>rinsert(iterator, size_type, value_type)</computeroutput>, <computeroutput>rinsert(iterator, InputIterator, InputIterator)</computeroutput> </para> 1756</para> 1757</para></description><requires><para><computeroutput>pos</computeroutput> is a valid iterator pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> or its end. </para> 1758</requires><postconditions><para>The number of <computeroutput>min[n, (pos - begin()) + reserve()]</computeroutput> elements will be inserted at the position <computeroutput>pos</computeroutput>.<sbr/> 1759The number of <computeroutput>min[pos - begin(), max[0, n - reserve()]]</computeroutput> elements will be overwritten at the beginning of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput>.<sbr/> 1760(See <emphasis>Example</emphasis> for the explanation.)<sbr/> 1761<sbr/> 1762 The amount of allocated memory in the internal buffer may be predictively increased. </para> 1763</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T(const T&)</computeroutput> throws. Whatever <computeroutput>T::operator = (const T&)</computeroutput> throws. </simpara></throws></method> 1764<method name="insert"><type>void</type><template> 1765 <template-type-parameter name="InputIterator"/> 1766 </template><parameter name="pos"><paramtype>iterator</paramtype><description><para>An iterator specifying the position where the range will be inserted. </para></description></parameter><parameter name="first"><paramtype>InputIterator</paramtype><description><para>The beginning of the range to be inserted. </para></description></parameter><parameter name="last"><paramtype>InputIterator</paramtype><description><para>The end of the range to be inserted. </para></description></parameter><purpose>Insert the range <computeroutput>[first, last)</computeroutput> at the specified position. </purpose><description><para> 1767 1768 1769 1770<formalpara><title>Exception Safety</title><para>Basic. </para> 1771</formalpara> 1772<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>). </para> 1773</formalpara> 1774<formalpara><title>Complexity</title><para>Linear (in <computeroutput>[size() + std::distance(first, last)]</computeroutput>; in <computeroutput>min[capacity().capacity(), size() + std::distance(first, last)]</computeroutput> if the <computeroutput>InputIterator</computeroutput> is a <ulink url="https://www.boost.org/sgi/stl/RandomAccessIterator.html">RandomAccessIterator</ulink>). </para> 1775</formalpara> 1776<formalpara><title>Example</title><para>Consider a <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> with the capacity of 6 and the size of 4. Its internal buffer may look like the one below.<sbr/> 1777<sbr/> 1778 <computeroutput>|1|2|3|4| | |</computeroutput><sbr/> 1779 <computeroutput>p ___^</computeroutput><sbr/> 1780<sbr/> 1781After inserting a range of elements at the position <computeroutput>p</computeroutput>:<sbr/> 1782<sbr/> 1783 <computeroutput>int array[] = { 5, 6, 7, 8, 9 };</computeroutput><sbr/> 1784<computeroutput>insert(p, array, array + 5);</computeroutput><sbr/> 1785<sbr/> 1786 actually only elements <computeroutput>6</computeroutput>, <computeroutput>7</computeroutput>, <computeroutput>8</computeroutput> and <computeroutput>9</computeroutput> from the specified range get inserted and elements <computeroutput>1</computeroutput> and <computeroutput>2</computeroutput> are overwritten. This is due to the fact the insert operation preserves the capacity. After insertion the internal buffer looks like this:<sbr/> 1787<sbr/> 1788<computeroutput>|6|7|8|9|3|4|</computeroutput><sbr/> 1789<sbr/> 1790For comparison if the capacity would not be preserved the internal buffer would then result in <computeroutput>|1|2|5|6|7|8|9|3|4|</computeroutput>. </para> 1791</formalpara> 1792<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>insert(iterator, value_type)</computeroutput>, <computeroutput>insert(iterator, size_type, value_type)</computeroutput>, <computeroutput>rinsert(iterator, value_type)</computeroutput>, <computeroutput>rinsert(iterator, size_type, value_type)</computeroutput>, <computeroutput>rinsert(iterator, InputIterator, InputIterator)</computeroutput> </para> 1793</para> 1794</para></description><requires><para><computeroutput>pos</computeroutput> is a valid iterator pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> or its end.<sbr/> 1795Valid range <computeroutput>[first, last)</computeroutput> where <computeroutput>first</computeroutput> and <computeroutput>last</computeroutput> meet the requirements of an <ulink url="https://www.boost.org/sgi/stl/InputIterator.html">InputIterator</ulink>. </para> 1796</requires><postconditions><para>Elements from the range <computeroutput>[first + max[0, distance(first, last) - (pos - begin()) - reserve()], last)</computeroutput> will be inserted at the position <computeroutput>pos</computeroutput>.<sbr/> 1797The number of <computeroutput>min[pos - begin(), max[0, distance(first, last) - reserve()]]</computeroutput> elements will be overwritten at the beginning of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput>.<sbr/> 1798(See <emphasis>Example</emphasis> for the explanation.)<sbr/> 1799<sbr/> 1800 The amount of allocated memory in the internal buffer may be predictively increased. </para> 1801</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T(const T&)</computeroutput> throws or nothing if <computeroutput>T::T(T&&)</computeroutput> is noexcept. </simpara></throws></method> 1802<method name="rinsert"><type>iterator</type><parameter name="pos"><paramtype>iterator</paramtype><description><para>An iterator specifying the position before which the <computeroutput>item</computeroutput> will be inserted. </para></description></parameter><parameter name="item"><paramtype>param_value_type</paramtype><description><para>The element to be inserted. </para></description></parameter><purpose>Insert an element before the specified position. </purpose><description><para> 1803 1804 1805 1806 1807<formalpara><title>Exception Safety</title><para>Basic. </para> 1808</formalpara> 1809<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>). </para> 1810</formalpara> 1811<formalpara><title>Complexity</title><para>Linear (in the size of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput>). </para> 1812</formalpara> 1813<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>rinsert(iterator, size_type, value_type)</computeroutput>, <computeroutput>rinsert(iterator, InputIterator, InputIterator)</computeroutput>, <computeroutput>insert(iterator, value_type)</computeroutput>, <computeroutput>insert(iterator, size_type, value_type)</computeroutput>, <computeroutput>insert(iterator, InputIterator, InputIterator)</computeroutput> </para> 1814</para> 1815</para></description><requires><para><computeroutput>pos</computeroutput> is a valid iterator pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> or its end. </para> 1816</requires><postconditions><para>The <computeroutput>item</computeroutput> will be inserted before the position <computeroutput>pos</computeroutput>.<sbr/> 1817 If the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> is full, the last element will be overwritten. If the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> is full and the <computeroutput>pos</computeroutput> points to <computeroutput>end()</computeroutput>, then the <computeroutput>item</computeroutput> will not be inserted. If the capacity is <computeroutput>0</computeroutput>, nothing will be inserted.<sbr/> 1818<sbr/> 1819 The amount of allocated memory in the internal buffer may be predictively increased. </para> 1820</postconditions><returns><para>Iterator to the inserted element or <computeroutput>end()</computeroutput> if the <computeroutput>item</computeroutput> is not inserted. (See the <emphasis>Effect</emphasis>.) </para> 1821</returns><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T(const T&)</computeroutput> throws. Whatever <computeroutput>T::operator = (const T&)</computeroutput> throws. </simpara></throws></method> 1822<method name="rinsert"><type>iterator</type><parameter name="pos"><paramtype>iterator</paramtype><description><para>An iterator specifying the position before which the <computeroutput>item</computeroutput> will be inserted. </para></description></parameter><parameter name="item"><paramtype>rvalue_type</paramtype><description><para>The element to be inserted. </para></description></parameter><purpose>Insert an element before the specified position. </purpose><description><para> 1823 1824 1825 1826 1827<formalpara><title>Exception Safety</title><para>Basic. </para> 1828</formalpara> 1829<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>). </para> 1830</formalpara> 1831<formalpara><title>Complexity</title><para>Linear (in the size of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput>). </para> 1832</formalpara> 1833<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>rinsert(iterator, size_type, value_type)</computeroutput>, <computeroutput>rinsert(iterator, InputIterator, InputIterator)</computeroutput>, <computeroutput>insert(iterator, value_type)</computeroutput>, <computeroutput>insert(iterator, size_type, value_type)</computeroutput>, <computeroutput>insert(iterator, InputIterator, InputIterator)</computeroutput> </para> 1834</para> 1835</para></description><requires><para><computeroutput>pos</computeroutput> is a valid iterator pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> or its end. </para> 1836</requires><postconditions><para>The <computeroutput>item</computeroutput> will be inserted before the position <computeroutput>pos</computeroutput>.<sbr/> 1837 If the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> is full, the last element will be overwritten. If the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> is full and the <computeroutput>pos</computeroutput> points to <computeroutput>end()</computeroutput>, then the <computeroutput>item</computeroutput> will not be inserted. If the capacity is <computeroutput>0</computeroutput>, nothing will be inserted.<sbr/> 1838<sbr/> 1839 The amount of allocated memory in the internal buffer may be predictively increased. </para> 1840</postconditions><returns><para>Iterator to the inserted element or <computeroutput>end()</computeroutput> if the <computeroutput>item</computeroutput> is not inserted. (See the <emphasis>Effect</emphasis>.) </para> 1841</returns><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T(const T&)</computeroutput> throws or nothing if <computeroutput>T::T(T&&)</computeroutput> is noexcept. </simpara></throws></method> 1842<method name="rinsert"><type>iterator</type><parameter name="pos"><paramtype>iterator</paramtype><description><para>An iterator specifying the position before which the <computeroutput>item</computeroutput> will be inserted. </para></description></parameter><purpose>Insert an element before the specified position. </purpose><description><para> 1843 1844 1845 1846 1847<formalpara><title>Exception Safety</title><para>Basic. </para> 1848</formalpara> 1849<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>). </para> 1850</formalpara> 1851<formalpara><title>Complexity</title><para>Linear (in the size of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput>). </para> 1852</formalpara> 1853<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>rinsert(iterator, size_type, value_type)</computeroutput>, <computeroutput>rinsert(iterator, InputIterator, InputIterator)</computeroutput>, <computeroutput>insert(iterator, value_type)</computeroutput>, <computeroutput>insert(iterator, size_type, value_type)</computeroutput>, <computeroutput>insert(iterator, InputIterator, InputIterator)</computeroutput> </para> 1854</para> 1855</para></description><requires><para><computeroutput>pos</computeroutput> is a valid iterator pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> or its end. </para> 1856</requires><postconditions><para>The <computeroutput>item</computeroutput> will be inserted before the position <computeroutput>pos</computeroutput>.<sbr/> 1857 If the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> is full, the last element will be overwritten. If the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> is full and the <computeroutput>pos</computeroutput> points to <computeroutput>end()</computeroutput>, then the <computeroutput>item</computeroutput> will not be inserted. If the capacity is <computeroutput>0</computeroutput>, nothing will be inserted.<sbr/> 1858<sbr/> 1859 The amount of allocated memory in the internal buffer may be predictively increased. </para> 1860</postconditions><returns><para>Iterator to the inserted element or <computeroutput>end()</computeroutput> if the <computeroutput>item</computeroutput> is not inserted. (See the <emphasis>Effect</emphasis>.) </para> 1861</returns><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T()</computeroutput> throws. Whatever <computeroutput>T::T(const T&)</computeroutput> throws or nothing if <computeroutput>T::T(T&&)</computeroutput> is noexcept. </simpara></throws></method> 1862<method name="rinsert"><type>void</type><parameter name="pos"><paramtype>iterator</paramtype><description><para>An iterator specifying the position where the <computeroutput>item</computeroutput>s will be inserted. </para></description></parameter><parameter name="n"><paramtype>size_type</paramtype><description><para>The number of <computeroutput>item</computeroutput>s the to be inserted. </para></description></parameter><parameter name="item"><paramtype>param_value_type</paramtype><description><para>The element whose copies will be inserted. </para></description></parameter><purpose>Insert <computeroutput>n</computeroutput> copies of the <computeroutput>item</computeroutput> before the specified position. </purpose><description><para> 1863 1864 1865 1866<formalpara><title>Exception Safety</title><para>Basic. </para> 1867</formalpara> 1868<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>). </para> 1869</formalpara> 1870<formalpara><title>Complexity</title><para>Linear (in <computeroutput>min[capacity().capacity(), size() + n]</computeroutput>). </para> 1871</formalpara> 1872<formalpara><title>Example</title><para>Consider a <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> with the capacity of 6 and the size of 4. Its internal buffer may look like the one below.<sbr/> 1873<sbr/> 1874 <computeroutput>|1|2|3|4| | |</computeroutput><sbr/> 1875 <computeroutput>p ___^</computeroutput><sbr/> 1876<sbr/> 1877After inserting 5 elements before the position <computeroutput>p</computeroutput>:<sbr/> 1878<sbr/> 1879 <computeroutput>rinsert(p, (size_t)5, 0);</computeroutput><sbr/> 1880<sbr/> 1881actually only 4 elements get inserted and elements <computeroutput>3</computeroutput> and <computeroutput>4</computeroutput> are overwritten. This is due to the fact the rinsert operation preserves the capacity. After insertion the internal buffer looks like this:<sbr/> 1882<sbr/> 1883<computeroutput>|1|2|0|0|0|0|</computeroutput><sbr/> 1884 <sbr/> 1885For comparison if the capacity would not be preserved the internal buffer would then result in <computeroutput>|1|2|0|0|0|0|0|3|4|</computeroutput>. </para> 1886</formalpara> 1887<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>rinsert(iterator, value_type)</computeroutput>, <computeroutput>rinsert(iterator, InputIterator, InputIterator)</computeroutput>, <computeroutput>insert(iterator, value_type)</computeroutput>, <computeroutput>insert(iterator, size_type, value_type)</computeroutput>, <computeroutput>insert(iterator, InputIterator, InputIterator)</computeroutput> </para> 1888</para> 1889</para></description><requires><para><computeroutput>pos</computeroutput> is a valid iterator pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> or its end. </para> 1890</requires><postconditions><para>The number of <computeroutput>min[n, (end() - pos) + reserve()]</computeroutput> elements will be inserted before the position <computeroutput>pos</computeroutput>.<sbr/> 1891The number of <computeroutput>min[end() - pos, max[0, n - reserve()]]</computeroutput> elements will be overwritten at the end of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput>.<sbr/> 1892(See <emphasis>Example</emphasis> for the explanation.)<sbr/> 1893<sbr/> 1894 The amount of allocated memory in the internal buffer may be predictively increased. </para> 1895</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T(const T&)</computeroutput> throws. Whatever <computeroutput>T::operator = (const T&)</computeroutput> throws. </simpara></throws></method> 1896<method name="rinsert"><type>void</type><template> 1897 <template-type-parameter name="InputIterator"/> 1898 </template><parameter name="pos"><paramtype>iterator</paramtype><description><para>An iterator specifying the position where the range will be inserted. </para></description></parameter><parameter name="first"><paramtype>InputIterator</paramtype><description><para>The beginning of the range to be inserted. </para></description></parameter><parameter name="last"><paramtype>InputIterator</paramtype><description><para>The end of the range to be inserted. </para></description></parameter><purpose>Insert the range <computeroutput>[first, last)</computeroutput> before the specified position. </purpose><description><para> 1899 1900 1901 1902<formalpara><title>Exception Safety</title><para>Basic. </para> 1903</formalpara> 1904<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>). </para> 1905</formalpara> 1906<formalpara><title>Complexity</title><para>Linear (in <computeroutput>[size() + std::distance(first, last)]</computeroutput>; in <computeroutput>min[capacity().capacity(), size() + std::distance(first, last)]</computeroutput> if the <computeroutput>InputIterator</computeroutput> is a <ulink url="https://www.boost.org/sgi/stl/RandomAccessIterator.html">RandomAccessIterator</ulink>). </para> 1907</formalpara> 1908<formalpara><title>Example</title><para>Consider a <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> with the capacity of 6 and the size of 4. Its internal buffer may look like the one below.<sbr/> 1909<sbr/> 1910 <computeroutput>|1|2|3|4| | |</computeroutput><sbr/> 1911 <computeroutput>p ___^</computeroutput><sbr/> 1912<sbr/> 1913After inserting a range of elements before the position <computeroutput>p</computeroutput>:<sbr/> 1914<sbr/> 1915 <computeroutput>int array[] = { 5, 6, 7, 8, 9 };</computeroutput><sbr/> 1916<computeroutput>insert(p, array, array + 5);</computeroutput><sbr/> 1917<sbr/> 1918 actually only elements <computeroutput>5</computeroutput>, <computeroutput>6</computeroutput>, <computeroutput>7</computeroutput> and <computeroutput>8</computeroutput> from the specified range get inserted and elements <computeroutput>3</computeroutput> and <computeroutput>4</computeroutput> are overwritten. This is due to the fact the rinsert operation preserves the capacity. After insertion the internal buffer looks like this:<sbr/> 1919<sbr/> 1920<computeroutput>|1|2|5|6|7|8|</computeroutput><sbr/> 1921<sbr/> 1922For comparison if the capacity would not be preserved the internal buffer would then result in <computeroutput>|1|2|5|6|7|8|9|3|4|</computeroutput>. </para> 1923</formalpara> 1924<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>rinsert(iterator, value_type)</computeroutput>, <computeroutput>rinsert(iterator, size_type, value_type)</computeroutput>, <computeroutput>insert(iterator, value_type)</computeroutput>, <computeroutput>insert(iterator, size_type, value_type)</computeroutput>, <computeroutput>insert(iterator, InputIterator, InputIterator)</computeroutput> </para> 1925</para> 1926</para></description><requires><para><computeroutput>pos</computeroutput> is a valid iterator pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> or its end.<sbr/> 1927 Valid range <computeroutput>[first, last)</computeroutput> where <computeroutput>first</computeroutput> and <computeroutput>last</computeroutput> meet the requirements of an <ulink url="https://www.boost.org/sgi/stl/InputIterator.html">InputIterator</ulink>. </para> 1928</requires><postconditions><para>Elements from the range <computeroutput>[first, last - max[0, distance(first, last) - (end() - pos) - reserve()])</computeroutput> will be inserted before the position <computeroutput>pos</computeroutput>.<sbr/> 1929The number of <computeroutput>min[end() - pos, max[0, distance(first, last) - reserve()]]</computeroutput> elements will be overwritten at the end of the <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>.<sbr/> 1930(See <emphasis>Example</emphasis> for the explanation.)<sbr/> 1931<sbr/> 1932 The amount of allocated memory in the internal buffer may be predictively increased. </para> 1933</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T(const T&)</computeroutput> throws. Whatever <computeroutput>T::operator = (const T&)</computeroutput> throws. </simpara></throws></method> 1934<method name="erase"><type>iterator</type><parameter name="pos"><paramtype>iterator</paramtype><description><para>An iterator pointing at the element to be removed. </para></description></parameter><purpose>Remove an element at the specified position. </purpose><description><para> 1935 1936 1937 1938 1939<formalpara><title>Exception Safety</title><para>Basic. </para> 1940</formalpara> 1941<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>). </para> 1942</formalpara> 1943<formalpara><title>Complexity</title><para>Linear (in the size of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput>). </para> 1944</formalpara> 1945<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>erase(iterator, iterator)</computeroutput>, <computeroutput>rerase(iterator)</computeroutput>, <computeroutput>rerase(iterator, iterator)</computeroutput>, <computeroutput>clear()</computeroutput> </para> 1946</para> 1947</para></description><requires><para><computeroutput>pos</computeroutput> is a valid iterator pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> (but not an <computeroutput>end()</computeroutput>). </para> 1948</requires><postconditions><para>The element at the position <computeroutput>pos</computeroutput> is removed.<sbr/> 1949<sbr/> 1950 The amount of allocated memory in the internal buffer may be predictively decreased. </para> 1951</postconditions><returns><para>Iterator to the first element remaining beyond the removed element or <computeroutput>end()</computeroutput> if no such element exists. </para> 1952</returns><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::operator = (const T&)</computeroutput> throws or nothing if <computeroutput>T::operator = (T&&)</computeroutput> is noexcept. </simpara></throws></method> 1953<method name="erase"><type>iterator</type><parameter name="first"><paramtype>iterator</paramtype><description><para>The beginning of the range to be removed. </para></description></parameter><parameter name="last"><paramtype>iterator</paramtype><description><para>The end of the range to be removed. </para></description></parameter><purpose>Erase the range <computeroutput>[first, last)</computeroutput>. </purpose><description><para> 1954 1955 1956 1957 1958<formalpara><title>Exception Safety</title><para>Basic. </para> 1959</formalpara> 1960<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>). </para> 1961</formalpara> 1962<formalpara><title>Complexity</title><para>Linear (in the size of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput>). </para> 1963</formalpara> 1964<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>erase(iterator)</computeroutput>, <computeroutput>rerase(iterator)</computeroutput>, <computeroutput>rerase(iterator, iterator)</computeroutput>, <computeroutput>clear()</computeroutput> </para> 1965</para> 1966</para></description><requires><para>Valid range <computeroutput>[first, last)</computeroutput>. </para> 1967</requires><postconditions><para>The elements from the range <computeroutput>[first, last)</computeroutput> are removed. (If <computeroutput>first == last</computeroutput> nothing is removed.)<sbr/> 1968<sbr/> 1969 The amount of allocated memory in the internal buffer may be predictively decreased. </para> 1970</postconditions><returns><para>Iterator to the first element remaining beyond the removed elements or <computeroutput>end()</computeroutput> if no such element exists. </para> 1971</returns><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::operator = (const T&)</computeroutput> throws or nothing if <computeroutput>T::operator = (T&&)</computeroutput> is noexcept. </simpara></throws></method> 1972<method name="rerase"><type>iterator</type><parameter name="pos"><paramtype>iterator</paramtype><description><para>An iterator pointing at the element to be removed. </para></description></parameter><purpose>Remove an element at the specified position. </purpose><description><para> 1973 1974 1975 1976 1977<formalpara><title>Exception Safety</title><para>Basic. </para> 1978</formalpara> 1979<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>). </para> 1980</formalpara> 1981<formalpara><title>Complexity</title><para>Linear (in the size of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput>). </para> 1982</formalpara> 1983<note><para>Basically there is no difference between <computeroutput>erase(iterator)</computeroutput> and this method. It is implemented only for consistency with the base <computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </para> 1984</note> 1985<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>erase(iterator)</computeroutput>, <computeroutput>erase(iterator, iterator)</computeroutput>, <computeroutput>rerase(iterator, iterator)</computeroutput>, <computeroutput>clear()</computeroutput> </para> 1986</para> 1987</para></description><requires><para><computeroutput>pos</computeroutput> is a valid iterator pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> (but not an <computeroutput>end()</computeroutput>).<sbr/> 1988<sbr/> 1989 The amount of allocated memory in the internal buffer may be predictively decreased. </para> 1990</requires><postconditions><para>The element at the position <computeroutput>pos</computeroutput> is removed. </para> 1991</postconditions><returns><para>Iterator to the first element remaining in front of the removed element or <computeroutput>begin()</computeroutput> if no such element exists. </para> 1992</returns><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::operator = (const T&)</computeroutput> throws or nothing if <computeroutput>T::operator = (T&&)</computeroutput> is noexcept. </simpara></throws></method> 1993<method name="rerase"><type>iterator</type><parameter name="first"><paramtype>iterator</paramtype><description><para>The beginning of the range to be removed. </para></description></parameter><parameter name="last"><paramtype>iterator</paramtype><description><para>The end of the range to be removed. </para></description></parameter><purpose>Erase the range <computeroutput>[first, last)</computeroutput>. </purpose><description><para> 1994 1995 1996 1997 1998<formalpara><title>Exception Safety</title><para>Basic. </para> 1999</formalpara> 2000<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>). </para> 2001</formalpara> 2002<formalpara><title>Complexity</title><para>Linear (in the size of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput>). </para> 2003</formalpara> 2004<note><para>Basically there is no difference between <computeroutput>erase(iterator, iterator)</computeroutput> and this method. It is implemented only for consistency with the base <computeroutput><<classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput>. </para> 2005</note> 2006<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>erase(iterator)</computeroutput>, <computeroutput>erase(iterator, iterator)</computeroutput>, <computeroutput>rerase(iterator)</computeroutput>, <computeroutput>clear()</computeroutput> </para> 2007</para> 2008</para></description><requires><para>Valid range <computeroutput>[first, last)</computeroutput>. </para> 2009</requires><postconditions><para>The elements from the range <computeroutput>[first, last)</computeroutput> are removed. (If <computeroutput>first == last</computeroutput> nothing is removed.)<sbr/> 2010<sbr/> 2011 The amount of allocated memory in the internal buffer may be predictively decreased. </para> 2012</postconditions><returns><para>Iterator to the first element remaining in front of the removed elements or <computeroutput>begin()</computeroutput> if no such element exists. </para> 2013</returns><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::operator = (const T&)</computeroutput> throws or nothing if <computeroutput>T::operator = (T&&)</computeroutput> is noexcept. </simpara></throws></method> 2014<method name="clear"><type>void</type><purpose>Remove all stored elements from the space optimized circular buffer. </purpose><description><para> 2015 2016<formalpara><title>Exception Safety</title><para>Basic. </para> 2017</formalpara> 2018<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>). </para> 2019</formalpara> 2020<formalpara><title>Complexity</title><para>Linear (in the size of the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput>). </para> 2021</formalpara> 2022<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>~circular_buffer_space_optimized()</computeroutput>, <computeroutput>erase(iterator)</computeroutput>, <computeroutput>erase(iterator, iterator)</computeroutput>, <computeroutput>rerase(iterator)</computeroutput>, <computeroutput>rerase(iterator, iterator)</computeroutput> </para> 2023</para> 2024</para></description><postconditions><para><computeroutput>size() == 0</computeroutput><sbr/> 2025<sbr/> 2026 The amount of allocated memory in the internal buffer may be predictively decreased. </para> 2027</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). </simpara></throws></method> 2028</method-group> 2029<constructor specifiers="explicit" cv="noexcept"><parameter name="alloc"><paramtype>const allocator_type &</paramtype><default>allocator_type()</default><description><para>The allocator. </para></description></parameter><purpose>Create an empty space optimized circular buffer with zero capacity. </purpose><description><para> 2030 2031 2032<formalpara><title>Complexity</title><para>Constant. </para> 2033</formalpara> 2034<warning><para>Since Boost version 1.36 the behaviour of this constructor has changed. Now it creates a space optimized circular buffer with zero capacity. </para> 2035</warning> 2036</para></description><postconditions><para><computeroutput>capacity().capacity() == 0 && capacity().min_capacity() == 0 && size() == 0</computeroutput> </para> 2037</postconditions><throws><simpara><classname>Nothing.</classname> </simpara></throws></constructor> 2038<constructor specifiers="explicit"><parameter name="capacity_ctrl"><paramtype>capacity_type</paramtype><description><para>The capacity controller representing the maximum number of elements which can be stored in the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> and the minimal allocated size of the internal buffer. </para></description></parameter><parameter name="alloc"><paramtype>const allocator_type &</paramtype><default>allocator_type()</default><description><para>The allocator. </para></description></parameter><purpose>Create an empty space optimized circular buffer with the specified capacity. </purpose><description><para> 2039 2040 2041<formalpara><title>Complexity</title><para>Constant. </para> 2042</formalpara> 2043</para></description><postconditions><para><computeroutput>capacity() == capacity_ctrl && size() == 0</computeroutput><sbr/> 2044<sbr/> 2045 The amount of allocated memory in the internal buffer is <computeroutput>capacity_ctrl.min_capacity()</computeroutput>. </para> 2046</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). </simpara></throws></constructor> 2047<constructor><parameter name="capacity_ctrl"><paramtype>capacity_type</paramtype><description><para>The capacity controller representing the maximum number of elements which can be stored in the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> and the minimal allocated size of the internal buffer. </para></description></parameter><parameter name="item"><paramtype>param_value_type</paramtype><description><para>The element the created <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> will be filled with. </para></description></parameter><parameter name="alloc"><paramtype>const allocator_type &</paramtype><default>allocator_type()</default><description><para>The allocator. </para></description></parameter><purpose>Create a full space optimized circular buffer with the specified capacity filled with <computeroutput>capacity_ctrl.capacity()</computeroutput> copies of <computeroutput>item</computeroutput>. </purpose><description><para> 2048 2049 2050<formalpara><title>Complexity</title><para>Linear (in the <computeroutput>capacity_ctrl.capacity()</computeroutput>). </para> 2051</formalpara> 2052</para></description><postconditions><para><computeroutput>capacity() == capacity_ctrl && full() && (*this)[0] == item && (*this)[1] == item && ... && (*this) [capacity_ctrl.capacity() - 1] == item </computeroutput><sbr/> 2053<sbr/> 2054 The amount of allocated memory in the internal buffer is <computeroutput>capacity_ctrl.capacity()</computeroutput>. </para> 2055</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). <computeroutput>T::T(const T&)</computeroutput> throws. </simpara></throws></constructor> 2056<constructor><parameter name="capacity_ctrl"><paramtype>capacity_type</paramtype><description><para>The capacity controller representing the maximum number of elements which can be stored in the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> and the minimal allocated size of the internal buffer. </para></description></parameter><parameter name="n"><paramtype>size_type</paramtype><description><para>The number of elements the created <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> will be filled with. </para></description></parameter><parameter name="item"><paramtype>param_value_type</paramtype><description><para>The element the created <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> will be filled with. </para></description></parameter><parameter name="alloc"><paramtype>const allocator_type &</paramtype><default>allocator_type()</default><description><para>The allocator. </para></description></parameter><purpose>Create a space optimized circular buffer with the specified capacity filled with <computeroutput>n</computeroutput> copies of <computeroutput>item</computeroutput>. </purpose><description><para> 2057 2058 2059 2060<formalpara><title>Complexity</title><para>Linear (in the <computeroutput>n</computeroutput>). </para> 2061</formalpara> 2062</para></description><requires><para><computeroutput>capacity_ctrl.capacity() >= n</computeroutput> </para> 2063</requires><postconditions><para><computeroutput>capacity() == capacity_ctrl && size() == n && (*this)[0] == item && (*this)[1] == item && ... && (*this)[n - 1] == item</computeroutput><sbr/> 2064<sbr/> 2065 The amount of allocated memory in the internal buffer is <computeroutput>max[n, capacity_ctrl.min_capacity()]</computeroutput>. </para> 2066</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T(const T&)</computeroutput> throws. </simpara></throws></constructor> 2067<constructor><parameter name="cb"><paramtype>const <classname>circular_buffer_space_optimized</classname>< T, Alloc > &</paramtype><description><para>The <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> to be copied. </para></description></parameter><purpose>The copy constructor. </purpose><description><para>Creates a copy of the specified <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput>. 2068 2069 2070<formalpara><title>Complexity</title><para>Linear (in the size of <computeroutput>cb</computeroutput>). </para> 2071</formalpara> 2072</para></description><postconditions><para><computeroutput>*this == cb</computeroutput><sbr/> 2073<sbr/> 2074 The amount of allocated memory in the internal buffer is <computeroutput>cb.size()</computeroutput>. </para> 2075</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T(const T&)</computeroutput> throws. </simpara></throws></constructor> 2076<constructor cv="noexcept"><parameter name="cb"><paramtype><classname>circular_buffer_space_optimized</classname>< T, Alloc > &&</paramtype><description><para><computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> to 'steal' value from. </para></description></parameter><purpose>The move constructor. </purpose><description><para>Move constructs a <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> from <computeroutput>cb</computeroutput>, leaving <computeroutput>cb</computeroutput> empty. 2077 2078 2079 2080<formalpara><title>Constant.</title><para/> 2081</formalpara> 2082</para></description><requires><para>C++ compiler with rvalue references support. </para> 2083</requires><postconditions><para><computeroutput>cb.empty()</computeroutput> </para> 2084</postconditions><throws><simpara><classname>Nothing.</classname> </simpara></throws></constructor> 2085<constructor><template> 2086 <template-type-parameter name="InputIterator"/> 2087 </template><parameter name="first"><paramtype>InputIterator</paramtype><description><para>The beginning of the range to be copied. </para></description></parameter><parameter name="last"><paramtype>InputIterator</paramtype><description><para>The end of the range to be copied. </para></description></parameter><parameter name="alloc"><paramtype>const allocator_type &</paramtype><default>allocator_type()</default><description><para>The allocator. </para></description></parameter><purpose>Create a full space optimized circular buffer filled with a copy of the range. </purpose><description><para> 2088 2089 2090 2091<formalpara><title>Complexity</title><para>Linear (in the <computeroutput>std::distance(first, last)</computeroutput>). </para> 2092</formalpara> 2093</para></description><requires><para>Valid range <computeroutput>[first, last)</computeroutput>.<sbr/> 2094 <computeroutput>first</computeroutput> and <computeroutput>last</computeroutput> have to meet the requirements of <ulink url="https://www.boost.org/sgi/stl/InputIterator.html">InputIterator</ulink>. </para> 2095</requires><postconditions><para><computeroutput>capacity().capacity() == std::distance(first, last) && capacity().min_capacity() == 0 && full() && (*this)[0]== *first && (*this)[1] == *(first + 1) && ... && (*this)[std::distance(first, last) - 1] == *(last - 1)</computeroutput><sbr/> 2096<sbr/> 2097 The amount of allocated memory in the internal buffer is <computeroutput>std::distance(first, last)</computeroutput>. </para> 2098</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T(const T&)</computeroutput> throws or nothing if <computeroutput>T::T(T&&)</computeroutput> is noexcept and <computeroutput>InputIterator</computeroutput> is a move iterator. </simpara></throws></constructor> 2099<constructor><template> 2100 <template-type-parameter name="InputIterator"/> 2101 </template><parameter name="capacity_ctrl"><paramtype>capacity_type</paramtype><description><para>The capacity controller representing the maximum number of elements which can be stored in the <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> and the minimal allocated size of the internal buffer. </para></description></parameter><parameter name="first"><paramtype>InputIterator</paramtype><description><para>The beginning of the range to be copied. </para></description></parameter><parameter name="last"><paramtype>InputIterator</paramtype><description><para>The end of the range to be copied. </para></description></parameter><parameter name="alloc"><paramtype>const allocator_type &</paramtype><default>allocator_type()</default><description><para>The allocator. </para></description></parameter><purpose>Create a space optimized circular buffer with the specified capacity (and the minimal guaranteed amount of allocated memory) filled with a copy of the range. </purpose><description><para> 2102 2103 2104 2105<formalpara><title>Complexity</title><para>Linear (in <computeroutput>std::distance(first, last)</computeroutput>; in <computeroutput>min[capacity_ctrl.capacity(), std::distance(first, last)]</computeroutput> if the <computeroutput>InputIterator</computeroutput> is a <ulink url="https://www.boost.org/sgi/stl/RandomAccessIterator.html">RandomAccessIterator</ulink>). </para> 2106</formalpara> 2107</para></description><requires><para>Valid range <computeroutput>[first, last)</computeroutput>.<sbr/> 2108 <computeroutput>first</computeroutput> and <computeroutput>last</computeroutput> have to meet the requirements of <ulink url="https://www.boost.org/sgi/stl/InputIterator.html">InputIterator</ulink>. </para> 2109</requires><postconditions><para><computeroutput>capacity() == capacity_ctrl && size() <= std::distance(first, last) && (*this)[0]== (last - capacity_ctrl.capacity()) && (*this)[1] == *(last - capacity_ctrl.capacity() + 1) && ... && (*this)[capacity_ctrl.capacity() - 1] == *(last - 1)</computeroutput><sbr/> 2110<sbr/> 2111 If the number of items to be copied from the range <computeroutput>[first, last)</computeroutput> is greater than the specified <computeroutput>capacity_ctrl.capacity()</computeroutput> then only elements from the range <computeroutput>[last - capacity_ctrl.capacity(), last)</computeroutput> will be copied.<sbr/> 2112<sbr/> 2113 The amount of allocated memory in the internal buffer is <computeroutput>max[capacity_ctrl.min_capacity(), min[capacity_ctrl.capacity(), std::distance(first, last)]]</computeroutput>. </para> 2114</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). Whatever <computeroutput>T::T(const T&)</computeroutput> throws. </simpara></throws></constructor> 2115<copy-assignment><type><classname>circular_buffer_space_optimized</classname>< T, Alloc > &</type><parameter name="cb"><paramtype>const <classname>circular_buffer_space_optimized</classname>< T, Alloc > &</paramtype><description><para>The <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> to be copied. </para></description></parameter><purpose>The assign operator. </purpose><description><para>Makes this <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> to become a copy of the specified <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput>. 2116 2117 2118<formalpara><title>Exception Safety</title><para>Strong. </para> 2119</formalpara> 2120<formalpara><title>Iterator Invalidation</title><para>Invalidates all iterators pointing to this <computeroutput><classname alt="boost::circular_buffer_space_optimized">circular_buffer_space_optimized</classname></computeroutput> (except iterators equal to <computeroutput>end()</computeroutput>). </para> 2121</formalpara> 2122<formalpara><title>Complexity</title><para>Linear (in the size of <computeroutput>cb</computeroutput>). </para> 2123</formalpara> 2124<para><emphasis role="bold">See Also:</emphasis><para><computeroutput>assign(size_type, const_reference)</computeroutput>, <computeroutput>assign(capacity_type, size_type, const_reference)</computeroutput>, <computeroutput>assign(InputIterator, InputIterator)</computeroutput>, <computeroutput>assign(capacity_type, InputIterator, InputIterator)</computeroutput> </para> 2125</para> 2126</para></description><postconditions><para><computeroutput>*this == cb</computeroutput><sbr/> 2127<sbr/> 2128 The amount of allocated memory in the internal buffer is <computeroutput>cb.size()</computeroutput>. </para> 2129</postconditions><throws><simpara><classname>An allocation error</classname> if memory is exhausted (<computeroutput>std::bad_alloc</computeroutput> if the standard allocator is used). <computeroutput>T::T(const T&)</computeroutput> throws. </simpara></throws></copy-assignment> 2130<copy-assignment cv="noexcept"><type><classname>circular_buffer_space_optimized</classname>< T, Alloc > &</type><parameter name="cb"><paramtype><classname>circular_buffer_space_optimized</classname>< T, Alloc > &&</paramtype><description><para><computeroutput><classname alt="boost::circular_buffer">circular_buffer</classname></computeroutput> to 'steal' value from. </para></description></parameter><purpose>Move assigns content of <computeroutput>cb</computeroutput> to <computeroutput>*this</computeroutput>, leaving <computeroutput>cb</computeroutput> empty. </purpose><description><para> 2131 2132 2133 2134<formalpara><title>Complexity</title><para>Constant. </para> 2135</formalpara> 2136</para></description><requires><para>C++ compiler with rvalue references support. </para> 2137</requires><postconditions><para><computeroutput>cb.empty()</computeroutput> </para> 2138</postconditions><throws><simpara><classname>Nothing.</classname> </simpara></throws></copy-assignment> 2139<method-group name="private static functions"> 2140</method-group> 2141</class> 2142 2143 2144 2145 2146 2147 2148<function name="operator=="><type>bool</type><template> 2149 <template-type-parameter name="T"/> 2150 <template-type-parameter name="Alloc"/> 2151 </template><parameter name="lhs"><paramtype>const <classname>circular_buffer_space_optimized</classname>< T, Alloc > &</paramtype></parameter><parameter name="rhs"><paramtype>const <classname>circular_buffer_space_optimized</classname>< T, Alloc > &</paramtype></parameter><purpose>Test two space optimized circular buffers for equality. </purpose></function> 2152<function name="operator<"><type>bool</type><template> 2153 <template-type-parameter name="T"/> 2154 <template-type-parameter name="Alloc"/> 2155 </template><parameter name="lhs"><paramtype>const <classname>circular_buffer_space_optimized</classname>< T, Alloc > &</paramtype></parameter><parameter name="rhs"><paramtype>const <classname>circular_buffer_space_optimized</classname>< T, Alloc > &</paramtype></parameter><purpose>Lexicographical comparison. </purpose></function> 2156<function name="operator!="><type>bool</type><template> 2157 <template-type-parameter name="T"/> 2158 <template-type-parameter name="Alloc"/> 2159 </template><parameter name="lhs"><paramtype>const <classname>circular_buffer_space_optimized</classname>< T, Alloc > &</paramtype></parameter><parameter name="rhs"><paramtype>const <classname>circular_buffer_space_optimized</classname>< T, Alloc > &</paramtype></parameter><purpose>Test two space optimized circular buffers for non-equality. </purpose></function> 2160<function name="operator>"><type>bool</type><template> 2161 <template-type-parameter name="T"/> 2162 <template-type-parameter name="Alloc"/> 2163 </template><parameter name="lhs"><paramtype>const <classname>circular_buffer_space_optimized</classname>< T, Alloc > &</paramtype></parameter><parameter name="rhs"><paramtype>const <classname>circular_buffer_space_optimized</classname>< T, Alloc > &</paramtype></parameter><purpose>Lexicographical comparison. </purpose></function> 2164<function name="operator<="><type>bool</type><template> 2165 <template-type-parameter name="T"/> 2166 <template-type-parameter name="Alloc"/> 2167 </template><parameter name="lhs"><paramtype>const <classname>circular_buffer_space_optimized</classname>< T, Alloc > &</paramtype></parameter><parameter name="rhs"><paramtype>const <classname>circular_buffer_space_optimized</classname>< T, Alloc > &</paramtype></parameter><purpose>Lexicographical comparison. </purpose></function> 2168<function name="operator>="><type>bool</type><template> 2169 <template-type-parameter name="T"/> 2170 <template-type-parameter name="Alloc"/> 2171 </template><parameter name="lhs"><paramtype>const <classname>circular_buffer_space_optimized</classname>< T, Alloc > &</paramtype></parameter><parameter name="rhs"><paramtype>const <classname>circular_buffer_space_optimized</classname>< T, Alloc > &</paramtype></parameter><purpose>Lexicographical comparison. </purpose></function> 2172<function name="swap"><type>void</type><template> 2173 <template-type-parameter name="T"/> 2174 <template-type-parameter name="Alloc"/> 2175 </template><parameter name="lhs"><paramtype><classname>circular_buffer_space_optimized</classname>< T, Alloc > &</paramtype></parameter><parameter name="rhs"><paramtype><classname>circular_buffer_space_optimized</classname>< T, Alloc > &</paramtype></parameter><purpose>Swap the contents of two space optimized circular buffers. </purpose></function> 2176</namespace> 2177</header> 2178</library-reference>