mirror of
https://github.com/ruby/ruby.git
synced 2022-11-09 12:17:21 -05:00
138 lines
3.8 KiB
Text
138 lines
3.8 KiB
Text
== \String Slices
|
||
|
||
A _slice_ of a string is a substring that is selected by certain criteria.
|
||
|
||
These instance methods make use of slicing:
|
||
|
||
- String#[] (also aliased as String#slice) returns a slice copied from +self+.
|
||
- String#[]= returns a copy of +self+ with a slice replaced.
|
||
- String#slice! returns +self+ with a slice removed.
|
||
|
||
Each of the above methods takes arguments that determine the slice
|
||
to be copied or replaced.
|
||
|
||
The arguments have several forms.
|
||
For string +string+, the forms are:
|
||
|
||
- <tt>string[index]</tt>.
|
||
- <tt>string[start, length]</tt>.
|
||
- <tt>string[range]</tt>.
|
||
- <tt>string[regexp, capture = 0]</tt>.
|
||
- <tt>string[substring]</tt>.
|
||
|
||
<b><tt>string[index]</tt></b>
|
||
|
||
When non-negative integer argument +index+ is given,
|
||
the slice is the 1-character substring found in +self+ at character offset +index+:
|
||
|
||
'bar'[0] # => "b"
|
||
'bar'[2] # => "r"
|
||
'bar'[20] # => nil
|
||
'тест'[2] # => "с"
|
||
'こんにちは'[4] # => "は"
|
||
|
||
When negative integer +index+ is given,
|
||
the slice begins at the offset given by counting backward from the end of +self+:
|
||
|
||
'bar'[-3] # => "b"
|
||
'bar'[-1] # => "r"
|
||
'bar'[-20] # => nil
|
||
|
||
<b><tt>string[start, length]</tt></b>
|
||
|
||
When non-negative integer arguments +start+ and +length+ are given,
|
||
the slice begins at character offset +start+, if it exists,
|
||
and continues for +length+ characters, if available:
|
||
|
||
'foo'[0, 2] # => "fo"
|
||
'тест'[1, 2] # => "ес"
|
||
'こんにちは'[2, 2] # => "にち"
|
||
# Zero length.
|
||
'foo'[2, 0] # => ""
|
||
# Length not entirely available.
|
||
'foo'[1, 200] # => "oo"
|
||
# Start out of range.
|
||
'foo'[4, 2] # => nil
|
||
|
||
Special case: if +start+ is equal to the length of +self+,
|
||
the slice is a new empty string:
|
||
|
||
'foo'[3, 2] # => ""
|
||
'foo'[3, 200] # => ""
|
||
|
||
When negative +start+ and non-negative +length+ are given,
|
||
the slice beginning is determined by counting backward from the end of +self+,
|
||
and the slice continues for +length+ characters, if available:
|
||
|
||
'foo'[-2, 2] # => "oo"
|
||
'foo'[-2, 200] # => "oo"
|
||
# Start out of range.
|
||
'foo'[-4, 2] # => nil
|
||
|
||
When negative +length+ is given, there is no slice:
|
||
|
||
'foo'[1, -1] # => nil
|
||
'foo'[-2, -1] # => nil
|
||
|
||
<b><tt>string[range]</tt></b>
|
||
|
||
When Range argument +range+ is given,
|
||
creates a substring of +string+ using the indices in +range+.
|
||
The slice is then determined as above:
|
||
|
||
'foo'[0..1] # => "fo"
|
||
'foo'[0, 2] # => "fo"
|
||
|
||
'foo'[2...2] # => ""
|
||
'foo'[2, 0] # => ""
|
||
|
||
'foo'[1..200] # => "oo"
|
||
'foo'[1, 200] # => "oo"
|
||
|
||
'foo'[4..5] # => nil
|
||
'foo'[4, 2] # => nil
|
||
|
||
'foo'[-4..-3] # => nil
|
||
'foo'[-4, 2] # => nil
|
||
|
||
'foo'[3..4] # => ""
|
||
'foo'[3, 2] # => ""
|
||
|
||
'foo'[-2..-1] # => "oo"
|
||
'foo'[-2, 2] # => "oo"
|
||
|
||
'foo'[-2..197] # => "oo"
|
||
'foo'[-2, 200] # => "oo"
|
||
|
||
<b><tt>string[regexp, capture = 0]</tt></b>
|
||
|
||
When the \Regexp argument +regexp+ is given,
|
||
and the +capture+ argument is <tt>0</tt>,
|
||
the slice is the first matching substring found in +self+:
|
||
|
||
'foo'[/o/] # => "o"
|
||
'foo'[/x/] # => nil
|
||
s = 'hello there'
|
||
s[/[aeiou](.)\1/] # => "ell"
|
||
s[/[aeiou](.)\1/, 0] # => "ell"
|
||
|
||
If argument +capture+ is given and not <tt>0</tt>,
|
||
it should be either an capture group index (integer)
|
||
or a capture group name (string or symbol);
|
||
the slice is the specified capture (see Regexp@Capturing):
|
||
|
||
s = 'hello there'
|
||
s[/[aeiou](.)\1/, 1] # => "l"
|
||
s[/(?<vowel>[aeiou])(?<non_vowel>[^aeiou])/, "non_vowel"] # => "l"
|
||
s[/(?<vowel>[aeiou])(?<non_vowel>[^aeiou])/, :vowel] # => "e"
|
||
|
||
If an invalid capture group index is given, there is no slice.
|
||
If an invalid capture group name is given, +IndexError+ is raised.
|
||
|
||
<b><tt>string[substring]</tt></b>
|
||
|
||
When the single \String argument +substring+ is given,
|
||
returns the substring from +self+ if found, otherwise +nil+:
|
||
|
||
'foo'['oo'] # => "oo"
|
||
'foo'['xx'] # => nil
|