ruby-changes:21404
From: drbrain <ko1@a...>
Date: Tue, 11 Oct 2011 08:50:16 +0900 (JST)
Subject: [ruby-changes:21404] drbrain:r33453 (trunk): * array.c (rb_ary_initialize): Improve explanation of Array.new
drbrain 2011-10-11 08:50:02 +0900 (Tue, 11 Oct 2011) New Revision: 33453 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=33453 Log: * 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 Modified files: trunk/ChangeLog trunk/array.c Index: array.c =================================================================== --- array.c (revision 33452) +++ array.c (revision 33453) @@ -478,10 +478,9 @@ * 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 @@ * 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. + * Returns a new array. * - * 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"] + * 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+. * - * # only one copy of the object is created - * a = Array.new(2, Hash.new) #=> [{}, {}] + * 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 } # => [{}, {}] + * Since all the Array elements store the same hash, changes to one of them + * will affect them all. + * + * 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"}, {}] + * a # => [{"cat"=>"feline"}, {}] * - * squares = Array.new(5) {|i| i*i} - * squares # => [0, 1, 4, 9, 16] - * - * copy = Array.new(squares) # => [0, 1, 4, 9, 16] */ static VALUE @@ -1213,9 +1231,9 @@ * 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 @@ /* * 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 <code>nil</code> 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 @@ /* * 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 Index: ChangeLog =================================================================== --- ChangeLog (revision 33452) +++ ChangeLog (revision 33453) @@ -1,3 +1,12 @@ +Tue Oct 11 08:49:40 2011 Eric Hodel <drbrain@s...> + + * 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 + Tue Oct 11 07:55:38 2011 Eric Hodel <drbrain@s...> * array.c: Add a description to Array, minor cleanups. Patch by -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/