String#[]=
static VALUE
rb_str_aset_m(int argc, VALUE *argv, VALUE str)
{
if (argc == 3) {
if (RB_TYPE_P(argv[0], T_REGEXP)) {
rb_str_subpat_set(str, argv[0], argv[1], argv[2]);
}
else {
rb_str_update(str, NUM2LONG(argv[0]), NUM2LONG(argv[1]), argv[2]);
}
return argv[2];
}
rb_check_arity(argc, 2, 3);
return rb_str_aset(str, argv[0], argv[1]);
}
Returns self with all, a substring, or none of its contents replaced; returns the argument other_string.
Form self[index] = other_string
With non-negative integer argument index given, searches for the 1-character substring found in self at character offset index:
s = 'hello' s[0] = 'foo' # => "foo" s # => "fooello" s = 'hello' s[4] = 'foo' # => "foo" s # => "hellfoo" s = 'hello' s[5] = 'foo' # => "foo" s # => "hellofoo" s = 'hello' s[6] = 'foo' # Raises IndexError: index 6 out of string.
With negative integer argument index given, counts backward from the end of self:
s = 'hello' s[-1] = 'foo' # => "foo" s # => "hellfoo" s = 'hello' s[-5] = 'foo' # => "foo" s # => "fooello" s = 'hello' s[-6] = 'foo' # Raises IndexError: index -6 out of string.
Form self[start, length] = other_string
With integer arguments start and length given, searches for a substring of size length characters (as available) beginning at character offset specified by start.
If argument start is non-negative, the offset is start:
s = 'hello' s[0, 1] = 'foo' # => "foo" s # => "fooello" s = 'hello' s[0, 5] = 'foo' # => "foo" s # => "foo" s = 'hello' s[0, 9] = 'foo' # => "foo" s # => "foo" s = 'hello' s[2, 0] = 'foo' # => "foo" s # => "hefoollo" s = 'hello' s[2, -1] = 'foo' # Raises IndexError: negative length -1.
If argument start is negative, counts backward from the end of self:
s = 'hello' s[-1, 1] = 'foo' # => "foo" s # => "hellfoo" s = 'hello' s[-1, 9] = 'foo' # => "foo" s # => "hellfoo" s = 'hello' s[-5, 2] = 'foo' # => "foo" s # => "foollo" s = 'hello' s[-3, 0] = 'foo' # => "foo" s # => "hefoollo" s = 'hello' s[-6, 2] = 'foo' # Raises IndexError: index -6 out of string.
Special case: if start equals the length of self, the argument is appended to self:
s = 'hello' s[5, 3] = 'foo' # => "foo" s # => "hellofoo"
Form self[range] = other_string
With Range argument range given, equivalent to self[range.start, range.size] = other_string:
s0 = 'hello' s1 = 'hello' s0[0..2] = 'foo' # => "foo" s1[0, 3] = 'foo' # => "foo" s0 # => "foolo" s1 # => "foolo" s = 'hello' s[0...2] = 'foo' # => "foo" s # => "foollo" s = 'hello' s[0...0] = 'foo' # => "foo" s # => "foohello" s = 'hello' s[9..10] = 'foo' # Raises RangeError: 9..10 out of range
Form self[regexp, capture = 0] = other_string
With Regexp argument regexp given and capture as zero, searches for a matching substring in self; updates Regexp-related global variables:
s = 'hello' s[/l/] = 'L' # => "L" [$`, $&, $'] # => ["he", "l", "lo"] s[/eLlo/] = 'owdy' # => "owdy" [$`, $&, $'] # => ["h", "eLlo", ""] s[/eLlo/] = 'owdy' # Raises IndexError: regexp not matched. [$`, $&, $'] # => [nil, nil, nil]
With capture as a positive integer n, searches for the nth matched group:
s = 'hello' s[/(h)(e)(l+)(o)/] = 'foo' # => "foo" [$`, $&, $'] # => ["", "hello", ""] s = 'hello' s[/(h)(e)(l+)(o)/, 1] = 'foo' # => "foo" s # => "fooello" [$`, $&, $'] # => ["", "hello", ""] s = 'hello' s[/(h)(e)(l+)(o)/, 2] = 'foo' # => "foo" s # => "hfoollo" [$`, $&, $'] # => ["", "hello", ""] s = 'hello' s[/(h)(e)(l+)(o)/, 4] = 'foo' # => "foo" s # => "hellfoo" [$`, $&, $'] # => ["", "hello", ""] s = 'hello' # => "hello" s[/(h)(e)(l+)(o)/, 5] = 'foo # Raises IndexError: index 5 out of regexp. s = 'hello' s[/nosuch/] = 'foo' # Raises IndexError: regexp not matched.
Form self[substring] = other_string
With string argument substring given:
s = 'hello' s['l'] = 'foo' # => "foo" s # => "hefoolo" s = 'hello' s['ll'] = 'foo' # => "foo" s # => "hefooo" s = 'Привет' s['ив'] = 'foo' # => "foo" s # => "Прfooет" s = 'こんにちは' s['んにち'] = 'foo' # => "foo" s # => "こfooは" s['nosuch'] = 'foo' # Raises IndexError: string not matched.
Related: see Modifying.