Bug #5412 » 0001-documentation-for-array.patch
array.c | ||
---|---|---|
* # only one copy of the object is created
|
||
* 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"}]
|
||
*
|
||
* # here multiple copies are created
|
||
* a = Array.new(2) { Hash.new }
|
||
* a[0]['cat'] = 'feline'
|
||
* a
|
||
* a #=> [{"cat"=>"feline"}, {}]
|
||
* a[1]['cat'] = 'Felix'
|
||
* a #=> [{"cat"=>"feline"}, {"cat"=>"Felix"}]
|
||
*
|
||
* squares = Array.new(5) {|i| i*i}
|
||
* squares
|
||
* squares #=> [0, 1, 4, 9, 16]
|
||
*
|
||
* copy = Array.new(squares)
|
||
* copy #=> [0, 1, 4, 9, 16]
|
||
*/
|
||
static VALUE
|
||
... | ... | |
* If no block is given, an enumerator is returned instead.
|
||
*
|
||
* a = [ "a", "b", "c", "d" ]
|
||
* a.collect {|x| x + "!" } #=> ["a!", "b!", "c!", "d!"]
|
||
* a.map {|x| x + "!" } #=> ["a!", "b!", "c!", "d!"]
|
||
* a #=> ["a", "b", "c", "d"]
|
||
*/
|
||
... | ... | |
* If no block is given, an enumerator is returned instead.
|
||
*
|
||
* a = [ "a", "b", "c", "d" ]
|
||
* a.collect! {|x| x + "!" }
|
||
* a.map! {|x| x + "!" }
|
||
* a #=> [ "a!", "b!", "c!", "d!" ]
|
||
*/
|
||
... | ... | |
* Comparison---Returns an integer (-1, 0,
|
||
* or +1) if this array is less than, equal to, or greater than
|
||
* <i>other_ary</i>. Each object in each array is compared
|
||
* (using <=>). If any value isn't
|
||
* equal, then that inequality is the return value. If all the
|
||
* values found are equal, then the return is based on a
|
||
* comparison of the array lengths. Thus, two arrays are
|
||
* (using <=>). Arrays are compared in an "elementwise" manner; the first two
|
||
* elements that are not equal will determine the return value for the whole
|
||
* comparison. If all the values found are equal, then the return is based
|
||
* on a comparison of the array lengths. Thus, two arrays are
|
||
* ``equal'' according to <code>Array#<=></code> if and only if they have
|
||
* the same length and the value of each element is equal to the
|
||
* value of the corresponding element in the other array.
|
||
... | ... | |
* 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.
|
||
*/
|
||
* == Creating Arrays
|
||
* A new array can be created by using the literal constructor
|
||
* <code>[]</code>. Arrays can be heterogenous, meaning that
|
||
* they can contain different types of objects. For example, the
|
||
* array below contains an Integer, a String and a Float:
|
||
* ary = [1, "two", 3.0] #=> [1, "two", 3.0]
|
||
* An array can also be created by explicitly calling +Array.new+ with zero,
|
||
* one or two arguments. If no arguments are supplied, an empty array gets
|
||
* created
|
||
* ary = Array.new #=> []
|
||
* The first optional argument to the constructor determines the initial size
|
||
* of the array. If only one argument is given, an array of that size
|
||
* gets created with each element set to nil.
|
||
* Array.new(3) #=> [nil, nil, nil]
|
||
* The second argument to the initializer can be an object of any type.
|
||
* This will populate the new array with identical "copies" of the same
|
||
* object, i.e. it references the same object. This is only recommended in
|
||
* cases when you need to instantiate arrays with natively immutable objects
|
||
* such +Symbols+, +Fixnums+, true/false, etc.
|
||
* arr = Array.new(3, true) #=> [true, true, true]
|
||
* To create arrays with non-identical copies of the same type of object, a
|
||
* block can be passed instead. This method is safe to use with mutable
|
||
* objects such as hashes, strings or other arrays:
|
||
* Array.new(4) { Hash.new } #=> [{}, {}, {}, {}]
|
||
* This is also a quick way to build up multi-dimensional arrays:
|
||
* empty_table = Array.new(3) { Array.new(3) }
|
||
* #=> [[nil, nil, nil], [nil, nil, nil], [nil, nil, nil]]
|
||
* == Example Usage
|
||
* In addition to the methods it mixes in through the Enumerable module, the
|
||
* Array class has proprietary methods for accessing, searching and otherwise
|
||
* manipulating arrays. Some of the more common ones are illustrated below.
|
||
* == Accessing Elements
|
||
* Elements in an array can be retrieved using the <code>Array#[]</code>
|
||
* method. It can take a single integer argument (a numeric index), a pair of
|
||
* arguments (start and length) or a range.
|
||
* === Single numeric index
|
||
* <code>Array#[]</code> called with a single numeric argument returns the
|
||
* element at the specified index. If an invalid index is referenced, nil
|
||
* is returned.
|
||
* arr = ['a', 'b', 'c']
|
||
* arr[1] #=> 'b'
|
||
* arr[100] #=> nil
|
||
* If a negative integer is passed to <code>Array#[]</code>, the element is
|
||
* retrieved by counting from the end. An index of -1 indicates the last
|
||
* element of the array, -2 is the next to last element in the array,
|
||
* and so on.
|
||
* arr = [1, 2, 3, 4, 5, 6]
|
||
* arr[-3] #=> 4
|
||
* arr[-100] #=> nil
|
||
* Another way to access a particular array element is by using the
|
||
* <code>Array#at</code> method
|
||
* arr.at(0) #=> 1
|
||
* === Retrieving a Subarray Using <code>Array[start, length]</code>
|
||
* By supplying two numeric parameters, it is possible to get back a
|
||
* consecutive subset of elements. The first integer represents
|
||
* the start index while the second counts the number of items from that
|
||
* start index:
|
||
* arr = ['a', 'b', 'c', 'd', 'e', 'f']
|
||
* arr[2, 3] #=> ['c', 'd', 'e']
|
||
* === Retrieving a Subarray Using a Range
|
||
* arr[1..4] #=> ['b', 'c', 'd', 'e']
|
||
* arr[3..100] #=> ['d', 'e', 'f']
|
||
* The +slice+ method works in an identical manner to <code>Array#[]</code>.
|
||
* The special methods +first+ and +last+ will return the first and last
|
||
* elements of an array, respectively.
|
||
* arr.first #=> 'a'
|
||
* arr.last #=> 'e'
|
||
* === Providing Fallbacks
|
||
* To raise an error for indices outside of the array bounds or else
|
||
* to provide a default value when that happens, you can use +fetch+:
|
||
* Fetch works just like <code>Array#[]</code> if a valid index gets supplied.
|
||
* arr = ['a', 'b', 'c', 'd', 'e', 'f']
|
||
* arr.fetch(4) #=> "c"
|
||
* With an invalid index it raises an +IndexError+
|
||
* arr.fetch(100) #=> IndexError: index 100 outside of array bounds: -6...6
|
||
* To prevent the error, you can supply a second argument which will act as a
|
||
* default value:
|
||
* arr.fetch(100, "oops") #=> "oops"
|
||
* If you call +fetch+ with a block as a second argument, it will execute the
|
||
* block which has access to the referenced index
|
||
* arr.fetch(100) {|i| puts "#{i} is out of bounds" }
|
||
* #=> "100 is out of bounds"
|
||
* == Obtaining Information about an Array
|
||
* Arrays keep track of their own length at all times. To query an array about
|
||
* the number of elements it contains, use +length+ or +count+
|
||
* browsers = ['Chrome', 'Firefox', 'Safari', 'Opera', 'IE']
|
||
* browsers.length #=> 5
|
||
* browsers.count #=> 5
|
||
* To check whether an array contains any elements at all
|
||
* browsers.empty? #=> false
|
||
* To check whether a particular item is included in the array
|
||
* browsers.include?('Konqueror') #=> false
|
||
* == Adding Items to Arrays
|
||
* Items can be added to the <b>end</b> of an array by using either +push+ or
|
||
* <code><<</code>
|
||
* arr = [1, 2, 3, 4]
|
||
* arr.push(5) #=> [1, 2, 3, 4, 5]
|
||
* arr << 6 #=> [1, 2, 3, 4, 5, 6]
|
||
* +unshift+ will add a new item to the <b>beginning</b> of an array.
|
||
* arr.unshift(0) #=> [0, 1, 2, 3, 4, 5, 6]
|
||
* With +insert+ you can add a new element to an array at any position.
|
||
* arr.insert(3, 'apple') #=> [0, 1, 2, 'apple', 3, 4, 5, 6]
|
||
* Using the +insert+ method, you can also insert multiple values at once:
|
||
* arr.insert(3, 'orange', 'pear', 'grapefruit')
|
||
* #=> [0, 1, 2, "orange", "pear", "grapefruit", "apple", 3, 4, 5, 6]
|
||
* == Removing Items from an Array
|
||
* The method +pop+ removes the <b>last element</b> in an array and also
|
||
* returns it:
|
||
* arr = [1, 2, 3, 4, 5, 6]
|
||
* arr.pop #=> 6
|
||
* arr #=> [1, 2, 3, 4, 5]
|
||
* To retrieve and at the same time remove the <b>first item</b>, you can use
|
||
* +shift+
|
||
* arr.shift #=> 1
|
||
* arr #=> [2, 3, 4, 5]
|
||
* To delete an element at a particular <b>index</b>
|
||
* arr.delete_at(2) #=> 4
|
||
* arr #=> [2, 3, 5]
|
||
* To delete a <b>particular element</b> anywhere in an array, use +delete+
|
||
* arr = [1, 2, 2, 3]
|
||
* arr.delete(2) #=> [1, 3]
|
||
* A useful method if you need to <b>remove +nil+ values</b> from an array is
|
||
* +compact+:
|
||
* arr = ['foo', 0, nil, 'bar', 7, 'baz', nil]
|
||
* arr.compact #=> ['foo', 0, 'bar', 7, 'baz']
|
||
* arr #=> ['foo', 0, nil, 'bar', 7, 'baz', nil]
|
||
* arr.compact! #=> ['foo', 0, 'bar', 7, 'baz']
|
||
* arr #=> ['foo', 0, 'bar', 7, 'baz']
|
||
* Another common need is to <b>remove duplicate elements</b> from an array.
|
||
* It has a non-destructive (+uniq+) and a destructive method (+uniq!+)
|
||
* arr = [2, 5, 6, 556, 6, 6, 8, 9, 0, 123, 556]
|
||
* arr.uniq #=> [2, 5, 6, 556, 8, 9, 0, 123]
|
||
* == Iterating over Arrays
|
||
* Like all classes that include the Enumerable module, +Array+ has an +each+
|
||
* method, which defines what elements should be iterated over and how. In
|
||
* case of <code>Array#each</code> all elements in the Array instance are
|
||
* yielded to the supplied block in sequence and only once. Note that this
|
||
* operation leaves the array unchanged.
|
||
* arr = [1, 2, 3, 4, 5]
|
||
* arr.each {|a| print a -= 10, " " } #-9 -8 -7 -6 -5 => [1, 2, 3, 4, 5]
|
||
* Another sometimes useful iterator is +reverse_each+ which will iterate over
|
||
* the elements in the array in reverse order.
|
||
* words = %w{rats live on no evil star}
|
||
* str = ""
|
||
* words.reverse_each {|word| str += "#{word.reverse} " }
|
||
* str #=> "rats live on no evil star"
|
||
* The +map+ method can be used to create a new array based on the original
|
||
* array, but with the values modified according to the supplied block:
|
||
* arr.map {|a| 2*a } #=> [2, 4, 6, 8, 10]
|
||
* arr #=> [1, 2, 3, 4, 5]
|
||
* arr.map! {|a| a**2 } #=> [1, 4, 9, 16, 25]
|
||
* arr #=> [1, 4, 9, 16, 25]
|
||
* == Selecting Items from an Array
|
||
*
|
||
* Elements can be selected from an array in a destructive or a
|
||
* non-destructive manner. While the destructive operations will modify the
|
||
* array they were called on, the non-destructive methods usually return a
|
||
* new array with the selected elements, but leave the original array
|
||
* unchanged.
|
||
* === Non-destructive Selection
|
||
* arr = [1, 2, 3, 4, 5, 6]
|
||
* arr.select {|a| a > 3 } #=> [4, 5, 6]
|
||
* arr.reject {|a| a < 3 } #=> [4, 5, 6]
|
||
* arr.drop_while {|a| a < 4 } #=> [4, 5, 6]
|
||
* arr #=> [1, 2, 3, 4, 5, 6]
|
||
* === Destructive Selection
|
||
* <code>Array#select!</code> and <code>Array#reject!</code> are the
|
||
* corresponding destructive methods to <code>Array#select</code> and
|
||
* <code>Array#reject</code>.
|
||
* Similar to +select+ vs. +reject+, +delete_if+ and +keep_if+ have the exact
|
||
* opposite result when supplied with the same block:
|
||
* arr.delete_if {|a| a < 4 } #=> [4, 5, 6]
|
||
* arr #=> [4, 5, 6]
|
||
*
|
||
* arr = [1, 2, 3, 4, 5, 6]
|
||
* arr.keep_if {|a| a < 4 } #=> [1, 2, 3]
|
||
* arr #=> [1, 2, 3]
|
||
*/
|
||
void
|
||
Init_Array(void)
|
||
... | ... | |
id_cmp = rb_intern("<=>");
|
||
sym_random = ID2SYM(rb_intern("random"));
|
||
}
|
||