| Home | Libraries | People | FAQ | More

## Function template string_sort

boost::sort::spreadsort::string_sort — String sort algorithm using random access iterators, wraps using default of `unsigned` char.

## Synopsis

    // In header: <boost/sort/spreadsort/string_sort.hpp>

    template<typename RandomAccessIter, typename Get_char, typename Get_length>
      void string_sort(RandomAccessIter first, RandomAccessIter last,
                       Get_char get_character, Get_length length);

## Description

(All variants fall back to `boost::sort::pdqsort` if the data size is too small, < `detail::min_sort_size`).

`string_sort` is a fast templated in-place hybrid radix/comparison algorithm, which in testing tends to be roughly 50% to 2X faster than `std::sort` for large tests (>=100kB).

Worst-case performance is O(N * (lg(range)/s + s)) , so `string_sort` is asymptotically faster than pure comparison-based algorithms.
Some performance plots of runtime vs. n and log(range) are provided:
windows_string_sort
osx_string_sort

| 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
`spreadsort` function provides a wrapper that calls the fastest sorting algorithm available for a data type, enabling faster generic-programming.

| Note
The lesser of O(N*log(N)) comparisons and O(N*log(K/S + S)) operations worst-case, where:

| Note
* N is `last` - `first`,

| Note
* K is the log of the range in bits (32 for 32-bit integers using their full range),

| Note
* S is a constant called max_splits, defaulting to 11 (except for strings where it is the log of the character size).

Parameters: |
`first` | Iterator pointer to first element.
`last` | Iterator pointing to one beyond the end of data.
`get_character` | Bracket functor equivalent to `operator`[], taking a number corresponding to the character offset.
`length` | Functor to get the length of the string in characters.
Requires: | [`first`, `last`) is a valid range.
Requires: | `RandomAccessIter` `value_type` is mutable.
Requires: | `RandomAccessIter` `value_type` is LessThanComparable
Requires: | `RandomAccessIter` `value_type` supports the `operator>>`, which returns an integer-type right-shifted a specified number of bits.
Postconditions: | The elements in the range [`first`, `last`) are sorted in ascending order.
Returns: | `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.