unstable sort [ci skip]

* array.c (rb_ary_sort_bang, rb_ary_sort, rb_ary_sort_by_bang):
  [DOC] describe that sort may not be stable.
* enum.c (enum_sort, enum_sort_by): ditto.

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@56413 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

ChangeLog

@@ -1,3 +1,10 @@
+Thu Oct 13 11:35:33 2016  Nobuyoshi Nakada  <nobu@ruby-lang.org>
+
+	* array.c (rb_ary_sort_bang, rb_ary_sort, rb_ary_sort_by_bang):
+	  [DOC] describe that sort may not be stable.
+
+	* enum.c (enum_sort, enum_sort_by): ditto.
+
 Thu Oct 13 11:31:40 2016  Nobuyoshi Nakada  <nobu@ruby-lang.org>
 
 	* test/rexml/xpath/test_text.rb (test_ancestors): Array#sort may

array.c

@@ -2436,6 +2436,9 @@ sort_2(const void *ap, const void *bp, void *dummy)
  *  an integer less than 0 when +b+ follows +a+, +0+ when +a+ and +b+
  *  are equivalent, or an integer greater than 0 when +a+ follows +b+.
  *
+ *  The result is not guaranteed as stable.  When comparison of two
+ *  elements returns +0+, the order of the elements is unpredictable.
+ *
  *  See also Enumerable#sort_by.
  *
  *     a = [ "d", "a", "e", "c", "b" ]
@@ -2517,6 +2520,8 @@ rb_ary_sort_bang(VALUE ary)
  *  an integer less than 0 when +b+ follows +a+, +0+ when +a+ and +b+
  *  are equivalent, or an integer greater than 0 when +a+ follows +b+.
  *
+ *  The result is not guaranteed as stable.  When comparison of two
+ *  elements returns +0+, the order of the elements is unpredictable.
  *
  *  See also Enumerable#sort_by.
  *
@@ -2674,6 +2679,9 @@ sort_by_i(RB_BLOCK_CALL_FUNC_ARGLIST(i, dummy))
  *  Sorts +self+ in place using a set of keys generated by mapping the
  *  values in +self+ through the given block.
  *
+ *  The result is not guaranteed as stable.  When two keys are equal,
+ *  the order of the corresponding elements is unpredictable.
+ *
  *  If no block is given, an Enumerator is returned instead.
  *
  */

enum.c

@@ -934,6 +934,9 @@ enum_first(int argc, VALUE *argv, VALUE obj)
  *  built-in Schwartzian Transform, useful when key computation or
  *  comparison is expensive.
  *
+ *  The result is not guaranteed as stable.  When comparison of two
+ *  elements returns +0+, the order of the elements is unpredictable.
+ *
  *     %w(rhea kea flea).sort          #=> ["flea", "kea", "rhea"]
  *     (1..10).sort { |a, b| b <=> a }  #=> [10, 9, 8, 7, 6, 5, 4, 3, 2, 1]
  */
@@ -1004,6 +1007,9 @@ sort_by_cmp(const void *ap, const void *bp, void *data)
  *  Sorts <i>enum</i> using a set of keys generated by mapping the
  *  values in <i>enum</i> through the given block.
  *
+ *  The result is not guaranteed as stable.  When two keys are equal,
+ *  the order of the corresponding elements is unpredictable.
+ *
  *  If no block is given, an enumerator is returned instead.
  *
  *     %w{apple pear fig}.sort_by { |word| word.length}