Preview Ruby 4.1 is a preview. It can change before the final release. Switch to Ruby 4.0 →

instance method

Array#values_at

(*::int | ::range[::int?] selector) -> ::Array[Elem?]

values_at(*specifiers) → new_array

static VALUE
rb_ary_values_at(int argc, VALUE *argv, VALUE ary)
{
    rb_len_t 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;
}

Returns elements from self in a new array; does not modify self.

The objects included in the returned array are the elements of self selected by the given specifiers, each of which must be a numeric index or a Range.

In brief:

Example

a = ['a', 'b', 'c', 'd']

# Index specifiers.
a.values_at(2, 0, 2, 0)     # => ["c", "a", "c", "a"] # May repeat.
a.values_at(-4, -3, -2, -1) # => ["a", "b", "c", "d"] # Counts backwards if negative.
a.values_at(-50, 50)        # => [nil, nil]           # Outside of self.

# Range specifiers.
a.values_at(1..3)       # => ["b", "c", "d"] # From range.begin to range.end.
a.values_at(1...3)      # => ["b", "c"]      # End excluded.
a.values_at(3..1)       # => []              # No such elements.

a.values_at(-3..3)  # => ["b", "c", "d"]     # Negative range.begin counts backwards.
a.values_at(-50..3)                          # Raises RangeError.

a.values_at(1..-2)  # => ["b", "c"]          # Negative range.end counts backwards.
a.values_at(1..-50) # => []                  # No such elements.

# Mixture of specifiers.
a.values_at(2..3, 3, 0..1, 0) # => ["c", "d", "d", "a", "b", "a"]

With no specifiers given, returns a new empty array:

Example

a = ['a', 'b', 'c', 'd']
a.values_at # => []

For each numeric specifier index, includes an element:

For each non-negative numeric specifier index that is in-range (less than self.size), includes the element at offset index:

Example
```
a.values_at(0, 2)     # => ["a", "c"]
a.values_at(0.1, 2.9) # => ["a", "c"]
```
For each negative numeric index that is in-range (greater than or equal to - self.size), counts backwards from the end of self:

Example
```
a.values_at(-1, -4) # => ["d", "a"]
```

The given indexes may be in any order, and may repeat:

Example

a.values_at(2, 0, 1, 0, 2) # => ["c", "a", "b", "a", "c"]

For each index that is out-of-range, includes nil:

Example

a.values_at(4, -5) # => [nil, nil]

For each Range specifier range, includes elements according to range.begin and range.end:

If both range.begin and range.end are non-negative and in-range (less than self.size), includes elements from index range.begin through range.end - 1 (if range.exclude_end?), or through range.end (otherwise):

Example
```
a.values_at(1..2)  # => ["b", "c"]
a.values_at(1...2) # => ["b"]
```
If range.begin is negative and in-range (greater than or equal to - self.size), counts backwards from the end of self:

Example
```
a.values_at(-2..3) # => ["c", "d"]
```
If range.begin is negative and out-of-range, raises an exception:

Example
```
a.values_at(-5..3) # Raises RangeError.
```
If range.end is positive and out-of-range, extends the returned array with nil elements:

Example
```
a.values_at(1..5) # => ["b", "c", "d", nil, nil]
```
If range.end is negative and in-range, counts backwards from the end of self:

Example
```
a.values_at(1..-2) # => ["b", "c"]
```
If range.end is negative and out-of-range, returns an empty array:

Example
```
a.values_at(1..-5) # => []
```

The given ranges may be in any order and may repeat:

Example

a.values_at(2..3, 0..1, 2..3) # => ["c", "d", "a", "b", "c", "d"]

The given specifiers may be any mixture of indexes and ranges:

Example

a.values_at(3, 1..2, 0, 2..3) # => ["d", "b", "c", "a", "c", "d"]

Related: see Methods for Fetching.

See also #unshift #zip #uniq! also in 4.0 · 3.4 · 3.3 · 3.2 · 3.1 · 3.0

‹ prev#unshift next ›#zip