unstable_sort_by vs panics

[mitsuhiko]

Location

slice::sort_unstable_by

Summary

I ran into a bug with total sort order again which caused a panic. While looking for what others were doing in that situation I ran into a pull request where someone attempted to work around this with unstable sort (cantino/mcfly#454).

Reading the documentation implies in the first part that the worst that happens is not a sorted slice, whereas in the end it mentions that it can panic:

If the comparison function compare does not implement a total order the resulting order of elements in the slice is unspecified.

later

May panic if compare does not implement a total order.

The documentation on sort_by is clearer in that regard:

If the comparison function compare does not implement a total order, the function may panic; even if the function exits normally, the resulting order of elements in the slice is unspecified. See also the note on panicking below.

This should probably be aligned.