ruby/doc/string/aset.rdoc

Returns +self+ with all, a substring, or none of its contents replaced;
returns the argument +other_string+.

<b>Form <tt>self[index] = other_string</tt></b>

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.

<b>Form <tt>self[start, length] = other_string</tt></b>

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"

<b>Form <tt>self[range] = other_string</tt></b>

With Range argument +range+ given,
equivalent to <tt>self[range.start, range.size] = other_string</tt>:

  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

<b>Form <tt>self[regexp, capture = 0] = other_string</tt></b>

With Regexp argument +regexp+ given and +capture+ as zero,
searches for a matching substring in +self+;
updates {Regexp-related global variables}[rdoc-ref:Regexp@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 +n+th 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.

<b>Form <tt>self[substring] = other_string</tt></b>

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}[rdoc-ref:String@Modifying].