| blob | 059d6911ee7cd35ce3af91c3df85e2bf3d61583a |
1 /**********************************************************************
3 array.c -
5 $Author$
6 created at: Fri Aug 6 09:46:12 JST 1993
8 Copyright (C) 1993-2007 Yukihiro Matsumoto
9 Copyright (C) 2000 Network Applied Communication Laboratory, Inc.
10 Copyright (C) 2000 Information-technology Promotion Agency, Japan
12 **********************************************************************/
34 #if !ARRAY_DEBUG
35 # undef NDEBUG
36 # define NDEBUG
37 #endif
40 VALUE rb_cArray;
41 VALUE rb_cArray_empty_frozen;
43 /* Flags of RArray
44 *
45 * 1: RARRAY_EMBED_FLAG
46 * The array is embedded (its contents follow the header, rather than
47 * being on a separately allocated buffer).
48 * 2: RARRAY_SHARED_FLAG (equal to ELTS_SHARED)
49 * The array is shared. The buffer this array points to is owned by
50 * another array (the shared root).
51 * 3-9: RARRAY_EMBED_LEN
52 * The length of the array when RARRAY_EMBED_FLAG is set.
53 * 12: RARRAY_SHARED_ROOT_FLAG
54 * The array is a shared root that does reference counting. The buffer
55 * this array points to is owned by this array but may be pointed to
56 * by other arrays.
57 * Note: Frozen arrays may be a shared root without this flag being
58 * set. Frozen arrays do not have reference counting because
59 * they cannot be modified. Not updating the reference count
60 * improves copy-on-write performance. Their reference count is
61 * assumed to be infinity.
62 * 14: RARRAY_PTR_IN_USE_FLAG
63 * The buffer of the array is in use. This is only used during
64 * debugging.
65 */
67 /* for OPTIMIZED_CMP: */
68 #define id_cmp idCmp
70 #define ARY_DEFAULT_SIZE 16
71 #define ARY_MAX_SIZE (LONG_MAX / (int)sizeof(VALUE))
72 #define SMALL_ARRAY_LEN 16
75 static int
77 {
79 }
81 #define ARY_HEAP_PTR(a) (RUBY_ASSERT(!ARY_EMBED_P(a)), RARRAY(a)->as.heap.ptr)
82 #define ARY_HEAP_LEN(a) (RUBY_ASSERT(!ARY_EMBED_P(a)), RARRAY(a)->as.heap.len)
83 #define ARY_HEAP_CAPA(a) (RUBY_ASSERT(!ARY_EMBED_P(a)), RUBY_ASSERT(!ARY_SHARED_ROOT_P(a)), \
84 RARRAY(a)->as.heap.aux.capa)
86 #define ARY_EMBED_PTR(a) (RUBY_ASSERT(ARY_EMBED_P(a)), RARRAY(a)->as.ary)
87 #define ARY_EMBED_LEN(a) \
88 (RUBY_ASSERT(ARY_EMBED_P(a)), \
89 (long)((RBASIC(a)->flags >> RARRAY_EMBED_LEN_SHIFT) & \
90 (RARRAY_EMBED_LEN_MASK >> RARRAY_EMBED_LEN_SHIFT)))
91 #define ARY_HEAP_SIZE(a) (RUBY_ASSERT(!ARY_EMBED_P(a)), RUBY_ASSERT(ARY_OWNS_HEAP_P(a)), ARY_CAPA(a) * sizeof(VALUE))
93 #define ARY_OWNS_HEAP_P(a) (RUBY_ASSERT(should_be_T_ARRAY((VALUE)(a))), \
94 !FL_TEST_RAW((a), RARRAY_SHARED_FLAG|RARRAY_EMBED_FLAG))
96 #define FL_SET_EMBED(a) do { \
97 RUBY_ASSERT(!ARY_SHARED_P(a)); \
98 FL_SET((a), RARRAY_EMBED_FLAG); \
99 ary_verify(a); \
100 } while (0)
102 #define FL_UNSET_EMBED(ary) FL_UNSET((ary), RARRAY_EMBED_FLAG|RARRAY_EMBED_LEN_MASK)
103 #define FL_SET_SHARED(ary) do { \
104 RUBY_ASSERT(!ARY_EMBED_P(ary)); \
105 FL_SET((ary), RARRAY_SHARED_FLAG); \
106 } while (0)
107 #define FL_UNSET_SHARED(ary) FL_UNSET((ary), RARRAY_SHARED_FLAG)
109 #define ARY_SET_PTR(ary, p) do { \
110 RUBY_ASSERT(!ARY_EMBED_P(ary)); \
111 RUBY_ASSERT(!OBJ_FROZEN(ary)); \
112 RARRAY(ary)->as.heap.ptr = (p); \
113 } while (0)
114 #define ARY_SET_EMBED_LEN(ary, n) do { \
115 long tmp_n = (n); \
116 RUBY_ASSERT(ARY_EMBED_P(ary)); \
117 RBASIC(ary)->flags &= ~RARRAY_EMBED_LEN_MASK; \
118 RBASIC(ary)->flags |= (tmp_n) << RARRAY_EMBED_LEN_SHIFT; \
119 } while (0)
120 #define ARY_SET_HEAP_LEN(ary, n) do { \
121 RUBY_ASSERT(!ARY_EMBED_P(ary)); \
122 RARRAY(ary)->as.heap.len = (n); \
123 } while (0)
124 #define ARY_SET_LEN(ary, n) do { \
125 if (ARY_EMBED_P(ary)) { \
126 ARY_SET_EMBED_LEN((ary), (n)); \
127 } \
128 else { \
129 ARY_SET_HEAP_LEN((ary), (n)); \
130 } \
131 RUBY_ASSERT(RARRAY_LEN(ary) == (n)); \
132 } while (0)
133 #define ARY_INCREASE_PTR(ary, n) do { \
134 RUBY_ASSERT(!ARY_EMBED_P(ary)); \
135 RUBY_ASSERT(!OBJ_FROZEN(ary)); \
136 RARRAY(ary)->as.heap.ptr += (n); \
137 } while (0)
138 #define ARY_INCREASE_LEN(ary, n) do { \
139 RUBY_ASSERT(!OBJ_FROZEN(ary)); \
140 if (ARY_EMBED_P(ary)) { \
141 ARY_SET_EMBED_LEN((ary), RARRAY_LEN(ary)+(n)); \
142 } \
143 else { \
144 RARRAY(ary)->as.heap.len += (n); \
145 } \
146 } while (0)
148 #define ARY_CAPA(ary) (ARY_EMBED_P(ary) ? ary_embed_capa(ary) : \
149 ARY_SHARED_ROOT_P(ary) ? RARRAY_LEN(ary) : ARY_HEAP_CAPA(ary))
150 #define ARY_SET_CAPA(ary, n) do { \
151 RUBY_ASSERT(!ARY_EMBED_P(ary)); \
152 RUBY_ASSERT(!ARY_SHARED_P(ary)); \
153 RUBY_ASSERT(!OBJ_FROZEN(ary)); \
154 RARRAY(ary)->as.heap.aux.capa = (n); \
155 } while (0)
157 #define ARY_SHARED_ROOT_OCCUPIED(ary) (!OBJ_FROZEN(ary) && ARY_SHARED_ROOT_REFCNT(ary) == 1)
158 #define ARY_SET_SHARED_ROOT_REFCNT(ary, value) do { \
159 RUBY_ASSERT(ARY_SHARED_ROOT_P(ary)); \
160 RUBY_ASSERT(!OBJ_FROZEN(ary)); \
161 RUBY_ASSERT((value) >= 0); \
162 RARRAY(ary)->as.heap.aux.capa = (value); \
163 } while (0)
164 #define FL_SET_SHARED_ROOT(ary) do { \
165 RUBY_ASSERT(!OBJ_FROZEN(ary)); \
166 RUBY_ASSERT(!ARY_EMBED_P(ary)); \
167 FL_SET((ary), RARRAY_SHARED_ROOT_FLAG); \
168 } while (0)
172 {
177 }
178 #undef RARRAY_ASET
180 static long
182 {
186 }
188 static size_t
190 {
192 }
194 static bool
196 {
198 }
200 bool
202 {
203 /* An array cannot be turned embeddable when the array is:
204 * - Shared root: other objects may point to the buffer of this array
205 * so we cannot make it embedded.
206 * - Frozen: this array may also be a shared root without the shared root
207 * flag.
208 * - Shared: we don't want to re-embed an array that points to a shared
209 * root (to save memory).
210 */
212 }
214 size_t
216 {
221 }
224 }
227 }
229 }
232 #if ARRAY_DEBUG
233 #define ary_verify(ary) ary_verify_(ary, __FILE__, __LINE__)
235 static VALUE
237 {
248 }
252 }
260 }
262 }
265 }
267 void
269 {
271 }
272 #else
273 #define ary_verify(ary) ((void)0)
274 #endif
276 VALUE *
278 {
279 #if ARRAY_DEBUG
281 #endif
283 }
285 void
287 {
288 #if ARRAY_DEBUG
290 #endif
291 }
293 void
295 {
298 }
299 }
301 static void
303 {
306 });
307 }
311 {
314 }
315 }
317 static void
319 {
323 });
324 }
326 static void
328 {
335 });
336 }
342 }
343 });
344 }
345 }
347 static void
349 {
351 }
355 {
357 }
359 static void
361 {
363 }
365 static void
367 {
369 }
371 static size_t
373 {
379 }
381 void
383 {
395 }
396 }
398 static void
400 {
415 }
418 }
420 }
433 }
434 }
437 }
441 {
449 }
452 }
454 static void
456 {
461 }
464 }
469 }
471 static void
473 {
477 }
478 }
480 static void
482 {
486 }
488 static void
490 {
493 }
496 }
500 }
502 static VALUE
504 {
509 }
511 }
513 static void
515 {
525 }
529 {
532 }
534 void
536 {
550 }
551 else if (ARY_SHARED_ROOT_OCCUPIED(shared_root) && len > ((shared_len = RARRAY_LEN(shared_root))>>1)) {
558 });
561 }
568 }
571 }
573 }
575 void
577 {
580 }
582 static VALUE
584 {
591 }
602 }
604 /* if array is shared, then it is likely it participate in push/shift pattern */
609 }
612 }
613 }
614 }
617 }
620 }
624 }
628 }
630 /*
631 * call-seq:
632 * array.freeze -> self
633 *
634 * Freezes +self+; returns +self+:
635 *
636 * a = []
637 * a.frozen? # => false
638 * a.freeze
639 * a.frozen? # => true
640 *
641 * An attempt to modify a frozen +Array+ raises FrozenError.
642 */
644 VALUE
646 {
653 }
656 }
658 /* This can be used to take a snapshot of an array (with
659 e.g. rb_ary_replace) and check later whether the array has been
660 modified from the snapshot. The snapshot is cheap, though if
661 something does modify the array it will pay the cost of copying
662 it. If Array#pop or Array#shift has been called, the array will
663 be still shared with the snapshot, but the array length will
664 differ. */
665 VALUE
667 {
673 }
675 }
677 static VALUE
679 {
685 /* Created array is:
686 * FL_SET_EMBED((VALUE)ary);
687 * ARY_SET_EMBED_LEN((VALUE)ary, 0);
688 */
690 }
692 static VALUE
694 {
699 }
701 static VALUE
703 {
706 }
708 static VALUE
710 {
711 VALUE ary;
715 }
718 }
724 }
732 }
735 }
737 VALUE
739 {
741 }
743 VALUE
745 {
747 }
749 VALUE
751 {
753 VALUE ary;
761 }
766 }
768 VALUE
770 {
771 VALUE ary;
777 }
780 }
782 VALUE
784 {
786 }
788 static VALUE
790 {
796 /* Created array is:
797 * FL_SET_EMBED((VALUE)ary);
798 * ARY_SET_EMBED_LEN((VALUE)ary, 0);
799 */
801 }
803 static VALUE
805 {
810 }
812 static VALUE
814 {
815 VALUE ary;
819 }
822 }
828 }
836 }
839 }
841 VALUE
843 {
844 VALUE ary;
850 }
853 }
855 VALUE
857 {
860 }
862 VALUE
864 {
869 }
871 void
873 {
879 }
883 }
886 }
890 }
893 }
894 }
898 static VALUE
900 {
906 }
908 VALUE
910 {
914 // bypass frozen checks
919 }
921 size_t
923 {
926 }
929 }
930 }
932 static VALUE
934 {
939 }
942 }
945 }
950 /* Shared roots cannot be embedded because the reference count
951 * (refcnt) is stored in as.heap.aux.capa. */
963 }
966 }
976 }
977 }
979 static VALUE
981 {
991 }
994 }
995 }
997 VALUE
999 {
1001 }
1003 VALUE
1005 {
1007 }
1008 #define to_ary rb_to_array_type
1010 VALUE
1012 {
1014 }
1016 VALUE
1018 {
1020 }
1022 VALUE
1024 {
1026 }
1028 /*
1029 * call-seq:
1030 * Array.try_convert(object) -> object, new_array, or nil
1031 *
1032 * Attempts to return an array, based on the given +object+.
1033 *
1034 * If +object+ is an array, returns +object+.
1035 *
1036 * Otherwise if +object+ responds to <tt>:to_ary</tt>.
1037 * calls <tt>object.to_ary</tt>:
1038 * if the return value is an array or +nil+, returns that value;
1039 * if not, raises TypeError.
1040 *
1041 * Otherwise returns +nil+.
1042 *
1043 * Related: see {Methods for Creating an Array}[rdoc-ref:Array@Methods+for+Creating+an+Array].
1044 */
1046 static VALUE
1048 {
1050 }
1052 /* :nodoc: */
1053 static VALUE
1055 {
1056 VALUE ary;
1063 }
1068 }
1071 }
1074 }
1076 /*
1077 * call-seq:
1078 * Array.new -> new_empty_array
1079 * Array.new(array) -> new_array
1080 * Array.new(size, default_value = nil) -> new_array
1081 * Array.new(size = 0) {|index| ... } -> new_array
1082 *
1083 * Returns a new array.
1084 *
1085 * With no block and no argument given, returns a new empty array:
1086 *
1087 * Array.new # => []
1088 *
1089 * With no block and array argument given, returns a new array with the same elements:
1090 *
1091 * Array.new([:foo, 'bar', 2]) # => [:foo, "bar", 2]
1092 *
1093 * With no block and integer argument given, returns a new array containing
1094 * that many instances of the given +default_value+:
1095 *
1096 * Array.new(0) # => []
1097 * Array.new(3) # => [nil, nil, nil]
1098 * Array.new(2, 3) # => [3, 3]
1099 *
1100 * With a block given, returns an array of the given +size+;
1101 * calls the block with each +index+ in the range <tt>(0...size)</tt>;
1102 * the element at that +index+ in the returned array is the blocks return value:
1103 *
1104 * Array.new(3) {|index| "Element #{index}" } # => ["Element 0", "Element 1", "Element 2"]
1105 *
1106 * A common pitfall for new Rubyists is providing an expression as +default_value+:
1107 *
1108 * array = Array.new(2, {})
1109 * array # => [{}, {}]
1110 * array[0][:a] = 1
1111 * array # => [{a: 1}, {a: 1}], as array[0] and array[1] are same object
1112 *
1113 * If you want the elements of the array to be distinct, you should pass a block:
1114 *
1115 * array = Array.new(2) { {} }
1116 * array # => [{}, {}]
1117 * array[0][:a] = 1
1118 * array # => [{a: 1}, {}], as array[0] and array[1] are different objects
1119 *
1120 * Raises TypeError if the first argument is not either an array
1121 * or an {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects]).
1122 * Raises ArgumentError if the first argument is a negative integer.
1123 *
1124 * Related: see {Methods for Creating an Array}[rdoc-ref:Array@Methods+for+Creating+an+Array].
1125 */
1127 static VALUE
1129 {
1140 }
1142 }
1149 }
1150 }
1153 /* NUM2LONG() may call size.to_int, ary can be frozen, modified, etc */
1156 }
1159 }
1160 /* recheck after argument conversion */
1168 }
1172 }
1173 }
1177 }
1179 }
1181 /*
1182 * Returns a new array, populated with the given objects:
1183 *
1184 * Array[1, 'a', /^A/] # => [1, "a", /^A/]
1185 * Array[] # => []
1186 * Array.[](1, 'a', /^A/) # => [1, "a", /^A/]
1187 *
1188 * Related: see {Methods for Creating an Array}[rdoc-ref:Array@Methods+for+Creating+an+Array].
1189 */
1191 static VALUE
1193 {
1198 }
1201 }
1203 void
1205 {
1213 }
1214 }
1217 }
1222 }
1225 }
1229 }
1231 }
1233 static VALUE
1235 {
1246 }
1250 /* The ary_make_shared call may allocate, which can trigger a GC
1251 * compaction. This can cause the array to be embedded because it has
1252 * a length of 0. */
1263 }
1267 }
1269 static VALUE
1271 {
1287 }
1290 }
1306 }
1308 }
1316 }
1317 });
1319 }
1322 }
1324 static VALUE
1326 {
1328 }
1330 enum ary_take_pos_flags
1331 {
1334 };
1336 static VALUE
1338 {
1344 }
1347 }
1350 }
1352 }
1354 static VALUE
1356 {
1358 /* the case optional argument is omitted should be handled in
1359 * callers of this function. if another arity case is added,
1360 * this arity check needs to rewrite. */
1363 }
1365 /*
1366 * call-seq:
1367 * self << object -> self
1368 *
1369 * Appends +object+ as the last element in +self+; returns +self+:
1370 *
1371 * [:foo, 'bar', 2] << :baz # => [:foo, "bar", 2, :baz]
1372 *
1373 * Appends +object+ as a single element, even if it is another array:
1374 *
1375 * [:foo, 'bar', 2] << [3, 4] # => [:foo, "bar", 2, [3, 4]]
1376 *
1377 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
1378 */
1380 VALUE
1382 {
1387 });
1391 }
1393 VALUE
1395 {
1401 }
1403 /*
1404 * call-seq:
1405 * push(*objects) -> self
1406 * append(*objects) -> self
1407 *
1408 * Appends each argument in +objects+ to +self+; returns +self+:
1409 *
1410 * a = [:foo, 'bar', 2] # => [:foo, "bar", 2]
1411 * a.push(:baz, :bat) # => [:foo, "bar", 2, :baz, :bat]
1412 *
1413 * Appends each argument as a single element, even if it is another array:
1414 *
1415 * a = [:foo, 'bar', 2] # => [:foo, "bar", 2]
1416 a.push([:baz, :bat], [:bam, :bad]) # => [:foo, "bar", 2, [:baz, :bat], [:bam, :bad]]
1417 *
1418 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
1419 */
1421 static VALUE
1423 {
1425 }
1427 VALUE
1429 {
1437 {
1439 }
1444 }
1446 /*
1447 * call-seq:
1448 * array.pop -> object or nil
1449 * array.pop(n) -> new_array
1450 *
1451 * Removes and returns trailing elements.
1452 *
1453 * When no argument is given and +self+ is not empty,
1454 * removes and returns the last element:
1455 *
1456 * a = [:foo, 'bar', 2]
1457 * a.pop # => 2
1458 * a # => [:foo, "bar"]
1459 *
1460 * Returns +nil+ if the array is empty.
1461 *
1462 * When a non-negative Integer argument +n+ is given and is in range,
1463 *
1464 * removes and returns the last +n+ elements in a new +Array+:
1465 * a = [:foo, 'bar', 2]
1466 * a.pop(2) # => ["bar", 2]
1467 *
1468 * If +n+ is positive and out of range,
1469 * removes and returns all elements:
1470 *
1471 * a = [:foo, 'bar', 2]
1472 * a.pop(50) # => [:foo, "bar", 2]
1473 *
1474 * Related: #push, #shift, #unshift.
1475 */
1477 static VALUE
1479 {
1480 VALUE result;
1484 }
1491 }
1493 VALUE
1495 {
1496 VALUE top;
1502 }
1509 }
1511 /*
1512 * call-seq:
1513 * array.shift -> object or nil
1514 * array.shift(n) -> new_array
1515 *
1516 * Removes and returns leading elements.
1517 *
1518 * When no argument is given, removes and returns the first element:
1519 *
1520 * a = [:foo, 'bar', 2]
1521 * a.shift # => :foo
1522 * a # => ['bar', 2]
1523 *
1524 * Returns +nil+ if +self+ is empty.
1525 *
1526 * When positive Integer argument +n+ is given, removes the first +n+ elements;
1527 * returns those elements in a new +Array+:
1528 *
1529 * a = [:foo, 'bar', 2]
1530 * a.shift(2) # => [:foo, 'bar']
1531 * a # => [2]
1532 *
1533 * If +n+ is as large as or larger than <tt>self.length</tt>,
1534 * removes all elements; returns those elements in a new +Array+:
1535 *
1536 * a = [:foo, 'bar', 2]
1537 * a.shift(3) # => [:foo, 'bar', 2]
1538 *
1539 * If +n+ is zero, returns a new empty +Array+; +self+ is unmodified.
1540 *
1541 * Related: #push, #pop, #unshift.
1542 */
1544 static VALUE
1546 {
1547 VALUE result;
1552 }
1560 }
1562 VALUE
1564 {
1567 }
1579 }
1583 }
1586 }
1593 }
1595 static VALUE
1596 make_room_for_unshift(VALUE ary, const VALUE *head, VALUE *sharedp, int argc, long capa, long len)
1597 {
1604 }
1610 }
1612 static VALUE
1614 {
1624 }
1626 /* use shared array for big "queues" */
1630 /* make a room for unshifted items */
1636 }
1638 /* sliding items */
1641 });
1645 }
1646 }
1648 static VALUE
1650 {
1656 }
1659 }
1666 }
1669 }
1676 }
1677 }
1678 }
1680 /*
1681 * call-seq:
1682 * array.unshift(*objects) -> self
1683 *
1684 * Prepends the given +objects+ to +self+:
1685 *
1686 * a = [:foo, 'bar', 2]
1687 * a.unshift(:bam, :bat) # => [:bam, :bat, :foo, "bar", 2]
1688 *
1689 * Related: #push, #pop, #shift.
1690 */
1692 VALUE
1694 {
1696 VALUE target_ary;
1701 }
1707 }
1709 VALUE
1711 {
1713 }
1715 /* faster version - use this if you don't need to treat negative offset */
1718 {
1723 }
1725 }
1727 VALUE
1729 {
1731 }
1733 VALUE
1735 {
1736 VALUE klass;
1744 }
1751 else
1753 }
1755 VALUE
1757 {
1759 }
1763 /*
1764 * call-seq:
1765 * self[index] -> object or nil
1766 * self[start, length] -> object or nil
1767 * self[range] -> object or nil
1768 * self[aseq] -> object or nil
1769 * slice(index) -> object or nil
1770 * slice(start, length) -> object or nil
1771 * slice(range) -> object or nil
1772 * slice(aseq) -> object or nil
1773 *
1774 * Returns elements from +self+; does not modify +self+.
1775 *
1776 * In brief:
1777 *
1778 * a = [:foo, 'bar', 2]
1779 *
1780 * # Single argument index: returns one element.
1781 * a[0] # => :foo # Zero-based index.
1782 * a[-1] # => 2 # Negative index counts backwards from end.
1783 *
1784 * # Arguments start and length: returns an array.
1785 * a[1, 2] # => ["bar", 2]
1786 * a[-2, 2] # => ["bar", 2] # Negative start counts backwards from end.
1787 *
1788 * # Single argument range: returns an array.
1789 * a[0..1] # => [:foo, "bar"]
1790 * a[0..-2] # => [:foo, "bar"] # Negative range-begin counts backwards from end.
1791 * a[-2..2] # => ["bar", 2] # Negative range-end counts backwards from end.
1792 *
1793 * When a single integer argument +index+ is given, returns the element at offset +index+:
1794 *
1795 * a = [:foo, 'bar', 2]
1796 * a[0] # => :foo
1797 * a[2] # => 2
1798 * a # => [:foo, "bar", 2]
1799 *
1800 * If +index+ is negative, counts backwards from the end of +self+:
1801 *
1802 * a = [:foo, 'bar', 2]
1803 * a[-1] # => 2
1804 * a[-2] # => "bar"
1805 *
1806 * If +index+ is out of range, returns +nil+.
1807 *
1808 * When two Integer arguments +start+ and +length+ are given,
1809 * returns a new +Array+ of size +length+ containing successive elements beginning at offset +start+:
1810 *
1811 * a = [:foo, 'bar', 2]
1812 * a[0, 2] # => [:foo, "bar"]
1813 * a[1, 2] # => ["bar", 2]
1814 *
1815 * If <tt>start + length</tt> is greater than <tt>self.length</tt>,
1816 * returns all elements from offset +start+ to the end:
1817 *
1818 * a = [:foo, 'bar', 2]
1819 * a[0, 4] # => [:foo, "bar", 2]
1820 * a[1, 3] # => ["bar", 2]
1821 * a[2, 2] # => [2]
1822 *
1823 * If <tt>start == self.size</tt> and <tt>length >= 0</tt>,
1824 * returns a new empty +Array+.
1825 *
1826 * If +length+ is negative, returns +nil+.
1827 *
1828 * When a single Range argument +range+ is given,
1829 * treats <tt>range.min</tt> as +start+ above
1830 * and <tt>range.size</tt> as +length+ above:
1831 *
1832 * a = [:foo, 'bar', 2]
1833 * a[0..1] # => [:foo, "bar"]
1834 * a[1..2] # => ["bar", 2]
1835 *
1836 * Special case: If <tt>range.start == a.size</tt>, returns a new empty +Array+.
1837 *
1838 * If <tt>range.end</tt> is negative, calculates the end index from the end:
1839 *
1840 * a = [:foo, 'bar', 2]
1841 * a[0..-1] # => [:foo, "bar", 2]
1842 * a[0..-2] # => [:foo, "bar"]
1843 * a[0..-3] # => [:foo]
1844 *
1845 * If <tt>range.start</tt> is negative, calculates the start index from the end:
1846 *
1847 * a = [:foo, 'bar', 2]
1848 * a[-1..2] # => [2]
1849 * a[-2..2] # => ["bar", 2]
1850 * a[-3..2] # => [:foo, "bar", 2]
1851 *
1852 * If <tt>range.start</tt> is larger than the array size, returns +nil+.
1853 *
1854 * a = [:foo, 'bar', 2]
1855 * a[4..1] # => nil
1856 * a[4..0] # => nil
1857 * a[4..-1] # => nil
1858 *
1859 * When a single Enumerator::ArithmeticSequence argument +aseq+ is given,
1860 * returns an +Array+ of elements corresponding to the indexes produced by
1861 * the sequence.
1862 *
1863 * a = ['--', 'data1', '--', 'data2', '--', 'data3']
1864 * a[(1..).step(2)] # => ["data1", "data2", "data3"]
1865 *
1866 * Unlike slicing with range, if the start or the end of the arithmetic sequence
1867 * is larger than array size, throws RangeError.
1868 *
1869 * a = ['--', 'data1', '--', 'data2', '--', 'data3']
1870 * a[(1..11).step(2)]
1871 * # RangeError (((1..11).step(2)) out of range)
1872 * a[(7..).step(2)]
1873 * # RangeError (((7..).step(2)) out of range)
1874 *
1875 * If given a single argument, and its type is not one of the listed, tries to
1876 * convert it to Integer, and raises if it is impossible:
1877 *
1878 * a = [:foo, 'bar', 2]
1879 * # Raises TypeError (no implicit conversion of Symbol into Integer):
1880 * a[:foo]
1881 *
1882 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
1883 */
1885 VALUE
1887 {
1891 }
1893 }
1895 static VALUE
1897 {
1902 }
1904 }
1906 VALUE
1908 {
1911 /* special case - speeding up */
1914 }
1915 /* check if idx is Range or ArithmeticSequence */
1923 }
1926 }
1928 /*
1929 * call-seq:
1930 * at(index) -> object or nil
1931 *
1932 * Returns the element of +self+ specified by the given +index+
1933 * or +nil+ if there is no such element;
1934 * +index+ must be an
1935 * {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects].
1936 *
1937 * For non-negative +index+, returns the element of +self+ at offset +index+:
1938 *
1939 * a = [:foo, 'bar', 2]
1940 * a.at(0) # => :foo
1941 * a.at(2) # => 2
1942 * a.at(2.0) # => 2
1943 *
1944 * For negative +index+, counts backwards from the end of +self+:
1945 *
1946 * a.at(-2) # => "bar"
1947 *
1948 * Related: Array#[];
1949 * see also {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
1950 */
1952 VALUE
1954 {
1956 }
1958 #if 0
1959 static VALUE
1961 {
1965 }
1968 }
1969 }
1970 #endif
1972 static VALUE
1974 {
1976 }
1978 static VALUE
1980 {
1983 }
1985 VALUE
1987 {
1990 }
1993 }
1994 }
1996 /*
1997 * call-seq:
1998 * fetch(index) -> element
1999 * fetch(index, default_value) -> element or default_value
2000 * fetch(index) {|index| ... } -> element or block_return_value
2001 *
2002 * Returns the element of +self+ at offset +index+ if +index+ is in range; +index+ must be an
2003 * {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects].
2004 *
2005 * With the single argument +index+ and no block,
2006 * returns the element at offset +index+:
2007 *
2008 * a = [:foo, 'bar', 2]
2009 * a.fetch(1) # => "bar"
2010 * a.fetch(1.1) # => "bar"
2011 *
2012 * If +index+ is negative, counts from the end of the array:
2013 *
2014 * a = [:foo, 'bar', 2]
2015 * a.fetch(-1) # => 2
2016 * a.fetch(-2) # => "bar"
2017 *
2018 * With arguments +index+ and +default_value+ (which may be any object) and no block,
2019 * returns +default_value+ if +index+ is out-of-range:
2020 *
2021 * a = [:foo, 'bar', 2]
2022 * a.fetch(1, nil) # => "bar"
2023 * a.fetch(3, :foo) # => :foo
2024 *
2025 * With argument +index+ and a block,
2026 * returns the element at offset +index+ if index is in range
2027 * (and the block is not called); otherwise calls the block with index and returns its return value:
2028 *
2029 * a = [:foo, 'bar', 2]
2030 * a.fetch(1) {|index| raise 'Cannot happen' } # => "bar"
2031 * a.fetch(50) {|index| "Value for #{index}" } # => "Value for 50"
2032 *
2033 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
2034 */
2036 static VALUE
2038 {
2047 }
2052 }
2058 }
2060 }
2062 }
2064 /*
2065 * call-seq:
2066 * array.index(object) -> integer or nil
2067 * array.index {|element| ... } -> integer or nil
2068 * array.index -> new_enumerator
2069 *
2070 * Returns the index of a specified element.
2071 *
2072 * When argument +object+ is given but no block,
2073 * returns the index of the first element +element+
2074 * for which <tt>object == element</tt>:
2075 *
2076 * a = [:foo, 'bar', 2, 'bar']
2077 * a.index('bar') # => 1
2078 *
2079 * Returns +nil+ if no such element found.
2080 *
2081 * When both argument +object+ and a block are given,
2082 * calls the block with each successive element;
2083 * returns the index of the first element for which the block returns a truthy value:
2084 *
2085 * a = [:foo, 'bar', 2, 'bar']
2086 * a.index {|element| element == 'bar' } # => 1
2087 *
2088 * Returns +nil+ if the block never returns a truthy value.
2089 *
2090 * When neither an argument nor a block is given, returns a new Enumerator:
2091 *
2092 * a = [:foo, 'bar', 2]
2093 * e = a.index
2094 * e # => #<Enumerator: [:foo, "bar", 2]:index>
2095 * e.each {|element| element == 'bar' } # => 1
2096 *
2097 * Related: #rindex.
2098 */
2100 static VALUE
2102 {
2103 VALUE val;
2111 }
2112 }
2114 }
2123 }
2124 }
2126 }
2128 /*
2129 * call-seq:
2130 * array.rindex(object) -> integer or nil
2131 * array.rindex {|element| ... } -> integer or nil
2132 * array.rindex -> new_enumerator
2133 *
2134 * Returns the index of the last element for which <tt>object == element</tt>.
2135 *
2136 * When argument +object+ is given but no block, returns the index of the last such element found:
2137 *
2138 * a = [:foo, 'bar', 2, 'bar']
2139 * a.rindex('bar') # => 3
2140 *
2141 * Returns +nil+ if no such object found.
2142 *
2143 * When a block is given but no argument, calls the block with each successive element;
2144 * returns the index of the last element for which the block returns a truthy value:
2145 *
2146 * a = [:foo, 'bar', 2, 'bar']
2147 * a.rindex {|element| element == 'bar' } # => 3
2148 *
2149 * Returns +nil+ if the block never returns a truthy value.
2150 *
2151 * When neither an argument nor a block is given, returns a new Enumerator:
2152 *
2153 * a = [:foo, 'bar', 2, 'bar']
2154 * e = a.rindex
2155 * e # => #<Enumerator: [:foo, "bar", 2, "bar"]:rindex>
2156 * e.each {|element| element == 'bar' } # => 3
2157 *
2158 * Related: #index.
2159 */
2161 static VALUE
2163 {
2164 VALUE val;
2174 }
2175 }
2177 }
2186 }
2189 }
2190 }
2192 }
2194 VALUE
2196 {
2201 }
2203 static void
2205 {
2216 }
2217 }
2220 }
2222 {
2225 }
2228 VALUE target_ary;
2231 }
2238 }
2240 }
2246 }
2251 }
2258 }
2262 }
2264 /* In this case, we're copying from a region in this array, so
2265 * we don't need to fire the write barrier. */
2267 }
2269 /* do not use RARRAY_PTR() because it can causes GC.
2270 * ary can contain T_NONE object because it is not cleared.
2271 */
2274 }
2275 }
2276 }
2278 void
2280 {
2286 }
2289 }
2291 }
2293 VALUE
2295 {
2303 }
2307 }
2310 }
2313 }
2325 }
2330 }
2332 }
2335 }
2337 static VALUE
2339 {
2342 }
2344 static VALUE
2346 {
2351 }
2353 /*
2354 * call-seq:
2355 * self[index] = object -> object
2356 * self[start, length] = object -> object
2357 * self[range] = object -> object
2358 *
2359 * Assigns elements in +self+, based on the given +object+; returns +object+.
2360 *
2361 * In brief:
2362 *
2363 * a_orig = [:foo, 'bar', 2]
2364 *
2365 * # With argument index.
2366 * a = a_orig.dup
2367 * a[0] = 'foo' # => "foo"
2368 * a # => ["foo", "bar", 2]
2369 * a = a_orig.dup
2370 * a[7] = 'foo' # => "foo"
2371 * a # => [:foo, "bar", 2, nil, nil, nil, nil, "foo"]
2372 *
2373 * # With arguments start and length.
2374 * a = a_orig.dup
2375 * a[0, 2] = 'foo' # => "foo"
2376 * a # => ["foo", 2]
2377 * a = a_orig.dup
2378 * a[6, 50] = 'foo' # => "foo"
2379 * a # => [:foo, "bar", 2, nil, nil, nil, "foo"]
2380 *
2381 * # With argument range.
2382 * a = a_orig.dup
2383 * a[0..1] = 'foo' # => "foo"
2384 * a # => ["foo", 2]
2385 * a = a_orig.dup
2386 * a[6..50] = 'foo' # => "foo"
2387 * a # => [:foo, "bar", 2, nil, nil, nil, "foo"]
2388 *
2389 * When Integer argument +index+ is given, assigns +object+ to an element in +self+.
2390 *
2391 * If +index+ is non-negative, assigns +object+ the element at offset +index+:
2392 *
2393 * a = [:foo, 'bar', 2]
2394 * a[0] = 'foo' # => "foo"
2395 * a # => ["foo", "bar", 2]
2396 *
2397 * If +index+ is greater than <tt>self.length</tt>, extends the array:
2398 *
2399 * a = [:foo, 'bar', 2]
2400 * a[7] = 'foo' # => "foo"
2401 * a # => [:foo, "bar", 2, nil, nil, nil, nil, "foo"]
2402 *
2403 * If +index+ is negative, counts backwards from the end of the array:
2404 *
2405 * a = [:foo, 'bar', 2]
2406 * a[-1] = 'two' # => "two"
2407 * a # => [:foo, "bar", "two"]
2408 *
2409 * When Integer arguments +start+ and +length+ are given and +object+ is not an +Array+,
2410 * removes <tt>length - 1</tt> elements beginning at offset +start+,
2411 * and assigns +object+ at offset +start+:
2412 *
2413 * a = [:foo, 'bar', 2]
2414 * a[0, 2] = 'foo' # => "foo"
2415 * a # => ["foo", 2]
2416 *
2417 * If +start+ is negative, counts backwards from the end of the array:
2418 *
2419 * a = [:foo, 'bar', 2]
2420 * a[-2, 2] = 'foo' # => "foo"
2421 * a # => [:foo, "foo"]
2422 *
2423 * If +start+ is non-negative and outside the array (<tt> >= self.size</tt>),
2424 * extends the array with +nil+, assigns +object+ at offset +start+,
2425 * and ignores +length+:
2426 *
2427 * a = [:foo, 'bar', 2]
2428 * a[6, 50] = 'foo' # => "foo"
2429 * a # => [:foo, "bar", 2, nil, nil, nil, "foo"]
2430 *
2431 * If +length+ is zero, shifts elements at and following offset +start+
2432 * and assigns +object+ at offset +start+:
2433 *
2434 * a = [:foo, 'bar', 2]
2435 * a[1, 0] = 'foo' # => "foo"
2436 * a # => [:foo, "foo", "bar", 2]
2437 *
2438 * If +length+ is too large for the existing array, does not extend the array:
2439 *
2440 * a = [:foo, 'bar', 2]
2441 * a[1, 5] = 'foo' # => "foo"
2442 * a # => [:foo, "foo"]
2443 *
2444 * When Range argument +range+ is given and +object+ is not an +Array+,
2445 * removes <tt>length - 1</tt> elements beginning at offset +start+,
2446 * and assigns +object+ at offset +start+:
2447 *
2448 * a = [:foo, 'bar', 2]
2449 * a[0..1] = 'foo' # => "foo"
2450 * a # => ["foo", 2]
2451 *
2452 * if <tt>range.begin</tt> is negative, counts backwards from the end of the array:
2453 *
2454 * a = [:foo, 'bar', 2]
2455 * a[-2..2] = 'foo' # => "foo"
2456 * a # => [:foo, "foo"]
2457 *
2458 * If the array length is less than <tt>range.begin</tt>,
2459 * extends the array with +nil+, assigns +object+ at offset <tt>range.begin</tt>,
2460 * and ignores +length+:
2461 *
2462 * a = [:foo, 'bar', 2]
2463 * a[6..50] = 'foo' # => "foo"
2464 * a # => [:foo, "bar", 2, nil, nil, nil, "foo"]
2465 *
2466 * If <tt>range.end</tt> is zero, shifts elements at and following offset +start+
2467 * and assigns +object+ at offset +start+:
2468 *
2469 * a = [:foo, 'bar', 2]
2470 * a[1..0] = 'foo' # => "foo"
2471 * a # => [:foo, "foo", "bar", 2]
2472 *
2473 * If <tt>range.end</tt> is negative, assigns +object+ at offset +start+,
2474 * retains <tt>range.end.abs -1</tt> elements past that, and removes those beyond:
2475 *
2476 * a = [:foo, 'bar', 2]
2477 * a[1..-1] = 'foo' # => "foo"
2478 * a # => [:foo, "foo"]
2479 * a = [:foo, 'bar', 2]
2480 * a[1..-2] = 'foo' # => "foo"
2481 * a # => [:foo, "foo", 2]
2482 * a = [:foo, 'bar', 2]
2483 * a[1..-3] = 'foo' # => "foo"
2484 * a # => [:foo, "foo", "bar", 2]
2485 * a = [:foo, 'bar', 2]
2486 *
2487 * If <tt>range.end</tt> is too large for the existing array,
2488 * replaces array elements, but does not extend the array with +nil+ values:
2489 *
2490 * a = [:foo, 'bar', 2]
2491 * a[1..5] = 'foo' # => "foo"
2492 * a # => [:foo, "foo"]
2493 *
2494 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
2495 */
2497 static VALUE
2499 {
2508 }
2512 }
2514 /* check if idx is Range */
2516 }
2520 }
2522 /*
2523 * call-seq:
2524 * array.insert(index, *objects) -> self
2525 *
2526 * Inserts given +objects+ before or after the element at Integer index +offset+;
2527 * returns +self+.
2528 *
2529 * When +index+ is non-negative, inserts all given +objects+
2530 * before the element at offset +index+:
2531 *
2532 * a = [:foo, 'bar', 2]
2533 * a.insert(1, :bat, :bam) # => [:foo, :bat, :bam, "bar", 2]
2534 *
2535 * Extends the array if +index+ is beyond the array (<tt>index >= self.size</tt>):
2536 *
2537 * a = [:foo, 'bar', 2]
2538 * a.insert(5, :bat, :bam)
2539 * a # => [:foo, "bar", 2, nil, nil, :bat, :bam]
2540 *
2541 * Does nothing if no objects given:
2542 *
2543 * a = [:foo, 'bar', 2]
2544 * a.insert(1)
2545 * a.insert(50)
2546 * a.insert(-50)
2547 * a # => [:foo, "bar", 2]
2548 *
2549 * When +index+ is negative, inserts all given +objects+
2550 * _after_ the element at offset <tt>index+self.size</tt>:
2551 *
2552 * a = [:foo, 'bar', 2]
2553 * a.insert(-2, :bat, :bam)
2554 * a # => [:foo, "bar", :bat, :bam, 2]
2555 *
2556 */
2558 static VALUE
2560 {
2569 }
2575 }
2576 pos++;
2577 }
2580 }
2582 static VALUE
2585 static VALUE
2587 {
2589 }
2591 // Primitive to avoid a race condition in Array#each.
2592 // Return `true` and write `value` and `index` if the element exists.
2593 static VALUE
2595 {
2599 }
2603 }
2605 VALUE
2607 {
2613 }
2615 }
2617 /*
2618 * call-seq:
2619 * each_index {|index| ... } -> self
2620 * each_index -> new_enumerator
2621 *
2622 * With a block given, iterates over the elements of +self+,
2623 * passing each <i>array index</i> to the block;
2624 * returns +self+:
2625 *
2626 * a = [:foo, 'bar', 2]
2627 * a.each_index {|index| puts "#{index} #{a[index]}" }
2628 *
2629 * Output:
2630 *
2631 * 0 foo
2632 * 1 bar
2633 * 2 2
2634 *
2635 * Allows the array to be modified during iteration:
2636 *
2637 * a = [:foo, 'bar', 2]
2638 * a.each_index {|index| puts index; a.clear if index > 0 }
2639 *
2640 * Output:
2641 *
2642 * 0
2643 * 1
2644 *
2645 * With no block given, returns a new Enumerator.
2646 *
2647 * Related: see {Methods for Iterating}[rdoc-ref:Array@Methods+for+Iterating].
2648 */
2650 static VALUE
2652 {
2658 }
2660 }
2662 /*
2663 * call-seq:
2664 * array.reverse_each {|element| ... } -> self
2665 * array.reverse_each -> Enumerator
2666 *
2667 * Iterates backwards over array elements.
2668 *
2669 * When a block given, passes, in reverse order, each element to the block;
2670 * returns +self+:
2671 *
2672 * a = [:foo, 'bar', 2]
2673 * a.reverse_each {|element| puts "#{element.class} #{element}" }
2674 *
2675 * Output:
2676 *
2677 * Integer 2
2678 * String bar
2679 * Symbol foo
2680 *
2681 * Allows the array to be modified during iteration:
2682 *
2683 * a = [:foo, 'bar', 2]
2684 * a.reverse_each {|element| puts element; a.clear if element.to_s.start_with?('b') }
2685 *
2686 * Output:
2687 *
2688 * 2
2689 * bar
2690 *
2691 * When no block given, returns a new Enumerator:
2692 *
2693 * a = [:foo, 'bar', 2]
2694 * e = a.reverse_each
2695 * e # => #<Enumerator: [:foo, "bar", 2]:reverse_each>
2696 * a1 = e.each {|element| puts "#{element.class} #{element}" }
2697 *
2698 * Output:
2699 *
2700 * Integer 2
2701 * String bar
2702 * Symbol foo
2703 *
2704 * Related: #each, #each_index.
2705 */
2707 static VALUE
2709 {
2720 }
2721 }
2723 }
2725 /*
2726 * call-seq:
2727 * array.length -> an_integer
2728 *
2729 * Returns the count of elements in +self+.
2730 */
2732 static VALUE
2734 {
2737 }
2739 /*
2740 * call-seq:
2741 * array.empty? -> true or false
2742 *
2743 * Returns +true+ if the count of elements in +self+ is zero,
2744 * +false+ otherwise.
2745 *
2746 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
2747 */
2749 static VALUE
2751 {
2753 }
2755 VALUE
2757 {
2766 }
2768 VALUE
2770 {
2772 }
2778 static VALUE
2780 {
2789 }
2792 }
2794 }
2796 static long
2798 {
2800 VALUE val;
2809 }
2811 }
2813 static void
2815 {
2820 }
2821 }
2823 static void
2825 {
2828 }
2838 }
2839 }
2841 static void
2843 {
2853 }
2856 }
2859 }
2862 }
2865 }
2866 }
2867 }
2869 VALUE
2871 {
2880 }
2895 }
2898 }
2906 }
2908 /*
2909 * call-seq:
2910 * array.join ->new_string
2911 * array.join(separator = $,) -> new_string
2912 *
2913 * Returns the new String formed by joining the array elements after conversion.
2914 * For each element +element+:
2915 *
2916 * - Uses <tt>element.to_s</tt> if +element+ is not a <tt>kind_of?(Array)</tt>.
2917 * - Uses recursive <tt>element.join(separator)</tt> if +element+ is a <tt>kind_of?(Array)</tt>.
2918 *
2919 * With no argument, joins using the output field separator, <tt>$,</tt>:
2920 *
2921 * a = [:foo, 'bar', 2]
2922 * $, # => nil
2923 * a.join # => "foobar2"
2924 *
2925 * With \string argument +separator+, joins using that separator:
2926 *
2927 * a = [:foo, 'bar', 2]
2928 * a.join("\n") # => "foo\nbar\n2"
2929 *
2930 * Joins recursively for nested Arrays:
2931 *
2932 * a = [:foo, [:bar, [:baz, :bat]]]
2933 * a.join # => "foobarbazbat"
2934 *
2935 */
2936 static VALUE
2938 {
2939 VALUE sep;
2945 }
2946 }
2949 }
2951 static VALUE
2953 {
2964 }
2967 }
2969 /*
2970 * call-seq:
2971 * array.inspect -> new_string
2972 *
2973 * Returns the new String formed by calling method <tt>#inspect</tt>
2974 * on each array element:
2975 *
2976 * a = [:foo, 'bar', 2]
2977 * a.inspect # => "[:foo, \"bar\", 2]"
2978 *
2979 */
2981 static VALUE
2983 {
2986 }
2988 VALUE
2990 {
2992 }
2994 /*
2995 * call-seq:
2996 * to_a -> self or new_array
2997 *
2998 * When +self+ is an instance of +Array+, returns +self+:
2999 *
3000 * a = [:foo, 'bar', 2]
3001 * a.to_a # => [:foo, "bar", 2]
3002 *
3003 * Otherwise, returns a new +Array+ containing the elements of +self+:
3004 *
3005 * class MyArray < Array; end
3006 * a = MyArray.new(['foo', 'bar', 'two'])
3007 * a.instance_of?(Array) # => false
3008 * a.kind_of?(Array) # => true
3009 * a1 = a.to_a
3010 * a1 # => ["foo", "bar", "two"]
3011 * a1.class # => Array # Not MyArray
3012 *
3013 */
3015 static VALUE
3017 {
3022 }
3024 }
3026 /*
3027 * call-seq:
3028 * array.to_h -> new_hash
3029 * array.to_h {|item| ... } -> new_hash
3030 *
3031 * Returns a new Hash formed from +self+.
3032 *
3033 * When a block is given, calls the block with each array element;
3034 * the block must return a 2-element +Array+ whose two elements
3035 * form a key-value pair in the returned Hash:
3036 *
3037 * a = ['foo', :bar, 1, [2, 3], {baz: 4}]
3038 * h = a.to_h {|item| [item, item] }
3039 * h # => {"foo"=>"foo", :bar=>:bar, 1=>1, [2, 3]=>[2, 3], {:baz=>4}=>{:baz=>4}}
3040 *
3041 * When no block is given, +self+ must be an +Array+ of 2-element sub-arrays,
3042 * each sub-array is formed into a key-value pair in the new Hash:
3043 *
3044 * [].to_h # => {}
3045 * a = [['foo', 'zero'], ['bar', 'one'], ['baz', 'two']]
3046 * h = a.to_h
3047 * h # => {"foo"=>"zero", "bar"=>"one", "baz"=>"two"}
3048 *
3049 */
3051 static VALUE
3053 {
3065 }
3069 }
3071 }
3073 }
3075 /*
3076 * call-seq:
3077 * array.to_ary -> self
3078 *
3079 * Returns +self+.
3080 */
3082 static VALUE
3084 {
3086 }
3088 static void
3090 {
3095 }
3096 }
3098 VALUE
3100 {
3110 }
3112 }
3114 /*
3115 * call-seq:
3116 * array.reverse! -> self
3117 *
3118 * Reverses +self+ in place:
3119 *
3120 * a = ['foo', 'bar', 'two']
3121 * a.reverse! # => ["two", "bar", "foo"]
3122 *
3123 */
3125 static VALUE
3127 {
3129 }
3131 /*
3132 * call-seq:
3133 * array.reverse -> new_array
3134 *
3135 * Returns a new +Array+ with the elements of +self+ in reverse order:
3136 *
3137 * a = ['foo', 'bar', 'two']
3138 * a1 = a.reverse
3139 * a1 # => ["two", "bar", "foo"]
3140 *
3141 */
3143 static VALUE
3145 {
3153 }
3156 }
3160 {
3162 }
3164 static void
3166 {
3171 }
3176 }
3182 }
3183 }
3185 VALUE
3187 {
3195 }
3196 }
3198 }
3200 /*
3201 * call-seq:
3202 * array.rotate! -> self
3203 * array.rotate!(count) -> self
3204 *
3205 * Rotates +self+ in place by moving elements from one end to the other; returns +self+.
3206 *
3207 * When no argument given, rotates the first element to the last position:
3208 *
3209 * a = [:foo, 'bar', 2, 'bar']
3210 * a.rotate! # => ["bar", 2, "bar", :foo]
3211 *
3212 * When given a non-negative Integer +count+,
3213 * rotates +count+ elements from the beginning to the end:
3214 *
3215 * a = [:foo, 'bar', 2]
3216 * a.rotate!(2)
3217 * a # => [2, :foo, "bar"]
3218 *
3219 * If +count+ is large, uses <tt>count % array.size</tt> as the count:
3220 *
3221 * a = [:foo, 'bar', 2]
3222 * a.rotate!(20)
3223 * a # => [2, :foo, "bar"]
3224 *
3225 * If +count+ is zero, returns +self+ unmodified:
3226 *
3227 * a = [:foo, 'bar', 2]
3228 * a.rotate!(0)
3229 * a # => [:foo, "bar", 2]
3230 *
3231 * When given a negative Integer +count+, rotates in the opposite direction,
3232 * from end to beginning:
3233 *
3234 * a = [:foo, 'bar', 2]
3235 * a.rotate!(-2)
3236 * a # => ["bar", 2, :foo]
3237 *
3238 * If +count+ is small (far from zero), uses <tt>count % array.size</tt> as the count:
3239 *
3240 * a = [:foo, 'bar', 2]
3241 * a.rotate!(-5)
3242 * a # => ["bar", 2, :foo]
3243 *
3244 */
3246 static VALUE
3248 {
3252 }
3254 /*
3255 * call-seq:
3256 * array.rotate -> new_array
3257 * array.rotate(count) -> new_array
3258 *
3259 * Returns a new +Array+ formed from +self+ with elements
3260 * rotated from one end to the other.
3261 *
3262 * When no argument given, returns a new +Array+ that is like +self+,
3263 * except that the first element has been rotated to the last position:
3264 *
3265 * a = [:foo, 'bar', 2, 'bar']
3266 * a1 = a.rotate
3267 * a1 # => ["bar", 2, "bar", :foo]
3268 *
3269 * When given a non-negative Integer +count+,
3270 * returns a new +Array+ with +count+ elements rotated from the beginning to the end:
3271 *
3272 * a = [:foo, 'bar', 2]
3273 * a1 = a.rotate(2)
3274 * a1 # => [2, :foo, "bar"]
3275 *
3276 * If +count+ is large, uses <tt>count % array.size</tt> as the count:
3277 *
3278 * a = [:foo, 'bar', 2]
3279 * a1 = a.rotate(20)
3280 * a1 # => [2, :foo, "bar"]
3281 *
3282 * If +count+ is zero, returns a copy of +self+, unmodified:
3283 *
3284 * a = [:foo, 'bar', 2]
3285 * a1 = a.rotate(0)
3286 * a1 # => [:foo, "bar", 2]
3287 *
3288 * When given a negative Integer +count+, rotates in the opposite direction,
3289 * from end to beginning:
3290 *
3291 * a = [:foo, 'bar', 2]
3292 * a1 = a.rotate(-2)
3293 * a1 # => ["bar", 2, :foo]
3294 *
3295 * If +count+ is small (far from zero), uses <tt>count % array.size</tt> as the count:
3296 *
3297 * a = [:foo, 'bar', 2]
3298 * a1 = a.rotate(-5)
3299 * a1 # => ["bar", 2, :foo]
3300 *
3301 */
3303 static VALUE
3305 {
3306 VALUE rotated;
3319 }
3322 }
3325 VALUE ary;
3326 VALUE receiver;
3327 };
3329 static VALUE
3331 {
3334 }
3336 }
3338 static void
3340 {
3343 }
3345 }
3347 static int
3349 {
3362 }
3364 static int
3366 {
3376 }
3379 }
3382 }
3389 }
3391 /*
3392 * call-seq:
3393 * array.sort! -> self
3394 * array.sort! {|a, b| ... } -> self
3395 *
3396 * Returns +self+ with its elements sorted in place.
3397 *
3398 * With no block, compares elements using operator <tt><=></tt>
3399 * (see Comparable):
3400 *
3401 * a = 'abcde'.split('').shuffle
3402 * a # => ["e", "b", "d", "a", "c"]
3403 * a.sort!
3404 * a # => ["a", "b", "c", "d", "e"]
3405 *
3406 * With a block, calls the block with each element pair;
3407 * for each element pair +a+ and +b+, the block should return an integer:
3408 *
3409 * - Negative when +b+ is to follow +a+.
3410 * - Zero when +a+ and +b+ are equivalent.
3411 * - Positive when +a+ is to follow +b+.
3412 *
3413 * Example:
3414 *
3415 * a = 'abcde'.split('').shuffle
3416 * a # => ["e", "b", "d", "a", "c"]
3417 * a.sort! {|a, b| a <=> b }
3418 * a # => ["a", "b", "c", "d", "e"]
3419 * a.sort! {|a, b| b <=> a }
3420 * a # => ["e", "d", "c", "b", "a"]
3421 *
3422 * When the block returns zero, the order for +a+ and +b+ is indeterminate,
3423 * and may be unstable:
3424 *
3425 * a = 'abcde'.split('').shuffle
3426 * a # => ["e", "b", "d", "a", "c"]
3427 * a.sort! {|a, b| 0 }
3428 * a # => ["d", "e", "c", "a", "b"]
3429 *
3430 */
3432 VALUE
3434 {
3453 }
3456 }
3459 }
3464 }
3469 }
3471 /* ary might be destructively operated in the given block */
3473 }
3476 }
3480 }
3481 /* tmp was lost ownership for the ptr */
3486 }
3487 /* tmp will be GC'ed. */
3489 }
3492 }
3494 /*
3495 * call-seq:
3496 * array.sort -> new_array
3497 * array.sort {|a, b| ... } -> new_array
3498 *
3499 * Returns a new +Array+ whose elements are those from +self+, sorted.
3500 *
3501 * With no block, compares elements using operator <tt><=></tt>
3502 * (see Comparable):
3503 *
3504 * a = 'abcde'.split('').shuffle
3505 * a # => ["e", "b", "d", "a", "c"]
3506 * a1 = a.sort
3507 * a1 # => ["a", "b", "c", "d", "e"]
3508 *
3509 * With a block, calls the block with each element pair;
3510 * for each element pair +a+ and +b+, the block should return an integer:
3511 *
3512 * - Negative when +b+ is to follow +a+.
3513 * - Zero when +a+ and +b+ are equivalent.
3514 * - Positive when +a+ is to follow +b+.
3515 *
3516 * Example:
3517 *
3518 * a = 'abcde'.split('').shuffle
3519 * a # => ["e", "b", "d", "a", "c"]
3520 * a1 = a.sort {|a, b| a <=> b }
3521 * a1 # => ["a", "b", "c", "d", "e"]
3522 * a2 = a.sort {|a, b| b <=> a }
3523 * a2 # => ["e", "d", "c", "b", "a"]
3524 *
3525 * When the block returns zero, the order for +a+ and +b+ is indeterminate,
3526 * and may be unstable:
3527 *
3528 * a = 'abcde'.split('').shuffle
3529 * a # => ["e", "b", "d", "a", "c"]
3530 * a1 = a.sort {|a, b| 0 }
3531 * a1 # => ["c", "e", "b", "d", "a"]
3532 *
3533 * Related: Enumerable#sort_by.
3534 */
3536 VALUE
3538 {
3542 }
3546 /*
3547 * call-seq:
3548 * bsearch {|element| ... } -> found_element or nil
3549 * bsearch -> new_enumerator
3550 *
3551 * Returns the element from +self+ found by a binary search,
3552 * or +nil+ if the search found no suitable element.
3553 *
3554 * See {Binary Searching}[rdoc-ref:bsearch.rdoc].
3555 *
3556 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
3557 */
3559 static VALUE
3561 {
3566 }
3568 }
3570 /*
3571 * call-seq:
3572 * bsearch_index {|element| ... } -> integer or nil
3573 * bsearch_index -> new_enumerator
3574 *
3575 * Returns the integer index of the element from +self+ found by a binary search,
3576 * or +nil+ if the search found no suitable element.
3577 *
3578 * See {Binary Searching}[rdoc-ref:bsearch.rdoc].
3579 *
3580 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
3581 */
3583 static VALUE
3585 {
3598 }
3602 }
3605 }
3612 }
3613 }
3618 }
3621 }
3624 }
3625 }
3628 }
3631 static VALUE
3633 {
3635 }
3637 /*
3638 * call-seq:
3639 * array.sort_by! {|element| ... } -> self
3640 * array.sort_by! -> new_enumerator
3641 *
3642 * Sorts the elements of +self+ in place,
3643 * using an ordering determined by the block; returns self.
3644 *
3645 * Calls the block with each successive element;
3646 * sorts elements based on the values returned from the block.
3647 *
3648 * For duplicates returned by the block, the ordering is indeterminate, and may be unstable.
3649 *
3650 * This example sorts strings based on their sizes:
3651 *
3652 * a = ['aaaa', 'bbb', 'cc', 'd']
3653 * a.sort_by! {|element| element.size }
3654 * a # => ["d", "cc", "bbb", "aaaa"]
3655 *
3656 * Returns a new Enumerator if no block given:
3657 *
3658 * a = ['aaaa', 'bbb', 'cc', 'd']
3659 * a.sort_by! # => #<Enumerator: ["aaaa", "bbb", "cc", "d"]:sort_by!>
3660 *
3661 */
3663 static VALUE
3665 {
3666 VALUE sorted;
3673 }
3676 /*
3677 * call-seq:
3678 * collect {|element| ... } -> new_array
3679 * collect -> new_enumerator
3680 * map {|element| ... } -> new_array
3681 * map -> new_enumerator
3682 *
3683 * With a block given, calls the block with each element of +self+;
3684 * returns a new array whose elements are the return values from the block:
3685 *
3686 * a = [:foo, 'bar', 2]
3687 * a1 = a.map {|element| element.class }
3688 * a1 # => [Symbol, String, Integer]
3689 *
3690 * With no block given, returns a new Enumerator.
3691 *
3692 * Related: #collect!;
3693 * see also {Methods for Converting}[rdoc-ref:Array@Methods+for+Converting].
3694 */
3696 static VALUE
3698 {
3700 VALUE collect;
3706 }
3708 }
3711 /*
3712 * call-seq:
3713 * collect! {|element| ... } -> new_array
3714 * collect! -> new_enumerator
3715 * map! {|element| ... } -> new_array
3716 * map! -> new_enumerator
3717 *
3718 * With a block given, calls the block with each element of +self+
3719 * and replaces the element with the block's return value;
3720 * returns +self+:
3721 *
3722 * a = [:foo, 'bar', 2]
3723 * a.map! { |element| element.class } # => [Symbol, String, Integer]
3724 *
3725 * With no block given, returns a new Enumerator.
3726 *
3727 * Related: #collect;
3728 * see also {Methods for Converting}[rdoc-ref:Array@Methods+for+Converting].
3729 */
3731 static VALUE
3733 {
3740 }
3742 }
3744 VALUE
3745 rb_get_values_at(VALUE obj, long olen, int argc, const VALUE *argv, VALUE (*func) (VALUE, long))
3746 {
3754 }
3755 /* check if idx is Range */
3760 }
3764 }
3766 }
3768 }
3770 static VALUE
3772 {
3776 }
3777 /* check if idx is Range */
3785 }
3788 }
3789 }
3791 }
3794 }
3796 }
3798 /*
3799 * call-seq:
3800 * array.values_at(*indexes) -> new_array
3801 *
3802 * Returns a new +Array+ whose elements are the elements
3803 * of +self+ at the given Integer or Range +indexes+.
3804 *
3805 * For each positive +index+, returns the element at offset +index+:
3806 *
3807 * a = [:foo, 'bar', 2]
3808 * a.values_at(0, 2) # => [:foo, 2]
3809 * a.values_at(0..1) # => [:foo, "bar"]
3810 *
3811 * The given +indexes+ may be in any order, and may repeat:
3812 *
3813 * a = [:foo, 'bar', 2]
3814 * a.values_at(2, 0, 1, 0, 2) # => [2, :foo, "bar", :foo, 2]
3815 * a.values_at(1, 0..2) # => ["bar", :foo, "bar", 2]
3816 *
3817 * Assigns +nil+ for an +index+ that is too large:
3818 *
3819 * a = [:foo, 'bar', 2]
3820 * a.values_at(0, 3, 1, 3) # => [:foo, nil, "bar", nil]
3821 *
3822 * Returns a new empty +Array+ if no arguments given.
3823 *
3824 * For each negative +index+, counts backward from the end of the array:
3825 *
3826 * a = [:foo, 'bar', 2]
3827 * a.values_at(-1, -3) # => [2, :foo]
3828 *
3829 * Assigns +nil+ for an +index+ that is too small:
3830 *
3831 * a = [:foo, 'bar', 2]
3832 * a.values_at(0, -5, 1, -6, 2) # => [:foo, nil, "bar", nil, 2]
3833 *
3834 * The given +indexes+ may have a mixture of signs:
3835 *
3836 * a = [:foo, 'bar', 2]
3837 * a.values_at(0, -2, 1, -1) # => [:foo, "bar", "bar", 2]
3838 *
3839 */
3841 static VALUE
3843 {
3848 }
3851 }
3854 /*
3855 * call-seq:
3856 * array.select {|element| ... } -> new_array
3857 * array.select -> new_enumerator
3858 *
3859 * Calls the block, if given, with each element of +self+;
3860 * returns a new +Array+ containing those elements of +self+
3861 * for which the block returns a truthy value:
3862 *
3863 * a = [:foo, 'bar', 2, :bam]
3864 * a1 = a.select {|element| element.to_s.start_with?('b') }
3865 * a1 # => ["bar", :bam]
3866 *
3867 * Returns a new Enumerator if no block given:
3868 *
3869 * a = [:foo, 'bar', 2, :bam]
3870 * a.select # => #<Enumerator: [:foo, "bar", 2, :bam]:select>
3871 *
3872 */
3874 static VALUE
3876 {
3877 VALUE result;
3885 }
3886 }
3888 }
3891 VALUE ary;
3893 };
3895 static VALUE
3897 {
3907 }
3909 }
3911 }
3913 static VALUE
3915 {
3928 });
3929 }
3931 }
3933 }
3935 /*
3936 * call-seq:
3937 * array.select! {|element| ... } -> self or nil
3938 * array.select! -> new_enumerator
3939 *
3940 * Calls the block, if given with each element of +self+;
3941 * removes from +self+ those elements for which the block returns +false+ or +nil+.
3942 *
3943 * Returns +self+ if any elements were removed:
3944 *
3945 * a = [:foo, 'bar', 2, :bam]
3946 * a.select! {|element| element.to_s.start_with?('b') } # => ["bar", :bam]
3947 *
3948 * Returns +nil+ if no elements were removed.
3949 *
3950 * Returns a new Enumerator if no block given:
3951 *
3952 * a = [:foo, 'bar', 2, :bam]
3953 * a.select! # => #<Enumerator: [:foo, "bar", 2, :bam]:select!>
3954 *
3955 */
3957 static VALUE
3959 {
3968 }
3970 /*
3971 * call-seq:
3972 * array.keep_if {|element| ... } -> self
3973 * array.keep_if -> new_enumeration
3974 *
3975 * Retains those elements for which the block returns a truthy value;
3976 * deletes all other elements; returns +self+:
3977 *
3978 * a = [:foo, 'bar', 2, :bam]
3979 * a.keep_if {|element| element.to_s.start_with?('b') } # => ["bar", :bam]
3980 *
3981 * Returns a new Enumerator if no block given:
3982 *
3983 * a = [:foo, 'bar', 2, :bam]
3984 * a.keep_if # => #<Enumerator: [:foo, "bar", 2, :bam]:keep_if>
3985 *
3986 */
3988 static VALUE
3990 {
3994 }
3996 static void
3998 {
4005 }
4006 }
4007 }
4009 /*
4010 * call-seq:
4011 * delete(object) -> last_removed_object
4012 * delete(object) {|element| ... } -> last_removed_object or block_return
4013 *
4014 * Removes zero or more elements from +self+.
4015 *
4016 * With no block given,
4017 * removes from +self+ each element +ele+ such that <tt>ele == object</tt>;
4018 * returns the last removed element:
4019 *
4020 * a = [0, 1, 2, 2.0]
4021 * a.delete(2) # => 2.0
4022 * a # => [0, 1]
4023 *
4024 * Returns +nil+ if no elements removed:
4025 *
4026 * a.delete(2) # => nil
4027 *
4028 * With a block given,
4029 * removes from +self+ each element +ele+ such that <tt>ele == object</tt>.
4030 *
4031 * If any such elements are found, ignores the block
4032 * and returns the last removed element:
4033 *
4034 * a = [0, 1, 2, 2.0]
4035 * a.delete(2) {|element| fail 'Cannot happen' } # => 2.0
4036 * a # => [0, 1]
4037 *
4038 * If no such element is found, returns the block's return value:
4039 *
4040 * a.delete(2) {|element| "Element #{element} not found." }
4041 * # => "Element 2 not found."
4042 *
4043 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
4044 */
4046 VALUE
4048 {
4058 }
4061 }
4062 i2++;
4063 }
4067 }
4069 }
4075 }
4077 void
4079 {
4087 }
4090 }
4091 i2++;
4092 }
4095 }
4098 }
4100 VALUE
4102 {
4104 VALUE del;
4110 }
4116 });
4120 }
4122 /*
4123 * call-seq:
4124 * delete_at(index) -> removed_object or nil
4125 *
4126 * Removes the element of +self+ at the given +index+, which must be an
4127 * {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects].
4128 *
4129 * When +index+ is non-negative, deletes the element at offset +index+:
4130 *
4131 * a = [:foo, 'bar', 2]
4132 * a.delete_at(1) # => "bar"
4133 * a # => [:foo, 2]
4134 *
4135 * When +index+ is negative, counts backward from the end of the array:
4136 *
4137 * a = [:foo, 'bar', 2]
4138 * a.delete_at(-2) # => "bar"
4139 * a # => [:foo, 2]
4140 *
4141 * When +index+ is out of range, returns +nil+.
4142 *
4143 * a = [:foo, 'bar', 2]
4144 * a.delete_at(3) # => nil
4145 * a.delete_at(-4) # => nil
4146 *
4147 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
4148 */
4150 static VALUE
4152 {
4154 }
4156 static VALUE
4158 {
4163 }
4166 }
4169 }
4172 }
4175 }
4178 }
4183 }
4184 }
4186 /*
4187 * call-seq:
4188 * array.slice!(n) -> object or nil
4189 * array.slice!(start, length) -> new_array or nil
4190 * array.slice!(range) -> new_array or nil
4191 *
4192 * Removes and returns elements from +self+.
4193 *
4194 * When the only argument is an Integer +n+,
4195 * removes and returns the _nth_ element in +self+:
4196 *
4197 * a = [:foo, 'bar', 2]
4198 * a.slice!(1) # => "bar"
4199 * a # => [:foo, 2]
4200 *
4201 * If +n+ is negative, counts backwards from the end of +self+:
4202 *
4203 * a = [:foo, 'bar', 2]
4204 * a.slice!(-1) # => 2
4205 * a # => [:foo, "bar"]
4206 *
4207 * If +n+ is out of range, returns +nil+.
4208 *
4209 * When the only arguments are Integers +start+ and +length+,
4210 * removes +length+ elements from +self+ beginning at offset +start+;
4211 * returns the deleted objects in a new +Array+:
4212 *
4213 * a = [:foo, 'bar', 2]
4214 * a.slice!(0, 2) # => [:foo, "bar"]
4215 * a # => [2]
4216 *
4217 * If <tt>start + length</tt> exceeds the array size,
4218 * removes and returns all elements from offset +start+ to the end:
4219 *
4220 * a = [:foo, 'bar', 2]
4221 * a.slice!(1, 50) # => ["bar", 2]
4222 * a # => [:foo]
4223 *
4224 * If <tt>start == a.size</tt> and +length+ is non-negative,
4225 * returns a new empty +Array+.
4226 *
4227 * If +length+ is negative, returns +nil+.
4228 *
4229 * When the only argument is a Range object +range+,
4230 * treats <tt>range.min</tt> as +start+ above and <tt>range.size</tt> as +length+ above:
4231 *
4232 * a = [:foo, 'bar', 2]
4233 * a.slice!(1..2) # => ["bar", 2]
4234 * a # => [:foo]
4235 *
4236 * If <tt>range.start == a.size</tt>, returns a new empty +Array+.
4237 *
4238 * If <tt>range.start</tt> is larger than the array size, returns +nil+.
4239 *
4240 * If <tt>range.end</tt> is negative, counts backwards from the end of the array:
4241 *
4242 * a = [:foo, 'bar', 2]
4243 * a.slice!(0..-2) # => [:foo, "bar"]
4244 * a # => [2]
4245 *
4246 * If <tt>range.start</tt> is negative,
4247 * calculates the start index backwards from the end of the array:
4248 *
4249 * a = [:foo, 'bar', 2]
4250 * a.slice!(-2..2) # => ["bar", 2]
4251 * a # => [:foo]
4252 *
4253 */
4255 static VALUE
4257 {
4258 VALUE arg1;
4269 }
4274 /* valid range */
4277 /* invalid range */
4280 /* not a range */
4282 }
4283 }
4286 }
4288 static VALUE
4290 {
4298 }
4299 }
4301 }
4303 static VALUE
4305 {
4315 }
4317 }
4319 }
4321 static VALUE
4323 {
4329 }
4331 /*
4332 * call-seq:
4333 * array.reject! {|element| ... } -> self or nil
4334 * array.reject! -> new_enumerator
4335 *
4336 * Removes each element for which the block returns a truthy value.
4337 *
4338 * Returns +self+ if any elements removed:
4339 *
4340 * a = [:foo, 'bar', 2, 'bat']
4341 * a.reject! {|element| element.to_s.start_with?('b') } # => [:foo, 2]
4342 *
4343 * Returns +nil+ if no elements removed.
4344 *
4345 * Returns a new Enumerator if no block given:
4346 *
4347 * a = [:foo, 'bar', 2]
4348 * a.reject! # => #<Enumerator: [:foo, "bar", 2]:reject!>
4349 *
4350 */
4352 static VALUE
4354 {
4358 }
4360 /*
4361 * call-seq:
4362 * array.reject {|element| ... } -> new_array
4363 * array.reject -> new_enumerator
4364 *
4365 * Returns a new +Array+ whose elements are all those from +self+
4366 * for which the block returns +false+ or +nil+:
4367 *
4368 * a = [:foo, 'bar', 2, 'bat']
4369 * a1 = a.reject {|element| element.to_s.start_with?('b') }
4370 * a1 # => [:foo, 2]
4371 *
4372 * Returns a new Enumerator if no block given:
4373 *
4374 * a = [:foo, 'bar', 2]
4375 * a.reject # => #<Enumerator: [:foo, "bar", 2]:reject>
4376 *
4377 */
4379 static VALUE
4381 {
4382 VALUE rejected_ary;
4388 }
4390 /*
4391 * call-seq:
4392 * delete_if {|element| ... } -> self
4393 * delete_if -> new_numerator
4394 *
4395 * With a block given, calls the block with each element of +self+;
4396 * removes the element if the block returns a truthy value;
4397 * returns +self+:
4398 *
4399 * a = [:foo, 'bar', 2, 'bat']
4400 * a.delete_if {|element| element.to_s.start_with?('b') } # => [:foo, 2]
4401 *
4402 * With no block given, returns a new Enumerator.
4403 *
4404 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
4405 */
4407 static VALUE
4409 {
4414 }
4416 static VALUE
4418 {
4424 }
4426 static VALUE
4428 {
4440 }
4443 /*
4444 * call-seq:
4445 * array.zip(*other_arrays) -> new_array
4446 * array.zip(*other_arrays) {|other_array| ... } -> nil
4447 *
4448 * When no block given, returns a new +Array+ +new_array+ of size <tt>self.size</tt>
4449 * whose elements are Arrays.
4450 *
4451 * Each nested array <tt>new_array[n]</tt> is of size <tt>other_arrays.size+1</tt>,
4452 * and contains:
4453 *
4454 * - The _nth_ element of +self+.
4455 * - The _nth_ element of each of the +other_arrays+.
4456 *
4457 * If all +other_arrays+ and +self+ are the same size:
4458 *
4459 * a = [:a0, :a1, :a2, :a3]
4460 * b = [:b0, :b1, :b2, :b3]
4461 * c = [:c0, :c1, :c2, :c3]
4462 * d = a.zip(b, c)
4463 * d # => [[:a0, :b0, :c0], [:a1, :b1, :c1], [:a2, :b2, :c2], [:a3, :b3, :c3]]
4464 *
4465 * If any array in +other_arrays+ is smaller than +self+,
4466 * fills to <tt>self.size</tt> with +nil+:
4467 *
4468 * a = [:a0, :a1, :a2, :a3]
4469 * b = [:b0, :b1, :b2]
4470 * c = [:c0, :c1]
4471 * d = a.zip(b, c)
4472 * d # => [[:a0, :b0, :c0], [:a1, :b1, :c1], [:a2, :b2, nil], [:a3, nil, nil]]
4473 *
4474 * If any array in +other_arrays+ is larger than +self+,
4475 * its trailing elements are ignored:
4476 *
4477 * a = [:a0, :a1, :a2, :a3]
4478 * b = [:b0, :b1, :b2, :b3, :b4]
4479 * c = [:c0, :c1, :c2, :c3, :c4, :c5]
4480 * d = a.zip(b, c)
4481 * d # => [[:a0, :b0, :c0], [:a1, :b1, :c1], [:a2, :b2, :c2], [:a3, :b3, :c3]]
4482 *
4483 * If an argument is not an array, it extracts the values by calling #each:
4484 *
4485 * a = [:a0, :a1, :a2, :a2]
4486 * b = 1..4
4487 * c = a.zip(b)
4488 * c # => [[:a0, 1], [:a1, 2], [:a2, 3], [:a2, 4]]
4489 *
4490 * When a block is given, calls the block with each of the sub-arrays (formed as above); returns +nil+:
4491 *
4492 * a = [:a0, :a1, :a2, :a3]
4493 * b = [:b0, :b1, :b2, :b3]
4494 * c = [:c0, :c1, :c2, :c3]
4495 * a.zip(b, c) {|sub_array| p sub_array} # => nil
4496 *
4497 * Output:
4498 *
4499 * [:a0, :b0, :c0]
4500 * [:a1, :b1, :c1]
4501 * [:a2, :b2, :c2]
4502 * [:a3, :b3, :c3]
4503 *
4504 */
4506 static VALUE
4508 {
4515 }
4529 }
4531 }
4534 }
4542 }
4544 }
4545 }
4546 }
4556 }
4558 }
4559 }
4562 }
4564 /*
4565 * call-seq:
4566 * array.transpose -> new_array
4567 *
4568 * Transposes the rows and columns in an +Array+ of Arrays;
4569 * the nested Arrays must all be the same size:
4570 *
4571 * a = [[:a0, :a1], [:b0, :b1], [:c0, :c1]]
4572 * a.transpose # => [[:a0, :b0, :c0], [:a1, :b1, :c1]]
4573 *
4574 */
4576 static VALUE
4578 {
4591 }
4592 }
4596 }
4599 }
4600 }
4602 }
4604 /*
4605 * call-seq:
4606 * array.replace(other_array) -> self
4607 *
4608 * Replaces the content of +self+ with the content of +other_array+; returns +self+:
4609 *
4610 * a = [:foo, 'bar', 2]
4611 * a.replace(['foo', :bar, 3]) # => ["foo", :bar, 3]
4612 *
4613 */
4615 VALUE
4617 {
4624 /* orig has enough space to embed the contents of orig. */
4629 }
4630 /* orig is embedded but copy does not have enough space to embed the
4631 * contents of orig. */
4641 // No allocation and exception expected that could leave `copy` in a
4642 // bad state from the edits above.
4644 }
4645 /* Otherwise, orig is on heap and copy does not have enough space to embed
4646 * the contents of orig. */
4653 }
4656 }
4658 /*
4659 * call-seq:
4660 * clear -> self
4661 *
4662 * Removes all elements from +self+; returns +self+:
4663 *
4664 * a = [:foo, 'bar', 2]
4665 * a.clear # => []
4666 *
4667 * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
4668 */
4670 VALUE
4672 {
4678 }
4683 }
4684 }
4687 }
4689 /*
4690 * call-seq:
4691 * array.fill(obj) -> self
4692 * array.fill(obj, start) -> self
4693 * array.fill(obj, start, length) -> self
4694 * array.fill(obj, range) -> self
4695 * array.fill {|index| ... } -> self
4696 * array.fill(start) {|index| ... } -> self
4697 * array.fill(start, length) {|index| ... } -> self
4698 * array.fill(range) {|index| ... } -> self
4699 *
4700 * Replaces specified elements in +self+ with specified objects; returns +self+.
4701 *
4702 * With argument +obj+ and no block given, replaces all elements with that one object:
4703 *
4704 * a = ['a', 'b', 'c', 'd']
4705 * a # => ["a", "b", "c", "d"]
4706 * a.fill(:X) # => [:X, :X, :X, :X]
4707 *
4708 * With arguments +obj+ and Integer +start+, and no block given,
4709 * replaces elements based on the given start.
4710 *
4711 * If +start+ is in range (<tt>0 <= start < array.size</tt>),
4712 * replaces all elements from offset +start+ through the end:
4713 *
4714 * a = ['a', 'b', 'c', 'd']
4715 * a.fill(:X, 2) # => ["a", "b", :X, :X]
4716 *
4717 * If +start+ is too large (<tt>start >= array.size</tt>), does nothing:
4718 *
4719 * a = ['a', 'b', 'c', 'd']
4720 * a.fill(:X, 4) # => ["a", "b", "c", "d"]
4721 * a = ['a', 'b', 'c', 'd']
4722 * a.fill(:X, 5) # => ["a", "b", "c", "d"]
4723 *
4724 * If +start+ is negative, counts from the end (starting index is <tt>start + array.size</tt>):
4725 *
4726 * a = ['a', 'b', 'c', 'd']
4727 * a.fill(:X, -2) # => ["a", "b", :X, :X]
4728 *
4729 * If +start+ is too small (less than and far from zero), replaces all elements:
4730 *
4731 * a = ['a', 'b', 'c', 'd']
4732 * a.fill(:X, -6) # => [:X, :X, :X, :X]
4733 * a = ['a', 'b', 'c', 'd']
4734 * a.fill(:X, -50) # => [:X, :X, :X, :X]
4735 *
4736 * With arguments +obj+, Integer +start+, and Integer +length+, and no block given,
4737 * replaces elements based on the given +start+ and +length+.
4738 *
4739 * If +start+ is in range, replaces +length+ elements beginning at offset +start+:
4740 *
4741 * a = ['a', 'b', 'c', 'd']
4742 * a.fill(:X, 1, 1) # => ["a", :X, "c", "d"]
4743 *
4744 * If +start+ is negative, counts from the end:
4745 *
4746 * a = ['a', 'b', 'c', 'd']
4747 * a.fill(:X, -2, 1) # => ["a", "b", :X, "d"]
4748 *
4749 * If +start+ is large (<tt>start >= array.size</tt>), extends +self+ with +nil+:
4750 *
4751 * a = ['a', 'b', 'c', 'd']
4752 * a.fill(:X, 5, 0) # => ["a", "b", "c", "d", nil]
4753 * a = ['a', 'b', 'c', 'd']
4754 * a.fill(:X, 5, 2) # => ["a", "b", "c", "d", nil, :X, :X]
4755 *
4756 * If +length+ is zero or negative, replaces no elements:
4757 *
4758 * a = ['a', 'b', 'c', 'd']
4759 * a.fill(:X, 1, 0) # => ["a", "b", "c", "d"]
4760 * a.fill(:X, 1, -1) # => ["a", "b", "c", "d"]
4761 *
4762 * With arguments +obj+ and Range +range+, and no block given,
4763 * replaces elements based on the given range.
4764 *
4765 * If the range is positive and ascending (<tt>0 < range.begin <= range.end</tt>),
4766 * replaces elements from <tt>range.begin</tt> to <tt>range.end</tt>:
4767 *
4768 * a = ['a', 'b', 'c', 'd']
4769 * a.fill(:X, (1..1)) # => ["a", :X, "c", "d"]
4770 *
4771 * If <tt>range.first</tt> is negative, replaces no elements:
4772 *
4773 * a = ['a', 'b', 'c', 'd']
4774 * a.fill(:X, (-1..1)) # => ["a", "b", "c", "d"]
4775 *
4776 * If <tt>range.last</tt> is negative, counts from the end:
4777 *
4778 * a = ['a', 'b', 'c', 'd']
4779 * a.fill(:X, (0..-2)) # => [:X, :X, :X, "d"]
4780 * a = ['a', 'b', 'c', 'd']
4781 * a.fill(:X, (1..-2)) # => ["a", :X, :X, "d"]
4782 *
4783 * If <tt>range.last</tt> and <tt>range.last</tt> are both negative,
4784 * both count from the end of the array:
4785 *
4786 * a = ['a', 'b', 'c', 'd']
4787 * a.fill(:X, (-1..-1)) # => ["a", "b", "c", :X]
4788 * a = ['a', 'b', 'c', 'd']
4789 * a.fill(:X, (-2..-2)) # => ["a", "b", :X, "d"]
4790 *
4791 * With no arguments and a block given, calls the block with each index;
4792 * replaces the corresponding element with the block's return value:
4793 *
4794 * a = ['a', 'b', 'c', 'd']
4795 * a.fill { |index| "new_#{index}" } # => ["new_0", "new_1", "new_2", "new_3"]
4796 *
4797 * With argument +start+ and a block given, calls the block with each index
4798 * from offset +start+ to the end; replaces the corresponding element
4799 * with the block's return value.
4800 *
4801 * If start is in range (<tt>0 <= start < array.size</tt>),
4802 * replaces from offset +start+ to the end:
4803 *
4804 * a = ['a', 'b', 'c', 'd']
4805 * a.fill(1) { |index| "new_#{index}" } # => ["a", "new_1", "new_2", "new_3"]
4806 *
4807 * If +start+ is too large(<tt>start >= array.size</tt>), does nothing:
4808 *
4809 * a = ['a', 'b', 'c', 'd']
4810 * a.fill(4) { |index| fail 'Cannot happen' } # => ["a", "b", "c", "d"]
4811 * a = ['a', 'b', 'c', 'd']
4812 * a.fill(4) { |index| fail 'Cannot happen' } # => ["a", "b", "c", "d"]
4813 *
4814 * If +start+ is negative, counts from the end:
4815 *
4816 * a = ['a', 'b', 'c', 'd']
4817 * a.fill(-2) { |index| "new_#{index}" } # => ["a", "b", "new_2", "new_3"]
4818 *
4819 * If start is too small (<tt>start <= -array.size</tt>, replaces all elements:
4820 *
4821 * a = ['a', 'b', 'c', 'd']
4822 * a.fill(-6) { |index| "new_#{index}" } # => ["new_0", "new_1", "new_2", "new_3"]
4823 * a = ['a', 'b', 'c', 'd']
4824 * a.fill(-50) { |index| "new_#{index}" } # => ["new_0", "new_1", "new_2", "new_3"]
4825 *
4826 * With arguments +start+ and +length+, and a block given,
4827 * calls the block for each index specified by start length;
4828 * replaces the corresponding element with the block's return value.
4829 *
4830 * If +start+ is in range, replaces +length+ elements beginning at offset +start+:
4831 *
4832 * a = ['a', 'b', 'c', 'd']
4833 * a.fill(1, 1) { |index| "new_#{index}" } # => ["a", "new_1", "c", "d"]
4834 *
4835 * If start is negative, counts from the end:
4836 *
4837 * a = ['a', 'b', 'c', 'd']
4838 * a.fill(-2, 1) { |index| "new_#{index}" } # => ["a", "b", "new_2", "d"]
4839 *
4840 * If +start+ is large (<tt>start >= array.size</tt>), extends +self+ with +nil+:
4841 *
4842 * a = ['a', 'b', 'c', 'd']
4843 * a.fill(5, 0) { |index| "new_#{index}" } # => ["a", "b", "c", "d", nil]
4844 * a = ['a', 'b', 'c', 'd']
4845 * a.fill(5, 2) { |index| "new_#{index}" } # => ["a", "b", "c", "d", nil, "new_5", "new_6"]
4846 *
4847 * If +length+ is zero or less, replaces no elements:
4848 *
4849 * a = ['a', 'b', 'c', 'd']
4850 * a.fill(1, 0) { |index| "new_#{index}" } # => ["a", "b", "c", "d"]
4851 * a.fill(1, -1) { |index| "new_#{index}" } # => ["a", "b", "c", "d"]
4852 *
4853 * With arguments +obj+ and +range+, and a block given,
4854 * calls the block with each index in the given range;
4855 * replaces the corresponding element with the block's return value.
4856 *
4857 * If the range is positive and ascending (<tt>range 0 < range.begin <= range.end</tt>,
4858 * replaces elements from <tt>range.begin</tt> to <tt>range.end</tt>:
4859 *
4860 * a = ['a', 'b', 'c', 'd']
4861 * a.fill(1..1) { |index| "new_#{index}" } # => ["a", "new_1", "c", "d"]
4862 *
4863 * If +range.first+ is negative, does nothing:
4864 *
4865 * a = ['a', 'b', 'c', 'd']
4866 * a.fill(-1..1) { |index| fail 'Cannot happen' } # => ["a", "b", "c", "d"]
4867 *
4868 * If <tt>range.last</tt> is negative, counts from the end:
4869 *
4870 * a = ['a', 'b', 'c', 'd']
4871 * a.fill(0..-2) { |index| "new_#{index}" } # => ["new_0", "new_1", "new_2", "d"]
4872 * a = ['a', 'b', 'c', 'd']
4873 * a.fill(1..-2) { |index| "new_#{index}" } # => ["a", "new_1", "new_2", "d"]
4874 *
4875 * If <tt>range.first</tt> and <tt>range.last</tt> are both negative,
4876 * both count from the end:
4877 *
4878 * a = ['a', 'b', 'c', 'd']
4879 * a.fill(-1..-1) { |index| "new_#{index}" } # => ["a", "b", "c", "new_3"]
4880 * a = ['a', 'b', 'c', 'd']
4881 * a.fill(-2..-2) { |index| "new_#{index}" } # => ["a", "b", "new_2", "d"]
4882 *
4883 */
4885 static VALUE
4887 {
4894 }
4897 }
4906 }
4907 /* fall through */
4913 }
4916 }
4920 }
4923 }
4928 }
4931 }
4934 VALUE v;
4941 }
4942 }
4945 }
4947 }
4949 /*
4950 * call-seq:
4951 * self + other_array -> new_array
4952 *
4953 * Returns a new array containing all elements of +self+
4954 * followed by all elements of +other_array+:
4955 *
4956 * a = [0, 1] + [2, 3]
4957 * a # => [0, 1, 2, 3]
4958 *
4959 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
4960 */
4962 VALUE
4964 {
4965 VALUE z;
4978 }
4980 static VALUE
4982 {
4986 }
4989 }
4991 /*
4992 * call-seq:
4993 * concat(*other_arrays) -> self
4994 *
4995 * Adds to +self+ all elements from each array in +other_arrays+; returns +self+:
4996 *
4997 * a = [0, 1]
4998 * a.concat(['two', 'three'], [:four, :five], a)
4999 * # => [0, 1, "two", "three", :four, :five, 0, 1]
5000 *
5001 * Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning].
5002 */
5004 static VALUE
5006 {
5011 }
5017 }
5019 }
5023 }
5025 VALUE
5027 {
5029 }
5031 /*
5032 * call-seq:
5033 * self * n -> new_array
5034 * self * string_separator -> new_string
5035 *
5036 * When non-negative integer argument +n+ is given,
5037 * returns a new array built by concatenating +n+ copies of +self+:
5038 *
5039 * a = ['x', 'y']
5040 * a * 3 # => ["x", "y", "x", "y", "x", "y"]
5041 *
5042 * When string argument +string_separator+ is given,
5043 * equivalent to <tt>array.join(string_separator)</tt>:
5044 *
5045 * [0, [0, 1], {foo: 0}] * ', ' # => "0, 0, 1, {:foo=>0}"
5046 *
5047 */
5049 static VALUE
5051 {
5059 }
5065 }
5068 }
5071 }
5084 }
5087 }
5088 }
5089 out:
5091 }
5093 /*
5094 * call-seq:
5095 * assoc(object) -> found_array or nil
5096 *
5097 * Returns the first element +ele+ in +self+ such that +ele+ is an array
5098 * and <tt>ele[0] == object</tt>:
5099 *
5100 * a = [{foo: 0}, [2, 4], [4, 5, 6], [4, 5]]
5101 * a.assoc(4) # => [4, 5, 6]
5102 *
5103 * Returns +nil+ if no such element is found.
5104 *
5105 * Related: Array#rassoc;
5106 * see also {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
5107 */
5109 VALUE
5111 {
5113 VALUE v;
5120 }
5122 }
5124 /*
5125 * call-seq:
5126 * array.rassoc(obj) -> found_array or nil
5127 *
5128 * Returns the first element in +self+ that is an +Array+
5129 * whose second element <tt>==</tt> +obj+:
5130 *
5131 * a = [{foo: 0}, [2, 4], [4, 5, 6], [4, 5]]
5132 * a.rassoc(4) # => [2, 4]
5133 *
5134 * Returns +nil+ if no such element is found.
5135 *
5136 * Related: #assoc.
5137 */
5139 VALUE
5141 {
5143 VALUE v;
5151 }
5153 }
5155 static VALUE
5157 {
5163 /* rb_equal() can evacuate ptrs */
5178 }
5181 }
5182 }
5183 p1++;
5184 p2++;
5185 }
5187 }
5189 /*
5190 * call-seq:
5191 * self == other_array -> true or false
5192 *
5193 * Returns whether both:
5194 *
5195 * - +self+ and +other_array+ are the same size.
5196 * - Their corresponding elements are the same;
5197 * that is, for each index +i+ in <tt>(0...self.size)</tt>,
5198 * <tt>self[i] == other_array[i]</tt>.
5199 *
5200 * Examples:
5201 *
5202 * [:foo, 'bar', 2] == [:foo, 'bar', 2] # => true
5203 * [:foo, 'bar', 2] == [:foo, 'bar', 2.0] # => true
5204 * [:foo, 'bar', 2] == [:foo, 'bar'] # => false # Different sizes.
5205 * [:foo, 'bar', 2] == [:foo, 'bar', 3] # => false # Different elements.
5206 *
5207 * This method is different from method Array#eql?,
5208 * which compares elements using <tt>Object#eql?</tt>.
5209 *
5210 * Related: see {Methods for Comparing}[rdoc-ref:Array@Methods+for+Comparing].
5211 */
5213 static VALUE
5215 {
5220 }
5222 }
5226 }
5228 static VALUE
5230 {
5237 }
5239 }
5241 /*
5242 * call-seq:
5243 * eql?(other_array) -> true or false
5244 *
5245 * Returns +true+ if +self+ and +other_array+ are the same size,
5246 * and if, for each index +i+ in +self+, <tt>self[i].eql?(other_array[i])</tt>:
5247 *
5248 * a0 = [:foo, 'bar', 2]
5249 * a1 = [:foo, 'bar', 2]
5250 * a1.eql?(a0) # => true
5251 *
5252 * Otherwise, returns +false+.
5253 *
5254 * This method is different from method Array#==,
5255 * which compares using method <tt>Object#==</tt>.
5256 *
5257 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
5258 */
5260 static VALUE
5262 {
5268 }
5270 VALUE
5272 {
5274 st_index_t h;
5275 VALUE n;
5282 }
5285 }
5287 /*
5288 * call-seq:
5289 * array.hash -> integer
5290 *
5291 * Returns the integer hash value for +self+.
5292 *
5293 * Two arrays with the same content will have the same hash code (and will compare using #eql?):
5294 *
5295 * [0, 1, 2].hash == [0, 1, 2].hash # => true
5296 * [0, 1, 2].hash == [0, 1, 3].hash # => false
5297 *
5298 */
5300 static VALUE
5302 {
5304 }
5306 /*
5307 * call-seq:
5308 * array.include?(obj) -> true or false
5309 *
5310 * Returns +true+ if for some index +i+ in +self+, <tt>obj == self[i]</tt>;
5311 * otherwise +false+:
5312 *
5313 * [0, 1, 2].include?(2) # => true
5314 * [0, 1, 2].include?(3) # => false
5315 */
5317 VALUE
5319 {
5321 VALUE e;
5327 }
5328 }
5330 }
5332 static VALUE
5334 {
5336 VALUE e;
5342 }
5343 }
5345 }
5347 static VALUE
5349 {
5356 }
5362 }
5363 }
5365 }
5367 /*
5368 * call-seq:
5369 * self <=> other_array -> -1, 0, or 1
5370 *
5371 * Returns -1, 0, or 1 as +self+ is determined
5372 * to be less than, equal to, or greater than +other_array+.
5373 *
5374 * Iterates over each index +i+ in <tt>(0...self.size)</tt>:
5375 *
5376 * - Computes <tt>result[i]</tt> as <tt>self[i] <=> other_array[i]</tt>.
5377 * - Immediately returns 1 if <tt>result[i]</tt> is 1:
5378 *
5379 * [0, 1, 2] <=> [0, 0, 2] # => 1
5380 *
5381 * - Immediately returns -1 if <tt>result[i]</tt> is -1:
5382 *
5383 * [0, 1, 2] <=> [0, 2, 2] # => -1
5384 *
5385 * - Continues if <tt>result[i]</tt> is 0.
5386 *
5387 * When every +result+ is 0,
5388 * returns <tt>self.size <=> other_array.size</tt>
5389 * (see Integer#<=>):
5390 *
5391 * [0, 1, 2] <=> [0, 1] # => 1
5392 * [0, 1, 2] <=> [0, 1, 2] # => 0
5393 * [0, 1, 2] <=> [0, 1, 2, 3] # => -1
5394 *
5395 * Note that when +other_array+ is larger than +self+,
5396 * its trailing elements do not affect the result:
5397 *
5398 * [0, 1, 2] <=> [0, 1, 2, -3] # => -1
5399 * [0, 1, 2] <=> [0, 1, 2, 0] # => -1
5400 * [0, 1, 2] <=> [0, 1, 2, 3] # => -1
5401 *
5402 * Related: see {Methods for Comparing}[rdoc-ref:Array@Methods+for+Comparing].
5403 */
5405 VALUE
5407 {
5409 VALUE v;
5420 }
5422 static VALUE
5424 {
5430 }
5432 }
5436 {
5442 }
5444 static VALUE
5446 {
5449 }
5451 static VALUE
5453 {
5459 }
5461 }
5463 static VALUE
5465 {
5468 }
5470 /*
5471 * call-seq:
5472 * self - other_array -> new_array
5473 *
5474 * Returns a new array containing only those elements of +self+
5475 * that are not found in +other_array+;
5476 * the order from +self+ is preserved:
5477 *
5478 * [0, 1, 1, 2, 1, 1, 3, 1, 1] - [1] # => [0, 2, 3]
5479 * [0, 1, 1, 2, 1, 1, 3, 1, 1] - [3, 2, 0, :foo] # => [1, 1, 1, 1, 1, 1]
5480 * [0, 1, 2] - [:foo] # => [0, 1, 2]
5481 *
5482 * Element are compared using method <tt>#eql?</tt>
5483 * (as defined in each element of +self+).
5484 *
5485 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
5486 */
5488 VALUE
5490 {
5491 VALUE ary3;
5492 VALUE hash;
5504 }
5506 }
5512 }
5515 }
5517 /*
5518 * call-seq:
5519 * difference(*other_arrays = []) -> new_array
5520 *
5521 * Returns a new array containing only those elements from +self+
5522 * that are not found in any of the given +other_arrays+;
5523 * items are compared using <tt>eql?</tt>; order from +self+ is preserved:
5524 *
5525 * [0, 1, 1, 2, 1, 1, 3, 1, 1].difference([1]) # => [0, 2, 3]
5526 * [0, 1, 2, 3].difference([3, 0], [1, 3]) # => [2]
5527 * [0, 1, 2].difference([4]) # => [0, 1, 2]
5528 * [0, 1, 2].difference # => [0, 1, 2]
5529 *
5530 * Returns a copy of +self+ if no arguments are given.
5531 *
5532 * Related: Array#-;
5533 * see also {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
5534 */
5536 static VALUE
5538 {
5539 VALUE ary_diff;
5550 }
5559 }
5562 }
5563 }
5565 }
5570 }
5573 /*
5574 * call-seq:
5575 * self & other_array -> new_array
5576 *
5577 * Returns a new array containing the _intersection_ of +self+ and +other_array+;
5578 * that is, containing those elements found in both +self+ and +other_array+:
5579 *
5580 * [0, 1, 2, 3] & [1, 2] # => [1, 2]
5581 *
5582 * Omits duplicates:
5583 *
5584 * [0, 1, 1, 0] & [0, 1] # => [0, 1]
5585 *
5586 * Preserves order from +self+:
5587 *
5588 * [0, 1, 2] & [3, 2, 1, 0] # => [0, 1, 2]
5589 *
5590 * Identifies common elements using method <tt>#eql?</tt>
5591 * (as defined in each element of +self+).
5592 *
5593 * Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
5594 */
5597 static VALUE
5599 {
5601 st_data_t vv;
5614 }
5616 }
5625 }
5626 }
5629 }
5631 /*
5632 * call-seq:
5633 * array.intersection(*other_arrays) -> new_array
5634 *
5635 * Returns a new +Array+ containing each element found both in +self+
5636 * and in all of the given Arrays +other_arrays+;
5637 * duplicates are omitted; items are compared using <tt>eql?</tt>
5638 * (items must also implement +hash+ correctly):
5639 *
5640 * [0, 1, 2, 3].intersection([0, 1, 2], [0, 1, 3]) # => [0, 1]
5641 * [0, 0, 1, 1, 2, 3].intersection([0, 1, 2], [0, 1, 3]) # => [0, 1]
5642 *
5643 * Preserves order from +self+:
5644 *
5645 * [0, 1, 2].intersection([2, 1, 0]) # => [0, 1, 2]
5646 *
5647 * Returns a copy of +self+ if no arguments given.
5648 *
5649 * Related: Array#&.
5650 */
5652 static VALUE
5654 {
5660 }
5663 }
5665 static int
5667 {
5671 }
5673 static void
5675 {
5681 }
5682 }
5684 static void
5686 {
5692 }
5693 }
5694 }
5696 /*
5697 * call-seq:
5698 * array | other_array -> new_array
5699 *
5700 * Returns the union of +array+ and +Array+ +other_array+;
5701 * duplicates are removed; order is preserved;
5702 * items are compared using <tt>eql?</tt>:
5703 *
5704 * [0, 1] | [2, 3] # => [0, 1, 2, 3]
5705 * [0, 1, 1] | [2, 2, 3] # => [0, 1, 2, 3]
5706 * [0, 1, 2] | [3, 2, 1, 0] # => [0, 1, 2, 3]
5707 *
5708 * Related: Array#union.
5709 */
5711 static VALUE
5713 {
5714 VALUE hash;
5722 }
5728 }
5730 /*
5731 * call-seq:
5732 * array.union(*other_arrays) -> new_array
5733 *
5734 * Returns a new +Array+ that is the union of +self+ and all given Arrays +other_arrays+;
5735 * duplicates are removed; order is preserved; items are compared using <tt>eql?</tt>:
5736 *
5737 * [0, 1, 2, 3].union([4, 5], [6, 7]) # => [0, 1, 2, 3, 4, 5, 6, 7]
5738 * [0, 1, 1].union([2, 1], [3, 1]) # => [0, 1, 2, 3]
5739 * [0, 1, 2, 3].union([3, 2], [1, 0]) # => [0, 1, 2, 3]
5740 *
5741 * Returns a copy of +self+ if no arguments given.
5742 *
5743 * Related: Array#|.
5744 */
5746 static VALUE
5748 {
5751 VALUE hash;
5757 }
5766 }
5772 }
5774 /*
5775 * call-seq:
5776 * ary.intersect?(other_ary) -> true or false
5777 *
5778 * Returns +true+ if the array and +other_ary+ have at least one element in
5779 * common, otherwise returns +false+:
5780 *
5781 * a = [ 1, 2, 3 ]
5782 * b = [ 3, 4, 5 ]
5783 * c = [ 5, 6, 7 ]
5784 * a.intersect?(b) #=> true
5785 * a.intersect?(c) #=> false
5786 *
5787 * +Array+ elements are compared using <tt>eql?</tt>
5788 * (items must also implement +hash+ correctly).
5789 */
5791 static VALUE
5793 {
5795 st_data_t vv;
5805 }
5807 }
5814 }
5825 }
5826 }
5829 }
5831 static VALUE
5833 {
5836 VALUE v;
5842 }
5843 }
5846 }
5848 static VALUE
5850 {
5855 VALUE v;
5862 }
5863 }
5866 }
5867 }
5870 }
5872 static VALUE
5874 {
5879 VALUE v;
5886 }
5887 }
5890 }
5891 }
5894 }
5896 static VALUE
5898 {
5903 VALUE v;
5910 }
5911 }
5914 }
5915 }
5918 }
5920 /*
5921 * call-seq:
5922 * array.max -> element
5923 * array.max {|a, b| ... } -> element
5924 * array.max(n) -> new_array
5925 * array.max(n) {|a, b| ... } -> new_array
5926 *
5927 * Returns one of the following:
5928 *
5929 * - The maximum-valued element from +self+.
5930 * - A new +Array+ of maximum-valued elements selected from +self+.
5931 *
5932 * When no block is given, each element in +self+ must respond to method <tt><=></tt>
5933 * with an Integer.
5934 *
5935 * With no argument and no block, returns the element in +self+
5936 * having the maximum value per method <tt><=></tt>:
5937 *
5938 * [0, 1, 2].max # => 2
5939 *
5940 * With an argument Integer +n+ and no block, returns a new +Array+ with at most +n+ elements,
5941 * in descending order per method <tt><=></tt>:
5942 *
5943 * [0, 1, 2, 3].max(3) # => [3, 2, 1]
5944 * [0, 1, 2, 3].max(6) # => [3, 2, 1, 0]
5945 *
5946 * When a block is given, the block must return an Integer.
5947 *
5948 * With a block and no argument, calls the block <tt>self.size-1</tt> times to compare elements;
5949 * returns the element having the maximum value per the block:
5950 *
5951 * ['0', '00', '000'].max {|a, b| a.size <=> b.size } # => "000"
5952 *
5953 * With an argument +n+ and a block, returns a new +Array+ with at most +n+ elements,
5954 * in descending order per the block:
5955 *
5956 * ['0', '00', '000'].max(2) {|a, b| a.size <=> b.size } # => ["000", "00"]
5957 *
5958 */
5959 static VALUE
5961 {
5963 VALUE num;
5975 }
5976 }
5977 }
5983 }
5986 }
5989 }
5992 }
5993 }
5994 }
5997 }
5999 static VALUE
6001 {
6004 VALUE v;
6010 }
6011 }
6014 }
6016 static VALUE
6018 {
6023 VALUE a;
6030 }
6031 }
6034 }
6035 }
6038 }
6040 static VALUE
6042 {
6047 VALUE a;
6054 }
6055 }
6058 }
6059 }
6062 }
6064 static VALUE
6066 {
6071 VALUE a;
6078 }
6079 }
6082 }
6083 }
6086 }
6088 /*
6089 * call-seq:
6090 * array.min -> element
6091 * array.min { |a, b| ... } -> element
6092 * array.min(n) -> new_array
6093 * array.min(n) { |a, b| ... } -> new_array
6094 *
6095 * Returns one of the following:
6096 *
6097 * - The minimum-valued element from +self+.
6098 * - A new +Array+ of minimum-valued elements selected from +self+.
6099 *
6100 * When no block is given, each element in +self+ must respond to method <tt><=></tt>
6101 * with an Integer.
6102 *
6103 * With no argument and no block, returns the element in +self+
6104 * having the minimum value per method <tt><=></tt>:
6105 *
6106 * [0, 1, 2].min # => 0
6107 *
6108 * With Integer argument +n+ and no block, returns a new +Array+ with at most +n+ elements,
6109 * in ascending order per method <tt><=></tt>:
6110 *
6111 * [0, 1, 2, 3].min(3) # => [0, 1, 2]
6112 * [0, 1, 2, 3].min(6) # => [0, 1, 2, 3]
6113 *
6114 * When a block is given, the block must return an Integer.
6115 *
6116 * With a block and no argument, calls the block <tt>self.size-1</tt> times to compare elements;
6117 * returns the element having the minimum value per the block:
6118 *
6119 * ['0', '00', '000'].min { |a, b| a.size <=> b.size } # => "0"
6120 *
6121 * With an argument +n+ and a block, returns a new +Array+ with at most +n+ elements,
6122 * in ascending order per the block:
6123 *
6124 * ['0', '00', '000'].min(2) {|a, b| a.size <=> b.size } # => ["0", "00"]
6125 *
6126 */
6127 static VALUE
6129 {
6131 VALUE num;
6143 }
6144 }
6145 }
6151 }
6154 }
6157 }
6160 }
6161 }
6162 }
6165 }
6167 /*
6168 * call-seq:
6169 * array.minmax -> [min_val, max_val]
6170 * array.minmax {|a, b| ... } -> [min_val, max_val]
6171 *
6172 * Returns a new 2-element +Array+ containing the minimum and maximum values
6173 * from +self+, either per method <tt><=></tt> or per a given block:.
6174 *
6175 * When no block is given, each element in +self+ must respond to method <tt><=></tt>
6176 * with an Integer;
6177 * returns a new 2-element +Array+ containing the minimum and maximum values
6178 * from +self+, per method <tt><=></tt>:
6179 *
6180 * [0, 1, 2].minmax # => [0, 2]
6181 *
6182 * When a block is given, the block must return an Integer;
6183 * the block is called <tt>self.size-1</tt> times to compare elements;
6184 * returns a new 2-element +Array+ containing the minimum and maximum values
6185 * from +self+, per the block:
6186 *
6187 * ['0', '00', '000'].minmax {|a, b| a.size <=> b.size } # => ["0", "000"]
6188 *
6189 */
6190 static VALUE
6192 {
6195 }
6197 }
6199 static int
6201 {
6204 }
6206 /*
6207 * call-seq:
6208 * array.uniq! -> self or nil
6209 * array.uniq! {|element| ... } -> self or nil
6210 *
6211 * Removes duplicate elements from +self+, the first occurrence always being retained;
6212 * returns +self+ if any elements removed, +nil+ otherwise.
6213 *
6214 * With no block given, identifies and removes elements using method <tt>eql?</tt>
6215 * to compare.
6216 *
6217 * Returns +self+ if any elements removed:
6218 *
6219 * a = [0, 0, 1, 1, 2, 2]
6220 * a.uniq! # => [0, 1, 2]
6221 *
6222 * Returns +nil+ if no elements removed.
6223 *
6224 * With a block given, calls the block for each element;
6225 * identifies (using method <tt>eql?</tt>) and removes
6226 * elements for which the block returns duplicate values.
6227 *
6228 * Returns +self+ if any elements removed:
6229 *
6230 * a = ['a', 'aa', 'aaa', 'b', 'bb', 'bbb']
6231 * a.uniq! {|element| element.size } # => ['a', 'aa', 'aaa']
6232 *
6233 * Returns +nil+ if no elements removed.
6234 */
6235 static VALUE
6237 {
6238 VALUE hash;
6246 else
6252 }
6258 }
6263 }
6265 /*
6266 * call-seq:
6267 * array.uniq -> new_array
6268 * array.uniq {|element| ... } -> new_array
6269 *
6270 * Returns a new +Array+ containing those elements from +self+ that are not duplicates,
6271 * the first occurrence always being retained.
6272 *
6273 * With no block given, identifies and omits duplicates using method <tt>eql?</tt>
6274 * to compare:
6275 *
6276 * a = [0, 0, 1, 1, 2, 2]
6277 * a.uniq # => [0, 1, 2]
6278 *
6279 * With a block given, calls the block for each element;
6280 * identifies (using method <tt>eql?</tt>) and omits duplicate values,
6281 * that is, those elements for which the block returns the same value:
6282 *
6283 * a = ['a', 'aa', 'aaa', 'b', 'bb', 'bbb']
6284 * a.uniq {|element| element.size } # => ["a", "aa", "aaa"]
6285 *
6286 */
6288 static VALUE
6290 {
6296 }
6300 }
6304 }
6307 }
6309 /*
6310 * call-seq:
6311 * compact! -> self or nil
6312 *
6313 * Removes all +nil+ elements from +self+;
6314 * Returns +self+ if any elements are removed, +nil+ otherwise:
6315 *
6316 * a = [nil, 0, nil, false, nil, '', nil, [], nil, {}]
6317 * a.compact! # => [0, false, "", [], {}]
6318 * a # => [0, false, "", [], {}]
6319 * a.compact! # => nil
6320 *
6321 * Related: Array#compact;
6322 * see also {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
6323 */
6325 static VALUE
6327 {
6338 }
6342 }
6346 }
6348 /*
6349 * call-seq:
6350 * compact -> new_array
6351 *
6352 * Returns a new array containing only the non-+nil+ elements from +self+;
6353 * element order is preserved:
6354 *
6355 * a = [nil, 0, nil, false, nil, '', nil, [], nil, {}]
6356 * a.compact # => [0, false, "", [], {}]
6357 *
6358 * Related: Array#compact!;
6359 * see also {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
6360 */
6362 static VALUE
6364 {
6368 }
6370 /*
6371 * call-seq:
6372 * count -> integer
6373 * count(object) -> integer
6374 * count {|element| ... } -> integer
6375 *
6376 * Returns a count of specified elements.
6377 *
6378 * With no argument and no block, returns the count of all elements:
6379 *
6380 * [0, :one, 'two', 3, 3.0].count # => 5
6381 *
6382 * With argument +object+ given, returns the count of elements <tt>==</tt> to +object+:
6383 *
6384 * [0, :one, 'two', 3, 3.0].count(3) # => 2
6385 *
6386 * With no argument and a block given, calls the block with each element;
6387 * returns the count of elements for which the block returns a truthy value:
6388 *
6389 * [0, 1, 2, 3].count {|element| element > 1 } # => 2
6390 *
6391 * With argument +object+ and a block given, issues a warning, ignores the block,
6392 * and returns the count of elements <tt>==</tt> to +object+.
6393 *
6394 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
6395 */
6397 static VALUE
6399 {
6403 VALUE v;
6411 }
6412 }
6418 }
6421 }
6422 }
6425 }
6427 static VALUE
6429 {
6439 }
6440 }
6443 }
6457 }
6468 }
6473 }
6475 }
6478 }
6484 }
6486 }
6491 }
6492 }
6495 }
6498 }
6502 }
6506 }
6510 }
6512 /*
6513 * call-seq:
6514 * array.flatten! -> self or nil
6515 * array.flatten!(level) -> self or nil
6516 *
6517 * Replaces each nested +Array+ in +self+ with the elements from that +Array+;
6518 * returns +self+ if any changes, +nil+ otherwise.
6519 *
6520 * With non-negative Integer argument +level+, flattens recursively through +level+ levels:
6521 *
6522 * a = [ 0, [ 1, [2, 3], 4 ], 5 ]
6523 * a.flatten!(1) # => [0, 1, [2, 3], 4, 5]
6524 * a = [ 0, [ 1, [2, 3], 4 ], 5 ]
6525 * a.flatten!(2) # => [0, 1, 2, 3, 4, 5]
6526 * a = [ 0, [ 1, [2, 3], 4 ], 5 ]
6527 * a.flatten!(3) # => [0, 1, 2, 3, 4, 5]
6528 * [0, 1, 2].flatten!(1) # => nil
6529 *
6530 * With no argument, a +nil+ argument, or with negative argument +level+, flattens all levels:
6531 *
6532 * a = [ 0, [ 1, [2, 3], 4 ], 5 ]
6533 * a.flatten! # => [0, 1, 2, 3, 4, 5]
6534 * [0, 1, 2].flatten! # => nil
6535 * a = [ 0, [ 1, [2, 3], 4 ], 5 ]
6536 * a.flatten!(-1) # => [0, 1, 2, 3, 4, 5]
6537 * a = [ 0, [ 1, [2, 3], 4 ], 5 ]
6538 * a.flatten!(-2) # => [0, 1, 2, 3, 4, 5]
6539 * [0, 1, 2].flatten!(-1) # => nil
6540 *
6541 */
6543 static VALUE
6545 {
6557 }
6563 }
6565 /*
6566 * call-seq:
6567 * array.flatten -> new_array
6568 * array.flatten(level) -> new_array
6569 *
6570 * Returns a new +Array+ that is a recursive flattening of +self+:
6571 * - Each non-Array element is unchanged.
6572 * - Each +Array+ is replaced by its individual elements.
6573 *
6574 * With non-negative Integer argument +level+, flattens recursively through +level+ levels:
6575 *
6576 * a = [ 0, [ 1, [2, 3], 4 ], 5 ]
6577 * a.flatten(0) # => [0, [1, [2, 3], 4], 5]
6578 * a = [ 0, [ 1, [2, 3], 4 ], 5 ]
6579 * a.flatten(1) # => [0, 1, [2, 3], 4, 5]
6580 * a = [ 0, [ 1, [2, 3], 4 ], 5 ]
6581 * a.flatten(2) # => [0, 1, 2, 3, 4, 5]
6582 * a = [ 0, [ 1, [2, 3], 4 ], 5 ]
6583 * a.flatten(3) # => [0, 1, 2, 3, 4, 5]
6584 *
6585 * With no argument, a +nil+ argument, or with negative argument +level+, flattens all levels:
6586 *
6587 * a = [ 0, [ 1, [2, 3], 4 ], 5 ]
6588 * a.flatten # => [0, 1, 2, 3, 4, 5]
6589 * [0, 1, 2].flatten # => [0, 1, 2]
6590 * a = [ 0, [ 1, [2, 3], 4 ], 5 ]
6591 * a.flatten(-1) # => [0, 1, 2, 3, 4, 5]
6592 * a = [ 0, [ 1, [2, 3], 4 ], 5 ]
6593 * a.flatten(-2) # => [0, 1, 2, 3, 4, 5]
6594 * [0, 1, 2].flatten(-1) # => [0, 1, 2]
6595 *
6596 */
6598 static VALUE
6600 {
6602 VALUE result;
6607 }
6612 }
6615 }
6617 #define RAND_UPTO(max) (long)rb_random_ulong_limited((randgen), (max)-1)
6619 static VALUE
6621 {
6629 VALUE tmp;
6632 }
6636 }
6639 }
6641 static VALUE
6643 {
6647 }
6653 },
6655 };
6657 static VALUE
6659 {
6660 VALUE result;
6669 else
6673 }
6680 }
6681 }
6687 }
6688 }
6705 {
6709 }
6711 }
6712 memo_threshold =
6725 }
6728 }
6733 }
6734 });
6735 }
6747 }
6755 st_data_t value;
6760 }
6761 });
6762 });
6766 }
6777 }
6778 });
6780 }
6784 }
6786 static VALUE
6788 {
6790 }
6792 static VALUE
6794 {
6799 }
6806 }
6808 /*
6809 * call-seq:
6810 * cycle(count = nil) {|element| ... } -> nil
6811 * cycle(count = nil) -> new_enumerator
6812 *
6813 * With a block given, may call the block, depending on the value of argument +count+;
6814 * +count+ must be an
6815 * {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects],
6816 * or +nil+.
6817 *
6818 * When +count+ is positive,
6819 * calls the block with each element, then does so repeatedly,
6820 * until it has done so +count+ times; returns +nil+:
6821 *
6822 * output = []
6823 * [0, 1].cycle(2) {|element| output.push(element) } # => nil
6824 * output # => [0, 1, 0, 1]
6825 *
6826 * When +count+ is zero or negative, does not call the block:
6827 *
6828 * [0, 1].cycle(0) {|element| fail 'Cannot happen' } # => nil
6829 * [0, 1].cycle(-1) {|element| fail 'Cannot happen' } # => nil
6830 *
6831 * When +count+ is +nil+, cycles forever:
6832 *
6833 * # Prints 0 and 1 forever.
6834 * [0, 1].cycle {|element| puts element }
6835 * [0, 1].cycle(nil) {|element| puts element }
6836 *
6837 * With no block given, returns a new Enumerator.
6838 *
6839 * Related: see {Methods for Iterating}[rdoc-ref:Array@Methods+for+Iterating].
6840 */
6841 static VALUE
6843 {
6851 }
6855 }
6860 }
6861 }
6863 }
6865 /*
6866 * Build a ruby array of the corresponding values and yield it to the
6867 * associated block.
6868 * Return the class of +values+ for reentry check.
6869 */
6870 static int
6872 {
6880 }
6882 /*
6883 * Compute permutations of +r+ elements of the set <code>[0..n-1]</code>.
6884 *
6885 * When we have a complete permutation of array indices, copy the values
6886 * at those indices into a new array and yield that array.
6887 *
6888 * n: the size of the set
6889 * r: the number of elements in each permutation
6890 * p: the array (of size r) that we're filling in
6891 * used: an array of booleans: whether a given index is already used
6892 * values: the Ruby array that holds the actual values to permute
6893 */
6894 static void
6896 {
6905 }
6914 }
6920 }
6921 }
6925 }
6926 }
6927 }
6929 /*
6930 * Returns the product of from, from-1, ..., from - how_many + 1.
6931 * https://en.wikipedia.org/wiki/Pochhammer_symbol
6932 */
6933 static VALUE
6935 {
6936 VALUE cnt;
6942 }
6943 }
6946 }
6948 }
6950 static VALUE
6952 {
6953 VALUE r;
6957 }
6960 }
6963 }
6968 }
6970 }
6972 static VALUE
6974 {
6979 }
6981 /*
6982 * call-seq:
6983 * array.permutation {|element| ... } -> self
6984 * array.permutation(n) {|element| ... } -> self
6985 * array.permutation -> new_enumerator
6986 * array.permutation(n) -> new_enumerator
6987 *
6988 * When invoked with a block, yield all permutations of elements of +self+; returns +self+.
6989 * The order of permutations is indeterminate.
6990 *
6991 * When a block and an in-range positive Integer argument +n+ (<tt>0 < n <= self.size</tt>)
6992 * are given, calls the block with all +n+-tuple permutations of +self+.
6993 *
6994 * Example:
6995 *
6996 * a = [0, 1, 2]
6997 * a.permutation(2) {|permutation| p permutation }
6998 *
6999 * Output:
7000 *
7001 * [0, 1]
7002 * [0, 2]
7003 * [1, 0]
7004 * [1, 2]
7005 * [2, 0]
7006 * [2, 1]
7007 *
7008 * Another example:
7009 *
7010 * a = [0, 1, 2]
7011 * a.permutation(3) {|permutation| p permutation }
7012 *
7013 * Output:
7014 *
7015 * [0, 1, 2]
7016 * [0, 2, 1]
7017 * [1, 0, 2]
7018 * [1, 2, 0]
7019 * [2, 0, 1]
7020 * [2, 1, 0]
7021 *
7022 * When +n+ is zero, calls the block once with a new empty +Array+:
7023 *
7024 * a = [0, 1, 2]
7025 * a.permutation(0) {|permutation| p permutation }
7026 *
7027 * Output:
7028 *
7029 * []
7030 *
7031 * When +n+ is out of range (negative or larger than <tt>self.size</tt>),
7032 * does not call the block:
7033 *
7034 * a = [0, 1, 2]
7035 * a.permutation(-1) {|permutation| fail 'Cannot happen' }
7036 * a.permutation(4) {|permutation| fail 'Cannot happen' }
7037 *
7038 * When a block given but no argument,
7039 * behaves the same as <tt>a.permutation(a.size)</tt>:
7040 *
7041 * a = [0, 1, 2]
7042 * a.permutation {|permutation| p permutation }
7043 *
7044 * Output:
7045 *
7046 * [0, 1, 2]
7047 * [0, 2, 1]
7048 * [1, 0, 2]
7049 * [1, 2, 0]
7050 * [2, 0, 1]
7051 * [2, 1, 0]
7052 *
7053 * Returns a new Enumerator if no block given:
7054 *
7055 * a = [0, 1, 2]
7056 * a.permutation # => #<Enumerator: [0, 1, 2]:permutation>
7057 * a.permutation(2) # => #<Enumerator: [0, 1, 2]:permutation(2)>
7058 *
7059 */
7061 static VALUE
7063 {
7067 RETURN_SIZED_ENUMERATOR(ary, argc, argv, rb_ary_permutation_size); /* Return enumerator if no block */
7073 /* no permutations: yield nothing */
7074 }
7077 }
7081 }
7082 }
7095 }
7097 }
7099 static void
7101 {
7109 }
7112 }
7117 }
7118 }
7120 static VALUE
7122 {
7127 }
7129 /*
7130 * call-seq:
7131 * combination(n) {|element| ... } -> self
7132 * combination(n) -> new_enumerator
7133 *
7134 * When a block and a positive
7135 * {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects]
7136 * argument +n+ (<tt>0 < n <= self.size</tt>)
7137 * are given, calls the block with all +n+-tuple combinations of +self+;
7138 * returns +self+:
7139 *
7140 * a = %w[a b c] # => ["a", "b", "c"]
7141 * a.combination(2) {|combination| p combination } # => ["a", "b", "c"]
7142 *
7143 * Output:
7144 *
7145 * ["a", "b"]
7146 * ["a", "c"]
7147 * ["b", "c"]
7148 *
7149 * The order of the yielded combinations is not guaranteed.
7150 *
7151 * When +n+ is zero, calls the block once with a new empty array:
7152 *
7153 * a.combination(0) {|combination| p combination }
7154 * [].combination(0) {|combination| p combination }
7155 *
7156 * Output:
7157 *
7158 * []
7159 * []
7160 *
7161 * When +n+ is negative or larger than +self.size+ and +self+ is non-empty,
7162 * does not call the block:
7163 *
7164 * a.combination(-1) {|combination| fail 'Cannot happen' } # => ["a", "b", "c"]
7165 * a.combination(4) {|combination| fail 'Cannot happen' } # => ["a", "b", "c"]
7166 *
7167 * With no block given, returns a new Enumerator.
7168 *
7169 * Related: Array#permutation;
7170 * see also {Methods for Iterating}[rdoc-ref:Array@Methods+for+Iterating].
7171 */
7173 static VALUE
7175 {
7182 /* yield nothing */
7183 }
7186 }
7190 }
7191 }
7201 }
7203 }
7205 /*
7206 * Compute repeated permutations of +r+ elements of the set
7207 * <code>[0..n-1]</code>.
7208 *
7209 * When we have a complete repeated permutation of array indices, copy the
7210 * values at those indices into a new array and yield that array.
7211 *
7212 * n: the size of the set
7213 * r: the number of elements in each permutation
7214 * p: the array (of size r) that we're filling in
7215 * values: the Ruby array that holds the actual values to permute
7216 */
7217 static void
7219 {
7227 }
7232 }
7233 }
7237 }
7238 }
7240 static VALUE
7242 {
7248 }
7251 }
7253 }
7255 /*
7256 * call-seq:
7257 * array.repeated_permutation(n) {|permutation| ... } -> self
7258 * array.repeated_permutation(n) -> new_enumerator
7259 *
7260 * Calls the block with each repeated permutation of length +n+ of the elements of +self+;
7261 * each permutation is an +Array+;
7262 * returns +self+. The order of the permutations is indeterminate.
7263 *
7264 * When a block and a positive Integer argument +n+ are given, calls the block with each
7265 * +n+-tuple repeated permutation of the elements of +self+.
7266 * The number of permutations is <tt>self.size**n</tt>.
7267 *
7268 * +n+ = 1:
7269 *
7270 * a = [0, 1, 2]
7271 * a.repeated_permutation(1) {|permutation| p permutation }
7272 *
7273 * Output:
7274 *
7275 * [0]
7276 * [1]
7277 * [2]
7278 *
7279 * +n+ = 2:
7280 *
7281 * a.repeated_permutation(2) {|permutation| p permutation }
7282 *
7283 * Output:
7284 *
7285 * [0, 0]
7286 * [0, 1]
7287 * [0, 2]
7288 * [1, 0]
7289 * [1, 1]
7290 * [1, 2]
7291 * [2, 0]
7292 * [2, 1]
7293 * [2, 2]
7294 *
7295 * If +n+ is zero, calls the block once with an empty +Array+.
7296 *
7297 * If +n+ is negative, does not call the block:
7298 *
7299 * a.repeated_permutation(-1) {|permutation| fail 'Cannot happen' }
7300 *
7301 * Returns a new Enumerator if no block given:
7302 *
7303 * a = [0, 1, 2]
7304 * a.repeated_permutation(2) # => #<Enumerator: [0, 1, 2]:permutation(2)>
7305 *
7306 * Using Enumerators, it's convenient to show the permutations and counts
7307 * for some values of +n+:
7308 *
7309 * e = a.repeated_permutation(0)
7310 * e.size # => 1
7311 * e.to_a # => [[]]
7312 * e = a.repeated_permutation(1)
7313 * e.size # => 3
7314 * e.to_a # => [[0], [1], [2]]
7315 * e = a.repeated_permutation(2)
7316 * e.size # => 9
7317 * e.to_a # => [[0, 0], [0, 1], [0, 2], [1, 0], [1, 1], [1, 2], [2, 0], [2, 1], [2, 2]]
7318 *
7319 */
7320 static VALUE
7322 {
7326 RETURN_SIZED_ENUMERATOR(ary, 1, &num, rb_ary_repeated_permutation_size); /* Return Enumerator if no block */
7330 /* no permutations: yield nothing */
7331 }
7334 }
7338 }
7339 }
7349 }
7351 }
7353 static void
7355 {
7363 }
7368 }
7369 }
7373 }
7374 }
7376 static VALUE
7378 {
7383 }
7385 }
7387 /*
7388 * call-seq:
7389 * array.repeated_combination(n) {|combination| ... } -> self
7390 * array.repeated_combination(n) -> new_enumerator
7391 *
7392 * Calls the block with each repeated combination of length +n+ of the elements of +self+;
7393 * each combination is an +Array+;
7394 * returns +self+. The order of the combinations is indeterminate.
7395 *
7396 * When a block and a positive Integer argument +n+ are given, calls the block with each
7397 * +n+-tuple repeated combination of the elements of +self+.
7398 * The number of combinations is <tt>(n+1)(n+2)/2</tt>.
7399 *
7400 * +n+ = 1:
7401 *
7402 * a = [0, 1, 2]
7403 * a.repeated_combination(1) {|combination| p combination }
7404 *
7405 * Output:
7406 *
7407 * [0]
7408 * [1]
7409 * [2]
7410 *
7411 * +n+ = 2:
7412 *
7413 * a.repeated_combination(2) {|combination| p combination }
7414 *
7415 * Output:
7416 *
7417 * [0, 0]
7418 * [0, 1]
7419 * [0, 2]
7420 * [1, 1]
7421 * [1, 2]
7422 * [2, 2]
7423 *
7424 * If +n+ is zero, calls the block once with an empty +Array+.
7425 *
7426 * If +n+ is negative, does not call the block:
7427 *
7428 * a.repeated_combination(-1) {|combination| fail 'Cannot happen' }
7429 *
7430 * Returns a new Enumerator if no block given:
7431 *
7432 * a = [0, 1, 2]
7433 * a.repeated_combination(2) # => #<Enumerator: [0, 1, 2]:combination(2)>
7434 *
7435 * Using Enumerators, it's convenient to show the combinations and counts
7436 * for some values of +n+:
7437 *
7438 * e = a.repeated_combination(0)
7439 * e.size # => 1
7440 * e.to_a # => [[]]
7441 * e = a.repeated_combination(1)
7442 * e.size # => 3
7443 * e.to_a # => [[0], [1], [2]]
7444 * e = a.repeated_combination(2)
7445 * e.size # => 6
7446 * e.to_a # => [[0, 0], [0, 1], [0, 2], [1, 1], [1, 2], [2, 2]]
7447 *
7448 */
7450 static VALUE
7452 {
7456 RETURN_SIZED_ENUMERATOR(ary, 1, &num, rb_ary_repeated_combination_size); /* Return enumerator if no block */
7459 /* yield nothing */
7460 }
7463 }
7467 }
7468 }
7470 /* yield nothing */
7471 }
7481 }
7483 }
7485 /*
7486 * call-seq:
7487 * array.product(*other_arrays) -> new_array
7488 * array.product(*other_arrays) {|combination| ... } -> self
7489 *
7490 * Computes and returns or yields all combinations of elements from all the Arrays,
7491 * including both +self+ and +other_arrays+:
7492 *
7493 * - The number of combinations is the product of the sizes of all the arrays,
7494 * including both +self+ and +other_arrays+.
7495 * - The order of the returned combinations is indeterminate.
7496 *
7497 * When no block is given, returns the combinations as an +Array+ of Arrays:
7498 *
7499 * a = [0, 1, 2]
7500 * a1 = [3, 4]
7501 * a2 = [5, 6]
7502 * p = a.product(a1)
7503 * p.size # => 6 # a.size * a1.size
7504 * p # => [[0, 3], [0, 4], [1, 3], [1, 4], [2, 3], [2, 4]]
7505 * p = a.product(a1, a2)
7506 * p.size # => 12 # a.size * a1.size * a2.size
7507 * p # => [[0, 3, 5], [0, 3, 6], [0, 4, 5], [0, 4, 6], [1, 3, 5], [1, 3, 6], [1, 4, 5], [1, 4, 6], [2, 3, 5], [2, 3, 6], [2, 4, 5], [2, 4, 6]]
7508 *
7509 * If any argument is an empty +Array+, returns an empty +Array+.
7510 *
7511 * If no argument is given, returns an +Array+ of 1-element Arrays,
7512 * each containing an element of +self+:
7513 *
7514 * a.product # => [[0], [1], [2]]
7515 *
7516 * When a block is given, yields each combination as an +Array+; returns +self+:
7517 *
7518 * a.product(a1) {|combination| p combination }
7519 *
7520 * Output:
7521 *
7522 * [0, 3]
7523 * [0, 4]
7524 * [1, 3]
7525 * [1, 4]
7526 * [2, 3]
7527 * [2, 4]
7528 *
7529 * If any argument is an empty +Array+, does not call the block:
7530 *
7531 * a.product(a1, a2, []) {|combination| fail 'Cannot happen' }
7532 *
7533 * If no argument is given, yields each element of +self+ as a 1-element +Array+:
7534 *
7535 * a.product {|combination| p combination }
7536 *
7537 * Output:
7538 *
7539 * [0]
7540 * [1]
7541 * [2]
7542 *
7543 */
7545 static VALUE
7547 {
7559 /* initialize the arrays of arrays */
7565 /* initialize the counters for the arrays */
7568 /* Otherwise, allocate and fill in an array of results */
7570 /* Make defensive copies of arrays; exit if any is empty */
7574 }
7575 }
7577 /* Compute the length of the result array; return [] if any is empty */
7583 }
7587 }
7589 }
7592 /* fill in one subarray */
7596 }
7598 /* put it on the result array */
7604 }
7607 }
7608 }
7611 }
7613 /*
7614 * Increment the last counter. If it overflows, reset to 0
7615 * and increment the one before it.
7616 */
7621 /* If the first counter overflows, we are done */
7624 }
7625 }
7627 done:
7631 }
7633 /*
7634 * call-seq:
7635 * array.take(n) -> new_array
7636 *
7637 * Returns a new +Array+ containing the first +n+ element of +self+,
7638 * where +n+ is a non-negative Integer;
7639 * does not modify +self+.
7640 *
7641 * Examples:
7642 *
7643 * a = [0, 1, 2, 3, 4, 5]
7644 * a.take(1) # => [0]
7645 * a.take(2) # => [0, 1]
7646 * a.take(50) # => [0, 1, 2, 3, 4, 5]
7647 * a # => [0, 1, 2, 3, 4, 5]
7648 *
7649 */
7651 static VALUE
7653 {
7657 }
7659 }
7661 /*
7662 * call-seq:
7663 * array.take_while {|element| ... } -> new_array
7664 * array.take_while -> new_enumerator
7665 *
7666 * Returns a new +Array+ containing zero or more leading elements of +self+;
7667 * does not modify +self+.
7668 *
7669 * With a block given, calls the block with each successive element of +self+;
7670 * stops if the block returns +false+ or +nil+;
7671 * returns a new +Array+ containing those elements for which the block returned a truthy value:
7672 *
7673 * a = [0, 1, 2, 3, 4, 5]
7674 * a.take_while {|element| element < 3 } # => [0, 1, 2]
7675 * a.take_while {|element| true } # => [0, 1, 2, 3, 4, 5]
7676 * a # => [0, 1, 2, 3, 4, 5]
7677 *
7678 * With no block given, returns a new Enumerator:
7679 *
7680 * [0, 1].take_while # => #<Enumerator: [0, 1]:take_while>
7681 *
7682 */
7684 static VALUE
7686 {
7692 }
7694 }
7696 /*
7697 * call-seq:
7698 * drop(n) -> new_array
7699 *
7700 * Returns a new array containing all but the first +n+ element of +self+,
7701 * where +n+ is a non-negative Integer;
7702 * does not modify +self+.
7703 *
7704 * Examples:
7705 *
7706 * a = [0, 1, 2, 3, 4, 5]
7707 * a.drop(0) # => [0, 1, 2, 3, 4, 5]
7708 * a.drop(1) # => [1, 2, 3, 4, 5]
7709 * a.drop(2) # => [2, 3, 4, 5]
7710 * a.drop(9) # => []
7711 *
7712 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
7713 */
7715 static VALUE
7717 {
7718 VALUE result;
7722 }
7727 }
7729 /*
7730 * call-seq:
7731 * drop_while {|element| ... } -> new_array
7732 * drop_while -> new_enumerator
7733 *
7734 * With a block given, calls the block with each successive element of +self+;
7735 * stops if the block returns +false+ or +nil+;
7736 * returns a new array _omitting_ those elements for which the block returned a truthy value;
7737 * does not modify +self+:
7738 *
7739 * a = [0, 1, 2, 3, 4, 5]
7740 * a.drop_while {|element| element < 3 } # => [3, 4, 5]
7741 *
7742 * With no block given, returns a new Enumerator.
7743 *
7744 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
7745 */
7747 static VALUE
7749 {
7755 }
7757 }
7759 /*
7760 * call-seq:
7761 * any? -> true or false
7762 * any?(object) -> true or false
7763 * any? {|element| ... } -> true or false
7764 *
7765 * Returns whether for any element of +self+, a given criterion is satisfied.
7766 *
7767 * With no block and no argument, returns whether any element of +self+ is truthy:
7768 *
7769 * [nil, false, []].any? # => true # Array object is truthy.
7770 * [nil, false, {}].any? # => true # Hash object is truthy.
7771 * [nil, false, ''].any? # => true # String object is truthy.
7772 * [nil, false].any? # => false # Nil and false are not truthy.
7773 *
7774 * With argument +object+ given,
7775 * returns whether <tt>object === ele</tt> for any element +ele+ in +self+:
7776 *
7777 * [nil, false, 0].any?(0) # => true
7778 * [nil, false, 1].any?(0) # => false
7779 * [nil, false, 'food'].any?(/foo/) # => true
7780 * [nil, false, 'food'].any?(/bar/) # => false
7781 *
7782 * With a block given,
7783 * calls the block with each element in +self+;
7784 * returns whether the block returns any truthy value:
7785 *
7786 * [0, 1, 2].any? {|ele| ele < 1 } # => true
7787 * [0, 1, 2].any? {|ele| ele < 0 } # => false
7788 *
7789 * With both a block and argument +object+ given,
7790 * ignores the block and uses +object+ as above.
7791 *
7792 * <b>Special case</b>: returns +false+ if +self+ is empty
7793 * (regardless of any given argument or block).
7794 *
7795 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
7796 */
7798 static VALUE
7800 {
7808 }
7811 }
7812 }
7816 }
7817 }
7821 }
7822 }
7824 }
7826 /*
7827 * call-seq:
7828 * all? -> true or false
7829 * all?(object) -> true or false
7830 * all? {|element| ... } -> true or false
7831 *
7832 * Returns whether for every element of +self+,
7833 * a given criterion is satisfied.
7834 *
7835 * With no block and no argument,
7836 * returns whether every element of +self+ is truthy:
7837 *
7838 * [[], {}, '', 0, 0.0, Object.new].all? # => true # All truthy objects.
7839 * [[], {}, '', 0, 0.0, nil].all? # => false # nil is not truthy.
7840 * [[], {}, '', 0, 0.0, false].all? # => false # false is not truthy.
7841 *
7842 * With argument +object+ given, returns whether <tt>object === ele</tt>
7843 * for every element +ele+ in +self+:
7844 *
7845 * [0, 0, 0].all?(0) # => true
7846 * [0, 1, 2].all?(1) # => false
7847 * ['food', 'fool', 'foot'].all?(/foo/) # => true
7848 * ['food', 'drink'].all?(/foo/) # => false
7849 *
7850 * With a block given, calls the block with each element in +self+;
7851 * returns whether the block returns only truthy values:
7852 *
7853 * [0, 1, 2].all? { |ele| ele < 3 } # => true
7854 * [0, 1, 2].all? { |ele| ele < 2 } # => false
7855 *
7856 * With both a block and argument +object+ given,
7857 * ignores the block and uses +object+ as above.
7858 *
7859 * <b>Special case</b>: returns +true+ if +self+ is empty
7860 * (regardless of any given argument or block).
7861 *
7862 * Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying].
7863 */
7865 static VALUE
7867 {
7875 }
7878 }
7879 }
7883 }
7884 }
7888 }
7889 }
7891 }
7893 /*
7894 * call-seq:
7895 * array.none? -> true or false
7896 * array.none? {|element| ... } -> true or false
7897 * array.none?(obj) -> true or false
7898 *
7899 * Returns +true+ if no element of +self+ meet a given criterion.
7900 *
7901 * With no block given and no argument, returns +true+ if +self+ has no truthy elements,
7902 * +false+ otherwise:
7903 *
7904 * [nil, false].none? # => true
7905 * [nil, 0, false].none? # => false
7906 * [].none? # => true
7907 *
7908 * With a block given and no argument, calls the block with each element in +self+;
7909 * returns +true+ if the block returns no truthy value, +false+ otherwise:
7910 *
7911 * [0, 1, 2].none? {|element| element > 3 } # => true
7912 * [0, 1, 2].none? {|element| element > 1 } # => false
7913 *
7914 * If argument +obj+ is given, returns +true+ if <tt>obj.===</tt> no element, +false+ otherwise:
7915 *
7916 * ['food', 'drink'].none?(/bar/) # => true
7917 * ['food', 'drink'].none?(/foo/) # => false
7918 * [].none?(/foo/) # => true
7919 * [0, 1, 2].none?(3) # => true
7920 * [0, 1, 2].none?(1) # => false
7921 *
7922 * Related: Enumerable#none?
7923 */
7925 static VALUE
7927 {
7935 }
7938 }
7939 }
7943 }
7944 }
7948 }
7949 }
7951 }
7953 /*
7954 * call-seq:
7955 * array.one? -> true or false
7956 * array.one? {|element| ... } -> true or false
7957 * array.one?(obj) -> true or false
7958 *
7959 * Returns +true+ if exactly one element of +self+ meets a given criterion.
7960 *
7961 * With no block given and no argument, returns +true+ if +self+ has exactly one truthy element,
7962 * +false+ otherwise:
7963 *
7964 * [nil, 0].one? # => true
7965 * [0, 0].one? # => false
7966 * [nil, nil].one? # => false
7967 * [].one? # => false
7968 *
7969 * With a block given and no argument, calls the block with each element in +self+;
7970 * returns +true+ if the block a truthy value for exactly one element, +false+ otherwise:
7971 *
7972 * [0, 1, 2].one? {|element| element > 0 } # => false
7973 * [0, 1, 2].one? {|element| element > 1 } # => true
7974 * [0, 1, 2].one? {|element| element > 2 } # => false
7975 *
7976 * If argument +obj+ is given, returns +true+ if <tt>obj.===</tt> exactly one element,
7977 * +false+ otherwise:
7978 *
7979 * [0, 1, 2].one?(0) # => true
7980 * [0, 0, 1].one?(0) # => false
7981 * [1, 1, 2].one?(0) # => false
7982 * ['food', 'drink'].one?(/bar/) # => false
7983 * ['food', 'drink'].one?(/foo/) # => true
7984 * [].one?(/foo/) # => false
7985 *
7986 * Related: Enumerable#one?
7987 */
7989 static VALUE
7991 {
8000 }
8005 }
8006 }
8007 }
8013 }
8014 }
8015 }
8021 }
8022 }
8023 }
8025 }
8027 /*
8028 * call-seq:
8029 * array.dig(index, *identifiers) -> object
8030 *
8031 * Finds and returns the object in nested object
8032 * specified by +index+ and +identifiers+;
8033 * the nested objects may be instances of various classes.
8034 * See {Dig Methods}[rdoc-ref:dig_methods.rdoc].
8035 *
8036 * Examples:
8037 *
8038 * a = [:foo, [:bar, :baz, [:bat, :bam]]]
8039 * a.dig(1) # => [:bar, :baz, [:bat, :bam]]
8040 * a.dig(1, 2) # => [:bat, :bam]
8041 * a.dig(1, 2, 0) # => :bat
8042 * a.dig(1, 2, 3) # => nil
8043 *
8044 * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
8045 */
8047 static VALUE
8049 {
8055 }
8059 {
8064 }
8067 }
8069 }
8071 /*
8072 * call-seq:
8073 * array.sum(init = 0) -> object
8074 * array.sum(init = 0) {|element| ... } -> object
8075 *
8076 * When no block is given, returns the object equivalent to:
8077 *
8078 * sum = init
8079 * array.each {|element| sum += element }
8080 * sum
8081 *
8082 * For example, <tt>[e1, e2, e3].sum</tt> returns <tt>init + e1 + e2 + e3</tt>.
8083 *
8084 * Examples:
8085 *
8086 * a = [0, 1, 2, 3]
8087 * a.sum # => 6
8088 * a.sum(100) # => 106
8089 *
8090 * The elements need not be numeric, but must be <tt>+</tt>-compatible
8091 * with each other and with +init+:
8092 *
8093 * a = ['abc', 'def', 'ghi']
8094 * a.sum('jkl') # => "jklabcdefghi"
8095 *
8096 * When a block is given, it is called with each element
8097 * and the block's return value (instead of the element itself) is used as the addend:
8098 *
8099 * a = ['zero', 1, :two]
8100 * s = a.sum('Coerced and concatenated: ') {|element| element.to_s }
8101 * s # => "Coerced and concatenated: zero1two"
8102 *
8103 * Notes:
8104 *
8105 * - Array#join and Array#flatten may be faster than Array#sum
8106 * for an +Array+ of Strings or an +Array+ of Arrays.
8107 * - Array#sum method may not respect method redefinition of "+" methods such as Integer#+.
8108 *
8109 */
8111 static VALUE
8113 {
8131 }
8142 }
8143 }
8149 else
8151 }
8152 else
8154 }
8158 not_exact:
8162 /*
8163 * Kahan-Babuska balancing compensated summation algorithm
8164 * See https://link.springer.com/article/10.1007/s00607-005-0139-x
8165 */
8177 has_float_value:
8185 else
8192 }
8196 else
8199 }
8205 else
8208 }
8212 not_float:
8214 }
8217 init_is_a_value:
8222 has_some_value:
8224 }
8226 }
8228 /* :nodoc: */
8229 static VALUE
8231 {
8233 }
8235 /*
8236 * An +Array+ is an ordered, integer-indexed collection of objects, called _elements_.
8237 * Any object (even another array) may be an array element,
8238 * and an array can contain objects of different types.
8239 *
8240 * == +Array+ Indexes
8241 *
8242 * +Array+ indexing starts at 0, as in C or Java.
8243 *
8244 * A positive index is an offset from the first element:
8245 *
8246 * - Index 0 indicates the first element.
8247 * - Index 1 indicates the second element.
8248 * - ...
8249 *
8250 * A negative index is an offset, backwards, from the end of the array:
8251 *
8252 * - Index -1 indicates the last element.
8253 * - Index -2 indicates the next-to-last element.
8254 * - ...
8255 *
8256 * A non-negative index is <i>in range</i> if and only if it is smaller than
8257 * the size of the array. For a 3-element array:
8258 *
8259 * - Indexes 0 through 2 are in range.
8260 * - Index 3 is out of range.
8261 *
8262 * A negative index is <i>in range</i> if and only if its absolute value is
8263 * not larger than the size of the array. For a 3-element array:
8264 *
8265 * - Indexes -1 through -3 are in range.
8266 * - Index -4 is out of range.
8267 *
8268 * Although the effective index into an array is always an integer,
8269 * some methods (both within and outside of class +Array+)
8270 * accept one or more non-integer arguments that are
8271 * {integer-convertible objects}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects].
8272 *
8273 *
8274 * == Creating Arrays
8275 *
8276 * You can create an +Array+ object explicitly with:
8277 *
8278 * - An {array literal}[rdoc-ref:literals.rdoc@Array+Literals]:
8279 *
8280 * [1, 'one', :one, [2, 'two', :two]]
8281 *
8282 * - A {%w or %W: string-array Literal}[rdoc-ref:literals.rdoc@25w+and+-25W-3A+String-Array+Literals]:
8283 *
8284 * %w[foo bar baz] # => ["foo", "bar", "baz"]
8285 * %w[1 % *] # => ["1", "%", "*"]
8286 *
8287 * - A {%i pr %I: symbol-array Literal}[rdoc-ref:literals.rdoc@25i+and+-25I-3A+Symbol-Array+Literals]:
8288 *
8289 * %i[foo bar baz] # => [:foo, :bar, :baz]
8290 * %i[1 % *] # => [:"1", :%, :*]
8291 *
8292 * - \Method Kernel#Array:
8293 *
8294 * Array(["a", "b"]) # => ["a", "b"]
8295 * Array(1..5) # => [1, 2, 3, 4, 5]
8296 * Array(key: :value) # => [[:key, :value]]
8297 * Array(nil) # => []
8298 * Array(1) # => [1]
8299 * Array({:a => "a", :b => "b"}) # => [[:a, "a"], [:b, "b"]]
8300 *
8301 * - \Method Array.new:
8302 *
8303 * Array.new # => []
8304 * Array.new(3) # => [nil, nil, nil]
8305 * Array.new(4) {Hash.new} # => [{}, {}, {}, {}]
8306 * Array.new(3, true) # => [true, true, true]
8307 *
8308 * Note that the last example above populates the array
8309 * with references to the same object.
8310 * This is recommended only in cases where that object is a natively immutable object
8311 * such as a symbol, a numeric, +nil+, +true+, or +false+.
8312 *
8313 * Another way to create an array with various objects, using a block;
8314 * this usage is safe for mutable objects such as hashes, strings or
8315 * other arrays:
8316 *
8317 * Array.new(4) {|i| i.to_s } # => ["0", "1", "2", "3"]
8318 *
8319 * Here is a way to create a multi-dimensional array:
8320 *
8321 * Array.new(3) {Array.new(3)}
8322 * # => [[nil, nil, nil], [nil, nil, nil], [nil, nil, nil]]
8323 *
8324 * A number of Ruby methods, both in the core and in the standard library,
8325 * provide instance method +to_a+, which converts an object to an array.
8326 *
8327 * - ARGF#to_a
8328 * - Array#to_a
8329 * - Enumerable#to_a
8330 * - Hash#to_a
8331 * - MatchData#to_a
8332 * - NilClass#to_a
8333 * - OptionParser#to_a
8334 * - Range#to_a
8335 * - Set#to_a
8336 * - Struct#to_a
8337 * - Time#to_a
8338 * - Benchmark::Tms#to_a
8339 * - CSV::Table#to_a
8340 * - Enumerator::Lazy#to_a
8341 * - Gem::List#to_a
8342 * - Gem::NameTuple#to_a
8343 * - Gem::Platform#to_a
8344 * - Gem::RequestSet::Lockfile::Tokenizer#to_a
8345 * - Gem::SourceList#to_a
8346 * - OpenSSL::X509::Extension#to_a
8347 * - OpenSSL::X509::Name#to_a
8348 * - Racc::ISet#to_a
8349 * - Rinda::RingFinger#to_a
8350 * - Ripper::Lexer::Elem#to_a
8351 * - RubyVM::InstructionSequence#to_a
8352 * - YAML::DBM#to_a
8353 *
8354 * == Example Usage
8355 *
8356 * In addition to the methods it mixes in through the Enumerable module, the
8357 * +Array+ class has proprietary methods for accessing, searching and otherwise
8358 * manipulating arrays.
8359 *
8360 * Some of the more common ones are illustrated below.
8361 *
8362 * == Accessing Elements
8363 *
8364 * Elements in an array can be retrieved using the Array#[] method. It can
8365 * take a single integer argument (a numeric index), a pair of arguments
8366 * (start and length) or a range. Negative indices start counting from the end,
8367 * with -1 being the last element.
8368 *
8369 * arr = [1, 2, 3, 4, 5, 6]
8370 * arr[2] #=> 3
8371 * arr[100] #=> nil
8372 * arr[-3] #=> 4
8373 * arr[2, 3] #=> [3, 4, 5]
8374 * arr[1..4] #=> [2, 3, 4, 5]
8375 * arr[1..-3] #=> [2, 3, 4]
8376 *
8377 * Another way to access a particular array element is by using the #at method
8378 *
8379 * arr.at(0) #=> 1
8380 *
8381 * The #slice method works in an identical manner to Array#[].
8382 *
8383 * To raise an error for indices outside of the array bounds or else to
8384 * provide a default value when that happens, you can use #fetch.
8385 *
8386 * arr = ['a', 'b', 'c', 'd', 'e', 'f']
8387 * arr.fetch(100) #=> IndexError: index 100 outside of array bounds: -6...6
8388 * arr.fetch(100, "oops") #=> "oops"
8389 *
8390 * The special methods #first and #last will return the first and last
8391 * elements of an array, respectively.
8392 *
8393 * arr.first #=> 1
8394 * arr.last #=> 6
8395 *
8396 * To return the first +n+ elements of an array, use #take
8397 *
8398 * arr.take(3) #=> [1, 2, 3]
8399 *
8400 * #drop does the opposite of #take, by returning the elements after +n+
8401 * elements have been dropped:
8402 *
8403 * arr.drop(3) #=> [4, 5, 6]
8404 *
8405 * == Obtaining Information about an +Array+
8406 *
8407 * Arrays keep track of their own length at all times. To query an array
8408 * about the number of elements it contains, use #length, #count or #size.
8409 *
8410 * browsers = ['Chrome', 'Firefox', 'Safari', 'Opera', 'IE']
8411 * browsers.length #=> 5
8412 * browsers.count #=> 5
8413 *
8414 * To check whether an array contains any elements at all
8415 *
8416 * browsers.empty? #=> false
8417 *
8418 * To check whether a particular item is included in the array
8419 *
8420 * browsers.include?('Konqueror') #=> false
8421 *
8422 * == Adding Items to Arrays
8423 *
8424 * Items can be added to the end of an array by using either #push or #<<
8425 *
8426 * arr = [1, 2, 3, 4]
8427 * arr.push(5) #=> [1, 2, 3, 4, 5]
8428 * arr << 6 #=> [1, 2, 3, 4, 5, 6]
8429 *
8430 * #unshift will add a new item to the beginning of an array.
8431 *
8432 * arr.unshift(0) #=> [0, 1, 2, 3, 4, 5, 6]
8433 *
8434 * With #insert you can add a new element to an array at any position.
8435 *
8436 * arr.insert(3, 'apple') #=> [0, 1, 2, 'apple', 3, 4, 5, 6]
8437 *
8438 * Using the #insert method, you can also insert multiple values at once:
8439 *
8440 * arr.insert(3, 'orange', 'pear', 'grapefruit')
8441 * #=> [0, 1, 2, "orange", "pear", "grapefruit", "apple", 3, 4, 5, 6]
8442 *
8443 * == Removing Items from an +Array+
8444 *
8445 * The method #pop removes the last element in an array and returns it:
8446 *
8447 * arr = [1, 2, 3, 4, 5, 6]
8448 * arr.pop #=> 6
8449 * arr #=> [1, 2, 3, 4, 5]
8450 *
8451 * To retrieve and at the same time remove the first item, use #shift:
8452 *
8453 * arr.shift #=> 1
8454 * arr #=> [2, 3, 4, 5]
8455 *
8456 * To delete an element at a particular index:
8457 *
8458 * arr.delete_at(2) #=> 4
8459 * arr #=> [2, 3, 5]
8460 *
8461 * To delete a particular element anywhere in an array, use #delete:
8462 *
8463 * arr = [1, 2, 2, 3]
8464 * arr.delete(2) #=> 2
8465 * arr #=> [1,3]
8466 *
8467 * A useful method if you need to remove +nil+ values from an array is
8468 * #compact:
8469 *
8470 * arr = ['foo', 0, nil, 'bar', 7, 'baz', nil]
8471 * arr.compact #=> ['foo', 0, 'bar', 7, 'baz']
8472 * arr #=> ['foo', 0, nil, 'bar', 7, 'baz', nil]
8473 * arr.compact! #=> ['foo', 0, 'bar', 7, 'baz']
8474 * arr #=> ['foo', 0, 'bar', 7, 'baz']
8475 *
8476 * Another common need is to remove duplicate elements from an array.
8477 *
8478 * It has the non-destructive #uniq, and destructive method #uniq!
8479 *
8480 * arr = [2, 5, 6, 556, 6, 6, 8, 9, 0, 123, 556]
8481 * arr.uniq #=> [2, 5, 6, 556, 8, 9, 0, 123]
8482 *
8483 * == Iterating over Arrays
8484 *
8485 * Like all classes that include the Enumerable module, +Array+ has an each
8486 * method, which defines what elements should be iterated over and how. In
8487 * case of Array's #each, all elements in the +Array+ instance are yielded to
8488 * the supplied block in sequence.
8489 *
8490 * Note that this operation leaves the array unchanged.
8491 *
8492 * arr = [1, 2, 3, 4, 5]
8493 * arr.each {|a| print a -= 10, " "}
8494 * # prints: -9 -8 -7 -6 -5
8495 * #=> [1, 2, 3, 4, 5]
8496 *
8497 * Another sometimes useful iterator is #reverse_each which will iterate over
8498 * the elements in the array in reverse order.
8499 *
8500 * words = %w[first second third fourth fifth sixth]
8501 * str = ""
8502 * words.reverse_each {|word| str += "#{word} "}
8503 * p str #=> "sixth fifth fourth third second first "
8504 *
8505 * The #map method can be used to create a new array based on the original
8506 * array, but with the values modified by the supplied block:
8507 *
8508 * arr.map {|a| 2*a} #=> [2, 4, 6, 8, 10]
8509 * arr #=> [1, 2, 3, 4, 5]
8510 * arr.map! {|a| a**2} #=> [1, 4, 9, 16, 25]
8511 * arr #=> [1, 4, 9, 16, 25]
8512 *
8513 *
8514 * == Selecting Items from an +Array+
8515 *
8516 * Elements can be selected from an array according to criteria defined in a
8517 * block. The selection can happen in a destructive or a non-destructive
8518 * manner. While the destructive operations will modify the array they were
8519 * called on, the non-destructive methods usually return a new array with the
8520 * selected elements, but leave the original array unchanged.
8521 *
8522 * === Non-destructive Selection
8523 *
8524 * arr = [1, 2, 3, 4, 5, 6]
8525 * arr.select {|a| a > 3} #=> [4, 5, 6]
8526 * arr.reject {|a| a < 3} #=> [3, 4, 5, 6]
8527 * arr.drop_while {|a| a < 4} #=> [4, 5, 6]
8528 * arr #=> [1, 2, 3, 4, 5, 6]
8529 *
8530 * === Destructive Selection
8531 *
8532 * #select! and #reject! are the corresponding destructive methods to #select
8533 * and #reject
8534 *
8535 * Similar to #select vs. #reject, #delete_if and #keep_if have the exact
8536 * opposite result when supplied with the same block:
8537 *
8538 * arr.delete_if {|a| a < 4} #=> [4, 5, 6]
8539 * arr #=> [4, 5, 6]
8540 *
8541 * arr = [1, 2, 3, 4, 5, 6]
8542 * arr.keep_if {|a| a < 4} #=> [1, 2, 3]
8543 * arr #=> [1, 2, 3]
8544 *
8545 * == What's Here
8546 *
8547 * First, what's elsewhere. \Class +Array+:
8548 *
8549 * - Inherits from {class Object}[rdoc-ref:Object@What-27s+Here].
8550 * - Includes {module Enumerable}[rdoc-ref:Enumerable@What-27s+Here],
8551 * which provides dozens of additional methods.
8552 *
8553 * Here, class +Array+ provides methods that are useful for:
8554 *
8555 * - {Creating an Array}[rdoc-ref:Array@Methods+for+Creating+an+Array]
8556 * - {Querying}[rdoc-ref:Array@Methods+for+Querying]
8557 * - {Comparing}[rdoc-ref:Array@Methods+for+Comparing]
8558 * - {Fetching}[rdoc-ref:Array@Methods+for+Fetching]
8559 * - {Assigning}[rdoc-ref:Array@Methods+for+Assigning]
8560 * - {Deleting}[rdoc-ref:Array@Methods+for+Deleting]
8561 * - {Combining}[rdoc-ref:Array@Methods+for+Combining]
8562 * - {Iterating}[rdoc-ref:Array@Methods+for+Iterating]
8563 * - {Converting}[rdoc-ref:Array@Methods+for+Converting]
8564 * - {And more....}[rdoc-ref:Array@Other+Methods]
8565 *
8566 * === Methods for Creating an +Array+
8567 *
8568 * - ::[]: Returns a new array populated with given objects.
8569 * - ::new: Returns a new array.
8570 * - ::try_convert: Returns a new array created from a given object.
8571 *
8572 * See also {Creating Arrays}[rdoc-ref:Array@Creating+Arrays].
8573 *
8574 * === Methods for Querying
8575 *
8576 * - #length (aliased as #size): Returns the count of elements.
8577 * - #include?: Returns whether any element <tt>==</tt> a given object.
8578 * - #empty?: Returns whether there are no elements.
8579 * - #all?: Returns whether all elements meet a given criterion.
8580 * - #any?: Returns whether any element meets a given criterion.
8581 * - #none?: Returns whether no element <tt>==</tt> a given object.
8582 * - #one?: Returns whether exactly one element <tt>==</tt> a given object.
8583 * - #count: Returns the count of elements that meet a given criterion.
8584 * - #find_index (aliased as #index): Returns the index of the first element that meets a given criterion.
8585 * - #rindex: Returns the index of the last element that meets a given criterion.
8586 * - #hash: Returns the integer hash code.
8587 *
8588 * === Methods for Comparing
8589 *
8590 * - #<=>: Returns -1, 0, or 1, as +self+ is less than, equal to, or
8591 * greater than a given object.
8592 * - #==: Returns whether each element in +self+ is <tt>==</tt> to the corresponding element
8593 * in a given object.
8594 * - #eql?: Returns whether each element in +self+ is <tt>eql?</tt> to the corresponding
8595 * element in a given object.
8597 * === Methods for Fetching
8598 *
8599 * These methods do not modify +self+.
8600 *
8601 * - #[] (aliased as #slice): Returns consecutive elements as determined by a given argument.
8602 * - #fetch: Returns the element at a given offset.
8603 * - #first: Returns one or more leading elements.
8604 * - #last: Returns one or more trailing elements.
8605 * - #max: Returns one or more maximum-valued elements,
8606 * as determined by <tt><=></tt> or a given block.
8607 * - #min: Returns one or more minimum-valued elements,
8608 * as determined by <tt><=></tt> or a given block.
8609 * - #minmax: Returns the minimum-valued and maximum-valued elements,
8610 * as determined by <tt><=></tt> or a given block.
8611 * - #assoc: Returns the first element that is an array
8612 * whose first element <tt>==</tt> a given object.
8613 * - #rassoc: Returns the first element that is an array
8614 * whose second element <tt>==</tt> a given object.
8615 * - #at: Returns the element at a given offset.
8616 * - #values_at: Returns the elements at given offsets.
8617 * - #dig: Returns the object in nested objects
8618 * that is specified by a given index and additional arguments.
8619 * - #drop: Returns trailing elements as determined by a given index.
8620 * - #take: Returns leading elements as determined by a given index.
8621 * - #drop_while: Returns trailing elements as determined by a given block.
8622 * - #take_while: Returns leading elements as determined by a given block.
8623 * - #sort: Returns all elements in an order determined by <tt><=></tt> or a given block.
8624 * - #reverse: Returns all elements in reverse order.
8625 * - #compact: Returns an array containing all non-+nil+ elements.
8626 * - #select (aliased as #filter): Returns an array containing elements selected by a given block.
8627 * - #uniq: Returns an array containing non-duplicate elements.
8628 * - #rotate: Returns all elements with some rotated from one end to the other.
8629 * - #bsearch: Returns an element selected via a binary search
8630 * as determined by a given block.
8631 * - #bsearch_index: Returns the index of an element selected via a binary search
8632 * as determined by a given block.
8633 * - #sample: Returns one or more random elements.
8634 * - #shuffle: Returns elements in a random order.
8635 *
8636 * === Methods for Assigning
8637 *
8638 * These methods add, replace, or reorder elements in +self+.
8639 *
8640 * - #[]=: Assigns specified elements with a given object.
8641 * - #<<: Appends an element.
8642 * - #push (aliased as #append): Appends elements.
8643 * - #unshift (aliased as #prepend): Prepends leading elements.
8644 * - #insert: Inserts given objects at a given offset; does not replace elements.
8645 * - #concat: Appends all elements from given arrays.
8646 * - #fill: Replaces specified elements with specified objects.
8647 * - #initialize_copy (aliased as #replace): Replaces the content of +self+ with the content of a given array.
8648 * - #reverse!: Replaces +self+ with its elements reversed.
8649 * - #rotate!: Replaces +self+ with its elements rotated.
8650 * - #shuffle!: Replaces +self+ with its elements in random order.
8651 * - #sort!: Replaces +self+ with its elements sorted,
8652 * as determined by <tt><=></tt> or a given block.
8653 * - #sort_by!: Replaces +self+ with its elements sorted, as determined by a given block.
8654 *
8655 * === Methods for Deleting
8656 *
8657 * Each of these methods removes elements from +self+:
8658 *
8659 * - #pop: Removes and returns the last element.
8660 * - #shift: Removes and returns the first element.
8661 * - #compact!: Removes all +nil+ elements.
8662 * - #delete: Removes elements equal to a given object.
8663 * - #delete_at: Removes the element at a given offset.
8664 * - #delete_if: Removes elements specified by a given block.
8665 * - #clear: Removes all elements.
8666 * - #keep_if: Removes elements not specified by a given block.
8667 * - #reject!: Removes elements specified by a given block.
8668 * - #select! (aliased as #filter!): Removes elements not specified by a given block.
8669 * - #slice!: Removes and returns a sequence of elements.
8670 * - #uniq!: Removes duplicates.
8671 *
8672 * === Methods for Combining
8673 *
8674 * - #&: Returns an array containing elements found both in +self+ and a given array.
8675 * - #intersection: Returns an array containing elements found both in +self+
8676 * and in each given array.
8677 * - #+: Returns an array containing all elements of +self+ followed by all elements of a given array.
8678 * - #-: Returns an array containing all elements of +self+ that are not found in a given array.
8679 * - #|: Returns an array containing all elements of +self+ and all elements of a given array,
8680 * duplicates removed.
8681 * - #union: Returns an array containing all elements of +self+ and all elements of given arrays,
8682 * duplicates removed.
8683 * - #difference: Returns an array containing all elements of +self+ that are not found
8684 * in any of the given arrays..
8685 * - #product: Returns or yields all combinations of elements from +self+ and given arrays.
8686 *
8687 * === Methods for Iterating
8688 *
8689 * - #each: Passes each element to a given block.
8690 * - #reverse_each: Passes each element, in reverse order, to a given block.
8691 * - #each_index: Passes each element index to a given block.
8692 * - #cycle: Calls a given block with each element, then does so again,
8693 * for a specified number of times, or forever.
8694 * - #combination: Calls a given block with combinations of elements of +self+;
8695 * a combination does not use the same element more than once.
8696 * - #permutation: Calls a given block with permutations of elements of +self+;
8697 * a permutation does not use the same element more than once.
8698 * - #repeated_combination: Calls a given block with combinations of elements of +self+;
8699 * a combination may use the same element more than once.
8700 * - #repeated_permutation: Calls a given block with permutations of elements of +self+;
8701 * a permutation may use the same element more than once.
8702 *
8703 * === Methods for Converting
8704 *
8705 * - #collect (aliased as #map): Returns an array containing the block return-value for each element.
8706 * - #collect! (aliased as #map!): Replaces each element with a block return-value.
8707 * - #flatten: Returns an array that is a recursive flattening of +self+.
8708 * - #flatten!: Replaces each nested array in +self+ with the elements from that array.
8709 * - #inspect (aliased as #to_s): Returns a new String containing the elements.
8710 * - #join: Returns a newsString containing the elements joined by the field separator.
8711 * - #to_a: Returns +self+ or a new array containing all elements.
8712 * - #to_ary: Returns +self+.
8713 * - #to_h: Returns a new hash formed from the elements.
8714 * - #transpose: Transposes +self+, which must be an array of arrays.
8715 * - #zip: Returns a new array of arrays containing +self+ and given arrays;
8716 * follow the link for details.
8717 *
8718 * === Other Methods
8719 *
8720 * - #*: Returns one of the following:
8721 *
8722 * - With integer argument +n+, a new array that is the concatenation
8723 * of +n+ copies of +self+.
8724 * - With string argument +field_separator+, a new string that is equivalent to
8725 * <tt>join(field_separator)</tt>.
8726 *
8727 * - #pack: Packs the elements into a binary sequence.
8728 * - #sum: Returns a sum of elements according to either <tt>+</tt> or a given block.
8729 */
8731 void
8733 {
8861 }