| blob | d28f03cb4c81ea37244505d051dbe426f4691989 |
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 * freeze -> self
633 *
634 * Freezes +self+ (if not already frozen); returns +self+:
635 *
636 * a = []
637 * a.frozen? # => false
638 * a.freeze
639 * a.frozen? # => true
640 *
641 * No further changes may be made to +self+;
642 * raises FrozenError if a change is attempted.
643 *
644 * Related: Kernel#frozen?.
645 */
647 VALUE
649 {
656 }
659 }
661 /* This can be used to take a snapshot of an array (with
662 e.g. rb_ary_replace) and check later whether the array has been
663 modified from the snapshot. The snapshot is cheap, though if
664 something does modify the array it will pay the cost of copying
665 it. If Array#pop or Array#shift has been called, the array will
666 be still shared with the snapshot, but the array length will
667 differ. */
668 VALUE
670 {
676 }
678 }
680 static VALUE
682 {
688 /* Created array is:
689 * FL_SET_EMBED((VALUE)ary);
690 * ARY_SET_EMBED_LEN((VALUE)ary, 0);
691 */
693 }
695 static VALUE
697 {
702 }
704 static VALUE
706 {
709 }
711 static VALUE
713 {
714 VALUE ary;
718 }
721 }
727 }
735 }
738 }
740 VALUE
742 {
744 }
746 VALUE
748 {
750 }
752 VALUE
754 {
756 VALUE ary;
764 }
769 }
771 VALUE
773 {
774 VALUE ary;
780 }
783 }
785 VALUE
787 {
789 }
791 static VALUE
793 {
799 /* Created array is:
800 * FL_SET_EMBED((VALUE)ary);
801 * ARY_SET_EMBED_LEN((VALUE)ary, 0);
802 */
804 }
806 static VALUE
808 {
813 }
815 static VALUE
817 {
818 VALUE ary;
822 }
825 }
831 }
839 }
842 }
844 VALUE
846 {
847 VALUE ary;
853 }
856 }
858 VALUE
860 {
863 }
865 VALUE
867 {
872 }
874 void
876 {
882 }
886 }
889 }
893 }
896 }
897 }
901 static VALUE
903 {
909 }
911 VALUE
913 {
917 // bypass frozen checks
922 }
924 size_t
926 {
929 }
932 }
933 }
935 static VALUE
937 {
942 }
945 }
948 }
953 /* Shared roots cannot be embedded because the reference count
954 * (refcnt) is stored in as.heap.aux.capa. */
966 }
969 }
979 }
980 }
982 static VALUE
984 {
994 }
997 }
998 }
1000 VALUE
1002 {
1004 }
1006 VALUE
1008 {
1010 }
1011 #define to_ary rb_to_array_type
1013 VALUE
1015 {
1017 }
1019 VALUE
1021 {
1023 }
1025 VALUE
1027 {
1029 }
1031 /*
1032 * call-seq:
1033 * Array.try_convert(object) -> object, new_array, or nil
1034 *
1035 * Attempts to return an array, based on the given +object+.
1036 *
1037 * If +object+ is an array, returns +object+.
1038 *
1039 * Otherwise if +object+ responds to <tt>:to_ary</tt>.
1040 * calls <tt>object.to_ary</tt>:
1041 * if the return value is an array or +nil+, returns that value;
1042 * if not, raises TypeError.
1043 *
1044 * Otherwise returns +nil+.
1045 *
1046 * Related: see {Methods for Creating an Array}[rdoc-ref:Array@Methods+for+Creating+an+Array].
1047 */
1049 static VALUE
1051 {
1053 }
1055 /* :nodoc: */
1056 static VALUE
1058 {
1059 VALUE ary;
1066 }
1071 }
1074 }
1077 }
1079 /*
1080 * call-seq:
1081 * Array.new -> new_empty_array
1082 * Array.new(array) -> new_array
1083 * Array.new(size, default_value = nil) -> new_array
1084 * Array.new(size = 0) {|index| ... } -> new_array
1085 *
1086 * Returns a new array.
1087 *
1088 * With no block and no argument given, returns a new empty array:
1089 *
1090 * Array.new # => []
1091 *
1092 * With no block and array argument given, returns a new array with the same elements:
1093 *
1094 * Array.new([:foo, 'bar', 2]) # => [:foo, "bar", 2]
1095 *
1096 * With no block and integer argument given, returns a new array containing
1097 * that many instances of the given +default_value+:
1098 *
1099 * Array.new(0) # => []
1100 * Array.new(3) # => [nil, nil, nil]
1101 * Array.new(2, 3) # => [3, 3]
1102 *
1103 * With a block given, returns an array of the given +size+;
1104 * calls the block with each +index+ in the range <tt>(0...size)</tt>;
1105 * the element at that +index+ in the returned array is the blocks return value:
1106 *
1107 * Array.new(3) {|index| "Element #{index}" } # => ["Element 0", "Element 1", "Element 2"]
1108 *
1109 * A common pitfall for new Rubyists is providing an expression as +default_value+:
1110 *
1111 * array = Array.new(2, {})
1112 * array # => [{}, {}]
1113 * array[0][:a] = 1
1114 * array # => [{a: 1}, {a: 1}], as array[0] and array[1] are same object
1115 *
1116 * If you want the elements of the array to be distinct, you should pass a block:
1117 *
1118 * array = Array.new(2) { {} }
1119 * array # => [{}, {}]
1120 * array[0][:a] = 1
1121 * array # => [{a: 1}, {}], as array[0] and array[1] are different objects
1122 *
1123 * Raises TypeError if the first argument is not either an array
1124 * or an {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects]).
1125 * Raises ArgumentError if the first argument is a negative integer.
1126 *
1127 * Related: see {Methods for Creating an Array}[rdoc-ref:Array@Methods+for+Creating+an+Array].
1128 */
1130 static VALUE
1132 {
1143 }
1145 }
1152 }
1153 }
1156 /* NUM2LONG() may call size.to_int, ary can be frozen, modified, etc */
1159 }
1162 }
1163 /* recheck after argument conversion */
1171 }
1175 }
1176 }
1180 }
1182 }
1184 /*
1185 * Returns a new array, populated with the given objects:
1186 *
1187 * Array[1, 'a', /^A/] # => [1, "a", /^A/]
1188 * Array[] # => []
1189 * Array.[](1, 'a', /^A/) # => [1, "a", /^A/]
1190 *
1191 * Related: see {Methods for Creating an Array}[rdoc-ref:Array@Methods+for+Creating+an+Array].
1192 */
1194 static VALUE
1196 {
1201 }
1204 }
1206 void
1208 {
1216 }
1217 }
1220 }
1225 }
1228 }
1232 }
1234 }
1236 static VALUE
1238 {
1249 }
1253 /* The ary_make_shared call may allocate, which can trigger a GC
1254 * compaction. This can cause the array to be embedded because it has
1255 * a length of 0. */
1266 }
1270 }
1272 static VALUE
1274 {
1290 }
1293 }
1309 }
1311 }
1319 }
1320 });
1322 }
1325 }
1327 static VALUE
1329 {
1331 }
1333 enum ary_take_pos_flags
1334 {
1337 };
1339 static VALUE
1341 {
1347 }
1350 }
1353 }
1355 }
1357 static VALUE
1359 {
1361 /* the case optional argument is omitted should be handled in
1362 * callers of this function. if another arity case is added,
1363 * this arity check needs to rewrite. */
1366 }
1368 /*
1369 * call-seq:
1370 * self << object -> self
1371 *
1372 * Appends +object+ as the last element in +self+; returns +self+:
1373 *
1374 * [:foo, 'bar', 2] << :baz # => [:foo, "bar", 2, :baz]
1375 *
1376 * Appends +object+ as a single element, even if it is another array:
1377 *
1378 * [:foo, 'bar', 2] << [3, 4] # => [:foo, "bar", 2, [3, 4]]
1379 *
1380 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
1381 */
1383 VALUE
1385 {
1390 });
1394 }
1396 VALUE
1398 {
1404 }
1406 /*
1407 * call-seq:
1408 * push(*objects) -> self
1409 * append(*objects) -> self
1410 *
1411 * Appends each argument in +objects+ to +self+; returns +self+:
1412 *
1413 * a = [:foo, 'bar', 2] # => [:foo, "bar", 2]
1414 * a.push(:baz, :bat) # => [:foo, "bar", 2, :baz, :bat]
1415 *
1416 * Appends each argument as a single element, even if it is another array:
1417 *
1418 * a = [:foo, 'bar', 2] # => [:foo, "bar", 2]
1419 a.push([:baz, :bat], [:bam, :bad]) # => [:foo, "bar", 2, [:baz, :bat], [:bam, :bad]]
1420 *
1421 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
1422 */
1424 static VALUE
1426 {
1428 }
1430 VALUE
1432 {
1440 {
1442 }
1447 }
1449 /*
1450 * call-seq:
1451 * pop -> object or nil
1452 * pop(count) -> new_array
1453 *
1454 * Removes and returns trailing elements of +self+.
1455 *
1456 * With no argument given, removes and returns the last element, if available;
1457 * otherwise returns +nil+:
1458 *
1459 * a = [:foo, 'bar', 2]
1460 * a.pop # => 2
1461 * a # => [:foo, "bar"]
1462 * [].pop # => nil
1463 *
1464 * With non-negative integer argument +count+ given,
1465 * returns a new array containing the trailing +count+ elements of +self+, as available:
1466 *
1467 * a = [:foo, 'bar', 2]
1468 * a.pop(2) # => ["bar", 2]
1469 * a # => [:foo]
1470 *
1471 * a = [:foo, 'bar', 2]
1472 * a.pop(50) # => [:foo, "bar", 2]
1473 * a # => []
1474 *
1475 * Related: Array#push;
1476 * see also {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
1477 */
1479 static VALUE
1481 {
1482 VALUE result;
1486 }
1493 }
1495 VALUE
1497 {
1498 VALUE top;
1504 }
1511 }
1513 /*
1514 * call-seq:
1515 * array.shift -> object or nil
1516 * array.shift(n) -> new_array
1517 *
1518 * Removes and returns leading elements.
1519 *
1520 * When no argument is given, removes and returns the first element:
1521 *
1522 * a = [:foo, 'bar', 2]
1523 * a.shift # => :foo
1524 * a # => ['bar', 2]
1525 *
1526 * Returns +nil+ if +self+ is empty.
1527 *
1528 * When positive Integer argument +n+ is given, removes the first +n+ elements;
1529 * returns those elements in a new +Array+:
1530 *
1531 * a = [:foo, 'bar', 2]
1532 * a.shift(2) # => [:foo, 'bar']
1533 * a # => [2]
1534 *
1535 * If +n+ is as large as or larger than <tt>self.length</tt>,
1536 * removes all elements; returns those elements in a new +Array+:
1537 *
1538 * a = [:foo, 'bar', 2]
1539 * a.shift(3) # => [:foo, 'bar', 2]
1540 *
1541 * If +n+ is zero, returns a new empty +Array+; +self+ is unmodified.
1542 *
1543 * Related: #push, #pop, #unshift.
1544 */
1546 static VALUE
1548 {
1549 VALUE result;
1554 }
1562 }
1564 VALUE
1566 {
1569 }
1581 }
1585 }
1588 }
1595 }
1597 static VALUE
1598 make_room_for_unshift(VALUE ary, const VALUE *head, VALUE *sharedp, int argc, long capa, long len)
1599 {
1606 }
1612 }
1614 static VALUE
1616 {
1626 }
1628 /* use shared array for big "queues" */
1632 /* make a room for unshifted items */
1638 }
1640 /* sliding items */
1643 });
1647 }
1648 }
1650 static VALUE
1652 {
1658 }
1661 }
1668 }
1671 }
1678 }
1679 }
1680 }
1682 /*
1683 * call-seq:
1684 * unshift(*objects) -> self
1685 * prepend(*objects) -> self
1686 *
1687 * Prepends the given +objects+ to +self+:
1688 *
1689 * a = [:foo, 'bar', 2]
1690 * a.unshift(:bam, :bat) # => [:bam, :bat, :foo, "bar", 2]
1691 *
1692 * Related: Array#shift;
1693 * see also {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
1694 */
1696 VALUE
1698 {
1700 VALUE target_ary;
1705 }
1711 }
1713 VALUE
1715 {
1717 }
1719 /* faster version - use this if you don't need to treat negative offset */
1722 {
1727 }
1729 }
1731 VALUE
1733 {
1735 }
1737 VALUE
1739 {
1740 VALUE klass;
1748 }
1755 else
1757 }
1759 VALUE
1761 {
1763 }
1767 /*
1768 * call-seq:
1769 * self[index] -> object or nil
1770 * self[start, length] -> object or nil
1771 * self[range] -> object or nil
1772 * self[aseq] -> object or nil
1773 * slice(index) -> object or nil
1774 * slice(start, length) -> object or nil
1775 * slice(range) -> object or nil
1776 * slice(aseq) -> object or nil
1777 *
1778 * Returns elements from +self+; does not modify +self+.
1779 *
1780 * In brief:
1781 *
1782 * a = [:foo, 'bar', 2]
1783 *
1784 * # Single argument index: returns one element.
1785 * a[0] # => :foo # Zero-based index.
1786 * a[-1] # => 2 # Negative index counts backwards from end.
1787 *
1788 * # Arguments start and length: returns an array.
1789 * a[1, 2] # => ["bar", 2]
1790 * a[-2, 2] # => ["bar", 2] # Negative start counts backwards from end.
1791 *
1792 * # Single argument range: returns an array.
1793 * a[0..1] # => [:foo, "bar"]
1794 * a[0..-2] # => [:foo, "bar"] # Negative range-begin counts backwards from end.
1795 * a[-2..2] # => ["bar", 2] # Negative range-end counts backwards from end.
1796 *
1797 * When a single integer argument +index+ is given, returns the element at offset +index+:
1798 *
1799 * a = [:foo, 'bar', 2]
1800 * a[0] # => :foo
1801 * a[2] # => 2
1802 * a # => [:foo, "bar", 2]
1803 *
1804 * If +index+ is negative, counts backwards from the end of +self+:
1805 *
1806 * a = [:foo, 'bar', 2]
1807 * a[-1] # => 2
1808 * a[-2] # => "bar"
1809 *
1810 * If +index+ is out of range, returns +nil+.
1811 *
1812 * When two Integer arguments +start+ and +length+ are given,
1813 * returns a new +Array+ of size +length+ containing successive elements beginning at offset +start+:
1814 *
1815 * a = [:foo, 'bar', 2]
1816 * a[0, 2] # => [:foo, "bar"]
1817 * a[1, 2] # => ["bar", 2]
1818 *
1819 * If <tt>start + length</tt> is greater than <tt>self.length</tt>,
1820 * returns all elements from offset +start+ to the end:
1821 *
1822 * a = [:foo, 'bar', 2]
1823 * a[0, 4] # => [:foo, "bar", 2]
1824 * a[1, 3] # => ["bar", 2]
1825 * a[2, 2] # => [2]
1826 *
1827 * If <tt>start == self.size</tt> and <tt>length >= 0</tt>,
1828 * returns a new empty +Array+.
1829 *
1830 * If +length+ is negative, returns +nil+.
1831 *
1832 * When a single Range argument +range+ is given,
1833 * treats <tt>range.min</tt> as +start+ above
1834 * and <tt>range.size</tt> as +length+ above:
1835 *
1836 * a = [:foo, 'bar', 2]
1837 * a[0..1] # => [:foo, "bar"]
1838 * a[1..2] # => ["bar", 2]
1839 *
1840 * Special case: If <tt>range.start == a.size</tt>, returns a new empty +Array+.
1841 *
1842 * If <tt>range.end</tt> is negative, calculates the end index from the end:
1843 *
1844 * a = [:foo, 'bar', 2]
1845 * a[0..-1] # => [:foo, "bar", 2]
1846 * a[0..-2] # => [:foo, "bar"]
1847 * a[0..-3] # => [:foo]
1848 *
1849 * If <tt>range.start</tt> is negative, calculates the start index from the end:
1850 *
1851 * a = [:foo, 'bar', 2]
1852 * a[-1..2] # => [2]
1853 * a[-2..2] # => ["bar", 2]
1854 * a[-3..2] # => [:foo, "bar", 2]
1855 *
1856 * If <tt>range.start</tt> is larger than the array size, returns +nil+.
1857 *
1858 * a = [:foo, 'bar', 2]
1859 * a[4..1] # => nil
1860 * a[4..0] # => nil
1861 * a[4..-1] # => nil
1862 *
1863 * When a single Enumerator::ArithmeticSequence argument +aseq+ is given,
1864 * returns an +Array+ of elements corresponding to the indexes produced by
1865 * the sequence.
1866 *
1867 * a = ['--', 'data1', '--', 'data2', '--', 'data3']
1868 * a[(1..).step(2)] # => ["data1", "data2", "data3"]
1869 *
1870 * Unlike slicing with range, if the start or the end of the arithmetic sequence
1871 * is larger than array size, throws RangeError.
1872 *
1873 * a = ['--', 'data1', '--', 'data2', '--', 'data3']
1874 * a[(1..11).step(2)]
1875 * # RangeError (((1..11).step(2)) out of range)
1876 * a[(7..).step(2)]
1877 * # RangeError (((7..).step(2)) out of range)
1878 *
1879 * If given a single argument, and its type is not one of the listed, tries to
1880 * convert it to Integer, and raises if it is impossible:
1881 *
1882 * a = [:foo, 'bar', 2]
1883 * # Raises TypeError (no implicit conversion of Symbol into Integer):
1884 * a[:foo]
1885 *
1886 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
1887 */
1889 VALUE
1891 {
1895 }
1897 }
1899 static VALUE
1901 {
1906 }
1908 }
1910 VALUE
1912 {
1915 /* special case - speeding up */
1918 }
1919 /* check if idx is Range or ArithmeticSequence */
1927 }
1930 }
1932 /*
1933 * call-seq:
1934 * at(index) -> object or nil
1935 *
1936 * Returns the element of +self+ specified by the given +index+
1937 * or +nil+ if there is no such element;
1938 * +index+ must be an
1939 * {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects].
1940 *
1941 * For non-negative +index+, returns the element of +self+ at offset +index+:
1942 *
1943 * a = [:foo, 'bar', 2]
1944 * a.at(0) # => :foo
1945 * a.at(2) # => 2
1946 * a.at(2.0) # => 2
1947 *
1948 * For negative +index+, counts backwards from the end of +self+:
1949 *
1950 * a.at(-2) # => "bar"
1951 *
1952 * Related: Array#[];
1953 * see also {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
1954 */
1956 VALUE
1958 {
1960 }
1962 #if 0
1963 static VALUE
1965 {
1969 }
1972 }
1973 }
1974 #endif
1976 static VALUE
1978 {
1980 }
1982 static VALUE
1984 {
1987 }
1989 VALUE
1991 {
1994 }
1997 }
1998 }
2000 /*
2001 * call-seq:
2002 * fetch(index) -> element
2003 * fetch(index, default_value) -> element or default_value
2004 * fetch(index) {|index| ... } -> element or block_return_value
2005 *
2006 * Returns the element of +self+ at offset +index+ if +index+ is in range; +index+ must be an
2007 * {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects].
2008 *
2009 * With the single argument +index+ and no block,
2010 * returns the element at offset +index+:
2011 *
2012 * a = [:foo, 'bar', 2]
2013 * a.fetch(1) # => "bar"
2014 * a.fetch(1.1) # => "bar"
2015 *
2016 * If +index+ is negative, counts from the end of the array:
2017 *
2018 * a = [:foo, 'bar', 2]
2019 * a.fetch(-1) # => 2
2020 * a.fetch(-2) # => "bar"
2021 *
2022 * With arguments +index+ and +default_value+ (which may be any object) and no block,
2023 * returns +default_value+ if +index+ is out-of-range:
2024 *
2025 * a = [:foo, 'bar', 2]
2026 * a.fetch(1, nil) # => "bar"
2027 * a.fetch(3, :foo) # => :foo
2028 *
2029 * With argument +index+ and a block,
2030 * returns the element at offset +index+ if index is in range
2031 * (and the block is not called); otherwise calls the block with index and returns its return value:
2032 *
2033 * a = [:foo, 'bar', 2]
2034 * a.fetch(1) {|index| raise 'Cannot happen' } # => "bar"
2035 * a.fetch(50) {|index| "Value for #{index}" } # => "Value for 50"
2036 *
2037 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
2038 */
2040 static VALUE
2042 {
2051 }
2056 }
2062 }
2064 }
2066 }
2068 /*
2069 * call-seq:
2070 * find_index(object) -> integer or nil
2071 * find_index {|element| ... } -> integer or nil
2072 * find_index -> new_enumerator
2073 * index(object) -> integer or nil
2074 * index {|element| ... } -> integer or nil
2075 * index -> new_enumerator
2076 *
2077 * Returns the zero-based integer index of a specified element, or +nil+.
2078 *
2079 * With only argument +object+ given,
2080 * returns the index of the first element +element+
2081 * for which <tt>object == element</tt>:
2082 *
2083 * a = [:foo, 'bar', 2, 'bar']
2084 * a.index('bar') # => 1
2085 *
2086 * Returns +nil+ if no such element found.
2087 *
2088 * With only a block given,
2089 * calls the block with each successive element;
2090 * returns the index of the first element for which the block returns a truthy value:
2091 *
2092 * a = [:foo, 'bar', 2, 'bar']
2093 * a.index {|element| element == 'bar' } # => 1
2094 *
2095 * Returns +nil+ if the block never returns a truthy value.
2096 *
2097 * With neither an argument nor a block given, returns a new Enumerator.
2098 *
2099 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
2100 */
2102 static VALUE
2104 {
2105 VALUE val;
2113 }
2114 }
2116 }
2125 }
2126 }
2128 }
2130 /*
2131 * call-seq:
2132 * rindex(object) -> integer or nil
2133 * rindex {|element| ... } -> integer or nil
2134 * rindex -> new_enumerator
2135 *
2136 * Returns the index of the last element for which <tt>object == element</tt>.
2137 *
2138 * With argument +object+ given, returns the index of the last such element found:
2139 *
2140 * a = [:foo, 'bar', 2, 'bar']
2141 * a.rindex('bar') # => 3
2142 *
2143 * Returns +nil+ if no such object found.
2144 *
2145 * With a block given, calls the block with each successive element;
2146 * returns the index of the last element for which the block returns a truthy value:
2147 *
2148 * a = [:foo, 'bar', 2, 'bar']
2149 * a.rindex {|element| element == 'bar' } # => 3
2150 *
2151 * Returns +nil+ if the block never returns a truthy value.
2152 *
2153 * When neither an argument nor a block is given, returns a new Enumerator.
2154 *
2155 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
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 * insert(index, *objects) -> self
2522 *
2523 * Inserts the given +objects+ as elements of +self+;
2524 * returns +self+.
2525 *
2526 * When +index+ is non-negative, inserts +objects+
2527 * _before_ the element at offset +index+:
2528 *
2529 * a = ['a', 'b', 'c'] # => ["a", "b", "c"]
2530 * a.insert(1, :x, :y, :z) # => ["a", :x, :y, :z, "b", "c"]
2531 *
2532 * Extends the array if +index+ is beyond the array (<tt>index >= self.size</tt>):
2533 *
2534 * a = ['a', 'b', 'c'] # => ["a", "b", "c"]
2535 * a.insert(5, :x, :y, :z) # => ["a", "b", "c", nil, nil, :x, :y, :z]
2536 *
2537 * When +index+ is negative, inserts +objects+
2538 * _after_ the element at offset <tt>index + self.size</tt>:
2539 *
2540 * a = ['a', 'b', 'c'] # => ["a", "b", "c"]
2541 * a.insert(-2, :x, :y, :z) # => ["a", "b", :x, :y, :z, "c"]
2542 *
2543 * With no +objects+ given, does nothing:
2544 *
2545 * a = ['a', 'b', 'c'] # => ["a", "b", "c"]
2546 * a.insert(1) # => ["a", "b", "c"]
2547 * a.insert(50) # => ["a", "b", "c"]
2548 * a.insert(-50) # => ["a", "b", "c"]
2549 *
2550 * Raises IndexError if +objects+ are given and +index+ is negative and out of range.
2551 *
2552 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
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 * each_index {|index| ... } -> self
2617 * each_index -> new_enumerator
2618 *
2619 * With a block given, iterates over the elements of +self+,
2620 * passing each <i>array index</i> to the block;
2621 * returns +self+:
2622 *
2623 * a = [:foo, 'bar', 2]
2624 * a.each_index {|index| puts "#{index} #{a[index]}" }
2625 *
2626 * Output:
2627 *
2628 * 0 foo
2629 * 1 bar
2630 * 2 2
2631 *
2632 * Allows the array to be modified during iteration:
2633 *
2634 * a = [:foo, 'bar', 2]
2635 * a.each_index {|index| puts index; a.clear if index > 0 }
2636 *
2637 * Output:
2638 *
2639 * 0
2640 * 1
2641 *
2642 * With no block given, returns a new Enumerator.
2643 *
2644 * Related: see {Methods for Iterating}[rdoc-ref:Array@Methods+for+Iterating].
2645 */
2647 static VALUE
2649 {
2655 }
2657 }
2659 /*
2660 * call-seq:
2661 * array.reverse_each {|element| ... } -> self
2662 * array.reverse_each -> Enumerator
2663 *
2664 * Iterates backwards over array elements.
2665 *
2666 * When a block given, passes, in reverse order, each element to the block;
2667 * returns +self+:
2668 *
2669 * a = [:foo, 'bar', 2]
2670 * a.reverse_each {|element| puts "#{element.class} #{element}" }
2671 *
2672 * Output:
2673 *
2674 * Integer 2
2675 * String bar
2676 * Symbol foo
2677 *
2678 * Allows the array to be modified during iteration:
2679 *
2680 * a = [:foo, 'bar', 2]
2681 * a.reverse_each {|element| puts element; a.clear if element.to_s.start_with?('b') }
2682 *
2683 * Output:
2684 *
2685 * 2
2686 * bar
2687 *
2688 * When no block given, returns a new Enumerator:
2689 *
2690 * a = [:foo, 'bar', 2]
2691 * e = a.reverse_each
2692 * e # => #<Enumerator: [:foo, "bar", 2]:reverse_each>
2693 * a1 = e.each {|element| puts "#{element.class} #{element}" }
2694 *
2695 * Output:
2696 *
2697 * Integer 2
2698 * String bar
2699 * Symbol foo
2700 *
2701 * Related: #each, #each_index.
2702 */
2704 static VALUE
2706 {
2717 }
2718 }
2720 }
2722 /*
2723 * call-seq:
2724 * length -> integer
2725 * size -> integer
2726 *
2727 * Returns the count of elements in +self+:
2728 *
2729 * [0, 1, 2].length # => 3
2730 * [].length # => 0
2731 *
2732 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
2733 */
2735 static VALUE
2737 {
2740 }
2742 /*
2743 * call-seq:
2744 * array.empty? -> true or false
2745 *
2746 * Returns +true+ if the count of elements in +self+ is zero,
2747 * +false+ otherwise.
2748 *
2749 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
2750 */
2752 static VALUE
2754 {
2756 }
2758 VALUE
2760 {
2769 }
2771 VALUE
2773 {
2775 }
2781 static VALUE
2783 {
2792 }
2795 }
2797 }
2799 static long
2801 {
2803 VALUE val;
2812 }
2814 }
2816 static void
2818 {
2823 }
2824 }
2826 static void
2828 {
2831 }
2841 }
2842 }
2844 static void
2846 {
2856 }
2859 }
2862 }
2865 }
2868 }
2869 }
2870 }
2872 VALUE
2874 {
2883 }
2898 }
2901 }
2909 }
2911 /*
2912 * call-seq:
2913 * array.join(separator = $,) -> new_string
2914 *
2915 * Returns the new string formed by joining the converted elements of +self+;
2916 * for each element +element+:
2917 *
2918 * - Converts recursively using <tt>element.join(separator)</tt>
2919 * if +element+ is a <tt>kind_of?(Array)</tt>.
2920 * - Otherwise, converts using <tt>element.to_s</tt>.
2921 *
2922 * With no argument given, joins using the output field separator, <tt>$,</tt>:
2923 *
2924 * a = [:foo, 'bar', 2]
2925 * $, # => nil
2926 * a.join # => "foobar2"
2927 *
2928 * With string argument +separator+ given, joins using that separator:
2929 *
2930 * a = [:foo, 'bar', 2]
2931 * a.join("\n") # => "foo\nbar\n2"
2932 *
2933 * Joins recursively for nested arrays:
2934 *
2935 * a = [:foo, [:bar, [:baz, :bat]]]
2936 * a.join # => "foobarbazbat"
2937 *
2938 * Related: see {Methods for Converting}[rdoc-ref:Array@Methods+for+Converting].
2939 */
2940 static VALUE
2942 {
2943 VALUE sep;
2949 }
2950 }
2953 }
2955 static VALUE
2957 {
2968 }
2971 }
2973 /*
2974 * call-seq:
2975 * inspect -> new_string
2976 *
2977 * Returns the new string formed by calling method <tt>#inspect</tt>
2978 * on each array element:
2979 *
2980 * a = [:foo, 'bar', 2]
2981 * a.inspect # => "[:foo, \"bar\", 2]"
2982 *
2983 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
2984 */
2986 static VALUE
2988 {
2991 }
2993 VALUE
2995 {
2997 }
2999 /*
3000 * call-seq:
3001 * to_a -> self or new_array
3002 *
3003 * When +self+ is an instance of +Array+, returns +self+:
3004 *
3005 * a = [:foo, 'bar', 2]
3006 * a.to_a # => [:foo, "bar", 2]
3007 *
3008 * Otherwise, returns a new +Array+ containing the elements of +self+:
3009 *
3010 * class MyArray < Array; end
3011 * a = MyArray.new(['foo', 'bar', 'two'])
3012 * a.instance_of?(Array) # => false
3013 * a.kind_of?(Array) # => true
3014 * a1 = a.to_a
3015 * a1 # => ["foo", "bar", "two"]
3016 * a1.class # => Array # Not MyArray
3017 *
3018 */
3020 static VALUE
3022 {
3027 }
3029 }
3031 /*
3032 * call-seq:
3033 * array.to_h -> new_hash
3034 * array.to_h {|item| ... } -> new_hash
3035 *
3036 * Returns a new Hash formed from +self+.
3037 *
3038 * When a block is given, calls the block with each array element;
3039 * the block must return a 2-element +Array+ whose two elements
3040 * form a key-value pair in the returned Hash:
3041 *
3042 * a = ['foo', :bar, 1, [2, 3], {baz: 4}]
3043 * h = a.to_h {|item| [item, item] }
3044 * h # => {"foo"=>"foo", :bar=>:bar, 1=>1, [2, 3]=>[2, 3], {:baz=>4}=>{:baz=>4}}
3045 *
3046 * When no block is given, +self+ must be an +Array+ of 2-element sub-arrays,
3047 * each sub-array is formed into a key-value pair in the new Hash:
3048 *
3049 * [].to_h # => {}
3050 * a = [['foo', 'zero'], ['bar', 'one'], ['baz', 'two']]
3051 * h = a.to_h
3052 * h # => {"foo"=>"zero", "bar"=>"one", "baz"=>"two"}
3053 *
3054 */
3056 static VALUE
3058 {
3070 }
3074 }
3076 }
3078 }
3080 /*
3081 * call-seq:
3082 * array.to_ary -> self
3083 *
3084 * Returns +self+.
3085 */
3087 static VALUE
3089 {
3091 }
3093 static void
3095 {
3100 }
3101 }
3103 VALUE
3105 {
3115 }
3117 }
3119 /*
3120 * call-seq:
3121 * reverse! -> self
3122 *
3123 * Reverses the order of the elements of +self+;
3124 * returns +self+:
3125 *
3126 * a = [0, 1, 2]
3127 * a.reverse! # => [2, 1, 0]
3128 * a # => [2, 1, 0]
3129 *
3130 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
3131 */
3133 static VALUE
3135 {
3137 }
3139 /*
3140 * call-seq:
3141 * reverse -> new_array
3142 *
3143 * Returns a new array containing the elements of +self+ in reverse order:
3144 *
3145 * [0, 1, 2].reverse # => [2, 1, 0]
3146 *
3147 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
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 * select {|element| ... } -> new_array
3864 * select -> new_enumerator
3865 * filter {|element| ... } -> new_array
3866 * filter -> new_enumerator
3867 *
3868 * With a block given, calls the block with each element of +self+;
3869 * returns a new array containing those elements of +self+
3870 * for which the block returns a truthy value:
3871 *
3872 * a = [:foo, 'bar', 2, :bam]
3873 * a.select {|element| element.to_s.start_with?('b') }
3874 * # => ["bar", :bam]
3875 *
3876 * With no block given, returns a new Enumerator.
3877 *
3878 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
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 * select! {|element| ... } -> self or nil
3945 * select! -> new_enumerator
3946 * filter! {|element| ... } -> self or nil
3947 * filter! -> new_enumerator
3948 *
3949 * With a block given, calls the block with each element of +self+;
3950 * removes from +self+ those elements for which the block returns +false+ or +nil+.
3951 *
3952 * Returns +self+ if any elements were removed:
3953 *
3954 * a = [:foo, 'bar', 2, :bam]
3955 * a.select! {|element| element.to_s.start_with?('b') } # => ["bar", :bam]
3956 *
3957 * Returns +nil+ if no elements were removed.
3958 *
3959 * With no block given, returns a new Enumerator.
3960 *
3961 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
3962 */
3964 static VALUE
3966 {
3975 }
3977 /*
3978 * call-seq:
3979 * keep_if {|element| ... } -> self
3980 * keep_if -> new_enumerator
3981 *
3982 * With a block given, calls the block with each element of +self+;
3983 * removes the element from +self+ if the block does not return a truthy value:
3984 *
3985 * a = [:foo, 'bar', 2, :bam]
3986 * a.keep_if {|element| element.to_s.start_with?('b') } # => ["bar", :bam]
3987 *
3988 * With no block given, returns a new Enumerator.
3989 *
3990 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
3991 */
3993 static VALUE
3995 {
3999 }
4001 static void
4003 {
4010 }
4011 }
4012 }
4014 /*
4015 * call-seq:
4016 * delete(object) -> last_removed_object
4017 * delete(object) {|element| ... } -> last_removed_object or block_return
4018 *
4019 * Removes zero or more elements from +self+.
4020 *
4021 * With no block given,
4022 * removes from +self+ each element +ele+ such that <tt>ele == object</tt>;
4023 * returns the last removed element:
4024 *
4025 * a = [0, 1, 2, 2.0]
4026 * a.delete(2) # => 2.0
4027 * a # => [0, 1]
4028 *
4029 * Returns +nil+ if no elements removed:
4030 *
4031 * a.delete(2) # => nil
4032 *
4033 * With a block given,
4034 * removes from +self+ each element +ele+ such that <tt>ele == object</tt>.
4035 *
4036 * If any such elements are found, ignores the block
4037 * and returns the last removed element:
4038 *
4039 * a = [0, 1, 2, 2.0]
4040 * a.delete(2) {|element| fail 'Cannot happen' } # => 2.0
4041 * a # => [0, 1]
4042 *
4043 * If no such element is found, returns the block's return value:
4044 *
4045 * a.delete(2) {|element| "Element #{element} not found." }
4046 * # => "Element 2 not found."
4047 *
4048 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
4049 */
4051 VALUE
4053 {
4063 }
4066 }
4067 i2++;
4068 }
4072 }
4074 }
4080 }
4082 void
4084 {
4092 }
4095 }
4096 i2++;
4097 }
4100 }
4103 }
4105 VALUE
4107 {
4109 VALUE del;
4115 }
4121 });
4125 }
4127 /*
4128 * call-seq:
4129 * delete_at(index) -> removed_object or nil
4130 *
4131 * Removes the element of +self+ at the given +index+, which must be an
4132 * {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects].
4133 *
4134 * When +index+ is non-negative, deletes the element at offset +index+:
4135 *
4136 * a = [:foo, 'bar', 2]
4137 * a.delete_at(1) # => "bar"
4138 * a # => [:foo, 2]
4139 *
4140 * When +index+ is negative, counts backward from the end of the array:
4141 *
4142 * a = [:foo, 'bar', 2]
4143 * a.delete_at(-2) # => "bar"
4144 * a # => [:foo, 2]
4145 *
4146 * When +index+ is out of range, returns +nil+.
4147 *
4148 * a = [:foo, 'bar', 2]
4149 * a.delete_at(3) # => nil
4150 * a.delete_at(-4) # => nil
4151 *
4152 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
4153 */
4155 static VALUE
4157 {
4159 }
4161 static VALUE
4163 {
4168 }
4171 }
4174 }
4177 }
4180 }
4183 }
4188 }
4189 }
4191 /*
4192 * call-seq:
4193 * array.slice!(n) -> object or nil
4194 * array.slice!(start, length) -> new_array or nil
4195 * array.slice!(range) -> new_array or nil
4196 *
4197 * Removes and returns elements from +self+.
4198 *
4199 * When the only argument is an Integer +n+,
4200 * removes and returns the _nth_ element in +self+:
4201 *
4202 * a = [:foo, 'bar', 2]
4203 * a.slice!(1) # => "bar"
4204 * a # => [:foo, 2]
4205 *
4206 * If +n+ is negative, counts backwards from the end of +self+:
4207 *
4208 * a = [:foo, 'bar', 2]
4209 * a.slice!(-1) # => 2
4210 * a # => [:foo, "bar"]
4211 *
4212 * If +n+ is out of range, returns +nil+.
4213 *
4214 * When the only arguments are Integers +start+ and +length+,
4215 * removes +length+ elements from +self+ beginning at offset +start+;
4216 * returns the deleted objects in a new +Array+:
4217 *
4218 * a = [:foo, 'bar', 2]
4219 * a.slice!(0, 2) # => [:foo, "bar"]
4220 * a # => [2]
4221 *
4222 * If <tt>start + length</tt> exceeds the array size,
4223 * removes and returns all elements from offset +start+ to the end:
4224 *
4225 * a = [:foo, 'bar', 2]
4226 * a.slice!(1, 50) # => ["bar", 2]
4227 * a # => [:foo]
4228 *
4229 * If <tt>start == a.size</tt> and +length+ is non-negative,
4230 * returns a new empty +Array+.
4231 *
4232 * If +length+ is negative, returns +nil+.
4233 *
4234 * When the only argument is a Range object +range+,
4235 * treats <tt>range.min</tt> as +start+ above and <tt>range.size</tt> as +length+ above:
4236 *
4237 * a = [:foo, 'bar', 2]
4238 * a.slice!(1..2) # => ["bar", 2]
4239 * a # => [:foo]
4240 *
4241 * If <tt>range.start == a.size</tt>, returns a new empty +Array+.
4242 *
4243 * If <tt>range.start</tt> is larger than the array size, returns +nil+.
4244 *
4245 * If <tt>range.end</tt> is negative, counts backwards from the end of the array:
4246 *
4247 * a = [:foo, 'bar', 2]
4248 * a.slice!(0..-2) # => [:foo, "bar"]
4249 * a # => [2]
4250 *
4251 * If <tt>range.start</tt> is negative,
4252 * calculates the start index backwards from the end of the array:
4253 *
4254 * a = [:foo, 'bar', 2]
4255 * a.slice!(-2..2) # => ["bar", 2]
4256 * a # => [:foo]
4257 *
4258 */
4260 static VALUE
4262 {
4263 VALUE arg1;
4274 }
4279 /* valid range */
4282 /* invalid range */
4285 /* not a range */
4287 }
4288 }
4291 }
4293 static VALUE
4295 {
4303 }
4304 }
4306 }
4308 static VALUE
4310 {
4320 }
4322 }
4324 }
4326 static VALUE
4328 {
4334 }
4336 /*
4337 * call-seq:
4338 * reject! {|element| ... } -> self or nil
4339 * reject! -> new_enumerator
4340 *
4341 * With a block given, calls the block with each element of +self+;
4342 * removes each element for which the block returns a truthy value.
4343 *
4344 * Returns +self+ if any elements removed:
4345 *
4346 * a = [:foo, 'bar', 2, 'bat']
4347 * a.reject! {|element| element.to_s.start_with?('b') } # => [:foo, 2]
4348 *
4349 * Returns +nil+ if no elements removed.
4350 *
4351 * With no block given, returns a new Enumerator.
4352 *
4353 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
4354 */
4356 static VALUE
4358 {
4362 }
4364 /*
4365 * call-seq:
4366 * reject {|element| ... } -> new_array
4367 * reject -> new_enumerator
4368 *
4369 * With a block given, returns a new array whose elements are all those from +self+
4370 * for which the block returns +false+ or +nil+:
4371 *
4372 * a = [:foo, 'bar', 2, 'bat']
4373 * a1 = a.reject {|element| element.to_s.start_with?('b') }
4374 * a1 # => [:foo, 2]
4375 *
4376 * With no block given, returns a new Enumerator.
4377 *
4378 * Related: {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
4379 */
4381 static VALUE
4383 {
4384 VALUE rejected_ary;
4390 }
4392 /*
4393 * call-seq:
4394 * delete_if {|element| ... } -> self
4395 * delete_if -> new_numerator
4396 *
4397 * With a block given, calls the block with each element of +self+;
4398 * removes the element if the block returns a truthy value;
4399 * returns +self+:
4400 *
4401 * a = [:foo, 'bar', 2, 'bat']
4402 * a.delete_if {|element| element.to_s.start_with?('b') } # => [:foo, 2]
4403 *
4404 * With no block given, returns a new Enumerator.
4405 *
4406 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
4407 */
4409 static VALUE
4411 {
4416 }
4418 static VALUE
4420 {
4426 }
4428 static VALUE
4430 {
4442 }
4445 /*
4446 * call-seq:
4447 * array.zip(*other_arrays) -> new_array
4448 * array.zip(*other_arrays) {|other_array| ... } -> nil
4449 *
4450 * When no block given, returns a new +Array+ +new_array+ of size <tt>self.size</tt>
4451 * whose elements are Arrays.
4452 *
4453 * Each nested array <tt>new_array[n]</tt> is of size <tt>other_arrays.size+1</tt>,
4454 * and contains:
4455 *
4456 * - The _nth_ element of +self+.
4457 * - The _nth_ element of each of the +other_arrays+.
4458 *
4459 * If all +other_arrays+ and +self+ are the same size:
4460 *
4461 * a = [:a0, :a1, :a2, :a3]
4462 * b = [:b0, :b1, :b2, :b3]
4463 * c = [:c0, :c1, :c2, :c3]
4464 * d = a.zip(b, c)
4465 * d # => [[:a0, :b0, :c0], [:a1, :b1, :c1], [:a2, :b2, :c2], [:a3, :b3, :c3]]
4466 *
4467 * If any array in +other_arrays+ is smaller than +self+,
4468 * fills to <tt>self.size</tt> with +nil+:
4469 *
4470 * a = [:a0, :a1, :a2, :a3]
4471 * b = [:b0, :b1, :b2]
4472 * c = [:c0, :c1]
4473 * d = a.zip(b, c)
4474 * d # => [[:a0, :b0, :c0], [:a1, :b1, :c1], [:a2, :b2, nil], [:a3, nil, nil]]
4475 *
4476 * If any array in +other_arrays+ is larger than +self+,
4477 * its trailing elements are ignored:
4478 *
4479 * a = [:a0, :a1, :a2, :a3]
4480 * b = [:b0, :b1, :b2, :b3, :b4]
4481 * c = [:c0, :c1, :c2, :c3, :c4, :c5]
4482 * d = a.zip(b, c)
4483 * d # => [[:a0, :b0, :c0], [:a1, :b1, :c1], [:a2, :b2, :c2], [:a3, :b3, :c3]]
4484 *
4485 * If an argument is not an array, it extracts the values by calling #each:
4486 *
4487 * a = [:a0, :a1, :a2, :a2]
4488 * b = 1..4
4489 * c = a.zip(b)
4490 * c # => [[:a0, 1], [:a1, 2], [:a2, 3], [:a2, 4]]
4491 *
4492 * When a block is given, calls the block with each of the sub-arrays (formed as above); returns +nil+:
4493 *
4494 * a = [:a0, :a1, :a2, :a3]
4495 * b = [:b0, :b1, :b2, :b3]
4496 * c = [:c0, :c1, :c2, :c3]
4497 * a.zip(b, c) {|sub_array| p sub_array} # => nil
4498 *
4499 * Output:
4500 *
4501 * [:a0, :b0, :c0]
4502 * [:a1, :b1, :c1]
4503 * [:a2, :b2, :c2]
4504 * [:a3, :b3, :c3]
4505 *
4506 */
4508 static VALUE
4510 {
4517 }
4531 }
4533 }
4536 }
4544 }
4546 }
4547 }
4548 }
4558 }
4560 }
4561 }
4564 }
4566 /*
4567 * call-seq:
4568 * array.transpose -> new_array
4569 *
4570 * Transposes the rows and columns in an +Array+ of Arrays;
4571 * the nested Arrays must all be the same size:
4572 *
4573 * a = [[:a0, :a1], [:b0, :b1], [:c0, :c1]]
4574 * a.transpose # => [[:a0, :b0, :c0], [:a1, :b1, :c1]]
4575 *
4576 */
4578 static VALUE
4580 {
4593 }
4594 }
4598 }
4601 }
4602 }
4604 }
4606 /*
4607 * call-seq:
4608 * initialize_copy(other_array) -> self
4609 * replace(other_array) -> self
4610 *
4611 * Replaces the elements of +self+ with the elements of +other_array+, which must be an
4612 * {array-convertible object}[rdoc-ref:implicit_conversion.rdoc@Array-Convertible+Objects];
4613 * returns +self+:
4614 *
4615 * a = ['a', 'b', 'c'] # => ["a", "b", "c"]
4616 * a.replace(['d', 'e']) # => ["d", "e"]
4617 *
4618 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
4619 */
4621 VALUE
4623 {
4630 /* orig has enough space to embed the contents of orig. */
4635 }
4636 /* orig is embedded but copy does not have enough space to embed the
4637 * contents of orig. */
4647 // No allocation and exception expected that could leave `copy` in a
4648 // bad state from the edits above.
4650 }
4651 /* Otherwise, orig is on heap and copy does not have enough space to embed
4652 * the contents of orig. */
4659 }
4662 }
4664 /*
4665 * call-seq:
4666 * clear -> self
4667 *
4668 * Removes all elements from +self+; returns +self+:
4669 *
4670 * a = [:foo, 'bar', 2]
4671 * a.clear # => []
4672 *
4673 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
4674 */
4676 VALUE
4678 {
4684 }
4689 }
4690 }
4693 }
4695 /*
4696 * call-seq:
4697 * fill(object, start = nil, count = nil) -> new_array
4698 * fill(object, range) -> new_array
4699 * fill(start = nil, count = nil) {|element| ... } -> new_array
4700 * fill(range) {|element| ... } -> new_array
4701 *
4702 * Replaces selected elements in +self+;
4703 * may add elements to +self+;
4704 * always returns +self+ (never a new array).
4705 *
4706 * In brief:
4707 *
4708 * # Non-negative start.
4709 * ['a', 'b', 'c', 'd'].fill('-', 1, 2) # => ["a", "-", "-", "d"]
4710 * ['a', 'b', 'c', 'd'].fill(1, 2) {|e| e.to_s } # => ["a", "1", "2", "d"]
4711 *
4712 * # Extends with specified values if necessary.
4713 * ['a', 'b', 'c', 'd'].fill('-', 3, 2) # => ["a", "b", "c", "-", "-"]
4714 * ['a', 'b', 'c', 'd'].fill(3, 2) {|e| e.to_s } # => ["a", "b", "c", "3", "4"]
4715 *
4716 * # Fills with nils if necessary.
4717 * ['a', 'b', 'c', 'd'].fill('-', 6, 2) # => ["a", "b", "c", "d", nil, nil, "-", "-"]
4718 * ['a', 'b', 'c', 'd'].fill(6, 2) {|e| e.to_s } # => ["a", "b", "c", "d", nil, nil, "6", "7"]
4719 *
4720 * # For negative start, counts backwards from the end.
4721 * ['a', 'b', 'c', 'd'].fill('-', -3, 3) # => ["a", "-", "-", "-"]
4722 * ['a', 'b', 'c', 'd'].fill(-3, 3) {|e| e.to_s } # => ["a", "1", "2", "3"]
4723 *
4724 * # Range.
4725 * ['a', 'b', 'c', 'd'].fill('-', 1..2) # => ["a", "-", "-", "d"]
4726 * ['a', 'b', 'c', 'd'].fill(1..2) {|e| e.to_s } # => ["a", "1", "2", "d"]
4727 *
4728 * When arguments +start+ and +count+ are given,
4729 * they select the elements of +self+ to be replaced;
4730 * each must be an
4731 * {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects]
4732 * (or +nil+):
4733 *
4734 * - +start+ specifies the zero-based offset of the first element to be replaced;
4735 * +nil+ means zero.
4736 * - +count+ is the number of consecutive elements to be replaced;
4737 * +nil+ means "all the rest."
4738 *
4739 * With argument +object+ given,
4740 * that one object is used for all replacements:
4741 *
4742 * o = Object.new # => #<Object:0x0000014e7bff7600>
4743 * a = ['a', 'b', 'c', 'd'] # => ["a", "b", "c", "d"]
4744 * a.fill(o, 1, 2)
4745 * # => ["a", #<Object:0x0000014e7bff7600>, #<Object:0x0000014e7bff7600>, "d"]
4746 *
4747 * With a block given, the block is called once for each element to be replaced;
4748 * the value passed to the block is the _index_ of the element to be replaced
4749 * (not the element itself);
4750 * the block's return value replaces the element:
4751 *
4752 * a = ['a', 'b', 'c', 'd'] # => ["a", "b", "c", "d"]
4753 * a.fill(1, 2) {|element| element.to_s } # => ["a", "1", "2", "d"]
4754 *
4755 * For arguments +start+ and +count+:
4756 *
4757 * - If +start+ is non-negative,
4758 * replaces +count+ elements beginning at offset +start+:
4759 *
4760 * ['a', 'b', 'c', 'd'].fill('-', 0, 2) # => ["-", "-", "c", "d"]
4761 * ['a', 'b', 'c', 'd'].fill('-', 1, 2) # => ["a", "-", "-", "d"]
4762 * ['a', 'b', 'c', 'd'].fill('-', 2, 2) # => ["a", "b", "-", "-"]
4763 *
4764 * ['a', 'b', 'c', 'd'].fill(0, 2) {|e| e.to_s } # => ["0", "1", "c", "d"]
4765 * ['a', 'b', 'c', 'd'].fill(1, 2) {|e| e.to_s } # => ["a", "1", "2", "d"]
4766 * ['a', 'b', 'c', 'd'].fill(2, 2) {|e| e.to_s } # => ["a", "b", "2", "3"]
4767 *
4768 * Extends +self+ if necessary:
4769 *
4770 * ['a', 'b', 'c', 'd'].fill('-', 3, 2) # => ["a", "b", "c", "-", "-"]
4771 * ['a', 'b', 'c', 'd'].fill('-', 4, 2) # => ["a", "b", "c", "d", "-", "-"]
4772 *
4773 * ['a', 'b', 'c', 'd'].fill(3, 2) {|e| e.to_s } # => ["a", "b", "c", "3", "4"]
4774 * ['a', 'b', 'c', 'd'].fill(4, 2) {|e| e.to_s } # => ["a", "b", "c", "d", "4", "5"]
4775 *
4776 * Fills with +nil+ if necessary:
4777 *
4778 * ['a', 'b', 'c', 'd'].fill('-', 5, 2) # => ["a", "b", "c", "d", nil, "-", "-"]
4779 * ['a', 'b', 'c', 'd'].fill('-', 6, 2) # => ["a", "b", "c", "d", nil, nil, "-", "-"]
4780 *
4781 * ['a', 'b', 'c', 'd'].fill(5, 2) {|e| e.to_s } # => ["a", "b", "c", "d", nil, "5", "6"]
4782 * ['a', 'b', 'c', 'd'].fill(6, 2) {|e| e.to_s } # => ["a", "b", "c", "d", nil, nil, "6", "7"]
4783 *
4784 * Does nothing if +count+ is non-positive:
4785 *
4786 * ['a', 'b', 'c', 'd'].fill('-', 2, 0) # => ["a", "b", "c", "d"]
4787 * ['a', 'b', 'c', 'd'].fill('-', 2, -100) # => ["a", "b", "c", "d"]
4788 * ['a', 'b', 'c', 'd'].fill('-', 6, -100) # => ["a", "b", "c", "d"]
4789 *
4790 * ['a', 'b', 'c', 'd'].fill(2, 0) {|e| fail 'Cannot happen' } # => ["a", "b", "c", "d"]
4791 * ['a', 'b', 'c', 'd'].fill(2, -100) {|e| fail 'Cannot happen' } # => ["a", "b", "c", "d"]
4792 * ['a', 'b', 'c', 'd'].fill(6, -100) {|e| fail 'Cannot happen' } # => ["a", "b", "c", "d"]
4793 *
4794 * - If +start+ is negative, counts backwards from the end of +self+:
4795 *
4796 * ['a', 'b', 'c', 'd'].fill('-', -4, 3) # => ["-", "-", "-", "d"]
4797 * ['a', 'b', 'c', 'd'].fill('-', -3, 3) # => ["a", "-", "-", "-"]
4798 *
4799 * ['a', 'b', 'c', 'd'].fill(-4, 3) {|e| e.to_s } # => ["0", "1", "2", "d"]
4800 * ['a', 'b', 'c', 'd'].fill(-3, 3) {|e| e.to_s } # => ["a", "1", "2", "3"]
4801 *
4802 * Extends +self+ if necessary:
4803 *
4804 * ['a', 'b', 'c', 'd'].fill('-', -2, 3) # => ["a", "b", "-", "-", "-"]
4805 * ['a', 'b', 'c', 'd'].fill('-', -1, 3) # => ["a", "b", "c", "-", "-", "-"]
4806 *
4807 * ['a', 'b', 'c', 'd'].fill(-2, 3) {|e| e.to_s } # => ["a", "b", "2", "3", "4"]
4808 * ['a', 'b', 'c', 'd'].fill(-1, 3) {|e| e.to_s } # => ["a", "b", "c", "3", "4", "5"]
4809 *
4810 * Starts at the beginning of +self+ if +start+ is negative and out-of-range:
4811 *
4812 * ['a', 'b', 'c', 'd'].fill('-', -5, 2) # => ["-", "-", "c", "d"]
4813 * ['a', 'b', 'c', 'd'].fill('-', -6, 2) # => ["-", "-", "c", "d"]
4814 *
4815 * ['a', 'b', 'c', 'd'].fill(-5, 2) {|e| e.to_s } # => ["0", "1", "c", "d"]
4816 * ['a', 'b', 'c', 'd'].fill(-6, 2) {|e| e.to_s } # => ["0", "1", "c", "d"]
4817 *
4818 * Does nothing if +count+ is non-positive:
4819 *
4820 * ['a', 'b', 'c', 'd'].fill('-', -2, 0) # => ["a", "b", "c", "d"]
4821 * ['a', 'b', 'c', 'd'].fill('-', -2, -1) # => ["a", "b", "c", "d"]
4822 *
4823 * ['a', 'b', 'c', 'd'].fill(-2, 0) {|e| fail 'Cannot happen' } # => ["a", "b", "c", "d"]
4824 * ['a', 'b', 'c', 'd'].fill(-2, -1) {|e| fail 'Cannot happen' } # => ["a", "b", "c", "d"]
4825 *
4826 * When argument +range+ is given,
4827 * it must be a Range object whose members are numeric;
4828 * its +begin+ and +end+ values determine the elements of +self+
4829 * to be replaced:
4830 *
4831 * - If both +begin+ and +end+ are positive, they specify the first and last elements
4832 * to be replaced:
4833 *
4834 * ['a', 'b', 'c', 'd'].fill('-', 1..2) # => ["a", "-", "-", "d"]
4835 * ['a', 'b', 'c', 'd'].fill(1..2) {|e| e.to_s } # => ["a", "1", "2", "d"]
4836 *
4837 * If +end+ is smaller than +begin+, replaces no elements:
4838 *
4839 * ['a', 'b', 'c', 'd'].fill('-', 2..1) # => ["a", "b", "c", "d"]
4840 * ['a', 'b', 'c', 'd'].fill(2..1) {|e| e.to_s } # => ["a", "b", "c", "d"]
4841 *
4842 * - If either is negative (or both are negative), counts backwards from the end of +self+:
4843 *
4844 * ['a', 'b', 'c', 'd'].fill('-', -3..2) # => ["a", "-", "-", "d"]
4845 * ['a', 'b', 'c', 'd'].fill('-', 1..-2) # => ["a", "-", "-", "d"]
4846 * ['a', 'b', 'c', 'd'].fill('-', -3..-2) # => ["a", "-", "-", "d"]
4847 *
4848 * ['a', 'b', 'c', 'd'].fill(-3..2) {|e| e.to_s } # => ["a", "1", "2", "d"]
4849 * ['a', 'b', 'c', 'd'].fill(1..-2) {|e| e.to_s } # => ["a", "1", "2", "d"]
4850 * ['a', 'b', 'c', 'd'].fill(-3..-2) {|e| e.to_s } # => ["a", "1", "2", "d"]
4851 *
4852 * - If the +end+ value is excluded (see Range#exclude_end?), omits the last replacement:
4853 *
4854 * ['a', 'b', 'c', 'd'].fill('-', 1...2) # => ["a", "-", "c", "d"]
4855 * ['a', 'b', 'c', 'd'].fill('-', 1...-2) # => ["a", "-", "c", "d"]
4856 *
4857 * ['a', 'b', 'c', 'd'].fill(1...2) {|e| e.to_s } # => ["a", "1", "c", "d"]
4858 * ['a', 'b', 'c', 'd'].fill(1...-2) {|e| e.to_s } # => ["a", "1", "c", "d"]
4859 *
4860 * - If the range is endless (see {Endless Ranges}[rdoc-ref:Range@Endless+Ranges]),
4861 * replaces elements to the end of +self+:
4862 *
4863 * ['a', 'b', 'c', 'd'].fill('-', 1..) # => ["a", "-", "-", "-"]
4864 * ['a', 'b', 'c', 'd'].fill(1..) {|e| e.to_s } # => ["a", "1", "2", "3"]
4865 *
4866 * - If the range is beginless (see {Beginless Ranges}[rdoc-ref:Range@Beginless+Ranges]),
4867 * replaces elements from the beginning of +self+:
4868 *
4869 * ['a', 'b', 'c', 'd'].fill('-', ..2) # => ["-", "-", "-", "d"]
4870 * ['a', 'b', 'c', 'd'].fill(..2) {|e| e.to_s } # => ["0", "1", "2", "d"]
4871 *
4872 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
4873 */
4875 static VALUE
4877 {
4884 }
4887 }
4896 }
4897 /* fall through */
4903 }
4906 }
4910 }
4913 }
4918 }
4921 }
4924 VALUE v;
4931 }
4932 }
4935 }
4937 }
4939 /*
4940 * call-seq:
4941 * self + other_array -> new_array
4942 *
4943 * Returns a new array containing all elements of +self+
4944 * followed by all elements of +other_array+:
4945 *
4946 * a = [0, 1] + [2, 3]
4947 * a # => [0, 1, 2, 3]
4948 *
4949 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
4950 */
4952 VALUE
4954 {
4955 VALUE z;
4968 }
4970 static VALUE
4972 {
4976 }
4979 }
4981 /*
4982 * call-seq:
4983 * concat(*other_arrays) -> self
4984 *
4985 * Adds to +self+ all elements from each array in +other_arrays+; returns +self+:
4986 *
4987 * a = [0, 1]
4988 * a.concat(['two', 'three'], [:four, :five], a)
4989 * # => [0, 1, "two", "three", :four, :five, 0, 1]
4990 *
4991 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
4992 */
4994 static VALUE
4996 {
5001 }
5007 }
5009 }
5013 }
5015 VALUE
5017 {
5019 }
5021 /*
5022 * call-seq:
5023 * self * n -> new_array
5024 * self * string_separator -> new_string
5025 *
5026 * When non-negative integer argument +n+ is given,
5027 * returns a new array built by concatenating +n+ copies of +self+:
5028 *
5029 * a = ['x', 'y']
5030 * a * 3 # => ["x", "y", "x", "y", "x", "y"]
5031 *
5032 * When string argument +string_separator+ is given,
5033 * equivalent to <tt>self.join(string_separator)</tt>:
5034 *
5035 * [0, [0, 1], {foo: 0}] * ', ' # => "0, 0, 1, {:foo=>0}"
5036 *
5037 */
5039 static VALUE
5041 {
5049 }
5055 }
5058 }
5061 }
5074 }
5077 }
5078 }
5079 out:
5081 }
5083 /*
5084 * call-seq:
5085 * assoc(object) -> found_array or nil
5086 *
5087 * Returns the first element +ele+ in +self+ such that +ele+ is an array
5088 * and <tt>ele[0] == object</tt>:
5089 *
5090 * a = [{foo: 0}, [2, 4], [4, 5, 6], [4, 5]]
5091 * a.assoc(4) # => [4, 5, 6]
5092 *
5093 * Returns +nil+ if no such element is found.
5094 *
5095 * Related: Array#rassoc;
5096 * see also {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
5097 */
5099 VALUE
5101 {
5103 VALUE v;
5110 }
5112 }
5114 /*
5115 * call-seq:
5116 * rassoc(object) -> found_array or nil
5117 *
5118 * Returns the first element +ele+ in +self+ such that +ele+ is an array
5119 * and <tt>ele[1] == object</tt>:
5120 *
5121 * a = [{foo: 0}, [2, 4], [4, 5, 6], [4, 5]]
5122 * a.rassoc(4) # => [2, 4]
5123 * a.rassoc(5) # => [4, 5, 6]
5124 *
5125 * Returns +nil+ if no such element is found.
5126 *
5127 * Related: Array#assoc;
5128 * see also {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
5129 */
5131 VALUE
5133 {
5135 VALUE v;
5143 }
5145 }
5147 static VALUE
5149 {
5155 /* rb_equal() can evacuate ptrs */
5170 }
5173 }
5174 }
5175 p1++;
5176 p2++;
5177 }
5179 }
5181 /*
5182 * call-seq:
5183 * self == other_array -> true or false
5184 *
5185 * Returns whether both:
5186 *
5187 * - +self+ and +other_array+ are the same size.
5188 * - Their corresponding elements are the same;
5189 * that is, for each index +i+ in <tt>(0...self.size)</tt>,
5190 * <tt>self[i] == other_array[i]</tt>.
5191 *
5192 * Examples:
5193 *
5194 * [:foo, 'bar', 2] == [:foo, 'bar', 2] # => true
5195 * [:foo, 'bar', 2] == [:foo, 'bar', 2.0] # => true
5196 * [:foo, 'bar', 2] == [:foo, 'bar'] # => false # Different sizes.
5197 * [:foo, 'bar', 2] == [:foo, 'bar', 3] # => false # Different elements.
5198 *
5199 * This method is different from method Array#eql?,
5200 * which compares elements using <tt>Object#eql?</tt>.
5201 *
5202 * Related: see {Methods for Comparing}[rdoc-ref:Array@Methods+for+Comparing].
5203 */
5205 static VALUE
5207 {
5212 }
5214 }
5218 }
5220 static VALUE
5222 {
5229 }
5231 }
5233 /*
5234 * call-seq:
5235 * eql?(other_array) -> true or false
5236 *
5237 * Returns +true+ if +self+ and +other_array+ are the same size,
5238 * and if, for each index +i+ in +self+, <tt>self[i].eql?(other_array[i])</tt>:
5239 *
5240 * a0 = [:foo, 'bar', 2]
5241 * a1 = [:foo, 'bar', 2]
5242 * a1.eql?(a0) # => true
5243 *
5244 * Otherwise, returns +false+.
5245 *
5246 * This method is different from method Array#==,
5247 * which compares using method <tt>Object#==</tt>.
5248 *
5249 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
5250 */
5252 static VALUE
5254 {
5260 }
5262 VALUE
5264 {
5266 st_index_t h;
5267 VALUE n;
5274 }
5277 }
5279 /*
5280 * call-seq:
5281 * hash -> integer
5282 *
5283 * Returns the integer hash value for +self+.
5284 *
5285 * Two arrays with the same content will have the same hash value
5286 * (and will compare using eql?):
5287 *
5288 * ['a', 'b'].hash == ['a', 'b'].hash # => true
5289 * ['a', 'b'].hash == ['a', 'c'].hash # => false
5290 * ['a', 'b'].hash == ['a'].hash # => false
5291 *
5292 */
5294 static VALUE
5296 {
5298 }
5300 /*
5301 * call-seq:
5302 * include?(object) -> true or false
5303 *
5304 * Returns whether for some element +element+ in +self+,
5305 * <tt>object == element</tt>:
5306 *
5307 * [0, 1, 2].include?(2) # => true
5308 * [0, 1, 2].include?(2.0) # => true
5309 * [0, 1, 2].include?(2.1) # => false
5310 *
5311 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
5312 */
5314 VALUE
5316 {
5318 VALUE e;
5324 }
5325 }
5327 }
5329 static VALUE
5331 {
5333 VALUE e;
5339 }
5340 }
5342 }
5344 static VALUE
5346 {
5353 }
5359 }
5360 }
5362 }
5364 /*
5365 * call-seq:
5366 * self <=> other_array -> -1, 0, or 1
5367 *
5368 * Returns -1, 0, or 1 as +self+ is determined
5369 * to be less than, equal to, or greater than +other_array+.
5370 *
5371 * Iterates over each index +i+ in <tt>(0...self.size)</tt>:
5372 *
5373 * - Computes <tt>result[i]</tt> as <tt>self[i] <=> other_array[i]</tt>.
5374 * - Immediately returns 1 if <tt>result[i]</tt> is 1:
5375 *
5376 * [0, 1, 2] <=> [0, 0, 2] # => 1
5377 *
5378 * - Immediately returns -1 if <tt>result[i]</tt> is -1:
5379 *
5380 * [0, 1, 2] <=> [0, 2, 2] # => -1
5381 *
5382 * - Continues if <tt>result[i]</tt> is 0.
5383 *
5384 * When every +result+ is 0,
5385 * returns <tt>self.size <=> other_array.size</tt>
5386 * (see Integer#<=>):
5387 *
5388 * [0, 1, 2] <=> [0, 1] # => 1
5389 * [0, 1, 2] <=> [0, 1, 2] # => 0
5390 * [0, 1, 2] <=> [0, 1, 2, 3] # => -1
5391 *
5392 * Note that when +other_array+ is larger than +self+,
5393 * its trailing elements do not affect the result:
5394 *
5395 * [0, 1, 2] <=> [0, 1, 2, -3] # => -1
5396 * [0, 1, 2] <=> [0, 1, 2, 0] # => -1
5397 * [0, 1, 2] <=> [0, 1, 2, 3] # => -1
5398 *
5399 * Related: see {Methods for Comparing}[rdoc-ref:Array@Methods+for+Comparing].
5400 */
5402 VALUE
5404 {
5406 VALUE v;
5417 }
5419 static VALUE
5421 {
5427 }
5429 }
5433 {
5439 }
5441 static VALUE
5443 {
5446 }
5448 static VALUE
5450 {
5456 }
5458 }
5460 static VALUE
5462 {
5465 }
5467 /*
5468 * call-seq:
5469 * self - other_array -> new_array
5470 *
5471 * Returns a new array containing only those elements of +self+
5472 * that are not found in +other_array+;
5473 * the order from +self+ is preserved:
5474 *
5475 * [0, 1, 1, 2, 1, 1, 3, 1, 1] - [1] # => [0, 2, 3]
5476 * [0, 1, 1, 2, 1, 1, 3, 1, 1] - [3, 2, 0, :foo] # => [1, 1, 1, 1, 1, 1]
5477 * [0, 1, 2] - [:foo] # => [0, 1, 2]
5478 *
5479 * Element are compared using method <tt>#eql?</tt>
5480 * (as defined in each element of +self+).
5481 *
5482 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
5483 */
5485 VALUE
5487 {
5488 VALUE ary3;
5489 VALUE hash;
5501 }
5503 }
5509 }
5512 }
5514 /*
5515 * call-seq:
5516 * difference(*other_arrays = []) -> new_array
5517 *
5518 * Returns a new array containing only those elements from +self+
5519 * that are not found in any of the given +other_arrays+;
5520 * items are compared using <tt>eql?</tt>; order from +self+ is preserved:
5521 *
5522 * [0, 1, 1, 2, 1, 1, 3, 1, 1].difference([1]) # => [0, 2, 3]
5523 * [0, 1, 2, 3].difference([3, 0], [1, 3]) # => [2]
5524 * [0, 1, 2].difference([4]) # => [0, 1, 2]
5525 * [0, 1, 2].difference # => [0, 1, 2]
5526 *
5527 * Returns a copy of +self+ if no arguments are given.
5528 *
5529 * Related: Array#-;
5530 * see also {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
5531 */
5533 static VALUE
5535 {
5536 VALUE ary_diff;
5547 }
5556 }
5559 }
5560 }
5562 }
5567 }
5570 /*
5571 * call-seq:
5572 * self & other_array -> new_array
5573 *
5574 * Returns a new array containing the _intersection_ of +self+ and +other_array+;
5575 * that is, containing those elements found in both +self+ and +other_array+:
5576 *
5577 * [0, 1, 2, 3] & [1, 2] # => [1, 2]
5578 *
5579 * Omits duplicates:
5580 *
5581 * [0, 1, 1, 0] & [0, 1] # => [0, 1]
5582 *
5583 * Preserves order from +self+:
5584 *
5585 * [0, 1, 2] & [3, 2, 1, 0] # => [0, 1, 2]
5586 *
5587 * Identifies common elements using method <tt>#eql?</tt>
5588 * (as defined in each element of +self+).
5589 *
5590 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
5591 */
5594 static VALUE
5596 {
5598 st_data_t vv;
5611 }
5613 }
5622 }
5623 }
5626 }
5628 /*
5629 * call-seq:
5630 * intersection(*other_arrays) -> new_array
5631 *
5632 * Returns a new array containing each element in +self+ that is +#eql?+
5633 * to at least one element in each of the given +other_arrays+;
5634 * duplicates are omitted:
5635 *
5636 * [0, 0, 1, 1, 2, 3].intersection([0, 1, 2], [0, 1, 3]) # => [0, 1]
5637 *
5638 * Each element must correctly implement method <tt>#hash</tt>.
5639 *
5640 * Order from +self+ is preserved:
5641 *
5642 * [0, 1, 2].intersection([2, 1, 0]) # => [0, 1, 2]
5643 *
5644 * Returns a copy of +self+ if no arguments are given.
5645 *
5646 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
5647 */
5649 static VALUE
5651 {
5657 }
5660 }
5662 static int
5664 {
5668 }
5670 static void
5672 {
5678 }
5679 }
5681 static void
5683 {
5689 }
5690 }
5691 }
5693 /*
5694 * call-seq:
5695 * array | other_array -> new_array
5696 *
5697 * Returns the union of +array+ and +Array+ +other_array+;
5698 * duplicates are removed; order is preserved;
5699 * items are compared using <tt>eql?</tt>:
5700 *
5701 * [0, 1] | [2, 3] # => [0, 1, 2, 3]
5702 * [0, 1, 1] | [2, 2, 3] # => [0, 1, 2, 3]
5703 * [0, 1, 2] | [3, 2, 1, 0] # => [0, 1, 2, 3]
5704 *
5705 * Related: Array#union.
5706 */
5708 static VALUE
5710 {
5711 VALUE hash;
5719 }
5725 }
5727 /*
5728 * call-seq:
5729 * array.union(*other_arrays) -> new_array
5730 *
5731 * Returns a new +Array+ that is the union of +self+ and all given Arrays +other_arrays+;
5732 * duplicates are removed; order is preserved; items are compared using <tt>eql?</tt>:
5733 *
5734 * [0, 1, 2, 3].union([4, 5], [6, 7]) # => [0, 1, 2, 3, 4, 5, 6, 7]
5735 * [0, 1, 1].union([2, 1], [3, 1]) # => [0, 1, 2, 3]
5736 * [0, 1, 2, 3].union([3, 2], [1, 0]) # => [0, 1, 2, 3]
5737 *
5738 * Returns a copy of +self+ if no arguments given.
5739 *
5740 * Related: Array#|.
5741 */
5743 static VALUE
5745 {
5748 VALUE hash;
5754 }
5763 }
5769 }
5771 /*
5772 * call-seq:
5773 * intersect?(other_array) -> true or false
5774 *
5775 * Returns whether +other_array+ has at least one element that is +#eql?+ to some element of +self+:
5776 *
5777 * [1, 2, 3].intersect?([3, 4, 5]) # => true
5778 * [1, 2, 3].intersect?([4, 5, 6]) # => false
5779 *
5780 * Each element must correctly implement method <tt>#hash</tt>.
5781 *
5782 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
5783 */
5785 static VALUE
5787 {
5789 st_data_t vv;
5799 }
5801 }
5808 }
5819 }
5820 }
5823 }
5825 static VALUE
5827 {
5830 VALUE v;
5836 }
5837 }
5840 }
5842 static VALUE
5844 {
5849 VALUE v;
5856 }
5857 }
5860 }
5861 }
5864 }
5866 static VALUE
5868 {
5873 VALUE v;
5880 }
5881 }
5884 }
5885 }
5888 }
5890 static VALUE
5892 {
5897 VALUE v;
5904 }
5905 }
5908 }
5909 }
5912 }
5914 /*
5915 * call-seq:
5916 * max -> element
5917 * max(n) -> new_array
5918 * max {|a, b| ... } -> element
5919 * max(n) {|a, b| ... } -> new_array
5920 *
5921 * Returns one of the following:
5922 *
5923 * - The maximum-valued element from +self+.
5924 * - A new array of maximum-valued elements from +self+.
5925 *
5926 * Does not modify +self+.
5927 *
5928 * With no block given, each element in +self+ must respond to method <tt>#<=></tt>
5929 * with a numeric.
5930 *
5931 * With no argument and no block, returns the element in +self+
5932 * having the maximum value per method <tt>#<=></tt>:
5933 *
5934 * [1, 0, 3, 2].max # => 3
5935 *
5936 * With non-negative numeric argument +n+ and no block,
5937 * returns a new array with at most +n+ elements,
5938 * in descending order, per method <tt>#<=></tt>:
5939 *
5940 * [1, 0, 3, 2].max(3) # => [3, 2, 1]
5941 * [1, 0, 3, 2].max(3.0) # => [3, 2, 1]
5942 * [1, 0, 3, 2].max(9) # => [3, 2, 1, 0]
5943 * [1, 0, 3, 2].max(0) # => []
5944 *
5945 * With a block given, the block must return a numeric.
5946 *
5947 * With a block and no argument, calls the block <tt>self.size - 1</tt> times to compare elements;
5948 * returns the element having the maximum value per the block:
5949 *
5950 * ['0', '', '000', '00'].max {|a, b| a.size <=> b.size }
5951 * # => "000"
5952 *
5953 * With non-negative numeric argument +n+ and a block,
5954 * returns a new array with at most +n+ elements,
5955 * in descending order, per the block:
5956 *
5957 * ['0', '', '000', '00'].max(2) {|a, b| a.size <=> b.size }
5958 * # => ["000", "00"]
5959 *
5960 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
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 * min -> element
6094 * min(n) -> new_array
6095 * min {|a, b| ... } -> element
6096 * 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 from +self+.
6102 *
6103 * Does not modify +self+.
6104 *
6105 * With no block given, each element in +self+ must respond to method <tt>#<=></tt>
6106 * with a numeric.
6107 *
6108 * With no argument and no block, returns the element in +self+
6109 * having the minimum value per method <tt>#<=></tt>:
6110 *
6111 * [1, 0, 3, 2].min # => 0
6112 *
6113 * With non-negative numeric argument +n+ and no block,
6114 * returns a new array with at most +n+ elements,
6115 * in ascending order, per method <tt>#<=></tt>:
6116 *
6117 * [1, 0, 3, 2].min(3) # => [0, 1, 2]
6118 * [1, 0, 3, 2].min(3.0) # => [0, 1, 2]
6119 * [1, 0, 3, 2].min(9) # => [0, 1, 2, 3]
6120 * [1, 0, 3, 2].min(0) # => []
6121 *
6122 * With a block given, the block must return a numeric.
6123 *
6124 * With a block and no argument, calls the block <tt>self.size - 1</tt> times to compare elements;
6125 * returns the element having the minimum value per the block:
6126 *
6127 * ['0', '', '000', '00'].min {|a, b| a.size <=> b.size }
6128 * # => ""
6129 *
6130 * With non-negative numeric argument +n+ and a block,
6131 * returns a new array with at most +n+ elements,
6132 * in ascending order, per the block:
6133 *
6134 * ['0', '', '000', '00'].min(2) {|a, b| a.size <=> b.size }
6135 * # => ["", "0"]
6136 *
6137 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
6138 */
6139 static VALUE
6141 {
6143 VALUE num;
6155 }
6156 }
6157 }
6163 }
6166 }
6169 }
6172 }
6173 }
6174 }
6177 }
6179 /*
6180 * call-seq:
6181 * minmax -> array
6182 * minmax {|a, b| ... } -> array
6183 *
6184 * Returns a 2-element array containing the minimum-valued and maximum-valued
6185 * elements from +self+;
6186 * does not modify +self+.
6187 *
6188 * With no block given, the minimum and maximum values are determined using method <tt>#<=></tt>:
6189 *
6190 * [1, 0, 3, 2].minmax # => [0, 3]
6191 *
6192 * With a block given, the block must return a numeric;
6193 * the block is called <tt>self.size - 1</tt> times to compare elements;
6194 * returns the elements having the minimum and maximum values per the block:
6195 *
6196 * ['0', '', '000', '00'].minmax {|a, b| a.size <=> b.size }
6197 * # => ["", "000"]
6198 *
6199 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
6200 */
6201 static VALUE
6203 {
6206 }
6208 }
6210 static int
6212 {
6215 }
6217 /*
6218 * call-seq:
6219 * array.uniq! -> self or nil
6220 * array.uniq! {|element| ... } -> self or nil
6221 *
6222 * Removes duplicate elements from +self+, the first occurrence always being retained;
6223 * returns +self+ if any elements removed, +nil+ otherwise.
6224 *
6225 * With no block given, identifies and removes elements using method <tt>eql?</tt>
6226 * to compare.
6227 *
6228 * Returns +self+ if any elements removed:
6229 *
6230 * a = [0, 0, 1, 1, 2, 2]
6231 * a.uniq! # => [0, 1, 2]
6232 *
6233 * Returns +nil+ if no elements removed.
6234 *
6235 * With a block given, calls the block for each element;
6236 * identifies (using method <tt>eql?</tt>) and removes
6237 * elements for which the block returns duplicate values.
6238 *
6239 * Returns +self+ if any elements removed:
6240 *
6241 * a = ['a', 'aa', 'aaa', 'b', 'bb', 'bbb']
6242 * a.uniq! {|element| element.size } # => ['a', 'aa', 'aaa']
6243 *
6244 * Returns +nil+ if no elements removed.
6245 */
6246 static VALUE
6248 {
6249 VALUE hash;
6257 else
6263 }
6269 }
6274 }
6276 /*
6277 * call-seq:
6278 * array.uniq -> new_array
6279 * array.uniq {|element| ... } -> new_array
6280 *
6281 * Returns a new +Array+ containing those elements from +self+ that are not duplicates,
6282 * the first occurrence always being retained.
6283 *
6284 * With no block given, identifies and omits duplicates using method <tt>eql?</tt>
6285 * to compare:
6286 *
6287 * a = [0, 0, 1, 1, 2, 2]
6288 * a.uniq # => [0, 1, 2]
6289 *
6290 * With a block given, calls the block for each element;
6291 * identifies (using method <tt>eql?</tt>) and omits duplicate values,
6292 * that is, those elements for which the block returns the same value:
6293 *
6294 * a = ['a', 'aa', 'aaa', 'b', 'bb', 'bbb']
6295 * a.uniq {|element| element.size } # => ["a", "aa", "aaa"]
6296 *
6297 */
6299 static VALUE
6301 {
6307 }
6311 }
6315 }
6318 }
6320 /*
6321 * call-seq:
6322 * compact! -> self or nil
6323 *
6324 * Removes all +nil+ elements from +self+;
6325 * Returns +self+ if any elements are removed, +nil+ otherwise:
6326 *
6327 * a = [nil, 0, nil, false, nil, '', nil, [], nil, {}]
6328 * a.compact! # => [0, false, "", [], {}]
6329 * a # => [0, false, "", [], {}]
6330 * a.compact! # => nil
6331 *
6332 * Related: Array#compact;
6333 * see also {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
6334 */
6336 static VALUE
6338 {
6349 }
6353 }
6357 }
6359 /*
6360 * call-seq:
6361 * compact -> new_array
6362 *
6363 * Returns a new array containing only the non-+nil+ elements from +self+;
6364 * element order is preserved:
6365 *
6366 * a = [nil, 0, nil, false, nil, '', nil, [], nil, {}]
6367 * a.compact # => [0, false, "", [], {}]
6368 *
6369 * Related: Array#compact!;
6370 * see also {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
6371 */
6373 static VALUE
6375 {
6379 }
6381 /*
6382 * call-seq:
6383 * count -> integer
6384 * count(object) -> integer
6385 * count {|element| ... } -> integer
6386 *
6387 * Returns a count of specified elements.
6388 *
6389 * With no argument and no block, returns the count of all elements:
6390 *
6391 * [0, :one, 'two', 3, 3.0].count # => 5
6392 *
6393 * With argument +object+ given, returns the count of elements <tt>==</tt> to +object+:
6394 *
6395 * [0, :one, 'two', 3, 3.0].count(3) # => 2
6396 *
6397 * With no argument and a block given, calls the block with each element;
6398 * returns the count of elements for which the block returns a truthy value:
6399 *
6400 * [0, 1, 2, 3].count {|element| element > 1 } # => 2
6401 *
6402 * With argument +object+ and a block given, issues a warning, ignores the block,
6403 * and returns the count of elements <tt>==</tt> to +object+.
6404 *
6405 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
6406 */
6408 static VALUE
6410 {
6414 VALUE v;
6422 }
6423 }
6429 }
6432 }
6433 }
6436 }
6438 static VALUE
6440 {
6450 }
6451 }
6454 }
6468 }
6479 }
6484 }
6486 }
6489 }
6495 }
6497 }
6502 }
6503 }
6506 }
6509 }
6513 }
6517 }
6521 }
6523 /*
6524 * call-seq:
6525 * flatten!(depth = nil) -> self or nil
6526 *
6527 * Returns +self+ as a recursively flattening of +self+ to +depth+ levels of recursion;
6528 * +depth+ must be an
6529 * {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects],
6530 * or +nil+.
6531 * At each level of recursion:
6532 *
6533 * - Each element that is an array is "flattened"
6534 * (that is, replaced by its individual array elements).
6535 * - Each element that is not an array is unchanged
6536 * (even if the element is an object that has instance method +flatten+).
6537 *
6538 * Returns +nil+ if no elements were flattened.
6539 *
6540 * With non-negative integer argument +depth+, flattens recursively through +depth+ levels:
6541 *
6542 * a = [ 0, [ 1, [2, 3], 4 ], 5, {foo: 0}, Set.new([6, 7]) ]
6543 * a # => [0, [1, [2, 3], 4], 5, {:foo=>0}, #<Set: {6, 7}>]
6544 * a.dup.flatten!(1) # => [0, 1, [2, 3], 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6545 * a.dup.flatten!(1.1) # => [0, 1, [2, 3], 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6546 * a.dup.flatten!(2) # => [0, 1, 2, 3, 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6547 * a.dup.flatten!(3) # => [0, 1, 2, 3, 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6548 *
6549 * With +nil+ or negative argument +depth+, flattens all levels:
6550 *
6551 * a.dup.flatten! # => [0, 1, 2, 3, 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6552 * a.dup.flatten!(-1) # => [0, 1, 2, 3, 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6553 *
6554 * Related: Array#flatten;
6555 * see also {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
6556 */
6558 static VALUE
6560 {
6572 }
6578 }
6580 /*
6581 * call-seq:
6582 * flatten(depth = nil) -> new_array
6583 *
6584 * Returns a new array that is a recursive flattening of +self+
6585 * to +depth+ levels of recursion;
6586 * +depth+ must be an
6587 * {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects]
6588 * or +nil+.
6589 * At each level of recursion:
6590 *
6591 * - Each element that is an array is "flattened"
6592 * (that is, replaced by its individual array elements).
6593 * - Each element that is not an array is unchanged
6594 * (even if the element is an object that has instance method +flatten+).
6595 *
6596 * With non-negative integer argument +depth+, flattens recursively through +depth+ levels:
6597 *
6598 * a = [ 0, [ 1, [2, 3], 4 ], 5, {foo: 0}, Set.new([6, 7]) ]
6599 * a # => [0, [1, [2, 3], 4], 5, {:foo=>0}, #<Set: {6, 7}>]
6600 * a.flatten(0) # => [0, [1, [2, 3], 4], 5, {:foo=>0}, #<Set: {6, 7}>]
6601 * a.flatten(1 ) # => [0, 1, [2, 3], 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6602 * a.flatten(1.1) # => [0, 1, [2, 3], 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6603 * a.flatten(2) # => [0, 1, 2, 3, 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6604 * a.flatten(3) # => [0, 1, 2, 3, 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6605 *
6606 * With +nil+ or negative +depth+, flattens all levels.
6607 *
6608 * a.flatten # => [0, 1, 2, 3, 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6609 * a.flatten(-1) # => [0, 1, 2, 3, 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6610 *
6611 * Related: Array#flatten!;
6612 * see also {Methods for Converting}[rdoc-ref:Array@Methods+for+Converting].
6613 */
6615 static VALUE
6617 {
6619 VALUE result;
6624 }
6629 }
6632 }
6634 #define RAND_UPTO(max) (long)rb_random_ulong_limited((randgen), (max)-1)
6636 static VALUE
6638 {
6646 VALUE tmp;
6649 }
6653 }
6656 }
6658 static VALUE
6660 {
6664 }
6670 },
6672 };
6674 static VALUE
6676 {
6677 VALUE result;
6686 else
6690 }
6697 }
6698 }
6704 }
6705 }
6722 {
6726 }
6728 }
6729 memo_threshold =
6742 }
6745 }
6750 }
6751 });
6752 }
6764 }
6772 st_data_t value;
6777 }
6778 });
6779 });
6783 }
6794 }
6795 });
6797 }
6801 }
6803 static VALUE
6805 {
6807 }
6809 static VALUE
6811 {
6816 }
6823 }
6825 /*
6826 * call-seq:
6827 * cycle(count = nil) {|element| ... } -> nil
6828 * cycle(count = nil) -> new_enumerator
6829 *
6830 * With a block given, may call the block, depending on the value of argument +count+;
6831 * +count+ must be an
6832 * {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects],
6833 * or +nil+.
6834 *
6835 * When +count+ is positive,
6836 * calls the block with each element, then does so repeatedly,
6837 * until it has done so +count+ times; returns +nil+:
6838 *
6839 * output = []
6840 * [0, 1].cycle(2) {|element| output.push(element) } # => nil
6841 * output # => [0, 1, 0, 1]
6842 *
6843 * When +count+ is zero or negative, does not call the block:
6844 *
6845 * [0, 1].cycle(0) {|element| fail 'Cannot happen' } # => nil
6846 * [0, 1].cycle(-1) {|element| fail 'Cannot happen' } # => nil
6847 *
6848 * When +count+ is +nil+, cycles forever:
6849 *
6850 * # Prints 0 and 1 forever.
6851 * [0, 1].cycle {|element| puts element }
6852 * [0, 1].cycle(nil) {|element| puts element }
6853 *
6854 * With no block given, returns a new Enumerator.
6855 *
6856 * Related: see {Methods for Iterating}[rdoc-ref:Array@Methods+for+Iterating].
6857 */
6858 static VALUE
6860 {
6868 }
6872 }
6877 }
6878 }
6880 }
6882 /*
6883 * Build a ruby array of the corresponding values and yield it to the
6884 * associated block.
6885 * Return the class of +values+ for reentry check.
6886 */
6887 static int
6889 {
6897 }
6899 /*
6900 * Compute permutations of +r+ elements of the set <code>[0..n-1]</code>.
6901 *
6902 * When we have a complete permutation of array indices, copy the values
6903 * at those indices into a new array and yield that array.
6904 *
6905 * n: the size of the set
6906 * r: the number of elements in each permutation
6907 * p: the array (of size r) that we're filling in
6908 * used: an array of booleans: whether a given index is already used
6909 * values: the Ruby array that holds the actual values to permute
6910 */
6911 static void
6913 {
6922 }
6931 }
6937 }
6938 }
6942 }
6943 }
6944 }
6946 /*
6947 * Returns the product of from, from-1, ..., from - how_many + 1.
6948 * https://en.wikipedia.org/wiki/Pochhammer_symbol
6949 */
6950 static VALUE
6952 {
6953 VALUE cnt;
6959 }
6960 }
6963 }
6965 }
6967 static VALUE
6969 {
6970 VALUE r;
6974 }
6977 }
6980 }
6985 }
6987 }
6989 static VALUE
6991 {
6996 }
6998 /*
6999 * call-seq:
7000 * permutation(n = self.size) {|permutation| ... } -> self
7001 * permutation(n = self.size) -> new_enumerator
7002 *
7003 * Iterates over permutations of the elements of +self+;
7004 * the order of permutations is indeterminate.
7005 *
7006 * With a block and an in-range positive integer argument +n+ (<tt>0 < n <= self.size</tt>) given,
7007 * calls the block with each +n+-tuple permutations of +self+;
7008 * returns +self+:
7009 *
7010 * a = [0, 1, 2]
7011 * perms = []
7012 * a.permutation(1) {|perm| perms.push(perm) }
7013 * perms # => [[0], [1], [2]]
7014 *
7015 * perms = []
7016 * a.permutation(2) {|perm| perms.push(perm) }
7017 * perms # => [[0, 1], [0, 2], [1, 0], [1, 2], [2, 0], [2, 1]]
7018 *
7019 * perms = []
7020 * a.permutation(3) {|perm| perms.push(perm) }
7021 * perms # => [[0, 1, 2], [0, 2, 1], [1, 0, 2], [1, 2, 0], [2, 0, 1], [2, 1, 0]]
7022 *
7023 * When +n+ is zero, calls the block once with a new empty array:
7024 *
7025 * perms = []
7026 * a.permutation(0) {|perm| perms.push(perm) }
7027 * perms # => [[]]
7028 *
7029 * When +n+ is out of range (negative or larger than <tt>self.size</tt>),
7030 * does not call the block:
7031 *
7032 * a.permutation(-1) {|permutation| fail 'Cannot happen' }
7033 * a.permutation(4) {|permutation| fail 'Cannot happen' }
7034 *
7035 * With no block given, returns a new Enumerator.
7036 *
7037 * Related: {Methods for Iterating}[rdoc-ref:Array@Methods+for+Iterating].
7038 */
7040 static VALUE
7042 {
7046 RETURN_SIZED_ENUMERATOR(ary, argc, argv, rb_ary_permutation_size); /* Return enumerator if no block */
7052 /* no permutations: yield nothing */
7053 }
7056 }
7060 }
7061 }
7074 }
7076 }
7078 static void
7080 {
7088 }
7091 }
7096 }
7097 }
7099 static VALUE
7101 {
7106 }
7108 /*
7109 * call-seq:
7110 * combination(n) {|element| ... } -> self
7111 * combination(n) -> new_enumerator
7112 *
7113 * When a block and a positive
7114 * {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects]
7115 * argument +n+ (<tt>0 < n <= self.size</tt>)
7116 * are given, calls the block with all +n+-tuple combinations of +self+;
7117 * returns +self+:
7118 *
7119 * a = %w[a b c] # => ["a", "b", "c"]
7120 * a.combination(2) {|combination| p combination } # => ["a", "b", "c"]
7121 *
7122 * Output:
7123 *
7124 * ["a", "b"]
7125 * ["a", "c"]
7126 * ["b", "c"]
7127 *
7128 * The order of the yielded combinations is not guaranteed.
7129 *
7130 * When +n+ is zero, calls the block once with a new empty array:
7131 *
7132 * a.combination(0) {|combination| p combination }
7133 * [].combination(0) {|combination| p combination }
7134 *
7135 * Output:
7136 *
7137 * []
7138 * []
7139 *
7140 * When +n+ is negative or larger than +self.size+ and +self+ is non-empty,
7141 * does not call the block:
7142 *
7143 * a.combination(-1) {|combination| fail 'Cannot happen' } # => ["a", "b", "c"]
7144 * a.combination(4) {|combination| fail 'Cannot happen' } # => ["a", "b", "c"]
7145 *
7146 * With no block given, returns a new Enumerator.
7147 *
7148 * Related: Array#permutation;
7149 * see also {Methods for Iterating}[rdoc-ref:Array@Methods+for+Iterating].
7150 */
7152 static VALUE
7154 {
7161 /* yield nothing */
7162 }
7165 }
7169 }
7170 }
7180 }
7182 }
7184 /*
7185 * Compute repeated permutations of +r+ elements of the set
7186 * <code>[0..n-1]</code>.
7187 *
7188 * When we have a complete repeated permutation of array indices, copy the
7189 * values at those indices into a new array and yield that array.
7190 *
7191 * n: the size of the set
7192 * r: the number of elements in each permutation
7193 * p: the array (of size r) that we're filling in
7194 * values: the Ruby array that holds the actual values to permute
7195 */
7196 static void
7198 {
7206 }
7211 }
7212 }
7216 }
7217 }
7219 static VALUE
7221 {
7227 }
7230 }
7232 }
7234 /*
7235 * call-seq:
7236 * array.repeated_permutation(n) {|permutation| ... } -> self
7237 * array.repeated_permutation(n) -> new_enumerator
7238 *
7239 * Calls the block with each repeated permutation of length +n+ of the elements of +self+;
7240 * each permutation is an +Array+;
7241 * returns +self+. The order of the permutations is indeterminate.
7242 *
7243 * When a block and a positive Integer argument +n+ are given, calls the block with each
7244 * +n+-tuple repeated permutation of the elements of +self+.
7245 * The number of permutations is <tt>self.size**n</tt>.
7246 *
7247 * +n+ = 1:
7248 *
7249 * a = [0, 1, 2]
7250 * a.repeated_permutation(1) {|permutation| p permutation }
7251 *
7252 * Output:
7253 *
7254 * [0]
7255 * [1]
7256 * [2]
7257 *
7258 * +n+ = 2:
7259 *
7260 * a.repeated_permutation(2) {|permutation| p permutation }
7261 *
7262 * Output:
7263 *
7264 * [0, 0]
7265 * [0, 1]
7266 * [0, 2]
7267 * [1, 0]
7268 * [1, 1]
7269 * [1, 2]
7270 * [2, 0]
7271 * [2, 1]
7272 * [2, 2]
7273 *
7274 * If +n+ is zero, calls the block once with an empty +Array+.
7275 *
7276 * If +n+ is negative, does not call the block:
7277 *
7278 * a.repeated_permutation(-1) {|permutation| fail 'Cannot happen' }
7279 *
7280 * Returns a new Enumerator if no block given:
7281 *
7282 * a = [0, 1, 2]
7283 * a.repeated_permutation(2) # => #<Enumerator: [0, 1, 2]:permutation(2)>
7284 *
7285 * Using Enumerators, it's convenient to show the permutations and counts
7286 * for some values of +n+:
7287 *
7288 * e = a.repeated_permutation(0)
7289 * e.size # => 1
7290 * e.to_a # => [[]]
7291 * e = a.repeated_permutation(1)
7292 * e.size # => 3
7293 * e.to_a # => [[0], [1], [2]]
7294 * e = a.repeated_permutation(2)
7295 * e.size # => 9
7296 * e.to_a # => [[0, 0], [0, 1], [0, 2], [1, 0], [1, 1], [1, 2], [2, 0], [2, 1], [2, 2]]
7297 *
7298 */
7299 static VALUE
7301 {
7305 RETURN_SIZED_ENUMERATOR(ary, 1, &num, rb_ary_repeated_permutation_size); /* Return Enumerator if no block */
7309 /* no permutations: yield nothing */
7310 }
7313 }
7317 }
7318 }
7328 }
7330 }
7332 static void
7334 {
7342 }
7347 }
7348 }
7352 }
7353 }
7355 static VALUE
7357 {
7362 }
7364 }
7366 /*
7367 * call-seq:
7368 * repeated_combination(size) {|combination| ... } -> self
7369 * repeated_combination(size) -> new_enumerator
7370 *
7371 * With a block given, calls the block with each repeated combination of length +size+
7372 * of the elements of +self+;
7373 * each combination is an array;
7374 * returns +self+. The order of the combinations is indeterminate.
7375 *
7376 * If a positive integer argument +size+ is given,
7377 * calls the block with each +size+-tuple repeated combination of the elements of +self+.
7378 * The number of combinations is <tt>(size+1)(size+2)/2</tt>.
7379 *
7380 * Examples:
7381 *
7382 * - +size+ is 1:
7383 *
7384 * c = []
7385 * [0, 1, 2].repeated_combination(1) {|combination| c.push(combination) }
7386 * c # => [[0], [1], [2]]
7387 *
7388 * - +size+ is 2:
7389 *
7390 * c = []
7391 * [0, 1, 2].repeated_combination(2) {|combination| c.push(combination) }
7392 * c # => [[0, 0], [0, 1], [0, 2], [1, 1], [1, 2], [2, 2]]
7393 *
7394 * If +size+ is zero, calls the block once with an empty array.
7395 *
7396 * If +size+ is negative, does not call the block:
7397 *
7398 * [0, 1, 2].repeated_combination(-1) {|combination| fail 'Cannot happen' }
7399 *
7400 * With no block given, returns a new Enumerator.
7401 *
7402 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
7403 */
7405 static VALUE
7407 {
7411 RETURN_SIZED_ENUMERATOR(ary, 1, &num, rb_ary_repeated_combination_size); /* Return enumerator if no block */
7414 /* yield nothing */
7415 }
7418 }
7422 }
7423 }
7425 /* yield nothing */
7426 }
7436 }
7438 }
7440 /*
7441 * call-seq:
7442 * product(*other_arrays) -> new_array
7443 * product(*other_arrays) {|combination| ... } -> self
7444 *
7445 * Computes all combinations of elements from all the arrays,
7446 * including both +self+ and +other_arrays+:
7447 *
7448 * - The number of combinations is the product of the sizes of all the arrays,
7449 * including both +self+ and +other_arrays+.
7450 * - The order of the returned combinations is indeterminate.
7451 *
7452 * With no block given, returns the combinations as an array of arrays:
7453 *
7454 * p = [0, 1].product([2, 3])
7455 * # => [[0, 2], [0, 3], [1, 2], [1, 3]]
7456 * p.size # => 4
7457 * p = [0, 1].product([2, 3], [4, 5])
7458 * # => [[0, 2, 4], [0, 2, 5], [0, 3, 4], [0, 3, 5], [1, 2, 4], [1, 2, 5], [1, 3, 4], [1, 3,...
7459 * p.size # => 8
7460 *
7461 * If +self+ or any argument is empty, returns an empty array:
7462 *
7463 * [].product([2, 3], [4, 5]) # => []
7464 * [0, 1].product([2, 3], []) # => []
7465 *
7466 * If no argument is given, returns an array of 1-element arrays,
7467 * each containing an element of +self+:
7468 *
7469 * a.product # => [[0], [1], [2]]
7470 *
7471 * With a block given, calls the block with each combination; returns +self+:
7472 *
7473 * p = []
7474 * [0, 1].product([2, 3]) {|combination| p.push(combination) }
7475 * p # => [[0, 2], [0, 3], [1, 2], [1, 3]]
7476 *
7477 * If +self+ or any argument is empty, does not call the block:
7478 *
7479 * [].product([2, 3], [4, 5]) {|combination| fail 'Cannot happen' }
7480 * # => []
7481 * [0, 1].product([2, 3], []) {|combination| fail 'Cannot happen' }
7482 * # => [0, 1]
7483 *
7484 * If no argument is given, calls the block with each element of +self+ as a 1-element array:
7485 *
7486 * p = []
7487 * [0, 1].product {|combination| p.push(combination) }
7488 * p # => [[0], [1]]
7489 *
7490 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
7491 */
7493 static VALUE
7495 {
7507 /* initialize the arrays of arrays */
7513 /* initialize the counters for the arrays */
7516 /* Otherwise, allocate and fill in an array of results */
7518 /* Make defensive copies of arrays; exit if any is empty */
7522 }
7523 }
7525 /* Compute the length of the result array; return [] if any is empty */
7531 }
7535 }
7537 }
7540 /* fill in one subarray */
7544 }
7546 /* put it on the result array */
7552 }
7555 }
7556 }
7559 }
7561 /*
7562 * Increment the last counter. If it overflows, reset to 0
7563 * and increment the one before it.
7564 */
7569 /* If the first counter overflows, we are done */
7572 }
7573 }
7575 done:
7579 }
7581 /*
7582 * call-seq:
7583 * array.take(n) -> new_array
7584 *
7585 * Returns a new +Array+ containing the first +n+ element of +self+,
7586 * where +n+ is a non-negative Integer;
7587 * does not modify +self+.
7588 *
7589 * Examples:
7590 *
7591 * a = [0, 1, 2, 3, 4, 5]
7592 * a.take(1) # => [0]
7593 * a.take(2) # => [0, 1]
7594 * a.take(50) # => [0, 1, 2, 3, 4, 5]
7595 * a # => [0, 1, 2, 3, 4, 5]
7596 *
7597 */
7599 static VALUE
7601 {
7605 }
7607 }
7609 /*
7610 * call-seq:
7611 * array.take_while {|element| ... } -> new_array
7612 * array.take_while -> new_enumerator
7613 *
7614 * Returns a new +Array+ containing zero or more leading elements of +self+;
7615 * does not modify +self+.
7616 *
7617 * With a block given, calls the block with each successive element of +self+;
7618 * stops if the block returns +false+ or +nil+;
7619 * returns a new +Array+ containing those elements for which the block returned a truthy value:
7620 *
7621 * a = [0, 1, 2, 3, 4, 5]
7622 * a.take_while {|element| element < 3 } # => [0, 1, 2]
7623 * a.take_while {|element| true } # => [0, 1, 2, 3, 4, 5]
7624 * a # => [0, 1, 2, 3, 4, 5]
7625 *
7626 * With no block given, returns a new Enumerator:
7627 *
7628 * [0, 1].take_while # => #<Enumerator: [0, 1]:take_while>
7629 *
7630 */
7632 static VALUE
7634 {
7640 }
7642 }
7644 /*
7645 * call-seq:
7646 * drop(n) -> new_array
7647 *
7648 * Returns a new array containing all but the first +n+ element of +self+,
7649 * where +n+ is a non-negative Integer;
7650 * does not modify +self+.
7651 *
7652 * Examples:
7653 *
7654 * a = [0, 1, 2, 3, 4, 5]
7655 * a.drop(0) # => [0, 1, 2, 3, 4, 5]
7656 * a.drop(1) # => [1, 2, 3, 4, 5]
7657 * a.drop(2) # => [2, 3, 4, 5]
7658 * a.drop(9) # => []
7659 *
7660 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
7661 */
7663 static VALUE
7665 {
7666 VALUE result;
7670 }
7675 }
7677 /*
7678 * call-seq:
7679 * drop_while {|element| ... } -> new_array
7680 * drop_while -> new_enumerator
7681 *
7682 * With a block given, calls the block with each successive element of +self+;
7683 * stops if the block returns +false+ or +nil+;
7684 * returns a new array _omitting_ those elements for which the block returned a truthy value;
7685 * does not modify +self+:
7686 *
7687 * a = [0, 1, 2, 3, 4, 5]
7688 * a.drop_while {|element| element < 3 } # => [3, 4, 5]
7689 *
7690 * With no block given, returns a new Enumerator.
7691 *
7692 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
7693 */
7695 static VALUE
7697 {
7703 }
7705 }
7707 /*
7708 * call-seq:
7709 * any? -> true or false
7710 * any?(object) -> true or false
7711 * any? {|element| ... } -> true or false
7712 *
7713 * Returns whether for any element of +self+, a given criterion is satisfied.
7714 *
7715 * With no block and no argument, returns whether any element of +self+ is truthy:
7716 *
7717 * [nil, false, []].any? # => true # Array object is truthy.
7718 * [nil, false, {}].any? # => true # Hash object is truthy.
7719 * [nil, false, ''].any? # => true # String object is truthy.
7720 * [nil, false].any? # => false # Nil and false are not truthy.
7721 *
7722 * With argument +object+ given,
7723 * returns whether <tt>object === ele</tt> for any element +ele+ in +self+:
7724 *
7725 * [nil, false, 0].any?(0) # => true
7726 * [nil, false, 1].any?(0) # => false
7727 * [nil, false, 'food'].any?(/foo/) # => true
7728 * [nil, false, 'food'].any?(/bar/) # => false
7729 *
7730 * With a block given,
7731 * calls the block with each element in +self+;
7732 * returns whether the block returns any truthy value:
7733 *
7734 * [0, 1, 2].any? {|ele| ele < 1 } # => true
7735 * [0, 1, 2].any? {|ele| ele < 0 } # => false
7736 *
7737 * With both a block and argument +object+ given,
7738 * ignores the block and uses +object+ as above.
7739 *
7740 * <b>Special case</b>: returns +false+ if +self+ is empty
7741 * (regardless of any given argument or block).
7742 *
7743 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
7744 */
7746 static VALUE
7748 {
7756 }
7759 }
7760 }
7764 }
7765 }
7769 }
7770 }
7772 }
7774 /*
7775 * call-seq:
7776 * all? -> true or false
7777 * all?(object) -> true or false
7778 * all? {|element| ... } -> true or false
7779 *
7780 * Returns whether for every element of +self+,
7781 * a given criterion is satisfied.
7782 *
7783 * With no block and no argument,
7784 * returns whether every element of +self+ is truthy:
7785 *
7786 * [[], {}, '', 0, 0.0, Object.new].all? # => true # All truthy objects.
7787 * [[], {}, '', 0, 0.0, nil].all? # => false # nil is not truthy.
7788 * [[], {}, '', 0, 0.0, false].all? # => false # false is not truthy.
7789 *
7790 * With argument +object+ given, returns whether <tt>object === ele</tt>
7791 * for every element +ele+ in +self+:
7792 *
7793 * [0, 0, 0].all?(0) # => true
7794 * [0, 1, 2].all?(1) # => false
7795 * ['food', 'fool', 'foot'].all?(/foo/) # => true
7796 * ['food', 'drink'].all?(/foo/) # => false
7797 *
7798 * With a block given, calls the block with each element in +self+;
7799 * returns whether the block returns only truthy values:
7800 *
7801 * [0, 1, 2].all? { |ele| ele < 3 } # => true
7802 * [0, 1, 2].all? { |ele| ele < 2 } # => false
7803 *
7804 * With both a block and argument +object+ given,
7805 * ignores the block and uses +object+ as above.
7806 *
7807 * <b>Special case</b>: returns +true+ if +self+ is empty
7808 * (regardless of any given argument or block).
7809 *
7810 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
7811 */
7813 static VALUE
7815 {
7823 }
7826 }
7827 }
7831 }
7832 }
7836 }
7837 }
7839 }
7841 /*
7842 * call-seq:
7843 * none? -> true or false
7844 * none?(object) -> true or false
7845 * none? {|element| ... } -> true or false
7846 *
7847 * Returns +true+ if no element of +self+ meets a given criterion, +false+ otherwise.
7848 *
7849 * With no block given and no argument, returns +true+ if +self+ has no truthy elements,
7850 * +false+ otherwise:
7851 *
7852 * [nil, false].none? # => true
7853 * [nil, 0, false].none? # => false
7854 * [].none? # => true
7855 *
7856 * With argument +object+ given, returns +false+ if for any element +element+,
7857 * <tt>object === element</tt>; +true+ otherwise:
7858 *
7859 * ['food', 'drink'].none?(/bar/) # => true
7860 * ['food', 'drink'].none?(/foo/) # => false
7861 * [].none?(/foo/) # => true
7862 * [0, 1, 2].none?(3) # => true
7863 * [0, 1, 2].none?(1) # => false
7864 *
7865 * With a block given, calls the block with each element in +self+;
7866 * returns +true+ if the block returns no truthy value, +false+ otherwise:
7867 *
7868 * [0, 1, 2].none? {|element| element > 3 } # => true
7869 * [0, 1, 2].none? {|element| element > 1 } # => false
7870 *
7871 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
7872 */
7874 static VALUE
7876 {
7884 }
7887 }
7888 }
7892 }
7893 }
7897 }
7898 }
7900 }
7902 /*
7903 * call-seq:
7904 * one? -> true or false
7905 * one? {|element| ... } -> true or false
7906 * one?(object) -> true or false
7907 *
7908 * Returns +true+ if exactly one element of +self+ meets a given criterion.
7909 *
7910 * With no block given and no argument, returns +true+ if +self+ has exactly one truthy element,
7911 * +false+ otherwise:
7912 *
7913 * [nil, 0].one? # => true
7914 * [0, 0].one? # => false
7915 * [nil, nil].one? # => false
7916 * [].one? # => false
7917 *
7918 * With a block given, calls the block with each element in +self+;
7919 * returns +true+ if the block a truthy value for exactly one element, +false+ otherwise:
7920 *
7921 * [0, 1, 2].one? {|element| element > 0 } # => false
7922 * [0, 1, 2].one? {|element| element > 1 } # => true
7923 * [0, 1, 2].one? {|element| element > 2 } # => false
7924 *
7925 * With argument +object+ given, returns +true+ if for exactly one element +element+, <tt>object === element</tt>;
7926 * +false+ otherwise:
7927 *
7928 * [0, 1, 2].one?(0) # => true
7929 * [0, 0, 1].one?(0) # => false
7930 * [1, 1, 2].one?(0) # => false
7931 * ['food', 'drink'].one?(/bar/) # => false
7932 * ['food', 'drink'].one?(/foo/) # => true
7933 * [].one?(/foo/) # => false
7934 *
7935 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
7936 */
7938 static VALUE
7940 {
7949 }
7954 }
7955 }
7956 }
7962 }
7963 }
7964 }
7970 }
7971 }
7972 }
7974 }
7976 /*
7977 * call-seq:
7978 * array.dig(index, *identifiers) -> object
7979 *
7980 * Finds and returns the object in nested object
7981 * specified by +index+ and +identifiers+;
7982 * the nested objects may be instances of various classes.
7983 * See {Dig Methods}[rdoc-ref:dig_methods.rdoc].
7984 *
7985 * Examples:
7986 *
7987 * a = [:foo, [:bar, :baz, [:bat, :bam]]]
7988 * a.dig(1) # => [:bar, :baz, [:bat, :bam]]
7989 * a.dig(1, 2) # => [:bat, :bam]
7990 * a.dig(1, 2, 0) # => :bat
7991 * a.dig(1, 2, 3) # => nil
7992 *
7993 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
7994 */
7996 static VALUE
7998 {
8004 }
8008 {
8013 }
8016 }
8018 }
8020 /*
8021 * call-seq:
8022 * array.sum(init = 0) -> object
8023 * array.sum(init = 0) {|element| ... } -> object
8024 *
8025 * When no block is given, returns the object equivalent to:
8026 *
8027 * sum = init
8028 * array.each {|element| sum += element }
8029 * sum
8030 *
8031 * For example, <tt>[e1, e2, e3].sum</tt> returns <tt>init + e1 + e2 + e3</tt>.
8032 *
8033 * Examples:
8034 *
8035 * a = [0, 1, 2, 3]
8036 * a.sum # => 6
8037 * a.sum(100) # => 106
8038 *
8039 * The elements need not be numeric, but must be <tt>+</tt>-compatible
8040 * with each other and with +init+:
8041 *
8042 * a = ['abc', 'def', 'ghi']
8043 * a.sum('jkl') # => "jklabcdefghi"
8044 *
8045 * When a block is given, it is called with each element
8046 * and the block's return value (instead of the element itself) is used as the addend:
8047 *
8048 * a = ['zero', 1, :two]
8049 * s = a.sum('Coerced and concatenated: ') {|element| element.to_s }
8050 * s # => "Coerced and concatenated: zero1two"
8051 *
8052 * Notes:
8053 *
8054 * - Array#join and Array#flatten may be faster than Array#sum
8055 * for an +Array+ of Strings or an +Array+ of Arrays.
8056 * - Array#sum method may not respect method redefinition of "+" methods such as Integer#+.
8057 *
8058 */
8060 static VALUE
8062 {
8080 }
8091 }
8092 }
8098 else
8100 }
8101 else
8103 }
8107 not_exact:
8111 /*
8112 * Kahan-Babuska balancing compensated summation algorithm
8113 * See https://link.springer.com/article/10.1007/s00607-005-0139-x
8114 */
8126 has_float_value:
8134 else
8141 }
8145 else
8148 }
8154 else
8157 }
8161 not_float:
8163 }
8166 init_is_a_value:
8171 has_some_value:
8173 }
8175 }
8177 /* :nodoc: */
8178 static VALUE
8180 {
8182 }
8184 /*
8185 * An +Array+ is an ordered, integer-indexed collection of objects, called _elements_.
8186 * Any object (even another array) may be an array element,
8187 * and an array can contain objects of different types.
8188 *
8189 * == +Array+ Indexes
8190 *
8191 * +Array+ indexing starts at 0, as in C or Java.
8192 *
8193 * A positive index is an offset from the first element:
8194 *
8195 * - Index 0 indicates the first element.
8196 * - Index 1 indicates the second element.
8197 * - ...
8198 *
8199 * A negative index is an offset, backwards, from the end of the array:
8200 *
8201 * - Index -1 indicates the last element.
8202 * - Index -2 indicates the next-to-last element.
8203 * - ...
8204 *
8205 * A non-negative index is <i>in range</i> if and only if it is smaller than
8206 * the size of the array. For a 3-element array:
8207 *
8208 * - Indexes 0 through 2 are in range.
8209 * - Index 3 is out of range.
8210 *
8211 * A negative index is <i>in range</i> if and only if its absolute value is
8212 * not larger than the size of the array. For a 3-element array:
8213 *
8214 * - Indexes -1 through -3 are in range.
8215 * - Index -4 is out of range.
8216 *
8217 * Although the effective index into an array is always an integer,
8218 * some methods (both within and outside of class +Array+)
8219 * accept one or more non-integer arguments that are
8220 * {integer-convertible objects}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects].
8221 *
8222 *
8223 * == Creating Arrays
8224 *
8225 * You can create an +Array+ object explicitly with:
8226 *
8227 * - An {array literal}[rdoc-ref:literals.rdoc@Array+Literals]:
8228 *
8229 * [1, 'one', :one, [2, 'two', :two]]
8230 *
8231 * - A {%w or %W: string-array Literal}[rdoc-ref:literals.rdoc@25w+and+-25W-3A+String-Array+Literals]:
8232 *
8233 * %w[foo bar baz] # => ["foo", "bar", "baz"]
8234 * %w[1 % *] # => ["1", "%", "*"]
8235 *
8236 * - A {%i pr %I: symbol-array Literal}[rdoc-ref:literals.rdoc@25i+and+-25I-3A+Symbol-Array+Literals]:
8237 *
8238 * %i[foo bar baz] # => [:foo, :bar, :baz]
8239 * %i[1 % *] # => [:"1", :%, :*]
8240 *
8241 * - \Method Kernel#Array:
8242 *
8243 * Array(["a", "b"]) # => ["a", "b"]
8244 * Array(1..5) # => [1, 2, 3, 4, 5]
8245 * Array(key: :value) # => [[:key, :value]]
8246 * Array(nil) # => []
8247 * Array(1) # => [1]
8248 * Array({:a => "a", :b => "b"}) # => [[:a, "a"], [:b, "b"]]
8249 *
8250 * - \Method Array.new:
8251 *
8252 * Array.new # => []
8253 * Array.new(3) # => [nil, nil, nil]
8254 * Array.new(4) {Hash.new} # => [{}, {}, {}, {}]
8255 * Array.new(3, true) # => [true, true, true]
8256 *
8257 * Note that the last example above populates the array
8258 * with references to the same object.
8259 * This is recommended only in cases where that object is a natively immutable object
8260 * such as a symbol, a numeric, +nil+, +true+, or +false+.
8261 *
8262 * Another way to create an array with various objects, using a block;
8263 * this usage is safe for mutable objects such as hashes, strings or
8264 * other arrays:
8265 *
8266 * Array.new(4) {|i| i.to_s } # => ["0", "1", "2", "3"]
8267 *
8268 * Here is a way to create a multi-dimensional array:
8269 *
8270 * Array.new(3) {Array.new(3)}
8271 * # => [[nil, nil, nil], [nil, nil, nil], [nil, nil, nil]]
8272 *
8273 * A number of Ruby methods, both in the core and in the standard library,
8274 * provide instance method +to_a+, which converts an object to an array.
8275 *
8276 * - ARGF#to_a
8277 * - Array#to_a
8278 * - Enumerable#to_a
8279 * - Hash#to_a
8280 * - MatchData#to_a
8281 * - NilClass#to_a
8282 * - OptionParser#to_a
8283 * - Range#to_a
8284 * - Set#to_a
8285 * - Struct#to_a
8286 * - Time#to_a
8287 * - Benchmark::Tms#to_a
8288 * - CSV::Table#to_a
8289 * - Enumerator::Lazy#to_a
8290 * - Gem::List#to_a
8291 * - Gem::NameTuple#to_a
8292 * - Gem::Platform#to_a
8293 * - Gem::RequestSet::Lockfile::Tokenizer#to_a
8294 * - Gem::SourceList#to_a
8295 * - OpenSSL::X509::Extension#to_a
8296 * - OpenSSL::X509::Name#to_a
8297 * - Racc::ISet#to_a
8298 * - Rinda::RingFinger#to_a
8299 * - Ripper::Lexer::Elem#to_a
8300 * - RubyVM::InstructionSequence#to_a
8301 * - YAML::DBM#to_a
8302 *
8303 * == Example Usage
8304 *
8305 * In addition to the methods it mixes in through the Enumerable module, the
8306 * +Array+ class has proprietary methods for accessing, searching and otherwise
8307 * manipulating arrays.
8308 *
8309 * Some of the more common ones are illustrated below.
8310 *
8311 * == Accessing Elements
8312 *
8313 * Elements in an array can be retrieved using the Array#[] method. It can
8314 * take a single integer argument (a numeric index), a pair of arguments
8315 * (start and length) or a range. Negative indices start counting from the end,
8316 * with -1 being the last element.
8317 *
8318 * arr = [1, 2, 3, 4, 5, 6]
8319 * arr[2] #=> 3
8320 * arr[100] #=> nil
8321 * arr[-3] #=> 4
8322 * arr[2, 3] #=> [3, 4, 5]
8323 * arr[1..4] #=> [2, 3, 4, 5]
8324 * arr[1..-3] #=> [2, 3, 4]
8325 *
8326 * Another way to access a particular array element is by using the #at method
8327 *
8328 * arr.at(0) #=> 1
8329 *
8330 * The #slice method works in an identical manner to Array#[].
8331 *
8332 * To raise an error for indices outside of the array bounds or else to
8333 * provide a default value when that happens, you can use #fetch.
8334 *
8335 * arr = ['a', 'b', 'c', 'd', 'e', 'f']
8336 * arr.fetch(100) #=> IndexError: index 100 outside of array bounds: -6...6
8337 * arr.fetch(100, "oops") #=> "oops"
8338 *
8339 * The special methods #first and #last will return the first and last
8340 * elements of an array, respectively.
8341 *
8342 * arr.first #=> 1
8343 * arr.last #=> 6
8344 *
8345 * To return the first +n+ elements of an array, use #take
8346 *
8347 * arr.take(3) #=> [1, 2, 3]
8348 *
8349 * #drop does the opposite of #take, by returning the elements after +n+
8350 * elements have been dropped:
8351 *
8352 * arr.drop(3) #=> [4, 5, 6]
8353 *
8354 * == Obtaining Information about an +Array+
8355 *
8356 * Arrays keep track of their own length at all times. To query an array
8357 * about the number of elements it contains, use #length, #count or #size.
8358 *
8359 * browsers = ['Chrome', 'Firefox', 'Safari', 'Opera', 'IE']
8360 * browsers.length #=> 5
8361 * browsers.count #=> 5
8362 *
8363 * To check whether an array contains any elements at all
8364 *
8365 * browsers.empty? #=> false
8366 *
8367 * To check whether a particular item is included in the array
8368 *
8369 * browsers.include?('Konqueror') #=> false
8370 *
8371 * == Adding Items to Arrays
8372 *
8373 * Items can be added to the end of an array by using either #push or #<<
8374 *
8375 * arr = [1, 2, 3, 4]
8376 * arr.push(5) #=> [1, 2, 3, 4, 5]
8377 * arr << 6 #=> [1, 2, 3, 4, 5, 6]
8378 *
8379 * #unshift will add a new item to the beginning of an array.
8380 *
8381 * arr.unshift(0) #=> [0, 1, 2, 3, 4, 5, 6]
8382 *
8383 * With #insert you can add a new element to an array at any position.
8384 *
8385 * arr.insert(3, 'apple') #=> [0, 1, 2, 'apple', 3, 4, 5, 6]
8386 *
8387 * Using the #insert method, you can also insert multiple values at once:
8388 *
8389 * arr.insert(3, 'orange', 'pear', 'grapefruit')
8390 * #=> [0, 1, 2, "orange", "pear", "grapefruit", "apple", 3, 4, 5, 6]
8391 *
8392 * == Removing Items from an +Array+
8393 *
8394 * The method #pop removes the last element in an array and returns it:
8395 *
8396 * arr = [1, 2, 3, 4, 5, 6]
8397 * arr.pop #=> 6
8398 * arr #=> [1, 2, 3, 4, 5]
8399 *
8400 * To retrieve and at the same time remove the first item, use #shift:
8401 *
8402 * arr.shift #=> 1
8403 * arr #=> [2, 3, 4, 5]
8404 *
8405 * To delete an element at a particular index:
8406 *
8407 * arr.delete_at(2) #=> 4
8408 * arr #=> [2, 3, 5]
8409 *
8410 * To delete a particular element anywhere in an array, use #delete:
8411 *
8412 * arr = [1, 2, 2, 3]
8413 * arr.delete(2) #=> 2
8414 * arr #=> [1,3]
8415 *
8416 * A useful method if you need to remove +nil+ values from an array is
8417 * #compact:
8418 *
8419 * arr = ['foo', 0, nil, 'bar', 7, 'baz', nil]
8420 * arr.compact #=> ['foo', 0, 'bar', 7, 'baz']
8421 * arr #=> ['foo', 0, nil, 'bar', 7, 'baz', nil]
8422 * arr.compact! #=> ['foo', 0, 'bar', 7, 'baz']
8423 * arr #=> ['foo', 0, 'bar', 7, 'baz']
8424 *
8425 * Another common need is to remove duplicate elements from an array.
8426 *
8427 * It has the non-destructive #uniq, and destructive method #uniq!
8428 *
8429 * arr = [2, 5, 6, 556, 6, 6, 8, 9, 0, 123, 556]
8430 * arr.uniq #=> [2, 5, 6, 556, 8, 9, 0, 123]
8431 *
8432 * == Iterating over Arrays
8433 *
8434 * Like all classes that include the Enumerable module, +Array+ has an each
8435 * method, which defines what elements should be iterated over and how. In
8436 * case of Array's #each, all elements in the +Array+ instance are yielded to
8437 * the supplied block in sequence.
8438 *
8439 * Note that this operation leaves the array unchanged.
8440 *
8441 * arr = [1, 2, 3, 4, 5]
8442 * arr.each {|a| print a -= 10, " "}
8443 * # prints: -9 -8 -7 -6 -5
8444 * #=> [1, 2, 3, 4, 5]
8445 *
8446 * Another sometimes useful iterator is #reverse_each which will iterate over
8447 * the elements in the array in reverse order.
8448 *
8449 * words = %w[first second third fourth fifth sixth]
8450 * str = ""
8451 * words.reverse_each {|word| str += "#{word} "}
8452 * p str #=> "sixth fifth fourth third second first "
8453 *
8454 * The #map method can be used to create a new array based on the original
8455 * array, but with the values modified by the supplied block:
8456 *
8457 * arr.map {|a| 2*a} #=> [2, 4, 6, 8, 10]
8458 * arr #=> [1, 2, 3, 4, 5]
8459 * arr.map! {|a| a**2} #=> [1, 4, 9, 16, 25]
8460 * arr #=> [1, 4, 9, 16, 25]
8461 *
8462 *
8463 * == Selecting Items from an +Array+
8464 *
8465 * Elements can be selected from an array according to criteria defined in a
8466 * block. The selection can happen in a destructive or a non-destructive
8467 * manner. While the destructive operations will modify the array they were
8468 * called on, the non-destructive methods usually return a new array with the
8469 * selected elements, but leave the original array unchanged.
8470 *
8471 * === Non-destructive Selection
8472 *
8473 * arr = [1, 2, 3, 4, 5, 6]
8474 * arr.select {|a| a > 3} #=> [4, 5, 6]
8475 * arr.reject {|a| a < 3} #=> [3, 4, 5, 6]
8476 * arr.drop_while {|a| a < 4} #=> [4, 5, 6]
8477 * arr #=> [1, 2, 3, 4, 5, 6]
8478 *
8479 * === Destructive Selection
8480 *
8481 * #select! and #reject! are the corresponding destructive methods to #select
8482 * and #reject
8483 *
8484 * Similar to #select vs. #reject, #delete_if and #keep_if have the exact
8485 * opposite result when supplied with the same block:
8486 *
8487 * arr.delete_if {|a| a < 4} #=> [4, 5, 6]
8488 * arr #=> [4, 5, 6]
8489 *
8490 * arr = [1, 2, 3, 4, 5, 6]
8491 * arr.keep_if {|a| a < 4} #=> [1, 2, 3]
8492 * arr #=> [1, 2, 3]
8493 *
8494 * == What's Here
8495 *
8496 * First, what's elsewhere. \Class +Array+:
8497 *
8498 * - Inherits from {class Object}[rdoc-ref:Object@What-27s+Here].
8499 * - Includes {module Enumerable}[rdoc-ref:Enumerable@What-27s+Here],
8500 * which provides dozens of additional methods.
8501 *
8502 * Here, class +Array+ provides methods that are useful for:
8503 *
8504 * - {Creating an Array}[rdoc-ref:Array@Methods+for+Creating+an+Array]
8505 * - {Querying}[rdoc-ref:Array@Methods+for+Querying]
8506 * - {Comparing}[rdoc-ref:Array@Methods+for+Comparing]
8507 * - {Fetching}[rdoc-ref:Array@Methods+for+Fetching]
8508 * - {Assigning}[rdoc-ref:Array@Methods+for+Assigning]
8509 * - {Deleting}[rdoc-ref:Array@Methods+for+Deleting]
8510 * - {Combining}[rdoc-ref:Array@Methods+for+Combining]
8511 * - {Iterating}[rdoc-ref:Array@Methods+for+Iterating]
8512 * - {Converting}[rdoc-ref:Array@Methods+for+Converting]
8513 * - {And more....}[rdoc-ref:Array@Other+Methods]
8514 *
8515 * === Methods for Creating an +Array+
8516 *
8517 * - ::[]: Returns a new array populated with given objects.
8518 * - ::new: Returns a new array.
8519 * - ::try_convert: Returns a new array created from a given object.
8520 *
8521 * See also {Creating Arrays}[rdoc-ref:Array@Creating+Arrays].
8522 *
8523 * === Methods for Querying
8524 *
8525 * - #length (aliased as #size): Returns the count of elements.
8526 * - #include?: Returns whether any element <tt>==</tt> a given object.
8527 * - #empty?: Returns whether there are no elements.
8528 * - #all?: Returns whether all elements meet a given criterion.
8529 * - #any?: Returns whether any element meets a given criterion.
8530 * - #none?: Returns whether no element <tt>==</tt> a given object.
8531 * - #one?: Returns whether exactly one element <tt>==</tt> a given object.
8532 * - #count: Returns the count of elements that meet a given criterion.
8533 * - #find_index (aliased as #index): Returns the index of the first element that meets a given criterion.
8534 * - #rindex: Returns the index of the last element that meets a given criterion.
8535 * - #hash: Returns the integer hash code.
8536 *
8537 * === Methods for Comparing
8538 *
8539 * - #<=>: Returns -1, 0, or 1, as +self+ is less than, equal to, or
8540 * greater than a given object.
8541 * - #==: Returns whether each element in +self+ is <tt>==</tt> to the corresponding element
8542 * in a given object.
8543 * - #eql?: Returns whether each element in +self+ is <tt>eql?</tt> to the corresponding
8544 * element in a given object.
8546 * === Methods for Fetching
8547 *
8548 * These methods do not modify +self+.
8549 *
8550 * - #[] (aliased as #slice): Returns consecutive elements as determined by a given argument.
8551 * - #fetch: Returns the element at a given offset.
8552 * - #fetch_values: Returns elements at given offsets.
8553 * - #first: Returns one or more leading elements.
8554 * - #last: Returns one or more trailing elements.
8555 * - #max: Returns one or more maximum-valued elements,
8556 * as determined by <tt>#<=></tt> or a given block.
8557 * - #min: Returns one or more minimum-valued elements,
8558 * as determined by <tt>#<=></tt> or a given block.
8559 * - #minmax: Returns the minimum-valued and maximum-valued elements,
8560 * as determined by <tt>#<=></tt> or a given block.
8561 * - #assoc: Returns the first element that is an array
8562 * whose first element <tt>==</tt> a given object.
8563 * - #rassoc: Returns the first element that is an array
8564 * whose second element <tt>==</tt> a given object.
8565 * - #at: Returns the element at a given offset.
8566 * - #values_at: Returns the elements at given offsets.
8567 * - #dig: Returns the object in nested objects
8568 * that is specified by a given index and additional arguments.
8569 * - #drop: Returns trailing elements as determined by a given index.
8570 * - #take: Returns leading elements as determined by a given index.
8571 * - #drop_while: Returns trailing elements as determined by a given block.
8572 * - #take_while: Returns leading elements as determined by a given block.
8573 * - #sort: Returns all elements in an order determined by <tt>#<=></tt> or a given block.
8574 * - #reverse: Returns all elements in reverse order.
8575 * - #compact: Returns an array containing all non-+nil+ elements.
8576 * - #select (aliased as #filter): Returns an array containing elements selected by a given block.
8577 * - #uniq: Returns an array containing non-duplicate elements.
8578 * - #rotate: Returns all elements with some rotated from one end to the other.
8579 * - #bsearch: Returns an element selected via a binary search
8580 * as determined by a given block.
8581 * - #bsearch_index: Returns the index of an element selected via a binary search
8582 * as determined by a given block.
8583 * - #sample: Returns one or more random elements.
8584 * - #shuffle: Returns elements in a random order.
8585 * - #reject: Returns an array containing elements not rejected by a given block.
8586 *
8587 * === Methods for Assigning
8588 *
8589 * These methods add, replace, or reorder elements in +self+.
8590 *
8591 * - #[]=: Assigns specified elements with a given object.
8592 * - #<<: Appends an element.
8593 * - #push (aliased as #append): Appends elements.
8594 * - #unshift (aliased as #prepend): Prepends leading elements.
8595 * - #insert: Inserts given objects at a given offset; does not replace elements.
8596 * - #concat: Appends all elements from given arrays.
8597 * - #fill: Replaces specified elements with specified objects.
8598 * - #flatten!: Replaces each nested array in +self+ with the elements from that array.
8599 * - #initialize_copy (aliased as #replace): Replaces the content of +self+ with the content of a given array.
8600 * - #reverse!: Replaces +self+ with its elements reversed.
8601 * - #rotate!: Replaces +self+ with its elements rotated.
8602 * - #shuffle!: Replaces +self+ with its elements in random order.
8603 * - #sort!: Replaces +self+ with its elements sorted,
8604 * as determined by <tt>#<=></tt> or a given block.
8605 * - #sort_by!: Replaces +self+ with its elements sorted, as determined by a given block.
8606 *
8607 * === Methods for Deleting
8608 *
8609 * Each of these methods removes elements from +self+:
8610 *
8611 * - #pop: Removes and returns the last element.
8612 * - #shift: Removes and returns the first element.
8613 * - #compact!: Removes all +nil+ elements.
8614 * - #delete: Removes elements equal to a given object.
8615 * - #delete_at: Removes the element at a given offset.
8616 * - #delete_if: Removes elements specified by a given block.
8617 * - #clear: Removes all elements.
8618 * - #keep_if: Removes elements not specified by a given block.
8619 * - #reject!: Removes elements specified by a given block.
8620 * - #select! (aliased as #filter!): Removes elements not specified by a given block.
8621 * - #slice!: Removes and returns a sequence of elements.
8622 * - #uniq!: Removes duplicates.
8623 *
8624 * === Methods for Combining
8625 *
8626 * - #&: Returns an array containing elements found both in +self+ and a given array.
8627 * - #intersection: Returns an array containing elements found both in +self+
8628 * and in each given array.
8629 * - #+: Returns an array containing all elements of +self+ followed by all elements of a given array.
8630 * - #-: Returns an array containing all elements of +self+ that are not found in a given array.
8631 * - #|: Returns an array containing all elements of +self+ and all elements of a given array,
8632 * duplicates removed.
8633 * - #union: Returns an array containing all elements of +self+ and all elements of given arrays,
8634 * duplicates removed.
8635 * - #difference: Returns an array containing all elements of +self+ that are not found
8636 * in any of the given arrays..
8637 * - #product: Returns or yields all combinations of elements from +self+ and given arrays.
8638 * - #reverse: Returns an array containing all elements of +self+ in reverse order.
8639 *
8640 * === Methods for Iterating
8641 *
8642 * - #each: Passes each element to a given block.
8643 * - #reverse_each: Passes each element, in reverse order, to a given block.
8644 * - #each_index: Passes each element index to a given block.
8645 * - #cycle: Calls a given block with each element, then does so again,
8646 * for a specified number of times, or forever.
8647 * - #combination: Calls a given block with combinations of elements of +self+;
8648 * a combination does not use the same element more than once.
8649 * - #permutation: Calls a given block with permutations of elements of +self+;
8650 * a permutation does not use the same element more than once.
8651 * - #repeated_combination: Calls a given block with combinations of elements of +self+;
8652 * a combination may use the same element more than once.
8653 * - #repeated_permutation: Calls a given block with permutations of elements of +self+;
8654 * a permutation may use the same element more than once.
8655 *
8656 * === Methods for Converting
8657 *
8658 * - #collect (aliased as #map): Returns an array containing the block return-value for each element.
8659 * - #collect! (aliased as #map!): Replaces each element with a block return-value.
8660 * - #flatten: Returns an array that is a recursive flattening of +self+.
8661 * - #inspect (aliased as #to_s): Returns a new String containing the elements.
8662 * - #join: Returns a newsString containing the elements joined by the field separator.
8663 * - #to_a: Returns +self+ or a new array containing all elements.
8664 * - #to_ary: Returns +self+.
8665 * - #to_h: Returns a new hash formed from the elements.
8666 * - #transpose: Transposes +self+, which must be an array of arrays.
8667 * - #zip: Returns a new array of arrays containing +self+ and given arrays;
8668 * follow the link for details.
8669 *
8670 * === Other Methods
8671 *
8672 * - #*: Returns one of the following:
8673 *
8674 * - With integer argument +n+, a new array that is the concatenation
8675 * of +n+ copies of +self+.
8676 * - With string argument +field_separator+, a new string that is equivalent to
8677 * <tt>join(field_separator)</tt>.
8678 *
8679 * - #pack: Packs the elements into a binary sequence.
8680 * - #sum: Returns a sum of elements according to either <tt>+</tt> or a given block.
8681 */
8683 void
8685 {
8813 }