TimSort

include/boost/sort/spreadsort/float_sort.hpp

@@ -23,6 +23,8 @@ Scott McMurray
 #include <boost/static_assert.hpp>
 #include <boost/sort/spreadsort/detail/constants.hpp>
 #include <boost/sort/spreadsort/detail/float_sort.hpp>
+#include <boost/range/begin.hpp>
+#include <boost/range/end.hpp>
 
 namespace boost {
 namespace sort {
@@ -90,6 +92,18 @@ Some performance plots of runtime vs. n and log(range) are provided:\n
       detail::float_sort(first, last);
   }
 
+    /*!
+    \brief Floating-point sort algorithm using range.
+
+    \param[in] range Range [first, last) for sorting.
+
+  */
+  template <class Range>
+  inline void float_sort(Range& range)
+  {
+    float_sort(boost::begin(range), boost::end(range));
+  }
+
   /*!
     \brief Floating-point sort algorithm using random access iterators with just right-shift functor.
 
@@ -108,6 +122,19 @@ Some performance plots of runtime vs. n and log(range) are provided:\n
       detail::float_sort(first, last, rshift(*first, 0), rshift);
   }
 
+    /*!
+    \brief Floating-point sort algorithm using range with just right-shift functor.
+
+    \param[in] range Range [first, last) for sorting.
+    \param[in] rshift Functor that returns the result of shifting the value_type right a specified number of bits.
+
+  */
+  template <class Range, class Right_shift>
+  inline void float_sort(Range& range, Right_shift rshift)
+  {
+      float_sort(boost::begin(range), boost::end(range), rshift);
+  }
+
 
   /*!
    \brief Float sort algorithm using random access iterators with both right-shift and user-defined comparison operator.
@@ -127,6 +154,21 @@ Some performance plots of runtime vs. n and log(range) are provided:\n
     else
       detail::float_sort(first, last, rshift(*first, 0), rshift, comp);
   }
+
+
+    /*!
+   \brief Float sort algorithm using range with both right-shift and user-defined comparison operator.
+
+   \param[in] range Range [first, last) for sorting.
+   \param[in] rshift Functor that returns the result of shifting the value_type right a specified number of bits.
+   \param[in] comp A binary functor that returns whether the first element passed to it should go before the second in order.
+  */
+
+  template <class Range, class Right_shift, class Compare>
+  inline void float_sort(Range& range, Right_shift rshift, Compare comp)
+  {
+      float_sort(boost::begin(range), boost::end(range), rshift, comp);
+  }
 }
 }
 }

include/boost/sort/spreadsort/integer_sort.hpp

@@ -24,6 +24,8 @@ Doxygen comments by Paul A. Bristow Jan 2015
 #include <boost/static_assert.hpp>
 #include <boost/sort/spreadsort/detail/constants.hpp>
 #include <boost/sort/spreadsort/detail/integer_sort.hpp>
+#include <boost/range/begin.hpp>
+#include <boost/range/end.hpp>
 
 namespace boost {
 namespace sort {
@@ -80,6 +82,46 @@ Some performance plots of runtime vs. n and log(range) are provided:\n
       detail::integer_sort(first, last, *first >> 0);
   }
 
+/*! \brief Integer sort algorithm using range.
+  (All variants fall back to @c std::sort if the data size is too small, < @c detail::min_sort_size).
+
+  \details @c integer_sort is a fast templated in-place hybrid radix/comparison algorithm,
+which in testing tends to be roughly 50% to 2X faster than @c std::sort for large tests (>=100kB).\n
+Worst-case performance is <em>  O(N * (lg(range)/s + s)) </em>,
+so @c integer_sort is asymptotically faster
+than pure comparison-based algorithms. @c s is @c max_splits, which defaults to 11,
+so its worst-case with default settings for 32-bit integers is
+<em> O(N * ((32/11) </em> slow radix-based iterations fast comparison-based iterations).\n\n
+Some performance plots of runtime vs. n and log(range) are provided:\n
+   <a href="../../doc/graph/windows_integer_sort.htm"> windows_integer_sort</a>
+   \n
+   <a href="../../doc/graph/osx_integer_sort.htm"> osx_integer_sort</a>
+
+   \param[in] range Range [first, last) for sorting.
+
+   \pre [@c first, @c last) is a valid range.
+   \post The elements in the range [@c first, @c last) are sorted in ascending order.
+
+   \throws std::exception 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.
+
+   \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.
+   \warning Invalid arguments cause undefined behaviour.
+   \note @c spreadsort function provides a wrapper that calls the fastest sorting algorithm available for a data type,
+   enabling faster generic-programming.
+
+   \remark The lesser of <em> O(N*log(N)) </em> comparisons and <em> O(N*log(K/S + S)) </em>operations worst-case, where:
+   \remark  *  N is @c last - @c first,
+   \remark  *  K is the log of the range in bits (32 for 32-bit integers using their full range),
+   \remark  *  S is a constant called max_splits, defaulting to 11 (except for strings where it is the log of the character size).
+
+*/
+template <class Range>
+inline void integer_sort(Range& range)
+{
+  integer_sort(boost::begin(range), boost::end(range));
+}
+
 /*! \brief Integer sort algorithm using random access iterators with both right-shift and user-defined comparison operator.
   (All variants fall back to @c std::sort if the data size is too small, < @c detail::min_sort_size).
 
@@ -129,6 +171,50 @@ Some performance plots of runtime vs. n and log(range) are provided:\n
       detail::integer_sort(first, last, shift(*first, 0), shift, comp);
   }
 
+/*! \brief Integer sort algorithm using range with both right-shift and user-defined comparison operator.
+  (All variants fall back to @c std::sort if the data size is too small, < @c detail::min_sort_size).
+
+  \details @c integer_sort is a fast templated in-place hybrid radix/comparison algorithm,
+which in testing tends to be roughly 50% to 2X faster than @c std::sort for large tests (>=100kB).\n
+Worst-case performance is <em>  O(N * (lg(range)/s + s)) </em>,
+so @c integer_sort is asymptotically faster
+than pure comparison-based algorithms. @c s is @c max_splits, which defaults to 11,
+so its worst-case with default settings for 32-bit integers is
+<em> O(N * ((32/11) </em> slow radix-based iterations fast comparison-based iterations).\n\n
+Some performance plots of runtime vs. n and log(range) are provided:\n
+   <a href="../../doc/graph/windows_integer_sort.htm"> windows_integer_sort</a>
+   \n
+   <a href="../../doc/graph/osx_integer_sort.htm"> osx_integer_sort</a>
+
+   \param[in] range Range [first, last) for sorting.
+   \param[in] shift Functor that returns the result of shifting the value_type right a specified number of bits.
+   \param[in] comp A binary functor that returns whether the first element passed to it should go before the second in order.
+
+   \pre [@c first, @c last) is a valid range.
+   \post The elements in the range [@c first, @c last) are sorted in ascending order.
+
+   \return @c void.
+
+   \throws std::exception 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.
+
+   \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.
+   \warning Invalid arguments cause undefined behaviour.
+   \note @c spreadsort function provides a wrapper that calls the fastest sorting algorithm available for a data type,
+   enabling faster generic-programming.
+
+   \remark The lesser of <em> O(N*log(N)) </em> comparisons and <em> O(N*log(K/S + S)) </em>operations worst-case, where:
+   \remark  *  N is @c last - @c first,
+   \remark  *  K is the log of the range in bits (32 for 32-bit integers using their full range),
+   \remark  *  S is a constant called max_splits, defaulting to 11 (except for strings where it is the log of the character size).
+*/
+template <class Range, class Right_shift, class Compare>
+inline void integer_sort(Range& range, Right_shift shift, Compare comp)
+{
+  integer_sort(boost::begin(range), boost::end(range), shift, comp);
+}
+
 /*! \brief Integer sort algorithm using random access iterators with just right-shift functor.
   (All variants fall back to @c std::sort if the data size is too small, < @c detail::min_sort_size).
 
@@ -177,6 +263,50 @@ Some performance plots of runtime vs. n and log(range) are provided:\n
     else
       detail::integer_sort(first, last, shift(*first, 0), shift);
   }
+
+
+/*! \brief Integer sort algorithm using range with just right-shift functor.
+  (All variants fall back to @c std::sort if the data size is too small, < @c detail::min_sort_size).
+
+  \details @c integer_sort is a fast templated in-place hybrid radix/comparison algorithm,
+which in testing tends to be roughly 50% to 2X faster than @c std::sort for large tests (>=100kB).\n
+
+\par Performance:
+Worst-case performance is <em>  O(N * (lg(range)/s + s)) </em>,
+so @c integer_sort is asymptotically faster
+than pure comparison-based algorithms. @c s is @c max_splits, which defaults to 11,
+so its worst-case with default settings for 32-bit integers is
+<em> O(N * ((32/11) </em> slow radix-based iterations fast comparison-based iterations).\n\n
+Some performance plots of runtime vs. n and log(range) are provided:\n
+  * <a href="../../doc/graph/windows_integer_sort.htm"> windows_integer_sort</a>\n
+  * <a href="../../doc/graph/osx_integer_sort.htm"> osx_integer_sort</a>
+
+   \param[in] range Range [first, last) for sorting.
+   \param[in] shift A functor that returns the result of shifting the value_type right a specified number of bits.
+
+   \pre [@c first, @c last) is a valid range.
+   \post The elements in the range [@c first, @c last) are sorted in ascending order.
+
+   \throws std::exception 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.
+
+   \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.
+   \warning Invalid arguments cause undefined behaviour.
+   \note @c spreadsort function provides a wrapper that calls the fastest sorting algorithm available for a data type,
+   enabling faster generic-programming.
+
+   \remark The lesser of <em> O(N*log(N)) </em> comparisons and <em> O(N*log(K/S + S)) </em>operations worst-case, where:
+   \remark  *  N is @c last - @c first,
+   \remark  *  K is the log of the range in bits (32 for 32-bit integers using their full range),
+   \remark  *  S is a constant called max_splits, defaulting to 11 (except for strings where it is the log of the character size).
+
+*/
+template <class Range, class Right_shift>
+inline void integer_sort(Range& range, Right_shift shift)
+{
+  integer_sort(boost::begin(range), boost::end(range), shift);
+}
 }
 }
 }

include/boost/sort/spreadsort/spreadsort.hpp

@@ -12,6 +12,8 @@ Some improvements suggested by:
 Phil Endecott and Frank Gennari
 float_mem_cast fix provided by:
 Scott McMurray
+ Range support provided by:
+ Alexander Zaitsev
 */
 
 #ifndef BOOST_SORT_SPREADSORT_HPP
@@ -25,6 +27,8 @@ Scott McMurray
 #include <boost/sort/spreadsort/integer_sort.hpp>
 #include <boost/sort/spreadsort/float_sort.hpp>
 #include <boost/sort/spreadsort/string_sort.hpp>
+#include <boost/range/begin.hpp>
+#include <boost/range/end.hpp>
 
 namespace boost {
 namespace sort {
@@ -139,6 +143,25 @@ namespace spreadsort {
     boost::uint16_t unused = 0;
     string_sort(first, last, unused);
   }
+
+/*!
+\brief Generic @c spreadsort variant detects value_type and calls required sort function.
+\note Sorting other data types requires picking between @c integer_sort, @c float_sort and @c string_sort directly,
+as @c spreadsort won't accept types that don't have the appropriate @c type_traits.
+
+\param[in] range Range [first, last) for sorting.
+
+\pre [@c first, @c last) is a valid range.
+\post The elements in the range [@c first, @c last) are sorted in ascending order.
+*/
+
+template <class Range>
+void spreadsort(Range& range)
+{
+    spreadsort(boost::begin(range), boost::end(range));
+}
+
+
 } // namespace spreadsort
 } // namespace sort
 } // namespace boost