Returns self as a recursively flattening of self to depth levels of recursion; depth must be an integer-convertible object, or nil. At each level of recursion:
Each element that is an array is “flattened” (that is, replaced by its individual array elements).
Each element that is not an array is unchanged (even if the element is an object that has instance method flatten).
Returns nil if no elements were flattened.
With non-negative integer argument depth, flattens recursively through depth levels:
a = [ 0, [ 1, [2, 3], 4 ], 5, {foo: 0}, Set.new([6, 7]) ] a # => [0, [1, [2, 3], 4], 5, {:foo=>0}, #<Set: {6, 7}>] a.dup.flatten!(1) # => [0, 1, [2, 3], 4, 5, {:foo=>0}, #<Set: {6, 7}>] a.dup.flatten!(1.1) # => [0, 1, [2, 3], 4, 5, {:foo=>0}, #<Set: {6, 7}>] a.dup.flatten!(2) # => [0, 1, 2, 3, 4, 5, {:foo=>0}, #<Set: {6, 7}>] a.dup.flatten!(3) # => [0, 1, 2, 3, 4, 5, {:foo=>0}, #<Set: {6, 7}>]
With nil or negative argument depth, flattens all levels:
a.dup.flatten! # => [0, 1, 2, 3, 4, 5, {:foo=>0}, #<Set: {6, 7}>] a.dup.flatten!(-1) # => [0, 1, 2, 3, 4, 5, {:foo=>0}, #<Set: {6, 7}>]
Related: Array#flatten; see also Methods for Assigning.
Returns a count of specified elements.
With no argument and no block, returns the count of all elements:
[0, :one, 'two', 3, 3.0].count # => 5
With argument object given, returns the count of elements == to object:
[0, :one, 'two', 3, 3.0].count(3) # => 2
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 object and a block given, issues a warning, ignores the block, and returns the count of elements == to object.
Related: see Methods for Querying.
With a block given, may call the block, depending on the value of argument count; count must be an integer-convertible object, or nil.
When count is positive, calls the block with each element, then does so repeatedly, until it has done so count times; returns nil:
output = [] [0, 1].cycle(2) {|element| output.push(element) } # => nil output # => [0, 1, 0, 1]
When 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 count is nil, cycles forever:
# Prints 0 and 1 forever. [0, 1].cycle {|element| puts element } [0, 1].cycle(nil) {|element| puts element }
With no block given, returns a new Enumerator.
Related: see Methods for Iterating.
Iterates over permutations of the elements of self; the order of permutations is indeterminate.
With a block and an in-range positive integer argument count (0 < count <= self.size) given, calls the block with each permutation of self of size count; returns self:
a = [0, 1, 2] perms = [] a.permutation(1) {|perm| perms.push(perm) } perms # => [[0], [1], [2]] perms = [] a.permutation(2) {|perm| perms.push(perm) } perms # => [[0, 1], [0, 2], [1, 0], [1, 2], [2, 0], [2, 1]] perms = [] a.permutation(3) {|perm| perms.push(perm) } perms # => [[0, 1, 2], [0, 2, 1], [1, 0, 2], [1, 2, 0], [2, 0, 1], [2, 1, 0]]
When count is zero, calls the block once with a new empty array:
perms = [] a.permutation(0) {|perm| perms.push(perm) } perms # => [[]]
When count is out of range (negative or larger than self.size), does not call the block:
a.permutation(-1) {|permutation| fail 'Cannot happen' } a.permutation(4) {|permutation| fail 'Cannot happen' }
With no block given, returns a new Enumerator.
Related: Methods for Iterating.
When a block and a positive integer-convertible object argument count (0 < count <= self.size) are given, calls the block with each combination of self of size count; returns self:
a = %w[a b c] # => ["a", "b", "c"] a.combination(2) {|combination| p combination } # => ["a", "b", "c"]
Output:
["a", "b"] ["a", "c"] ["b", "c"]
The order of the yielded combinations is not guaranteed.
When count is zero, calls the block once with a new empty array:
a.combination(0) {|combination| p combination } [].combination(0) {|combination| p combination }
Output:
[] []
When count is negative or larger than self.size and self is non-empty, does not call the block:
a.combination(-1) {|combination| fail 'Cannot happen' } # => ["a", "b", "c"] a.combination(4) {|combination| fail 'Cannot happen' } # => ["a", "b", "c"]
With no block given, returns a new Enumerator.
Related: Array#permutation; see also Methods for Iterating.
Computes 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 and other_arrays.
The order of the returned combinations is indeterminate.
With no block given, returns the combinations as an array of arrays:
p = [0, 1].product([2, 3]) # => [[0, 2], [0, 3], [1, 2], [1, 3]] p.size # => 4 p = [0, 1].product([2, 3], [4, 5]) # => [[0, 2, 4], [0, 2, 5], [0, 3, 4], [0, 3, 5], [1, 2, 4], [1, 2, 5], [1, 3, 4], [1, 3,... p.size # => 8
If self or any argument is empty, returns an empty array:
[].product([2, 3], [4, 5]) # => [] [0, 1].product([2, 3], []) # => []
If no argument is given, returns an array of 1-element arrays, each containing an element of self:
a.product # => [[0], [1], [2]]
With a block given, calls the block with each combination; returns self:
p = [] [0, 1].product([2, 3]) {|combination| p.push(combination) } p # => [[0, 2], [0, 3], [1, 2], [1, 3]]
If self or any argument is empty, does not call the block:
[].product([2, 3], [4, 5]) {|combination| fail 'Cannot happen' } # => [] [0, 1].product([2, 3], []) {|combination| fail 'Cannot happen' } # => [0, 1]
If no argument is given, calls the block with each element of self as a 1-element array:
p = [] [0, 1].product {|combination| p.push(combination) } p # => [[0], [1]]
Related: see Methods for Combining.
Returns a new array containing the first count element of self (as available); count must be a non-negative numeric; does not modify self:
a = ['a', 'b', 'c', 'd'] a.take(2) # => ["a", "b"] a.take(2.1) # => ["a", "b"] a.take(50) # => ["a", "b", "c", "d"] a.take(0) # => []
Related: see Methods for Fetching.
Returns a new array containing all but the first count element of self, where count 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] a.drop(9) # => []
Related: see Methods for Fetching.
Returns whether for any element of self, a given criterion is satisfied.
With no block and no argument, returns whether any element of self is truthy:
[nil, false, []].any? # => true # Array object is truthy. [nil, false, {}].any? # => true # Hash object is truthy. [nil, false, ''].any? # => true # String object is truthy. [nil, false].any? # => false # Nil and false are not truthy.
With argument object given, returns whether object === ele for any element ele in self:
[nil, false, 0].any?(0) # => true [nil, false, 1].any?(0) # => false [nil, false, 'food'].any?(/foo/) # => true [nil, false, 'food'].any?(/bar/) # => false
With a block given, calls the block with each element in self; returns whether the block returns any truthy value:
[0, 1, 2].any? {|ele| ele < 1 } # => true [0, 1, 2].any? {|ele| ele < 0 } # => false
With both a block and argument object given, ignores the block and uses object as above.
Special case: returns false if self is empty (regardless of any given argument or block).
Related: see Methods for Querying.
Returns whether for every element of self, a given criterion is satisfied.
With no block and no argument, returns whether every element of self is truthy:
[[], {}, '', 0, 0.0, Object.new].all? # => true # All truthy objects.
[[], {}, '', 0, 0.0, nil].all? # => false # nil is not truthy.
[[], {}, '', 0, 0.0, false].all? # => false # false is not truthy.
With argument object given, returns whether object === ele for every element ele in self:
[0, 0, 0].all?(0) # => true [0, 1, 2].all?(1) # => false ['food', 'fool', 'foot'].all?(/foo/) # => true ['food', 'drink'].all?(/foo/) # => false
With a block given, calls the block with each element in self; returns whether the block returns only truthy values:
[0, 1, 2].all? { |ele| ele < 3 } # => true [0, 1, 2].all? { |ele| ele < 2 } # => false
With both a block and argument object given, ignores the block and uses object as above.
Special case: returns true if self is empty (regardless of any given argument or block).
Related: see Methods for Querying.
Returns true if no element of self meets a given criterion, false otherwise.
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 argument object given, returns false if for any element element, object === element; true 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
With a block given, 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
Related: see Methods for Querying.
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, 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
With argument object given, returns true if for exactly one element element, object === 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: see Methods for Querying.
Finds and returns the object in nested object 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) # => :bat a.dig(1, 2, 3) # => nil
Related: see Methods for Fetching.
With no block given, returns the sum of init and all elements of self; for array array and value init, equivalent to:
sum = init array.each {|element| sum += element } sum
For example, [e0, e1, e2].sum returns init + e0 + e1 + e2.
Examples:
[0, 1, 2, 3].sum # => 6 [0, 1, 2, 3].sum(100) # => 106 ['abc', 'def', 'ghi'].sum('jkl') # => "jklabcdefghi" [[:foo, :bar], ['foo', 'bar']].sum([2, 3]) # => [2, 3, :foo, :bar, "foo", "bar"]
The init value and elements need not be numeric, but must all be +-compatible:
# Raises TypeError: Array can't be coerced into Integer. [[:foo, :bar], ['foo', 'bar']].sum(2)
With a block given, calls the block with each element of self; the block’s return value (instead of the element itself) is used as the addend:
['zero', 1, :two].sum('Coerced and concatenated: ') {|element| element.to_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#+.
Freezes self (if not already frozen); returns self:
a = [] a.frozen? # => false a.freeze a.frozen? # => true
No further changes may be made to self; raises FrozenError if a change is attempted.
Related: Kernel#frozen?.
Appends each argument in objects to self; returns self:
a = [:foo, 'bar', 2] # => [:foo, "bar", 2] a.push(:baz, :bat) # => [:foo, "bar", 2, :baz, :bat]
Appends each argument as a single element, even if it is another array:
a = [:foo, 'bar', 2] # => [:foo, "bar", 2] a.push([:baz, :bat], [:bam, :bad]) # => [:foo, "bar", 2, [:baz, :bat], [:bam, :bad]]
Related: see Methods for Assigning.
Prepends the given objects to self:
a = [:foo, 'bar', 2] a.unshift(:bam, :bat) # => [:bam, :bat, :foo, "bar", 2]
Related: Array#shift; see also Methods for Assigning.
Shuffles all elements in self into a random order, as selected by the object given by the keyword argument random. Returns self:
a = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] a.shuffle! # => [5, 3, 8, 7, 6, 1, 9, 4, 2, 0] a.shuffle! # => [9, 4, 0, 6, 2, 8, 1, 5, 3, 7]
Duplicate elements are included:
a = [0, 1, 0, 1, 0, 1, 0, 1, 0, 1] a.shuffle! # => [1, 0, 0, 1, 1, 0, 1, 0, 0, 1] a.shuffle! # => [0, 1, 0, 1, 1, 0, 1, 0, 1, 0]
The object given with the keyword argument random is used as the random number generator.
Related: see Methods for Assigning.
Returns a new array containing all elements from self in a random order, as selected by the object given by the keyword argument random:
a = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] a.shuffle # => [0, 8, 1, 9, 6, 3, 4, 7, 2, 5] a.shuffle # => [8, 9, 0, 5, 1, 2, 6, 4, 7, 3]
Duplicate elements are included:
a = [0, 1, 0, 1, 0, 1, 0, 1, 0, 1] a.shuffle # => [1, 0, 1, 1, 0, 0, 1, 0, 0, 1] a.shuffle # => [1, 1, 0, 0, 0, 1, 1, 0, 0, 1]
The object given with the keyword argument random is used as the random number generator.
Related: see Methods for Fetching.
Returns random elements from self, as selected by the object given by the keyword argument random.
With no argument count given, returns one random element from self:
a = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] a.sample # => 3 a.sample # => 8
Returns nil if self is empty:
[].sample # => nil
With a non-negative numeric argument count given, returns a new array containing count random elements from self:
a.sample(3) # => [8, 9, 2] a.sample(6) # => [9, 6, 0, 3, 1, 4]
The order of the result array is unrelated to the order of self.
Returns a new empty array if self is empty:
[].sample(4) # => []
May return duplicates in self:
a = [1, 1, 1, 2, 2, 3] a.sample(a.size) # => [1, 1, 3, 2, 1, 2]
Returns no more than a.size elements (because no new duplicates are introduced):
a.sample(50) # => [6, 4, 1, 8, 5, 9, 0, 2, 3, 7]
The object given with the keyword argument random is used as the random number generator:
a = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] a.sample(random: Random.new(1)) # => 6 a.sample(4, random: Random.new(1)) # => [6, 10, 9, 2]
Related: see Methods for Fetching.
Returns elements from self, or nil; does not modify self.
With no argument given, returns the first element (if available):
a = [:foo, 'bar', 2] a.first # => :foo a # => [:foo, "bar", 2]
If self is empty, returns nil.
[].first # => nil
With a non-negative integer argument count given, returns the first count elements (as available) in a new array:
a.first(0) # => [] a.first(2) # => [:foo, "bar"] a.first(50) # => [:foo, "bar", 2]
Related: see Methods for Querying.
Returns elements from self, or nil; self is not modified.
With no argument given, returns the last element, or nil if self is empty:
a = [:foo, 'bar', 2] a.last # => 2 a # => [:foo, "bar", 2] [].last # => nil
With non-negative integer argument count given, returns a new array containing the trailing count elements of self, as available:
a = [:foo, 'bar', 2] a.last(2) # => ["bar", 2] a.last(50) # => [:foo, "bar", 2] a.last(0) # => [] [].last(3) # => []
Related: see Methods for Fetching.
Builds a command line string from an argument list array joining all elements escaped for the Bourne shell and separated by a space.
See Shellwords.shelljoin for details.
Formats each element in self into a binary string; returns that string. See Packed Data.
Return the list of all array-oriented instance variables.