From 4cae27f3845d1d322c8218324a040bde6833108c Mon Sep 17 00:00:00 2001 From: Alvaro Pereyra Date: Sat, 8 Oct 2011 17:57:11 -0500 Subject: [PATCH] Improves array content for some methods and examples for uniq/uniq! --- array.c | 96 ++++++++++++++++++++++++++++++++++++++++----------------------- 1 files changed, 61 insertions(+), 35 deletions(-) diff --git a/array.c b/array.c index 8816d15..2a2adcb 100644 --- a/array.c +++ b/array.c @@ -478,7 +478,7 @@ 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. + * Tries 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. @@ -506,36 +506,56 @@ 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. In the second it is created with _size_ copies of _obj_ - * (that is, _size_ references to the same - * _obj_). The third form creates a copy of the array + * Returns a new array. In the first form, if no arguments + * are sent, the new array will be empty. When they are sent, + * it is created with _size_ copies of _obj_. Take notice that + * all elements will reference the same object _obj_. + * + * Array.new(3, "Hi") + * # => ["Hi", "Hi", "Hi"] + * + * 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. + * to_ary on the parameter). + * + * first_array = ["Matz", "Guido"] + * + * second_array = Array.new(first_array) + * # => ["Matz", "Guido"] + * + * 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 - * Array.new(2) - * Array.new(5, "A") + * Array.new(3){ |index| index ** 2 } + * # => [0, 1, 4] * - * # only one copy of the object is created - * a = Array.new(2, Hash.new) + * == Common gotchas + * + * When sending the second parameter, the same initialized + * object will be used as the value for all the array + * elements + * + * a = Array.new(2, Hash.new) + * # => [{}, {}] + * * a[0]['cat'] = 'feline' - * a + * a # => [{"cat"=>"feline"}, {"cat"=>"feline"}] + * * a[1]['cat'] = 'Felix' - * a + * a # => [{"cat"=>"Felix"}, {"cat"=>"Felix"}] + * + * Since all the Array elements store the same hash object 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: * - * # here multiple copies are created * a = Array.new(2) { Hash.new } * a[0]['cat'] = 'feline' - * a - * - * squares = Array.new(5) {|i| i*i} - * squares + * a # => [{"cat"=>"feline"}, {}] * - * copy = Array.new(squares) */ static VALUE @@ -1208,9 +1228,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 @@ -1945,7 +1965,6 @@ rb_ary_rotate(VALUE ary, long cnt) * * a = [ "a", "b", "c", "d" ] * a.rotate! #=> ["b", "c", "d", "a"] - * a #=> ["b", "c", "d", "a"] * a.rotate!(2) #=> ["d", "a", "b", "c"] * a.rotate!(-3) #=> ["a", "b", "c", "d"] */ @@ -3509,16 +3528,20 @@ push_value(st_data_t key, st_data_t val, st_data_t ary) * call-seq: * ary.uniq! -> 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 @@ -3565,12 +3588,15 @@ rb_ary_uniq_bang(VALUE ary) * call-seq: * ary.uniq -> new_ary * - * 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 -- 1.7.4.4