ruby-changes:62112
From: Burdette <ko1@a...>
Date: Fri, 3 Jul 2020 23:49:55 +0900 (JST)
Subject: [ruby-changes:62112] e8010c7401 (master): Enhanced RDoc for Array (#3276)
https://git.ruby-lang.org/ruby.git/commit/?id=e8010c7401 From e8010c7401764f54173ffbe8c2bde38cd6d216fa Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Fri, 3 Jul 2020 09:49:36 -0500 Subject: Enhanced RDoc for Array (#3276) *Methods: keep_if delete delete_at slice! diff --git a/array.c b/array.c index 5e27926..04dc17b 100644 --- a/array.c +++ b/array.c @@ -1285,10 +1285,10 @@ 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 * + * Array#append is an alias for \Array#push. + * * Appends trailing elements. * - * Array#append is an alias for \Array#push. - * See also: * - #pop: Removes and returns trailing elements. * - #shift: Removes and returns leading elements. @@ -1658,9 +1658,9 @@ ary_ensure_room_for_unshift(VALUE ary, int argc) https://github.com/ruby/ruby/blob/trunk/array.c#L1658 * array.unshift(*objects) -> self * array.prepend(*objects) -> self * - * Prepends leading elements. + * Array#prepend is an alias for Array#unshift. * - * Array#prepend is an alias for \Array#unshift. + * Prepends leading elements. * * See also: * - #push: Appends trailing elements. @@ -1823,6 +1823,12 @@ static VALUE rb_ary_aref2(VALUE ary, VALUE b, VALUE e); https://github.com/ruby/ruby/blob/trunk/array.c#L1823 * a[-2..2] # => ["bar", 2] * a[-3..2] # => [:foo, "bar", 2] * + * If <tt>range.start</tt> is larger than the array size, returns +nil+: + * a = [:foo, 'bar', 2] + * a[4..1] # => nil + * a[4..0] # => nil + * a[4..-1] # => nil + * * --- * * Raises an exception if given a single argument @@ -2121,6 +2127,8 @@ rb_ary_fetch(int argc, VALUE *argv, VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L2127 * Array#find_index is an alias for Array#index. * See also Array#rindex. * + * Returns the index of a specified element. + * * --- * * When argument +object+ is given but no block, @@ -3118,10 +3126,12 @@ inspect_ary(VALUE ary, VALUE dummy, int recur) https://github.com/ruby/ruby/blob/trunk/array.c#L3126 * array.inspect -> new_string * array.to_s => new_string * - * Returns the new String formed by calling method <tt>#inspect</tt> + * Array#to_s is an alias for Array#inspect. + * + * Returns the new \String formed by calling method <tt>#inspect</tt> * on each array element: * a = [:foo, 'bar', 2] - * a.inspect # => "[:foo, \"bar\", 2]" + * a.inspect # => "[:foo, \"bar\", 2]" * * Raises an exception if any element lacks instance method <tt>#inspect</tt>: * a = [:foo, 'bar', 2, BasicObject.new] @@ -4254,19 +4264,19 @@ rb_ary_select_bang(VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L4264 /* * call-seq: - * ary.keep_if {|item| block} -> ary - * ary.keep_if -> Enumerator - * - * Deletes every element of +self+ for which the given block evaluates to - * +false+, and returns +self+. - * - * If no block is given, an Enumerator is returned instead. + * array.keep_if {|element| ... } -> self + * array.keep_if -> new_enumeration * - * a = %w[ a b c d e f ] - * a.keep_if {|v| v =~ /[aeiou]/ } #=> ["a", "e"] - * a #=> ["a", "e"] + * Retains those elements for which the block returns a truthy value; + * deletes all other elements; returns +self+: + * a = [:foo, 'bar', 2, :bam] + * a1 = a.keep_if {|element| element.to_s.start_with?('b') } + * a1 # => ["bar", :bam] + * a1.equal?(a) # => true # Returned self * - * See also Array#select!. + * Returns a new \Enumerator if no block given: + * a = [:foo, 'bar', 2, :bam] + * a.keep_if # => #<Enumerator: [:foo, "bar", 2, :bam]:keep_if> */ static VALUE @@ -4292,22 +4302,42 @@ ary_resize_smaller(VALUE ary, long len) https://github.com/ruby/ruby/blob/trunk/array.c#L4302 /* * call-seq: - * ary.delete(obj) -> item or nil - * ary.delete(obj) {block} -> item or result of block + * array.delete(obj) -> deleted_object + * array.delete(obj) {|nosuch| ... } -> deleted_object or block_return + * + * Removes zero or more elements from +self+; returns +self+. + * + * --- + * + * When no block is given, + * removes from +self+ each element +ele+ such that <tt>ele == obj</tt>; + * returns the last deleted element: + * s1 = 'bar'; s2 = 'bar' + * a = [:foo, s1, 2, s2] + * deleted_obj = a.delete('bar') + * a # => [:foo, 2] + * deleted_obj.equal?(s2) # => true # Returned self + * + * Returns +nil+ if no elements removed: + * a = [:foo, 'bar', 2] + * a.delete(:nosuch) # => nil * - * Deletes all items from +self+ that are equal to +obj+. + * --- * - * Returns the last deleted item, or +nil+ if no matching item is found. + * When a block is given, + * removes from +self+ each element +ele+ such that <tt>ele == obj</tt>. * - * If the optional code block is given, the result of the block is returned if - * the item is not found. (To remove +nil+ elements and get an informative - * return value, use Array#compact!) + * If any such elements are found, ignores the block + * and returns the last deleted element: + * s1 = 'bar'; s2 = 'bar' + * a = [:foo, s1, 2, s2] + * deleted_obj = a.delete('bar') {|obj| fail 'Cannot happen' } + * a # => [:foo, 2] + * deleted_obj.object_id == s2.object_id # => true * - * a = [ "a", "b", "b", "b", "c" ] - * a.delete("b") #=> "b" - * a #=> ["a", "c"] - * a.delete("z") #=> nil - * a.delete("z") {"not found"} #=> "not found" + * If no such elements are found, returns the block's return value: + * a = [:foo, 'bar', 2] + * a.delete(:nosuch) {|obj| "#{obj} not found" } # => "nosuch not found" */ VALUE @@ -4388,17 +4418,41 @@ rb_ary_delete_at(VALUE ary, long pos) https://github.com/ruby/ruby/blob/trunk/array.c#L4418 /* * call-seq: - * ary.delete_at(index) -> obj or nil + * array.delete_at(index) -> deleted_object or nil + * + * Deletes an element from +self+, per the given +index+. + * + * The given +index+ must be an + * {Integer-convertible object}[doc/implicit_conversion_rdoc.html#label-Integer-Convertible+Objects]. + * + * --- + * + * When +index+ is non-negative, deletes the element at offset +index+: + * a = [:foo, 'bar', 2] + * a.delete_at(1) # => "bar" + * a # => [:foo, 2] + * + * If index is too large, returns nil: + * a = [:foo, 'bar', 2] + * a.delete_at(5) # => nil + * + * --- + * + * When +index+ is negative, counts backward from the end of the array: + * a = [:foo, 'bar', 2] + * a.delete_at(-2) # => "bar" + * a # => [:foo, 2] * - * Deletes the element at the specified +index+, returning that element, or - * +nil+ if the +index+ is out of range. + * If +index+ is too small (far from zero), returns nil: + * a = [:foo, 'bar', 2] + * a.delete_at(-5) # => nil * - * See also Array#slice! + * --- * - * a = ["ant", "bat", "cat", "dog"] - * a.delete_at(2) #=> "cat" - * a #=> ["ant", "bat", "dog"] - * a.delete_at(99) #=> nil + * Raises an exception if index is not an Integer-convertible object: + * a = [:foo, 'bar', 2] + * # Raises TypeError (no implicit conversion of Symbol into Integer): + * a.delete_at(:foo) */ static VALUE @@ -4440,23 +4494,109 @@ ary_slice_bang_by_rb_ary_splice(VALUE ary, long pos, long len) https://github.com/ruby/ruby/blob/trunk/array.c#L4494 /* * call-seq: - * ary.slice!(index) -> obj or nil - * ary.slice!(start, length) -> new_ary or nil - * ary.slice!(range) -> new_ary or nil + * array.slice!(n) -> obj or nil + * array.slice!(start, length) -> new_array or nil + * array.slice!(range) -> new_array or nil * - * Deletes the element(s) given by an +index+ (optionally up to +length+ - * elements) or by a +range+. + * Removes and returns elements from +self+. * - * Returns the deleted object (or objects), or +nil+ if the +index+ is out of - * range. + * - Argument +n+, if given must be an \Integer object. + * - Arguments +start+ and +length+, if given must be \Integer objects. + * - Argument +range+, if given, must be a \Range object. * - * a = [ "a", "b", "c" ] - * a.slice!(1) #=> "b" - * a #=> ["a", "c"] - * a.slice!(-1) #=> "c" - * a #=> ["a"] - * a.slice!(100) #=> nil - * a #=> ["a"] + * --- + * + * When the only argument is an \Integer +n+, + * removes and returns the _nth_ element in +self+: + * a = [:foo, 'bar', 2] + * a.slice!(1) # => "bar" + * a # => [:foo, 2] + * + * If +n+ is negative, counts backwards from the end of +self+: + * a = [:foo, 'bar', 2] + * a.slice!(-1) # => 2 + * a # => [:foo, "bar"] + * + * If +n+ is out of range, returns +nil+: + * a = [:foo, 'bar', 2] + * a.slice!(50) # => nil + * a.slice!(-50) # => nil + * a # => [:foo, "bar", 2] + * + * --- + * + * When the only arguments are Integers +start+ and +length+, + * removes +length+ elements from +self+ beginning at offset +start+; + * returns the deleted objects in a new Array: + * a = [:foo, 'bar', 2] + * a.slice!(0, 2) # => [:foo, "bar"] + * a # => [2] + * + * If <tt>start + length</tt> exceeds the array size, + * removes and returns all elements from offset +start+ to the end: + * a = [:foo, 'bar', 2] + * a.slice!(1, 50) # => ["bar", 2] + * a # => [:foo] + * + * If <tt>start == a.size</tt> and +length+ is non-negative, + * returns a new empty \Array: + * a = [:foo, 'bar', 2] + * a.slice!(a.size, 0) # => [] + * a.slice!(a.size, 50) # => [] + * a # => [:foo, "bar", 2] + * + * If +length+ is negative, returns +nil+: + * a = [:foo, 'bar', 2] + * a.slice!(2, -1) # => nil + * a.slice!(1, -2) (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/