[ci skip] Enhanced RDoc for Array (#3252)

Methods:

    map/collect
    map!/collect!
    values_at
    select/filter
    select!/filter!

1 files changed, 132 insertions, 73 deletions

diff --git a/array.c b/array.c
index 9b47bf674f..bbfbc2baec 100644
--- a/array.c
+++ b/array.c
@@ -1253,7 +1253,7 @@ ary_take_first_or_last(int argc, const VALUE *argv, VALUE ary, enum ary_take_pos
  *  Appends +object+ as one element, even if it is another \Array:
  *
  *    a = [:foo, 'bar', 2]
- *    a1 = a << [3, 4] # =>
+ *    a1 = a << [3, 4]
  *    a1 # => [:foo, "bar", 2, [3, 4]]
  */
 
@@ -1285,7 +1285,9 @@ rb_ary_cat(VALUE ary, const VALUE *argv, long len)
  *    array.push(*objects) -> self
  *    array.append(*objects) -> self
  *
- *  Appends trailing elements. #append is an alias for \#push.
+ *  Appends trailing elements.
+ *
+ *  Array#append is an alias for \Array#push.
 
  *  See also:
  *  - #pop:  Removes and returns trailing elements.
@@ -1622,7 +1624,9 @@ ary_ensure_room_for_unshift(VALUE ary, int argc)
  *    array.unshift(*objects) -> self
  *    array.prepend(*objects) -> self
  *
- *  Prepends leading elements. #prepend is an alias for \#unshift.
+ *  Prepends leading elements.
+ *
+ *  Array#prepend is an alias for \Array#unshift.
  *
  *  See also:
  *  - #push:  Appends trailing elements.
@@ -2080,7 +2084,7 @@ rb_ary_fetch(int argc, VALUE *argv, VALUE ary)
  *    array.find_index {|element| ... } -> integer or nil
  *    array.find_index -> new_enumerator
  *
- *  Array#index is an alias for Array#find_index.
+ *  Array#find_index is an alias for Array#index.
  *  See also Array#rindex.
  *
  *  ---
@@ -3850,18 +3854,28 @@ sort_by_i(RB_BLOCK_CALL_FUNC_ARGLIST(i, dummy))
 
 /*
  *  call-seq:
- *     ary.sort_by! {|obj| block}      -> ary
- *     ary.sort_by!                    -> Enumerator
+ *    array.sort_by! {|element| ... } -> self
+ *    array.sort_by! -> new_enumerator
  *
- *  Sorts +self+ in place using a set of keys generated by mapping the
- *  values in +self+ through the given block.
+ *  Sorts the elements of +self+ in place,
+ *  using an ordering determined by the block; returns self.
  *
- *  The result is not guaranteed to be stable.  When two keys are equal,
- *  the order of the corresponding elements is unpredictable.
+ *  Calls the block with each successive element;
+ *  sorts elements based on the values returned from the block.
  *
- *  If no block is given, an Enumerator is returned instead.
+ *  For duplicates returned by the block, the ordering is indeterminate, and may be unstable.
  *
- *  See also Enumerable#sort_by.
+ *  This example sorts strings based on their sizes:
+ *    a = ['aaaa', 'bbb', 'cc', 'd']
+ *    a.sort_by! {|element| element.size }
+ *    a # => ["d", "cc", "bbb", "aaaa"]
+ *
+ *  ---
+ *
+ *  Returns a new \Enumerator if no block given:
+ *
+ *    a = ['aaaa', 'bbb', 'cc', 'd']
+ *    a.sort_by! # => #<Enumerator: ["aaaa", "bbb", "cc", "d"]:sort_by!>
  */
 
 static VALUE
@@ -3879,23 +3893,25 @@ rb_ary_sort_by_bang(VALUE ary)
 
 /*
  *  call-seq:
- *     ary.collect {|item| block}    -> new_ary
- *     ary.map     {|item| block}    -> new_ary
- *     ary.collect                   -> Enumerator
- *     ary.map                       -> Enumerator
- *
- *  Invokes the given block once for each element of +self+.
+ *    array.map {|element| ... } -> new_array
+ *    array.map -> new_enumerator
+ *    array.collect {|element| ... } -> new_array
+ *    array.collect -> new_enumerator
  *
- *  Creates a new array containing the values returned by the block.
+ *  Array#map is an alias for Array#collect.
  *
- *  See also Enumerable#collect.
+ *  Calls the block, if given, with each element of +self+;
+ *  returns a new \Array whose elements are the return values from the block:
+ *    a = [:foo, 'bar', 2]
+ *    a1 = a.collect {|element| element.class }
+ *    a1 # => [Symbol, String, Integer]
  *
- *  If no block is given, an Enumerator is returned instead.
+ *  ---
  *
- *     a = [ "a", "b", "c", "d" ]
- *     a.collect {|x| x + "!"}           #=> ["a!", "b!", "c!", "d!"]
- *     a.map.with_index {|x, i| x * i}   #=> ["", "b", "cc", "ddd"]
- *     a                                 #=> ["a", "b", "c", "d"]
+ *  Returns a new \Enumerator if no block given:
+ *    a = [:foo, 'bar', 2]
+ *    a1 = a.collect
+ *    a1 # => #<Enumerator: [:foo, "bar", 2]:collect>
  */
 
 static VALUE
@@ -3915,23 +3931,26 @@ rb_ary_collect(VALUE ary)
 
 /*
  *  call-seq:
- *     ary.collect! {|item| block }   -> ary
- *     ary.map!     {|item| block }   -> ary
- *     ary.collect!                   -> Enumerator
- *     ary.map!                       -> Enumerator
+ *    array.map! {|element| ... } -> self
+ *    array.map! -> new_enumerator
+ *    array.collect! {|element| ... } -> self
+ *    array.collect! -> new_enumerator
  *
- *  Invokes the given block once for each element of +self+, replacing the
- *  element with the value returned by the block.
+ *  Array#map! is an alias for Array#collect!.
  *
- *  See also Enumerable#collect.
+ *  Calls the block, if given, with each element;
+ *  replaces the element with the block's return value:
+ *    a = [:foo, 'bar', 2]
+ *    a1 = a.collect! { |element| element.class }
+ *    a1 # => [Symbol, String, Integer]
+ *    a1.equal?(a) # => true # Returned self
  *
- *  If no block is given, an Enumerator is returned instead.
+ *  ---
  *
- *     a = [ "a", "b", "c", "d" ]
- *     a.map! {|x| x + "!" }
- *     a #=>  [ "a!", "b!", "c!", "d!" ]
- *     a.collect!.with_index {|x, i| x[0...i] }
- *     a #=>  ["", "b", "c!", "d!"]
+ *  Returns a new \Enumerator if no block given:
+ *    a = [:foo, 'bar', 2]
+ *    a1 = a.collect!
+ *    a1 # => #<Enumerator: [:foo, "bar", 2]:collect!>
  */
 
 static VALUE
@@ -4003,20 +4022,51 @@ append_values_at_single(VALUE result, VALUE ary, long olen, VALUE idx)
 
 /*
  *  call-seq:
- *     ary.values_at(selector, ...)  -> new_ary
+ *    array.values_at(*indexes) -> new_array
+ *
+ *  Returns a new \Array whose elements are the elements
+ *  of +self+ at the given +indexes+.
+ *
+ *  Each +index+ given in +indexes+ must be an
+ *  {Integer-convertible object}[doc/implicit_conversion_rdoc.html#label-Integer-Convertible+Objects].
+ *
+ *  ---
+ *
+ *  For each positive +index+, returns the element at offset +index+:
+ *    a = [:foo, 'bar', 2]
+ *    a.values_at(0, 2) # => [:foo, 2]
  *
- *  Returns an array containing the elements in +self+ corresponding to the
- *  given +selector+(s).
+ *  The given +indexes+ may be in any order, and may repeat:
+ *    a = [:foo, 'bar', 2]
+ *    a.values_at(2, 0, 1, 0, 2) # => [2, :foo, "bar", :foo, 2]
+ *
+ *  Assigns +nil+ for an +index+ that is too large:
+ *    a = [:foo, 'bar', 2]
+ *    a.values_at(0, 3, 1, 3) # => [:foo, nil, "bar", nil]
+ *
+ *  Returns a new empty \Array if no arguments given:
+ *    [].values_at # => []
+ *
+ *  ---
+ *
+ *  For each negative +index+, counts backward from the end of the array:
+ *    a = [:foo, 'bar', 2]
+ *    a.values_at(-1, -3) # => [2, :foo]
  *
- *  The selectors may be either integer indices or ranges.
+ *  Assigns +nil+ for an +index+ that is too small:
+ *    a = [:foo, 'bar', 2]
+ *    a.values_at(0, -5, 1, -6, 2) # => [:foo, nil, "bar", nil, 2]
  *
- *  See also Array#select.
+ *  The given +indexes+ may have a mixture of signs:
+ *    a = [:foo, 'bar', 2]
+ *    a.values_at(0, -2, 1, -1) # => [:foo, "bar", "bar", 2]
  *
- *     a = %w{ a b c d e f }
- *     a.values_at(1, 3, 5)          # => ["b", "d", "f"]
- *     a.values_at(1, 3, 5, 7)       # => ["b", "d", "f", nil]
- *     a.values_at(-1, -2, -2, -7)   # => ["f", "e", "e", nil]
- *     a.values_at(4..6, 3...6)      # => ["e", "f", nil, "d", "e", "f"]
+ *  ---
+ *
+ *  Raises an exception if any +index+ is not an Integer-convertible object:
+ *    a = [:foo, 'bar', 2]
+ *    # Raises TypeError (no implicit conversion of Symbol into Integer):
+ *    a.values_at(0, :foo)
  */
 
 static VALUE
@@ -4034,24 +4084,25 @@ rb_ary_values_at(int argc, VALUE *argv, VALUE ary)
 
 /*
  *  call-seq:
- *     ary.select {|item| block}   -> new_ary
- *     ary.select                  -> Enumerator
- *     ary.filter {|item| block}   -> new_ary
- *     ary.filter                  -> Enumerator
+ *    array.select {|element| ... } -> new_array
+ *    array.select -> new_enumerator
+ *    array.filter {|element| ... } -> new_array
+ *    array.filter -> new_enumerator
  *
- *  Returns a new array containing all elements of +ary+
- *  for which the given +block+ returns a true value.
- *
- *  If no block is given, an Enumerator is returned instead.
+ *  Array#filter is an alias for Array#select.
  *
- *     [1,2,3,4,5].select {|num| num.even? }     #=> [2, 4]
+ *  Calls the block, if given, with each element of +self+;
+ *  returns a new \Array containing those elements of +self+
+ *  for which the block returns a truthy value:
+ *    a = [:foo, 'bar', 2, :bam]
+ *    a1 = a.select {|element| element.to_s.start_with?('b') }
+ *    a1 # => ["bar", :bam]
  *
- *     a = %w[ a b c d e f ]
- *     a.select {|v| v =~ /[aeiou]/ }    #=> ["a", "e"]
- *
- *  See also Enumerable#select.
+ *  ---
  *
- *  Array#filter is an alias for Array#select.
+ *  Returns a new \Enumerator if no block given:
+ *    a = [:foo, 'bar', 2, :bam]
+ *    a.select # => #<Enumerator: [:foo, "bar", 2, :bam]:select>
  */
 
 static VALUE
@@ -4116,23 +4167,31 @@ select_bang_ensure(VALUE a)
 
 /*
  *  call-seq:
- *     ary.select! {|item| block } -> ary or nil
- *     ary.select!                 -> Enumerator
- *     ary.filter! {|item| block } -> ary or nil
- *     ary.filter!                 -> Enumerator
+ *    array.select! {|element| ... } -> self or nil
+ *    array.select! -> new_enumerator
+ *    array.filter! {|element| ... } -> self or nil
+ *    array.filter! -> new_enumerator
  *
- *  Invokes the given block passing in successive elements from +self+,
- *  deleting elements for which the block returns a +false+ value.
+ *  Array#filter! is an alias for Array#select!.
  *
- *  The array may not be changed instantly every time the block is called.
+ *  Calls the block, if given  with each element of +self+;
+ *  removes from +self+ those elements for which the block returns +false+ or +nil+.
  *
- *  If changes were made, it will return +self+, otherwise it returns +nil+.
+ *  Returns +self+ if any elements were removed:
+ *    a = [:foo, 'bar', 2, :bam]
+ *    a1 = a.select! {|element| element.to_s.start_with?('b') }
+ *    a1 # => ["bar", :bam]
+ *    a1.equal?(a) # => true # Returned self
  *
- *  If no block is given, an Enumerator is returned instead.
+ *  Returns +nil+ if no elements were removed:
+ *    a = [:foo, 'bar', 2, :bam]
+ *    a.select! { |element| element.kind_of?(Object) } # => nil
  *
- *  See also Array#keep_if.
+ *  ---
  *
- *  Array#filter! is an alias for Array#select!.
+ *  Returns a new \Enumerator if no block given:
+ *    a = [:foo, 'bar', 2, :bam]
+ *    a.select! # => #<Enumerator: [:foo, "bar", 2, :bam]:select!>
  */
 
 static VALUE