Public Class Methods
[](*args) click to toggle source
Returns a new array populated with the given objects.
Array.[]( 1, 'a', /^A/) # => [1, "a", /^A/]Array[ 1, 'a', /^A/ ] # => [1, "a", /^A/][ 1, 'a', /^A/ ] # => [1, "a", /^A/]
static VALUErb_ary_s_create(int argc, VALUE *argv, VALUE klass){ VALUE ary = ary_new(klass, argc); if (argc > 0 && argv) { ary_memcpy(ary, 0, argc, argv); ARY_SET_LEN(ary, argc); } return ary;}
new → new_empty_array click to toggle source
new(array) → new_array
new(size) → new_array
new(size, default_value) → new_array
new(size) {|index| ... } → new_array
Returns a new Array.
With no block and no arguments, returns a new empty Array object.
With no block and a single Array argument array
, returns a new Array formed from array
:
a = Array.new([:foo, 'bar', 2])a.class # => Arraya # => [:foo, "bar", 2]
With no block and a single Integer argument size
, returns a new Array of the given size whose elements are all nil
:
a = Array.new(3)a # => [nil, nil, nil]
With no block and arguments size
and default_value
, returns an Array of the given size; each element is that same default_value
:
a = Array.new(3, 'x')a # => ['x', 'x', 'x']
With a block and argument size
, returns an Array of the given size; the block is called with each successive integer index
; the element for that index
is the return value from the block:
a = Array.new(3) {|index| "Element #{index}" }a # => ["Element 0", "Element 1", "Element 2"]
Raises ArgumentError if size
is negative.
With a block and no argument, or a single argument 0
, ignores the block and returns a new empty Array.
static VALUErb_ary_initialize(int argc, VALUE *argv, VALUE ary){ long len; VALUE size, val; rb_ary_modify(ary); if (argc == 0) { if (ARY_OWNS_HEAP_P(ary) && ARY_HEAP_PTR(ary) != NULL) { ary_heap_free(ary); } rb_ary_unshare_safe(ary); FL_SET_EMBED(ary); ARY_SET_EMBED_LEN(ary, 0); if (rb_block_given_p()) { rb_warning("given block not used"); } return ary; } rb_scan_args(argc, argv, "02", &size, &val); if (argc == 1 && !FIXNUM_P(size)) { val = rb_check_array_type(size); if (!NIL_P(val)) { rb_ary_replace(ary, val); return ary; } } len = NUM2LONG(size); /* NUM2LONG() may call size.to_int, ary can be frozen, modified, etc */ if (len < 0) { rb_raise(rb_eArgError, "negative array size"); } if (len > ARY_MAX_SIZE) { rb_raise(rb_eArgError, "array size too big"); } /* recheck after argument conversion */ rb_ary_modify(ary); ary_resize_capa(ary, len); if (rb_block_given_p()) { long i; if (argc == 2) { rb_warn("block supersedes default value argument"); } for (i=0; i<len; i++) { rb_ary_store(ary, i, rb_yield(LONG2NUM(i))); ARY_SET_LEN(ary, i + 1); } } else { ary_memfill(ary, 0, len, val); ARY_SET_LEN(ary, len); } return ary;}
try_convert(object) → object, new_array, or nil click to toggle source
If object
is an Array object, returns object
.
Otherwise if object
responds to :to_ary
, calls object.to_ary
and returns the result.
Returns nil
if object
does not respond to :to_ary
Raises an exception unless object.to_ary
returns an Array object.
static VALUErb_ary_s_try_convert(VALUE dummy, VALUE ary){ return rb_check_array_type(ary);}
Public Instance Methods
array & other_array → new_array click to toggle source
Returns a new Array containing each element found in both array
and Array other_array
; duplicates are omitted; items are compared using eql?
:
[0, 1, 2, 3] & [1, 2] # => [1, 2][0, 1, 0, 1] & [0, 1] # => [0, 1]
Preserves order from array
:
[0, 1, 2] & [3, 2, 1, 0] # => [0, 1, 2]
Related: Array#intersection.
static VALUErb_ary_and(VALUE ary1, VALUE ary2){ VALUE hash, ary3, v; st_data_t vv; long i; ary2 = to_ary(ary2); ary3 = rb_ary_new(); if (RARRAY_LEN(ary1) == 0 || RARRAY_LEN(ary2) == 0) return ary3; if (RARRAY_LEN(ary1) <= SMALL_ARRAY_LEN && RARRAY_LEN(ary2) <= SMALL_ARRAY_LEN) { for (i=0; i<RARRAY_LEN(ary1); i++) { v = RARRAY_AREF(ary1, i); if (!rb_ary_includes_by_eql(ary2, v)) continue; if (rb_ary_includes_by_eql(ary3, v)) continue; rb_ary_push(ary3, v); } return ary3; } hash = ary_make_hash(ary2); for (i=0; i<RARRAY_LEN(ary1); i++) { v = RARRAY_AREF(ary1, i); vv = (st_data_t)v; if (rb_hash_stlike_delete(hash, &vv, 0)) { rb_ary_push(ary3, v); } } ary_recycle_hash(hash); return ary3;}
array * n → new_array click to toggle source
array * string_separator → new_string
When non-negative argument Integer n
is given, returns a new Array built by concatenating the n
copies of self
:
a = ['x', 'y']a * 3 # => ["x", "y", "x", "y", "x", "y"]
When String argument string_separator
is given, equivalent to array.join(string_separator)
:
[0, [0, 1], {foo: 0}] * ', ' # => "0, 0, 1, {:foo=>0}"
static VALUErb_ary_times(VALUE ary, VALUE times){ VALUE ary2, tmp; const VALUE *ptr; long t, len; tmp = rb_check_string_type(times); if (!NIL_P(tmp)) { return rb_ary_join(ary, tmp); } len = NUM2LONG(times); if (len == 0) { ary2 = ary_new(rb_cArray, 0); goto out; } if (len < 0) { rb_raise(rb_eArgError, "negative argument"); } if (ARY_MAX_SIZE/len < RARRAY_LEN(ary)) { rb_raise(rb_eArgError, "argument too big"); } len *= RARRAY_LEN(ary); ary2 = ary_new(rb_cArray, len); ARY_SET_LEN(ary2, len); ptr = RARRAY_CONST_PTR_TRANSIENT(ary); t = RARRAY_LEN(ary); if (0 < t) { ary_memcpy(ary2, 0, t, ptr); while (t <= len/2) { ary_memcpy(ary2, t, t, RARRAY_CONST_PTR_TRANSIENT(ary2)); t *= 2; } if (t < len) { ary_memcpy(ary2, t, len-t, RARRAY_CONST_PTR_TRANSIENT(ary2)); } } out: return ary2;}
array + other_array → new_array click to toggle source
Returns a new Array containing all elements of array
followed by all elements of other_array
:
a = [0, 1] + [2, 3]a # => [0, 1, 2, 3]
Related: concat.
VALUErb_ary_plus(VALUE x, VALUE y){ VALUE z; long len, xlen, ylen; y = to_ary(y); xlen = RARRAY_LEN(x); ylen = RARRAY_LEN(y); len = xlen + ylen; z = rb_ary_new2(len); ary_memcpy(z, 0, xlen, RARRAY_CONST_PTR_TRANSIENT(x)); ary_memcpy(z, xlen, ylen, RARRAY_CONST_PTR_TRANSIENT(y)); ARY_SET_LEN(z, len); return z;}
array - other_array → new_array click to toggle source
Returns a new Array containing only those elements from array
that are not found in Array other_array
; items are compared using eql?
; the order from array
is preserved:
[0, 1, 1, 2, 1, 1, 3, 1, 1] - [1] # => [0, 2, 3][0, 1, 2, 3] - [3, 0] # => [1, 2][0, 1, 2] - [4] # => [0, 1, 2]
Related: Array#difference.
static VALUErb_ary_diff(VALUE ary1, VALUE ary2){ VALUE ary3; VALUE hash; long i; ary2 = to_ary(ary2); if (RARRAY_LEN(ary2) == 0) { return ary_make_shared_copy(ary1); } ary3 = rb_ary_new(); if (RARRAY_LEN(ary1) <= SMALL_ARRAY_LEN || RARRAY_LEN(ary2) <= SMALL_ARRAY_LEN) { for (i=0; i<RARRAY_LEN(ary1); i++) { VALUE elt = rb_ary_elt(ary1, i); if (rb_ary_includes_by_eql(ary2, elt)) continue; rb_ary_push(ary3, elt); } return ary3; } hash = ary_make_hash(ary2); for (i=0; i<RARRAY_LEN(ary1); i++) { if (rb_hash_stlike_lookup(hash, RARRAY_AREF(ary1, i), NULL)) continue; rb_ary_push(ary3, rb_ary_elt(ary1, i)); } ary_recycle_hash(hash); return ary3;}
array << object → self click to toggle source
Appends object
to self
; returns self
:
a = [:foo, 'bar', 2]a << :baz # => [:foo, "bar", 2, :baz]
Appends object
as one element, even if it is another Array:
a = [:foo, 'bar', 2]a1 = a << [3, 4]a1 # => [:foo, "bar", 2, [3, 4]]
VALUErb_ary_push(VALUE ary, VALUE item){ long idx = RARRAY_LEN((ary_verify(ary), ary)); VALUE target_ary = ary_ensure_room_for_push(ary, 1); RARRAY_PTR_USE_TRANSIENT(ary, ptr, { RB_OBJ_WRITE(target_ary, &ptr[idx], item); }); ARY_SET_LEN(ary, idx + 1); ary_verify(ary); return ary;}
array <=> other_array → -1, 0, or 1 click to toggle source
Returns -1, 0, or 1 as self
is less than, equal to, or greater than other_array
. For each index i
in self
, evaluates result = self[i] <=> other_array[i]
.
Returns -1 if any result is -1:
[0, 1, 2] <=> [0, 1, 3] # => -1
Returns 1 if any result is 1:
[0, 1, 2] <=> [0, 1, 1] # => 1
When all results are zero:
Returns -1 if
array
is smaller thanother_array
:[0, 1, 2] <=> [0, 1, 2, 3] # => -1
Returns 1 if
array
is larger thanother_array
:[0, 1, 2] <=> [0, 1] # => 1
Returns 0 if
array
andother_array
are the same size:[0, 1, 2] <=> [0, 1, 2] # => 0
VALUErb_ary_cmp(VALUE ary1, VALUE ary2){ long len; VALUE v; ary2 = rb_check_array_type(ary2); if (NIL_P(ary2)) return Qnil; if (ary1 == ary2) return INT2FIX(0); v = rb_exec_recursive_paired(recursive_cmp, ary1, ary2, ary2); if (v != Qundef) return v; len = RARRAY_LEN(ary1) - RARRAY_LEN(ary2); if (len == 0) return INT2FIX(0); if (len > 0) return INT2FIX(1); return INT2FIX(-1);}
array == other_array → true or false click to toggle source
Returns true
if both array.size == other_array.size
and for each index i
in array
, array[i] == other_array[i]
:
a0 = [:foo, 'bar', 2]a1 = [:foo, 'bar', 2.0]a1 == a0 # => true[] == [] # => true
Otherwise, returns false
.
This method is different from method Array#eql?, which compares elements using Object#eql?
.
static VALUErb_ary_equal(VALUE ary1, VALUE ary2){ if (ary1 == ary2) return Qtrue; if (!RB_TYPE_P(ary2, T_ARRAY)) { if (!rb_respond_to(ary2, idTo_ary)) { return Qfalse; } return rb_equal(ary2, ary1); } if (RARRAY_LEN(ary1) != RARRAY_LEN(ary2)) return Qfalse; if (RARRAY_CONST_PTR_TRANSIENT(ary1) == RARRAY_CONST_PTR_TRANSIENT(ary2)) return Qtrue; return rb_exec_recursive_paired(recursive_equal, ary1, ary2, ary2);}
array[index] → object or nil click to toggle source
array[start, length] → object or nil
array[range] → object or nil
array[aseq] → object or nil
slice(index) → object or nil
slice(start, length) → object or nil
slice(range) → object or nil
slice(aseq) → object or nil
Returns elements from self
; does not modify self
.
When a single Integer argument index
is given, returns the element at offset index
:
a = [:foo, 'bar', 2]a[0] # => :fooa[2] # => 2a # => [:foo, "bar", 2]
If index
is negative, counts relative to the end of self
:
a = [:foo, 'bar', 2]a[-1] # => 2a[-2] # => "bar"
If index
is out of range, returns nil
.
When two Integer arguments start
and length
are given, returns a new Array of size length
containing successive elements beginning at offset start
:
a = [:foo, 'bar', 2]a[0, 2] # => [:foo, "bar"]a[1, 2] # => ["bar", 2]
If start + length
is greater than self.length
, returns all elements from offset start
to the end:
a = [:foo, 'bar', 2]a[0, 4] # => [:foo, "bar", 2]a[1, 3] # => ["bar", 2]a[2, 2] # => [2]
If start == self.size
and length >= 0
, returns a new empty Array.
If length
is negative, returns nil
.
When a single Range argument range
is given, treats range.min
as start
above and range.size
as length
above:
a = [:foo, 'bar', 2]a[0..1] # => [:foo, "bar"]a[1..2] # => ["bar", 2]
Special case: If range.start == a.size
, returns a new empty Array.
If range.end
is negative, calculates the end index from the end:
a = [:foo, 'bar', 2]a[0..-1] # => [:foo, "bar", 2]a[0..-2] # => [:foo, "bar"]a[0..-3] # => [:foo]
If range.start
is negative, calculates the start index from the end:
a = [:foo, 'bar', 2]a[-1..2] # => [2]a[-2..2] # => ["bar", 2]a[-3..2] # => [:foo, "bar", 2]
If range.start
is larger than the array size, returns nil
.
a = [:foo, 'bar', 2]a[4..1] # => nila[4..0] # => nila[4..-1] # => nil
When a single Enumerator::ArithmeticSequence argument aseq
is given, returns an Array of elements corresponding to the indexes produced by the sequence.
a = ['--', 'data1', '--', 'data2', '--', 'data3']a[(1..).step(2)] # => ["data1", "data2", "data3"]
Unlike slicing with range, if the start or the end of the arithmetic sequence is larger than array size, throws RangeError.
a = ['--', 'data1', '--', 'data2', '--', 'data3']a[(1..11).step(2)]# RangeError (((1..11).step(2)) out of range)a[(7..).step(2)]# RangeError (((7..).step(2)) out of range)
If given a single argument, and its type is not one of the listed, tries to convert it to Integer, and raises if it is impossible:
a = [:foo, 'bar', 2]# Raises TypeError (no implicit conversion of Symbol into Integer):a[:foo]
Array#slice is an alias for Array#[].
VALUErb_ary_aref(int argc, const VALUE *argv, VALUE ary){ rb_check_arity(argc, 1, 2); if (argc == 2) { return rb_ary_aref2(ary, argv[0], argv[1]); } return rb_ary_aref1(ary, argv[0]);}
array[index] = object → object click to toggle source
array[start, length] = object → object
array[range] = object → object
Assigns elements in self
; returns the given object
.
When Integer argument index
is given, assigns object
to an element in self
.
If index
is non-negative, assigns object
the element at offset index
:
a = [:foo, 'bar', 2]a[0] = 'foo' # => "foo"a # => ["foo", "bar", 2]
If index
is greater than self.length
, extends the array:
a = [:foo, 'bar', 2]a[7] = 'foo' # => "foo"a # => [:foo, "bar", 2, nil, nil, nil, nil, "foo"]
If index
is negative, counts backwards from the end of the array:
a = [:foo, 'bar', 2]a[-1] = 'two' # => "two"a # => [:foo, "bar", "two"]
When Integer arguments start
and length
are given and object
is not an Array, removes length - 1
elements beginning at offset start
, and assigns object
at offset start
:
a = [:foo, 'bar', 2]a[0, 2] = 'foo' # => "foo"a # => ["foo", 2]
If start
is negative, counts backwards from the end of the array:
a = [:foo, 'bar', 2]a[-2, 2] = 'foo' # => "foo"a # => [:foo, "foo"]
If start
is non-negative and outside the array ( >= self.size
), extends the array with nil
, assigns object
at offset start
, and ignores length
:
a = [:foo, 'bar', 2]a[6, 50] = 'foo' # => "foo"a # => [:foo, "bar", 2, nil, nil, nil, "foo"]
If length
is zero, shifts elements at and following offset start
and assigns object
at offset start
:
a = [:foo, 'bar', 2]a[1, 0] = 'foo' # => "foo"a # => [:foo, "foo", "bar", 2]
If length
is too large for the existing array, does not extend the array:
a = [:foo, 'bar', 2]a[1, 5] = 'foo' # => "foo"a # => [:foo, "foo"]
When Range argument range
is given and object
is an Array, removes length - 1
elements beginning at offset start
, and assigns object
at offset start
:
a = [:foo, 'bar', 2]a[0..1] = 'foo' # => "foo"a # => ["foo", 2]
if range.begin
is negative, counts backwards from the end of the array:
a = [:foo, 'bar', 2]a[-2..2] = 'foo' # => "foo"a # => [:foo, "foo"]
If the array length is less than range.begin
, assigns object
at offset range.begin
, and ignores length
:
a = [:foo, 'bar', 2]a[6..50] = 'foo' # => "foo"a # => [:foo, "bar", 2, nil, nil, nil, "foo"]
If range.end
is zero, shifts elements at and following offset start
and assigns object
at offset start
:
a = [:foo, 'bar', 2]a[1..0] = 'foo' # => "foo"a # => [:foo, "foo", "bar", 2]
If range.end
is negative, assigns object
at offset start
, retains range.end.abs -1
elements past that, and removes those beyond:
a = [:foo, 'bar', 2]a[1..-1] = 'foo' # => "foo"a # => [:foo, "foo"]a = [:foo, 'bar', 2]a[1..-2] = 'foo' # => "foo"a # => [:foo, "foo", 2]a = [:foo, 'bar', 2]a[1..-3] = 'foo' # => "foo"a # => [:foo, "foo", "bar", 2]a = [:foo, 'bar', 2]
If range.end
is too large for the existing array, replaces array elements, but does not extend the array with nil
values:
a = [:foo, 'bar', 2]a[1..5] = 'foo' # => "foo"a # => [:foo, "foo"]
static VALUErb_ary_aset(int argc, VALUE *argv, VALUE ary){ long offset, beg, len; rb_check_arity(argc, 2, 3); rb_ary_modify_check(ary); if (argc == 3) { beg = NUM2LONG(argv[0]); len = NUM2LONG(argv[1]); return ary_aset_by_rb_ary_splice(ary, beg, len, argv[2]); } if (FIXNUM_P(argv[0])) { offset = FIX2LONG(argv[0]); return ary_aset_by_rb_ary_store(ary, offset, argv[1]); } if (rb_range_beg_len(argv[0], &beg, &len, RARRAY_LEN(ary), 1)) { /* check if idx is Range */ return ary_aset_by_rb_ary_splice(ary, beg, len, argv[1]); } offset = NUM2LONG(argv[0]); return ary_aset_by_rb_ary_store(ary, offset, argv[1]);}
all? → true or false click to toggle source
all? {|element| ... } → true or false
all?(obj) → true or false
Returns true
if all elements of self
meet a given criterion.
With no block given and no argument, returns true
if self
contains only truthy elements, false
otherwise:
[0, 1, :foo].all? # => true[0, nil, 2].all? # => false[].all? # => true
With a block given and no argument, calls the block with each element in self
; returns true
if the block returns only truthy values, false
otherwise:
[0, 1, 2].all? { |element| element < 3 } # => true[0, 1, 2].all? { |element| element < 2 } # => false
If argument obj
is given, returns true
if obj.===
every element, false
otherwise:
['food', 'fool', 'foot'].all?(/foo/) # => true['food', 'drink'].all?(/bar/) # => false[].all?(/foo/) # => true[0, 0, 0].all?(0) # => true[0, 1, 2].all?(1) # => false
Related: Enumerable#all?
static VALUErb_ary_all_p(int argc, VALUE *argv, VALUE ary){ long i, len = RARRAY_LEN(ary); rb_check_arity(argc, 0, 1); if (!len) return Qtrue; if (argc) { if (rb_block_given_p()) { rb_warn("given block not used"); } for (i = 0; i < RARRAY_LEN(ary); ++i) { if (!RTEST(rb_funcall(argv[0], idEqq, 1, RARRAY_AREF(ary, i)))) return Qfalse; } } else if (!rb_block_given_p()) { for (i = 0; i < len; ++i) { if (!RTEST(RARRAY_AREF(ary, i))) return Qfalse; } } else { for (i = 0; i < RARRAY_LEN(ary); ++i) { if (!RTEST(rb_yield(RARRAY_AREF(ary, i)))) return Qfalse; } } return Qtrue;}
any? → true or false click to toggle source
any? {|element| ... } → true or false
any?(obj) → true or false
Returns true
if any element of self
meets a given criterion.
With no block given and no argument, returns true
if self
has any truthy element, false
otherwise:
[nil, 0, false].any? # => true[nil, false].any? # => false[].any? # => false
With a block given and no argument, calls the block with each element in self
; returns true
if the block returns any truthy value, false
otherwise:
[0, 1, 2].any? {|element| element > 1 } # => true[0, 1, 2].any? {|element| element > 2 } # => false
If argument obj
is given, returns true
if obj
.===
any element, false
otherwise:
['food', 'drink'].any?(/foo/) # => true['food', 'drink'].any?(/bar/) # => false[].any?(/foo/) # => false[0, 1, 2].any?(1) # => true[0, 1, 2].any?(3) # => false
Related: Enumerable#any?
static VALUErb_ary_any_p(int argc, VALUE *argv, VALUE ary){ long i, len = RARRAY_LEN(ary); rb_check_arity(argc, 0, 1); if (!len) return Qfalse; if (argc) { if (rb_block_given_p()) { rb_warn("given block not used"); } for (i = 0; i < RARRAY_LEN(ary); ++i) { if (RTEST(rb_funcall(argv[0], idEqq, 1, RARRAY_AREF(ary, i)))) return Qtrue; } } else if (!rb_block_given_p()) { for (i = 0; i < len; ++i) { if (RTEST(RARRAY_AREF(ary, i))) return Qtrue; } } else { for (i = 0; i < RARRAY_LEN(ary); ++i) { if (RTEST(rb_yield(RARRAY_AREF(ary, i)))) return Qtrue; } } return Qfalse;}
append(*args) click to toggle source
Alias for: push
assoc(obj) → found_array or nil click to toggle source
Returns the first element in self
that is an Array whose first element ==
obj
:
a = [{foo: 0}, [2, 4], [4, 5, 6], [4, 5]]a.assoc(4) # => [4, 5, 6]
Returns nil
if no such element is found.
Related: rassoc.
VALUErb_ary_assoc(VALUE ary, VALUE key){ long i; VALUE v; for (i = 0; i < RARRAY_LEN(ary); ++i) { v = rb_check_array_type(RARRAY_AREF(ary, i)); if (!NIL_P(v) && RARRAY_LEN(v) > 0 && rb_equal(RARRAY_AREF(v, 0), key)) return v; } return Qnil;}
at(index) → object click to toggle source
Returns the element at Integer offset index
; does not modify self
.
a = [:foo, 'bar', 2]a.at(0) # => :fooa.at(2) # => 2
VALUErb_ary_at(VALUE ary, VALUE pos){ return rb_ary_entry(ary, NUM2LONG(pos));}
bsearch {|element| ... } → object click to toggle source
bsearch → new_enumerator
Returns an element from self
selected by a binary search.
See Binary Searching.
static VALUErb_ary_bsearch(VALUE ary){ VALUE index_result = rb_ary_bsearch_index(ary); if (FIXNUM_P(index_result)) { return rb_ary_entry(ary, FIX2LONG(index_result)); } return index_result;}
bsearch_index {|element| ... } → integer or nil click to toggle source
bsearch_index → new_enumerator
Searches self
as described at method bsearch, but returns the index of the found element instead of the element itself.
static VALUErb_ary_bsearch_index(VALUE ary){ long low = 0, high = RARRAY_LEN(ary), mid; int smaller = 0, satisfied = 0; VALUE v, val; RETURN_ENUMERATOR(ary, 0, 0); while (low < high) { mid = low + ((high - low) / 2); val = rb_ary_entry(ary, mid); v = rb_yield(val); if (FIXNUM_P(v)) { if (v == INT2FIX(0)) return INT2FIX(mid); smaller = (SIGNED_VALUE)v < 0; /* Fixnum preserves its sign-bit */ } else if (v == Qtrue) { satisfied = 1; smaller = 1; } else if (!RTEST(v)) { smaller = 0; } else if (rb_obj_is_kind_of(v, rb_cNumeric)) { const VALUE zero = INT2FIX(0); switch (rb_cmpint(rb_funcallv(v, id_cmp, 1, &zero), v, zero)) { case 0: return INT2FIX(mid); case 1: smaller = 1; break; case -1: smaller = 0; } } else { rb_raise(rb_eTypeError, "wrong argument type %"PRIsVALUE " (must be numeric, true, false or nil)", rb_obj_class(v)); } if (smaller) { high = mid; } else { low = mid + 1; } } if (!satisfied) return Qnil; return INT2FIX(low);}
clear → self click to toggle source
Removes all elements from self
:
a = [:foo, 'bar', 2]a.clear # => []
VALUErb_ary_clear(VALUE ary){ rb_ary_modify_check(ary); if (ARY_SHARED_P(ary)) { if (!ARY_EMBED_P(ary)) { rb_ary_unshare(ary); FL_SET_EMBED(ary); ARY_SET_EMBED_LEN(ary, 0); } } else { ARY_SET_LEN(ary, 0); if (ARY_DEFAULT_SIZE * 2 < ARY_CAPA(ary)) { ary_resize_capa(ary, ARY_DEFAULT_SIZE * 2); } } ary_verify(ary); return ary;}
map {|element| ... } → new_array click to toggle source
map → new_enumerator
Calls the block, if given, with each element of self
; returns a new Array whose elements are the return values from the block:
a = [:foo, 'bar', 2]a1 = a.map {|element| element.class }a1 # => [Symbol, String, Integer]
Returns a new Enumerator if no block given:
a = [:foo, 'bar', 2]a1 = a.mapa1 # => #<Enumerator: [:foo, "bar", 2]:map>
Array#collect is an alias for Array#map.
static VALUErb_ary_collect(VALUE ary){ long i; VALUE collect; RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); collect = rb_ary_new2(RARRAY_LEN(ary)); for (i = 0; i < RARRAY_LEN(ary); i++) { rb_ary_push(collect, rb_yield(RARRAY_AREF(ary, i))); } return collect;}
map! {|element| ... } → self click to toggle source
map! → new_enumerator
Calls the block, if given, with each element; replaces the element with the block's return value:
a = [:foo, 'bar', 2]a.map! { |element| element.class } # => [Symbol, String, Integer]
Returns a new Enumerator if no block given:
a = [:foo, 'bar', 2]a1 = a.map!a1 # => #<Enumerator: [:foo, "bar", 2]:map!>
Array#collect! is an alias for Array#map!.
static VALUErb_ary_collect_bang(VALUE ary){ long i; RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); rb_ary_modify(ary); for (i = 0; i < RARRAY_LEN(ary); i++) { rb_ary_store(ary, i, rb_yield(RARRAY_AREF(ary, i))); } return ary;}
combination(n) {|element| ... } → self click to toggle source
combination(n) → new_enumerator
Calls the block, if given, with combinations of elements of self
; returns self
. The order of combinations is indeterminate.
When a block and an in-range positive Integer argument n
(0 < n <= self.size
) are given, calls the block with all n
-tuple combinations of self
.
Example:
a = [0, 1, 2]a.combination(2) {|combination| p combination }
Output:
[0, 1][0, 2][1, 2]
Another example:
a = [0, 1, 2]a.combination(3) {|combination| p combination }
Output:
[0, 1, 2]
When n
is zero, calls the block once with a new empty Array:
a = [0, 1, 2]a1 = a.combination(0) {|combination| p combination }
Output:
[]
When n
is out of range (negative or larger than self.size
), does not call the block:
a = [0, 1, 2]a.combination(-1) {|combination| fail 'Cannot happen' }a.combination(4) {|combination| fail 'Cannot happen' }
Returns a new Enumerator if no block given:
a = [0, 1, 2]a.combination(2) # => #<Enumerator: [0, 1, 2]:combination(2)>
static VALUErb_ary_combination(VALUE ary, VALUE num){ long i, n, len; n = NUM2LONG(num); RETURN_SIZED_ENUMERATOR(ary, 1, &num, rb_ary_combination_size); len = RARRAY_LEN(ary); if (n < 0 || len < n) { /* yield nothing */ } else if (n == 0) { rb_yield(rb_ary_new2(0)); } else if (n == 1) { for (i = 0; i < RARRAY_LEN(ary); i++) { rb_yield(rb_ary_new3(1, RARRAY_AREF(ary, i))); } } else { VALUE ary0 = ary_make_shared_copy(ary); /* private defensive copy of ary */ volatile VALUE t0; long *stack = ALLOCV_N(long, t0, n+1); RBASIC_CLEAR_CLASS(ary0); combinate0(len, n, stack, ary0); ALLOCV_END(t0); RBASIC_SET_CLASS_RAW(ary0, rb_cArray); } return ary;}
compact → new_array click to toggle source
Returns a new Array containing all non-nil
elements from self
:
a = [nil, 0, nil, 1, nil, 2, nil]a.compact # => [0, 1, 2]
static VALUErb_ary_compact(VALUE ary){ ary = rb_ary_dup(ary); rb_ary_compact_bang(ary); return ary;}
compact! → self or nil click to toggle source
Removes all nil
elements from self
.
Returns self
if any elements removed, otherwise nil
.
static VALUErb_ary_compact_bang(VALUE ary){ VALUE *p, *t, *end; long n; rb_ary_modify(ary); p = t = (VALUE *)RARRAY_CONST_PTR_TRANSIENT(ary); /* WB: no new reference */ end = p + RARRAY_LEN(ary); while (t < end) { if (NIL_P(*t)) t++; else *p++ = *t++; } n = p - RARRAY_CONST_PTR_TRANSIENT(ary); if (RARRAY_LEN(ary) == n) { return Qnil; } ary_resize_smaller(ary, n); return ary;}
concat(*other_arrays) → self click to toggle source
Adds to array
all elements from each Array in other_arrays
; returns self
:
a = [0, 1]a.concat([2, 3], [4, 5]) # => [0, 1, 2, 3, 4, 5]
static VALUErb_ary_concat_multi(int argc, VALUE *argv, VALUE ary){ rb_ary_modify_check(ary); if (argc == 1) { rb_ary_concat(ary, argv[0]); } else if (argc > 1) { int i; VALUE args = rb_ary_tmp_new(argc); for (i = 0; i < argc; i++) { rb_ary_concat(args, argv[i]); } ary_append(ary, args); } ary_verify(ary); return ary;}
count → an_integer click to toggle source
count(obj) → an_integer
count {|element| ... } → an_integer
Returns a count of specified elements.
With no argument and no block, returns the count of all elements:
[0, 1, 2].count # => 3[].count # => 0
With argument obj
, returns the count of elements ==
to obj
:
[0, 1, 2, 0.0].count(0) # => 2[0, 1, 2].count(3) # => 0
With no argument and a block given, calls the block with each element; returns the count of elements for which the block returns a truthy value:
[0, 1, 2, 3].count {|element| element > 1} # => 2
With argument obj
and a block given, issues a warning, ignores the block, and returns the count of elements ==
to obj
:
static VALUErb_ary_count(int argc, VALUE *argv, VALUE ary){ long i, n = 0; if (rb_check_arity(argc, 0, 1) == 0) { VALUE v; if (!rb_block_given_p()) return LONG2NUM(RARRAY_LEN(ary)); for (i = 0; i < RARRAY_LEN(ary); i++) { v = RARRAY_AREF(ary, i); if (RTEST(rb_yield(v))) n++; } } else { VALUE obj = argv[0]; if (rb_block_given_p()) { rb_warn("given block not used"); } for (i = 0; i < RARRAY_LEN(ary); i++) { if (rb_equal(RARRAY_AREF(ary, i), obj)) n++; } } return LONG2NUM(n);}
cycle {|element| ... } → nil click to toggle source
cycle(count) {|element| ... } → nil
cycle → new_enumerator
cycle(count) → new_enumerator
When called with positive Integer argument count
and a block, calls the block with each element, then does so again, until it has done so count
times; returns nil
:
output = [][0, 1].cycle(2) {|element| output.push(element) } # => niloutput # => [0, 1, 0, 1]
If count
is zero or negative, does not call the block:
[0, 1].cycle(0) {|element| fail 'Cannot happen' } # => nil[0, 1].cycle(-1) {|element| fail 'Cannot happen' } # => nil
When a block is given, and argument is omitted or nil
, cycles forever:
# Prints 0 and 1 forever.[0, 1].cycle {|element| puts element }[0, 1].cycle(nil) {|element| puts element }
When no block is given, returns a new Enumerator:
[0, 1].cycle(2) # => #<Enumerator: [0, 1]:cycle(2)>[0, 1].cycle # => # => #<Enumerator: [0, 1]:cycle>[0, 1].cycle.first(5) # => [0, 1, 0, 1, 0]
static VALUErb_ary_cycle(int argc, VALUE *argv, VALUE ary){ long n, i; rb_check_arity(argc, 0, 1); RETURN_SIZED_ENUMERATOR(ary, argc, argv, rb_ary_cycle_size); if (argc == 0 || NIL_P(argv[0])) { n = -1; } else { n = NUM2LONG(argv[0]); if (n <= 0) return Qnil; } while (RARRAY_LEN(ary) > 0 && (n < 0 || 0 < n--)) { for (i=0; i<RARRAY_LEN(ary); i++) { rb_yield(RARRAY_AREF(ary, i)); } } return Qnil;}
deconstruct() click to toggle source
static VALUErb_ary_deconstruct(VALUE ary){ return ary;}
delete(obj) → deleted_object click to toggle source
delete(obj) {|nosuch| ... } → deleted_object or block_return
Removes zero or more elements from self
; returns self
.
When no block is given, removes from self
each element ele
such that ele == obj
; returns the last deleted element:
s1 = 'bar'; s2 = 'bar'a = [:foo, s1, 2, s2]a.delete('bar') # => "bar"a # => [:foo, 2]
Returns nil
if no elements removed.
When a block is given, removes from self
each element ele
such that ele == obj
.
If any such elements are found, ignores the block and returns the last deleted element:
s1 = 'bar'; s2 = 'bar'a = [:foo, s1, 2, s2]deleted_obj = a.delete('bar') {|obj| fail 'Cannot happen' }a # => [:foo, 2]
If no such elements are found, returns the block's return value:
a = [:foo, 'bar', 2]a.delete(:nosuch) {|obj| "#{obj} not found" } # => "nosuch not found"
VALUErb_ary_delete(VALUE ary, VALUE item){ VALUE v = item; long i1, i2; for (i1 = i2 = 0; i1 < RARRAY_LEN(ary); i1++) { VALUE e = RARRAY_AREF(ary, i1); if (rb_equal(e, item)) { v = e; continue; } if (i1 != i2) { rb_ary_store(ary, i2, e); } i2++; } if (RARRAY_LEN(ary) == i2) { if (rb_block_given_p()) { return rb_yield(item); } return Qnil; } ary_resize_smaller(ary, i2); ary_verify(ary); return v;}
delete_at(index) → deleted_object or nil click to toggle source
Deletes an element from self
, per the given Integer index
.
When index
is non-negative, deletes the element at offset index
:
a = [:foo, 'bar', 2]a.delete_at(1) # => "bar"a # => [:foo, 2]
If index is too large, returns nil
.
When index
is negative, counts backward from the end of the array:
a = [:foo, 'bar', 2]a.delete_at(-2) # => "bar"a # => [:foo, 2]
If index
is too small (far from zero), returns nil.
static VALUErb_ary_delete_at_m(VALUE ary, VALUE pos){ return rb_ary_delete_at(ary, NUM2LONG(pos));}
delete_if {|element| ... } → self click to toggle source
delete_if → Enumerator
Removes each element in self
for which the block returns a truthy value; returns self
:
a = [:foo, 'bar', 2, 'bat']a.delete_if {|element| element.to_s.start_with?('b') } # => [:foo, 2]
Returns a new Enumerator if no block given:
a = [:foo, 'bar', 2]a.delete_if # => #<Enumerator: [:foo, "bar", 2]:delete_if>
static VALUErb_ary_delete_if(VALUE ary){ ary_verify(ary); RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); ary_reject_bang(ary); return ary;}
difference(*other_arrays) → new_array click to toggle source
Returns a new Array containing only those elements from self
that are not found in any of the Arrays other_arrays
; items are compared using eql?
; order from self
is preserved:
[0, 1, 1, 2, 1, 1, 3, 1, 1].difference([1]) # => [0, 2, 3][0, 1, 2, 3].difference([3, 0], [1, 3]) # => [2][0, 1, 2].difference([4]) # => [0, 1, 2]
Returns a copy of self
if no arguments given.
Related: Array#-.
static VALUErb_ary_difference_multi(int argc, VALUE *argv, VALUE ary){ VALUE ary_diff; long i, length; volatile VALUE t0; bool *is_hash = ALLOCV_N(bool, t0, argc); ary_diff = rb_ary_new(); length = RARRAY_LEN(ary); for (i = 0; i < argc; i++) { argv[i] = to_ary(argv[i]); is_hash[i] = (length > SMALL_ARRAY_LEN && RARRAY_LEN(argv[i]) > SMALL_ARRAY_LEN); if (is_hash[i]) argv[i] = ary_make_hash(argv[i]); } for (i = 0; i < RARRAY_LEN(ary); i++) { int j; VALUE elt = rb_ary_elt(ary, i); for (j = 0; j < argc; j++) { if (is_hash[j]) { if (rb_hash_stlike_lookup(argv[j], RARRAY_AREF(ary, i), NULL)) break; } else { if (rb_ary_includes_by_eql(argv[j], elt)) break; } } if (j == argc) rb_ary_push(ary_diff, elt); } ALLOCV_END(t0); return ary_diff;}
dig(index, *identifiers) → object click to toggle source
Finds and returns the object in nested objects that is specified by index
and identifiers
. The nested objects may be instances of various classes. See Dig Methods.
Examples:
a = [:foo, [:bar, :baz, [:bat, :bam]]]a.dig(1) # => [:bar, :baz, [:bat, :bam]]a.dig(1, 2) # => [:bat, :bam]a.dig(1, 2, 0) # => :bata.dig(1, 2, 3) # => nil
static VALUErb_ary_dig(int argc, VALUE *argv, VALUE self){ rb_check_arity(argc, 1, UNLIMITED_ARGUMENTS); self = rb_ary_at(self, *argv); if (!--argc) return self; ++argv; return rb_obj_dig(argc, argv, self, Qnil);}
drop(n) → new_array click to toggle source
Returns a new Array containing all but the first n
element of self
, where n
is a non-negative Integer; does not modify self
.
Examples:
a = [0, 1, 2, 3, 4, 5]a.drop(0) # => [0, 1, 2, 3, 4, 5]a.drop(1) # => [1, 2, 3, 4, 5]a.drop(2) # => [2, 3, 4, 5]
static VALUErb_ary_drop(VALUE ary, VALUE n){ VALUE result; long pos = NUM2LONG(n); if (pos < 0) { rb_raise(rb_eArgError, "attempt to drop negative size"); } result = rb_ary_subseq(ary, pos, RARRAY_LEN(ary)); if (NIL_P(result)) result = rb_ary_new(); return result;}
drop_while {|element| ... } → new_array click to toggle source
drop_while → new_enumerator
Returns a new Array containing zero or more trailing elements of self
; does not modify self
.
With a block given, calls the block with each successive element of self
; stops if the block returns false
or nil
; returns a new Array omitting those elements for which the block returned a truthy value:
a = [0, 1, 2, 3, 4, 5]a.drop_while {|element| element < 3 } # => [3, 4, 5]
With no block given, returns a new Enumerator:
[0, 1].drop_while # => # => #<Enumerator: [0, 1]:drop_while>
static VALUErb_ary_drop_while(VALUE ary){ long i; RETURN_ENUMERATOR(ary, 0, 0); for (i = 0; i < RARRAY_LEN(ary); i++) { if (!RTEST(rb_yield(RARRAY_AREF(ary, i)))) break; } return rb_ary_drop(ary, LONG2FIX(i));}
each {|element| ... } → self click to toggle source
each → Enumerator
Iterates over array elements.
When a block given, passes each successive array element to the block; returns self
:
a = [:foo, 'bar', 2]a.each {|element| puts "#{element.class} #{element}" }
Output:
Symbol fooString barInteger 2
Allows the array to be modified during iteration:
a = [:foo, 'bar', 2]a.each {|element| puts element; a.clear if element.to_s.start_with?('b') }
Output:
foobar
When no block given, returns a new Enumerator:
a = [:foo, 'bar', 2]e = a.eache # => #<Enumerator: [:foo, "bar", 2]:each>a1 = e.each {|element| puts "#{element.class} #{element}" }
Output:
Symbol fooString barInteger 2
Related: each_index, reverse_each.
VALUErb_ary_each(VALUE ary){ long i; ary_verify(ary); RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); for (i=0; i<RARRAY_LEN(ary); i++) { rb_yield(RARRAY_AREF(ary, i)); } return ary;}
each_index {|index| ... } → self click to toggle source
each_index → Enumerator
Iterates over array indexes.
When a block given, passes each successive array index to the block; returns self
:
a = [:foo, 'bar', 2]a.each_index {|index| puts "#{index} #{a[index]}" }
Output:
0 foo1 bar2 2
Allows the array to be modified during iteration:
a = [:foo, 'bar', 2]a.each_index {|index| puts index; a.clear if index > 0 }
Output:
01
When no block given, returns a new Enumerator:
a = [:foo, 'bar', 2]e = a.each_indexe # => #<Enumerator: [:foo, "bar", 2]:each_index>a1 = e.each {|index| puts "#{index} #{a[index]}"}
Output:
0 foo1 bar2 2
Related: each, reverse_each.
static VALUErb_ary_each_index(VALUE ary){ long i; RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); for (i=0; i<RARRAY_LEN(ary); i++) { rb_yield(LONG2NUM(i)); } return ary;}
empty? → true or false click to toggle source
Returns true
if the count of elements in self
is zero, false
otherwise.
static VALUErb_ary_empty_p(VALUE ary){ return RBOOL(RARRAY_LEN(ary) == 0);}
eql? other_array → true or false click to toggle source
Returns true
if self
and other_array
are the same size, and if, for each index i
in self
, self[i].eql? other_array[i]
:
a0 = [:foo, 'bar', 2]a1 = [:foo, 'bar', 2]a1.eql?(a0) # => true
Otherwise, returns false
.
This method is different from method Array#==, which compares using method Object#==
.
static VALUErb_ary_eql(VALUE ary1, VALUE ary2){ if (ary1 == ary2) return Qtrue; if (!RB_TYPE_P(ary2, T_ARRAY)) return Qfalse; if (RARRAY_LEN(ary1) != RARRAY_LEN(ary2)) return Qfalse; if (RARRAY_CONST_PTR_TRANSIENT(ary1) == RARRAY_CONST_PTR_TRANSIENT(ary2)) return Qtrue; return rb_exec_recursive_paired(recursive_eql, ary1, ary2, ary2);}
fetch(index) → element click to toggle source
fetch(index, default_value) → element
fetch(index) {|index| ... } → element
Returns the element at offset index
.
With the single Integer argument index
, returns the element at offset index
:
a = [:foo, 'bar', 2]a.fetch(1) # => "bar"
If index
is negative, counts from the end of the array:
a = [:foo, 'bar', 2]a.fetch(-1) # => 2a.fetch(-2) # => "bar"
With arguments index
and default_value
, returns the element at offset index
if index is in range, otherwise returns default_value
:
a = [:foo, 'bar', 2]a.fetch(1, nil) # => "bar"
With argument index
and a block, returns the element at offset index
if index is in range (and the block is not called); otherwise calls the block with index and returns its return value:
a = [:foo, 'bar', 2]a.fetch(1) {|index| raise 'Cannot happen' } # => "bar"a.fetch(50) {|index| "Value for #{index}" } # => "Value for 50"
static VALUErb_ary_fetch(int argc, VALUE *argv, VALUE ary){ VALUE pos, ifnone; long block_given; long idx; rb_scan_args(argc, argv, "11", &pos, &ifnone); block_given = rb_block_given_p(); if (block_given && argc == 2) { rb_warn("block supersedes default value argument"); } idx = NUM2LONG(pos); if (idx < 0) { idx += RARRAY_LEN(ary); } if (idx < 0 || RARRAY_LEN(ary) <= idx) { if (block_given) return rb_yield(pos); if (argc == 1) { rb_raise(rb_eIndexError, "index %ld outside of array bounds: %ld...%ld", idx - (idx < 0 ? RARRAY_LEN(ary) : 0), -RARRAY_LEN(ary), RARRAY_LEN(ary)); } return ifnone; } return RARRAY_AREF(ary, idx);}
fill(obj) → self click to toggle source
fill(obj, start) → self
fill(obj, start, length) → self
fill(obj, range) → self
fill {|index| ... } → self
fill(start) {|index| ... } → self
fill(start, length) {|index| ... } → self
fill(range) {|index| ... } → self
Replaces specified elements in self
with specified objects; returns self
.
With argument obj
and no block given, replaces all elements with that one object:
a = ['a', 'b', 'c', 'd']a # => ["a", "b", "c", "d"]a.fill(:X) # => [:X, :X, :X, :X]
With arguments obj
and Integer start
, and no block given, replaces elements based on the given start.
If start
is in range (0 <= start < array.size
), replaces all elements from offset start
through the end:
a = ['a', 'b', 'c', 'd']a.fill(:X, 2) # => ["a", "b", :X, :X]
If start
is too large (start >= array.size
), does nothing:
a = ['a', 'b', 'c', 'd']a.fill(:X, 4) # => ["a", "b", "c", "d"]a = ['a', 'b', 'c', 'd']a.fill(:X, 5) # => ["a", "b", "c", "d"]
If start
is negative, counts from the end (starting index is start + array.size
):
a = ['a', 'b', 'c', 'd']a.fill(:X, -2) # => ["a", "b", :X, :X]
If start
is too small (less than and far from zero), replaces all elements:
a = ['a', 'b', 'c', 'd']a.fill(:X, -6) # => [:X, :X, :X, :X]a = ['a', 'b', 'c', 'd']a.fill(:X, -50) # => [:X, :X, :X, :X]
With arguments obj
, Integer start
, and Integer length
, and no block given, replaces elements based on the given start
and length
.
If start
is in range, replaces length
elements beginning at offset start
:
a = ['a', 'b', 'c', 'd']a.fill(:X, 1, 1) # => ["a", :X, "c", "d"]
If start
is negative, counts from the end:
a = ['a', 'b', 'c', 'd']a.fill(:X, -2, 1) # => ["a", "b", :X, "d"]
If start
is large (start >= array.size
), extends self
with nil
:
a = ['a', 'b', 'c', 'd']a.fill(:X, 5, 0) # => ["a", "b", "c", "d", nil]a = ['a', 'b', 'c', 'd']a.fill(:X, 5, 2) # => ["a", "b", "c", "d", nil, :X, :X]
If length
is zero or negative, replaces no elements:
a = ['a', 'b', 'c', 'd']a.fill(:X, 1, 0) # => ["a", "b", "c", "d"]a.fill(:X, 1, -1) # => ["a", "b", "c", "d"]
With arguments obj
and Range range
, and no block given, replaces elements based on the given range.
If the range is positive and ascending (0 < range.begin <= range.end
), replaces elements from range.begin
to range.end
:
a = ['a', 'b', 'c', 'd']a.fill(:X, (1..1)) # => ["a", :X, "c", "d"]
If range.first
is negative, replaces no elements:
a = ['a', 'b', 'c', 'd']a.fill(:X, (-1..1)) # => ["a", "b", "c", "d"]
If range.last
is negative, counts from the end:
a = ['a', 'b', 'c', 'd']a.fill(:X, (0..-2)) # => [:X, :X, :X, "d"]a = ['a', 'b', 'c', 'd']a.fill(:X, (1..-2)) # => ["a", :X, :X, "d"]
If range.last
and range.last
are both negative, both count from the end of the array:
a = ['a', 'b', 'c', 'd']a.fill(:X, (-1..-1)) # => ["a", "b", "c", :X]a = ['a', 'b', 'c', 'd']a.fill(:X, (-2..-2)) # => ["a", "b", :X, "d"]
With no arguments and a block given, calls the block with each index; replaces the corresponding element with the block's return value:
a = ['a', 'b', 'c', 'd']a.fill { |index| "new_#{index}" } # => ["new_0", "new_1", "new_2", "new_3"]
With argument start
and a block given, calls the block with each index from offset start
to the end; replaces the corresponding element with the block's return value:
If start is in range (0 <= start < array.size
), replaces from offset start
to the end:
a = ['a', 'b', 'c', 'd']a.fill(1) { |index| "new_#{index}" } # => ["a", "new_1", "new_2", "new_3"]
If start
is too large(start >= array.size
), does nothing:
a = ['a', 'b', 'c', 'd']a.fill(4) { |index| fail 'Cannot happen' } # => ["a", "b", "c", "d"]a = ['a', 'b', 'c', 'd']a.fill(4) { |index| fail 'Cannot happen' } # => ["a", "b", "c", "d"]
If start
is negative, counts from the end:
a = ['a', 'b', 'c', 'd']a.fill(-2) { |index| "new_#{index}" } # => ["a", "b", "new_2", "new_3"]
If start is too small (start <= -array.size
, replaces all elements:
a = ['a', 'b', 'c', 'd']a.fill(-6) { |index| "new_#{index}" } # => ["new_0", "new_1", "new_2", "new_3"]a = ['a', 'b', 'c', 'd']a.fill(-50) { |index| "new_#{index}" } # => ["new_0", "new_1", "new_2", "new_3"]
With arguments start
and length
, and a block given, calls the block for each index specified by start length; replaces the corresponding element with the block's return value.
If start
is in range, replaces length
elements beginning at offset start
:
a = ['a', 'b', 'c', 'd']a.fill(1, 1) { |index| "new_#{index}" } # => ["a", "new_1", "c", "d"]
If start is negative, counts from the end:
a = ['a', 'b', 'c', 'd']a.fill(-2, 1) { |index| "new_#{index}" } # => ["a", "b", "new_2", "d"]
If start
is large (start >= array.size
), extends self
with nil
:
a = ['a', 'b', 'c', 'd']a.fill(5, 0) { |index| "new_#{index}" } # => ["a", "b", "c", "d", nil]a = ['a', 'b', 'c', 'd']a.fill(5, 2) { |index| "new_#{index}" } # => ["a", "b", "c", "d", nil, "new_5", "new_6"]
If length
is zero or less, replaces no elements:
a = ['a', 'b', 'c', 'd']a.fill(1, 0) { |index| "new_#{index}" } # => ["a", "b", "c", "d"]a.fill(1, -1) { |index| "new_#{index}" } # => ["a", "b", "c", "d"]
With arguments obj
and range
, and a block given, calls the block with each index in the given range; replaces the corresponding element with the block's return value.
If the range is positive and ascending (range 0 < range.begin <= range.end
, replaces elements from range.begin
to range.end
:
a = ['a', 'b', 'c', 'd']a.fill(1..1) { |index| "new_#{index}" } # => ["a", "new_1", "c", "d"]
If range.first
is negative, does nothing:
a = ['a', 'b', 'c', 'd']a.fill(-1..1) { |index| fail 'Cannot happen' } # => ["a", "b", "c", "d"]
If range.last
is negative, counts from the end:
a = ['a', 'b', 'c', 'd']a.fill(0..-2) { |index| "new_#{index}" } # => ["new_0", "new_1", "new_2", "d"]a = ['a', 'b', 'c', 'd']a.fill(1..-2) { |index| "new_#{index}" } # => ["a", "new_1", "new_2", "d"]
If range.first
and range.last
are both negative, both count from the end:
a = ['a', 'b', 'c', 'd']a.fill(-1..-1) { |index| "new_#{index}" } # => ["a", "b", "c", "new_3"]a = ['a', 'b', 'c', 'd']a.fill(-2..-2) { |index| "new_#{index}" } # => ["a", "b", "new_2", "d"]
static VALUErb_ary_fill(int argc, VALUE *argv, VALUE ary){ VALUE item = Qundef, arg1, arg2; long beg = 0, end = 0, len = 0; if (rb_block_given_p()) { rb_scan_args(argc, argv, "02", &arg1, &arg2); argc += 1; /* hackish */ } else { rb_scan_args(argc, argv, "12", &item, &arg1, &arg2); } switch (argc) { case 1: beg = 0; len = RARRAY_LEN(ary); break; case 2: if (rb_range_beg_len(arg1, &beg, &len, RARRAY_LEN(ary), 1)) { break; } /* fall through */ case 3: beg = NIL_P(arg1) ? 0 : NUM2LONG(arg1); if (beg < 0) { beg = RARRAY_LEN(ary) + beg; if (beg < 0) beg = 0; } len = NIL_P(arg2) ? RARRAY_LEN(ary) - beg : NUM2LONG(arg2); break; } rb_ary_modify(ary); if (len < 0) { return ary; } if (beg >= ARY_MAX_SIZE || len > ARY_MAX_SIZE - beg) { rb_raise(rb_eArgError, "argument too big"); } end = beg + len; if (RARRAY_LEN(ary) < end) { if (end >= ARY_CAPA(ary)) { ary_resize_capa(ary, end); } ary_mem_clear(ary, RARRAY_LEN(ary), end - RARRAY_LEN(ary)); ARY_SET_LEN(ary, end); } if (item == Qundef) { VALUE v; long i; for (i=beg; i<end; i++) { v = rb_yield(LONG2NUM(i)); if (i>=RARRAY_LEN(ary)) break; ARY_SET(ary, i, v); } } else { ary_memfill(ary, beg, len, item); } return ary;}
select {|element| ... } → new_array click to toggle source
select → new_enumerator
Calls the block, if given, with each element of self
; returns a new Array containing those elements of self
for which the block returns a truthy value:
a = [:foo, 'bar', 2, :bam]a1 = a.select {|element| element.to_s.start_with?('b') }a1 # => ["bar", :bam]
Returns a new Enumerator if no block given:
a = [:foo, 'bar', 2, :bam]a.select # => #<Enumerator: [:foo, "bar", 2, :bam]:select>
Array#filter is an alias for Array#select.
static VALUErb_ary_select(VALUE ary){ VALUE result; long i; RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); result = rb_ary_new2(RARRAY_LEN(ary)); for (i = 0; i < RARRAY_LEN(ary); i++) { if (RTEST(rb_yield(RARRAY_AREF(ary, i)))) { rb_ary_push(result, rb_ary_elt(ary, i)); } } return result;}
select! {|element| ... } → self or nil click to toggle source
select! → new_enumerator
Calls the block, if given with each element of self
; removes from self
those elements for which the block returns false
or nil
.
Returns self
if any elements were removed:
a = [:foo, 'bar', 2, :bam]a.select! {|element| element.to_s.start_with?('b') } # => ["bar", :bam]
Returns nil
if no elements were removed.
Returns a new Enumerator if no block given:
a = [:foo, 'bar', 2, :bam]a.select! # => #<Enumerator: [:foo, "bar", 2, :bam]:select!>
Array#filter! is an alias for Array#select!.
static VALUErb_ary_select_bang(VALUE ary){ struct select_bang_arg args; RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); rb_ary_modify(ary); args.ary = ary; args.len[0] = args.len[1] = 0; return rb_ensure(select_bang_i, (VALUE)&args, select_bang_ensure, (VALUE)&args);}
index(object) → integer or nil click to toggle source
index {|element| ... } → integer or nil
index → new_enumerator
Returns the index of a specified element.
When argument object
is given but no block, returns the index of the first element element
for which object == element
:
a = [:foo, 'bar', 2, 'bar']a.index('bar') # => 1
Returns nil
if no such element found.
When both argument object
and a block are given, calls the block with each successive element; returns the index of the first element for which the block returns a truthy value:
a = [:foo, 'bar', 2, 'bar']a.index {|element| element == 'bar' } # => 1
Returns nil
if the block never returns a truthy value.
When neither an argument nor a block is given, returns a new Enumerator:
a = [:foo, 'bar', 2]e = a.indexe # => #<Enumerator: [:foo, "bar", 2]:index>e.each {|element| element == 'bar' } # => 1
Array#find_index is an alias for Array#index.
Related: rindex.
static VALUErb_ary_index(int argc, VALUE *argv, VALUE ary){ VALUE val; long i; if (argc == 0) { RETURN_ENUMERATOR(ary, 0, 0); for (i=0; i<RARRAY_LEN(ary); i++) { if (RTEST(rb_yield(RARRAY_AREF(ary, i)))) { return LONG2NUM(i); } } return Qnil; } rb_check_arity(argc, 0, 1); val = argv[0]; if (rb_block_given_p()) rb_warn("given block not used"); for (i=0; i<RARRAY_LEN(ary); i++) { VALUE e = RARRAY_AREF(ary, i); if (rb_equal(e, val)) { return LONG2NUM(i); } } return Qnil;}
first → object or nil click to toggle source
first(n) → new_array
Returns elements from self
; does not modify self
.
When no argument is given, returns the first element:
a = [:foo, 'bar', 2]a.first # => :fooa # => [:foo, "bar", 2]
If self
is empty, returns nil
.
When non-negative Integer argument n
is given, returns the first n
elements in a new Array:
a = [:foo, 'bar', 2]a.first(2) # => [:foo, "bar"]
If n >= array.size
, returns all elements:
a = [:foo, 'bar', 2]a.first(50) # => [:foo, "bar", 2]
If n == 0
returns an new empty Array:
a = [:foo, 'bar', 2]a.first(0) # []
Related: last.
static VALUErb_ary_first(int argc, VALUE *argv, VALUE ary){ if (argc == 0) { if (RARRAY_LEN(ary) == 0) return Qnil; return RARRAY_AREF(ary, 0); } else { return ary_take_first_or_last(argc, argv, ary, ARY_TAKE_FIRST); }}
flatten → new_array click to toggle source
flatten(level) → new_array
Returns a new Array that is a recursive flattening of self
:
Each non-Array element is unchanged.
Each Array is replaced by its individual elements.
With non-negative Integer argument level
, flattens recursively through level
levels:
a = [ 0, [ 1, [2, 3], 4 ], 5 ]a.flatten(0) # => [0, [1, [2, 3], 4], 5]a = [ 0, [ 1, [2, 3], 4 ], 5 ]a.flatten(1) # => [0, 1, [2, 3], 4, 5]a = [ 0, [ 1, [2, 3], 4 ], 5 ]a.flatten(2) # => [0, 1, 2, 3, 4, 5]a = [ 0, [ 1, [2, 3], 4 ], 5 ]a.flatten(3) # => [0, 1, 2, 3, 4, 5]
With no argument, a nil
argument, or with negative argument level
, flattens all levels:
a = [ 0, [ 1, [2, 3], 4 ], 5 ]a.flatten # => [0, 1, 2, 3, 4, 5][0, 1, 2].flatten # => [0, 1, 2]a = [ 0, [ 1, [2, 3], 4 ], 5 ]a.flatten(-1) # => [0, 1, 2, 3, 4, 5]a = [ 0, [ 1, [2, 3], 4 ], 5 ]a.flatten(-2) # => [0, 1, 2, 3, 4, 5][0, 1, 2].flatten(-1) # => [0, 1, 2]
static VALUErb_ary_flatten(int argc, VALUE *argv, VALUE ary){ int level = -1; VALUE result; if (rb_check_arity(argc, 0, 1) && !NIL_P(argv[0])) { level = NUM2INT(argv[0]); if (level == 0) return ary_make_shared_copy(ary); } result = flatten(ary, level); if (result == ary) { result = ary_make_shared_copy(ary); } return result;}
flatten! → self or nil click to toggle source
flatten!(level) → self or nil
Replaces each nested Array in self
with the elements from that Array; returns self
if any changes, nil
otherwise.
With non-negative Integer argument level
, flattens recursively through level
levels:
a = [ 0, [ 1, [2, 3], 4 ], 5 ]a.flatten!(1) # => [0, 1, [2, 3], 4, 5]a = [ 0, [ 1, [2, 3], 4 ], 5 ]a.flatten!(2) # => [0, 1, 2, 3, 4, 5]a = [ 0, [ 1, [2, 3], 4 ], 5 ]a.flatten!(3) # => [0, 1, 2, 3, 4, 5][0, 1, 2].flatten!(1) # => nil
With no argument, a nil
argument, or with negative argument level
, flattens all levels:
a = [ 0, [ 1, [2, 3], 4 ], 5 ]a.flatten! # => [0, 1, 2, 3, 4, 5][0, 1, 2].flatten! # => nila = [ 0, [ 1, [2, 3], 4 ], 5 ]a.flatten!(-1) # => [0, 1, 2, 3, 4, 5]a = [ 0, [ 1, [2, 3], 4 ], 5 ]a.flatten!(-2) # => [0, 1, 2, 3, 4, 5][0, 1, 2].flatten!(-1) # => nil
static VALUErb_ary_flatten_bang(int argc, VALUE *argv, VALUE ary){ int mod = 0, level = -1; VALUE result, lv; lv = (rb_check_arity(argc, 0, 1) ? argv[0] : Qnil); rb_ary_modify_check(ary); if (!NIL_P(lv)) level = NUM2INT(lv); if (level == 0) return Qnil; result = flatten(ary, level); if (result == ary) { return Qnil; } if (!(mod = ARY_EMBED_P(result))) rb_obj_freeze(result); rb_ary_replace(ary, result); if (mod) ARY_SET_EMBED_LEN(result, 0); return ary;}
hash → integer click to toggle source
Returns the integer hash value for self
.
Two arrays with the same content will have the same hash code (and will compare using eql?):
[0, 1, 2].hash == [0, 1, 2].hash # => true[0, 1, 2].hash == [0, 1, 3].hash # => false
static VALUErb_ary_hash(VALUE ary){ long i; st_index_t h; VALUE n; h = rb_hash_start(RARRAY_LEN(ary)); h = rb_hash_uint(h, (st_index_t)rb_ary_hash); for (i=0; i<RARRAY_LEN(ary); i++) { n = rb_hash(RARRAY_AREF(ary, i)); h = rb_hash_uint(h, NUM2LONG(n)); } h = rb_hash_end(h); return ST2FIX(h);}
include?(obj) → true or false click to toggle source
Returns true
if for some index i
in self
, obj == self[i]
; otherwise false
:
[0, 1, 2].include?(2) # => true[0, 1, 2].include?(3) # => false
VALUErb_ary_includes(VALUE ary, VALUE item){ long i; VALUE e; for (i=0; i<RARRAY_LEN(ary); i++) { e = RARRAY_AREF(ary, i); if (rb_equal(e, item)) { return Qtrue; } } return Qfalse;}
index(object) → integer or nil click to toggle source
index {|element| ... } → integer or nil
index → new_enumerator
Returns the index of a specified element.
When argument object
is given but no block, returns the index of the first element element
for which object == element
:
a = [:foo, 'bar', 2, 'bar']a.index('bar') # => 1
Returns nil
if no such element found.
When both argument object
and a block are given, calls the block with each successive element; returns the index of the first element for which the block returns a truthy value:
a = [:foo, 'bar', 2, 'bar']a.index {|element| element == 'bar' } # => 1
Returns nil
if the block never returns a truthy value.
When neither an argument nor a block is given, returns a new Enumerator:
a = [:foo, 'bar', 2]e = a.indexe # => #<Enumerator: [:foo, "bar", 2]:index>e.each {|element| element == 'bar' } # => 1
Array#find_index is an alias for Array#index.
Related: rindex.
static VALUErb_ary_index(int argc, VALUE *argv, VALUE ary){ VALUE val; long i; if (argc == 0) { RETURN_ENUMERATOR(ary, 0, 0); for (i=0; i<RARRAY_LEN(ary); i++) { if (RTEST(rb_yield(RARRAY_AREF(ary, i)))) { return LONG2NUM(i); } } return Qnil; } rb_check_arity(argc, 0, 1); val = argv[0]; if (rb_block_given_p()) rb_warn("given block not used"); for (i=0; i<RARRAY_LEN(ary); i++) { VALUE e = RARRAY_AREF(ary, i); if (rb_equal(e, val)) { return LONG2NUM(i); } } return Qnil;}
replace(other_array) → self click to toggle source
Replaces the content of self
with the content of other_array
; returns self
:
a = [:foo, 'bar', 2]a.replace(['foo', :bar, 3]) # => ["foo", :bar, 3]
VALUErb_ary_replace(VALUE copy, VALUE orig){ rb_ary_modify_check(copy); orig = to_ary(orig); if (copy == orig) return copy; if (RARRAY_LEN(orig) <= RARRAY_EMBED_LEN_MAX) { VALUE shared_root = 0; if (ARY_OWNS_HEAP_P(copy)) { ary_heap_free(copy); } else if (ARY_SHARED_P(copy)) { shared_root = ARY_SHARED_ROOT(copy); FL_UNSET_SHARED(copy); } FL_SET_EMBED(copy); ary_memcpy(copy, 0, RARRAY_LEN(orig), RARRAY_CONST_PTR_TRANSIENT(orig)); if (shared_root) { rb_ary_decrement_share(shared_root); } ARY_SET_LEN(copy, RARRAY_LEN(orig)); } else { VALUE shared_root = ary_make_shared(orig); if (ARY_OWNS_HEAP_P(copy)) { ary_heap_free(copy); } else { rb_ary_unshare_safe(copy); } FL_UNSET_EMBED(copy); ARY_SET_PTR(copy, ARY_HEAP_PTR(orig)); ARY_SET_LEN(copy, ARY_HEAP_LEN(orig)); rb_ary_set_shared(copy, shared_root); } ary_verify(copy); return copy;}
insert(index, *objects) → self click to toggle source
Inserts given objects
before or after the element at Integer index offset
; returns self
.
When index
is non-negative, inserts all given objects
before the element at offset index
:
a = [:foo, 'bar', 2]a.insert(1, :bat, :bam) # => [:foo, :bat, :bam, "bar", 2]
Extends the array if index
is beyond the array (index >= self.size
):
a = [:foo, 'bar', 2]a.insert(5, :bat, :bam)a # => [:foo, "bar", 2, nil, nil, :bat, :bam]
Does nothing if no objects given:
a = [:foo, 'bar', 2]a.insert(1)a.insert(50)a.insert(-50)a # => [:foo, "bar", 2]
When index
is negative, inserts all given objects
after the element at offset index+self.size
:
a = [:foo, 'bar', 2]a.insert(-2, :bat, :bam)a # => [:foo, "bar", :bat, :bam, 2]
static VALUErb_ary_insert(int argc, VALUE *argv, VALUE ary){ long pos; rb_check_arity(argc, 1, UNLIMITED_ARGUMENTS); rb_ary_modify_check(ary); pos = NUM2LONG(argv[0]); if (argc == 1) return ary; if (pos == -1) { pos = RARRAY_LEN(ary); } else if (pos < 0) { long minpos = -RARRAY_LEN(ary) - 1; if (pos < minpos) { rb_raise(rb_eIndexError, "index %ld too small for array; minimum: %ld", pos, minpos); } pos++; } rb_ary_splice(ary, pos, 0, argv + 1, argc - 1); return ary;}
inspect → new_string click to toggle source
Returns the new String formed by calling method #inspect
on each array element:
a = [:foo, 'bar', 2]a.inspect # => "[:foo, \"bar\", 2]"
Array#to_s is an alias for Array#inspect.
static VALUErb_ary_inspect(VALUE ary){ if (RARRAY_LEN(ary) == 0) return rb_usascii_str_new2("[]"); return rb_exec_recursive(inspect_ary, ary, 0);}
Also aliased as: to_s
intersect?(other_ary) → true or false click to toggle source
Returns true
if the array and other_ary
have at least one element in common, otherwise returns false
.
a = [ 1, 2, 3 ]b = [ 3, 4, 5 ]c = [ 5, 6, 7 ]a.intersect?(b) #=> truea.intersect?(c) #=> false
static VALUErb_ary_intersect_p(VALUE ary1, VALUE ary2){ VALUE hash, v, result, shorter, longer; st_data_t vv; long i; ary2 = to_ary(ary2); if (RARRAY_LEN(ary1) == 0 || RARRAY_LEN(ary2) == 0) return Qfalse; if (RARRAY_LEN(ary1) <= SMALL_ARRAY_LEN && RARRAY_LEN(ary2) <= SMALL_ARRAY_LEN) { for (i=0; i<RARRAY_LEN(ary1); i++) { v = RARRAY_AREF(ary1, i); if (rb_ary_includes_by_eql(ary2, v)) return Qtrue; } return Qfalse; } shorter = ary1; longer = ary2; if (RARRAY_LEN(ary1) > RARRAY_LEN(ary2)) { longer = ary1; shorter = ary2; } hash = ary_make_hash(shorter); result = Qfalse; for (i=0; i<RARRAY_LEN(longer); i++) { v = RARRAY_AREF(longer, i); vv = (st_data_t)v; if (rb_hash_stlike_lookup(hash, vv, 0)) { result = Qtrue; break; } } ary_recycle_hash(hash); return result;}
intersection(*other_arrays) → new_array click to toggle source
Returns a new Array containing each element found both in self
and in all of the given Arrays other_arrays
; duplicates are omitted; items are compared using eql?
:
[0, 1, 2, 3].intersection([0, 1, 2], [0, 1, 3]) # => [0, 1][0, 0, 1, 1, 2, 3].intersection([0, 1, 2], [0, 1, 3]) # => [0, 1]
Preserves order from self
:
[0, 1, 2].intersection([2, 1, 0]) # => [0, 1, 2]
Returns a copy of self
if no arguments given.
Related: Array#&.
static VALUErb_ary_intersection_multi(int argc, VALUE *argv, VALUE ary){ VALUE result = rb_ary_dup(ary); int i; for (i = 0; i < argc; i++) { result = rb_ary_and(result, argv[i]); } return result;}
join →new_string click to toggle source
join(separator = $,) → new_string
Returns the new String formed by joining the array elements after conversion. For each element element
Uses
element.to_s
ifelement
is not akind_of?(Array)
.Uses recursive
element.join(separator)
ifelement
is akind_of?(Array)
.
With no argument, joins using the output field separator, $,
:
a = [:foo, 'bar', 2]$, # => nila.join # => "foobar2"
With string argument separator
, joins using that separator:
a = [:foo, 'bar', 2]a.join("\n") # => "foo\nbar\n2"
Joins recursively for nested Arrays:
a = [:foo, [:bar, [:baz, :bat]]]a.join # => "foobarbazbat"
static VALUErb_ary_join_m(int argc, VALUE *argv, VALUE ary){ VALUE sep; if (rb_check_arity(argc, 0, 1) == 0 || NIL_P(sep = argv[0])) { sep = rb_output_fs; if (!NIL_P(sep)) { rb_category_warn(RB_WARN_CATEGORY_DEPRECATED, "$, is set to non-nil value"); } } return rb_ary_join(ary, sep);}
Also aliased as: to_s
keep_if {|element| ... } → self click to toggle source
keep_if → new_enumeration
Retains those elements for which the block returns a truthy value; deletes all other elements; returns self
:
a = [:foo, 'bar', 2, :bam]a.keep_if {|element| element.to_s.start_with?('b') } # => ["bar", :bam]
Returns a new Enumerator if no block given:
a = [:foo, 'bar', 2, :bam]a.keep_if # => #<Enumerator: [:foo, "bar", 2, :bam]:keep_if>
static VALUErb_ary_keep_if(VALUE ary){ RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); rb_ary_select_bang(ary); return ary;}
last → object or nil click to toggle source
last(n) → new_array
Returns elements from self
; self
is not modified.
When no argument is given, returns the last element:
a = [:foo, 'bar', 2]a.last # => 2a # => [:foo, "bar", 2]
If self
is empty, returns nil
.
When non-negative Innteger argument n
is given, returns the last n
elements in a new Array:
a = [:foo, 'bar', 2]a.last(2) # => ["bar", 2]
If n >= array.size
, returns all elements:
a = [:foo, 'bar', 2]a.last(50) # => [:foo, "bar", 2]
If n == 0
, returns an new empty Array:
a = [:foo, 'bar', 2]a.last(0) # []
Related: first.
VALUErb_ary_last(int argc, const VALUE *argv, VALUE ary){ if (argc == 0) { long len = RARRAY_LEN(ary); if (len == 0) return Qnil; return RARRAY_AREF(ary, len-1); } else { return ary_take_first_or_last(argc, argv, ary, ARY_TAKE_LAST); }}
length → an_integer click to toggle source
Returns the count of elements in self
.
static VALUErb_ary_length(VALUE ary){ long len = RARRAY_LEN(ary); return LONG2NUM(len);}
map {|element| ... } → new_array click to toggle source
map → new_enumerator
Calls the block, if given, with each element of self
; returns a new Array whose elements are the return values from the block:
a = [:foo, 'bar', 2]a1 = a.map {|element| element.class }a1 # => [Symbol, String, Integer]
Returns a new Enumerator if no block given:
a = [:foo, 'bar', 2]a1 = a.mapa1 # => #<Enumerator: [:foo, "bar", 2]:map>
Array#collect is an alias for Array#map.
static VALUErb_ary_collect(VALUE ary){ long i; VALUE collect; RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); collect = rb_ary_new2(RARRAY_LEN(ary)); for (i = 0; i < RARRAY_LEN(ary); i++) { rb_ary_push(collect, rb_yield(RARRAY_AREF(ary, i))); } return collect;}
map! {|element| ... } → self click to toggle source
map! → new_enumerator
Calls the block, if given, with each element; replaces the element with the block's return value:
a = [:foo, 'bar', 2]a.map! { |element| element.class } # => [Symbol, String, Integer]
Returns a new Enumerator if no block given:
a = [:foo, 'bar', 2]a1 = a.map!a1 # => #<Enumerator: [:foo, "bar", 2]:map!>
Array#collect! is an alias for Array#map!.
static VALUErb_ary_collect_bang(VALUE ary){ long i; RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); rb_ary_modify(ary); for (i = 0; i < RARRAY_LEN(ary); i++) { rb_ary_store(ary, i, rb_yield(RARRAY_AREF(ary, i))); } return ary;}
max → element click to toggle source
max {|a, b| ... } → element
max(n) → new_array
max(n) {|a, b| ... } → new_array
Returns one of the following:
The maximum-valued element from
self
.A new Array of maximum-valued elements selected from
self
.
When no block is given, each element in self
must respond to method <=>
with an Integer.
With no argument and no block, returns the element in self
having the maximum value per method <=>
:
[0, 1, 2].max # => 2
With an argument Integer n
and no block, returns a new Array with at most n
elements, in descending order per method <=>
:
[0, 1, 2, 3].max(3) # => [3, 2, 1][0, 1, 2, 3].max(6) # => [3, 2, 1, 0]
When a block is given, the block must return an Integer.
With a block and no argument, calls the block self.size-1
times to compare elements; returns the element having the maximum value per the block:
['0', '00', '000'].max {|a, b| a.size <=> b.size } # => "000"
With an argument n
and a block, returns a new Array with at most n
elements, in descending order per the block:
['0', '00', '000'].max(2) {|a, b| a.size <=> b.size } # => ["000", "00"]
static VALUErb_ary_max(int argc, VALUE *argv, VALUE ary){ struct cmp_opt_data cmp_opt = { 0, 0 }; VALUE result = Qundef, v; VALUE num; long i; if (rb_check_arity(argc, 0, 1) && !NIL_P(num = argv[0])) return rb_nmin_run(ary, num, 0, 1, 1); const long n = RARRAY_LEN(ary); if (rb_block_given_p()) { for (i = 0; i < RARRAY_LEN(ary); i++) { v = RARRAY_AREF(ary, i); if (result == Qundef || rb_cmpint(rb_yield_values(2, v, result), v, result) > 0) { result = v; } } } else if (n > 0) { result = RARRAY_AREF(ary, 0); if (n > 1) { if (FIXNUM_P(result) && CMP_OPTIMIZABLE(cmp_opt, Integer)) { return ary_max_opt_fixnum(ary, 1, result); } else if (STRING_P(result) && CMP_OPTIMIZABLE(cmp_opt, String)) { return ary_max_opt_string(ary, 1, result); } else if (RB_FLOAT_TYPE_P(result) && CMP_OPTIMIZABLE(cmp_opt, Float)) { return ary_max_opt_float(ary, 1, result); } else { return ary_max_generic(ary, 1, result); } } } if (result == Qundef) return Qnil; return result;}
min → element click to toggle source
min { |a, b| ... } → element
min(n) → new_array
min(n) { |a, b| ... } → new_array
Returns one of the following:
The minimum-valued element from
self
.A new Array of minimum-valued elements selected from
self
.
When no block is given, each element in self
must respond to method <=>
with an Integer.
With no argument and no block, returns the element in self
having the minimum value per method <=>
:
[0, 1, 2].min # => 0
With Integer argument n
and no block, returns a new Array with at most n
elements, in ascending order per method <=>
:
[0, 1, 2, 3].min(3) # => [0, 1, 2][0, 1, 2, 3].min(6) # => [0, 1, 2, 3]
When a block is given, the block must return an Integer.
With a block and no argument, calls the block self.size-1
times to compare elements; returns the element having the minimum value per the block:
['0', '00', '000'].min { |a, b| a.size <=> b.size } # => "0"
With an argument n
and a block, returns a new Array with at most n
elements, in ascending order per the block:
['0', '00', '000'].min(2) {|a, b| a.size <=> b.size } # => ["0", "00"]
static VALUErb_ary_min(int argc, VALUE *argv, VALUE ary){ struct cmp_opt_data cmp_opt = { 0, 0 }; VALUE result = Qundef, v; VALUE num; long i; if (rb_check_arity(argc, 0, 1) && !NIL_P(num = argv[0])) return rb_nmin_run(ary, num, 0, 0, 1); const long n = RARRAY_LEN(ary); if (rb_block_given_p()) { for (i = 0; i < RARRAY_LEN(ary); i++) { v = RARRAY_AREF(ary, i); if (result == Qundef || rb_cmpint(rb_yield_values(2, v, result), v, result) < 0) { result = v; } } } else if (n > 0) { result = RARRAY_AREF(ary, 0); if (n > 1) { if (FIXNUM_P(result) && CMP_OPTIMIZABLE(cmp_opt, Integer)) { return ary_min_opt_fixnum(ary, 1, result); } else if (STRING_P(result) && CMP_OPTIMIZABLE(cmp_opt, String)) { return ary_min_opt_string(ary, 1, result); } else if (RB_FLOAT_TYPE_P(result) && CMP_OPTIMIZABLE(cmp_opt, Float)) { return ary_min_opt_float(ary, 1, result); } else { return ary_min_generic(ary, 1, result); } } } if (result == Qundef) return Qnil; return result;}
minmax → [min_val, max_val] click to toggle source
minmax {|a, b| ... } → [min_val, max_val]
Returns a new 2-element Array containing the minimum and maximum values from self
, either per method <=>
or per a given block:.
When no block is given, each element in self
must respond to method <=>
with an Integer; returns a new 2-element Array containing the minimum and maximum values from self
, per method <=>
:
[0, 1, 2].minmax # => [0, 2]
When a block is given, the block must return an Integer; the block is called self.size-1
times to compare elements; returns a new 2-element Array containing the minimum and maximum values from self
, per the block:
['0', '00', '000'].minmax {|a, b| a.size <=> b.size } # => ["0", "000"]
static VALUErb_ary_minmax(VALUE ary){ if (rb_block_given_p()) { return rb_call_super(0, NULL); } return rb_assoc_new(rb_ary_min(0, 0, ary), rb_ary_max(0, 0, ary));}
none? → true or false click to toggle source
none? {|element| ... } → true or false
none?(obj) → true or false
Returns true
if no element of self
meet a given criterion.
With no block given and no argument, returns true
if self
has no truthy elements, false
otherwise:
[nil, false].none? # => true[nil, 0, false].none? # => false[].none? # => true
With a block given and no argument, calls the block with each element in self
; returns true
if the block returns no truthy value, false
otherwise:
[0, 1, 2].none? {|element| element > 3 } # => true[0, 1, 2].none? {|element| element > 1 } # => false
If argument obj
is given, returns true
if obj.===
no element, false
otherwise:
['food', 'drink'].none?(/bar/) # => true['food', 'drink'].none?(/foo/) # => false[].none?(/foo/) # => true[0, 1, 2].none?(3) # => true[0, 1, 2].none?(1) # => false
Related: Enumerable#none?
static VALUErb_ary_none_p(int argc, VALUE *argv, VALUE ary){ long i, len = RARRAY_LEN(ary); rb_check_arity(argc, 0, 1); if (!len) return Qtrue; if (argc) { if (rb_block_given_p()) { rb_warn("given block not used"); } for (i = 0; i < RARRAY_LEN(ary); ++i) { if (RTEST(rb_funcall(argv[0], idEqq, 1, RARRAY_AREF(ary, i)))) return Qfalse; } } else if (!rb_block_given_p()) { for (i = 0; i < len; ++i) { if (RTEST(RARRAY_AREF(ary, i))) return Qfalse; } } else { for (i = 0; i < RARRAY_LEN(ary); ++i) { if (RTEST(rb_yield(RARRAY_AREF(ary, i)))) return Qfalse; } } return Qtrue;}
old_to_s() click to toggle source
Alias for: to_s
one? → true or false click to toggle source
one? {|element| ... } → true or false
one?(obj) → true or false
Returns true
if exactly one element of self
meets a given criterion.
With no block given and no argument, returns true
if self
has exactly one truthy element, false
otherwise:
[nil, 0].one? # => true[0, 0].one? # => false[nil, nil].one? # => false[].one? # => false
With a block given and no argument, calls the block with each element in self
; returns true
if the block a truthy value for exactly one element, false
otherwise:
[0, 1, 2].one? {|element| element > 0 } # => false[0, 1, 2].one? {|element| element > 1 } # => true[0, 1, 2].one? {|element| element > 2 } # => false
If argument obj
is given, returns true
if obj.===
exactly one element, false
otherwise:
[0, 1, 2].one?(0) # => true[0, 0, 1].one?(0) # => false[1, 1, 2].one?(0) # => false['food', 'drink'].one?(/bar/) # => false['food', 'drink'].one?(/foo/) # => true[].one?(/foo/) # => false
Related: Enumerable#one?
static VALUErb_ary_one_p(int argc, VALUE *argv, VALUE ary){ long i, len = RARRAY_LEN(ary); VALUE result = Qfalse; rb_check_arity(argc, 0, 1); if (!len) return Qfalse; if (argc) { if (rb_block_given_p()) { rb_warn("given block not used"); } for (i = 0; i < RARRAY_LEN(ary); ++i) { if (RTEST(rb_funcall(argv[0], idEqq, 1, RARRAY_AREF(ary, i)))) { if (result) return Qfalse; result = Qtrue; } } } else if (!rb_block_given_p()) { for (i = 0; i < len; ++i) { if (RTEST(RARRAY_AREF(ary, i))) { if (result) return Qfalse; result = Qtrue; } } } else { for (i = 0; i < RARRAY_LEN(ary); ++i) { if (RTEST(rb_yield(RARRAY_AREF(ary, i)))) { if (result) return Qfalse; result = Qtrue; } } } return result;}
pack( aTemplateString ) → aBinaryString click to toggle source
pack( aTemplateString, buffer: aBufferString ) → aBufferString
Packs the contents of arr into a binary sequence according to the directives in aTemplateString (see the table below) Directives “A,'' “a,'' and “Z'' may be followed by a count, which gives the width of the resulting field. The remaining directives also may take a count, indicating the number of array elements to convert. If the count is an asterisk (“*
''), all remaining array elements will be converted. Any of the directives “sSiIlL
'' may be followed by an underscore (“_
'') or exclamation mark (“!
'') to use the underlying platform's native size for the specified type; otherwise, they use a platform-independent size. Spaces are ignored in the template string. See also String#unpack.
a = [ "a", "b", "c" ]n = [ 65, 66, 67 ]a.pack("A3A3A3") #=> "a b c "a.pack("a3a3a3") #=> "a\000\000b\000\000c\000\000"n.pack("ccc") #=> "ABC"
If aBufferString is specified and its capacity is enough, pack
uses it as the buffer and returns it. When the offset is specified by the beginning of aTemplateString, the result is filled after the offset. If original contents of aBufferString exists and it's longer than the offset, the rest of offsetOfBuffer are overwritten by the result. If it's shorter, the gap is filled with “\0
''.
# packed data is appended by default[255].pack("C", buffer:"foo".b) #=> "foo\xFF"# "@0" (offset 0) specifies that packed data is filled from beginning.# Also, original data after packed data is removed. ("oo" is removed.)[255].pack("@0C", buffer:"foo".b) #=> "\xFF"# If the offset is bigger than the original length, \x00 is filled.[255].pack("@5C", buffer:"foo".b) #=> "foo\x00\x00\xFF"
Note that “buffer:'' option does not guarantee not to allocate memory in pack
. If the capacity of aBufferString is not enough, pack
allocates memory.
Directives for pack
.
Integer | Array |Directive | Element | Meaning----------------------------------------------------------------------------C | Integer | 8-bit unsigned (unsigned char)S | Integer | 16-bit unsigned, native endian (uint16_t)L | Integer | 32-bit unsigned, native endian (uint32_t)Q | Integer | 64-bit unsigned, native endian (uint64_t)J | Integer | pointer width unsigned, native endian (uintptr_t) | | (J is available since Ruby 2.3.) | |c | Integer | 8-bit signed (signed char)s | Integer | 16-bit signed, native endian (int16_t)l | Integer | 32-bit signed, native endian (int32_t)q | Integer | 64-bit signed, native endian (int64_t)j | Integer | pointer width signed, native endian (intptr_t) | | (j is available since Ruby 2.3.) | |S_ S! | Integer | unsigned short, native endianI I_ I! | Integer | unsigned int, native endianL_ L! | Integer | unsigned long, native endianQ_ Q! | Integer | unsigned long long, native endian (ArgumentError | | if the platform has no long long type.) | | (Q_ and Q! is available since Ruby 2.1.)J! | Integer | uintptr_t, native endian (same with J) | | (J! is available since Ruby 2.3.) | |s_ s! | Integer | signed short, native endiani i_ i! | Integer | signed int, native endianl_ l! | Integer | signed long, native endianq_ q! | Integer | signed long long, native endian (ArgumentError | | if the platform has no long long type.) | | (q_ and q! is available since Ruby 2.1.)j! | Integer | intptr_t, native endian (same with j) | | (j! is available since Ruby 2.3.) | |S> s> S!> s!> | Integer | same as the directives without ">" exceptL> l> L!> l!> | | big endianI!> i!> | | (available since Ruby 1.9.3)Q> q> Q!> q!> | | "S>" is the same as "n"J> j> J!> j!> | | "L>" is the same as "N" | |S< s< S!< s!< | Integer | same as the directives without "<" exceptL< l< L!< l!< | | little endianI!< i!< | | (available since Ruby 1.9.3)Q< q< Q!< q!< | | "S<" is the same as "v"J< j< J!< j!< | | "L<" is the same as "V" | |n | Integer | 16-bit unsigned, network (big-endian) byte orderN | Integer | 32-bit unsigned, network (big-endian) byte orderv | Integer | 16-bit unsigned, VAX (little-endian) byte orderV | Integer | 32-bit unsigned, VAX (little-endian) byte order | |U | Integer | UTF-8 characterw | Integer | BER-compressed integerFloat | Array |Directive | Element | Meaning---------------------------------------------------------------------------D d | Float | double-precision, native formatF f | Float | single-precision, native formatE | Float | double-precision, little-endian byte ordere | Float | single-precision, little-endian byte orderG | Float | double-precision, network (big-endian) byte orderg | Float | single-precision, network (big-endian) byte orderString | Array |Directive | Element | Meaning---------------------------------------------------------------------------A | String | arbitrary binary string (space padded, count is width)a | String | arbitrary binary string (null padded, count is width)Z | String | same as ``a'', except that null is added with *B | String | bit string (MSB first)b | String | bit string (LSB first)H | String | hex string (high nibble first)h | String | hex string (low nibble first)u | String | UU-encoded stringM | String | quoted printable, MIME encoding (see also RFC2045) | | (text mode but input must use LF and output LF)m | String | base64 encoded string (see RFC 2045) | | (if count is 0, no line feed are added, see RFC 4648) | | (count specifies input bytes between each LF, | | rounded down to nearest multiple of 3)P | String | pointer to a structure (fixed-length string)p | String | pointer to a null-terminated stringMisc. | Array |Directive | Element | Meaning---------------------------------------------------------------------------@ | --- | moves to absolute positionX | --- | back up a bytex | --- | null byte
# File pack.rb, line 143def pack(fmt, buffer: nil) Primitive.pack_pack(fmt, buffer)end
permutation {|element| ... } → self click to toggle source
permutation(n) {|element| ... } → self
permutation → new_enumerator
permutation(n) → new_enumerator
When invoked with a block, yield all permutations of elements of self
; returns self
. The order of permutations is indeterminate.
When a block and an in-range positive Integer argument n
(0 < n <= self.size
) are given, calls the block with all n
-tuple permutations of self
.
Example:
a = [0, 1, 2]a.permutation(2) {|permutation| p permutation }
Output:
[0, 1][0, 2][1, 0][1, 2][2, 0][2, 1]
Another example:
a = [0, 1, 2]a.permutation(3) {|permutation| p permutation }
Output:
[0, 1, 2][0, 2, 1][1, 0, 2][1, 2, 0][2, 0, 1][2, 1, 0]
When n
is zero, calls the block once with a new empty Array:
a = [0, 1, 2]a.permutation(0) {|permutation| p permutation }
Output:
[]
When n
is out of range (negative or larger than self.size
), does not call the block:
a = [0, 1, 2]a.permutation(-1) {|permutation| fail 'Cannot happen' }a.permutation(4) {|permutation| fail 'Cannot happen' }
When a block given but no argument, behaves the same as a.permutation(a.size)
:
a = [0, 1, 2]a.permutation {|permutation| p permutation }
Output:
[0, 1, 2][0, 2, 1][1, 0, 2][1, 2, 0][2, 0, 1][2, 1, 0]
Returns a new Enumerator if no block given:
a = [0, 1, 2]a.permutation # => #<Enumerator: [0, 1, 2]:permutation>a.permutation(2) # => #<Enumerator: [0, 1, 2]:permutation(2)>
static VALUErb_ary_permutation(int argc, VALUE *argv, VALUE ary){ long r, n, i; n = RARRAY_LEN(ary); /* Array length */ RETURN_SIZED_ENUMERATOR(ary, argc, argv, rb_ary_permutation_size); /* Return enumerator if no block */ r = n; if (rb_check_arity(argc, 0, 1) && !NIL_P(argv[0])) r = NUM2LONG(argv[0]); /* Permutation size from argument */ if (r < 0 || n < r) { /* no permutations: yield nothing */ } else if (r == 0) { /* exactly one permutation: the zero-length array */ rb_yield(rb_ary_new2(0)); } else if (r == 1) { /* this is a special, easy case */ for (i = 0; i < RARRAY_LEN(ary); i++) { rb_yield(rb_ary_new3(1, RARRAY_AREF(ary, i))); } } else { /* this is the general case */ volatile VALUE t0; long *p = ALLOCV_N(long, t0, r+roomof(n, sizeof(long))); char *used = (char*)(p + r); VALUE ary0 = ary_make_shared_copy(ary); /* private defensive copy of ary */ RBASIC_CLEAR_CLASS(ary0); MEMZERO(used, char, n); /* initialize array */ permute0(n, r, p, used, ary0); /* compute and yield permutations */ ALLOCV_END(t0); RBASIC_SET_CLASS_RAW(ary0, rb_cArray); } return ary;}
pop → object or nil click to toggle source
pop(n) → new_array
Removes and returns trailing elements.
When no argument is given and self
is not empty, removes and returns the last element:
a = [:foo, 'bar', 2]a.pop # => 2a # => [:foo, "bar"]
Returns nil
if the array is empty.
When a non-negative Integer argument n
is given and is in range, removes and returns the last n
elements in a new Array:
a = [:foo, 'bar', 2]a.pop(2) # => ["bar", 2]
If n
is positive and out of range, removes and returns all elements:
a = [:foo, 'bar', 2]a.pop(50) # => [:foo, "bar", 2]
Related: push, shift, unshift.
static VALUErb_ary_pop_m(int argc, VALUE *argv, VALUE ary){ VALUE result; if (argc == 0) { return rb_ary_pop(ary); } rb_ary_modify_check(ary); result = ary_take_first_or_last(argc, argv, ary, ARY_TAKE_LAST); ARY_INCREASE_LEN(ary, -RARRAY_LEN(result)); ary_verify(ary); return result;}
prepend(*args) click to toggle source
Alias for: unshift
product(*other_arrays) → new_array click to toggle source
product(*other_arrays) {|combination| ... } → self
Computes and returns or yields all combinations of elements from all the Arrays, including both self
and other_arrays
.
The number of combinations is the product of the sizes of all the arrays, including both
self
andother_arrays
.The order of the returned combinations is indeterminate.
When no block is given, returns the combinations as an Array of Arrays:
a = [0, 1, 2]a1 = [3, 4]a2 = [5, 6]p = a.product(a1)p.size # => 6 # a.size * a1.sizep # => [[0, 3], [0, 4], [1, 3], [1, 4], [2, 3], [2, 4]]p = a.product(a1, a2)p.size # => 12 # a.size * a1.size * a2.sizep # => [[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]]
If any argument is an empty Array, returns an empty Array.
If no argument is given, returns an Array of 1-element Arrays, each containing an element of self
:
a.product # => [[0], [1], [2]]
When a block is given, yields each combination as an Array; returns self
:
a.product(a1) {|combination| p combination }
Output:
[0, 3][0, 4][1, 3][1, 4][2, 3][2, 4]
If any argument is an empty Array, does not call the block:
a.product(a1, a2, []) {|combination| fail 'Cannot happen' }
If no argument is given, yields each element of self
as a 1-element Array:
a.product {|combination| p combination }
Output:
[0][1][2]
static VALUErb_ary_product(int argc, VALUE *argv, VALUE ary){ int n = argc+1; /* How many arrays we're operating on */ volatile VALUE t0 = tmpary(n); volatile VALUE t1 = Qundef; VALUE *arrays = RARRAY_PTR(t0); /* The arrays we're computing the product of */ int *counters = ALLOCV_N(int, t1, n); /* The current position in each one */ VALUE result = Qnil; /* The array we'll be returning, when no block given */ long i,j; long resultlen = 1; RBASIC_CLEAR_CLASS(t0); /* initialize the arrays of arrays */ ARY_SET_LEN(t0, n); arrays[0] = ary; for (i = 1; i < n; i++) arrays[i] = Qnil; for (i = 1; i < n; i++) arrays[i] = to_ary(argv[i-1]); /* initialize the counters for the arrays */ for (i = 0; i < n; i++) counters[i] = 0; /* Otherwise, allocate and fill in an array of results */ if (rb_block_given_p()) { /* Make defensive copies of arrays; exit if any is empty */ for (i = 0; i < n; i++) { if (RARRAY_LEN(arrays[i]) == 0) goto done; arrays[i] = ary_make_shared_copy(arrays[i]); } } else { /* Compute the length of the result array; return [] if any is empty */ for (i = 0; i < n; i++) { long k = RARRAY_LEN(arrays[i]); if (k == 0) { result = rb_ary_new2(0); goto done; } if (MUL_OVERFLOW_LONG_P(resultlen, k)) rb_raise(rb_eRangeError, "too big to product"); resultlen *= k; } result = rb_ary_new2(resultlen); } for (;;) { int m; /* fill in one subarray */ VALUE subarray = rb_ary_new2(n); for (j = 0; j < n; j++) { rb_ary_push(subarray, rb_ary_entry(arrays[j], counters[j])); } /* put it on the result array */ if (NIL_P(result)) { FL_SET(t0, FL_USER5); rb_yield(subarray); if (! FL_TEST(t0, FL_USER5)) { rb_raise(rb_eRuntimeError, "product reentered"); } else { FL_UNSET(t0, FL_USER5); } } else { rb_ary_push(result, subarray); } /* * Increment the last counter. If it overflows, reset to 0 * and increment the one before it. */ m = n-1; counters[m]++; while (counters[m] == RARRAY_LEN(arrays[m])) { counters[m] = 0; /* If the first counter overflows, we are done */ if (--m < 0) goto done; counters[m]++; } }done: tmpary_discard(t0); ALLOCV_END(t1); return NIL_P(result) ? ary : result;}
push(*objects) → self click to toggle source
Appends trailing elements.
Appends each argument in objects
to self
; returns self
:
a = [:foo, 'bar', 2]a.push(:baz, :bat) # => [:foo, "bar", 2, :baz, :bat]
Appends each argument as one element, even if it is another Array:
a = [:foo, 'bar', 2]a1 = a.push([:baz, :bat], [:bam, :bad])a1 # => [:foo, "bar", 2, [:baz, :bat], [:bam, :bad]]
Array#append is an alias for Array#push.
Related: pop, shift, unshift.
static VALUErb_ary_push_m(int argc, VALUE *argv, VALUE ary){ return rb_ary_cat(ary, argv, argc);}
Also aliased as: append
rassoc(obj) → found_array or nil click to toggle source
Returns the first element in self
that is an Array whose second element ==
obj
:
a = [{foo: 0}, [2, 4], [4, 5, 6], [4, 5]]a.rassoc(4) # => [2, 4]
Returns nil
if no such element is found.
Related: assoc.
VALUErb_ary_rassoc(VALUE ary, VALUE value){ long i; VALUE v; for (i = 0; i < RARRAY_LEN(ary); ++i) { v = RARRAY_AREF(ary, i); if (RB_TYPE_P(v, T_ARRAY) && RARRAY_LEN(v) > 1 && rb_equal(RARRAY_AREF(v, 1), value)) return v; } return Qnil;}
reject {|element| ... } → new_array click to toggle source
reject → new_enumerator
Returns a new Array whose elements are all those from self
for which the block returns false
or nil
:
a = [:foo, 'bar', 2, 'bat']a1 = a.reject {|element| element.to_s.start_with?('b') }a1 # => [:foo, 2]
Returns a new Enumerator if no block given:
a = [:foo, 'bar', 2]a.reject # => #<Enumerator: [:foo, "bar", 2]:reject>
static VALUErb_ary_reject(VALUE ary){ VALUE rejected_ary; RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); rejected_ary = rb_ary_new(); ary_reject(ary, rejected_ary); return rejected_ary;}
reject! {|element| ... } → self or nil click to toggle source
reject! → new_enumerator
Removes each element for which the block returns a truthy value.
Returns self
if any elements removed:
a = [:foo, 'bar', 2, 'bat']a.reject! {|element| element.to_s.start_with?('b') } # => [:foo, 2]
Returns nil
if no elements removed.
Returns a new Enumerator if no block given:
a = [:foo, 'bar', 2]a.reject! # => #<Enumerator: [:foo, "bar", 2]:reject!>
static VALUErb_ary_reject_bang(VALUE ary){ RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); rb_ary_modify(ary); return ary_reject_bang(ary);}
repeated_combination(n) {|combination| ... } → self click to toggle source
repeated_combination(n) → new_enumerator
Calls the block with each repeated combination of length n
of the elements of self
; each combination is an Array; returns self
. The order of the combinations is indeterminate.
When a block and a positive Integer argument n
are given, calls the block with each n
-tuple repeated combination of the elements of self
. The number of combinations is (n+1)(n+2)/2
.
n
= 1:
a = [0, 1, 2]a.repeated_combination(1) {|combination| p combination }
Output:
[0][1][2]
n
= 2:
a.repeated_combination(2) {|combination| p combination }
Output:
[0, 0][0, 1][0, 2][1, 1][1, 2][2, 2]
If n
is zero, calls the block once with an empty Array.
If n
is negative, does not call the block:
a.repeated_combination(-1) {|combination| fail 'Cannot happen' }
Returns a new Enumerator if no block given:
a = [0, 1, 2]a.repeated_combination(2) # => #<Enumerator: [0, 1, 2]:combination(2)>
Using Enumerators, it's convenient to show the combinations and counts for some values of n
:
e = a.repeated_combination(0)e.size # => 1e.to_a # => [[]]e = a.repeated_combination(1)e.size # => 3e.to_a # => [[0], [1], [2]]e = a.repeated_combination(2)e.size # => 6e.to_a # => [[0, 0], [0, 1], [0, 2], [1, 1], [1, 2], [2, 2]]
static VALUErb_ary_repeated_combination(VALUE ary, VALUE num){ long n, i, len; n = NUM2LONG(num); /* Combination size from argument */ RETURN_SIZED_ENUMERATOR(ary, 1, &num, rb_ary_repeated_combination_size); /* Return enumerator if no block */ len = RARRAY_LEN(ary); if (n < 0) { /* yield nothing */ } else if (n == 0) { rb_yield(rb_ary_new2(0)); } else if (n == 1) { for (i = 0; i < RARRAY_LEN(ary); i++) { rb_yield(rb_ary_new3(1, RARRAY_AREF(ary, i))); } } else if (len == 0) { /* yield nothing */ } else { volatile VALUE t0; long *p = ALLOCV_N(long, t0, n); VALUE ary0 = ary_make_shared_copy(ary); /* private defensive copy of ary */ RBASIC_CLEAR_CLASS(ary0); rcombinate0(len, n, p, n, ary0); /* compute and yield repeated combinations */ ALLOCV_END(t0); RBASIC_SET_CLASS_RAW(ary0, rb_cArray); } return ary;}
repeated_permutation(n) {|permutation| ... } → self click to toggle source
repeated_permutation(n) → new_enumerator
Calls the block with each repeated permutation of length n
of the elements of self
; each permutation is an Array; returns self
. The order of the permutations is indeterminate.
When a block and a positive Integer argument n
are given, calls the block with each n
-tuple repeated permutation of the elements of self
. The number of permutations is self.size**n
.
n
= 1:
a = [0, 1, 2]a.repeated_permutation(1) {|permutation| p permutation }
Output:
[0][1][2]
n
= 2:
a.repeated_permutation(2) {|permutation| p permutation }
Output:
[0, 0][0, 1][0, 2][1, 0][1, 1][1, 2][2, 0][2, 1][2, 2]
If n
is zero, calls the block once with an empty Array.
If n
is negative, does not call the block:
a.repeated_permutation(-1) {|permutation| fail 'Cannot happen' }
Returns a new Enumerator if no block given:
a = [0, 1, 2]a.repeated_permutation(2) # => #<Enumerator: [0, 1, 2]:permutation(2)>
Using Enumerators, it's convenient to show the permutations and counts for some values of n
:
e = a.repeated_permutation(0)e.size # => 1e.to_a # => [[]]e = a.repeated_permutation(1)e.size # => 3e.to_a # => [[0], [1], [2]]e = a.repeated_permutation(2)e.size # => 9e.to_a # => [[0, 0], [0, 1], [0, 2], [1, 0], [1, 1], [1, 2], [2, 0], [2, 1], [2, 2]]
static VALUErb_ary_repeated_permutation(VALUE ary, VALUE num){ long r, n, i; n = RARRAY_LEN(ary); /* Array length */ RETURN_SIZED_ENUMERATOR(ary, 1, &num, rb_ary_repeated_permutation_size); /* Return Enumerator if no block */ r = NUM2LONG(num); /* Permutation size from argument */ if (r < 0) { /* no permutations: yield nothing */ } else if (r == 0) { /* exactly one permutation: the zero-length array */ rb_yield(rb_ary_new2(0)); } else if (r == 1) { /* this is a special, easy case */ for (i = 0; i < RARRAY_LEN(ary); i++) { rb_yield(rb_ary_new3(1, RARRAY_AREF(ary, i))); } } else { /* this is the general case */ volatile VALUE t0; long *p = ALLOCV_N(long, t0, r); VALUE ary0 = ary_make_shared_copy(ary); /* private defensive copy of ary */ RBASIC_CLEAR_CLASS(ary0); rpermute0(n, r, p, ary0); /* compute and yield repeated permutations */ ALLOCV_END(t0); RBASIC_SET_CLASS_RAW(ary0, rb_cArray); } return ary;}
replace(other_array) → self click to toggle source
Replaces the content of self
with the content of other_array
; returns self
:
a = [:foo, 'bar', 2]a.replace(['foo', :bar, 3]) # => ["foo", :bar, 3]
VALUErb_ary_replace(VALUE copy, VALUE orig){ rb_ary_modify_check(copy); orig = to_ary(orig); if (copy == orig) return copy; if (RARRAY_LEN(orig) <= RARRAY_EMBED_LEN_MAX) { VALUE shared_root = 0; if (ARY_OWNS_HEAP_P(copy)) { ary_heap_free(copy); } else if (ARY_SHARED_P(copy)) { shared_root = ARY_SHARED_ROOT(copy); FL_UNSET_SHARED(copy); } FL_SET_EMBED(copy); ary_memcpy(copy, 0, RARRAY_LEN(orig), RARRAY_CONST_PTR_TRANSIENT(orig)); if (shared_root) { rb_ary_decrement_share(shared_root); } ARY_SET_LEN(copy, RARRAY_LEN(orig)); } else { VALUE shared_root = ary_make_shared(orig); if (ARY_OWNS_HEAP_P(copy)) { ary_heap_free(copy); } else { rb_ary_unshare_safe(copy); } FL_UNSET_EMBED(copy); ARY_SET_PTR(copy, ARY_HEAP_PTR(orig)); ARY_SET_LEN(copy, ARY_HEAP_LEN(orig)); rb_ary_set_shared(copy, shared_root); } ary_verify(copy); return copy;}
reverse → new_array click to toggle source
Returns a new Array with the elements of self
in reverse order.
a = ['foo', 'bar', 'two']a1 = a.reversea1 # => ["two", "bar", "foo"]
static VALUErb_ary_reverse_m(VALUE ary){ long len = RARRAY_LEN(ary); VALUE dup = rb_ary_new2(len); if (len > 0) { const VALUE *p1 = RARRAY_CONST_PTR_TRANSIENT(ary); VALUE *p2 = (VALUE *)RARRAY_CONST_PTR_TRANSIENT(dup) + len - 1; do *p2-- = *p1++; while (--len > 0); } ARY_SET_LEN(dup, RARRAY_LEN(ary)); return dup;}
reverse! → self click to toggle source
Reverses self
in place:
a = ['foo', 'bar', 'two']a.reverse! # => ["two", "bar", "foo"]
static VALUErb_ary_reverse_bang(VALUE ary){ return rb_ary_reverse(ary);}
reverse_each {|element| ... } → self click to toggle source
reverse_each → Enumerator
Iterates backwards over array elements.
When a block given, passes, in reverse order, each element to the block; returns self
:
a = [:foo, 'bar', 2]a.reverse_each {|element| puts "#{element.class} #{element}" }
Output:
Integer 2String barSymbol foo
Allows the array to be modified during iteration:
a = [:foo, 'bar', 2]a.reverse_each {|element| puts element; a.clear if element.to_s.start_with?('b') }
Output:
2bar
When no block given, returns a new Enumerator:
a = [:foo, 'bar', 2]e = a.reverse_eache # => #<Enumerator: [:foo, "bar", 2]:reverse_each>a1 = e.each {|element| puts "#{element.class} #{element}" }
Output:
Integer 2String barSymbol foo
Related: each, each_index.
static VALUErb_ary_reverse_each(VALUE ary){ long len; RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); len = RARRAY_LEN(ary); while (len--) { long nlen; rb_yield(RARRAY_AREF(ary, len)); nlen = RARRAY_LEN(ary); if (nlen < len) { len = nlen; } } return ary;}
rindex(object) → integer or nil click to toggle source
rindex {|element| ... } → integer or nil
rindex → new_enumerator
Returns the index of the last element for which object == element
.
When argument object
is given but no block, returns the index of the last such element found:
a = [:foo, 'bar', 2, 'bar']a.rindex('bar') # => 3
Returns nil
if no such object found.
When a block is given but no argument, calls the block with each successive element; returns the index of the last element for which the block returns a truthy value:
a = [:foo, 'bar', 2, 'bar']a.rindex {|element| element == 'bar' } # => 3
Returns nil
if the block never returns a truthy value.
When neither an argument nor a block is given, returns a new Enumerator:
a = [:foo, 'bar', 2, 'bar']e = a.rindexe # => #<Enumerator: [:foo, "bar", 2, "bar"]:rindex>e.each {|element| element == 'bar' } # => 3
Related: index.
static VALUErb_ary_rindex(int argc, VALUE *argv, VALUE ary){ VALUE val; long i = RARRAY_LEN(ary), len; if (argc == 0) { RETURN_ENUMERATOR(ary, 0, 0); while (i--) { if (RTEST(rb_yield(RARRAY_AREF(ary, i)))) return LONG2NUM(i); if (i > (len = RARRAY_LEN(ary))) { i = len; } } return Qnil; } rb_check_arity(argc, 0, 1); val = argv[0]; if (rb_block_given_p()) rb_warn("given block not used"); while (i--) { VALUE e = RARRAY_AREF(ary, i); if (rb_equal(e, val)) { return LONG2NUM(i); } if (i > RARRAY_LEN(ary)) { break; } } return Qnil;}
rotate → new_array click to toggle source
rotate(count) → new_array
Returns a new Array formed from self
with elements rotated from one end to the other.
When no argument given, returns a new Array that is like self
, except that the first element has been rotated to the last position:
a = [:foo, 'bar', 2, 'bar']a1 = a.rotatea1 # => ["bar", 2, "bar", :foo]
When given a non-negative Integer count
, returns a new Array with count
elements rotated from the beginning to the end:
a = [:foo, 'bar', 2]a1 = a.rotate(2)a1 # => [2, :foo, "bar"]
If count
is large, uses count % array.size
as the count:
a = [:foo, 'bar', 2]a1 = a.rotate(20)a1 # => [2, :foo, "bar"]
If count
is zero, returns a copy of self
, unmodified:
a = [:foo, 'bar', 2]a1 = a.rotate(0)a1 # => [:foo, "bar", 2]
When given a negative Integer count
, rotates in the opposite direction, from end to beginning:
a = [:foo, 'bar', 2]a1 = a.rotate(-2)a1 # => ["bar", 2, :foo]
If count
is small (far from zero), uses count % array.size
as the count:
a = [:foo, 'bar', 2]a1 = a.rotate(-5)a1 # => ["bar", 2, :foo]
static VALUErb_ary_rotate_m(int argc, VALUE *argv, VALUE ary){ VALUE rotated; const VALUE *ptr; long len; long cnt = (rb_check_arity(argc, 0, 1) ? NUM2LONG(argv[0]) : 1); len = RARRAY_LEN(ary); rotated = rb_ary_new2(len); if (len > 0) { cnt = rotate_count(cnt, len); ptr = RARRAY_CONST_PTR_TRANSIENT(ary); len -= cnt; ary_memcpy(rotated, 0, len, ptr + cnt); ary_memcpy(rotated, len, cnt, ptr); } ARY_SET_LEN(rotated, RARRAY_LEN(ary)); return rotated;}
rotate! → self click to toggle source
rotate!(count) → self
Rotates self
in place by moving elements from one end to the other; returns self
.
When no argument given, rotates the first element to the last position:
a = [:foo, 'bar', 2, 'bar']a.rotate! # => ["bar", 2, "bar", :foo]
When given a non-negative Integer count
, rotates count
elements from the beginning to the end:
a = [:foo, 'bar', 2]a.rotate!(2)a # => [2, :foo, "bar"]
If count
is large, uses count % array.size
as the count:
a = [:foo, 'bar', 2]a.rotate!(20)a # => [2, :foo, "bar"]
If count
is zero, returns self
unmodified:
a = [:foo, 'bar', 2]a.rotate!(0)a # => [:foo, "bar", 2]
When given a negative Integer count
, rotates in the opposite direction, from end to beginning:
a = [:foo, 'bar', 2]a.rotate!(-2)a # => ["bar", 2, :foo]
If count
is small (far from zero), uses count % array.size
as the count:
a = [:foo, 'bar', 2]a.rotate!(-5)a # => ["bar", 2, :foo]
static VALUErb_ary_rotate_bang(int argc, VALUE *argv, VALUE ary){ long n = (rb_check_arity(argc, 0, 1) ? NUM2LONG(argv[0]) : 1); rb_ary_rotate(ary, n); return ary;}
sample(random: Random) → object click to toggle source
sample(n, random: Random) → new_ary
Returns random elements from self
.
When no arguments are given, returns a random element from self
:
a = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]a.sample # => 3a.sample # => 8
If self
is empty, returns nil
.
When argument n
is given, returns a new Array containing n
random elements from self
:
a.sample(3) # => [8, 9, 2]a.sample(6) # => [9, 6, 10, 3, 1, 4]
Returns no more than a.size
elements (because no new duplicates are introduced):
a.sample(a.size * 2) # => [6, 4, 1, 8, 5, 9, 10, 2, 3, 7]
But self
may contain duplicates:
a = [1, 1, 1, 2, 2, 3]a.sample(a.size * 2) # => [1, 1, 3, 2, 1, 2]
The argument n
must be a non-negative numeric value. The order of the result array is unrelated to the order of self
. Returns a new empty Array if self
is empty.
The optional random
argument will be used as the random number generator:
a = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]a.sample(random: Random.new(1)) #=> 6a.sample(4, random: Random.new(1)) #=> [6, 10, 9, 2]
# File array.rb, line 60def sample(n = (ary = false), random: Random) if Primitive.mandatory_only? # Primitive.cexpr! %{ rb_ary_sample(self, rb_cRandom, Qfalse, Qfalse) } Primitive.ary_sample0 else # Primitive.cexpr! %{ rb_ary_sample(self, random, n, ary) } Primitive.ary_sample(random, n, ary) endend
select {|element| ... } → new_array click to toggle source
select → new_enumerator
Calls the block, if given, with each element of self
; returns a new Array containing those elements of self
for which the block returns a truthy value:
a = [:foo, 'bar', 2, :bam]a1 = a.select {|element| element.to_s.start_with?('b') }a1 # => ["bar", :bam]
Returns a new Enumerator if no block given:
a = [:foo, 'bar', 2, :bam]a.select # => #<Enumerator: [:foo, "bar", 2, :bam]:select>
Array#filter is an alias for Array#select.
static VALUErb_ary_select(VALUE ary){ VALUE result; long i; RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); result = rb_ary_new2(RARRAY_LEN(ary)); for (i = 0; i < RARRAY_LEN(ary); i++) { if (RTEST(rb_yield(RARRAY_AREF(ary, i)))) { rb_ary_push(result, rb_ary_elt(ary, i)); } } return result;}
select! {|element| ... } → self or nil click to toggle source
select! → new_enumerator
Calls the block, if given with each element of self
; removes from self
those elements for which the block returns false
or nil
.
Returns self
if any elements were removed:
a = [:foo, 'bar', 2, :bam]a.select! {|element| element.to_s.start_with?('b') } # => ["bar", :bam]
Returns nil
if no elements were removed.
Returns a new Enumerator if no block given:
a = [:foo, 'bar', 2, :bam]a.select! # => #<Enumerator: [:foo, "bar", 2, :bam]:select!>
Array#filter! is an alias for Array#select!.
static VALUErb_ary_select_bang(VALUE ary){ struct select_bang_arg args; RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); rb_ary_modify(ary); args.ary = ary; args.len[0] = args.len[1] = 0; return rb_ensure(select_bang_i, (VALUE)&args, select_bang_ensure, (VALUE)&args);}
shift → object or nil click to toggle source
shift(n) → new_array
Removes and returns leading elements.
When no argument is given, removes and returns the first element:
a = [:foo, 'bar', 2]a.shift # => :fooa # => ['bar', 2]
Returns nil
if self
is empty.
When positive Integer argument n
is given, removes the first n
elements; returns those elements in a new Array:
a = [:foo, 'bar', 2]a.shift(2) # => [:foo, 'bar']a # => [2]
If n
is as large as or larger than self.length
, removes all elements; returns those elements in a new Array:
a = [:foo, 'bar', 2]a.shift(3) # => [:foo, 'bar', 2]
If n
is zero, returns a new empty Array; self
is unmodified.
Related: push, pop, unshift.
static VALUErb_ary_shift_m(int argc, VALUE *argv, VALUE ary){ VALUE result; long n; if (argc == 0) { return rb_ary_shift(ary); } rb_ary_modify_check(ary); result = ary_take_first_or_last(argc, argv, ary, ARY_TAKE_FIRST); n = RARRAY_LEN(result); rb_ary_behead(ary,n); return result;}
shuffle(random: Random) → new_ary click to toggle source
Returns a new array with elements of self
shuffled.
a = [1, 2, 3] #=> [1, 2, 3]a.shuffle #=> [2, 3, 1]a #=> [1, 2, 3]
The optional random
argument will be used as the random number generator:
a.shuffle(random: Random.new(1)) #=> [1, 3, 2]
# File array.rb, line 26def shuffle(random: Random) Primitive.rb_ary_shuffle(random)end
shuffle!(random: Random) → array click to toggle source
Shuffles the elements of self
in place.
a = [1, 2, 3] #=> [1, 2, 3]a.shuffle! #=> [2, 3, 1]a #=> [2, 3, 1]
The optional random
argument will be used as the random number generator:
a.shuffle!(random: Random.new(1)) #=> [1, 3, 2]
# File array.rb, line 12def shuffle!(random: Random) Primitive.rb_ary_shuffle_bang(random)end
length → an_integer click to toggle source
Returns the count of elements in self
.
static VALUErb_ary_length(VALUE ary){ long len = RARRAY_LEN(ary); return LONG2NUM(len);}
slice(index) → object or nil click to toggle source
slice(start, length) → object or nil
slice(range) → object or nil
slice(aseq) → object or nil
Returns elements from self
; does not modify self
.
When a single Integer argument index
is given, returns the element at offset index
:
a = [:foo, 'bar', 2]a[0] # => :fooa[2] # => 2a # => [:foo, "bar", 2]
If index
is negative, counts relative to the end of self
:
a = [:foo, 'bar', 2]a[-1] # => 2a[-2] # => "bar"
If index
is out of range, returns nil
.
When two Integer arguments start
and length
are given, returns a new Array of size length
containing successive elements beginning at offset start
:
a = [:foo, 'bar', 2]a[0, 2] # => [:foo, "bar"]a[1, 2] # => ["bar", 2]
If start + length
is greater than self.length
, returns all elements from offset start
to the end:
a = [:foo, 'bar', 2]a[0, 4] # => [:foo, "bar", 2]a[1, 3] # => ["bar", 2]a[2, 2] # => [2]
If start == self.size
and length >= 0
, returns a new empty Array.
If length
is negative, returns nil
.
When a single Range argument range
is given, treats range.min
as start
above and range.size
as length
above:
a = [:foo, 'bar', 2]a[0..1] # => [:foo, "bar"]a[1..2] # => ["bar", 2]
Special case: If range.start == a.size
, returns a new empty Array.
If range.end
is negative, calculates the end index from the end:
a = [:foo, 'bar', 2]a[0..-1] # => [:foo, "bar", 2]a[0..-2] # => [:foo, "bar"]a[0..-3] # => [:foo]
If range.start
is negative, calculates the start index from the end:
a = [:foo, 'bar', 2]a[-1..2] # => [2]a[-2..2] # => ["bar", 2]a[-3..2] # => [:foo, "bar", 2]
If range.start
is larger than the array size, returns nil
.
a = [:foo, 'bar', 2]a[4..1] # => nila[4..0] # => nila[4..-1] # => nil
When a single Enumerator::ArithmeticSequence argument aseq
is given, returns an Array of elements corresponding to the indexes produced by the sequence.
a = ['--', 'data1', '--', 'data2', '--', 'data3']a[(1..).step(2)] # => ["data1", "data2", "data3"]
Unlike slicing with range, if the start or the end of the arithmetic sequence is larger than array size, throws RangeError.
a = ['--', 'data1', '--', 'data2', '--', 'data3']a[(1..11).step(2)]# RangeError (((1..11).step(2)) out of range)a[(7..).step(2)]# RangeError (((7..).step(2)) out of range)
If given a single argument, and its type is not one of the listed, tries to convert it to Integer, and raises if it is impossible:
a = [:foo, 'bar', 2]# Raises TypeError (no implicit conversion of Symbol into Integer):a[:foo]
Array#slice is an alias for Array#[].
VALUErb_ary_aref(int argc, const VALUE *argv, VALUE ary){ rb_check_arity(argc, 1, 2); if (argc == 2) { return rb_ary_aref2(ary, argv[0], argv[1]); } return rb_ary_aref1(ary, argv[0]);}
slice!(n) → object or nil click to toggle source
slice!(start, length) → new_array or nil
slice!(range) → new_array or nil
Removes and returns elements from self
.
When the only argument is an Integer n
, removes and returns the nth element in self
:
a = [:foo, 'bar', 2]a.slice!(1) # => "bar"a # => [:foo, 2]
If n
is negative, counts backwards from the end of self
:
a = [:foo, 'bar', 2]a.slice!(-1) # => 2a # => [:foo, "bar"]
If n
is out of range, returns nil
.
When the only arguments are Integers start
and length
, removes length
elements from self
beginning at offset start
; returns the deleted objects in a new Array:
a = [:foo, 'bar', 2]a.slice!(0, 2) # => [:foo, "bar"]a # => [2]
If start + length
exceeds the array size, removes and returns all elements from offset start
to the end:
a = [:foo, 'bar', 2]a.slice!(1, 50) # => ["bar", 2]a # => [:foo]
If start == a.size
and length
is non-negative, returns a new empty Array.
If length
is negative, returns nil
.
When the only argument is a Range object range
, treats range.min
as start
above and range.size
as length
above:
a = [:foo, 'bar', 2] a.slice!(1..2) # => ["bar", 2]a # => [:foo]
If range.start == a.size
, returns a new empty Array.
If range.start
is larger than the array size, returns nil
.
If range.end
is negative, counts backwards from the end of the array:
a = [:foo, 'bar', 2]a.slice!(0..-2) # => [:foo, "bar"]a # => [2]
If range.start
is negative, calculates the start index backwards from the end of the array:
a = [:foo, 'bar', 2]a.slice!(-2..2) # => ["bar", 2]a # => [:foo]
static VALUErb_ary_slice_bang(int argc, VALUE *argv, VALUE ary){ VALUE arg1; long pos, len; rb_ary_modify_check(ary); rb_check_arity(argc, 1, 2); arg1 = argv[0]; if (argc == 2) { pos = NUM2LONG(argv[0]); len = NUM2LONG(argv[1]); return ary_slice_bang_by_rb_ary_splice(ary, pos, len); } if (!FIXNUM_P(arg1)) { switch (rb_range_beg_len(arg1, &pos, &len, RARRAY_LEN(ary), 0)) { case Qtrue: /* valid range */ return ary_slice_bang_by_rb_ary_splice(ary, pos, len); case Qnil: /* invalid range */ return Qnil; default: /* not a range */ break; } } return rb_ary_delete_at(ary, NUM2LONG(arg1));}
sort → new_array click to toggle source
sort {|a, b| ... } → new_array
Returns a new Array whose elements are those from self
, sorted.
With no block, compares elements using operator <=>
(see Comparable):
a = 'abcde'.split('').shufflea # => ["e", "b", "d", "a", "c"]a1 = a.sorta1 # => ["a", "b", "c", "d", "e"]
With a block, calls the block with each element pair; for each element pair a
and b
, the block should return an integer:
Negative when
b
is to followa
.Zero when
a
andb
are equivalent.Positive when
a
is to followb
.
Example:
a = 'abcde'.split('').shufflea # => ["e", "b", "d", "a", "c"]a1 = a.sort {|a, b| a <=> b }a1 # => ["a", "b", "c", "d", "e"]a2 = a.sort {|a, b| b <=> a }a2 # => ["e", "d", "c", "b", "a"]
When the block returns zero, the order for a
and b
is indeterminate, and may be unstable:
a = 'abcde'.split('').shufflea # => ["e", "b", "d", "a", "c"]a1 = a.sort {|a, b| 0 }a1 # => ["c", "e", "b", "d", "a"]
Related: Enumerable#sort_by.
VALUErb_ary_sort(VALUE ary){ ary = rb_ary_dup(ary); rb_ary_sort_bang(ary); return ary;}
sort! → self click to toggle source
sort! {|a, b| ... } → self
Returns self
with its elements sorted in place.
With no block, compares elements using operator <=>
(see Comparable):
a = 'abcde'.split('').shufflea # => ["e", "b", "d", "a", "c"]a.sort!a # => ["a", "b", "c", "d", "e"]
With a block, calls the block with each element pair; for each element pair a
and b
, the block should return an integer:
Negative when
b
is to followa
.Zero when
a
andb
are equivalent.Positive when
a
is to followb
.
Example:
a = 'abcde'.split('').shufflea # => ["e", "b", "d", "a", "c"]a.sort! {|a, b| a <=> b }a # => ["a", "b", "c", "d", "e"]a.sort! {|a, b| b <=> a }a # => ["e", "d", "c", "b", "a"]
When the block returns zero, the order for a
and b
is indeterminate, and may be unstable:
a = 'abcde'.split('').shufflea # => ["e", "b", "d", "a", "c"]a.sort! {|a, b| 0 }a # => ["d", "e", "c", "a", "b"]
VALUErb_ary_sort_bang(VALUE ary){ rb_ary_modify(ary); assert(!ARY_SHARED_P(ary)); if (RARRAY_LEN(ary) > 1) { VALUE tmp = ary_make_substitution(ary); /* only ary refers tmp */ struct ary_sort_data data; long len = RARRAY_LEN(ary); RBASIC_CLEAR_CLASS(tmp); data.ary = tmp; data.receiver = ary; data.cmp_opt.opt_methods = 0; data.cmp_opt.opt_inited = 0; RARRAY_PTR_USE(tmp, ptr, { ruby_qsort(ptr, len, sizeof(VALUE), rb_block_given_p()?sort_1:sort_2, &data); }); /* WB: no new reference */ rb_ary_modify(ary); if (ARY_EMBED_P(tmp)) { if (ARY_SHARED_P(ary)) { /* ary might be destructively operated in the given block */ rb_ary_unshare(ary); FL_SET_EMBED(ary); } ary_memcpy(ary, 0, ARY_EMBED_LEN(tmp), ARY_EMBED_PTR(tmp)); ARY_SET_LEN(ary, ARY_EMBED_LEN(tmp)); } else { if (!ARY_EMBED_P(ary) && ARY_HEAP_PTR(ary) == ARY_HEAP_PTR(tmp)) { FL_UNSET_SHARED(ary); ARY_SET_CAPA(ary, RARRAY_LEN(tmp)); } else { assert(!ARY_SHARED_P(tmp)); if (ARY_EMBED_P(ary)) { FL_UNSET_EMBED(ary); } else if (ARY_SHARED_P(ary)) { /* ary might be destructively operated in the given block */ rb_ary_unshare(ary); } else { ary_heap_free(ary); } ARY_SET_PTR(ary, ARY_HEAP_PTR(tmp)); ARY_SET_HEAP_LEN(ary, len); ARY_SET_CAPA(ary, ARY_HEAP_LEN(tmp)); } /* tmp was lost ownership for the ptr */ FL_UNSET(tmp, FL_FREEZE); FL_SET_EMBED(tmp); ARY_SET_EMBED_LEN(tmp, 0); FL_SET(tmp, FL_FREEZE); } /* tmp will be GC'ed. */ RBASIC_SET_CLASS_RAW(tmp, rb_cArray); /* rb_cArray must be marked */ } ary_verify(ary); return ary;}
sort_by! {|element| ... } → self click to toggle source
sort_by! → new_enumerator
Sorts the elements of self
in place, using an ordering determined by the block; returns self.
Calls the block with each successive element; sorts elements based on the values returned from the block.
For duplicates returned by the block, the ordering is indeterminate, and may be unstable.
This example sorts strings based on their sizes:
a = ['aaaa', 'bbb', 'cc', 'd']a.sort_by! {|element| element.size }a # => ["d", "cc", "bbb", "aaaa"]
Returns a new Enumerator if no block given:
a = ['aaaa', 'bbb', 'cc', 'd']a.sort_by! # => #<Enumerator: ["aaaa", "bbb", "cc", "d"]:sort_by!>
static VALUErb_ary_sort_by_bang(VALUE ary){ VALUE sorted; RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); rb_ary_modify(ary); sorted = rb_block_call(ary, rb_intern("sort_by"), 0, 0, sort_by_i, 0); rb_ary_replace(ary, sorted); return ary;}
sum(init = 0) → object click to toggle source
sum(init = 0) {|element| ... } → object
When no block is given, returns the object equivalent to:
sum = initarray.each {|element| sum += element }sum
For example, [e1, e2, e3].sum
returns init + e1 + e2 + e3
.
Examples:
a = [0, 1, 2, 3]a.sum # => 6a.sum(100) # => 106
The elements need not be numeric, but must be +
-compatible with each other and with init
:
a = ['abc', 'def', 'ghi']a.sum('jkl') # => "jklabcdefghi"
When a block is given, it is called with each element and the block's return value (instead of the element itself) is used as the addend:
a = ['zero', 1, :two]s = a.sum('Coerced and concatenated: ') {|element| element.to_s }s # => "Coerced and concatenated: zero1two"
Notes:
Array#join and Array#flatten may be faster than Array#sum for an Array of Strings or an Array of Arrays.
Array#sum method may not respect method redefinition of “+” methods such as Integer#+.
static VALUErb_ary_sum(int argc, VALUE *argv, VALUE ary){ VALUE e, v, r; long i, n; int block_given; v = (rb_check_arity(argc, 0, 1) ? argv[0] : LONG2FIX(0)); block_given = rb_block_given_p(); if (RARRAY_LEN(ary) == 0) return v; n = 0; r = Qundef; for (i = 0; i < RARRAY_LEN(ary); i++) { e = RARRAY_AREF(ary, i); if (block_given) e = rb_yield(e); if (FIXNUM_P(e)) { n += FIX2LONG(e); /* should not overflow long type */ if (!FIXABLE(n)) { v = rb_big_plus(LONG2NUM(n), v); n = 0; } } else if (RB_BIGNUM_TYPE_P(e)) v = rb_big_plus(e, v); else if (RB_TYPE_P(e, T_RATIONAL)) { if (r == Qundef) r = e; else r = rb_rational_plus(r, e); } else goto not_exact; } v = finish_exact_sum(n, r, v, argc!=0); return v; not_exact: v = finish_exact_sum(n, r, v, i!=0); if (RB_FLOAT_TYPE_P(e)) { /* * Kahan-Babuska balancing compensated summation algorithm * See https://link.springer.com/article/10.1007/s00607-005-0139-x */ double f, c; double x, t; f = NUM2DBL(v); c = 0.0; goto has_float_value; for (; i < RARRAY_LEN(ary); i++) { e = RARRAY_AREF(ary, i); if (block_given) e = rb_yield(e); if (RB_FLOAT_TYPE_P(e)) has_float_value: x = RFLOAT_VALUE(e); else if (FIXNUM_P(e)) x = FIX2LONG(e); else if (RB_BIGNUM_TYPE_P(e)) x = rb_big2dbl(e); else if (RB_TYPE_P(e, T_RATIONAL)) x = rb_num2dbl(e); else goto not_float; if (isnan(f)) continue; if (isnan(x)) { f = x; continue; } if (isinf(x)) { if (isinf(f) && signbit(x) != signbit(f)) f = NAN; else f = x; continue; } if (isinf(f)) continue; t = f + x; if (fabs(f) >= fabs(x)) c += ((f - t) + x); else c += ((x - t) + f); f = t; } f += c; return DBL2NUM(f); not_float: v = DBL2NUM(f); } goto has_some_value; for (; i < RARRAY_LEN(ary); i++) { e = RARRAY_AREF(ary, i); if (block_given) e = rb_yield(e); has_some_value: v = rb_funcall(v, idPLUS, 1, e); } return v;}
take(n) → new_array click to toggle source
Returns a new Array containing the first n
element of self
, where n
is a non-negative Integer; does not modify self
.
Examples:
a = [0, 1, 2, 3, 4, 5]a.take(1) # => [0]a.take(2) # => [0, 1]a.take(50) # => [0, 1, 2, 3, 4, 5]a # => [0, 1, 2, 3, 4, 5]
static VALUErb_ary_take(VALUE obj, VALUE n){ long len = NUM2LONG(n); if (len < 0) { rb_raise(rb_eArgError, "attempt to take negative size"); } return rb_ary_subseq(obj, 0, len);}
take_while {|element| ... } → new_array click to toggle source
take_while → new_enumerator
Returns a new Array containing zero or more leading elements of self
; does not modify self
.
With a block given, calls the block with each successive element of self
; stops if the block returns false
or nil
; returns a new Array containing those elements for which the block returned a truthy value:
a = [0, 1, 2, 3, 4, 5]a.take_while {|element| element < 3 } # => [0, 1, 2]a.take_while {|element| true } # => [0, 1, 2, 3, 4, 5]a # => [0, 1, 2, 3, 4, 5]
With no block given, returns a new Enumerator:
[0, 1].take_while # => #<Enumerator: [0, 1]:take_while>
static VALUErb_ary_take_while(VALUE ary){ long i; RETURN_ENUMERATOR(ary, 0, 0); for (i = 0; i < RARRAY_LEN(ary); i++) { if (!RTEST(rb_yield(RARRAY_AREF(ary, i)))) break; } return rb_ary_take(ary, LONG2FIX(i));}
to_a → self or new_array click to toggle source
When self
is an instance of Array, returns self
:
a = [:foo, 'bar', 2]a.to_a # => [:foo, "bar", 2]
Otherwise, returns a new Array containing the elements of self
:
class MyArray < Array; enda = MyArray.new(['foo', 'bar', 'two'])a.instance_of?(Array) # => falsea.kind_of?(Array) # => truea1 = a.to_aa1 # => ["foo", "bar", "two"]a1.class # => Array # Not MyArray
static VALUErb_ary_to_a(VALUE ary){ if (rb_obj_class(ary) != rb_cArray) { VALUE dup = rb_ary_new2(RARRAY_LEN(ary)); rb_ary_replace(dup, ary); return dup; } return ary;}
to_ary → self click to toggle source
Returns self
.
static VALUErb_ary_to_ary_m(VALUE ary){ return ary;}
to_h → new_hash click to toggle source
to_h {|item| ... } → new_hash
Returns a new Hash formed from self
.
When a block is given, calls the block with each array element; the block must return a 2-element Array whose two elements form a key-value pair in the returned Hash:
a = ['foo', :bar, 1, [2, 3], {baz: 4}]h = a.to_h {|item| [item, item] }h # => {"foo"=>"foo", :bar=>:bar, 1=>1, [2, 3]=>[2, 3], {:baz=>4}=>{:baz=>4}}
When no block is given, self
must be an Array of 2-element sub-arrays, each sub-array is formed into a key-value pair in the new Hash:
[].to_h # => {}a = [['foo', 'zero'], ['bar', 'one'], ['baz', 'two']]h = a.to_hh # => {"foo"=>"zero", "bar"=>"one", "baz"=>"two"}
static VALUErb_ary_to_h(VALUE ary){ long i; VALUE hash = rb_hash_new_with_size(RARRAY_LEN(ary)); int block_given = rb_block_given_p(); for (i=0; i<RARRAY_LEN(ary); i++) { const VALUE e = rb_ary_elt(ary, i); const VALUE elt = block_given ? rb_yield_force_blockarg(e) : e; const VALUE key_value_pair = rb_check_array_type(elt); if (NIL_P(key_value_pair)) { rb_raise(rb_eTypeError, "wrong element type %"PRIsVALUE" at %ld (expected array)", rb_obj_class(elt), i); } if (RARRAY_LEN(key_value_pair) != 2) { rb_raise(rb_eArgError, "wrong array length at %ld (expected 2, was %ld)", i, RARRAY_LEN(key_value_pair)); } rb_hash_aset(hash, RARRAY_AREF(key_value_pair, 0), RARRAY_AREF(key_value_pair, 1)); } return hash;}
to_s() click to toggle source
Also aliased as: old_to_s
Alias for: inspect
transpose → new_array click to toggle source
Transposes the rows and columns in an Array of Arrays; the nested Arrays must all be the same size:
a = [[:a0, :a1], [:b0, :b1], [:c0, :c1]]a.transpose # => [[:a0, :b0, :c0], [:a1, :b1, :c1]]
static VALUErb_ary_transpose(VALUE ary){ long elen = -1, alen, i, j; VALUE tmp, result = 0; alen = RARRAY_LEN(ary); if (alen == 0) return rb_ary_dup(ary); for (i=0; i<alen; i++) { tmp = to_ary(rb_ary_elt(ary, i)); if (elen < 0) { /* first element */ elen = RARRAY_LEN(tmp); result = rb_ary_new2(elen); for (j=0; j<elen; j++) { rb_ary_store(result, j, rb_ary_new2(alen)); } } else if (elen != RARRAY_LEN(tmp)) { rb_raise(rb_eIndexError, "element size differs (%ld should be %ld)", RARRAY_LEN(tmp), elen); } for (j=0; j<elen; j++) { rb_ary_store(rb_ary_elt(result, j), i, rb_ary_elt(tmp, j)); } } return result;}
union(*other_arrays) → new_array click to toggle source
Returns a new Array that is the union of self
and all given Arrays other_arrays
; duplicates are removed; order is preserved; items are compared using eql?
:
[0, 1, 2, 3].union([4, 5], [6, 7]) # => [0, 1, 2, 3, 4, 5, 6, 7][0, 1, 1].union([2, 1], [3, 1]) # => [0, 1, 2, 3][0, 1, 2, 3].union([3, 2], [1, 0]) # => [0, 1, 2, 3]
Returns a copy of self
if no arguments given.
Related: Array#|.
static VALUErb_ary_union_multi(int argc, VALUE *argv, VALUE ary){ int i; long sum; VALUE hash, ary_union; sum = RARRAY_LEN(ary); for (i = 0; i < argc; i++) { argv[i] = to_ary(argv[i]); sum += RARRAY_LEN(argv[i]); } if (sum <= SMALL_ARRAY_LEN) { ary_union = rb_ary_new(); rb_ary_union(ary_union, ary); for (i = 0; i < argc; i++) rb_ary_union(ary_union, argv[i]); return ary_union; } hash = ary_make_hash(ary); for (i = 0; i < argc; i++) rb_ary_union_hash(hash, argv[i]); ary_union = rb_hash_values(hash); ary_recycle_hash(hash); return ary_union;}
uniq → new_array click to toggle source
uniq {|element| ... } → new_array
Returns a new Array containing those elements from self
that are not duplicates, the first occurrence always being retained.
With no block given, identifies and omits duplicates using method eql?
to compare.
a = [0, 0, 1, 1, 2, 2]a.uniq # => [0, 1, 2]
With a block given, calls the block for each element; identifies (using method eql?
) and omits duplicate values, that is, those elements for which the block returns the same value:
a = ['a', 'aa', 'aaa', 'b', 'bb', 'bbb']a.uniq {|element| element.size } # => ["a", "aa", "aaa"]
static VALUErb_ary_uniq(VALUE ary){ VALUE hash, uniq; if (RARRAY_LEN(ary) <= 1) { hash = 0; uniq = rb_ary_dup(ary); } else if (rb_block_given_p()) { hash = ary_make_hash_by(ary); uniq = rb_hash_values(hash); } else { hash = ary_make_hash(ary); uniq = rb_hash_values(hash); } if (hash) { ary_recycle_hash(hash); } return uniq;}
uniq! → self or nil click to toggle source
uniq! {|element| ... } → self or nil
Removes duplicate elements from self
, the first occurrence always being retained; returns self
if any elements removed, nil
otherwise.
With no block given, identifies and removes elements using method eql?
to compare.
Returns self
if any elements removed:
a = [0, 0, 1, 1, 2, 2]a.uniq! # => [0, 1, 2]
Returns nil
if no elements removed.
With a block given, calls the block for each element; identifies (using method eql?
) and removes elements for which the block returns duplicate values.
Returns self
if any elements removed:
a = ['a', 'aa', 'aaa', 'b', 'bb', 'bbb']a.uniq! {|element| element.size } # => ['a', 'aa', 'aaa']
Returns nil
if no elements removed.
static VALUErb_ary_uniq_bang(VALUE ary){ VALUE hash; long hash_size; rb_ary_modify_check(ary); if (RARRAY_LEN(ary) <= 1) return Qnil; if (rb_block_given_p()) hash = ary_make_hash_by(ary); else hash = ary_make_hash(ary); hash_size = RHASH_SIZE(hash); if (RARRAY_LEN(ary) == hash_size) { return Qnil; } rb_ary_modify_check(ary); ARY_SET_LEN(ary, 0); if (ARY_SHARED_P(ary) && !ARY_EMBED_P(ary)) { rb_ary_unshare(ary); FL_SET_EMBED(ary); } ary_resize_capa(ary, hash_size); rb_hash_foreach(hash, push_value, ary); ary_recycle_hash(hash); return ary;}
unshift(*objects) → self click to toggle source
Prepends the given objects
to self
:
a = [:foo, 'bar', 2]a.unshift(:bam, :bat) # => [:bam, :bat, :foo, "bar", 2]
Array#prepend is an alias for Array#unshift.
Related: push, pop, shift.
static VALUErb_ary_unshift_m(int argc, VALUE *argv, VALUE ary){ long len = RARRAY_LEN(ary); VALUE target_ary; if (argc == 0) { rb_ary_modify_check(ary); return ary; } target_ary = ary_ensure_room_for_unshift(ary, argc); ary_memcpy0(ary, 0, argc, argv, target_ary); ARY_SET_LEN(ary, len + argc); return ary;}
Also aliased as: prepend
values_at(*indexes) → new_array click to toggle source
Returns a new Array whose elements are the elements of self
at the given Integer or Range indexes
.
For each positive index
, returns the element at offset index
:
a = [:foo, 'bar', 2]a.values_at(0, 2) # => [:foo, 2]a.values_at(0..1) # => [:foo, "bar"]
The given indexes
may be in any order, and may repeat:
a = [:foo, 'bar', 2]a.values_at(2, 0, 1, 0, 2) # => [2, :foo, "bar", :foo, 2]a.values_at(1, 0..2) # => ["bar", :foo, "bar", 2]
Assigns nil
for an index
that is too large:
a = [:foo, 'bar', 2]a.values_at(0, 3, 1, 3) # => [:foo, nil, "bar", nil]
Returns a new empty Array if no arguments given.
For each negative index
, counts backward from the end of the array:
a = [:foo, 'bar', 2]a.values_at(-1, -3) # => [2, :foo]
Assigns nil
for an index
that is too small:
a = [:foo, 'bar', 2]a.values_at(0, -5, 1, -6, 2) # => [:foo, nil, "bar", nil, 2]
The given indexes
may have a mixture of signs:
a = [:foo, 'bar', 2]a.values_at(0, -2, 1, -1) # => [:foo, "bar", "bar", 2]
static VALUErb_ary_values_at(int argc, VALUE *argv, VALUE ary){ long i, olen = RARRAY_LEN(ary); VALUE result = rb_ary_new_capa(argc); for (i = 0; i < argc; ++i) { append_values_at_single(result, ary, olen, argv[i]); } RB_GC_GUARD(ary); return result;}
zip(*other_arrays) → new_array click to toggle source
zip(*other_arrays) {|other_array| ... } → nil
When no block given, returns a new Array new_array
of size self.size
whose elements are Arrays.
Each nested array new_array[n]
is of size other_arrays.size+1
, and contains:
The nth element of
self
.The nth element of each of the
other_arrays
.
If all other_arrays
and self
are the same size:
a = [:a0, :a1, :a2, :a3]b = [:b0, :b1, :b2, :b3]c = [:c0, :c1, :c2, :c3]d = a.zip(b, c)d # => [[:a0, :b0, :c0], [:a1, :b1, :c1], [:a2, :b2, :c2], [:a3, :b3, :c3]]
If any array in other_arrays
is smaller than self
, fills to self.size
with nil
:
a = [:a0, :a1, :a2, :a3]b = [:b0, :b1, :b2]c = [:c0, :c1]d = a.zip(b, c)d # => [[:a0, :b0, :c0], [:a1, :b1, :c1], [:a2, :b2, nil], [:a3, nil, nil]]
If any array in other_arrays
is larger than self
, its trailing elements are ignored:
a = [:a0, :a1, :a2, :a3]b = [:b0, :b1, :b2, :b3, :b4]c = [:c0, :c1, :c2, :c3, :c4, :c5]d = a.zip(b, c)d # => [[:a0, :b0, :c0], [:a1, :b1, :c1], [:a2, :b2, :c2], [:a3, :b3, :c3]]
When a block is given, calls the block with each of the sub-arrays (formed as above); returns nil
a = [:a0, :a1, :a2, :a3]b = [:b0, :b1, :b2, :b3]c = [:c0, :c1, :c2, :c3]a.zip(b, c) {|sub_array| p sub_array} # => nil
Output:
[:a0, :b0, :c0][:a1, :b1, :c1][:a2, :b2, :c2][:a3, :b3, :c3]
static VALUErb_ary_zip(int argc, VALUE *argv, VALUE ary){ int i, j; long len = RARRAY_LEN(ary); VALUE result = Qnil; for (i=0; i<argc; i++) { argv[i] = take_items(argv[i], len); } if (rb_block_given_p()) { int arity = rb_block_arity(); if (arity > 1) { VALUE work, *tmp; tmp = ALLOCV_N(VALUE, work, argc+1); for (i=0; i<RARRAY_LEN(ary); i++) { tmp[0] = RARRAY_AREF(ary, i); for (j=0; j<argc; j++) { tmp[j+1] = rb_ary_elt(argv[j], i); } rb_yield_values2(argc+1, tmp); } if (work) ALLOCV_END(work); } else { for (i=0; i<RARRAY_LEN(ary); i++) { VALUE tmp = rb_ary_new2(argc+1); rb_ary_push(tmp, RARRAY_AREF(ary, i)); for (j=0; j<argc; j++) { rb_ary_push(tmp, rb_ary_elt(argv[j], i)); } rb_yield(tmp); } } } else { result = rb_ary_new_capa(len); for (i=0; i<len; i++) { VALUE tmp = rb_ary_new_capa(argc+1); rb_ary_push(tmp, RARRAY_AREF(ary, i)); for (j=0; j<argc; j++) { rb_ary_push(tmp, rb_ary_elt(argv[j], i)); } rb_ary_push(result, tmp); } } return result;}
array | other_array → new_array click to toggle source
Returns the union of array
and Array other_array
; duplicates are removed; order is preserved; items are compared using eql?
:
[0, 1] | [2, 3] # => [0, 1, 2, 3][0, 1, 1] | [2, 2, 3] # => [0, 1, 2, 3][0, 1, 2] | [3, 2, 1, 0] # => [0, 1, 2, 3]
Related: Array#union.
static VALUErb_ary_or(VALUE ary1, VALUE ary2){ VALUE hash, ary3; ary2 = to_ary(ary2); if (RARRAY_LEN(ary1) + RARRAY_LEN(ary2) <= SMALL_ARRAY_LEN) { ary3 = rb_ary_new(); rb_ary_union(ary3, ary1); rb_ary_union(ary3, ary2); return ary3; } hash = ary_make_hash(ary1); rb_ary_union_hash(hash, ary2); ary3 = rb_hash_values(hash); ary_recycle_hash(hash); return ary3;}