| blob | dd49c3b4f8a954b57bebb84223e61d9dffff7fd3 |
1 /**********************************************************************
3 array.c -
5 $Author$
6 created at: Fri Aug 6 09:46:12 JST 1993
8 Copyright (C) 1993-2007 Yukihiro Matsumoto
9 Copyright (C) 2000 Network Applied Communication Laboratory, Inc.
10 Copyright (C) 2000 Information-technology Promotion Agency, Japan
12 **********************************************************************/
34 #if !ARRAY_DEBUG
35 # undef NDEBUG
36 # define NDEBUG
37 #endif
40 VALUE rb_cArray;
41 VALUE rb_cArray_empty_frozen;
43 /* Flags of RArray
44 *
45 * 1: RARRAY_EMBED_FLAG
46 * The array is embedded (its contents follow the header, rather than
47 * being on a separately allocated buffer).
48 * 2: RARRAY_SHARED_FLAG (equal to ELTS_SHARED)
49 * The array is shared. The buffer this array points to is owned by
50 * another array (the shared root).
51 * 3-9: RARRAY_EMBED_LEN
52 * The length of the array when RARRAY_EMBED_FLAG is set.
53 * 12: RARRAY_SHARED_ROOT_FLAG
54 * The array is a shared root that does reference counting. The buffer
55 * this array points to is owned by this array but may be pointed to
56 * by other arrays.
57 * Note: Frozen arrays may be a shared root without this flag being
58 * set. Frozen arrays do not have reference counting because
59 * they cannot be modified. Not updating the reference count
60 * improves copy-on-write performance. Their reference count is
61 * assumed to be infinity.
62 * 14: RARRAY_PTR_IN_USE_FLAG
63 * The buffer of the array is in use. This is only used during
64 * debugging.
65 */
67 /* for OPTIMIZED_CMP: */
68 #define id_cmp idCmp
70 #define ARY_DEFAULT_SIZE 16
71 #define ARY_MAX_SIZE (LONG_MAX / (int)sizeof(VALUE))
72 #define SMALL_ARRAY_LEN 16
75 static int
77 {
79 }
81 #define ARY_HEAP_PTR(a) (RUBY_ASSERT(!ARY_EMBED_P(a)), RARRAY(a)->as.heap.ptr)
82 #define ARY_HEAP_LEN(a) (RUBY_ASSERT(!ARY_EMBED_P(a)), RARRAY(a)->as.heap.len)
83 #define ARY_HEAP_CAPA(a) (RUBY_ASSERT(!ARY_EMBED_P(a)), RUBY_ASSERT(!ARY_SHARED_ROOT_P(a)), \
84 RARRAY(a)->as.heap.aux.capa)
86 #define ARY_EMBED_PTR(a) (RUBY_ASSERT(ARY_EMBED_P(a)), RARRAY(a)->as.ary)
87 #define ARY_EMBED_LEN(a) \
88 (RUBY_ASSERT(ARY_EMBED_P(a)), \
89 (long)((RBASIC(a)->flags >> RARRAY_EMBED_LEN_SHIFT) & \
90 (RARRAY_EMBED_LEN_MASK >> RARRAY_EMBED_LEN_SHIFT)))
91 #define ARY_HEAP_SIZE(a) (RUBY_ASSERT(!ARY_EMBED_P(a)), RUBY_ASSERT(ARY_OWNS_HEAP_P(a)), ARY_CAPA(a) * sizeof(VALUE))
93 #define ARY_OWNS_HEAP_P(a) (RUBY_ASSERT(should_be_T_ARRAY((VALUE)(a))), \
94 !FL_TEST_RAW((a), RARRAY_SHARED_FLAG|RARRAY_EMBED_FLAG))
96 #define FL_SET_EMBED(a) do { \
97 RUBY_ASSERT(!ARY_SHARED_P(a)); \
98 FL_SET((a), RARRAY_EMBED_FLAG); \
99 ary_verify(a); \
100 } while (0)
102 #define FL_UNSET_EMBED(ary) FL_UNSET((ary), RARRAY_EMBED_FLAG|RARRAY_EMBED_LEN_MASK)
103 #define FL_SET_SHARED(ary) do { \
104 RUBY_ASSERT(!ARY_EMBED_P(ary)); \
105 FL_SET((ary), RARRAY_SHARED_FLAG); \
106 } while (0)
107 #define FL_UNSET_SHARED(ary) FL_UNSET((ary), RARRAY_SHARED_FLAG)
109 #define ARY_SET_PTR(ary, p) do { \
110 RUBY_ASSERT(!ARY_EMBED_P(ary)); \
111 RUBY_ASSERT(!OBJ_FROZEN(ary)); \
112 RARRAY(ary)->as.heap.ptr = (p); \
113 } while (0)
114 #define ARY_SET_EMBED_LEN(ary, n) do { \
115 long tmp_n = (n); \
116 RUBY_ASSERT(ARY_EMBED_P(ary)); \
117 RBASIC(ary)->flags &= ~RARRAY_EMBED_LEN_MASK; \
118 RBASIC(ary)->flags |= (tmp_n) << RARRAY_EMBED_LEN_SHIFT; \
119 } while (0)
120 #define ARY_SET_HEAP_LEN(ary, n) do { \
121 RUBY_ASSERT(!ARY_EMBED_P(ary)); \
122 RARRAY(ary)->as.heap.len = (n); \
123 } while (0)
124 #define ARY_SET_LEN(ary, n) do { \
125 if (ARY_EMBED_P(ary)) { \
126 ARY_SET_EMBED_LEN((ary), (n)); \
127 } \
128 else { \
129 ARY_SET_HEAP_LEN((ary), (n)); \
130 } \
131 RUBY_ASSERT(RARRAY_LEN(ary) == (n)); \
132 } while (0)
133 #define ARY_INCREASE_PTR(ary, n) do { \
134 RUBY_ASSERT(!ARY_EMBED_P(ary)); \
135 RUBY_ASSERT(!OBJ_FROZEN(ary)); \
136 RARRAY(ary)->as.heap.ptr += (n); \
137 } while (0)
138 #define ARY_INCREASE_LEN(ary, n) do { \
139 RUBY_ASSERT(!OBJ_FROZEN(ary)); \
140 if (ARY_EMBED_P(ary)) { \
141 ARY_SET_EMBED_LEN((ary), RARRAY_LEN(ary)+(n)); \
142 } \
143 else { \
144 RARRAY(ary)->as.heap.len += (n); \
145 } \
146 } while (0)
148 #define ARY_CAPA(ary) (ARY_EMBED_P(ary) ? ary_embed_capa(ary) : \
149 ARY_SHARED_ROOT_P(ary) ? RARRAY_LEN(ary) : ARY_HEAP_CAPA(ary))
150 #define ARY_SET_CAPA(ary, n) do { \
151 RUBY_ASSERT(!ARY_EMBED_P(ary)); \
152 RUBY_ASSERT(!ARY_SHARED_P(ary)); \
153 RUBY_ASSERT(!OBJ_FROZEN(ary)); \
154 RARRAY(ary)->as.heap.aux.capa = (n); \
155 } while (0)
157 #define ARY_SHARED_ROOT_OCCUPIED(ary) (!OBJ_FROZEN(ary) && ARY_SHARED_ROOT_REFCNT(ary) == 1)
158 #define ARY_SET_SHARED_ROOT_REFCNT(ary, value) do { \
159 RUBY_ASSERT(ARY_SHARED_ROOT_P(ary)); \
160 RUBY_ASSERT(!OBJ_FROZEN(ary)); \
161 RUBY_ASSERT((value) >= 0); \
162 RARRAY(ary)->as.heap.aux.capa = (value); \
163 } while (0)
164 #define FL_SET_SHARED_ROOT(ary) do { \
165 RUBY_ASSERT(!OBJ_FROZEN(ary)); \
166 RUBY_ASSERT(!ARY_EMBED_P(ary)); \
167 FL_SET((ary), RARRAY_SHARED_ROOT_FLAG); \
168 } while (0)
172 {
177 }
178 #undef RARRAY_ASET
180 static long
182 {
186 }
188 static size_t
190 {
192 }
194 static bool
196 {
198 }
200 bool
202 {
203 /* An array cannot be turned embeddable when the array is:
204 * - Shared root: other objects may point to the buffer of this array
205 * so we cannot make it embedded.
206 * - Frozen: this array may also be a shared root without the shared root
207 * flag.
208 * - Shared: we don't want to re-embed an array that points to a shared
209 * root (to save memory).
210 */
212 }
214 size_t
216 {
221 }
224 }
227 }
229 }
232 #if ARRAY_DEBUG
233 #define ary_verify(ary) ary_verify_(ary, __FILE__, __LINE__)
235 static VALUE
237 {
248 }
252 }
260 }
262 }
265 }
267 void
269 {
271 }
272 #else
273 #define ary_verify(ary) ((void)0)
274 #endif
276 VALUE *
278 {
279 #if ARRAY_DEBUG
281 #endif
283 }
285 void
287 {
288 #if ARRAY_DEBUG
290 #endif
291 }
293 void
295 {
298 }
299 }
301 static void
303 {
306 });
307 }
311 {
314 }
315 }
317 static void
319 {
323 });
324 }
326 static void
328 {
335 });
336 }
342 }
343 });
344 }
345 }
347 static void
349 {
351 }
355 {
357 }
359 static void
361 {
363 }
365 static void
367 {
369 }
371 static size_t
373 {
379 }
381 void
383 {
395 }
396 }
398 static void
400 {
415 }
418 }
420 }
433 }
434 }
437 }
441 {
449 }
452 }
454 static void
456 {
461 }
464 }
469 }
471 static void
473 {
477 }
478 }
480 static void
482 {
486 }
488 static void
490 {
493 }
496 }
500 }
502 static VALUE
504 {
509 }
511 }
513 static void
515 {
525 }
529 {
532 }
534 void
536 {
550 }
551 else if (ARY_SHARED_ROOT_OCCUPIED(shared_root) && len > ((shared_len = RARRAY_LEN(shared_root))>>1)) {
558 });
561 }
568 }
571 }
573 }
575 void
577 {
580 }
582 static VALUE
584 {
591 }
602 }
604 /* if array is shared, then it is likely it participate in push/shift pattern */
609 }
612 }
613 }
614 }
617 }
620 }
624 }
628 }
630 /*
631 * call-seq:
632 * array.freeze -> self
633 *
634 * Freezes +self+; returns +self+:
635 *
636 * a = []
637 * a.frozen? # => false
638 * a.freeze
639 * a.frozen? # => true
640 *
641 * An attempt to modify a frozen +Array+ raises FrozenError.
642 */
644 VALUE
646 {
653 }
656 }
658 /* This can be used to take a snapshot of an array (with
659 e.g. rb_ary_replace) and check later whether the array has been
660 modified from the snapshot. The snapshot is cheap, though if
661 something does modify the array it will pay the cost of copying
662 it. If Array#pop or Array#shift has been called, the array will
663 be still shared with the snapshot, but the array length will
664 differ. */
665 VALUE
667 {
673 }
675 }
677 static VALUE
679 {
685 /* Created array is:
686 * FL_SET_EMBED((VALUE)ary);
687 * ARY_SET_EMBED_LEN((VALUE)ary, 0);
688 */
690 }
692 static VALUE
694 {
699 }
701 static VALUE
703 {
706 }
708 static VALUE
710 {
711 VALUE ary;
715 }
718 }
724 }
732 }
735 }
737 VALUE
739 {
741 }
743 VALUE
745 {
747 }
749 VALUE
751 {
753 VALUE ary;
761 }
766 }
768 VALUE
770 {
771 VALUE ary;
777 }
780 }
782 VALUE
784 {
786 }
788 static VALUE
790 {
796 /* Created array is:
797 * FL_SET_EMBED((VALUE)ary);
798 * ARY_SET_EMBED_LEN((VALUE)ary, 0);
799 */
801 }
803 static VALUE
805 {
810 }
812 static VALUE
814 {
815 VALUE ary;
819 }
822 }
828 }
836 }
839 }
841 VALUE
843 {
844 VALUE ary;
850 }
853 }
855 VALUE
857 {
860 }
862 VALUE
864 {
869 }
871 void
873 {
879 }
883 }
886 }
890 }
893 }
894 }
898 static VALUE
900 {
906 }
908 VALUE
910 {
914 // bypass frozen checks
919 }
921 size_t
923 {
926 }
929 }
930 }
932 static VALUE
934 {
939 }
942 }
945 }
950 /* Shared roots cannot be embedded because the reference count
951 * (refcnt) is stored in as.heap.aux.capa. */
963 }
966 }
976 }
977 }
979 static VALUE
981 {
991 }
994 }
995 }
997 VALUE
999 {
1001 }
1003 VALUE
1005 {
1007 }
1008 #define to_ary rb_to_array_type
1010 VALUE
1012 {
1014 }
1016 VALUE
1018 {
1020 }
1022 VALUE
1024 {
1026 }
1028 /*
1029 * call-seq:
1030 * Array.try_convert(object) -> object, new_array, or nil
1031 *
1032 * Attempts to return an array, based on the given +object+.
1033 *
1034 * If +object+ is an array, returns +object+.
1035 *
1036 * Otherwise if +object+ responds to <tt>:to_ary</tt>.
1037 * calls <tt>object.to_ary</tt>:
1038 * if the return value is an array or +nil+, returns that value;
1039 * if not, raises TypeError.
1040 *
1041 * Otherwise returns +nil+.
1042 *
1043 * Related: see {Methods for Creating an Array}[rdoc-ref:Array@Methods+for+Creating+an+Array].
1044 */
1046 static VALUE
1048 {
1050 }
1052 /* :nodoc: */
1053 static VALUE
1055 {
1056 VALUE ary;
1063 }
1068 }
1071 }
1074 }
1076 /*
1077 * call-seq:
1078 * Array.new -> new_empty_array
1079 * Array.new(array) -> new_array
1080 * Array.new(size, default_value = nil) -> new_array
1081 * Array.new(size = 0) {|index| ... } -> new_array
1082 *
1083 * Returns a new array.
1084 *
1085 * With no block and no argument given, returns a new empty array:
1086 *
1087 * Array.new # => []
1088 *
1089 * With no block and array argument given, returns a new array with the same elements:
1090 *
1091 * Array.new([:foo, 'bar', 2]) # => [:foo, "bar", 2]
1092 *
1093 * With no block and integer argument given, returns a new array containing
1094 * that many instances of the given +default_value+:
1095 *
1096 * Array.new(0) # => []
1097 * Array.new(3) # => [nil, nil, nil]
1098 * Array.new(2, 3) # => [3, 3]
1099 *
1100 * With a block given, returns an array of the given +size+;
1101 * calls the block with each +index+ in the range <tt>(0...size)</tt>;
1102 * the element at that +index+ in the returned array is the blocks return value:
1103 *
1104 * Array.new(3) {|index| "Element #{index}" } # => ["Element 0", "Element 1", "Element 2"]
1105 *
1106 * A common pitfall for new Rubyists is providing an expression as +default_value+:
1107 *
1108 * array = Array.new(2, {})
1109 * array # => [{}, {}]
1110 * array[0][:a] = 1
1111 * array # => [{a: 1}, {a: 1}], as array[0] and array[1] are same object
1112 *
1113 * If you want the elements of the array to be distinct, you should pass a block:
1114 *
1115 * array = Array.new(2) { {} }
1116 * array # => [{}, {}]
1117 * array[0][:a] = 1
1118 * array # => [{a: 1}, {}], as array[0] and array[1] are different objects
1119 *
1120 * Raises TypeError if the first argument is not either an array
1121 * or an {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects]).
1122 * Raises ArgumentError if the first argument is a negative integer.
1123 *
1124 * Related: see {Methods for Creating an Array}[rdoc-ref:Array@Methods+for+Creating+an+Array].
1125 */
1127 static VALUE
1129 {
1140 }
1142 }
1149 }
1150 }
1153 /* NUM2LONG() may call size.to_int, ary can be frozen, modified, etc */
1156 }
1159 }
1160 /* recheck after argument conversion */
1168 }
1172 }
1173 }
1177 }
1179 }
1181 /*
1182 * Returns a new array, populated with the given objects:
1183 *
1184 * Array[1, 'a', /^A/] # => [1, "a", /^A/]
1185 * Array[] # => []
1186 * Array.[](1, 'a', /^A/) # => [1, "a", /^A/]
1187 *
1188 * Related: see {Methods for Creating an Array}[rdoc-ref:Array@Methods+for+Creating+an+Array].
1189 */
1191 static VALUE
1193 {
1198 }
1201 }
1203 void
1205 {
1213 }
1214 }
1217 }
1222 }
1225 }
1229 }
1231 }
1233 static VALUE
1235 {
1246 }
1250 /* The ary_make_shared call may allocate, which can trigger a GC
1251 * compaction. This can cause the array to be embedded because it has
1252 * a length of 0. */
1263 }
1267 }
1269 static VALUE
1271 {
1287 }
1290 }
1306 }
1308 }
1316 }
1317 });
1319 }
1322 }
1324 static VALUE
1326 {
1328 }
1330 enum ary_take_pos_flags
1331 {
1334 };
1336 static VALUE
1338 {
1344 }
1347 }
1350 }
1352 }
1354 static VALUE
1356 {
1358 /* the case optional argument is omitted should be handled in
1359 * callers of this function. if another arity case is added,
1360 * this arity check needs to rewrite. */
1363 }
1365 /*
1366 * call-seq:
1367 * self << object -> self
1368 *
1369 * Appends +object+ as the last element in +self+; returns +self+:
1370 *
1371 * [:foo, 'bar', 2] << :baz # => [:foo, "bar", 2, :baz]
1372 *
1373 * Appends +object+ as a single element, even if it is another array:
1374 *
1375 * [:foo, 'bar', 2] << [3, 4] # => [:foo, "bar", 2, [3, 4]]
1376 *
1377 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
1378 */
1380 VALUE
1382 {
1387 });
1391 }
1393 VALUE
1395 {
1401 }
1403 /*
1404 * call-seq:
1405 * push(*objects) -> self
1406 * append(*objects) -> self
1407 *
1408 * Appends each argument in +objects+ to +self+; returns +self+:
1409 *
1410 * a = [:foo, 'bar', 2] # => [:foo, "bar", 2]
1411 * a.push(:baz, :bat) # => [:foo, "bar", 2, :baz, :bat]
1412 *
1413 * Appends each argument as a single element, even if it is another array:
1414 *
1415 * a = [:foo, 'bar', 2] # => [:foo, "bar", 2]
1416 a.push([:baz, :bat], [:bam, :bad]) # => [:foo, "bar", 2, [:baz, :bat], [:bam, :bad]]
1417 *
1418 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
1419 */
1421 static VALUE
1423 {
1425 }
1427 VALUE
1429 {
1437 {
1439 }
1444 }
1446 /*
1447 * call-seq:
1448 * array.pop -> object or nil
1449 * array.pop(n) -> new_array
1450 *
1451 * Removes and returns trailing elements.
1452 *
1453 * When no argument is given and +self+ is not empty,
1454 * removes and returns the last element:
1455 *
1456 * a = [:foo, 'bar', 2]
1457 * a.pop # => 2
1458 * a # => [:foo, "bar"]
1459 *
1460 * Returns +nil+ if the array is empty.
1461 *
1462 * When a non-negative Integer argument +n+ is given and is in range,
1463 *
1464 * removes and returns the last +n+ elements in a new +Array+:
1465 * a = [:foo, 'bar', 2]
1466 * a.pop(2) # => ["bar", 2]
1467 *
1468 * If +n+ is positive and out of range,
1469 * removes and returns all elements:
1470 *
1471 * a = [:foo, 'bar', 2]
1472 * a.pop(50) # => [:foo, "bar", 2]
1473 *
1474 * Related: #push, #shift, #unshift.
1475 */
1477 static VALUE
1479 {
1480 VALUE result;
1484 }
1491 }
1493 VALUE
1495 {
1496 VALUE top;
1502 }
1509 }
1511 /*
1512 * call-seq:
1513 * array.shift -> object or nil
1514 * array.shift(n) -> new_array
1515 *
1516 * Removes and returns leading elements.
1517 *
1518 * When no argument is given, removes and returns the first element:
1519 *
1520 * a = [:foo, 'bar', 2]
1521 * a.shift # => :foo
1522 * a # => ['bar', 2]
1523 *
1524 * Returns +nil+ if +self+ is empty.
1525 *
1526 * When positive Integer argument +n+ is given, removes the first +n+ elements;
1527 * returns those elements in a new +Array+:
1528 *
1529 * a = [:foo, 'bar', 2]
1530 * a.shift(2) # => [:foo, 'bar']
1531 * a # => [2]
1532 *
1533 * If +n+ is as large as or larger than <tt>self.length</tt>,
1534 * removes all elements; returns those elements in a new +Array+:
1535 *
1536 * a = [:foo, 'bar', 2]
1537 * a.shift(3) # => [:foo, 'bar', 2]
1538 *
1539 * If +n+ is zero, returns a new empty +Array+; +self+ is unmodified.
1540 *
1541 * Related: #push, #pop, #unshift.
1542 */
1544 static VALUE
1546 {
1547 VALUE result;
1552 }
1560 }
1562 VALUE
1564 {
1567 }
1579 }
1583 }
1586 }
1593 }
1595 static VALUE
1596 make_room_for_unshift(VALUE ary, const VALUE *head, VALUE *sharedp, int argc, long capa, long len)
1597 {
1604 }
1610 }
1612 static VALUE
1614 {
1624 }
1626 /* use shared array for big "queues" */
1630 /* make a room for unshifted items */
1636 }
1638 /* sliding items */
1641 });
1645 }
1646 }
1648 static VALUE
1650 {
1656 }
1659 }
1666 }
1669 }
1676 }
1677 }
1678 }
1680 /*
1681 * call-seq:
1682 * array.unshift(*objects) -> self
1683 *
1684 * Prepends the given +objects+ to +self+:
1685 *
1686 * a = [:foo, 'bar', 2]
1687 * a.unshift(:bam, :bat) # => [:bam, :bat, :foo, "bar", 2]
1688 *
1689 * Related: #push, #pop, #shift.
1690 */
1692 VALUE
1694 {
1696 VALUE target_ary;
1701 }
1707 }
1709 VALUE
1711 {
1713 }
1715 /* faster version - use this if you don't need to treat negative offset */
1718 {
1723 }
1725 }
1727 VALUE
1729 {
1731 }
1733 VALUE
1735 {
1736 VALUE klass;
1744 }
1751 else
1753 }
1755 VALUE
1757 {
1759 }
1763 /*
1764 * call-seq:
1765 * self[index] -> object or nil
1766 * self[start, length] -> object or nil
1767 * self[range] -> object or nil
1768 * self[aseq] -> object or nil
1769 * slice(index) -> object or nil
1770 * slice(start, length) -> object or nil
1771 * slice(range) -> object or nil
1772 * slice(aseq) -> object or nil
1773 *
1774 * Returns elements from +self+; does not modify +self+.
1775 *
1776 * In brief:
1777 *
1778 * a = [:foo, 'bar', 2]
1779 *
1780 * # Single argument index: returns one element.
1781 * a[0] # => :foo # Zero-based index.
1782 * a[-1] # => 2 # Negative index counts backwards from end.
1783 *
1784 * # Arguments start and length: returns an array.
1785 * a[1, 2] # => ["bar", 2]
1786 * a[-2, 2] # => ["bar", 2] # Negative start counts backwards from end.
1787 *
1788 * # Single argument range: returns an array.
1789 * a[0..1] # => [:foo, "bar"]
1790 * a[0..-2] # => [:foo, "bar"] # Negative range-begin counts backwards from end.
1791 * a[-2..2] # => ["bar", 2] # Negative range-end counts backwards from end.
1792 *
1793 * When a single integer argument +index+ is given, returns the element at offset +index+:
1794 *
1795 * a = [:foo, 'bar', 2]
1796 * a[0] # => :foo
1797 * a[2] # => 2
1798 * a # => [:foo, "bar", 2]
1799 *
1800 * If +index+ is negative, counts backwards from the end of +self+:
1801 *
1802 * a = [:foo, 'bar', 2]
1803 * a[-1] # => 2
1804 * a[-2] # => "bar"
1805 *
1806 * If +index+ is out of range, returns +nil+.
1807 *
1808 * When two Integer arguments +start+ and +length+ are given,
1809 * returns a new +Array+ of size +length+ containing successive elements beginning at offset +start+:
1810 *
1811 * a = [:foo, 'bar', 2]
1812 * a[0, 2] # => [:foo, "bar"]
1813 * a[1, 2] # => ["bar", 2]
1814 *
1815 * If <tt>start + length</tt> is greater than <tt>self.length</tt>,
1816 * returns all elements from offset +start+ to the end:
1817 *
1818 * a = [:foo, 'bar', 2]
1819 * a[0, 4] # => [:foo, "bar", 2]
1820 * a[1, 3] # => ["bar", 2]
1821 * a[2, 2] # => [2]
1822 *
1823 * If <tt>start == self.size</tt> and <tt>length >= 0</tt>,
1824 * returns a new empty +Array+.
1825 *
1826 * If +length+ is negative, returns +nil+.
1827 *
1828 * When a single Range argument +range+ is given,
1829 * treats <tt>range.min</tt> as +start+ above
1830 * and <tt>range.size</tt> as +length+ above:
1831 *
1832 * a = [:foo, 'bar', 2]
1833 * a[0..1] # => [:foo, "bar"]
1834 * a[1..2] # => ["bar", 2]
1835 *
1836 * Special case: If <tt>range.start == a.size</tt>, returns a new empty +Array+.
1837 *
1838 * If <tt>range.end</tt> is negative, calculates the end index from the end:
1839 *
1840 * a = [:foo, 'bar', 2]
1841 * a[0..-1] # => [:foo, "bar", 2]
1842 * a[0..-2] # => [:foo, "bar"]
1843 * a[0..-3] # => [:foo]
1844 *
1845 * If <tt>range.start</tt> is negative, calculates the start index from the end:
1846 *
1847 * a = [:foo, 'bar', 2]
1848 * a[-1..2] # => [2]
1849 * a[-2..2] # => ["bar", 2]
1850 * a[-3..2] # => [:foo, "bar", 2]
1851 *
1852 * If <tt>range.start</tt> is larger than the array size, returns +nil+.
1853 *
1854 * a = [:foo, 'bar', 2]
1855 * a[4..1] # => nil
1856 * a[4..0] # => nil
1857 * a[4..-1] # => nil
1858 *
1859 * When a single Enumerator::ArithmeticSequence argument +aseq+ is given,
1860 * returns an +Array+ of elements corresponding to the indexes produced by
1861 * the sequence.
1862 *
1863 * a = ['--', 'data1', '--', 'data2', '--', 'data3']
1864 * a[(1..).step(2)] # => ["data1", "data2", "data3"]
1865 *
1866 * Unlike slicing with range, if the start or the end of the arithmetic sequence
1867 * is larger than array size, throws RangeError.
1868 *
1869 * a = ['--', 'data1', '--', 'data2', '--', 'data3']
1870 * a[(1..11).step(2)]
1871 * # RangeError (((1..11).step(2)) out of range)
1872 * a[(7..).step(2)]
1873 * # RangeError (((7..).step(2)) out of range)
1874 *
1875 * If given a single argument, and its type is not one of the listed, tries to
1876 * convert it to Integer, and raises if it is impossible:
1877 *
1878 * a = [:foo, 'bar', 2]
1879 * # Raises TypeError (no implicit conversion of Symbol into Integer):
1880 * a[:foo]
1881 *
1882 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
1883 */
1885 VALUE
1887 {
1891 }
1893 }
1895 static VALUE
1897 {
1902 }
1904 }
1906 VALUE
1908 {
1911 /* special case - speeding up */
1914 }
1915 /* check if idx is Range or ArithmeticSequence */
1923 }
1926 }
1928 /*
1929 * call-seq:
1930 * at(index) -> object or nil
1931 *
1932 * Returns the element of +self+ specified by the given +index+
1933 * or +nil+ if there is no such element;
1934 * +index+ must be an
1935 * {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects].
1936 *
1937 * For non-negative +index+, returns the element of +self+ at offset +index+:
1938 *
1939 * a = [:foo, 'bar', 2]
1940 * a.at(0) # => :foo
1941 * a.at(2) # => 2
1942 * a.at(2.0) # => 2
1943 *
1944 * For negative +index+, counts backwards from the end of +self+:
1945 *
1946 * a.at(-2) # => "bar"
1947 *
1948 * Related: Array#[];
1949 * see also {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
1950 */
1952 VALUE
1954 {
1956 }
1958 #if 0
1959 static VALUE
1961 {
1965 }
1968 }
1969 }
1970 #endif
1972 static VALUE
1974 {
1976 }
1978 static VALUE
1980 {
1983 }
1985 VALUE
1987 {
1990 }
1993 }
1994 }
1996 /*
1997 * call-seq:
1998 * array.fetch(index) -> element
1999 * array.fetch(index, default_value) -> element
2000 * array.fetch(index) {|index| ... } -> element
2001 *
2002 * Returns the element at offset +index+.
2003 *
2004 * With the single Integer argument +index+,
2005 * returns the element at offset +index+:
2006 *
2007 * a = [:foo, 'bar', 2]
2008 * a.fetch(1) # => "bar"
2009 *
2010 * If +index+ is negative, counts from the end of the array:
2011 *
2012 * a = [:foo, 'bar', 2]
2013 * a.fetch(-1) # => 2
2014 * a.fetch(-2) # => "bar"
2015 *
2016 * With arguments +index+ and +default_value+,
2017 * returns the element at offset +index+ if index is in range,
2018 * otherwise returns +default_value+:
2019 *
2020 * a = [:foo, 'bar', 2]
2021 * a.fetch(1, nil) # => "bar"
2022 *
2023 * With argument +index+ and a block,
2024 * returns the element at offset +index+ if index is in range
2025 * (and the block is not called); otherwise calls the block with index and returns its return value:
2026 *
2027 * a = [:foo, 'bar', 2]
2028 * a.fetch(1) {|index| raise 'Cannot happen' } # => "bar"
2029 * a.fetch(50) {|index| "Value for #{index}" } # => "Value for 50"
2030 *
2031 */
2033 static VALUE
2035 {
2044 }
2049 }
2055 }
2057 }
2059 }
2061 /*
2062 * call-seq:
2063 * array.index(object) -> integer or nil
2064 * array.index {|element| ... } -> integer or nil
2065 * array.index -> new_enumerator
2066 *
2067 * Returns the index of a specified element.
2068 *
2069 * When argument +object+ is given but no block,
2070 * returns the index of the first element +element+
2071 * for which <tt>object == element</tt>:
2072 *
2073 * a = [:foo, 'bar', 2, 'bar']
2074 * a.index('bar') # => 1
2075 *
2076 * Returns +nil+ if no such element found.
2077 *
2078 * When both argument +object+ and a block are given,
2079 * calls the block with each successive element;
2080 * returns the index of the first element for which the block returns a truthy value:
2081 *
2082 * a = [:foo, 'bar', 2, 'bar']
2083 * a.index {|element| element == 'bar' } # => 1
2084 *
2085 * Returns +nil+ if the block never returns a truthy value.
2086 *
2087 * When neither an argument nor a block is given, returns a new Enumerator:
2088 *
2089 * a = [:foo, 'bar', 2]
2090 * e = a.index
2091 * e # => #<Enumerator: [:foo, "bar", 2]:index>
2092 * e.each {|element| element == 'bar' } # => 1
2093 *
2094 * Related: #rindex.
2095 */
2097 static VALUE
2099 {
2100 VALUE val;
2108 }
2109 }
2111 }
2120 }
2121 }
2123 }
2125 /*
2126 * call-seq:
2127 * array.rindex(object) -> integer or nil
2128 * array.rindex {|element| ... } -> integer or nil
2129 * array.rindex -> new_enumerator
2130 *
2131 * Returns the index of the last element for which <tt>object == element</tt>.
2132 *
2133 * When argument +object+ is given but no block, returns the index of the last such element found:
2134 *
2135 * a = [:foo, 'bar', 2, 'bar']
2136 * a.rindex('bar') # => 3
2137 *
2138 * Returns +nil+ if no such object found.
2139 *
2140 * When a block is given but no argument, calls the block with each successive element;
2141 * returns the index of the last element for which the block returns a truthy value:
2142 *
2143 * a = [:foo, 'bar', 2, 'bar']
2144 * a.rindex {|element| element == 'bar' } # => 3
2145 *
2146 * Returns +nil+ if the block never returns a truthy value.
2147 *
2148 * When neither an argument nor a block is given, returns a new Enumerator:
2149 *
2150 * a = [:foo, 'bar', 2, 'bar']
2151 * e = a.rindex
2152 * e # => #<Enumerator: [:foo, "bar", 2, "bar"]:rindex>
2153 * e.each {|element| element == 'bar' } # => 3
2154 *
2155 * Related: #index.
2156 */
2158 static VALUE
2160 {
2161 VALUE val;
2171 }
2172 }
2174 }
2183 }
2186 }
2187 }
2189 }
2191 VALUE
2193 {
2198 }
2200 static void
2202 {
2213 }
2214 }
2217 }
2219 {
2222 }
2225 VALUE target_ary;
2228 }
2235 }
2237 }
2243 }
2248 }
2255 }
2259 }
2261 /* In this case, we're copying from a region in this array, so
2262 * we don't need to fire the write barrier. */
2264 }
2266 /* do not use RARRAY_PTR() because it can causes GC.
2267 * ary can contain T_NONE object because it is not cleared.
2268 */
2271 }
2272 }
2273 }
2275 void
2277 {
2283 }
2286 }
2288 }
2290 VALUE
2292 {
2300 }
2304 }
2307 }
2310 }
2322 }
2327 }
2329 }
2332 }
2334 static VALUE
2336 {
2339 }
2341 static VALUE
2343 {
2348 }
2350 /*
2351 * call-seq:
2352 * self[index] = object -> object
2353 * self[start, length] = object -> object
2354 * self[range] = object -> object
2355 *
2356 * Assigns elements in +self+, based on the given +object+; returns +object+.
2357 *
2358 * In brief:
2359 *
2360 * a_orig = [:foo, 'bar', 2]
2361 *
2362 * # With argument index.
2363 * a = a_orig.dup
2364 * a[0] = 'foo' # => "foo"
2365 * a # => ["foo", "bar", 2]
2366 * a = a_orig.dup
2367 * a[7] = 'foo' # => "foo"
2368 * a # => [:foo, "bar", 2, nil, nil, nil, nil, "foo"]
2369 *
2370 * # With arguments start and length.
2371 * a = a_orig.dup
2372 * a[0, 2] = 'foo' # => "foo"
2373 * a # => ["foo", 2]
2374 * a = a_orig.dup
2375 * a[6, 50] = 'foo' # => "foo"
2376 * a # => [:foo, "bar", 2, nil, nil, nil, "foo"]
2377 *
2378 * # With argument range.
2379 * a = a_orig.dup
2380 * a[0..1] = 'foo' # => "foo"
2381 * a # => ["foo", 2]
2382 * a = a_orig.dup
2383 * a[6..50] = 'foo' # => "foo"
2384 * a # => [:foo, "bar", 2, nil, nil, nil, "foo"]
2385 *
2386 * When Integer argument +index+ is given, assigns +object+ to an element in +self+.
2387 *
2388 * If +index+ is non-negative, assigns +object+ the element at offset +index+:
2389 *
2390 * a = [:foo, 'bar', 2]
2391 * a[0] = 'foo' # => "foo"
2392 * a # => ["foo", "bar", 2]
2393 *
2394 * If +index+ is greater than <tt>self.length</tt>, extends the array:
2395 *
2396 * a = [:foo, 'bar', 2]
2397 * a[7] = 'foo' # => "foo"
2398 * a # => [:foo, "bar", 2, nil, nil, nil, nil, "foo"]
2399 *
2400 * If +index+ is negative, counts backwards from the end of the array:
2401 *
2402 * a = [:foo, 'bar', 2]
2403 * a[-1] = 'two' # => "two"
2404 * a # => [:foo, "bar", "two"]
2405 *
2406 * When Integer arguments +start+ and +length+ are given and +object+ is not an +Array+,
2407 * removes <tt>length - 1</tt> elements beginning at offset +start+,
2408 * and assigns +object+ at offset +start+:
2409 *
2410 * a = [:foo, 'bar', 2]
2411 * a[0, 2] = 'foo' # => "foo"
2412 * a # => ["foo", 2]
2413 *
2414 * If +start+ is negative, counts backwards from the end of the array:
2415 *
2416 * a = [:foo, 'bar', 2]
2417 * a[-2, 2] = 'foo' # => "foo"
2418 * a # => [:foo, "foo"]
2419 *
2420 * If +start+ is non-negative and outside the array (<tt> >= self.size</tt>),
2421 * extends the array with +nil+, assigns +object+ at offset +start+,
2422 * and ignores +length+:
2423 *
2424 * a = [:foo, 'bar', 2]
2425 * a[6, 50] = 'foo' # => "foo"
2426 * a # => [:foo, "bar", 2, nil, nil, nil, "foo"]
2427 *
2428 * If +length+ is zero, shifts elements at and following offset +start+
2429 * and assigns +object+ at offset +start+:
2430 *
2431 * a = [:foo, 'bar', 2]
2432 * a[1, 0] = 'foo' # => "foo"
2433 * a # => [:foo, "foo", "bar", 2]
2434 *
2435 * If +length+ is too large for the existing array, does not extend the array:
2436 *
2437 * a = [:foo, 'bar', 2]
2438 * a[1, 5] = 'foo' # => "foo"
2439 * a # => [:foo, "foo"]
2440 *
2441 * When Range argument +range+ is given and +object+ is not an +Array+,
2442 * removes <tt>length - 1</tt> elements beginning at offset +start+,
2443 * and assigns +object+ at offset +start+:
2444 *
2445 * a = [:foo, 'bar', 2]
2446 * a[0..1] = 'foo' # => "foo"
2447 * a # => ["foo", 2]
2448 *
2449 * if <tt>range.begin</tt> is negative, counts backwards from the end of the array:
2450 *
2451 * a = [:foo, 'bar', 2]
2452 * a[-2..2] = 'foo' # => "foo"
2453 * a # => [:foo, "foo"]
2454 *
2455 * If the array length is less than <tt>range.begin</tt>,
2456 * extends the array with +nil+, assigns +object+ at offset <tt>range.begin</tt>,
2457 * and ignores +length+:
2458 *
2459 * a = [:foo, 'bar', 2]
2460 * a[6..50] = 'foo' # => "foo"
2461 * a # => [:foo, "bar", 2, nil, nil, nil, "foo"]
2462 *
2463 * If <tt>range.end</tt> is zero, shifts elements at and following offset +start+
2464 * and assigns +object+ at offset +start+:
2465 *
2466 * a = [:foo, 'bar', 2]
2467 * a[1..0] = 'foo' # => "foo"
2468 * a # => [:foo, "foo", "bar", 2]
2469 *
2470 * If <tt>range.end</tt> is negative, assigns +object+ at offset +start+,
2471 * retains <tt>range.end.abs -1</tt> elements past that, and removes those beyond:
2472 *
2473 * a = [:foo, 'bar', 2]
2474 * a[1..-1] = 'foo' # => "foo"
2475 * a # => [:foo, "foo"]
2476 * a = [:foo, 'bar', 2]
2477 * a[1..-2] = 'foo' # => "foo"
2478 * a # => [:foo, "foo", 2]
2479 * a = [:foo, 'bar', 2]
2480 * a[1..-3] = 'foo' # => "foo"
2481 * a # => [:foo, "foo", "bar", 2]
2482 * a = [:foo, 'bar', 2]
2483 *
2484 * If <tt>range.end</tt> is too large for the existing array,
2485 * replaces array elements, but does not extend the array with +nil+ values:
2486 *
2487 * a = [:foo, 'bar', 2]
2488 * a[1..5] = 'foo' # => "foo"
2489 * a # => [:foo, "foo"]
2490 *
2491 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
2492 */
2494 static VALUE
2496 {
2505 }
2509 }
2511 /* check if idx is Range */
2513 }
2517 }
2519 /*
2520 * call-seq:
2521 * array.insert(index, *objects) -> self
2522 *
2523 * Inserts given +objects+ before or after the element at Integer index +offset+;
2524 * returns +self+.
2525 *
2526 * When +index+ is non-negative, inserts all given +objects+
2527 * before the element at offset +index+:
2528 *
2529 * a = [:foo, 'bar', 2]
2530 * a.insert(1, :bat, :bam) # => [:foo, :bat, :bam, "bar", 2]
2531 *
2532 * Extends the array if +index+ is beyond the array (<tt>index >= self.size</tt>):
2533 *
2534 * a = [:foo, 'bar', 2]
2535 * a.insert(5, :bat, :bam)
2536 * a # => [:foo, "bar", 2, nil, nil, :bat, :bam]
2537 *
2538 * Does nothing if no objects given:
2539 *
2540 * a = [:foo, 'bar', 2]
2541 * a.insert(1)
2542 * a.insert(50)
2543 * a.insert(-50)
2544 * a # => [:foo, "bar", 2]
2545 *
2546 * When +index+ is negative, inserts all given +objects+
2547 * _after_ the element at offset <tt>index+self.size</tt>:
2548 *
2549 * a = [:foo, 'bar', 2]
2550 * a.insert(-2, :bat, :bam)
2551 * a # => [:foo, "bar", :bat, :bam, 2]
2552 *
2553 */
2555 static VALUE
2557 {
2566 }
2572 }
2573 pos++;
2574 }
2577 }
2579 static VALUE
2582 static VALUE
2584 {
2586 }
2588 // Primitive to avoid a race condition in Array#each.
2589 // Return `true` and write `value` and `index` if the element exists.
2590 static VALUE
2592 {
2596 }
2600 }
2602 VALUE
2604 {
2610 }
2612 }
2614 /*
2615 * call-seq:
2616 * array.each_index {|index| ... } -> self
2617 * array.each_index -> Enumerator
2618 *
2619 * Iterates over array indexes.
2620 *
2621 * When a block given, passes each successive array index to the block;
2622 * returns +self+:
2623 *
2624 * a = [:foo, 'bar', 2]
2625 * a.each_index {|index| puts "#{index} #{a[index]}" }
2626 *
2627 * Output:
2628 *
2629 * 0 foo
2630 * 1 bar
2631 * 2 2
2632 *
2633 * Allows the array to be modified during iteration:
2634 *
2635 * a = [:foo, 'bar', 2]
2636 * a.each_index {|index| puts index; a.clear if index > 0 }
2637 *
2638 * Output:
2639 *
2640 * 0
2641 * 1
2642 *
2643 * When no block given, returns a new Enumerator:
2644 *
2645 * a = [:foo, 'bar', 2]
2646 * e = a.each_index
2647 * e # => #<Enumerator: [:foo, "bar", 2]:each_index>
2648 * a1 = e.each {|index| puts "#{index} #{a[index]}"}
2649 *
2650 * Output:
2651 *
2652 * 0 foo
2653 * 1 bar
2654 * 2 2
2655 *
2656 * Related: #each, #reverse_each.
2657 */
2659 static VALUE
2661 {
2667 }
2669 }
2671 /*
2672 * call-seq:
2673 * array.reverse_each {|element| ... } -> self
2674 * array.reverse_each -> Enumerator
2675 *
2676 * Iterates backwards over array elements.
2677 *
2678 * When a block given, passes, in reverse order, each element to the block;
2679 * returns +self+:
2680 *
2681 * a = [:foo, 'bar', 2]
2682 * a.reverse_each {|element| puts "#{element.class} #{element}" }
2683 *
2684 * Output:
2685 *
2686 * Integer 2
2687 * String bar
2688 * Symbol foo
2689 *
2690 * Allows the array to be modified during iteration:
2691 *
2692 * a = [:foo, 'bar', 2]
2693 * a.reverse_each {|element| puts element; a.clear if element.to_s.start_with?('b') }
2694 *
2695 * Output:
2696 *
2697 * 2
2698 * bar
2699 *
2700 * When no block given, returns a new Enumerator:
2701 *
2702 * a = [:foo, 'bar', 2]
2703 * e = a.reverse_each
2704 * e # => #<Enumerator: [:foo, "bar", 2]:reverse_each>
2705 * a1 = e.each {|element| puts "#{element.class} #{element}" }
2706 *
2707 * Output:
2708 *
2709 * Integer 2
2710 * String bar
2711 * Symbol foo
2712 *
2713 * Related: #each, #each_index.
2714 */
2716 static VALUE
2718 {
2729 }
2730 }
2732 }
2734 /*
2735 * call-seq:
2736 * array.length -> an_integer
2737 *
2738 * Returns the count of elements in +self+.
2739 */
2741 static VALUE
2743 {
2746 }
2748 /*
2749 * call-seq:
2750 * array.empty? -> true or false
2751 *
2752 * Returns +true+ if the count of elements in +self+ is zero,
2753 * +false+ otherwise.
2754 */
2756 static VALUE
2758 {
2760 }
2762 VALUE
2764 {
2773 }
2775 VALUE
2777 {
2779 }
2785 static VALUE
2787 {
2796 }
2799 }
2801 }
2803 static long
2805 {
2807 VALUE val;
2816 }
2818 }
2820 static void
2822 {
2827 }
2828 }
2830 static void
2832 {
2835 }
2845 }
2846 }
2848 static void
2850 {
2860 }
2863 }
2866 }
2869 }
2872 }
2873 }
2874 }
2876 VALUE
2878 {
2887 }
2902 }
2905 }
2913 }
2915 /*
2916 * call-seq:
2917 * array.join ->new_string
2918 * array.join(separator = $,) -> new_string
2919 *
2920 * Returns the new String formed by joining the array elements after conversion.
2921 * For each element +element+:
2922 *
2923 * - Uses <tt>element.to_s</tt> if +element+ is not a <tt>kind_of?(Array)</tt>.
2924 * - Uses recursive <tt>element.join(separator)</tt> if +element+ is a <tt>kind_of?(Array)</tt>.
2925 *
2926 * With no argument, joins using the output field separator, <tt>$,</tt>:
2927 *
2928 * a = [:foo, 'bar', 2]
2929 * $, # => nil
2930 * a.join # => "foobar2"
2931 *
2932 * With \string argument +separator+, joins using that separator:
2933 *
2934 * a = [:foo, 'bar', 2]
2935 * a.join("\n") # => "foo\nbar\n2"
2936 *
2937 * Joins recursively for nested Arrays:
2938 *
2939 * a = [:foo, [:bar, [:baz, :bat]]]
2940 * a.join # => "foobarbazbat"
2941 *
2942 */
2943 static VALUE
2945 {
2946 VALUE sep;
2952 }
2953 }
2956 }
2958 static VALUE
2960 {
2971 }
2974 }
2976 /*
2977 * call-seq:
2978 * array.inspect -> new_string
2979 *
2980 * Returns the new String formed by calling method <tt>#inspect</tt>
2981 * on each array element:
2982 *
2983 * a = [:foo, 'bar', 2]
2984 * a.inspect # => "[:foo, \"bar\", 2]"
2985 *
2986 */
2988 static VALUE
2990 {
2993 }
2995 VALUE
2997 {
2999 }
3001 /*
3002 * call-seq:
3003 * to_a -> self or new_array
3004 *
3005 * When +self+ is an instance of +Array+, returns +self+:
3006 *
3007 * a = [:foo, 'bar', 2]
3008 * a.to_a # => [:foo, "bar", 2]
3009 *
3010 * Otherwise, returns a new +Array+ containing the elements of +self+:
3011 *
3012 * class MyArray < Array; end
3013 * a = MyArray.new(['foo', 'bar', 'two'])
3014 * a.instance_of?(Array) # => false
3015 * a.kind_of?(Array) # => true
3016 * a1 = a.to_a
3017 * a1 # => ["foo", "bar", "two"]
3018 * a1.class # => Array # Not MyArray
3019 *
3020 */
3022 static VALUE
3024 {
3029 }
3031 }
3033 /*
3034 * call-seq:
3035 * array.to_h -> new_hash
3036 * array.to_h {|item| ... } -> new_hash
3037 *
3038 * Returns a new Hash formed from +self+.
3039 *
3040 * When a block is given, calls the block with each array element;
3041 * the block must return a 2-element +Array+ whose two elements
3042 * form a key-value pair in the returned Hash:
3043 *
3044 * a = ['foo', :bar, 1, [2, 3], {baz: 4}]
3045 * h = a.to_h {|item| [item, item] }
3046 * h # => {"foo"=>"foo", :bar=>:bar, 1=>1, [2, 3]=>[2, 3], {:baz=>4}=>{:baz=>4}}
3047 *
3048 * When no block is given, +self+ must be an +Array+ of 2-element sub-arrays,
3049 * each sub-array is formed into a key-value pair in the new Hash:
3050 *
3051 * [].to_h # => {}
3052 * a = [['foo', 'zero'], ['bar', 'one'], ['baz', 'two']]
3053 * h = a.to_h
3054 * h # => {"foo"=>"zero", "bar"=>"one", "baz"=>"two"}
3055 *
3056 */
3058 static VALUE
3060 {
3072 }
3076 }
3078 }
3080 }
3082 /*
3083 * call-seq:
3084 * array.to_ary -> self
3085 *
3086 * Returns +self+.
3087 */
3089 static VALUE
3091 {
3093 }
3095 static void
3097 {
3102 }
3103 }
3105 VALUE
3107 {
3117 }
3119 }
3121 /*
3122 * call-seq:
3123 * array.reverse! -> self
3124 *
3125 * Reverses +self+ in place:
3126 *
3127 * a = ['foo', 'bar', 'two']
3128 * a.reverse! # => ["two", "bar", "foo"]
3129 *
3130 */
3132 static VALUE
3134 {
3136 }
3138 /*
3139 * call-seq:
3140 * array.reverse -> new_array
3141 *
3142 * Returns a new +Array+ with the elements of +self+ in reverse order:
3143 *
3144 * a = ['foo', 'bar', 'two']
3145 * a1 = a.reverse
3146 * a1 # => ["two", "bar", "foo"]
3147 *
3148 */
3150 static VALUE
3152 {
3160 }
3163 }
3167 {
3169 }
3171 static void
3173 {
3178 }
3183 }
3189 }
3190 }
3192 VALUE
3194 {
3202 }
3203 }
3205 }
3207 /*
3208 * call-seq:
3209 * array.rotate! -> self
3210 * array.rotate!(count) -> self
3211 *
3212 * Rotates +self+ in place by moving elements from one end to the other; returns +self+.
3213 *
3214 * When no argument given, rotates the first element to the last position:
3215 *
3216 * a = [:foo, 'bar', 2, 'bar']
3217 * a.rotate! # => ["bar", 2, "bar", :foo]
3218 *
3219 * When given a non-negative Integer +count+,
3220 * rotates +count+ elements from the beginning to the end:
3221 *
3222 * a = [:foo, 'bar', 2]
3223 * a.rotate!(2)
3224 * a # => [2, :foo, "bar"]
3225 *
3226 * If +count+ is large, uses <tt>count % array.size</tt> as the count:
3227 *
3228 * a = [:foo, 'bar', 2]
3229 * a.rotate!(20)
3230 * a # => [2, :foo, "bar"]
3231 *
3232 * If +count+ is zero, returns +self+ unmodified:
3233 *
3234 * a = [:foo, 'bar', 2]
3235 * a.rotate!(0)
3236 * a # => [:foo, "bar", 2]
3237 *
3238 * When given a negative Integer +count+, rotates in the opposite direction,
3239 * from end to beginning:
3240 *
3241 * a = [:foo, 'bar', 2]
3242 * a.rotate!(-2)
3243 * a # => ["bar", 2, :foo]
3244 *
3245 * If +count+ is small (far from zero), uses <tt>count % array.size</tt> as the count:
3246 *
3247 * a = [:foo, 'bar', 2]
3248 * a.rotate!(-5)
3249 * a # => ["bar", 2, :foo]
3250 *
3251 */
3253 static VALUE
3255 {
3259 }
3261 /*
3262 * call-seq:
3263 * array.rotate -> new_array
3264 * array.rotate(count) -> new_array
3265 *
3266 * Returns a new +Array+ formed from +self+ with elements
3267 * rotated from one end to the other.
3268 *
3269 * When no argument given, returns a new +Array+ that is like +self+,
3270 * except that the first element has been rotated to the last position:
3271 *
3272 * a = [:foo, 'bar', 2, 'bar']
3273 * a1 = a.rotate
3274 * a1 # => ["bar", 2, "bar", :foo]
3275 *
3276 * When given a non-negative Integer +count+,
3277 * returns a new +Array+ with +count+ elements rotated from the beginning to the end:
3278 *
3279 * a = [:foo, 'bar', 2]
3280 * a1 = a.rotate(2)
3281 * a1 # => [2, :foo, "bar"]
3282 *
3283 * If +count+ is large, uses <tt>count % array.size</tt> as the count:
3284 *
3285 * a = [:foo, 'bar', 2]
3286 * a1 = a.rotate(20)
3287 * a1 # => [2, :foo, "bar"]
3288 *
3289 * If +count+ is zero, returns a copy of +self+, unmodified:
3290 *
3291 * a = [:foo, 'bar', 2]
3292 * a1 = a.rotate(0)
3293 * a1 # => [:foo, "bar", 2]
3294 *
3295 * When given a negative Integer +count+, rotates in the opposite direction,
3296 * from end to beginning:
3297 *
3298 * a = [:foo, 'bar', 2]
3299 * a1 = a.rotate(-2)
3300 * a1 # => ["bar", 2, :foo]
3301 *
3302 * If +count+ is small (far from zero), uses <tt>count % array.size</tt> as the count:
3303 *
3304 * a = [:foo, 'bar', 2]
3305 * a1 = a.rotate(-5)
3306 * a1 # => ["bar", 2, :foo]
3307 *
3308 */
3310 static VALUE
3312 {
3313 VALUE rotated;
3326 }
3329 }
3332 VALUE ary;
3333 VALUE receiver;
3334 };
3336 static VALUE
3338 {
3341 }
3343 }
3345 static void
3347 {
3350 }
3352 }
3354 static int
3356 {
3369 }
3371 static int
3373 {
3383 }
3386 }
3389 }
3396 }
3398 /*
3399 * call-seq:
3400 * array.sort! -> self
3401 * array.sort! {|a, b| ... } -> self
3402 *
3403 * Returns +self+ with its elements sorted in place.
3404 *
3405 * With no block, compares elements using operator <tt><=></tt>
3406 * (see Comparable):
3407 *
3408 * a = 'abcde'.split('').shuffle
3409 * a # => ["e", "b", "d", "a", "c"]
3410 * a.sort!
3411 * a # => ["a", "b", "c", "d", "e"]
3412 *
3413 * With a block, calls the block with each element pair;
3414 * for each element pair +a+ and +b+, the block should return an integer:
3415 *
3416 * - Negative when +b+ is to follow +a+.
3417 * - Zero when +a+ and +b+ are equivalent.
3418 * - Positive when +a+ is to follow +b+.
3419 *
3420 * Example:
3421 *
3422 * a = 'abcde'.split('').shuffle
3423 * a # => ["e", "b", "d", "a", "c"]
3424 * a.sort! {|a, b| a <=> b }
3425 * a # => ["a", "b", "c", "d", "e"]
3426 * a.sort! {|a, b| b <=> a }
3427 * a # => ["e", "d", "c", "b", "a"]
3428 *
3429 * When the block returns zero, the order for +a+ and +b+ is indeterminate,
3430 * and may be unstable:
3431 *
3432 * a = 'abcde'.split('').shuffle
3433 * a # => ["e", "b", "d", "a", "c"]
3434 * a.sort! {|a, b| 0 }
3435 * a # => ["d", "e", "c", "a", "b"]
3436 *
3437 */
3439 VALUE
3441 {
3460 }
3463 }
3466 }
3471 }
3476 }
3478 /* ary might be destructively operated in the given block */
3480 }
3483 }
3487 }
3488 /* tmp was lost ownership for the ptr */
3493 }
3494 /* tmp will be GC'ed. */
3496 }
3499 }
3501 /*
3502 * call-seq:
3503 * array.sort -> new_array
3504 * array.sort {|a, b| ... } -> new_array
3505 *
3506 * Returns a new +Array+ whose elements are those from +self+, sorted.
3507 *
3508 * With no block, compares elements using operator <tt><=></tt>
3509 * (see Comparable):
3510 *
3511 * a = 'abcde'.split('').shuffle
3512 * a # => ["e", "b", "d", "a", "c"]
3513 * a1 = a.sort
3514 * a1 # => ["a", "b", "c", "d", "e"]
3515 *
3516 * With a block, calls the block with each element pair;
3517 * for each element pair +a+ and +b+, the block should return an integer:
3518 *
3519 * - Negative when +b+ is to follow +a+.
3520 * - Zero when +a+ and +b+ are equivalent.
3521 * - Positive when +a+ is to follow +b+.
3522 *
3523 * Example:
3524 *
3525 * a = 'abcde'.split('').shuffle
3526 * a # => ["e", "b", "d", "a", "c"]
3527 * a1 = a.sort {|a, b| a <=> b }
3528 * a1 # => ["a", "b", "c", "d", "e"]
3529 * a2 = a.sort {|a, b| b <=> a }
3530 * a2 # => ["e", "d", "c", "b", "a"]
3531 *
3532 * When the block returns zero, the order for +a+ and +b+ is indeterminate,
3533 * and may be unstable:
3534 *
3535 * a = 'abcde'.split('').shuffle
3536 * a # => ["e", "b", "d", "a", "c"]
3537 * a1 = a.sort {|a, b| 0 }
3538 * a1 # => ["c", "e", "b", "d", "a"]
3539 *
3540 * Related: Enumerable#sort_by.
3541 */
3543 VALUE
3545 {
3549 }
3553 /*
3554 * call-seq:
3555 * bsearch {|element| ... } -> found_element or nil
3556 * bsearch -> new_enumerator
3557 *
3558 * Returns the element from +self+ found by a binary search,
3559 * or +nil+ if the search found no suitable element.
3560 *
3561 * See {Binary Searching}[rdoc-ref:bsearch.rdoc].
3562 *
3563 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
3564 */
3566 static VALUE
3568 {
3573 }
3575 }
3577 /*
3578 * call-seq:
3579 * bsearch_index {|element| ... } -> integer or nil
3580 * bsearch_index -> new_enumerator
3581 *
3582 * Returns the integer index of the element from +self+ found by a binary search,
3583 * or +nil+ if the search found no suitable element.
3584 *
3585 * See {Binary Searching}[rdoc-ref:bsearch.rdoc].
3586 *
3587 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
3588 */
3590 static VALUE
3592 {
3605 }
3609 }
3612 }
3619 }
3620 }
3625 }
3628 }
3631 }
3632 }
3635 }
3638 static VALUE
3640 {
3642 }
3644 /*
3645 * call-seq:
3646 * array.sort_by! {|element| ... } -> self
3647 * array.sort_by! -> new_enumerator
3648 *
3649 * Sorts the elements of +self+ in place,
3650 * using an ordering determined by the block; returns self.
3651 *
3652 * Calls the block with each successive element;
3653 * sorts elements based on the values returned from the block.
3654 *
3655 * For duplicates returned by the block, the ordering is indeterminate, and may be unstable.
3656 *
3657 * This example sorts strings based on their sizes:
3658 *
3659 * a = ['aaaa', 'bbb', 'cc', 'd']
3660 * a.sort_by! {|element| element.size }
3661 * a # => ["d", "cc", "bbb", "aaaa"]
3662 *
3663 * Returns a new Enumerator if no block given:
3664 *
3665 * a = ['aaaa', 'bbb', 'cc', 'd']
3666 * a.sort_by! # => #<Enumerator: ["aaaa", "bbb", "cc", "d"]:sort_by!>
3667 *
3668 */
3670 static VALUE
3672 {
3673 VALUE sorted;
3680 }
3683 /*
3684 * call-seq:
3685 * collect {|element| ... } -> new_array
3686 * collect -> new_enumerator
3687 * map {|element| ... } -> new_array
3688 * map -> new_enumerator
3689 *
3690 * With a block given, calls the block with each element of +self+;
3691 * returns a new array whose elements are the return values from the block:
3692 *
3693 * a = [:foo, 'bar', 2]
3694 * a1 = a.map {|element| element.class }
3695 * a1 # => [Symbol, String, Integer]
3696 *
3697 * With no block given, returns a new Enumerator.
3698 *
3699 * Related: #collect!;
3700 * see also {Methods for Converting}[rdoc-ref:Array@Methods+for+Converting].
3701 */
3703 static VALUE
3705 {
3707 VALUE collect;
3713 }
3715 }
3718 /*
3719 * call-seq:
3720 * collect! {|element| ... } -> new_array
3721 * collect! -> new_enumerator
3722 * map! {|element| ... } -> new_array
3723 * map! -> new_enumerator
3724 *
3725 * With a block given, calls the block with each element of +self+
3726 * and replaces the element with the block's return value;
3727 * returns +self+:
3728 *
3729 * a = [:foo, 'bar', 2]
3730 * a.map! { |element| element.class } # => [Symbol, String, Integer]
3731 *
3732 * With no block given, returns a new Enumerator.
3733 *
3734 * Related: #collect;
3735 * see also {Methods for Converting}[rdoc-ref:Array@Methods+for+Converting].
3736 */
3738 static VALUE
3740 {
3747 }
3749 }
3751 VALUE
3752 rb_get_values_at(VALUE obj, long olen, int argc, const VALUE *argv, VALUE (*func) (VALUE, long))
3753 {
3761 }
3762 /* check if idx is Range */
3767 }
3771 }
3773 }
3775 }
3777 static VALUE
3779 {
3783 }
3784 /* check if idx is Range */
3792 }
3795 }
3796 }
3798 }
3801 }
3803 }
3805 /*
3806 * call-seq:
3807 * array.values_at(*indexes) -> new_array
3808 *
3809 * Returns a new +Array+ whose elements are the elements
3810 * of +self+ at the given Integer or Range +indexes+.
3811 *
3812 * For each positive +index+, returns the element at offset +index+:
3813 *
3814 * a = [:foo, 'bar', 2]
3815 * a.values_at(0, 2) # => [:foo, 2]
3816 * a.values_at(0..1) # => [:foo, "bar"]
3817 *
3818 * The given +indexes+ may be in any order, and may repeat:
3819 *
3820 * a = [:foo, 'bar', 2]
3821 * a.values_at(2, 0, 1, 0, 2) # => [2, :foo, "bar", :foo, 2]
3822 * a.values_at(1, 0..2) # => ["bar", :foo, "bar", 2]
3823 *
3824 * Assigns +nil+ for an +index+ that is too large:
3825 *
3826 * a = [:foo, 'bar', 2]
3827 * a.values_at(0, 3, 1, 3) # => [:foo, nil, "bar", nil]
3828 *
3829 * Returns a new empty +Array+ if no arguments given.
3830 *
3831 * For each negative +index+, counts backward from the end of the array:
3832 *
3833 * a = [:foo, 'bar', 2]
3834 * a.values_at(-1, -3) # => [2, :foo]
3835 *
3836 * Assigns +nil+ for an +index+ that is too small:
3837 *
3838 * a = [:foo, 'bar', 2]
3839 * a.values_at(0, -5, 1, -6, 2) # => [:foo, nil, "bar", nil, 2]
3840 *
3841 * The given +indexes+ may have a mixture of signs:
3842 *
3843 * a = [:foo, 'bar', 2]
3844 * a.values_at(0, -2, 1, -1) # => [:foo, "bar", "bar", 2]
3845 *
3846 */
3848 static VALUE
3850 {
3855 }
3858 }
3861 /*
3862 * call-seq:
3863 * array.select {|element| ... } -> new_array
3864 * array.select -> new_enumerator
3865 *
3866 * Calls the block, if given, with each element of +self+;
3867 * returns a new +Array+ containing those elements of +self+
3868 * for which the block returns a truthy value:
3869 *
3870 * a = [:foo, 'bar', 2, :bam]
3871 * a1 = a.select {|element| element.to_s.start_with?('b') }
3872 * a1 # => ["bar", :bam]
3873 *
3874 * Returns a new Enumerator if no block given:
3875 *
3876 * a = [:foo, 'bar', 2, :bam]
3877 * a.select # => #<Enumerator: [:foo, "bar", 2, :bam]:select>
3878 *
3879 */
3881 static VALUE
3883 {
3884 VALUE result;
3892 }
3893 }
3895 }
3898 VALUE ary;
3900 };
3902 static VALUE
3904 {
3914 }
3916 }
3918 }
3920 static VALUE
3922 {
3935 });
3936 }
3938 }
3940 }
3942 /*
3943 * call-seq:
3944 * array.select! {|element| ... } -> self or nil
3945 * array.select! -> new_enumerator
3946 *
3947 * Calls the block, if given with each element of +self+;
3948 * removes from +self+ those elements for which the block returns +false+ or +nil+.
3949 *
3950 * Returns +self+ if any elements were removed:
3951 *
3952 * a = [:foo, 'bar', 2, :bam]
3953 * a.select! {|element| element.to_s.start_with?('b') } # => ["bar", :bam]
3954 *
3955 * Returns +nil+ if no elements were removed.
3956 *
3957 * Returns a new Enumerator if no block given:
3958 *
3959 * a = [:foo, 'bar', 2, :bam]
3960 * a.select! # => #<Enumerator: [:foo, "bar", 2, :bam]:select!>
3961 *
3962 */
3964 static VALUE
3966 {
3975 }
3977 /*
3978 * call-seq:
3979 * array.keep_if {|element| ... } -> self
3980 * array.keep_if -> new_enumeration
3981 *
3982 * Retains those elements for which the block returns a truthy value;
3983 * deletes all other elements; returns +self+:
3984 *
3985 * a = [:foo, 'bar', 2, :bam]
3986 * a.keep_if {|element| element.to_s.start_with?('b') } # => ["bar", :bam]
3987 *
3988 * Returns a new Enumerator if no block given:
3989 *
3990 * a = [:foo, 'bar', 2, :bam]
3991 * a.keep_if # => #<Enumerator: [:foo, "bar", 2, :bam]:keep_if>
3992 *
3993 */
3995 static VALUE
3997 {
4001 }
4003 static void
4005 {
4012 }
4013 }
4014 }
4016 /*
4017 * call-seq:
4018 * delete(object) -> last_removed_object
4019 * delete(object) {|element| ... } -> last_removed_object or block_return
4020 *
4021 * Removes zero or more elements from +self+.
4022 *
4023 * With no block given,
4024 * removes from +self+ each element +ele+ such that <tt>ele == object</tt>;
4025 * returns the last removed element:
4026 *
4027 * a = [0, 1, 2, 2.0]
4028 * a.delete(2) # => 2.0
4029 * a # => [0, 1]
4030 *
4031 * Returns +nil+ if no elements removed:
4032 *
4033 * a.delete(2) # => nil
4034 *
4035 * With a block given,
4036 * removes from +self+ each element +ele+ such that <tt>ele == object</tt>.
4037 *
4038 * If any such elements are found, ignores the block
4039 * and returns the last removed element:
4040 *
4041 * a = [0, 1, 2, 2.0]
4042 * a.delete(2) {|element| fail 'Cannot happen' } # => 2.0
4043 * a # => [0, 1]
4044 *
4045 * If no such element is found, returns the block's return value:
4046 *
4047 * a.delete(2) {|element| "Element #{element} not found." }
4048 * # => "Element 2 not found."
4049 *
4050 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
4051 */
4053 VALUE
4055 {
4065 }
4068 }
4069 i2++;
4070 }
4074 }
4076 }
4082 }
4084 void
4086 {
4094 }
4097 }
4098 i2++;
4099 }
4102 }
4105 }
4107 VALUE
4109 {
4111 VALUE del;
4117 }
4123 });
4127 }
4129 /*
4130 * call-seq:
4131 * delete_at(index) -> removed_object or nil
4132 *
4133 * Removes the element of +self+ at the given +index+, which must be an
4134 * {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects].
4135 *
4136 * When +index+ is non-negative, deletes the element at offset +index+:
4137 *
4138 * a = [:foo, 'bar', 2]
4139 * a.delete_at(1) # => "bar"
4140 * a # => [:foo, 2]
4141 *
4142 * When +index+ is negative, counts backward from the end of the array:
4143 *
4144 * a = [:foo, 'bar', 2]
4145 * a.delete_at(-2) # => "bar"
4146 * a # => [:foo, 2]
4147 *
4148 * When +index+ is out of range, returns +nil+.
4149 *
4150 * a = [:foo, 'bar', 2]
4151 * a.delete_at(3) # => nil
4152 * a.delete_at(-4) # => nil
4153 *
4154 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
4155 */
4157 static VALUE
4159 {
4161 }
4163 static VALUE
4165 {
4170 }
4173 }
4176 }
4179 }
4182 }
4185 }
4190 }
4191 }
4193 /*
4194 * call-seq:
4195 * array.slice!(n) -> object or nil
4196 * array.slice!(start, length) -> new_array or nil
4197 * array.slice!(range) -> new_array or nil
4198 *
4199 * Removes and returns elements from +self+.
4200 *
4201 * When the only argument is an Integer +n+,
4202 * removes and returns the _nth_ element in +self+:
4203 *
4204 * a = [:foo, 'bar', 2]
4205 * a.slice!(1) # => "bar"
4206 * a # => [:foo, 2]
4207 *
4208 * If +n+ is negative, counts backwards from the end of +self+:
4209 *
4210 * a = [:foo, 'bar', 2]
4211 * a.slice!(-1) # => 2
4212 * a # => [:foo, "bar"]
4213 *
4214 * If +n+ is out of range, returns +nil+.
4215 *
4216 * When the only arguments are Integers +start+ and +length+,
4217 * removes +length+ elements from +self+ beginning at offset +start+;
4218 * returns the deleted objects in a new +Array+:
4219 *
4220 * a = [:foo, 'bar', 2]
4221 * a.slice!(0, 2) # => [:foo, "bar"]
4222 * a # => [2]
4223 *
4224 * If <tt>start + length</tt> exceeds the array size,
4225 * removes and returns all elements from offset +start+ to the end:
4226 *
4227 * a = [:foo, 'bar', 2]
4228 * a.slice!(1, 50) # => ["bar", 2]
4229 * a # => [:foo]
4230 *
4231 * If <tt>start == a.size</tt> and +length+ is non-negative,
4232 * returns a new empty +Array+.
4233 *
4234 * If +length+ is negative, returns +nil+.
4235 *
4236 * When the only argument is a Range object +range+,
4237 * treats <tt>range.min</tt> as +start+ above and <tt>range.size</tt> as +length+ above:
4238 *
4239 * a = [:foo, 'bar', 2]
4240 * a.slice!(1..2) # => ["bar", 2]
4241 * a # => [:foo]
4242 *
4243 * If <tt>range.start == a.size</tt>, returns a new empty +Array+.
4244 *
4245 * If <tt>range.start</tt> is larger than the array size, returns +nil+.
4246 *
4247 * If <tt>range.end</tt> is negative, counts backwards from the end of the array:
4248 *
4249 * a = [:foo, 'bar', 2]
4250 * a.slice!(0..-2) # => [:foo, "bar"]
4251 * a # => [2]
4252 *
4253 * If <tt>range.start</tt> is negative,
4254 * calculates the start index backwards from the end of the array:
4255 *
4256 * a = [:foo, 'bar', 2]
4257 * a.slice!(-2..2) # => ["bar", 2]
4258 * a # => [:foo]
4259 *
4260 */
4262 static VALUE
4264 {
4265 VALUE arg1;
4276 }
4281 /* valid range */
4284 /* invalid range */
4287 /* not a range */
4289 }
4290 }
4293 }
4295 static VALUE
4297 {
4305 }
4306 }
4308 }
4310 static VALUE
4312 {
4322 }
4324 }
4326 }
4328 static VALUE
4330 {
4336 }
4338 /*
4339 * call-seq:
4340 * array.reject! {|element| ... } -> self or nil
4341 * array.reject! -> new_enumerator
4342 *
4343 * Removes each element for which the block returns a truthy value.
4344 *
4345 * Returns +self+ if any elements removed:
4346 *
4347 * a = [:foo, 'bar', 2, 'bat']
4348 * a.reject! {|element| element.to_s.start_with?('b') } # => [:foo, 2]
4349 *
4350 * Returns +nil+ if no elements removed.
4351 *
4352 * Returns a new Enumerator if no block given:
4353 *
4354 * a = [:foo, 'bar', 2]
4355 * a.reject! # => #<Enumerator: [:foo, "bar", 2]:reject!>
4356 *
4357 */
4359 static VALUE
4361 {
4365 }
4367 /*
4368 * call-seq:
4369 * array.reject {|element| ... } -> new_array
4370 * array.reject -> new_enumerator
4371 *
4372 * Returns a new +Array+ whose elements are all those from +self+
4373 * for which the block returns +false+ or +nil+:
4374 *
4375 * a = [:foo, 'bar', 2, 'bat']
4376 * a1 = a.reject {|element| element.to_s.start_with?('b') }
4377 * a1 # => [:foo, 2]
4378 *
4379 * Returns a new Enumerator if no block given:
4380 *
4381 * a = [:foo, 'bar', 2]
4382 * a.reject # => #<Enumerator: [:foo, "bar", 2]:reject>
4383 *
4384 */
4386 static VALUE
4388 {
4389 VALUE rejected_ary;
4395 }
4397 /*
4398 * call-seq:
4399 * delete_if {|element| ... } -> self
4400 * delete_if -> new_numerator
4401 *
4402 * With a block given, calls the block with each element of +self+;
4403 * removes the element if the block returns a truthy value;
4404 * returns +self+:
4405 *
4406 * a = [:foo, 'bar', 2, 'bat']
4407 * a.delete_if {|element| element.to_s.start_with?('b') } # => [:foo, 2]
4408 *
4409 * With no block given, returns a new Enumerator.
4410 *
4411 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
4412 */
4414 static VALUE
4416 {
4421 }
4423 static VALUE
4425 {
4431 }
4433 static VALUE
4435 {
4447 }
4450 /*
4451 * call-seq:
4452 * array.zip(*other_arrays) -> new_array
4453 * array.zip(*other_arrays) {|other_array| ... } -> nil
4454 *
4455 * When no block given, returns a new +Array+ +new_array+ of size <tt>self.size</tt>
4456 * whose elements are Arrays.
4457 *
4458 * Each nested array <tt>new_array[n]</tt> is of size <tt>other_arrays.size+1</tt>,
4459 * and contains:
4460 *
4461 * - The _nth_ element of +self+.
4462 * - The _nth_ element of each of the +other_arrays+.
4463 *
4464 * If all +other_arrays+ and +self+ are the same size:
4465 *
4466 * a = [:a0, :a1, :a2, :a3]
4467 * b = [:b0, :b1, :b2, :b3]
4468 * c = [:c0, :c1, :c2, :c3]
4469 * d = a.zip(b, c)
4470 * d # => [[:a0, :b0, :c0], [:a1, :b1, :c1], [:a2, :b2, :c2], [:a3, :b3, :c3]]
4471 *
4472 * If any array in +other_arrays+ is smaller than +self+,
4473 * fills to <tt>self.size</tt> with +nil+:
4474 *
4475 * a = [:a0, :a1, :a2, :a3]
4476 * b = [:b0, :b1, :b2]
4477 * c = [:c0, :c1]
4478 * d = a.zip(b, c)
4479 * d # => [[:a0, :b0, :c0], [:a1, :b1, :c1], [:a2, :b2, nil], [:a3, nil, nil]]
4480 *
4481 * If any array in +other_arrays+ is larger than +self+,
4482 * its trailing elements are ignored:
4483 *
4484 * a = [:a0, :a1, :a2, :a3]
4485 * b = [:b0, :b1, :b2, :b3, :b4]
4486 * c = [:c0, :c1, :c2, :c3, :c4, :c5]
4487 * d = a.zip(b, c)
4488 * d # => [[:a0, :b0, :c0], [:a1, :b1, :c1], [:a2, :b2, :c2], [:a3, :b3, :c3]]
4489 *
4490 * If an argument is not an array, it extracts the values by calling #each:
4491 *
4492 * a = [:a0, :a1, :a2, :a2]
4493 * b = 1..4
4494 * c = a.zip(b)
4495 * c # => [[:a0, 1], [:a1, 2], [:a2, 3], [:a2, 4]]
4496 *
4497 * When a block is given, calls the block with each of the sub-arrays (formed as above); returns +nil+:
4498 *
4499 * a = [:a0, :a1, :a2, :a3]
4500 * b = [:b0, :b1, :b2, :b3]
4501 * c = [:c0, :c1, :c2, :c3]
4502 * a.zip(b, c) {|sub_array| p sub_array} # => nil
4503 *
4504 * Output:
4505 *
4506 * [:a0, :b0, :c0]
4507 * [:a1, :b1, :c1]
4508 * [:a2, :b2, :c2]
4509 * [:a3, :b3, :c3]
4510 *
4511 */
4513 static VALUE
4515 {
4522 }
4536 }
4538 }
4541 }
4549 }
4551 }
4552 }
4553 }
4563 }
4565 }
4566 }
4569 }
4571 /*
4572 * call-seq:
4573 * array.transpose -> new_array
4574 *
4575 * Transposes the rows and columns in an +Array+ of Arrays;
4576 * the nested Arrays must all be the same size:
4577 *
4578 * a = [[:a0, :a1], [:b0, :b1], [:c0, :c1]]
4579 * a.transpose # => [[:a0, :b0, :c0], [:a1, :b1, :c1]]
4580 *
4581 */
4583 static VALUE
4585 {
4598 }
4599 }
4603 }
4606 }
4607 }
4609 }
4611 /*
4612 * call-seq:
4613 * array.replace(other_array) -> self
4614 *
4615 * Replaces the content of +self+ with the content of +other_array+; returns +self+:
4616 *
4617 * a = [:foo, 'bar', 2]
4618 * a.replace(['foo', :bar, 3]) # => ["foo", :bar, 3]
4619 *
4620 */
4622 VALUE
4624 {
4631 /* orig has enough space to embed the contents of orig. */
4636 }
4637 /* orig is embedded but copy does not have enough space to embed the
4638 * contents of orig. */
4648 // No allocation and exception expected that could leave `copy` in a
4649 // bad state from the edits above.
4651 }
4652 /* Otherwise, orig is on heap and copy does not have enough space to embed
4653 * the contents of orig. */
4660 }
4663 }
4665 /*
4666 * call-seq:
4667 * clear -> self
4668 *
4669 * Removes all elements from +self+; returns +self+:
4670 *
4671 * a = [:foo, 'bar', 2]
4672 * a.clear # => []
4673 *
4674 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
4675 */
4677 VALUE
4679 {
4685 }
4690 }
4691 }
4694 }
4696 /*
4697 * call-seq:
4698 * array.fill(obj) -> self
4699 * array.fill(obj, start) -> self
4700 * array.fill(obj, start, length) -> self
4701 * array.fill(obj, range) -> self
4702 * array.fill {|index| ... } -> self
4703 * array.fill(start) {|index| ... } -> self
4704 * array.fill(start, length) {|index| ... } -> self
4705 * array.fill(range) {|index| ... } -> self
4706 *
4707 * Replaces specified elements in +self+ with specified objects; returns +self+.
4708 *
4709 * With argument +obj+ and no block given, replaces all elements with that one object:
4710 *
4711 * a = ['a', 'b', 'c', 'd']
4712 * a # => ["a", "b", "c", "d"]
4713 * a.fill(:X) # => [:X, :X, :X, :X]
4714 *
4715 * With arguments +obj+ and Integer +start+, and no block given,
4716 * replaces elements based on the given start.
4717 *
4718 * If +start+ is in range (<tt>0 <= start < array.size</tt>),
4719 * replaces all elements from offset +start+ through the end:
4720 *
4721 * a = ['a', 'b', 'c', 'd']
4722 * a.fill(:X, 2) # => ["a", "b", :X, :X]
4723 *
4724 * If +start+ is too large (<tt>start >= array.size</tt>), does nothing:
4725 *
4726 * a = ['a', 'b', 'c', 'd']
4727 * a.fill(:X, 4) # => ["a", "b", "c", "d"]
4728 * a = ['a', 'b', 'c', 'd']
4729 * a.fill(:X, 5) # => ["a", "b", "c", "d"]
4730 *
4731 * If +start+ is negative, counts from the end (starting index is <tt>start + array.size</tt>):
4732 *
4733 * a = ['a', 'b', 'c', 'd']
4734 * a.fill(:X, -2) # => ["a", "b", :X, :X]
4735 *
4736 * If +start+ is too small (less than and far from zero), replaces all elements:
4737 *
4738 * a = ['a', 'b', 'c', 'd']
4739 * a.fill(:X, -6) # => [:X, :X, :X, :X]
4740 * a = ['a', 'b', 'c', 'd']
4741 * a.fill(:X, -50) # => [:X, :X, :X, :X]
4742 *
4743 * With arguments +obj+, Integer +start+, and Integer +length+, and no block given,
4744 * replaces elements based on the given +start+ and +length+.
4745 *
4746 * If +start+ is in range, replaces +length+ elements beginning at offset +start+:
4747 *
4748 * a = ['a', 'b', 'c', 'd']
4749 * a.fill(:X, 1, 1) # => ["a", :X, "c", "d"]
4750 *
4751 * If +start+ is negative, counts from the end:
4752 *
4753 * a = ['a', 'b', 'c', 'd']
4754 * a.fill(:X, -2, 1) # => ["a", "b", :X, "d"]
4755 *
4756 * If +start+ is large (<tt>start >= array.size</tt>), extends +self+ with +nil+:
4757 *
4758 * a = ['a', 'b', 'c', 'd']
4759 * a.fill(:X, 5, 0) # => ["a", "b", "c", "d", nil]
4760 * a = ['a', 'b', 'c', 'd']
4761 * a.fill(:X, 5, 2) # => ["a", "b", "c", "d", nil, :X, :X]
4762 *
4763 * If +length+ is zero or negative, replaces no elements:
4764 *
4765 * a = ['a', 'b', 'c', 'd']
4766 * a.fill(:X, 1, 0) # => ["a", "b", "c", "d"]
4767 * a.fill(:X, 1, -1) # => ["a", "b", "c", "d"]
4768 *
4769 * With arguments +obj+ and Range +range+, and no block given,
4770 * replaces elements based on the given range.
4771 *
4772 * If the range is positive and ascending (<tt>0 < range.begin <= range.end</tt>),
4773 * replaces elements from <tt>range.begin</tt> to <tt>range.end</tt>:
4774 *
4775 * a = ['a', 'b', 'c', 'd']
4776 * a.fill(:X, (1..1)) # => ["a", :X, "c", "d"]
4777 *
4778 * If <tt>range.first</tt> is negative, replaces no elements:
4779 *
4780 * a = ['a', 'b', 'c', 'd']
4781 * a.fill(:X, (-1..1)) # => ["a", "b", "c", "d"]
4782 *
4783 * If <tt>range.last</tt> is negative, counts from the end:
4784 *
4785 * a = ['a', 'b', 'c', 'd']
4786 * a.fill(:X, (0..-2)) # => [:X, :X, :X, "d"]
4787 * a = ['a', 'b', 'c', 'd']
4788 * a.fill(:X, (1..-2)) # => ["a", :X, :X, "d"]
4789 *
4790 * If <tt>range.last</tt> and <tt>range.last</tt> are both negative,
4791 * both count from the end of the array:
4792 *
4793 * a = ['a', 'b', 'c', 'd']
4794 * a.fill(:X, (-1..-1)) # => ["a", "b", "c", :X]
4795 * a = ['a', 'b', 'c', 'd']
4796 * a.fill(:X, (-2..-2)) # => ["a", "b", :X, "d"]
4797 *
4798 * With no arguments and a block given, calls the block with each index;
4799 * replaces the corresponding element with the block's return value:
4800 *
4801 * a = ['a', 'b', 'c', 'd']
4802 * a.fill { |index| "new_#{index}" } # => ["new_0", "new_1", "new_2", "new_3"]
4803 *
4804 * With argument +start+ and a block given, calls the block with each index
4805 * from offset +start+ to the end; replaces the corresponding element
4806 * with the block's return value.
4807 *
4808 * If start is in range (<tt>0 <= start < array.size</tt>),
4809 * replaces from offset +start+ to the end:
4810 *
4811 * a = ['a', 'b', 'c', 'd']
4812 * a.fill(1) { |index| "new_#{index}" } # => ["a", "new_1", "new_2", "new_3"]
4813 *
4814 * If +start+ is too large(<tt>start >= array.size</tt>), does nothing:
4815 *
4816 * a = ['a', 'b', 'c', 'd']
4817 * a.fill(4) { |index| fail 'Cannot happen' } # => ["a", "b", "c", "d"]
4818 * a = ['a', 'b', 'c', 'd']
4819 * a.fill(4) { |index| fail 'Cannot happen' } # => ["a", "b", "c", "d"]
4820 *
4821 * If +start+ is negative, counts from the end:
4822 *
4823 * a = ['a', 'b', 'c', 'd']
4824 * a.fill(-2) { |index| "new_#{index}" } # => ["a", "b", "new_2", "new_3"]
4825 *
4826 * If start is too small (<tt>start <= -array.size</tt>, replaces all elements:
4827 *
4828 * a = ['a', 'b', 'c', 'd']
4829 * a.fill(-6) { |index| "new_#{index}" } # => ["new_0", "new_1", "new_2", "new_3"]
4830 * a = ['a', 'b', 'c', 'd']
4831 * a.fill(-50) { |index| "new_#{index}" } # => ["new_0", "new_1", "new_2", "new_3"]
4832 *
4833 * With arguments +start+ and +length+, and a block given,
4834 * calls the block for each index specified by start length;
4835 * replaces the corresponding element with the block's return value.
4836 *
4837 * If +start+ is in range, replaces +length+ elements beginning at offset +start+:
4838 *
4839 * a = ['a', 'b', 'c', 'd']
4840 * a.fill(1, 1) { |index| "new_#{index}" } # => ["a", "new_1", "c", "d"]
4841 *
4842 * If start is negative, counts from the end:
4843 *
4844 * a = ['a', 'b', 'c', 'd']
4845 * a.fill(-2, 1) { |index| "new_#{index}" } # => ["a", "b", "new_2", "d"]
4846 *
4847 * If +start+ is large (<tt>start >= array.size</tt>), extends +self+ with +nil+:
4848 *
4849 * a = ['a', 'b', 'c', 'd']
4850 * a.fill(5, 0) { |index| "new_#{index}" } # => ["a", "b", "c", "d", nil]
4851 * a = ['a', 'b', 'c', 'd']
4852 * a.fill(5, 2) { |index| "new_#{index}" } # => ["a", "b", "c", "d", nil, "new_5", "new_6"]
4853 *
4854 * If +length+ is zero or less, replaces no elements:
4855 *
4856 * a = ['a', 'b', 'c', 'd']
4857 * a.fill(1, 0) { |index| "new_#{index}" } # => ["a", "b", "c", "d"]
4858 * a.fill(1, -1) { |index| "new_#{index}" } # => ["a", "b", "c", "d"]
4859 *
4860 * With arguments +obj+ and +range+, and a block given,
4861 * calls the block with each index in the given range;
4862 * replaces the corresponding element with the block's return value.
4863 *
4864 * If the range is positive and ascending (<tt>range 0 < range.begin <= range.end</tt>,
4865 * replaces elements from <tt>range.begin</tt> to <tt>range.end</tt>:
4866 *
4867 * a = ['a', 'b', 'c', 'd']
4868 * a.fill(1..1) { |index| "new_#{index}" } # => ["a", "new_1", "c", "d"]
4869 *
4870 * If +range.first+ is negative, does nothing:
4871 *
4872 * a = ['a', 'b', 'c', 'd']
4873 * a.fill(-1..1) { |index| fail 'Cannot happen' } # => ["a", "b", "c", "d"]
4874 *
4875 * If <tt>range.last</tt> is negative, counts from the end:
4876 *
4877 * a = ['a', 'b', 'c', 'd']
4878 * a.fill(0..-2) { |index| "new_#{index}" } # => ["new_0", "new_1", "new_2", "d"]
4879 * a = ['a', 'b', 'c', 'd']
4880 * a.fill(1..-2) { |index| "new_#{index}" } # => ["a", "new_1", "new_2", "d"]
4881 *
4882 * If <tt>range.first</tt> and <tt>range.last</tt> are both negative,
4883 * both count from the end:
4884 *
4885 * a = ['a', 'b', 'c', 'd']
4886 * a.fill(-1..-1) { |index| "new_#{index}" } # => ["a", "b", "c", "new_3"]
4887 * a = ['a', 'b', 'c', 'd']
4888 * a.fill(-2..-2) { |index| "new_#{index}" } # => ["a", "b", "new_2", "d"]
4889 *
4890 */
4892 static VALUE
4894 {
4901 }
4904 }
4913 }
4914 /* fall through */
4920 }
4923 }
4927 }
4930 }
4935 }
4938 }
4941 VALUE v;
4948 }
4949 }
4952 }
4954 }
4956 /*
4957 * call-seq:
4958 * self + other_array -> new_array
4959 *
4960 * Returns a new array containing all elements of +self+
4961 * followed by all elements of +other_array+:
4962 *
4963 * a = [0, 1] + [2, 3]
4964 * a # => [0, 1, 2, 3]
4965 *
4966 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
4967 */
4969 VALUE
4971 {
4972 VALUE z;
4985 }
4987 static VALUE
4989 {
4993 }
4996 }
4998 /*
4999 * call-seq:
5000 * concat(*other_arrays) -> self
5001 *
5002 * Adds to +self+ all elements from each array in +other_arrays+; returns +self+:
5003 *
5004 * a = [0, 1]
5005 * a.concat(['two', 'three'], [:four, :five], a)
5006 * # => [0, 1, "two", "three", :four, :five, 0, 1]
5007 *
5008 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
5009 */
5011 static VALUE
5013 {
5018 }
5024 }
5026 }
5030 }
5032 VALUE
5034 {
5036 }
5038 /*
5039 * call-seq:
5040 * self * n -> new_array
5041 * self * string_separator -> new_string
5042 *
5043 * When non-negative integer argument +n+ is given,
5044 * returns a new array built by concatenating +n+ copies of +self+:
5045 *
5046 * a = ['x', 'y']
5047 * a * 3 # => ["x", "y", "x", "y", "x", "y"]
5048 *
5049 * When string argument +string_separator+ is given,
5050 * equivalent to <tt>array.join(string_separator)</tt>:
5051 *
5052 * [0, [0, 1], {foo: 0}] * ', ' # => "0, 0, 1, {:foo=>0}"
5053 *
5054 */
5056 static VALUE
5058 {
5066 }
5072 }
5075 }
5078 }
5091 }
5094 }
5095 }
5096 out:
5098 }
5100 /*
5101 * call-seq:
5102 * assoc(object) -> found_array or nil
5103 *
5104 * Returns the first element +ele+ in +self+ such that +ele+ is an array
5105 * and <tt>ele[0] == object</tt>:
5106 *
5107 * a = [{foo: 0}, [2, 4], [4, 5, 6], [4, 5]]
5108 * a.assoc(4) # => [4, 5, 6]
5109 *
5110 * Returns +nil+ if no such element is found.
5111 *
5112 * Related: Array#rassoc;
5113 * see also {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
5114 */
5116 VALUE
5118 {
5120 VALUE v;
5127 }
5129 }
5131 /*
5132 * call-seq:
5133 * array.rassoc(obj) -> found_array or nil
5134 *
5135 * Returns the first element in +self+ that is an +Array+
5136 * whose second element <tt>==</tt> +obj+:
5137 *
5138 * a = [{foo: 0}, [2, 4], [4, 5, 6], [4, 5]]
5139 * a.rassoc(4) # => [2, 4]
5140 *
5141 * Returns +nil+ if no such element is found.
5142 *
5143 * Related: #assoc.
5144 */
5146 VALUE
5148 {
5150 VALUE v;
5158 }
5160 }
5162 static VALUE
5164 {
5170 /* rb_equal() can evacuate ptrs */
5185 }
5188 }
5189 }
5190 p1++;
5191 p2++;
5192 }
5194 }
5196 /*
5197 * call-seq:
5198 * self == other_array -> true or false
5199 *
5200 * Returns whether both:
5201 *
5202 * - +self+ and +other_array+ are the same size.
5203 * - Their corresponding elements are the same;
5204 * that is, for each index +i+ in <tt>(0...self.size)</tt>,
5205 * <tt>self[i] == other_array[i]</tt>.
5206 *
5207 * Examples:
5208 *
5209 * [:foo, 'bar', 2] == [:foo, 'bar', 2] # => true
5210 * [:foo, 'bar', 2] == [:foo, 'bar', 2.0] # => true
5211 * [:foo, 'bar', 2] == [:foo, 'bar'] # => false # Different sizes.
5212 * [:foo, 'bar', 2] == [:foo, 'bar', 3] # => false # Different elements.
5213 *
5214 * This method is different from method Array#eql?,
5215 * which compares elements using <tt>Object#eql?</tt>.
5216 *
5217 * Related: see {Methods for Comparing}[rdoc-ref:Array@Methods+for+Comparing].
5218 */
5220 static VALUE
5222 {
5227 }
5229 }
5233 }
5235 static VALUE
5237 {
5244 }
5246 }
5248 /*
5249 * call-seq:
5250 * array.eql?(other_array) -> true or false
5251 *
5252 * Returns +true+ if +self+ and +other_array+ are the same size,
5253 * and if, for each index +i+ in +self+, <tt>self[i].eql?(other_array[i])</tt>:
5254 *
5255 * a0 = [:foo, 'bar', 2]
5256 * a1 = [:foo, 'bar', 2]
5257 * a1.eql?(a0) # => true
5258 *
5259 * Otherwise, returns +false+.
5260 *
5261 * This method is different from method Array#==,
5262 * which compares using method <tt>Object#==</tt>.
5263 */
5265 static VALUE
5267 {
5273 }
5275 VALUE
5277 {
5279 st_index_t h;
5280 VALUE n;
5287 }
5290 }
5292 /*
5293 * call-seq:
5294 * array.hash -> integer
5295 *
5296 * Returns the integer hash value for +self+.
5297 *
5298 * Two arrays with the same content will have the same hash code (and will compare using #eql?):
5299 *
5300 * [0, 1, 2].hash == [0, 1, 2].hash # => true
5301 * [0, 1, 2].hash == [0, 1, 3].hash # => false
5302 *
5303 */
5305 static VALUE
5307 {
5309 }
5311 /*
5312 * call-seq:
5313 * array.include?(obj) -> true or false
5314 *
5315 * Returns +true+ if for some index +i+ in +self+, <tt>obj == self[i]</tt>;
5316 * otherwise +false+:
5317 *
5318 * [0, 1, 2].include?(2) # => true
5319 * [0, 1, 2].include?(3) # => false
5320 */
5322 VALUE
5324 {
5326 VALUE e;
5332 }
5333 }
5335 }
5337 static VALUE
5339 {
5341 VALUE e;
5347 }
5348 }
5350 }
5352 static VALUE
5354 {
5361 }
5367 }
5368 }
5370 }
5372 /*
5373 * call-seq:
5374 * self <=> other_array -> -1, 0, or 1
5375 *
5376 * Returns -1, 0, or 1 as +self+ is determined
5377 * to be less than, equal to, or greater than +other_array+.
5378 *
5379 * Iterates over each index +i+ in <tt>(0...self.size)</tt>:
5380 *
5381 * - Computes <tt>result[i]</tt> as <tt>self[i] <=> other_array[i]</tt>.
5382 * - Immediately returns 1 if <tt>result[i]</tt> is 1:
5383 *
5384 * [0, 1, 2] <=> [0, 0, 2] # => 1
5385 *
5386 * - Immediately returns -1 if <tt>result[i]</tt> is -1:
5387 *
5388 * [0, 1, 2] <=> [0, 2, 2] # => -1
5389 *
5390 * - Continues if <tt>result[i]</tt> is 0.
5391 *
5392 * When every +result+ is 0,
5393 * returns <tt>self.size <=> other_array.size</tt>
5394 * (see Integer#<=>):
5395 *
5396 * [0, 1, 2] <=> [0, 1] # => 1
5397 * [0, 1, 2] <=> [0, 1, 2] # => 0
5398 * [0, 1, 2] <=> [0, 1, 2, 3] # => -1
5399 *
5400 * Note that when +other_array+ is larger than +self+,
5401 * its trailing elements do not affect the result:
5402 *
5403 * [0, 1, 2] <=> [0, 1, 2, -3] # => -1
5404 * [0, 1, 2] <=> [0, 1, 2, 0] # => -1
5405 * [0, 1, 2] <=> [0, 1, 2, 3] # => -1
5406 *
5407 * Related: see {Methods for Comparing}[rdoc-ref:Array@Methods+for+Comparing].
5408 */
5410 VALUE
5412 {
5414 VALUE v;
5425 }
5427 static VALUE
5429 {
5435 }
5437 }
5441 {
5447 }
5449 static VALUE
5451 {
5454 }
5456 static VALUE
5458 {
5464 }
5466 }
5468 static VALUE
5470 {
5473 }
5475 /*
5476 * call-seq:
5477 * self - other_array -> new_array
5478 *
5479 * Returns a new array containing only those elements of +self+
5480 * that are not found in +other_array+;
5481 * the order from +self+ is preserved:
5482 *
5483 * [0, 1, 1, 2, 1, 1, 3, 1, 1] - [1] # => [0, 2, 3]
5484 * [0, 1, 1, 2, 1, 1, 3, 1, 1] - [3, 2, 0, :foo] # => [1, 1, 1, 1, 1, 1]
5485 * [0, 1, 2] - [:foo] # => [0, 1, 2]
5486 *
5487 * Element are compared using method <tt>#eql?</tt>
5488 * (as defined in each element of +self+).
5489 *
5490 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
5491 */
5493 VALUE
5495 {
5496 VALUE ary3;
5497 VALUE hash;
5509 }
5511 }
5517 }
5520 }
5522 /*
5523 * call-seq:
5524 * array.difference(*other_arrays) -> new_array
5525 *
5526 * Returns a new +Array+ containing only those elements from +self+
5527 * that are not found in any of the Arrays +other_arrays+;
5528 * items are compared using <tt>eql?</tt>; order from +self+ is preserved:
5529 *
5530 * [0, 1, 1, 2, 1, 1, 3, 1, 1].difference([1]) # => [0, 2, 3]
5531 * [0, 1, 2, 3].difference([3, 0], [1, 3]) # => [2]
5532 * [0, 1, 2].difference([4]) # => [0, 1, 2]
5533 *
5534 * Returns a copy of +self+ if no arguments given.
5535 *
5536 * Related: Array#-.
5537 */
5539 static VALUE
5541 {
5542 VALUE ary_diff;
5553 }
5562 }
5565 }
5566 }
5568 }
5573 }
5576 /*
5577 * call-seq:
5578 * self & other_array -> new_array
5579 *
5580 * Returns a new array containing the _intersection_ of +self+ and +other_array+;
5581 * that is, containing those elements found in both +self+ and +other_array+:
5582 *
5583 * [0, 1, 2, 3] & [1, 2] # => [1, 2]
5584 *
5585 * Omits duplicates:
5586 *
5587 * [0, 1, 1, 0] & [0, 1] # => [0, 1]
5588 *
5589 * Preserves order from +self+:
5590 *
5591 * [0, 1, 2] & [3, 2, 1, 0] # => [0, 1, 2]
5592 *
5593 * Identifies common elements using method <tt>#eql?</tt>
5594 * (as defined in each element of +self+).
5595 *
5596 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
5597 */
5600 static VALUE
5602 {
5604 st_data_t vv;
5617 }
5619 }
5628 }
5629 }
5632 }
5634 /*
5635 * call-seq:
5636 * array.intersection(*other_arrays) -> new_array
5637 *
5638 * Returns a new +Array+ containing each element found both in +self+
5639 * and in all of the given Arrays +other_arrays+;
5640 * duplicates are omitted; items are compared using <tt>eql?</tt>
5641 * (items must also implement +hash+ correctly):
5642 *
5643 * [0, 1, 2, 3].intersection([0, 1, 2], [0, 1, 3]) # => [0, 1]
5644 * [0, 0, 1, 1, 2, 3].intersection([0, 1, 2], [0, 1, 3]) # => [0, 1]
5645 *
5646 * Preserves order from +self+:
5647 *
5648 * [0, 1, 2].intersection([2, 1, 0]) # => [0, 1, 2]
5649 *
5650 * Returns a copy of +self+ if no arguments given.
5651 *
5652 * Related: Array#&.
5653 */
5655 static VALUE
5657 {
5663 }
5666 }
5668 static int
5670 {
5674 }
5676 static void
5678 {
5684 }
5685 }
5687 static void
5689 {
5695 }
5696 }
5697 }
5699 /*
5700 * call-seq:
5701 * array | other_array -> new_array
5702 *
5703 * Returns the union of +array+ and +Array+ +other_array+;
5704 * duplicates are removed; order is preserved;
5705 * items are compared using <tt>eql?</tt>:
5706 *
5707 * [0, 1] | [2, 3] # => [0, 1, 2, 3]
5708 * [0, 1, 1] | [2, 2, 3] # => [0, 1, 2, 3]
5709 * [0, 1, 2] | [3, 2, 1, 0] # => [0, 1, 2, 3]
5710 *
5711 * Related: Array#union.
5712 */
5714 static VALUE
5716 {
5717 VALUE hash;
5725 }
5731 }
5733 /*
5734 * call-seq:
5735 * array.union(*other_arrays) -> new_array
5736 *
5737 * Returns a new +Array+ that is the union of +self+ and all given Arrays +other_arrays+;
5738 * duplicates are removed; order is preserved; items are compared using <tt>eql?</tt>:
5739 *
5740 * [0, 1, 2, 3].union([4, 5], [6, 7]) # => [0, 1, 2, 3, 4, 5, 6, 7]
5741 * [0, 1, 1].union([2, 1], [3, 1]) # => [0, 1, 2, 3]
5742 * [0, 1, 2, 3].union([3, 2], [1, 0]) # => [0, 1, 2, 3]
5743 *
5744 * Returns a copy of +self+ if no arguments given.
5745 *
5746 * Related: Array#|.
5747 */
5749 static VALUE
5751 {
5754 VALUE hash;
5760 }
5769 }
5775 }
5777 /*
5778 * call-seq:
5779 * ary.intersect?(other_ary) -> true or false
5780 *
5781 * Returns +true+ if the array and +other_ary+ have at least one element in
5782 * common, otherwise returns +false+:
5783 *
5784 * a = [ 1, 2, 3 ]
5785 * b = [ 3, 4, 5 ]
5786 * c = [ 5, 6, 7 ]
5787 * a.intersect?(b) #=> true
5788 * a.intersect?(c) #=> false
5789 *
5790 * +Array+ elements are compared using <tt>eql?</tt>
5791 * (items must also implement +hash+ correctly).
5792 */
5794 static VALUE
5796 {
5798 st_data_t vv;
5808 }
5810 }
5817 }
5828 }
5829 }
5832 }
5834 static VALUE
5836 {
5839 VALUE v;
5845 }
5846 }
5849 }
5851 static VALUE
5853 {
5858 VALUE v;
5865 }
5866 }
5869 }
5870 }
5873 }
5875 static VALUE
5877 {
5882 VALUE v;
5889 }
5890 }
5893 }
5894 }
5897 }
5899 static VALUE
5901 {
5906 VALUE v;
5913 }
5914 }
5917 }
5918 }
5921 }
5923 /*
5924 * call-seq:
5925 * array.max -> element
5926 * array.max {|a, b| ... } -> element
5927 * array.max(n) -> new_array
5928 * array.max(n) {|a, b| ... } -> new_array
5929 *
5930 * Returns one of the following:
5931 *
5932 * - The maximum-valued element from +self+.
5933 * - A new +Array+ of maximum-valued elements selected from +self+.
5934 *
5935 * When no block is given, each element in +self+ must respond to method <tt><=></tt>
5936 * with an Integer.
5937 *
5938 * With no argument and no block, returns the element in +self+
5939 * having the maximum value per method <tt><=></tt>:
5940 *
5941 * [0, 1, 2].max # => 2
5942 *
5943 * With an argument Integer +n+ and no block, returns a new +Array+ with at most +n+ elements,
5944 * in descending order per method <tt><=></tt>:
5945 *
5946 * [0, 1, 2, 3].max(3) # => [3, 2, 1]
5947 * [0, 1, 2, 3].max(6) # => [3, 2, 1, 0]
5948 *
5949 * When a block is given, the block must return an Integer.
5950 *
5951 * With a block and no argument, calls the block <tt>self.size-1</tt> times to compare elements;
5952 * returns the element having the maximum value per the block:
5953 *
5954 * ['0', '00', '000'].max {|a, b| a.size <=> b.size } # => "000"
5955 *
5956 * With an argument +n+ and a block, returns a new +Array+ with at most +n+ elements,
5957 * in descending order per the block:
5958 *
5959 * ['0', '00', '000'].max(2) {|a, b| a.size <=> b.size } # => ["000", "00"]
5960 *
5961 */
5962 static VALUE
5964 {
5966 VALUE num;
5978 }
5979 }
5980 }
5986 }
5989 }
5992 }
5995 }
5996 }
5997 }
6000 }
6002 static VALUE
6004 {
6007 VALUE v;
6013 }
6014 }
6017 }
6019 static VALUE
6021 {
6026 VALUE a;
6033 }
6034 }
6037 }
6038 }
6041 }
6043 static VALUE
6045 {
6050 VALUE a;
6057 }
6058 }
6061 }
6062 }
6065 }
6067 static VALUE
6069 {
6074 VALUE a;
6081 }
6082 }
6085 }
6086 }
6089 }
6091 /*
6092 * call-seq:
6093 * array.min -> element
6094 * array.min { |a, b| ... } -> element
6095 * array.min(n) -> new_array
6096 * array.min(n) { |a, b| ... } -> new_array
6097 *
6098 * Returns one of the following:
6099 *
6100 * - The minimum-valued element from +self+.
6101 * - A new +Array+ of minimum-valued elements selected from +self+.
6102 *
6103 * When no block is given, each element in +self+ must respond to method <tt><=></tt>
6104 * with an Integer.
6105 *
6106 * With no argument and no block, returns the element in +self+
6107 * having the minimum value per method <tt><=></tt>:
6108 *
6109 * [0, 1, 2].min # => 0
6110 *
6111 * With Integer argument +n+ and no block, returns a new +Array+ with at most +n+ elements,
6112 * in ascending order per method <tt><=></tt>:
6113 *
6114 * [0, 1, 2, 3].min(3) # => [0, 1, 2]
6115 * [0, 1, 2, 3].min(6) # => [0, 1, 2, 3]
6116 *
6117 * When a block is given, the block must return an Integer.
6118 *
6119 * With a block and no argument, calls the block <tt>self.size-1</tt> times to compare elements;
6120 * returns the element having the minimum value per the block:
6121 *
6122 * ['0', '00', '000'].min { |a, b| a.size <=> b.size } # => "0"
6123 *
6124 * With an argument +n+ and a block, returns a new +Array+ with at most +n+ elements,
6125 * in ascending order per the block:
6126 *
6127 * ['0', '00', '000'].min(2) {|a, b| a.size <=> b.size } # => ["0", "00"]
6128 *
6129 */
6130 static VALUE
6132 {
6134 VALUE num;
6146 }
6147 }
6148 }
6154 }
6157 }
6160 }
6163 }
6164 }
6165 }
6168 }
6170 /*
6171 * call-seq:
6172 * array.minmax -> [min_val, max_val]
6173 * array.minmax {|a, b| ... } -> [min_val, max_val]
6174 *
6175 * Returns a new 2-element +Array+ containing the minimum and maximum values
6176 * from +self+, either per method <tt><=></tt> or per a given block:.
6177 *
6178 * When no block is given, each element in +self+ must respond to method <tt><=></tt>
6179 * with an Integer;
6180 * returns a new 2-element +Array+ containing the minimum and maximum values
6181 * from +self+, per method <tt><=></tt>:
6182 *
6183 * [0, 1, 2].minmax # => [0, 2]
6184 *
6185 * When a block is given, the block must return an Integer;
6186 * the block is called <tt>self.size-1</tt> times to compare elements;
6187 * returns a new 2-element +Array+ containing the minimum and maximum values
6188 * from +self+, per the block:
6189 *
6190 * ['0', '00', '000'].minmax {|a, b| a.size <=> b.size } # => ["0", "000"]
6191 *
6192 */
6193 static VALUE
6195 {
6198 }
6200 }
6202 static int
6204 {
6207 }
6209 /*
6210 * call-seq:
6211 * array.uniq! -> self or nil
6212 * array.uniq! {|element| ... } -> self or nil
6213 *
6214 * Removes duplicate elements from +self+, the first occurrence always being retained;
6215 * returns +self+ if any elements removed, +nil+ otherwise.
6216 *
6217 * With no block given, identifies and removes elements using method <tt>eql?</tt>
6218 * to compare.
6219 *
6220 * Returns +self+ if any elements removed:
6221 *
6222 * a = [0, 0, 1, 1, 2, 2]
6223 * a.uniq! # => [0, 1, 2]
6224 *
6225 * Returns +nil+ if no elements removed.
6226 *
6227 * With a block given, calls the block for each element;
6228 * identifies (using method <tt>eql?</tt>) and removes
6229 * elements for which the block returns duplicate values.
6230 *
6231 * Returns +self+ if any elements removed:
6232 *
6233 * a = ['a', 'aa', 'aaa', 'b', 'bb', 'bbb']
6234 * a.uniq! {|element| element.size } # => ['a', 'aa', 'aaa']
6235 *
6236 * Returns +nil+ if no elements removed.
6237 */
6238 static VALUE
6240 {
6241 VALUE hash;
6249 else
6255 }
6261 }
6266 }
6268 /*
6269 * call-seq:
6270 * array.uniq -> new_array
6271 * array.uniq {|element| ... } -> new_array
6272 *
6273 * Returns a new +Array+ containing those elements from +self+ that are not duplicates,
6274 * the first occurrence always being retained.
6275 *
6276 * With no block given, identifies and omits duplicates using method <tt>eql?</tt>
6277 * to compare:
6278 *
6279 * a = [0, 0, 1, 1, 2, 2]
6280 * a.uniq # => [0, 1, 2]
6281 *
6282 * With a block given, calls the block for each element;
6283 * identifies (using method <tt>eql?</tt>) and omits duplicate values,
6284 * that is, those elements for which the block returns the same value:
6285 *
6286 * a = ['a', 'aa', 'aaa', 'b', 'bb', 'bbb']
6287 * a.uniq {|element| element.size } # => ["a", "aa", "aaa"]
6288 *
6289 */
6291 static VALUE
6293 {
6299 }
6303 }
6307 }
6310 }
6312 /*
6313 * call-seq:
6314 * compact! -> self or nil
6315 *
6316 * Removes all +nil+ elements from +self+;
6317 * Returns +self+ if any elements are removed, +nil+ otherwise:
6318 *
6319 * a = [nil, 0, nil, false, nil, '', nil, [], nil, {}]
6320 * a.compact! # => [0, false, "", [], {}]
6321 * a # => [0, false, "", [], {}]
6322 * a.compact! # => nil
6323 *
6324 * Related: Array#compact;
6325 * see also {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
6326 */
6328 static VALUE
6330 {
6341 }
6345 }
6349 }
6351 /*
6352 * call-seq:
6353 * compact -> new_array
6354 *
6355 * Returns a new array containing only the non-+nil+ elements from +self+;
6356 * element order is preserved:
6357 *
6358 * a = [nil, 0, nil, false, nil, '', nil, [], nil, {}]
6359 * a.compact # => [0, false, "", [], {}]
6360 *
6361 * Related: Array#compact!.
6362 */
6364 static VALUE
6366 {
6370 }
6372 /*
6373 * call-seq:
6374 * count -> integer
6375 * count(object) -> integer
6376 * count {|element| ... } -> integer
6377 *
6378 * Returns a count of specified elements.
6379 *
6380 * With no argument and no block, returns the count of all elements:
6381 *
6382 * [0, :one, 'two', 3, 3.0].count # => 5
6383 *
6384 * With argument +object+ given, returns the count of elements <tt>==</tt> to +object+:
6385 *
6386 * [0, :one, 'two', 3, 3.0].count(3) # => 2
6387 *
6388 * With no argument and a block given, calls the block with each element;
6389 * returns the count of elements for which the block returns a truthy value:
6390 *
6391 * [0, 1, 2, 3].count {|element| element > 1 } # => 2
6392 *
6393 * With argument +object+ and a block given, issues a warning, ignores the block,
6394 * and returns the count of elements <tt>==</tt> to +object+.
6395 *
6396 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
6397 */
6399 static VALUE
6401 {
6405 VALUE v;
6413 }
6414 }
6420 }
6423 }
6424 }
6427 }
6429 static VALUE
6431 {
6441 }
6442 }
6445 }
6459 }
6470 }
6475 }
6477 }
6480 }
6486 }
6488 }
6493 }
6494 }
6497 }
6500 }
6504 }
6508 }
6512 }
6514 /*
6515 * call-seq:
6516 * array.flatten! -> self or nil
6517 * array.flatten!(level) -> self or nil
6518 *
6519 * Replaces each nested +Array+ in +self+ with the elements from that +Array+;
6520 * returns +self+ if any changes, +nil+ otherwise.
6521 *
6522 * With non-negative Integer argument +level+, flattens recursively through +level+ levels:
6523 *
6524 * a = [ 0, [ 1, [2, 3], 4 ], 5 ]
6525 * a.flatten!(1) # => [0, 1, [2, 3], 4, 5]
6526 * a = [ 0, [ 1, [2, 3], 4 ], 5 ]
6527 * a.flatten!(2) # => [0, 1, 2, 3, 4, 5]
6528 * a = [ 0, [ 1, [2, 3], 4 ], 5 ]
6529 * a.flatten!(3) # => [0, 1, 2, 3, 4, 5]
6530 * [0, 1, 2].flatten!(1) # => nil
6531 *
6532 * With no argument, a +nil+ argument, or with negative argument +level+, flattens all levels:
6533 *
6534 * a = [ 0, [ 1, [2, 3], 4 ], 5 ]
6535 * a.flatten! # => [0, 1, 2, 3, 4, 5]
6536 * [0, 1, 2].flatten! # => nil
6537 * a = [ 0, [ 1, [2, 3], 4 ], 5 ]
6538 * a.flatten!(-1) # => [0, 1, 2, 3, 4, 5]
6539 * a = [ 0, [ 1, [2, 3], 4 ], 5 ]
6540 * a.flatten!(-2) # => [0, 1, 2, 3, 4, 5]
6541 * [0, 1, 2].flatten!(-1) # => nil
6542 *
6543 */
6545 static VALUE
6547 {
6559 }
6565 }
6567 /*
6568 * call-seq:
6569 * array.flatten -> new_array
6570 * array.flatten(level) -> new_array
6571 *
6572 * Returns a new +Array+ that is a recursive flattening of +self+:
6573 * - Each non-Array element is unchanged.
6574 * - Each +Array+ is replaced by its individual elements.
6575 *
6576 * With non-negative Integer argument +level+, flattens recursively through +level+ levels:
6577 *
6578 * a = [ 0, [ 1, [2, 3], 4 ], 5 ]
6579 * a.flatten(0) # => [0, [1, [2, 3], 4], 5]
6580 * a = [ 0, [ 1, [2, 3], 4 ], 5 ]
6581 * a.flatten(1) # => [0, 1, [2, 3], 4, 5]
6582 * a = [ 0, [ 1, [2, 3], 4 ], 5 ]
6583 * a.flatten(2) # => [0, 1, 2, 3, 4, 5]
6584 * a = [ 0, [ 1, [2, 3], 4 ], 5 ]
6585 * a.flatten(3) # => [0, 1, 2, 3, 4, 5]
6586 *
6587 * With no argument, a +nil+ argument, or with negative argument +level+, flattens all levels:
6588 *
6589 * a = [ 0, [ 1, [2, 3], 4 ], 5 ]
6590 * a.flatten # => [0, 1, 2, 3, 4, 5]
6591 * [0, 1, 2].flatten # => [0, 1, 2]
6592 * a = [ 0, [ 1, [2, 3], 4 ], 5 ]
6593 * a.flatten(-1) # => [0, 1, 2, 3, 4, 5]
6594 * a = [ 0, [ 1, [2, 3], 4 ], 5 ]
6595 * a.flatten(-2) # => [0, 1, 2, 3, 4, 5]
6596 * [0, 1, 2].flatten(-1) # => [0, 1, 2]
6597 *
6598 */
6600 static VALUE
6602 {
6604 VALUE result;
6609 }
6614 }
6617 }
6619 #define RAND_UPTO(max) (long)rb_random_ulong_limited((randgen), (max)-1)
6621 static VALUE
6623 {
6631 VALUE tmp;
6634 }
6638 }
6641 }
6643 static VALUE
6645 {
6649 }