diff options
| -rw-r--r-- | array.c | 274 | ||||
| -rw-r--r-- | doc/syntax/calling_methods.rdoc | 36 |
2 files changed, 226 insertions, 84 deletions
@@ -935,21 +935,26 @@ rb_check_to_array(VALUE ary) /* * call-seq: - * Array.try_convert(obj) -> array or nil + * Array.try_convert(obj) -> new_array or nil * - * Tries to convert +obj+ into an array, using the +to_ary+ method. Returns - * the converted array or +nil+ if +obj+ cannot be converted. - * This method can be used to check if an argument is an array. + * Tries to convert +obj+ to an \Array. * - * Array.try_convert([1]) #=> [1] - * Array.try_convert("1") #=> nil + * When +obj+ is an + * {Array-convertible object}[doc/implicit_conversion_rdoc.html#label-Array-Convertible+Objects] + * (implements +to_ary+), + * returns the \Array object created by converting it: * - * if tmp = Array.try_convert(arg) - * # the argument is an array - * elsif tmp = String.try_convert(arg) - * # the argument is a string - * end + * class ToAryReturnsArray < Set + * def to_ary + * self.to_a + * end + * end + * as = ToAryReturnsArray.new([:foo, :bar, :baz]) + * Array.try_convert(as) # => [:foo, :bar, :baz] * + * Returns +nil+ if +obj+ is not \Array-convertible: + * + * Array.try_convert(:foo) # => nil */ static VALUE @@ -960,58 +965,96 @@ rb_ary_s_try_convert(VALUE dummy, VALUE ary) /* * call-seq: - * Array.new(size=0, default=nil) - * Array.new(array) - * Array.new(size) {|index| block } + * Array.new -> new_empty_array + * Array.new(array) -> new_array + * Array.new(size) -> new_array + * Array.new(size, default_value) -> new_array + * Array.new(size) {|index| ... } -> new_array + * + * Returns a new \Array. + * + * Argument +array+, if given, must be an + * {Array-convertible object}[doc/implicit_conversion_rdoc.html#label-Array-Convertible+Objects] + * (implements +to_ary+). + * + * Argument +size+, if given must be an + * {Integer-convertible object}[doc/implicit_conversion_rdoc.html#label-Integer-Convertible+Objects] + * (implements +to_int+). + * + * Argument +default_value+ may be any object. * - * 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 +default+ are sent, an array is created with - * +size+ copies of +default+. Take notice that all elements will reference the - * same object +default+. + * With no block and no arguments, returns a new empty \Array object: * - * The second form creates a copy of the array passed as a parameter (the - * array is generated by calling to_ary on the parameter). + * a = Array.new + * a # => [] * - * first_array = ["Matz", "Guido"] + * With no block and a single argument +array+, + * returns a new \Array formed from +array+: * - * second_array = Array.new(first_array) #=> ["Matz", "Guido"] + * a = Array.new([:foo, 'bar', 2]) + * a.class # => Array + * a # => [:foo, "bar", 2] * - * first_array.equal? second_array #=> false + * With no block and a single argument +size+, + * returns a new \Array of the given size + * whose elements are all +nil+: * - * 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. + * a = Array.new(0) + * a # => [] + * a = Array.new(3) + * a # => [nil, nil, nil] * - * Array.new(3) {|index| index ** 2} - * # => [0, 1, 4] + * With no block and arguments +size+ and +default_value+, + * returns an \Array of the given size; + * each element is that same +default_value+: * - * == Common gotchas + * a = Array.new(3, 'x') + * a # => ['x', 'x', 'x'] + * a[1].equal?(a[0]) # => true # Identity check. + * a[2].equal?(a[0]) # => true # Identity check. * - * When sending the second parameter, the same object will be used as the - * value for all the array elements: + * With a block and argument +size+, + * returns an \Array of the given size; + * the block is called with each successive integer +index+; + * the element for that +index+ is the return value from the block: * - * a = Array.new(2, Hash.new) - * # => [{}, {}] + * a = Array.new(3) { |index| "Element #{index}" } + * a # => ["Element 0", "Element 1", "Element 2"] * - * a[0]['cat'] = 'feline' - * a # => [{"cat"=>"feline"}, {"cat"=>"feline"}] + * With a block and no argument, + * or a single argument +0+, + * ignores the block and returns a new empty \Array: * - * a[1]['cat'] = 'Felix' - * a # => [{"cat"=>"Felix"}, {"cat"=>"Felix"}] + * a = Array.new(0) { |n| fail 'Cannot happen' } + * a # => [] + * a = Array.new { |n| fail 'Cannot happen' } + * a # => [] * - * Since all the Array elements store the same hash, changes to one of them - * will affect them all. + * With a block and arguments +size+ and +default_value+, + * gives a warning message + * ('warning: block supersedes default value argument'), + * and assigns elements from the block's return values: * - * 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: + * Array.new(4, :default) {} # => [nil, nil, nil, nil] * - * a = Array.new(2) {Hash.new} - * a[0]['cat'] = 'feline' - * a # => [{"cat"=>"feline"}, {}] + * --- * + * Raises an exception if +size+ is a negative integer: + * + * # Raises ArgumentError (negative array size): + * Array.new(-1) + * # Raises ArgumentError (negative array size): + * Array.new(-1, :default) + * # Raises ArgumentError (negative array size): + * Array.new(-1) { |n| } + * + * Raises an exception if the single argument is neither \Array-convertible + * nor \Integer-convertible. + * + * # Raises TypeError (no implicit conversion of Symbol into Integer): + * Array.new(:foo) */ static VALUE @@ -1193,18 +1236,20 @@ ary_take_first_or_last(int argc, const VALUE *argv, VALUE ary, enum ary_take_pos /* * call-seq: - * ary << obj -> ary + * ary << obj -> self * - * Append---Pushes the given object on to the end of this array. This - * expression returns the array itself, so several appends - * may be chained together. + * Appends +obj+ to +ary+; returns +self+: * - * a = [ 1, 2 ] - * a << "c" << "d" << [ 3, 4 ] - * #=> [ 1, 2, "c", "d", [ 3, 4 ] ] - * a - * #=> [ 1, 2, "c", "d", [ 3, 4 ] ] + * a = [:foo, 'bar', 2] + * a1 = a << :baz + * a1 # => [:foo, "bar", 2, :baz] + * a1.equal?(a) # => true * + * Appends +obj+ as one element, even if it is another \Array: + * + * a = [:foo, 'bar', 2] + * a1 = a << [3, 4] # => + * a1 # => [:foo, "bar", 2, [3, 4]] */ VALUE @@ -1232,19 +1277,21 @@ rb_ary_cat(VALUE ary, const VALUE *argv, long len) /* * call-seq: - * ary.push(obj, ...) -> ary - * ary.append(obj, ...) -> ary + * ary.push(*objects) -> self + * ary.append(*objects) -> self * - * Append --- Pushes the given object(s) on to the end of this array. This - * expression returns the array itself, so several appends - * may be chained together. See also Array#pop for the opposite - * effect. + * Appends each argument in +objects+ to the array; returns +self+: * - * a = [ "a", "b", "c" ] - * a.push("d", "e", "f") - * #=> ["a", "b", "c", "d", "e", "f"] - * [1, 2, 3].push(4).push(5) - * #=> [1, 2, 3, 4, 5] + * a = [:foo, 'bar', 2] + * a1 = a.push(:baz, :bat) + * a1 # => [:foo, "bar", 2, :baz, :bat] + * a1.equal?(a) # => true + * + * Appends each argument as one element, even if it is another \Array: + * + * a = [:foo, 'bar', 2] + * a1 = a.push([:baz, :bat], [:bam, :bad]) + * a1 # => [:foo, "bar", 2, [:baz, :bat], [:bam, :bad]] */ static VALUE @@ -1274,20 +1321,62 @@ rb_ary_pop(VALUE ary) /* * call-seq: - * ary.pop -> obj or nil - * ary.pop(n) -> new_ary + * ary.pop -> obj or nil + * ary.pop(n) -> new_array * - * Removes the last element from +self+ and returns it, or - * +nil+ if the array is empty. + * Removes and returns trailing elements from the array. * - * If a number +n+ is given, returns an array of the last +n+ elements - * (or less) just like <code>array.slice!(-n, n)</code> does. See also - * Array#push for the opposite effect. + * Argument +n+, if given, must be an + * {Integer-convertible object}[doc/implicit_conversion_rdoc.html#label-Integer-Convertible+Objects] + * (implements +to_int+). * - * a = [ "a", "b", "c", "d" ] - * a.pop #=> "d" - * a.pop(2) #=> ["b", "c"] - * a #=> ["a"] + * --- + * + * When no argument is given and the array is not empty, + * removes and returns the last element in the array: + * + * a = [:foo, 'bar', 2] + * a.pop # => 2 + * a # => [:foo, "bar"] + * + * Returns +nil+ if the array is empty: + * + * a = [] + * a.pop # => nil + * + * --- + * + * When argument +n+ is given and is non-negative and in range, + * removes and returns the last +n+ elements in a new \Array: + * + * a = [:foo, 'bar', 2] + * a1 = a.pop(2) + * a1 # => ["bar", 2] + * a # => [:foo] + * a.pop(0) # => [] + * + * If +n+ is positive and out of range, + * removes and returns all elements: + * + * a = [:foo, 'bar', 2] + * a1 = a.pop(50) + * a1 # => [:foo, "bar", 2] + * a # => [] + * a.pop(1) # => [] + * + * --- + * + * Raises an exception if +n+ is negative: + * + * a = [:foo, 'bar', 2] + * # Raises ArgumentError (negative array size): + * a1 = a.pop(-1) + * + * Raises an exception if +n+ is not \Integer-convertible (implements +to_int+). + * + * a = [:foo, 'bar', 2] + * # Raises TypeError (no implicit conversion of String into Integer): + * a1 = a.pop('x') */ static VALUE @@ -6621,12 +6710,32 @@ rb_ary_deconstruct(VALUE ary) } /* - * Arrays are ordered, integer-indexed collections of any object. + * An \Array is an ordered, integer-indexed collection of objects, + * called _elements_. Any object may be an \Array element. + * + * == \Array Indexes + * + * \Array indexing starts at 0, as in C or Java. * - * Array indexing starts at 0, as in C or Java. A negative index is assumed - * to be relative to the end of the array---that is, an index of -1 indicates - * the last element of the array, -2 is the next to last element in the - * array, and so on. + * A positive index is an offset from the first element: + * - Index 0 indicates the first element. + * - Index 1 indicates the second element. + * - ... + * + * A negative index is an offset, backwards, from the end of the array: + * - Index -1 indicates the last element. + * - Index -2 indicates the next-to-last element. + * - ... + * + * A non-negative index is <i>in range</i> if it is smaller than + * the size of the array. For a 3-element array: + * - Indexes 0 through 2 are in range. + * - Index 3 is out of range. + * + * A negative index is <i>in range</i> if its absolute value is + * not larger than the size of the array. For a 3-element array: + * - Indexes -1 through -3 are in range. + * - Index -4 is out of range. * * == Creating Arrays * @@ -6855,7 +6964,6 @@ rb_ary_deconstruct(VALUE ary) * arr = [1, 2, 3, 4, 5, 6] * arr.keep_if {|a| a < 4} #=> [1, 2, 3] * arr #=> [1, 2, 3] - * */ void diff --git a/doc/syntax/calling_methods.rdoc b/doc/syntax/calling_methods.rdoc index 5abecc69da..fc806d5c31 100644 --- a/doc/syntax/calling_methods.rdoc +++ b/doc/syntax/calling_methods.rdoc @@ -30,7 +30,41 @@ NoMethodError. You may also use <code>::</code> to designate a receiver, but this is rarely used due to the potential for confusion with <code>::</code> for namespaces. -=== Safe navigation operator +=== Chaining \Method Calls + +You can "chain" method calls by immediately following one method call with another. + +This example chains methods Array#append and Array#compact: + + a = [:foo, 'bar', 2] + a1 = [:baz, nil, :bam, nil] + a2 = a.append(*a1).compact + a2 # => [:foo, "bar", 2, :baz, :bam] + +Details: + +- First method <tt>merge</tt> creates a copy of <tt>a</tt>, + appends (separately) each element of <tt>a1</tt> to the copy, and returns + [:foo, "bar", 2, :baz, nil, :bam, nil] +- Chained method <tt>compact</tt> creates a copy of that return value, + removes its <tt>nil</tt>-valued entries, and returns + [:foo, "bar", 2, :baz, :bam] + +You can chain methods that are in different classes. +This example chains methods Hash#to_a and Array#reverse: + + h = {foo: 0, bar: 1, baz: 2} + h.to_a.reverse # => [[:baz, 2], [:bar, 1], [:foo, 0]] + +Details: + +- First method Hash#to_a converts <tt>a</tt> to an \Array, and returns + [[:foo, 0], [:bar, 1], [:baz, 2]] +- Chained method Array#reverse creates copy of that return value, + reverses it, and returns + [[:baz, 2], [:bar, 1], [:foo, 0]] + +=== Safe Navigation Operator <code>&.</code>, called "safe navigation operator", allows to skip method call when receiver is +nil+. It returns +nil+ and doesn't evaluate method's arguments |