[CLJ-1414] sort's docstring should say whether it is stable Created: 02/May/14 Updated: 12/Sep/14
|Affects Version/s:||Release 1.6|
|Labels:||collections, docstring, ft|
sort's docstring does not address whether the sort will be stable.
Stability is a useful property. It appears to be customary among programming tools to document whether their sort is stable. Java's Collections javadoc pledges a stable sort. The man-page of GNU coreutils sort in Ubuntu mentions its stability. The perldoc of Perl's sort function indicates it is a stable sort now but was not always.
Pillars of the Clojure community have commented on sort's stability:
(1) A recent book assembled by Cognitect consultants, "Clojure Cookbook", says Clojure's sort function "uses Java's built-in sort" and that "[t]he sort is also stable".
(2) In a 2011 discussion thread, "Clojure sort: is it specified to be stable for all targets?" https://groups.google.com/forum/#!topic/clojure/j3aNAmEJW9A , Stuart Sierra replied that "if it's not specified in the doc string, then it's not a promise. That said, [...] I would generally expect a language built-in `sort` routine to be stable, so take that for what it's worth."
Let's promote this open secret / blue-ribbon rumor to a statement in the official documentation.
|Comment by Alex Miller [ 05/May/14 10:23 AM ]|
Sounds reasonable. Needs patch from contributor.
|Comment by Andy Fingerhut [ 30/Aug/14 3:07 PM ]|
Patch clj-1414-v1.patch dated Aug 30 2014 adds the sentence "Guaranteed to be stable: equal elements will not be reordered." to the doc strings of both sort and sort-by.