Project

General

Profile

Feature #6517 ยป 0001-Array-documentation-examples-and-formatting.patch

zzak (Zachary Scott), 05/31/2012 09:28 AM

View differences:

array.c
274 274
    }
275 275
}
276 276

  
277
/*
278
 *  call-seq:
279
 *      ary.freeze -> ary
280
 *
281
 *  Calls Object#freeze on +ary+ to prevent any further
282
 *  modification. A +RuntimeError+ will be raised if a modification
283
 *  attempt is made.
284
 * 
285
 */
286

  
277 287
VALUE
278 288
rb_ary_freeze(VALUE ary)
279 289
{
......
284 294
 *  call-seq:
285 295
 *     ary.frozen?  -> true or false
286 296
 *
287
 *  Return <code>true</code> if this array is frozen (or temporarily frozen
288
 *  while being sorted).
297
 *  Return +true+ if this array is frozen (or temporarily frozen
298
 *  while being sorted). See also Object#frozen?
289 299
 */
290 300

  
291 301
static VALUE
......
774 784
 *
775 785
 *  Append---Pushes the given object(s) on to the end of this array. This
776 786
 *  expression returns the array itself, so several appends
777
 *  may be chained together.
787
 *  may be chained together. See also Array#pop for the opposite
788
 *  effect.
778 789
 *
779 790
 *     a = [ "a", "b", "c" ]
780 791
 *     a.push("d", "e", "f")
781 792
 *             #=> ["a", "b", "c", "d", "e", "f"]
793
 *     [1, 2, 3,].push(4).push(5)
794
 *             #=> [1, 2, 3, 4, 5]
782 795
 */
783 796

  
784 797
static VALUE
......
810 823
 *     ary.pop(n) -> new_ary
811 824
 *
812 825
 *  Removes the last element from +self+ and returns it, or
813
 *  <code>nil</code> if the array is empty.
826
 *  +nil+ if the array is empty.
814 827
 *
815
 *  If a number +n+ is given, returns an array of the last n elements
816
 *  (or less) just like <code>array.slice!(-n, n)</code> does.
828
 *  If a number +n+ is given, returns an array of the last +n+ elements
829
 *  (or less) just like <code>array.slice!(-n, n)</code> does. See also
830
 *  Array#push for the opposite effect.
817 831
 *
818 832
 *     a = [ "a", "b", "c", "d" ]
819 833
 *     a.pop     #=> "d"
......
870 884
 *     ary.shift(n) -> new_ary
871 885
 *
872 886
 *  Returns the first element of +self+ and removes it (shifting all
873
 *  other elements down by one). Returns <code>nil</code> if the array
887
 *  other elements down by one). Returns +nil+ if the array
874 888
 *  is empty.
875 889
 *
876
 *  If a number +n+ is given, returns an array of the first n elements
877
 *  (or less) just like <code>array.slice!(0, n)</code> does.
890
 *  If a number +n+ is given, returns an array of the first +n+ elements
891
 *  (or less) just like <code>array.slice!(0, n)</code> does. With +ary+
892
 *  containing only the remainder elements, not including what was shifted to
893
 *  +new_ary+. See also Array#unshift for the opposite effect.
878 894
 *
879 895
 *     args = [ "-m", "-q", "filename" ]
880 896
 *     args.shift     #=> "-m"
......
916 932
 *  call-seq:
917 933
 *     ary.unshift(obj, ...)  -> ary
918 934
 *
919
 *  Prepends objects to the front of +self+,
920
 *  moving other elements upwards.
935
 *  Prepends objects to the front of +self+, moving other elements upwards.
936
 *  See also Array#shift for the opposite effect.
921 937
 *
922 938
 *     a = [ "b", "c", "d" ]
923 939
 *     a.unshift("a")   #=> ["a", "b", "c", "d"]
......
1056 1072
 *  call-seq:
1057 1073
 *     ary.at(index)   ->   obj  or nil
1058 1074
 *
1059
 *  Returns the element at +index+. A
1060
 *  negative index counts from the end of +self+.  Returns +nil+
1061
 *  if the index is out of range. See also <code>Array#[]</code>.
1075
 *  Returns the element at +index+. A negative index counts from the end of
1076
 *  +self+. Returns +nil+ if the index is out of range. See also
1077
 *  <code>Array#[]</code>.
1062 1078
 *
1063 1079
 *     a = [ "a", "b", "c", "d", "e" ]
1064 1080
 *     a.at(0)     #=> "a"
......
1078 1094
 *
1079 1095
 *  Returns the first element, or the first +n+ elements, of the array.
1080 1096
 *  If the array is empty, the first form returns <code>nil</code>, and the
1081
 *  second form returns an empty array.
1097
 *  second form returns an empty array. See also <code>Array#last</code> for
1098
 *  the opposite effect.
1082 1099
 *
1083 1100
 *     a = [ "q", "r", "s", "t" ]
1084 1101
 *     a.first     #=> "q"
......
1103 1120
 *     ary.last(n)  ->  new_ary
1104 1121
 *
1105 1122
 *  Returns the last element(s) of +self+. If the array is empty,
1106
 *  the first form returns <code>nil</code>.
1123
 *  the first form returns <code>nil</code>. 
1124
 *
1125
 *  See also <code>Array#first</code> for the opposite effect.
1107 1126
 *
1108 1127
 *     a = [ "w", "x", "y", "z" ]
1109 1128
 *     a.last     #=> "z"
......
1128 1147
 *     ary.fetch(index, default )          -> obj
1129 1148
 *     ary.fetch(index) {|index| block }   -> obj
1130 1149
 *
1131
 *  Tries to return the element at position +index+. If the index lies outside
1132
 *  the array, the first form throws an IndexError exception, the second form
1133
 *  returns +default+, and the third form returns the value of invoking the
1134
 *  block, passing in the index. Negative values of +index+ count from the end
1135
 *  of the array.
1136
 *
1137 1150
 *  Tries to return the element at position +index+, but throws an IndexError
1138
 *  exception if the referenced index lies outside of the array bounds.  This
1151
 *  exception if the referenced _index_ lies outside of the array bounds.  This
1139 1152
 *  error can be prevented by supplying a second argument, which will act as a
1140
 *  +default+ value.  Alternatively, if the second argument is a block it will
1141
 *  only be executed when an invalid index is referenced.  Negative values of
1142
 *  +index+ count from the end of the array.
1153
 *  +default+ value. 
1154
 *
1155
 *  Alternatively, if the second argument is a block it will only be executed
1156
 *  when an invalid _index_ is referenced.  Negative values of +index+ count
1157
 *  from the end of the array.
1143 1158
 *
1144 1159
 *     a = [ 11, 22, 33, 44 ]
1145 1160
 *     a.fetch(1)               #=> 22
......
1181 1196
 *  call-seq:
1182 1197
 *     ary.index(obj)           ->  int or nil
1183 1198
 *     ary.index {|item| block} ->  int or nil
1184
 *     ary.index                ->  an_enumerator
1199
 *     ary.index                ->  Enumerator
1200
 *
1201
 *  Returns the _index_ of the first object in +self+ such that the object is
1202
 *  <code>==</code> to +obj+.
1203
 *
1204
 *  If a block is given instead of an argument, returns the _index_ of first
1205
 *  the object for which the block returns +true+.  Returns +nil+ if no match
1206
 *  is found.
1185 1207
 *
1186
 *  Returns the index of the first object in +self+ such that the object is
1187
 *  <code>==</code> to +obj+. If a block is given instead of an
1188
 *  argument, returns index of first object for which <em>block</em> is true.
1189
 *  Returns <code>nil</code> if no match is found.
1190
 *  See also <code>Array#rindex</code>.
1208
 *  See also Array#rindex.
1191 1209
 *
1192
 *  If neither block nor argument is given, an enumerator is returned instead.
1210
 *  An Enumerator is returned if neither a  block nor argument is given.
1193 1211
 *
1194 1212
 *     a = [ "a", "b", "c" ]
1195 1213
 *     a.index("b")        #=> 1
1196 1214
 *     a.index("z")        #=> nil
1197 1215
 *     a.index{|x|x=="b"}  #=> 1
1198 1216
 *
1199
 *  This is an alias of <code>#find_index</code>.
1217
 *  This is an alias of Array#find_index.
1200 1218
 */
1201 1219

  
1202 1220
static VALUE
......
1228 1246
 *  call-seq:
1229 1247
 *     ary.rindex(obj)           ->  int or nil
1230 1248
 *     ary.rindex {|item| block} ->  int or nil
1231
 *     ary.rindex                ->  an_enumerator
1249
 *     ary.rindex                ->  Enumerator
1250
 *
1251
 *  Returns the _index_ of the last object in +self+ <code>==</code> to +obj+.
1252
 *
1253
 *  If a block is given instead of an argument, returns _index_ of first object
1254
 *  for which block returns +true+, starting from the last object.
1255
 *
1256
 *  Returns +nil+ if no match is found.
1232 1257
 *
1233
 *  Returns the index of the last object in +self+
1234
 *  <code>==</code> to +obj+. If a block is given instead of an
1235
 *  argument, returns index of first object for which <em>block</em> is
1236
 *  true, starting from the last object.
1237
 *  Returns <code>nil</code> if no match is found.
1238 1258
 *  See also Array#index.
1239 1259
 *
1240
 *  If neither block nor argument is given, an enumerator is returned instead.
1260
 *  If neither block nor argument is given, an Enumerator is returned instead.
1241 1261
 *
1242 1262
 *     a = [ "a", "b", "b", "b", "c" ]
1243 1263
 *     a.rindex("b")             #=> 3
......
1409 1429
 *     ary[start, length] = obj or other_ary or nil  ->  obj or other_ary or nil
1410 1430
 *     ary[range]         = obj or other_ary or nil  ->  obj or other_ary or nil
1411 1431
 *
1412
 *  Element Assignment---Sets the element at +index+,
1413
 *  or replaces a subarray starting at +start+ and
1414
 *  continuing for +length+ elements, or replaces a subarray
1415
 *  specified by +range+.  If indices are greater than
1416
 *  the current capacity of the array, the array grows
1417
 *  automatically. A negative indices will count backward
1418
 *  from the end of the array. Inserts elements if +length+ is
1419
 *  zero. An IndexError is raised if a negative index points
1420
 *  past the beginning of the array. See also
1421
 *  Array#push, and Array#unshift.
1432
 *  Element Assignment---Sets the element at _index_, or replaces a subarray
1433
 *  from _start_ for _length_ elements, or replaces a subarray specified by
1434
 *  _range_. 
1435
 *
1436
 *  If indices are greater than the current capacity of the array, the array
1437
 *  grows automatically. A negative indices will count backward from the end of
1438
 *  the array. Inserts elements if +length+ is zero.
1439
 *
1440
 *  An IndexError is raised if a negative index points past the beginning of
1441
 *  the array.
1442
 *
1443
 *  See also Array#push, and Array#unshift.
1422 1444
 *
1423 1445
 *     a = Array.new
1424 1446
 *     a[4] = "4";                 #=> [nil, nil, nil, nil, "4"]
......
1465 1487
 *  call-seq:
1466 1488
 *     ary.insert(index, obj...)  -> ary
1467 1489
 *
1468
 *  Inserts the given values before the element with the given index
1469
 *  (which may be negative).
1490
 *  Inserts the given values before the element with the given _index_.
1491
 *
1492
 *  Negative indices count backwards from the end of the array, 
1493
 *  where +-1+ is the last element.
1470 1494
 *
1471 1495
 *     a = %w{ a b c d }
1472 1496
 *     a.insert(2, 99)         #=> ["a", "b", 99, "c", "d"]
......
1495 1519
/*
1496 1520
 *  call-seq:
1497 1521
 *     ary.each {|item| block }   -> ary
1498
 *     ary.each                   -> an_enumerator
1522
 *     ary.each                   -> Enumerator
1499 1523
 *
1500
 *  Calls +block+ once for each element in +self+, passing that
1501
 *  element as a parameter.
1524
 *  Calls the given block once for each element in +self+, passing that element
1525
 *  as a parameter.
1502 1526
 *
1503
 *  If no block is given, an enumerator is returned instead.
1527
 *  An Enumerator is returned instead, if no block is given.
1504 1528
 *
1505 1529
 *     a = [ "a", "b", "c" ]
1506 1530
 *     a.each {|x| print x, " -- " }
......
1526 1550
/*
1527 1551
 *  call-seq:
1528 1552
 *     ary.each_index {|index| block }  -> ary
1529
 *     ary.each_index                   -> an_enumerator
1553
 *     ary.each_index                   -> Enumerator
1530 1554
 *
1531
 *  Same as Array#each, but passes the index of the element instead of the
1555
 *  Same as Array#each, but passes the _index_ of the element instead of the
1532 1556
 *  element itself.
1533 1557
 *
1534
 *  If no block is given, an enumerator is returned instead.
1558
 *  An Enumerator is returned instead, if no block is given.
1535 1559
 *
1536 1560
 *
1537 1561
 *     a = [ "a", "b", "c" ]
......
1557 1581
/*
1558 1582
 *  call-seq:
1559 1583
 *     ary.reverse_each {|item| block }   -> ary
1560
 *     ary.reverse_each                   -> an_enumerator
1584
 *     ary.reverse_each                   -> Enumerator
1561 1585
 *
1562 1586
 *  Same as Array#each, but traverses +self+ in reverse order.
1563 1587
 *
......
1592 1616
 *  Returns the number of elements in +self+. May be zero.
1593 1617
 *
1594 1618
 *     [ 1, 2, 3, 4, 5 ].length   #=> 5
1619
 *     [].length                  #=> 0
1595 1620
 */
1596 1621

  
1597 1622
static VALUE
......
1605 1630
 *  call-seq:
1606 1631
 *     ary.empty?   -> true or false
1607 1632
 *
1608
 *  Returns <code>true</code> if +self+ contains no elements.
1633
 *  Returns +true+ if +self+ contains no elements.
1609 1634
 *
1610 1635
 *     [].empty?   #=> true
1611 1636
 */
......
1771 1796

  
1772 1797
/*
1773 1798
 *  call-seq:
1774
 *     ary.join(sep=$,)    -> str
1799
 *     ary.join(separator=$)    -> str
1775 1800
 *
1776 1801
 *  Returns a string created by converting each element of the array to
1777
 *  a string, separated by +sep+.
1802
 *  a string, separated by the given +separator+.
1778 1803
 *
1779 1804
 *     [ "a", "b", "c" ].join        #=> "abc"
1780 1805
 *     [ "a", "b", "c" ].join("-")   #=> "a-b-c"
......
1817 1842

  
1818 1843
/*
1819 1844
 *  call-seq:
1820
 *     ary.to_s -> string
1821 1845
 *     ary.inspect  -> string
1846
 *     ary.to_s     -> string
1822 1847
 *
1823 1848
 *  Creates a string representation of +self+.
1849
 *
1850
 *     [ "a", "b", "c" ].to_s     #=> "[\"a\", \"b\", \"c\"]"
1824 1851
 */
1825 1852

  
1826 1853
static VALUE
......
1840 1867
 *  call-seq:
1841 1868
 *     ary.to_a     -> ary
1842 1869
 *
1843
 *  Returns +self+. If called on a subclass of Array, converts
1844
 *  the receiver to an Array object.
1870
 *  Returns +self+.
1871
 *
1872
 *  If called on a subclass of Array, converts the receiver to an Array object.
1845 1873
 */
1846 1874

  
1847 1875
static VALUE
......
1912 1940

  
1913 1941
/*
1914 1942
 *  call-seq:
1915
 *     ary.reverse -> new_ary
1943
 *     ary.reverse    -> new_ary
1916 1944
 *
1917 1945
 *  Returns a new array containing +self+'s elements in reverse order.
1918 1946
 *
......
1964 1992

  
1965 1993
/*
1966 1994
 *  call-seq:
1967
 *     ary.rotate!(cnt=1) -> ary
1995
 *     ary.rotate!(count=1)   -> ary
1968 1996
 *
1969
 *  Rotates +self+ in place so that the element at +cnt+ comes first,
1970
 *  and returns +self+.  If +cnt+ is negative then it rotates in
1971
 *  the opposite direction.
1997
 *  Rotates +self+ in place so that the element at +count+ comes first, and
1998
 *  returns +self+. 
1999
 *
2000
 *  If +count+ is negative then it rotates in the opposite direction, starting
2001
 *  from the end of the array where +-1+ is the last element.
1972 2002
 *
1973 2003
 *     a = [ "a", "b", "c", "d" ]
1974 2004
 *     a.rotate!        #=> ["b", "c", "d", "a"]
......
1993 2023

  
1994 2024
/*
1995 2025
 *  call-seq:
1996
 *     ary.rotate(cnt=1) -> new_ary
2026
 *     ary.rotate(count=1)    -> new_ary
2027
 *
2028
 *  Returns new array by rotating +self+ so that the element at +count+ is the
2029
 *  first element of the new array.
1997 2030
 *
1998
 *  Returns new array by rotating +self+ so that the element at
1999
 *  +cnt+ in +self+ is the first element of the new array. If +cnt+
2000
 *  is negative then it rotates in the opposite direction.
2031
 *  If +count+ is negative then it rotates in the opposite direction, starting
2032
 *  from the end of +self+ where +-1+ is the last element.
2001 2033
 *
2002 2034
 *     a = [ "a", "b", "c", "d" ]
2003 2035
 *     a.rotate         #=> ["b", "c", "d", "a"]
......
2106 2138
 *     ary.sort!                   -> ary
2107 2139
 *     ary.sort! {| a,b | block }  -> ary
2108 2140
 *
2109
 *  Sorts +self+. Comparisons for
2110
 *  the sort will be done using the <code><=></code> operator or using
2111
 *  an optional code block. The block implements a comparison between
2112
 *  +a+ and +b+, returning -1, 0, or +1. See also
2113
 *  Enumerable#sort_by.
2141
 *  Sorts +self+. 
2142
 *
2143
 *  Comparisons for the sort will be done using the <code><=></code> operator
2144
 *  or using an optional code block.
2145
 *
2146
 *  The given block implements a comparison between +a+ and +b+, returning
2147
 *  +-1+, +0+, or ++1+.
2148
 *
2149
 *  See also Enumerable#sort_by.
2114 2150
 *
2115 2151
 *     a = [ "d", "a", "e", "c", "b" ]
2116 2152
 *     a.sort!                    #=> ["a", "b", "c", "d", "e"]
......
2182 2218
 *     ary.sort                   -> new_ary
2183 2219
 *     ary.sort {| a,b | block }  -> new_ary
2184 2220
 *
2185
 *  Returns a new array created by sorting +self+. Comparisons for
2186
 *  the sort will be done using the <code><=></code> operator or using
2187
 *  an optional code block. The block implements a comparison between
2188
 *  +a+ and +b+, returning -1, 0, or +1. See also
2189
 *  Enumerable#sort_by.
2221
 *  Returns a new array created by sorting +self+.
2222
 *
2223
 *  Comparisons for the sort will be done using the <code><=></code> operator
2224
 *  or using an optional code block.
2225
 *
2226
 *  The given block implements a comparison between +a+ and +b+, returning
2227
 *  +-1+, +0+, or ++1+.
2228
 *
2229
 *  See also Enumerable#sort_by.
2190 2230
 *
2191 2231
 *     a = [ "d", "a", "e", "c", "b" ]
2192 2232
 *     a.sort                    #=> ["a", "b", "c", "d", "e"]
......
2211 2251
/*
2212 2252
 *  call-seq:
2213 2253
 *     ary.sort_by! {| obj | block }    -> ary
2214
 *     ary.sort_by!                     -> an_enumerator
2254
 *     ary.sort_by!                     -> Enumerator
2215 2255
 *
2216 2256
 *  Sorts +self+ in place using a set of keys generated by mapping the
2217 2257
 *  values in +self+ through the given block.
2218 2258
 *
2219
 *  If no block is given, an enumerator is returned instead.
2259
 *  If no block is given, an Enumerator is returned instead.
2220 2260
 *
2221 2261
 */
2222 2262

  
......
2237 2277
 *  call-seq:
2238 2278
 *     ary.collect {|item| block }  -> new_ary
2239 2279
 *     ary.map     {|item| block }  -> new_ary
2240
 *     ary.collect                  -> an_enumerator
2241
 *     ary.map                      -> an_enumerator
2280
 *     ary.collect                  -> Enumerator
2281
 *     ary.map                      -> Enumerator
2282
 *
2283
 *  Invokes the given block once for each element of +self+.
2284
 *
2285
 *  Creates a new array containing the values returned by the given block.
2242 2286
 *
2243
 *  Invokes +block+ once for each element of +self+. Creates a
2244
 *  new array containing the values returned by the block.
2245 2287
 *  See also Enumerable#collect.
2246 2288
 *
2247
 *  If no block is given, an enumerator is returned instead.
2289
 *  If no block is given, an Enumerator is returned instead.
2248 2290
 *
2249 2291
 *     a = [ "a", "b", "c", "d" ]
2250 2292
 *     a.map {|x| x + "!" }   #=> ["a!", "b!", "c!", "d!"]
......
2270 2312
 *  call-seq:
2271 2313
 *     ary.collect! {|item| block }   -> ary
2272 2314
 *     ary.map!     {|item| block }   -> ary
2273
 *     ary.collect                    -> an_enumerator
2274
 *     ary.map                        -> an_enumerator
2315
 *     ary.collect                    -> Enumerator
2316
 *     ary.map                        -> Enumerator
2317
 *
2318
 *  Invokes the given block once for each element of +self+, replacing the
2319
 *  element with the value returned by the block.
2275 2320
 *
2276
 *  Invokes the block once for each element of +self+, replacing the
2277
 *  element with the value returned by +block+.
2278 2321
 *  See also Enumerable#collect.
2279 2322
 *
2280
 *  If no block is given, an enumerator is returned instead.
2323
 *  If no block is given, an Enumerator is returned instead.
2281 2324
 *
2282 2325
 *     a = [ "a", "b", "c", "d" ]
2283 2326
 *     a.map! {|x| x + "!" }
......
2329 2372
 *  call-seq:
2330 2373
 *     ary.values_at(selector,... )  -> new_ary
2331 2374
 *
2332
 *  Returns an array containing the elements in
2333
 *  +self+ corresponding to the given selector(s). The selectors
2334
 *  may be either integer indices or ranges.
2375
 *  Returns an array containing the elements in +self+ corresponding to the
2376
 *  given _selector(s)_.
2377
 *
2378
 *  The selectors may be either integer indices or ranges.
2379
 *
2335 2380
 *  See also Array#select.
2336 2381
 *
2337 2382
 *     a = %w{ a b c d e f }
......
2351 2396
/*
2352 2397
 *  call-seq:
2353 2398
 *     ary.select {|item| block } -> new_ary
2354
 *     ary.select                 -> an_enumerator
2399
 *     ary.select                 -> Enumerator
2355 2400
 *
2356
 *  Invokes the block passing in successive elements from +self+,
2357
 *  returning an array containing those elements for which the block
2358
 *  returns a true value (equivalent to Enumerable#select).
2401
 *  Invokes the given block passing in successive elements from +self+,
2402
 *  returning an array containing those elements for which the block returns
2403
 *  a +true+ value.
2359 2404
 *
2360
 *  If no block is given, an enumerator is returned instead.
2405
 *  See also Enumerable#select.
2406
 *
2407
 *  If no block is given, an Enumerator is returned instead.
2361 2408
 *
2362 2409
 *     a = %w{ a b c d e f }
2363 2410
 *     a.select {|v| v =~ /[aeiou]/}   #=> ["a", "e"]
......
2382 2429
/*
2383 2430
 *  call-seq:
2384 2431
 *     ary.select! {|item| block } -> ary or nil
2385
 *     ary.select!                 -> an_enumerator
2432
 *     ary.select!                 -> Enumerator
2433
 *
2434
 *  Invokes the given block passing in successive elements from +self+,
2435
 *  deleting elements for which the block returns a +false+ value.
2436
 *
2437
 *  If changes were made, it will return +self+, otherwise it returns +nil+.
2386 2438
 *
2387
 *  Invokes the block passing in successive elements from
2388
 *  +self+, deleting elements for which the block returns a
2389
 *  false value. It returns +self+ if changes were made,
2390
 *  otherwise it returns <code>nil</code>.
2391 2439
 *  See also Array#keep_if
2392 2440
 *
2393
 *  If no block is given, an enumerator is returned instead.
2441
 *  If no block is given, an Enumerator is returned instead.
2394 2442
 *
2395 2443
 */
2396 2444

  
......
2419 2467
/*
2420 2468
 *  call-seq:
2421 2469
 *     ary.keep_if {|item| block } -> ary
2422
 *     ary.keep_if                 -> an_enumerator
2470
 *     ary.keep_if                 -> Enumerator
2471
 *
2472
 *  Deletes every element of +self+ for which the given block evaluates to
2473
 *  +false+.
2423 2474
 *
2424
 *  Deletes every element of +self+ for which +block+ evaluates
2425
 *  to false.
2426 2475
 *  See also Array#select!
2427 2476
 *
2428
 *  If no block is given, an enumerator is returned instead.
2477
 *  If no block is given, an Enumerator is returned instead.
2429 2478
 *
2430 2479
 *     a = %w{ a b c d e f }
2431 2480
 *     a.keep_if {|v| v =~ /[aeiou]/}   #=> ["a", "e"]
......
2445 2494
 *     ary.delete(obj) { block }  -> obj or nil
2446 2495
 *
2447 2496
 *  Deletes items from +self+ that are equal to +obj+.
2448
 *  If any items are found, returns +obj+.   If
2449
 *  the item is not found, returns <code>nil</code>. If the optional
2450
 *  code block is given, returns the result of +block+ if the item
2451
 *  is not found.  (To remove <code>nil</code> elements and
2452
 *  get an informative return value, use #compact!)
2497
 *
2498
 *  If any items are found, returns +obj+, otherwise +nil+ is returned instead.
2499
 *
2500
 *  If the optional code block is given, the result of the block is returned if
2501
 *  the item is not found.  (To remove +nil+ elements and get an informative
2502
 *  return value, use Array#compact!)
2453 2503
 *
2454 2504
 *     a = [ "a", "b", "b", "b", "c" ]
2455 2505
 *     a.delete("b")                   #=> "b"
......
2520 2570
 *  call-seq:
2521 2571
 *     ary.delete_at(index)  -> obj or nil
2522 2572
 *
2523
 *  Deletes the element at the specified index, returning that element,
2524
 *  or <code>nil</code> if the index is out of range. See also
2525
 *  Array#slice!.
2573
 *  Deletes the element at the specified +index+, returning that element, or
2574
 *  +nil+ if the +index+ is out of range.
2575
 *
2576
 *  See also Array#slice!
2526 2577
 *
2527 2578
 *     a = ["ant", "bat", "cat", "dog"]
2528 2579
 *     a.delete_at(2)    #=> "cat"
......
2542 2593
 *     ary.slice!(start, length) -> new_ary or nil
2543 2594
 *     ary.slice!(range)         -> new_ary or nil
2544 2595
 *
2545
 *  Deletes the element(s) given by an index (optionally with a length)
2546
 *  or by a range. Returns the deleted object (or objects), or
2547
 *  <code>nil</code> if the index is out of range.
2596
 *  Deletes the element(s) given by an +index+ (optionally with a +length+) or
2597
 *  by a +range+.
2598
 *
2599
 *  Returns the deleted object (or objects), or +nil+ if the +index+ is out of
2600
 *  range.
2548 2601
 *
2549 2602
 *     a = [ "a", "b", "c" ]
2550 2603
 *     a.slice!(1)     #=> "b"
......
2643 2696
/*
2644 2697
 *  call-seq:
2645 2698
 *     ary.reject! {|item| block }  -> ary or nil
2646
 *     ary.reject!                  -> an_enumerator
2699
 *     ary.reject!                  -> Enumerator
2700
 *
2701
 *  Equivalent to Array#delete_if, deleting elements from +self+ for which the
2702
 *  block evaluates to +true+, but returns +nil+ if no changes were made.
2703
 *
2704
 *  The array is changed instantly every time the block is called, not after the iteration is over.
2647 2705
 *
2648
 *  Equivalent to Array#delete_if, deleting elements from
2649
 *  +self+ for which the block evaluates to true, but returns
2650
 *  <code>nil</code> if no changes were made.
2651
 *  The array is changed instantly every time the block is called and
2652
 *  not after the iteration is over.
2653 2706
 *  See also Enumerable#reject and Array#delete_if.
2654 2707
 *
2655
 *  If no block is given, an enumerator is returned instead.
2708
 *  If no block is given, an Enumerator is returned instead.
2656 2709
 *
2657 2710
 */
2658 2711

  
......
2666 2719
/*
2667 2720
 *  call-seq:
2668 2721
 *     ary.reject {|item| block }  -> new_ary
2669
 *     ary.reject                  -> an_enumerator
2722
 *     ary.reject                  -> Enumerator
2723
 *
2724
 *  Returns a new array containing the items in +self+ for which the given
2725
 *  block is not +true+.
2670 2726
 *
2671
 *  Returns a new array containing the items in +self+
2672
 *  for which the block is not true.
2673 2727
 *  See also Array#delete_if
2674 2728
 *
2675
 *  If no block is given, an enumerator is returned instead.
2729
 *  If no block is given, an Enumerator is returned instead.
2676 2730
 *
2677 2731
 */
2678 2732

  
......
2690 2744
/*
2691 2745
 *  call-seq:
2692 2746
 *     ary.delete_if {|item| block }  -> ary
2693
 *     ary.delete_if                  -> an_enumerator
2747
 *     ary.delete_if                  -> Enumerator
2748
 *
2749
 *  Deletes every element of +self+ for which block evaluates to +true+.
2750
 *
2751
 *  The array is changed instantly every time the block is called, not after
2752
 *  the iteration is over.
2694 2753
 *
2695
 *  Deletes every element of +self+ for which +block+ evaluates
2696
 *  to true.
2697
 *  The array is changed instantly every time the block is called and
2698
 *  not after the iteration is over.
2699 2754
 *  See also Array#reject!
2700 2755
 *
2701
 *  If no block is given, an enumerator is returned instead.
2756
 *  If no block is given, an Enumerator is returned instead.
2702 2757
 *
2703 2758
 *     a = [ "a", "b", "c" ]
2704 2759
 *     a.delete_if {|x| x >= "b" }   #=> ["a"]
......
2740 2795
 *     ary.zip(arg, ...)                   -> new_ary
2741 2796
 *     ary.zip(arg, ...) {| arr | block }  -> nil
2742 2797
 *
2743
 *  Converts any arguments to arrays, then merges elements of
2744
 *  +self+ with corresponding elements from each argument. This
2745
 *  generates a sequence of <code>self.size</code> <em>n</em>-element
2746
 *  arrays, where <em>n</em> is one more that the count of arguments. If
2747
 *  the size of any argument is less than <code>enumObj.size</code>,
2748
 *  <code>nil</code> values are supplied. If a block is given, it is
2749
 *  invoked for each output array, otherwise an array of arrays is
2750
 *  returned.
2798
 *  Converts any arguments to arrays, then merges elements of +self+ with
2799
 *  corresponding elements from each argument.
2800
 *
2801
 *  This generates a sequence of +self.size+ _n_-element arrays, where _n_ is
2802
 *  one more that the count of arguments.
2803
 *
2804
 *  If the size of any argument is less than +enumObj.size+, +nil+ values are
2805
 *  supplied.
2806
 *
2807
 *  If a block is given, it is invoked for each output +array+, otherwise an
2808
 *  array of arrays is returned.
2751 2809
 *
2752 2810
 *     a = [ 4, 5, 6 ]
2753 2811
 *     b = [ 7, 8, 9 ]
......
2792 2850
 *  call-seq:
2793 2851
 *     ary.transpose -> new_ary
2794 2852
 *
2795
 *  Assumes that +self+ is an array of arrays and transposes the
2796
 *  rows and columns.
2853
 *  Assumes that +self+ is an array of arrays and transposes the rows and
2854
 *  columns.
2797 2855
 *
2798 2856
 *     a = [[1,2], [3,4], [5,6]]
2799 2857
 *     a.transpose   #=> [[1, 3, 5], [2, 4, 6]]
2858
 *
2859
 *  If the length of the subarrays don't match, an IndexError is raised.
2800 2860
 */
2801 2861

  
2802 2862
static VALUE
......
2831 2891
 *  call-seq:
2832 2892
 *     ary.replace(other_ary)  -> ary
2833 2893
 *
2834
 *  Replaces the contents of +self+ with the contents of
2835
 *  +other_ary+, truncating or expanding if necessary.
2894
 *  Replaces the contents of +self+ with the contents of +other_ary+,
2895
 *  truncating or expanding if necessary.
2836 2896
 *
2837 2897
 *     a = [ "a", "b", "c", "d", "e" ]
2838 2898
 *     a.replace([ "x", "y", "z" ])   #=> ["x", "y", "z"]
......
2918 2978
 *     ary.fill(range) {|index| block }             -> ary
2919 2979
 *
2920 2980
 *  The first three forms set the selected elements of +self+ (which
2921
 *  may be the entire array) to +obj+. A +start+ of
2922
 *  <code>nil</code> is equivalent to zero. A +length+ of
2923
 *  <code>nil</code> is equivalent to <code>self.length</code>. The last three
2924
 *  forms fill the array with the value of the block. The block is
2925
 *  passed the absolute index of each element to be filled.
2926
 *  Negative values of +start+ count from the end of the array.
2981
 *  may be the entire array) to +obj+.
2982
 *
2983
 *  A +start+ of +nil+ is equivalent to zero.
2984
 *
2985
 *  A +length+ of +nil+ is equivalent to +self.length+.
2986
 *
2987
 *  The last three forms fill the array with the value of the given block,
2988
 *  which is passed the absolute index of each element to be filled.
2989
 *
2990
 *  Negative values of +start+ count from the end of the array, where +-1+ is
2991
 *  the last element.
2927 2992
 *
2928 2993
 *     a = [ "a", "b", "c", "d" ]
2929 2994
 *     a.fill("x")              #=> ["x", "x", "x", "x"]
......
3012 3077
 *  two arrays together to produce a third array.
3013 3078
 *
3014 3079
 *     [ 1, 2, 3 ] + [ 4, 5 ]    #=> [ 1, 2, 3, 4, 5 ]
3080
 *     a = [ "a", "b", "c" ]
3081
 *     a + [ "d", "e", "f" ]
3082
 *     a                         #=> [ "a", "b", "c", "d", "e", "f" ]
3015 3083
 */
3016 3084

  
3017 3085
VALUE
......
3036 3104
 *  Appends the elements of +other_ary+ to +self+.
3037 3105
 *
3038 3106
 *     [ "a", "b" ].concat( ["c", "d"] ) #=> [ "a", "b", "c", "d" ]
3107
 *     a = [ 1, 2, 3 ]
3108
 *     a.concat( [ 4, 5 ] )
3109
 *     a                                 #=> [ 1, 2, 3, 4, 5 ]
3039 3110
 */
3040 3111

  
3041

  
3042 3112
VALUE
3043 3113
rb_ary_concat(VALUE x, VALUE y)
3044 3114
{
......
3057 3127
 *     ary * str     -> new_string
3058 3128
 *
3059 3129
 *  Repetition---With a String argument, equivalent to
3060
 *  self.join(str). Otherwise, returns a new array
3061
 *  built by concatenating the +int+ copies of +self+.
3130
 *  <code>self.join(str)</code>.
3131
 *
3132
 *  Otherwise, returns a new array built by concatenating the +int+ copies of
3133
 *  +self+.
3062 3134
 *
3063 3135
 *
3064 3136
 *     [ 1, 2, 3 ] * 3    #=> [ 1, 2, 3, 1, 2, 3, 1, 2, 3 ]
......
3116 3188
 *  call-seq:
3117 3189
 *     ary.assoc(obj)   -> new_ary  or  nil
3118 3190
 *
3119
 *  Searches through an array whose elements are also arrays
3120
 *  comparing +obj+ with the first element of each contained array
3121
 *  using obj.==.
3122
 *  Returns the first contained array that matches (that
3123
 *  is, the first associated array),
3124
 *  or +nil+ if no match is found.
3125
 *  See also Array#rassoc.
3191
 *  Searches through an array whose elements are also arrays comparing +obj+
3192
 *  with the first element of each contained array using <code>obj.==</code>.
3193
 *
3194
 *  Returns the first contained array that matches (that is, the first
3195
 *  associated array), or +nil+ if no match is found.
3196
 *
3197
 *  See also Array#rassoc
3126 3198
 *
3127 3199
 *     s1 = [ "colors", "red", "blue", "green" ]
3128 3200
 *     s2 = [ "letters", "a", "b", "c" ]
......
3151 3223
 *  call-seq:
3152 3224
 *     ary.rassoc(obj) -> new_ary or nil
3153 3225
 *
3154
 *  Searches through the array whose elements are also arrays. Compares
3155
 *  +obj+ with the second element of each contained array using
3156
 *  <code>==</code>. Returns the first contained array that matches. See
3157
 *  also Array#assoc.
3226
 *  Searches through the array whose elements are also arrays.
3227
 *
3228
 *  Compares +obj+ with the second element of each contained array using
3229
 *  <code>obj.==</code>.
3230
 *
3231
 *  Returns the first contained array that matches +obj+.
3232
 *
3233
 *  See also Array#assoc.
3158 3234
 *
3159 3235
 *     a = [ [ 1, "one"], [2, "two"], [3, "three"], ["ii", "two"] ]
3160 3236
 *     a.rassoc("two")    #=> [2, "two"]
......
3194 3270
 *  call-seq:
3195 3271
 *     ary == other_ary   ->   bool
3196 3272
 *
3197
 *  Equality---Two arrays are equal if they contain the same number
3198
 *  of elements and if each element is equal to (according to
3199
 *  Object.==) the corresponding element in the other array.
3273
 *  Equality---Two arrays are equal if they contain the same number of elements
3274
 *  and if each element is equal to (according to Object.==) the corresponding
3275
 *  element in +other_ary+.
3200 3276
 *
3201 3277
 *     [ "a", "c" ]    == [ "a", "c", 7 ]     #=> false
3202 3278
 *     [ "a", "c", 7 ] == [ "a", "c", 7 ]     #=> true
......
3235 3311
 *  call-seq:
3236 3312
 *     ary.eql?(other)  -> true or false
3237 3313
 *
3238
 *  Returns <code>true</code> if +self+ and +other+ are the same object,
3314
 *  Returns +true+ if +self+ and +other+ are the same object,
3239 3315
 *  or are both arrays with the same content.
3240 3316
 */
3241 3317

  
......
3273 3349
 *  call-seq:
3274 3350
 *     ary.hash   -> fixnum
3275 3351
 *
3276
 *  Compute a hash-code for this array. Two arrays with the same content
3277
 *  will have the same hash code (and will compare using <code>eql?</code>).
3352
 *  Compute a hash-code for this array.
3353
 *
3354
 *  Two arrays with the same content will have the same hash code (and will
3355
 *  compare using +eql?+).
3278 3356
 */
3279 3357

  
3280 3358
static VALUE
......
3287 3365
 *  call-seq:
3288 3366
 *     ary.include?(object)   -> true or false
3289 3367
 *
3290
 *  Returns <code>true</code> if the given +object+ is present in
3291
 *  +self+ (that is, if any object <code>==</code> +object+),
3292
 *  <code>false</code> otherwise.
3368
 *  Returns +true+ if the given +object+ is present in +self+ (that is, if any
3369
 *  object <code>==</code> +object+), otherwise returns +false+.
3293 3370
 *
3294 3371
 *     a = [ "a", "b", "c" ]
3295 3372
 *     a.include?("b")   #=> true
......
3333 3410
 *  call-seq:
3334 3411
 *     ary <=> other_ary   ->  -1, 0, +1 or nil
3335 3412
 *
3336
 *  Comparison---Returns an integer (-1, 0,
3337
 *  or +1) if this array is less than, equal to, or greater than
3338
 *  +other_ary+.
3413
 *  Comparison---Returns an integer (+-1+, +0+, or <code>+1</code>) if this
3414
 *  array is less than, equal to, or greater than +other_ary+.
3415
 *
3416
 *  Each object in each array is compared (using Array#<=>).
3417
 *
3418
 *  Arrays are compared in an "element-wise" manner; the first two elements
3419
 *  that are not equal will determine the return value for the whole
3420
 *  comparison.
3339 3421
 *
3340
 *  Each object in each array is compared (using <=>). Arrays are compared in
3341
 *  an "element-wise" manner; the first two elements that are not equal will
3342
 *  determine the return value for the whole comparison.  If all the values
3343
 *  are equal, then the return is based on a comparison of the array lengths.
3344
 *  Thus, two arrays are "equal" according to Array#<=> if and only if they
3345
 *  have the same length and the value of each element is equal to the
3346
 *  value of the corresponding element in the other array.
3422
 *  If all the values are equal, then the return is based on a comparison of
3423
 *  the array lengths. Thus, two arrays are "equal" according to Array#<=> if,
3424
 *  and only if, they have the same length and the value of each element is
3425
 *  equal to the value of the corresponding element in the other array.
3347 3426
 *
3348 3427
 *     [ "a", "a", "c" ]    <=> [ "a", "b", "c" ]   #=> -1
3349 3428
 *     [ 1, 2, 3, 4, 5, 6 ] <=> [ 1, 2 ]            #=> +1
......
3429 3508
 *  call-seq:
3430 3509
 *     ary - other_ary    -> new_ary
3431 3510
 *
3432
 *  Array Difference---Returns a new array that is a copy of
3433
 *  the original array, removing any items that also appear in
3434
 *  +other_ary+. (If you need set-like behavior, see the
3435
 *  library class Set.)
3511
 *  Array Difference---Returns a new array that is a copy of the original
3512
 *  array, removing any items that also appear in +other_ary+. (If you need
3513
 *  set-like behavior, see the library class Set.)
3436 3514
 *
3437 3515
 *     [ 1, 1, 2, 2, 3, 3, 4, 5 ] - [ 1, 2, 4 ]  #=>  [ 3, 3, 5 ]
3438 3516
 */
......
3459 3537
 *  call-seq:
3460 3538
 *     ary & other_ary      -> new_ary
3461 3539
 *
3462
 *  Set Intersection---Returns a new array
3463
 *  containing elements common to the two arrays, with no duplicates.
3540
 *  Set Intersection---Returns a new array containing elements common to the
3541
 *  two arrays, excluding any duplicates.
3464 3542
 *
3465
 *     [ 1, 1, 3, 5 ] & [ 1, 2, 3 ]   #=> [ 1, 3 ]
3543
 *     [ 1, 1, 3, 5 ] & [ 1, 2, 3 ]                 #=> [ 1, 3 ]
3544
 *     [ 'a', 'b', 'b', 'z' ] & [ 'a', 'b', 'c' ]   #=> [ 'a', 'b' ]
3466 3545
 */
3467 3546

  
3468 3547

  
......
3496 3575
 *  call-seq:
3497 3576
 *     ary | other_ary     -> new_ary
3498 3577
 *
3499
 *  Set Union---Returns a new array by joining this array with
3500
 *  +other_ary+, removing duplicates.
3578
 *  Set Union---Returns a new array by joining +ary+ with +other_ary+,
3579
 *  excluding any duplicates.
3501 3580
 *
3502
 *     [ "a", "b", "c" ] | [ "c", "d", "a" ]
3503
 *            #=> [ "a", "b", "c", "d" ]
3581
 *     [ "a", "b", "c" ] | [ "c", "d", "a" ]    #=> [ "a", "b", "c", "d" ]
3504 3582
 */
3505 3583

  
3506 3584
static VALUE
......
3542 3620
 *     ary.uniq!                -> ary or nil
3543 3621
 *     ary.uniq! { |item| ... } -> ary or nil
3544 3622
 *
3545
 *  Removes duplicate elements from +self+. If a block is given,
3546
 *  it will use the return value of the block for comparison.
3547
 *  Returns <code>nil</code> if no changes are made (that is, no
3548
 *  duplicates are found).
3623
 *  Removes duplicate elements from +self+.
3624
 *
3625
 *  If a block is given, it will use the return value of the block for
3626
 *  comparison.
3627
 *
3628
 *  Returns +nil+ if no changes are made (that is, no duplicates are found).
3549 3629
 *
3550 3630
 *     a = [ "a", "a", "b", "b", "c" ]
3551 3631
 *     a.uniq!   # => ["a", "b", "c"]
......
3647 3727
 *     ary.compact!    -> ary  or  nil
3648 3728
 *
3649 3729
 *  Removes +nil+ elements from the array.
3730
 *
3650 3731
 *  Returns +nil+ if no changes were made, otherwise returns the array.
3651 3732
 *
3652 3733
 *     [ "a", nil, "b", nil, "c" ].compact! #=> [ "a", "b", "c" ]
......
3703 3784
 *     ary.count(obj) -> int
3704 3785
 *     ary.count { |item| block }  -> int
3705 3786
 *
3706
 *  Returns the number of elements.  If an argument is given, counts
3707
 *  the number of elements which equals to +obj+.  If a block is
3708
 *  given, counts the number of elements for which the block returns a true
3709
 *  value.
3787
 *  Returns the number of elements.
3788
 *
3789
 *  If an argument is given, counts the number of elements which equals to
3790
 *  +obj+ using <code>===</code>. 
3791
 *
3792
 *  If a block is given, counts the number of elements for which the block
3793
 *  returns a true value.
3710 3794
 *
3711 3795
 *     ary = [1, 2, 4, 2]
3712 3796
 *     ary.count             #=> 4
......
3805 3889
 *     ary.flatten!(level) -> array or nil
3806 3890
 *
3807 3891
 *  Flattens +self+ in place.
3808
 *  Returns <code>nil</code> if no modifications were made (i.e.,
3809
 *  the array contains no subarrays.)  If the optional +level+
3810
 *  argument determines the level of recursion to flatten.
3892
 *
3893
 *  Returns +nil+ if no modifications were made (i.e., the array contains no
3894
 *  subarrays.)
3895
 *
3896
 *  The optional +level+ argument determines the level of recursion to flatten.
3811 3897
 *
3812 3898
 *     a = [ 1, 2, [3, [4, 5] ] ]
3813 3899
 *     a.flatten!   #=> [1, 2, 3, 4, 5]
......
3845 3931
 *     ary.flatten -> new_ary
3846 3932
 *     ary.flatten(level) -> new_ary
3847 3933
 *
3848
 *  Returns a new array that is a one-dimensional flattening of this
3849
 *  array (recursively). That is, for every element that is an array,
3850
 *  extract its elements into the new array.  If the optional
3851
 *  +level+ argument determines the level of recursion to flatten.
3934
 *  Returns a new array that is a one-dimensional flattening of +self+
3935
 *  (recursively).
3936
 *
3937
 *  That is, for every element that is an array, extract its elements into
3938
 *  the new array.
3939
 *
3940
 *  The optional +level+ argument determines the level of recursion to
3941
 *  flatten.
3852 3942
 *
3853 3943
 *     s = [ 1, 2, 3 ]           #=> [1, 2, 3]
3854 3944
 *     t = [ 4, 5, 6, [7, 8] ]   #=> [4, 5, 6, [7, 8]]
......
3886 3976
 *     ary.shuffle!(random: rng) -> ary
3887 3977
 *
3888 3978
 *  Shuffles elements in +self+ in place.
3889
 *  If +rng+ is given, it will be used as the random number generator.
3979
 *
3980
 *  The optional +rng+ argument will be used as random number generator.
3890 3981
 */
3891 3982

  
3892 3983
static VALUE
......
3923 4014
 *     ary.shuffle              -> new_ary
3924 4015
 *     ary.shuffle(random: rng) -> new_ary
3925 4016
 *
3926
 *  Returns a new array with elements of this array shuffled.
4017
 *  Returns a new array with elements of +self+ shuffled.
3927 4018
 *
3928 4019
 *     a = [ 1, 2, 3 ]           #=> [1, 2, 3]
3929 4020
 *     a.shuffle                 #=> [2, 3, 1]
3930 4021
 *
3931
 *  If +rng+ is given, it will be used as the random number generator.
4022
 *  The optional +rng+ argument will be used as the random number generator.
3932 4023
 *
3933 4024
 *     a.shuffle(random: Random.new(1))  #=> [1, 3, 2]
3934 4025
 */
......
3949 4040
 *     ary.sample(n)               -> new_ary
3950 4041
 *     ary.sample(n, random: rng)  -> new_ary
3951 4042
 *
3952
 *  Choose a random element or +n+ random elements from the array. The elements
3953
 *  are chosen by using random and unique indices into the array in order to
3954
 *  ensure that an element doesn't repeat itself unless the array already
3955
 *  contained duplicate elements. If the array is empty the first form returns
3956
 *  <code>nil</code> and the second form returns an empty array.
4043
 *  Choose a random element or +n+ random elements from the array.
3957 4044
 *
3958
 *  If +rng+ is given, it will be used as the random number generator.
4045
 *  The elements are chosen by using random and unique indices into the array
4046
 *  in order to ensure that an element doesn't repeat itself unless the array
4047
 *  already contained duplicate elements.
4048
 *
4049
 *  If the array is empty the first form returns +nil+ and the second form
4050
 *  returns an empty array.
4051
 *
4052
 *  The optional +rng+ argument will be used as the random number generator.
3959 4053
 *
3960 4054
 *     a = [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ]
3961 4055
 *     a.sample         #=> 7
......
4064 4158
/*
4065 4159
 *  call-seq:
4066 4160
 *     ary.cycle(n=nil) {|obj| block }  -> nil
4067
 *     ary.cycle(n=nil)                 -> an_enumerator
4161
 *     ary.cycle(n=nil)                 -> Enumerator
4162
 *
4163
 *  Calls the given block for each element repeatedly +n+ times or forever if
4164
 *  none or +nil+ is given.
4068 4165
 *
4069
 *  Calls +block+ for each element repeatedly +n+ times or
4070
 *  forever if none or +nil+ is given.  If a non-positive number is
4071
 *  given or the array is empty, does nothing.  Returns +nil+ if the
4072
 *  loop has finished without getting interrupted.
4166
 *  Does nothing if a non-positive number is given or the array is empty.
4073 4167
 *
4074
 *  If no block is given, an enumerator is returned instead.
4168
 *  Returns +nil+ if the loop has finished without getting interrupted.
4075 4169
 *
4170
 *  If no block is given, an Enumerator is returned instead.
4076 4171
 *
4077 4172
 *     a = ["a", "b", "c"]
4078 4173
 *     a.cycle {|x| puts x }  # print, a, b, c, a, b, c,.. forever.
......
4111 4206
#define tmpary_discard(a) (ary_discard(a), RBASIC(a)->klass = rb_cArray)
4112 4207

  
4113 4208
/*
4114
 * Recursively compute permutations of r elements of the set [0..n-1].
4209
 * Recursively compute permutations of +r+ elements of the set
4210
 * <code>[0..n-1]</code>.
4211
 *
4115 4212
 * When we have a complete permutation of array indexes, copy the values
4116 4213
 * at those indexes into a new array and yield that array.
4117 4214
 *
......
4157 4254
/*
4158 4255
 *  call-seq:
4159 4256
 *     ary.permutation { |p| block }          -> ary
4160
 *     ary.permutation                        -> an_enumerator
4257
 *     ary.permutation                        -> Enumerator
4161 4258
 *     ary.permutation(n) { |p| block }       -> ary
4162
 *     ary.permutation(n)                     -> an_enumerator
4259
 *     ary.permutation(n)                     -> Enumerator
4260
 *
4261
 * When invoked with a block, yield all permutations of length +n+ of the
4262
 * elements of the array, then return the array itself.
4163 4263
 *
4164
 * When invoked with a block, yield all permutations of length +n+
4165
 * of the elements of the array, then return the array itself.
4166 4264
 * If +n+ is not specified, yield all permutations of all elements.
4167
 * The implementation makes no guarantees about the order in which
4168
 * the permutations are yielded.
4169 4265
 *
4170
 * If no block is given, an enumerator is returned instead.
4266
 * The implementation makes no guarantees about the order in which the
4267
 * permutations are yielded.
4268
 *
4269
 * If no block is given, an Enumerator is returned instead.
4171 4270
 *
4172 4271
 * Examples:
4173 4272
 *
......
4187 4286
    long r, n, i;
4188 4287

  
4189 4288
    n = RARRAY_LEN(ary);                  /* Array length */
4190
    RETURN_ENUMERATOR(ary, argc, argv);   /* Return enumerator if no block */
4289
    RETURN_ENUMERATOR(ary, argc, argv);   /* Return Enumerator if no block */
4191 4290
    rb_scan_args(argc, argv, "01", &num);
4192 4291
    r = NIL_P(num) ? n : NUM2LONG(num);   /* Permutation size from argument */
4193 4292

  
......
4223 4322
/*
4224 4323
 *  call-seq:
4225 4324
 *     ary.combination(n) { |c| block }    -> ary
4226
 *     ary.combination(n)                  -> an_enumerator
4325
 *     ary.combination(n)                  -> Enumerator
4326
 *
4327
 * When invoked with a block, yields all combinations of length +n+ of elements
4328
 * from the array and then returns the array itself.
4227 4329
 *
4228
 * When invoked with a block, yields all combinations of length +n+
4229
 * of elements from the array and then returns the array itself.
4230
 * The implementation makes no guarantees about the order in which
4231
 * the combinations are yielded.
4330
 * The implementation makes no guarantees about the order in which the
4331
 * combinations are yielded.
4232 4332
 *
4233
 * If no block is given, an enumerator is returned instead.
4333
 * If no block is given, an Enumerator is returned instead.
4234 4334
 *
4235 4335
 * Examples:
4236 4336
 *
......
4294 4394
}
4295 4395

  
4296 4396
/*
4297
 * Recursively compute repeated permutations of r elements of the set
4298
 * [0..n-1].
4397
 * Recursively compute repeated permutations of +r+ elements of the set
4398
 * <code>[0..n-1]</code>.
4399
 *
4299 4400
 * When we have a complete repeated permutation of array indexes, copy the
4300 4401
 * values at those indexes into a new array and yield that array.
4301 4402
 *
......
4335 4436
/*
4336 4437
 *  call-seq:
4337 4438
 *     ary.repeated_permutation(n) { |p| block } -> ary
4338
 *     ary.repeated_permutation(n)               -> an_enumerator
4439
 *     ary.repeated_permutation(n)               -> Enumerator
4339 4440
 *
4340
 * When invoked with a block, yield all repeated permutations of length
4341
 * +n+ of the elements of the array, then return the array itself.
4342
 * The implementation makes no guarantees about the order in which
4343
 * the repeated permutations are yielded.
4441
 * When invoked with a block, yield all repeated permutations of length +n+ of
4442
 * the elements of the array, then return the array itself.
4344 4443
 *
4345
 * If no block is given, an enumerator is returned instead.
4444
 * The implementation makes no guarantees about the order in which the repeated
4445
 * permutations are yielded.
4446
 *
4447
 * If no block is given, an Enumerator is returned instead.
4346 4448
 *
4347 4449
 * Examples:
4348 4450
 *
......
4360 4462
    long r, n, i;
4361 4463

  
4362 4464
    n = RARRAY_LEN(ary);                  /* Array length */
4363
    RETURN_ENUMERATOR(ary, 1, &num);      /* Return enumerator if no block */
4465
    RETURN_ENUMERATOR(ary, 1, &num);      /* Return Enumerator if no block */
4364 4466
    r = NUM2LONG(num);                    /* Permutation size from argument */
4365 4467

  
4366 4468
    if (r < 0) {
......
4414 4516
/*
4415 4517
 *  call-seq:
4416 4518
 *     ary.repeated_combination(n) { |c| block } -> ary
4417
 *     ary.repeated_combination(n)               -> an_enumerator
4519
 *     ary.repeated_combination(n)               -> Enumerator
4520
 *
4521
 * When invoked with a block, yields all repeated combinations of length +n+ of
4522
 * elements from the array and then returns the array itself.
4418 4523
 *
4419
 * When invoked with a block, yields all repeated combinations of
4420
 * length +n+ of elements from the array and then returns
4421
 * the array itself.
4422
 * The implementation makes no guarantees about the order in which
4423
 * the repeated combinations are yielded.
4524
 * The implementation makes no guarantees about the order in which the repeated
4525
 * combinations are yielded.
4424 4526
 *
4425
 * If no block is given, an enumerator is returned instead.
4527
 * If no block is given, an Enumerator is returned instead.
4426 4528
 *
4427 4529
 * Examples:
4428 4530
 *
......
4444 4546
    long n, i, len;
4445 4547

  
4446 4548
    n = NUM2LONG(num);                 /* Combination size from argument */
4447
    RETURN_ENUMERATOR(ary, 1, &num);   /* Return enumerator if no block */
4549
    RETURN_ENUMERATOR(ary, 1, &num);   /* Return Enumerator if no block */
4448 4550
    len = RARRAY_LEN(ary);
4449 4551
    if (n < 0) {
4450 4552
	/* yield nothing */
......
4479 4581
 *     ary.product(other_ary, ...) { |p| block }  -> ary
4480 4582
 *
4481 4583
 *  Returns an array of all combinations of elements from all arrays.
4482
 *  The length of the returned array is the product of the length
4483
 *  of +self+ and the argument arrays.
4484
 *  If given a block, #product will yield all combinations
4485
 *  and return +self+ instead.
4486 4584
 *
4585
 *  The length of the returned array is the product of the length of +self+ and
4586
 *  the argument arrays.
4587
 *
4588
 *  If given a block, #product will yield all combinations and return +self+
4589
 *  instead.
4487 4590
 *
4488 4591
 *     [1,2,3].product([4,5])     #=> [[1,4],[1,5],[2,4],[2,5],[3,4],[3,5]]
4489 4592
 *     [1,2].product([1,2])       #=> [[1,1],[1,2],[2,1],[2,2]]
......
4589 4692
 *
4590 4693
 *  Returns first +n+ elements from the array.
4591 4694
 *
4695
 *  If a non-positive number is given, raises an ArgumentError.
4696
 *
4592 4697
 *     a = [1, 2, 3, 4, 5, 0]
4593 4698
 *     a.take(3)             #=> [1, 2, 3]
4594 4699
 *
......
4607 4712
/*
4608 4713
 *  call-seq:
4609 4714
 *     ary.take_while {|arr| block }   -> new_ary
4610
 *     ary.take_while                  -> an_enumerator
4715
 *     ary.take_while                  -> Enumerator
4611 4716
 *
4612
 *  Passes elements to the block until the block returns +nil+ or +false+,
4613
 *  then stops iterating and returns an array of all prior elements.
4717
 *  Passes elements to the block until the block returns +nil+ or +false+, then
4718
 *  stops iterating and returns an array of all prior elements.
4614 4719
 *
4615
 *  If no block is given, an enumerator is returned instead.
4720
 *  If no block is given, an Enumerator is returned instead.
4616 4721
 *
4617 4722
 *     a = [1, 2, 3, 4, 5, 0]
4618 4723
 *     a.take_while {|i| i < 3 }   #=> [1, 2]
......
4635 4740
 *  call-seq:
4636 4741
 *     ary.drop(n)               -> new_ary
4637 4742
 *
4638
 *  Drops first n elements from +ary+ and returns the rest of
4639
 *  the elements in an array.
4743
 *  Drops first +n+ elements from +ary+ and returns the rest of the elements in
4744
 *  an array.
4745
 *
4746
 *  If a non-positive number is given, raises an ArgumentError.
4640 4747
 *
4641 4748
 *     a = [1, 2, 3, 4, 5, 0]
4642 4749
 *     a.drop(3)             #=> [4, 5, 0]
......
4660 4767
/*
4661 4768
 *  call-seq:
4662 4769
 *     ary.drop_while {|arr| block }   -> new_ary
4663
 *     ary.drop_while                  -> an_enumerator
4770
 *     ary.drop_while                  -> Enumerator
4664 4771
 *
4665
 *  Drops elements up to, but not including, the first element for
4666
 *  which the block returns +nil+ or +false+ and returns an array
4667
 *  containing the remaining elements.
4772
 *  Drops elements up to, but not including, the first element for which the
4773
 *  block returns +nil+ or +false+ and returns an array containing the
4774
 *  remaining elements.
4668 4775
 *
4669
 *  If no block is given, an enumerator is returned instead.
4776
 *  If no block is given, an Enumerator is returned instead.
4670 4777
 *
4671 4778
 *     a = [1, 2, 3, 4, 5, 0]
4672 4779
 *     a.drop_while {|i| i < 3 }   #=> [3, 4, 5, 0]
......
4686 4793
}
4687 4794

  
4688 4795
/*
4689
 * Arrays are ordered, integer-indexed collections of any object.
4690
 * Array indexing starts at 0, as in C or Java.  A negative index is
4691
 * assumed to be relative to the end of the array---that is, an index of -1
4692
 * indicates the last element of the array, -2 is the next to last
4693
 * element in the array, and so on.
4694
 *
4695
 * == Creating Arrays
4696
 *
4697
 * A new array can be created by using the literal constructor
4698
 * <code>[]</code>.  Arrays can contain different types of objects.  For
4699
 * example, the array below contains an Integer, a String and a Float:
4700
 *
4701
 *    ary = [1, "two", 3.0] #=> [1, "two", 3.0]
4702
 *
4703
 * An array can also be created by explicitly calling Array.new with zero,
4704
 * one (the initial size of the Array) or two arguments (the initial size and
4705
 * a default object).
4706
 *
4707
 *    ary = Array.new    #=> []
4708
 *    Array.new(3)       #=> [nil, nil, nil]
4709
 *    Array.new(3, true) #=> [0, 0, 0]
4710
 *
4711
 * Note that the second argument populates the array with references the same
4712
 * object.  Therefore, it is only recommended in cases when you need to
4713
 * instantiate arrays with natively immutable objects such Symbols, numbers,
4714
 * true or false.
4715
 *
4716
 * To create an array with separate objects a block can be passed instead.
4717
 * This method is safe to use with mutable objects such as hashes, strings or
4718
 * other arrays:
4719
 *
4720
 *    Array.new(4) { Hash.new } #=> [{}, {}, {}, {}]
4721
 *
4722
 * This is also a quick way to build up multi-dimensional arrays:
4723
 *
4724
 *    empty_table = Array.new(3) { Array.new(3) }
4725
 *    #=> [[nil, nil, nil], [nil, nil, nil], [nil, nil, nil]]
4726
 *
4727
 * == Example Usage
4728
 *
4729
 * In addition to the methods it mixes in through the Enumerable module, the
4730
 * Array class has proprietary methods for accessing, searching and otherwise
4731
 * manipulating arrays.  Some of the more common ones are illustrated below.
4732
 *
4733
 * == Accessing Elements
4734
 *
4735
 * Elements in an array can be retrieved using the Array#[] method.  It can
4736
 * take a single integer argument (a numeric index), a pair of arguments
4737
 * (start and length) or a range.
4738
 *
4739
 *    arr = [1, 2, 3, 4, 5, 6]
4740
 *    arr[2]    #=> 3
4741
 *    arr[100]  #=> nil
4742
 *    arr[-3]   #=> 4
4743
 *    arr[2, 3] #=> [3, 4, 5]
4744
 *    arr[1..4] #=> [2, 3, 4, 5]
4745
 *
4746
 * Another way to access a particular array element is by using the #at method
4747
 *
4748
 *    arr.at(0) #=> 1
4749
 *
4750
 * The #slice method works in an identical manner to Array#[].
4751
 *
4752
 * To raise an error for indices outside of the array bounds or else to provide
4753
 * a default value when that happens, you can use #fetch.
4754
 *
4755
 *    arr = ['a', 'b', 'c', 'd', 'e', 'f']
4756
 *    arr.fetch(100) #=> IndexError: index 100 outside of array bounds: -6...6
4757
 *    arr.fetch(100, "oops") #=> "oops"
4758
 *
4759
 * The special methods #first and #last will return the first and last
4760
 * elements of an array, respectively.
4761
 *
4762
 *    arr.first #=> 1
4763
 *    arr.last  #=> 6
4764
 *
4765
 * To return the first n elements of an array, use #take
4766
 *
4767
 *    arr.take(3) #=> [1, 2, 3]
4768
 *
4769
 * #drop does the opposite of #take, by returning the elements after n elements
4770
 * have been dropped:
4771
 *
4772
 *    arr.drop(3) #=> [4, 5, 6]
4773
 *
4774
 * == Obtaining Information about an Array
4775
 *
4776
 * Arrays keep track of their own length at all times.  To query an array about
4777
 * the number of elements it contains, use #length, #count or #size.
4778
 *
4779
 *   browsers = ['Chrome', 'Firefox', 'Safari', 'Opera', 'IE']
4780
 *   browsers.length #=> 5
4781
 *   browsers.count #=> 5
4782
 *
4783
 * To check whether an array contains any elements at all
4784
 *
4785
 *   browsers.empty? #=> false
4786
 *
4787
 * To check whether a particular item is included in the array
4788
 *
4789
 *   browsers.include?('Konqueror') #=> false
4790
 *
4791
 * == Adding Items to Arrays
4792
 *
4793
 * Items can be added to the end of an array by using either #push or
4794
 * <code><<</code>
4795
 *
4796
 *   arr = [1, 2, 3, 4]
4797
 *   arr.push(5) #=> [1, 2, 3, 4, 5]
4798
 *   arr << 6    #=> [1, 2, 3, 4, 5, 6]
4799
 *
4800
 * #unshift will add a new item to the beginning of an array.
4801
 *
4802
 *    arr.unshift(0) #=> [0, 1, 2, 3, 4, 5, 6]
4803
 *
4804
 * With #insert you can add a new element to an array at any position.
4805
 *
4806
 *    arr.insert(3, 'apple')  #=> [0, 1, 2, 'apple', 3, 4, 5, 6]
4807
 *
4808
 * Using the #insert method, you can also insert multiple values at once:
4809
 *
4810
 *    arr.insert(3, 'orange', 'pear', 'grapefruit')
4811
 *    #=> [0, 1, 2, "orange", "pear", "grapefruit", "apple", 3, 4, 5, 6]
4812
 *
4813
 * == Removing Items from an Array
4814
 *
4815
 * The method #pop removes the last element in an array and returns it:
4816
 *
4817
 *    arr =  [1, 2, 3, 4, 5, 6]
4818
 *    arr.pop #=> 6
4819
 *    arr #=> [1, 2, 3, 4, 5]
4820
 *
4821
 * To retrieve and at the same time remove the first item, use #shift:
4822
 *
4823
 *    arr.shift #=> 1
4824
 *    arr #=> [2, 3, 4, 5]
4825
 *
4826
 * To delete an element at a particular index:
4827
 *
4828
 *    arr.delete_at(2) #=> 4
4829
 *    arr #=> [2, 3, 5]
4830
 *
4831
 * To delete a particular element anywhere in an array, use #delete:
4832
 *
4833
 *    arr = [1, 2, 2, 3]
4834
 *    arr.delete(2) #=> [1, 3]
4835
 *
4836
 * A useful method if you need to remove +nil+ values from an array is
4837
 * #compact:
4838
 *
4839
 *    arr = ['foo', 0, nil, 'bar', 7, 'baz', nil]
4840
 *    arr.compact  #=> ['foo', 0, 'bar', 7, 'baz']
4841
 *    arr          #=> ['foo', 0, nil, 'bar', 7, 'baz', nil]
4842
 *    arr.compact! #=> ['foo', 0, 'bar', 7, 'baz']
4843
 *    arr          #=> ['foo', 0, 'bar', 7, 'baz']
4844
 *
4845
 * Another common need is to remove duplicate elements from an array.
4846
 * It has a non-destructive (#uniq) and a destructive method (#uniq!)
4847
 *
4848
 *    arr = [2, 5, 6, 556, 6, 6, 8, 9, 0, 123, 556]
4849
 *    arr.uniq #=> [2, 5, 6, 556, 8, 9, 0, 123]
... This diff was truncated because it exceeds the maximum size that can be displayed.