318b7763ec6a13a8fc32cf75d78e384f2e447acd
| blob | 318b7763ec6a13a8fc32cf75d78e384f2e447acd |
1 /**********************************************************************
3 array.c -
5 $Author$
6 created at: Fri Aug 6 09:46:12 JST 1993
8 Copyright (C) 1993-2007 Yukihiro Matsumoto
9 Copyright (C) 2000 Network Applied Communication Laboratory, Inc.
10 Copyright (C) 2000 Information-technology Promotion Agency, Japan
12 **********************************************************************/
34 #if !ARRAY_DEBUG
35 # undef NDEBUG
36 # define NDEBUG
37 #endif
40 VALUE rb_cArray;
41 VALUE rb_cArray_empty_frozen;
43 /* Flags of RArray
44 *
45 * 1: RARRAY_EMBED_FLAG
46 * The array is embedded (its contents follow the header, rather than
47 * being on a separately allocated buffer).
48 * 2: RARRAY_SHARED_FLAG (equal to ELTS_SHARED)
49 * The array is shared. The buffer this array points to is owned by
50 * another array (the shared root).
51 * 3-9: RARRAY_EMBED_LEN
52 * The length of the array when RARRAY_EMBED_FLAG is set.
53 * 12: RARRAY_SHARED_ROOT_FLAG
54 * The array is a shared root that does reference counting. The buffer
55 * this array points to is owned by this array but may be pointed to
56 * by other arrays.
57 * Note: Frozen arrays may be a shared root without this flag being
58 * set. Frozen arrays do not have reference counting because
59 * they cannot be modified. Not updating the reference count
60 * improves copy-on-write performance. Their reference count is
61 * assumed to be infinity.
62 * 14: RARRAY_PTR_IN_USE_FLAG
63 * The buffer of the array is in use. This is only used during
64 * debugging.
65 */
67 /* for OPTIMIZED_CMP: */
68 #define id_cmp idCmp
70 #define ARY_DEFAULT_SIZE 16
71 #define ARY_MAX_SIZE (LONG_MAX / (int)sizeof(VALUE))
72 #define SMALL_ARRAY_LEN 16
75 static int
77 {
79 }
81 #define ARY_HEAP_PTR(a) (RUBY_ASSERT(!ARY_EMBED_P(a)), RARRAY(a)->as.heap.ptr)
82 #define ARY_HEAP_LEN(a) (RUBY_ASSERT(!ARY_EMBED_P(a)), RARRAY(a)->as.heap.len)
83 #define ARY_HEAP_CAPA(a) (RUBY_ASSERT(!ARY_EMBED_P(a)), RUBY_ASSERT(!ARY_SHARED_ROOT_P(a)), \
84 RARRAY(a)->as.heap.aux.capa)
86 #define ARY_EMBED_PTR(a) (RUBY_ASSERT(ARY_EMBED_P(a)), RARRAY(a)->as.ary)
87 #define ARY_EMBED_LEN(a) \
88 (RUBY_ASSERT(ARY_EMBED_P(a)), \
89 (long)((RBASIC(a)->flags >> RARRAY_EMBED_LEN_SHIFT) & \
90 (RARRAY_EMBED_LEN_MASK >> RARRAY_EMBED_LEN_SHIFT)))
91 #define ARY_HEAP_SIZE(a) (RUBY_ASSERT(!ARY_EMBED_P(a)), RUBY_ASSERT(ARY_OWNS_HEAP_P(a)), ARY_CAPA(a) * sizeof(VALUE))
93 #define ARY_OWNS_HEAP_P(a) (RUBY_ASSERT(should_be_T_ARRAY((VALUE)(a))), \
94 !FL_TEST_RAW((a), RARRAY_SHARED_FLAG|RARRAY_EMBED_FLAG))
96 #define FL_SET_EMBED(a) do { \
97 RUBY_ASSERT(!ARY_SHARED_P(a)); \
98 FL_SET((a), RARRAY_EMBED_FLAG); \
99 ary_verify(a); \
100 } while (0)
102 #define FL_UNSET_EMBED(ary) FL_UNSET((ary), RARRAY_EMBED_FLAG|RARRAY_EMBED_LEN_MASK)
103 #define FL_SET_SHARED(ary) do { \
104 RUBY_ASSERT(!ARY_EMBED_P(ary)); \
105 FL_SET((ary), RARRAY_SHARED_FLAG); \
106 } while (0)
107 #define FL_UNSET_SHARED(ary) FL_UNSET((ary), RARRAY_SHARED_FLAG)
109 #define ARY_SET_PTR(ary, p) do { \
110 RUBY_ASSERT(!ARY_EMBED_P(ary)); \
111 RUBY_ASSERT(!OBJ_FROZEN(ary)); \
112 RARRAY(ary)->as.heap.ptr = (p); \
113 } while (0)
114 #define ARY_SET_EMBED_LEN(ary, n) do { \
115 long tmp_n = (n); \
116 RUBY_ASSERT(ARY_EMBED_P(ary)); \
117 RBASIC(ary)->flags &= ~RARRAY_EMBED_LEN_MASK; \
118 RBASIC(ary)->flags |= (tmp_n) << RARRAY_EMBED_LEN_SHIFT; \
119 } while (0)
120 #define ARY_SET_HEAP_LEN(ary, n) do { \
121 RUBY_ASSERT(!ARY_EMBED_P(ary)); \
122 RARRAY(ary)->as.heap.len = (n); \
123 } while (0)
124 #define ARY_SET_LEN(ary, n) do { \
125 if (ARY_EMBED_P(ary)) { \
126 ARY_SET_EMBED_LEN((ary), (n)); \
127 } \
128 else { \
129 ARY_SET_HEAP_LEN((ary), (n)); \
130 } \
131 RUBY_ASSERT(RARRAY_LEN(ary) == (n)); \
132 } while (0)
133 #define ARY_INCREASE_PTR(ary, n) do { \
134 RUBY_ASSERT(!ARY_EMBED_P(ary)); \
135 RUBY_ASSERT(!OBJ_FROZEN(ary)); \
136 RARRAY(ary)->as.heap.ptr += (n); \
137 } while (0)
138 #define ARY_INCREASE_LEN(ary, n) do { \
139 RUBY_ASSERT(!OBJ_FROZEN(ary)); \
140 if (ARY_EMBED_P(ary)) { \
141 ARY_SET_EMBED_LEN((ary), RARRAY_LEN(ary)+(n)); \
142 } \
143 else { \
144 RARRAY(ary)->as.heap.len += (n); \
145 } \
146 } while (0)
148 #define ARY_CAPA(ary) (ARY_EMBED_P(ary) ? ary_embed_capa(ary) : \
149 ARY_SHARED_ROOT_P(ary) ? RARRAY_LEN(ary) : ARY_HEAP_CAPA(ary))
150 #define ARY_SET_CAPA(ary, n) do { \
151 RUBY_ASSERT(!ARY_EMBED_P(ary)); \
152 RUBY_ASSERT(!ARY_SHARED_P(ary)); \
153 RUBY_ASSERT(!OBJ_FROZEN(ary)); \
154 RARRAY(ary)->as.heap.aux.capa = (n); \
155 } while (0)
157 #define ARY_SHARED_ROOT_OCCUPIED(ary) (!OBJ_FROZEN(ary) && ARY_SHARED_ROOT_REFCNT(ary) == 1)
158 #define ARY_SET_SHARED_ROOT_REFCNT(ary, value) do { \
159 RUBY_ASSERT(ARY_SHARED_ROOT_P(ary)); \
160 RUBY_ASSERT(!OBJ_FROZEN(ary)); \
161 RUBY_ASSERT((value) >= 0); \
162 RARRAY(ary)->as.heap.aux.capa = (value); \
163 } while (0)
164 #define FL_SET_SHARED_ROOT(ary) do { \
165 RUBY_ASSERT(!OBJ_FROZEN(ary)); \
166 RUBY_ASSERT(!ARY_EMBED_P(ary)); \
167 FL_SET((ary), RARRAY_SHARED_ROOT_FLAG); \
168 } while (0)
172 {
177 }
178 #undef RARRAY_ASET
180 static long
182 {
186 }
188 static size_t
190 {
192 }
194 static bool
196 {
198 }
200 bool
202 {
203 /* An array cannot be turned embeddable when the array is:
204 * - Shared root: other objects may point to the buffer of this array
205 * so we cannot make it embedded.
206 * - Frozen: this array may also be a shared root without the shared root
207 * flag.
208 * - Shared: we don't want to re-embed an array that points to a shared
209 * root (to save memory).
210 */
212 }
214 size_t
216 {
221 }
224 }
227 }
229 }
232 #if ARRAY_DEBUG
233 #define ary_verify(ary) ary_verify_(ary, __FILE__, __LINE__)
235 static VALUE
237 {
248 }
252 }
260 }
262 }
265 }
267 void
269 {
271 }
272 #else
273 #define ary_verify(ary) ((void)0)
274 #endif
276 VALUE *
278 {
279 #if ARRAY_DEBUG
281 #endif
283 }
285 void
287 {
288 #if ARRAY_DEBUG
290 #endif
291 }
293 void
295 {
298 }
299 }
301 static void
303 {
306 });
307 }
311 {
314 }
315 }
317 static void
319 {
323 });
324 }
326 static void
328 {
335 });
336 }
342 }
343 });
344 }
345 }
347 static void
349 {
351 }
355 {
357 }
359 static void
361 {
363 }
365 static void
367 {
369 }
371 static size_t
373 {
379 }
381 void
383 {
395 }
396 }
398 static void
400 {
415 }
418 }
420 }
433 }
434 }
437 }
441 {
449 }
452 }
454 static void
456 {
461 }
464 }
469 }
471 static void
473 {
477 }
478 }
480 static void
482 {
486 }
488 static void
490 {
493 }
496 }
500 }
502 static VALUE
504 {
509 }
511 }
513 static void
515 {
525 }
529 {
532 }
534 void
536 {
550 }
551 else if (ARY_SHARED_ROOT_OCCUPIED(shared_root) && len > ((shared_len = RARRAY_LEN(shared_root))>>1)) {
558 });
561 }
568 }
571 }
573 }
575 void
577 {
580 }
582 static VALUE
584 {
591 }
602 }
604 /* if array is shared, then it is likely it participate in push/shift pattern */
609 }
612 }
613 }
614 }
617 }
620 }
624 }
628 }
630 /*
631 * call-seq:
632 * freeze -> self
633 *
634 * Freezes +self+ (if not already frozen); returns +self+:
635 *
636 * a = []
637 * a.frozen? # => false
638 * a.freeze
639 * a.frozen? # => true
640 *
641 * No further changes may be made to +self+;
642 * raises FrozenError if a change is attempted.
643 *
644 * Related: Kernel#frozen?.
645 */
647 VALUE
649 {
656 }
659 }
661 /* This can be used to take a snapshot of an array (with
662 e.g. rb_ary_replace) and check later whether the array has been
663 modified from the snapshot. The snapshot is cheap, though if
664 something does modify the array it will pay the cost of copying
665 it. If Array#pop or Array#shift has been called, the array will
666 be still shared with the snapshot, but the array length will
667 differ. */
668 VALUE
670 {
676 }
678 }
680 static VALUE
682 {
688 /* Created array is:
689 * FL_SET_EMBED((VALUE)ary);
690 * ARY_SET_EMBED_LEN((VALUE)ary, 0);
691 */
693 }
695 static VALUE
697 {
702 }
704 static VALUE
706 {
709 }
711 static VALUE
713 {
714 VALUE ary;
718 }
721 }
727 }
735 }
738 }
740 VALUE
742 {
744 }
746 VALUE
748 {
750 }
752 VALUE
754 {
756 VALUE ary;
764 }
769 }
771 VALUE
773 {
774 VALUE ary;
780 }
783 }
785 VALUE
787 {
789 }
791 static VALUE
793 {
799 /* Created array is:
800 * FL_SET_EMBED((VALUE)ary);
801 * ARY_SET_EMBED_LEN((VALUE)ary, 0);
802 */
804 }
806 static VALUE
808 {
813 }
815 static VALUE
817 {
818 VALUE ary;
822 }
825 }
831 }
839 }
842 }
844 VALUE
846 {
847 VALUE ary;
853 }
856 }
858 VALUE
860 {
863 }
865 VALUE
867 {
872 }
874 void
876 {
882 }
886 }
889 }
893 }
896 }
897 }
901 static VALUE
903 {
909 }
911 VALUE
913 {
917 // bypass frozen checks
922 }
924 size_t
926 {
929 }
932 }
933 }
935 static VALUE
937 {
942 }
945 }
948 }
953 /* Shared roots cannot be embedded because the reference count
954 * (refcnt) is stored in as.heap.aux.capa. */
966 }
969 }
979 }
980 }
982 static VALUE
984 {
994 }
997 }
998 }
1000 VALUE
1002 {
1004 }
1006 VALUE
1008 {
1010 }
1011 #define to_ary rb_to_array_type
1013 VALUE
1015 {
1017 }
1019 VALUE
1021 {
1023 }
1025 VALUE
1027 {
1029 }
1031 /*
1032 * call-seq:
1033 * Array.try_convert(object) -> object, new_array, or nil
1034 *
1035 * Attempts to return an array, based on the given +object+.
1036 *
1037 * If +object+ is an array, returns +object+.
1038 *
1039 * Otherwise if +object+ responds to <tt>:to_ary</tt>.
1040 * calls <tt>object.to_ary</tt>:
1041 * if the return value is an array or +nil+, returns that value;
1042 * if not, raises TypeError.
1043 *
1044 * Otherwise returns +nil+.
1045 *
1046 * Related: see {Methods for Creating an Array}[rdoc-ref:Array@Methods+for+Creating+an+Array].
1047 */
1049 static VALUE
1051 {
1053 }
1055 /* :nodoc: */
1056 static VALUE
1058 {
1059 VALUE ary;
1066 }
1071 }
1074 }
1077 }
1079 /*
1080 * call-seq:
1081 * Array.new -> new_empty_array
1082 * Array.new(array) -> new_array
1083 * Array.new(size, default_value = nil) -> new_array
1084 * Array.new(size = 0) {|index| ... } -> new_array
1085 *
1086 * Returns a new array.
1087 *
1088 * With no block and no argument given, returns a new empty array:
1089 *
1090 * Array.new # => []
1091 *
1092 * With no block and array argument given, returns a new array with the same elements:
1093 *
1094 * Array.new([:foo, 'bar', 2]) # => [:foo, "bar", 2]
1095 *
1096 * With no block and integer argument given, returns a new array containing
1097 * that many instances of the given +default_value+:
1098 *
1099 * Array.new(0) # => []
1100 * Array.new(3) # => [nil, nil, nil]
1101 * Array.new(2, 3) # => [3, 3]
1102 *
1103 * With a block given, returns an array of the given +size+;
1104 * calls the block with each +index+ in the range <tt>(0...size)</tt>;
1105 * the element at that +index+ in the returned array is the blocks return value:
1106 *
1107 * Array.new(3) {|index| "Element #{index}" } # => ["Element 0", "Element 1", "Element 2"]
1108 *
1109 * A common pitfall for new Rubyists is providing an expression as +default_value+:
1110 *
1111 * array = Array.new(2, {})
1112 * array # => [{}, {}]
1113 * array[0][:a] = 1
1114 * array # => [{a: 1}, {a: 1}], as array[0] and array[1] are same object
1115 *
1116 * If you want the elements of the array to be distinct, you should pass a block:
1117 *
1118 * array = Array.new(2) { {} }
1119 * array # => [{}, {}]
1120 * array[0][:a] = 1
1121 * array # => [{a: 1}, {}], as array[0] and array[1] are different objects
1122 *
1123 * Raises TypeError if the first argument is not either an array
1124 * or an {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects]).
1125 * Raises ArgumentError if the first argument is a negative integer.
1126 *
1127 * Related: see {Methods for Creating an Array}[rdoc-ref:Array@Methods+for+Creating+an+Array].
1128 */
1130 static VALUE
1132 {
1143 }
1145 }
1152 }
1153 }
1156 /* NUM2LONG() may call size.to_int, ary can be frozen, modified, etc */
1159 }
1162 }
1163 /* recheck after argument conversion */
1171 }
1175 }
1176 }
1180 }
1182 }
1184 /*
1185 * Returns a new array, populated with the given objects:
1186 *
1187 * Array[1, 'a', /^A/] # => [1, "a", /^A/]
1188 * Array[] # => []
1189 * Array.[](1, 'a', /^A/) # => [1, "a", /^A/]
1190 *
1191 * Related: see {Methods for Creating an Array}[rdoc-ref:Array@Methods+for+Creating+an+Array].
1192 */
1194 static VALUE
1196 {
1201 }
1204 }
1206 void
1208 {
1216 }
1217 }
1220 }
1225 }
1228 }
1232 }
1234 }
1236 static VALUE
1238 {
1249 }
1253 /* The ary_make_shared call may allocate, which can trigger a GC
1254 * compaction. This can cause the array to be embedded because it has
1255 * a length of 0. */
1266 }
1270 }
1272 static VALUE
1274 {
1290 }
1293 }
1309 }
1311 }
1319 }
1320 });
1322 }
1325 }
1327 static VALUE
1329 {
1331 }
1333 enum ary_take_pos_flags
1334 {
1337 };
1339 static VALUE
1341 {
1347 }
1350 }
1353 }
1355 }
1357 static VALUE
1359 {
1361 /* the case optional argument is omitted should be handled in
1362 * callers of this function. if another arity case is added,
1363 * this arity check needs to rewrite. */
1366 }
1368 /*
1369 * call-seq:
1370 * self << object -> self
1371 *
1372 * Appends +object+ as the last element in +self+; returns +self+:
1373 *
1374 * [:foo, 'bar', 2] << :baz # => [:foo, "bar", 2, :baz]
1375 *
1376 * Appends +object+ as a single element, even if it is another array:
1377 *
1378 * [:foo, 'bar', 2] << [3, 4] # => [:foo, "bar", 2, [3, 4]]
1379 *
1380 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
1381 */
1383 VALUE
1385 {
1390 });
1394 }
1396 VALUE
1398 {
1404 }
1406 /*
1407 * call-seq:
1408 * push(*objects) -> self
1409 * append(*objects) -> self
1410 *
1411 * Appends each argument in +objects+ to +self+; returns +self+:
1412 *
1413 * a = [:foo, 'bar', 2] # => [:foo, "bar", 2]
1414 * a.push(:baz, :bat) # => [:foo, "bar", 2, :baz, :bat]
1415 *
1416 * Appends each argument as a single element, even if it is another array:
1417 *
1418 * a = [:foo, 'bar', 2] # => [:foo, "bar", 2]
1419 a.push([:baz, :bat], [:bam, :bad]) # => [:foo, "bar", 2, [:baz, :bat], [:bam, :bad]]
1420 *
1421 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
1422 */
1424 static VALUE
1426 {
1428 }
1430 VALUE
1432 {
1440 {
1442 }
1447 }
1449 /*
1450 * call-seq:
1451 * pop -> object or nil
1452 * pop(count) -> new_array
1453 *
1454 * Removes and returns trailing elements of +self+.
1455 *
1456 * With no argument given, removes and returns the last element, if available;
1457 * otherwise returns +nil+:
1458 *
1459 * a = [:foo, 'bar', 2]
1460 * a.pop # => 2
1461 * a # => [:foo, "bar"]
1462 * [].pop # => nil
1463 *
1464 * With non-negative integer argument +count+ given,
1465 * returns a new array containing the trailing +count+ elements of +self+, as available:
1466 *
1467 * a = [:foo, 'bar', 2]
1468 * a.pop(2) # => ["bar", 2]
1469 * a # => [:foo]
1470 *
1471 * a = [:foo, 'bar', 2]
1472 * a.pop(50) # => [:foo, "bar", 2]
1473 * a # => []
1474 *
1475 * Related: Array#push;
1476 * see also {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
1477 */
1479 static VALUE
1481 {
1482 VALUE result;
1486 }
1493 }
1495 VALUE
1497 {
1498 VALUE top;
1504 }
1511 }
1513 /*
1514 * call-seq:
1515 * shift -> object or nil
1516 * shift(count) -> new_array or nil
1517 *
1518 * Removes and returns leading elements from +self+.
1519 *
1520 * With no argument, removes and returns one element, if available,
1521 * or +nil+ otherwise:
1522 *
1523 * a = [0, 1, 2, 3]
1524 * a.shift # => 0
1525 * a # => [1, 2, 3]
1526 * [].shift # => nil
1527 *
1528 * With non-negative numeric argument +count+ given,
1529 * removes and returns the first +count+ elements:
1530 *
1531 * a = [0, 1, 2, 3]
1532 * a.shift(2) # => [0, 1]
1533 * a # => [2, 3]
1534 * a.shift(1.1) # => [2]
1535 * a # => [3]
1536 * a.shift(0) # => []
1537 * a # => [3]
1538 *
1539 * If +count+ is large,
1540 * removes and returns all elements:
1541 *
1542 * a = [0, 1, 2, 3]
1543 * a.shift(50) # => [0, 1, 2, 3]
1544 * a # => []
1545 *
1546 * If +self+ is empty, returns a new empty array.
1547 *
1548 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
1549 */
1551 static VALUE
1553 {
1554 VALUE result;
1559 }
1567 }
1569 VALUE
1571 {
1574 }
1586 }
1590 }
1593 }
1600 }
1602 static VALUE
1603 make_room_for_unshift(VALUE ary, const VALUE *head, VALUE *sharedp, int argc, long capa, long len)
1604 {
1611 }
1617 }
1619 static VALUE
1621 {
1631 }
1633 /* use shared array for big "queues" */
1637 /* make a room for unshifted items */
1643 }
1645 /* sliding items */
1648 });
1652 }
1653 }
1655 static VALUE
1657 {
1663 }
1666 }
1673 }
1676 }
1683 }
1684 }
1685 }
1687 /*
1688 * call-seq:
1689 * unshift(*objects) -> self
1690 * prepend(*objects) -> self
1691 *
1692 * Prepends the given +objects+ to +self+:
1693 *
1694 * a = [:foo, 'bar', 2]
1695 * a.unshift(:bam, :bat) # => [:bam, :bat, :foo, "bar", 2]
1696 *
1697 * Related: Array#shift;
1698 * see also {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
1699 */
1701 VALUE
1703 {
1705 VALUE target_ary;
1710 }
1716 }
1718 VALUE
1720 {
1722 }
1724 /* faster version - use this if you don't need to treat negative offset */
1727 {
1732 }
1734 }
1736 VALUE
1738 {
1740 }
1742 VALUE
1744 {
1745 VALUE klass;
1753 }
1760 else
1762 }
1764 VALUE
1766 {
1768 }
1772 /*
1773 * call-seq:
1774 * self[index] -> object or nil
1775 * self[start, length] -> object or nil
1776 * self[range] -> object or nil
1777 * self[aseq] -> object or nil
1778 * slice(index) -> object or nil
1779 * slice(start, length) -> object or nil
1780 * slice(range) -> object or nil
1781 * slice(aseq) -> object or nil
1782 *
1783 * Returns elements from +self+; does not modify +self+.
1784 *
1785 * In brief:
1786 *
1787 * a = [:foo, 'bar', 2]
1788 *
1789 * # Single argument index: returns one element.
1790 * a[0] # => :foo # Zero-based index.
1791 * a[-1] # => 2 # Negative index counts backwards from end.
1792 *
1793 * # Arguments start and length: returns an array.
1794 * a[1, 2] # => ["bar", 2]
1795 * a[-2, 2] # => ["bar", 2] # Negative start counts backwards from end.
1796 *
1797 * # Single argument range: returns an array.
1798 * a[0..1] # => [:foo, "bar"]
1799 * a[0..-2] # => [:foo, "bar"] # Negative range-begin counts backwards from end.
1800 * a[-2..2] # => ["bar", 2] # Negative range-end counts backwards from end.
1801 *
1802 * When a single integer argument +index+ is given, returns the element at offset +index+:
1803 *
1804 * a = [:foo, 'bar', 2]
1805 * a[0] # => :foo
1806 * a[2] # => 2
1807 * a # => [:foo, "bar", 2]
1808 *
1809 * If +index+ is negative, counts backwards from the end of +self+:
1810 *
1811 * a = [:foo, 'bar', 2]
1812 * a[-1] # => 2
1813 * a[-2] # => "bar"
1814 *
1815 * If +index+ is out of range, returns +nil+.
1816 *
1817 * When two Integer arguments +start+ and +length+ are given,
1818 * returns a new +Array+ of size +length+ containing successive elements beginning at offset +start+:
1819 *
1820 * a = [:foo, 'bar', 2]
1821 * a[0, 2] # => [:foo, "bar"]
1822 * a[1, 2] # => ["bar", 2]
1823 *
1824 * If <tt>start + length</tt> is greater than <tt>self.length</tt>,
1825 * returns all elements from offset +start+ to the end:
1826 *
1827 * a = [:foo, 'bar', 2]
1828 * a[0, 4] # => [:foo, "bar", 2]
1829 * a[1, 3] # => ["bar", 2]
1830 * a[2, 2] # => [2]
1831 *
1832 * If <tt>start == self.size</tt> and <tt>length >= 0</tt>,
1833 * returns a new empty +Array+.
1834 *
1835 * If +length+ is negative, returns +nil+.
1836 *
1837 * When a single Range argument +range+ is given,
1838 * treats <tt>range.min</tt> as +start+ above
1839 * and <tt>range.size</tt> as +length+ above:
1840 *
1841 * a = [:foo, 'bar', 2]
1842 * a[0..1] # => [:foo, "bar"]
1843 * a[1..2] # => ["bar", 2]
1844 *
1845 * Special case: If <tt>range.start == a.size</tt>, returns a new empty +Array+.
1846 *
1847 * If <tt>range.end</tt> is negative, calculates the end index from the end:
1848 *
1849 * a = [:foo, 'bar', 2]
1850 * a[0..-1] # => [:foo, "bar", 2]
1851 * a[0..-2] # => [:foo, "bar"]
1852 * a[0..-3] # => [:foo]
1853 *
1854 * If <tt>range.start</tt> is negative, calculates the start index from the end:
1855 *
1856 * a = [:foo, 'bar', 2]
1857 * a[-1..2] # => [2]
1858 * a[-2..2] # => ["bar", 2]
1859 * a[-3..2] # => [:foo, "bar", 2]
1860 *
1861 * If <tt>range.start</tt> is larger than the array size, returns +nil+.
1862 *
1863 * a = [:foo, 'bar', 2]
1864 * a[4..1] # => nil
1865 * a[4..0] # => nil
1866 * a[4..-1] # => nil
1867 *
1868 * When a single Enumerator::ArithmeticSequence argument +aseq+ is given,
1869 * returns an +Array+ of elements corresponding to the indexes produced by
1870 * the sequence.
1871 *
1872 * a = ['--', 'data1', '--', 'data2', '--', 'data3']
1873 * a[(1..).step(2)] # => ["data1", "data2", "data3"]
1874 *
1875 * Unlike slicing with range, if the start or the end of the arithmetic sequence
1876 * is larger than array size, throws RangeError.
1877 *
1878 * a = ['--', 'data1', '--', 'data2', '--', 'data3']
1879 * a[(1..11).step(2)]
1880 * # RangeError (((1..11).step(2)) out of range)
1881 * a[(7..).step(2)]
1882 * # RangeError (((7..).step(2)) out of range)
1883 *
1884 * If given a single argument, and its type is not one of the listed, tries to
1885 * convert it to Integer, and raises if it is impossible:
1886 *
1887 * a = [:foo, 'bar', 2]
1888 * # Raises TypeError (no implicit conversion of Symbol into Integer):
1889 * a[:foo]
1890 *
1891 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
1892 */
1894 VALUE
1896 {
1900 }
1902 }
1904 static VALUE
1906 {
1911 }
1913 }
1915 VALUE
1917 {
1920 /* special case - speeding up */
1923 }
1924 /* check if idx is Range or ArithmeticSequence */
1932 }
1935 }
1937 /*
1938 * call-seq:
1939 * at(index) -> object or nil
1940 *
1941 * Returns the element of +self+ specified by the given +index+
1942 * or +nil+ if there is no such element;
1943 * +index+ must be an
1944 * {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects].
1945 *
1946 * For non-negative +index+, returns the element of +self+ at offset +index+:
1947 *
1948 * a = [:foo, 'bar', 2]
1949 * a.at(0) # => :foo
1950 * a.at(2) # => 2
1951 * a.at(2.0) # => 2
1952 *
1953 * For negative +index+, counts backwards from the end of +self+:
1954 *
1955 * a.at(-2) # => "bar"
1956 *
1957 * Related: Array#[];
1958 * see also {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
1959 */
1961 VALUE
1963 {
1965 }
1967 #if 0
1968 static VALUE
1970 {
1974 }
1977 }
1978 }
1979 #endif
1981 static VALUE
1983 {
1985 }
1987 static VALUE
1989 {
1992 }
1994 VALUE
1996 {
1999 }
2002 }
2003 }
2005 /*
2006 * call-seq:
2007 * fetch(index) -> element
2008 * fetch(index, default_value) -> element or default_value
2009 * fetch(index) {|index| ... } -> element or block_return_value
2010 *
2011 * Returns the element of +self+ at offset +index+ if +index+ is in range; +index+ must be an
2012 * {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects].
2013 *
2014 * With the single argument +index+ and no block,
2015 * returns the element at offset +index+:
2016 *
2017 * a = [:foo, 'bar', 2]
2018 * a.fetch(1) # => "bar"
2019 * a.fetch(1.1) # => "bar"
2020 *
2021 * If +index+ is negative, counts from the end of the array:
2022 *
2023 * a = [:foo, 'bar', 2]
2024 * a.fetch(-1) # => 2
2025 * a.fetch(-2) # => "bar"
2026 *
2027 * With arguments +index+ and +default_value+ (which may be any object) and no block,
2028 * returns +default_value+ if +index+ is out-of-range:
2029 *
2030 * a = [:foo, 'bar', 2]
2031 * a.fetch(1, nil) # => "bar"
2032 * a.fetch(3, :foo) # => :foo
2033 *
2034 * With argument +index+ and a block,
2035 * returns the element at offset +index+ if index is in range
2036 * (and the block is not called); otherwise calls the block with index and returns its return value:
2037 *
2038 * a = [:foo, 'bar', 2]
2039 * a.fetch(1) {|index| raise 'Cannot happen' } # => "bar"
2040 * a.fetch(50) {|index| "Value for #{index}" } # => "Value for 50"
2041 *
2042 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
2043 */
2045 static VALUE
2047 {
2056 }
2061 }
2067 }
2069 }
2071 }
2073 /*
2074 * call-seq:
2075 * find_index(object) -> integer or nil
2076 * find_index {|element| ... } -> integer or nil
2077 * find_index -> new_enumerator
2078 * index(object) -> integer or nil
2079 * index {|element| ... } -> integer or nil
2080 * index -> new_enumerator
2081 *
2082 * Returns the zero-based integer index of a specified element, or +nil+.
2083 *
2084 * With only argument +object+ given,
2085 * returns the index of the first element +element+
2086 * for which <tt>object == element</tt>:
2087 *
2088 * a = [:foo, 'bar', 2, 'bar']
2089 * a.index('bar') # => 1
2090 *
2091 * Returns +nil+ if no such element found.
2092 *
2093 * With only a block given,
2094 * calls the block with each successive element;
2095 * returns the index of the first element for which the block returns a truthy value:
2096 *
2097 * a = [:foo, 'bar', 2, 'bar']
2098 * a.index {|element| element == 'bar' } # => 1
2099 *
2100 * Returns +nil+ if the block never returns a truthy value.
2101 *
2102 * With neither an argument nor a block given, returns a new Enumerator.
2103 *
2104 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
2105 */
2107 static VALUE
2109 {
2110 VALUE val;
2118 }
2119 }
2121 }
2130 }
2131 }
2133 }
2135 /*
2136 * call-seq:
2137 * rindex(object) -> integer or nil
2138 * rindex {|element| ... } -> integer or nil
2139 * rindex -> new_enumerator
2140 *
2141 * Returns the index of the last element for which <tt>object == element</tt>.
2142 *
2143 * With argument +object+ given, returns the index of the last such element found:
2144 *
2145 * a = [:foo, 'bar', 2, 'bar']
2146 * a.rindex('bar') # => 3
2147 *
2148 * Returns +nil+ if no such object found.
2149 *
2150 * With a block given, calls the block with each successive element;
2151 * returns the index of the last element for which the block returns a truthy value:
2152 *
2153 * a = [:foo, 'bar', 2, 'bar']
2154 * a.rindex {|element| element == 'bar' } # => 3
2155 *
2156 * Returns +nil+ if the block never returns a truthy value.
2157 *
2158 * When neither an argument nor a block is given, returns a new Enumerator.
2159 *
2160 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
2161 */
2163 static VALUE
2165 {
2166 VALUE val;
2176 }
2177 }
2179 }
2188 }
2191 }
2192 }
2194 }
2196 VALUE
2198 {
2203 }
2205 static void
2207 {
2218 }
2219 }
2222 }
2224 {
2227 }
2230 VALUE target_ary;
2233 }
2240 }
2242 }
2248 }
2253 }
2260 }
2264 }
2266 /* In this case, we're copying from a region in this array, so
2267 * we don't need to fire the write barrier. */
2269 }
2271 /* do not use RARRAY_PTR() because it can causes GC.
2272 * ary can contain T_NONE object because it is not cleared.
2273 */
2276 }
2277 }
2278 }
2280 void
2282 {
2288 }
2291 }
2293 }
2295 VALUE
2297 {
2305 }
2309 }
2312 }
2315 }
2327 }
2332 }
2334 }
2337 }
2339 static VALUE
2341 {
2344 }
2346 static VALUE
2348 {
2353 }
2355 /*
2356 * call-seq:
2357 * self[index] = object -> object
2358 * self[start, length] = object -> object
2359 * self[range] = object -> object
2360 *
2361 * Assigns elements in +self+, based on the given +object+; returns +object+.
2362 *
2363 * In brief:
2364 *
2365 * a_orig = [:foo, 'bar', 2]
2366 *
2367 * # With argument index.
2368 * a = a_orig.dup
2369 * a[0] = 'foo' # => "foo"
2370 * a # => ["foo", "bar", 2]
2371 * a = a_orig.dup
2372 * a[7] = 'foo' # => "foo"
2373 * a # => [:foo, "bar", 2, nil, nil, nil, nil, "foo"]
2374 *
2375 * # With arguments start and length.
2376 * a = a_orig.dup
2377 * a[0, 2] = 'foo' # => "foo"
2378 * a # => ["foo", 2]
2379 * a = a_orig.dup
2380 * a[6, 50] = 'foo' # => "foo"
2381 * a # => [:foo, "bar", 2, nil, nil, nil, "foo"]
2382 *
2383 * # With argument range.
2384 * a = a_orig.dup
2385 * a[0..1] = 'foo' # => "foo"
2386 * a # => ["foo", 2]
2387 * a = a_orig.dup
2388 * a[6..50] = 'foo' # => "foo"
2389 * a # => [:foo, "bar", 2, nil, nil, nil, "foo"]
2390 *
2391 * When Integer argument +index+ is given, assigns +object+ to an element in +self+.
2392 *
2393 * If +index+ is non-negative, assigns +object+ the element at offset +index+:
2394 *
2395 * a = [:foo, 'bar', 2]
2396 * a[0] = 'foo' # => "foo"
2397 * a # => ["foo", "bar", 2]
2398 *
2399 * If +index+ is greater than <tt>self.length</tt>, extends the array:
2400 *
2401 * a = [:foo, 'bar', 2]
2402 * a[7] = 'foo' # => "foo"
2403 * a # => [:foo, "bar", 2, nil, nil, nil, nil, "foo"]
2404 *
2405 * If +index+ is negative, counts backwards from the end of the array:
2406 *
2407 * a = [:foo, 'bar', 2]
2408 * a[-1] = 'two' # => "two"
2409 * a # => [:foo, "bar", "two"]
2410 *
2411 * When Integer arguments +start+ and +length+ are given and +object+ is not an +Array+,
2412 * removes <tt>length - 1</tt> elements beginning at offset +start+,
2413 * and assigns +object+ at offset +start+:
2414 *
2415 * a = [:foo, 'bar', 2]
2416 * a[0, 2] = 'foo' # => "foo"
2417 * a # => ["foo", 2]
2418 *
2419 * If +start+ is negative, counts backwards from the end of the array:
2420 *
2421 * a = [:foo, 'bar', 2]
2422 * a[-2, 2] = 'foo' # => "foo"
2423 * a # => [:foo, "foo"]
2424 *
2425 * If +start+ is non-negative and outside the array (<tt> >= self.size</tt>),
2426 * extends the array with +nil+, assigns +object+ at offset +start+,
2427 * and ignores +length+:
2428 *
2429 * a = [:foo, 'bar', 2]
2430 * a[6, 50] = 'foo' # => "foo"
2431 * a # => [:foo, "bar", 2, nil, nil, nil, "foo"]
2432 *
2433 * If +length+ is zero, shifts elements at and following offset +start+
2434 * and assigns +object+ at offset +start+:
2435 *
2436 * a = [:foo, 'bar', 2]
2437 * a[1, 0] = 'foo' # => "foo"
2438 * a # => [:foo, "foo", "bar", 2]
2439 *
2440 * If +length+ is too large for the existing array, does not extend the array:
2441 *
2442 * a = [:foo, 'bar', 2]
2443 * a[1, 5] = 'foo' # => "foo"
2444 * a # => [:foo, "foo"]
2445 *
2446 * When Range argument +range+ is given and +object+ is not an +Array+,
2447 * removes <tt>length - 1</tt> elements beginning at offset +start+,
2448 * and assigns +object+ at offset +start+:
2449 *
2450 * a = [:foo, 'bar', 2]
2451 * a[0..1] = 'foo' # => "foo"
2452 * a # => ["foo", 2]
2453 *
2454 * if <tt>range.begin</tt> is negative, counts backwards from the end of the array:
2455 *
2456 * a = [:foo, 'bar', 2]
2457 * a[-2..2] = 'foo' # => "foo"
2458 * a # => [:foo, "foo"]
2459 *
2460 * If the array length is less than <tt>range.begin</tt>,
2461 * extends the array with +nil+, assigns +object+ at offset <tt>range.begin</tt>,
2462 * and ignores +length+:
2463 *
2464 * a = [:foo, 'bar', 2]
2465 * a[6..50] = 'foo' # => "foo"
2466 * a # => [:foo, "bar", 2, nil, nil, nil, "foo"]
2467 *
2468 * If <tt>range.end</tt> is zero, shifts elements at and following offset +start+
2469 * and assigns +object+ at offset +start+:
2470 *
2471 * a = [:foo, 'bar', 2]
2472 * a[1..0] = 'foo' # => "foo"
2473 * a # => [:foo, "foo", "bar", 2]
2474 *
2475 * If <tt>range.end</tt> is negative, assigns +object+ at offset +start+,
2476 * retains <tt>range.end.abs -1</tt> elements past that, and removes those beyond:
2477 *
2478 * a = [:foo, 'bar', 2]
2479 * a[1..-1] = 'foo' # => "foo"
2480 * a # => [:foo, "foo"]
2481 * a = [:foo, 'bar', 2]
2482 * a[1..-2] = 'foo' # => "foo"
2483 * a # => [:foo, "foo", 2]
2484 * a = [:foo, 'bar', 2]
2485 * a[1..-3] = 'foo' # => "foo"
2486 * a # => [:foo, "foo", "bar", 2]
2487 * a = [:foo, 'bar', 2]
2488 *
2489 * If <tt>range.end</tt> is too large for the existing array,
2490 * replaces array elements, but does not extend the array with +nil+ values:
2491 *
2492 * a = [:foo, 'bar', 2]
2493 * a[1..5] = 'foo' # => "foo"
2494 * a # => [:foo, "foo"]
2495 *
2496 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
2497 */
2499 static VALUE
2501 {
2510 }
2514 }
2516 /* check if idx is Range */
2518 }
2522 }
2524 /*
2525 * call-seq:
2526 * insert(index, *objects) -> self
2527 *
2528 * Inserts the given +objects+ as elements of +self+;
2529 * returns +self+.
2530 *
2531 * When +index+ is non-negative, inserts +objects+
2532 * _before_ the element at offset +index+:
2533 *
2534 * a = ['a', 'b', 'c'] # => ["a", "b", "c"]
2535 * a.insert(1, :x, :y, :z) # => ["a", :x, :y, :z, "b", "c"]
2536 *
2537 * Extends the array if +index+ is beyond the array (<tt>index >= self.size</tt>):
2538 *
2539 * a = ['a', 'b', 'c'] # => ["a", "b", "c"]
2540 * a.insert(5, :x, :y, :z) # => ["a", "b", "c", nil, nil, :x, :y, :z]
2541 *
2542 * When +index+ is negative, inserts +objects+
2543 * _after_ the element at offset <tt>index + self.size</tt>:
2544 *
2545 * a = ['a', 'b', 'c'] # => ["a", "b", "c"]
2546 * a.insert(-2, :x, :y, :z) # => ["a", "b", :x, :y, :z, "c"]
2547 *
2548 * With no +objects+ given, does nothing:
2549 *
2550 * a = ['a', 'b', 'c'] # => ["a", "b", "c"]
2551 * a.insert(1) # => ["a", "b", "c"]
2552 * a.insert(50) # => ["a", "b", "c"]
2553 * a.insert(-50) # => ["a", "b", "c"]
2554 *
2555 * Raises IndexError if +objects+ are given and +index+ is negative and out of range.
2556 *
2557 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
2558 */
2560 static VALUE
2562 {
2571 }
2577 }
2578 pos++;
2579 }
2582 }
2584 static VALUE
2587 static VALUE
2589 {
2591 }
2593 // Primitive to avoid a race condition in Array#each.
2594 // Return `true` and write `value` and `index` if the element exists.
2595 static VALUE
2597 {
2601 }
2605 }
2607 VALUE
2609 {
2615 }
2617 }
2619 /*
2620 * call-seq:
2621 * each_index {|index| ... } -> self
2622 * each_index -> new_enumerator
2623 *
2624 * With a block given, iterates over the elements of +self+,
2625 * passing each <i>array index</i> to the block;
2626 * returns +self+:
2627 *
2628 * a = [:foo, 'bar', 2]
2629 * a.each_index {|index| puts "#{index} #{a[index]}" }
2630 *
2631 * Output:
2632 *
2633 * 0 foo
2634 * 1 bar
2635 * 2 2
2636 *
2637 * Allows the array to be modified during iteration:
2638 *
2639 * a = [:foo, 'bar', 2]
2640 * a.each_index {|index| puts index; a.clear if index > 0 }
2641 * a # => []
2642 *
2643 * Output:
2644 *
2645 * 0
2646 * 1
2647 *
2648 * With no block given, returns a new Enumerator.
2649 *
2650 * Related: see {Methods for Iterating}[rdoc-ref:Array@Methods+for+Iterating].
2651 */
2653 static VALUE
2655 {
2661 }
2663 }
2665 /*
2666 * call-seq:
2667 * reverse_each {|element| ... } -> self
2668 * reverse_each -> Enumerator
2669 *
2670 * When a block given, iterates backwards over the elements of +self+,
2671 * passing, in reverse order, each element to the block;
2672 * returns +self+:
2673 *
2674 * a = []
2675 * [0, 1, 2].reverse_each {|element| a.push(element) }
2676 * a # => [2, 1, 0]
2677 *
2678 * Allows the array to be modified during iteration:
2679 *
2680 * a = ['a', 'b', 'c']
2681 * a.reverse_each {|element| a.clear if element.start_with?('b') }
2682 * a # => []
2683 *
2684 * When no block given, returns a new Enumerator.
2685 *
2686 * Related: see {Methods for Iterating}[rdoc-ref:Array@Methods+for+Iterating].
2687 */
2689 static VALUE
2691 {
2702 }
2703 }
2705 }
2707 /*
2708 * call-seq:
2709 * length -> integer
2710 * size -> integer
2711 *
2712 * Returns the count of elements in +self+:
2713 *
2714 * [0, 1, 2].length # => 3
2715 * [].length # => 0
2716 *
2717 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
2718 */
2720 static VALUE
2722 {
2725 }
2727 /*
2728 * call-seq:
2729 * array.empty? -> true or false
2730 *
2731 * Returns +true+ if the count of elements in +self+ is zero,
2732 * +false+ otherwise.
2733 *
2734 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
2735 */
2737 static VALUE
2739 {
2741 }
2743 VALUE
2745 {
2754 }
2756 VALUE
2758 {
2760 }
2766 static VALUE
2768 {
2777 }
2780 }
2782 }
2784 static long
2786 {
2788 VALUE val;
2797 }
2799 }
2801 static void
2803 {
2808 }
2809 }
2811 static void
2813 {
2816 }
2826 }
2827 }
2829 static void
2831 {
2841 }
2844 }
2847 }
2850 }
2853 }
2854 }
2855 }
2857 VALUE
2859 {
2868 }
2883 }
2886 }
2894 }
2896 /*
2897 * call-seq:
2898 * array.join(separator = $,) -> new_string
2899 *
2900 * Returns the new string formed by joining the converted elements of +self+;
2901 * for each element +element+:
2902 *
2903 * - Converts recursively using <tt>element.join(separator)</tt>
2904 * if +element+ is a <tt>kind_of?(Array)</tt>.
2905 * - Otherwise, converts using <tt>element.to_s</tt>.
2906 *
2907 * With no argument given, joins using the output field separator, <tt>$,</tt>:
2908 *
2909 * a = [:foo, 'bar', 2]
2910 * $, # => nil
2911 * a.join # => "foobar2"
2912 *
2913 * With string argument +separator+ given, joins using that separator:
2914 *
2915 * a = [:foo, 'bar', 2]
2916 * a.join("\n") # => "foo\nbar\n2"
2917 *
2918 * Joins recursively for nested arrays:
2919 *
2920 * a = [:foo, [:bar, [:baz, :bat]]]
2921 * a.join # => "foobarbazbat"
2922 *
2923 * Related: see {Methods for Converting}[rdoc-ref:Array@Methods+for+Converting].
2924 */
2925 static VALUE
2927 {
2928 VALUE sep;
2934 }
2935 }
2938 }
2940 static VALUE
2942 {
2953 }
2956 }
2958 /*
2959 * call-seq:
2960 * inspect -> new_string
2961 * to_s -> new_string
2962 *
2963 * Returns the new string formed by calling method <tt>#inspect</tt>
2964 * on each array element:
2965 *
2966 * a = [:foo, 'bar', 2]
2967 * a.inspect # => "[:foo, \"bar\", 2]"
2968 *
2969 * Related: see {Methods for Converting}[rdoc-ref:Array@Methods+for+Converting].
2970 */
2972 static VALUE
2974 {
2977 }
2979 VALUE
2981 {
2983 }
2985 /*
2986 * call-seq:
2987 * to_a -> self or new_array
2988 *
2989 * When +self+ is an instance of +Array+, returns +self+.
2990 *
2991 * Otherwise, returns a new array containing the elements of +self+:
2992 *
2993 * class MyArray < Array; end
2994 * my_a = MyArray.new(['foo', 'bar', 'two'])
2995 * a = my_a.to_a
2996 * a # => ["foo", "bar", "two"]
2997 * a.class # => Array # Not MyArray.
2998 *
2999 * Related: see {Methods for Converting}[rdoc-ref:Array@Methods+for+Converting].
3000 */
3002 static VALUE
3004 {
3009 }
3011 }
3013 /*
3014 * call-seq:
3015 * to_h -> new_hash
3016 * to_h {|element| ... } -> new_hash
3017 *
3018 * Returns a new hash formed from +self+.
3019 *
3020 * With no block given, each element of +self+ must be a 2-element sub-array;
3021 * forms each sub-array into a key-value pair in the new hash:
3022 *
3023 * a = [['foo', 'zero'], ['bar', 'one'], ['baz', 'two']]
3024 * a.to_h # => {"foo"=>"zero", "bar"=>"one", "baz"=>"two"}
3025 * [].to_h # => {}
3026 *
3027 * With a block given, the block must return a 2-element array;
3028 * calls the block with each element of +self+;
3029 * forms each returned array into a key-value pair in the returned hash:
3030 *
3031 * a = ['foo', :bar, 1, [2, 3], {baz: 4}]
3032 * a.to_h {|element| [element, element.class] }
3033 * # => {"foo"=>String, :bar=>Symbol, 1=>Integer, [2, 3]=>Array, {:baz=>4}=>Hash}
3034 *
3035 * Related: see {Methods for Converting}[rdoc-ref:Array@Methods+for+Converting].
3036 */
3038 static VALUE
3040 {
3052 }
3056 }
3058 }
3060 }
3062 /*
3063 * call-seq:
3064 * array.to_ary -> self
3065 *
3066 * Returns +self+.
3067 */
3069 static VALUE
3071 {
3073 }
3075 static void
3077 {
3082 }
3083 }
3085 VALUE
3087 {
3097 }
3099 }
3101 /*
3102 * call-seq:
3103 * reverse! -> self
3104 *
3105 * Reverses the order of the elements of +self+;
3106 * returns +self+:
3107 *
3108 * a = [0, 1, 2]
3109 * a.reverse! # => [2, 1, 0]
3110 * a # => [2, 1, 0]
3111 *
3112 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
3113 */
3115 static VALUE
3117 {
3119 }
3121 /*
3122 * call-seq:
3123 * reverse -> new_array
3124 *
3125 * Returns a new array containing the elements of +self+ in reverse order:
3126 *
3127 * [0, 1, 2].reverse # => [2, 1, 0]
3128 *
3129 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
3130 */
3132 static VALUE
3134 {
3142 }
3145 }
3149 {
3151 }
3153 static void
3155 {
3160 }
3165 }
3171 }
3172 }
3174 VALUE
3176 {
3184 }
3185 }
3187 }
3189 /*
3190 * call-seq:
3191 * rotate!(count = 1) -> self
3192 *
3193 * Rotates +self+ in place by moving elements from one end to the other; returns +self+.
3194 *
3195 * With non-negative numeric +count+,
3196 * rotates +count+ elements from the beginning to the end:
3197 *
3198 * [0, 1, 2, 3].rotate!(2) # => [2, 3, 0, 1]
3199 [0, 1, 2, 3].rotate!(2.1) # => [2, 3, 0, 1]
3200 *
3201 * If +count+ is large, uses <tt>count % array.size</tt> as the count:
3202 *
3203 * [0, 1, 2, 3].rotate!(21) # => [1, 2, 3, 0]
3204 *
3205 * If +count+ is zero, rotates no elements:
3206 *
3207 * [0, 1, 2, 3].rotate!(0) # => [0, 1, 2, 3]
3208 *
3209 * With a negative numeric +count+, rotates in the opposite direction,
3210 * from end to beginning:
3211 *
3212 * [0, 1, 2, 3].rotate!(-1) # => [3, 0, 1, 2]
3213 *
3214 * If +count+ is small (far from zero), uses <tt>count % array.size</tt> as the count:
3215 *
3216 * [0, 1, 2, 3].rotate!(-21) # => [3, 0, 1, 2]
3217 *
3218 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
3219 */
3221 static VALUE
3223 {
3227 }
3229 /*
3230 * call-seq:
3231 * rotate(count = 1) -> new_array
3232 *
3233 * Returns a new array formed from +self+ with elements
3234 * rotated from one end to the other.
3235 *
3236 * With non-negative numeric +count+,
3237 * rotates elements from the beginning to the end:
3238 *
3239 * [0, 1, 2, 3].rotate(2) # => [2, 3, 0, 1]
3240 * [0, 1, 2, 3].rotate(2.1) # => [2, 3, 0, 1]
3241 *
3242 * If +count+ is large, uses <tt>count % array.size</tt> as the count:
3243 *
3244 * [0, 1, 2, 3].rotate(22) # => [2, 3, 0, 1]
3245 *
3246 * With a +count+ of zero, rotates no elements:
3247 *
3248 * [0, 1, 2, 3].rotate(0) # => [0, 1, 2, 3]
3249 *
3250 * With negative numeric +count+, rotates in the opposite direction,
3251 * from the end to the beginning:
3252 *
3253 * [0, 1, 2, 3].rotate(-1) # => [3, 0, 1, 2]
3254 *
3255 * If +count+ is small (far from zero), uses <tt>count % array.size</tt> as the count:
3256 *
3257 * [0, 1, 2, 3].rotate(-21) # => [3, 0, 1, 2]
3258 *
3259 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
3260 */
3262 static VALUE
3264 {
3265 VALUE rotated;
3278 }
3281 }
3284 VALUE ary;
3285 VALUE receiver;
3286 };
3288 static VALUE
3290 {
3293 }
3295 }
3297 static void
3299 {
3302 }
3304 }
3306 static int
3308 {
3321 }
3323 static int
3325 {
3335 }
3338 }
3341 }
3348 }
3350 /*
3351 * call-seq:
3352 * sort! -> self
3353 * sort! {|a, b| ... } -> self
3354 *
3355 * Like Array#sort, but returns +self+ with its elements sorted in place.
3356 *
3357 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
3358 */
3360 VALUE
3362 {
3381 }
3384 }
3387 }
3392 }
3397 }
3399 /* ary might be destructively operated in the given block */
3401 }
3404 }
3408 }
3409 /* tmp was lost ownership for the ptr */
3414 }
3415 /* tmp will be GC'ed. */
3417 }
3420 }
3422 /*
3423 * call-seq:
3424 * sort -> new_array
3425 * sort {|a, b| ... } -> new_array
3426 *
3427 * Returns a new array containing the elements of +self+, sorted.
3428 *
3429 * With no block given, compares elements using operator <tt>#<=></tt>
3430 * (see Object#<=>):
3431 *
3432 * [0, 2, 3, 1].sort # => [0, 1, 2, 3]
3433 *
3434 * With a block given, calls the block with each combination of pairs of elements from +self+;
3435 * for each pair +a+ and +b+, the block should return a numeric:
3436 *
3437 * - Negative when +b+ is to follow +a+.
3438 * - Zero when +a+ and +b+ are equivalent.
3439 * - Positive when +a+ is to follow +b+.
3440 *
3441 * Example:
3442 *
3443 * a = [3, 2, 0, 1]
3444 * a.sort {|a, b| a <=> b } # => [0, 1, 2, 3]
3445 * a.sort {|a, b| b <=> a } # => [3, 2, 1, 0]
3446 *
3447 * When the block returns zero, the order for +a+ and +b+ is indeterminate,
3448 * and may be unstable.
3449 *
3450 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
3451 */
3453 VALUE
3455 {
3459 }
3463 /*
3464 * call-seq:
3465 * bsearch {|element| ... } -> found_element or nil
3466 * bsearch -> new_enumerator
3467 *
3468 * Returns the element from +self+ found by a binary search,
3469 * or +nil+ if the search found no suitable element.
3470 *
3471 * See {Binary Searching}[rdoc-ref:bsearch.rdoc].
3472 *
3473 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
3474 */
3476 static VALUE
3478 {
3483 }
3485 }
3487 /*
3488 * call-seq:
3489 * bsearch_index {|element| ... } -> integer or nil
3490 * bsearch_index -> new_enumerator
3491 *
3492 * Returns the integer index of the element from +self+ found by a binary search,
3493 * or +nil+ if the search found no suitable element.
3494 *
3495 * See {Binary Searching}[rdoc-ref:bsearch.rdoc].
3496 *
3497 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
3498 */
3500 static VALUE
3502 {
3515 }
3519 }
3522 }
3529 }
3530 }
3535 }
3538 }
3541 }
3542 }
3545 }
3548 static VALUE
3550 {
3552 }
3554 /*
3555 * call-seq:
3556 * sort_by! {|element| ... } -> self
3557 * sort_by! -> new_enumerator
3558 *
3559 * With a block given, sorts the elements of +self+ in place;
3560 * returns self.
3561 *
3562 * Calls the block with each successive element;
3563 * sorts elements based on the values returned from the block:
3564 *
3565 * a = ['aaaa', 'bbb', 'cc', 'd']
3566 * a.sort_by! {|element| element.size }
3567 * a # => ["d", "cc", "bbb", "aaaa"]
3568 *
3569 * For duplicate values returned by the block, the ordering is indeterminate, and may be unstable.
3570 *
3571 * With no block given, returns a new Enumerator.
3572 *
3573 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
3574 */
3576 static VALUE
3578 {
3579 VALUE sorted;
3586 }
3589 /*
3590 * call-seq:
3591 * collect {|element| ... } -> new_array
3592 * collect -> new_enumerator
3593 * map {|element| ... } -> new_array
3594 * map -> new_enumerator
3595 *
3596 * With a block given, calls the block with each element of +self+;
3597 * returns a new array whose elements are the return values from the block:
3598 *
3599 * a = [:foo, 'bar', 2]
3600 * a1 = a.map {|element| element.class }
3601 * a1 # => [Symbol, String, Integer]
3602 *
3603 * With no block given, returns a new Enumerator.
3604 *
3605 * Related: #collect!;
3606 * see also {Methods for Converting}[rdoc-ref:Array@Methods+for+Converting].
3607 */
3609 static VALUE
3611 {
3613 VALUE collect;
3619 }
3621 }
3624 /*
3625 * call-seq:
3626 * collect! {|element| ... } -> new_array
3627 * collect! -> new_enumerator
3628 * map! {|element| ... } -> new_array
3629 * map! -> new_enumerator
3630 *
3631 * With a block given, calls the block with each element of +self+
3632 * and replaces the element with the block's return value;
3633 * returns +self+:
3634 *
3635 * a = [:foo, 'bar', 2]
3636 * a.map! { |element| element.class } # => [Symbol, String, Integer]
3637 *
3638 * With no block given, returns a new Enumerator.
3639 *
3640 * Related: #collect;
3641 * see also {Methods for Converting}[rdoc-ref:Array@Methods+for+Converting].
3642 */
3644 static VALUE
3646 {
3653 }
3655 }
3657 VALUE
3658 rb_get_values_at(VALUE obj, long olen, int argc, const VALUE *argv, VALUE (*func) (VALUE, long))
3659 {
3667 }
3668 /* check if idx is Range */
3673 }
3677 }
3679 }
3681 }
3683 static VALUE
3685 {
3689 }
3690 /* check if idx is Range */
3698 }
3701 }
3702 }
3704 }
3707 }
3709 }
3711 /*
3712 * call-seq:
3713 * array.values_at(*indexes) -> new_array
3714 *
3715 * Returns a new +Array+ whose elements are the elements
3716 * of +self+ at the given Integer or Range +indexes+.
3717 *
3718 * For each positive +index+, returns the element at offset +index+:
3719 *
3720 * a = [:foo, 'bar', 2]
3721 * a.values_at(0, 2) # => [:foo, 2]
3722 * a.values_at(0..1) # => [:foo, "bar"]
3723 *
3724 * The given +indexes+ may be in any order, and may repeat:
3725 *
3726 * a = [:foo, 'bar', 2]
3727 * a.values_at(2, 0, 1, 0, 2) # => [2, :foo, "bar", :foo, 2]
3728 * a.values_at(1, 0..2) # => ["bar", :foo, "bar", 2]
3729 *
3730 * Assigns +nil+ for an +index+ that is too large:
3731 *
3732 * a = [:foo, 'bar', 2]
3733 * a.values_at(0, 3, 1, 3) # => [:foo, nil, "bar", nil]
3734 *
3735 * Returns a new empty +Array+ if no arguments given.
3736 *
3737 * For each negative +index+, counts backward from the end of the array:
3738 *
3739 * a = [:foo, 'bar', 2]
3740 * a.values_at(-1, -3) # => [2, :foo]
3741 *
3742 * Assigns +nil+ for an +index+ that is too small:
3743 *
3744 * a = [:foo, 'bar', 2]
3745 * a.values_at(0, -5, 1, -6, 2) # => [:foo, nil, "bar", nil, 2]
3746 *
3747 * The given +indexes+ may have a mixture of signs:
3748 *
3749 * a = [:foo, 'bar', 2]
3750 * a.values_at(0, -2, 1, -1) # => [:foo, "bar", "bar", 2]
3751 *
3752 */
3754 static VALUE
3756 {
3761 }
3764 }
3767 /*
3768 * call-seq:
3769 * select {|element| ... } -> new_array
3770 * select -> new_enumerator
3771 * filter {|element| ... } -> new_array
3772 * filter -> new_enumerator
3773 *
3774 * With a block given, calls the block with each element of +self+;
3775 * returns a new array containing those elements of +self+
3776 * for which the block returns a truthy value:
3777 *
3778 * a = [:foo, 'bar', 2, :bam]
3779 * a.select {|element| element.to_s.start_with?('b') }
3780 * # => ["bar", :bam]
3781 *
3782 * With no block given, returns a new Enumerator.
3783 *
3784 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
3785 */
3787 static VALUE
3789 {
3790 VALUE result;
3798 }
3799 }
3801 }
3804 VALUE ary;
3806 };
3808 static VALUE
3810 {
3820 }
3822 }
3824 }
3826 static VALUE
3828 {
3841 });
3842 }
3844 }
3846 }
3848 /*
3849 * call-seq:
3850 * select! {|element| ... } -> self or nil
3851 * select! -> new_enumerator
3852 * filter! {|element| ... } -> self or nil
3853 * filter! -> new_enumerator
3854 *
3855 * With a block given, calls the block with each element of +self+;
3856 * removes from +self+ those elements for which the block returns +false+ or +nil+.
3857 *
3858 * Returns +self+ if any elements were removed:
3859 *
3860 * a = [:foo, 'bar', 2, :bam]
3861 * a.select! {|element| element.to_s.start_with?('b') } # => ["bar", :bam]
3862 *
3863 * Returns +nil+ if no elements were removed.
3864 *
3865 * With no block given, returns a new Enumerator.
3866 *
3867 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
3868 */
3870 static VALUE
3872 {
3881 }
3883 /*
3884 * call-seq:
3885 * keep_if {|element| ... } -> self
3886 * keep_if -> new_enumerator
3887 *
3888 * With a block given, calls the block with each element of +self+;
3889 * removes the element from +self+ if the block does not return a truthy value:
3890 *
3891 * a = [:foo, 'bar', 2, :bam]
3892 * a.keep_if {|element| element.to_s.start_with?('b') } # => ["bar", :bam]
3893 *
3894 * With no block given, returns a new Enumerator.
3895 *
3896 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
3897 */
3899 static VALUE
3901 {
3905 }
3907 static void
3909 {
3916 }
3917 }
3918 }
3920 /*
3921 * call-seq:
3922 * delete(object) -> last_removed_object
3923 * delete(object) {|element| ... } -> last_removed_object or block_return
3924 *
3925 * Removes zero or more elements from +self+.
3926 *
3927 * With no block given,
3928 * removes from +self+ each element +ele+ such that <tt>ele == object</tt>;
3929 * returns the last removed element:
3930 *
3931 * a = [0, 1, 2, 2.0]
3932 * a.delete(2) # => 2.0
3933 * a # => [0, 1]
3934 *
3935 * Returns +nil+ if no elements removed:
3936 *
3937 * a.delete(2) # => nil
3938 *
3939 * With a block given,
3940 * removes from +self+ each element +ele+ such that <tt>ele == object</tt>.
3941 *
3942 * If any such elements are found, ignores the block
3943 * and returns the last removed element:
3944 *
3945 * a = [0, 1, 2, 2.0]
3946 * a.delete(2) {|element| fail 'Cannot happen' } # => 2.0
3947 * a # => [0, 1]
3948 *
3949 * If no such element is found, returns the block's return value:
3950 *
3951 * a.delete(2) {|element| "Element #{element} not found." }
3952 * # => "Element 2 not found."
3953 *
3954 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
3955 */
3957 VALUE
3959 {
3969 }
3972 }
3973 i2++;
3974 }
3978 }
3980 }
3986 }
3988 void
3990 {
3998 }
4001 }
4002 i2++;
4003 }
4006 }
4009 }
4011 VALUE
4013 {
4015 VALUE del;
4021 }
4027 });
4031 }
4033 /*
4034 * call-seq:
4035 * delete_at(index) -> removed_object or nil
4036 *
4037 * Removes the element of +self+ at the given +index+, which must be an
4038 * {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects].
4039 *
4040 * When +index+ is non-negative, deletes the element at offset +index+:
4041 *
4042 * a = [:foo, 'bar', 2]
4043 * a.delete_at(1) # => "bar"
4044 * a # => [:foo, 2]
4045 *
4046 * When +index+ is negative, counts backward from the end of the array:
4047 *
4048 * a = [:foo, 'bar', 2]
4049 * a.delete_at(-2) # => "bar"
4050 * a # => [:foo, 2]
4051 *
4052 * When +index+ is out of range, returns +nil+.
4053 *
4054 * a = [:foo, 'bar', 2]
4055 * a.delete_at(3) # => nil
4056 * a.delete_at(-4) # => nil
4057 *
4058 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
4059 */
4061 static VALUE
4063 {
4065 }
4067 static VALUE
4069 {
4074 }
4077 }
4080 }
4083 }
4086 }
4089 }
4094 }
4095 }
4097 /*
4098 * call-seq:
4099 * slice!(index) -> object or nil
4100 * slice!(start, length) -> new_array or nil
4101 * slice!(range) -> new_array or nil
4102 *
4103 * Removes and returns elements from +self+.
4104 *
4105 * With numeric argument +index+ given,
4106 * removes and returns the element at offset +index+:
4107 *
4108 * a = ['a', 'b', 'c', 'd']
4109 * a.slice!(2) # => "c"
4110 * a # => ["a", "b", "d"]
4111 * a.slice!(2.1) # => "d"
4112 * a # => ["a", "b"]
4113 *
4114 * If +index+ is negative, counts backwards from the end of +self+:
4115 *
4116 * a = ['a', 'b', 'c', 'd']
4117 * a.slice!(-2) # => "c"
4118 * a # => ["a", "b", "d"]
4119 *
4120 * If +index+ is out of range, returns +nil+.
4121 *
4122 * With numeric arguments +start+ and +length+ given,
4123 * removes +length+ elements from +self+ beginning at zero-based offset +start+;
4124 * returns the removed objects in a new array:
4125 *
4126 * a = ['a', 'b', 'c', 'd']
4127 * a.slice!(1, 2) # => ["b", "c"]
4128 * a # => ["a", "d"]
4129 * a.slice!(0.1, 1.1) # => ["a"]
4130 * a # => ["d"]
4131 *
4132 * If +start+ is negative, counts backwards from the end of +self+:
4133 *
4134 * a = ['a', 'b', 'c', 'd']
4135 * a.slice!(-2, 1) # => ["c"]
4136 * a # => ["a", "b", "d"]
4137 *
4138 * If +start+ is out-of-range, returns +nil+:
4139 *
4140 * a = ['a', 'b', 'c', 'd']
4141 * a.slice!(5, 1) # => nil
4142 * a.slice!(-5, 1) # => nil
4143 *
4144 * If <tt>start + length</tt> exceeds the array size,
4145 * removes and returns all elements from offset +start+ to the end:
4146 *
4147 * a = ['a', 'b', 'c', 'd']
4148 * a.slice!(2, 50) # => ["c", "d"]
4149 * a # => ["a", "b"]
4150 *
4151 * If <tt>start == a.size</tt> and +length+ is non-negative,
4152 * returns a new empty array.
4153 *
4154 * If +length+ is negative, returns +nil+.
4155 *
4156 * With Range argument +range+ given,
4157 * treats <tt>range.min</tt> as +start+ (as above)
4158 * and <tt>range.size</tt> as +length+ (as above):
4159 *
4160 * a = ['a', 'b', 'c', 'd']
4161 * a.slice!(1..2) # => ["b", "c"]
4162 * a # => ["a", "d"]
4163 *
4164 * If <tt>range.start == a.size</tt>, returns a new empty array:
4165 *
4166 * a = ['a', 'b', 'c', 'd']
4167 * a.slice!(4..5) # => []
4168 *
4169 * If <tt>range.start</tt> is larger than the array size, returns +nil+:
4170 *
4171 * a = ['a', 'b', 'c', 'd']
4172 a.slice!(5..6) # => nil
4173 *
4174 * If <tt>range.start</tt> is negative,
4175 * calculates the start index by counting backwards from the end of +self+:
4176 *
4177 * a = ['a', 'b', 'c', 'd']
4178 * a.slice!(-2..2) # => ["c"]
4179 *
4180 * If <tt>range.end</tt> is negative,
4181 * calculates the end index by counting backwards from the end of +self+:
4182 *
4183 * a = ['a', 'b', 'c', 'd']
4184 * a.slice!(0..-2) # => ["a", "b", "c"]
4185 *
4186 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
4187 */
4189 static VALUE
4191 {
4192 VALUE arg1;
4203 }
4208 /* valid range */
4211 /* invalid range */
4214 /* not a range */
4216 }
4217 }
4220 }
4222 static VALUE
4224 {
4232 }
4233 }
4235 }
4237 static VALUE
4239 {
4249 }
4251 }
4253 }
4255 static VALUE
4257 {
4263 }
4265 /*
4266 * call-seq:
4267 * reject! {|element| ... } -> self or nil
4268 * reject! -> new_enumerator
4269 *
4270 * With a block given, calls the block with each element of +self+;
4271 * removes each element for which the block returns a truthy value.
4272 *
4273 * Returns +self+ if any elements removed:
4274 *
4275 * a = [:foo, 'bar', 2, 'bat']
4276 * a.reject! {|element| element.to_s.start_with?('b') } # => [:foo, 2]
4277 *
4278 * Returns +nil+ if no elements removed.
4279 *
4280 * With no block given, returns a new Enumerator.
4281 *
4282 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
4283 */
4285 static VALUE
4287 {
4291 }
4293 /*
4294 * call-seq:
4295 * reject {|element| ... } -> new_array
4296 * reject -> new_enumerator
4297 *
4298 * With a block given, returns a new array whose elements are all those from +self+
4299 * for which the block returns +false+ or +nil+:
4300 *
4301 * a = [:foo, 'bar', 2, 'bat']
4302 * a1 = a.reject {|element| element.to_s.start_with?('b') }
4303 * a1 # => [:foo, 2]
4304 *
4305 * With no block given, returns a new Enumerator.
4306 *
4307 * Related: {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
4308 */
4310 static VALUE
4312 {
4313 VALUE rejected_ary;
4319 }
4321 /*
4322 * call-seq:
4323 * delete_if {|element| ... } -> self
4324 * delete_if -> new_numerator
4325 *
4326 * With a block given, calls the block with each element of +self+;
4327 * removes the element if the block returns a truthy value;
4328 * returns +self+:
4329 *
4330 * a = [:foo, 'bar', 2, 'bat']
4331 * a.delete_if {|element| element.to_s.start_with?('b') } # => [:foo, 2]
4332 *
4333 * With no block given, returns a new Enumerator.
4334 *
4335 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
4336 */
4338 static VALUE
4340 {
4345 }
4347 static VALUE
4349 {
4355 }
4357 static VALUE
4359 {
4371 }
4374 /*
4375 * call-seq:
4376 * array.zip(*other_arrays) -> new_array
4377 * array.zip(*other_arrays) {|other_array| ... } -> nil
4378 *
4379 * When no block given, returns a new +Array+ +new_array+ of size <tt>self.size</tt>
4380 * whose elements are Arrays.
4381 *
4382 * Each nested array <tt>new_array[n]</tt> is of size <tt>other_arrays.size+1</tt>,
4383 * and contains:
4384 *
4385 * - The _nth_ element of +self+.
4386 * - The _nth_ element of each of the +other_arrays+.
4387 *
4388 * If all +other_arrays+ and +self+ are the same size:
4389 *
4390 * a = [:a0, :a1, :a2, :a3]
4391 * b = [:b0, :b1, :b2, :b3]
4392 * c = [:c0, :c1, :c2, :c3]
4393 * d = a.zip(b, c)
4394 * d # => [[:a0, :b0, :c0], [:a1, :b1, :c1], [:a2, :b2, :c2], [:a3, :b3, :c3]]
4395 *
4396 * If any array in +other_arrays+ is smaller than +self+,
4397 * fills to <tt>self.size</tt> with +nil+:
4398 *
4399 * a = [:a0, :a1, :a2, :a3]
4400 * b = [:b0, :b1, :b2]
4401 * c = [:c0, :c1]
4402 * d = a.zip(b, c)
4403 * d # => [[:a0, :b0, :c0], [:a1, :b1, :c1], [:a2, :b2, nil], [:a3, nil, nil]]
4404 *
4405 * If any array in +other_arrays+ is larger than +self+,
4406 * its trailing elements are ignored:
4407 *
4408 * a = [:a0, :a1, :a2, :a3]
4409 * b = [:b0, :b1, :b2, :b3, :b4]
4410 * c = [:c0, :c1, :c2, :c3, :c4, :c5]
4411 * d = a.zip(b, c)
4412 * d # => [[:a0, :b0, :c0], [:a1, :b1, :c1], [:a2, :b2, :c2], [:a3, :b3, :c3]]
4413 *
4414 * If an argument is not an array, it extracts the values by calling #each:
4415 *
4416 * a = [:a0, :a1, :a2, :a2]
4417 * b = 1..4
4418 * c = a.zip(b)
4419 * c # => [[:a0, 1], [:a1, 2], [:a2, 3], [:a2, 4]]
4420 *
4421 * When a block is given, calls the block with each of the sub-arrays (formed as above); returns +nil+:
4422 *
4423 * a = [:a0, :a1, :a2, :a3]
4424 * b = [:b0, :b1, :b2, :b3]
4425 * c = [:c0, :c1, :c2, :c3]
4426 * a.zip(b, c) {|sub_array| p sub_array} # => nil
4427 *
4428 * Output:
4429 *
4430 * [:a0, :b0, :c0]
4431 * [:a1, :b1, :c1]
4432 * [:a2, :b2, :c2]
4433 * [:a3, :b3, :c3]
4434 *
4435 */
4437 static VALUE
4439 {
4446 }
4460 }
4462 }
4465 }
4473 }
4475 }
4476 }
4477 }
4487 }
4489 }
4490 }
4493 }
4495 /*
4496 * call-seq:
4497 * transpose -> new_array
4498 *
4499 * Returns a new array that is +self+
4500 * as a {transposed matrix}[https://en.wikipedia.org/wiki/Transpose]:
4501 *
4502 * a = [[:a0, :a1], [:b0, :b1], [:c0, :c1]]
4503 * a.transpose # => [[:a0, :b0, :c0], [:a1, :b1, :c1]]
4504 *
4505 * The elements of +self+ must all be the same size.
4506 *
4507 * Related: see {Methods for Converting}[rdoc-ref:Array@Methods+for+Converting].
4508 */
4510 static VALUE
4512 {
4525 }
4526 }
4530 }
4533 }
4534 }
4536 }
4538 /*
4539 * call-seq:
4540 * initialize_copy(other_array) -> self
4541 * replace(other_array) -> self
4542 *
4543 * Replaces the elements of +self+ with the elements of +other_array+, which must be an
4544 * {array-convertible object}[rdoc-ref:implicit_conversion.rdoc@Array-Convertible+Objects];
4545 * returns +self+:
4546 *
4547 * a = ['a', 'b', 'c'] # => ["a", "b", "c"]
4548 * a.replace(['d', 'e']) # => ["d", "e"]
4549 *
4550 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
4551 */
4553 VALUE
4555 {
4562 /* orig has enough space to embed the contents of orig. */
4567 }
4568 /* orig is embedded but copy does not have enough space to embed the
4569 * contents of orig. */
4579 // No allocation and exception expected that could leave `copy` in a
4580 // bad state from the edits above.
4582 }
4583 /* Otherwise, orig is on heap and copy does not have enough space to embed
4584 * the contents of orig. */
4591 }
4594 }
4596 /*
4597 * call-seq:
4598 * clear -> self
4599 *
4600 * Removes all elements from +self+; returns +self+:
4601 *
4602 * a = [:foo, 'bar', 2]
4603 * a.clear # => []
4604 *
4605 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
4606 */
4608 VALUE
4610 {
4616 }
4621 }
4622 }
4625 }
4627 /*
4628 * call-seq:
4629 * fill(object, start = nil, count = nil) -> new_array
4630 * fill(object, range) -> new_array
4631 * fill(start = nil, count = nil) {|element| ... } -> new_array
4632 * fill(range) {|element| ... } -> new_array
4633 *
4634 * Replaces selected elements in +self+;
4635 * may add elements to +self+;
4636 * always returns +self+ (never a new array).
4637 *
4638 * In brief:
4639 *
4640 * # Non-negative start.
4641 * ['a', 'b', 'c', 'd'].fill('-', 1, 2) # => ["a", "-", "-", "d"]
4642 * ['a', 'b', 'c', 'd'].fill(1, 2) {|e| e.to_s } # => ["a", "1", "2", "d"]
4643 *
4644 * # Extends with specified values if necessary.
4645 * ['a', 'b', 'c', 'd'].fill('-', 3, 2) # => ["a", "b", "c", "-", "-"]
4646 * ['a', 'b', 'c', 'd'].fill(3, 2) {|e| e.to_s } # => ["a", "b", "c", "3", "4"]
4647 *
4648 * # Fills with nils if necessary.
4649 * ['a', 'b', 'c', 'd'].fill('-', 6, 2) # => ["a", "b", "c", "d", nil, nil, "-", "-"]
4650 * ['a', 'b', 'c', 'd'].fill(6, 2) {|e| e.to_s } # => ["a", "b", "c", "d", nil, nil, "6", "7"]
4651 *
4652 * # For negative start, counts backwards from the end.
4653 * ['a', 'b', 'c', 'd'].fill('-', -3, 3) # => ["a", "-", "-", "-"]
4654 * ['a', 'b', 'c', 'd'].fill(-3, 3) {|e| e.to_s } # => ["a", "1", "2", "3"]
4655 *
4656 * # Range.
4657 * ['a', 'b', 'c', 'd'].fill('-', 1..2) # => ["a", "-", "-", "d"]
4658 * ['a', 'b', 'c', 'd'].fill(1..2) {|e| e.to_s } # => ["a", "1", "2", "d"]
4659 *
4660 * When arguments +start+ and +count+ are given,
4661 * they select the elements of +self+ to be replaced;
4662 * each must be an
4663 * {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects]
4664 * (or +nil+):
4665 *
4666 * - +start+ specifies the zero-based offset of the first element to be replaced;
4667 * +nil+ means zero.
4668 * - +count+ is the number of consecutive elements to be replaced;
4669 * +nil+ means "all the rest."
4670 *
4671 * With argument +object+ given,
4672 * that one object is used for all replacements:
4673 *
4674 * o = Object.new # => #<Object:0x0000014e7bff7600>
4675 * a = ['a', 'b', 'c', 'd'] # => ["a", "b", "c", "d"]
4676 * a.fill(o, 1, 2)
4677 * # => ["a", #<Object:0x0000014e7bff7600>, #<Object:0x0000014e7bff7600>, "d"]
4678 *
4679 * With a block given, the block is called once for each element to be replaced;
4680 * the value passed to the block is the _index_ of the element to be replaced
4681 * (not the element itself);
4682 * the block's return value replaces the element:
4683 *
4684 * a = ['a', 'b', 'c', 'd'] # => ["a", "b", "c", "d"]
4685 * a.fill(1, 2) {|element| element.to_s } # => ["a", "1", "2", "d"]
4686 *
4687 * For arguments +start+ and +count+:
4688 *
4689 * - If +start+ is non-negative,
4690 * replaces +count+ elements beginning at offset +start+:
4691 *
4692 * ['a', 'b', 'c', 'd'].fill('-', 0, 2) # => ["-", "-", "c", "d"]
4693 * ['a', 'b', 'c', 'd'].fill('-', 1, 2) # => ["a", "-", "-", "d"]
4694 * ['a', 'b', 'c', 'd'].fill('-', 2, 2) # => ["a", "b", "-", "-"]
4695 *
4696 * ['a', 'b', 'c', 'd'].fill(0, 2) {|e| e.to_s } # => ["0", "1", "c", "d"]
4697 * ['a', 'b', 'c', 'd'].fill(1, 2) {|e| e.to_s } # => ["a", "1", "2", "d"]
4698 * ['a', 'b', 'c', 'd'].fill(2, 2) {|e| e.to_s } # => ["a", "b", "2", "3"]
4699 *
4700 * Extends +self+ if necessary:
4701 *
4702 * ['a', 'b', 'c', 'd'].fill('-', 3, 2) # => ["a", "b", "c", "-", "-"]
4703 * ['a', 'b', 'c', 'd'].fill('-', 4, 2) # => ["a", "b", "c", "d", "-", "-"]
4704 *
4705 * ['a', 'b', 'c', 'd'].fill(3, 2) {|e| e.to_s } # => ["a", "b", "c", "3", "4"]
4706 * ['a', 'b', 'c', 'd'].fill(4, 2) {|e| e.to_s } # => ["a", "b", "c", "d", "4", "5"]
4707 *
4708 * Fills with +nil+ if necessary:
4709 *
4710 * ['a', 'b', 'c', 'd'].fill('-', 5, 2) # => ["a", "b", "c", "d", nil, "-", "-"]
4711 * ['a', 'b', 'c', 'd'].fill('-', 6, 2) # => ["a", "b", "c", "d", nil, nil, "-", "-"]
4712 *
4713 * ['a', 'b', 'c', 'd'].fill(5, 2) {|e| e.to_s } # => ["a", "b", "c", "d", nil, "5", "6"]
4714 * ['a', 'b', 'c', 'd'].fill(6, 2) {|e| e.to_s } # => ["a", "b", "c", "d", nil, nil, "6", "7"]
4715 *
4716 * Does nothing if +count+ is non-positive:
4717 *
4718 * ['a', 'b', 'c', 'd'].fill('-', 2, 0) # => ["a", "b", "c", "d"]
4719 * ['a', 'b', 'c', 'd'].fill('-', 2, -100) # => ["a", "b", "c", "d"]
4720 * ['a', 'b', 'c', 'd'].fill('-', 6, -100) # => ["a", "b", "c", "d"]
4721 *
4722 * ['a', 'b', 'c', 'd'].fill(2, 0) {|e| fail 'Cannot happen' } # => ["a", "b", "c", "d"]
4723 * ['a', 'b', 'c', 'd'].fill(2, -100) {|e| fail 'Cannot happen' } # => ["a", "b", "c", "d"]
4724 * ['a', 'b', 'c', 'd'].fill(6, -100) {|e| fail 'Cannot happen' } # => ["a", "b", "c", "d"]
4725 *
4726 * - If +start+ is negative, counts backwards from the end of +self+:
4727 *
4728 * ['a', 'b', 'c', 'd'].fill('-', -4, 3) # => ["-", "-", "-", "d"]
4729 * ['a', 'b', 'c', 'd'].fill('-', -3, 3) # => ["a", "-", "-", "-"]
4730 *
4731 * ['a', 'b', 'c', 'd'].fill(-4, 3) {|e| e.to_s } # => ["0", "1", "2", "d"]
4732 * ['a', 'b', 'c', 'd'].fill(-3, 3) {|e| e.to_s } # => ["a", "1", "2", "3"]
4733 *
4734 * Extends +self+ if necessary:
4735 *
4736 * ['a', 'b', 'c', 'd'].fill('-', -2, 3) # => ["a", "b", "-", "-", "-"]
4737 * ['a', 'b', 'c', 'd'].fill('-', -1, 3) # => ["a", "b", "c", "-", "-", "-"]
4738 *
4739 * ['a', 'b', 'c', 'd'].fill(-2, 3) {|e| e.to_s } # => ["a", "b", "2", "3", "4"]
4740 * ['a', 'b', 'c', 'd'].fill(-1, 3) {|e| e.to_s } # => ["a", "b", "c", "3", "4", "5"]
4741 *
4742 * Starts at the beginning of +self+ if +start+ is negative and out-of-range:
4743 *
4744 * ['a', 'b', 'c', 'd'].fill('-', -5, 2) # => ["-", "-", "c", "d"]
4745 * ['a', 'b', 'c', 'd'].fill('-', -6, 2) # => ["-", "-", "c", "d"]
4746 *
4747 * ['a', 'b', 'c', 'd'].fill(-5, 2) {|e| e.to_s } # => ["0", "1", "c", "d"]
4748 * ['a', 'b', 'c', 'd'].fill(-6, 2) {|e| e.to_s } # => ["0", "1", "c", "d"]
4749 *
4750 * Does nothing if +count+ is non-positive:
4751 *
4752 * ['a', 'b', 'c', 'd'].fill('-', -2, 0) # => ["a", "b", "c", "d"]
4753 * ['a', 'b', 'c', 'd'].fill('-', -2, -1) # => ["a", "b", "c", "d"]
4754 *
4755 * ['a', 'b', 'c', 'd'].fill(-2, 0) {|e| fail 'Cannot happen' } # => ["a", "b", "c", "d"]
4756 * ['a', 'b', 'c', 'd'].fill(-2, -1) {|e| fail 'Cannot happen' } # => ["a", "b", "c", "d"]
4757 *
4758 * When argument +range+ is given,
4759 * it must be a Range object whose members are numeric;
4760 * its +begin+ and +end+ values determine the elements of +self+
4761 * to be replaced:
4762 *
4763 * - If both +begin+ and +end+ are positive, they specify the first and last elements
4764 * to be replaced:
4765 *
4766 * ['a', 'b', 'c', 'd'].fill('-', 1..2) # => ["a", "-", "-", "d"]
4767 * ['a', 'b', 'c', 'd'].fill(1..2) {|e| e.to_s } # => ["a", "1", "2", "d"]
4768 *
4769 * If +end+ is smaller than +begin+, replaces no elements:
4770 *
4771 * ['a', 'b', 'c', 'd'].fill('-', 2..1) # => ["a", "b", "c", "d"]
4772 * ['a', 'b', 'c', 'd'].fill(2..1) {|e| e.to_s } # => ["a", "b", "c", "d"]
4773 *
4774 * - If either is negative (or both are negative), counts backwards from the end of +self+:
4775 *
4776 * ['a', 'b', 'c', 'd'].fill('-', -3..2) # => ["a", "-", "-", "d"]
4777 * ['a', 'b', 'c', 'd'].fill('-', 1..-2) # => ["a", "-", "-", "d"]
4778 * ['a', 'b', 'c', 'd'].fill('-', -3..-2) # => ["a", "-", "-", "d"]
4779 *
4780 * ['a', 'b', 'c', 'd'].fill(-3..2) {|e| e.to_s } # => ["a", "1", "2", "d"]
4781 * ['a', 'b', 'c', 'd'].fill(1..-2) {|e| e.to_s } # => ["a", "1", "2", "d"]
4782 * ['a', 'b', 'c', 'd'].fill(-3..-2) {|e| e.to_s } # => ["a", "1", "2", "d"]
4783 *
4784 * - If the +end+ value is excluded (see Range#exclude_end?), omits the last replacement:
4785 *
4786 * ['a', 'b', 'c', 'd'].fill('-', 1...2) # => ["a", "-", "c", "d"]
4787 * ['a', 'b', 'c', 'd'].fill('-', 1...-2) # => ["a", "-", "c", "d"]
4788 *
4789 * ['a', 'b', 'c', 'd'].fill(1...2) {|e| e.to_s } # => ["a", "1", "c", "d"]
4790 * ['a', 'b', 'c', 'd'].fill(1...-2) {|e| e.to_s } # => ["a", "1", "c", "d"]
4791 *
4792 * - If the range is endless (see {Endless Ranges}[rdoc-ref:Range@Endless+Ranges]),
4793 * replaces elements to the end of +self+:
4794 *
4795 * ['a', 'b', 'c', 'd'].fill('-', 1..) # => ["a", "-", "-", "-"]
4796 * ['a', 'b', 'c', 'd'].fill(1..) {|e| e.to_s } # => ["a", "1", "2", "3"]
4797 *
4798 * - If the range is beginless (see {Beginless Ranges}[rdoc-ref:Range@Beginless+Ranges]),
4799 * replaces elements from the beginning of +self+:
4800 *
4801 * ['a', 'b', 'c', 'd'].fill('-', ..2) # => ["-", "-", "-", "d"]
4802 * ['a', 'b', 'c', 'd'].fill(..2) {|e| e.to_s } # => ["0", "1", "2", "d"]
4803 *
4804 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
4805 */
4807 static VALUE
4809 {
4816 }
4819 }
4828 }
4829 /* fall through */
4835 }
4838 }
4842 }
4845 }
4850 }
4853 }
4856 VALUE v;
4863 }
4864 }
4867 }
4869 }
4871 /*
4872 * call-seq:
4873 * self + other_array -> new_array
4874 *
4875 * Returns a new array containing all elements of +self+
4876 * followed by all elements of +other_array+:
4877 *
4878 * a = [0, 1] + [2, 3]
4879 * a # => [0, 1, 2, 3]
4880 *
4881 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
4882 */
4884 VALUE
4886 {
4887 VALUE z;
4900 }
4902 static VALUE
4904 {
4908 }
4911 }
4913 /*
4914 * call-seq:
4915 * concat(*other_arrays) -> self
4916 *
4917 * Adds to +self+ all elements from each array in +other_arrays+; returns +self+:
4918 *
4919 * a = [0, 1]
4920 * a.concat(['two', 'three'], [:four, :five], a)
4921 * # => [0, 1, "two", "three", :four, :five, 0, 1]
4922 *
4923 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
4924 */
4926 static VALUE
4928 {
4933 }
4939 }
4941 }
4945 }
4947 VALUE
4949 {
4951 }
4953 /*
4954 * call-seq:
4955 * self * n -> new_array
4956 * self * string_separator -> new_string
4957 *
4958 * When non-negative integer argument +n+ is given,
4959 * returns a new array built by concatenating +n+ copies of +self+:
4960 *
4961 * a = ['x', 'y']
4962 * a * 3 # => ["x", "y", "x", "y", "x", "y"]
4963 *
4964 * When string argument +string_separator+ is given,
4965 * equivalent to <tt>self.join(string_separator)</tt>:
4966 *
4967 * [0, [0, 1], {foo: 0}] * ', ' # => "0, 0, 1, {:foo=>0}"
4968 *
4969 */
4971 static VALUE
4973 {
4981 }
4987 }
4990 }
4993 }
5006 }
5009 }
5010 }
5011 out:
5013 }
5015 /*
5016 * call-seq:
5017 * assoc(object) -> found_array or nil
5018 *
5019 * Returns the first element +ele+ in +self+ such that +ele+ is an array
5020 * and <tt>ele[0] == object</tt>:
5021 *
5022 * a = [{foo: 0}, [2, 4], [4, 5, 6], [4, 5]]
5023 * a.assoc(4) # => [4, 5, 6]
5024 *
5025 * Returns +nil+ if no such element is found.
5026 *
5027 * Related: Array#rassoc;
5028 * see also {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
5029 */
5031 VALUE
5033 {
5035 VALUE v;
5042 }
5044 }
5046 /*
5047 * call-seq:
5048 * rassoc(object) -> found_array or nil
5049 *
5050 * Returns the first element +ele+ in +self+ such that +ele+ is an array
5051 * and <tt>ele[1] == object</tt>:
5052 *
5053 * a = [{foo: 0}, [2, 4], [4, 5, 6], [4, 5]]
5054 * a.rassoc(4) # => [2, 4]
5055 * a.rassoc(5) # => [4, 5, 6]
5056 *
5057 * Returns +nil+ if no such element is found.
5058 *
5059 * Related: Array#assoc;
5060 * see also {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
5061 */
5063 VALUE
5065 {
5067 VALUE v;
5075 }
5077 }
5079 static VALUE
5081 {
5087 /* rb_equal() can evacuate ptrs */
5102 }
5105 }
5106 }
5107 p1++;
5108 p2++;
5109 }
5111 }
5113 /*
5114 * call-seq:
5115 * self == other_array -> true or false
5116 *
5117 * Returns whether both:
5118 *
5119 * - +self+ and +other_array+ are the same size.
5120 * - Their corresponding elements are the same;
5121 * that is, for each index +i+ in <tt>(0...self.size)</tt>,
5122 * <tt>self[i] == other_array[i]</tt>.
5123 *
5124 * Examples:
5125 *
5126 * [:foo, 'bar', 2] == [:foo, 'bar', 2] # => true
5127 * [:foo, 'bar', 2] == [:foo, 'bar', 2.0] # => true
5128 * [:foo, 'bar', 2] == [:foo, 'bar'] # => false # Different sizes.
5129 * [:foo, 'bar', 2] == [:foo, 'bar', 3] # => false # Different elements.
5130 *
5131 * This method is different from method Array#eql?,
5132 * which compares elements using <tt>Object#eql?</tt>.
5133 *
5134 * Related: see {Methods for Comparing}[rdoc-ref:Array@Methods+for+Comparing].
5135 */
5137 static VALUE
5139 {
5144 }
5146 }
5150 }
5152 static VALUE
5154 {
5161 }
5163 }
5165 /*
5166 * call-seq:
5167 * eql?(other_array) -> true or false
5168 *
5169 * Returns +true+ if +self+ and +other_array+ are the same size,
5170 * and if, for each index +i+ in +self+, <tt>self[i].eql?(other_array[i])</tt>:
5171 *
5172 * a0 = [:foo, 'bar', 2]
5173 * a1 = [:foo, 'bar', 2]
5174 * a1.eql?(a0) # => true
5175 *
5176 * Otherwise, returns +false+.
5177 *
5178 * This method is different from method Array#==,
5179 * which compares using method <tt>Object#==</tt>.
5180 *
5181 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
5182 */
5184 static VALUE
5186 {
5192 }
5194 VALUE
5196 {
5198 st_index_t h;
5199 VALUE n;
5206 }
5209 }
5211 /*
5212 * call-seq:
5213 * hash -> integer
5214 *
5215 * Returns the integer hash value for +self+.
5216 *
5217 * Two arrays with the same content will have the same hash value
5218 * (and will compare using eql?):
5219 *
5220 * ['a', 'b'].hash == ['a', 'b'].hash # => true
5221 * ['a', 'b'].hash == ['a', 'c'].hash # => false
5222 * ['a', 'b'].hash == ['a'].hash # => false
5223 *
5224 */
5226 static VALUE
5228 {
5230 }
5232 /*
5233 * call-seq:
5234 * include?(object) -> true or false
5235 *
5236 * Returns whether for some element +element+ in +self+,
5237 * <tt>object == element</tt>:
5238 *
5239 * [0, 1, 2].include?(2) # => true
5240 * [0, 1, 2].include?(2.0) # => true
5241 * [0, 1, 2].include?(2.1) # => false
5242 *
5243 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
5244 */
5246 VALUE
5248 {
5250 VALUE e;
5256 }
5257 }
5259 }
5261 static VALUE
5263 {
5265 VALUE e;
5271 }
5272 }
5274 }
5276 static VALUE
5278 {
5285 }
5291 }
5292 }
5294 }
5296 /*
5297 * call-seq:
5298 * self <=> other_array -> -1, 0, or 1
5299 *
5300 * Returns -1, 0, or 1 as +self+ is determined
5301 * to be less than, equal to, or greater than +other_array+.
5302 *
5303 * Iterates over each index +i+ in <tt>(0...self.size)</tt>:
5304 *
5305 * - Computes <tt>result[i]</tt> as <tt>self[i] <=> other_array[i]</tt>.
5306 * - Immediately returns 1 if <tt>result[i]</tt> is 1:
5307 *
5308 * [0, 1, 2] <=> [0, 0, 2] # => 1
5309 *
5310 * - Immediately returns -1 if <tt>result[i]</tt> is -1:
5311 *
5312 * [0, 1, 2] <=> [0, 2, 2] # => -1
5313 *
5314 * - Continues if <tt>result[i]</tt> is 0.
5315 *
5316 * When every +result+ is 0,
5317 * returns <tt>self.size <=> other_array.size</tt>
5318 * (see Integer#<=>):
5319 *
5320 * [0, 1, 2] <=> [0, 1] # => 1
5321 * [0, 1, 2] <=> [0, 1, 2] # => 0
5322 * [0, 1, 2] <=> [0, 1, 2, 3] # => -1
5323 *
5324 * Note that when +other_array+ is larger than +self+,
5325 * its trailing elements do not affect the result:
5326 *
5327 * [0, 1, 2] <=> [0, 1, 2, -3] # => -1
5328 * [0, 1, 2] <=> [0, 1, 2, 0] # => -1
5329 * [0, 1, 2] <=> [0, 1, 2, 3] # => -1
5330 *
5331 * Related: see {Methods for Comparing}[rdoc-ref:Array@Methods+for+Comparing].
5332 */
5334 VALUE
5336 {
5338 VALUE v;
5349 }
5351 static VALUE
5353 {
5359 }
5361 }
5365 {
5371 }
5373 static VALUE
5375 {
5378 }
5380 static VALUE
5382 {
5388 }
5390 }
5392 static VALUE
5394 {
5397 }
5399 /*
5400 * call-seq:
5401 * self - other_array -> new_array
5402 *
5403 * Returns a new array containing only those elements of +self+
5404 * that are not found in +other_array+;
5405 * the order from +self+ is preserved:
5406 *
5407 * [0, 1, 1, 2, 1, 1, 3, 1, 1] - [1] # => [0, 2, 3]
5408 * [0, 1, 1, 2, 1, 1, 3, 1, 1] - [3, 2, 0, :foo] # => [1, 1, 1, 1, 1, 1]
5409 * [0, 1, 2] - [:foo] # => [0, 1, 2]
5410 *
5411 * Element are compared using method <tt>#eql?</tt>
5412 * (as defined in each element of +self+).
5413 *
5414 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
5415 */
5417 VALUE
5419 {
5420 VALUE ary3;
5421 VALUE hash;
5433 }
5435 }
5441 }
5444 }
5446 /*
5447 * call-seq:
5448 * difference(*other_arrays = []) -> new_array
5449 *
5450 * Returns a new array containing only those elements from +self+
5451 * that are not found in any of the given +other_arrays+;
5452 * items are compared using <tt>eql?</tt>; order from +self+ is preserved:
5453 *
5454 * [0, 1, 1, 2, 1, 1, 3, 1, 1].difference([1]) # => [0, 2, 3]
5455 * [0, 1, 2, 3].difference([3, 0], [1, 3]) # => [2]
5456 * [0, 1, 2].difference([4]) # => [0, 1, 2]
5457 * [0, 1, 2].difference # => [0, 1, 2]
5458 *
5459 * Returns a copy of +self+ if no arguments are given.
5460 *
5461 * Related: Array#-;
5462 * see also {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
5463 */
5465 static VALUE
5467 {
5468 VALUE ary_diff;
5479 }
5488 }
5491 }
5492 }
5494 }
5499 }
5502 /*
5503 * call-seq:
5504 * self & other_array -> new_array
5505 *
5506 * Returns a new array containing the _intersection_ of +self+ and +other_array+;
5507 * that is, containing those elements found in both +self+ and +other_array+:
5508 *
5509 * [0, 1, 2, 3] & [1, 2] # => [1, 2]
5510 *
5511 * Omits duplicates:
5512 *
5513 * [0, 1, 1, 0] & [0, 1] # => [0, 1]
5514 *
5515 * Preserves order from +self+:
5516 *
5517 * [0, 1, 2] & [3, 2, 1, 0] # => [0, 1, 2]
5518 *
5519 * Identifies common elements using method <tt>#eql?</tt>
5520 * (as defined in each element of +self+).
5521 *
5522 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
5523 */
5526 static VALUE
5528 {
5530 st_data_t vv;
5543 }
5545 }
5554 }
5555 }
5558 }
5560 /*
5561 * call-seq:
5562 * intersection(*other_arrays) -> new_array
5563 *
5564 * Returns a new array containing each element in +self+ that is +#eql?+
5565 * to at least one element in each of the given +other_arrays+;
5566 * duplicates are omitted:
5567 *
5568 * [0, 0, 1, 1, 2, 3].intersection([0, 1, 2], [0, 1, 3]) # => [0, 1]
5569 *
5570 * Each element must correctly implement method <tt>#hash</tt>.
5571 *
5572 * Order from +self+ is preserved:
5573 *
5574 * [0, 1, 2].intersection([2, 1, 0]) # => [0, 1, 2]
5575 *
5576 * Returns a copy of +self+ if no arguments are given.
5577 *
5578 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
5579 */
5581 static VALUE
5583 {
5589 }
5592 }
5594 static int
5596 {
5600 }
5602 static void
5604 {
5610 }
5611 }
5613 static void
5615 {
5621 }
5622 }
5623 }
5625 /*
5626 * call-seq:
5627 * array | other_array -> new_array
5628 *
5629 * Returns the union of +array+ and +Array+ +other_array+;
5630 * duplicates are removed; order is preserved;
5631 * items are compared using <tt>eql?</tt>:
5632 *
5633 * [0, 1] | [2, 3] # => [0, 1, 2, 3]
5634 * [0, 1, 1] | [2, 2, 3] # => [0, 1, 2, 3]
5635 * [0, 1, 2] | [3, 2, 1, 0] # => [0, 1, 2, 3]
5636 *
5637 * Related: Array#union.
5638 */
5640 static VALUE
5642 {
5643 VALUE hash;
5651 }
5657 }
5659 /*
5660 * call-seq:
5661 * union(*other_arrays) -> new_array
5662 *
5663 * Returns a new array that is the union of the elements of +self+
5664 * and all given arrays +other_arrays+;
5665 * items are compared using <tt>eql?</tt>:
5666 *
5667 * [0, 1, 2, 3].union([4, 5], [6, 7]) # => [0, 1, 2, 3, 4, 5, 6, 7]
5668 *
5669 * Removes duplicates (preserving the first found):
5670 *
5671 * [0, 1, 1].union([2, 1], [3, 1]) # => [0, 1, 2, 3]
5672 *
5673 * Preserves order (preserving the position of the first found):
5674 *
5675 * [3, 2, 1, 0].union([5, 3], [4, 2]) # => [3, 2, 1, 0, 5, 4]
5676 *
5677 * With no arguments given, returns a copy of +self+.
5678 *
5679 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
5680 */
5682 static VALUE
5684 {
5687 VALUE hash;
5693 }
5702 }
5708 }
5710 /*
5711 * call-seq:
5712 * intersect?(other_array) -> true or false
5713 *
5714 * Returns whether +other_array+ has at least one element that is +#eql?+ to some element of +self+:
5715 *
5716 * [1, 2, 3].intersect?([3, 4, 5]) # => true
5717 * [1, 2, 3].intersect?([4, 5, 6]) # => false
5718 *
5719 * Each element must correctly implement method <tt>#hash</tt>.
5720 *
5721 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
5722 */
5724 static VALUE
5726 {
5728 st_data_t vv;
5738 }
5740 }
5747 }
5758 }
5759 }
5762 }
5764 static VALUE
5766 {
5769 VALUE v;
5775 }
5776 }
5779 }
5781 static VALUE
5783 {
5788 VALUE v;
5795 }
5796 }
5799 }
5800 }
5803 }
5805 static VALUE
5807 {
5812 VALUE v;
5819 }
5820 }
5823 }
5824 }
5827 }
5829 static VALUE
5831 {
5836 VALUE v;
5843 }
5844 }
5847 }
5848 }
5851 }
5853 /*
5854 * call-seq:
5855 * max -> element
5856 * max(n) -> new_array
5857 * max {|a, b| ... } -> element
5858 * max(n) {|a, b| ... } -> new_array
5859 *
5860 * Returns one of the following:
5861 *
5862 * - The maximum-valued element from +self+.
5863 * - A new array of maximum-valued elements from +self+.
5864 *
5865 * Does not modify +self+.
5866 *
5867 * With no block given, each element in +self+ must respond to method <tt>#<=></tt>
5868 * with a numeric.
5869 *
5870 * With no argument and no block, returns the element in +self+
5871 * having the maximum value per method <tt>#<=></tt>:
5872 *
5873 * [1, 0, 3, 2].max # => 3
5874 *
5875 * With non-negative numeric argument +n+ and no block,
5876 * returns a new array with at most +n+ elements,
5877 * in descending order, per method <tt>#<=></tt>:
5878 *
5879 * [1, 0, 3, 2].max(3) # => [3, 2, 1]
5880 * [1, 0, 3, 2].max(3.0) # => [3, 2, 1]
5881 * [1, 0, 3, 2].max(9) # => [3, 2, 1, 0]
5882 * [1, 0, 3, 2].max(0) # => []
5883 *
5884 * With a block given, the block must return a numeric.
5885 *
5886 * With a block and no argument, calls the block <tt>self.size - 1</tt> times to compare elements;
5887 * returns the element having the maximum value per the block:
5888 *
5889 * ['0', '', '000', '00'].max {|a, b| a.size <=> b.size }
5890 * # => "000"
5891 *
5892 * With non-negative numeric argument +n+ and a block,
5893 * returns a new array with at most +n+ elements,
5894 * in descending order, per the block:
5895 *
5896 * ['0', '', '000', '00'].max(2) {|a, b| a.size <=> b.size }
5897 * # => ["000", "00"]
5898 *
5899 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
5900 */
5901 static VALUE
5903 {
5905 VALUE num;
5917 }
5918 }
5919 }
5925 }
5928 }
5931 }
5934 }
5935 }
5936 }
5939 }
5941 static VALUE
5943 {
5946 VALUE v;
5952 }
5953 }
5956 }
5958 static VALUE
5960 {
5965 VALUE a;
5972 }
5973 }
5976 }
5977 }
5980 }
5982 static VALUE
5984 {
5989 VALUE a;
5996 }
5997 }
6000 }
6001 }
6004 }
6006 static VALUE
6008 {
6013 VALUE a;
6020 }
6021 }
6024 }
6025 }
6028 }
6030 /*
6031 * call-seq:
6032 * min -> element
6033 * min(n) -> new_array
6034 * min {|a, b| ... } -> element
6035 * min(n) {|a, b| ... } -> new_array
6036 *
6037 * Returns one of the following:
6038 *
6039 * - The minimum-valued element from +self+.
6040 * - A new array of minimum-valued elements from +self+.
6041 *
6042 * Does not modify +self+.
6043 *
6044 * With no block given, each element in +self+ must respond to method <tt>#<=></tt>
6045 * with a numeric.
6046 *
6047 * With no argument and no block, returns the element in +self+
6048 * having the minimum value per method <tt>#<=></tt>:
6049 *
6050 * [1, 0, 3, 2].min # => 0
6051 *
6052 * With non-negative numeric argument +n+ and no block,
6053 * returns a new array with at most +n+ elements,
6054 * in ascending order, per method <tt>#<=></tt>:
6055 *
6056 * [1, 0, 3, 2].min(3) # => [0, 1, 2]
6057 * [1, 0, 3, 2].min(3.0) # => [0, 1, 2]
6058 * [1, 0, 3, 2].min(9) # => [0, 1, 2, 3]
6059 * [1, 0, 3, 2].min(0) # => []
6060 *
6061 * With a block given, the block must return a numeric.
6062 *
6063 * With a block and no argument, calls the block <tt>self.size - 1</tt> times to compare elements;
6064 * returns the element having the minimum value per the block:
6065 *
6066 * ['0', '', '000', '00'].min {|a, b| a.size <=> b.size }
6067 * # => ""
6068 *
6069 * With non-negative numeric argument +n+ and a block,
6070 * returns a new array with at most +n+ elements,
6071 * in ascending order, per the block:
6072 *
6073 * ['0', '', '000', '00'].min(2) {|a, b| a.size <=> b.size }
6074 * # => ["", "0"]
6075 *
6076 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
6077 */
6078 static VALUE
6080 {
6082 VALUE num;
6094 }
6095 }
6096 }
6102 }
6105 }
6108 }
6111 }
6112 }
6113 }
6116 }
6118 /*
6119 * call-seq:
6120 * minmax -> array
6121 * minmax {|a, b| ... } -> array
6122 *
6123 * Returns a 2-element array containing the minimum-valued and maximum-valued
6124 * elements from +self+;
6125 * does not modify +self+.
6126 *
6127 * With no block given, the minimum and maximum values are determined using method <tt>#<=></tt>:
6128 *
6129 * [1, 0, 3, 2].minmax # => [0, 3]
6130 *
6131 * With a block given, the block must return a numeric;
6132 * the block is called <tt>self.size - 1</tt> times to compare elements;
6133 * returns the elements having the minimum and maximum values per the block:
6134 *
6135 * ['0', '', '000', '00'].minmax {|a, b| a.size <=> b.size }
6136 * # => ["", "000"]
6137 *
6138 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
6139 */
6140 static VALUE
6142 {
6145 }
6147 }
6149 static int
6151 {
6154 }
6156 /*
6157 * call-seq:
6158 * array.uniq! -> self or nil
6159 * array.uniq! {|element| ... } -> self or nil
6160 *
6161 * Removes duplicate elements from +self+, the first occurrence always being retained;
6162 * returns +self+ if any elements removed, +nil+ otherwise.
6163 *
6164 * With no block given, identifies and removes elements using method <tt>eql?</tt>
6165 * to compare.
6166 *
6167 * Returns +self+ if any elements removed:
6168 *
6169 * a = [0, 0, 1, 1, 2, 2]
6170 * a.uniq! # => [0, 1, 2]
6171 *
6172 * Returns +nil+ if no elements removed.
6173 *
6174 * With a block given, calls the block for each element;
6175 * identifies (using method <tt>eql?</tt>) and removes
6176 * elements for which the block returns duplicate values.
6177 *
6178 * Returns +self+ if any elements removed:
6179 *
6180 * a = ['a', 'aa', 'aaa', 'b', 'bb', 'bbb']
6181 * a.uniq! {|element| element.size } # => ['a', 'aa', 'aaa']
6182 *
6183 * Returns +nil+ if no elements removed.
6184 */
6185 static VALUE
6187 {
6188 VALUE hash;
6196 else
6202 }
6208 }
6213 }
6215 /*
6216 * call-seq:
6217 * array.uniq -> new_array
6218 * array.uniq {|element| ... } -> new_array
6219 *
6220 * Returns a new +Array+ containing those elements from +self+ that are not duplicates,
6221 * the first occurrence always being retained.
6222 *
6223 * With no block given, identifies and omits duplicates using method <tt>eql?</tt>
6224 * to compare:
6225 *
6226 * a = [0, 0, 1, 1, 2, 2]
6227 * a.uniq # => [0, 1, 2]
6228 *
6229 * With a block given, calls the block for each element;
6230 * identifies (using method <tt>eql?</tt>) and omits duplicate values,
6231 * that is, those elements for which the block returns the same value:
6232 *
6233 * a = ['a', 'aa', 'aaa', 'b', 'bb', 'bbb']
6234 * a.uniq {|element| element.size } # => ["a", "aa", "aaa"]
6235 *
6236 */
6238 static VALUE
6240 {
6246 }
6250 }
6254 }
6257 }
6259 /*
6260 * call-seq:
6261 * compact! -> self or nil
6262 *
6263 * Removes all +nil+ elements from +self+;
6264 * Returns +self+ if any elements are removed, +nil+ otherwise:
6265 *
6266 * a = [nil, 0, nil, false, nil, '', nil, [], nil, {}]
6267 * a.compact! # => [0, false, "", [], {}]
6268 * a # => [0, false, "", [], {}]
6269 * a.compact! # => nil
6270 *
6271 * Related: Array#compact;
6272 * see also {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
6273 */
6275 static VALUE
6277 {
6288 }
6292 }
6296 }
6298 /*
6299 * call-seq:
6300 * compact -> new_array
6301 *
6302 * Returns a new array containing only the non-+nil+ elements from +self+;
6303 * element order is preserved:
6304 *
6305 * a = [nil, 0, nil, false, nil, '', nil, [], nil, {}]
6306 * a.compact # => [0, false, "", [], {}]
6307 *
6308 * Related: Array#compact!;
6309 * see also {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
6310 */
6312 static VALUE
6314 {
6318 }
6320 /*
6321 * call-seq:
6322 * count -> integer
6323 * count(object) -> integer
6324 * count {|element| ... } -> integer
6325 *
6326 * Returns a count of specified elements.
6327 *
6328 * With no argument and no block, returns the count of all elements:
6329 *
6330 * [0, :one, 'two', 3, 3.0].count # => 5
6331 *
6332 * With argument +object+ given, returns the count of elements <tt>==</tt> to +object+:
6333 *
6334 * [0, :one, 'two', 3, 3.0].count(3) # => 2
6335 *
6336 * With no argument and a block given, calls the block with each element;
6337 * returns the count of elements for which the block returns a truthy value:
6338 *
6339 * [0, 1, 2, 3].count {|element| element > 1 } # => 2
6340 *
6341 * With argument +object+ and a block given, issues a warning, ignores the block,
6342 * and returns the count of elements <tt>==</tt> to +object+.
6343 *
6344 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
6345 */
6347 static VALUE
6349 {
6353 VALUE v;
6361 }
6362 }
6368 }
6371 }
6372 }
6375 }
6377 static VALUE
6379 {
6389 }
6390 }
6393 }
6407 }
6418 }
6423 }
6425 }
6428 }
6434 }
6436 }
6441 }
6442 }
6445 }
6448 }
6452 }
6456 }
6460 }
6462 /*
6463 * call-seq:
6464 * flatten!(depth = nil) -> self or nil
6465 *
6466 * Returns +self+ as a recursively flattening of +self+ to +depth+ levels of recursion;
6467 * +depth+ must be an
6468 * {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects],
6469 * or +nil+.
6470 * At each level of recursion:
6471 *
6472 * - Each element that is an array is "flattened"
6473 * (that is, replaced by its individual array elements).
6474 * - Each element that is not an array is unchanged
6475 * (even if the element is an object that has instance method +flatten+).
6476 *
6477 * Returns +nil+ if no elements were flattened.
6478 *
6479 * With non-negative integer argument +depth+, flattens recursively through +depth+ levels:
6480 *
6481 * a = [ 0, [ 1, [2, 3], 4 ], 5, {foo: 0}, Set.new([6, 7]) ]
6482 * a # => [0, [1, [2, 3], 4], 5, {:foo=>0}, #<Set: {6, 7}>]
6483 * a.dup.flatten!(1) # => [0, 1, [2, 3], 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6484 * a.dup.flatten!(1.1) # => [0, 1, [2, 3], 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6485 * a.dup.flatten!(2) # => [0, 1, 2, 3, 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6486 * a.dup.flatten!(3) # => [0, 1, 2, 3, 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6487 *
6488 * With +nil+ or negative argument +depth+, flattens all levels:
6489 *
6490 * a.dup.flatten! # => [0, 1, 2, 3, 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6491 * a.dup.flatten!(-1) # => [0, 1, 2, 3, 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6492 *
6493 * Related: Array#flatten;
6494 * see also {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
6495 */
6497 static VALUE
6499 {
6511 }
6517 }
6519 /*
6520 * call-seq:
6521 * flatten(depth = nil) -> new_array
6522 *
6523 * Returns a new array that is a recursive flattening of +self+
6524 * to +depth+ levels of recursion;
6525 * +depth+ must be an
6526 * {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects]
6527 * or +nil+.
6528 * At each level of recursion:
6529 *
6530 * - Each element that is an array is "flattened"
6531 * (that is, replaced by its individual array elements).
6532 * - Each element that is not an array is unchanged
6533 * (even if the element is an object that has instance method +flatten+).
6534 *
6535 * With non-negative integer argument +depth+, flattens recursively through +depth+ levels:
6536 *
6537 * a = [ 0, [ 1, [2, 3], 4 ], 5, {foo: 0}, Set.new([6, 7]) ]
6538 * a # => [0, [1, [2, 3], 4], 5, {:foo=>0}, #<Set: {6, 7}>]
6539 * a.flatten(0) # => [0, [1, [2, 3], 4], 5, {:foo=>0}, #<Set: {6, 7}>]
6540 * a.flatten(1 ) # => [0, 1, [2, 3], 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6541 * a.flatten(1.1) # => [0, 1, [2, 3], 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6542 * a.flatten(2) # => [0, 1, 2, 3, 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6543 * a.flatten(3) # => [0, 1, 2, 3, 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6544 *
6545 * With +nil+ or negative +depth+, flattens all levels.
6546 *
6547 * a.flatten # => [0, 1, 2, 3, 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6548 * a.flatten(-1) # => [0, 1, 2, 3, 4, 5, {:foo=>0}, #<Set: {6, 7}>]
6549 *
6550 * Related: Array#flatten!;
6551 * see also {Methods for Converting}[rdoc-ref:Array@Methods+for+Converting].
6552 */
6554 static VALUE
6556 {
6558 VALUE result;
6563 }
6568 }
6571 }
6573 #define RAND_UPTO(max) (long)rb_random_ulong_limited((randgen), (max)-1)
6575 static VALUE
6577 {
6585 VALUE tmp;
6588 }
6592 }
6595 }
6597 static VALUE
6599 {
6603 }
6609 },
6611 };
6613 static VALUE
6615 {
6616 VALUE result;
6625 else
6629 }
6636 }
6637 }
6643 }
6644 }
6661 {
6665 }
6667 }
6668 memo_threshold =
6681 }
6684 }
6689 }
6690 });
6691 }
6703 }
6711 st_data_t value;
6716 }
6717 });
6718 });
6722 }
6733 }
6734 });
6736 }
6740 }
6742 static VALUE
6744 {
6746 }
6748 static VALUE
6750 {
6755 }
6762 }
6764 /*
6765 * call-seq:
6766 * cycle(count = nil) {|element| ... } -> nil
6767 * cycle(count = nil) -> new_enumerator
6768 *
6769 * With a block given, may call the block, depending on the value of argument +count+;
6770 * +count+ must be an
6771 * {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects],
6772 * or +nil+.
6773 *
6774 * When +count+ is positive,
6775 * calls the block with each element, then does so repeatedly,
6776 * until it has done so +count+ times; returns +nil+:
6777 *
6778 * output = []
6779 * [0, 1].cycle(2) {|element| output.push(element) } # => nil
6780 * output # => [0, 1, 0, 1]
6781 *
6782 * When +count+ is zero or negative, does not call the block:
6783 *
6784 * [0, 1].cycle(0) {|element| fail 'Cannot happen' } # => nil
6785 * [0, 1].cycle(-1) {|element| fail 'Cannot happen' } # => nil
6786 *
6787 * When +count+ is +nil+, cycles forever:
6788 *
6789 * # Prints 0 and 1 forever.
6790 * [0, 1].cycle {|element| puts element }
6791 * [0, 1].cycle(nil) {|element| puts element }
6792 *
6793 * With no block given, returns a new Enumerator.
6794 *
6795 * Related: see {Methods for Iterating}[rdoc-ref:Array@Methods+for+Iterating].
6796 */
6797 static VALUE
6799 {
6807 }
6811 }
6816 }
6817 }
6819 }
6821 /*
6822 * Build a ruby array of the corresponding values and yield it to the
6823 * associated block.
6824 * Return the class of +values+ for reentry check.
6825 */
6826 static int
6828 {
6836 }
6838 /*
6839 * Compute permutations of +r+ elements of the set <code>[0..n-1]</code>.
6840 *
6841 * When we have a complete permutation of array indices, copy the values
6842 * at those indices into a new array and yield that array.
6843 *
6844 * n: the size of the set
6845 * r: the number of elements in each permutation
6846 * p: the array (of size r) that we're filling in
6847 * used: an array of booleans: whether a given index is already used
6848 * values: the Ruby array that holds the actual values to permute
6849 */
6850 static void
6852 {
6861 }
6870 }
6876 }
6877 }
6881 }
6882 }
6883 }
6885 /*
6886 * Returns the product of from, from-1, ..., from - how_many + 1.
6887 * https://en.wikipedia.org/wiki/Pochhammer_symbol
6888 */
6889 static VALUE
6891 {
6892 VALUE cnt;
6898 }
6899 }
6902 }
6904 }
6906 static VALUE
6908 {
6909 VALUE r;
6913 }
6916 }
6919 }
6924 }
6926 }
6928 static VALUE
6930 {
6935 }
6937 /*
6938 * call-seq:
6939 * permutation(n = self.size) {|permutation| ... } -> self
6940 * permutation(n = self.size) -> new_enumerator
6941 *
6942 * Iterates over permutations of the elements of +self+;
6943 * the order of permutations is indeterminate.
6944 *
6945 * With a block and an in-range positive integer argument +n+ (<tt>0 < n <= self.size</tt>) given,
6946 * calls the block with each +n+-tuple permutations of +self+;
6947 * returns +self+:
6948 *
6949 * a = [0, 1, 2]
6950 * perms = []
6951 * a.permutation(1) {|perm| perms.push(perm) }
6952 * perms # => [[0], [1], [2]]
6953 *
6954 * perms = []
6955 * a.permutation(2) {|perm| perms.push(perm) }
6956 * perms # => [[0, 1], [0, 2], [1, 0], [1, 2], [2, 0], [2, 1]]
6957 *
6958 * perms = []
6959 * a.permutation(3) {|perm| perms.push(perm) }
6960 * perms # => [[0, 1, 2], [0, 2, 1], [1, 0, 2], [1, 2, 0], [2, 0, 1], [2, 1, 0]]
6961 *
6962 * When +n+ is zero, calls the block once with a new empty array:
6963 *
6964 * perms = []
6965 * a.permutation(0) {|perm| perms.push(perm) }
6966 * perms # => [[]]
6967 *
6968 * When +n+ is out of range (negative or larger than <tt>self.size</tt>),
6969 * does not call the block:
6970 *
6971 * a.permutation(-1) {|permutation| fail 'Cannot happen' }
6972 * a.permutation(4) {|permutation| fail 'Cannot happen' }
6973 *
6974 * With no block given, returns a new Enumerator.
6975 *
6976 * Related: {Methods for Iterating}[rdoc-ref:Array@Methods+for+Iterating].
6977 */
6979 static VALUE
6981 {
6985 RETURN_SIZED_ENUMERATOR(ary, argc, argv, rb_ary_permutation_size); /* Return enumerator if no block */
6991 /* no permutations: yield nothing */
6992 }
6995 }
6999 }
7000 }
7013 }
7015 }
7017 static void
7019 {
7027 }
7030 }
7035 }
7036 }
7038 static VALUE
7040 {
7045 }
7047 /*
7048 * call-seq:
7049 * combination(n) {|element| ... } -> self
7050 * combination(n) -> new_enumerator
7051 *
7052 * When a block and a positive
7053 * {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects]
7054 * argument +n+ (<tt>0 < n <= self.size</tt>)
7055 * are given, calls the block with all +n+-tuple combinations of +self+;
7056 * returns +self+:
7057 *
7058 * a = %w[a b c] # => ["a", "b", "c"]
7059 * a.combination(2) {|combination| p combination } # => ["a", "b", "c"]
7060 *
7061 * Output:
7062 *
7063 * ["a", "b"]
7064 * ["a", "c"]
7065 * ["b", "c"]
7066 *
7067 * The order of the yielded combinations is not guaranteed.
7068 *
7069 * When +n+ is zero, calls the block once with a new empty array:
7070 *
7071 * a.combination(0) {|combination| p combination }
7072 * [].combination(0) {|combination| p combination }
7073 *
7074 * Output:
7075 *
7076 * []
7077 * []
7078 *
7079 * When +n+ is negative or larger than +self.size+ and +self+ is non-empty,
7080 * does not call the block:
7081 *
7082 * a.combination(-1) {|combination| fail 'Cannot happen' } # => ["a", "b", "c"]
7083 * a.combination(4) {|combination| fail 'Cannot happen' } # => ["a", "b", "c"]
7084 *
7085 * With no block given, returns a new Enumerator.
7086 *
7087 * Related: Array#permutation;
7088 * see also {Methods for Iterating}[rdoc-ref:Array@Methods+for+Iterating].
7089 */
7091 static VALUE
7093 {
7100 /* yield nothing */
7101 }
7104 }
7108 }
7109 }
7119 }
7121 }
7123 /*
7124 * Compute repeated permutations of +r+ elements of the set
7125 * <code>[0..n-1]</code>.
7126 *
7127 * When we have a complete repeated permutation of array indices, copy the
7128 * values at those indices into a new array and yield that array.
7129 *
7130 * n: the size of the set
7131 * r: the number of elements in each permutation
7132 * p: the array (of size r) that we're filling in
7133 * values: the Ruby array that holds the actual values to permute
7134 */
7135 static void
7137 {
7145 }
7150 }
7151 }
7155 }
7156 }
7158 static VALUE
7160 {
7166 }
7169 }
7171 }
7173 /*
7174 * call-seq:
7175 * repeated_permutation(size) {|permutation| ... } -> self
7176 * repeated_permutation(size) -> new_enumerator
7177 *
7178 * With a block given, calls the block with each repeated permutation of length +size+
7179 * of the elements of +self+;
7180 * each permutation is an array;
7181 * returns +self+. The order of the permutations is indeterminate.
7182 *
7183 * If a positive integer argument +size+ is given,
7184 * calls the block with each +size+-tuple repeated permutation of the elements of +self+.
7185 * The number of permutations is <tt>self.size**size</tt>.
7186 *
7187 * Examples:
7188 *
7189 * - +size+ is 1:
7190 *
7191 * p = []
7192 * [0, 1, 2].repeated_permutation(1) {|permutation| p.push(permutation) }
7193 * p # => [[0], [1], [2]]
7194 *
7195 * - +size+ is 2:
7196 *
7197 * p = []
7198 * [0, 1, 2].repeated_permutation(2) {|permutation| p.push(permutation) }
7199 * p # => [[0, 0], [0, 1], [0, 2], [1, 0], [1, 1], [1, 2], [2, 0], [2, 1], [2, 2]]
7200 *
7201 * If +size+ is zero, calls the block once with an empty array.
7202 *
7203 * If +size+ is negative, does not call the block:
7204 *
7205 * [0, 1, 2].repeated_permutation(-1) {|permutation| fail 'Cannot happen' }
7206 *
7207 * With no block given, returns a new Enumerator.
7208 *
7209 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
7210 */
7211 static VALUE
7213 {
7217 RETURN_SIZED_ENUMERATOR(ary, 1, &num, rb_ary_repeated_permutation_size); /* Return Enumerator if no block */
7221 /* no permutations: yield nothing */
7222 }
7225 }
7229 }
7230 }
7240 }
7242 }
7244 static void
7246 {
7254 }
7259 }
7260 }
7264 }
7265 }
7267 static VALUE
7269 {
7274 }
7276 }
7278 /*
7279 * call-seq:
7280 * repeated_combination(size) {|combination| ... } -> self
7281 * repeated_combination(size) -> new_enumerator
7282 *
7283 * With a block given, calls the block with each repeated combination of length +size+
7284 * of the elements of +self+;
7285 * each combination is an array;
7286 * returns +self+. The order of the combinations is indeterminate.
7287 *
7288 * If a positive integer argument +size+ is given,
7289 * calls the block with each +size+-tuple repeated combination of the elements of +self+.
7290 * The number of combinations is <tt>(size+1)(size+2)/2</tt>.
7291 *
7292 * Examples:
7293 *
7294 * - +size+ is 1:
7295 *
7296 * c = []
7297 * [0, 1, 2].repeated_combination(1) {|combination| c.push(combination) }
7298 * c # => [[0], [1], [2]]
7299 *
7300 * - +size+ is 2:
7301 *
7302 * c = []
7303 * [0, 1, 2].repeated_combination(2) {|combination| c.push(combination) }
7304 * c # => [[0, 0], [0, 1], [0, 2], [1, 1], [1, 2], [2, 2]]
7305 *
7306 * If +size+ is zero, calls the block once with an empty array.
7307 *
7308 * If +size+ is negative, does not call the block:
7309 *
7310 * [0, 1, 2].repeated_combination(-1) {|combination| fail 'Cannot happen' }
7311 *
7312 * With no block given, returns a new Enumerator.
7313 *
7314 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
7315 */
7317 static VALUE
7319 {
7323 RETURN_SIZED_ENUMERATOR(ary, 1, &num, rb_ary_repeated_combination_size); /* Return enumerator if no block */
7326 /* yield nothing */
7327 }
7330 }
7334 }
7335 }
7337 /* yield nothing */
7338 }
7348 }
7350 }
7352 /*
7353 * call-seq:
7354 * product(*other_arrays) -> new_array
7355 * product(*other_arrays) {|combination| ... } -> self
7356 *
7357 * Computes all combinations of elements from all the arrays,
7358 * including both +self+ and +other_arrays+:
7359 *
7360 * - The number of combinations is the product of the sizes of all the arrays,
7361 * including both +self+ and +other_arrays+.
7362 * - The order of the returned combinations is indeterminate.
7363 *
7364 * With no block given, returns the combinations as an array of arrays:
7365 *
7366 * p = [0, 1].product([2, 3])
7367 * # => [[0, 2], [0, 3], [1, 2], [1, 3]]
7368 * p.size # => 4
7369 * p = [0, 1].product([2, 3], [4, 5])
7370 * # => [[0, 2, 4], [0, 2, 5], [0, 3, 4], [0, 3, 5], [1, 2, 4], [1, 2, 5], [1, 3, 4], [1, 3,...
7371 * p.size # => 8
7372 *
7373 * If +self+ or any argument is empty, returns an empty array:
7374 *
7375 * [].product([2, 3], [4, 5]) # => []
7376 * [0, 1].product([2, 3], []) # => []
7377 *
7378 * If no argument is given, returns an array of 1-element arrays,
7379 * each containing an element of +self+:
7380 *
7381 * a.product # => [[0], [1], [2]]
7382 *
7383 * With a block given, calls the block with each combination; returns +self+:
7384 *
7385 * p = []
7386 * [0, 1].product([2, 3]) {|combination| p.push(combination) }
7387 * p # => [[0, 2], [0, 3], [1, 2], [1, 3]]
7388 *
7389 * If +self+ or any argument is empty, does not call the block:
7390 *
7391 * [].product([2, 3], [4, 5]) {|combination| fail 'Cannot happen' }
7392 * # => []
7393 * [0, 1].product([2, 3], []) {|combination| fail 'Cannot happen' }
7394 * # => [0, 1]
7395 *
7396 * If no argument is given, calls the block with each element of +self+ as a 1-element array:
7397 *
7398 * p = []
7399 * [0, 1].product {|combination| p.push(combination) }
7400 * p # => [[0], [1]]
7401 *
7402 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
7403 */
7405 static VALUE
7407 {
7419 /* initialize the arrays of arrays */
7425 /* initialize the counters for the arrays */
7428 /* Otherwise, allocate and fill in an array of results */
7430 /* Make defensive copies of arrays; exit if any is empty */
7434 }
7435 }
7437 /* Compute the length of the result array; return [] if any is empty */
7443 }
7447 }
7449 }
7452 /* fill in one subarray */
7456 }
7458 /* put it on the result array */
7464 }
7467 }
7468 }
7471 }
7473 /*
7474 * Increment the last counter. If it overflows, reset to 0
7475 * and increment the one before it.
7476 */
7481 /* If the first counter overflows, we are done */
7484 }
7485 }
7487 done:
7491 }
7493 /*
7494 * call-seq:
7495 * take(count) -> new_array
7496 *
7497 * Returns a new array containing the first +count+ element of +self+
7498 * (as available);
7499 * +count+ must be a non-negative numeric;
7500 * does not modify +self+:
7501 *
7502 * a = ['a', 'b', 'c', 'd']
7503 * a.take(2) # => ["a", "b"]
7504 * a.take(2.1) # => ["a", "b"]
7505 * a.take(50) # => ["a", "b", "c", "d"]
7506 * a.take(0) # => []
7507 *
7508 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
7509 */
7511 static VALUE
7513 {
7517 }
7519 }
7521 /*
7522 * call-seq:
7523 * take_while {|element| ... } -> new_array
7524 * take_while -> new_enumerator
7525 *
7526 * With a block given, calls the block with each successive element of +self+;
7527 * stops iterating if the block returns +false+ or +nil+;
7528 * returns a new array containing those elements for which the block returned a truthy value:
7529 *
7530 * a = [0, 1, 2, 3, 4, 5]
7531 * a.take_while {|element| element < 3 } # => [0, 1, 2]
7532 * a.take_while {|element| true } # => [0, 1, 2, 3, 4, 5]
7533 * a.take_while {|element| false } # => []
7534 *
7535 * With no block given, returns a new Enumerator.
7536 *
7537 * Does not modify +self+.
7538 *
7539 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
7540 */
7542 static VALUE
7544 {
7550 }
7552 }
7554 /*
7555 * call-seq:
7556 * drop(n) -> new_array
7557 *
7558 * Returns a new array containing all but the first +n+ element of +self+,
7559 * where +n+ is a non-negative Integer;
7560 * does not modify +self+.
7561 *
7562 * Examples:
7563 *
7564 * a = [0, 1, 2, 3, 4, 5]
7565 * a.drop(0) # => [0, 1, 2, 3, 4, 5]
7566 * a.drop(1) # => [1, 2, 3, 4, 5]
7567 * a.drop(2) # => [2, 3, 4, 5]
7568 * a.drop(9) # => []
7569 *
7570 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
7571 */
7573 static VALUE
7575 {
7576 VALUE result;
7580 }
7585 }
7587 /*
7588 * call-seq:
7589 * drop_while {|element| ... } -> new_array
7590 * drop_while -> new_enumerator
7591 *
7592 * With a block given, calls the block with each successive element of +self+;
7593 * stops if the block returns +false+ or +nil+;
7594 * returns a new array _omitting_ those elements for which the block returned a truthy value;
7595 * does not modify +self+:
7596 *
7597 * a = [0, 1, 2, 3, 4, 5]
7598 * a.drop_while {|element| element < 3 } # => [3, 4, 5]
7599 *
7600 * With no block given, returns a new Enumerator.
7601 *
7602 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
7603 */
7605 static VALUE
7607 {
7613 }
7615 }
7617 /*
7618 * call-seq:
7619 * any? -> true or false
7620 * any?(object) -> true or false
7621 * any? {|element| ... } -> true or false
7622 *
7623 * Returns whether for any element of +self+, a given criterion is satisfied.
7624 *
7625 * With no block and no argument, returns whether any element of +self+ is truthy:
7626 *
7627 * [nil, false, []].any? # => true # Array object is truthy.
7628 * [nil, false, {}].any? # => true # Hash object is truthy.
7629 * [nil, false, ''].any? # => true # String object is truthy.
7630 * [nil, false].any? # => false # Nil and false are not truthy.
7631 *
7632 * With argument +object+ given,
7633 * returns whether <tt>object === ele</tt> for any element +ele+ in +self+:
7634 *
7635 * [nil, false, 0].any?(0) # => true
7636 * [nil, false, 1].any?(0) # => false
7637 * [nil, false, 'food'].any?(/foo/) # => true
7638 * [nil, false, 'food'].any?(/bar/) # => false
7639 *
7640 * With a block given,
7641 * calls the block with each element in +self+;
7642 * returns whether the block returns any truthy value:
7643 *
7644 * [0, 1, 2].any? {|ele| ele < 1 } # => true
7645 * [0, 1, 2].any? {|ele| ele < 0 } # => false
7646 *
7647 * With both a block and argument +object+ given,
7648 * ignores the block and uses +object+ as above.
7649 *
7650 * <b>Special case</b>: returns +false+ if +self+ is empty
7651 * (regardless of any given argument or block).
7652 *
7653 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
7654 */
7656 static VALUE
7658 {
7666 }
7669 }
7670 }
7674 }
7675 }
7679 }
7680 }
7682 }
7684 /*
7685 * call-seq:
7686 * all? -> true or false
7687 * all?(object) -> true or false
7688 * all? {|element| ... } -> true or false
7689 *
7690 * Returns whether for every element of +self+,
7691 * a given criterion is satisfied.
7692 *
7693 * With no block and no argument,
7694 * returns whether every element of +self+ is truthy:
7695 *
7696 * [[], {}, '', 0, 0.0, Object.new].all? # => true # All truthy objects.
7697 * [[], {}, '', 0, 0.0, nil].all? # => false # nil is not truthy.
7698 * [[], {}, '', 0, 0.0, false].all? # => false # false is not truthy.
7699 *
7700 * With argument +object+ given, returns whether <tt>object === ele</tt>
7701 * for every element +ele+ in +self+:
7702 *
7703 * [0, 0, 0].all?(0) # => true
7704 * [0, 1, 2].all?(1) # => false
7705 * ['food', 'fool', 'foot'].all?(/foo/) # => true
7706 * ['food', 'drink'].all?(/foo/) # => false
7707 *
7708 * With a block given, calls the block with each element in +self+;
7709 * returns whether the block returns only truthy values:
7710 *
7711 * [0, 1, 2].all? { |ele| ele < 3 } # => true
7712 * [0, 1, 2].all? { |ele| ele < 2 } # => false
7713 *
7714 * With both a block and argument +object+ given,
7715 * ignores the block and uses +object+ as above.
7716 *
7717 * <b>Special case</b>: returns +true+ if +self+ is empty
7718 * (regardless of any given argument or block).
7719 *
7720 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
7721 */
7723 static VALUE
7725 {
7733 }
7736 }
7737 }
7741 }
7742 }
7746 }
7747 }
7749 }
7751 /*
7752 * call-seq:
7753 * none? -> true or false
7754 * none?(object) -> true or false
7755 * none? {|element| ... } -> true or false
7756 *
7757 * Returns +true+ if no element of +self+ meets a given criterion, +false+ otherwise.
7758 *
7759 * With no block given and no argument, returns +true+ if +self+ has no truthy elements,
7760 * +false+ otherwise:
7761 *
7762 * [nil, false].none? # => true
7763 * [nil, 0, false].none? # => false
7764 * [].none? # => true
7765 *
7766 * With argument +object+ given, returns +false+ if for any element +element+,
7767 * <tt>object === element</tt>; +true+ otherwise:
7768 *
7769 * ['food', 'drink'].none?(/bar/) # => true
7770 * ['food', 'drink'].none?(/foo/) # => false
7771 * [].none?(/foo/) # => true
7772 * [0, 1, 2].none?(3) # => true
7773 * [0, 1, 2].none?(1) # => false
7774 *
7775 * With a block given, calls the block with each element in +self+;
7776 * returns +true+ if the block returns no truthy value, +false+ otherwise:
7777 *
7778 * [0, 1, 2].none? {|element| element > 3 } # => true
7779 * [0, 1, 2].none? {|element| element > 1 } # => false
7780 *
7781 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
7782 */
7784 static VALUE
7786 {
7794 }
7797 }
7798 }
7802 }
7803 }
7807 }
7808 }
7810 }
7812 /*
7813 * call-seq:
7814 * one? -> true or false
7815 * one? {|element| ... } -> true or false
7816 * one?(object) -> true or false
7817 *
7818 * Returns +true+ if exactly one element of +self+ meets a given criterion.
7819 *
7820 * With no block given and no argument, returns +true+ if +self+ has exactly one truthy element,
7821 * +false+ otherwise:
7822 *
7823 * [nil, 0].one? # => true
7824 * [0, 0].one? # => false
7825 * [nil, nil].one? # => false
7826 * [].one? # => false
7827 *
7828 * With a block given, calls the block with each element in +self+;
7829 * returns +true+ if the block a truthy value for exactly one element, +false+ otherwise:
7830 *
7831 * [0, 1, 2].one? {|element| element > 0 } # => false
7832 * [0, 1, 2].one? {|element| element > 1 } # => true
7833 * [0, 1, 2].one? {|element| element > 2 } # => false
7834 *
7835 * With argument +object+ given, returns +true+ if for exactly one element +element+, <tt>object === element</tt>;
7836 * +false+ otherwise:
7837 *
7838 * [0, 1, 2].one?(0) # => true
7839 * [0, 0, 1].one?(0) # => false
7840 * [1, 1, 2].one?(0) # => false
7841 * ['food', 'drink'].one?(/bar/) # => false
7842 * ['food', 'drink'].one?(/foo/) # => true
7843 * [].one?(/foo/) # => false
7844 *
7845 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
7846 */
7848 static VALUE
7850 {
7859 }
7864 }
7865 }
7866 }
7872 }
7873 }
7874 }
7880 }
7881 }
7882 }
7884 }
7886 /*
7887 * call-seq:
7888 * array.dig(index, *identifiers) -> object
7889 *
7890 * Finds and returns the object in nested object
7891 * specified by +index+ and +identifiers+;
7892 * the nested objects may be instances of various classes.
7893 * See {Dig Methods}[rdoc-ref:dig_methods.rdoc].
7894 *
7895 * Examples:
7896 *
7897 * a = [:foo, [:bar, :baz, [:bat, :bam]]]
7898 * a.dig(1) # => [:bar, :baz, [:bat, :bam]]
7899 * a.dig(1, 2) # => [:bat, :bam]
7900 * a.dig(1, 2, 0) # => :bat
7901 * a.dig(1, 2, 3) # => nil
7902 *
7903 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
7904 */
7906 static VALUE
7908 {
7914 }
7918 {
7923 }
7926 }
7928 }
7930 /*
7931 * call-seq:
7932 * sum(init = 0) -> object
7933 * sum(init = 0) {|element| ... } -> object
7934 *
7935 * With no block given, returns the sum of +init+ and all elements of +self+;
7936 * for array +array+ and value +init+, equivalent to:
7937 *
7938 * sum = init
7939 * array.each {|element| sum += element }
7940 * sum
7941 *
7942 * For example, <tt>[e0, e1, e2].sum</tt> returns <tt>init + e0 + e1 + e2</tt>.
7943 *
7944 * Examples:
7945 *
7946 * [0, 1, 2, 3].sum # => 6
7947 * [0, 1, 2, 3].sum(100) # => 106
7948 * ['abc', 'def', 'ghi'].sum('jkl') # => "jklabcdefghi"
7949 * [[:foo, :bar], ['foo', 'bar']].sum([2, 3])
7950 * # => [2, 3, :foo, :bar, "foo", "bar"]
7951 *
7952 * The +init+ value and elements need not be numeric, but must all be <tt>+</tt>-compatible:
7953 *
7954 * # Raises TypeError: Array can't be coerced into Integer.
7955 * [[:foo, :bar], ['foo', 'bar']].sum(2)
7956 *
7957 * With a block given, calls the block with each element of +self+;
7958 * the block's return value (instead of the element itself) is used as the addend:
7959 *
7960 * ['zero', 1, :two].sum('Coerced and concatenated: ') {|element| element.to_s }
7961 * # => "Coerced and concatenated: zero1two"
7962 *
7963 * Notes:
7964 *
7965 * - Array#join and Array#flatten may be faster than Array#sum
7966 * for an array of strings or an array of arrays.
7967 * - Array#sum method may not respect method redefinition of "+" methods such as Integer#+.
7968 *
7969 */
7971 static VALUE
7973 {
7991 }
8002 }
8003 }
8009 else
8011 }
8012 else
8014 }
8018 not_exact:
8022 /*
8023 * Kahan-Babuska balancing compensated summation algorithm
8024 * See https://link.springer.com/article/10.1007/s00607-005-0139-x
8025 */
8037 has_float_value:
8045 else
8052 }
8056 else
8059 }
8065 else
8068 }
8072 not_float:
8074 }
8077 init_is_a_value:
8082 has_some_value:
8084 }
8086 }
8088 /* :nodoc: */
8089 static VALUE
8091 {
8093 }
8095 /*
8096 * An +Array+ is an ordered, integer-indexed collection of objects, called _elements_.
8097 * Any object (even another array) may be an array element,
8098 * and an array can contain objects of different types.
8099 *
8100 * == +Array+ Indexes
8101 *
8102 * +Array+ indexing starts at 0, as in C or Java.
8103 *
8104 * A positive index is an offset from the first element:
8105 *
8106 * - Index 0 indicates the first element.
8107 * - Index 1 indicates the second element.
8108 * - ...
8109 *
8110 * A negative index is an offset, backwards, from the end of the array:
8111 *
8112 * - Index -1 indicates the last element.
8113 * - Index -2 indicates the next-to-last element.
8114 * - ...
8115 *
8116 * A non-negative index is <i>in range</i> if and only if it is smaller than
8117 * the size of the array. For a 3-element array:
8118 *
8119 * - Indexes 0 through 2 are in range.
8120 * - Index 3 is out of range.
8121 *
8122 * A negative index is <i>in range</i> if and only if its absolute value is
8123 * not larger than the size of the array. For a 3-element array:
8124 *
8125 * - Indexes -1 through -3 are in range.
8126 * - Index -4 is out of range.
8127 *
8128 * Although the effective index into an array is always an integer,
8129 * some methods (both within and outside of class +Array+)
8130 * accept one or more non-integer arguments that are
8131 * {integer-convertible objects}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects].
8132 *
8133 *
8134 * == Creating Arrays
8135 *
8136 * You can create an +Array+ object explicitly with:
8137 *
8138 * - An {array literal}[rdoc-ref:literals.rdoc@Array+Literals]:
8139 *
8140 * [1, 'one', :one, [2, 'two', :two]]
8141 *
8142 * - A {%w or %W: string-array Literal}[rdoc-ref:literals.rdoc@25w+and+-25W-3A+String-Array+Literals]:
8143 *
8144 * %w[foo bar baz] # => ["foo", "bar", "baz"]
8145 * %w[1 % *] # => ["1", "%", "*"]
8146 *
8147 * - A {%i pr %I: symbol-array Literal}[rdoc-ref:literals.rdoc@25i+and+-25I-3A+Symbol-Array+Literals]:
8148 *
8149 * %i[foo bar baz] # => [:foo, :bar, :baz]
8150 * %i[1 % *] # => [:"1", :%, :*]
8151 *
8152 * - \Method Kernel#Array:
8153 *
8154 * Array(["a", "b"]) # => ["a", "b"]
8155 * Array(1..5) # => [1, 2, 3, 4, 5]
8156 * Array(key: :value) # => [[:key, :value]]
8157 * Array(nil) # => []
8158 * Array(1) # => [1]
8159 * Array({:a => "a", :b => "b"}) # => [[:a, "a"], [:b, "b"]]
8160 *
8161 * - \Method Array.new:
8162 *
8163 * Array.new # => []
8164 * Array.new(3) # => [nil, nil, nil]
8165 * Array.new(4) {Hash.new} # => [{}, {}, {}, {}]
8166 * Array.new(3, true) # => [true, true, true]
8167 *
8168 * Note that the last example above populates the array
8169 * with references to the same object.
8170 * This is recommended only in cases where that object is a natively immutable object
8171 * such as a symbol, a numeric, +nil+, +true+, or +false+.
8172 *
8173 * Another way to create an array with various objects, using a block;
8174 * this usage is safe for mutable objects such as hashes, strings or
8175 * other arrays:
8176 *
8177 * Array.new(4) {|i| i.to_s } # => ["0", "1", "2", "3"]
8178 *
8179 * Here is a way to create a multi-dimensional array:
8180 *
8181 * Array.new(3) {Array.new(3)}
8182 * # => [[nil, nil, nil], [nil, nil, nil], [nil, nil, nil]]
8183 *
8184 * A number of Ruby methods, both in the core and in the standard library,
8185 * provide instance method +to_a+, which converts an object to an array.
8186 *
8187 * - ARGF#to_a
8188 * - Array#to_a
8189 * - Enumerable#to_a
8190 * - Hash#to_a
8191 * - MatchData#to_a
8192 * - NilClass#to_a
8193 * - OptionParser#to_a
8194 * - Range#to_a
8195 * - Set#to_a
8196 * - Struct#to_a
8197 * - Time#to_a
8198 * - Benchmark::Tms#to_a
8199 * - CSV::Table#to_a
8200 * - Enumerator::Lazy#to_a
8201 * - Gem::List#to_a
8202 * - Gem::NameTuple#to_a
8203 * - Gem::Platform#to_a
8204 * - Gem::RequestSet::Lockfile::Tokenizer#to_a
8205 * - Gem::SourceList#to_a
8206 * - OpenSSL::X509::Extension#to_a
8207 * - OpenSSL::X509::Name#to_a
8208 * - Racc::ISet#to_a
8209 * - Rinda::RingFinger#to_a
8210 * - Ripper::Lexer::Elem#to_a
8211 * - RubyVM::InstructionSequence#to_a
8212 * - YAML::DBM#to_a
8213 *
8214 * == Example Usage
8215 *
8216 * In addition to the methods it mixes in through the Enumerable module, the
8217 * +Array+ class has proprietary methods for accessing, searching and otherwise
8218 * manipulating arrays.
8219 *
8220 * Some of the more common ones are illustrated below.
8221 *
8222 * == Accessing Elements
8223 *
8224 * Elements in an array can be retrieved using the Array#[] method. It can
8225 * take a single integer argument (a numeric index), a pair of arguments
8226 * (start and length) or a range. Negative indices start counting from the end,
8227 * with -1 being the last element.
8228 *
8229 * arr = [1, 2, 3, 4, 5, 6]
8230 * arr[2] #=> 3
8231 * arr[100] #=> nil
8232 * arr[-3] #=> 4
8233 * arr[2, 3] #=> [3, 4, 5]
8234 * arr[1..4] #=> [2, 3, 4, 5]
8235 * arr[1..-3] #=> [2, 3, 4]
8236 *
8237 * Another way to access a particular array element is by using the #at method
8238 *
8239 * arr.at(0) #=> 1
8240 *
8241 * The #slice method works in an identical manner to Array#[].
8242 *
8243 * To raise an error for indices outside of the array bounds or else to
8244 * provide a default value when that happens, you can use #fetch.
8245 *
8246 * arr = ['a', 'b', 'c', 'd', 'e', 'f']
8247 * arr.fetch(100) #=> IndexError: index 100 outside of array bounds: -6...6
8248 * arr.fetch(100, "oops") #=> "oops"
8249 *
8250 * The special methods #first and #last will return the first and last
8251 * elements of an array, respectively.
8252 *
8253 * arr.first #=> 1
8254 * arr.last #=> 6
8255 *
8256 * To return the first +n+ elements of an array, use #take
8257 *
8258 * arr.take(3) #=> [1, 2, 3]
8259 *
8260 * #drop does the opposite of #take, by returning the elements after +n+
8261 * elements have been dropped:
8262 *
8263 * arr.drop(3) #=> [4, 5, 6]
8264 *
8265 * == Obtaining Information about an +Array+
8266 *
8267 * Arrays keep track of their own length at all times. To query an array
8268 * about the number of elements it contains, use #length, #count or #size.
8269 *
8270 * browsers = ['Chrome', 'Firefox', 'Safari', 'Opera', 'IE']
8271 * browsers.length #=> 5
8272 * browsers.count #=> 5
8273 *
8274 * To check whether an array contains any elements at all
8275 *
8276 * browsers.empty? #=> false
8277 *
8278 * To check whether a particular item is included in the array
8279 *
8280 * browsers.include?('Konqueror') #=> false
8281 *
8282 * == Adding Items to Arrays
8283 *
8284 * Items can be added to the end of an array by using either #push or #<<
8285 *
8286 * arr = [1, 2, 3, 4]
8287 * arr.push(5) #=> [1, 2, 3, 4, 5]
8288 * arr << 6 #=> [1, 2, 3, 4, 5, 6]
8289 *
8290 * #unshift will add a new item to the beginning of an array.
8291 *
8292 * arr.unshift(0) #=> [0, 1, 2, 3, 4, 5, 6]
8293 *
8294 * With #insert you can add a new element to an array at any position.
8295 *
8296 * arr.insert(3, 'apple') #=> [0, 1, 2, 'apple', 3, 4, 5, 6]
8297 *
8298 * Using the #insert method, you can also insert multiple values at once:
8299 *
8300 * arr.insert(3, 'orange', 'pear', 'grapefruit')
8301 * #=> [0, 1, 2, "orange", "pear", "grapefruit", "apple", 3, 4, 5, 6]
8302 *
8303 * == Removing Items from an +Array+
8304 *
8305 * The method #pop removes the last element in an array and returns it:
8306 *
8307 * arr = [1, 2, 3, 4, 5, 6]
8308 * arr.pop #=> 6
8309 * arr #=> [1, 2, 3, 4, 5]
8310 *
8311 * To retrieve and at the same time remove the first item, use #shift:
8312 *
8313 * arr.shift #=> 1
8314 * arr #=> [2, 3, 4, 5]
8315 *
8316 * To delete an element at a particular index:
8317 *
8318 * arr.delete_at(2) #=> 4
8319 * arr #=> [2, 3, 5]
8320 *
8321 * To delete a particular element anywhere in an array, use #delete:
8322 *
8323 * arr = [1, 2, 2, 3]
8324 * arr.delete(2) #=> 2
8325 * arr #=> [1,3]
8326 *
8327 * A useful method if you need to remove +nil+ values from an array is
8328 * #compact:
8329 *
8330 * arr = ['foo', 0, nil, 'bar', 7, 'baz', nil]
8331 * arr.compact #=> ['foo', 0, 'bar', 7, 'baz']
8332 * arr #=> ['foo', 0, nil, 'bar', 7, 'baz', nil]
8333 * arr.compact! #=> ['foo', 0, 'bar', 7, 'baz']
8334 * arr #=> ['foo', 0, 'bar', 7, 'baz']
8335 *
8336 * Another common need is to remove duplicate elements from an array.
8337 *
8338 * It has the non-destructive #uniq, and destructive method #uniq!
8339 *
8340 * arr = [2, 5, 6, 556, 6, 6, 8, 9, 0, 123, 556]
8341 * arr.uniq #=> [2, 5, 6, 556, 8, 9, 0, 123]
8342 *
8343 * == Iterating over Arrays
8344 *
8345 * Like all classes that include the Enumerable module, +Array+ has an each
8346 * method, which defines what elements should be iterated over and how. In
8347 * case of Array's #each, all elements in the +Array+ instance are yielded to
8348 * the supplied block in sequence.
8349 *
8350 * Note that this operation leaves the array unchanged.
8351 *
8352 * arr = [1, 2, 3, 4, 5]
8353 * arr.each {|a| print a -= 10, " "}
8354 * # prints: -9 -8 -7 -6 -5
8355 * #=> [1, 2, 3, 4, 5]
8356 *
8357 * Another sometimes useful iterator is #reverse_each which will iterate over
8358 * the elements in the array in reverse order.
8359 *
8360 * words = %w[first second third fourth fifth sixth]
8361 * str = ""
8362 * words.reverse_each {|word| str += "#{word} "}
8363 * p str #=> "sixth fifth fourth third second first "
8364 *
8365 * The #map method can be used to create a new array based on the original
8366 * array, but with the values modified by the supplied block:
8367 *
8368 * arr.map {|a| 2*a} #=> [2, 4, 6, 8, 10]
8369 * arr #=> [1, 2, 3, 4, 5]
8370 * arr.map! {|a| a**2} #=> [1, 4, 9, 16, 25]
8371 * arr #=> [1, 4, 9, 16, 25]
8372 *
8373 *
8374 * == Selecting Items from an +Array+
8375 *
8376 * Elements can be selected from an array according to criteria defined in a
8377 * block. The selection can happen in a destructive or a non-destructive
8378 * manner. While the destructive operations will modify the array they were
8379 * called on, the non-destructive methods usually return a new array with the
8380 * selected elements, but leave the original array unchanged.
8381 *
8382 * === Non-destructive Selection
8383 *
8384 * arr = [1, 2, 3, 4, 5, 6]
8385 * arr.select {|a| a > 3} #=> [4, 5, 6]
8386 * arr.reject {|a| a < 3} #=> [3, 4, 5, 6]
8387 * arr.drop_while {|a| a < 4} #=> [4, 5, 6]
8388 * arr #=> [1, 2, 3, 4, 5, 6]
8389 *
8390 * === Destructive Selection
8391 *
8392 * #select! and #reject! are the corresponding destructive methods to #select
8393 * and #reject
8394 *
8395 * Similar to #select vs. #reject, #delete_if and #keep_if have the exact
8396 * opposite result when supplied with the same block:
8397 *
8398 * arr.delete_if {|a| a < 4} #=> [4, 5, 6]
8399 * arr #=> [4, 5, 6]
8400 *
8401 * arr = [1, 2, 3, 4, 5, 6]
8402 * arr.keep_if {|a| a < 4} #=> [1, 2, 3]
8403 * arr #=> [1, 2, 3]
8404 *
8405 * == What's Here
8406 *
8407 * First, what's elsewhere. \Class +Array+:
8408 *
8409 * - Inherits from {class Object}[rdoc-ref:Object@What-27s+Here].
8410 * - Includes {module Enumerable}[rdoc-ref:Enumerable@What-27s+Here],
8411 * which provides dozens of additional methods.
8412 *
8413 * Here, class +Array+ provides methods that are useful for:
8414 *
8415 * - {Creating an Array}[rdoc-ref:Array@Methods+for+Creating+an+Array]
8416 * - {Querying}[rdoc-ref:Array@Methods+for+Querying]
8417 * - {Comparing}[rdoc-ref:Array@Methods+for+Comparing]
8418 * - {Fetching}[rdoc-ref:Array@Methods+for+Fetching]
8419 * - {Assigning}[rdoc-ref:Array@Methods+for+Assigning]
8420 * - {Deleting}[rdoc-ref:Array@Methods+for+Deleting]
8421 * - {Combining}[rdoc-ref:Array@Methods+for+Combining]
8422 * - {Iterating}[rdoc-ref:Array@Methods+for+Iterating]
8423 * - {Converting}[rdoc-ref:Array@Methods+for+Converting]
8424 * - {And more....}[rdoc-ref:Array@Other+Methods]
8425 *
8426 * === Methods for Creating an +Array+
8427 *
8428 * - ::[]: Returns a new array populated with given objects.
8429 * - ::new: Returns a new array.
8430 * - ::try_convert: Returns a new array created from a given object.
8431 *
8432 * See also {Creating Arrays}[rdoc-ref:Array@Creating+Arrays].
8433 *
8434 * === Methods for Querying
8435 *
8436 * - #length (aliased as #size): Returns the count of elements.
8437 * - #include?: Returns whether any element <tt>==</tt> a given object.
8438 * - #empty?: Returns whether there are no elements.
8439 * - #all?: Returns whether all elements meet a given criterion.
8440 * - #any?: Returns whether any element meets a given criterion.
8441 * - #none?: Returns whether no element <tt>==</tt> a given object.
8442 * - #one?: Returns whether exactly one element <tt>==</tt> a given object.
8443 * - #count: Returns the count of elements that meet a given criterion.
8444 * - #find_index (aliased as #index): Returns the index of the first element that meets a given criterion.
8445 * - #rindex: Returns the index of the last element that meets a given criterion.
8446 * - #hash: Returns the integer hash code.
8447 *
8448 * === Methods for Comparing
8449 *
8450 * - #<=>: Returns -1, 0, or 1, as +self+ is less than, equal to, or
8451 * greater than a given object.
8452 * - #==: Returns whether each element in +self+ is <tt>==</tt> to the corresponding element
8453 * in a given object.
8454 * - #eql?: Returns whether each element in +self+ is <tt>eql?</tt> to the corresponding
8455 * element in a given object.
8457 * === Methods for Fetching
8458 *
8459 * These methods do not modify +self+.
8460 *
8461 * - #[] (aliased as #slice): Returns consecutive elements as determined by a given argument.
8462 * - #fetch: Returns the element at a given offset.
8463 * - #fetch_values: Returns elements at given offsets.
8464 * - #first: Returns one or more leading elements.
8465 * - #last: Returns one or more trailing elements.
8466 * - #max: Returns one or more maximum-valued elements,
8467 * as determined by <tt>#<=></tt> or a given block.
8468 * - #min: Returns one or more minimum-valued elements,
8469 * as determined by <tt>#<=></tt> or a given block.
8470 * - #minmax: Returns the minimum-valued and maximum-valued elements,
8471 * as determined by <tt>#<=></tt> or a given block.
8472 * - #assoc: Returns the first element that is an array
8473 * whose first element <tt>==</tt> a given object.
8474 * - #rassoc: Returns the first element that is an array
8475 * whose second element <tt>==</tt> a given object.
8476 * - #at: Returns the element at a given offset.
8477 * - #values_at: Returns the elements at given offsets.
8478 * - #dig: Returns the object in nested objects
8479 * that is specified by a given index and additional arguments.
8480 * - #drop: Returns trailing elements as determined by a given index.
8481 * - #take: Returns leading elements as determined by a given index.
8482 * - #drop_while: Returns trailing elements as determined by a given block.
8483 * - #take_while: Returns leading elements as determined by a given block.
8484 * - #sort: Returns all elements in an order determined by <tt>#<=></tt> or a given block.
8485 * - #reverse: Returns all elements in reverse order.
8486 * - #compact: Returns an array containing all non-+nil+ elements.
8487 * - #select (aliased as #filter): Returns an array containing elements selected by a given block.
8488 * - #uniq: Returns an array containing non-duplicate elements.
8489 * - #rotate: Returns all elements with some rotated from one end to the other.
8490 * - #bsearch: Returns an element selected via a binary search
8491 * as determined by a given block.
8492 * - #bsearch_index: Returns the index of an element selected via a binary search
8493 * as determined by a given block.
8494 * - #sample: Returns one or more random elements.
8495 * - #shuffle: Returns elements in a random order.
8496 * - #reject: Returns an array containing elements not rejected by a given block.
8497 *
8498 * === Methods for Assigning
8499 *
8500 * These methods add, replace, or reorder elements in +self+.
8501 *
8502 * - #[]=: Assigns specified elements with a given object.
8503 * - #<<: Appends an element.
8504 * - #push (aliased as #append): Appends elements.
8505 * - #unshift (aliased as #prepend): Prepends leading elements.
8506 * - #insert: Inserts given objects at a given offset; does not replace elements.
8507 * - #concat: Appends all elements from given arrays.
8508 * - #fill: Replaces specified elements with specified objects.
8509 * - #flatten!: Replaces each nested array in +self+ with the elements from that array.
8510 * - #initialize_copy (aliased as #replace): Replaces the content of +self+ with the content of a given array.
8511 * - #reverse!: Replaces +self+ with its elements reversed.
8512 * - #rotate!: Replaces +self+ with its elements rotated.
8513 * - #shuffle!: Replaces +self+ with its elements in random order.
8514 * - #sort!: Replaces +self+ with its elements sorted,
8515 * as determined by <tt>#<=></tt> or a given block.
8516 * - #sort_by!: Replaces +self+ with its elements sorted, as determined by a given block.
8517 *
8518 * === Methods for Deleting
8519 *
8520 * Each of these methods removes elements from +self+:
8521 *
8522 * - #pop: Removes and returns the last element.
8523 * - #shift: Removes and returns the first element.
8524 * - #compact!: Removes all +nil+ elements.
8525 * - #delete: Removes elements equal to a given object.
8526 * - #delete_at: Removes the element at a given offset.
8527 * - #delete_if: Removes elements specified by a given block.
8528 * - #clear: Removes all elements.
8529 * - #keep_if: Removes elements not specified by a given block.
8530 * - #reject!: Removes elements specified by a given block.
8531 * - #select! (aliased as #filter!): Removes elements not specified by a given block.
8532 * - #slice!: Removes and returns a sequence of elements.
8533 * - #uniq!: Removes duplicates.
8534 *
8535 * === Methods for Combining
8536 *
8537 * - #&: Returns an array containing elements found both in +self+ and a given array.
8538 * - #intersection: Returns an array containing elements found both in +self+
8539 * and in each given array.
8540 * - #+: Returns an array containing all elements of +self+ followed by all elements of a given array.
8541 * - #-: Returns an array containing all elements of +self+ that are not found in a given array.
8542 * - #|: Returns an array containing all elements of +self+ and all elements of a given array,
8543 * duplicates removed.
8544 * - #union: Returns an array containing all elements of +self+ and all elements of given arrays,
8545 * duplicates removed.
8546 * - #difference: Returns an array containing all elements of +self+ that are not found
8547 * in any of the given arrays..
8548 * - #product: Returns or yields all combinations of elements from +self+ and given arrays.
8549 * - #reverse: Returns an array containing all elements of +self+ in reverse order.
8550 *
8551 * === Methods for Iterating
8552 *
8553 * - #each: Passes each element to a given block.
8554 * - #reverse_each: Passes each element, in reverse order, to a given block.
8555 * - #each_index: Passes each element index to a given block.
8556 * - #cycle: Calls a given block with each element, then does so again,
8557 * for a specified number of times, or forever.
8558 * - #combination: Calls a given block with combinations of elements of +self+;
8559 * a combination does not use the same element more than once.
8560 * - #permutation: Calls a given block with permutations of elements of +self+;
8561 * a permutation does not use the same element more than once.
8562 * - #repeated_combination: Calls a given block with combinations of elements of +self+;
8563 * a combination may use the same element more than once.
8564 * - #repeated_permutation: Calls a given block with permutations of elements of +self+;
8565 * a permutation may use the same element more than once.
8566 *
8567 * === Methods for Converting
8568 *
8569 * - #collect (aliased as #map): Returns an array containing the block return-value for each element.
8570 * - #collect! (aliased as #map!): Replaces each element with a block return-value.
8571 * - #flatten: Returns an array that is a recursive flattening of +self+.
8572 * - #inspect (aliased as #to_s): Returns a new String containing the elements.
8573 * - #join: Returns a newsString containing the elements joined by the field separator.
8574 * - #to_a: Returns +self+ or a new array containing all elements.
8575 * - #to_ary: Returns +self+.
8576 * - #to_h: Returns a new hash formed from the elements.
8577 * - #transpose: Transposes +self+, which must be an array of arrays.
8578 * - #zip: Returns a new array of arrays containing +self+ and given arrays;
8579 * follow the link for details.
8580 *
8581 * === Other Methods
8582 *
8583 * - #*: Returns one of the following:
8584 *
8585 * - With integer argument +n+, a new array that is the concatenation
8586 * of +n+ copies of +self+.
8587 * - With string argument +field_separator+, a new string that is equivalent to
8588 * <tt>join(field_separator)</tt>.
8589 *
8590 * - #pack: Packs the elements into a binary sequence.
8591 * - #sum: Returns a sum of elements according to either <tt>+</tt> or a given block.
8592 */
8594 void
8596 {
8724 }