diff options
Diffstat (limited to 'doc/string.rb')
| -rw-r--r-- | doc/string.rb | 158 |
1 files changed, 10 insertions, 148 deletions
diff --git a/doc/string.rb b/doc/string.rb index 9ed97d49f6..4dac94e93a 100644 --- a/doc/string.rb +++ b/doc/string.rb @@ -159,156 +159,17 @@ # - #rstrip, #rstrip!: Strip trailing whitespace. # - #strip, #strip!: Strip leading and trailing whitespace. # -# == +String+ Slices -# -# A _slice_ of a string is a substring selected by certain criteria. -# -# These instance methods utilize slicing: -# -# - String#[] (aliased as String#slice): Returns a slice copied from +self+. -# - String#[]=: Mutates +self+ with the slice replaced. -# - String#slice!: Mutates +self+ with the slice removed and returns the removed slice. -# -# Each of the above methods takes arguments that determine the slice -# to be copied or replaced. -# -# The arguments have several forms. -# For a 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 a 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 a 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+ equals the length of +self+, -# the slice is a new empty string: -# -# 'foo'[3, 2] # => "" -# 'foo'[3, 200] # => "" -# -# When a negative +start+ and non-negative +length+ are given, -# the slice begins by counting backward from the end of +self+, -# and continues for +length+ characters, if available: -# -# 'foo'[-2, 2] # => "oo" -# 'foo'[-2, 200] # => "oo" -# # Start out of range. -# 'foo'[-4, 2] # => nil -# -# When a negative +length+ is given, there is no slice: -# -# 'foo'[1, -1] # => nil -# 'foo'[-2, -1] # => nil -# -# <b><tt>string[range]</tt></b> -# -# When a Range argument +range+ is given, -# it 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 the argument +capture+ is provided and not <tt>0</tt>, -# it should be either a capture group index (integer) -# or a capture group name (String or Symbol); -# the slice is the specified capture (see Regexp@Groups and Captures): -# -# 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, -# it returns the substring from +self+ if found, otherwise +nil+: -# -# 'foo'['oo'] # => "oo" -# 'foo'['xx'] # => nil -# # == What's Here # # First, what's elsewhere. Class +String+: # -# - Inherits from the {Object class}[rdoc-ref:Object@What-27s+Here]. -# - Includes the {Comparable module}[rdoc-ref:Comparable@What-27s+Here]. +# - Inherits from the {Object class}[rdoc-ref:Object@Whats+Here]. +# - Includes the {Comparable module}[rdoc-ref:Comparable@Whats+Here]. # # Here, class +String+ provides methods that are useful for: # # - {Creating a \String}[rdoc-ref:String@Creating+a+String]. -# - {Freezing/Unfreezing a \String}[rdoc-ref:String@Freezing-2FUnfreezing]. +# - {Freezing/Unfreezing a \String}[rdoc-ref:String@FreezingUnfreezing]. # - {Querying a \String}[rdoc-ref:String@Querying]. # - {Comparing Strings}[rdoc-ref:String@Comparing]. # - {Modifying a \String}[rdoc-ref:String@Modifying]. @@ -333,10 +194,10 @@ # # _Counts_ # -# - #length (aliased as #size): Returns the count of characters (not bytes). -# - #empty?: Returns whether the length of +self+ is zero. # - #bytesize: Returns the count of bytes. # - #count: Returns the count of substrings matching given strings. +# - #empty?: Returns whether the length of +self+ is zero. +# - #length (aliased as #size): Returns the count of characters (not bytes). # # _Substrings_ # @@ -387,6 +248,7 @@ # - #<<: Returns +self+ concatenated with a given string or integer. # - #append_as_bytes: Returns +self+ concatenated with strings without performing any # encoding validation or conversion. +# - #prepend: Prefixes to +self+ the concatenation of given other strings. # # _Substitution_ # @@ -396,7 +258,7 @@ # - #gsub!: Replaces each substring that matches a given pattern with a given replacement string; # returns +self+ if any changes, +nil+ otherwise. # - #succ! (aliased as #next!): Returns +self+ modified to become its own successor. -# - #initialize_copy (aliased as #replace): Returns +self+ with its entire content replaced by a given string. +# - #replace: Returns +self+ with its entire content replaced by a given string. # - #reverse!: Returns +self+ with its characters in reverse order. # - #setbyte: Sets the byte at a given integer offset to a given value; returns the argument. # - #tr!: Replaces specified characters in +self+ with specified replacement characters; @@ -447,7 +309,6 @@ # - #+: Returns the concatenation of +self+ and a given other string. # - #center: Returns a copy of +self+, centered by specified padding. # - #concat: Returns the concatenation of +self+ with given other strings. -# - #prepend: Returns the concatenation of a given other string with +self+. # - #ljust: Returns a copy of +self+ of a given length, right-padded with a given other string. # - #rjust: Returns a copy of +self+ of a given length, left-padded with a given other string. # @@ -461,8 +322,7 @@ # _Substitution_ # # - #dump: Returns a printable version of +self+, enclosed in double-quotes. -# - #undump: Returns a copy of +self+ with all <tt>\xNN</tt> notations replaced by <tt>\uNNNN</tt> notations -# and all escaped characters unescaped. +# - #undump: Inverse of #dump; returns a copy of +self+ with changes of the kinds made by #dump "undone." # - #sub: Returns a copy of +self+ with the first substring matching a given pattern # replaced with a given replacement string. # - #gsub: Returns a copy of +self+ with each substring that matches a given pattern @@ -538,8 +398,10 @@ # - #hex: Returns the integer value of the leading characters, interpreted as hexadecimal digits. # - #oct: Returns the integer value of the leading characters, interpreted as octal digits. # - #ord: Returns the integer ordinal of the first character in +self+. +# - #to_c: Returns the complex value of leading characters, interpreted as a complex number. # - #to_i: Returns the integer value of leading characters, interpreted as an integer. # - #to_f: Returns the floating-point value of leading characters, interpreted as a floating-point number. +# - #to_r: Returns the rational value of leading characters, interpreted as a rational. # # <em>Strings and Symbols</em> # |