nobu	2016-02-28 10:20:39 +0900 (Sun, 28 Feb 2016)

  New Revision: 53958

  https://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=revision&revision=53958

  Log:
    Clarify set intersection and union documentation
    
    * array.c (rb_ary_and): clarify that set intersection returns the
      unique elements common to both arrays.
    
    * array.c (rb_ary_or): clarify that union preserves the order from
      the given arrays.
    
    - Most know what intersection means, but saying the operation
      excludes duplicates could be misleading ([1] & [1], duplicates
      excluded, might mean a result of []).
    - Instead, saying intersection returns the unique elements common to both
      arrays is more concise and less ambiguous.
    - The set union's documentation was incomplete in its describing
      preservation of order. Saying union preserves the order of the
      original array neglects the idea that the order of the elements
      in both arrays, as given, will be preserved.
    - Instead, saying set union preserves the order from the given arrays (and
      adding an example) fully demonstrates the idea.
    
    [Fix GH-1273] [ci skip]

  Modified files:
    trunk/ChangeLog
    trunk/array.c
Index: array.c
===================================================================
--- array.c	(revision 53957)
+++ array.c	(revision 53958)
@@ -4098,13 +4098,12 @@ rb_ary_diff(VALUE ary1, VALUE ary2) https://github.com/ruby/ruby/blob/trunk/array.c#L4098
  *  call-seq:
  *     ary & other_ary      -> new_ary
  *
- *  Set Intersection --- Returns a new array containing elements common to the
- *  two arrays, excluding any duplicates. The order is preserved from the
- *  original array.
+ *  Set Intersection --- Returns a new array containing unique elements common to the
+ *  two arrays. The order is preserved from the original array.
  *
  *  It compares elements using their #hash and #eql? methods for efficiency.
  *
- *     [ 1, 1, 3, 5 ] & [ 1, 2, 3 ]                 #=> [ 1, 3 ]
+ *     [ 1, 1, 3, 5 ] & [ 3, 2, 1 ]                 #=> [ 1, 3 ]
  *     [ 'a', 'b', 'b', 'z' ] & [ 'a', 'b', 'c' ]   #=> [ 'a', 'b' ]
  *
  *  See also Array#uniq.
@@ -4150,11 +4149,12 @@ ary_hash_orset(st_data_t *key, st_data_t https://github.com/ruby/ruby/blob/trunk/array.c#L4149
  *     ary | other_ary     -> new_ary
  *
  *  Set Union --- Returns a new array by joining +ary+ with +other_ary+,
- *  excluding any duplicates and preserving the order from the original array.
+ *  excluding any duplicates and preserving the order from the given arrays.
  *
  *  It compares elements using their #hash and #eql? methods for efficiency.
  *
  *     [ "a", "b", "c" ] | [ "c", "d", "a" ]    #=> [ "a", "b", "c", "d" ]
+ *     [ "c", "d", "a" ] | [ "a", "b", "c" ]    #=> [ "c", "d", "a", "b" ]
  *
  *  See also Array#uniq.
  */
Index: ChangeLog
===================================================================
--- ChangeLog	(revision 53957)
+++ ChangeLog	(revision 53958)
@@ -1,3 +1,11 @@ https://github.com/ruby/ruby/blob/trunk/ChangeLog#L1
+Sun Feb 28 10:19:47 2016  Ryan T. Hosford  <tad.hosford@g...>
+
+	* array.c (rb_ary_and): clarify that set intersection returns the
+	  unique elements common to both arrays.
+
+	* array.c (rb_ary_or): clarify that union preserves the order from
+	  the given arrays.
+
 Sat Feb 27 17:05:29 2016  Martin Duerst  <duerst@i...>
 
 	* enc/unicode/case-folding.rb, casefold.h: Reducing size of TitleCase

--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/