| blob | b0a874bc836233f7ceedac81e46d67cd38347469 |
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 **********************************************************************/
35 #if !ARRAY_DEBUG
36 # undef NDEBUG
37 # define NDEBUG
38 #endif
41 VALUE rb_cArray;
42 VALUE rb_cArray_empty_frozen;
44 /* Flags of RArray
45 *
46 * 0: RARRAY_SHARED_FLAG (equal to ELTS_SHARED)
47 * The array is shared. The buffer this array points to is owned by
48 * another array (the shared root).
49 * 1: RARRAY_EMBED_FLAG
50 * The array is embedded (its contents follow the header, rather than
51 * being on a separately allocated buffer).
52 * 3-9: RARRAY_EMBED_LEN
53 * The length of the array when RARRAY_EMBED_FLAG is set.
54 * 12: RARRAY_SHARED_ROOT_FLAG
55 * The array is a shared root that does reference counting. The buffer
56 * this array points to is owned by this array but may be pointed to
57 * by other arrays.
58 * Note: Frozen arrays may be a shared root without this flag being
59 * set. Frozen arrays do not have reference counting because
60 * they cannot be modified. Not updating the reference count
61 * improves copy-on-write performance. Their reference count is
62 * assumed to be infinity.
63 * 14: RARRAY_PTR_IN_USE_FLAG
64 * The buffer of the array is in use. This is only used during
65 * debugging.
66 */
68 /* for OPTIMIZED_CMP: */
69 #define id_cmp idCmp
71 #define ARY_DEFAULT_SIZE 16
72 #define ARY_MAX_SIZE (LONG_MAX / (int)sizeof(VALUE))
73 #define SMALL_ARRAY_LEN 16
76 static int
78 {
80 }
82 #define ARY_HEAP_PTR(a) (RUBY_ASSERT(!ARY_EMBED_P(a)), RARRAY(a)->as.heap.ptr)
83 #define ARY_HEAP_LEN(a) (RUBY_ASSERT(!ARY_EMBED_P(a)), RARRAY(a)->as.heap.len)
84 #define ARY_HEAP_CAPA(a) (RUBY_ASSERT(!ARY_EMBED_P(a)), RUBY_ASSERT(!ARY_SHARED_ROOT_P(a)), \
85 RARRAY(a)->as.heap.aux.capa)
87 #define ARY_EMBED_PTR(a) (RUBY_ASSERT(ARY_EMBED_P(a)), RARRAY(a)->as.ary)
88 #define ARY_EMBED_LEN(a) \
89 (RUBY_ASSERT(ARY_EMBED_P(a)), \
90 (long)((RBASIC(a)->flags >> RARRAY_EMBED_LEN_SHIFT) & \
91 (RARRAY_EMBED_LEN_MASK >> RARRAY_EMBED_LEN_SHIFT)))
92 #define ARY_HEAP_SIZE(a) (RUBY_ASSERT(!ARY_EMBED_P(a)), RUBY_ASSERT(ARY_OWNS_HEAP_P(a)), ARY_CAPA(a) * sizeof(VALUE))
94 #define ARY_OWNS_HEAP_P(a) (RUBY_ASSERT(should_be_T_ARRAY((VALUE)(a))), \
95 !FL_TEST_RAW((a), RARRAY_SHARED_FLAG|RARRAY_EMBED_FLAG))
97 #define FL_SET_EMBED(a) do { \
98 RUBY_ASSERT(!ARY_SHARED_P(a)); \
99 FL_SET((a), RARRAY_EMBED_FLAG); \
100 ary_verify(a); \
101 } while (0)
103 #define FL_UNSET_EMBED(ary) FL_UNSET((ary), RARRAY_EMBED_FLAG|RARRAY_EMBED_LEN_MASK)
104 #define FL_SET_SHARED(ary) do { \
105 RUBY_ASSERT(!ARY_EMBED_P(ary)); \
106 FL_SET((ary), RARRAY_SHARED_FLAG); \
107 } while (0)
108 #define FL_UNSET_SHARED(ary) FL_UNSET((ary), RARRAY_SHARED_FLAG)
110 #define ARY_SET_PTR(ary, p) do { \
111 RUBY_ASSERT(!ARY_EMBED_P(ary)); \
112 RUBY_ASSERT(!OBJ_FROZEN(ary)); \
113 RARRAY(ary)->as.heap.ptr = (p); \
114 } while (0)
115 #define ARY_SET_EMBED_LEN(ary, n) do { \
116 long tmp_n = (n); \
117 RUBY_ASSERT(ARY_EMBED_P(ary)); \
118 RBASIC(ary)->flags &= ~RARRAY_EMBED_LEN_MASK; \
119 RBASIC(ary)->flags |= (tmp_n) << RARRAY_EMBED_LEN_SHIFT; \
120 } while (0)
121 #define ARY_SET_HEAP_LEN(ary, n) do { \
122 RUBY_ASSERT(!ARY_EMBED_P(ary)); \
123 RARRAY(ary)->as.heap.len = (n); \
124 } while (0)
125 #define ARY_SET_LEN(ary, n) do { \
126 if (ARY_EMBED_P(ary)) { \
127 ARY_SET_EMBED_LEN((ary), (n)); \
128 } \
129 else { \
130 ARY_SET_HEAP_LEN((ary), (n)); \
131 } \
132 RUBY_ASSERT(RARRAY_LEN(ary) == (n)); \
133 } while (0)
134 #define ARY_INCREASE_PTR(ary, n) do { \
135 RUBY_ASSERT(!ARY_EMBED_P(ary)); \
136 RUBY_ASSERT(!OBJ_FROZEN(ary)); \
137 RARRAY(ary)->as.heap.ptr += (n); \
138 } while (0)
139 #define ARY_INCREASE_LEN(ary, n) do { \
140 RUBY_ASSERT(!OBJ_FROZEN(ary)); \
141 if (ARY_EMBED_P(ary)) { \
142 ARY_SET_EMBED_LEN((ary), RARRAY_LEN(ary)+(n)); \
143 } \
144 else { \
145 RARRAY(ary)->as.heap.len += (n); \
146 } \
147 } while (0)
149 #define ARY_CAPA(ary) (ARY_EMBED_P(ary) ? ary_embed_capa(ary) : \
150 ARY_SHARED_ROOT_P(ary) ? RARRAY_LEN(ary) : ARY_HEAP_CAPA(ary))
151 #define ARY_SET_CAPA(ary, n) do { \
152 RUBY_ASSERT(!ARY_EMBED_P(ary)); \
153 RUBY_ASSERT(!ARY_SHARED_P(ary)); \
154 RUBY_ASSERT(!OBJ_FROZEN(ary)); \
155 RARRAY(ary)->as.heap.aux.capa = (n); \
156 } while (0)
158 #define ARY_SHARED_ROOT_OCCUPIED(ary) (!OBJ_FROZEN(ary) && ARY_SHARED_ROOT_REFCNT(ary) == 1)
159 #define ARY_SET_SHARED_ROOT_REFCNT(ary, value) do { \
160 RUBY_ASSERT(ARY_SHARED_ROOT_P(ary)); \
161 RUBY_ASSERT(!OBJ_FROZEN(ary)); \
162 RUBY_ASSERT((value) >= 0); \
163 RARRAY(ary)->as.heap.aux.capa = (value); \
164 } while (0)
165 #define FL_SET_SHARED_ROOT(ary) do { \
166 RUBY_ASSERT(!OBJ_FROZEN(ary)); \
167 RUBY_ASSERT(!ARY_EMBED_P(ary)); \
168 FL_SET((ary), RARRAY_SHARED_ROOT_FLAG); \
169 } while (0)
173 {
178 }
179 #undef RARRAY_ASET
181 static long
183 {
187 }
189 static size_t
191 {
193 }
195 static bool
197 {
199 }
201 bool
203 {
204 /* An array cannot be turned embeddable when the array is:
205 * - Shared root: other objects may point to the buffer of this array
206 * so we cannot make it embedded.
207 * - Frozen: this array may also be a shared root without the shared root
208 * flag.
209 * - Shared: we don't want to re-embed an array that points to a shared
210 * root (to save memory).
211 */
213 }
215 size_t
217 {
222 }
225 }
228 }
230 }
233 #if ARRAY_DEBUG
234 #define ary_verify(ary) ary_verify_(ary, __FILE__, __LINE__)
236 static VALUE
238 {
249 }
253 }
261 }
263 }
266 }
267 #else
268 #define ary_verify(ary) ((void)0)
269 #endif
271 VALUE *
273 {
274 #if ARRAY_DEBUG
276 #endif
278 }
280 void
282 {
283 #if ARRAY_DEBUG
285 #endif
286 }
288 void
290 {
293 }
294 }
296 static void
298 {
301 });
302 }
306 {
309 }
310 }
312 static void
314 {
318 });
319 }
321 static void
323 {
330 });
331 }
337 }
338 });
339 }
340 }
342 static void
344 {
346 }
350 {
352 }
354 static void
356 {
358 }
360 static void
362 {
364 }
366 static size_t
368 {
374 }
376 void
378 {
390 }
391 }
393 static void
395 {
410 }
413 }
415 }
428 }
429 }
432 }
436 {
444 }
447 }
449 static void
451 {
456 }
459 }
464 }
466 static void
468 {
472 }
473 }
475 static void
477 {
481 }
483 static void
485 {
488 }
491 }
495 }
497 static VALUE
499 {
504 }
506 }
508 static void
510 {
520 }
524 {
529 }
531 void
533 {
547 }
548 else if (ARY_SHARED_ROOT_OCCUPIED(shared_root) && len > ((shared_len = RARRAY_LEN(shared_root))>>1)) {
555 });
558 }
565 }
568 }
570 }
572 void
574 {
577 }
579 static VALUE
581 {
588 }
599 }
601 /* if array is shared, then it is likely it participate in push/shift pattern */
606 }
609 }
610 }
611 }
614 }
617 }
621 }
625 }
627 /*
628 * call-seq:
629 * freeze -> self
630 *
631 * Freezes +self+ (if not already frozen); returns +self+:
632 *
633 * a = []
634 * a.frozen? # => false
635 * a.freeze
636 * a.frozen? # => true
637 *
638 * No further changes may be made to +self+;
639 * raises FrozenError if a change is attempted.
640 *
641 * Related: Kernel#frozen?.
642 */
644 VALUE
646 {
653 }
656 }
658 /* This can be used to take a snapshot of an array (with
659 e.g. rb_ary_replace) and check later whether the array has been
660 modified from the snapshot. The snapshot is cheap, though if
661 something does modify the array it will pay the cost of copying
662 it. If Array#pop or Array#shift has been called, the array will
663 be still shared with the snapshot, but the array length will
664 differ. */
665 VALUE
667 {
673 }
675 }
677 static VALUE
679 {
685 /* Created array is:
686 * FL_SET_EMBED((VALUE)ary);
687 * ARY_SET_EMBED_LEN((VALUE)ary, 0);
688 */
690 }
692 static VALUE
694 {
699 }
701 static VALUE
703 {
706 }
708 static VALUE
710 {
713 VALUE ary;
717 }
720 }
726 }
734 }
737 }
739 VALUE
741 {
743 }
745 VALUE
747 {
749 }
751 VALUE
753 {
755 VALUE ary;
763 }
768 }
770 VALUE
772 {
773 VALUE ary;
779 }
782 }
784 VALUE
786 {
788 }
790 static VALUE
792 {
798 /* Created array is:
799 * FL_SET_EMBED((VALUE)ary);
800 * ARY_SET_EMBED_LEN((VALUE)ary, 0);
801 */
803 }
805 static VALUE
807 {
812 }
814 static VALUE
816 {
817 VALUE ary;
821 }
824 }
830 }
838 }
841 }
843 VALUE
845 {
846 VALUE ary;
852 }
855 }
857 VALUE
859 {
862 }
864 VALUE
866 {
871 }
873 void
875 {
881 }
885 }
888 }
892 }
895 }
896 }
900 static VALUE
902 {
908 }
910 VALUE
912 {
916 // bypass frozen checks
921 }
923 size_t
925 {
928 }
931 }
932 }
934 static VALUE
936 {
941 }
944 }
947 }
952 /* Shared roots cannot be embedded because the reference count
953 * (refcnt) is stored in as.heap.aux.capa. */
965 }
968 }
978 }
979 }
981 static VALUE
983 {
993 }
996 }
997 }
999 VALUE
1001 {
1003 }
1005 VALUE
1007 {
1009 }
1010 #define to_ary rb_to_array_type
1012 VALUE
1014 {
1016 }
1018 VALUE
1020 {
1022 }
1024 VALUE
1026 {
1028 }
1030 /*
1031 * call-seq:
1032 * Array.try_convert(object) -> object, new_array, or nil
1033 *
1034 * Attempts to return an array, based on the given +object+.
1035 *
1036 * If +object+ is an array, returns +object+.
1037 *
1038 * Otherwise if +object+ responds to <tt>:to_ary</tt>.
1039 * calls <tt>object.to_ary</tt>:
1040 * if the return value is an array or +nil+, returns that value;
1041 * if not, raises TypeError.
1042 *
1043 * Otherwise returns +nil+.
1044 *
1045 * Related: see {Methods for Creating an Array}[rdoc-ref:Array@Methods+for+Creating+an+Array].
1046 */
1048 static VALUE
1050 {
1052 }
1054 /* :nodoc: */
1055 static VALUE
1057 {
1058 VALUE ary;
1065 }
1070 }
1073 }
1076 }
1078 /*
1079 * call-seq:
1080 * Array.new -> new_empty_array
1081 * Array.new(array) -> new_array
1082 * Array.new(size, default_value = nil) -> new_array
1083 * Array.new(size = 0) {|index| ... } -> new_array
1084 *
1085 * Returns a new array.
1086 *
1087 * With no block and no argument given, returns a new empty array:
1088 *
1089 * Array.new # => []
1090 *
1091 * With no block and array argument given, returns a new array with the same elements:
1092 *
1093 * Array.new([:foo, 'bar', 2]) # => [:foo, "bar", 2]
1094 *
1095 * With no block and integer argument given, returns a new array containing
1096 * that many instances of the given +default_value+:
1097 *
1098 * Array.new(0) # => []
1099 * Array.new(3) # => [nil, nil, nil]
1100 * Array.new(2, 3) # => [3, 3]
1101 *
1102 * With a block given, returns an array of the given +size+;
1103 * calls the block with each +index+ in the range <tt>(0...size)</tt>;
1104 * the element at that +index+ in the returned array is the blocks return value:
1105 *
1106 * Array.new(3) {|index| "Element #{index}" } # => ["Element 0", "Element 1", "Element 2"]
1107 *
1108 * A common pitfall for new Rubyists is providing an expression as +default_value+:
1109 *
1110 * array = Array.new(2, {})
1111 * array # => [{}, {}]
1112 * array[0][:a] = 1
1113 * array # => [{a: 1}, {a: 1}], as array[0] and array[1] are same object
1114 *
1115 * If you want the elements of the array to be distinct, you should pass a block:
1116 *
1117 * array = Array.new(2) { {} }
1118 * array # => [{}, {}]
1119 * array[0][:a] = 1
1120 * array # => [{a: 1}, {}], as array[0] and array[1] are different objects
1121 *
1122 * Raises TypeError if the first argument is not either an array
1123 * or an {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects]).
1124 * Raises ArgumentError if the first argument is a negative integer.
1125 *
1126 * Related: see {Methods for Creating an Array}[rdoc-ref:Array@Methods+for+Creating+an+Array].
1127 */
1129 static VALUE
1131 {
1142 }
1144 }
1151 }
1152 }
1155 /* NUM2LONG() may call size.to_int, ary can be frozen, modified, etc */
1158 }
1161 }
1162 /* recheck after argument conversion */
1170 }
1174 }
1175 }
1179 }
1181 }
1183 /*
1184 * Returns a new array, populated with the given objects:
1185 *
1186 * Array[1, 'a', /^A/] # => [1, "a", /^A/]
1187 * Array[] # => []
1188 * Array.[](1, 'a', /^A/) # => [1, "a", /^A/]
1189 *
1190 * Related: see {Methods for Creating an Array}[rdoc-ref:Array@Methods+for+Creating+an+Array].
1191 */
1193 static VALUE
1195 {
1200 }
1203 }
1205 void
1207 {
1215 }
1216 }
1219 }
1224 }
1227 }
1231 }
1233 }
1235 static VALUE
1237 {
1248 }
1252 /* The ary_make_shared call may allocate, which can trigger a GC
1253 * compaction. This can cause the array to be embedded because it has
1254 * a length of 0. */
1265 }
1269 }
1271 static VALUE
1273 {
1289 }
1292 }
1308 }
1310 }
1318 }
1319 });
1321 }
1324 }
1326 static VALUE
1328 {
1330 }
1332 enum ary_take_pos_flags
1333 {
1336 };
1338 static VALUE
1340 {
1346 }
1349 }
1352 }
1354 }
1356 static VALUE
1358 {
1360 /* the case optional argument is omitted should be handled in
1361 * callers of this function. if another arity case is added,
1362 * this arity check needs to rewrite. */
1365 }
1367 /*
1368 * call-seq:
1369 * self << object -> self
1370 *
1371 * Appends +object+ as the last element in +self+; returns +self+:
1372 *
1373 * [:foo, 'bar', 2] << :baz # => [:foo, "bar", 2, :baz]
1374 *
1375 * Appends +object+ as a single element, even if it is another array:
1376 *
1377 * [:foo, 'bar', 2] << [3, 4] # => [:foo, "bar", 2, [3, 4]]
1378 *
1379 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
1380 */
1382 VALUE
1384 {
1389 });
1393 }
1395 VALUE
1397 {
1403 }
1405 /*
1406 * call-seq:
1407 * push(*objects) -> self
1408 * append(*objects) -> self
1409 *
1410 * Appends each argument in +objects+ to +self+; returns +self+:
1411 *
1412 * a = [:foo, 'bar', 2] # => [:foo, "bar", 2]
1413 * a.push(:baz, :bat) # => [:foo, "bar", 2, :baz, :bat]
1414 *
1415 * Appends each argument as a single element, even if it is another array:
1416 *
1417 * a = [:foo, 'bar', 2] # => [:foo, "bar", 2]
1418 a.push([:baz, :bat], [:bam, :bad]) # => [:foo, "bar", 2, [:baz, :bat], [:bam, :bad]]
1419 *
1420 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
1421 */
1423 static VALUE
1425 {
1427 }
1429 VALUE
1431 {
1439 {
1441 }
1446 }
1448 /*
1449 * call-seq:
1450 * pop -> object or nil
1451 * pop(count) -> new_array
1452 *
1453 * Removes and returns trailing elements of +self+.
1454 *
1455 * With no argument given, removes and returns the last element, if available;
1456 * otherwise returns +nil+:
1457 *
1458 * a = [:foo, 'bar', 2]
1459 * a.pop # => 2
1460 * a # => [:foo, "bar"]
1461 * [].pop # => nil
1462 *
1463 * With non-negative integer argument +count+ given,
1464 * returns a new array containing the trailing +count+ elements of +self+, as available:
1465 *
1466 * a = [:foo, 'bar', 2]
1467 * a.pop(2) # => ["bar", 2]
1468 * a # => [:foo]
1469 *
1470 * a = [:foo, 'bar', 2]
1471 * a.pop(50) # => [:foo, "bar", 2]
1472 * a # => []
1473 *
1474 * Related: Array#push;
1475 * see also {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
1476 */
1478 static VALUE
1480 {
1481 VALUE result;
1485 }
1492 }
1494 VALUE
1496 {
1497 VALUE top;
1503 }
1510 }
1512 /*
1513 * call-seq:
1514 * shift -> object or nil
1515 * shift(count) -> new_array or nil
1516 *
1517 * Removes and returns leading elements from +self+.
1518 *
1519 * With no argument, removes and returns one element, if available,
1520 * or +nil+ otherwise:
1521 *
1522 * a = [0, 1, 2, 3]
1523 * a.shift # => 0
1524 * a # => [1, 2, 3]
1525 * [].shift # => nil
1526 *
1527 * With non-negative numeric argument +count+ given,
1528 * removes and returns the first +count+ elements:
1529 *
1530 * a = [0, 1, 2, 3]
1531 * a.shift(2) # => [0, 1]
1532 * a # => [2, 3]
1533 * a.shift(1.1) # => [2]
1534 * a # => [3]
1535 * a.shift(0) # => []
1536 * a # => [3]
1537 *
1538 * If +count+ is large,
1539 * removes and returns all elements:
1540 *
1541 * a = [0, 1, 2, 3]
1542 * a.shift(50) # => [0, 1, 2, 3]
1543 * a # => []
1544 *
1545 * If +self+ is empty, returns a new empty array.
1546 *
1547 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
1548 */
1550 static VALUE
1552 {
1553 VALUE result;
1558 }
1566 }
1568 VALUE
1570 {
1573 }
1585 }
1589 }
1592 }
1599 }
1601 static VALUE
1602 make_room_for_unshift(VALUE ary, const VALUE *head, VALUE *sharedp, int argc, long capa, long len)
1603 {
1610 }
1616 }
1618 static VALUE
1620 {
1630 }
1632 /* use shared array for big "queues" */
1636 /* make a room for unshifted items */
1642 }
1644 /* sliding items */
1647 });
1651 }
1652 }
1654 static VALUE
1656 {
1662 }
1665 }
1672 }
1675 }
1682 }
1683 }
1684 }
1686 /*
1687 * call-seq:
1688 * unshift(*objects) -> self
1689 * prepend(*objects) -> self
1690 *
1691 * Prepends the given +objects+ to +self+:
1692 *
1693 * a = [:foo, 'bar', 2]
1694 * a.unshift(:bam, :bat) # => [:bam, :bat, :foo, "bar", 2]
1695 *
1696 * Related: Array#shift;
1697 * see also {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
1698 */
1700 VALUE
1702 {
1704 VALUE target_ary;
1709 }
1715 }
1717 VALUE
1719 {
1721 }
1723 /* faster version - use this if you don't need to treat negative offset */
1726 {
1731 }
1733 }
1735 VALUE
1737 {
1739 }
1741 VALUE
1743 {
1744 VALUE klass;
1752 }
1759 else
1761 }
1763 VALUE
1765 {
1767 }
1771 /*
1772 * call-seq:
1773 * self[index] -> object or nil
1774 * self[start, length] -> object or nil
1775 * self[range] -> object or nil
1776 * self[aseq] -> object or nil
1777 * slice(index) -> object or nil
1778 * slice(start, length) -> object or nil
1779 * slice(range) -> object or nil
1780 * slice(aseq) -> object or nil
1781 *
1782 * Returns elements from +self+; does not modify +self+.
1783 *
1784 * In brief:
1785 *
1786 * a = [:foo, 'bar', 2]
1787 *
1788 * # Single argument index: returns one element.
1789 * a[0] # => :foo # Zero-based index.
1790 * a[-1] # => 2 # Negative index counts backwards from end.
1791 *
1792 * # Arguments start and length: returns an array.
1793 * a[1, 2] # => ["bar", 2]
1794 * a[-2, 2] # => ["bar", 2] # Negative start counts backwards from end.
1795 *
1796 * # Single argument range: returns an array.
1797 * a[0..1] # => [:foo, "bar"]
1798 * a[0..-2] # => [:foo, "bar"] # Negative range-begin counts backwards from end.
1799 * a[-2..2] # => ["bar", 2] # Negative range-end counts backwards from end.
1800 *
1801 * When a single integer argument +index+ is given, returns the element at offset +index+:
1802 *
1803 * a = [:foo, 'bar', 2]
1804 * a[0] # => :foo
1805 * a[2] # => 2
1806 * a # => [:foo, "bar", 2]
1807 *
1808 * If +index+ is negative, counts backwards from the end of +self+:
1809 *
1810 * a = [:foo, 'bar', 2]
1811 * a[-1] # => 2
1812 * a[-2] # => "bar"
1813 *
1814 * If +index+ is out of range, returns +nil+.
1815 *
1816 * When two Integer arguments +start+ and +length+ are given,
1817 * returns a new array of size +length+ containing successive elements beginning at offset +start+:
1818 *
1819 * a = [:foo, 'bar', 2]
1820 * a[0, 2] # => [:foo, "bar"]
1821 * a[1, 2] # => ["bar", 2]
1822 *
1823 * If <tt>start + length</tt> is greater than <tt>self.length</tt>,
1824 * returns all elements from offset +start+ to the end:
1825 *
1826 * a = [:foo, 'bar', 2]
1827 * a[0, 4] # => [:foo, "bar", 2]
1828 * a[1, 3] # => ["bar", 2]
1829 * a[2, 2] # => [2]
1830 *
1831 * If <tt>start == self.size</tt> and <tt>length >= 0</tt>,
1832 * returns a new empty array.
1833 *
1834 * If +length+ is negative, returns +nil+.
1835 *
1836 * When a single Range argument +range+ is given,
1837 * treats <tt>range.min</tt> as +start+ above
1838 * and <tt>range.size</tt> as +length+ above:
1839 *
1840 * a = [:foo, 'bar', 2]
1841 * a[0..1] # => [:foo, "bar"]
1842 * a[1..2] # => ["bar", 2]
1843 *
1844 * Special case: If <tt>range.start == a.size</tt>, returns a new empty array.
1845 *
1846 * If <tt>range.end</tt> is negative, calculates the end index from the end:
1847 *
1848 * a = [:foo, 'bar', 2]
1849 * a[0..-1] # => [:foo, "bar", 2]
1850 * a[0..-2] # => [:foo, "bar"]
1851 * a[0..-3] # => [:foo]
1852 *
1853 * If <tt>range.start</tt> is negative, calculates the start index from the end:
1854 *
1855 * a = [:foo, 'bar', 2]
1856 * a[-1..2] # => [2]
1857 * a[-2..2] # => ["bar", 2]
1858 * a[-3..2] # => [:foo, "bar", 2]
1859 *
1860 * If <tt>range.start</tt> is larger than the array size, returns +nil+.
1861 *
1862 * a = [:foo, 'bar', 2]
1863 * a[4..1] # => nil
1864 * a[4..0] # => nil
1865 * a[4..-1] # => nil
1866 *
1867 * When a single Enumerator::ArithmeticSequence argument +aseq+ is given,
1868 * returns an array of elements corresponding to the indexes produced by
1869 * the sequence.
1870 *
1871 * a = ['--', 'data1', '--', 'data2', '--', 'data3']
1872 * a[(1..).step(2)] # => ["data1", "data2", "data3"]
1873 *
1874 * Unlike slicing with range, if the start or the end of the arithmetic sequence
1875 * is larger than array size, throws RangeError.
1876 *
1877 * a = ['--', 'data1', '--', 'data2', '--', 'data3']
1878 * a[(1..11).step(2)]
1879 * # RangeError (((1..11).step(2)) out of range)
1880 * a[(7..).step(2)]
1881 * # RangeError (((7..).step(2)) out of range)
1882 *
1883 * If given a single argument, and its type is not one of the listed, tries to
1884 * convert it to Integer, and raises if it is impossible:
1885 *
1886 * a = [:foo, 'bar', 2]
1887 * # Raises TypeError (no implicit conversion of Symbol into Integer):
1888 * a[:foo]
1889 *
1890 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
1891 */
1893 VALUE
1895 {
1899 }
1901 }
1903 static VALUE
1905 {
1910 }
1912 }
1914 VALUE
1916 {
1919 /* special case - speeding up */
1922 }
1923 /* check if idx is Range or ArithmeticSequence */
1931 }
1934 }
1936 /*
1937 * call-seq:
1938 * at(index) -> object or nil
1939 *
1940 * Returns the element of +self+ specified by the given +index+
1941 * or +nil+ if there is no such element;
1942 * +index+ must be an
1943 * {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects].
1944 *
1945 * For non-negative +index+, returns the element of +self+ at offset +index+:
1946 *
1947 * a = [:foo, 'bar', 2]
1948 * a.at(0) # => :foo
1949 * a.at(2) # => 2
1950 * a.at(2.0) # => 2
1951 *
1952 * For negative +index+, counts backwards from the end of +self+:
1953 *
1954 * a.at(-2) # => "bar"
1955 *
1956 * Related: Array#[];
1957 * see also {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
1958 */
1960 VALUE
1962 {
1964 }
1966 #if 0
1967 static VALUE
1969 {
1973 }
1976 }
1977 }
1978 #endif
1980 static VALUE
1982 {
1984 }
1986 static VALUE
1988 {
1991 }
1993 VALUE
1995 {
1998 }
2001 }
2002 }
2004 /*
2005 * call-seq:
2006 * fetch(index) -> element
2007 * fetch(index, default_value) -> element or default_value
2008 * fetch(index) {|index| ... } -> element or block_return_value
2009 *
2010 * Returns the element of +self+ at offset +index+ if +index+ is in range; +index+ must be an
2011 * {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects].
2012 *
2013 * With the single argument +index+ and no block,
2014 * returns the element at offset +index+:
2015 *
2016 * a = [:foo, 'bar', 2]
2017 * a.fetch(1) # => "bar"
2018 * a.fetch(1.1) # => "bar"
2019 *
2020 * If +index+ is negative, counts from the end of the array:
2021 *
2022 * a = [:foo, 'bar', 2]
2023 * a.fetch(-1) # => 2
2024 * a.fetch(-2) # => "bar"
2025 *
2026 * With arguments +index+ and +default_value+ (which may be any object) and no block,
2027 * returns +default_value+ if +index+ is out-of-range:
2028 *
2029 * a = [:foo, 'bar', 2]
2030 * a.fetch(1, nil) # => "bar"
2031 * a.fetch(3, :foo) # => :foo
2032 *
2033 * With argument +index+ and a block,
2034 * returns the element at offset +index+ if index is in range
2035 * (and the block is not called); otherwise calls the block with index and returns its return value:
2036 *
2037 * a = [:foo, 'bar', 2]
2038 * a.fetch(1) {|index| raise 'Cannot happen' } # => "bar"
2039 * a.fetch(50) {|index| "Value for #{index}" } # => "Value for 50"
2040 *
2041 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
2042 */
2044 static VALUE
2046 {
2055 }
2060 }
2066 }
2068 }
2070 }
2072 /*
2073 * call-seq:
2074 * find_index(object) -> integer or nil
2075 * find_index {|element| ... } -> integer or nil
2076 * find_index -> new_enumerator
2077 * index(object) -> integer or nil
2078 * index {|element| ... } -> integer or nil
2079 * index -> new_enumerator
2080 *
2081 * Returns the zero-based integer index of a specified element, or +nil+.
2082 *
2083 * With only argument +object+ given,
2084 * returns the index of the first element +element+
2085 * for which <tt>object == element</tt>:
2086 *
2087 * a = [:foo, 'bar', 2, 'bar']
2088 * a.index('bar') # => 1
2089 *
2090 * Returns +nil+ if no such element found.
2091 *
2092 * With only a block given,
2093 * calls the block with each successive element;
2094 * returns the index of the first element for which the block returns a truthy value:
2095 *
2096 * a = [:foo, 'bar', 2, 'bar']
2097 * a.index {|element| element == 'bar' } # => 1
2098 *
2099 * Returns +nil+ if the block never returns a truthy value.
2100 *
2101 * With neither an argument nor a block given, returns a new Enumerator.
2102 *
2103 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
2104 */
2106 static VALUE
2108 {
2109 VALUE val;
2117 }
2118 }
2120 }
2129 }
2130 }
2132 }
2134 /*
2135 * call-seq:
2136 * rindex(object) -> integer or nil
2137 * rindex {|element| ... } -> integer or nil
2138 * rindex -> new_enumerator
2139 *
2140 * Returns the index of the last element for which <tt>object == element</tt>.
2141 *
2142 * With argument +object+ given, returns the index of the last such element found:
2143 *
2144 * a = [:foo, 'bar', 2, 'bar']
2145 * a.rindex('bar') # => 3
2146 *
2147 * Returns +nil+ if no such object found.
2148 *
2149 * With a block given, calls the block with each successive element;
2150 * returns the index of the last element for which the block returns a truthy value:
2151 *
2152 * a = [:foo, 'bar', 2, 'bar']
2153 * a.rindex {|element| element == 'bar' } # => 3
2154 *
2155 * Returns +nil+ if the block never returns a truthy value.
2156 *
2157 * When neither an argument nor a block is given, returns a new Enumerator.
2158 *
2159 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
2160 */
2162 static VALUE
2164 {
2165 VALUE val;
2175 }
2176 }
2178 }
2187 }
2190 }
2191 }
2193 }
2195 VALUE
2197 {
2202 }
2204 static void
2206 {
2217 }
2218 }
2221 }
2223 {
2226 }
2229 VALUE target_ary;
2232 }
2239 }
2241 }
2247 }
2252 }
2259 }
2263 }
2265 /* In this case, we're copying from a region in this array, so
2266 * we don't need to fire the write barrier. */
2268 }
2270 /* do not use RARRAY_PTR() because it can causes GC.
2271 * ary can contain T_NONE object because it is not cleared.
2272 */
2275 }
2276 }
2277 }
2279 void
2281 {
2287 }
2290 }
2292 }
2294 VALUE
2296 {
2304 }
2308 }
2311 }
2314 }
2326 }
2331 }
2333 }
2336 }
2338 static VALUE
2340 {
2343 }
2345 static VALUE
2347 {
2352 }
2354 /*
2355 * call-seq:
2356 * self[index] = object -> object
2357 * self[start, length] = object -> object
2358 * self[range] = object -> object
2359 *
2360 * Assigns elements in +self+, based on the given +object+; returns +object+.
2361 *
2362 * In brief:
2363 *
2364 * a_orig = [:foo, 'bar', 2]
2365 *
2366 * # With argument index.
2367 * a = a_orig.dup
2368 * a[0] = 'foo' # => "foo"
2369 * a # => ["foo", "bar", 2]
2370 * a = a_orig.dup
2371 * a[7] = 'foo' # => "foo"
2372 * a # => [:foo, "bar", 2, nil, nil, nil, nil, "foo"]
2373 *
2374 * # With arguments start and length.
2375 * a = a_orig.dup
2376 * a[0, 2] = 'foo' # => "foo"
2377 * a # => ["foo", 2]
2378 * a = a_orig.dup
2379 * a[6, 50] = 'foo' # => "foo"
2380 * a # => [:foo, "bar", 2, nil, nil, nil, "foo"]
2381 *
2382 * # With argument range.
2383 * a = a_orig.dup
2384 * a[0..1] = 'foo' # => "foo"
2385 * a # => ["foo", 2]
2386 * a = a_orig.dup
2387 * a[6..50] = 'foo' # => "foo"
2388 * a # => [:foo, "bar", 2, nil, nil, nil, "foo"]
2389 *
2390 * When Integer argument +index+ is given, assigns +object+ to an element in +self+.
2391 *
2392 * If +index+ is non-negative, assigns +object+ the element at offset +index+:
2393 *
2394 * a = [:foo, 'bar', 2]
2395 * a[0] = 'foo' # => "foo"
2396 * a # => ["foo", "bar", 2]
2397 *
2398 * If +index+ is greater than <tt>self.length</tt>, extends the array:
2399 *
2400 * a = [:foo, 'bar', 2]
2401 * a[7] = 'foo' # => "foo"
2402 * a # => [:foo, "bar", 2, nil, nil, nil, nil, "foo"]
2403 *
2404 * If +index+ is negative, counts backwards from the end of the array:
2405 *
2406 * a = [:foo, 'bar', 2]
2407 * a[-1] = 'two' # => "two"
2408 * a # => [:foo, "bar", "two"]
2409 *
2410 * When Integer arguments +start+ and +length+ are given and +object+ is not an array,
2411 * removes <tt>length - 1</tt> elements beginning at offset +start+,
2412 * and assigns +object+ at offset +start+:
2413 *
2414 * a = [:foo, 'bar', 2]
2415 * a[0, 2] = 'foo' # => "foo"
2416 * a # => ["foo", 2]
2417 *
2418 * If +start+ is negative, counts backwards from the end of the array:
2419 *
2420 * a = [:foo, 'bar', 2]
2421 * a[-2, 2] = 'foo' # => "foo"
2422 * a # => [:foo, "foo"]
2423 *
2424 * If +start+ is non-negative and outside the array (<tt> >= self.size</tt>),
2425 * extends the array with +nil+, assigns +object+ at offset +start+,
2426 * and ignores +length+:
2427 *
2428 * a = [:foo, 'bar', 2]
2429 * a[6, 50] = 'foo' # => "foo"
2430 * a # => [:foo, "bar", 2, nil, nil, nil, "foo"]
2431 *
2432 * If +length+ is zero, shifts elements at and following offset +start+
2433 * and assigns +object+ at offset +start+:
2434 *
2435 * a = [:foo, 'bar', 2]
2436 * a[1, 0] = 'foo' # => "foo"
2437 * a # => [:foo, "foo", "bar", 2]
2438 *
2439 * If +length+ is too large for the existing array, does not extend the array:
2440 *
2441 * a = [:foo, 'bar', 2]
2442 * a[1, 5] = 'foo' # => "foo"
2443 * a # => [:foo, "foo"]
2444 *
2445 * When Range argument +range+ is given and +object+ is not an array,
2446 * removes <tt>length - 1</tt> elements beginning at offset +start+,
2447 * and assigns +object+ at offset +start+:
2448 *
2449 * a = [:foo, 'bar', 2]
2450 * a[0..1] = 'foo' # => "foo"
2451 * a # => ["foo", 2]
2452 *
2453 * if <tt>range.begin</tt> is negative, counts backwards from the end of the array:
2454 *
2455 * a = [:foo, 'bar', 2]
2456 * a[-2..2] = 'foo' # => "foo"
2457 * a # => [:foo, "foo"]
2458 *
2459 * If the array length is less than <tt>range.begin</tt>,
2460 * extends the array with +nil+, assigns +object+ at offset <tt>range.begin</tt>,
2461 * and ignores +length+:
2462 *
2463 * a = [:foo, 'bar', 2]
2464 * a[6..50] = 'foo' # => "foo"
2465 * a # => [:foo, "bar", 2, nil, nil, nil, "foo"]
2466 *
2467 * If <tt>range.end</tt> is zero, shifts elements at and following offset +start+
2468 * and assigns +object+ at offset +start+:
2469 *
2470 * a = [:foo, 'bar', 2]
2471 * a[1..0] = 'foo' # => "foo"
2472 * a # => [:foo, "foo", "bar", 2]
2473 *
2474 * If <tt>range.end</tt> is negative, assigns +object+ at offset +start+,
2475 * retains <tt>range.end.abs -1</tt> elements past that, and removes those beyond:
2476 *
2477 * a = [:foo, 'bar', 2]
2478 * a[1..-1] = 'foo' # => "foo"
2479 * a # => [:foo, "foo"]
2480 * a = [:foo, 'bar', 2]
2481 * a[1..-2] = 'foo' # => "foo"
2482 * a # => [:foo, "foo", 2]
2483 * a = [:foo, 'bar', 2]
2484 * a[1..-3] = 'foo' # => "foo"
2485 * a # => [:foo, "foo", "bar", 2]
2486 * a = [:foo, 'bar', 2]
2487 *
2488 * If <tt>range.end</tt> is too large for the existing array,
2489 * replaces array elements, but does not extend the array with +nil+ values:
2490 *
2491 * a = [:foo, 'bar', 2]
2492 * a[1..5] = 'foo' # => "foo"
2493 * a # => [:foo, "foo"]
2494 *
2495 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
2496 */
2498 static VALUE
2500 {
2509 }
2513 }
2515 /* check if idx is Range */
2517 }
2521 }
2523 /*
2524 * call-seq:
2525 * insert(index, *objects) -> self
2526 *
2527 * Inserts the given +objects+ as elements of +self+;
2528 * returns +self+.
2529 *
2530 * When +index+ is non-negative, inserts +objects+
2531 * _before_ the element at offset +index+:
2532 *
2533 * a = ['a', 'b', 'c'] # => ["a", "b", "c"]
2534 * a.insert(1, :x, :y, :z) # => ["a", :x, :y, :z, "b", "c"]
2535 *
2536 * Extends the array if +index+ is beyond the array (<tt>index >= self.size</tt>):
2537 *
2538 * a = ['a', 'b', 'c'] # => ["a", "b", "c"]
2539 * a.insert(5, :x, :y, :z) # => ["a", "b", "c", nil, nil, :x, :y, :z]
2540 *
2541 * When +index+ is negative, inserts +objects+
2542 * _after_ the element at offset <tt>index + self.size</tt>:
2543 *
2544 * a = ['a', 'b', 'c'] # => ["a", "b", "c"]
2545 * a.insert(-2, :x, :y, :z) # => ["a", "b", :x, :y, :z, "c"]
2546 *
2547 * With no +objects+ given, does nothing:
2548 *
2549 * a = ['a', 'b', 'c'] # => ["a", "b", "c"]
2550 * a.insert(1) # => ["a", "b", "c"]
2551 * a.insert(50) # => ["a", "b", "c"]
2552 * a.insert(-50) # => ["a", "b", "c"]
2553 *
2554 * Raises IndexError if +objects+ are given and +index+ is negative and out of range.
2555 *
2556 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
2557 */
2559 static VALUE
2561 {
2570 }
2576 }
2577 pos++;
2578 }
2581 }
2583 static VALUE
2586 static VALUE
2588 {
2590 }
2592 // Primitive to avoid a race condition in Array#each.
2593 // Return `true` and write `value` and `index` if the element exists.
2594 static VALUE
2596 {
2600 }
2604 }
2606 /*
2607 * call-seq:
2608 * each {|element| ... } -> self
2609 * each -> new_enumerator
2610 *
2611 * With a block given, iterates over the elements of +self+,
2612 * passing each element to the block;
2613 * returns +self+:
2614 *
2615 * a = [:foo, 'bar', 2]
2616 * a.each {|element| puts "#{element.class} #{element}" }
2617 *
2618 * Output:
2619 *
2620 * Symbol foo
2621 * String bar
2622 * Integer 2
2623 *
2624 * Allows the array to be modified during iteration:
2625 *
2626 * a = [:foo, 'bar', 2]
2627 * a.each {|element| puts element; a.clear if element.to_s.start_with?('b') }
2628 *
2629 * Output:
2630 *
2631 * foo
2632 * bar
2633 *
2634 * With no block given, returns a new Enumerator.
2635 *
2636 * Related: see {Methods for Iterating}[rdoc-ref:Array@Methods+for+Iterating].
2637 */
2639 VALUE
2641 {
2647 }
2649 }
2651 /*
2652 * call-seq:
2653 * each_index {|index| ... } -> self
2654 * each_index -> new_enumerator
2655 *
2656 * With a block given, iterates over the elements of +self+,
2657 * passing each <i>array index</i> to the block;
2658 * returns +self+:
2659 *
2660 * a = [:foo, 'bar', 2]
2661 * a.each_index {|index| puts "#{index} #{a[index]}" }
2662 *
2663 * Output:
2664 *
2665 * 0 foo
2666 * 1 bar
2667 * 2 2
2668 *
2669 * Allows the array to be modified during iteration:
2670 *
2671 * a = [:foo, 'bar', 2]
2672 * a.each_index {|index| puts index; a.clear if index > 0 }
2673 * a # => []
2674 *
2675 * Output:
2676 *
2677 * 0
2678 * 1
2679 *
2680 * With no block given, returns a new Enumerator.
2681 *
2682 * Related: see {Methods for Iterating}[rdoc-ref:Array@Methods+for+Iterating].
2683 */
2685 static VALUE
2687 {
2693 }
2695 }
2697 /*
2698 * call-seq:
2699 * reverse_each {|element| ... } -> self
2700 * reverse_each -> Enumerator
2701 *
2702 * When a block given, iterates backwards over the elements of +self+,
2703 * passing, in reverse order, each element to the block;
2704 * returns +self+:
2705 *
2706 * a = []
2707 * [0, 1, 2].reverse_each {|element| a.push(element) }
2708 * a # => [2, 1, 0]
2709 *
2710 * Allows the array to be modified during iteration:
2711 *
2712 * a = ['a', 'b', 'c']
2713 * a.reverse_each {|element| a.clear if element.start_with?('b') }
2714 * a # => []
2715 *
2716 * When no block given, returns a new Enumerator.
2717 *
2718 * Related: see {Methods for Iterating}[rdoc-ref:Array@Methods+for+Iterating].
2719 */
2721 static VALUE
2723 {
2734 }
2735 }
2737 }
2739 /*
2740 * call-seq:
2741 * length -> integer
2742 * size -> integer
2743 *
2744 * Returns the count of elements in +self+:
2745 *
2746 * [0, 1, 2].length # => 3
2747 * [].length # => 0
2748 *
2749 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
2750 */
2752 static VALUE
2754 {
2757 }
2759 /*
2760 * call-seq:
2761 * empty? -> true or false
2762 *
2763 * Returns +true+ if the count of elements in +self+ is zero,
2764 * +false+ otherwise.
2765 *
2766 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
2767 */
2769 static VALUE
2771 {
2773 }
2775 VALUE
2777 {
2786 }
2788 VALUE
2790 {
2792 }
2798 static VALUE
2800 {
2809 }
2812 }
2814 }
2816 static long
2818 {
2820 VALUE val;
2829 }
2831 }
2833 static void
2835 {
2840 }
2841 }
2843 static void
2845 {
2848 }
2858 }
2859 }
2861 static void
2863 {
2873 }
2876 }
2879 }
2882 }
2885 }
2886 }
2887 }
2889 VALUE
2891 {
2900 }
2915 }
2918 }
2926 }
2928 /*
2929 * call-seq:
2930 * join(separator = $,) -> new_string
2931 *
2932 * Returns the new string formed by joining the converted elements of +self+;
2933 * for each element +element+:
2934 *
2935 * - Converts recursively using <tt>element.join(separator)</tt>
2936 * if +element+ is a <tt>kind_of?(Array)</tt>.
2937 * - Otherwise, converts using <tt>element.to_s</tt>.
2938 *
2939 * With no argument given, joins using the output field separator, <tt>$,</tt>:
2940 *
2941 * a = [:foo, 'bar', 2]
2942 * $, # => nil
2943 * a.join # => "foobar2"
2944 *
2945 * With string argument +separator+ given, joins using that separator:
2946 *
2947 * a = [:foo, 'bar', 2]
2948 * a.join("\n") # => "foo\nbar\n2"
2949 *
2950 * Joins recursively for nested arrays:
2951 *
2952 * a = [:foo, [:bar, [:baz, :bat]]]
2953 * a.join # => "foobarbazbat"
2954 *
2955 * Related: see {Methods for Converting}[rdoc-ref:Array@Methods+for+Converting].
2956 */
2957 static VALUE
2959 {
2960 VALUE sep;
2966 }
2967 }
2970 }
2972 static VALUE
2974 {
2985 }
2988 }
2990 /*
2991 * call-seq:
2992 * inspect -> new_string
2993 * to_s -> new_string
2994 *
2995 * Returns the new string formed by calling method <tt>#inspect</tt>
2996 * on each array element:
2997 *
2998 * a = [:foo, 'bar', 2]
2999 * a.inspect # => "[:foo, \"bar\", 2]"
3000 *
3001 * Related: see {Methods for Converting}[rdoc-ref:Array@Methods+for+Converting].
3002 */
3004 static VALUE
3006 {
3009 }
3011 VALUE
3013 {
3015 }
3017 /*
3018 * call-seq:
3019 * to_a -> self or new_array
3020 *
3021 * When +self+ is an instance of \Array, returns +self+.
3022 *
3023 * Otherwise, returns a new array containing the elements of +self+:
3024 *
3025 * class MyArray < Array; end
3026 * my_a = MyArray.new(['foo', 'bar', 'two'])
3027 * a = my_a.to_a
3028 * a # => ["foo", "bar", "two"]
3029 * a.class # => Array # Not MyArray.
3030 *
3031 * Related: see {Methods for Converting}[rdoc-ref:Array@Methods+for+Converting].
3032 */
3034 static VALUE
3036 {
3041 }
3043 }
3045 /*
3046 * call-seq:
3047 * to_h -> new_hash
3048 * to_h {|element| ... } -> new_hash
3049 *
3050 * Returns a new hash formed from +self+.
3051 *
3052 * With no block given, each element of +self+ must be a 2-element sub-array;
3053 * forms each sub-array into a key-value pair in the new hash:
3054 *
3055 * a = [['foo', 'zero'], ['bar', 'one'], ['baz', 'two']]
3056 * a.to_h # => {"foo"=>"zero", "bar"=>"one", "baz"=>"two"}
3057 * [].to_h # => {}
3058 *
3059 * With a block given, the block must return a 2-element array;
3060 * calls the block with each element of +self+;
3061 * forms each returned array into a key-value pair in the returned hash:
3062 *
3063 * a = ['foo', :bar, 1, [2, 3], {baz: 4}]
3064 * a.to_h {|element| [element, element.class] }
3065 * # => {"foo"=>String, :bar=>Symbol, 1=>Integer, [2, 3]=>Array, {:baz=>4}=>Hash}
3066 *
3067 * Related: see {Methods for Converting}[rdoc-ref:Array@Methods+for+Converting].
3068 */
3070 static VALUE
3072 {
3084 }
3088 }
3090 }
3092 }
3094 /*
3095 * call-seq:
3096 * to_ary -> self
3097 *
3098 * Returns +self+.
3099 */
3101 static VALUE
3103 {
3105 }
3107 static void
3109 {
3114 }
3115 }
3117 VALUE
3119 {
3129 }
3131 }
3133 /*
3134 * call-seq:
3135 * reverse! -> self
3136 *
3137 * Reverses the order of the elements of +self+;
3138 * returns +self+:
3139 *
3140 * a = [0, 1, 2]
3141 * a.reverse! # => [2, 1, 0]
3142 * a # => [2, 1, 0]
3143 *
3144 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
3145 */
3147 static VALUE
3149 {
3151 }
3153 /*
3154 * call-seq:
3155 * reverse -> new_array
3156 *
3157 * Returns a new array containing the elements of +self+ in reverse order:
3158 *
3159 * [0, 1, 2].reverse # => [2, 1, 0]
3160 *
3161 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
3162 */
3164 static VALUE
3166 {
3174 }
3177 }
3181 {
3183 }
3185 static void
3187 {
3192 }
3197 }
3203 }
3204 }
3206 VALUE
3208 {
3216 }
3217 }
3219 }
3221 /*
3222 * call-seq:
3223 * rotate!(count = 1) -> self
3224 *
3225 * Rotates +self+ in place by moving elements from one end to the other; returns +self+.
3226 *
3227 * With non-negative numeric +count+,
3228 * rotates +count+ elements from the beginning to the end:
3229 *
3230 * [0, 1, 2, 3].rotate!(2) # => [2, 3, 0, 1]
3231 [0, 1, 2, 3].rotate!(2.1) # => [2, 3, 0, 1]
3232 *
3233 * If +count+ is large, uses <tt>count % array.size</tt> as the count:
3234 *
3235 * [0, 1, 2, 3].rotate!(21) # => [1, 2, 3, 0]
3236 *
3237 * If +count+ is zero, rotates no elements:
3238 *
3239 * [0, 1, 2, 3].rotate!(0) # => [0, 1, 2, 3]
3240 *
3241 * With a negative numeric +count+, rotates in the opposite direction,
3242 * from end to beginning:
3243 *
3244 * [0, 1, 2, 3].rotate!(-1) # => [3, 0, 1, 2]
3245 *
3246 * If +count+ is small (far from zero), uses <tt>count % array.size</tt> as the count:
3247 *
3248 * [0, 1, 2, 3].rotate!(-21) # => [3, 0, 1, 2]
3249 *
3250 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
3251 */
3253 static VALUE
3255 {
3259 }
3261 /*
3262 * call-seq:
3263 * rotate(count = 1) -> new_array
3264 *
3265 * Returns a new array formed from +self+ with elements
3266 * rotated from one end to the other.
3267 *
3268 * With non-negative numeric +count+,
3269 * rotates elements from the beginning to the end:
3270 *
3271 * [0, 1, 2, 3].rotate(2) # => [2, 3, 0, 1]
3272 * [0, 1, 2, 3].rotate(2.1) # => [2, 3, 0, 1]
3273 *
3274 * If +count+ is large, uses <tt>count % array.size</tt> as the count:
3275 *
3276 * [0, 1, 2, 3].rotate(22) # => [2, 3, 0, 1]
3277 *
3278 * With a +count+ of zero, rotates no elements:
3279 *
3280 * [0, 1, 2, 3].rotate(0) # => [0, 1, 2, 3]
3281 *
3282 * With negative numeric +count+, rotates in the opposite direction,
3283 * from the end to the beginning:
3284 *
3285 * [0, 1, 2, 3].rotate(-1) # => [3, 0, 1, 2]
3286 *
3287 * If +count+ is small (far from zero), uses <tt>count % array.size</tt> as the count:
3288 *
3289 * [0, 1, 2, 3].rotate(-21) # => [3, 0, 1, 2]
3290 *
3291 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
3292 */
3294 static VALUE
3296 {
3297 VALUE rotated;
3310 }
3313 }
3316 VALUE ary;
3317 VALUE receiver;
3318 };
3320 static VALUE
3322 {
3325 }
3327 }
3329 static void
3331 {
3334 }
3336 }
3338 static int
3340 {
3353 }
3355 static int
3357 {
3367 }
3370 }
3373 }
3380 }
3382 /*
3383 * call-seq:
3384 * sort! -> self
3385 * sort! {|a, b| ... } -> self
3386 *
3387 * Like Array#sort, but returns +self+ with its elements sorted in place.
3388 *
3389 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
3390 */
3392 VALUE
3394 {
3413 }
3416 }
3419 }
3424 }
3429 }
3431 /* ary might be destructively operated in the given block */
3433 }
3436 }
3440 }
3441 /* tmp was lost ownership for the ptr */
3446 }
3447 /* tmp will be GC'ed. */
3449 }
3452 }
3454 /*
3455 * call-seq:
3456 * sort -> new_array
3457 * sort {|a, b| ... } -> new_array
3458 *
3459 * Returns a new array containing the elements of +self+, sorted.
3460 *
3461 * With no block given, compares elements using operator <tt>#<=></tt>
3462 * (see Object#<=>):
3463 *
3464 * [0, 2, 3, 1].sort # => [0, 1, 2, 3]
3465 *
3466 * With a block given, calls the block with each combination of pairs of elements from +self+;
3467 * for each pair +a+ and +b+, the block should return a numeric:
3468 *
3469 * - Negative when +b+ is to follow +a+.
3470 * - Zero when +a+ and +b+ are equivalent.
3471 * - Positive when +a+ is to follow +b+.
3472 *
3473 * Example:
3474 *
3475 * a = [3, 2, 0, 1]
3476 * a.sort {|a, b| a <=> b } # => [0, 1, 2, 3]
3477 * a.sort {|a, b| b <=> a } # => [3, 2, 1, 0]
3478 *
3479 * When the block returns zero, the order for +a+ and +b+ is indeterminate,
3480 * and may be unstable.
3481 *
3482 * See an example in Numeric#nonzero? for the idiom to sort more
3483 * complex structure.
3484 *
3485 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
3486 */
3488 VALUE
3490 {
3494 }
3498 /*
3499 * call-seq:
3500 * bsearch {|element| ... } -> found_element or nil
3501 * bsearch -> new_enumerator
3502 *
3503 * Returns the element from +self+ found by a binary search,
3504 * or +nil+ if the search found no suitable element.
3505 *
3506 * See {Binary Searching}[rdoc-ref:bsearch.rdoc].
3507 *
3508 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
3509 */
3511 static VALUE
3513 {
3518 }
3520 }
3522 /*
3523 * call-seq:
3524 * bsearch_index {|element| ... } -> integer or nil
3525 * bsearch_index -> new_enumerator
3526 *
3527 * Returns the integer index of the element from +self+ found by a binary search,
3528 * or +nil+ if the search found no suitable element.
3529 *
3530 * See {Binary Searching}[rdoc-ref:bsearch.rdoc].
3531 *
3532 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
3533 */
3535 static VALUE
3537 {
3550 }
3554 }
3557 }
3564 }
3565 }
3570 }
3573 }
3576 }
3577 }
3580 }
3583 static VALUE
3585 {
3587 }
3589 /*
3590 * call-seq:
3591 * sort_by! {|element| ... } -> self
3592 * sort_by! -> new_enumerator
3593 *
3594 * With a block given, sorts the elements of +self+ in place;
3595 * returns self.
3596 *
3597 * Calls the block with each successive element;
3598 * sorts elements based on the values returned from the block:
3599 *
3600 * a = ['aaaa', 'bbb', 'cc', 'd']
3601 * a.sort_by! {|element| element.size }
3602 * a # => ["d", "cc", "bbb", "aaaa"]
3603 *
3604 * For duplicate values returned by the block, the ordering is indeterminate, and may be unstable.
3605 *
3606 * With no block given, returns a new Enumerator.
3607 *
3608 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
3609 */
3611 static VALUE
3613 {
3614 VALUE sorted;
3621 }
3623 }
3626 /*
3627 * call-seq:
3628 * collect {|element| ... } -> new_array
3629 * collect -> new_enumerator
3630 * map {|element| ... } -> new_array
3631 * map -> new_enumerator
3632 *
3633 * With a block given, calls the block with each element of +self+;
3634 * returns a new array whose elements are the return values from the block:
3635 *
3636 * a = [:foo, 'bar', 2]
3637 * a1 = a.map {|element| element.class }
3638 * a1 # => [Symbol, String, Integer]
3639 *
3640 * With no block given, returns a new Enumerator.
3641 *
3642 * Related: #collect!;
3643 * see also {Methods for Converting}[rdoc-ref:Array@Methods+for+Converting].
3644 */
3646 static VALUE
3648 {
3650 VALUE collect;
3656 }
3658 }
3661 /*
3662 * call-seq:
3663 * collect! {|element| ... } -> new_array
3664 * collect! -> new_enumerator
3665 * map! {|element| ... } -> new_array
3666 * map! -> new_enumerator
3667 *
3668 * With a block given, calls the block with each element of +self+
3669 * and replaces the element with the block's return value;
3670 * returns +self+:
3671 *
3672 * a = [:foo, 'bar', 2]
3673 * a.map! { |element| element.class } # => [Symbol, String, Integer]
3674 *
3675 * With no block given, returns a new Enumerator.
3676 *
3677 * Related: #collect;
3678 * see also {Methods for Converting}[rdoc-ref:Array@Methods+for+Converting].
3679 */
3681 static VALUE
3683 {
3690 }
3692 }
3694 VALUE
3695 rb_get_values_at(VALUE obj, long olen, int argc, const VALUE *argv, VALUE (*func) (VALUE, long))
3696 {
3704 }
3705 /* check if idx is Range */
3710 }
3714 }
3716 }
3718 }
3720 static VALUE
3722 {
3726 }
3727 /* check if idx is Range */
3735 }
3738 }
3739 }
3741 }
3744 }
3746 }
3748 /*
3749 * call-seq:
3750 * values_at(*specifiers) -> new_array
3751 *
3752 * Returns elements from +self+ in a new array; does not modify +self+.
3753 *
3754 * The objects included in the returned array are the elements of +self+
3755 * selected by the given +specifiers+,
3756 * each of which must be a numeric index or a Range.
3757 *
3758 * In brief:
3759 *
3760 * a = ['a', 'b', 'c', 'd']
3761 *
3762 * # Index specifiers.
3763 * a.values_at(2, 0, 2, 0) # => ["c", "a", "c", "a"] # May repeat.
3764 * a.values_at(-4, -3, -2, -1) # => ["a", "b", "c", "d"] # Counts backwards if negative.
3765 * a.values_at(-50, 50) # => [nil, nil] # Outside of self.
3766 *
3767 * # Range specifiers.
3768 * a.values_at(1..3) # => ["b", "c", "d"] # From range.begin to range.end.
3769 * a.values_at(1...3) # => ["b", "c"] # End excluded.
3770 * a.values_at(3..1) # => [] # No such elements.
3771 *
3772 * a.values_at(-3..3) # => ["b", "c", "d"] # Negative range.begin counts backwards.
3773 * a.values_at(-50..3) # Raises RangeError.
3774 *
3775 * a.values_at(1..-2) # => ["b", "c"] # Negative range.end counts backwards.
3776 * a.values_at(1..-50) # => [] # No such elements.
3777 *
3778 * # Mixture of specifiers.
3779 * a.values_at(2..3, 3, 0..1, 0) # => ["c", "d", "d", "a", "b", "a"]
3780 *
3781 * With no +specifiers+ given, returns a new empty array:
3782 *
3783 * a = ['a', 'b', 'c', 'd']
3784 * a.values_at # => []
3785 *
3786 * For each numeric specifier +index+, includes an element:
3787 *
3788 * - For each non-negative numeric specifier +index+ that is in-range (less than <tt>self.size</tt>),
3789 * includes the element at offset +index+:
3790 *
3791 * a.values_at(0, 2) # => ["a", "c"]
3792 * a.values_at(0.1, 2.9) # => ["a", "c"]
3793 *
3794 * - For each negative numeric +index+ that is in-range (greater than or equal to <tt>- self.size</tt>),
3795 * counts backwards from the end of +self+:
3796 *
3797 * a.values_at(-1, -4) # => ["d", "a"]
3798 *
3799 * The given indexes may be in any order, and may repeat:
3800 *
3801 * a.values_at(2, 0, 1, 0, 2) # => ["c", "a", "b", "a", "c"]
3802 *
3803 * For each +index+ that is out-of-range, includes +nil+:
3804 *
3805 * a.values_at(4, -5) # => [nil, nil]
3806 *
3807 * For each Range specifier +range+, includes elements
3808 * according to <tt>range.begin</tt> and <tt>range.end</tt>:
3809 *
3810 * - If both <tt>range.begin</tt> and <tt>range.end</tt>
3811 * are non-negative and in-range (less than <tt>self.size</tt>),
3812 * includes elements from index <tt>range.begin</tt>
3813 * through <tt>range.end - 1</tt> (if <tt>range.exclude_end?</tt>),
3814 * or through <tt>range.end</tt> (otherwise):
3815 *
3816 * a.values_at(1..2) # => ["b", "c"]
3817 * a.values_at(1...2) # => ["b"]
3818 *
3819 * - If <tt>range.begin</tt> is negative and in-range (greater than or equal to <tt>- self.size</tt>),
3820 * counts backwards from the end of +self+:
3821 *
3822 * a.values_at(-2..3) # => ["c", "d"]
3823 *
3824 * - If <tt>range.begin</tt> is negative and out-of-range, raises an exception:
3825 *
3826 * a.values_at(-5..3) # Raises RangeError.
3827 *
3828 * - If <tt>range.end</tt> is positive and out-of-range,
3829 * extends the returned array with +nil+ elements:
3830 *
3831 * a.values_at(1..5) # => ["b", "c", "d", nil, nil]
3832 *
3833 * - If <tt>range.end</tt> is negative and in-range,
3834 * counts backwards from the end of +self+:
3835 *
3836 * a.values_at(1..-2) # => ["b", "c"]
3837 *
3838 * - If <tt>range.end</tt> is negative and out-of-range,
3839 * returns an empty array:
3840 *
3841 * a.values_at(1..-5) # => []
3842 *
3843 * The given ranges may be in any order and may repeat:
3844 *
3845 * a.values_at(2..3, 0..1, 2..3) # => ["c", "d", "a", "b", "c", "d"]
3846 *
3847 * The given specifiers may be any mixture of indexes and ranges:
3848 *
3849 * a.values_at(3, 1..2, 0, 2..3) # => ["d", "b", "c", "a", "c", "d"]
3850 *
3851 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
3852 */
3854 static VALUE
3856 {
3861 }
3864 }
3867 /*
3868 * call-seq:
3869 * select {|element| ... } -> new_array
3870 * select -> new_enumerator
3871 * filter {|element| ... } -> new_array
3872 * filter -> new_enumerator
3873 *
3874 * With a block given, calls the block with each element of +self+;
3875 * returns a new array containing those elements of +self+
3876 * for which the block returns a truthy value:
3877 *
3878 * a = [:foo, 'bar', 2, :bam]
3879 * a.select {|element| element.to_s.start_with?('b') }
3880 * # => ["bar", :bam]
3881 *
3882 * With no block given, returns a new Enumerator.
3883 *
3884 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
3885 */
3887 static VALUE
3889 {
3890 VALUE result;
3898 }
3899 }
3901 }
3904 VALUE ary;
3906 };
3908 static VALUE
3910 {
3920 }
3922 }
3924 }
3926 static VALUE
3928 {
3941 });
3942 }
3944 }
3946 }
3948 /*
3949 * call-seq:
3950 * select! {|element| ... } -> self or nil
3951 * select! -> new_enumerator
3952 * filter! {|element| ... } -> self or nil
3953 * filter! -> new_enumerator
3954 *
3955 * With a block given, calls the block with each element of +self+;
3956 * removes from +self+ those elements for which the block returns +false+ or +nil+.
3957 *
3958 * Returns +self+ if any elements were removed:
3959 *
3960 * a = [:foo, 'bar', 2, :bam]
3961 * a.select! {|element| element.to_s.start_with?('b') } # => ["bar", :bam]
3962 *
3963 * Returns +nil+ if no elements were removed.
3964 *
3965 * With no block given, returns a new Enumerator.
3966 *
3967 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
3968 */
3970 static VALUE
3972 {
3981 }
3983 /*
3984 * call-seq:
3985 * keep_if {|element| ... } -> self
3986 * keep_if -> new_enumerator
3987 *
3988 * With a block given, calls the block with each element of +self+;
3989 * removes the element from +self+ if the block does not return a truthy value:
3990 *
3991 * a = [:foo, 'bar', 2, :bam]
3992 * a.keep_if {|element| element.to_s.start_with?('b') } # => ["bar", :bam]
3993 *
3994 * With no block given, returns a new Enumerator.
3995 *
3996 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
3997 */
3999 static VALUE
4001 {
4005 }
4007 static void
4009 {
4016 }
4017 }
4018 }
4020 /*
4021 * call-seq:
4022 * delete(object) -> last_removed_object
4023 * delete(object) {|element| ... } -> last_removed_object or block_return
4024 *
4025 * Removes zero or more elements from +self+.
4026 *
4027 * With no block given,
4028 * removes from +self+ each element +ele+ such that <tt>ele == object</tt>;
4029 * returns the last removed element:
4030 *
4031 * a = [0, 1, 2, 2.0]
4032 * a.delete(2) # => 2.0
4033 * a # => [0, 1]
4034 *
4035 * Returns +nil+ if no elements removed:
4036 *
4037 * a.delete(2) # => nil
4038 *
4039 * With a block given,
4040 * removes from +self+ each element +ele+ such that <tt>ele == object</tt>.
4041 *
4042 * If any such elements are found, ignores the block
4043 * and returns the last removed element:
4044 *
4045 * a = [0, 1, 2, 2.0]
4046 * a.delete(2) {|element| fail 'Cannot happen' } # => 2.0
4047 * a # => [0, 1]
4048 *
4049 * If no such element is found, returns the block's return value:
4050 *
4051 * a.delete(2) {|element| "Element #{element} not found." }
4052 * # => "Element 2 not found."
4053 *
4054 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
4055 */
4057 VALUE
4059 {
4069 }
4072 }
4073 i2++;
4074 }
4078 }
4080 }
4086 }
4088 void
4090 {
4098 }
4101 }
4102 i2++;
4103 }
4106 }
4109 }
4111 VALUE
4113 {
4115 VALUE del;
4121 }
4127 });
4131 }
4133 /*
4134 * call-seq:
4135 * delete_at(index) -> removed_object or nil
4136 *
4137 * Removes the element of +self+ at the given +index+, which must be an
4138 * {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects].
4139 *
4140 * When +index+ is non-negative, deletes the element at offset +index+:
4141 *
4142 * a = [:foo, 'bar', 2]
4143 * a.delete_at(1) # => "bar"
4144 * a # => [:foo, 2]
4145 *
4146 * When +index+ is negative, counts backward from the end of the array:
4147 *
4148 * a = [:foo, 'bar', 2]
4149 * a.delete_at(-2) # => "bar"
4150 * a # => [:foo, 2]
4151 *
4152 * When +index+ is out of range, returns +nil+.
4153 *
4154 * a = [:foo, 'bar', 2]
4155 * a.delete_at(3) # => nil
4156 * a.delete_at(-4) # => nil
4157 *
4158 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
4159 */
4161 static VALUE
4163 {
4165 }
4167 static VALUE
4169 {
4174 }
4177 }
4180 }
4183 }
4186 }
4189 }
4194 }
4195 }
4197 /*
4198 * call-seq:
4199 * slice!(index) -> object or nil
4200 * slice!(start, length) -> new_array or nil
4201 * slice!(range) -> new_array or nil
4202 *
4203 * Removes and returns elements from +self+.
4204 *
4205 * With numeric argument +index+ given,
4206 * removes and returns the element at offset +index+:
4207 *
4208 * a = ['a', 'b', 'c', 'd']
4209 * a.slice!(2) # => "c"
4210 * a # => ["a", "b", "d"]
4211 * a.slice!(2.1) # => "d"
4212 * a # => ["a", "b"]
4213 *
4214 * If +index+ is negative, counts backwards from the end of +self+:
4215 *
4216 * a = ['a', 'b', 'c', 'd']
4217 * a.slice!(-2) # => "c"
4218 * a # => ["a", "b", "d"]
4219 *
4220 * If +index+ is out of range, returns +nil+.
4221 *
4222 * With numeric arguments +start+ and +length+ given,
4223 * removes +length+ elements from +self+ beginning at zero-based offset +start+;
4224 * returns the removed objects in a new array:
4225 *
4226 * a = ['a', 'b', 'c', 'd']
4227 * a.slice!(1, 2) # => ["b", "c"]
4228 * a # => ["a", "d"]
4229 * a.slice!(0.1, 1.1) # => ["a"]
4230 * a # => ["d"]
4231 *
4232 * If +start+ is negative, counts backwards from the end of +self+:
4233 *
4234 * a = ['a', 'b', 'c', 'd']
4235 * a.slice!(-2, 1) # => ["c"]
4236 * a # => ["a", "b", "d"]
4237 *
4238 * If +start+ is out-of-range, returns +nil+:
4239 *
4240 * a = ['a', 'b', 'c', 'd']
4241 * a.slice!(5, 1) # => nil
4242 * a.slice!(-5, 1) # => nil
4243 *
4244 * If <tt>start + length</tt> exceeds the array size,
4245 * removes and returns all elements from offset +start+ to the end:
4246 *
4247 * a = ['a', 'b', 'c', 'd']
4248 * a.slice!(2, 50) # => ["c", "d"]
4249 * a # => ["a", "b"]
4250 *
4251 * If <tt>start == a.size</tt> and +length+ is non-negative,
4252 * returns a new empty array.
4253 *
4254 * If +length+ is negative, returns +nil+.
4255 *
4256 * With Range argument +range+ given,
4257 * treats <tt>range.min</tt> as +start+ (as above)
4258 * and <tt>range.size</tt> as +length+ (as above):
4259 *
4260 * a = ['a', 'b', 'c', 'd']
4261 * a.slice!(1..2) # => ["b", "c"]
4262 * a # => ["a", "d"]
4263 *
4264 * If <tt>range.start == a.size</tt>, returns a new empty array:
4265 *
4266 * a = ['a', 'b', 'c', 'd']
4267 * a.slice!(4..5) # => []
4268 *
4269 * If <tt>range.start</tt> is larger than the array size, returns +nil+:
4270 *
4271 * a = ['a', 'b', 'c', 'd']
4272 a.slice!(5..6) # => nil
4273 *
4274 * If <tt>range.start</tt> is negative,
4275 * calculates the start index by counting backwards from the end of +self+:
4276 *
4277 * a = ['a', 'b', 'c', 'd']
4278 * a.slice!(-2..2) # => ["c"]
4279 *
4280 * If <tt>range.end</tt> is negative,
4281 * calculates the end index by counting backwards from the end of +self+:
4282 *
4283 * a = ['a', 'b', 'c', 'd']
4284 * a.slice!(0..-2) # => ["a", "b", "c"]
4285 *
4286 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
4287 */
4289 static VALUE
4291 {
4292 VALUE arg1;
4303 }
4308 /* valid range */
4311 /* invalid range */
4314 /* not a range */
4316 }
4317 }
4320 }
4322 static VALUE
4324 {
4332 }
4333 }
4335 }
4337 static VALUE
4339 {
4349 }
4351 }
4353 }
4355 static VALUE
4357 {
4363 }
4365 /*
4366 * call-seq:
4367 * reject! {|element| ... } -> self or nil
4368 * reject! -> new_enumerator
4369 *
4370 * With a block given, calls the block with each element of +self+;
4371 * removes each element for which the block returns a truthy value.
4372 *
4373 * Returns +self+ if any elements removed:
4374 *
4375 * a = [:foo, 'bar', 2, 'bat']
4376 * a.reject! {|element| element.to_s.start_with?('b') } # => [:foo, 2]
4377 *
4378 * Returns +nil+ if no elements removed.
4379 *
4380 * With no block given, returns a new Enumerator.
4381 *
4382 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
4383 */
4385 static VALUE
4387 {
4391 }
4393 /*
4394 * call-seq:
4395 * reject {|element| ... } -> new_array
4396 * reject -> new_enumerator
4397 *
4398 * With a block given, returns a new array whose elements are all those from +self+
4399 * for which the block returns +false+ or +nil+:
4400 *
4401 * a = [:foo, 'bar', 2, 'bat']
4402 * a1 = a.reject {|element| element.to_s.start_with?('b') }
4403 * a1 # => [:foo, 2]
4404 *
4405 * With no block given, returns a new Enumerator.
4406 *
4407 * Related: {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
4408 */
4410 static VALUE
4412 {
4413 VALUE rejected_ary;
4419 }
4421 /*
4422 * call-seq:
4423 * delete_if {|element| ... } -> self
4424 * delete_if -> new_numerator
4425 *
4426 * With a block given, calls the block with each element of +self+;
4427 * removes the element if the block returns a truthy value;
4428 * returns +self+:
4429 *
4430 * a = [:foo, 'bar', 2, 'bat']
4431 * a.delete_if {|element| element.to_s.start_with?('b') } # => [:foo, 2]
4432 *
4433 * With no block given, returns a new Enumerator.
4434 *
4435 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
4436 */
4438 static VALUE
4440 {
4445 }
4447 static VALUE
4449 {
4455 }
4457 static VALUE
4459 {
4471 }
4474 /*
4475 * call-seq:
4476 * zip(*other_arrays) -> new_array
4477 * zip(*other_arrays) {|sub_array| ... } -> nil
4478 *
4479 * With no block given, combines +self+ with the collection of +other_arrays+;
4480 * returns a new array of sub-arrays:
4481 *
4482 * [0, 1].zip(['zero', 'one'], [:zero, :one])
4483 * # => [[0, "zero", :zero], [1, "one", :one]]
4484 *
4485 * Returned:
4486 *
4487 * - The outer array is of size <tt>self.size</tt>.
4488 * - Each sub-array is of size <tt>other_arrays.size + 1</tt>.
4489 * - The _nth_ sub-array contains (in order):
4490 *
4491 * - The _nth_ element of +self+.
4492 * - The _nth_ element of each of the other arrays, as available.
4493 *
4494 * Example:
4495 *
4496 * a = [0, 1]
4497 * zipped = a.zip(['zero', 'one'], [:zero, :one])
4498 * # => [[0, "zero", :zero], [1, "one", :one]]
4499 * zipped.size # => 2 # Same size as a.
4500 * zipped.first.size # => 3 # Size of other arrays plus 1.
4501 *
4502 * When the other arrays are all the same size as +self+,
4503 * the returned sub-arrays are a rearrangement containing exactly elements of all the arrays
4504 * (including +self+), with no omissions or additions:
4505 *
4506 * a = [:a0, :a1, :a2, :a3]
4507 * b = [:b0, :b1, :b2, :b3]
4508 * c = [:c0, :c1, :c2, :c3]
4509 * d = a.zip(b, c)
4510 * pp d
4511 * # =>
4512 * [[:a0, :b0, :c0],
4513 * [:a1, :b1, :c1],
4514 * [:a2, :b2, :c2],
4515 * [:a3, :b3, :c3]]
4516 *
4517 * When one of the other arrays is smaller than +self+,
4518 * pads the corresponding sub-array with +nil+ elements:
4519 *
4520 * a = [:a0, :a1, :a2, :a3]
4521 * b = [:b0, :b1, :b2]
4522 * c = [:c0, :c1]
4523 * d = a.zip(b, c)
4524 * pp d
4525 * # =>
4526 * [[:a0, :b0, :c0],
4527 * [:a1, :b1, :c1],
4528 * [:a2, :b2, nil],
4529 * [:a3, nil, nil]]
4530 *
4531 * When one of the other arrays is larger than +self+,
4532 * _ignores_ its trailing elements:
4533 *
4534 * a = [:a0, :a1, :a2, :a3]
4535 * b = [:b0, :b1, :b2, :b3, :b4]
4536 * c = [:c0, :c1, :c2, :c3, :c4, :c5]
4537 * d = a.zip(b, c)
4538 * pp d
4539 * # =>
4540 * [[:a0, :b0, :c0],
4541 * [:a1, :b1, :c1],
4542 * [:a2, :b2, :c2],
4543 * [:a3, :b3, :c3]]
4544 *
4545 * With a block given, calls the block with each of the other arrays;
4546 * returns +nil+:
4547 *
4548 * d = []
4549 * a = [:a0, :a1, :a2, :a3]
4550 * b = [:b0, :b1, :b2, :b3]
4551 * c = [:c0, :c1, :c2, :c3]
4552 * a.zip(b, c) {|sub_array| d.push(sub_array.reverse) } # => nil
4553 * pp d
4554 * # =>
4555 * [[:c0, :b0, :a0],
4556 * [:c1, :b1, :a1],
4557 * [:c2, :b2, :a2],
4558 * [:c3, :b3, :a3]]
4559 *
4560 * For an *object* in *other_arrays* that is not actually an array,
4561 * forms the the "other array" as <tt>object.to_ary</tt>, if defined,
4562 * or as <tt>object.each.to_a</tt> otherwise.
4563 *
4564 * Related: see {Methods for Converting}[rdoc-ref:Array@Methods+for+Converting].
4565 */
4567 static VALUE
4569 {
4576 }
4590 }
4592 }
4595 }
4603 }
4605 }
4606 }
4607 }
4617 }
4619 }
4620 }
4623 }
4625 /*
4626 * call-seq:
4627 * transpose -> new_array
4628 *
4629 * Returns a new array that is +self+
4630 * as a {transposed matrix}[https://en.wikipedia.org/wiki/Transpose]:
4631 *
4632 * a = [[:a0, :a1], [:b0, :b1], [:c0, :c1]]
4633 * a.transpose # => [[:a0, :b0, :c0], [:a1, :b1, :c1]]
4634 *
4635 * The elements of +self+ must all be the same size.
4636 *
4637 * Related: see {Methods for Converting}[rdoc-ref:Array@Methods+for+Converting].
4638 */
4640 static VALUE
4642 {
4655 }
4656 }
4660 }
4663 }
4664 }
4666 }
4668 /*
4669 * call-seq:
4670 * initialize_copy(other_array) -> self
4671 * replace(other_array) -> self
4672 *
4673 * Replaces the elements of +self+ with the elements of +other_array+, which must be an
4674 * {array-convertible object}[rdoc-ref:implicit_conversion.rdoc@Array-Convertible+Objects];
4675 * returns +self+:
4676 *
4677 * a = ['a', 'b', 'c'] # => ["a", "b", "c"]
4678 * a.replace(['d', 'e']) # => ["d", "e"]
4679 *
4680 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
4681 */
4683 VALUE
4685 {
4692 /* orig has enough space to embed the contents of orig. */
4697 }
4698 /* orig is embedded but copy does not have enough space to embed the
4699 * contents of orig. */
4709 // No allocation and exception expected that could leave `copy` in a
4710 // bad state from the edits above.
4712 }
4713 /* Otherwise, orig is on heap and copy does not have enough space to embed
4714 * the contents of orig. */
4721 }
4724 }
4726 /*
4727 * call-seq:
4728 * clear -> self
4729 *
4730 * Removes all elements from +self+; returns +self+:
4731 *
4732 * a = [:foo, 'bar', 2]
4733 * a.clear # => []
4734 *
4735 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
4736 */
4738 VALUE
4740 {
4746 }
4751 }
4752 }
4755 }
4757 /*
4758 * call-seq:
4759 * fill(object, start = nil, count = nil) -> new_array
4760 * fill(object, range) -> new_array
4761 * fill(start = nil, count = nil) {|element| ... } -> new_array
4762 * fill(range) {|element| ... } -> new_array
4763 *
4764 * Replaces selected elements in +self+;
4765 * may add elements to +self+;
4766 * always returns +self+ (never a new array).
4767 *
4768 * In brief:
4769 *
4770 * # Non-negative start.
4771 * ['a', 'b', 'c', 'd'].fill('-', 1, 2) # => ["a", "-", "-", "d"]
4772 * ['a', 'b', 'c', 'd'].fill(1, 2) {|e| e.to_s } # => ["a", "1", "2", "d"]
4773 *
4774 * # Extends with specified values if necessary.
4775 * ['a', 'b', 'c', 'd'].fill('-', 3, 2) # => ["a", "b", "c", "-", "-"]
4776 * ['a', 'b', 'c', 'd'].fill(3, 2) {|e| e.to_s } # => ["a", "b", "c", "3", "4"]
4777 *
4778 * # Fills with nils if necessary.
4779 * ['a', 'b', 'c', 'd'].fill('-', 6, 2) # => ["a", "b", "c", "d", nil, nil, "-", "-"]
4780 * ['a', 'b', 'c', 'd'].fill(6, 2) {|e| e.to_s } # => ["a", "b", "c", "d", nil, nil, "6", "7"]
4781 *
4782 * # For negative start, counts backwards from the end.
4783 * ['a', 'b', 'c', 'd'].fill('-', -3, 3) # => ["a", "-", "-", "-"]
4784 * ['a', 'b', 'c', 'd'].fill(-3, 3) {|e| e.to_s } # => ["a", "1", "2", "3"]
4785 *
4786 * # Range.
4787 * ['a', 'b', 'c', 'd'].fill('-', 1..2) # => ["a", "-", "-", "d"]
4788 * ['a', 'b', 'c', 'd'].fill(1..2) {|e| e.to_s } # => ["a", "1", "2", "d"]
4789 *
4790 * When arguments +start+ and +count+ are given,
4791 * they select the elements of +self+ to be replaced;
4792 * each must be an
4793 * {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects]
4794 * (or +nil+):
4795 *
4796 * - +start+ specifies the zero-based offset of the first element to be replaced;
4797 * +nil+ means zero.
4798 * - +count+ is the number of consecutive elements to be replaced;
4799 * +nil+ means "all the rest."
4800 *
4801 * With argument +object+ given,
4802 * that one object is used for all replacements:
4803 *
4804 * o = Object.new # => #<Object:0x0000014e7bff7600>
4805 * a = ['a', 'b', 'c', 'd'] # => ["a", "b", "c", "d"]
4806 * a.fill(o, 1, 2)
4807 * # => ["a", #<Object:0x0000014e7bff7600>, #<Object:0x0000014e7bff7600>, "d"]
4808 *
4809 * With a block given, the block is called once for each element to be replaced;
4810 * the value passed to the block is the _index_ of the element to be replaced
4811 * (not the element itself);
4812 * the block's return value replaces the element:
4813 *
4814 * a = ['a', 'b', 'c', 'd'] # => ["a", "b", "c", "d"]
4815 * a.fill(1, 2) {|element| element.to_s } # => ["a", "1", "2", "d"]
4816 *
4817 * For arguments +start+ and +count+:
4818 *
4819 * - If +start+ is non-negative,
4820 * replaces +count+ elements beginning at offset +start+:
4821 *
4822 * ['a', 'b', 'c', 'd'].fill('-', 0, 2) # => ["-", "-", "c", "d"]
4823 * ['a', 'b', 'c', 'd'].fill('-', 1, 2) # => ["a", "-", "-", "d"]
4824 * ['a', 'b', 'c', 'd'].fill('-', 2, 2) # => ["a", "b", "-", "-"]
4825 *
4826 * ['a', 'b', 'c', 'd'].fill(0, 2) {|e| e.to_s } # => ["0", "1", "c", "d"]
4827 * ['a', 'b', 'c', 'd'].fill(1, 2) {|e| e.to_s } # => ["a", "1", "2", "d"]
4828 * ['a', 'b', 'c', 'd'].fill(2, 2) {|e| e.to_s } # => ["a", "b", "2", "3"]
4829 *
4830 * Extends +self+ if necessary:
4831 *
4832 * ['a', 'b', 'c', 'd'].fill('-', 3, 2) # => ["a", "b", "c", "-", "-"]
4833 * ['a', 'b', 'c', 'd'].fill('-', 4, 2) # => ["a", "b", "c", "d", "-", "-"]
4834 *
4835 * ['a', 'b', 'c', 'd'].fill(3, 2) {|e| e.to_s } # => ["a", "b", "c", "3", "4"]
4836 * ['a', 'b', 'c', 'd'].fill(4, 2) {|e| e.to_s } # => ["a", "b", "c", "d", "4", "5"]
4837 *
4838 * Fills with +nil+ if necessary:
4839 *
4840 * ['a', 'b', 'c', 'd'].fill('-', 5, 2) # => ["a", "b", "c", "d", nil, "-", "-"]
4841 * ['a', 'b', 'c', 'd'].fill('-', 6, 2) # => ["a", "b", "c", "d", nil, nil, "-", "-"]
4842 *
4843 * ['a', 'b', 'c', 'd'].fill(5, 2) {|e| e.to_s } # => ["a", "b", "c", "d", nil, "5", "6"]
4844 * ['a', 'b', 'c', 'd'].fill(6, 2) {|e| e.to_s } # => ["a", "b", "c", "d", nil, nil, "6", "7"]
4845 *
4846 * Does nothing if +count+ is non-positive:
4847 *
4848 * ['a', 'b', 'c', 'd'].fill('-', 2, 0) # => ["a", "b", "c", "d"]
4849 * ['a', 'b', 'c', 'd'].fill('-', 2, -100) # => ["a", "b", "c", "d"]
4850 * ['a', 'b', 'c', 'd'].fill('-', 6, -100) # => ["a", "b", "c", "d"]
4851 *
4852 * ['a', 'b', 'c', 'd'].fill(2, 0) {|e| fail 'Cannot happen' } # => ["a", "b", "c", "d"]
4853 * ['a', 'b', 'c', 'd'].fill(2, -100) {|e| fail 'Cannot happen' } # => ["a", "b", "c", "d"]
4854 * ['a', 'b', 'c', 'd'].fill(6, -100) {|e| fail 'Cannot happen' } # => ["a", "b", "c", "d"]
4855 *
4856 * - If +start+ is negative, counts backwards from the end of +self+:
4857 *
4858 * ['a', 'b', 'c', 'd'].fill('-', -4, 3) # => ["-", "-", "-", "d"]
4859 * ['a', 'b', 'c', 'd'].fill('-', -3, 3) # => ["a", "-", "-", "-"]
4860 *
4861 * ['a', 'b', 'c', 'd'].fill(-4, 3) {|e| e.to_s } # => ["0", "1", "2", "d"]
4862 * ['a', 'b', 'c', 'd'].fill(-3, 3) {|e| e.to_s } # => ["a", "1", "2", "3"]
4863 *
4864 * Extends +self+ if necessary:
4865 *
4866 * ['a', 'b', 'c', 'd'].fill('-', -2, 3) # => ["a", "b", "-", "-", "-"]
4867 * ['a', 'b', 'c', 'd'].fill('-', -1, 3) # => ["a", "b", "c", "-", "-", "-"]
4868 *
4869 * ['a', 'b', 'c', 'd'].fill(-2, 3) {|e| e.to_s } # => ["a", "b", "2", "3", "4"]
4870 * ['a', 'b', 'c', 'd'].fill(-1, 3) {|e| e.to_s } # => ["a", "b", "c", "3", "4", "5"]
4871 *
4872 * Starts at the beginning of +self+ if +start+ is negative and out-of-range:
4873 *
4874 * ['a', 'b', 'c', 'd'].fill('-', -5, 2) # => ["-", "-", "c", "d"]
4875 * ['a', 'b', 'c', 'd'].fill('-', -6, 2) # => ["-", "-", "c", "d"]
4876 *
4877 * ['a', 'b', 'c', 'd'].fill(-5, 2) {|e| e.to_s } # => ["0", "1", "c", "d"]
4878 * ['a', 'b', 'c', 'd'].fill(-6, 2) {|e| e.to_s } # => ["0", "1", "c", "d"]
4879 *
4880 * Does nothing if +count+ is non-positive:
4881 *
4882 * ['a', 'b', 'c', 'd'].fill('-', -2, 0) # => ["a", "b", "c", "d"]
4883 * ['a', 'b', 'c', 'd'].fill('-', -2, -1) # => ["a", "b", "c", "d"]
4884 *
4885 * ['a', 'b', 'c', 'd'].fill(-2, 0) {|e| fail 'Cannot happen' } # => ["a", "b", "c", "d"]
4886 * ['a', 'b', 'c', 'd'].fill(-2, -1) {|e| fail 'Cannot happen' } # => ["a", "b", "c", "d"]
4887 *
4888 * When argument +range+ is given,
4889 * it must be a Range object whose members are numeric;
4890 * its +begin+ and +end+ values determine the elements of +self+
4891 * to be replaced:
4892 *
4893 * - If both +begin+ and +end+ are positive, they specify the first and last elements
4894 * to be replaced:
4895 *
4896 * ['a', 'b', 'c', 'd'].fill('-', 1..2) # => ["a", "-", "-", "d"]
4897 * ['a', 'b', 'c', 'd'].fill(1..2) {|e| e.to_s } # => ["a", "1", "2", "d"]
4898 *
4899 * If +end+ is smaller than +begin+, replaces no elements:
4900 *
4901 * ['a', 'b', 'c', 'd'].fill('-', 2..1) # => ["a", "b", "c", "d"]
4902 * ['a', 'b', 'c', 'd'].fill(2..1) {|e| e.to_s } # => ["a", "b", "c", "d"]
4903 *
4904 * - If either is negative (or both are negative), counts backwards from the end of +self+:
4905 *
4906 * ['a', 'b', 'c', 'd'].fill('-', -3..2) # => ["a", "-", "-", "d"]
4907 * ['a', 'b', 'c', 'd'].fill('-', 1..-2) # => ["a", "-", "-", "d"]
4908 * ['a', 'b', 'c', 'd'].fill('-', -3..-2) # => ["a", "-", "-", "d"]
4909 *
4910 * ['a', 'b', 'c', 'd'].fill(-3..2) {|e| e.to_s } # => ["a", "1", "2", "d"]
4911 * ['a', 'b', 'c', 'd'].fill(1..-2) {|e| e.to_s } # => ["a", "1", "2", "d"]
4912 * ['a', 'b', 'c', 'd'].fill(-3..-2) {|e| e.to_s } # => ["a", "1", "2", "d"]
4913 *
4914 * - If the +end+ value is excluded (see Range#exclude_end?), omits the last replacement:
4915 *
4916 * ['a', 'b', 'c', 'd'].fill('-', 1...2) # => ["a", "-", "c", "d"]
4917 * ['a', 'b', 'c', 'd'].fill('-', 1...-2) # => ["a", "-", "c", "d"]
4918 *
4919 * ['a', 'b', 'c', 'd'].fill(1...2) {|e| e.to_s } # => ["a", "1", "c", "d"]
4920 * ['a', 'b', 'c', 'd'].fill(1...-2) {|e| e.to_s } # => ["a", "1", "c", "d"]
4921 *
4922 * - If the range is endless (see {Endless Ranges}[rdoc-ref:Range@Endless+Ranges]),
4923 * replaces elements to the end of +self+:
4924 *
4925 * ['a', 'b', 'c', 'd'].fill('-', 1..) # => ["a", "-", "-", "-"]
4926 * ['a', 'b', 'c', 'd'].fill(1..) {|e| e.to_s } # => ["a", "1", "2", "3"]
4927 *
4928 * - If the range is beginless (see {Beginless Ranges}[rdoc-ref:Range@Beginless+Ranges]),
4929 * replaces elements from the beginning of +self+:
4930 *
4931 * ['a', 'b', 'c', 'd'].fill('-', ..2) # => ["-", "-", "-", "d"]
4932 * ['a', 'b', 'c', 'd'].fill(..2) {|e| e.to_s } # => ["0", "1", "2", "d"]
4933 *
4934 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
4935 */
4937 static VALUE
4939 {
4946 }
4949 }
4958 }
4959 /* fall through */
4965 }
4968 }
4972 }
4975 }
4980 }
4983 }
4986 VALUE v;
4993 }
4994 }
4997 }
4999 }
5001 /*
5002 * call-seq:
5003 * self + other_array -> new_array
5004 *
5005 * Returns a new array containing all elements of +self+
5006 * followed by all elements of +other_array+:
5007 *
5008 * a = [0, 1] + [2, 3]
5009 * a # => [0, 1, 2, 3]
5010 *
5011 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
5012 */
5014 VALUE
5016 {
5017 VALUE z;
5030 }
5032 static VALUE
5034 {
5038 }
5041 }
5043 /*
5044 * call-seq:
5045 * concat(*other_arrays) -> self
5046 *
5047 * Adds to +self+ all elements from each array in +other_arrays+; returns +self+:
5048 *
5049 * a = [0, 1]
5050 * a.concat(['two', 'three'], [:four, :five], a)
5051 * # => [0, 1, "two", "three", :four, :five, 0, 1]
5052 *
5053 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
5054 */
5056 static VALUE
5058 {
5063 }
5069 }
5071 }
5075 }
5077 VALUE
5079 {
5081 }
5083 /*
5084 * call-seq:
5085 * self * n -> new_array
5086 * self * string_separator -> new_string
5087 *
5088 * When non-negative integer argument +n+ is given,
5089 * returns a new array built by concatenating +n+ copies of +self+:
5090 *
5091 * a = ['x', 'y']
5092 * a * 3 # => ["x", "y", "x", "y", "x", "y"]
5093 *
5094 * When string argument +string_separator+ is given,
5095 * equivalent to <tt>self.join(string_separator)</tt>:
5096 *
5097 * [0, [0, 1], {foo: 0}] * ', ' # => "0, 0, 1, {foo: 0}"
5098 *
5099 */
5101 static VALUE
5103 {
5111 }
5117 }
5120 }
5123 }
5136 }
5139 }
5140 }
5141 out:
5143 }
5145 /*
5146 * call-seq:
5147 * assoc(object) -> found_array or nil
5148 *
5149 * Returns the first element +ele+ in +self+ such that +ele+ is an array
5150 * and <tt>ele[0] == object</tt>:
5151 *
5152 * a = [{foo: 0}, [2, 4], [4, 5, 6], [4, 5]]
5153 * a.assoc(4) # => [4, 5, 6]
5154 *
5155 * Returns +nil+ if no such element is found.
5156 *
5157 * Related: Array#rassoc;
5158 * see also {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
5159 */
5161 VALUE
5163 {
5165 VALUE v;
5172 }
5174 }
5176 /*
5177 * call-seq:
5178 * rassoc(object) -> found_array or nil
5179 *
5180 * Returns the first element +ele+ in +self+ such that +ele+ is an array
5181 * and <tt>ele[1] == object</tt>:
5182 *
5183 * a = [{foo: 0}, [2, 4], [4, 5, 6], [4, 5]]
5184 * a.rassoc(4) # => [2, 4]
5185 * a.rassoc(5) # => [4, 5, 6]
5186 *
5187 * Returns +nil+ if no such element is found.
5188 *
5189 * Related: Array#assoc;
5190 * see also {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
5191 */
5193 VALUE
5195 {
5197 VALUE v;
5205 }
5207 }
5209 static VALUE
5211 {
5217 /* rb_equal() can evacuate ptrs */
5232 }
5235 }
5236 }
5237 p1++;
5238 p2++;
5239 }
5241 }
5243 /*
5244 * call-seq:
5245 * self == other_array -> true or false
5246 *
5247 * Returns whether both:
5248 *
5249 * - +self+ and +other_array+ are the same size.
5250 * - Their corresponding elements are the same;
5251 * that is, for each index +i+ in <tt>(0...self.size)</tt>,
5252 * <tt>self[i] == other_array[i]</tt>.
5253 *
5254 * Examples:
5255 *
5256 * [:foo, 'bar', 2] == [:foo, 'bar', 2] # => true
5257 * [:foo, 'bar', 2] == [:foo, 'bar', 2.0] # => true
5258 * [:foo, 'bar', 2] == [:foo, 'bar'] # => false # Different sizes.
5259 * [:foo, 'bar', 2] == [:foo, 'bar', 3] # => false # Different elements.
5260 *
5261 * This method is different from method Array#eql?,
5262 * which compares elements using <tt>Object#eql?</tt>.
5263 *
5264 * Related: see {Methods for Comparing}[rdoc-ref:Array@Methods+for+Comparing].
5265 */
5267 static VALUE
5269 {
5274 }
5276 }
5280 }
5282 static VALUE
5284 {
5291 }
5293 }
5295 /*
5296 * call-seq:
5297 * eql?(other_array) -> true or false
5298 *
5299 * Returns +true+ if +self+ and +other_array+ are the same size,
5300 * and if, for each index +i+ in +self+, <tt>self[i].eql?(other_array[i])</tt>:
5301 *
5302 * a0 = [:foo, 'bar', 2]
5303 * a1 = [:foo, 'bar', 2]
5304 * a1.eql?(a0) # => true
5305 *
5306 * Otherwise, returns +false+.
5307 *
5308 * This method is different from method Array#==,
5309 * which compares using method <tt>Object#==</tt>.
5310 *
5311 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
5312 */
5314 static VALUE
5316 {
5322 }
5324 VALUE
5326 {
5328 st_index_t h;
5329 VALUE n;
5336 }
5339 }
5341 /*
5342 * call-seq:
5343 * hash -> integer
5344 *
5345 * Returns the integer hash value for +self+.
5346 *
5347 * Two arrays with the same content will have the same hash value
5348 * (and will compare using eql?):
5349 *
5350 * ['a', 'b'].hash == ['a', 'b'].hash # => true
5351 * ['a', 'b'].hash == ['a', 'c'].hash # => false
5352 * ['a', 'b'].hash == ['a'].hash # => false
5353 *
5354 */
5356 static VALUE
5358 {
5360 }
5362 /*
5363 * call-seq:
5364 * include?(object) -> true or false
5365 *
5366 * Returns whether for some element +element+ in +self+,
5367 * <tt>object == element</tt>:
5368 *
5369 * [0, 1, 2].include?(2) # => true
5370 * [0, 1, 2].include?(2.0) # => true
5371 * [0, 1, 2].include?(2.1) # => false
5372 *
5373 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
5374 */
5376 VALUE
5378 {
5380 VALUE e;
5386 }
5387 }
5389 }
5391 static VALUE
5393 {
5395 VALUE e;
5401 }
5402 }
5404 }
5406 static VALUE
5408 {
5415 }
5421 }
5422 }
5424 }
5426 /*
5427 * call-seq:
5428 * self <=> other_array -> -1, 0, or 1
5429 *
5430 * Returns -1, 0, or 1 as +self+ is determined
5431 * to be less than, equal to, or greater than +other_array+.
5432 *
5433 * Iterates over each index +i+ in <tt>(0...self.size)</tt>:
5434 *
5435 * - Computes <tt>result[i]</tt> as <tt>self[i] <=> other_array[i]</tt>.
5436 * - Immediately returns 1 if <tt>result[i]</tt> is 1:
5437 *
5438 * [0, 1, 2] <=> [0, 0, 2] # => 1
5439 *
5440 * - Immediately returns -1 if <tt>result[i]</tt> is -1:
5441 *
5442 * [0, 1, 2] <=> [0, 2, 2] # => -1
5443 *
5444 * - Continues if <tt>result[i]</tt> is 0.
5445 *
5446 * When every +result+ is 0,
5447 * returns <tt>self.size <=> other_array.size</tt>
5448 * (see Integer#<=>):
5449 *
5450 * [0, 1, 2] <=> [0, 1] # => 1
5451 * [0, 1, 2] <=> [0, 1, 2] # => 0
5452 * [0, 1, 2] <=> [0, 1, 2, 3] # => -1
5453 *
5454 * Note that when +other_array+ is larger than +self+,
5455 * its trailing elements do not affect the result:
5456 *
5457 * [0, 1, 2] <=> [0, 1, 2, -3] # => -1
5458 * [0, 1, 2] <=> [0, 1, 2, 0] # => -1
5459 * [0, 1, 2] <=> [0, 1, 2, 3] # => -1
5460 *
5461 * Related: see {Methods for Comparing}[rdoc-ref:Array@Methods+for+Comparing].
5462 */
5464 VALUE
5466 {
5468 VALUE v;
5479 }
5481 static VALUE
5483 {
5489 }
5491 }
5495 {
5501 }
5503 static VALUE
5505 {
5508 }
5510 static VALUE
5512 {
5518 }
5520 }
5522 static VALUE
5524 {
5527 }
5529 /*
5530 * call-seq:
5531 * self - other_array -> new_array
5532 *
5533 * Returns a new array containing only those elements of +self+
5534 * that are not found in +other_array+;
5535 * the order from +self+ is preserved:
5536 *
5537 * [0, 1, 1, 2, 1, 1, 3, 1, 1] - [1] # => [0, 2, 3]
5538 * [0, 1, 1, 2, 1, 1, 3, 1, 1] - [3, 2, 0, :foo] # => [1, 1, 1, 1, 1, 1]
5539 * [0, 1, 2] - [:foo] # => [0, 1, 2]
5540 *
5541 * Element are compared using method <tt>#eql?</tt>
5542 * (as defined in each element of +self+).
5543 *
5544 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
5545 */
5547 VALUE
5549 {
5550 VALUE ary3;
5551 VALUE hash;
5563 }
5565 }
5571 }
5574 }
5576 /*
5577 * call-seq:
5578 * difference(*other_arrays = []) -> new_array
5579 *
5580 * Returns a new array containing only those elements from +self+
5581 * that are not found in any of the given +other_arrays+;
5582 * items are compared using <tt>eql?</tt>; order from +self+ is preserved:
5583 *
5584 * [0, 1, 1, 2, 1, 1, 3, 1, 1].difference([1]) # => [0, 2, 3]
5585 * [0, 1, 2, 3].difference([3, 0], [1, 3]) # => [2]
5586 * [0, 1, 2].difference([4]) # => [0, 1, 2]
5587 * [0, 1, 2].difference # => [0, 1, 2]
5588 *
5589 * Returns a copy of +self+ if no arguments are given.
5590 *
5591 * Related: Array#-;
5592 * see also {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
5593 */
5595 static VALUE
5597 {
5598 VALUE ary_diff;
5609 }
5618 }
5621 }
5622 }
5624 }
5629 }
5632 /*
5633 * call-seq:
5634 * self & other_array -> new_array
5635 *
5636 * Returns a new array containing the _intersection_ of +self+ and +other_array+;
5637 * that is, containing those elements found in both +self+ and +other_array+:
5638 *
5639 * [0, 1, 2, 3] & [1, 2] # => [1, 2]
5640 *
5641 * Omits duplicates:
5642 *
5643 * [0, 1, 1, 0] & [0, 1] # => [0, 1]
5644 *
5645 * Preserves order from +self+:
5646 *
5647 * [0, 1, 2] & [3, 2, 1, 0] # => [0, 1, 2]
5648 *
5649 * Identifies common elements using method <tt>#eql?</tt>
5650 * (as defined in each element of +self+).
5651 *
5652 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
5653 */
5656 static VALUE
5658 {
5660 st_data_t vv;
5673 }
5675 }
5684 }
5685 }
5688 }
5690 /*
5691 * call-seq:
5692 * intersection(*other_arrays) -> new_array
5693 *
5694 * Returns a new array containing each element in +self+ that is +#eql?+
5695 * to at least one element in each of the given +other_arrays+;
5696 * duplicates are omitted:
5697 *
5698 * [0, 0, 1, 1, 2, 3].intersection([0, 1, 2], [0, 1, 3]) # => [0, 1]
5699 *
5700 * Each element must correctly implement method <tt>#hash</tt>.
5701 *
5702 * Order from +self+ is preserved:
5703 *
5704 * [0, 1, 2].intersection([2, 1, 0]) # => [0, 1, 2]
5705 *
5706 * Returns a copy of +self+ if no arguments are given.
5707 *
5708 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
5709 */
5711 static VALUE
5713 {
5719 }
5722 }
5724 static int
5726 {
5730 }
5732 static void
5734 {
5740 }
5741 }
5743 static void
5745 {
5751 }
5752 }
5753 }
5755 /*
5756 * call-seq:
5757 * self | other_array -> new_array
5758 *
5759 * Returns the union of +self+ and +other_array+;
5760 * duplicates are removed; order is preserved;
5761 * items are compared using <tt>eql?</tt>:
5762 *
5763 * [0, 1] | [2, 3] # => [0, 1, 2, 3]
5764 * [0, 1, 1] | [2, 2, 3] # => [0, 1, 2, 3]
5765 * [0, 1, 2] | [3, 2, 1, 0] # => [0, 1, 2, 3]
5766 *
5767 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
5768 */
5770 static VALUE
5772 {
5773 VALUE hash;
5781 }
5787 }
5789 /*
5790 * call-seq:
5791 * union(*other_arrays) -> new_array
5792 *
5793 * Returns a new array that is the union of the elements of +self+
5794 * and all given arrays +other_arrays+;
5795 * items are compared using <tt>eql?</tt>:
5796 *
5797 * [0, 1, 2, 3].union([4, 5], [6, 7]) # => [0, 1, 2, 3, 4, 5, 6, 7]
5798 *
5799 * Removes duplicates (preserving the first found):
5800 *
5801 * [0, 1, 1].union([2, 1], [3, 1]) # => [0, 1, 2, 3]
5802 *
5803 * Preserves order (preserving the position of the first found):
5804 *
5805 * [3, 2, 1, 0].union([5, 3], [4, 2]) # => [3, 2, 1, 0, 5, 4]
5806 *
5807 * With no arguments given, returns a copy of +self+.
5808 *
5809 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
5810 */
5812 static VALUE
5814 {
5817 VALUE hash;
5823 }
5832 }
5838 }
5840 /*
5841 * call-seq:
5842 * intersect?(other_array) -> true or false
5843 *
5844 * Returns whether +other_array+ has at least one element that is +#eql?+ to some element of +self+:
5845 *
5846 * [1, 2, 3].intersect?([3, 4, 5]) # => true
5847 * [1, 2, 3].intersect?([4, 5, 6]) # => false
5848 *
5849 * Each element must correctly implement method <tt>#hash</tt>.
5850 *
5851 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
5852 */
5854 static VALUE
5856 {
5858 st_data_t vv;
5868 }
5870 }
5877 }
5888 }
5889 }
5892 }
5894 static VALUE
5896 {
5899 VALUE v;
5905 }
5906 }
5909 }
5911 static VALUE
5913 {
5918 VALUE v;
5925 }
5926 }
5929 }
5930 }
5933 }
5935 static VALUE
5937 {
5942 VALUE v;
5949 }
5950 }
5953 }
5954 }
5957 }
5959 static VALUE
5961 {
5966 VALUE v;
5973 }
5974 }
5977 }
5978 }
5981 }
5983 /*
5984 * call-seq:
5985 * max -> element
5986 * max(count) -> new_array
5987 * max {|a, b| ... } -> element
5988 * max(count) {|a, b| ... } -> new_array
5989 *
5990 * Returns one of the following:
5991 *
5992 * - The maximum-valued element from +self+.
5993 * - A new array of maximum-valued elements from +self+.
5994 *
5995 * Does not modify +self+.
5996 *
5997 * With no block given, each element in +self+ must respond to method <tt>#<=></tt>
5998 * with a numeric.
5999 *
6000 * With no argument and no block, returns the element in +self+
6001 * having the maximum value per method <tt>#<=></tt>:
6002 *
6003 * [1, 0, 3, 2].max # => 3
6004 *
6005 * With non-negative numeric argument +count+ and no block,
6006 * returns a new array with at most +count+ elements,
6007 * in descending order, per method <tt>#<=></tt>:
6008 *
6009 * [1, 0, 3, 2].max(3) # => [3, 2, 1]
6010 * [1, 0, 3, 2].max(3.0) # => [3, 2, 1]
6011 * [1, 0, 3, 2].max(9) # => [3, 2, 1, 0]
6012 * [1, 0, 3, 2].max(0) # => []
6013 *
6014 * With a block given, the block must return a numeric.
6015 *
6016 * With a block and no argument, calls the block <tt>self.size - 1</tt> times to compare elements;
6017 * returns the element having the maximum value per the block:
6018 *
6019 * ['0', '', '000', '00'].max {|a, b| a.size <=> b.size }
6020 * # => "000"
6021 *
6022 * With non-negative numeric argument +count+ and a block,
6023 * returns a new array with at most +count+ elements,
6024 * in descending order, per the block:
6025 *
6026 * ['0', '', '000', '00'].max(2) {|a, b| a.size <=> b.size }
6027 * # => ["000", "00"]
6028 *
6029 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
6030 */
6031 static VALUE
6033 {
6035 VALUE num;
6047 }
6048 }
6049 }
6055 }
6058 }
6061 }
6064 }
6065 }
6066 }
6069 }
6071 static VALUE
6073 {
6076 VALUE v;
6082 }
6083 }
6086 }
6088 static VALUE
6090 {
6095 VALUE a;
6102 }
6103 }
6106 }
6107 }
6110 }
6112 static VALUE
6114 {
6119 VALUE a;
6126 }
6127 }
6130 }
6131 }
6134 }
6136 static VALUE
6138 {
6143 VALUE a;
6150 }
6151 }
6154 }
6155 }
6158 }
6160 /*
6161 * call-seq:
6162 * min -> element
6163 * min(count) -> new_array
6164 * min {|a, b| ... } -> element
6165 * min(count) {|a, b| ... } -> new_array
6166 *
6167 * Returns one of the following:
6168 *
6169 * - The minimum-valued element from +self+.
6170 * - A new array of minimum-valued elements from +self+.
6171 *
6172 * Does not modify +self+.
6173 *
6174 * With no block given, each element in +self+ must respond to method <tt>#<=></tt>
6175 * with a numeric.
6176 *
6177 * With no argument and no block, returns the element in +self+
6178 * having the minimum value per method <tt>#<=></tt>:
6179 *
6180 * [1, 0, 3, 2].min # => 0
6181 *
6182 * With non-negative numeric argument +count+ and no block,
6183 * returns a new array with at most +count+ elements,
6184 * in ascending order, per method <tt>#<=></tt>:
6185 *
6186 * [1, 0, 3, 2].min(3) # => [0, 1, 2]
6187 * [1, 0, 3, 2].min(3.0) # => [0, 1, 2]
6188 * [1, 0, 3, 2].min(9) # => [0, 1, 2, 3]
6189 * [1, 0, 3, 2].min(0) # => []
6190 *
6191 * With a block given, the block must return a numeric.
6192 *
6193 * With a block and no argument, calls the block <tt>self.size - 1</tt> times to compare elements;
6194 * returns the element having the minimum value per the block:
6195 *
6196 * ['0', '', '000', '00'].min {|a, b| a.size <=> b.size }
6197 * # => ""
6198 *
6199 * With non-negative numeric argument +count+ and a block,
6200 * returns a new array with at most +count+ elements,
6201 * in ascending order, per the block:
6202 *
6203 * ['0', '', '000', '00'].min(2) {|a, b| a.size <=> b.size }
6204 * # => ["", "0"]
6205 *
6206 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
6207 */
6208 static VALUE
6210 {
6212 VALUE num;
6224 }
6225 }
6226 }
6232 }
6235 }
6238 }
6241 }
6242 }
6243 }
6246 }
6248 /*
6249 * call-seq:
6250 * minmax -> array
6251 * minmax {|a, b| ... } -> array
6252 *
6253 * Returns a 2-element array containing the minimum-valued and maximum-valued
6254 * elements from +self+;
6255 * does not modify +self+.
6256 *
6257 * With no block given, the minimum and maximum values are determined using method <tt>#<=></tt>:
6258 *
6259 * [1, 0, 3, 2].minmax # => [0, 3]
6260 *
6261 * With a block given, the block must return a numeric;
6262 * the block is called <tt>self.size - 1</tt> times to compare elements;
6263 * returns the elements having the minimum and maximum values per the block:
6264 *
6265 * ['0', '', '000', '00'].minmax {|a, b| a.size <=> b.size }
6266 * # => ["", "000"]
6267 *
6268 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
6269 */
6270 static VALUE
6272 {
6275 }
6277 }
6279 static int
6281 {
6284 }
6286 /*
6287 * call-seq:
6288 * uniq! -> self or nil
6289 * uniq! {|element| ... } -> self or nil
6290 *
6291 * Removes duplicate elements from +self+, the first occurrence always being retained;
6292 * returns +self+ if any elements removed, +nil+ otherwise.
6293 *
6294 * With no block given, identifies and removes elements using method <tt>eql?</tt>
6295 * to compare elements:
6296 *
6297 * a = [0, 0, 1, 1, 2, 2]
6298 * a.uniq! # => [0, 1, 2]
6299 * a.uniq! # => nil
6300 *
6301 * With a block given, calls the block for each element;
6302 * identifies and omits "duplicate" elements using method <tt>eql?</tt>
6303 * to compare <i>block return values</i>;
6304 * that is, an element is a duplicate if its block return value
6305 * is the same as that of a previous element:
6306 *
6307 * a = ['a', 'aa', 'aaa', 'b', 'bb', 'bbb']
6308 * a.uniq! {|element| element.size } # => ["a", "aa", "aaa"]
6309 * a.uniq! {|element| element.size } # => nil
6310 *
6311 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
6312 */
6313 static VALUE
6315 {
6316 VALUE hash;
6324 else
6330 }
6336 }
6341 }
6343 /*
6344 * call-seq:
6345 * uniq -> new_array
6346 * uniq {|element| ... } -> new_array
6347 *
6348 * Returns a new array containing those elements from +self+ that are not duplicates,
6349 * the first occurrence always being retained.
6350 *
6351 * With no block given, identifies and omits duplicate elements using method <tt>eql?</tt>
6352 * to compare elements:
6353 *
6354 * a = [0, 0, 1, 1, 2, 2]
6355 * a.uniq # => [0, 1, 2]
6356 *
6357 * With a block given, calls the block for each element;
6358 * identifies and omits "duplicate" elements using method <tt>eql?</tt>
6359 * to compare <i>block return values</i>;
6360 * that is, an element is a duplicate if its block return value
6361 * is the same as that of a previous element:
6362 *
6363 * a = ['a', 'aa', 'aaa', 'b', 'bb', 'bbb']
6364 * a.uniq {|element| element.size } # => ["a", "aa", "aaa"]
6365 *
6366 * Related: {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
6367 */
6369 static VALUE
6371 {
6377 }
6381 }
6385 }
6388 }
6390 /*
6391 * call-seq:
6392 * compact! -> self or nil
6393 *
6394 * Removes all +nil+ elements from +self+;
6395 * Returns +self+ if any elements are removed, +nil+ otherwise:
6396 *
6397 * a = [nil, 0, nil, false, nil, '', nil, [], nil, {}]
6398 * a.compact! # => [0, false, "", [], {}]
6399 * a # => [0, false, "", [], {}]
6400 * a.compact! # => nil
6401 *
6402 * Related: Array#compact;
6403 * see also {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
6404 */
6406 static VALUE
6408 {
6419 }
6423 }
6427 }
6429 /*
6430 * call-seq:
6431 * compact -> new_array
6432 *
6433 * Returns a new array containing only the non-+nil+ elements from +self+;
6434 * element order is preserved:
6435 *
6436 * a = [nil, 0, nil, false, nil, '', nil, [], nil, {}]
6437 * a.compact # => [0, false, "", [], {}]
6438 *
6439 * Related: Array#compact!;
6440 * see also {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
6441 */
6443 static VALUE
6445 {
6449 }
6451 /*
6452 * call-seq:
6453 * count -> integer
6454 * count(object) -> integer
6455 * count {|element| ... } -> integer
6456 *
6457 * Returns a count of specified elements.
6458 *
6459 * With no argument and no block, returns the count of all elements:
6460 *
6461 * [0, :one, 'two', 3, 3.0].count # => 5
6462 *
6463 * With argument +object+ given, returns the count of elements <tt>==</tt> to +object+:
6464 *
6465 * [0, :one, 'two', 3, 3.0].count(3) # => 2
6466 *
6467 * With no argument and a block given, calls the block with each element;
6468 * returns the count of elements for which the block returns a truthy value:
6469 *
6470 * [0, 1, 2, 3].count {|element| element > 1 } # => 2
6471 *
6472 * With argument +object+ and a block given, issues a warning, ignores the block,
6473 * and returns the count of elements <tt>==</tt> to +object+.
6474 *
6475 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
6476 */
6478 static VALUE
6480 {
6484 VALUE v;
6492 }
6493 }
6499 }
6502 }
6503 }
6506 }
6508 static VALUE
6510 {
6520 }
6521 }
6524 }
6538 }
6549 }
6554 }
6556 }
6559 }
6565 }
6567 }
6572 }
6573 }
6576 }
6579 }
6583 }
6587 }
6591 }
6593 /*
6594 * call-seq:
6595 * flatten!(depth = nil) -> self or nil
6596 *
6597 * Returns +self+ as a recursively flattening of +self+ to +depth+ levels of recursion;
6598 * +depth+ must be an
6599 * {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects],
6600 * or +nil+.
6601 * At each level of recursion:
6602 *
6603 * - Each element that is an array is "flattened"
6604 * (that is, replaced by its individual array elements).
6605 * - Each element that is not an array is unchanged
6606 * (even if the element is an object that has instance method +flatten+).
6607 *
6608 * Returns +nil+ if no elements were flattened.
6609 *
6610 * With non-negative integer argument +depth+, flattens recursively through +depth+ levels:
6611 *
6612 * a = [ 0, [ 1, [2, 3], 4 ], 5, {foo: 0}, Set.new([6, 7]) ]
6613 * a # => [0, [1, [2, 3], 4], 5, {:foo=>0}, #<Set: {6, 7}>]
6614 * a.dup.flatten!(1) # => [0, 1, [2, 3], 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6615 * a.dup.flatten!(1.1) # => [0, 1, [2, 3], 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6616 * a.dup.flatten!(2) # => [0, 1, 2, 3, 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6617 * a.dup.flatten!(3) # => [0, 1, 2, 3, 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6618 *
6619 * With +nil+ or negative argument +depth+, flattens all levels:
6620 *
6621 * a.dup.flatten! # => [0, 1, 2, 3, 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6622 * a.dup.flatten!(-1) # => [0, 1, 2, 3, 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6623 *
6624 * Related: Array#flatten;
6625 * see also {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
6626 */
6628 static VALUE
6630 {
6642 }
6648 }
6650 /*
6651 * call-seq:
6652 * flatten(depth = nil) -> new_array
6653 *
6654 * Returns a new array that is a recursive flattening of +self+
6655 * to +depth+ levels of recursion;
6656 * +depth+ must be an
6657 * {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects]
6658 * or +nil+.
6659 * At each level of recursion:
6660 *
6661 * - Each element that is an array is "flattened"
6662 * (that is, replaced by its individual array elements).
6663 * - Each element that is not an array is unchanged
6664 * (even if the element is an object that has instance method +flatten+).
6665 *
6666 * With non-negative integer argument +depth+, flattens recursively through +depth+ levels:
6667 *
6668 * a = [ 0, [ 1, [2, 3], 4 ], 5, {foo: 0}, Set.new([6, 7]) ]
6669 * a # => [0, [1, [2, 3], 4], 5, {:foo=>0}, #<Set: {6, 7}>]
6670 * a.flatten(0) # => [0, [1, [2, 3], 4], 5, {:foo=>0}, #<Set: {6, 7}>]
6671 * a.flatten(1 ) # => [0, 1, [2, 3], 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6672 * a.flatten(1.1) # => [0, 1, [2, 3], 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6673 * a.flatten(2) # => [0, 1, 2, 3, 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6674 * a.flatten(3) # => [0, 1, 2, 3, 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6675 *
6676 * With +nil+ or negative +depth+, flattens all levels.
6677 *
6678 * a.flatten # => [0, 1, 2, 3, 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6679 * a.flatten(-1) # => [0, 1, 2, 3, 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6680 *
6681 * Related: Array#flatten!;
6682 * see also {Methods for Converting}[rdoc-ref:Array@Methods+for+Converting].
6683 */
6685 static VALUE
6687 {
6689 VALUE result;
6694 }
6699 }
6702 }
6704 #define RAND_UPTO(max) (long)rb_random_ulong_limited((randgen), (max)-1)
6706 static VALUE
6708 {
6716 VALUE tmp;
6719 }
6723 }
6726 }
6728 static VALUE
6730 {
6734 }
6740 },
6742 };
6744 static VALUE
6746 {
6747 VALUE result;
6756 else
6760 }
6767 }
6768 }
6774 }
6775 }
6792 {
6796 }
6798 }
6799 memo_threshold =
6812 }
6815 }
6820 }
6821 });
6822 }
6834 }
6842 st_data_t value;
6847 }
6848 });
6849 });
6853 }
6864 }
6865 });
6867 }
6871 }
6873 static VALUE
6875 {
6877 }
6879 static VALUE
6881 {
6883 }
6885 static VALUE
6887 {
6892 }
6899 }
6901 /*
6902 * call-seq:
6903 * cycle(count = nil) {|element| ... } -> nil
6904 * cycle(count = nil) -> new_enumerator
6905 *
6906 * With a block given, may call the block, depending on the value of argument +count+;
6907 * +count+ must be an
6908 * {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects],
6909 * or +nil+.
6910 *
6911 * When +count+ is positive,
6912 * calls the block with each element, then does so repeatedly,
6913 * until it has done so +count+ times; returns +nil+:
6914 *
6915 * output = []
6916 * [0, 1].cycle(2) {|element| output.push(element) } # => nil
6917 * output # => [0, 1, 0, 1]
6918 *
6919 * When +count+ is zero or negative, does not call the block:
6920 *
6921 * [0, 1].cycle(0) {|element| fail 'Cannot happen' } # => nil
6922 * [0, 1].cycle(-1) {|element| fail 'Cannot happen' } # => nil
6923 *
6924 * When +count+ is +nil+, cycles forever:
6925 *
6926 * # Prints 0 and 1 forever.
6927 * [0, 1].cycle {|element| puts element }
6928 * [0, 1].cycle(nil) {|element| puts element }
6929 *
6930 * With no block given, returns a new Enumerator.
6931 *
6932 * Related: see {Methods for Iterating}[rdoc-ref:Array@Methods+for+Iterating].
6933 */
6934 static VALUE
6936 {
6944 }
6948 }
6953 }
6954 }
6956 }
6958 /*
6959 * Build a ruby array of the corresponding values and yield it to the
6960 * associated block.
6961 * Return the class of +values+ for reentry check.
6962 */
6963 static int
6965 {
6973 }
6975 /*
6976 * Compute permutations of +r+ elements of the set <code>[0..n-1]</code>.
6977 *
6978 * When we have a complete permutation of array indices, copy the values
6979 * at those indices into a new array and yield that array.
6980 *
6981 * n: the size of the set
6982 * r: the number of elements in each permutation
6983 * p: the array (of size r) that we're filling in
6984 * used: an array of booleans: whether a given index is already used
6985 * values: the Ruby array that holds the actual values to permute
6986 */
6987 static void
6989 {
6998 }
7007 }
7013 }
7014 }
7018 }
7019 }
7020 }
7022 /*
7023 * Returns the product of from, from-1, ..., from - how_many + 1.
7024 * https://en.wikipedia.org/wiki/Pochhammer_symbol
7025 */
7026 static VALUE
7028 {
7029 VALUE cnt;
7035 }
7036 }
7039 }
7041 }
7043 static VALUE
7045 {
7046 VALUE r;
7050 }
7053 }
7056 }
7061 }
7063 }
7065 static VALUE
7067 {
7072 }
7074 /*
7075 * call-seq:
7076 * permutation(count = self.size) {|permutation| ... } -> self
7077 * permutation(count = self.size) -> new_enumerator
7078 *
7079 * Iterates over permutations of the elements of +self+;
7080 * the order of permutations is indeterminate.
7081 *
7082 * With a block and an in-range positive integer argument +count+ (<tt>0 < count <= self.size</tt>) given,
7083 * calls the block with each permutation of +self+ of size +count+;
7084 * returns +self+:
7085 *
7086 * a = [0, 1, 2]
7087 * perms = []
7088 * a.permutation(1) {|perm| perms.push(perm) }
7089 * perms # => [[0], [1], [2]]
7090 *
7091 * perms = []
7092 * a.permutation(2) {|perm| perms.push(perm) }
7093 * perms # => [[0, 1], [0, 2], [1, 0], [1, 2], [2, 0], [2, 1]]
7094 *
7095 * perms = []
7096 * a.permutation(3) {|perm| perms.push(perm) }
7097 * perms # => [[0, 1, 2], [0, 2, 1], [1, 0, 2], [1, 2, 0], [2, 0, 1], [2, 1, 0]]
7098 *
7099 * When +count+ is zero, calls the block once with a new empty array:
7100 *
7101 * perms = []
7102 * a.permutation(0) {|perm| perms.push(perm) }
7103 * perms # => [[]]
7104 *
7105 * When +count+ is out of range (negative or larger than <tt>self.size</tt>),
7106 * does not call the block:
7107 *
7108 * a.permutation(-1) {|permutation| fail 'Cannot happen' }
7109 * a.permutation(4) {|permutation| fail 'Cannot happen' }
7110 *
7111 * With no block given, returns a new Enumerator.
7112 *
7113 * Related: {Methods for Iterating}[rdoc-ref:Array@Methods+for+Iterating].
7114 */
7116 static VALUE
7118 {
7122 RETURN_SIZED_ENUMERATOR(ary, argc, argv, rb_ary_permutation_size); /* Return enumerator if no block */
7128 /* no permutations: yield nothing */
7129 }
7132 }
7136 }
7137 }
7150 }
7152 }
7154 static void
7156 {
7164 }
7167 }
7172 }
7173 }
7175 static VALUE
7177 {
7182 }
7184 /*
7185 * call-seq:
7186 * combination(count) {|element| ... } -> self
7187 * combination(count) -> new_enumerator
7188 *
7189 * When a block and a positive
7190 * {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects]
7191 * argument +count+ (<tt>0 < count <= self.size</tt>)
7192 * are given, calls the block with each combination of +self+ of size +count+;
7193 * returns +self+:
7194 *
7195 * a = %w[a b c] # => ["a", "b", "c"]
7196 * a.combination(2) {|combination| p combination } # => ["a", "b", "c"]
7197 *
7198 * Output:
7199 *
7200 * ["a", "b"]
7201 * ["a", "c"]
7202 * ["b", "c"]
7203 *
7204 * The order of the yielded combinations is not guaranteed.
7205 *
7206 * When +count+ is zero, calls the block once with a new empty array:
7207 *
7208 * a.combination(0) {|combination| p combination }
7209 * [].combination(0) {|combination| p combination }
7210 *
7211 * Output:
7212 *
7213 * []
7214 * []
7215 *
7216 * When +count+ is negative or larger than +self.size+ and +self+ is non-empty,
7217 * does not call the block:
7218 *
7219 * a.combination(-1) {|combination| fail 'Cannot happen' } # => ["a", "b", "c"]
7220 * a.combination(4) {|combination| fail 'Cannot happen' } # => ["a", "b", "c"]
7221 *
7222 * With no block given, returns a new Enumerator.
7223 *
7224 * Related: Array#permutation;
7225 * see also {Methods for Iterating}[rdoc-ref:Array@Methods+for+Iterating].
7226 */
7228 static VALUE
7230 {
7237 /* yield nothing */
7238 }
7241 }
7245 }
7246 }
7256 }
7258 }
7260 /*
7261 * Compute repeated permutations of +r+ elements of the set
7262 * <code>[0..n-1]</code>.
7263 *
7264 * When we have a complete repeated permutation of array indices, copy the
7265 * values at those indices into a new array and yield that array.
7266 *
7267 * n: the size of the set
7268 * r: the number of elements in each permutation
7269 * p: the array (of size r) that we're filling in
7270 * values: the Ruby array that holds the actual values to permute
7271 */
7272 static void
7274 {
7282 }
7287 }
7288 }
7292 }
7293 }
7295 static VALUE
7297 {
7303 }
7306 }
7308 }
7310 /*
7311 * call-seq:
7312 * repeated_permutation(size) {|permutation| ... } -> self
7313 * repeated_permutation(size) -> new_enumerator
7314 *
7315 * With a block given, calls the block with each repeated permutation of length +size+
7316 * of the elements of +self+;
7317 * each permutation is an array;
7318 * returns +self+. The order of the permutations is indeterminate.
7319 *
7320 * If a positive integer argument +size+ is given,
7321 * calls the block with each +size+-tuple repeated permutation of the elements of +self+.
7322 * The number of permutations is <tt>self.size**size</tt>.
7323 *
7324 * Examples:
7325 *
7326 * - +size+ is 1:
7327 *
7328 * p = []
7329 * [0, 1, 2].repeated_permutation(1) {|permutation| p.push(permutation) }
7330 * p # => [[0], [1], [2]]
7331 *
7332 * - +size+ is 2:
7333 *
7334 * p = []
7335 * [0, 1, 2].repeated_permutation(2) {|permutation| p.push(permutation) }
7336 * p # => [[0, 0], [0, 1], [0, 2], [1, 0], [1, 1], [1, 2], [2, 0], [2, 1], [2, 2]]
7337 *
7338 * If +size+ is zero, calls the block once with an empty array.
7339 *
7340 * If +size+ is negative, does not call the block:
7341 *
7342 * [0, 1, 2].repeated_permutation(-1) {|permutation| fail 'Cannot happen' }
7343 *
7344 * With no block given, returns a new Enumerator.
7345 *
7346 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
7347 */
7348 static VALUE
7350 {
7354 RETURN_SIZED_ENUMERATOR(ary, 1, &num, rb_ary_repeated_permutation_size); /* Return Enumerator if no block */
7358 /* no permutations: yield nothing */
7359 }
7362 }
7366 }
7367 }
7377 }
7379 }
7381 static void
7383 {
7391 }
7396 }
7397 }
7401 }
7402 }
7404 static VALUE
7406 {
7411 }
7413 }
7415 /*
7416 * call-seq:
7417 * repeated_combination(size) {|combination| ... } -> self
7418 * repeated_combination(size) -> new_enumerator
7419 *
7420 * With a block given, calls the block with each repeated combination of length +size+
7421 * of the elements of +self+;
7422 * each combination is an array;
7423 * returns +self+. The order of the combinations is indeterminate.
7424 *
7425 * If a positive integer argument +size+ is given,
7426 * calls the block with each +size+-tuple repeated combination of the elements of +self+.
7427 * The number of combinations is <tt>(size+1)(size+2)/2</tt>.
7428 *
7429 * Examples:
7430 *
7431 * - +size+ is 1:
7432 *
7433 * c = []
7434 * [0, 1, 2].repeated_combination(1) {|combination| c.push(combination) }
7435 * c # => [[0], [1], [2]]
7436 *
7437 * - +size+ is 2:
7438 *
7439 * c = []
7440 * [0, 1, 2].repeated_combination(2) {|combination| c.push(combination) }
7441 * c # => [[0, 0], [0, 1], [0, 2], [1, 1], [1, 2], [2, 2]]
7442 *
7443 * If +size+ is zero, calls the block once with an empty array.
7444 *
7445 * If +size+ is negative, does not call the block:
7446 *
7447 * [0, 1, 2].repeated_combination(-1) {|combination| fail 'Cannot happen' }
7448 *
7449 * With no block given, returns a new Enumerator.
7450 *
7451 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
7452 */
7454 static VALUE
7456 {
7460 RETURN_SIZED_ENUMERATOR(ary, 1, &num, rb_ary_repeated_combination_size); /* Return enumerator if no block */
7463 /* yield nothing */
7464 }
7467 }
7471 }
7472 }
7474 /* yield nothing */
7475 }
7485 }
7487 }
7489 /*
7490 * call-seq:
7491 * product(*other_arrays) -> new_array
7492 * product(*other_arrays) {|combination| ... } -> self
7493 *
7494 * Computes all combinations of elements from all the arrays,
7495 * including both +self+ and +other_arrays+:
7496 *
7497 * - The number of combinations is the product of the sizes of all the arrays,
7498 * including both +self+ and +other_arrays+.
7499 * - The order of the returned combinations is indeterminate.
7500 *
7501 * With no block given, returns the combinations as an array of arrays:
7502 *
7503 * p = [0, 1].product([2, 3])
7504 * # => [[0, 2], [0, 3], [1, 2], [1, 3]]
7505 * p.size # => 4
7506 * p = [0, 1].product([2, 3], [4, 5])
7507 * # => [[0, 2, 4], [0, 2, 5], [0, 3, 4], [0, 3, 5], [1, 2, 4], [1, 2, 5], [1, 3, 4], [1, 3,...
7508 * p.size # => 8
7509 *
7510 * If +self+ or any argument is empty, returns an empty array:
7511 *
7512 * [].product([2, 3], [4, 5]) # => []
7513 * [0, 1].product([2, 3], []) # => []
7514 *
7515 * If no argument is given, returns an array of 1-element arrays,
7516 * each containing an element of +self+:
7517 *
7518 * a.product # => [[0], [1], [2]]
7519 *
7520 * With a block given, calls the block with each combination; returns +self+:
7521 *
7522 * p = []
7523 * [0, 1].product([2, 3]) {|combination| p.push(combination) }
7524 * p # => [[0, 2], [0, 3], [1, 2], [1, 3]]
7525 *
7526 * If +self+ or any argument is empty, does not call the block:
7527 *
7528 * [].product([2, 3], [4, 5]) {|combination| fail 'Cannot happen' }
7529 * # => []
7530 * [0, 1].product([2, 3], []) {|combination| fail 'Cannot happen' }
7531 * # => [0, 1]
7532 *
7533 * If no argument is given, calls the block with each element of +self+ as a 1-element array:
7534 *
7535 * p = []
7536 * [0, 1].product {|combination| p.push(combination) }
7537 * p # => [[0], [1]]
7538 *
7539 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
7540 */
7542 static VALUE
7544 {
7556 /* initialize the arrays of arrays */
7562 /* initialize the counters for the arrays */
7565 /* Otherwise, allocate and fill in an array of results */
7567 /* Make defensive copies of arrays; exit if any is empty */
7571 }
7572 }
7574 /* Compute the length of the result array; return [] if any is empty */
7580 }
7584 }
7586 }
7589 /* fill in one subarray */
7593 }
7595 /* put it on the result array */
7601 }
7604 }
7605 }
7608 }
7610 /*
7611 * Increment the last counter. If it overflows, reset to 0
7612 * and increment the one before it.
7613 */
7618 /* If the first counter overflows, we are done */
7621 }
7622 }
7624 done:
7628 }
7630 /*
7631 * call-seq:
7632 * take(count) -> new_array
7633 *
7634 * Returns a new array containing the first +count+ element of +self+
7635 * (as available);
7636 * +count+ must be a non-negative numeric;
7637 * does not modify +self+:
7638 *
7639 * a = ['a', 'b', 'c', 'd']
7640 * a.take(2) # => ["a", "b"]
7641 * a.take(2.1) # => ["a", "b"]
7642 * a.take(50) # => ["a", "b", "c", "d"]
7643 * a.take(0) # => []
7644 *
7645 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
7646 */
7648 static VALUE
7650 {
7654 }
7656 }
7658 /*
7659 * call-seq:
7660 * take_while {|element| ... } -> new_array
7661 * take_while -> new_enumerator
7662 *
7663 * With a block given, calls the block with each successive element of +self+;
7664 * stops iterating if the block returns +false+ or +nil+;
7665 * returns a new array containing those elements for which the block returned a truthy value:
7666 *
7667 * a = [0, 1, 2, 3, 4, 5]
7668 * a.take_while {|element| element < 3 } # => [0, 1, 2]
7669 * a.take_while {|element| true } # => [0, 1, 2, 3, 4, 5]
7670 * a.take_while {|element| false } # => []
7671 *
7672 * With no block given, returns a new Enumerator.
7673 *
7674 * Does not modify +self+.
7675 *
7676 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
7677 */
7679 static VALUE
7681 {
7687 }
7689 }
7691 /*
7692 * call-seq:
7693 * drop(count) -> new_array
7694 *
7695 * Returns a new array containing all but the first +count+ element of +self+,
7696 * where +count+ is a non-negative integer;
7697 * does not modify +self+.
7698 *
7699 * Examples:
7700 *
7701 * a = [0, 1, 2, 3, 4, 5]
7702 * a.drop(0) # => [0, 1, 2, 3, 4, 5]
7703 * a.drop(1) # => [1, 2, 3, 4, 5]
7704 * a.drop(2) # => [2, 3, 4, 5]
7705 * a.drop(9) # => []
7706 *
7707 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
7708 */
7710 static VALUE
7712 {
7713 VALUE result;
7717 }
7722 }
7724 /*
7725 * call-seq:
7726 * drop_while {|element| ... } -> new_array
7727 * drop_while -> new_enumerator
7728 *
7729 * With a block given, calls the block with each successive element of +self+;
7730 * stops if the block returns +false+ or +nil+;
7731 * returns a new array _omitting_ those elements for which the block returned a truthy value;
7732 * does not modify +self+:
7733 *
7734 * a = [0, 1, 2, 3, 4, 5]
7735 * a.drop_while {|element| element < 3 } # => [3, 4, 5]
7736 *
7737 * With no block given, returns a new Enumerator.
7738 *
7739 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
7740 */
7742 static VALUE
7744 {
7750 }
7752 }
7754 /*
7755 * call-seq:
7756 * any? -> true or false
7757 * any?(object) -> true or false
7758 * any? {|element| ... } -> true or false
7759 *
7760 * Returns whether for any element of +self+, a given criterion is satisfied.
7761 *
7762 * With no block and no argument, returns whether any element of +self+ is truthy:
7763 *
7764 * [nil, false, []].any? # => true # Array object is truthy.
7765 * [nil, false, {}].any? # => true # Hash object is truthy.
7766 * [nil, false, ''].any? # => true # String object is truthy.
7767 * [nil, false].any? # => false # Nil and false are not truthy.
7768 *
7769 * With argument +object+ given,
7770 * returns whether <tt>object === ele</tt> for any element +ele+ in +self+:
7771 *
7772 * [nil, false, 0].any?(0) # => true
7773 * [nil, false, 1].any?(0) # => false
7774 * [nil, false, 'food'].any?(/foo/) # => true
7775 * [nil, false, 'food'].any?(/bar/) # => false
7776 *
7777 * With a block given,
7778 * calls the block with each element in +self+;
7779 * returns whether the block returns any truthy value:
7780 *
7781 * [0, 1, 2].any? {|ele| ele < 1 } # => true
7782 * [0, 1, 2].any? {|ele| ele < 0 } # => false
7783 *
7784 * With both a block and argument +object+ given,
7785 * ignores the block and uses +object+ as above.
7786 *
7787 * <b>Special case</b>: returns +false+ if +self+ is empty
7788 * (regardless of any given argument or block).
7789 *
7790 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
7791 */
7793 static VALUE
7795 {
7803 }
7806 }
7807 }
7811 }
7812 }
7816 }
7817 }
7819 }
7821 /*
7822 * call-seq:
7823 * all? -> true or false
7824 * all?(object) -> true or false
7825 * all? {|element| ... } -> true or false
7826 *
7827 * Returns whether for every element of +self+,
7828 * a given criterion is satisfied.
7829 *
7830 * With no block and no argument,
7831 * returns whether every element of +self+ is truthy:
7832 *
7833 * [[], {}, '', 0, 0.0, Object.new].all? # => true # All truthy objects.
7834 * [[], {}, '', 0, 0.0, nil].all? # => false # nil is not truthy.
7835 * [[], {}, '', 0, 0.0, false].all? # => false # false is not truthy.
7836 *
7837 * With argument +object+ given, returns whether <tt>object === ele</tt>
7838 * for every element +ele+ in +self+:
7839 *
7840 * [0, 0, 0].all?(0) # => true
7841 * [0, 1, 2].all?(1) # => false
7842 * ['food', 'fool', 'foot'].all?(/foo/) # => true
7843 * ['food', 'drink'].all?(/foo/) # => false
7844 *
7845 * With a block given, calls the block with each element in +self+;
7846 * returns whether the block returns only truthy values:
7847 *
7848 * [0, 1, 2].all? { |ele| ele < 3 } # => true
7849 * [0, 1, 2].all? { |ele| ele < 2 } # => false
7850 *
7851 * With both a block and argument +object+ given,
7852 * ignores the block and uses +object+ as above.
7853 *
7854 * <b>Special case</b>: returns +true+ if +self+ is empty
7855 * (regardless of any given argument or block).
7856 *
7857 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
7858 */
7860 static VALUE
7862 {
7870 }
7873 }
7874 }
7878 }
7879 }
7883 }
7884 }
7886 }
7888 /*
7889 * call-seq:
7890 * none? -> true or false
7891 * none?(object) -> true or false
7892 * none? {|element| ... } -> true or false
7893 *
7894 * Returns +true+ if no element of +self+ meets a given criterion, +false+ otherwise.
7895 *
7896 * With no block given and no argument, returns +true+ if +self+ has no truthy elements,
7897 * +false+ otherwise:
7898 *
7899 * [nil, false].none? # => true
7900 * [nil, 0, false].none? # => false
7901 * [].none? # => true
7902 *
7903 * With argument +object+ given, returns +false+ if for any element +element+,
7904 * <tt>object === element</tt>; +true+ otherwise:
7905 *
7906 * ['food', 'drink'].none?(/bar/) # => true
7907 * ['food', 'drink'].none?(/foo/) # => false
7908 * [].none?(/foo/) # => true
7909 * [0, 1, 2].none?(3) # => true
7910 * [0, 1, 2].none?(1) # => false
7911 *
7912 * With a block given, calls the block with each element in +self+;
7913 * returns +true+ if the block returns no truthy value, +false+ otherwise:
7914 *
7915 * [0, 1, 2].none? {|element| element > 3 } # => true
7916 * [0, 1, 2].none? {|element| element > 1 } # => false
7917 *
7918 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
7919 */
7921 static VALUE
7923 {
7931 }
7934 }
7935 }
7939 }
7940 }
7944 }
7945 }
7947 }
7949 /*
7950 * call-seq:
7951 * one? -> true or false
7952 * one? {|element| ... } -> true or false
7953 * one?(object) -> true or false
7954 *
7955 * Returns +true+ if exactly one element of +self+ meets a given criterion.
7956 *
7957 * With no block given and no argument, returns +true+ if +self+ has exactly one truthy element,
7958 * +false+ otherwise:
7959 *
7960 * [nil, 0].one? # => true
7961 * [0, 0].one? # => false
7962 * [nil, nil].one? # => false
7963 * [].one? # => false
7964 *
7965 * With a block given, calls the block with each element in +self+;
7966 * returns +true+ if the block a truthy value for exactly one element, +false+ otherwise:
7967 *
7968 * [0, 1, 2].one? {|element| element > 0 } # => false
7969 * [0, 1, 2].one? {|element| element > 1 } # => true
7970 * [0, 1, 2].one? {|element| element > 2 } # => false
7971 *
7972 * With argument +object+ given, returns +true+ if for exactly one element +element+, <tt>object === element</tt>;
7973 * +false+ otherwise:
7974 *
7975 * [0, 1, 2].one?(0) # => true
7976 * [0, 0, 1].one?(0) # => false
7977 * [1, 1, 2].one?(0) # => false
7978 * ['food', 'drink'].one?(/bar/) # => false
7979 * ['food', 'drink'].one?(/foo/) # => true
7980 * [].one?(/foo/) # => false
7981 *
7982 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
7983 */
7985 static VALUE
7987 {
7996 }
8001 }
8002 }
8003 }
8009 }
8010 }
8011 }
8017 }
8018 }
8019 }
8021 }
8023 /*
8024 * call-seq:
8025 * dig(index, *identifiers) -> object
8026 *
8027 * Finds and returns the object in nested object
8028 * specified by +index+ and +identifiers+;
8029 * the nested objects may be instances of various classes.
8030 * See {Dig Methods}[rdoc-ref:dig_methods.rdoc].
8031 *
8032 * Examples:
8033 *
8034 * a = [:foo, [:bar, :baz, [:bat, :bam]]]
8035 * a.dig(1) # => [:bar, :baz, [:bat, :bam]]
8036 * a.dig(1, 2) # => [:bat, :bam]
8037 * a.dig(1, 2, 0) # => :bat
8038 * a.dig(1, 2, 3) # => nil
8039 *
8040 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
8041 */
8043 static VALUE
8045 {
8051 }
8055 {
8060 }
8063 }
8065 }
8067 /*
8068 * call-seq:
8069 * sum(init = 0) -> object
8070 * sum(init = 0) {|element| ... } -> object
8071 *
8072 * With no block given, returns the sum of +init+ and all elements of +self+;
8073 * for array +array+ and value +init+, equivalent to:
8074 *
8075 * sum = init
8076 * array.each {|element| sum += element }
8077 * sum
8078 *
8079 * For example, <tt>[e0, e1, e2].sum</tt> returns <tt>init + e0 + e1 + e2</tt>.
8080 *
8081 * Examples:
8082 *
8083 * [0, 1, 2, 3].sum # => 6
8084 * [0, 1, 2, 3].sum(100) # => 106
8085 * ['abc', 'def', 'ghi'].sum('jkl') # => "jklabcdefghi"
8086 * [[:foo, :bar], ['foo', 'bar']].sum([2, 3])
8087 * # => [2, 3, :foo, :bar, "foo", "bar"]
8088 *
8089 * The +init+ value and elements need not be numeric, but must all be <tt>+</tt>-compatible:
8090 *
8091 * # Raises TypeError: Array can't be coerced into Integer.
8092 * [[:foo, :bar], ['foo', 'bar']].sum(2)
8093 *
8094 * With a block given, calls the block with each element of +self+;
8095 * the block's return value (instead of the element itself) is used as the addend:
8096 *
8097 * ['zero', 1, :two].sum('Coerced and concatenated: ') {|element| element.to_s }
8098 * # => "Coerced and concatenated: zero1two"
8099 *
8100 * Notes:
8101 *
8102 * - Array#join and Array#flatten may be faster than Array#sum
8103 * for an array of strings or an array of arrays.
8104 * - Array#sum method may not respect method redefinition of "+" methods such as Integer#+.
8105 *
8106 */
8108 static VALUE
8110 {
8128 }
8139 }
8140 }
8146 else
8148 }
8149 else
8151 }
8155 not_exact:
8159 /*
8160 * Kahan-Babuska balancing compensated summation algorithm
8161 * See https://link.springer.com/article/10.1007/s00607-005-0139-x
8162 */
8174 has_float_value:
8182 else
8189 }
8193 else
8196 }
8202 else
8205 }
8209 not_float:
8211 }
8214 init_is_a_value:
8219 has_some_value:
8221 }
8223 }
8225 /* :nodoc: */
8226 static VALUE
8228 {
8230 }
8232 /*
8233 * An \Array object is an ordered, integer-indexed collection of objects,
8234 * called _elements_;
8235 * the object represents
8236 * an {array data structure}[https://en.wikipedia.org/wiki/Array_(data_structure)].
8237 *
8238 * An element may be any object (even another array);
8239 * elements may be any mixture of objects of different types.
8240 *
8241 * Important data structures that use arrays include:
8242 *
8243 * - {Coordinate vector}[https://en.wikipedia.org/wiki/Coordinate_vector].
8244 * - {Matrix}[https://en.wikipedia.org/wiki/Matrix_(mathematics)].
8245 * - {Heap}[https://en.wikipedia.org/wiki/Heap_(data_structure)].
8246 * - {Hash table}[https://en.wikipedia.org/wiki/Hash_table].
8247 * - {Deque (double-ended queue)}[https://en.wikipedia.org/wiki/Double-ended_queue].
8248 * - {Queue}[https://en.wikipedia.org/wiki/Queue_(abstract_data_type)].
8249 * - {Stack}[https://en.wikipedia.org/wiki/Stack_(abstract_data_type)].
8250 *
8251 * There are also array-like data structures:
8252 *
8253 * - {Associative array}[https://en.wikipedia.org/wiki/Associative_array] (see Hash).
8254 * - {Directory}[https://en.wikipedia.org/wiki/Directory_(computing)] (see Dir).
8255 * - {Environment}[https://en.wikipedia.org/wiki/Environment_variable] (see ENV).
8256 * - {Set}[https://en.wikipedia.org/wiki/Set_(abstract_data_type)] (see Set).
8257 * - {String}[https://en.wikipedia.org/wiki/String_(computer_science)] (see String).
8258 *
8259 * == \Array Indexes
8260 *
8261 * \Array indexing starts at 0, as in C or Java.
8262 *
8263 * A non-negative index is an offset from the first element:
8264 *
8265 * - Index 0 indicates the first element.
8266 * - Index 1 indicates the second element.
8267 * - ...
8268 *
8269 * A negative index is an offset, backwards, from the end of the array:
8270 *
8271 * - Index -1 indicates the last element.
8272 * - Index -2 indicates the next-to-last element.
8273 * - ...
8274 *
8275 *
8276 * === In-Range and Out-of-Range Indexes
8277 *
8278 * A non-negative index is <i>in range</i> if and only if it is smaller than
8279 * the size of the array. For a 3-element array:
8280 *
8281 * - Indexes 0 through 2 are in range.
8282 * - Index 3 is out of range.
8283 *
8284 * A negative index is <i>in range</i> if and only if its absolute value is
8285 * not larger than the size of the array. For a 3-element array:
8286 *
8287 * - Indexes -1 through -3 are in range.
8288 * - Index -4 is out of range.
8289 *
8290 * === Effective Index
8291 *
8292 * Although the effective index into an array is always an integer,
8293 * some methods (both within class \Array and elsewhere)
8294 * accept one or more non-integer arguments that are
8295 * {integer-convertible objects}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects].
8296 *
8297 * == Creating Arrays
8298 *
8299 * You can create an \Array object explicitly with:
8300 *
8301 * - An {array literal}[rdoc-ref:syntax/literals.rdoc@Array+Literals]:
8302 *
8303 * [1, 'one', :one, [2, 'two', :two]]
8304 *
8305 * - A {%w or %W string-array Literal}[rdoc-ref:syntax/literals.rdoc@25w+and+-25W-3A+String-Array+Literals]:
8306 *
8307 * %w[foo bar baz] # => ["foo", "bar", "baz"]
8308 * %w[1 % *] # => ["1", "%", "*"]
8309 *
8310 * - A {%i or %I symbol-array Literal}[rdoc-ref:syntax/literals.rdoc@25i+and+-25I-3A+Symbol-Array+Literals]:
8311 *
8312 * %i[foo bar baz] # => [:foo, :bar, :baz]
8313 * %i[1 % *] # => [:"1", :%, :*]
8314 *
8315 * - Method Kernel#Array:
8316 *
8317 * Array(["a", "b"]) # => ["a", "b"]
8318 * Array(1..5) # => [1, 2, 3, 4, 5]
8319 * Array(key: :value) # => [[:key, :value]]
8320 * Array(nil) # => []
8321 * Array(1) # => [1]
8322 * Array({:a => "a", :b => "b"}) # => [[:a, "a"], [:b, "b"]]
8323 *
8324 * - Method Array.new:
8325 *
8326 * Array.new # => []
8327 * Array.new(3) # => [nil, nil, nil]
8328 * Array.new(4) {Hash.new} # => [{}, {}, {}, {}]
8329 * Array.new(3, true) # => [true, true, true]
8330 *
8331 * Note that the last example above populates the array
8332 * with references to the same object.
8333 * This is recommended only in cases where that object is a natively immutable object
8334 * such as a symbol, a numeric, +nil+, +true+, or +false+.
8335 *
8336 * Another way to create an array with various objects, using a block;
8337 * this usage is safe for mutable objects such as hashes, strings or
8338 * other arrays:
8339 *
8340 * Array.new(4) {|i| i.to_s } # => ["0", "1", "2", "3"]
8341 *
8342 * Here is a way to create a multi-dimensional array:
8343 *
8344 * Array.new(3) {Array.new(3)}
8345 * # => [[nil, nil, nil], [nil, nil, nil], [nil, nil, nil]]
8346 *
8347 * A number of Ruby methods, both in the core and in the standard library,
8348 * provide instance method +to_a+, which converts an object to an array.
8349 *
8350 * - ARGF#to_a
8351 * - Array#to_a
8352 * - Enumerable#to_a
8353 * - Hash#to_a
8354 * - MatchData#to_a
8355 * - NilClass#to_a
8356 * - OptionParser#to_a
8357 * - Range#to_a
8358 * - Set#to_a
8359 * - Struct#to_a
8360 * - Time#to_a
8361 * - Benchmark::Tms#to_a
8362 * - CSV::Table#to_a
8363 * - Enumerator::Lazy#to_a
8364 * - Gem::List#to_a
8365 * - Gem::NameTuple#to_a
8366 * - Gem::Platform#to_a
8367 * - Gem::RequestSet::Lockfile::Tokenizer#to_a
8368 * - Gem::SourceList#to_a
8369 * - OpenSSL::X509::Extension#to_a
8370 * - OpenSSL::X509::Name#to_a
8371 * - Racc::ISet#to_a
8372 * - Rinda::RingFinger#to_a
8373 * - Ripper::Lexer::Elem#to_a
8374 * - RubyVM::InstructionSequence#to_a
8375 * - YAML::DBM#to_a
8376 *
8377 * == Example Usage
8378 *
8379 * In addition to the methods it mixes in through the Enumerable module,
8380 * class \Array has proprietary methods for accessing, searching and otherwise
8381 * manipulating arrays.
8382 *
8383 * Some of the more common ones are illustrated below.
8384 *
8385 * == Accessing Elements
8386 *
8387 * Elements in an array can be retrieved using the Array#[] method. It can
8388 * take a single integer argument (a numeric index), a pair of arguments
8389 * (start and length) or a range. Negative indices start counting from the end,
8390 * with -1 being the last element.
8391 *
8392 * arr = [1, 2, 3, 4, 5, 6]
8393 * arr[2] #=> 3
8394 * arr[100] #=> nil
8395 * arr[-3] #=> 4
8396 * arr[2, 3] #=> [3, 4, 5]
8397 * arr[1..4] #=> [2, 3, 4, 5]
8398 * arr[1..-3] #=> [2, 3, 4]
8399 *
8400 * Another way to access a particular array element is by using the #at method
8401 *
8402 * arr.at(0) #=> 1
8403 *
8404 * The #slice method works in an identical manner to Array#[].
8405 *
8406 * To raise an error for indices outside of the array bounds or else to
8407 * provide a default value when that happens, you can use #fetch.
8408 *
8409 * arr = ['a', 'b', 'c', 'd', 'e', 'f']
8410 * arr.fetch(100) #=> IndexError: index 100 outside of array bounds: -6...6
8411 * arr.fetch(100, "oops") #=> "oops"
8412 *
8413 * The special methods #first and #last will return the first and last
8414 * elements of an array, respectively.
8415 *
8416 * arr.first #=> 1
8417 * arr.last #=> 6
8418 *
8419 * To return the first +n+ elements of an array, use #take
8420 *
8421 * arr.take(3) #=> [1, 2, 3]
8422 *
8423 * #drop does the opposite of #take, by returning the elements after +n+
8424 * elements have been dropped:
8425 *
8426 * arr.drop(3) #=> [4, 5, 6]
8427 *
8428 * == Obtaining Information about an \Array
8429 *
8430 * An array keeps track of its own length at all times. To query an array
8431 * about the number of elements it contains, use #length, #count or #size.
8432 *
8433 * browsers = ['Chrome', 'Firefox', 'Safari', 'Opera', 'IE']
8434 * browsers.length #=> 5
8435 * browsers.count #=> 5
8436 *
8437 * To check whether an array contains any elements at all
8438 *
8439 * browsers.empty? #=> false
8440 *
8441 * To check whether a particular item is included in the array
8442 *
8443 * browsers.include?('Konqueror') #=> false
8444 *
8445 * == Adding Items to an \Array
8446 *
8447 * Items can be added to the end of an array by using either #push or #<<
8448 *
8449 * arr = [1, 2, 3, 4]
8450 * arr.push(5) #=> [1, 2, 3, 4, 5]
8451 * arr << 6 #=> [1, 2, 3, 4, 5, 6]
8452 *
8453 * #unshift will add a new item to the beginning of an array.
8454 *
8455 * arr.unshift(0) #=> [0, 1, 2, 3, 4, 5, 6]
8456 *
8457 * With #insert you can add a new element to an array at any position.
8458 *
8459 * arr.insert(3, 'apple') #=> [0, 1, 2, 'apple', 3, 4, 5, 6]
8460 *
8461 * Using the #insert method, you can also insert multiple values at once:
8462 *
8463 * arr.insert(3, 'orange', 'pear', 'grapefruit')
8464 * #=> [0, 1, 2, "orange", "pear", "grapefruit", "apple", 3, 4, 5, 6]
8465 *
8466 * == Removing Items from an \Array
8467 *
8468 * The method #pop removes the last element in an array and returns it:
8469 *
8470 * arr = [1, 2, 3, 4, 5, 6]
8471 * arr.pop #=> 6
8472 * arr #=> [1, 2, 3, 4, 5]
8473 *
8474 * To retrieve and at the same time remove the first item, use #shift:
8475 *
8476 * arr.shift #=> 1
8477 * arr #=> [2, 3, 4, 5]
8478 *
8479 * To delete an element at a particular index:
8480 *
8481 * arr.delete_at(2) #=> 4
8482 * arr #=> [2, 3, 5]
8483 *
8484 * To delete a particular element anywhere in an array, use #delete:
8485 *
8486 * arr = [1, 2, 2, 3]
8487 * arr.delete(2) #=> 2
8488 * arr #=> [1,3]
8489 *
8490 * A useful method if you need to remove +nil+ values from an array is
8491 * #compact:
8492 *
8493 * arr = ['foo', 0, nil, 'bar', 7, 'baz', nil]
8494 * arr.compact #=> ['foo', 0, 'bar', 7, 'baz']
8495 * arr #=> ['foo', 0, nil, 'bar', 7, 'baz', nil]
8496 * arr.compact! #=> ['foo', 0, 'bar', 7, 'baz']
8497 * arr #=> ['foo', 0, 'bar', 7, 'baz']
8498 *
8499 * Another common need is to remove duplicate elements from an array.
8500 *
8501 * It has the non-destructive #uniq, and destructive method #uniq!
8502 *
8503 * arr = [2, 5, 6, 556, 6, 6, 8, 9, 0, 123, 556]
8504 * arr.uniq #=> [2, 5, 6, 556, 8, 9, 0, 123]
8505 *
8506 * == Iterating over an \Array
8507 *
8508 * Like all classes that include the Enumerable module, class \Array has an each
8509 * method, which defines what elements should be iterated over and how. In
8510 * case of Array#each, all elements in +self+ are yielded to
8511 * the supplied block in sequence.
8512 *
8513 * Note that this operation leaves the array unchanged.
8514 *
8515 * arr = [1, 2, 3, 4, 5]
8516 * arr.each {|a| print a -= 10, " "}
8517 * # prints: -9 -8 -7 -6 -5
8518 * #=> [1, 2, 3, 4, 5]
8519 *
8520 * Another sometimes useful iterator is #reverse_each which will iterate over
8521 * the elements in the array in reverse order.
8522 *
8523 * words = %w[first second third fourth fifth sixth]
8524 * str = ""
8525 * words.reverse_each {|word| str += "#{word} "}
8526 * p str #=> "sixth fifth fourth third second first "
8527 *
8528 * The #map method can be used to create a new array based on the original
8529 * array, but with the values modified by the supplied block:
8530 *
8531 * arr.map {|a| 2*a} #=> [2, 4, 6, 8, 10]
8532 * arr #=> [1, 2, 3, 4, 5]
8533 * arr.map! {|a| a**2} #=> [1, 4, 9, 16, 25]
8534 * arr #=> [1, 4, 9, 16, 25]
8535 *
8536 *
8537 * == Selecting Items from an \Array
8538 *
8539 * Elements can be selected from an array according to criteria defined in a
8540 * block. The selection can happen in a destructive or a non-destructive
8541 * manner. While the destructive operations will modify the array they were
8542 * called on, the non-destructive methods usually return a new array with the
8543 * selected elements, but leave the original array unchanged.
8544 *
8545 * === Non-destructive Selection
8546 *
8547 * arr = [1, 2, 3, 4, 5, 6]
8548 * arr.select {|a| a > 3} #=> [4, 5, 6]
8549 * arr.reject {|a| a < 3} #=> [3, 4, 5, 6]
8550 * arr.drop_while {|a| a < 4} #=> [4, 5, 6]
8551 * arr #=> [1, 2, 3, 4, 5, 6]
8552 *
8553 * === Destructive Selection
8554 *
8555 * #select! and #reject! are the corresponding destructive methods to #select
8556 * and #reject
8557 *
8558 * Similar to #select vs. #reject, #delete_if and #keep_if have the exact
8559 * opposite result when supplied with the same block:
8560 *
8561 * arr.delete_if {|a| a < 4} #=> [4, 5, 6]
8562 * arr #=> [4, 5, 6]
8563 *
8564 * arr = [1, 2, 3, 4, 5, 6]
8565 * arr.keep_if {|a| a < 4} #=> [1, 2, 3]
8566 * arr #=> [1, 2, 3]
8567 *
8568 * == What's Here
8569 *
8570 * First, what's elsewhere. Class \Array:
8571 *
8572 * - Inherits from {class Object}[rdoc-ref:Object@What-27s+Here].
8573 * - Includes {module Enumerable}[rdoc-ref:Enumerable@What-27s+Here],
8574 * which provides dozens of additional methods.
8575 *
8576 * Here, class \Array provides methods that are useful for:
8577 *
8578 * - {Creating an Array}[rdoc-ref:Array@Methods+for+Creating+an+Array]
8579 * - {Querying}[rdoc-ref:Array@Methods+for+Querying]
8580 * - {Comparing}[rdoc-ref:Array@Methods+for+Comparing]
8581 * - {Fetching}[rdoc-ref:Array@Methods+for+Fetching]
8582 * - {Assigning}[rdoc-ref:Array@Methods+for+Assigning]
8583 * - {Deleting}[rdoc-ref:Array@Methods+for+Deleting]
8584 * - {Combining}[rdoc-ref:Array@Methods+for+Combining]
8585 * - {Iterating}[rdoc-ref:Array@Methods+for+Iterating]
8586 * - {Converting}[rdoc-ref:Array@Methods+for+Converting]
8587 * - {And more....}[rdoc-ref:Array@Other+Methods]
8588 *
8589 * === Methods for Creating an \Array
8590 *
8591 * - ::[]: Returns a new array populated with given objects.
8592 * - ::new: Returns a new array.
8593 * - ::try_convert: Returns a new array created from a given object.
8594 *
8595 * See also {Creating Arrays}[rdoc-ref:Array@Creating+Arrays].
8596 *
8597 * === Methods for Querying
8598 *
8599 * - #all?: Returns whether all elements meet a given criterion.
8600 * - #any?: Returns whether any element meets a given criterion.
8601 * - #count: Returns the count of elements that meet a given criterion.
8602 * - #empty?: Returns whether there are no elements.
8603 * - #find_index (aliased as #index): Returns the index of the first element that meets a given criterion.
8604 * - #hash: Returns the integer hash code.
8605 * - #include?: Returns whether any element <tt>==</tt> a given object.
8606 * - #length (aliased as #size): Returns the count of elements.
8607 * - #none?: Returns whether no element <tt>==</tt> a given object.
8608 * - #one?: Returns whether exactly one element <tt>==</tt> a given object.
8609 * - #rindex: Returns the index of the last element that meets a given criterion.
8610 *
8611 * === Methods for Comparing
8612 *
8613 * - #<=>: Returns -1, 0, or 1, as +self+ is less than, equal to, or greater than a given object.
8614 * - #==: Returns whether each element in +self+ is <tt>==</tt> to the corresponding element in a given object.
8615 * - #eql?: Returns whether each element in +self+ is <tt>eql?</tt> to the corresponding element in a given object.
8617 * === Methods for Fetching
8618 *
8619 * These methods do not modify +self+.
8620 *
8621 * - #[] (aliased as #slice): Returns consecutive elements as determined by a given argument.
8622 * - #assoc: Returns the first element that is an array whose first element <tt>==</tt> a given object.
8623 * - #at: Returns the element at a given offset.
8624 * - #bsearch: Returns an element selected via a binary search as determined by a given block.
8625 * - #bsearch_index: Returns the index of an element selected via a binary search as determined by a given block.
8626 * - #compact: Returns an array containing all non-+nil+ elements.
8627 * - #dig: Returns the object in nested objects that is specified by a given index and additional arguments.
8628 * - #drop: Returns trailing elements as determined by a given index.
8629 * - #drop_while: Returns trailing elements as determined by a given block.
8630 * - #fetch: Returns the element at a given offset.
8631 * - #fetch_values: Returns elements at given offsets.
8632 * - #first: Returns one or more leading elements.
8633 * - #last: Returns one or more trailing elements.
8634 * - #max: Returns one or more maximum-valued elements, as determined by <tt>#<=></tt> or a given block.
8635 * - #min: Returns one or more minimum-valued elements, as determined by <tt>#<=></tt> or a given block.
8636 * - #minmax: Returns the minimum-valued and maximum-valued elements, as determined by <tt>#<=></tt> or a given block.
8637 * - #rassoc: Returns the first element that is an array whose second element <tt>==</tt> a given object.
8638 * - #reject: Returns an array containing elements not rejected by a given block.
8639 * - #reverse: Returns all elements in reverse order.
8640 * - #rotate: Returns all elements with some rotated from one end to the other.
8641 * - #sample: Returns one or more random elements.
8642 * - #select (aliased as #filter): Returns an array containing elements selected by a given block.
8643 * - #shuffle: Returns elements in a random order.
8644 * - #sort: Returns all elements in an order determined by <tt>#<=></tt> or a given block.
8645 * - #take: Returns leading elements as determined by a given index.
8646 * - #take_while: Returns leading elements as determined by a given block.
8647 * - #uniq: Returns an array containing non-duplicate elements.
8648 * - #values_at: Returns the elements at given offsets.
8649 *
8650 * === Methods for Assigning
8651 *
8652 * These methods add, replace, or reorder elements in +self+.
8653 *
8654 * - #<<: Appends an element.
8655 * - #[]=: Assigns specified elements with a given object.
8656 * - #concat: Appends all elements from given arrays.
8657 * - #fill: Replaces specified elements with specified objects.
8658 * - #flatten!: Replaces each nested array in +self+ with the elements from that array.
8659 * - #initialize_copy (aliased as #replace): Replaces the content of +self+ with the content of a given array.
8660 * - #insert: Inserts given objects at a given offset; does not replace elements.
8661 * - #push (aliased as #append): Appends elements.
8662 * - #reverse!: Replaces +self+ with its elements reversed.
8663 * - #rotate!: Replaces +self+ with its elements rotated.
8664 * - #shuffle!: Replaces +self+ with its elements in random order.
8665 * - #sort!: Replaces +self+ with its elements sorted, as determined by <tt>#<=></tt> or a given block.
8666 * - #sort_by!: Replaces +self+ with its elements sorted, as determined by a given block.
8667 * - #unshift (aliased as #prepend): Prepends leading elements.
8668 *
8669 * === Methods for Deleting
8670 *
8671 * Each of these methods removes elements from +self+:
8672 *
8673 * - #clear: Removes all elements.
8674 * - #compact!: Removes all +nil+ elements.
8675 * - #delete: Removes elements equal to a given object.
8676 * - #delete_at: Removes the element at a given offset.
8677 * - #delete_if: Removes elements specified by a given block.
8678 * - #keep_if: Removes elements not specified by a given block.
8679 * - #pop: Removes and returns the last element.
8680 * - #reject!: Removes elements specified by a given block.
8681 * - #select! (aliased as #filter!): Removes elements not specified by a given block.
8682 * - #shift: Removes and returns the first element.
8683 * - #slice!: Removes and returns a sequence of elements.
8684 * - #uniq!: Removes duplicates.
8685 *
8686 * === Methods for Combining
8687 *
8688 * - #&: Returns an array containing elements found both in +self+ and a given array.
8689 * - #+: Returns an array containing all elements of +self+ followed by all elements of a given array.
8690 * - #-: Returns an array containing all elements of +self+ that are not found in a given array.
8691 * - #|: Returns an array containing all element of +self+ and all elements of a given array, duplicates removed.
8692 * - #difference: Returns an array containing all elements of +self+ that are not found in any of the given arrays..
8693 * - #intersection: Returns an array containing elements found both in +self+ and in each given array.
8694 * - #product: Returns or yields all combinations of elements from +self+ and given arrays.
8695 * - #reverse: Returns an array containing all elements of +self+ in reverse order.
8696 * - #union: Returns an array containing all elements of +self+ and all elements of given arrays, duplicates removed.
8697 *
8698 * === Methods for Iterating
8699 *
8700 * - #combination: Calls a given block with combinations of elements of +self+; a combination does not use the same element more than once.
8701 * - #cycle: Calls a given block with each element, then does so again, for a specified number of times, or forever.
8702 * - #each: Passes each element to a given block.
8703 * - #each_index: Passes each element index to a given block.
8704 * - #permutation: Calls a given block with permutations of elements of +self+; a permutation does not use the same element more than once.
8705 * - #repeated_combination: Calls a given block with combinations of elements of +self+; a combination may use the same element more than once.
8706 * - #repeated_permutation: Calls a given block with permutations of elements of +self+; a permutation may use the same element more than once.
8707 * - #reverse_each: Passes each element, in reverse order, to a given block.
8708 *
8709 * === Methods for Converting
8710 *
8711 * - #collect (aliased as #map): Returns an array containing the block return-value for each element.
8712 * - #collect! (aliased as #map!): Replaces each element with a block return-value.
8713 * - #flatten: Returns an array that is a recursive flattening of +self+.
8714 * - #inspect (aliased as #to_s): Returns a new String containing the elements.
8715 * - #join: Returns a newsString containing the elements joined by the field separator.
8716 * - #to_a: Returns +self+ or a new array containing all elements.
8717 * - #to_ary: Returns +self+.
8718 * - #to_h: Returns a new hash formed from the elements.
8719 * - #transpose: Transposes +self+, which must be an array of arrays.
8720 * - #zip: Returns a new array of arrays containing +self+ and given arrays.
8721 *
8722 * === Other Methods
8723 *
8724 * - #*: Returns one of the following:
8725 *
8726 * - With integer argument +n+, a new array that is the concatenation
8727 * of +n+ copies of +self+.
8728 * - With string argument +field_separator+, a new string that is equivalent to
8729 * <tt>join(field_separator)</tt>.
8730 *
8731 * - #pack: Packs the elements into a binary sequence.
8732 * - #sum: Returns a sum of elements according to either <tt>+</tt> or a given block.
8733 */
8735 void
8737 {
8866 }