1<?xml version="1.0" standalone="yes"?> 2<library-reference id="boost_sort_c___reference"><title>Boost.Sort C++ Reference</title><header name="boost/sort/spreadsort/float_sort.hpp"> 3<namespace name="boost"> 4<namespace name="sort"> 5<namespace name="spreadsort"> 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31<function name="float_mem_cast"><type>Cast_type</type><template> 32 <template-type-parameter name="Data_type"><purpose><para>Floating-point IEEE 754/IEC559 type. </para></purpose></template-type-parameter> 33 <template-type-parameter name="Cast_type"><purpose><para>Integer type (same size) to which to cast.</para></purpose></template-type-parameter> 34 </template><parameter name="data"><paramtype>const Data_type &</paramtype></parameter><purpose>Casts a float to the specified integer type. </purpose><description><para> 35<formalpara><title>Example:</title><para><programlisting language="c++">struct rightshift { 36 int operator()(const DATA_TYPE &x, const unsigned offset) const { 37 return float_mem_cast<KEY_TYPE, CAST_TYPE>(x.key) >> offset; 38 } 39}; 40</programlisting> </para> 41</formalpara> 42</para></description></function> 43<function name="float_sort"><type>void</type><template> 44 <template-type-parameter name="RandomAccessIter"/> 45 </template><parameter name="first"><paramtype>RandomAccessIter</paramtype></parameter><parameter name="last"><paramtype>RandomAccessIter</paramtype></parameter><description><para>\brief @c float_sort with casting to the appropriate size. 46 47\param[in] first Iterator pointer to first element. 48\param[in] last Iterator pointing to one beyond the end of data. 49</para><para>Some performance plots of runtime vs. n and log(range) are provided:<sbr/> 50 <ulink url="../../doc/graph/windows_float_sort.htm">windows_float_sort</ulink> <sbr/> 51 <ulink url="../../doc/graph/osx_float_sort.htm">osx_float_sort</ulink></para><para><formalpara><title>A simple example of sorting some floating-point is:</title><para><programlisting language="c++">vector<float> vec; 52vec.push_back(1.0); 53vec.push_back(2.3); 54vec.push_back(1.3); 55spreadsort(vec.begin(), vec.end()); 56</programlisting> </para> 57</formalpara> 58<formalpara><title>The sorted vector contains ascending values "1.0 1.3 2.3".</title><para/> 59</formalpara> 60</para></description></function> 61<function name="float_sort"><type>void</type><template> 62 <template-type-parameter name="Range"/> 63 </template><parameter name="range"><paramtype>Range &</paramtype><description><para>Range [first, last) for sorting. </para></description></parameter><purpose>Floating-point sort algorithm using range. </purpose><description><para> 64</para></description></function> 65<function name="float_sort"><type>void</type><template> 66 <template-type-parameter name="RandomAccessIter"/> 67 <template-type-parameter name="Right_shift"/> 68 </template><parameter name="first"><paramtype>RandomAccessIter</paramtype><description><para>Iterator pointer to first element. </para></description></parameter><parameter name="last"><paramtype>RandomAccessIter</paramtype><description><para>Iterator pointing to one beyond the end of data. </para></description></parameter><parameter name="rshift"><paramtype>Right_shift</paramtype><description><para>Functor that returns the result of shifting the value_type right a specified number of bits. </para></description></parameter><purpose>Floating-point sort algorithm using random access iterators with just right-shift functor. </purpose><description><para> 69</para></description></function> 70<function name="float_sort"><type>void</type><template> 71 <template-type-parameter name="Range"/> 72 <template-type-parameter name="Right_shift"/> 73 </template><parameter name="range"><paramtype>Range &</paramtype><description><para>Range [first, last) for sorting. </para></description></parameter><parameter name="rshift"><paramtype>Right_shift</paramtype><description><para>Functor that returns the result of shifting the value_type right a specified number of bits. </para></description></parameter><purpose>Floating-point sort algorithm using range with just right-shift functor. </purpose><description><para> 74</para></description></function> 75<function name="float_sort"><type>void</type><template> 76 <template-type-parameter name="RandomAccessIter"/> 77 <template-type-parameter name="Right_shift"/> 78 <template-type-parameter name="Compare"/> 79 </template><parameter name="first"><paramtype>RandomAccessIter</paramtype><description><para>Iterator pointer to first element. </para></description></parameter><parameter name="last"><paramtype>RandomAccessIter</paramtype><description><para>Iterator pointing to one beyond the end of data. </para></description></parameter><parameter name="rshift"><paramtype>Right_shift</paramtype><description><para>Functor that returns the result of shifting the value_type right a specified number of bits. </para></description></parameter><parameter name="comp"><paramtype>Compare</paramtype><description><para>A binary functor that returns whether the first element passed to it should go before the second in order. </para></description></parameter><purpose>Float sort algorithm using random access iterators with both right-shift and user-defined comparison operator. </purpose><description><para> 80</para></description></function> 81<function name="float_sort"><type>void</type><template> 82 <template-type-parameter name="Range"/> 83 <template-type-parameter name="Right_shift"/> 84 <template-type-parameter name="Compare"/> 85 </template><parameter name="range"><paramtype>Range &</paramtype><description><para>Range [first, last) for sorting. </para></description></parameter><parameter name="rshift"><paramtype>Right_shift</paramtype><description><para>Functor that returns the result of shifting the value_type right a specified number of bits. </para></description></parameter><parameter name="comp"><paramtype>Compare</paramtype><description><para>A binary functor that returns whether the first element passed to it should go before the second in order. </para></description></parameter><purpose>Float sort algorithm using range with both right-shift and user-defined comparison operator. </purpose><description><para> 86</para></description></function> 87</namespace> 88</namespace> 89</namespace> 90</header> 91<header name="boost/sort/spreadsort/integer_sort.hpp"> 92<namespace name="boost"> 93<namespace name="sort"> 94<namespace name="spreadsort"> 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114<function name="integer_sort"><type>void</type><template> 115 <template-type-parameter name="RandomAccessIter"/> 116 </template><parameter name="first"><paramtype>RandomAccessIter</paramtype><description><para>Iterator pointer to first element. </para></description></parameter><parameter name="last"><paramtype>RandomAccessIter</paramtype><description><para>Iterator pointing to one beyond the end of data.</para></description></parameter><purpose>Integer sort algorithm using random access iterators. (All variants fall back to <computeroutput>boost::sort::pdqsort</computeroutput> if the data size is too small, < <computeroutput>detail::min_sort_size</computeroutput>). </purpose><description><para><computeroutput>integer_sort</computeroutput> is a fast templated in-place hybrid radix/comparison algorithm, which in testing tends to be roughly 50% to 2X faster than <computeroutput>std::sort</computeroutput> for large tests (>=100kB).<sbr/> 117Worst-case performance is <emphasis> O(N * (lg(range)/s + s)) </emphasis>, so <computeroutput>integer_sort</computeroutput> is asymptotically faster than pure comparison-based algorithms. <computeroutput>s</computeroutput> is <computeroutput>max_splits</computeroutput>, which defaults to 11, so its worst-case with default settings for 32-bit integers is <emphasis> O(N * ((32/11) </emphasis> slow radix-based iterations fast comparison-based iterations).<sbr/> 118<sbr/> 119Some performance plots of runtime vs. n and log(range) are provided:<sbr/> 120 <ulink url="../../doc/graph/windows_integer_sort.htm">windows_integer_sort</ulink> <sbr/> 121 <ulink url="../../doc/graph/osx_integer_sort.htm">osx_integer_sort</ulink></para><para> 122 123 124 125 126 127 128<warning><para>Throwing an exception may cause data loss. This will also throw if a small vector resize throws, in which case there will be no data loss. </para> 129</warning> 130<warning><para>Invalid arguments cause undefined behaviour. </para> 131</warning> 132<note><para><computeroutput>spreadsort</computeroutput> function provides a wrapper that calls the fastest sorting algorithm available for a data type, enabling faster generic-programming.</para> 133</note> 134<para>The lesser of <emphasis> O(N*log(N)) </emphasis> comparisons and <emphasis> O(N*log(K/S + S)) </emphasis>operations worst-case, where: </para> 135 136<para>* N is <computeroutput>last</computeroutput> - <computeroutput>first</computeroutput>, </para> 137 138<para>* K is the log of the range in bits (32 for 32-bit integers using their full range), </para> 139 140<para>* S is a constant called max_splits, defaulting to 11 (except for strings where it is the log of the character size). </para> 141 142</para></description><requires><para>[<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) is a valid range. </para> 143</requires><requires><para><computeroutput>RandomAccessIter</computeroutput> <computeroutput>value_type</computeroutput> is mutable. </para> 144</requires><requires><para><computeroutput>RandomAccessIter</computeroutput> <computeroutput>value_type</computeroutput> is <ulink url="http://en.cppreference.com/w/cpp/concept/LessThanComparable">LessThanComparable</ulink> </para> 145</requires><requires><para><computeroutput>RandomAccessIter</computeroutput> <computeroutput>value_type</computeroutput> supports the <computeroutput>operator>></computeroutput>, which returns an integer-type right-shifted a specified number of bits. </para> 146</requires><postconditions><para>The elements in the range [<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) are sorted in ascending order.</para> 147</postconditions><throws><simpara><classname>std::exception</classname> Propagates exceptions if any of the element comparisons, the element swaps (or moves), the right shift, subtraction of right-shifted elements, functors, or any operations on iterators throw.</simpara></throws></function> 148<function name="integer_sort"><type>void</type><template> 149 <template-type-parameter name="Range"/> 150 </template><parameter name="range"><paramtype>Range &</paramtype><description><para>Range [first, last) for sorting.</para></description></parameter><purpose>Integer sort algorithm using range. (All variants fall back to <computeroutput>boost::sort::pdqsort</computeroutput> if the data size is too small, < <computeroutput>detail::min_sort_size</computeroutput>). </purpose><description><para><computeroutput>integer_sort</computeroutput> is a fast templated in-place hybrid radix/comparison algorithm, which in testing tends to be roughly 50% to 2X faster than <computeroutput>std::sort</computeroutput> for large tests (>=100kB).<sbr/> 151Worst-case performance is <emphasis> O(N * (lg(range)/s + s)) </emphasis>, so <computeroutput>integer_sort</computeroutput> is asymptotically faster than pure comparison-based algorithms. <computeroutput>s</computeroutput> is <computeroutput>max_splits</computeroutput>, which defaults to 11, so its worst-case with default settings for 32-bit integers is <emphasis> O(N * ((32/11) </emphasis> slow radix-based iterations fast comparison-based iterations).<sbr/> 152<sbr/> 153Some performance plots of runtime vs. n and log(range) are provided:<sbr/> 154 <ulink url="../../doc/graph/windows_integer_sort.htm">windows_integer_sort</ulink> <sbr/> 155 <ulink url="../../doc/graph/osx_integer_sort.htm">osx_integer_sort</ulink></para><para> 156 157 158 159<warning><para>Throwing an exception may cause data loss. This will also throw if a small vector resize throws, in which case there will be no data loss. </para> 160</warning> 161<warning><para>Invalid arguments cause undefined behaviour. </para> 162</warning> 163<note><para><computeroutput>spreadsort</computeroutput> function provides a wrapper that calls the fastest sorting algorithm available for a data type, enabling faster generic-programming.</para> 164</note> 165<para>The lesser of <emphasis> O(N*log(N)) </emphasis> comparisons and <emphasis> O(N*log(K/S + S)) </emphasis>operations worst-case, where: </para> 166 167<para>* N is <computeroutput>last</computeroutput> - <computeroutput>first</computeroutput>, </para> 168 169<para>* K is the log of the range in bits (32 for 32-bit integers using their full range), </para> 170 171<para>* S is a constant called max_splits, defaulting to 11 (except for strings where it is the log of the character size). </para> 172 173</para></description><requires><para>[<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) is a valid range. </para> 174</requires><postconditions><para>The elements in the range [<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) are sorted in ascending order.</para> 175</postconditions><throws><simpara><classname>std::exception</classname> Propagates exceptions if any of the element comparisons, the element swaps (or moves), the right shift, subtraction of right-shifted elements, functors, or any operations on iterators throw.</simpara></throws></function> 176<function name="integer_sort"><type>void</type><template> 177 <template-type-parameter name="RandomAccessIter"/> 178 <template-type-parameter name="Right_shift"/> 179 <template-type-parameter name="Compare"/> 180 </template><parameter name="first"><paramtype>RandomAccessIter</paramtype><description><para>Iterator pointer to first element. </para></description></parameter><parameter name="last"><paramtype>RandomAccessIter</paramtype><description><para>Iterator pointing to one beyond the end of data. </para></description></parameter><parameter name="shift"><paramtype>Right_shift</paramtype><description><para>Functor that returns the result of shifting the value_type right a specified number of bits. </para></description></parameter><parameter name="comp"><paramtype>Compare</paramtype><description><para>A binary functor that returns whether the first element passed to it should go before the second in order.</para></description></parameter><purpose>Integer sort algorithm using random access iterators with both right-shift and user-defined comparison operator. (All variants fall back to <computeroutput>boost::sort::pdqsort</computeroutput> if the data size is too small, < <computeroutput>detail::min_sort_size</computeroutput>). </purpose><description><para><computeroutput>integer_sort</computeroutput> is a fast templated in-place hybrid radix/comparison algorithm, which in testing tends to be roughly 50% to 2X faster than <computeroutput>std::sort</computeroutput> for large tests (>=100kB).<sbr/> 181Worst-case performance is <emphasis> O(N * (lg(range)/s + s)) </emphasis>, so <computeroutput>integer_sort</computeroutput> is asymptotically faster than pure comparison-based algorithms. <computeroutput>s</computeroutput> is <computeroutput>max_splits</computeroutput>, which defaults to 11, so its worst-case with default settings for 32-bit integers is <emphasis> O(N * ((32/11) </emphasis> slow radix-based iterations fast comparison-based iterations).<sbr/> 182<sbr/> 183Some performance plots of runtime vs. n and log(range) are provided:<sbr/> 184 <ulink url="../../doc/graph/windows_integer_sort.htm">windows_integer_sort</ulink> <sbr/> 185 <ulink url="../../doc/graph/osx_integer_sort.htm">osx_integer_sort</ulink></para><para> 186 187 188 189 190 191<warning><para>Throwing an exception may cause data loss. This will also throw if a small vector resize throws, in which case there will be no data loss. </para> 192</warning> 193<warning><para>Invalid arguments cause undefined behaviour. </para> 194</warning> 195<note><para><computeroutput>spreadsort</computeroutput> function provides a wrapper that calls the fastest sorting algorithm available for a data type, enabling faster generic-programming.</para> 196</note> 197<para>The lesser of <emphasis> O(N*log(N)) </emphasis> comparisons and <emphasis> O(N*log(K/S + S)) </emphasis>operations worst-case, where: </para> 198 199<para>* N is <computeroutput>last</computeroutput> - <computeroutput>first</computeroutput>, </para> 200 201<para>* K is the log of the range in bits (32 for 32-bit integers using their full range), </para> 202 203<para>* S is a constant called max_splits, defaulting to 11 (except for strings where it is the log of the character size). </para> 204 205</para></description><requires><para>[<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) is a valid range. </para> 206</requires><requires><para><computeroutput>RandomAccessIter</computeroutput> <computeroutput>value_type</computeroutput> is mutable. </para> 207</requires><postconditions><para>The elements in the range [<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) are sorted in ascending order.</para> 208</postconditions><returns><para><computeroutput>void</computeroutput>.</para> 209</returns><throws><simpara><classname>std::exception</classname> Propagates exceptions if any of the element comparisons, the element swaps (or moves), the right shift, subtraction of right-shifted elements, functors, or any operations on iterators throw.</simpara></throws></function> 210<function name="integer_sort"><type>void</type><template> 211 <template-type-parameter name="Range"/> 212 <template-type-parameter name="Right_shift"/> 213 <template-type-parameter name="Compare"/> 214 </template><parameter name="range"><paramtype>Range &</paramtype><description><para>Range [first, last) for sorting. </para></description></parameter><parameter name="shift"><paramtype>Right_shift</paramtype><description><para>Functor that returns the result of shifting the value_type right a specified number of bits. </para></description></parameter><parameter name="comp"><paramtype>Compare</paramtype><description><para>A binary functor that returns whether the first element passed to it should go before the second in order.</para></description></parameter><purpose>Integer sort algorithm using range with both right-shift and user-defined comparison operator. (All variants fall back to <computeroutput>boost::sort::pdqsort</computeroutput> if the data size is too small, < <computeroutput>detail::min_sort_size</computeroutput>). </purpose><description><para><computeroutput>integer_sort</computeroutput> is a fast templated in-place hybrid radix/comparison algorithm, which in testing tends to be roughly 50% to 2X faster than <computeroutput>std::sort</computeroutput> for large tests (>=100kB).<sbr/> 215Worst-case performance is <emphasis> O(N * (lg(range)/s + s)) </emphasis>, so <computeroutput>integer_sort</computeroutput> is asymptotically faster than pure comparison-based algorithms. <computeroutput>s</computeroutput> is <computeroutput>max_splits</computeroutput>, which defaults to 11, so its worst-case with default settings for 32-bit integers is <emphasis> O(N * ((32/11) </emphasis> slow radix-based iterations fast comparison-based iterations).<sbr/> 216<sbr/> 217Some performance plots of runtime vs. n and log(range) are provided:<sbr/> 218 <ulink url="../../doc/graph/windows_integer_sort.htm">windows_integer_sort</ulink> <sbr/> 219 <ulink url="../../doc/graph/osx_integer_sort.htm">osx_integer_sort</ulink></para><para> 220 221 222 223 224<warning><para>Throwing an exception may cause data loss. This will also throw if a small vector resize throws, in which case there will be no data loss. </para> 225</warning> 226<warning><para>Invalid arguments cause undefined behaviour. </para> 227</warning> 228<note><para><computeroutput>spreadsort</computeroutput> function provides a wrapper that calls the fastest sorting algorithm available for a data type, enabling faster generic-programming.</para> 229</note> 230<para>The lesser of <emphasis> O(N*log(N)) </emphasis> comparisons and <emphasis> O(N*log(K/S + S)) </emphasis>operations worst-case, where: </para> 231 232<para>* N is <computeroutput>last</computeroutput> - <computeroutput>first</computeroutput>, </para> 233 234<para>* K is the log of the range in bits (32 for 32-bit integers using their full range), </para> 235 236<para>* S is a constant called max_splits, defaulting to 11 (except for strings where it is the log of the character size). </para> 237 238</para></description><requires><para>[<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) is a valid range. </para> 239</requires><postconditions><para>The elements in the range [<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) are sorted in ascending order.</para> 240</postconditions><returns><para><computeroutput>void</computeroutput>.</para> 241</returns><throws><simpara><classname>std::exception</classname> Propagates exceptions if any of the element comparisons, the element swaps (or moves), the right shift, subtraction of right-shifted elements, functors, or any operations on iterators throw.</simpara></throws></function> 242<function name="integer_sort"><type>void</type><template> 243 <template-type-parameter name="RandomAccessIter"/> 244 <template-type-parameter name="Right_shift"/> 245 </template><parameter name="first"><paramtype>RandomAccessIter</paramtype><description><para>Iterator pointer to first element. </para></description></parameter><parameter name="last"><paramtype>RandomAccessIter</paramtype><description><para>Iterator pointing to one beyond the end of data. </para></description></parameter><parameter name="shift"><paramtype>Right_shift</paramtype><description><para>A functor that returns the result of shifting the value_type right a specified number of bits.</para></description></parameter><purpose>Integer sort algorithm using random access iterators with just right-shift functor. (All variants fall back to <computeroutput>boost::sort::pdqsort</computeroutput> if the data size is too small, < <computeroutput>detail::min_sort_size</computeroutput>). </purpose><description><para><computeroutput>integer_sort</computeroutput> is a fast templated in-place hybrid radix/comparison algorithm, which in testing tends to be roughly 50% to 2X faster than <computeroutput>std::sort</computeroutput> for large tests (>=100kB).<sbr/> 246 <formalpara><title>Performance:</title><para>Worst-case performance is <emphasis> O(N * (lg(range)/s + s)) </emphasis>, so <computeroutput>integer_sort</computeroutput> is asymptotically faster than pure comparison-based algorithms. <computeroutput>s</computeroutput> is <computeroutput>max_splits</computeroutput>, which defaults to 11, so its worst-case with default settings for 32-bit integers is <emphasis> O(N * ((32/11) </emphasis> slow radix-based iterations fast comparison-based iterations).<sbr/> 247<sbr/> 248Some performance plots of runtime vs. n and log(range) are provided:<sbr/> 249 <ulink url="../../doc/graph/windows_integer_sort.htm">windows_integer_sort</ulink><sbr/> 250 <ulink url="../../doc/graph/osx_integer_sort.htm">osx_integer_sort</ulink></para> 251</formalpara> 252 253 254 255 256 257 258<warning><para>Throwing an exception may cause data loss. This will also throw if a small vector resize throws, in which case there will be no data loss. </para> 259</warning> 260<warning><para>Invalid arguments cause undefined behaviour. </para> 261</warning> 262<note><para><computeroutput>spreadsort</computeroutput> function provides a wrapper that calls the fastest sorting algorithm available for a data type, enabling faster generic-programming.</para> 263</note> 264<para>The lesser of <emphasis> O(N*log(N)) </emphasis> comparisons and <emphasis> O(N*log(K/S + S)) </emphasis>operations worst-case, where: </para> 265 266<para>* N is <computeroutput>last</computeroutput> - <computeroutput>first</computeroutput>, </para> 267 268<para>* K is the log of the range in bits (32 for 32-bit integers using their full range), </para> 269 270<para>* S is a constant called max_splits, defaulting to 11 (except for strings where it is the log of the character size). </para> 271 272</para></description><requires><para>[<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) is a valid range. </para> 273</requires><requires><para><computeroutput>RandomAccessIter</computeroutput> <computeroutput>value_type</computeroutput> is mutable. </para> 274</requires><requires><para><computeroutput>RandomAccessIter</computeroutput> <computeroutput>value_type</computeroutput> is <ulink url="http://en.cppreference.com/w/cpp/concept/LessThanComparable">LessThanComparable</ulink> </para> 275</requires><postconditions><para>The elements in the range [<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) are sorted in ascending order.</para> 276</postconditions><throws><simpara><classname>std::exception</classname> Propagates exceptions if any of the element comparisons, the element swaps (or moves), the right shift, subtraction of right-shifted elements, functors, or any operations on iterators throw.</simpara></throws></function> 277<function name="integer_sort"><type>void</type><template> 278 <template-type-parameter name="Range"/> 279 <template-type-parameter name="Right_shift"/> 280 </template><parameter name="range"><paramtype>Range &</paramtype><description><para>Range [first, last) for sorting. </para></description></parameter><parameter name="shift"><paramtype>Right_shift</paramtype><description><para>A functor that returns the result of shifting the value_type right a specified number of bits.</para></description></parameter><purpose>Integer sort algorithm using range with just right-shift functor. (All variants fall back to <computeroutput>boost::sort::pdqsort</computeroutput> if the data size is too small, < <computeroutput>detail::min_sort_size</computeroutput>). </purpose><description><para><computeroutput>integer_sort</computeroutput> is a fast templated in-place hybrid radix/comparison algorithm, which in testing tends to be roughly 50% to 2X faster than <computeroutput>std::sort</computeroutput> for large tests (>=100kB).<sbr/> 281 <formalpara><title>Performance:</title><para>Worst-case performance is <emphasis> O(N * (lg(range)/s + s)) </emphasis>, so <computeroutput>integer_sort</computeroutput> is asymptotically faster than pure comparison-based algorithms. <computeroutput>s</computeroutput> is <computeroutput>max_splits</computeroutput>, which defaults to 11, so its worst-case with default settings for 32-bit integers is <emphasis> O(N * ((32/11) </emphasis> slow radix-based iterations fast comparison-based iterations).<sbr/> 282<sbr/> 283Some performance plots of runtime vs. n and log(range) are provided:<sbr/> 284 <ulink url="../../doc/graph/windows_integer_sort.htm">windows_integer_sort</ulink><sbr/> 285 <ulink url="../../doc/graph/osx_integer_sort.htm">osx_integer_sort</ulink></para> 286</formalpara> 287 288 289 290 291<warning><para>Throwing an exception may cause data loss. This will also throw if a small vector resize throws, in which case there will be no data loss. </para> 292</warning> 293<warning><para>Invalid arguments cause undefined behaviour. </para> 294</warning> 295<note><para><computeroutput>spreadsort</computeroutput> function provides a wrapper that calls the fastest sorting algorithm available for a data type, enabling faster generic-programming.</para> 296</note> 297<para>The lesser of <emphasis> O(N*log(N)) </emphasis> comparisons and <emphasis> O(N*log(K/S + S)) </emphasis>operations worst-case, where: </para> 298 299<para>* N is <computeroutput>last</computeroutput> - <computeroutput>first</computeroutput>, </para> 300 301<para>* K is the log of the range in bits (32 for 32-bit integers using their full range), </para> 302 303<para>* S is a constant called max_splits, defaulting to 11 (except for strings where it is the log of the character size). </para> 304 305</para></description><requires><para>[<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) is a valid range. </para> 306</requires><postconditions><para>The elements in the range [<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) are sorted in ascending order.</para> 307</postconditions><throws><simpara><classname>std::exception</classname> Propagates exceptions if any of the element comparisons, the element swaps (or moves), the right shift, subtraction of right-shifted elements, functors, or any operations on iterators throw.</simpara></throws></function> 308 309 310 311 312 313 314 315</namespace> 316</namespace> 317</namespace> 318</header> 319<header name="boost/sort/spreadsort/spreadsort.hpp"> 320<namespace name="boost"> 321<namespace name="sort"> 322<namespace name="spreadsort"> 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337<function name="spreadsort"><type>boost::enable_if_c< std::numeric_limits< typename std::iterator_traits< RandomAccessIter >::value_type >::is_integer, void >::type</type><template> 338 <template-type-parameter name="RandomAccessIter"/> 339 </template><parameter name="first"><paramtype>RandomAccessIter</paramtype><description><para>Iterator pointer to first element. </para></description></parameter><parameter name="last"><paramtype>RandomAccessIter</paramtype><description><para>Iterator pointing to one beyond the end of data.</para></description></parameter><purpose>Generic <computeroutput>spreadsort</computeroutput> variant detecting integer-type elements so call to <computeroutput>integer_sort</computeroutput>. </purpose><description><para>If the data type provided is an integer, <computeroutput>integer_sort</computeroutput> is used. <note><para>Sorting other data types requires picking between <computeroutput>integer_sort</computeroutput>, <computeroutput>float_sort</computeroutput> and <computeroutput>string_sort</computeroutput> directly, as <computeroutput>spreadsort</computeroutput> won't accept types that don't have the appropriate <computeroutput>type_traits</computeroutput>. </para> 340</note> 341 342 343 344 345 346 347</para></description><requires><para>[<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) is a valid range. </para> 348</requires><requires><para><computeroutput>RandomAccessIter</computeroutput> <computeroutput>value_type</computeroutput> is mutable. </para> 349</requires><requires><para><computeroutput>RandomAccessIter</computeroutput> <computeroutput>value_type</computeroutput> is <ulink url="http://en.cppreference.com/w/cpp/concept/LessThanComparable">LessThanComparable</ulink> </para> 350</requires><requires><para><computeroutput>RandomAccessIter</computeroutput> <computeroutput>value_type</computeroutput> supports the <computeroutput>operator>></computeroutput>, which returns an integer-type right-shifted a specified number of bits. </para> 351</requires><postconditions><para>The elements in the range [<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) are sorted in ascending order. </para> 352</postconditions></function> 353<function name="spreadsort"><type>boost::enable_if_c< !std::numeric_limits< typename std::iterator_traits< RandomAccessIter >::value_type >::is_integer &&std::numeric_limits< typename std::iterator_traits< RandomAccessIter >::value_type >::is_iec559, void >::type</type><template> 354 <template-type-parameter name="RandomAccessIter"/> 355 </template><parameter name="first"><paramtype>RandomAccessIter</paramtype><description><para>Iterator pointer to first element. </para></description></parameter><parameter name="last"><paramtype>RandomAccessIter</paramtype><description><para>Iterator pointing to one beyond the end of data.</para></description></parameter><purpose>Generic <computeroutput>spreadsort</computeroutput> variant detecting float element type so call to <computeroutput>float_sort</computeroutput>. </purpose><description><para>If the data type provided is a float or castable-float, <computeroutput>float_sort</computeroutput> is used. <note><para>Sorting other data types requires picking between <computeroutput>integer_sort</computeroutput>, <computeroutput>float_sort</computeroutput> and <computeroutput>string_sort</computeroutput> directly, as <computeroutput>spreadsort</computeroutput> won't accept types that don't have the appropriate <computeroutput>type_traits</computeroutput>.</para> 356</note> 357 358 359 360 361 362 363</para></description><requires><para>[<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) is a valid range. </para> 364</requires><requires><para><computeroutput>RandomAccessIter</computeroutput> <computeroutput>value_type</computeroutput> is mutable. </para> 365</requires><requires><para><computeroutput>RandomAccessIter</computeroutput> <computeroutput>value_type</computeroutput> is <ulink url="http://en.cppreference.com/w/cpp/concept/LessThanComparable">LessThanComparable</ulink> </para> 366</requires><requires><para><computeroutput>RandomAccessIter</computeroutput> <computeroutput>value_type</computeroutput> supports the <computeroutput>operator>></computeroutput>, which returns an integer-type right-shifted a specified number of bits. </para> 367</requires><postconditions><para>The elements in the range [<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) are sorted in ascending order. </para> 368</postconditions></function> 369<function name="spreadsort"><type>boost::enable_if_c< is_same< typename std::iterator_traits< RandomAccessIter >::value_type, typename std::string >::value, void >::type</type><template> 370 <template-type-parameter name="RandomAccessIter"/> 371 </template><parameter name="first"><paramtype>RandomAccessIter</paramtype><description><para>Iterator pointer to first element. </para></description></parameter><parameter name="last"><paramtype>RandomAccessIter</paramtype><description><para>Iterator pointing to one beyond the end of data.</para></description></parameter><purpose>Generic <computeroutput>spreadsort</computeroutput> variant detecting string element type so call to <computeroutput>string_sort</computeroutput> for <computeroutput>std::strings</computeroutput>. </purpose><description><para>If the data type provided is a string, <computeroutput>string_sort</computeroutput> is used. <note><para>Sorting other data types requires picking between <computeroutput>integer_sort</computeroutput>, <computeroutput>float_sort</computeroutput> and <computeroutput>string_sort</computeroutput> directly, as <computeroutput>spreadsort</computeroutput> won't accept types that don't have the appropriate <computeroutput>type_traits</computeroutput>.</para> 372</note> 373 374 375 376 377 378 379</para></description><requires><para>[<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) is a valid range. </para> 380</requires><requires><para><computeroutput>RandomAccessIter</computeroutput> <computeroutput>value_type</computeroutput> is mutable. </para> 381</requires><requires><para><computeroutput>RandomAccessIter</computeroutput> <computeroutput>value_type</computeroutput> is <ulink url="http://en.cppreference.com/w/cpp/concept/LessThanComparable">LessThanComparable</ulink> </para> 382</requires><requires><para><computeroutput>RandomAccessIter</computeroutput> <computeroutput>value_type</computeroutput> supports the <computeroutput>operator>></computeroutput>, which returns an integer-type right-shifted a specified number of bits. </para> 383</requires><postconditions><para>The elements in the range [<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) are sorted in ascending order. </para> 384</postconditions></function> 385<function name="spreadsort"><type>boost::enable_if_c< is_same< typename std::iterator_traits< RandomAccessIter >::value_type, typename std::wstring >::value &&sizeof(wchar_t)==2, void >::type</type><template> 386 <template-type-parameter name="RandomAccessIter"/> 387 </template><parameter name="first"><paramtype>RandomAccessIter</paramtype><description><para>Iterator pointer to first element. </para></description></parameter><parameter name="last"><paramtype>RandomAccessIter</paramtype><description><para>Iterator pointing to one beyond the end of data.</para></description></parameter><purpose>Generic <computeroutput>spreadsort</computeroutput> variant detecting string element type so call to <computeroutput>string_sort</computeroutput> for <computeroutput>std::wstrings</computeroutput>. </purpose><description><para>If the data type provided is a wstring, <computeroutput>string_sort</computeroutput> is used. <note><para>Sorting other data types requires picking between <computeroutput>integer_sort</computeroutput>, <computeroutput>float_sort</computeroutput> and <computeroutput>string_sort</computeroutput> directly, as <computeroutput>spreadsort</computeroutput> won't accept types that don't have the appropriate <computeroutput>type_traits</computeroutput>. Also, 2-byte wide-characters are the limit above which string_sort is inefficient, so on platforms with wider characters, this will not accept wstrings.</para> 388</note> 389 390 391 392 393 394 395</para></description><requires><para>[<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) is a valid range. </para> 396</requires><requires><para><computeroutput>RandomAccessIter</computeroutput> <computeroutput>value_type</computeroutput> is mutable. </para> 397</requires><requires><para><computeroutput>RandomAccessIter</computeroutput> <computeroutput>value_type</computeroutput> is <ulink url="http://en.cppreference.com/w/cpp/concept/LessThanComparable">LessThanComparable</ulink> </para> 398</requires><requires><para><computeroutput>RandomAccessIter</computeroutput> <computeroutput>value_type</computeroutput> supports the <computeroutput>operator>></computeroutput>, which returns an integer-type right-shifted a specified number of bits. </para> 399</requires><postconditions><para>The elements in the range [<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) are sorted in ascending order. </para> 400</postconditions></function> 401<function name="spreadsort"><type>void</type><template> 402 <template-type-parameter name="Range"/> 403 </template><parameter name="range"><paramtype>Range &</paramtype><description><para>Range [first, last) for sorting.</para></description></parameter><purpose>Generic <computeroutput>spreadsort</computeroutput> variant detects value_type and calls required sort function. </purpose><description><para><note><para>Sorting other data types requires picking between <computeroutput>integer_sort</computeroutput>, <computeroutput>float_sort</computeroutput> and <computeroutput>string_sort</computeroutput> directly, as <computeroutput>spreadsort</computeroutput> won't accept types that don't have the appropriate <computeroutput>type_traits</computeroutput>.</para> 404</note> 405 406 407 408</para></description><requires><para>[<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) is a valid range. </para> 409</requires><postconditions><para>The elements in the range [<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) are sorted in ascending order. </para> 410</postconditions></function> 411 412 413 414 415 416 417 418 419 420 421 422 423 424</namespace> 425</namespace> 426</namespace> 427</header> 428<header name="boost/sort/spreadsort/string_sort.hpp"> 429<namespace name="boost"> 430<namespace name="sort"> 431<namespace name="spreadsort"> 432<function name="string_sort"><type>void</type><template> 433 <template-type-parameter name="RandomAccessIter"><purpose><para><ulink url="http://www.cplusplus.com/reference/iterator/RandomAccessIterator/">Random access iterator</ulink> </para></purpose></template-type-parameter> 434 <template-type-parameter name="Unsigned_char_type"><purpose><para>Unsigned character type used for string. </para></purpose></template-type-parameter> 435 </template><parameter name="first"><paramtype>RandomAccessIter</paramtype><description><para>Iterator pointer to first element. </para></description></parameter><parameter name="last"><paramtype>RandomAccessIter</paramtype><description><para>Iterator pointing to one beyond the end of data. </para></description></parameter><parameter name="unused"><paramtype>Unsigned_char_type</paramtype><description><para>value with the same type as the result of the [] operator, defining the Unsigned_char_type. The actual value is unused.</para></description></parameter><purpose>String sort algorithm using random access iterators, allowing character-type overloads.<sbr/> 436 (All variants fall back to <computeroutput>boost::sort::pdqsort</computeroutput> if the data size is too small, < <computeroutput>detail::min_sort_size</computeroutput>). </purpose><description><para><computeroutput>string_sort</computeroutput> is a fast templated in-place hybrid radix/comparison algorithm, which in testing tends to be roughly 50% to 2X faster than <computeroutput>std::sort</computeroutput> for large tests (>=100kB).<sbr/> 437<formalpara><title/><para>Worst-case performance is <emphasis> O(N * (lg(range)/s + s)) </emphasis>, so <computeroutput>string_sort</computeroutput> is asymptotically faster than pure comparison-based algorithms. <sbr/> 438<sbr/> 439Some performance plots of runtime vs. n and log(range) are provided:<sbr/> 440<ulink url="../../doc/graph/windows_string_sort.htm">windows_string_sort</ulink><sbr/> 441<ulink url="../../doc/graph/osx_string_sort.htm">osx_string_sort</ulink></para> 442</formalpara> 443 444 445 446 447 448 449 450 451<warning><para>Throwing an exception may cause data loss. This will also throw if a small vector resize throws, in which case there will be no data loss. </para> 452</warning> 453<warning><para>Invalid arguments cause undefined behaviour. </para> 454</warning> 455<note><para><computeroutput>spreadsort</computeroutput> function provides a wrapper that calls the fastest sorting algorithm available for a data type, enabling faster generic-programming.</para> 456</note> 457<para>The lesser of <emphasis> O(N*log(N)) </emphasis> comparisons and <emphasis> O(N*log(K/S + S)) </emphasis>operations worst-case, where: </para> 458 459<para>* N is <computeroutput>last</computeroutput> - <computeroutput>first</computeroutput>, </para> 460 461<para>* K is the log of the range in bits (32 for 32-bit integers using their full range), </para> 462 463<para>* S is a constant called max_splits, defaulting to 11 (except for strings where it is the log of the character size). </para> 464 465</para></description><requires><para>[<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) is a valid range. </para> 466</requires><requires><para><computeroutput>RandomAccessIter</computeroutput> <computeroutput>value_type</computeroutput> is mutable. </para> 467</requires><requires><para><computeroutput>RandomAccessIter</computeroutput> <computeroutput>value_type</computeroutput> is <ulink url="http://en.cppreference.com/w/cpp/concept/LessThanComparable">LessThanComparable</ulink> </para> 468</requires><requires><para><computeroutput>RandomAccessIter</computeroutput> <computeroutput>value_type</computeroutput> supports the <computeroutput>operator>></computeroutput>, which returns an integer-type right-shifted a specified number of bits. </para> 469</requires><postconditions><para>The elements in the range [<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) are sorted in ascending order.</para> 470</postconditions><throws><simpara><classname>std::exception</classname> Propagates exceptions if any of the element comparisons, the element swaps (or moves), the right shift, subtraction of right-shifted elements, functors, or any operations on iterators throw.</simpara></throws></function> 471<function name="string_sort"><type>void</type><template> 472 <template-type-parameter name="Range"/> 473 <template-type-parameter name="Unsigned_char_type"><purpose><para>Unsigned character type used for string. </para></purpose></template-type-parameter> 474 </template><parameter name="range"><paramtype>Range &</paramtype><description><para>Range [first, last) for sorting. </para></description></parameter><parameter name="unused"><paramtype>Unsigned_char_type</paramtype><description><para>value with the same type as the result of the [] operator, defining the Unsigned_char_type. The actual value is unused.</para></description></parameter><purpose>String sort algorithm using range, allowing character-type overloads.<sbr/> 475 (All variants fall back to <computeroutput>boost::sort::pdqsort</computeroutput> if the data size is too small, < <computeroutput>detail::min_sort_size</computeroutput>). </purpose><description><para><computeroutput>string_sort</computeroutput> is a fast templated in-place hybrid radix/comparison algorithm, which in testing tends to be roughly 50% to 2X faster than <computeroutput>std::sort</computeroutput> for large tests (>=100kB).<sbr/> 476<formalpara><title/><para>Worst-case performance is <emphasis> O(N * (lg(range)/s + s)) </emphasis>, so <computeroutput>string_sort</computeroutput> is asymptotically faster than pure comparison-based algorithms. <sbr/> 477<sbr/> 478Some performance plots of runtime vs. n and log(range) are provided:<sbr/> 479<ulink url="../../doc/graph/windows_string_sort.htm">windows_string_sort</ulink><sbr/> 480<ulink url="../../doc/graph/osx_string_sort.htm">osx_string_sort</ulink></para> 481</formalpara> 482 483 484 485 486 487<warning><para>Throwing an exception may cause data loss. This will also throw if a small vector resize throws, in which case there will be no data loss. </para> 488</warning> 489<warning><para>Invalid arguments cause undefined behaviour. </para> 490</warning> 491<note><para><computeroutput>spreadsort</computeroutput> function provides a wrapper that calls the fastest sorting algorithm available for a data type, enabling faster generic-programming.</para> 492</note> 493<para>The lesser of <emphasis> O(N*log(N)) </emphasis> comparisons and <emphasis> O(N*log(K/S + S)) </emphasis>operations worst-case, where: </para> 494 495<para>* N is <computeroutput>last</computeroutput> - <computeroutput>first</computeroutput>, </para> 496 497<para>* K is the log of the range in bits (32 for 32-bit integers using their full range), </para> 498 499<para>* S is a constant called max_splits, defaulting to 11 (except for strings where it is the log of the character size). </para> 500 501</para></description><requires><para>[<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) is a valid range. </para> 502</requires><postconditions><para>The elements in the range [<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) are sorted in ascending order.</para> 503</postconditions><throws><simpara><classname>std::exception</classname> Propagates exceptions if any of the element comparisons, the element swaps (or moves), the right shift, subtraction of right-shifted elements, functors, or any operations on iterators throw.</simpara></throws></function> 504<function name="string_sort"><type>void</type><template> 505 <template-type-parameter name="RandomAccessIter"/> 506 </template><parameter name="first"><paramtype>RandomAccessIter</paramtype><description><para>Iterator pointer to first element. </para></description></parameter><parameter name="last"><paramtype>RandomAccessIter</paramtype><description><para>Iterator pointing to one beyond the end of data.</para></description></parameter><purpose>String sort algorithm using random access iterators, wraps using default of unsigned char. (All variants fall back to <computeroutput>boost::sort::pdqsort</computeroutput> if the data size is too small, < <computeroutput>detail::min_sort_size</computeroutput>). </purpose><description><para><computeroutput>string_sort</computeroutput> is a fast templated in-place hybrid radix/comparison algorithm, which in testing tends to be roughly 50% to 2X faster than <computeroutput>std::sort</computeroutput> for large tests (>=100kB).<sbr/> 507Worst-case performance is <emphasis> O(N * (lg(range)/s + s)) </emphasis>, so <computeroutput>string_sort</computeroutput> is asymptotically faster than pure comparison-based algorithms. <sbr/> 508<sbr/> 509Some performance plots of runtime vs. n and log(range) are provided:<sbr/> 510 <ulink url="../../doc/graph/windows_string_sort.htm">windows_string_sort</ulink> <sbr/> 511 <ulink url="../../doc/graph/osx_string_sort.htm">osx_string_sort</ulink></para><para> 512 513 514 515 516 517 518<warning><para>Throwing an exception may cause data loss. This will also throw if a small vector resize throws, in which case there will be no data loss. </para> 519</warning> 520<warning><para>Invalid arguments cause undefined behaviour. </para> 521</warning> 522<note><para><computeroutput>spreadsort</computeroutput> function provides a wrapper that calls the fastest sorting algorithm available for a data type, enabling faster generic-programming.</para> 523</note> 524<para>The lesser of <emphasis> O(N*log(N)) </emphasis> comparisons and <emphasis> O(N*log(K/S + S)) </emphasis>operations worst-case, where: </para> 525 526<para>* N is <computeroutput>last</computeroutput> - <computeroutput>first</computeroutput>, </para> 527 528<para>* K is the log of the range in bits (32 for 32-bit integers using their full range), </para> 529 530<para>* S is a constant called max_splits, defaulting to 11 (except for strings where it is the log of the character size). </para> 531 532</para></description><requires><para>[<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) is a valid range. </para> 533</requires><requires><para><computeroutput>RandomAccessIter</computeroutput> <computeroutput>value_type</computeroutput> is mutable. </para> 534</requires><requires><para><computeroutput>RandomAccessIter</computeroutput> <computeroutput>value_type</computeroutput> is <ulink url="http://en.cppreference.com/w/cpp/concept/LessThanComparable">LessThanComparable</ulink> </para> 535</requires><requires><para><computeroutput>RandomAccessIter</computeroutput> <computeroutput>value_type</computeroutput> supports the <computeroutput>operator>></computeroutput>, which returns an integer-type right-shifted a specified number of bits. </para> 536</requires><postconditions><para>The elements in the range [<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) are sorted in ascending order.</para> 537</postconditions><throws><simpara><classname>std::exception</classname> Propagates exceptions if any of the element comparisons, the element swaps (or moves), the right shift, subtraction of right-shifted elements, functors, or any operations on iterators throw.</simpara></throws></function> 538<function name="string_sort"><type>void</type><template> 539 <template-type-parameter name="Range"/> 540 </template><parameter name="range"><paramtype>Range &</paramtype><description><para>Range [first, last) for sorting.</para></description></parameter><purpose>String sort algorithm using range, wraps using default of unsigned char. (All variants fall back to <computeroutput>boost::sort::pdqsort</computeroutput> if the data size is too small, < <computeroutput>detail::min_sort_size</computeroutput>). </purpose><description><para><computeroutput>string_sort</computeroutput> is a fast templated in-place hybrid radix/comparison algorithm, which in testing tends to be roughly 50% to 2X faster than <computeroutput>std::sort</computeroutput> for large tests (>=100kB).<sbr/> 541Worst-case performance is <emphasis> O(N * (lg(range)/s + s)) </emphasis>, so <computeroutput>string_sort</computeroutput> is asymptotically faster than pure comparison-based algorithms. <sbr/> 542<sbr/> 543Some performance plots of runtime vs. n and log(range) are provided:<sbr/> 544 <ulink url="../../doc/graph/windows_string_sort.htm">windows_string_sort</ulink> <sbr/> 545 <ulink url="../../doc/graph/osx_string_sort.htm">osx_string_sort</ulink></para><para> 546 547 548 549<warning><para>Throwing an exception may cause data loss. This will also throw if a small vector resize throws, in which case there will be no data loss. </para> 550</warning> 551<warning><para>Invalid arguments cause undefined behaviour. </para> 552</warning> 553<note><para><computeroutput>spreadsort</computeroutput> function provides a wrapper that calls the fastest sorting algorithm available for a data type, enabling faster generic-programming.</para> 554</note> 555<para>The lesser of <emphasis> O(N*log(N)) </emphasis> comparisons and <emphasis> O(N*log(K/S + S)) </emphasis>operations worst-case, where: </para> 556 557<para>* N is <computeroutput>last</computeroutput> - <computeroutput>first</computeroutput>, </para> 558 559<para>* K is the log of the range in bits (32 for 32-bit integers using their full range), </para> 560 561<para>* S is a constant called max_splits, defaulting to 11 (except for strings where it is the log of the character size). </para> 562 563</para></description><requires><para>[<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) is a valid range. </para> 564</requires><postconditions><para>The elements in the range [<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) are sorted in ascending order.</para> 565</postconditions><throws><simpara><classname>std::exception</classname> Propagates exceptions if any of the element comparisons, the element swaps (or moves), the right shift, subtraction of right-shifted elements, functors, or any operations on iterators throw.</simpara></throws></function> 566<function name="reverse_string_sort"><type>void</type><template> 567 <template-type-parameter name="RandomAccessIter"><purpose><para><ulink url="http://www.cplusplus.com/reference/iterator/RandomAccessIterator/">Random access iterator</ulink> </para></purpose></template-type-parameter> 568 <template-type-parameter name="Compare"/> 569 <template-type-parameter name="Unsigned_char_type"><purpose><para>Unsigned character type used for string.</para></purpose></template-type-parameter> 570 </template><parameter name="first"><paramtype>RandomAccessIter</paramtype><description><para>Iterator pointer to first element. </para></description></parameter><parameter name="last"><paramtype>RandomAccessIter</paramtype><description><para>Iterator pointing to one beyond the end of data. </para></description></parameter><parameter name="comp"><paramtype>Compare</paramtype><description><para>A binary functor that returns whether the first element passed to it should go before the second in order. </para></description></parameter><parameter name="unused"><paramtype>Unsigned_char_type</paramtype><description><para>value with the same type as the result of the [] operator, defining the Unsigned_char_type. The actual value is unused.</para></description></parameter><purpose>String sort algorithm using random access iterators, allowing character-type overloads. </purpose><description><para>(All variants fall back to <computeroutput>boost::sort::pdqsort</computeroutput> if the data size is too small, < detail::min_sort_size).</para><para><computeroutput>string_sort</computeroutput> is a fast templated in-place hybrid radix/comparison algorithm, which in testing tends to be roughly 50% to 2X faster than <computeroutput>std::sort</computeroutput> for large tests (>=100kB).<sbr/> 571<formalpara><title/><para>Worst-case performance is <emphasis> O(N * (lg(range)/s + s)) </emphasis>, so <computeroutput>string_sort</computeroutput> is asymptotically faster than pure comparison-based algorithms. <sbr/> 572<sbr/> 573Some performance plots of runtime vs. n and log(range) are provided:<sbr/> 574<ulink url="../../doc/graph/windows_string_sort.htm">windows_string_sort</ulink><sbr/> 575<ulink url="../../doc/graph/osx_string_sort.htm">osx_string_sort</ulink></para> 576</formalpara> 577 578 579 580 581 582 583 584 585 586<warning><para>Throwing an exception may cause data loss. This will also throw if a small vector resize throws, in which case there will be no data loss. </para> 587</warning> 588<warning><para>Invalid arguments cause undefined behaviour. </para> 589</warning> 590<note><para><computeroutput>spreadsort</computeroutput> function provides a wrapper that calls the fastest sorting algorithm available for a data type, enabling faster generic-programming.</para> 591</note> 592<para>The lesser of <emphasis> O(N*log(N)) </emphasis> comparisons and <emphasis> O(N*log(K/S + S)) </emphasis>operations worst-case, where: </para> 593 594<para>* N is <computeroutput>last</computeroutput> - <computeroutput>first</computeroutput>, </para> 595 596<para>* K is the log of the range in bits (32 for 32-bit integers using their full range), </para> 597 598<para>* S is a constant called max_splits, defaulting to 11 (except for strings where it is the log of the character size). </para> 599 600</para></description><requires><para>[<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) is a valid range. </para> 601</requires><requires><para><computeroutput>RandomAccessIter</computeroutput> <computeroutput>value_type</computeroutput> is mutable. </para> 602</requires><requires><para><computeroutput>RandomAccessIter</computeroutput> <computeroutput>value_type</computeroutput> is <ulink url="http://en.cppreference.com/w/cpp/concept/LessThanComparable">LessThanComparable</ulink> </para> 603</requires><requires><para><computeroutput>RandomAccessIter</computeroutput> <computeroutput>value_type</computeroutput> supports the <computeroutput>operator>></computeroutput>, which returns an integer-type right-shifted a specified number of bits. </para> 604</requires><postconditions><para>The elements in the range [<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) are sorted in ascending order.</para> 605</postconditions><returns><para><computeroutput>void</computeroutput>.</para> 606</returns><throws><simpara><classname>std::exception</classname> Propagates exceptions if any of the element comparisons, the element swaps (or moves), the right shift, subtraction of right-shifted elements, functors, or any operations on iterators throw.</simpara></throws></function> 607<function name="reverse_string_sort"><type>void</type><template> 608 <template-type-parameter name="Range"/> 609 <template-type-parameter name="Compare"/> 610 <template-type-parameter name="Unsigned_char_type"><purpose><para>Unsigned character type used for string.</para></purpose></template-type-parameter> 611 </template><parameter name="range"><paramtype>Range &</paramtype><description><para>Range [first, last) for sorting. </para></description></parameter><parameter name="comp"><paramtype>Compare</paramtype><description><para>A binary functor that returns whether the first element passed to it should go before the second in order. </para></description></parameter><parameter name="unused"><paramtype>Unsigned_char_type</paramtype><description><para>value with the same type as the result of the [] operator, defining the Unsigned_char_type. The actual value is unused.</para></description></parameter><purpose>String sort algorithm using range, allowing character-type overloads. </purpose><description><para>(All variants fall back to <computeroutput>boost::sort::pdqsort</computeroutput> if the data size is too small, < detail::min_sort_size).</para><para><computeroutput>string_sort</computeroutput> is a fast templated in-place hybrid radix/comparison algorithm, which in testing tends to be roughly 50% to 2X faster than <computeroutput>std::sort</computeroutput> for large tests (>=100kB).<sbr/> 612Worst-case performance is <emphasis> O(N * (lg(range)/s + s)) </emphasis>, so <computeroutput>string_sort</computeroutput> is asymptotically faster than pure comparison-based algorithms. <sbr/> 613<sbr/> 614Some performance plots of runtime vs. n and log(range) are provided:<sbr/> 615 <ulink url="../../doc/graph/windows_integer_sort.htm">windows_integer_sort</ulink> <sbr/> 616 <ulink url="../../doc/graph/osx_integer_sort.htm">osx_integer_sort</ulink></para><para> 617 618 619 620 621 622<warning><para>Throwing an exception may cause data loss. This will also throw if a small vector resize throws, in which case there will be no data loss. </para> 623</warning> 624<warning><para>Invalid arguments cause undefined behaviour. </para> 625</warning> 626<note><para><computeroutput>spreadsort</computeroutput> function provides a wrapper that calls the fastest sorting algorithm available for a data type, enabling faster generic-programming.</para> 627</note> 628<para>The lesser of <emphasis> O(N*log(N)) </emphasis> comparisons and <emphasis> O(N*log(K/S + S)) </emphasis>operations worst-case, where: </para> 629 630<para>* N is <computeroutput>last</computeroutput> - <computeroutput>first</computeroutput>, </para> 631 632<para>* K is the log of the range in bits (32 for 32-bit integers using their full range), </para> 633 634<para>* S is a constant called max_splits, defaulting to 11 (except for strings where it is the log of the character size). </para> 635 636</para></description><requires><para>[<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) is a valid range. </para> 637</requires><postconditions><para>The elements in the range [<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) are sorted in ascending order.</para> 638</postconditions><returns><para><computeroutput>void</computeroutput>.</para> 639</returns><throws><simpara><classname>std::exception</classname> Propagates exceptions if any of the element comparisons, the element swaps (or moves), the right shift, subtraction of right-shifted elements, functors, or any operations on iterators throw.</simpara></throws></function> 640<function name="reverse_string_sort"><type>void</type><template> 641 <template-type-parameter name="RandomAccessIter"/> 642 <template-type-parameter name="Compare"/> 643 </template><parameter name="first"><paramtype>RandomAccessIter</paramtype><description><para>Iterator pointer to first element. </para></description></parameter><parameter name="last"><paramtype>RandomAccessIter</paramtype><description><para>Iterator pointing to one beyond the end of data. </para></description></parameter><parameter name="comp"><paramtype>Compare</paramtype><description><para>A binary functor that returns whether the first element passed to it should go before the second in order.</para></description></parameter><purpose>String sort algorithm using random access iterators, wraps using default of <computeroutput>unsigned</computeroutput> char. </purpose><description><para>(All variants fall back to <computeroutput>boost::sort::pdqsort</computeroutput> if the data size is too small, < <computeroutput>detail::min_sort_size</computeroutput>).</para><para><computeroutput>string_sort</computeroutput> is a fast templated in-place hybrid radix/comparison algorithm, which in testing tends to be roughly 50% to 2X faster than <computeroutput>std::sort</computeroutput> for large tests (>=100kB).<sbr/> 644<formalpara><title/><para>Worst-case performance is <emphasis> O(N * (lg(range)/s + s)) </emphasis>, so <computeroutput>string_sort</computeroutput> is asymptotically faster than pure comparison-based algorithms.<sbr/> 645<sbr/> 646Some performance plots of runtime vs. n and log(range) are provided:<sbr/> 647<ulink url="../../doc/graph/windows_string_sort.htm">windows_string_sort</ulink><sbr/> 648<ulink url="../../doc/graph/osx_string_sort.htm">osx_string_sort</ulink></para> 649</formalpara> 650 651 652 653 654 655 656 657 658<warning><para>Throwing an exception may cause data loss. This will also throw if a small vector resize throws, in which case there will be no data loss. </para> 659</warning> 660<warning><para>Invalid arguments cause undefined behaviour. </para> 661</warning> 662<note><para><computeroutput>spreadsort</computeroutput> function provides a wrapper that calls the fastest sorting algorithm available for a data type, enabling faster generic-programming.</para> 663</note> 664<para>The lesser of <emphasis> O(N*log(N)) </emphasis> comparisons and <emphasis> O(N*log(K/S + S)) </emphasis>operations worst-case, where: </para> 665 666<para>* N is <computeroutput>last</computeroutput> - <computeroutput>first</computeroutput>, </para> 667 668<para>* K is the log of the range in bits (32 for 32-bit integers using their full range), </para> 669 670<para>* S is a constant called max_splits, defaulting to 11 (except for strings where it is the log of the character size). </para> 671 672</para></description><requires><para>[<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) is a valid range. </para> 673</requires><requires><para><computeroutput>RandomAccessIter</computeroutput> <computeroutput>value_type</computeroutput> is mutable. </para> 674</requires><requires><para><computeroutput>RandomAccessIter</computeroutput> <computeroutput>value_type</computeroutput> is <ulink url="http://en.cppreference.com/w/cpp/concept/LessThanComparable">LessThanComparable</ulink> </para> 675</requires><requires><para><computeroutput>RandomAccessIter</computeroutput> <computeroutput>value_type</computeroutput> supports the <computeroutput>operator>></computeroutput>, which returns an integer-type right-shifted a specified number of bits. </para> 676</requires><postconditions><para>The elements in the range [<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) are sorted in ascending order.</para> 677</postconditions><returns><para><computeroutput>void</computeroutput>.</para> 678</returns><throws><simpara><classname>std::exception</classname> Propagates exceptions if any of the element comparisons, the element swaps (or moves), the right shift, subtraction of right-shifted elements, functors, or any operations on iterators throw.</simpara></throws></function> 679<function name="reverse_string_sort"><type>void</type><template> 680 <template-type-parameter name="Range"/> 681 <template-type-parameter name="Compare"/> 682 </template><parameter name="range"><paramtype>Range &</paramtype><description><para>Range [first, last) for sorting. </para></description></parameter><parameter name="comp"><paramtype>Compare</paramtype><description><para>A binary functor that returns whether the first element passed to it should go before the second in order.</para></description></parameter><purpose>String sort algorithm using range, wraps using default of <computeroutput>unsigned</computeroutput> char. </purpose><description><para>(All variants fall back to <computeroutput>boost::sort::pdqsort</computeroutput> if the data size is too small, < <computeroutput>detail::min_sort_size</computeroutput>).</para><para><computeroutput>string_sort</computeroutput> is a fast templated in-place hybrid radix/comparison algorithm, which in testing tends to be roughly 50% to 2X faster than <computeroutput>std::sort</computeroutput> for large tests (>=100kB).<sbr/> 683<formalpara><title/><para>Worst-case performance is <emphasis> O(N * (lg(range)/s + s)) </emphasis>, so <computeroutput>string_sort</computeroutput> is asymptotically faster than pure comparison-based algorithms. <sbr/> 684<sbr/> 685Some performance plots of runtime vs. n and log(range) are provided:<sbr/> 686<ulink url="../../doc/graph/windows_string_sort.htm">windows_string_sort</ulink><sbr/> 687<ulink url="../../doc/graph/osx_string_sort.htm">osx_string_sort</ulink></para> 688</formalpara> 689 690 691 692 693 694<warning><para>Throwing an exception may cause data loss. This will also throw if a small vector resize throws, in which case there will be no data loss. </para> 695</warning> 696<warning><para>Invalid arguments cause undefined behaviour. </para> 697</warning> 698<note><para><computeroutput>spreadsort</computeroutput> function provides a wrapper that calls the fastest sorting algorithm available for a data type, enabling faster generic-programming.</para> 699</note> 700<para>The lesser of <emphasis> O(N*log(N)) </emphasis> comparisons and <emphasis> O(N*log(K/S + S)) </emphasis>operations worst-case, where: </para> 701 702<para>* N is <computeroutput>last</computeroutput> - <computeroutput>first</computeroutput>, </para> 703 704<para>* K is the log of the range in bits (32 for 32-bit integers using their full range), </para> 705 706<para>* S is a constant called max_splits, defaulting to 11 (except for strings where it is the log of the character size). </para> 707 708</para></description><requires><para>[<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) is a valid range. </para> 709</requires><postconditions><para>The elements in the range [<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) are sorted in ascending order.</para> 710</postconditions><returns><para><computeroutput>void</computeroutput>.</para> 711</returns><throws><simpara><classname>std::exception</classname> Propagates exceptions if any of the element comparisons, the element swaps (or moves), the right shift, subtraction of right-shifted elements, functors, or any operations on iterators throw.</simpara></throws></function> 712<function name="string_sort"><type>void</type><template> 713 <template-type-parameter name="RandomAccessIter"/> 714 <template-type-parameter name="Get_char"/> 715 <template-type-parameter name="Get_length"/> 716 </template><parameter name="first"><paramtype>RandomAccessIter</paramtype><description><para>Iterator pointer to first element. </para></description></parameter><parameter name="last"><paramtype>RandomAccessIter</paramtype><description><para>Iterator pointing to one beyond the end of data. </para></description></parameter><parameter name="get_character"><paramtype>Get_char</paramtype><description><para>Bracket functor equivalent to <computeroutput>operator</computeroutput>[], taking a number corresponding to the character offset. </para></description></parameter><parameter name="length"><paramtype>Get_length</paramtype><description><para>Functor to get the length of the string in characters.</para></description></parameter><purpose>String sort algorithm using random access iterators, wraps using default of <computeroutput>unsigned</computeroutput> char. </purpose><description><para>(All variants fall back to <computeroutput>boost::sort::pdqsort</computeroutput> if the data size is too small, < <computeroutput>detail::min_sort_size</computeroutput>).</para><para><computeroutput>string_sort</computeroutput> is a fast templated in-place hybrid radix/comparison algorithm, which in testing tends to be roughly 50% to 2X faster than <computeroutput>std::sort</computeroutput> for large tests (>=100kB).<sbr/> 717<formalpara><title/><para>Worst-case performance is <emphasis> O(N * (lg(range)/s + s)) </emphasis>, so <computeroutput>string_sort</computeroutput> is asymptotically faster than pure comparison-based algorithms. <sbr/> 718<sbr/> 719Some performance plots of runtime vs. n and log(range) are provided:<sbr/> 720<ulink url="../../doc/graph/windows_string_sort.htm">windows_string_sort</ulink><sbr/> 721<ulink url="../../doc/graph/osx_string_sort.htm">osx_string_sort</ulink></para> 722</formalpara> 723 724 725 726 727 728 729 730 731<warning><para>Throwing an exception may cause data loss. This will also throw if a small vector resize throws, in which case there will be no data loss. </para> 732</warning> 733<warning><para>Invalid arguments cause undefined behaviour. </para> 734</warning> 735<note><para><computeroutput>spreadsort</computeroutput> function provides a wrapper that calls the fastest sorting algorithm available for a data type, enabling faster generic-programming.</para> 736</note> 737<para>The lesser of <emphasis> O(N*log(N)) </emphasis> comparisons and <emphasis> O(N*log(K/S + S)) </emphasis>operations worst-case, where: </para> 738 739<para>* N is <computeroutput>last</computeroutput> - <computeroutput>first</computeroutput>, </para> 740 741<para>* K is the log of the range in bits (32 for 32-bit integers using their full range), </para> 742 743<para>* S is a constant called max_splits, defaulting to 11 (except for strings where it is the log of the character size). </para> 744 745</para></description><requires><para>[<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) is a valid range. </para> 746</requires><requires><para><computeroutput>RandomAccessIter</computeroutput> <computeroutput>value_type</computeroutput> is mutable. </para> 747</requires><requires><para><computeroutput>RandomAccessIter</computeroutput> <computeroutput>value_type</computeroutput> is <ulink url="http://en.cppreference.com/w/cpp/concept/LessThanComparable">LessThanComparable</ulink> </para> 748</requires><requires><para><computeroutput>RandomAccessIter</computeroutput> <computeroutput>value_type</computeroutput> supports the <computeroutput>operator>></computeroutput>, which returns an integer-type right-shifted a specified number of bits. </para> 749</requires><postconditions><para>The elements in the range [<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) are sorted in ascending order.</para> 750</postconditions><returns><para><computeroutput>void</computeroutput>.</para> 751</returns><throws><simpara><classname>std::exception</classname> Propagates exceptions if any of the element comparisons, the element swaps (or moves), the right shift, subtraction of right-shifted elements, functors, or any operations on iterators throw.</simpara></throws></function> 752<function name="string_sort"><type>void</type><template> 753 <template-type-parameter name="Range"/> 754 <template-type-parameter name="Get_char"/> 755 <template-type-parameter name="Get_length"/> 756 </template><parameter name="range"><paramtype>Range &</paramtype><description><para>Range [first, last) for sorting. </para></description></parameter><parameter name="get_character"><paramtype>Get_char</paramtype><description><para>Bracket functor equivalent to <computeroutput>operator</computeroutput>[], taking a number corresponding to the character offset. </para></description></parameter><parameter name="length"><paramtype>Get_length</paramtype><description><para>Functor to get the length of the string in characters.</para></description></parameter><purpose>String sort algorithm using range, wraps using default of <computeroutput>unsigned</computeroutput> char. </purpose><description><para>(All variants fall back to <computeroutput>boost::sort::pdqsort</computeroutput> if the data size is too small, < <computeroutput>detail::min_sort_size</computeroutput>).</para><para><computeroutput>string_sort</computeroutput> is a fast templated in-place hybrid radix/comparison algorithm, which in testing tends to be roughly 50% to 2X faster than <computeroutput>std::sort</computeroutput> for large tests (>=100kB).<sbr/> 757<formalpara><title/><para>Worst-case performance is <emphasis> O(N * (lg(range)/s + s)) </emphasis>, so <computeroutput>string_sort</computeroutput> is asymptotically faster than pure comparison-based algorithms. <sbr/> 758<sbr/> 759Some performance plots of runtime vs. n and log(range) are provided:<sbr/> 760<ulink url="../../doc/graph/windows_string_sort.htm">windows_string_sort</ulink><sbr/> 761<ulink url="../../doc/graph/osx_string_sort.htm">osx_string_sort</ulink></para> 762</formalpara> 763 764 765 766 767 768<warning><para>Throwing an exception may cause data loss. This will also throw if a small vector resize throws, in which case there will be no data loss. </para> 769</warning> 770<warning><para>Invalid arguments cause undefined behaviour. </para> 771</warning> 772<note><para><computeroutput>spreadsort</computeroutput> function provides a wrapper that calls the fastest sorting algorithm available for a data type, enabling faster generic-programming.</para> 773</note> 774<para>The lesser of <emphasis> O(N*log(N)) </emphasis> comparisons and <emphasis> O(N*log(K/S + S)) </emphasis>operations worst-case, where: </para> 775 776<para>* N is <computeroutput>last</computeroutput> - <computeroutput>first</computeroutput>, </para> 777 778<para>* K is the log of the range in bits (32 for 32-bit integers using their full range), </para> 779 780<para>* S is a constant called max_splits, defaulting to 11 (except for strings where it is the log of the character size). </para> 781 782</para></description><requires><para>[<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) is a valid range. </para> 783</requires><postconditions><para>The elements in the range [<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) are sorted in ascending order.</para> 784</postconditions><returns><para><computeroutput>void</computeroutput>.</para> 785</returns><throws><simpara><classname>std::exception</classname> Propagates exceptions if any of the element comparisons, the element swaps (or moves), the right shift, subtraction of right-shifted elements, functors, or any operations on iterators throw.</simpara></throws></function> 786<function name="string_sort"><type>void</type><template> 787 <template-type-parameter name="RandomAccessIter"/> 788 <template-type-parameter name="Get_char"/> 789 <template-type-parameter name="Get_length"/> 790 <template-type-parameter name="Compare"/> 791 </template><parameter name="first"><paramtype>RandomAccessIter</paramtype><description><para>Iterator pointer to first element. </para></description></parameter><parameter name="last"><paramtype>RandomAccessIter</paramtype><description><para>Iterator pointing to one beyond the end of data. </para></description></parameter><parameter name="get_character"><paramtype>Get_char</paramtype><description><para>Bracket functor equivalent to <computeroutput>operator</computeroutput>[], taking a number corresponding to the character offset. </para></description></parameter><parameter name="length"><paramtype>Get_length</paramtype><description><para>Functor to get the length of the string in characters. </para></description></parameter><parameter name="comp"><paramtype>Compare</paramtype><description><para>A binary functor that returns whether the first element passed to it should go before the second in order.</para></description></parameter><purpose>String sort algorithm using random access iterators, wraps using default of <computeroutput>unsigned</computeroutput> char. </purpose><description><para>(All variants fall back to <computeroutput>boost::sort::pdqsort</computeroutput> if the data size is too small, < <computeroutput>detail::min_sort_size</computeroutput>).</para><para><computeroutput>string_sort</computeroutput> is a fast templated in-place hybrid radix/comparison algorithm, which in testing tends to be roughly 50% to 2X faster than <computeroutput>std::sort</computeroutput> for large tests (>=100kB).<sbr/> 792<formalpara><title/><para>Worst-case performance is <emphasis> O(N * (lg(range)/s + s)) </emphasis>, so <computeroutput>string_sort</computeroutput> is asymptotically faster than pure comparison-based algorithms. <sbr/> 793<sbr/> 794Some performance plots of runtime vs. n and log(range) are provided:<sbr/> 795<ulink url="../../doc/graph/windows_string_sort.htm">windows_string_sort</ulink><sbr/> 796<ulink url="../../doc/graph/osx_string_sort.htm">osx_string_sort</ulink></para> 797</formalpara> 798 799 800 801 802 803 804 805<warning><para>Throwing an exception may cause data loss. This will also throw if a small vector resize throws, in which case there will be no data loss. </para> 806</warning> 807<warning><para>Invalid arguments cause undefined behaviour. </para> 808</warning> 809<note><para><computeroutput>spreadsort</computeroutput> function provides a wrapper that calls the fastest sorting algorithm available for a data type, enabling faster generic-programming.</para> 810</note> 811<para>The lesser of <emphasis> O(N*log(N)) </emphasis> comparisons and <emphasis> O(N*log(K/S + S)) </emphasis>operations worst-case, where: </para> 812 813<para>* N is <computeroutput>last</computeroutput> - <computeroutput>first</computeroutput>, </para> 814 815<para>* K is the log of the range in bits (32 for 32-bit integers using their full range), </para> 816 817<para>* S is a constant called max_splits, defaulting to 11 (except for strings where it is the log of the character size). </para> 818 819</para></description><requires><para>[<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) is a valid range. </para> 820</requires><requires><para><computeroutput>RandomAccessIter</computeroutput> <computeroutput>value_type</computeroutput> is mutable. </para> 821</requires><requires><para><computeroutput>RandomAccessIter</computeroutput> <computeroutput>value_type</computeroutput> is <ulink url="http://en.cppreference.com/w/cpp/concept/LessThanComparable">LessThanComparable</ulink> </para> 822</requires><postconditions><para>The elements in the range [<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) are sorted in ascending order.</para> 823</postconditions><returns><para><computeroutput>void</computeroutput>.</para> 824</returns><throws><simpara><classname>std::exception</classname> Propagates exceptions if any of the element comparisons, the element swaps (or moves), the right shift, subtraction of right-shifted elements, functors, or any operations on iterators throw.</simpara></throws></function> 825<function name="string_sort"><type>void</type><template> 826 <template-type-parameter name="Range"/> 827 <template-type-parameter name="Get_char"/> 828 <template-type-parameter name="Get_length"/> 829 <template-type-parameter name="Compare"/> 830 </template><parameter name="range"><paramtype>Range &</paramtype><description><para>Range [first, last) for sorting. </para></description></parameter><parameter name="get_character"><paramtype>Get_char</paramtype><description><para>Bracket functor equivalent to <computeroutput>operator</computeroutput>[], taking a number corresponding to the character offset. </para></description></parameter><parameter name="length"><paramtype>Get_length</paramtype><description><para>Functor to get the length of the string in characters. </para></description></parameter><parameter name="comp"><paramtype>Compare</paramtype><description><para>A binary functor that returns whether the first element passed to it should go before the second in order.</para></description></parameter><purpose>String sort algorithm using range, wraps using default of <computeroutput>unsigned</computeroutput> char. </purpose><description><para>(All variants fall back to <computeroutput>boost::sort::pdqsort</computeroutput> if the data size is too small, < <computeroutput>detail::min_sort_size</computeroutput>).</para><para><computeroutput>string_sort</computeroutput> is a fast templated in-place hybrid radix/comparison algorithm, which in testing tends to be roughly 50% to 2X faster than <computeroutput>std::sort</computeroutput> for large tests (>=100kB).<sbr/> 831<formalpara><title/><para>Worst-case performance is <emphasis> O(N * (lg(range)/s + s)) </emphasis>, so <computeroutput>string_sort</computeroutput> is asymptotically faster than pure comparison-based algorithms. <sbr/> 832<sbr/> 833Some performance plots of runtime vs. n and log(range) are provided:<sbr/> 834<ulink url="../../doc/graph/windows_string_sort.htm">windows_string_sort</ulink><sbr/> 835<ulink url="../../doc/graph/osx_string_sort.htm">osx_string_sort</ulink></para> 836</formalpara> 837 838 839 840 841 842<warning><para>Throwing an exception may cause data loss. This will also throw if a small vector resize throws, in which case there will be no data loss. </para> 843</warning> 844<warning><para>Invalid arguments cause undefined behaviour. </para> 845</warning> 846<note><para><computeroutput>spreadsort</computeroutput> function provides a wrapper that calls the fastest sorting algorithm available for a data type, enabling faster generic-programming.</para> 847</note> 848<para>The lesser of <emphasis> O(N*log(N)) </emphasis> comparisons and <emphasis> O(N*log(K/S + S)) </emphasis>operations worst-case, where: </para> 849 850<para>* N is <computeroutput>last</computeroutput> - <computeroutput>first</computeroutput>, </para> 851 852<para>* K is the log of the range in bits (32 for 32-bit integers using their full range), </para> 853 854<para>* S is a constant called max_splits, defaulting to 11 (except for strings where it is the log of the character size). </para> 855 856</para></description><requires><para>[<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) is a valid range. </para> 857</requires><postconditions><para>The elements in the range [<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) are sorted in ascending order.</para> 858</postconditions><returns><para><computeroutput>void</computeroutput>.</para> 859</returns><throws><simpara><classname>std::exception</classname> Propagates exceptions if any of the element comparisons, the element swaps (or moves), the right shift, subtraction of right-shifted elements, functors, or any operations on iterators throw.</simpara></throws></function> 860<function name="reverse_string_sort"><type>void</type><template> 861 <template-type-parameter name="RandomAccessIter"/> 862 <template-type-parameter name="Get_char"/> 863 <template-type-parameter name="Get_length"/> 864 <template-type-parameter name="Compare"/> 865 </template><parameter name="first"><paramtype>RandomAccessIter</paramtype><description><para>Iterator pointer to first element. </para></description></parameter><parameter name="last"><paramtype>RandomAccessIter</paramtype><description><para>Iterator pointing to one beyond the end of data. </para></description></parameter><parameter name="get_character"><paramtype>Get_char</paramtype><description><para>Bracket functor equivalent to <computeroutput>operator</computeroutput>[], taking a number corresponding to the character offset. </para></description></parameter><parameter name="length"><paramtype>Get_length</paramtype><description><para>Functor to get the length of the string in characters. </para></description></parameter><parameter name="comp"><paramtype>Compare</paramtype><description><para>A binary functor that returns whether the first element passed to it should go before the second in order.</para></description></parameter><purpose>Reverse String sort algorithm using random access iterators. </purpose><description><para>(All variants fall back to <computeroutput>boost::sort::pdqsort</computeroutput> if the data size is too small, < <computeroutput>detail::min_sort_size</computeroutput>).</para><para><computeroutput>string_sort</computeroutput> is a fast templated in-place hybrid radix/comparison algorithm, which in testing tends to be roughly 50% to 2X faster than <computeroutput>std::sort</computeroutput> for large tests (>=100kB).<sbr/> 866<formalpara><title/><para>Worst-case performance is <emphasis> O(N * (lg(range)/s + s)) </emphasis>, so <computeroutput>string_sort</computeroutput> is asymptotically faster than pure comparison-based algorithms. <sbr/> 867<sbr/> 868Some performance plots of runtime vs. n and log(range) are provided:<sbr/> 869<ulink url="../../doc/graph/windows_string_sort.htm">windows_string_sort</ulink><sbr/> 870<ulink url="../../doc/graph/osx_string_sort.htm">osx_string_sort</ulink></para> 871</formalpara> 872 873 874 875 876 877 878 879<warning><para>Throwing an exception may cause data loss. This will also throw if a small vector resize throws, in which case there will be no data loss. </para> 880</warning> 881<warning><para>Invalid arguments cause undefined behaviour. </para> 882</warning> 883<note><para><computeroutput>spreadsort</computeroutput> function provides a wrapper that calls the fastest sorting algorithm available for a data type, enabling faster generic-programming.</para> 884</note> 885<para>The lesser of <emphasis> O(N*log(N)) </emphasis> comparisons and <emphasis> O(N*log(K/S + S)) </emphasis>operations worst-case, where: </para> 886 887<para>* N is <computeroutput>last</computeroutput> - <computeroutput>first</computeroutput>, </para> 888 889<para>* K is the log of the range in bits (32 for 32-bit integers using their full range), </para> 890 891<para>* S is a constant called max_splits, defaulting to 11 (except for strings where it is the log of the character size). </para> 892 893</para></description><requires><para>[<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) is a valid range. </para> 894</requires><requires><para><computeroutput>RandomAccessIter</computeroutput> <computeroutput>value_type</computeroutput> is mutable. </para> 895</requires><requires><para><computeroutput>RandomAccessIter</computeroutput> <computeroutput>value_type</computeroutput> is <ulink url="http://en.cppreference.com/w/cpp/concept/LessThanComparable">LessThanComparable</ulink> </para> 896</requires><postconditions><para>The elements in the range [<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) are sorted in ascending order.</para> 897</postconditions><returns><para><computeroutput>void</computeroutput>.</para> 898</returns><throws><simpara><classname>std::exception</classname> Propagates exceptions if any of the element comparisons, the element swaps (or moves), the right shift, subtraction of right-shifted elements, functors, or any operations on iterators throw.</simpara></throws></function> 899<function name="reverse_string_sort"><type>void</type><template> 900 <template-type-parameter name="Range"/> 901 <template-type-parameter name="Get_char"/> 902 <template-type-parameter name="Get_length"/> 903 <template-type-parameter name="Compare"/> 904 </template><parameter name="range"><paramtype>Range &</paramtype><description><para>Range [first, last) for sorting. </para></description></parameter><parameter name="get_character"><paramtype>Get_char</paramtype><description><para>Bracket functor equivalent to <computeroutput>operator</computeroutput>[], taking a number corresponding to the character offset. </para></description></parameter><parameter name="length"><paramtype>Get_length</paramtype><description><para>Functor to get the length of the string in characters. </para></description></parameter><parameter name="comp"><paramtype>Compare</paramtype><description><para>A binary functor that returns whether the first element passed to it should go before the second in order.</para></description></parameter><purpose>Reverse String sort algorithm using range. </purpose><description><para>(All variants fall back to <computeroutput>boost::sort::pdqsort</computeroutput> if the data size is too small, < <computeroutput>detail::min_sort_size</computeroutput>).</para><para><computeroutput>string_sort</computeroutput> is a fast templated in-place hybrid radix/comparison algorithm, which in testing tends to be roughly 50% to 2X faster than <computeroutput>std::sort</computeroutput> for large tests (>=100kB).<sbr/> 905<formalpara><title/><para>Worst-case performance is <emphasis> O(N * (lg(range)/s + s)) </emphasis>, so <computeroutput>string_sort</computeroutput> is asymptotically faster than pure comparison-based algorithms. <sbr/> 906<sbr/> 907Some performance plots of runtime vs. n and log(range) are provided:<sbr/> 908<ulink url="../../doc/graph/windows_string_sort.htm">windows_string_sort</ulink><sbr/> 909<ulink url="../../doc/graph/osx_string_sort.htm">osx_string_sort</ulink></para> 910</formalpara> 911 912 913 914 915 916<warning><para>Throwing an exception may cause data loss. This will also throw if a small vector resize throws, in which case there will be no data loss. </para> 917</warning> 918<warning><para>Invalid arguments cause undefined behaviour. </para> 919</warning> 920<note><para><computeroutput>spreadsort</computeroutput> function provides a wrapper that calls the fastest sorting algorithm available for a data type, enabling faster generic-programming.</para> 921</note> 922<para>The lesser of <emphasis> O(N*log(N)) </emphasis> comparisons and <emphasis> O(N*log(K/S + S)) </emphasis>operations worst-case, where: </para> 923 924<para>* N is <computeroutput>last</computeroutput> - <computeroutput>first</computeroutput>, </para> 925 926<para>* K is the log of the range in bits (32 for 32-bit integers using their full range), </para> 927 928<para>* S is a constant called max_splits, defaulting to 11 (except for strings where it is the log of the character size). </para> 929 930</para></description><requires><para>[<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) is a valid range. </para> 931</requires><postconditions><para>The elements in the range [<computeroutput>first</computeroutput>, <computeroutput>last</computeroutput>) are sorted in ascending order.</para> 932</postconditions><returns><para><computeroutput>void</computeroutput>.</para> 933</returns><throws><simpara><classname>std::exception</classname> Propagates exceptions if any of the element comparisons, the element swaps (or moves), the right shift, subtraction of right-shifted elements, functors, or any operations on iterators throw.</simpara></throws></function> 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952</namespace> 953</namespace> 954</namespace> 955</header> 956</library-reference>