array[index]         = obj                     →  obj
array[start, length] = obj or an_array or nil  →  obj or an_array or nil
array[range]         = obj or an_array or nil  →  obj or an_array or nil

Element Assignment—Sets the element at index, or replaces a subarray starting at start and continuing for length elements, or replaces a subarray specified by range. If indices are greater than the current capacity of the array, the array grows automatically. A negative indices will count backward from the end of the array. Inserts elements if length is zero. If nil is used in the second and third form, deletes elements from self. An IndexError is raised if a negative index points past the beginning of the array. See also Array#push, and Array#unshift.

a = Array.new
a[4] = "4";                 #=> [nil, nil, nil, nil, "4"]
a[0, 3] = [ 'a', 'b', 'c' ] #=> ["a", "b", "c", nil, "4"]
a[1..2] = [ 1, 2 ]          #=> ["a", 1, 2, nil, "4"]
a[0, 2] = "?"               #=> ["?", 2, nil, "4"]
a[0..2] = "A"               #=> ["A", "4"]
a[-1]   = "Z"               #=> ["A", "Z"]
a[1..-1] = nil              #=> ["A"]

Source Code

/* 
*  call-seq:
*     array[index]         = obj                     ->  obj
*     array[start, length] = obj or an_array or nil  ->  obj or an_array or nil
*     array[range]         = obj or an_array or nil  ->  obj or an_array or nil
*
*  Element Assignment---Sets the element at _index_,
*  or replaces a subarray starting at _start_ and
*  continuing for _length_ elements, or replaces a subarray
*  specified by _range_.  If indices are greater than
*  the current capacity of the array, the array grows
*  automatically. A negative indices will count backward
*  from the end of the array. Inserts elements if _length_ is
*  zero. If +nil+ is used in the second and third form,
*  deletes elements from _self_. An +IndexError+ is raised if a
*  negative index points past the beginning of the array. See also
*  <code>Array#push</code>, and <code>Array#unshift</code>.
* 
*     a = Array.new
*     a[4] = "4";                 #=> [nil, nil, nil, nil, "4"]
*     a[0, 3] = [ 'a', 'b', 'c' ] #=> ["a", "b", "c", nil, "4"]
*     a[1..2] = [ 1, 2 ]          #=> ["a", 1, 2, nil, "4"]
*     a[0, 2] = "?"               #=> ["?", 2, nil, "4"]
*     a[0..2] = "A"               #=> ["A", "4"]
*     a[-1]   = "Z"               #=> ["A", "Z"]
*     a[1..-1] = nil              #=> ["A"]
*/

static VALUE
rb_ary_aset(argc, argv, ary)
   int argc;
   VALUE *argv;
   VALUE ary;
{
   long offset, beg, len;

   if (argc == 3) {
       if (SYMBOL_P(argv[0])) {
           rb_raise(rb_eTypeError, "Symbol as array index");
       }
       if (SYMBOL_P(argv[1])) {
           rb_raise(rb_eTypeError, "Symbol as subarray length");
       }
       rb_ary_splice(ary, NUM2LONG(argv[0]), NUM2LONG(argv[1]), argv[2]);
       return argv[2];
   }
   if (argc != 2) {
       rb_raise(rb_eArgError, "wrong number of arguments (%d for 2)", argc);
   }
   if (FIXNUM_P(argv[0])) {
       offset = FIX2LONG(argv[0]);
       goto fixnum;
   }
   if (SYMBOL_P(argv[0])) {
       rb_raise(rb_eTypeError, "Symbol as array index");
   }
   if (rb_range_beg_len(argv[0], &beg, &len, RARRAY(ary)->len, 1)) {
       /* check if idx is Range */
       rb_ary_splice(ary, beg, len, argv[1]);
       return argv[1];
   }

   offset = NUM2LONG(argv[0]);
fixnum:
   rb_ary_store(ary, offset, argv[1]);
   return argv[1];
}