Clojure

sort's docstring should say whether it is stable

Details

  • Type: Enhancement Enhancement
  • Status: Open Open
  • Priority: Minor Minor
  • Resolution: Unresolved
  • Affects Version/s: Release 1.6
  • Fix Version/s: None
  • Component/s: None
  • Approval:
    Triaged

Description

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.

Activity

Hide
Alex Miller added a comment -

Sounds reasonable. Needs patch from contributor.

Show
Alex Miller added a comment - Sounds reasonable. Needs patch from contributor.
Alex Miller made changes -
Field Original Value New Value
Approval Triaged [ 10120 ]
Hide
Andy Fingerhut added a comment -

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.

Show
Andy Fingerhut added a comment - 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.
Andy Fingerhut made changes -
Attachment clj-1414-v1.patch [ 13293 ]
Alex Miller made changes -
Labels collections docstring collections docstring ft

People

Vote (2)
Watch (1)

Dates

  • Created:
    Updated: