更新 sort-by 和 sort 的文档字符串，以指明它们将提供稳定的排序

Question

Clojure 的 sort 和 sort-by 都承诺“保证稳定性：相等的元素不会重排。”

ClojureScript 中当前实现的 sort 和 sort-by 来自

9ee4dbf63d3968b70f29708aa03aace98cdcb624 作者：Stuart Halloway <[email protected]> 日期：2011年7月14日星期四 12:18:34 -0500

`
(defn sort
"返回 coll 中元素的排序序列。Comp 可以是
返回布尔值的比较函数，或 -/0/+ 值的比较器。
默认 Comp 为 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
"返回按以下排序顺序排序 coll 中元素的序列，其中排序
顺序由比较 (keyfn item) 确定。Comp 可以是
返回布尔值的比较函数，或 -/0/+ 值的比较器。
默认 Comp 为 compare。
([keyfn coll]
(sort-by keyfn compare coll))
([keyfn comp coll]

 (sort (fn [x y] ((fn->comparator comp) (keyfn x) (keyfn y))) coll)))

`

由于此实现显然在过去的8年内调用了 Google 的 stableSort，也许文档字符串可以修改以反映这一点。

参考资料，Google Closure Array 文档：(链接: https://google.github.io/closure-library/api/goog.array.html)

请注意，stableSort 的文档字符串实际上没有提到稳定性，但排序函数包含“此排序不保证稳定性。”

Answer 1

评论者：seancorfield

(from a discussion on Slack, I offered this opinion which someone suggested I should add to this ticket)

我认为明确声明以下内容会很好

Guaranteed to be stable: equal elements will not be reordered.

或

Not guaranteed to be stable.

这样，开发人员就会知道他们是否可以依赖稳定性，或者他们不应依赖它（尽管当前实现碰巧是稳定的）。

Answer 2

评论者：pbwolf

Clojure的排序文档字符串说明，“保证稳定性：相等的元素不会被重新排序。”之前它已稳定，但没有这样记录。见https://dev.clojure.org/jira/browse/CLJ-1414

我希望CLJS（a）将与Clojure以相同的方式稳定，（b）并匹配Clojure关于稳定性的文档。

Answer 3

评论者：saurabh

如果这个问题仍然开放，我想着手解决它

Answer 4

评论者：dnolen

去做吧，你已经提交了CA吗？

Answer 5

参考：https://clojure.atlassian.net/browse/CLJS-3035（由dpsutton报告）