ruby-changes:61927
From: Burdette <ko1@a...>
Date: Thu, 25 Jun 2020 03:32:03 +0900 (JST)
Subject: [ruby-changes:61927] 5e860ed4c1 (master): [ci skip] Enhanced RDoc for Array (#3252)
https://git.ruby-lang.org/ruby.git/commit/?id=5e860ed4c1 From 5e860ed4c16e1fe6978754691584041d6a8cb93a Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Wed, 24 Jun 2020 13:31:42 -0500 Subject: [ci skip] Enhanced RDoc for Array (#3252) Methods: map/collect map!/collect! values_at select/filter select!/filter! diff --git a/array.c b/array.c index 9b47bf6..bbfbc2b 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 https://github.com/ruby/ruby/blob/trunk/array.c#L1253 * 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) https://github.com/ruby/ruby/blob/trunk/array.c#L1285 * 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) https://github.com/ruby/ruby/blob/trunk/array.c#L1624 * 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) https://github.com/ruby/ruby/blob/trunk/array.c#L2084 * 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)) https://github.com/ruby/ruby/blob/trunk/array.c#L3854 /* * 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) https://github.com/ruby/ruby/blob/trunk/array.c#L3893 /* * 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) https://github.com/ruby/ruby/blob/trunk/array.c#L3931 /* * 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) https://github.com/ruby/ruby/blob/trunk/array.c#L4022 /* * 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) https://github.com/ruby/ruby/blob/trunk/array.c#L4084 /* * 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> */ (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/