[DOC] Fix grammar errors, typos, and improve readability of string.rb
Because this file's comments have one extra space after the `#` sign, almost every line is updated. IMO, it's better to address this issue in one go. Co-authored-by: Jeremy Evans <code@jeremyevans.net>
This commit is contained in:
Stan Lo
GitHub
parent
211857f48f
commit
77016a7b43
Notes:
git
2024-12-14 01:19:40 +00:00
Merged: https://github.com/ruby/ruby/pull/12151 Merged-By: jeremyevans <code@jeremyevans.net>
140
string.rb
140
string.rb
@ -17,11 +17,11 @@
|
||||
# Some +String+ methods modify +self+.
|
||||
# Typically, a method whose name ends with <tt>!</tt> modifies +self+
|
||||
# and returns +self+;
|
||||
# often a similarly named method (without the <tt>!</tt>)
|
||||
# often, a similarly named method (without the <tt>!</tt>)
|
||||
# returns a new string.
|
||||
#
|
||||
# In general, if there exist both bang and non-bang version of method,
|
||||
# the bang! mutates and the non-bang! does not.
|
||||
# In general, if both bang and non-bang versions of a method exist,
|
||||
# the bang method mutates and the non-bang method does not.
|
||||
# However, a method without a bang can also mutate, such as String#replace.
|
||||
#
|
||||
# == Substitution Methods
|
||||
@ -37,16 +37,16 @@
|
||||
#
|
||||
# Each of these methods takes:
|
||||
#
|
||||
# - A first argument, +pattern+ (string or regexp),
|
||||
# - A first argument, +pattern+ (String or Regexp),
|
||||
# that specifies the substring(s) to be replaced.
|
||||
#
|
||||
# - Either of these:
|
||||
# - Either of the following:
|
||||
#
|
||||
# - A second argument, +replacement+ (string or hash),
|
||||
# - A second argument, +replacement+ (String or Hash),
|
||||
# that determines the replacing string.
|
||||
# - A block that will determine the replacing string.
|
||||
#
|
||||
# The examples in this section mostly use methods String#sub and String#gsub;
|
||||
# The examples in this section mostly use the String#sub and String#gsub methods;
|
||||
# the principles illustrated apply to all four substitution methods.
|
||||
#
|
||||
# <b>Argument +pattern+</b>
|
||||
@ -62,26 +62,26 @@
|
||||
# 'THX1138'.gsub(/\d+/, '00') # => "THX00"
|
||||
#
|
||||
# When +pattern+ is a string, all its characters are treated
|
||||
# as ordinary characters (not as regexp special characters):
|
||||
# as ordinary characters (not as Regexp special characters):
|
||||
#
|
||||
# 'THX1138'.gsub('\d+', '00') # => "THX1138"
|
||||
#
|
||||
# <b>+String+ +replacement+</b>
|
||||
#
|
||||
# If +replacement+ is a string, that string will determine
|
||||
# the replacing string that is to be substituted for the matched text.
|
||||
# If +replacement+ is a string, that string determines
|
||||
# the replacing string that is substituted for the matched text.
|
||||
#
|
||||
# Each of the examples above uses a simple string as the replacing string.
|
||||
#
|
||||
# +String+ +replacement+ may contain back-references to the pattern's captures:
|
||||
#
|
||||
# - <tt>\n</tt> (_n_ a non-negative integer) refers to <tt>$n</tt>.
|
||||
# - <tt>\n</tt> (_n_ is a non-negative integer) refers to <tt>$n</tt>.
|
||||
# - <tt>\k<name></tt> refers to the named capture +name+.
|
||||
#
|
||||
# See Regexp for details.
|
||||
#
|
||||
# Note that within the string +replacement+, a character combination
|
||||
# such as <tt>$&</tt> is treated as ordinary text, and not as
|
||||
# such as <tt>$&</tt> is treated as ordinary text, not as
|
||||
# a special match variable.
|
||||
# However, you may refer to some special match variables using these
|
||||
# combinations:
|
||||
@ -89,11 +89,11 @@
|
||||
# - <tt>\&</tt> and <tt>\0</tt> correspond to <tt>$&</tt>,
|
||||
# which contains the complete matched text.
|
||||
# - <tt>\'</tt> corresponds to <tt>$'</tt>,
|
||||
# which contains string after match.
|
||||
# which contains the string after the match.
|
||||
# - <tt>\`</tt> corresponds to <tt>$`</tt>,
|
||||
# which contains string before match.
|
||||
# which contains the string before the match.
|
||||
# - <tt>\\+</tt> corresponds to <tt>$+</tt>,
|
||||
# which contains last capture group.
|
||||
# which contains the last capture group.
|
||||
#
|
||||
# See Regexp for details.
|
||||
#
|
||||
@ -108,16 +108,16 @@
|
||||
# <tt>"..\\\\&.."</tt>.
|
||||
#
|
||||
# If you want to write a non-back-reference string <tt>\&</tt> in
|
||||
# +replacement+, you need first to escape the backslash to prevent
|
||||
# +replacement+, you need to first escape the backslash to prevent
|
||||
# this method from interpreting it as a back-reference, and then you
|
||||
# need to escape the backslashes again to prevent a string literal from
|
||||
# consuming them: <tt>"..\\\\\\\\&.."</tt>.
|
||||
#
|
||||
# You may want to use the block form to avoid a lot of backslashes.
|
||||
# You may want to use the block form to avoid excessive backslashes.
|
||||
#
|
||||
# <b>\Hash +replacement+</b>
|
||||
#
|
||||
# If argument +replacement+ is a hash, and +pattern+ matches one of its keys,
|
||||
# If the argument +replacement+ is a hash, and +pattern+ matches one of its keys,
|
||||
# the replacing string is the value for that key:
|
||||
#
|
||||
# h = {'foo' => 'bar', 'baz' => 'bat'}
|
||||
@ -141,7 +141,7 @@
|
||||
#
|
||||
# == Whitespace in Strings
|
||||
#
|
||||
# In class +String+, _whitespace_ is defined as a contiguous sequence of characters
|
||||
# In the class +String+, _whitespace_ is defined as a contiguous sequence of characters
|
||||
# consisting of any mixture of the following:
|
||||
#
|
||||
# - NL (null): <tt>"\x00"</tt>, <tt>"\u0000"</tt>.
|
||||
@ -153,37 +153,37 @@
|
||||
# - SP (space): <tt>"\x20"</tt>, <tt>" "</tt>.
|
||||
#
|
||||
#
|
||||
# Whitespace is relevant for these methods:
|
||||
# Whitespace is relevant for the following methods:
|
||||
#
|
||||
# - #lstrip, #lstrip!: strip leading whitespace.
|
||||
# - #rstrip, #rstrip!: strip trailing whitespace.
|
||||
# - #strip, #strip!: strip leading and trailing whitespace.
|
||||
# - #lstrip, #lstrip!: Strip leading whitespace.
|
||||
# - #rstrip, #rstrip!: Strip trailing whitespace.
|
||||
# - #strip, #strip!: Strip leading and trailing whitespace.
|
||||
#
|
||||
# == +String+ Slices
|
||||
#
|
||||
# A _slice_ of a string is a substring that is selected by certain criteria.
|
||||
# A _slice_ of a string is a substring selected by certain criteria.
|
||||
#
|
||||
# These instance methods make use of slicing:
|
||||
# These instance methods utilize slicing:
|
||||
#
|
||||
# - String#[] (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.
|
||||
# - 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 string +string+, the forms are:
|
||||
# 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>.
|
||||
# - <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,
|
||||
# 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"
|
||||
@ -192,7 +192,7 @@
|
||||
# 'тест'[2] # => "с"
|
||||
# 'こんにちは'[4] # => "は"
|
||||
#
|
||||
# When negative integer +index+ is given,
|
||||
# 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"
|
||||
@ -215,30 +215,30 @@
|
||||
# # Start out of range.
|
||||
# 'foo'[4, 2] # => nil
|
||||
#
|
||||
# Special case: if +start+ is equal to the length of +self+,
|
||||
# Special case: if +start+ equals 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:
|
||||
# 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 negative +length+ is given, there is no slice:
|
||||
# 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 Range argument +range+ is given,
|
||||
# creates a substring of +string+ using the indices in +range+.
|
||||
# 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"
|
||||
@ -277,10 +277,10 @@
|
||||
# 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@Groups+and+Captures):
|
||||
# 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"
|
||||
@ -293,7 +293,7 @@
|
||||
# <b><tt>string[substring]</tt></b>
|
||||
#
|
||||
# When the single +String+ argument +substring+ is given,
|
||||
# returns the substring from +self+ if found, otherwise +nil+:
|
||||
# it returns the substring from +self+ if found, otherwise +nil+:
|
||||
#
|
||||
# 'foo'['oo'] # => "oo"
|
||||
# 'foo'['xx'] # => nil
|
||||
@ -302,8 +302,8 @@
|
||||
#
|
||||
# First, what's elsewhere. \Class +String+:
|
||||
#
|
||||
# - Inherits from {class Object}[rdoc-ref:Object@What-27s+Here].
|
||||
# - Includes {module Comparable}[rdoc-ref:Comparable@What-27s+Here].
|
||||
# - Inherits from the {Object class}[rdoc-ref:Object@What-27s+Here].
|
||||
# - Includes the {Comparable module}[rdoc-ref:Comparable@What-27s+Here].
|
||||
#
|
||||
# Here, class +String+ provides methods that are useful for:
|
||||
#
|
||||
@ -323,11 +323,11 @@
|
||||
#
|
||||
# === Methods for a Frozen/Unfrozen String
|
||||
#
|
||||
# - #+@: Returns a string that is not frozen: +self+, if not frozen;
|
||||
# - #+@: Returns a string that is not frozen: +self+ if not frozen;
|
||||
# +self.dup+ otherwise.
|
||||
# - #-@ (aliased as #dedup): Returns a string that is frozen: +self+, if already frozen;
|
||||
# - #-@ (aliased as #dedup): Returns a string that is frozen: +self+ if already frozen;
|
||||
# +self.freeze+ otherwise.
|
||||
# - #freeze: Freezes +self+, if not already frozen; returns +self+.
|
||||
# - #freeze: Freezes +self+ if not already frozen; returns +self+.
|
||||
#
|
||||
# === Methods for Querying
|
||||
#
|
||||
@ -382,7 +382,7 @@
|
||||
#
|
||||
# _Insertion_
|
||||
#
|
||||
# - #insert: Returns +self+ with a given string inserted at a given offset.
|
||||
# - #insert: Returns +self+ with a given string inserted at a specified offset.
|
||||
# - #<<: Returns +self+ concatenated with a given string or integer.
|
||||
# - #append_as_bytes: Returns +self+ concatenated with strings without performing any
|
||||
# encoding validation or conversion.
|
||||
@ -414,7 +414,7 @@
|
||||
#
|
||||
# _Encoding_
|
||||
#
|
||||
# - #encode!: Returns +self+ with all characters transcoded from one given encoding into another.
|
||||
# - #encode!: Returns +self+ with all characters transcoded from one encoding to another.
|
||||
# - #unicode_normalize!: Unicode-normalizes +self+; returns +self+.
|
||||
# - #scrub!: Replaces each invalid byte with a given character; returns +self+.
|
||||
# - #force_encoding: Changes the encoding to a given encoding; returns +self+.
|
||||
@ -428,7 +428,7 @@
|
||||
# - #lstrip!: Removes leading whitespace; returns +self+ if any changes, +nil+ otherwise.
|
||||
# - #rstrip!: Removes trailing whitespace; returns +self+ if any changes, +nil+ otherwise.
|
||||
# - #strip!: Removes leading and trailing whitespace; returns +self+ if any changes, +nil+ otherwise.
|
||||
# - #chomp!: Removes trailing record separator, if found; returns +self+ if any changes, +nil+ otherwise.
|
||||
# - #chomp!: Removes the trailing record separator, if found; returns +self+ if any changes, +nil+ otherwise.
|
||||
# - #chop!: Removes trailing newline characters if found; otherwise removes the last character;
|
||||
# returns +self+ if any changes, +nil+ otherwise.
|
||||
#
|
||||
@ -439,9 +439,9 @@
|
||||
#
|
||||
# _Extension_
|
||||
#
|
||||
# - #*: Returns the concatenation of multiple copies of +self+,
|
||||
# - #*: Returns the concatenation of multiple copies of +self+.
|
||||
# - #+: Returns the concatenation of +self+ and a given other string.
|
||||
# - #center: Returns a copy of +self+ centered between pad substring.
|
||||
# - #center: Returns a copy of +self+ centered between pad substrings.
|
||||
# - #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.
|
||||
@ -452,16 +452,16 @@
|
||||
# - #b: Returns a copy of +self+ with ASCII-8BIT encoding.
|
||||
# - #scrub: Returns a copy of +self+ with each invalid byte replaced with a given character.
|
||||
# - #unicode_normalize: Returns a copy of +self+ with each character Unicode-normalized.
|
||||
# - #encode: Returns a copy of +self+ with all characters transcoded from one given encoding into another.
|
||||
# - #encode: Returns a copy of +self+ with all characters transcoded from one encoding to another.
|
||||
#
|
||||
# _Substitution_
|
||||
#
|
||||
# - #dump: Returns a copy of +self+ with all non-printing characters replaced by \xHH notation
|
||||
# and all special characters escaped.
|
||||
# - #undump: Returns a copy of +self+ with all <tt>\xNN</tt> notation replace by <tt>\uNNNN</tt> notation
|
||||
# - #undump: Returns a copy of +self+ with all <tt>\xNN</tt> notations replaced by <tt>\uNNNN</tt> notations
|
||||
# and all escaped characters unescaped.
|
||||
# - #sub: Returns a copy of +self+ with the first substring matching a given pattern
|
||||
# replaced with a given replacement string;.
|
||||
# replaced with a given replacement string.
|
||||
# - #gsub: Returns a copy of +self+ with each substring that matches a given pattern
|
||||
# replaced with a given replacement string.
|
||||
# - #succ (aliased as #next): Returns the string that is the successor to +self+.
|
||||
@ -470,7 +470,7 @@
|
||||
# - #tr_s: Returns a copy of +self+ with specified characters replaced with
|
||||
# specified replacement characters,
|
||||
# removing duplicates from the substrings that were modified.
|
||||
# - #%: Returns the string resulting from formatting a given object into +self+
|
||||
# - #%: Returns the string resulting from formatting a given object into +self+.
|
||||
#
|
||||
# _Casing_
|
||||
#
|
||||
@ -483,7 +483,7 @@
|
||||
#
|
||||
# _Deletion_
|
||||
#
|
||||
# - #delete: Returns a copy of +self+ with characters removed
|
||||
# - #delete: Returns a copy of +self+ with characters removed.
|
||||
# - #delete_prefix: Returns a copy of +self+ with a given prefix removed.
|
||||
# - #delete_suffix: Returns a copy of +self+ with a given suffix removed.
|
||||
# - #lstrip: Returns a copy of +self+ with leading whitespace removed.
|
||||
@ -492,7 +492,7 @@
|
||||
# - #chomp: Returns a copy of +self+ with a trailing record separator removed, if found.
|
||||
# - #chop: Returns a copy of +self+ with trailing newline characters or the last character removed.
|
||||
# - #squeeze: Returns a copy of +self+ with contiguous duplicate characters removed.
|
||||
# - #[] (aliased as #slice): Returns a substring determined by a given index, start/length, or range, or string.
|
||||
# - #[] (aliased as #slice): Returns a substring determined by a given index, start/length, range, regexp, or string.
|
||||
# - #byteslice: Returns a substring determined by a given index, start/length, or range.
|
||||
# - #chr: Returns the first character.
|
||||
#
|
||||
@ -510,23 +510,23 @@
|
||||
# - #bytes: Returns an array of the bytes in +self+.
|
||||
# - #chars: Returns an array of the characters in +self+.
|
||||
# - #codepoints: Returns an array of the integer ordinals in +self+.
|
||||
# - #getbyte: Returns an integer byte as determined by a given index.
|
||||
# - #getbyte: Returns the integer byte at the given index in +self+.
|
||||
# - #grapheme_clusters: Returns an array of the grapheme clusters in +self+.
|
||||
#
|
||||
# _Splitting_
|
||||
#
|
||||
# - #lines: Returns an array of the lines in +self+, as determined by a given record separator.
|
||||
# - #partition: Returns a 3-element array determined by the first substring that matches
|
||||
# a given substring or regexp,
|
||||
# a given substring or regexp.
|
||||
# - #rpartition: Returns a 3-element array determined by the last substring that matches
|
||||
# a given substring or regexp,
|
||||
# a given substring or regexp.
|
||||
# - #split: Returns an array of substrings determined by a given delimiter -- regexp or string --
|
||||
# or, if a block given, passes those substrings to the block.
|
||||
# or, if a block is given, passes those substrings to the block.
|
||||
#
|
||||
# _Matching_
|
||||
#
|
||||
# - #scan: Returns an array of substrings matching a given regexp or string, or,
|
||||
# if a block given, passes each matching substring to the block.
|
||||
# if a block is given, passes each matching substring to the block.
|
||||
# - #unpack: Returns an array of substrings extracted from +self+ according to a given format.
|
||||
# - #unpack1: Returns the first substring extracted from +self+ according to a given format.
|
||||
#
|
||||
@ -540,7 +540,7 @@
|
||||
#
|
||||
# <em>Strings and Symbols</em>
|
||||
#
|
||||
# - #inspect: Returns copy of +self+, enclosed in double-quotes, with special characters escaped.
|
||||
# - #inspect: Returns a copy of +self+, enclosed in double quotes, with special characters escaped.
|
||||
# - #intern (aliased as #to_sym): Returns the symbol corresponding to +self+.
|
||||
#
|
||||
# === Methods for Iterating
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user