0001-Improves-array-content-for-some-methods-and-examples.patch

Alvaro Pereyra Rabanal, 10/10/2011 03:25 AM

Download (5.75 KB)

View differences:

array.c
478 478
 *  call-seq:
479 479
 *     Array.try_convert(obj) -> array or nil
480 480
 *
481
 *  Try to convert <i>obj</i> into an array, using +to_ary+ method.
481
 *  Tries to convert <i>obj</i> into an array, using +to_ary+ method.
482 482
 *  Returns converted array or +nil+ if <i>obj</i> cannot be converted
483 483
 *  for any reason. This method can be used to check if an argument is an
484 484
 *  array.
......
506 506
 *     Array.new(array)
507 507
 *     Array.new(size) {|index| block }
508 508
 *
509
 *  Returns a new array. In the first form, the new array is
510
 *  empty. In the second it is created with _size_ copies of _obj_
511
 *  (that is, _size_ references to the same
512
 *  _obj_). The third form creates a copy of the array
509
 *  Returns a new array. In the first form, if no arguments 
510
 *  are sent, the new array will be empty. When they are sent,
511
 *  it is created with _size_ copies of _obj_. Take notice that
512
 *  all elements will reference the same object _obj_.
513
 * 
514
 *    Array.new(3, "Hi") 
515
 *    # => ["Hi", "Hi", "Hi"] 
516
 *
517
 *  The second form creates a copy of the array
513 518
 *  passed as a parameter (the array is generated by calling
514
 *  to_ary  on the parameter). In the last form, an array
515
 *  of the given size is created. Each element in this array is
516
 *  calculated by passing the element's index to the given block and
517
 *  storing the return value.
519
 *  to_ary  on the parameter). 
520
 * 
521
 *    first_array = ["Matz", "Guido"]
522
 *
523
 *    second_array = Array.new(first_array) 
524
 *    # => ["Matz", "Guido"]
525
 *
526
 *  In the last form, an array of the given size is created. 
527
 *  Each element in this array is created by passing the element's index
528
 *  to the given block and storing the return value.
518 529
 *
519
 *     Array.new
520
 *     Array.new(2)
521
 *     Array.new(5, "A")
530
 *    Array.new(3){ |index| index ** 2 }
531
 *    # => [0, 1, 4]
522 532
 *
523
 *     # only one copy of the object is created
524
 *     a = Array.new(2, Hash.new)
533
 *  == Common gotchas
534
 *
535
 *  When sending the second parameter, the same initialized
536
 *  object will be used as the value for all the array
537
 *  elements
538
 * 
539
 *     a = Array.new(2, Hash.new) 
540
 *     # => [{}, {}]
541
 * 
525 542
 *     a[0]['cat'] = 'feline'
526
 *     a
543
 *     a # => [{"cat"=>"feline"}, {"cat"=>"feline"}]
544
 *
527 545
 *     a[1]['cat'] = 'Felix'
528
 *     a
546
 *     a # => [{"cat"=>"Felix"}, {"cat"=>"Felix"}]
547
 *
548
 *  Since all the Array elements store the same hash object changes to 
549
 *  one of them will affect them all.
550
 *  
551
 *  If multiple copies are what you want, you should use the block 
552
 *  version which uses the result of that block each time an element
553
 *  of the array needs to be initialized:
529 554
 *
530
 *     # here multiple copies are created
531 555
 *     a = Array.new(2) { Hash.new }
532 556
 *     a[0]['cat'] = 'feline'
533
 *     a
534
 *
535
 *     squares = Array.new(5) {|i| i*i}
536
 *     squares
557
 *     a # => [{"cat"=>"feline"}, {}]
537 558
 *
538
 *     copy = Array.new(squares)
539 559
 */
540 560

  
541 561
static VALUE
......
1208 1228
 *  If neither block nor argument is given, an enumerator is returned instead.
1209 1229
 *
1210 1230
 *     a = [ "a", "b", "b", "b", "c" ]
1211
 *     a.rindex("b")        #=> 3
1212
 *     a.rindex("z")        #=> nil
1213
 *     a.rindex{|x|x=="b"}  #=> 3
1231
 *     a.rindex("b")           #=> 3
1232
 *     a.rindex("z")           #=> nil
1233
 *     a.rindex{ |x| x=="b" }  #=> 3
1214 1234
 */
1215 1235

  
1216 1236
static VALUE
......
1945 1965
 *
1946 1966
 *     a = [ "a", "b", "c", "d" ]
1947 1967
 *     a.rotate!        #=> ["b", "c", "d", "a"]
1948
 *     a                #=> ["b", "c", "d", "a"]
1949 1968
 *     a.rotate!(2)     #=> ["d", "a", "b", "c"]
1950 1969
 *     a.rotate!(-3)    #=> ["a", "b", "c", "d"]
1951 1970
 */
......
3509 3528
 *  call-seq:
3510 3529
 *     ary.uniq! -> ary or nil
3511 3530
 *
3512
 *  Removes duplicate elements from +self+.
3531
 *  Removes duplicate elements from +self+. If a block is given,
3532
 *  it will use the return value of the block for comparison.
3513 3533
 *  Returns <code>nil</code> if no changes are made (that is, no
3514 3534
 *  duplicates are found).
3515 3535
 *
3516 3536
 *     a = [ "a", "a", "b", "b", "c" ]
3517
 *     a.uniq!   #=> ["a", "b", "c"]
3537
 *     a.uniq!   # => ["a", "b", "c"]
3538
 *
3518 3539
 *     b = [ "a", "b", "c" ]
3519
 *     b.uniq!   #=> nil
3520
 *     c = [ "a:def", "a:xyz", "b:abc", "b:xyz", "c:jkl" ]
3521
 *     c.uniq! {|s| s[/^\w+/]}  #=> [ "a:def", "b:abc", "c:jkl" ]
3540
 *     b.uniq!   # => nil
3541
 *
3542
 *     c = [["student","sam"], ["student","george"], ["teacher","matz"]]
3543
 *     c.uniq!{ |s| s.first } # => [["student", "sam"], ["teacher", "matz"]] 
3544
 * 
3522 3545
 */
3523 3546

  
3524 3547
static VALUE
......
3565 3588
 *  call-seq:
3566 3589
 *     ary.uniq   -> new_ary
3567 3590
 *
3568
 *  Returns a new array by removing duplicate values in +self+.
3591
 *  Returns a new array by removing duplicate values in +self+. If a block
3592
 *  is given, it will use the return value of the block for comparison.
3569 3593
 *
3570 3594
 *     a = [ "a", "a", "b", "b", "c" ]
3571
 *     a.uniq   #=> ["a", "b", "c"]
3572
 *     c = [ "a:def", "a:xyz", "b:abc", "b:xyz", "c:jkl" ]
3573
 *     c.uniq {|s| s[/^\w+/]}  #=> [ "a:def", "b:abc", "c:jkl" ]
3595
 *     a.uniq   # => ["a", "b", "c"]
3596
 *
3597
 *     b = [["student","sam"], ["student","george"], ["teacher","matz"]]
3598
 *     b.uniq{ |s| s.first } # => [["student", "sam"], ["teacher", "matz"]] 
3599
 * 
3574 3600
 */
3575 3601

  
3576 3602
static VALUE
3577
-