Boost.Sort

- Main Page
- Namespaces
- Classes
- Files

- File List
- File Members

integer_sort.hpp
Go to the documentation of this file.
1 //Templated Spreadsort-based implementation of integer_sort
2
3 // Copyright Steven J. Ross 2001 - 2014.
4 // Distributed under the Boost Software License, Version 1.0.
5 // (See accompanying file LICENSE_1_0.txt or copy at
6 // http://www.boost.org/LICENSE_1_0.txt)
7
8 // See http://www.boost.org/libs/sort/ for library home page.
9
10 /*
11 Some improvements suggested by:
12 Phil Endecott and Frank Gennari
13
14 Doxygen comments by Paul A. Bristow Jan 2015
15
16 */
17
18 #ifndef BOOST_INTEGER_SORT_HPP
19 #define BOOST_INTEGER_SORT_HPP
20 #include <algorithm>
21 #include <vector>
22 #include <cstring>
23 #include <limits>
24 #include <boost/static_assert.hpp>
25 #include <boost/sort/spreadsort/detail/constants.hpp>
26 #include <boost/sort/spreadsort/detail/integer_sort.hpp>
27
28 namespace boost {
29 namespace sort {
30 //Top-level sorting call for integers.
31
32
33 /*! \brief Integer sort algorithm using random access iterators.
34 (All variants fall back to @c std::sort if the data size is too small, < @c detail::min_sort_size).
35
36 \details @c integer_sort is a fast templated in-place hybrid radix/comparison algorithm,
37 which in testing tends to be roughly 50% to 2X faster than @c std::sort for large tests (>=100kB).\n
38 Worst-case performance is <em> O(N * (lg(range)/s + s)) </em>,
39 so @c integer_sort is asymptotically faster
40 than pure comparison-based algorithms. @c s is @c max_splits, which defaults to 11,
41 so its worst-case with default settings for 32-bit integers is
42 <em> O(N * ((32/11) </em> slow radix-based iterations fast comparison-based iterations).\n\n
43 Some performance plots of runtime vs. n and log(range) are provided:\n
44 <a href="../../doc/graph/windows_integer_sort.htm"> windows_integer_sort</a>
45 \n
46 <a href="../../doc/graph/osx_integer_sort.htm"> osx_integer_sort</a>
47
48
49 \tparam RandomAccessIter <a href="http://www.cplusplus.com/reference/iterator/RandomAccessIterator/">Random access iterator</a>
50 \param[in] first Iterator pointer to first element.
51 \param[in] last Iterator pointing to one beyond the end of data.
52
53 \pre [@c first, @c last) is a valid range.
54 \pre @c RandomAccessIter @c value_type is mutable.
55 \pre @c RandomAccessIter @c value_type is <a href="http://en.cppreference.com/w/cpp/concept/LessThanComparable">LessThanComparable</a>
56 \pre @c RandomAccessIter @c value_type supports the @c operator>>,
57 which returns an integer-type right-shifted a specified number of bits.
58 \post The elements in the range [@c first, @c last) are sorted in ascending order.
59
60 \throws std::exception Propagates exceptions if any of the element comparisons, the element swaps (or moves),
61 the right shift, subtraction of right-shifted elements, functors, or any operations on iterators throw.
62
63 \warning 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.
64 \warning Invalid arguments cause undefined behaviour.
65 \note @c spreadsort function provides a wrapper that calls the fastest sorting algorithm available for a data type,
66 enabling faster generic-programming.
67
68 \remark The lesser of <em> O(N*log(N)) </em> comparisons and <em> O(N*log(K/S + S)) </em>operations worst-case, where:
69 \remark * N is @c last - @c first,
70 \remark * K is the log of the range in bits (32 for 32-bit integers using their full range),
71 \remark * S is a constant called max_splits, defaulting to 11 (except for strings where it is the log of the character size).
72
73 */
74 template <class RandomAccessIter>
75 inline void integer_sort(RandomAccessIter first, RandomAccessIter last)
76 {
77 // Don't sort if it's too small to optimize.
78 if (last - first < detail::min_sort_size)
79 std::sort(first, last);
80 else
81 detail::integer_sort(first, last, *first >> 0);
82 }
83
84 /*! \brief Integer sort algorithm using random access iterators with both right-shift and user-defined comparison operator.
85 (All variants fall back to @c std::sort if the data size is too small, < @c detail::min_sort_size).
86
87 \details @c integer_sort is a fast templated in-place hybrid radix/comparison algorithm,
88 which in testing tends to be roughly 50% to 2X faster than @c std::sort for large tests (>=100kB).\n
89 Worst-case performance is <em> O(N * (lg(range)/s + s)) </em>,
90 so @c integer_sort is asymptotically faster
91 than pure comparison-based algorithms. @c s is @c max_splits, which defaults to 11,
92 so its worst-case with default settings for 32-bit integers is
93 <em> O(N * ((32/11) </em> slow radix-based iterations fast comparison-based iterations).\n\n
94 Some performance plots of runtime vs. n and log(range) are provided:\n
95 <a href="../../doc/graph/windows_integer_sort.htm"> windows_integer_sort</a>
96 \n
97 <a href="../../doc/graph/osx_integer_sort.htm"> osx_integer_sort</a>
98
99 \tparam RandomAccessIter <a href="http://www.cplusplus.com/reference/iterator/RandomAccessIterator/">Random access iterator</a>
100 \tparam Right_shift functor for right-shift by parameter @c shift bits.
101 \tparam Comp To provide @c operator< for user-defined comparison.
102
103 \param[in] first Iterator pointer to first element.
104 \param[in] last Iterator pointing to one beyond the end of data.
105 \param[in] shift Number of bits to right-shift (using functor).
106 \param[in] comp comparison functor.
107
108 \pre [@c first, @c last) is a valid range.
109 \pre @c RandomAccessIter @c value_type is mutable.
110 \pre @c RandomAccessIter @c value_type is <a href="http://en.cppreference.com/w/cpp/concept/LessThanComparable">LessThanComparable</a>
111 \pre @c RandomAccessIter @c value_type supports the @c operator>>,
112 which returns an integer-type right-shifted a specified number of bits.
113 \post The elements in the range [@c first, @c last) are sorted in ascending order.
114
115 \return @c void.
116
117 \throws std::exception Propagates exceptions if any of the element comparisons, the element swaps (or moves),
118 the right shift, subtraction of right-shifted elements, functors,
119 or any operations on iterators throw.
120
121 \warning 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.
122 \warning Invalid arguments cause undefined behaviour.
123 \note @c spreadsort function provides a wrapper that calls the fastest sorting algorithm available for a data type,
124 enabling faster generic-programming.
125
126 \remark The lesser of <em> O(N*log(N)) </em> comparisons and <em> O(N*log(K/S + S)) </em>operations worst-case, where:
127 \remark * N is @c last - @c first,
128 \remark * K is the log of the range in bits (32 for 32-bit integers using their full range),
129 \remark * S is a constant called max_splits, defaulting to 11 (except for strings where it is the log of the character size).
130 */
131 template <class RandomAccessIter, class Right_shift, class Compare>
132 inline void integer_sort(RandomAccessIter first, RandomAccessIter last,
133 Right_shift shift, Compare comp) {
134 if (last - first < detail::min_sort_size)
135 std::sort(first, last, comp);
136 else
137 detail::integer_sort(first, last, shift(*first, 0), shift, comp);
138 }
139
140 /*! \brief Integer sort algorithm using random access iterators with just right-shift functor.
141 (All variants fall back to @c std::sort if the data size is too small, < @c detail::min_sort_size).
142
143 \details @c integer_sort is a fast templated in-place hybrid radix/comparison algorithm,
144 which in testing tends to be roughly 50% to 2X faster than @c std::sort for large tests (>=100kB).\n
145
146 \par Performance:
147 Worst-case performance is <em> O(N * (lg(range)/s + s)) </em>,
148 so @c integer_sort is asymptotically faster
149 than pure comparison-based algorithms. @c s is @c max_splits, which defaults to 11,
150 so its worst-case with default settings for 32-bit integers is
151 <em> O(N * ((32/11) </em> slow radix-based iterations fast comparison-based iterations).\n\n
152 Some performance plots of runtime vs. n and log(range) are provided:\n
153 * <a href="../../doc/graph/windows_integer_sort.htm"> windows_integer_sort</a>\n
154 * <a href="../../doc/graph/osx_integer_sort.htm"> osx_integer_sort</a>
155
156 \tparam RandomAccessIter <a href="http://www.cplusplus.com/reference/iterator/RandomAccessIterator/">Random access iterator</a>
157 \tparam Right_shift functor for right-shift by parameter @c shift bits.
158
159 \param[in] first Iterator pointer to first element.
160 \param[in] last Iterator pointing to one beyond the end of data.
161 \param[in] shift Number of bits to right-shift (using functor).
162
163 \pre [@c first, @c last) is a valid range.
164 \pre @c RandomAccessIter @c value_type is mutable.
165 \pre @c RandomAccessIter @c value_type is <a href="http://en.cppreference.com/w/cpp/concept/LessThanComparable">LessThanComparable</a>
166 \pre @c RandomAccessIter @c value_type supports the @c operator>>,
167 which returns an integer-type right-shifted a specified number of bits.
168 \post The elements in the range [@c first, @c last) are sorted in ascending order.
169
170 \throws std::exception Propagates exceptions if any of the element comparisons, the element swaps (or moves),
171 the right shift, subtraction of right-shifted elements, functors,
172 or any operations on iterators throw.
173
174 \warning 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.
175 \warning Invalid arguments cause undefined behaviour.
176 \note @c spreadsort function provides a wrapper that calls the fastest sorting algorithm available for a data type,
177 enabling faster generic-programming.
178
179 \remark The lesser of <em> O(N*log(N)) </em> comparisons and <em> O(N*log(K/S + S)) </em>operations worst-case, where:
180 \remark * N is @c last - @c first,
181 \remark * K is the log of the range in bits (32 for 32-bit integers using their full range),
182 \remark * S is a constant called max_splits, defaulting to 11 (except for strings where it is the log of the character size).
183
184 */
185 template <class RandomAccessIter, class Right_shift>
186 inline void integer_sort(RandomAccessIter first, RandomAccessIter last,
187 Right_shift shift) {
188 if (last - first < detail::min_sort_size)
189 std::sort(first, last);
190 else
191 detail::integer_sort(first, last, shift(*first, 0), shift);
192 }
193 }
194 }
195
196 #endif
197
boost::sort::integer_sort
void integer_sort(RandomAccessIter first, RandomAccessIter last)
Integer sort algorithm using random access iterators. (All variants fall back to std::sort if the dat...
Definition: integer_sort.hpp:75
boost
Definition: float_sort.hpp:27
boost::sort::integer_sort
void integer_sort(RandomAccessIter first, RandomAccessIter last, Right_shift shift)
Integer sort algorithm using random access iterators with just right-shift functor. (All variants fall back to std::sort if the data size is too small, < detail::min_sort_size).
Definition: integer_sort.hpp:186