Update sort-by and sort docstrings to indicate they will be stable sorts

Description

Clojure sort and sort-by both promise "Guaranteed to be stable: equal elements will not be reordered."

The current implementations of `sort` and `sort-by` in ClojureScript are from

1 2 3 9ee4dbf63d3968b70f29708aa03aace98cdcb624 Author: Stuart Halloway <stu@thinkrelevance.com> AuthorDate: Thu Jul 14 12:18:34 2011 -0500

core.cljs

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 (defn sort "Returns a sorted sequence of the items in coll. Comp can be boolean-valued comparison function, or a -/0/+ valued comparator. Comp defaults to compare." ([coll] (sort compare coll)) ([comp coll] (if (seq coll) (let [a (to-array coll)] ;; matching Clojure's stable sort, though docs don't promise it (garray/stableSort a (fn->comparator comp)) (seq a)) ()))) (defn sort-by "Returns a sorted sequence of the items in coll, where the sort order is determined by comparing (keyfn item). Comp can be boolean-valued comparison function, or a -/0/+ valued comparator. Comp defaults to compare." ([keyfn coll] (sort-by keyfn compare coll)) ([keyfn comp coll] (sort (fn [x y] ((fn->comparator comp) (keyfn x) (keyfn y))) coll)))

Since this implementation has apparently called google's stableSort for the last 8 years perhaps the docstring could be amended to reflect this.

For reference, the google closure array documentation: https://google.github.io/closure-library/api/goog.array.html:

Note that stableSort's docstring actually doesn't mention stability but the sort function contains "This sort is not guaranteed to be stable."

Environment

Clojurescript 1.10.439 but I was unable to select in the "Affects Version/s" list

Status

Assignee

Unassigned

Reporter

Daniel Sutton

Labels

Approval

None

Patch

None

Affects versions

1.10.238

Priority

Minor
Configure