| blob | 967659d7fd05c8370852148236394c2fffd44d35 |
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 * 0: RARRAY_SHARED_FLAG (equal to ELTS_SHARED)
46 * The array is shared. The buffer this array points to is owned by
47 * another array (the shared root).
48 * 1: RARRAY_EMBED_FLAG
49 * The array is embedded (its contents follow the header, rather than
50 * being on a separately allocated buffer).
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 }
266 #else
267 #define ary_verify(ary) ((void)0)
268 #endif
270 VALUE *
272 {
273 #if ARRAY_DEBUG
275 #endif
277 }
279 void
281 {
282 #if ARRAY_DEBUG
284 #endif
285 }
287 void
289 {
292 }
293 }
295 static void
297 {
300 });
301 }
305 {
308 }
309 }
311 static void
313 {
317 });
318 }
320 static void
322 {
329 });
330 }
336 }
337 });
338 }
339 }
341 static void
343 {
345 }
349 {
351 }
353 static void
355 {
357 }
359 static void
361 {
363 }
365 static size_t
367 {
373 }
375 void
377 {
389 }
390 }
392 static void
394 {
409 }
412 }
414 }
427 }
428 }
431 }
435 {
443 }
446 }
448 static void
450 {
455 }
458 }
463 }
465 static void
467 {
471 }
472 }
474 static void
476 {
480 }
482 static void
484 {
487 }
490 }
494 }
496 static VALUE
498 {
503 }
505 }
507 static void
509 {
519 }
523 {
526 }
528 void
530 {
544 }
545 else if (ARY_SHARED_ROOT_OCCUPIED(shared_root) && len > ((shared_len = RARRAY_LEN(shared_root))>>1)) {
552 });
555 }
562 }
565 }
567 }
569 void
571 {
574 }
576 static VALUE
578 {
585 }
596 }
598 /* if array is shared, then it is likely it participate in push/shift pattern */
603 }
606 }
607 }
608 }
611 }
614 }
618 }
622 }
624 /*
625 * call-seq:
626 * freeze -> self
627 *
628 * Freezes +self+ (if not already frozen); returns +self+:
629 *
630 * a = []
631 * a.frozen? # => false
632 * a.freeze
633 * a.frozen? # => true
634 *
635 * No further changes may be made to +self+;
636 * raises FrozenError if a change is attempted.
637 *
638 * Related: Kernel#frozen?.
639 */
641 VALUE
643 {
650 }
653 }
655 /* This can be used to take a snapshot of an array (with
656 e.g. rb_ary_replace) and check later whether the array has been
657 modified from the snapshot. The snapshot is cheap, though if
658 something does modify the array it will pay the cost of copying
659 it. If Array#pop or Array#shift has been called, the array will
660 be still shared with the snapshot, but the array length will
661 differ. */
662 VALUE
664 {
670 }
672 }
674 static VALUE
676 {
682 /* Created array is:
683 * FL_SET_EMBED((VALUE)ary);
684 * ARY_SET_EMBED_LEN((VALUE)ary, 0);
685 */
687 }
689 static VALUE
691 {
696 }
698 static VALUE
700 {
703 }
705 static VALUE
707 {
708 VALUE ary;
712 }
715 }
721 }
729 }
732 }
734 VALUE
736 {
738 }
740 VALUE
742 {
744 }
746 VALUE
748 {
750 VALUE ary;
758 }
763 }
765 VALUE
767 {
768 VALUE ary;
774 }
777 }
779 VALUE
781 {
783 }
785 static VALUE
787 {
793 /* Created array is:
794 * FL_SET_EMBED((VALUE)ary);
795 * ARY_SET_EMBED_LEN((VALUE)ary, 0);
796 */
798 }
800 static VALUE
802 {
807 }
809 static VALUE
811 {
812 VALUE ary;
816 }
819 }
825 }
833 }
836 }
838 VALUE
840 {
841 VALUE ary;
847 }
850 }
852 VALUE
854 {
857 }
859 VALUE
861 {
866 }
868 void
870 {
876 }
880 }
883 }
887 }
890 }
891 }
895 static VALUE
897 {
903 }
905 VALUE
907 {
911 // bypass frozen checks
916 }
918 size_t
920 {
923 }
926 }
927 }
929 static VALUE
931 {
936 }
939 }
942 }
947 /* Shared roots cannot be embedded because the reference count
948 * (refcnt) is stored in as.heap.aux.capa. */
960 }
963 }
973 }
974 }
976 static VALUE
978 {
988 }
991 }
992 }
994 VALUE
996 {
998 }
1000 VALUE
1002 {
1004 }
1005 #define to_ary rb_to_array_type
1007 VALUE
1009 {
1011 }
1013 VALUE
1015 {
1017 }
1019 VALUE
1021 {
1023 }
1025 /*
1026 * call-seq:
1027 * Array.try_convert(object) -> object, new_array, or nil
1028 *
1029 * Attempts to return an array, based on the given +object+.
1030 *
1031 * If +object+ is an array, returns +object+.
1032 *
1033 * Otherwise if +object+ responds to <tt>:to_ary</tt>.
1034 * calls <tt>object.to_ary</tt>:
1035 * if the return value is an array or +nil+, returns that value;
1036 * if not, raises TypeError.
1037 *
1038 * Otherwise returns +nil+.
1039 *
1040 * Related: see {Methods for Creating an Array}[rdoc-ref:Array@Methods+for+Creating+an+Array].
1041 */
1043 static VALUE
1045 {
1047 }
1049 /* :nodoc: */
1050 static VALUE
1052 {
1053 VALUE ary;
1060 }
1065 }
1068 }
1071 }
1073 /*
1074 * call-seq:
1075 * Array.new -> new_empty_array
1076 * Array.new(array) -> new_array
1077 * Array.new(size, default_value = nil) -> new_array
1078 * Array.new(size = 0) {|index| ... } -> new_array
1079 *
1080 * Returns a new array.
1081 *
1082 * With no block and no argument given, returns a new empty array:
1083 *
1084 * Array.new # => []
1085 *
1086 * With no block and array argument given, returns a new array with the same elements:
1087 *
1088 * Array.new([:foo, 'bar', 2]) # => [:foo, "bar", 2]
1089 *
1090 * With no block and integer argument given, returns a new array containing
1091 * that many instances of the given +default_value+:
1092 *
1093 * Array.new(0) # => []
1094 * Array.new(3) # => [nil, nil, nil]
1095 * Array.new(2, 3) # => [3, 3]
1096 *
1097 * With a block given, returns an array of the given +size+;
1098 * calls the block with each +index+ in the range <tt>(0...size)</tt>;
1099 * the element at that +index+ in the returned array is the blocks return value:
1100 *
1101 * Array.new(3) {|index| "Element #{index}" } # => ["Element 0", "Element 1", "Element 2"]
1102 *
1103 * A common pitfall for new Rubyists is providing an expression as +default_value+:
1104 *
1105 * array = Array.new(2, {})
1106 * array # => [{}, {}]
1107 * array[0][:a] = 1
1108 * array # => [{a: 1}, {a: 1}], as array[0] and array[1] are same object
1109 *
1110 * If you want the elements of the array to be distinct, you should pass a block:
1111 *
1112 * array = Array.new(2) { {} }
1113 * array # => [{}, {}]
1114 * array[0][:a] = 1
1115 * array # => [{a: 1}, {}], as array[0] and array[1] are different objects
1116 *
1117 * Raises TypeError if the first argument is not either an array
1118 * or an {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects]).
1119 * Raises ArgumentError if the first argument is a negative integer.
1120 *
1121 * Related: see {Methods for Creating an Array}[rdoc-ref:Array@Methods+for+Creating+an+Array].
1122 */
1124 static VALUE
1126 {
1137 }
1139 }
1146 }
1147 }
1150 /* NUM2LONG() may call size.to_int, ary can be frozen, modified, etc */
1153 }
1156 }
1157 /* recheck after argument conversion */
1165 }
1169 }
1170 }
1174 }
1176 }
1178 /*
1179 * Returns a new array, populated with the given objects:
1180 *
1181 * Array[1, 'a', /^A/] # => [1, "a", /^A/]
1182 * Array[] # => []
1183 * Array.[](1, 'a', /^A/) # => [1, "a", /^A/]
1184 *
1185 * Related: see {Methods for Creating an Array}[rdoc-ref:Array@Methods+for+Creating+an+Array].
1186 */
1188 static VALUE
1190 {
1195 }
1198 }
1200 void
1202 {
1210 }
1211 }
1214 }
1219 }
1222 }
1226 }
1228 }
1230 static VALUE
1232 {
1243 }
1247 /* The ary_make_shared call may allocate, which can trigger a GC
1248 * compaction. This can cause the array to be embedded because it has
1249 * a length of 0. */
1260 }
1264 }
1266 static VALUE
1268 {
1284 }
1287 }
1303 }
1305 }
1313 }
1314 });
1316 }
1319 }
1321 static VALUE
1323 {
1325 }
1327 enum ary_take_pos_flags
1328 {
1331 };
1333 static VALUE
1335 {
1341 }
1344 }
1347 }
1349 }
1351 static VALUE
1353 {
1355 /* the case optional argument is omitted should be handled in
1356 * callers of this function. if another arity case is added,
1357 * this arity check needs to rewrite. */
1360 }
1362 /*
1363 * call-seq:
1364 * self << object -> self
1365 *
1366 * Appends +object+ as the last element in +self+; returns +self+:
1367 *
1368 * [:foo, 'bar', 2] << :baz # => [:foo, "bar", 2, :baz]
1369 *
1370 * Appends +object+ as a single element, even if it is another array:
1371 *
1372 * [:foo, 'bar', 2] << [3, 4] # => [:foo, "bar", 2, [3, 4]]
1373 *
1374 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
1375 */
1377 VALUE
1379 {
1384 });
1388 }
1390 VALUE
1392 {
1398 }
1400 /*
1401 * call-seq:
1402 * push(*objects) -> self
1403 * append(*objects) -> self
1404 *
1405 * Appends each argument in +objects+ to +self+; returns +self+:
1406 *
1407 * a = [:foo, 'bar', 2] # => [:foo, "bar", 2]
1408 * a.push(:baz, :bat) # => [:foo, "bar", 2, :baz, :bat]
1409 *
1410 * Appends each argument as a single element, even if it is another array:
1411 *
1412 * a = [:foo, 'bar', 2] # => [:foo, "bar", 2]
1413 a.push([:baz, :bat], [:bam, :bad]) # => [:foo, "bar", 2, [:baz, :bat], [:bam, :bad]]
1414 *
1415 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
1416 */
1418 static VALUE
1420 {
1422 }
1424 VALUE
1426 {
1434 {
1436 }
1441 }
1443 /*
1444 * call-seq:
1445 * pop -> object or nil
1446 * pop(count) -> new_array
1447 *
1448 * Removes and returns trailing elements of +self+.
1449 *
1450 * With no argument given, removes and returns the last element, if available;
1451 * otherwise returns +nil+:
1452 *
1453 * a = [:foo, 'bar', 2]
1454 * a.pop # => 2
1455 * a # => [:foo, "bar"]
1456 * [].pop # => nil
1457 *
1458 * With non-negative integer argument +count+ given,
1459 * returns a new array containing the trailing +count+ elements of +self+, as available:
1460 *
1461 * a = [:foo, 'bar', 2]
1462 * a.pop(2) # => ["bar", 2]
1463 * a # => [:foo]
1464 *
1465 * a = [:foo, 'bar', 2]
1466 * a.pop(50) # => [:foo, "bar", 2]
1467 * a # => []
1468 *
1469 * Related: Array#push;
1470 * see also {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
1471 */
1473 static VALUE
1475 {
1476 VALUE result;
1480 }
1487 }
1489 VALUE
1491 {
1492 VALUE top;
1498 }
1505 }
1507 /*
1508 * call-seq:
1509 * shift -> object or nil
1510 * shift(count) -> new_array or nil
1511 *
1512 * Removes and returns leading elements from +self+.
1513 *
1514 * With no argument, removes and returns one element, if available,
1515 * or +nil+ otherwise:
1516 *
1517 * a = [0, 1, 2, 3]
1518 * a.shift # => 0
1519 * a # => [1, 2, 3]
1520 * [].shift # => nil
1521 *
1522 * With non-negative numeric argument +count+ given,
1523 * removes and returns the first +count+ elements:
1524 *
1525 * a = [0, 1, 2, 3]
1526 * a.shift(2) # => [0, 1]
1527 * a # => [2, 3]
1528 * a.shift(1.1) # => [2]
1529 * a # => [3]
1530 * a.shift(0) # => []
1531 * a # => [3]
1532 *
1533 * If +count+ is large,
1534 * removes and returns all elements:
1535 *
1536 * a = [0, 1, 2, 3]
1537 * a.shift(50) # => [0, 1, 2, 3]
1538 * a # => []
1539 *
1540 * If +self+ is empty, returns a new empty array.
1541 *
1542 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
1543 */
1545 static VALUE
1547 {
1548 VALUE result;
1553 }
1561 }
1563 VALUE
1565 {
1568 }
1580 }
1584 }
1587 }
1594 }
1596 static VALUE
1597 make_room_for_unshift(VALUE ary, const VALUE *head, VALUE *sharedp, int argc, long capa, long len)
1598 {
1605 }
1611 }
1613 static VALUE
1615 {
1625 }
1627 /* use shared array for big "queues" */
1631 /* make a room for unshifted items */
1637 }
1639 /* sliding items */
1642 });
1646 }
1647 }
1649 static VALUE
1651 {
1657 }
1660 }
1667 }
1670 }
1677 }
1678 }
1679 }
1681 /*
1682 * call-seq:
1683 * unshift(*objects) -> self
1684 * prepend(*objects) -> self
1685 *
1686 * Prepends the given +objects+ to +self+:
1687 *
1688 * a = [:foo, 'bar', 2]
1689 * a.unshift(:bam, :bat) # => [:bam, :bat, :foo, "bar", 2]
1690 *
1691 * Related: Array#shift;
1692 * see also {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
1693 */
1695 VALUE
1697 {
1699 VALUE target_ary;
1704 }
1710 }
1712 VALUE
1714 {
1716 }
1718 /* faster version - use this if you don't need to treat negative offset */
1721 {
1726 }
1728 }
1730 VALUE
1732 {
1734 }
1736 VALUE
1738 {
1739 VALUE klass;
1747 }
1754 else
1756 }
1758 VALUE
1760 {
1762 }
1766 /*
1767 * call-seq:
1768 * self[index] -> object or nil
1769 * self[start, length] -> object or nil
1770 * self[range] -> object or nil
1771 * self[aseq] -> object or nil
1772 * slice(index) -> object or nil
1773 * slice(start, length) -> object or nil
1774 * slice(range) -> object or nil
1775 * slice(aseq) -> object or nil
1776 *
1777 * Returns elements from +self+; does not modify +self+.
1778 *
1779 * In brief:
1780 *
1781 * a = [:foo, 'bar', 2]
1782 *
1783 * # Single argument index: returns one element.
1784 * a[0] # => :foo # Zero-based index.
1785 * a[-1] # => 2 # Negative index counts backwards from end.
1786 *
1787 * # Arguments start and length: returns an array.
1788 * a[1, 2] # => ["bar", 2]
1789 * a[-2, 2] # => ["bar", 2] # Negative start counts backwards from end.
1790 *
1791 * # Single argument range: returns an array.
1792 * a[0..1] # => [:foo, "bar"]
1793 * a[0..-2] # => [:foo, "bar"] # Negative range-begin counts backwards from end.
1794 * a[-2..2] # => ["bar", 2] # Negative range-end counts backwards from end.
1795 *
1796 * When a single integer argument +index+ is given, returns the element at offset +index+:
1797 *
1798 * a = [:foo, 'bar', 2]
1799 * a[0] # => :foo
1800 * a[2] # => 2
1801 * a # => [:foo, "bar", 2]
1802 *
1803 * If +index+ is negative, counts backwards from the end of +self+:
1804 *
1805 * a = [:foo, 'bar', 2]
1806 * a[-1] # => 2
1807 * a[-2] # => "bar"
1808 *
1809 * If +index+ is out of range, returns +nil+.
1810 *
1811 * When two Integer arguments +start+ and +length+ are given,
1812 * returns a new +Array+ of size +length+ containing successive elements beginning at offset +start+:
1813 *
1814 * a = [:foo, 'bar', 2]
1815 * a[0, 2] # => [:foo, "bar"]
1816 * a[1, 2] # => ["bar", 2]
1817 *
1818 * If <tt>start + length</tt> is greater than <tt>self.length</tt>,
1819 * returns all elements from offset +start+ to the end:
1820 *
1821 * a = [:foo, 'bar', 2]
1822 * a[0, 4] # => [:foo, "bar", 2]
1823 * a[1, 3] # => ["bar", 2]
1824 * a[2, 2] # => [2]
1825 *
1826 * If <tt>start == self.size</tt> and <tt>length >= 0</tt>,
1827 * returns a new empty +Array+.
1828 *
1829 * If +length+ is negative, returns +nil+.
1830 *
1831 * When a single Range argument +range+ is given,
1832 * treats <tt>range.min</tt> as +start+ above
1833 * and <tt>range.size</tt> as +length+ above:
1834 *
1835 * a = [:foo, 'bar', 2]
1836 * a[0..1] # => [:foo, "bar"]
1837 * a[1..2] # => ["bar", 2]
1838 *
1839 * Special case: If <tt>range.start == a.size</tt>, returns a new empty +Array+.
1840 *
1841 * If <tt>range.end</tt> is negative, calculates the end index from the end:
1842 *
1843 * a = [:foo, 'bar', 2]
1844 * a[0..-1] # => [:foo, "bar", 2]
1845 * a[0..-2] # => [:foo, "bar"]
1846 * a[0..-3] # => [:foo]
1847 *
1848 * If <tt>range.start</tt> is negative, calculates the start index from the end:
1849 *
1850 * a = [:foo, 'bar', 2]
1851 * a[-1..2] # => [2]
1852 * a[-2..2] # => ["bar", 2]
1853 * a[-3..2] # => [:foo, "bar", 2]
1854 *
1855 * If <tt>range.start</tt> is larger than the array size, returns +nil+.
1856 *
1857 * a = [:foo, 'bar', 2]
1858 * a[4..1] # => nil
1859 * a[4..0] # => nil
1860 * a[4..-1] # => nil
1861 *
1862 * When a single Enumerator::ArithmeticSequence argument +aseq+ is given,
1863 * returns an +Array+ of elements corresponding to the indexes produced by
1864 * the sequence.
1865 *
1866 * a = ['--', 'data1', '--', 'data2', '--', 'data3']
1867 * a[(1..).step(2)] # => ["data1", "data2", "data3"]
1868 *
1869 * Unlike slicing with range, if the start or the end of the arithmetic sequence
1870 * is larger than array size, throws RangeError.
1871 *
1872 * a = ['--', 'data1', '--', 'data2', '--', 'data3']
1873 * a[(1..11).step(2)]
1874 * # RangeError (((1..11).step(2)) out of range)
1875 * a[(7..).step(2)]
1876 * # RangeError (((7..).step(2)) out of range)
1877 *
1878 * If given a single argument, and its type is not one of the listed, tries to
1879 * convert it to Integer, and raises if it is impossible:
1880 *
1881 * a = [:foo, 'bar', 2]
1882 * # Raises TypeError (no implicit conversion of Symbol into Integer):
1883 * a[:foo]
1884 *
1885 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
1886 */
1888 VALUE
1890 {
1894 }
1896 }
1898 static VALUE
1900 {
1905 }
1907 }
1909 VALUE
1911 {
1914 /* special case - speeding up */
1917 }
1918 /* check if idx is Range or ArithmeticSequence */
1926 }
1929 }
1931 /*
1932 * call-seq:
1933 * at(index) -> object or nil
1934 *
1935 * Returns the element of +self+ specified by the given +index+
1936 * or +nil+ if there is no such element;
1937 * +index+ must be an
1938 * {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects].
1939 *
1940 * For non-negative +index+, returns the element of +self+ at offset +index+:
1941 *
1942 * a = [:foo, 'bar', 2]
1943 * a.at(0) # => :foo
1944 * a.at(2) # => 2
1945 * a.at(2.0) # => 2
1946 *
1947 * For negative +index+, counts backwards from the end of +self+:
1948 *
1949 * a.at(-2) # => "bar"
1950 *
1951 * Related: Array#[];
1952 * see also {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
1953 */
1955 VALUE
1957 {
1959 }
1961 #if 0
1962 static VALUE
1964 {
1968 }
1971 }
1972 }
1973 #endif
1975 static VALUE
1977 {
1979 }
1981 static VALUE
1983 {
1986 }
1988 VALUE
1990 {
1993 }
1996 }
1997 }
1999 /*
2000 * call-seq:
2001 * fetch(index) -> element
2002 * fetch(index, default_value) -> element or default_value
2003 * fetch(index) {|index| ... } -> element or block_return_value
2004 *
2005 * Returns the element of +self+ at offset +index+ if +index+ is in range; +index+ must be an
2006 * {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects].
2007 *
2008 * With the single argument +index+ and no block,
2009 * returns the element at offset +index+:
2010 *
2011 * a = [:foo, 'bar', 2]
2012 * a.fetch(1) # => "bar"
2013 * a.fetch(1.1) # => "bar"
2014 *
2015 * If +index+ is negative, counts from the end of the array:
2016 *
2017 * a = [:foo, 'bar', 2]
2018 * a.fetch(-1) # => 2
2019 * a.fetch(-2) # => "bar"
2020 *
2021 * With arguments +index+ and +default_value+ (which may be any object) and no block,
2022 * returns +default_value+ if +index+ is out-of-range:
2023 *
2024 * a = [:foo, 'bar', 2]
2025 * a.fetch(1, nil) # => "bar"
2026 * a.fetch(3, :foo) # => :foo
2027 *
2028 * With argument +index+ and a block,
2029 * returns the element at offset +index+ if index is in range
2030 * (and the block is not called); otherwise calls the block with index and returns its return value:
2031 *
2032 * a = [:foo, 'bar', 2]
2033 * a.fetch(1) {|index| raise 'Cannot happen' } # => "bar"
2034 * a.fetch(50) {|index| "Value for #{index}" } # => "Value for 50"
2035 *
2036 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
2037 */
2039 static VALUE
2041 {
2050 }
2055 }
2061 }
2063 }
2065 }
2067 /*
2068 * call-seq:
2069 * find_index(object) -> integer or nil
2070 * find_index {|element| ... } -> integer or nil
2071 * find_index -> new_enumerator
2072 * index(object) -> integer or nil
2073 * index {|element| ... } -> integer or nil
2074 * index -> new_enumerator
2075 *
2076 * Returns the zero-based integer index of a specified element, or +nil+.
2077 *
2078 * With only argument +object+ given,
2079 * returns the index of the first element +element+
2080 * for which <tt>object == element</tt>:
2081 *
2082 * a = [:foo, 'bar', 2, 'bar']
2083 * a.index('bar') # => 1
2084 *
2085 * Returns +nil+ if no such element found.
2086 *
2087 * With only a block given,
2088 * calls the block with each successive element;
2089 * returns the index of the first element for which the block returns a truthy value:
2090 *
2091 * a = [:foo, 'bar', 2, 'bar']
2092 * a.index {|element| element == 'bar' } # => 1
2093 *
2094 * Returns +nil+ if the block never returns a truthy value.
2095 *
2096 * With neither an argument nor a block given, returns a new Enumerator.
2097 *
2098 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
2099 */
2101 static VALUE
2103 {
2104 VALUE val;
2112 }
2113 }
2115 }
2124 }
2125 }
2127 }
2129 /*
2130 * call-seq:
2131 * rindex(object) -> integer or nil
2132 * rindex {|element| ... } -> integer or nil
2133 * rindex -> new_enumerator
2134 *
2135 * Returns the index of the last element for which <tt>object == element</tt>.
2136 *
2137 * With argument +object+ given, returns the index of the last such element found:
2138 *
2139 * a = [:foo, 'bar', 2, 'bar']
2140 * a.rindex('bar') # => 3
2141 *
2142 * Returns +nil+ if no such object found.
2143 *
2144 * With a block given, calls the block with each successive element;
2145 * returns the index of the last element for which the block returns a truthy value:
2146 *
2147 * a = [:foo, 'bar', 2, 'bar']
2148 * a.rindex {|element| element == 'bar' } # => 3
2149 *
2150 * Returns +nil+ if the block never returns a truthy value.
2151 *
2152 * When neither an argument nor a block is given, returns a new Enumerator.
2153 *
2154 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
2155 */
2157 static VALUE
2159 {
2160 VALUE val;
2170 }
2171 }
2173 }
2182 }
2185 }
2186 }
2188 }
2190 VALUE
2192 {
2197 }
2199 static void
2201 {
2212 }
2213 }
2216 }
2218 {
2221 }
2224 VALUE target_ary;
2227 }
2234 }
2236 }
2242 }
2247 }
2254 }
2258 }
2260 /* In this case, we're copying from a region in this array, so
2261 * we don't need to fire the write barrier. */
2263 }
2265 /* do not use RARRAY_PTR() because it can causes GC.
2266 * ary can contain T_NONE object because it is not cleared.
2267 */
2270 }
2271 }
2272 }
2274 void
2276 {
2282 }
2285 }
2287 }
2289 VALUE
2291 {
2299 }
2303 }
2306 }
2309 }
2321 }
2326 }
2328 }
2331 }
2333 static VALUE
2335 {
2338 }
2340 static VALUE
2342 {
2347 }
2349 /*
2350 * call-seq:
2351 * self[index] = object -> object
2352 * self[start, length] = object -> object
2353 * self[range] = object -> object
2354 *
2355 * Assigns elements in +self+, based on the given +object+; returns +object+.
2356 *
2357 * In brief:
2358 *
2359 * a_orig = [:foo, 'bar', 2]
2360 *
2361 * # With argument index.
2362 * a = a_orig.dup
2363 * a[0] = 'foo' # => "foo"
2364 * a # => ["foo", "bar", 2]
2365 * a = a_orig.dup
2366 * a[7] = 'foo' # => "foo"
2367 * a # => [:foo, "bar", 2, nil, nil, nil, nil, "foo"]
2368 *
2369 * # With arguments start and length.
2370 * a = a_orig.dup
2371 * a[0, 2] = 'foo' # => "foo"
2372 * a # => ["foo", 2]
2373 * a = a_orig.dup
2374 * a[6, 50] = 'foo' # => "foo"
2375 * a # => [:foo, "bar", 2, nil, nil, nil, "foo"]
2376 *
2377 * # With argument range.
2378 * a = a_orig.dup
2379 * a[0..1] = 'foo' # => "foo"
2380 * a # => ["foo", 2]
2381 * a = a_orig.dup
2382 * a[6..50] = 'foo' # => "foo"
2383 * a # => [:foo, "bar", 2, nil, nil, nil, "foo"]
2384 *
2385 * When Integer argument +index+ is given, assigns +object+ to an element in +self+.
2386 *
2387 * If +index+ is non-negative, assigns +object+ the element at offset +index+:
2388 *
2389 * a = [:foo, 'bar', 2]
2390 * a[0] = 'foo' # => "foo"
2391 * a # => ["foo", "bar", 2]
2392 *
2393 * If +index+ is greater than <tt>self.length</tt>, extends the array:
2394 *
2395 * a = [:foo, 'bar', 2]
2396 * a[7] = 'foo' # => "foo"
2397 * a # => [:foo, "bar", 2, nil, nil, nil, nil, "foo"]
2398 *
2399 * If +index+ is negative, counts backwards from the end of the array:
2400 *
2401 * a = [:foo, 'bar', 2]
2402 * a[-1] = 'two' # => "two"
2403 * a # => [:foo, "bar", "two"]
2404 *
2405 * When Integer arguments +start+ and +length+ are given and +object+ is not an +Array+,
2406 * removes <tt>length - 1</tt> elements beginning at offset +start+,
2407 * and assigns +object+ at offset +start+:
2408 *
2409 * a = [:foo, 'bar', 2]
2410 * a[0, 2] = 'foo' # => "foo"
2411 * a # => ["foo", 2]
2412 *
2413 * If +start+ is negative, counts backwards from the end of the array:
2414 *
2415 * a = [:foo, 'bar', 2]
2416 * a[-2, 2] = 'foo' # => "foo"
2417 * a # => [:foo, "foo"]
2418 *
2419 * If +start+ is non-negative and outside the array (<tt> >= self.size</tt>),
2420 * extends the array with +nil+, assigns +object+ at offset +start+,
2421 * and ignores +length+:
2422 *
2423 * a = [:foo, 'bar', 2]
2424 * a[6, 50] = 'foo' # => "foo"
2425 * a # => [:foo, "bar", 2, nil, nil, nil, "foo"]
2426 *
2427 * If +length+ is zero, shifts elements at and following offset +start+
2428 * and assigns +object+ at offset +start+:
2429 *
2430 * a = [:foo, 'bar', 2]
2431 * a[1, 0] = 'foo' # => "foo"
2432 * a # => [:foo, "foo", "bar", 2]
2433 *
2434 * If +length+ is too large for the existing array, does not extend the array:
2435 *
2436 * a = [:foo, 'bar', 2]
2437 * a[1, 5] = 'foo' # => "foo"
2438 * a # => [:foo, "foo"]
2439 *
2440 * When Range argument +range+ is given and +object+ is not an +Array+,
2441 * removes <tt>length - 1</tt> elements beginning at offset +start+,
2442 * and assigns +object+ at offset +start+:
2443 *
2444 * a = [:foo, 'bar', 2]
2445 * a[0..1] = 'foo' # => "foo"
2446 * a # => ["foo", 2]
2447 *
2448 * if <tt>range.begin</tt> is negative, counts backwards from the end of the array:
2449 *
2450 * a = [:foo, 'bar', 2]
2451 * a[-2..2] = 'foo' # => "foo"
2452 * a # => [:foo, "foo"]
2453 *
2454 * If the array length is less than <tt>range.begin</tt>,
2455 * extends the array with +nil+, assigns +object+ at offset <tt>range.begin</tt>,
2456 * and ignores +length+:
2457 *
2458 * a = [:foo, 'bar', 2]
2459 * a[6..50] = 'foo' # => "foo"
2460 * a # => [:foo, "bar", 2, nil, nil, nil, "foo"]
2461 *
2462 * If <tt>range.end</tt> is zero, shifts elements at and following offset +start+
2463 * and assigns +object+ at offset +start+:
2464 *
2465 * a = [:foo, 'bar', 2]
2466 * a[1..0] = 'foo' # => "foo"
2467 * a # => [:foo, "foo", "bar", 2]
2468 *
2469 * If <tt>range.end</tt> is negative, assigns +object+ at offset +start+,
2470 * retains <tt>range.end.abs -1</tt> elements past that, and removes those beyond:
2471 *
2472 * a = [:foo, 'bar', 2]
2473 * a[1..-1] = 'foo' # => "foo"
2474 * a # => [:foo, "foo"]
2475 * a = [:foo, 'bar', 2]
2476 * a[1..-2] = 'foo' # => "foo"
2477 * a # => [:foo, "foo", 2]
2478 * a = [:foo, 'bar', 2]
2479 * a[1..-3] = 'foo' # => "foo"
2480 * a # => [:foo, "foo", "bar", 2]
2481 * a = [:foo, 'bar', 2]
2482 *
2483 * If <tt>range.end</tt> is too large for the existing array,
2484 * replaces array elements, but does not extend the array with +nil+ values:
2485 *
2486 * a = [:foo, 'bar', 2]
2487 * a[1..5] = 'foo' # => "foo"
2488 * a # => [:foo, "foo"]
2489 *
2490 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
2491 */
2493 static VALUE
2495 {
2504 }
2508 }
2510 /* check if idx is Range */
2512 }
2516 }
2518 /*
2519 * call-seq:
2520 * insert(index, *objects) -> self
2521 *
2522 * Inserts the given +objects+ as elements of +self+;
2523 * returns +self+.
2524 *
2525 * When +index+ is non-negative, inserts +objects+
2526 * _before_ the element at offset +index+:
2527 *
2528 * a = ['a', 'b', 'c'] # => ["a", "b", "c"]
2529 * a.insert(1, :x, :y, :z) # => ["a", :x, :y, :z, "b", "c"]
2530 *
2531 * Extends the array if +index+ is beyond the array (<tt>index >= self.size</tt>):
2532 *
2533 * a = ['a', 'b', 'c'] # => ["a", "b", "c"]
2534 * a.insert(5, :x, :y, :z) # => ["a", "b", "c", nil, nil, :x, :y, :z]
2535 *
2536 * When +index+ is negative, inserts +objects+
2537 * _after_ the element at offset <tt>index + self.size</tt>:
2538 *
2539 * a = ['a', 'b', 'c'] # => ["a", "b", "c"]
2540 * a.insert(-2, :x, :y, :z) # => ["a", "b", :x, :y, :z, "c"]
2541 *
2542 * With no +objects+ given, does nothing:
2543 *
2544 * a = ['a', 'b', 'c'] # => ["a", "b", "c"]
2545 * a.insert(1) # => ["a", "b", "c"]
2546 * a.insert(50) # => ["a", "b", "c"]
2547 * a.insert(-50) # => ["a", "b", "c"]
2548 *
2549 * Raises IndexError if +objects+ are given and +index+ is negative and out of range.
2550 *
2551 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
2552 */
2554 static VALUE
2556 {
2565 }
2571 }
2572 pos++;
2573 }
2576 }
2578 static VALUE
2581 static VALUE
2583 {
2585 }
2587 // Primitive to avoid a race condition in Array#each.
2588 // Return `true` and write `value` and `index` if the element exists.
2589 static VALUE
2591 {
2595 }
2599 }
2601 /*
2602 * call-seq:
2603 * each {|element| ... } -> self
2604 * each -> new_enumerator
2605 *
2606 * With a block given, iterates over the elements of +self+,
2607 * passing each element to the block;
2608 * returns +self+:
2609 *
2610 * a = [:foo, 'bar', 2]
2611 * a.each {|element| puts "#{element.class} #{element}" }
2612 *
2613 * Output:
2614 *
2615 * Symbol foo
2616 * String bar
2617 * Integer 2
2618 *
2619 * Allows the array to be modified during iteration:
2620 *
2621 * a = [:foo, 'bar', 2]
2622 * a.each {|element| puts element; a.clear if element.to_s.start_with?('b') }
2623 *
2624 * Output:
2625 *
2626 * foo
2627 * bar
2628 *
2629 * With no block given, returns a new Enumerator.
2630 *
2631 * Related: see {Methods for Iterating}[rdoc-ref:Array@Methods+for+Iterating].
2632 */
2634 VALUE
2636 {
2642 }
2644 }
2646 /*
2647 * call-seq:
2648 * each_index {|index| ... } -> self
2649 * each_index -> new_enumerator
2650 *
2651 * With a block given, iterates over the elements of +self+,
2652 * passing each <i>array index</i> to the block;
2653 * returns +self+:
2654 *
2655 * a = [:foo, 'bar', 2]
2656 * a.each_index {|index| puts "#{index} #{a[index]}" }
2657 *
2658 * Output:
2659 *
2660 * 0 foo
2661 * 1 bar
2662 * 2 2
2663 *
2664 * Allows the array to be modified during iteration:
2665 *
2666 * a = [:foo, 'bar', 2]
2667 * a.each_index {|index| puts index; a.clear if index > 0 }
2668 * a # => []
2669 *
2670 * Output:
2671 *
2672 * 0
2673 * 1
2674 *
2675 * With no block given, returns a new Enumerator.
2676 *
2677 * Related: see {Methods for Iterating}[rdoc-ref:Array@Methods+for+Iterating].
2678 */
2680 static VALUE
2682 {
2688 }
2690 }
2692 /*
2693 * call-seq:
2694 * reverse_each {|element| ... } -> self
2695 * reverse_each -> Enumerator
2696 *
2697 * When a block given, iterates backwards over the elements of +self+,
2698 * passing, in reverse order, each element to the block;
2699 * returns +self+:
2700 *
2701 * a = []
2702 * [0, 1, 2].reverse_each {|element| a.push(element) }
2703 * a # => [2, 1, 0]
2704 *
2705 * Allows the array to be modified during iteration:
2706 *
2707 * a = ['a', 'b', 'c']
2708 * a.reverse_each {|element| a.clear if element.start_with?('b') }
2709 * a # => []
2710 *
2711 * When no block given, returns a new Enumerator.
2712 *
2713 * Related: see {Methods for Iterating}[rdoc-ref:Array@Methods+for+Iterating].
2714 */
2716 static VALUE
2718 {
2729 }
2730 }
2732 }
2734 /*
2735 * call-seq:
2736 * length -> integer
2737 * size -> integer
2738 *
2739 * Returns the count of elements in +self+:
2740 *
2741 * [0, 1, 2].length # => 3
2742 * [].length # => 0
2743 *
2744 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
2745 */
2747 static VALUE
2749 {
2752 }
2754 /*
2755 * call-seq:
2756 * array.empty? -> true or false
2757 *
2758 * Returns +true+ if the count of elements in +self+ is zero,
2759 * +false+ otherwise.
2760 *
2761 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
2762 */
2764 static VALUE
2766 {
2768 }
2770 VALUE
2772 {
2781 }
2783 VALUE
2785 {
2787 }
2793 static VALUE
2795 {
2804 }
2807 }
2809 }
2811 static long
2813 {
2815 VALUE val;
2824 }
2826 }
2828 static void
2830 {
2835 }
2836 }
2838 static void
2840 {
2843 }
2853 }
2854 }
2856 static void
2858 {
2868 }
2871 }
2874 }
2877 }
2880 }
2881 }
2882 }
2884 VALUE
2886 {
2895 }
2910 }
2913 }
2921 }
2923 /*
2924 * call-seq:
2925 * array.join(separator = $,) -> new_string
2926 *
2927 * Returns the new string formed by joining the converted elements of +self+;
2928 * for each element +element+:
2929 *
2930 * - Converts recursively using <tt>element.join(separator)</tt>
2931 * if +element+ is a <tt>kind_of?(Array)</tt>.
2932 * - Otherwise, converts using <tt>element.to_s</tt>.
2933 *
2934 * With no argument given, joins using the output field separator, <tt>$,</tt>:
2935 *
2936 * a = [:foo, 'bar', 2]
2937 * $, # => nil
2938 * a.join # => "foobar2"
2939 *
2940 * With string argument +separator+ given, joins using that separator:
2941 *
2942 * a = [:foo, 'bar', 2]
2943 * a.join("\n") # => "foo\nbar\n2"
2944 *
2945 * Joins recursively for nested arrays:
2946 *
2947 * a = [:foo, [:bar, [:baz, :bat]]]
2948 * a.join # => "foobarbazbat"
2949 *
2950 * Related: see {Methods for Converting}[rdoc-ref:Array@Methods+for+Converting].
2951 */
2952 static VALUE
2954 {
2955 VALUE sep;
2961 }
2962 }
2965 }
2967 static VALUE
2969 {
2980 }
2983 }
2985 /*
2986 * call-seq:
2987 * inspect -> new_string
2988 * to_s -> new_string
2989 *
2990 * Returns the new string formed by calling method <tt>#inspect</tt>
2991 * on each array element:
2992 *
2993 * a = [:foo, 'bar', 2]
2994 * a.inspect # => "[:foo, \"bar\", 2]"
2995 *
2996 * Related: see {Methods for Converting}[rdoc-ref:Array@Methods+for+Converting].
2997 */
2999 static VALUE
3001 {
3004 }
3006 VALUE
3008 {
3010 }
3012 /*
3013 * call-seq:
3014 * to_a -> self or new_array
3015 *
3016 * When +self+ is an instance of +Array+, returns +self+.
3017 *
3018 * Otherwise, returns a new array containing the elements of +self+:
3019 *
3020 * class MyArray < Array; end
3021 * my_a = MyArray.new(['foo', 'bar', 'two'])
3022 * a = my_a.to_a
3023 * a # => ["foo", "bar", "two"]
3024 * a.class # => Array # Not MyArray.
3025 *
3026 * Related: see {Methods for Converting}[rdoc-ref:Array@Methods+for+Converting].
3027 */
3029 static VALUE
3031 {
3036 }
3038 }
3040 /*
3041 * call-seq:
3042 * to_h -> new_hash
3043 * to_h {|element| ... } -> new_hash
3044 *
3045 * Returns a new hash formed from +self+.
3046 *
3047 * With no block given, each element of +self+ must be a 2-element sub-array;
3048 * forms each sub-array into a key-value pair in the new hash:
3049 *
3050 * a = [['foo', 'zero'], ['bar', 'one'], ['baz', 'two']]
3051 * a.to_h # => {"foo"=>"zero", "bar"=>"one", "baz"=>"two"}
3052 * [].to_h # => {}
3053 *
3054 * With a block given, the block must return a 2-element array;
3055 * calls the block with each element of +self+;
3056 * forms each returned array into a key-value pair in the returned hash:
3057 *
3058 * a = ['foo', :bar, 1, [2, 3], {baz: 4}]
3059 * a.to_h {|element| [element, element.class] }
3060 * # => {"foo"=>String, :bar=>Symbol, 1=>Integer, [2, 3]=>Array, {:baz=>4}=>Hash}
3061 *
3062 * Related: see {Methods for Converting}[rdoc-ref:Array@Methods+for+Converting].
3063 */
3065 static VALUE
3067 {
3079 }
3083 }
3085 }
3087 }
3089 /*
3090 * call-seq:
3091 * array.to_ary -> self
3092 *
3093 * Returns +self+.
3094 */
3096 static VALUE
3098 {
3100 }
3102 static void
3104 {
3109 }
3110 }
3112 VALUE
3114 {
3124 }
3126 }
3128 /*
3129 * call-seq:
3130 * reverse! -> self
3131 *
3132 * Reverses the order of the elements of +self+;
3133 * returns +self+:
3134 *
3135 * a = [0, 1, 2]
3136 * a.reverse! # => [2, 1, 0]
3137 * a # => [2, 1, 0]
3138 *
3139 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
3140 */
3142 static VALUE
3144 {
3146 }
3148 /*
3149 * call-seq:
3150 * reverse -> new_array
3151 *
3152 * Returns a new array containing the elements of +self+ in reverse order:
3153 *
3154 * [0, 1, 2].reverse # => [2, 1, 0]
3155 *
3156 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
3157 */
3159 static VALUE
3161 {
3169 }
3172 }
3176 {
3178 }
3180 static void
3182 {
3187 }
3192 }
3198 }
3199 }
3201 VALUE
3203 {
3211 }
3212 }
3214 }
3216 /*
3217 * call-seq:
3218 * rotate!(count = 1) -> self
3219 *
3220 * Rotates +self+ in place by moving elements from one end to the other; returns +self+.
3221 *
3222 * With non-negative numeric +count+,
3223 * rotates +count+ elements from the beginning to the end:
3224 *
3225 * [0, 1, 2, 3].rotate!(2) # => [2, 3, 0, 1]
3226 [0, 1, 2, 3].rotate!(2.1) # => [2, 3, 0, 1]
3227 *
3228 * If +count+ is large, uses <tt>count % array.size</tt> as the count:
3229 *
3230 * [0, 1, 2, 3].rotate!(21) # => [1, 2, 3, 0]
3231 *
3232 * If +count+ is zero, rotates no elements:
3233 *
3234 * [0, 1, 2, 3].rotate!(0) # => [0, 1, 2, 3]
3235 *
3236 * With a negative numeric +count+, rotates in the opposite direction,
3237 * from end to beginning:
3238 *
3239 * [0, 1, 2, 3].rotate!(-1) # => [3, 0, 1, 2]
3240 *
3241 * If +count+ is small (far from zero), uses <tt>count % array.size</tt> as the count:
3242 *
3243 * [0, 1, 2, 3].rotate!(-21) # => [3, 0, 1, 2]
3244 *
3245 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
3246 */
3248 static VALUE
3250 {
3254 }
3256 /*
3257 * call-seq:
3258 * rotate(count = 1) -> new_array
3259 *
3260 * Returns a new array formed from +self+ with elements
3261 * rotated from one end to the other.
3262 *
3263 * With non-negative numeric +count+,
3264 * rotates elements from the beginning to the end:
3265 *
3266 * [0, 1, 2, 3].rotate(2) # => [2, 3, 0, 1]
3267 * [0, 1, 2, 3].rotate(2.1) # => [2, 3, 0, 1]
3268 *
3269 * If +count+ is large, uses <tt>count % array.size</tt> as the count:
3270 *
3271 * [0, 1, 2, 3].rotate(22) # => [2, 3, 0, 1]
3272 *
3273 * With a +count+ of zero, rotates no elements:
3274 *
3275 * [0, 1, 2, 3].rotate(0) # => [0, 1, 2, 3]
3276 *
3277 * With negative numeric +count+, rotates in the opposite direction,
3278 * from the end to the beginning:
3279 *
3280 * [0, 1, 2, 3].rotate(-1) # => [3, 0, 1, 2]
3281 *
3282 * If +count+ is small (far from zero), uses <tt>count % array.size</tt> as the count:
3283 *
3284 * [0, 1, 2, 3].rotate(-21) # => [3, 0, 1, 2]
3285 *
3286 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
3287 */
3289 static VALUE
3291 {
3292 VALUE rotated;
3305 }
3308 }
3311 VALUE ary;
3312 VALUE receiver;
3313 };
3315 static VALUE
3317 {
3320 }
3322 }
3324 static void
3326 {
3329 }
3331 }
3333 static int
3335 {
3348 }
3350 static int
3352 {
3362 }
3365 }
3368 }
3375 }
3377 /*
3378 * call-seq:
3379 * sort! -> self
3380 * sort! {|a, b| ... } -> self
3381 *
3382 * Like Array#sort, but returns +self+ with its elements sorted in place.
3383 *
3384 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
3385 */
3387 VALUE
3389 {
3408 }
3411 }
3414 }
3419 }
3424 }
3426 /* ary might be destructively operated in the given block */
3428 }
3431 }
3435 }
3436 /* tmp was lost ownership for the ptr */
3441 }
3442 /* tmp will be GC'ed. */
3444 }
3447 }
3449 /*
3450 * call-seq:
3451 * sort -> new_array
3452 * sort {|a, b| ... } -> new_array
3453 *
3454 * Returns a new array containing the elements of +self+, sorted.
3455 *
3456 * With no block given, compares elements using operator <tt>#<=></tt>
3457 * (see Object#<=>):
3458 *
3459 * [0, 2, 3, 1].sort # => [0, 1, 2, 3]
3460 *
3461 * With a block given, calls the block with each combination of pairs of elements from +self+;
3462 * for each pair +a+ and +b+, the block should return a numeric:
3463 *
3464 * - Negative when +b+ is to follow +a+.
3465 * - Zero when +a+ and +b+ are equivalent.
3466 * - Positive when +a+ is to follow +b+.
3467 *
3468 * Example:
3469 *
3470 * a = [3, 2, 0, 1]
3471 * a.sort {|a, b| a <=> b } # => [0, 1, 2, 3]
3472 * a.sort {|a, b| b <=> a } # => [3, 2, 1, 0]
3473 *
3474 * When the block returns zero, the order for +a+ and +b+ is indeterminate,
3475 * and may be unstable.
3476 *
3477 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
3478 */
3480 VALUE
3482 {
3486 }
3490 /*
3491 * call-seq:
3492 * bsearch {|element| ... } -> found_element or nil
3493 * bsearch -> new_enumerator
3494 *
3495 * Returns the element from +self+ found by a binary search,
3496 * or +nil+ if the search found no suitable element.
3497 *
3498 * See {Binary Searching}[rdoc-ref:bsearch.rdoc].
3499 *
3500 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
3501 */
3503 static VALUE
3505 {
3510 }
3512 }
3514 /*
3515 * call-seq:
3516 * bsearch_index {|element| ... } -> integer or nil
3517 * bsearch_index -> new_enumerator
3518 *
3519 * Returns the integer index of the element from +self+ found by a binary search,
3520 * or +nil+ if the search found no suitable element.
3521 *
3522 * See {Binary Searching}[rdoc-ref:bsearch.rdoc].
3523 *
3524 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
3525 */
3527 static VALUE
3529 {
3542 }
3546 }
3549 }
3556 }
3557 }
3562 }
3565 }
3568 }
3569 }
3572 }
3575 static VALUE
3577 {
3579 }
3581 /*
3582 * call-seq:
3583 * sort_by! {|element| ... } -> self
3584 * sort_by! -> new_enumerator
3585 *
3586 * With a block given, sorts the elements of +self+ in place;
3587 * returns self.
3588 *
3589 * Calls the block with each successive element;
3590 * sorts elements based on the values returned from the block:
3591 *
3592 * a = ['aaaa', 'bbb', 'cc', 'd']
3593 * a.sort_by! {|element| element.size }
3594 * a # => ["d", "cc", "bbb", "aaaa"]
3595 *
3596 * For duplicate values returned by the block, the ordering is indeterminate, and may be unstable.
3597 *
3598 * With no block given, returns a new Enumerator.
3599 *
3600 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
3601 */
3603 static VALUE
3605 {
3606 VALUE sorted;
3613 }
3616 /*
3617 * call-seq:
3618 * collect {|element| ... } -> new_array
3619 * collect -> new_enumerator
3620 * map {|element| ... } -> new_array
3621 * map -> new_enumerator
3622 *
3623 * With a block given, calls the block with each element of +self+;
3624 * returns a new array whose elements are the return values from the block:
3625 *
3626 * a = [:foo, 'bar', 2]
3627 * a1 = a.map {|element| element.class }
3628 * a1 # => [Symbol, String, Integer]
3629 *
3630 * With no block given, returns a new Enumerator.
3631 *
3632 * Related: #collect!;
3633 * see also {Methods for Converting}[rdoc-ref:Array@Methods+for+Converting].
3634 */
3636 static VALUE
3638 {
3640 VALUE collect;
3646 }
3648 }
3651 /*
3652 * call-seq:
3653 * collect! {|element| ... } -> new_array
3654 * collect! -> new_enumerator
3655 * map! {|element| ... } -> new_array
3656 * map! -> new_enumerator
3657 *
3658 * With a block given, calls the block with each element of +self+
3659 * and replaces the element with the block's return value;
3660 * returns +self+:
3661 *
3662 * a = [:foo, 'bar', 2]
3663 * a.map! { |element| element.class } # => [Symbol, String, Integer]
3664 *
3665 * With no block given, returns a new Enumerator.
3666 *
3667 * Related: #collect;
3668 * see also {Methods for Converting}[rdoc-ref:Array@Methods+for+Converting].
3669 */
3671 static VALUE
3673 {
3680 }
3682 }
3684 VALUE
3685 rb_get_values_at(VALUE obj, long olen, int argc, const VALUE *argv, VALUE (*func) (VALUE, long))
3686 {
3694 }
3695 /* check if idx is Range */
3700 }
3704 }
3706 }
3708 }
3710 static VALUE
3712 {
3716 }
3717 /* check if idx is Range */
3725 }
3728 }
3729 }
3731 }
3734 }
3736 }
3738 /*
3739 * call-seq:
3740 * values_at(*specifiers) -> new_array
3741 *
3742 * Returns elements from +self+ in a new array; does not modify +self+.
3743 *
3744 * The objects included in the returned array are the elements of +self+
3745 * selected by the given +specifiers+,
3746 * each of which must be a numeric index or a Range.
3747 *
3748 * In brief:
3749 *
3750 * a = ['a', 'b', 'c', 'd']
3751 *
3752 * # Index specifiers.
3753 * a.values_at(2, 0, 2, 0) # => ["c", "a", "c", "a"] # May repeat.
3754 * a.values_at(-4, -3, -2, -1) # => ["a", "b", "c", "d"] # Counts backwards if negative.
3755 * a.values_at(-50, 50) # => [nil, nil] # Outside of self.
3756 *
3757 * # Range specifiers.
3758 * a.values_at(1..3) # => ["b", "c", "d"] # From range.begin to range.end.
3759 * a.values_at(1...3) # => ["b", "c"] # End excluded.
3760 * a.values_at(3..1) # => [] # No such elements.
3761 *
3762 * a.values_at(-3..3) # => ["b", "c", "d"] # Negative range.begin counts backwards.
3763 * a.values_at(-50..3) # Raises RangeError.
3764 *
3765 * a.values_at(1..-2) # => ["b", "c"] # Negative range.end counts backwards.
3766 * a.values_at(1..-50) # => [] # No such elements.
3767 *
3768 * # Mixture of specifiers.
3769 * a.values_at(2..3, 3, 0..1, 0) # => ["c", "d", "d", "a", "b", "a"]
3770 *
3771 * With no +specifiers+ given, returns a new empty array:
3772 *
3773 * a = ['a', 'b', 'c', 'd']
3774 * a.values_at # => []
3775 *
3776 * For each numeric specifier +index+, includes an element:
3777 *
3778 * - For each non-negative numeric specifier +index+ that is in-range (less than <tt>self.size</tt>),
3779 * includes the element at offset +index+:
3780 *
3781 * a.values_at(0, 2) # => ["a", "c"]
3782 * a.values_at(0.1, 2.9) # => ["a", "c"]
3783 *
3784 * - For each negative numeric +index+ that is in-range (greater than or equal to <tt>- self.size</tt>),
3785 * counts backwards from the end of +self+:
3786 *
3787 * a.values_at(-1, -4) # => ["d", "a"]
3788 *
3789 * The given indexes may be in any order, and may repeat:
3790 *
3791 * a.values_at(2, 0, 1, 0, 2) # => ["c", "a", "b", "a", "c"]
3792 *
3793 * For each +index+ that is out-of-range, includes +nil+:
3794 *
3795 * a.values_at(4, -5) # => [nil, nil]
3796 *
3797 * For each Range specifier +range+, includes elements
3798 * according to <tt>range.begin</tt> and <tt>range.end</tt>:
3799 *
3800 * - If both <tt>range.begin</tt> and <tt>range.end</tt>
3801 * are non-negative and in-range (less than <tt>self.size</tt>),
3802 * includes elements from index <tt>range.begin</tt>
3803 * through <tt>range.end - 1</tt> (if <tt>range.exclude_end?</tt>),
3804 * or through <tt>range.end</tt> (otherwise):
3805 *
3806 * a.values_at(1..2) # => ["b", "c"]
3807 * a.values_at(1...2) # => ["b"]
3808 *
3809 * - If <tt>range.begin</tt> is negative and in-range (greater than or equal to <tt>- self.size</tt>),
3810 * counts backwards from the end of +self+:
3811 *
3812 * a.values_at(-2..3) # => ["c", "d"]
3813 *
3814 * - If <tt>range.begin</tt> is negative and out-of-range, raises an exception:
3815 *
3816 * a.values_at(-5..3) # Raises RangeError.
3817 *
3818 * - If <tt>range.end</tt> is positive and out-of-range,
3819 * extends the returned array with +nil+ elements:
3820 *
3821 * a.values_at(1..5) # => ["b", "c", "d", nil, nil]
3822 *
3823 * - If <tt>range.end</tt> is negative and in-range,
3824 * counts backwards from the end of +self+:
3825 *
3826 * a.values_at(1..-2) # => ["b", "c"]
3827 *
3828 * - If <tt>range.end</tt> is negative and out-of-range,
3829 * returns an empty array:
3830 *
3831 * a.values_at(1..-5) # => []
3832 *
3833 * The given ranges may be in any order and may repeat:
3834 *
3835 * a.values_at(2..3, 0..1, 2..3) # => ["c", "d", "a", "b", "c", "d"]
3836 *
3837 * The given specifiers may be any mixture of indexes and ranges:
3838 *
3839 * a.values_at(3, 1..2, 0, 2..3) # => ["d", "b", "c", "a", "c", "d"]
3840 *
3841 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
3842 */
3844 static VALUE
3846 {
3851 }
3854 }
3857 /*
3858 * call-seq:
3859 * select {|element| ... } -> new_array
3860 * select -> new_enumerator
3861 * filter {|element| ... } -> new_array
3862 * filter -> new_enumerator
3863 *
3864 * With a block given, calls the block with each element of +self+;
3865 * returns a new array containing those elements of +self+
3866 * for which the block returns a truthy value:
3867 *
3868 * a = [:foo, 'bar', 2, :bam]
3869 * a.select {|element| element.to_s.start_with?('b') }
3870 * # => ["bar", :bam]
3871 *
3872 * With no block given, returns a new Enumerator.
3873 *
3874 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
3875 */
3877 static VALUE
3879 {
3880 VALUE result;
3888 }
3889 }
3891 }
3894 VALUE ary;
3896 };
3898 static VALUE
3900 {
3910 }
3912 }
3914 }
3916 static VALUE
3918 {
3931 });
3932 }
3934 }
3936 }
3938 /*
3939 * call-seq:
3940 * select! {|element| ... } -> self or nil
3941 * select! -> new_enumerator
3942 * filter! {|element| ... } -> self or nil
3943 * filter! -> new_enumerator
3944 *
3945 * With a block given, calls the block with each element of +self+;
3946 * removes from +self+ those elements for which the block returns +false+ or +nil+.
3947 *
3948 * Returns +self+ if any elements were removed:
3949 *
3950 * a = [:foo, 'bar', 2, :bam]
3951 * a.select! {|element| element.to_s.start_with?('b') } # => ["bar", :bam]
3952 *
3953 * Returns +nil+ if no elements were removed.
3954 *
3955 * With no block given, returns a new Enumerator.
3956 *
3957 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
3958 */
3960 static VALUE
3962 {
3971 }
3973 /*
3974 * call-seq:
3975 * keep_if {|element| ... } -> self
3976 * keep_if -> new_enumerator
3977 *
3978 * With a block given, calls the block with each element of +self+;
3979 * removes the element from +self+ if the block does not return a truthy value:
3980 *
3981 * a = [:foo, 'bar', 2, :bam]
3982 * a.keep_if {|element| element.to_s.start_with?('b') } # => ["bar", :bam]
3983 *
3984 * With no block given, returns a new Enumerator.
3985 *
3986 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
3987 */
3989 static VALUE
3991 {
3995 }
3997 static void
3999 {
4006 }
4007 }
4008 }
4010 /*
4011 * call-seq:
4012 * delete(object) -> last_removed_object
4013 * delete(object) {|element| ... } -> last_removed_object or block_return
4014 *
4015 * Removes zero or more elements from +self+.
4016 *
4017 * With no block given,
4018 * removes from +self+ each element +ele+ such that <tt>ele == object</tt>;
4019 * returns the last removed element:
4020 *
4021 * a = [0, 1, 2, 2.0]
4022 * a.delete(2) # => 2.0
4023 * a # => [0, 1]
4024 *
4025 * Returns +nil+ if no elements removed:
4026 *
4027 * a.delete(2) # => nil
4028 *
4029 * With a block given,
4030 * removes from +self+ each element +ele+ such that <tt>ele == object</tt>.
4031 *
4032 * If any such elements are found, ignores the block
4033 * and returns the last removed element:
4034 *
4035 * a = [0, 1, 2, 2.0]
4036 * a.delete(2) {|element| fail 'Cannot happen' } # => 2.0
4037 * a # => [0, 1]
4038 *
4039 * If no such element is found, returns the block's return value:
4040 *
4041 * a.delete(2) {|element| "Element #{element} not found." }
4042 * # => "Element 2 not found."
4043 *
4044 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
4045 */
4047 VALUE
4049 {
4059 }
4062 }
4063 i2++;
4064 }
4068 }
4070 }
4076 }
4078 void
4080 {
4088 }
4091 }
4092 i2++;
4093 }
4096 }
4099 }
4101 VALUE
4103 {
4105 VALUE del;
4111 }
4117 });
4121 }
4123 /*
4124 * call-seq:
4125 * delete_at(index) -> removed_object or nil
4126 *
4127 * Removes the element of +self+ at the given +index+, which must be an
4128 * {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects].
4129 *
4130 * When +index+ is non-negative, deletes the element at offset +index+:
4131 *
4132 * a = [:foo, 'bar', 2]
4133 * a.delete_at(1) # => "bar"
4134 * a # => [:foo, 2]
4135 *
4136 * When +index+ is negative, counts backward from the end of the array:
4137 *
4138 * a = [:foo, 'bar', 2]
4139 * a.delete_at(-2) # => "bar"
4140 * a # => [:foo, 2]
4141 *
4142 * When +index+ is out of range, returns +nil+.
4143 *
4144 * a = [:foo, 'bar', 2]
4145 * a.delete_at(3) # => nil
4146 * a.delete_at(-4) # => nil
4147 *
4148 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
4149 */
4151 static VALUE
4153 {
4155 }
4157 static VALUE
4159 {
4164 }
4167 }
4170 }
4173 }
4176 }
4179 }
4184 }
4185 }
4187 /*
4188 * call-seq:
4189 * slice!(index) -> object or nil
4190 * slice!(start, length) -> new_array or nil
4191 * slice!(range) -> new_array or nil
4192 *
4193 * Removes and returns elements from +self+.
4194 *
4195 * With numeric argument +index+ given,
4196 * removes and returns the element at offset +index+:
4197 *
4198 * a = ['a', 'b', 'c', 'd']
4199 * a.slice!(2) # => "c"
4200 * a # => ["a", "b", "d"]
4201 * a.slice!(2.1) # => "d"
4202 * a # => ["a", "b"]
4203 *
4204 * If +index+ is negative, counts backwards from the end of +self+:
4205 *
4206 * a = ['a', 'b', 'c', 'd']
4207 * a.slice!(-2) # => "c"
4208 * a # => ["a", "b", "d"]
4209 *
4210 * If +index+ is out of range, returns +nil+.
4211 *
4212 * With numeric arguments +start+ and +length+ given,
4213 * removes +length+ elements from +self+ beginning at zero-based offset +start+;
4214 * returns the removed objects in a new array:
4215 *
4216 * a = ['a', 'b', 'c', 'd']
4217 * a.slice!(1, 2) # => ["b", "c"]
4218 * a # => ["a", "d"]
4219 * a.slice!(0.1, 1.1) # => ["a"]
4220 * a # => ["d"]
4221 *
4222 * If +start+ is negative, counts backwards from the end of +self+:
4223 *
4224 * a = ['a', 'b', 'c', 'd']
4225 * a.slice!(-2, 1) # => ["c"]
4226 * a # => ["a", "b", "d"]
4227 *
4228 * If +start+ is out-of-range, returns +nil+:
4229 *
4230 * a = ['a', 'b', 'c', 'd']
4231 * a.slice!(5, 1) # => nil
4232 * a.slice!(-5, 1) # => nil
4233 *
4234 * If <tt>start + length</tt> exceeds the array size,
4235 * removes and returns all elements from offset +start+ to the end:
4236 *
4237 * a = ['a', 'b', 'c', 'd']
4238 * a.slice!(2, 50) # => ["c", "d"]
4239 * a # => ["a", "b"]
4240 *
4241 * If <tt>start == a.size</tt> and +length+ is non-negative,
4242 * returns a new empty array.
4243 *
4244 * If +length+ is negative, returns +nil+.
4245 *
4246 * With Range argument +range+ given,
4247 * treats <tt>range.min</tt> as +start+ (as above)
4248 * and <tt>range.size</tt> as +length+ (as above):
4249 *
4250 * a = ['a', 'b', 'c', 'd']
4251 * a.slice!(1..2) # => ["b", "c"]
4252 * a # => ["a", "d"]
4253 *
4254 * If <tt>range.start == a.size</tt>, returns a new empty array:
4255 *
4256 * a = ['a', 'b', 'c', 'd']
4257 * a.slice!(4..5) # => []
4258 *
4259 * If <tt>range.start</tt> is larger than the array size, returns +nil+:
4260 *
4261 * a = ['a', 'b', 'c', 'd']
4262 a.slice!(5..6) # => nil
4263 *
4264 * If <tt>range.start</tt> is negative,
4265 * calculates the start index by counting backwards from the end of +self+:
4266 *
4267 * a = ['a', 'b', 'c', 'd']
4268 * a.slice!(-2..2) # => ["c"]
4269 *
4270 * If <tt>range.end</tt> is negative,
4271 * calculates the end index by counting backwards from the end of +self+:
4272 *
4273 * a = ['a', 'b', 'c', 'd']
4274 * a.slice!(0..-2) # => ["a", "b", "c"]
4275 *
4276 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
4277 */
4279 static VALUE
4281 {
4282 VALUE arg1;
4293 }
4298 /* valid range */
4301 /* invalid range */
4304 /* not a range */
4306 }
4307 }
4310 }
4312 static VALUE
4314 {
4322 }
4323 }
4325 }
4327 static VALUE
4329 {
4339 }
4341 }
4343 }
4345 static VALUE
4347 {
4353 }
4355 /*
4356 * call-seq:
4357 * reject! {|element| ... } -> self or nil
4358 * reject! -> new_enumerator
4359 *
4360 * With a block given, calls the block with each element of +self+;
4361 * removes each element for which the block returns a truthy value.
4362 *
4363 * Returns +self+ if any elements removed:
4364 *
4365 * a = [:foo, 'bar', 2, 'bat']
4366 * a.reject! {|element| element.to_s.start_with?('b') } # => [:foo, 2]
4367 *
4368 * Returns +nil+ if no elements removed.
4369 *
4370 * With no block given, returns a new Enumerator.
4371 *
4372 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
4373 */
4375 static VALUE
4377 {
4381 }
4383 /*
4384 * call-seq:
4385 * reject {|element| ... } -> new_array
4386 * reject -> new_enumerator
4387 *
4388 * With a block given, returns a new array whose elements are all those from +self+
4389 * for which the block returns +false+ or +nil+:
4390 *
4391 * a = [:foo, 'bar', 2, 'bat']
4392 * a1 = a.reject {|element| element.to_s.start_with?('b') }
4393 * a1 # => [:foo, 2]
4394 *
4395 * With no block given, returns a new Enumerator.
4396 *
4397 * Related: {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
4398 */
4400 static VALUE
4402 {
4403 VALUE rejected_ary;
4409 }
4411 /*
4412 * call-seq:
4413 * delete_if {|element| ... } -> self
4414 * delete_if -> new_numerator
4415 *
4416 * With a block given, calls the block with each element of +self+;
4417 * removes the element if the block returns a truthy value;
4418 * returns +self+:
4419 *
4420 * a = [:foo, 'bar', 2, 'bat']
4421 * a.delete_if {|element| element.to_s.start_with?('b') } # => [:foo, 2]
4422 *
4423 * With no block given, returns a new Enumerator.
4424 *
4425 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
4426 */
4428 static VALUE
4430 {
4435 }
4437 static VALUE
4439 {
4445 }
4447 static VALUE
4449 {
4461 }
4464 /*
4465 * call-seq:
4466 * zip(*other_arrays) -> new_array
4467 * zip(*other_arrays) {|sub_array| ... } -> nil
4468 *
4469 * With no block given, combines +self+ with the collection of +other_arrays+;
4470 * returns a new array of sub-arrays:
4471 *
4472 * [0, 1].zip(['zero', 'one'], [:zero, :one])
4473 * # => [[0, "zero", :zero], [1, "one", :one]]
4474 *
4475 * Returned:
4476 *
4477 * - The outer array is of size <tt>self.size</tt>.
4478 * - Each sub-array is of size <tt>other_arrays.size + 1</tt>.
4479 * - The _nth_ sub-array contains (in order):
4480 *
4481 * - The _nth_ element of +self+.
4482 * - The _nth_ element of each of the other arrays, as available.
4483 *
4484 * Example:
4485 *
4486 * a = [0, 1]
4487 * zipped = a.zip(['zero', 'one'], [:zero, :one])
4488 * # => [[0, "zero", :zero], [1, "one", :one]]
4489 * zipped.size # => 2 # Same size as a.
4490 * zipped.first.size # => 3 # Size of other arrays plus 1.
4491 *
4492 * When the other arrays are all the same size as +self+,
4493 * the returned sub-arrays are a rearrangement containing exactly elements of all the arrays
4494 * (including +self+), with no omissions or additions:
4495 *
4496 * a = [:a0, :a1, :a2, :a3]
4497 * b = [:b0, :b1, :b2, :b3]
4498 * c = [:c0, :c1, :c2, :c3]
4499 * d = a.zip(b, c)
4500 * pp d
4501 * # =>
4502 * [[:a0, :b0, :c0],
4503 * [:a1, :b1, :c1],
4504 * [:a2, :b2, :c2],
4505 * [:a3, :b3, :c3]]
4506 *
4507 * When one of the other arrays is smaller than +self+,
4508 * pads the corresponding sub-array with +nil+ elements:
4509 *
4510 * a = [:a0, :a1, :a2, :a3]
4511 * b = [:b0, :b1, :b2]
4512 * c = [:c0, :c1]
4513 * d = a.zip(b, c)
4514 * pp d
4515 * # =>
4516 * [[:a0, :b0, :c0],
4517 * [:a1, :b1, :c1],
4518 * [:a2, :b2, nil],
4519 * [:a3, nil, nil]]
4520 *
4521 * When one of the other arrays is larger than +self+,
4522 * _ignores_ its trailing elements:
4523 *
4524 * a = [:a0, :a1, :a2, :a3]
4525 * b = [:b0, :b1, :b2, :b3, :b4]
4526 * c = [:c0, :c1, :c2, :c3, :c4, :c5]
4527 * d = a.zip(b, c)
4528 * pp d
4529 * # =>
4530 * [[:a0, :b0, :c0],
4531 * [:a1, :b1, :c1],
4532 * [:a2, :b2, :c2],
4533 * [:a3, :b3, :c3]]
4534 *
4535 * With a block given, calls the block with each of the other arrays;
4536 * returns +nil+:
4537 *
4538 * d = []
4539 * a = [:a0, :a1, :a2, :a3]
4540 * b = [:b0, :b1, :b2, :b3]
4541 * c = [:c0, :c1, :c2, :c3]
4542 * a.zip(b, c) {|sub_array| d.push(sub_array.reverse) } # => nil
4543 * pp d
4544 * # =>
4545 * [[:c0, :b0, :a0],
4546 * [:c1, :b1, :a1],
4547 * [:c2, :b2, :a2],
4548 * [:c3, :b3, :a3]]
4549 *
4550 * For an *object* in *other_arrays* that is not actually an array,
4551 * forms the the "other array" as <tt>object.to_ary</tt>, if defined,
4552 * or as <tt>object.each.to_a</tt> otherwise.
4553 *
4554 * Related: see {Methods for Converting}[rdoc-ref:Array@Methods+for+Converting].
4555 */
4557 static VALUE
4559 {
4566 }
4580 }
4582 }
4585 }
4593 }
4595 }
4596 }
4597 }
4607 }
4609 }
4610 }
4613 }
4615 /*
4616 * call-seq:
4617 * transpose -> new_array
4618 *
4619 * Returns a new array that is +self+
4620 * as a {transposed matrix}[https://en.wikipedia.org/wiki/Transpose]:
4621 *
4622 * a = [[:a0, :a1], [:b0, :b1], [:c0, :c1]]
4623 * a.transpose # => [[:a0, :b0, :c0], [:a1, :b1, :c1]]
4624 *
4625 * The elements of +self+ must all be the same size.
4626 *
4627 * Related: see {Methods for Converting}[rdoc-ref:Array@Methods+for+Converting].
4628 */
4630 static VALUE
4632 {
4645 }
4646 }
4650 }
4653 }
4654 }
4656 }
4658 /*
4659 * call-seq:
4660 * initialize_copy(other_array) -> self
4661 * replace(other_array) -> self
4662 *
4663 * Replaces the elements of +self+ with the elements of +other_array+, which must be an
4664 * {array-convertible object}[rdoc-ref:implicit_conversion.rdoc@Array-Convertible+Objects];
4665 * returns +self+:
4666 *
4667 * a = ['a', 'b', 'c'] # => ["a", "b", "c"]
4668 * a.replace(['d', 'e']) # => ["d", "e"]
4669 *
4670 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
4671 */
4673 VALUE
4675 {
4682 /* orig has enough space to embed the contents of orig. */
4687 }
4688 /* orig is embedded but copy does not have enough space to embed the
4689 * contents of orig. */
4699 // No allocation and exception expected that could leave `copy` in a
4700 // bad state from the edits above.
4702 }
4703 /* Otherwise, orig is on heap and copy does not have enough space to embed
4704 * the contents of orig. */
4711 }
4714 }
4716 /*
4717 * call-seq:
4718 * clear -> self
4719 *
4720 * Removes all elements from +self+; returns +self+:
4721 *
4722 * a = [:foo, 'bar', 2]
4723 * a.clear # => []
4724 *
4725 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
4726 */
4728 VALUE
4730 {
4736 }
4741 }
4742 }
4745 }
4747 /*
4748 * call-seq:
4749 * fill(object, start = nil, count = nil) -> new_array
4750 * fill(object, range) -> new_array
4751 * fill(start = nil, count = nil) {|element| ... } -> new_array
4752 * fill(range) {|element| ... } -> new_array
4753 *
4754 * Replaces selected elements in +self+;
4755 * may add elements to +self+;
4756 * always returns +self+ (never a new array).
4757 *
4758 * In brief:
4759 *
4760 * # Non-negative start.
4761 * ['a', 'b', 'c', 'd'].fill('-', 1, 2) # => ["a", "-", "-", "d"]
4762 * ['a', 'b', 'c', 'd'].fill(1, 2) {|e| e.to_s } # => ["a", "1", "2", "d"]
4763 *
4764 * # Extends with specified values if necessary.
4765 * ['a', 'b', 'c', 'd'].fill('-', 3, 2) # => ["a", "b", "c", "-", "-"]
4766 * ['a', 'b', 'c', 'd'].fill(3, 2) {|e| e.to_s } # => ["a", "b", "c", "3", "4"]
4767 *
4768 * # Fills with nils if necessary.
4769 * ['a', 'b', 'c', 'd'].fill('-', 6, 2) # => ["a", "b", "c", "d", nil, nil, "-", "-"]
4770 * ['a', 'b', 'c', 'd'].fill(6, 2) {|e| e.to_s } # => ["a", "b", "c", "d", nil, nil, "6", "7"]
4771 *
4772 * # For negative start, counts backwards from the end.
4773 * ['a', 'b', 'c', 'd'].fill('-', -3, 3) # => ["a", "-", "-", "-"]
4774 * ['a', 'b', 'c', 'd'].fill(-3, 3) {|e| e.to_s } # => ["a", "1", "2", "3"]
4775 *
4776 * # Range.
4777 * ['a', 'b', 'c', 'd'].fill('-', 1..2) # => ["a", "-", "-", "d"]
4778 * ['a', 'b', 'c', 'd'].fill(1..2) {|e| e.to_s } # => ["a", "1", "2", "d"]
4779 *
4780 * When arguments +start+ and +count+ are given,
4781 * they select the elements of +self+ to be replaced;
4782 * each must be an
4783 * {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects]
4784 * (or +nil+):
4785 *
4786 * - +start+ specifies the zero-based offset of the first element to be replaced;
4787 * +nil+ means zero.
4788 * - +count+ is the number of consecutive elements to be replaced;
4789 * +nil+ means "all the rest."
4790 *
4791 * With argument +object+ given,
4792 * that one object is used for all replacements:
4793 *
4794 * o = Object.new # => #<Object:0x0000014e7bff7600>
4795 * a = ['a', 'b', 'c', 'd'] # => ["a", "b", "c", "d"]
4796 * a.fill(o, 1, 2)
4797 * # => ["a", #<Object:0x0000014e7bff7600>, #<Object:0x0000014e7bff7600>, "d"]
4798 *
4799 * With a block given, the block is called once for each element to be replaced;
4800 * the value passed to the block is the _index_ of the element to be replaced
4801 * (not the element itself);
4802 * the block's return value replaces the element:
4803 *
4804 * a = ['a', 'b', 'c', 'd'] # => ["a", "b", "c", "d"]
4805 * a.fill(1, 2) {|element| element.to_s } # => ["a", "1", "2", "d"]
4806 *
4807 * For arguments +start+ and +count+:
4808 *
4809 * - If +start+ is non-negative,
4810 * replaces +count+ elements beginning at offset +start+:
4811 *
4812 * ['a', 'b', 'c', 'd'].fill('-', 0, 2) # => ["-", "-", "c", "d"]
4813 * ['a', 'b', 'c', 'd'].fill('-', 1, 2) # => ["a", "-", "-", "d"]
4814 * ['a', 'b', 'c', 'd'].fill('-', 2, 2) # => ["a", "b", "-", "-"]
4815 *
4816 * ['a', 'b', 'c', 'd'].fill(0, 2) {|e| e.to_s } # => ["0", "1", "c", "d"]
4817 * ['a', 'b', 'c', 'd'].fill(1, 2) {|e| e.to_s } # => ["a", "1", "2", "d"]
4818 * ['a', 'b', 'c', 'd'].fill(2, 2) {|e| e.to_s } # => ["a", "b", "2", "3"]
4819 *
4820 * Extends +self+ if necessary:
4821 *
4822 * ['a', 'b', 'c', 'd'].fill('-', 3, 2) # => ["a", "b", "c", "-", "-"]
4823 * ['a', 'b', 'c', 'd'].fill('-', 4, 2) # => ["a", "b", "c", "d", "-", "-"]
4824 *
4825 * ['a', 'b', 'c', 'd'].fill(3, 2) {|e| e.to_s } # => ["a", "b", "c", "3", "4"]
4826 * ['a', 'b', 'c', 'd'].fill(4, 2) {|e| e.to_s } # => ["a", "b", "c", "d", "4", "5"]
4827 *
4828 * Fills with +nil+ if necessary:
4829 *
4830 * ['a', 'b', 'c', 'd'].fill('-', 5, 2) # => ["a", "b", "c", "d", nil, "-", "-"]
4831 * ['a', 'b', 'c', 'd'].fill('-', 6, 2) # => ["a", "b", "c", "d", nil, nil, "-", "-"]
4832 *
4833 * ['a', 'b', 'c', 'd'].fill(5, 2) {|e| e.to_s } # => ["a", "b", "c", "d", nil, "5", "6"]
4834 * ['a', 'b', 'c', 'd'].fill(6, 2) {|e| e.to_s } # => ["a", "b", "c", "d", nil, nil, "6", "7"]
4835 *
4836 * Does nothing if +count+ is non-positive:
4837 *
4838 * ['a', 'b', 'c', 'd'].fill('-', 2, 0) # => ["a", "b", "c", "d"]
4839 * ['a', 'b', 'c', 'd'].fill('-', 2, -100) # => ["a", "b", "c", "d"]
4840 * ['a', 'b', 'c', 'd'].fill('-', 6, -100) # => ["a", "b", "c", "d"]
4841 *
4842 * ['a', 'b', 'c', 'd'].fill(2, 0) {|e| fail 'Cannot happen' } # => ["a", "b", "c", "d"]
4843 * ['a', 'b', 'c', 'd'].fill(2, -100) {|e| fail 'Cannot happen' } # => ["a", "b", "c", "d"]
4844 * ['a', 'b', 'c', 'd'].fill(6, -100) {|e| fail 'Cannot happen' } # => ["a", "b", "c", "d"]
4845 *
4846 * - If +start+ is negative, counts backwards from the end of +self+:
4847 *
4848 * ['a', 'b', 'c', 'd'].fill('-', -4, 3) # => ["-", "-", "-", "d"]
4849 * ['a', 'b', 'c', 'd'].fill('-', -3, 3) # => ["a", "-", "-", "-"]
4850 *
4851 * ['a', 'b', 'c', 'd'].fill(-4, 3) {|e| e.to_s } # => ["0", "1", "2", "d"]
4852 * ['a', 'b', 'c', 'd'].fill(-3, 3) {|e| e.to_s } # => ["a", "1", "2", "3"]
4853 *
4854 * Extends +self+ if necessary:
4855 *
4856 * ['a', 'b', 'c', 'd'].fill('-', -2, 3) # => ["a", "b", "-", "-", "-"]
4857 * ['a', 'b', 'c', 'd'].fill('-', -1, 3) # => ["a", "b", "c", "-", "-", "-"]
4858 *
4859 * ['a', 'b', 'c', 'd'].fill(-2, 3) {|e| e.to_s } # => ["a", "b", "2", "3", "4"]
4860 * ['a', 'b', 'c', 'd'].fill(-1, 3) {|e| e.to_s } # => ["a", "b", "c", "3", "4", "5"]
4861 *
4862 * Starts at the beginning of +self+ if +start+ is negative and out-of-range:
4863 *
4864 * ['a', 'b', 'c', 'd'].fill('-', -5, 2) # => ["-", "-", "c", "d"]
4865 * ['a', 'b', 'c', 'd'].fill('-', -6, 2) # => ["-", "-", "c", "d"]
4866 *
4867 * ['a', 'b', 'c', 'd'].fill(-5, 2) {|e| e.to_s } # => ["0", "1", "c", "d"]
4868 * ['a', 'b', 'c', 'd'].fill(-6, 2) {|e| e.to_s } # => ["0", "1", "c", "d"]
4869 *
4870 * Does nothing if +count+ is non-positive:
4871 *
4872 * ['a', 'b', 'c', 'd'].fill('-', -2, 0) # => ["a", "b", "c", "d"]
4873 * ['a', 'b', 'c', 'd'].fill('-', -2, -1) # => ["a", "b", "c", "d"]
4874 *
4875 * ['a', 'b', 'c', 'd'].fill(-2, 0) {|e| fail 'Cannot happen' } # => ["a", "b", "c", "d"]
4876 * ['a', 'b', 'c', 'd'].fill(-2, -1) {|e| fail 'Cannot happen' } # => ["a", "b", "c", "d"]
4877 *
4878 * When argument +range+ is given,
4879 * it must be a Range object whose members are numeric;
4880 * its +begin+ and +end+ values determine the elements of +self+
4881 * to be replaced:
4882 *
4883 * - If both +begin+ and +end+ are positive, they specify the first and last elements
4884 * to be replaced:
4885 *
4886 * ['a', 'b', 'c', 'd'].fill('-', 1..2) # => ["a", "-", "-", "d"]
4887 * ['a', 'b', 'c', 'd'].fill(1..2) {|e| e.to_s } # => ["a", "1", "2", "d"]
4888 *
4889 * If +end+ is smaller than +begin+, replaces no elements:
4890 *
4891 * ['a', 'b', 'c', 'd'].fill('-', 2..1) # => ["a", "b", "c", "d"]
4892 * ['a', 'b', 'c', 'd'].fill(2..1) {|e| e.to_s } # => ["a", "b", "c", "d"]
4893 *
4894 * - If either is negative (or both are negative), counts backwards from the end of +self+:
4895 *
4896 * ['a', 'b', 'c', 'd'].fill('-', -3..2) # => ["a", "-", "-", "d"]
4897 * ['a', 'b', 'c', 'd'].fill('-', 1..-2) # => ["a", "-", "-", "d"]
4898 * ['a', 'b', 'c', 'd'].fill('-', -3..-2) # => ["a", "-", "-", "d"]
4899 *
4900 * ['a', 'b', 'c', 'd'].fill(-3..2) {|e| e.to_s } # => ["a", "1", "2", "d"]
4901 * ['a', 'b', 'c', 'd'].fill(1..-2) {|e| e.to_s } # => ["a", "1", "2", "d"]
4902 * ['a', 'b', 'c', 'd'].fill(-3..-2) {|e| e.to_s } # => ["a", "1", "2", "d"]
4903 *
4904 * - If the +end+ value is excluded (see Range#exclude_end?), omits the last replacement:
4905 *
4906 * ['a', 'b', 'c', 'd'].fill('-', 1...2) # => ["a", "-", "c", "d"]
4907 * ['a', 'b', 'c', 'd'].fill('-', 1...-2) # => ["a", "-", "c", "d"]
4908 *
4909 * ['a', 'b', 'c', 'd'].fill(1...2) {|e| e.to_s } # => ["a", "1", "c", "d"]
4910 * ['a', 'b', 'c', 'd'].fill(1...-2) {|e| e.to_s } # => ["a", "1", "c", "d"]
4911 *
4912 * - If the range is endless (see {Endless Ranges}[rdoc-ref:Range@Endless+Ranges]),
4913 * replaces elements to the end of +self+:
4914 *
4915 * ['a', 'b', 'c', 'd'].fill('-', 1..) # => ["a", "-", "-", "-"]
4916 * ['a', 'b', 'c', 'd'].fill(1..) {|e| e.to_s } # => ["a", "1", "2", "3"]
4917 *
4918 * - If the range is beginless (see {Beginless Ranges}[rdoc-ref:Range@Beginless+Ranges]),
4919 * replaces elements from the beginning of +self+:
4920 *
4921 * ['a', 'b', 'c', 'd'].fill('-', ..2) # => ["-", "-", "-", "d"]
4922 * ['a', 'b', 'c', 'd'].fill(..2) {|e| e.to_s } # => ["0", "1", "2", "d"]
4923 *
4924 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
4925 */
4927 static VALUE
4929 {
4936 }
4939 }
4948 }
4949 /* fall through */
4955 }
4958 }
4962 }
4965 }
4970 }
4973 }
4976 VALUE v;
4983 }
4984 }
4987 }
4989 }
4991 /*
4992 * call-seq:
4993 * self + other_array -> new_array
4994 *
4995 * Returns a new array containing all elements of +self+
4996 * followed by all elements of +other_array+:
4997 *
4998 * a = [0, 1] + [2, 3]
4999 * a # => [0, 1, 2, 3]
5000 *
5001 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
5002 */
5004 VALUE
5006 {
5007 VALUE z;
5020 }
5022 static VALUE
5024 {
5028 }
5031 }
5033 /*
5034 * call-seq:
5035 * concat(*other_arrays) -> self
5036 *
5037 * Adds to +self+ all elements from each array in +other_arrays+; returns +self+:
5038 *
5039 * a = [0, 1]
5040 * a.concat(['two', 'three'], [:four, :five], a)
5041 * # => [0, 1, "two", "three", :four, :five, 0, 1]
5042 *
5043 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
5044 */
5046 static VALUE
5048 {
5053 }
5059 }
5061 }
5065 }
5067 VALUE
5069 {
5071 }
5073 /*
5074 * call-seq:
5075 * self * n -> new_array
5076 * self * string_separator -> new_string
5077 *
5078 * When non-negative integer argument +n+ is given,
5079 * returns a new array built by concatenating +n+ copies of +self+:
5080 *
5081 * a = ['x', 'y']
5082 * a * 3 # => ["x", "y", "x", "y", "x", "y"]
5083 *
5084 * When string argument +string_separator+ is given,
5085 * equivalent to <tt>self.join(string_separator)</tt>:
5086 *
5087 * [0, [0, 1], {foo: 0}] * ', ' # => "0, 0, 1, {:foo=>0}"
5088 *
5089 */
5091 static VALUE
5093 {
5101 }
5107 }
5110 }
5113 }
5126 }
5129 }
5130 }
5131 out:
5133 }
5135 /*
5136 * call-seq:
5137 * assoc(object) -> found_array or nil
5138 *
5139 * Returns the first element +ele+ in +self+ such that +ele+ is an array
5140 * and <tt>ele[0] == object</tt>:
5141 *
5142 * a = [{foo: 0}, [2, 4], [4, 5, 6], [4, 5]]
5143 * a.assoc(4) # => [4, 5, 6]
5144 *
5145 * Returns +nil+ if no such element is found.
5146 *
5147 * Related: Array#rassoc;
5148 * see also {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
5149 */
5151 VALUE
5153 {
5155 VALUE v;
5162 }
5164 }
5166 /*
5167 * call-seq:
5168 * rassoc(object) -> found_array or nil
5169 *
5170 * Returns the first element +ele+ in +self+ such that +ele+ is an array
5171 * and <tt>ele[1] == object</tt>:
5172 *
5173 * a = [{foo: 0}, [2, 4], [4, 5, 6], [4, 5]]
5174 * a.rassoc(4) # => [2, 4]
5175 * a.rassoc(5) # => [4, 5, 6]
5176 *
5177 * Returns +nil+ if no such element is found.
5178 *
5179 * Related: Array#assoc;
5180 * see also {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
5181 */
5183 VALUE
5185 {
5187 VALUE v;
5195 }
5197 }
5199 static VALUE
5201 {
5207 /* rb_equal() can evacuate ptrs */
5222 }
5225 }
5226 }
5227 p1++;
5228 p2++;
5229 }
5231 }
5233 /*
5234 * call-seq:
5235 * self == other_array -> true or false
5236 *
5237 * Returns whether both:
5238 *
5239 * - +self+ and +other_array+ are the same size.
5240 * - Their corresponding elements are the same;
5241 * that is, for each index +i+ in <tt>(0...self.size)</tt>,
5242 * <tt>self[i] == other_array[i]</tt>.
5243 *
5244 * Examples:
5245 *
5246 * [:foo, 'bar', 2] == [:foo, 'bar', 2] # => true
5247 * [:foo, 'bar', 2] == [:foo, 'bar', 2.0] # => true
5248 * [:foo, 'bar', 2] == [:foo, 'bar'] # => false # Different sizes.
5249 * [:foo, 'bar', 2] == [:foo, 'bar', 3] # => false # Different elements.
5250 *
5251 * This method is different from method Array#eql?,
5252 * which compares elements using <tt>Object#eql?</tt>.
5253 *
5254 * Related: see {Methods for Comparing}[rdoc-ref:Array@Methods+for+Comparing].
5255 */
5257 static VALUE
5259 {
5264 }
5266 }
5270 }
5272 static VALUE
5274 {
5281 }
5283 }
5285 /*
5286 * call-seq:
5287 * eql?(other_array) -> true or false
5288 *
5289 * Returns +true+ if +self+ and +other_array+ are the same size,
5290 * and if, for each index +i+ in +self+, <tt>self[i].eql?(other_array[i])</tt>:
5291 *
5292 * a0 = [:foo, 'bar', 2]
5293 * a1 = [:foo, 'bar', 2]
5294 * a1.eql?(a0) # => true
5295 *
5296 * Otherwise, returns +false+.
5297 *
5298 * This method is different from method Array#==,
5299 * which compares using method <tt>Object#==</tt>.
5300 *
5301 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
5302 */
5304 static VALUE
5306 {
5312 }
5314 VALUE
5316 {
5318 st_index_t h;
5319 VALUE n;
5326 }
5329 }
5331 /*
5332 * call-seq:
5333 * hash -> integer
5334 *
5335 * Returns the integer hash value for +self+.
5336 *
5337 * Two arrays with the same content will have the same hash value
5338 * (and will compare using eql?):
5339 *
5340 * ['a', 'b'].hash == ['a', 'b'].hash # => true
5341 * ['a', 'b'].hash == ['a', 'c'].hash # => false
5342 * ['a', 'b'].hash == ['a'].hash # => false
5343 *
5344 */
5346 static VALUE
5348 {
5350 }
5352 /*
5353 * call-seq:
5354 * include?(object) -> true or false
5355 *
5356 * Returns whether for some element +element+ in +self+,
5357 * <tt>object == element</tt>:
5358 *
5359 * [0, 1, 2].include?(2) # => true
5360 * [0, 1, 2].include?(2.0) # => true
5361 * [0, 1, 2].include?(2.1) # => false
5362 *
5363 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
5364 */
5366 VALUE
5368 {
5370 VALUE e;
5376 }
5377 }
5379 }
5381 static VALUE
5383 {
5385 VALUE e;
5391 }
5392 }
5394 }
5396 static VALUE
5398 {
5405 }
5411 }
5412 }
5414 }
5416 /*
5417 * call-seq:
5418 * self <=> other_array -> -1, 0, or 1
5419 *
5420 * Returns -1, 0, or 1 as +self+ is determined
5421 * to be less than, equal to, or greater than +other_array+.
5422 *
5423 * Iterates over each index +i+ in <tt>(0...self.size)</tt>:
5424 *
5425 * - Computes <tt>result[i]</tt> as <tt>self[i] <=> other_array[i]</tt>.
5426 * - Immediately returns 1 if <tt>result[i]</tt> is 1:
5427 *
5428 * [0, 1, 2] <=> [0, 0, 2] # => 1
5429 *
5430 * - Immediately returns -1 if <tt>result[i]</tt> is -1:
5431 *
5432 * [0, 1, 2] <=> [0, 2, 2] # => -1
5433 *
5434 * - Continues if <tt>result[i]</tt> is 0.
5435 *
5436 * When every +result+ is 0,
5437 * returns <tt>self.size <=> other_array.size</tt>
5438 * (see Integer#<=>):
5439 *
5440 * [0, 1, 2] <=> [0, 1] # => 1
5441 * [0, 1, 2] <=> [0, 1, 2] # => 0
5442 * [0, 1, 2] <=> [0, 1, 2, 3] # => -1
5443 *
5444 * Note that when +other_array+ is larger than +self+,
5445 * its trailing elements do not affect the result:
5446 *
5447 * [0, 1, 2] <=> [0, 1, 2, -3] # => -1
5448 * [0, 1, 2] <=> [0, 1, 2, 0] # => -1
5449 * [0, 1, 2] <=> [0, 1, 2, 3] # => -1
5450 *
5451 * Related: see {Methods for Comparing}[rdoc-ref:Array@Methods+for+Comparing].
5452 */
5454 VALUE
5456 {
5458 VALUE v;
5469 }
5471 static VALUE
5473 {
5479 }
5481 }
5485 {
5491 }
5493 static VALUE
5495 {
5498 }
5500 static VALUE
5502 {
5508 }
5510 }
5512 static VALUE
5514 {
5517 }
5519 /*
5520 * call-seq:
5521 * self - other_array -> new_array
5522 *
5523 * Returns a new array containing only those elements of +self+
5524 * that are not found in +other_array+;
5525 * the order from +self+ is preserved:
5526 *
5527 * [0, 1, 1, 2, 1, 1, 3, 1, 1] - [1] # => [0, 2, 3]
5528 * [0, 1, 1, 2, 1, 1, 3, 1, 1] - [3, 2, 0, :foo] # => [1, 1, 1, 1, 1, 1]
5529 * [0, 1, 2] - [:foo] # => [0, 1, 2]
5530 *
5531 * Element are compared using method <tt>#eql?</tt>
5532 * (as defined in each element of +self+).
5533 *
5534 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
5535 */
5537 VALUE
5539 {
5540 VALUE ary3;
5541 VALUE hash;
5553 }
5555 }
5561 }
5564 }
5566 /*
5567 * call-seq:
5568 * difference(*other_arrays = []) -> new_array
5569 *
5570 * Returns a new array containing only those elements from +self+
5571 * that are not found in any of the given +other_arrays+;
5572 * items are compared using <tt>eql?</tt>; order from +self+ is preserved:
5573 *
5574 * [0, 1, 1, 2, 1, 1, 3, 1, 1].difference([1]) # => [0, 2, 3]
5575 * [0, 1, 2, 3].difference([3, 0], [1, 3]) # => [2]
5576 * [0, 1, 2].difference([4]) # => [0, 1, 2]
5577 * [0, 1, 2].difference # => [0, 1, 2]
5578 *
5579 * Returns a copy of +self+ if no arguments are given.
5580 *
5581 * Related: Array#-;
5582 * see also {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
5583 */
5585 static VALUE
5587 {
5588 VALUE ary_diff;
5599 }
5608 }
5611 }
5612 }
5614 }
5619 }
5622 /*
5623 * call-seq:
5624 * self & other_array -> new_array
5625 *
5626 * Returns a new array containing the _intersection_ of +self+ and +other_array+;
5627 * that is, containing those elements found in both +self+ and +other_array+:
5628 *
5629 * [0, 1, 2, 3] & [1, 2] # => [1, 2]
5630 *
5631 * Omits duplicates:
5632 *
5633 * [0, 1, 1, 0] & [0, 1] # => [0, 1]
5634 *
5635 * Preserves order from +self+:
5636 *
5637 * [0, 1, 2] & [3, 2, 1, 0] # => [0, 1, 2]
5638 *
5639 * Identifies common elements using method <tt>#eql?</tt>
5640 * (as defined in each element of +self+).
5641 *
5642 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
5643 */
5646 static VALUE
5648 {
5650 st_data_t vv;
5663 }
5665 }
5674 }
5675 }
5678 }
5680 /*
5681 * call-seq:
5682 * intersection(*other_arrays) -> new_array
5683 *
5684 * Returns a new array containing each element in +self+ that is +#eql?+
5685 * to at least one element in each of the given +other_arrays+;
5686 * duplicates are omitted:
5687 *
5688 * [0, 0, 1, 1, 2, 3].intersection([0, 1, 2], [0, 1, 3]) # => [0, 1]
5689 *
5690 * Each element must correctly implement method <tt>#hash</tt>.
5691 *
5692 * Order from +self+ is preserved:
5693 *
5694 * [0, 1, 2].intersection([2, 1, 0]) # => [0, 1, 2]
5695 *
5696 * Returns a copy of +self+ if no arguments are given.
5697 *
5698 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
5699 */
5701 static VALUE
5703 {
5709 }
5712 }
5714 static int
5716 {
5720 }
5722 static void
5724 {
5730 }
5731 }
5733 static void
5735 {
5741 }
5742 }
5743 }
5745 /*
5746 * call-seq:
5747 * self | other_array -> new_array
5748 *
5749 * Returns the union of +self+ and +other_array+;
5750 * duplicates are removed; order is preserved;
5751 * items are compared using <tt>eql?</tt>:
5752 *
5753 * [0, 1] | [2, 3] # => [0, 1, 2, 3]
5754 * [0, 1, 1] | [2, 2, 3] # => [0, 1, 2, 3]
5755 * [0, 1, 2] | [3, 2, 1, 0] # => [0, 1, 2, 3]
5756 *
5757 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
5758 */
5760 static VALUE
5762 {
5763 VALUE hash;
5771 }
5777 }
5779 /*
5780 * call-seq:
5781 * union(*other_arrays) -> new_array
5782 *
5783 * Returns a new array that is the union of the elements of +self+
5784 * and all given arrays +other_arrays+;
5785 * items are compared using <tt>eql?</tt>:
5786 *
5787 * [0, 1, 2, 3].union([4, 5], [6, 7]) # => [0, 1, 2, 3, 4, 5, 6, 7]
5788 *
5789 * Removes duplicates (preserving the first found):
5790 *
5791 * [0, 1, 1].union([2, 1], [3, 1]) # => [0, 1, 2, 3]
5792 *
5793 * Preserves order (preserving the position of the first found):
5794 *
5795 * [3, 2, 1, 0].union([5, 3], [4, 2]) # => [3, 2, 1, 0, 5, 4]
5796 *
5797 * With no arguments given, returns a copy of +self+.
5798 *
5799 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
5800 */
5802 static VALUE
5804 {
5807 VALUE hash;
5813 }
5822 }
5828 }
5830 /*
5831 * call-seq:
5832 * intersect?(other_array) -> true or false
5833 *
5834 * Returns whether +other_array+ has at least one element that is +#eql?+ to some element of +self+:
5835 *
5836 * [1, 2, 3].intersect?([3, 4, 5]) # => true
5837 * [1, 2, 3].intersect?([4, 5, 6]) # => false
5838 *
5839 * Each element must correctly implement method <tt>#hash</tt>.
5840 *
5841 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
5842 */
5844 static VALUE
5846 {
5848 st_data_t vv;
5858 }
5860 }
5867 }
5878 }
5879 }
5882 }
5884 static VALUE
5886 {
5889 VALUE v;
5895 }
5896 }
5899 }
5901 static VALUE
5903 {
5908 VALUE v;
5915 }
5916 }
5919 }
5920 }
5923 }
5925 static VALUE
5927 {
5932 VALUE v;
5939 }
5940 }
5943 }
5944 }
5947 }
5949 static VALUE
5951 {
5956 VALUE v;
5963 }
5964 }
5967 }
5968 }
5971 }
5973 /*
5974 * call-seq:
5975 * max -> element
5976 * max(count) -> new_array
5977 * max {|a, b| ... } -> element
5978 * max(count) {|a, b| ... } -> new_array
5979 *
5980 * Returns one of the following:
5981 *
5982 * - The maximum-valued element from +self+.
5983 * - A new array of maximum-valued elements from +self+.
5984 *
5985 * Does not modify +self+.
5986 *
5987 * With no block given, each element in +self+ must respond to method <tt>#<=></tt>
5988 * with a numeric.
5989 *
5990 * With no argument and no block, returns the element in +self+
5991 * having the maximum value per method <tt>#<=></tt>:
5992 *
5993 * [1, 0, 3, 2].max # => 3
5994 *
5995 * With non-negative numeric argument +count+ and no block,
5996 * returns a new array with at most +count+ elements,
5997 * in descending order, per method <tt>#<=></tt>:
5998 *
5999 * [1, 0, 3, 2].max(3) # => [3, 2, 1]
6000 * [1, 0, 3, 2].max(3.0) # => [3, 2, 1]
6001 * [1, 0, 3, 2].max(9) # => [3, 2, 1, 0]
6002 * [1, 0, 3, 2].max(0) # => []
6003 *
6004 * With a block given, the block must return a numeric.
6005 *
6006 * With a block and no argument, calls the block <tt>self.size - 1</tt> times to compare elements;
6007 * returns the element having the maximum value per the block:
6008 *
6009 * ['0', '', '000', '00'].max {|a, b| a.size <=> b.size }
6010 * # => "000"
6011 *
6012 * With non-negative numeric argument +count+ and a block,
6013 * returns a new array with at most +count+ elements,
6014 * in descending order, per the block:
6015 *
6016 * ['0', '', '000', '00'].max(2) {|a, b| a.size <=> b.size }
6017 * # => ["000", "00"]
6018 *
6019 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
6020 */
6021 static VALUE
6023 {
6025 VALUE num;
6037 }
6038 }
6039 }
6045 }
6048 }
6051 }
6054 }
6055 }
6056 }
6059 }
6061 static VALUE
6063 {
6066 VALUE v;
6072 }
6073 }
6076 }
6078 static VALUE
6080 {
6085 VALUE a;
6092 }
6093 }
6096 }
6097 }
6100 }
6102 static VALUE
6104 {
6109 VALUE a;
6116 }
6117 }
6120 }
6121 }
6124 }
6126 static VALUE
6128 {
6133 VALUE a;
6140 }
6141 }
6144 }
6145 }
6148 }
6150 /*
6151 * call-seq:
6152 * min -> element
6153 * min(count) -> new_array
6154 * min {|a, b| ... } -> element
6155 * min(count) {|a, b| ... } -> new_array
6156 *
6157 * Returns one of the following:
6158 *
6159 * - The minimum-valued element from +self+.
6160 * - A new array of minimum-valued elements from +self+.
6161 *
6162 * Does not modify +self+.
6163 *
6164 * With no block given, each element in +self+ must respond to method <tt>#<=></tt>
6165 * with a numeric.
6166 *
6167 * With no argument and no block, returns the element in +self+
6168 * having the minimum value per method <tt>#<=></tt>:
6169 *
6170 * [1, 0, 3, 2].min # => 0
6171 *
6172 * With non-negative numeric argument +count+ and no block,
6173 * returns a new array with at most +count+ elements,
6174 * in ascending order, per method <tt>#<=></tt>:
6175 *
6176 * [1, 0, 3, 2].min(3) # => [0, 1, 2]
6177 * [1, 0, 3, 2].min(3.0) # => [0, 1, 2]
6178 * [1, 0, 3, 2].min(9) # => [0, 1, 2, 3]
6179 * [1, 0, 3, 2].min(0) # => []
6180 *
6181 * With a block given, the block must return a numeric.
6182 *
6183 * With a block and no argument, calls the block <tt>self.size - 1</tt> times to compare elements;
6184 * returns the element having the minimum value per the block:
6185 *
6186 * ['0', '', '000', '00'].min {|a, b| a.size <=> b.size }
6187 * # => ""
6188 *
6189 * With non-negative numeric argument +count+ and a block,
6190 * returns a new array with at most +count+ elements,
6191 * in ascending order, per the block:
6192 *
6193 * ['0', '', '000', '00'].min(2) {|a, b| a.size <=> b.size }
6194 * # => ["", "0"]
6195 *
6196 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
6197 */
6198 static VALUE
6200 {
6202 VALUE num;
6214 }
6215 }
6216 }
6222 }
6225 }
6228 }
6231 }
6232 }
6233 }
6236 }
6238 /*
6239 * call-seq:
6240 * minmax -> array
6241 * minmax {|a, b| ... } -> array
6242 *
6243 * Returns a 2-element array containing the minimum-valued and maximum-valued
6244 * elements from +self+;
6245 * does not modify +self+.
6246 *
6247 * With no block given, the minimum and maximum values are determined using method <tt>#<=></tt>:
6248 *
6249 * [1, 0, 3, 2].minmax # => [0, 3]
6250 *
6251 * With a block given, the block must return a numeric;
6252 * the block is called <tt>self.size - 1</tt> times to compare elements;
6253 * returns the elements having the minimum and maximum values per the block:
6254 *
6255 * ['0', '', '000', '00'].minmax {|a, b| a.size <=> b.size }
6256 * # => ["", "000"]
6257 *
6258 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
6259 */
6260 static VALUE
6262 {
6265 }
6267 }
6269 static int
6271 {
6274 }
6276 /*
6277 * call-seq:
6278 * uniq! -> self or nil
6279 * uniq! {|element| ... } -> self or nil
6280 *
6281 * Removes duplicate elements from +self+, the first occurrence always being retained;
6282 * returns +self+ if any elements removed, +nil+ otherwise.
6283 *
6284 * With no block given, identifies and removes elements using method <tt>eql?</tt>
6285 * to compare elements:
6286 *
6287 * a = [0, 0, 1, 1, 2, 2]
6288 * a.uniq! # => [0, 1, 2]
6289 * a.uniq! # => nil
6290 *
6291 * With a block given, calls the block for each element;
6292 * identifies and omits "duplicate" elements using method <tt>eql?</tt>
6293 * to compare <i>block return values</i>;
6294 * that is, an element is a duplicate if its block return value
6295 * is the same as that of a previous element:
6296 *
6297 * a = ['a', 'aa', 'aaa', 'b', 'bb', 'bbb']
6298 * a.uniq! {|element| element.size } # => ["a", "aa", "aaa"]
6299 * a.uniq! {|element| element.size } # => nil
6300 *
6301 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
6302 */
6303 static VALUE
6305 {
6306 VALUE hash;
6314 else
6320 }
6326 }
6331 }
6333 /*
6334 * call-seq:
6335 * uniq -> new_array
6336 * uniq {|element| ... } -> new_array
6337 *
6338 * Returns a new array containing those elements from +self+ that are not duplicates,
6339 * the first occurrence always being retained.
6340 *
6341 * With no block given, identifies and omits duplicate elements using method <tt>eql?</tt>
6342 * to compare elements:
6343 *
6344 * a = [0, 0, 1, 1, 2, 2]
6345 * a.uniq # => [0, 1, 2]
6346 *
6347 * With a block given, calls the block for each element;
6348 * identifies and omits "duplicate" elements using method <tt>eql?</tt>
6349 * to compare <i>block return values</i>;
6350 * that is, an element is a duplicate if its block return value
6351 * is the same as that of a previous element:
6352 *
6353 * a = ['a', 'aa', 'aaa', 'b', 'bb', 'bbb']
6354 * a.uniq {|element| element.size } # => ["a", "aa", "aaa"]
6355 *
6356 * Related: {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
6357 */
6359 static VALUE
6361 {
6367 }
6371 }
6375 }
6378 }
6380 /*
6381 * call-seq:
6382 * compact! -> self or nil
6383 *
6384 * Removes all +nil+ elements from +self+;
6385 * Returns +self+ if any elements are removed, +nil+ otherwise:
6386 *
6387 * a = [nil, 0, nil, false, nil, '', nil, [], nil, {}]
6388 * a.compact! # => [0, false, "", [], {}]
6389 * a # => [0, false, "", [], {}]
6390 * a.compact! # => nil
6391 *
6392 * Related: Array#compact;
6393 * see also {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
6394 */
6396 static VALUE
6398 {
6409 }
6413 }
6417 }
6419 /*
6420 * call-seq:
6421 * compact -> new_array
6422 *
6423 * Returns a new array containing only the non-+nil+ elements from +self+;
6424 * element order is preserved:
6425 *
6426 * a = [nil, 0, nil, false, nil, '', nil, [], nil, {}]
6427 * a.compact # => [0, false, "", [], {}]
6428 *
6429 * Related: Array#compact!;
6430 * see also {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
6431 */
6433 static VALUE
6435 {
6439 }
6441 /*
6442 * call-seq:
6443 * count -> integer
6444 * count(object) -> integer
6445 * count {|element| ... } -> integer
6446 *
6447 * Returns a count of specified elements.
6448 *
6449 * With no argument and no block, returns the count of all elements:
6450 *
6451 * [0, :one, 'two', 3, 3.0].count # => 5
6452 *
6453 * With argument +object+ given, returns the count of elements <tt>==</tt> to +object+:
6454 *
6455 * [0, :one, 'two', 3, 3.0].count(3) # => 2
6456 *
6457 * With no argument and a block given, calls the block with each element;
6458 * returns the count of elements for which the block returns a truthy value:
6459 *
6460 * [0, 1, 2, 3].count {|element| element > 1 } # => 2
6461 *
6462 * With argument +object+ and a block given, issues a warning, ignores the block,
6463 * and returns the count of elements <tt>==</tt> to +object+.
6464 *
6465 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
6466 */
6468 static VALUE
6470 {
6474 VALUE v;
6482 }
6483 }
6489 }
6492 }
6493 }
6496 }
6498 static VALUE
6500 {
6510 }
6511 }
6514 }
6528 }
6539 }
6544 }
6546 }
6549 }
6555 }
6557 }
6562 }
6563 }
6566 }
6569 }
6573 }
6577 }
6581 }
6583 /*
6584 * call-seq:
6585 * flatten!(depth = nil) -> self or nil
6586 *
6587 * Returns +self+ as a recursively flattening of +self+ to +depth+ levels of recursion;
6588 * +depth+ must be an
6589 * {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects],
6590 * or +nil+.
6591 * At each level of recursion:
6592 *
6593 * - Each element that is an array is "flattened"
6594 * (that is, replaced by its individual array elements).
6595 * - Each element that is not an array is unchanged
6596 * (even if the element is an object that has instance method +flatten+).
6597 *
6598 * Returns +nil+ if no elements were flattened.
6599 *
6600 * With non-negative integer argument +depth+, flattens recursively through +depth+ levels:
6601 *
6602 * a = [ 0, [ 1, [2, 3], 4 ], 5, {foo: 0}, Set.new([6, 7]) ]
6603 * a # => [0, [1, [2, 3], 4], 5, {:foo=>0}, #<Set: {6, 7}>]
6604 * a.dup.flatten!(1) # => [0, 1, [2, 3], 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6605 * a.dup.flatten!(1.1) # => [0, 1, [2, 3], 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6606 * a.dup.flatten!(2) # => [0, 1, 2, 3, 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6607 * a.dup.flatten!(3) # => [0, 1, 2, 3, 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6608 *
6609 * With +nil+ or negative argument +depth+, flattens all levels:
6610 *
6611 * a.dup.flatten! # => [0, 1, 2, 3, 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6612 * a.dup.flatten!(-1) # => [0, 1, 2, 3, 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6613 *
6614 * Related: Array#flatten;
6615 * see also {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
6616 */
6618 static VALUE
6620 {
6632 }
6638 }
6640 /*
6641 * call-seq:
6642 * flatten(depth = nil) -> new_array
6643 *
6644 * Returns a new array that is a recursive flattening of +self+
6645 * to +depth+ levels of recursion;
6646 * +depth+ must be an
6647 * {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects]
6648 * or +nil+.
6649 * At each level of recursion:
6650 *
6651 * - Each element that is an array is "flattened"
6652 * (that is, replaced by its individual array elements).
6653 * - Each element that is not an array is unchanged
6654 * (even if the element is an object that has instance method +flatten+).
6655 *
6656 * With non-negative integer argument +depth+, flattens recursively through +depth+ levels:
6657 *
6658 * a = [ 0, [ 1, [2, 3], 4 ], 5, {foo: 0}, Set.new([6, 7]) ]
6659 * a # => [0, [1, [2, 3], 4], 5, {:foo=>0}, #<Set: {6, 7}>]
6660 * a.flatten(0) # => [0, [1, [2, 3], 4], 5, {:foo=>0}, #<Set: {6, 7}>]
6661 * a.flatten(1 ) # => [0, 1, [2, 3], 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6662 * a.flatten(1.1) # => [0, 1, [2, 3], 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6663 * a.flatten(2) # => [0, 1, 2, 3, 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6664 * a.flatten(3) # => [0, 1, 2, 3, 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6665 *
6666 * With +nil+ or negative +depth+, flattens all levels.
6667 *
6668 * a.flatten # => [0, 1, 2, 3, 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6669 * a.flatten(-1) # => [0, 1, 2, 3, 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6670 *
6671 * Related: Array#flatten!;
6672 * see also {Methods for Converting}[rdoc-ref:Array@Methods+for+Converting].
6673 */
6675 static VALUE
6677 {
6679 VALUE result;
6684 }
6689 }
6692 }
6694 #define RAND_UPTO(max) (long)rb_random_ulong_limited((randgen), (max)-1)
6696 static VALUE
6698 {
6706 VALUE tmp;
6709 }
6713 }
6716 }
6718 static VALUE
6720 {
6724 }
6730 },
6732 };
6734 static VALUE
6736 {
6737 VALUE result;
6746 else
6750 }
6757 }
6758 }
6764 }
6765 }
6782 {
6786 }
6788 }
6789 memo_threshold =
6802 }
6805 }
6810 }
6811 });
6812 }
6824 }
6832 st_data_t value;
6837 }
6838 });
6839 });
6843 }
6854 }
6855 });
6857 }
6861 }
6863 static VALUE
6865 {
6867 }
6869 static VALUE
6871 {
6873 }
6875 static VALUE
6877 {
6882 }
6889 }
6891 /*
6892 * call-seq:
6893 * cycle(count = nil) {|element| ... } -> nil
6894 * cycle(count = nil) -> new_enumerator
6895 *
6896 * With a block given, may call the block, depending on the value of argument +count+;
6897 * +count+ must be an
6898 * {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects],
6899 * or +nil+.
6900 *
6901 * When +count+ is positive,
6902 * calls the block with each element, then does so repeatedly,
6903 * until it has done so +count+ times; returns +nil+:
6904 *
6905 * output = []
6906 * [0, 1].cycle(2) {|element| output.push(element) } # => nil
6907 * output # => [0, 1, 0, 1]
6908 *
6909 * When +count+ is zero or negative, does not call the block:
6910 *
6911 * [0, 1].cycle(0) {|element| fail 'Cannot happen' } # => nil
6912 * [0, 1].cycle(-1) {|element| fail 'Cannot happen' } # => nil
6913 *
6914 * When +count+ is +nil+, cycles forever:
6915 *
6916 * # Prints 0 and 1 forever.
6917 * [0, 1].cycle {|element| puts element }
6918 * [0, 1].cycle(nil) {|element| puts element }
6919 *
6920 * With no block given, returns a new Enumerator.
6921 *
6922 * Related: see {Methods for Iterating}[rdoc-ref:Array@Methods+for+Iterating].
6923 */
6924 static VALUE
6926 {
6934 }
6938 }
6943 }
6944 }
6946 }
6948 /*
6949 * Build a ruby array of the corresponding values and yield it to the
6950 * associated block.
6951 * Return the class of +values+ for reentry check.
6952 */
6953 static int
6955 {
6963 }
6965 /*
6966 * Compute permutations of +r+ elements of the set <code>[0..n-1]</code>.
6967 *
6968 * When we have a complete permutation of array indices, copy the values
6969 * at those indices into a new array and yield that array.
6970 *
6971 * n: the size of the set
6972 * r: the number of elements in each permutation
6973 * p: the array (of size r) that we're filling in
6974 * used: an array of booleans: whether a given index is already used
6975 * values: the Ruby array that holds the actual values to permute
6976 */
6977 static void
6979 {
6988 }
6997 }
7003 }
7004 }
7008 }
7009 }
7010 }
7012 /*
7013 * Returns the product of from, from-1, ..., from - how_many + 1.
7014 * https://en.wikipedia.org/wiki/Pochhammer_symbol
7015 */
7016 static VALUE
7018 {
7019 VALUE cnt;
7025 }
7026 }
7029 }
7031 }
7033 static VALUE
7035 {
7036 VALUE r;
7040 }
7043 }
7046 }
7051 }
7053 }
7055 static VALUE
7057 {
7062 }
7064 /*
7065 * call-seq:
7066 * permutation(count = self.size) {|permutation| ... } -> self
7067 * permutation(count = self.size) -> new_enumerator
7068 *
7069 * Iterates over permutations of the elements of +self+;
7070 * the order of permutations is indeterminate.
7071 *
7072 * With a block and an in-range positive integer argument +count+ (<tt>0 < count <= self.size</tt>) given,
7073 * calls the block with each permutation of +self+ of size +count+;
7074 * returns +self+:
7075 *
7076 * a = [0, 1, 2]
7077 * perms = []
7078 * a.permutation(1) {|perm| perms.push(perm) }
7079 * perms # => [[0], [1], [2]]
7080 *
7081 * perms = []
7082 * a.permutation(2) {|perm| perms.push(perm) }
7083 * perms # => [[0, 1], [0, 2], [1, 0], [1, 2], [2, 0], [2, 1]]
7084 *
7085 * perms = []
7086 * a.permutation(3) {|perm| perms.push(perm) }
7087 * perms # => [[0, 1, 2], [0, 2, 1], [1, 0, 2], [1, 2, 0], [2, 0, 1], [2, 1, 0]]
7088 *
7089 * When +count+ is zero, calls the block once with a new empty array:
7090 *
7091 * perms = []
7092 * a.permutation(0) {|perm| perms.push(perm) }
7093 * perms # => [[]]
7094 *
7095 * When +count+ is out of range (negative or larger than <tt>self.size</tt>),
7096 * does not call the block:
7097 *
7098 * a.permutation(-1) {|permutation| fail 'Cannot happen' }
7099 * a.permutation(4) {|permutation| fail 'Cannot happen' }
7100 *
7101 * With no block given, returns a new Enumerator.
7102 *
7103 * Related: {Methods for Iterating}[rdoc-ref:Array@Methods+for+Iterating].
7104 */
7106 static VALUE
7108 {
7112 RETURN_SIZED_ENUMERATOR(ary, argc, argv, rb_ary_permutation_size); /* Return enumerator if no block */
7118 /* no permutations: yield nothing */
7119 }
7122 }
7126 }
7127 }
7140 }
7142 }
7144 static void
7146 {
7154 }
7157 }
7162 }
7163 }
7165 static VALUE
7167 {
7172 }
7174 /*
7175 * call-seq:
7176 * combination(count) {|element| ... } -> self
7177 * combination(count) -> new_enumerator
7178 *
7179 * When a block and a positive
7180 * {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects]
7181 * argument +count+ (<tt>0 < count <= self.size</tt>)
7182 * are given, calls the block with each combination of +self+ of size +count+;
7183 * returns +self+:
7184 *
7185 * a = %w[a b c] # => ["a", "b", "c"]
7186 * a.combination(2) {|combination| p combination } # => ["a", "b", "c"]
7187 *
7188 * Output:
7189 *
7190 * ["a", "b"]
7191 * ["a", "c"]
7192 * ["b", "c"]
7193 *
7194 * The order of the yielded combinations is not guaranteed.
7195 *
7196 * When +count+ is zero, calls the block once with a new empty array:
7197 *
7198 * a.combination(0) {|combination| p combination }
7199 * [].combination(0) {|combination| p combination }
7200 *
7201 * Output:
7202 *
7203 * []
7204 * []
7205 *
7206 * When +count+ is negative or larger than +self.size+ and +self+ is non-empty,
7207 * does not call the block:
7208 *
7209 * a.combination(-1) {|combination| fail 'Cannot happen' } # => ["a", "b", "c"]
7210 * a.combination(4) {|combination| fail 'Cannot happen' } # => ["a", "b", "c"]
7211 *
7212 * With no block given, returns a new Enumerator.
7213 *
7214 * Related: Array#permutation;
7215 * see also {Methods for Iterating}[rdoc-ref:Array@Methods+for+Iterating].
7216 */
7218 static VALUE
7220 {
7227 /* yield nothing */
7228 }
7231 }
7235 }
7236 }
7246 }
7248 }
7250 /*
7251 * Compute repeated permutations of +r+ elements of the set
7252 * <code>[0..n-1]</code>.
7253 *
7254 * When we have a complete repeated permutation of array indices, copy the
7255 * values at those indices into a new array and yield that array.
7256 *
7257 * n: the size of the set
7258 * r: the number of elements in each permutation
7259 * p: the array (of size r) that we're filling in
7260 * values: the Ruby array that holds the actual values to permute
7261 */
7262 static void
7264 {
7272 }
7277 }
7278 }
7282 }
7283 }
7285 static VALUE
7287 {
7293 }
7296 }
7298 }
7300 /*
7301 * call-seq:
7302 * repeated_permutation(size) {|permutation| ... } -> self
7303 * repeated_permutation(size) -> new_enumerator
7304 *
7305 * With a block given, calls the block with each repeated permutation of length +size+
7306 * of the elements of +self+;
7307 * each permutation is an array;
7308 * returns +self+. The order of the permutations is indeterminate.
7309 *
7310 * If a positive integer argument +size+ is given,
7311 * calls the block with each +size+-tuple repeated permutation of the elements of +self+.
7312 * The number of permutations is <tt>self.size**size</tt>.
7313 *
7314 * Examples:
7315 *
7316 * - +size+ is 1:
7317 *
7318 * p = []
7319 * [0, 1, 2].repeated_permutation(1) {|permutation| p.push(permutation) }
7320 * p # => [[0], [1], [2]]
7321 *
7322 * - +size+ is 2:
7323 *
7324 * p = []
7325 * [0, 1, 2].repeated_permutation(2) {|permutation| p.push(permutation) }
7326 * p # => [[0, 0], [0, 1], [0, 2], [1, 0], [1, 1], [1, 2], [2, 0], [2, 1], [2, 2]]
7327 *
7328 * If +size+ is zero, calls the block once with an empty array.
7329 *
7330 * If +size+ is negative, does not call the block:
7331 *
7332 * [0, 1, 2].repeated_permutation(-1) {|permutation| fail 'Cannot happen' }
7333 *
7334 * With no block given, returns a new Enumerator.
7335 *
7336 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
7337 */
7338 static VALUE
7340 {
7344 RETURN_SIZED_ENUMERATOR(ary, 1, &num, rb_ary_repeated_permutation_size); /* Return Enumerator if no block */
7348 /* no permutations: yield nothing */
7349 }
7352 }
7356 }
7357 }
7367 }
7369 }
7371 static void
7373 {
7381 }
7386 }
7387 }
7391 }
7392 }
7394 static VALUE
7396 {
7401 }
7403 }
7405 /*
7406 * call-seq:
7407 * repeated_combination(size) {|combination| ... } -> self
7408 * repeated_combination(size) -> new_enumerator
7409 *
7410 * With a block given, calls the block with each repeated combination of length +size+
7411 * of the elements of +self+;
7412 * each combination is an array;
7413 * returns +self+. The order of the combinations is indeterminate.
7414 *
7415 * If a positive integer argument +size+ is given,
7416 * calls the block with each +size+-tuple repeated combination of the elements of +self+.
7417 * The number of combinations is <tt>(size+1)(size+2)/2</tt>.
7418 *
7419 * Examples:
7420 *
7421 * - +size+ is 1:
7422 *
7423 * c = []
7424 * [0, 1, 2].repeated_combination(1) {|combination| c.push(combination) }
7425 * c # => [[0], [1], [2]]
7426 *
7427 * - +size+ is 2:
7428 *
7429 * c = []
7430 * [0, 1, 2].repeated_combination(2) {|combination| c.push(combination) }
7431 * c # => [[0, 0], [0, 1], [0, 2], [1, 1], [1, 2], [2, 2]]
7432 *
7433 * If +size+ is zero, calls the block once with an empty array.
7434 *
7435 * If +size+ is negative, does not call the block:
7436 *
7437 * [0, 1, 2].repeated_combination(-1) {|combination| fail 'Cannot happen' }
7438 *
7439 * With no block given, returns a new Enumerator.
7440 *
7441 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
7442 */
7444 static VALUE
7446 {
7450 RETURN_SIZED_ENUMERATOR(ary, 1, &num, rb_ary_repeated_combination_size); /* Return enumerator if no block */
7453 /* yield nothing */
7454 }
7457 }
7461 }
7462 }
7464 /* yield nothing */
7465 }
7475 }
7477 }
7479 /*
7480 * call-seq:
7481 * product(*other_arrays) -> new_array
7482 * product(*other_arrays) {|combination| ... } -> self
7483 *
7484 * Computes all combinations of elements from all the arrays,
7485 * including both +self+ and +other_arrays+:
7486 *
7487 * - The number of combinations is the product of the sizes of all the arrays,
7488 * including both +self+ and +other_arrays+.
7489 * - The order of the returned combinations is indeterminate.
7490 *
7491 * With no block given, returns the combinations as an array of arrays:
7492 *
7493 * p = [0, 1].product([2, 3])
7494 * # => [[0, 2], [0, 3], [1, 2], [1, 3]]
7495 * p.size # => 4
7496 * p = [0, 1].product([2, 3], [4, 5])
7497 * # => [[0, 2, 4], [0, 2, 5], [0, 3, 4], [0, 3, 5], [1, 2, 4], [1, 2, 5], [1, 3, 4], [1, 3,...
7498 * p.size # => 8
7499 *
7500 * If +self+ or any argument is empty, returns an empty array:
7501 *
7502 * [].product([2, 3], [4, 5]) # => []
7503 * [0, 1].product([2, 3], []) # => []
7504 *
7505 * If no argument is given, returns an array of 1-element arrays,
7506 * each containing an element of +self+:
7507 *
7508 * a.product # => [[0], [1], [2]]
7509 *
7510 * With a block given, calls the block with each combination; returns +self+:
7511 *
7512 * p = []
7513 * [0, 1].product([2, 3]) {|combination| p.push(combination) }
7514 * p # => [[0, 2], [0, 3], [1, 2], [1, 3]]
7515 *
7516 * If +self+ or any argument is empty, does not call the block:
7517 *
7518 * [].product([2, 3], [4, 5]) {|combination| fail 'Cannot happen' }
7519 * # => []
7520 * [0, 1].product([2, 3], []) {|combination| fail 'Cannot happen' }
7521 * # => [0, 1]
7522 *
7523 * If no argument is given, calls the block with each element of +self+ as a 1-element array:
7524 *
7525 * p = []
7526 * [0, 1].product {|combination| p.push(combination) }
7527 * p # => [[0], [1]]
7528 *
7529 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
7530 */
7532 static VALUE
7534 {
7546 /* initialize the arrays of arrays */
7552 /* initialize the counters for the arrays */
7555 /* Otherwise, allocate and fill in an array of results */
7557 /* Make defensive copies of arrays; exit if any is empty */
7561 }
7562 }
7564 /* Compute the length of the result array; return [] if any is empty */
7570 }
7574 }
7576 }
7579 /* fill in one subarray */
7583 }
7585 /* put it on the result array */
7591 }
7594 }
7595 }
7598 }
7600 /*
7601 * Increment the last counter. If it overflows, reset to 0
7602 * and increment the one before it.
7603 */
7608 /* If the first counter overflows, we are done */
7611 }
7612 }
7614 done:
7618 }
7620 /*
7621 * call-seq:
7622 * take(count) -> new_array
7623 *
7624 * Returns a new array containing the first +count+ element of +self+
7625 * (as available);
7626 * +count+ must be a non-negative numeric;
7627 * does not modify +self+:
7628 *
7629 * a = ['a', 'b', 'c', 'd']
7630 * a.take(2) # => ["a", "b"]
7631 * a.take(2.1) # => ["a", "b"]
7632 * a.take(50) # => ["a", "b", "c", "d"]
7633 * a.take(0) # => []
7634 *
7635 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
7636 */
7638 static VALUE
7640 {
7644 }
7646 }
7648 /*
7649 * call-seq:
7650 * take_while {|element| ... } -> new_array
7651 * take_while -> new_enumerator
7652 *
7653 * With a block given, calls the block with each successive element of +self+;
7654 * stops iterating if the block returns +false+ or +nil+;
7655 * returns a new array containing those elements for which the block returned a truthy value:
7656 *
7657 * a = [0, 1, 2, 3, 4, 5]
7658 * a.take_while {|element| element < 3 } # => [0, 1, 2]
7659 * a.take_while {|element| true } # => [0, 1, 2, 3, 4, 5]
7660 * a.take_while {|element| false } # => []
7661 *
7662 * With no block given, returns a new Enumerator.
7663 *
7664 * Does not modify +self+.
7665 *
7666 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
7667 */
7669 static VALUE
7671 {
7677 }
7679 }
7681 /*
7682 * call-seq:
7683 * drop(count) -> new_array
7684 *
7685 * Returns a new array containing all but the first +count+ element of +self+,
7686 * where +count+ is a non-negative integer;
7687 * does not modify +self+.
7688 *
7689 * Examples:
7690 *
7691 * a = [0, 1, 2, 3, 4, 5]
7692 * a.drop(0) # => [0, 1, 2, 3, 4, 5]
7693 * a.drop(1) # => [1, 2, 3, 4, 5]
7694 * a.drop(2) # => [2, 3, 4, 5]
7695 * a.drop(9) # => []
7696 *
7697 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
7698 */
7700 static VALUE
7702 {
7703 VALUE result;
7707 }
7712 }
7714 /*
7715 * call-seq:
7716 * drop_while {|element| ... } -> new_array
7717 * drop_while -> new_enumerator
7718 *
7719 * With a block given, calls the block with each successive element of +self+;
7720 * stops if the block returns +false+ or +nil+;
7721 * returns a new array _omitting_ those elements for which the block returned a truthy value;
7722 * does not modify +self+:
7723 *
7724 * a = [0, 1, 2, 3, 4, 5]
7725 * a.drop_while {|element| element < 3 } # => [3, 4, 5]
7726 *
7727 * With no block given, returns a new Enumerator.
7728 *
7729 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
7730 */
7732 static VALUE
7734 {
7740 }
7742 }
7744 /*
7745 * call-seq:
7746 * any? -> true or false
7747 * any?(object) -> true or false
7748 * any? {|element| ... } -> true or false
7749 *
7750 * Returns whether for any element of +self+, a given criterion is satisfied.
7751 *
7752 * With no block and no argument, returns whether any element of +self+ is truthy:
7753 *
7754 * [nil, false, []].any? # => true # Array object is truthy.
7755 * [nil, false, {}].any? # => true # Hash object is truthy.
7756 * [nil, false, ''].any? # => true # String object is truthy.
7757 * [nil, false].any? # => false # Nil and false are not truthy.
7758 *
7759 * With argument +object+ given,
7760 * returns whether <tt>object === ele</tt> for any element +ele+ in +self+:
7761 *
7762 * [nil, false, 0].any?(0) # => true
7763 * [nil, false, 1].any?(0) # => false
7764 * [nil, false, 'food'].any?(/foo/) # => true
7765 * [nil, false, 'food'].any?(/bar/) # => false
7766 *
7767 * With a block given,
7768 * calls the block with each element in +self+;
7769 * returns whether the block returns any truthy value:
7770 *
7771 * [0, 1, 2].any? {|ele| ele < 1 } # => true
7772 * [0, 1, 2].any? {|ele| ele < 0 } # => false
7773 *
7774 * With both a block and argument +object+ given,
7775 * ignores the block and uses +object+ as above.
7776 *
7777 * <b>Special case</b>: returns +false+ if +self+ is empty
7778 * (regardless of any given argument or block).
7779 *
7780 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
7781 */
7783 static VALUE
7785 {
7793 }
7796 }
7797 }
7801 }
7802 }
7806 }
7807 }
7809 }
7811 /*
7812 * call-seq:
7813 * all? -> true or false
7814 * all?(object) -> true or false
7815 * all? {|element| ... } -> true or false
7816 *
7817 * Returns whether for every element of +self+,
7818 * a given criterion is satisfied.
7819 *
7820 * With no block and no argument,
7821 * returns whether every element of +self+ is truthy:
7822 *
7823 * [[], {}, '', 0, 0.0, Object.new].all? # => true # All truthy objects.
7824 * [[], {}, '', 0, 0.0, nil].all? # => false # nil is not truthy.
7825 * [[], {}, '', 0, 0.0, false].all? # => false # false is not truthy.
7826 *
7827 * With argument +object+ given, returns whether <tt>object === ele</tt>
7828 * for every element +ele+ in +self+:
7829 *
7830 * [0, 0, 0].all?(0) # => true
7831 * [0, 1, 2].all?(1) # => false
7832 * ['food', 'fool', 'foot'].all?(/foo/) # => true
7833 * ['food', 'drink'].all?(/foo/) # => false
7834 *
7835 * With a block given, calls the block with each element in +self+;
7836 * returns whether the block returns only truthy values:
7837 *
7838 * [0, 1, 2].all? { |ele| ele < 3 } # => true
7839 * [0, 1, 2].all? { |ele| ele < 2 } # => false
7840 *
7841 * With both a block and argument +object+ given,
7842 * ignores the block and uses +object+ as above.
7843 *
7844 * <b>Special case</b>: returns +true+ if +self+ is empty
7845 * (regardless of any given argument or block).
7846 *
7847 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
7848 */
7850 static VALUE
7852 {
7860 }
7863 }
7864 }
7868 }
7869 }
7873 }
7874 }
7876 }
7878 /*
7879 * call-seq:
7880 * none? -> true or false
7881 * none?(object) -> true or false
7882 * none? {|element| ... } -> true or false
7883 *
7884 * Returns +true+ if no element of +self+ meets a given criterion, +false+ otherwise.
7885 *
7886 * With no block given and no argument, returns +true+ if +self+ has no truthy elements,
7887 * +false+ otherwise:
7888 *
7889 * [nil, false].none? # => true
7890 * [nil, 0, false].none? # => false
7891 * [].none? # => true
7892 *
7893 * With argument +object+ given, returns +false+ if for any element +element+,
7894 * <tt>object === element</tt>; +true+ otherwise:
7895 *
7896 * ['food', 'drink'].none?(/bar/) # => true
7897 * ['food', 'drink'].none?(/foo/) # => false
7898 * [].none?(/foo/) # => true
7899 * [0, 1, 2].none?(3) # => true
7900 * [0, 1, 2].none?(1) # => false
7901 *
7902 * With a block given, calls the block with each element in +self+;
7903 * returns +true+ if the block returns no truthy value, +false+ otherwise:
7904 *
7905 * [0, 1, 2].none? {|element| element > 3 } # => true
7906 * [0, 1, 2].none? {|element| element > 1 } # => false
7907 *
7908 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
7909 */
7911 static VALUE
7913 {
7921 }
7924 }
7925 }
7929 }
7930 }
7934 }
7935 }
7937 }
7939 /*
7940 * call-seq:
7941 * one? -> true or false
7942 * one? {|element| ... } -> true or false
7943 * one?(object) -> true or false
7944 *
7945 * Returns +true+ if exactly one element of +self+ meets a given criterion.
7946 *
7947 * With no block given and no argument, returns +true+ if +self+ has exactly one truthy element,
7948 * +false+ otherwise:
7949 *
7950 * [nil, 0].one? # => true
7951 * [0, 0].one? # => false
7952 * [nil, nil].one? # => false
7953 * [].one? # => false
7954 *
7955 * With a block given, calls the block with each element in +self+;
7956 * returns +true+ if the block a truthy value for exactly one element, +false+ otherwise:
7957 *
7958 * [0, 1, 2].one? {|element| element > 0 } # => false
7959 * [0, 1, 2].one? {|element| element > 1 } # => true
7960 * [0, 1, 2].one? {|element| element > 2 } # => false
7961 *
7962 * With argument +object+ given, returns +true+ if for exactly one element +element+, <tt>object === element</tt>;
7963 * +false+ otherwise:
7964 *
7965 * [0, 1, 2].one?(0) # => true
7966 * [0, 0, 1].one?(0) # => false
7967 * [1, 1, 2].one?(0) # => false
7968 * ['food', 'drink'].one?(/bar/) # => false
7969 * ['food', 'drink'].one?(/foo/) # => true
7970 * [].one?(/foo/) # => false
7971 *
7972 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
7973 */
7975 static VALUE
7977 {
7986 }
7991 }
7992 }
7993 }
7999 }
8000 }
8001 }
8007 }
8008 }
8009 }
8011 }
8013 /*
8014 * call-seq:
8015 * array.dig(index, *identifiers) -> object
8016 *
8017 * Finds and returns the object in nested object
8018 * specified by +index+ and +identifiers+;
8019 * the nested objects may be instances of various classes.
8020 * See {Dig Methods}[rdoc-ref:dig_methods.rdoc].
8021 *
8022 * Examples:
8023 *
8024 * a = [:foo, [:bar, :baz, [:bat, :bam]]]
8025 * a.dig(1) # => [:bar, :baz, [:bat, :bam]]
8026 * a.dig(1, 2) # => [:bat, :bam]
8027 * a.dig(1, 2, 0) # => :bat
8028 * a.dig(1, 2, 3) # => nil
8029 *
8030 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
8031 */
8033 static VALUE
8035 {
8041 }
8045 {
8050 }
8053 }
8055 }
8057 /*
8058 * call-seq:
8059 * sum(init = 0) -> object
8060 * sum(init = 0) {|element| ... } -> object
8061 *
8062 * With no block given, returns the sum of +init+ and all elements of +self+;
8063 * for array +array+ and value +init+, equivalent to:
8064 *
8065 * sum = init
8066 * array.each {|element| sum += element }
8067 * sum
8068 *
8069 * For example, <tt>[e0, e1, e2].sum</tt> returns <tt>init + e0 + e1 + e2</tt>.
8070 *
8071 * Examples:
8072 *
8073 * [0, 1, 2, 3].sum # => 6
8074 * [0, 1, 2, 3].sum(100) # => 106
8075 * ['abc', 'def', 'ghi'].sum('jkl') # => "jklabcdefghi"
8076 * [[:foo, :bar], ['foo', 'bar']].sum([2, 3])
8077 * # => [2, 3, :foo, :bar, "foo", "bar"]
8078 *
8079 * The +init+ value and elements need not be numeric, but must all be <tt>+</tt>-compatible:
8080 *
8081 * # Raises TypeError: Array can't be coerced into Integer.
8082 * [[:foo, :bar], ['foo', 'bar']].sum(2)
8083 *
8084 * With a block given, calls the block with each element of +self+;
8085 * the block's return value (instead of the element itself) is used as the addend:
8086 *
8087 * ['zero', 1, :two].sum('Coerced and concatenated: ') {|element| element.to_s }
8088 * # => "Coerced and concatenated: zero1two"
8089 *
8090 * Notes:
8091 *
8092 * - Array#join and Array#flatten may be faster than Array#sum
8093 * for an array of strings or an array of arrays.
8094 * - Array#sum method may not respect method redefinition of "+" methods such as Integer#+.
8095 *
8096 */
8098 static VALUE
8100 {
8118 }
8129 }
8130 }
8136 else
8138 }
8139 else
8141 }
8145 not_exact:
8149 /*
8150 * Kahan-Babuska balancing compensated summation algorithm
8151 * See https://link.springer.com/article/10.1007/s00607-005-0139-x
8152 */
8164 has_float_value:
8172 else
8179 }
8183 else
8186 }
8192 else
8195 }
8199 not_float:
8201 }
8204 init_is_a_value:
8209 has_some_value:
8211 }
8213 }
8215 /* :nodoc: */
8216 static VALUE
8218 {
8220 }
8222 /*
8223 * An \Array object is an ordered, integer-indexed collection of objects,
8224 * called _elements_;
8225 * the object represents
8226 * an {array data structure}[https://en.wikipedia.org/wiki/Array_(data_structure)].
8227 *
8228 * An element may be any object (even another array);
8229 * elements may be any mixture of objects of different types.
8230 *
8231 * Important data structures that use arrays include:
8232 *
8233 * - {Coordinate vector}[https://en.wikipedia.org/wiki/Coordinate_vector].
8234 * - {Matrix}[https://en.wikipedia.org/wiki/Matrix_(mathematics)].
8235 * - {Heap}[https://en.wikipedia.org/wiki/Heap_(data_structure)].
8236 * - {Hash table}[https://en.wikipedia.org/wiki/Hash_table].
8237 * - {Deque (double-ended queue)}[https://en.wikipedia.org/wiki/Double-ended_queue].
8238 * - {Queue}[https://en.wikipedia.org/wiki/Queue_(abstract_data_type)].
8239 * - {Stack}[https://en.wikipedia.org/wiki/Stack_(abstract_data_type)].
8240 *
8241 * There are also array-like data structures:
8242 *
8243 * - {Associative array}[https://en.wikipedia.org/wiki/Associative_array] (see Hash).
8244 * - {Directory}[https://en.wikipedia.org/wiki/Directory_(computing)] (see Dir).
8245 * - {Environment}[https://en.wikipedia.org/wiki/Environment_variable] (see ENV).
8246 * - {Set}[https://en.wikipedia.org/wiki/Set_(abstract_data_type)] (see Set).
8247 * - {String}[https://en.wikipedia.org/wiki/String_(computer_science)] (see String).
8248 *
8249 * == \Array Indexes
8250 *
8251 * \Array indexing starts at 0, as in C or Java.
8252 *
8253 * A non-negative index is an offset from the first element:
8254 *
8255 * - Index 0 indicates the first element.
8256 * - Index 1 indicates the second element.
8257 * - ...
8258 *
8259 * A negative index is an offset, backwards, from the end of the array:
8260 *
8261 * - Index -1 indicates the last element.
8262 * - Index -2 indicates the next-to-last element.
8263 * - ...
8264 *
8265 *
8266 * === In-Range and Out-of-Range Indexes
8267 *
8268 * A non-negative index is <i>in range</i> if and only if it is smaller than
8269 * the size of the array. For a 3-element array:
8270 *
8271 * - Indexes 0 through 2 are in range.
8272 * - Index 3 is out of range.
8273 *
8274 * A negative index is <i>in range</i> if and only if its absolute value is
8275 * not larger than the size of the array. For a 3-element array:
8276 *
8277 * - Indexes -1 through -3 are in range.
8278 * - Index -4 is out of range.
8279 *
8280 * === Effective Index
8281 *
8282 * Although the effective index into an array is always an integer,
8283 * some methods (both within class \Array and elsewhere)
8284 * accept one or more non-integer arguments that are
8285 * {integer-convertible objects}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects].
8286 *
8287 * == Creating Arrays
8288 *
8289 * You can create an \Array object explicitly with:
8290 *
8291 * - An {array literal}[rdoc-ref:syntax/literals.rdoc@Array+Literals]:
8292 *
8293 * [1, 'one', :one, [2, 'two', :two]]
8294 *
8295 * - A {%w or %W string-array Literal}[rdoc-ref:syntax/literals.rdoc@25w+and+-25W-3A+String-Array+Literals]:
8296 *
8297 * %w[foo bar baz] # => ["foo", "bar", "baz"]
8298 * %w[1 % *] # => ["1", "%", "*"]
8299 *
8300 * - A {%i or %I symbol-array Literal}[rdoc-ref:syntax/literals.rdoc@25i+and+-25I-3A+Symbol-Array+Literals]:
8301 *
8302 * %i[foo bar baz] # => [:foo, :bar, :baz]
8303 * %i[1 % *] # => [:"1", :%, :*]
8304 *
8305 * - \Method Kernel#Array:
8306 *
8307 * Array(["a", "b"]) # => ["a", "b"]
8308 * Array(1..5) # => [1, 2, 3, 4, 5]
8309 * Array(key: :value) # => [[:key, :value]]
8310 * Array(nil) # => []
8311 * Array(1) # => [1]
8312 * Array({:a => "a", :b => "b"}) # => [[:a, "a"], [:b, "b"]]
8313 *
8314 * - \Method Array.new:
8315 *
8316 * Array.new # => []
8317 * Array.new(3) # => [nil, nil, nil]
8318 * Array.new(4) {Hash.new} # => [{}, {}, {}, {}]
8319 * Array.new(3, true) # => [true, true, true]
8320 *
8321 * Note that the last example above populates the array
8322 * with references to the same object.
8323 * This is recommended only in cases where that object is a natively immutable object
8324 * such as a symbol, a numeric, +nil+, +true+, or +false+.
8325 *
8326 * Another way to create an array with various objects, using a block;
8327 * this usage is safe for mutable objects such as hashes, strings or
8328 * other arrays:
8329 *
8330 * Array.new(4) {|i| i.to_s } # => ["0", "1", "2", "3"]
8331 *
8332 * Here is a way to create a multi-dimensional array:
8333 *
8334 * Array.new(3) {Array.new(3)}
8335 * # => [[nil, nil, nil], [nil, nil, nil], [nil, nil, nil]]
8336 *
8337 * A number of Ruby methods, both in the core and in the standard library,
8338 * provide instance method +to_a+, which converts an object to an array.
8339 *
8340 * - ARGF#to_a
8341 * - Array#to_a
8342 * - Enumerable#to_a
8343 * - Hash#to_a
8344 * - MatchData#to_a
8345 * - NilClass#to_a
8346 * - OptionParser#to_a
8347 * - Range#to_a
8348 * - Set#to_a
8349 * - Struct#to_a
8350 * - Time#to_a
8351 * - Benchmark::Tms#to_a
8352 * - CSV::Table#to_a
8353 * - Enumerator::Lazy#to_a
8354 * - Gem::List#to_a
8355 * - Gem::NameTuple#to_a
8356 * - Gem::Platform#to_a
8357 * - Gem::RequestSet::Lockfile::Tokenizer#to_a
8358 * - Gem::SourceList#to_a
8359 * - OpenSSL::X509::Extension#to_a
8360 * - OpenSSL::X509::Name#to_a
8361 * - Racc::ISet#to_a
8362 * - Rinda::RingFinger#to_a
8363 * - Ripper::Lexer::Elem#to_a
8364 * - RubyVM::InstructionSequence#to_a
8365 * - YAML::DBM#to_a
8366 *
8367 * == Example Usage
8368 *
8369 * In addition to the methods it mixes in through the Enumerable module, the
8370 * +Array+ class has proprietary methods for accessing, searching and otherwise
8371 * manipulating arrays.
8372 *
8373 * Some of the more common ones are illustrated below.
8374 *
8375 * == Accessing Elements
8376 *
8377 * Elements in an array can be retrieved using the Array#[] method. It can
8378 * take a single integer argument (a numeric index), a pair of arguments
8379 * (start and length) or a range. Negative indices start counting from the end,
8380 * with -1 being the last element.
8381 *
8382 * arr = [1, 2, 3, 4, 5, 6]
8383 * arr[2] #=> 3
8384 * arr[100] #=> nil
8385 * arr[-3] #=> 4
8386 * arr[2, 3] #=> [3, 4, 5]
8387 * arr[1..4] #=> [2, 3, 4, 5]
8388 * arr[1..-3] #=> [2, 3, 4]
8389 *
8390 * Another way to access a particular array element is by using the #at method
8391 *
8392 * arr.at(0) #=> 1
8393 *
8394 * The #slice method works in an identical manner to Array#[].
8395 *
8396 * To raise an error for indices outside of the array bounds or else to
8397 * provide a default value when that happens, you can use #fetch.
8398 *
8399 * arr = ['a', 'b', 'c', 'd', 'e', 'f']
8400 * arr.fetch(100) #=> IndexError: index 100 outside of array bounds: -6...6
8401 * arr.fetch(100, "oops") #=> "oops"
8402 *
8403 * The special methods #first and #last will return the first and last
8404 * elements of an array, respectively.
8405 *
8406 * arr.first #=> 1
8407 * arr.last #=> 6
8408 *
8409 * To return the first +n+ elements of an array, use #take
8410 *
8411 * arr.take(3) #=> [1, 2, 3]
8412 *
8413 * #drop does the opposite of #take, by returning the elements after +n+
8414 * elements have been dropped:
8415 *
8416 * arr.drop(3) #=> [4, 5, 6]
8417 *
8418 * == Obtaining Information about an +Array+
8419 *
8420 * Arrays keep track of their own length at all times. To query an array
8421 * about the number of elements it contains, use #length, #count or #size.
8422 *
8423 * browsers = ['Chrome', 'Firefox', 'Safari', 'Opera', 'IE']
8424 * browsers.length #=> 5
8425 * browsers.count #=> 5
8426 *
8427 * To check whether an array contains any elements at all
8428 *
8429 * browsers.empty? #=> false
8430 *
8431 * To check whether a particular item is included in the array
8432 *
8433 * browsers.include?('Konqueror') #=> false
8434 *
8435 * == Adding Items to Arrays
8436 *
8437 * Items can be added to the end of an array by using either #push or #<<
8438 *
8439 * arr = [1, 2, 3, 4]
8440 * arr.push(5) #=> [1, 2, 3, 4, 5]
8441 * arr << 6 #=> [1, 2, 3, 4, 5, 6]
8442 *
8443 * #unshift will add a new item to the beginning of an array.
8444 *
8445 * arr.unshift(0) #=> [0, 1, 2, 3, 4, 5, 6]
8446 *
8447 * With #insert you can add a new element to an array at any position.
8448 *
8449 * arr.insert(3, 'apple') #=> [0, 1, 2, 'apple', 3, 4, 5, 6]
8450 *
8451 * Using the #insert method, you can also insert multiple values at once:
8452 *
8453 * arr.insert(3, 'orange', 'pear', 'grapefruit')
8454 * #=> [0, 1, 2, "orange", "pear", "grapefruit", "apple", 3, 4, 5, 6]
8455 *
8456 * == Removing Items from an +Array+
8457 *
8458 * The method #pop removes the last element in an array and returns it:
8459 *
8460 * arr = [1, 2, 3, 4, 5, 6]
8461 * arr.pop #=> 6
8462 * arr #=> [1, 2, 3, 4, 5]
8463 *
8464 * To retrieve and at the same time remove the first item, use #shift:
8465 *
8466 * arr.shift #=> 1
8467 * arr #=> [2, 3, 4, 5]
8468 *
8469 * To delete an element at a particular index:
8470 *
8471 * arr.delete_at(2) #=> 4
8472 * arr #=> [2, 3, 5]
8473 *
8474 * To delete a particular element anywhere in an array, use #delete:
8475 *
8476 * arr = [1, 2, 2, 3]
8477 * arr.delete(2) #=> 2
8478 * arr #=> [1,3]
8479 *
8480 * A useful method if you need to remove +nil+ values from an array is
8481 * #compact:
8482 *
8483 * arr = ['foo', 0, nil, 'bar', 7, 'baz', nil]
8484 * arr.compact #=> ['foo', 0, 'bar', 7, 'baz']
8485 * arr #=> ['foo', 0, nil, 'bar', 7, 'baz', nil]
8486 * arr.compact! #=> ['foo', 0, 'bar', 7, 'baz']
8487 * arr #=> ['foo', 0, 'bar', 7, 'baz']
8488 *
8489 * Another common need is to remove duplicate elements from an array.
8490 *
8491 * It has the non-destructive #uniq, and destructive method #uniq!
8492 *
8493 * arr = [2, 5, 6, 556, 6, 6, 8, 9, 0, 123, 556]
8494 * arr.uniq #=> [2, 5, 6, 556, 8, 9, 0, 123]
8495 *
8496 * == Iterating over Arrays
8497 *
8498 * Like all classes that include the Enumerable module, +Array+ has an each
8499 * method, which defines what elements should be iterated over and how. In
8500 * case of Array's #each, all elements in the +Array+ instance are yielded to
8501 * the supplied block in sequence.
8502 *
8503 * Note that this operation leaves the array unchanged.
8504 *
8505 * arr = [1, 2, 3, 4, 5]
8506 * arr.each {|a| print a -= 10, " "}
8507 * # prints: -9 -8 -7 -6 -5
8508 * #=> [1, 2, 3, 4, 5]
8509 *
8510 * Another sometimes useful iterator is #reverse_each which will iterate over
8511 * the elements in the array in reverse order.
8512 *
8513 * words = %w[first second third fourth fifth sixth]
8514 * str = ""
8515 * words.reverse_each {|word| str += "#{word} "}
8516 * p str #=> "sixth fifth fourth third second first "
8517 *
8518 * The #map method can be used to create a new array based on the original
8519 * array, but with the values modified by the supplied block:
8520 *
8521 * arr.map {|a| 2*a} #=> [2, 4, 6, 8, 10]
8522 * arr #=> [1, 2, 3, 4, 5]
8523 * arr.map! {|a| a**2} #=> [1, 4, 9, 16, 25]
8524 * arr #=> [1, 4, 9, 16, 25]
8525 *
8526 *
8527 * == Selecting Items from an +Array+
8528 *
8529 * Elements can be selected from an array according to criteria defined in a
8530 * block. The selection can happen in a destructive or a non-destructive
8531 * manner. While the destructive operations will modify the array they were
8532 * called on, the non-destructive methods usually return a new array with the
8533 * selected elements, but leave the original array unchanged.
8534 *
8535 * === Non-destructive Selection
8536 *
8537 * arr = [1, 2, 3, 4, 5, 6]
8538 * arr.select {|a| a > 3} #=> [4, 5, 6]
8539 * arr.reject {|a| a < 3} #=> [3, 4, 5, 6]
8540 * arr.drop_while {|a| a < 4} #=> [4, 5, 6]
8541 * arr #=> [1, 2, 3, 4, 5, 6]
8542 *
8543 * === Destructive Selection
8544 *
8545 * #select! and #reject! are the corresponding destructive methods to #select
8546 * and #reject
8547 *
8548 * Similar to #select vs. #reject, #delete_if and #keep_if have the exact
8549 * opposite result when supplied with the same block:
8550 *
8551 * arr.delete_if {|a| a < 4} #=> [4, 5, 6]
8552 * arr #=> [4, 5, 6]
8553 *
8554 * arr = [1, 2, 3, 4, 5, 6]
8555 * arr.keep_if {|a| a < 4} #=> [1, 2, 3]
8556 * arr #=> [1, 2, 3]
8557 *
8558 * == What's Here
8559 *
8560 * First, what's elsewhere. \Class +Array+:
8561 *
8562 * - Inherits from {class Object}[rdoc-ref:Object@What-27s+Here].
8563 * - Includes {module Enumerable}[rdoc-ref:Enumerable@What-27s+Here],
8564 * which provides dozens of additional methods.
8565 *
8566 * Here, class +Array+ provides methods that are useful for:
8567 *
8568 * - {Creating an Array}[rdoc-ref:Array@Methods+for+Creating+an+Array]
8569 * - {Querying}[rdoc-ref:Array@Methods+for+Querying]
8570 * - {Comparing}[rdoc-ref:Array@Methods+for+Comparing]
8571 * - {Fetching}[rdoc-ref:Array@Methods+for+Fetching]
8572 * - {Assigning}[rdoc-ref:Array@Methods+for+Assigning]
8573 * - {Deleting}[rdoc-ref:Array@Methods+for+Deleting]
8574 * - {Combining}[rdoc-ref:Array@Methods+for+Combining]
8575 * - {Iterating}[rdoc-ref:Array@Methods+for+Iterating]
8576 * - {Converting}[rdoc-ref:Array@Methods+for+Converting]
8577 * - {And more....}[rdoc-ref:Array@Other+Methods]
8578 *
8579 * === Methods for Creating an +Array+
8580 *
8581 * - ::[]: Returns a new array populated with given objects.
8582 * - ::new: Returns a new array.
8583 * - ::try_convert: Returns a new array created from a given object.
8584 *
8585 * See also {Creating Arrays}[rdoc-ref:Array@Creating+Arrays].
8586 *
8587 * === Methods for Querying
8588 *
8589 * - #all?: Returns whether all elements meet a given criterion.
8590 * - #any?: Returns whether any element meets a given criterion.
8591 * - #count: Returns the count of elements that meet a given criterion.
8592 * - #empty?: Returns whether there are no elements.
8593 * - #find_index (aliased as #index): Returns the index of the first element that meets a given criterion.
8594 * - #hash: Returns the integer hash code.
8595 * - #include?: Returns whether any element <tt>==</tt> a given object.
8596 * - #length (aliased as #size): Returns the count of elements.
8597 * - #none?: Returns whether no element <tt>==</tt> a given object.
8598 * - #one?: Returns whether exactly one element <tt>==</tt> a given object.
8599 * - #rindex: Returns the index of the last element that meets a given criterion.
8600 *
8601 * === Methods for Comparing
8602 *
8603 * - #<=>: Returns -1, 0, or 1, as +self+ is less than, equal to, or greater than a given object.
8604 * - #==: Returns whether each element in +self+ is <tt>==</tt> to the corresponding element in a given object.
8605 * - #eql?: Returns whether each element in +self+ is <tt>eql?</tt> to the corresponding element in a given object.
8607 * === Methods for Fetching
8608 *
8609 * These methods do not modify +self+.
8610 *
8611 * - #[] (aliased as #slice): Returns consecutive elements as determined by a given argument.
8612 * - #assoc: Returns the first element that is an array whose first element <tt>==</tt> a given object.
8613 * - #at: Returns the element at a given offset.
8614 * - #bsearch: Returns an element selected via a binary search as determined by a given block.
8615 * - #bsearch_index: Returns the index of an element selected via a binary search as determined by a given block.
8616 * - #compact: Returns an array containing all non-+nil+ elements.
8617 * - #dig: Returns the object in nested objects that is specified by a given index and additional arguments.
8618 * - #drop: Returns trailing elements as determined by a given index.
8619 * - #drop_while: Returns trailing elements as determined by a given block.
8620 * - #fetch: Returns the element at a given offset.
8621 * - #fetch_values: Returns elements at given offsets.
8622 * - #first: Returns one or more leading elements.
8623 * - #last: Returns one or more trailing elements.
8624 * - #max: Returns one or more maximum-valued elements, as determined by <tt>#<=></tt> or a given block.
8625 * - #min: Returns one or more minimum-valued elements, as determined by <tt>#<=></tt> or a given block.
8626 * - #minmax: Returns the minimum-valued and maximum-valued elements, as determined by <tt>#<=></tt> or a given block.
8627 * - #rassoc: Returns the first element that is an array whose second element <tt>==</tt> a given object.
8628 * - #reject: Returns an array containing elements not rejected by a given block.
8629 * - #reverse: Returns all elements in reverse order.
8630 * - #rotate: Returns all elements with some rotated from one end to the other.
8631 * - #sample: Returns one or more random elements.
8632 * - #select (aliased as #filter): Returns an array containing elements selected by a given block.
8633 * - #shuffle: Returns elements in a random order.
8634 * - #sort: Returns all elements in an order determined by <tt>#<=></tt> or a given block.
8635 * - #take: Returns leading elements as determined by a given index.
8636 * - #take_while: Returns leading elements as determined by a given block.
8637 * - #uniq: Returns an array containing non-duplicate elements.
8638 * - #values_at: Returns the elements at given offsets.
8639 *
8640 * === Methods for Assigning
8641 *
8642 * These methods add, replace, or reorder elements in +self+.
8643 *
8644 * - #<<: Appends an element.
8645 * - #[]=: Assigns specified elements with a given object.
8646 * - #concat: Appends all elements from given arrays.
8647 * - #fill: Replaces specified elements with specified objects.
8648 * - #flatten!: Replaces each nested array in +self+ with the elements from that array.
8649 * - #initialize_copy (aliased as #replace): Replaces the content of +self+ with the content of a given array.
8650 * - #insert: Inserts given objects at a given offset; does not replace elements.
8651 * - #push (aliased as #append): Appends elements.
8652 * - #reverse!: Replaces +self+ with its elements reversed.
8653 * - #rotate!: Replaces +self+ with its elements rotated.
8654 * - #shuffle!: Replaces +self+ with its elements in random order.
8655 * - #sort!: Replaces +self+ with its elements sorted, as determined by <tt>#<=></tt> or a given block.
8656 * - #sort_by!: Replaces +self+ with its elements sorted, as determined by a given block.
8657 * - #unshift (aliased as #prepend): Prepends leading elements.
8658 *
8659 * === Methods for Deleting
8660 *
8661 * Each of these methods removes elements from +self+:
8662 *
8663 * - #clear: Removes all elements.
8664 * - #compact!: Removes all +nil+ elements.
8665 * - #delete: Removes elements equal to a given object.
8666 * - #delete_at: Removes the element at a given offset.
8667 * - #delete_if: Removes elements specified by a given block.
8668 * - #keep_if: Removes elements not specified by a given block.
8669 * - #pop: Removes and returns the last element.
8670 * - #reject!: Removes elements specified by a given block.
8671 * - #select! (aliased as #filter!): Removes elements not specified by a given block.
8672 * - #shift: Removes and returns the first element.
8673 * - #slice!: Removes and returns a sequence of elements.
8674 * - #uniq!: Removes duplicates.
8675 *
8676 * === Methods for Combining
8677 *
8678 * - #&: Returns an array containing elements found both in +self+ and a given array.
8679 * - #+: Returns an array containing all elements of +self+ followed by all elements of a given array.
8680 * - #-: Returns an array containing all elements of +self+ that are not found in a given array.
8681 * - #|: Returns an array containing all element of +self+ and all elements of a given array, duplicates removed.
8682 * - #difference: Returns an array containing all elements of +self+ that are not found in any of the given arrays..
8683 * - #intersection: Returns an array containing elements found both in +self+ and in each given array.
8684 * - #product: Returns or yields all combinations of elements from +self+ and given arrays.
8685 * - #reverse: Returns an array containing all elements of +self+ in reverse order.
8686 * - #union: Returns an array containing all elements of +self+ and all elements of given arrays, duplicates removed.
8687 *
8688 * === Methods for Iterating
8689 *
8690 * - #combination: Calls a given block with combinations of elements of +self+; a combination does not use the same element more than once.
8691 * - #cycle: Calls a given block with each element, then does so again, for a specified number of times, or forever.
8692 * - #each: Passes each element to a given block.
8693 * - #each_index: Passes each element index to a given block.
8694 * - #permutation: Calls a given block with permutations of elements of +self+; a permutation does not use the same element more than once.
8695 * - #repeated_combination: Calls a given block with combinations of elements of +self+; a combination may use the same element more than once.
8696 * - #repeated_permutation: Calls a given block with permutations of elements of +self+; a permutation may use the same element more than once.
8697 * - #reverse_each: Passes each element, in reverse order, to a given block.
8698 *
8699 * === Methods for Converting
8700 *
8701 * - #collect (aliased as #map): Returns an array containing the block return-value for each element.
8702 * - #collect! (aliased as #map!): Replaces each element with a block return-value.
8703 * - #flatten: Returns an array that is a recursive flattening of +self+.
8704 * - #inspect (aliased as #to_s): Returns a new String containing the elements.
8705 * - #join: Returns a newsString containing the elements joined by the field separator.
8706 * - #to_a: Returns +self+ or a new array containing all elements.
8707 * - #to_ary: Returns +self+.
8708 * - #to_h: Returns a new hash formed from the elements.
8709 * - #transpose: Transposes +self+, which must be an array of arrays.
8710 * - #zip: Returns a new array of arrays containing +self+ and given arrays.
8711 *
8712 * === Other Methods
8713 *
8714 * - #*: Returns one of the following:
8715 *
8716 * - With integer argument +n+, a new array that is the concatenation
8717 * of +n+ copies of +self+.
8718 * - With string argument +field_separator+, a new string that is equivalent to
8719 * <tt>join(field_separator)</tt>.
8720 *
8721 * - #pack: Packs the elements into a binary sequence.
8722 * - #sum: Returns a sum of elements according to either <tt>+</tt> or a given block.
8723 */
8725 void
8727 {
8856 }