From 48cbe2025fd062081d3528f2c06e94b580298b15 Mon Sep 17 00:00:00 2001 From: drbrain Date: Mon, 10 Oct 2011 23:50:02 +0000 Subject: * array.c (rb_ary_initialize): Improve explanation of Array.new parameters. Patch by Alvaro Pereyra Rabanal. [Ruby 1.9 - Bug #5425] * array.c (rb_ary_s_try_convert): Fix typo (try => tries) * array.c (rb_ary_rindex): Add spacing for block. * array.c (rb_ary_uniq_bang): Describe block * array.c (rb_ary_uniq): ditto git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@33453 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- array.c | 111 ++++++++++++++++++++++++++++++++++++++++------------------------ 1 file changed, 69 insertions(+), 42 deletions(-) (limited to 'array.c') diff --git a/array.c b/array.c index d44d9c0545..cfe44a9015 100644 --- a/array.c +++ b/array.c @@ -478,10 +478,9 @@ rb_check_array_type(VALUE ary) * call-seq: * Array.try_convert(obj) -> array or nil * - * Try to convert +obj+ into an array, using +to_ary+ method. - * Returns converted array or +nil+ if +obj+ cannot be converted - * for any reason. This method can be used to check if an argument is an - * array. + * Tries to convert +obj+ into an array, using +to_ary+ method. Returns the + * converted array or +nil+ if +obj+ cannot be converted for any reason. + * This method can be used to check if an argument is an array. * * Array.try_convert([1]) #=> [1] * Array.try_convert("1") #=> nil @@ -506,35 +505,54 @@ rb_ary_s_try_convert(VALUE dummy, VALUE ary) * Array.new(array) * Array.new(size) {|index| block } * - * Returns a new array. In the first form, the new array is empty, or it is - * created with +size+ copies of +obj+ (that is, +size+ references to the - * same +obj+). The second form creates a copy of the array passed as a - * parameter (the array is generated by calling to_ary on the parameter). In - * the last form, an array of the given size is created. Each element in this - * array is calculated by passing the element's index to the given block and - * storing the return value. - * - * Array.new # => [] (empty array) - * Array.new(2) # => [nil,nil] - * Array.new(5, "A") # => ["A", "A", "A", "A", "A"] - * Array.new(5) {|i| i.to_s } # => ["0", "1", "2", "3", "4"] - * - * # only one copy of the object is created - * a = Array.new(2, Hash.new) #=> [{}, {}] + * Returns a new array. + * + * In the first form, if no arguments are sent, the new array will be empty. + * When a +size+ and an optional +obj+ are sent, an array is created with + * +size+ copies of +obj+. Take notice that all elements will reference the + * same object +obj+. + * + * The second form creates a copy of the array passed as a parameter (the + * array is generated by calling to_ary on the parameter). + * + * first_array = ["Matz", "Guido"] + * + * second_array = Array.new(first_array) #=> ["Matz", "Guido"] + * + * first_array.equal? second_array #=> false + * + * In the last form, an array of the given size is created. Each element in + * this array is created by passing the element's index to the given block + * and storing the return value. + * + * Array.new(3){ |index| index ** 2 } + * # => [0, 1, 4] + * + * == Common gotchas + * + * When sending the second parameter, the same object will be used as the + * value for all the array elements: + * + * a = Array.new(2, Hash.new) + * # => [{}, {}] + * * a[0]['cat'] = 'feline' - * a # => [{"cat"=>"feline"}, {"cat"=>"feline"}] + * a # => [{"cat"=>"feline"}, {"cat"=>"feline"}] + * * a[1]['cat'] = 'Felix' - * a # => [{"cat"=>"Felix"}, {"cat"=>"Felix"}] + * a # => [{"cat"=>"Felix"}, {"cat"=>"Felix"}] * - * # here multiple copies are created - * a = Array.new(2) { Hash.new } # => [{}, {}] - * a[0]['cat'] = 'feline' - * a # => [{"cat"=>"feline"}, {}] + * Since all the Array elements store the same hash, changes to one of them + * will affect them all. * - * squares = Array.new(5) {|i| i*i} - * squares # => [0, 1, 4, 9, 16] + * If multiple copies are what you want, you should use the block + * version which uses the result of that block each time an element + * of the array needs to be initialized: + * + * a = Array.new(2) { Hash.new } + * a[0]['cat'] = 'feline' + * a # => [{"cat"=>"feline"}, {}] * - * copy = Array.new(squares) # => [0, 1, 4, 9, 16] */ static VALUE @@ -1213,9 +1231,9 @@ rb_ary_index(int argc, VALUE *argv, VALUE ary) * If neither block nor argument is given, an enumerator is returned instead. * * a = [ "a", "b", "b", "b", "c" ] - * a.rindex("b") #=> 3 - * a.rindex("z") #=> nil - * a.rindex{|x|x=="b"} #=> 3 + * a.rindex("b") #=> 3 + * a.rindex("z") #=> nil + * a.rindex { |x| x == "b" } #=> 3 */ static VALUE @@ -3512,18 +3530,23 @@ push_value(st_data_t key, st_data_t val, st_data_t ary) /* * call-seq: - * ary.uniq! -> ary or nil + * ary.uniq! -> ary or nil + * ary.uniq! { |item| ... } -> ary or nil * - * Removes duplicate elements from +self+. + * Removes duplicate elements from +self+. If a block is given, + * it will use the return value of the block for comparison. * Returns nil if no changes are made (that is, no * duplicates are found). * * a = [ "a", "a", "b", "b", "c" ] - * a.uniq! #=> ["a", "b", "c"] + * a.uniq! # => ["a", "b", "c"] + * * b = [ "a", "b", "c" ] - * b.uniq! #=> nil - * c = [ "a:def", "a:xyz", "b:abc", "b:xyz", "c:jkl" ] - * c.uniq! {|s| s[/^\w+/]} #=> [ "a:def", "b:abc", "c:jkl" ] + * b.uniq! # => nil + * + * c = [["student","sam"], ["student","george"], ["teacher","matz"]] + * c.uniq! { |s| s.first } # => [["student", "sam"], ["teacher", "matz"]] + * */ static VALUE @@ -3568,14 +3591,18 @@ rb_ary_uniq_bang(VALUE ary) /* * call-seq: - * ary.uniq -> new_ary + * ary.uniq -> ary or nil + * ary.uniq { |item| ... } -> ary or nil * - * Returns a new array by removing duplicate values in +self+. + * Returns a new array by removing duplicate values in +self+. If a block + * is given, it will use the return value of the block for comparison. * * a = [ "a", "a", "b", "b", "c" ] - * a.uniq #=> ["a", "b", "c"] - * c = [ "a:def", "a:xyz", "b:abc", "b:xyz", "c:jkl" ] - * c.uniq {|s| s[/^\w+/]} #=> [ "a:def", "b:abc", "c:jkl" ] + * a.uniq # => ["a", "b", "c"] + * + * b = [["student","sam"], ["student","george"], ["teacher","matz"]] + * b.uniq { |s| s.first } # => [["student", "sam"], ["teacher", "matz"]] + * */ static VALUE -- cgit v1.2.3