Maintenance Ruby 3.4 gets fixes, but no new features. Switch to Ruby 4.0 →

instance method

Array#fill

(Elem obj) -> self

(Elem obj, ::int? start, ?::int? length) -> self

(Elem obj, ::Range[::Integer] range) -> self

(?::int? start, ?::int? length) { (::Integer index) -> Elem } -> self

(::Range[::Integer] range) { (::Integer index) -> Elem } -> self

fill(object, start = nil, count = nil) → new_array

fill(object, range) → new_array

fill(start = nil, count = nil) {|element| ... } → new_array

fill(range) {|element| ... } → new_array

array.c View on GitHub ↗

static VALUE
rb_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 (UNDEF_P(item)) {
        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;
}

Replaces selected elements in self; may add elements to self; always returns self (never a new array).

In brief:

Example

# Non-negative start.
['a', 'b', 'c', 'd'].fill('-', 1, 2)          # => ["a", "-", "-", "d"]
['a', 'b', 'c', 'd'].fill(1, 2) {|e| e.to_s } # => ["a", "1", "2", "d"]

# Extends with specified values if necessary.
['a', 'b', 'c', 'd'].fill('-', 3, 2)          # => ["a", "b", "c", "-", "-"]
['a', 'b', 'c', 'd'].fill(3, 2) {|e| e.to_s } # => ["a", "b", "c", "3", "4"]

# Fills with nils if necessary.
['a', 'b', 'c', 'd'].fill('-', 6, 2)          # => ["a", "b", "c", "d", nil, nil, "-", "-"]
['a', 'b', 'c', 'd'].fill(6, 2) {|e| e.to_s } # => ["a", "b", "c", "d", nil, nil, "6", "7"]

# For negative start, counts backwards from the end.
['a', 'b', 'c', 'd'].fill('-', -3, 3)          # => ["a", "-", "-", "-"]
['a', 'b', 'c', 'd'].fill(-3, 3) {|e| e.to_s } # => ["a", "1", "2", "3"]

# Range.
['a', 'b', 'c', 'd'].fill('-', 1..2)          # => ["a", "-", "-", "d"]
['a', 'b', 'c', 'd'].fill(1..2) {|e| e.to_s } # => ["a", "1", "2", "d"]

When arguments start and count are given, they select the elements of self to be replaced; each must be an integer-convertible object (or nil):

start specifies the zero-based offset of the first element to be replaced; nil means zero.
count is the number of consecutive elements to be replaced; nil means “all the rest.”

With argument object given, that one object is used for all replacements:

Example

o = Object.new           # => #<Object:0x0000014e7bff7600>
a = ['a', 'b', 'c', 'd'] # => ["a", "b", "c", "d"]
a.fill(o, 1, 2)
# => ["a", #<Object:0x0000014e7bff7600>, #<Object:0x0000014e7bff7600>, "d"]

With a block given, the block is called once for each element to be replaced; the value passed to the block is the index of the element to be replaced (not the element itself); the block’s return value replaces the element:

Example

a = ['a', 'b', 'c', 'd']               # => ["a", "b", "c", "d"]
a.fill(1, 2) {|element| element.to_s } # => ["a", "1", "2", "d"]

For arguments start and count:

If start is non-negative, replaces count elements beginning at offset start:

Example

['a', 'b', 'c', 'd'].fill('-', 0, 2) # => ["-", "-", "c", "d"]
['a', 'b', 'c', 'd'].fill('-', 1, 2) # => ["a", "-", "-", "d"]
['a', 'b', 'c', 'd'].fill('-', 2, 2) # => ["a", "b", "-", "-"]

['a', 'b', 'c', 'd'].fill(0, 2) {|e| e.to_s } # => ["0", "1", "c", "d"]
['a', 'b', 'c', 'd'].fill(1, 2) {|e| e.to_s } # => ["a", "1", "2", "d"]
['a', 'b', 'c', 'd'].fill(2, 2) {|e| e.to_s } # => ["a", "b", "2", "3"]

Extends self if necessary:

Example

['a', 'b', 'c', 'd'].fill('-', 3, 2) # => ["a", "b", "c", "-", "-"]
['a', 'b', 'c', 'd'].fill('-', 4, 2) # => ["a", "b", "c", "d", "-", "-"]

['a', 'b', 'c', 'd'].fill(3, 2) {|e| e.to_s } # => ["a", "b", "c", "3", "4"]
['a', 'b', 'c', 'd'].fill(4, 2) {|e| e.to_s } # => ["a", "b", "c", "d", "4", "5"]

Fills with nil if necessary:

Example

['a', 'b', 'c', 'd'].fill('-', 5, 2) # => ["a", "b", "c", "d", nil, "-", "-"]
['a', 'b', 'c', 'd'].fill('-', 6, 2) # => ["a", "b", "c", "d", nil, nil, "-", "-"]

['a', 'b', 'c', 'd'].fill(5, 2) {|e| e.to_s } # => ["a", "b", "c", "d", nil, "5", "6"]
['a', 'b', 'c', 'd'].fill(6, 2) {|e| e.to_s } # => ["a", "b", "c", "d", nil, nil, "6", "7"]

Does nothing if count is non-positive:

Example

['a', 'b', 'c', 'd'].fill('-', 2, 0)    # => ["a", "b", "c", "d"]
['a', 'b', 'c', 'd'].fill('-', 2, -100) # => ["a", "b", "c", "d"]
['a', 'b', 'c', 'd'].fill('-', 6, -100) # => ["a", "b", "c", "d"]

['a', 'b', 'c', 'd'].fill(2, 0) {|e| fail 'Cannot happen' }    # => ["a", "b", "c", "d"]
['a', 'b', 'c', 'd'].fill(2, -100) {|e| fail 'Cannot happen' } # => ["a", "b", "c", "d"]
['a', 'b', 'c', 'd'].fill(6, -100) {|e| fail 'Cannot happen' } # => ["a", "b", "c", "d"]

If start is negative, counts backwards from the end of self:

Example

['a', 'b', 'c', 'd'].fill('-', -4, 3) # => ["-", "-", "-", "d"]
['a', 'b', 'c', 'd'].fill('-', -3, 3) # => ["a", "-", "-", "-"]

['a', 'b', 'c', 'd'].fill(-4, 3) {|e| e.to_s } # => ["0", "1", "2", "d"]
['a', 'b', 'c', 'd'].fill(-3, 3) {|e| e.to_s } # => ["a", "1", "2", "3"]

Extends self if necessary:

Example

['a', 'b', 'c', 'd'].fill('-', -2, 3) # => ["a", "b", "-", "-", "-"]
['a', 'b', 'c', 'd'].fill('-', -1, 3) # => ["a", "b", "c", "-", "-", "-"]

['a', 'b', 'c', 'd'].fill(-2, 3) {|e| e.to_s } # => ["a", "b", "2", "3", "4"]
['a', 'b', 'c', 'd'].fill(-1, 3) {|e| e.to_s } # => ["a", "b", "c", "3", "4", "5"]

Starts at the beginning of self if start is negative and out-of-range:

Example

['a', 'b', 'c', 'd'].fill('-', -5, 2) # => ["-", "-", "c", "d"]
['a', 'b', 'c', 'd'].fill('-', -6, 2) # => ["-", "-", "c", "d"]

['a', 'b', 'c', 'd'].fill(-5, 2) {|e| e.to_s } # => ["0", "1", "c", "d"]
['a', 'b', 'c', 'd'].fill(-6, 2) {|e| e.to_s } # => ["0", "1", "c", "d"]

Does nothing if count is non-positive:

Example

['a', 'b', 'c', 'd'].fill('-', -2, 0)  # => ["a", "b", "c", "d"]
['a', 'b', 'c', 'd'].fill('-', -2, -1) # => ["a", "b", "c", "d"]

['a', 'b', 'c', 'd'].fill(-2, 0) {|e| fail 'Cannot happen' }  # => ["a", "b", "c", "d"]
['a', 'b', 'c', 'd'].fill(-2, -1) {|e| fail 'Cannot happen' } # => ["a", "b", "c", "d"]

When argument range is given, it must be a Range object whose members are numeric; its begin and end values determine the elements of self to be replaced:

If both begin and end are positive, they specify the first and last elements to be replaced:

Example

['a', 'b', 'c', 'd'].fill('-', 1..2)          # => ["a", "-", "-", "d"]
['a', 'b', 'c', 'd'].fill(1..2) {|e| e.to_s } # => ["a", "1", "2", "d"]

If end is smaller than begin, replaces no elements:

Example

['a', 'b', 'c', 'd'].fill('-', 2..1)          # => ["a", "b", "c", "d"]
['a', 'b', 'c', 'd'].fill(2..1) {|e| e.to_s } # => ["a", "b", "c", "d"]

If either is negative (or both are negative), counts backwards from the end of self:

Example

['a', 'b', 'c', 'd'].fill('-', -3..2)  # => ["a", "-", "-", "d"]
['a', 'b', 'c', 'd'].fill('-', 1..-2)  # => ["a", "-", "-", "d"]
['a', 'b', 'c', 'd'].fill('-', -3..-2) # => ["a", "-", "-", "d"]

['a', 'b', 'c', 'd'].fill(-3..2) {|e| e.to_s }  # => ["a", "1", "2", "d"]
['a', 'b', 'c', 'd'].fill(1..-2) {|e| e.to_s }  # => ["a", "1", "2", "d"]
['a', 'b', 'c', 'd'].fill(-3..-2) {|e| e.to_s } # => ["a", "1", "2", "d"]

If the end value is excluded (see Range#exclude_end?), omits the last replacement:

Example

['a', 'b', 'c', 'd'].fill('-', 1...2)  # => ["a", "-", "c", "d"]
['a', 'b', 'c', 'd'].fill('-', 1...-2) # => ["a", "-", "c", "d"]

['a', 'b', 'c', 'd'].fill(1...2) {|e| e.to_s }  # => ["a", "1", "c", "d"]
['a', 'b', 'c', 'd'].fill(1...-2) {|e| e.to_s } # => ["a", "1", "c", "d"]

If the range is endless (see Endless Ranges), replaces elements to the end of self:

Example

['a', 'b', 'c', 'd'].fill('-', 1..)          # => ["a", "-", "-", "-"]
['a', 'b', 'c', 'd'].fill(1..) {|e| e.to_s } # => ["a", "1", "2", "3"]

If the range is beginless (see Beginless Ranges), replaces elements from the beginning of self:

Example

['a', 'b', 'c', 'd'].fill('-', ..2)          # => ["-", "-", "-", "d"]
['a', 'b', 'c', 'd'].fill(..2) {|e| e.to_s } # => ["0", "1", "2", "d"]

Related: see Methods for Assigning.

See also #fetch_values #filter #fetch #filter! also in 4.1 · 4.0 · 3.3 · 3.2 · 3.1 · 3.0

‹ prev#fetch_values next ›#filter