1 files changed, 31 insertions, 0 deletions
diff --git a/src/tools/clippy/src/docs/stable_sort_primitive.txt b/src/tools/clippy/src/docs/stable_sort_primitive.txt
new file mode 100644
index 000000000..6465dbee4
--- /dev/null
+++ b/src/tools/clippy/src/docs/stable_sort_primitive.txt
@@ -0,0 +1,31 @@
+### What it does
+When sorting primitive values (integers, bools, chars, as well
+as arrays, slices, and tuples of such items), it is typically better to
+use an unstable sort than a stable sort.
+
+### Why is this bad?
+Typically, using a stable sort consumes more memory and cpu cycles.
+Because values which compare equal are identical, preserving their
+relative order (the guarantee that a stable sort provides) means
+nothing, while the extra costs still apply.
+
+### Known problems
+
+As pointed out in
+[issue #8241](https://github.com/rust-lang/rust-clippy/issues/8241),
+a stable sort can instead be significantly faster for certain scenarios
+(eg. when a sorted vector is extended with new data and resorted).
+
+For more information and benchmarking results, please refer to the
+issue linked above.
+
+### Example
+```
+let mut vec = vec![2, 1, 3];
+vec.sort();
+```
+Use instead:
+```
+let mut vec = vec![2, 1, 3];
+vec.sort_unstable();
+```
+\ No newline at end of file