类 String

一个 String 对象包含任意的字节序列，通常表示文本或二进制数据。可以使用 String::new 或使用字面量来创建 String 对象。

String 对象与 Symbol 对象的不同之处在于，Symbol 对象被设计为用作标识符，而不是文本或数据。

您可以使用以下方式显式创建 String 对象

字符串字面量。
Here 文档字面量。

您可以使用以下方法将某些对象转换为字符串

方法 String。

一些 String 方法会修改 self。通常，名称以 ! 结尾的方法会修改 self 并返回 self；通常，类似命名的方法（不带 !）会返回一个新的字符串。

一般来说，如果一个方法同时存在感叹号版本和非感叹号版本，则感叹号版本会改变原对象，而非感叹号版本不会。但是，没有感叹号的方法也可能会改变原对象，例如 String#replace。

替换方法¶ ↑

这些方法执行替换操作

String#sub：执行一次替换（或不替换）；返回一个新的字符串。
String#sub!：执行一次替换（或不替换）；如果发生任何更改，则返回 self，否则返回 nil。
String#gsub：执行零次或多次替换；返回一个新的字符串。
String#gsub!：执行零次或多次替换；如果发生任何更改，则返回 self，否则返回 nil。

这些方法中的每一个都接受

第一个参数，pattern（String 或 Regexp），指定要替换的子字符串。
以下任意一种
- 第二个参数，replacement（String 或 Hash），确定替换字符串。
- 一个用于确定替换字符串的块。

本节中的示例大多使用 String#sub 和 String#gsub 方法；所说明的原则适用于所有四个替换方法。

参数 pattern

参数 pattern 通常是正则表达式

s = 'hello'
s.sub(/[aeiou]/, '*') # => "h*llo"
s.gsub(/[aeiou]/, '*') # => "h*ll*"
s.gsub(/[aeiou]/, '')  # => "hll"
s.sub(/ell/, 'al')     # => "halo"
s.gsub(/xyzzy/, '*')   # => "hello"
'THX1138'.gsub(/\d+/, '00') # => "THX00"

当 pattern 是字符串时，其所有字符都被视为普通字符（而不是 Regexp 特殊字符）

'THX1138'.gsub('\d+', '00') # => "THX1138"

String replacement

如果 replacement 是一个字符串，则该字符串确定要替换匹配文本的替换字符串。

上面的每个示例都使用一个简单的字符串作为替换字符串。

String replacement 可能包含对模式捕获的反向引用

\n（n 是一个非负整数）引用 $n。
\k<name> 引用名为 name 的命名捕获。

有关详细信息，请参阅 Regexp。

请注意，在字符串 replacement 中，诸如 $& 之类的字符组合被视为普通文本，而不是特殊的匹配变量。但是，您可以使用以下组合引用一些特殊的匹配变量

\& 和 \0 对应于 $&，其中包含完整的匹配文本。
\' 对应于 $'，其中包含匹配后的字符串。
\` 对应于 $`，其中包含匹配前的字符串。
\+ 对应于 $+，其中包含最后一个捕获组。

有关详细信息，请参阅 Regexp。

请注意，\\ 被解释为转义符，即单个反斜杠。

还要注意，字符串字面量会消耗反斜杠。有关字符串字面量的详细信息，请参阅字符串字面量。

反向引用通常以附加的反斜杠开头。例如，如果您想在带有双引号字符串字面量的 replacement 中编写反向引用 \&，则需要编写 "..\\&.."。

如果您想在 replacement 中编写非反向引用字符串 \&，则需要首先转义反斜杠以防止此方法将其解释为反向引用，然后需要再次转义反斜杠以防止字符串字面量消耗它们："..\\\\&.."。

您可能希望使用块形式来避免过多的反斜杠。

哈希 replacement

如果参数 replacement 是一个哈希，并且 pattern 与其键之一匹配，则替换字符串是该键的值

h = {'foo' => 'bar', 'baz' => 'bat'}
'food'.sub('foo', h) # => "bard"

请注意，符号键不匹配

h = {foo: 'bar', baz: 'bat'}
'food'.sub('foo', h) # => "d"

块

在块形式中，当前匹配的字符串将传递给块；块的返回值将成为替换字符串

s = '@'
'1234'.gsub(/\d/) { |match| s.succ! } # => "ABCD"

诸如 $1、$2、$`、$& 和 $' 之类的特殊匹配变量会被适当地设置。

字符串中的空白¶ ↑

在 String 类中，空白被定义为由以下任何混合组成的连续字符序列

NL (null)："\x00", "\u0000"。
HT (水平制表符)："\x09", "\t"。
LF (换行符)："\x0a", "\n"。
VT (垂直制表符)："\x0b", "\v"。
FF (换页符)："\x0c", "\f"。
CR (回车符)："\x0d", "\r"。
SP (空格)："\x20", " "。

空白与以下方法相关

lstrip, lstrip!：删除前导空白。
rstrip, rstrip!：删除尾随空白。
strip, strip!：删除前导和尾随空白。

`String` 切片¶ ↑

字符串的切片是通过某些条件选择的子字符串。

这些实例方法使用切片

String#[]（别名为 String#slice）：返回从 self 复制的切片。
String#[]=：用替换的切片来修改 self。
String#slice!：删除 self 中的切片，并返回删除的切片，从而修改 self。

上述每个方法都接受确定要复制或替换的切片的参数。

参数有多种形式。对于字符串 string，形式为

string[index]
string[start, length]
string[range]
string[regexp, capture = 0]
string[substring]

string[index]

当给定一个非负整数参数 index 时，切片是在字符偏移量 index 处在 self 中找到的 1 个字符的子字符串

'bar'[0]      # => "b"
'bar'[2]      # => "r"
'bar'[20]     # => nil
'тест'[2]     # => "с"
'こんにちは'[4] # => "は"

当给定一个负整数 index 时，切片从通过从 self 的末尾向后计数给定的偏移量处开始

'bar'[-3]      # => "b"
'bar'[-1]      # => "r"
'bar'[-20]     # => nil

string[start, length]

当给定非负整数参数 start 和 length 时，切片从字符偏移量 start 开始（如果存在），并继续 length 个字符（如果可用）

'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

特殊情况：如果 start 等于 self 的长度，则切片是一个新的空字符串

'foo'[3, 2]    # => ""
'foo'[3, 200]  # => ""

当给定负 start 和非负 length 时，切片通过从 self 的末尾向后计数开始，并继续 length 个字符（如果可用）

'foo'[-2, 2]     # => "oo"
'foo'[-2, 200]   # => "oo"
# Start out of range.
'foo'[-4, 2]     # => nil

当给定负 length 时，没有切片

'foo'[1, -1]   # => nil
'foo'[-2, -1]  # => nil

string[range]

当给定 Range 参数 range 时，它会使用 range 中的索引创建一个 string 的子字符串。然后，按照上面的方式确定切片

'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"

string[regexp, capture = 0]

当给定 Regexp 参数 regexp 并且 capture 参数为 0 时，切片是在 self 中找到的第一个匹配的子字符串

'foo'[/o/]                # => "o"
'foo'[/x/]                # => nil
s = 'hello there'
s[/[aeiou](.)\1/]        # => "ell"
s[/[aeiou](.)\1/, 0]     # => "ell"

如果提供了参数 capture 且不为 0，则它应为捕获组索引（整数）或捕获组名称（String 或 Symbol）；切片是指定的捕获（请参阅 Regexp 中的组和捕获）

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"

如果给定了无效的捕获组索引，则没有切片。如果给定了无效的捕获组名称，则会引发 IndexError。

string[substring]

当给定单个 String 参数 substring 时，如果找到该子字符串，则返回 self 中的子字符串，否则返回 nil。

'foo'['oo'] # => "oo"
'foo'['xx'] # => nil

本节内容¶ ↑

首先，看看其他地方的内容。String 类

继承自 Object 类。
包含 Comparable 模块。

在这里，String 类提供了以下有用的方法：

用于创建 `String` 的方法¶ ↑

::new: 返回一个新的字符串。
::try_convert: 返回从给定对象创建的新字符串。

用于冻结/未冻结 `String` 的方法¶ ↑

+@: 返回一个未冻结的字符串：如果 self 未冻结，则返回 self；否则返回 self.dup。
-@ (别名为 dedup): 返回一个已冻结的字符串：如果 self 已经冻结，则返回 self；否则返回 self.freeze。
freeze: 如果 self 尚未冻结，则冻结 self；返回 self。

用于查询的方法¶ ↑

计数

length (别名为 size): 返回字符数（不是字节数）。
empty?: 如果 self.length 为零，则返回 true；否则返回 false。
bytesize: 返回字节数。
count: 返回与给定字符串匹配的子字符串计数。

子字符串

#=~: 返回与给定 Regexp 或其他对象匹配的第一个子字符串的索引；如果未找到匹配项，则返回 nil。
index: 返回给定子字符串首次出现的位置的索引；如果未找到，则返回 nil。
rindex: 返回给定子字符串最后出现的位置的索引；如果未找到，则返回 nil。
include?: 如果字符串包含给定子字符串，则返回 true；否则返回 false。
match: 如果字符串与给定 Regexp 匹配，则返回 MatchData 对象；否则返回 nil。
match?: 如果字符串与给定 Regexp 匹配，则返回 true；否则返回 false。
start_with?: 如果字符串以任何给定的子字符串开头，则返回 true。
end_with?: 如果字符串以任何给定的子字符串结尾，则返回 true。

编码

encoding: 返回表示字符串编码的 Encoding 对象。
unicode_normalized?: 如果字符串为 Unicode 规范化形式，则返回 true；否则返回 false。
valid_encoding?: 如果字符串仅包含对其编码有效的字符，则返回 true。
ascii_only?: 如果字符串仅包含 ASCII 字符，则返回 true；否则返回 false。

其他

sum: 返回字符串的基本校验和：每个字节的总和。
hash: 返回整数哈希码。

用于比较的方法¶ ↑

== (别名为 ===): 如果给定的另一个字符串与 self 具有相同的内容，则返回 true。
eql?: 如果内容与给定的另一个字符串相同，则返回 true。
#<=>: 如果给定的另一个字符串小于、等于或大于 self，则返回 -1、0 或 1。
casecmp: 忽略大小写，如果给定的另一个字符串小于、等于或大于 self，则返回 -1、0 或 1。
casecmp?: 如果字符串在 Unicode 大小写折叠后与给定字符串相等，则返回 true；否则返回 false。

用于修改 `String` 的方法¶ ↑

这些方法中的每一个都会修改 self。

插入

insert: 返回 self，并在指定的偏移量处插入给定字符串。
<<: 返回 self，并与给定字符串或整数连接。
append_as_bytes: 返回 self，并连接字符串，而不执行任何编码验证或转换。

替换

sub!: 将与给定模式匹配的第一个子字符串替换为给定的替换字符串；如果有任何更改，则返回 self，否则返回 nil。
gsub!: 将与给定模式匹配的每个子字符串替换为给定的替换字符串；如果有任何更改，则返回 self，否则返回 nil。
succ! (别名为 next!): 返回 self 修改后的版本，使其成为自己的后继者。
initialize_copy (别名为 replace): 返回 self，其全部内容被给定的字符串替换。
reverse!: 返回 self，其字符顺序颠倒。
setbyte: 将给定整数偏移量处的字节设置为给定值；返回参数。
tr!: 将 self 中指定的字符替换为指定的替换字符；如果有任何更改，则返回 self，否则返回 nil。
tr_s!: 将 self 中指定的字符替换为指定的替换字符，并删除被修改的子字符串中的重复项；如果有任何更改，则返回 self，否则返回 nil。

大小写

capitalize!: 将首字母大写，其余字母小写；如果有任何更改，则返回 self，否则返回 nil。
downcase!: 将所有字符小写；如果有任何更改，则返回 self，否则返回 nil。
upcase!: 将所有字符大写；如果有任何更改，则返回 self，否则返回 nil。
swapcase!: 将每个小写字符大写，将每个大写字符小写；如果有任何更改，则返回 self，否则返回 nil。

编码

encode!: 返回 self，其所有字符都从一个编码转码为另一个编码。
unicode_normalize!: 将 self Unicode 规范化；返回 self。
scrub!: 将每个无效字节替换为给定的字符；返回 self。
force_encoding: 将编码更改为给定的编码；返回 self。

删除

clear: 删除所有内容，使 self 为空；返回 self。
slice!, []=: 删除由给定索引、起始/长度、范围、正则表达式或子字符串确定的子字符串。
squeeze!: 删除连续重复的字符；返回 self。
delete!: 删除由子字符串参数的交集确定的字符。
lstrip!: 删除前导空格；如果有任何更改，则返回 self，否则返回 nil。
rstrip!: 删除尾随空格；如果有任何更改，则返回 self，否则返回 nil。
strip!: 删除前导和尾随空格；如果有任何更改，则返回 self，否则返回 nil。
chomp!: 删除尾随记录分隔符（如果找到）；如果有任何更改，则返回 self，否则返回 nil。
chop!: 删除尾随换行符（如果找到）；否则删除最后一个字符；如果有任何更改，则返回 self，否则返回 nil。

用于转换为新 `String` 的方法¶ ↑

这些方法中的每一个都会基于 self 返回新的 String，通常只是 self 的修改副本。

扩展

*: 返回 self 的多个副本的连接。
+: 返回 self 和给定的另一个字符串的连接。
center: 返回 self 的副本，该副本位于填充子字符串之间居中。
concat: 返回 self 与给定的其他字符串的连接。
prepend: 返回给定的另一个字符串与 self 的连接。
ljust: 返回给定长度的 self 的副本，该副本右侧填充了给定的另一个字符串。
rjust: 返回给定长度的 self 的副本，该副本左侧填充了给定的另一个字符串。

编码

b: 返回编码为 ASCII-8BIT 的 self 的副本。
scrub: 返回 self 的副本，其中每个无效字节都替换为给定的字符。
unicode_normalize: 返回 self 的副本，其中每个字符都经过 Unicode 规范化。
encode: 返回 self 的副本，其中所有字符都从一个编码转码为另一个编码。

替换

dump: 返回 self 的副本，其中所有非打印字符都替换为 xHH 表示法，并且所有特殊字符都已转义。
undump: 返回 self 的副本，其中所有 \xNN 表示法都替换为 \uNNNN 表示法，并且所有转义字符都已取消转义。
sub: 返回一个 self 的副本，其中第一个与给定模式匹配的子字符串被替换为给定的替换字符串。
gsub: 返回一个 self 的副本，其中每个与给定模式匹配的子字符串都被替换为给定的替换字符串。
succ (别名为 next): 返回 self 的后继字符串。
reverse: 返回一个 self 的副本，其中的字符顺序反转。
tr: 返回一个 self 的副本，其中指定的字符被替换为指定的替换字符。
tr_s: 返回一个 self 的副本，其中指定的字符被替换为指定的替换字符，并从修改后的子字符串中删除重复项。
%: 返回将给定对象格式化为 self 后得到的字符串。

大小写

capitalize: 返回一个 self 的副本，其中第一个字符大写，所有其他字符小写。
downcase: 返回一个 self 的副本，其中所有字符都小写。
upcase: 返回一个 self 的副本，其中所有字符都大写。
swapcase: 返回一个 self 的副本，其中所有大写字符都小写，所有小写字符都大写。

删除

delete: 返回一个 self 的副本，其中删除了指定的字符。
delete_prefix: 返回一个 self 的副本，其中删除了给定的前缀。
delete_suffix: 返回一个 self 的副本，其中删除了给定的后缀。
lstrip: 返回一个 self 的副本，其中删除了前导空格。
rstrip: 返回一个 self 的副本，其中删除了尾随空格。
strip: 返回一个 self 的副本，其中删除了前导和尾随空格。
chomp: 返回一个 self 的副本，如果找到尾随的记录分隔符，则将其删除。
chop: 返回一个 self 的副本，其中删除了尾随的换行符或最后一个字符。
squeeze: 返回一个 self 的副本，其中删除了连续的重复字符。
[] (别名为 slice): 返回由给定的索引、起始/长度、范围、正则表达式或字符串确定的子字符串。
byteslice: 返回由给定的索引、起始/长度或范围确定的子字符串。
chr: 返回第一个字符。

复制

to_s (别名为 to_str): 如果 self 是 String 的子类，则返回复制到 String 中的 self；否则，返回 self。

转换为非 `String` 的方法¶ ↑

这些方法中的每一个都将 self 的内容转换为非 String 类型。

字符、字节和群集

bytes: 返回 self 中字节的数组。
chars: 返回 self 中字符的数组。
codepoints: 返回 self 中整数序数的数组。
getbyte: 返回 self 中给定索引处的整数字节。
grapheme_clusters: 返回 self 中字素群集的数组。

分割

lines: 返回 self 中行的数组，由给定的记录分隔符确定。
partition: 返回一个由与给定子字符串或正则表达式匹配的第一个子字符串确定的 3 元素数组。
rpartition: 返回一个由与给定子字符串或正则表达式匹配的最后一个子字符串确定的 3 元素数组。
split: 返回由给定的分隔符（正则表达式或字符串）确定的子字符串数组；或者，如果给定了块，则将这些子字符串传递给该块。

匹配

scan: 返回与给定的正则表达式或字符串匹配的子字符串数组；或者，如果给定了块，则将每个匹配的子字符串传递给该块。
unpack: 返回根据给定格式从 self 中提取的子字符串数组。
unpack1: 返回根据给定格式从 self 中提取的第一个子字符串。

数值

hex: 返回前导字符的整数值，解释为十六进制数字。
oct: 返回前导字符的整数值，解释为八进制数字。
ord: 返回 self 中第一个字符的整数序数。
to_i: 返回前导字符的整数值，解释为整数。
to_f: 返回前导字符的浮点数值，解释为浮点数。

字符串和符号

inspect: 返回一个 self 的副本，用双引号括起来，并转义特殊字符。
intern (别名为 to_sym): 返回与 self 对应的符号。

用于迭代的方法¶ ↑

each_byte: 用 self 中每个连续的字节调用给定的块。
each_char: 用 self 中每个连续的字符调用给定的块。
each_codepoint: 用 self 中每个连续的整数码位调用给定的块。
each_grapheme_cluster: 用 self 中每个连续的字素群集调用给定的块。
each_line: 用 self 中每个连续的行调用给定的块，由给定的记录分隔符确定。
upto: 用连续调用 succ 返回的每个字符串值调用给定的块。

公共类方法

new(string = '', **opts) → new_string 点击以切换源

返回一个新的 String，它是 string 的副本。

如果没有参数，则返回编码为 ASCII-8BIT 的空字符串

s = String.new
s # => ""
s.encoding # => #<Encoding:ASCII-8BIT>

如果使用可选参数 string 且没有关键字参数，则返回具有相同编码的 string 的副本

String.new('foo')               # => "foo"
String.new('тест')              # => "тест"
String.new('こんにちは')          # => "こんにちは"

(与 String.new 不同，像 '' 这样的字符串字面量或 here 文档字面量始终具有脚本编码。)

如果使用可选关键字参数 encoding，则返回具有指定编码的 string 的副本；encoding 可以是 Encoding 对象、编码名称或编码名称别名

String.new('foo', encoding: Encoding::US_ASCII).encoding # => #<Encoding:US-ASCII>
String.new('foo', encoding: 'US-ASCII').encoding         # => #<Encoding:US-ASCII>
String.new('foo', encoding: 'ASCII').encoding            # => #<Encoding:US-ASCII>

给定的编码不必对字符串的内容有效，并且不会检查其有效性

s = String.new('こんにちは', encoding: 'ascii')
s.valid_encoding? # => false

但是会检查给定的 encoding 本身

String.new('foo', encoding: 'bar') # Raises ArgumentError.

如果使用可选关键字参数 capacity，则返回 string 的副本（如果未给出 string，则返回空字符串）；给定的 capacity 仅为建议值，可能设置也可能不设置内部缓冲区的大小，这反过来可能会影响性能

String.new(capacity: 1)
String.new('foo', capacity: 4096)

请注意，Ruby 字符串在内部以 null 结尾，因此内部缓冲区大小将比请求的容量大一个或多个字节，具体取决于编码。

string、encoding 和 capacity 参数可以一起使用

String.new('hello', encoding: 'UTF-8', capacity: 25)

static VALUE
rb_str_init(int argc, VALUE *argv, VALUE str)
{
    static ID keyword_ids[2];
    VALUE orig, opt, venc, vcapa;
    VALUE kwargs[2];
    rb_encoding *enc = 0;
    int n;

    if (!keyword_ids[0]) {
        keyword_ids[0] = rb_id_encoding();
        CONST_ID(keyword_ids[1], "capacity");
    }

    n = rb_scan_args(argc, argv, "01:", &orig, &opt);
    if (!NIL_P(opt)) {
        rb_get_kwargs(opt, keyword_ids, 0, 2, kwargs);
        venc = kwargs[0];
        vcapa = kwargs[1];
        if (!UNDEF_P(venc) && !NIL_P(venc)) {
            enc = rb_to_encoding(venc);
        }
        if (!UNDEF_P(vcapa) && !NIL_P(vcapa)) {
            long capa = NUM2LONG(vcapa);
            long len = 0;
            int termlen = enc ? rb_enc_mbminlen(enc) : 1;

            if (capa < STR_BUF_MIN_SIZE) {
                capa = STR_BUF_MIN_SIZE;
            }
            if (n == 1) {
                StringValue(orig);
                len = RSTRING_LEN(orig);
                if (capa < len) {
                    capa = len;
                }
                if (orig == str) n = 0;
            }
            str_modifiable(str);
            if (STR_EMBED_P(str) || FL_TEST(str, STR_SHARED|STR_NOFREE)) {
                /* make noembed always */
                const size_t size = (size_t)capa + termlen;
                const char *const old_ptr = RSTRING_PTR(str);
                const size_t osize = RSTRING_LEN(str) + TERM_LEN(str);
                char *new_ptr = ALLOC_N(char, size);
                if (STR_EMBED_P(str)) RUBY_ASSERT((long)osize <= str_embed_capa(str));
                memcpy(new_ptr, old_ptr, osize < size ? osize : size);
                FL_UNSET_RAW(str, STR_SHARED|STR_NOFREE);
                RSTRING(str)->as.heap.ptr = new_ptr;
            }
            else if (STR_HEAP_SIZE(str) != (size_t)capa + termlen) {
                SIZED_REALLOC_N(RSTRING(str)->as.heap.ptr, char,
                        (size_t)capa + termlen, STR_HEAP_SIZE(str));
            }
            STR_SET_LEN(str, len);
            TERM_FILL(&RSTRING(str)->as.heap.ptr[len], termlen);
            if (n == 1) {
                memcpy(RSTRING(str)->as.heap.ptr, RSTRING_PTR(orig), len);
                rb_enc_cr_str_exact_copy(str, orig);
            }
            FL_SET(str, STR_NOEMBED);
            RSTRING(str)->as.heap.aux.capa = capa;
        }
        else if (n == 1) {
            rb_str_replace(str, orig);
        }
        if (enc) {
            rb_enc_associate(str, enc);
            ENC_CODERANGE_CLEAR(str);
        }
    }
    else if (n == 1) {
        rb_str_replace(str, orig);
    }
    return str;
}

try_convert(object) → object, new_string, or nil 点击以切换源

如果 object 是一个 String 对象，则返回 object。

否则，如果 object 响应 :to_str，则调用 object.to_str 并返回结果。

如果 object 不响应 :to_str，则返回 nil。

除非 object.to_str 返回 String 对象，否则会引发异常。

static VALUE
rb_str_s_try_convert(VALUE dummy, VALUE str)
{
    return rb_check_string_type(str);
}

公共实例方法

string % object → new_string 点击以切换源

返回将 object 格式化为格式规范 self 的结果（有关格式化详细信息，请参阅 Kernel#sprintf）

"%05d" % 123 # => "00123"

如果 self 包含多个替换项，则 object 必须是包含要替换的值的 Array 或 Hash

"%-5s: %016x" % [ "ID", self.object_id ] # => "ID   : 00002b054ec93168"
"foo = %{foo}" % {foo: 'bar'} # => "foo = bar"
"foo = %{foo}, baz = %{baz}" % {foo: 'bar', baz: 'bat'} # => "foo = bar, baz = bat"

static VALUE
rb_str_format_m(VALUE str, VALUE arg)
{
    VALUE tmp = rb_check_array_type(arg);

    if (!NIL_P(tmp)) {
        return rb_str_format(RARRAY_LENINT(tmp), RARRAY_CONST_PTR(tmp), str);
    }
    return rb_str_format(1, &arg, str);
}

string * integer → new_string 点击以切换源

返回一个新的 String，其中包含 self 的 integer 个副本

"Ho! " * 3 # => "Ho! Ho! Ho! "
"Ho! " * 0 # => ""

VALUE
rb_str_times(VALUE str, VALUE times)
{
    VALUE str2;
    long n, len;
    char *ptr2;
    int termlen;

    if (times == INT2FIX(1)) {
        return str_duplicate(rb_cString, str);
    }
    if (times == INT2FIX(0)) {
        str2 = str_alloc_embed(rb_cString, 0);
        rb_enc_copy(str2, str);
        return str2;
    }
    len = NUM2LONG(times);
    if (len < 0) {
        rb_raise(rb_eArgError, "negative argument");
    }
    if (RSTRING_LEN(str) == 1 && RSTRING_PTR(str)[0] == 0) {
        if (STR_EMBEDDABLE_P(len, 1)) {
            str2 = str_alloc_embed(rb_cString, len + 1);
            memset(RSTRING_PTR(str2), 0, len + 1);
        }
        else {
            str2 = str_alloc_heap(rb_cString);
            RSTRING(str2)->as.heap.aux.capa = len;
            RSTRING(str2)->as.heap.ptr = ZALLOC_N(char, (size_t)len + 1);
        }
        STR_SET_LEN(str2, len);
        rb_enc_copy(str2, str);
        return str2;
    }
    if (len && LONG_MAX/len <  RSTRING_LEN(str)) {
        rb_raise(rb_eArgError, "argument too big");
    }

    len *= RSTRING_LEN(str);
    termlen = TERM_LEN(str);
    str2 = str_enc_new(rb_cString, 0, len, STR_ENC_GET(str));
    ptr2 = RSTRING_PTR(str2);
    if (len) {
        n = RSTRING_LEN(str);
        memcpy(ptr2, RSTRING_PTR(str), n);
        while (n <= len/2) {
            memcpy(ptr2 + n, ptr2, n);
            n *= 2;
        }
        memcpy(ptr2 + n, ptr2, len-n);
    }
    STR_SET_LEN(str2, len);
    TERM_FILL(&ptr2[len], termlen);
    rb_enc_cr_str_copy_for_substr(str2, str);

    return str2;
}

string + other_string → new_string 点击以切换源

返回一个新的 String，其中包含与 self 连接的 other_string

"Hello from " + self.to_s # => "Hello from main"

VALUE
rb_str_plus(VALUE str1, VALUE str2)
{
    VALUE str3;
    rb_encoding *enc;
    char *ptr1, *ptr2, *ptr3;
    long len1, len2;
    int termlen;

    StringValue(str2);
    enc = rb_enc_check_str(str1, str2);
    RSTRING_GETMEM(str1, ptr1, len1);
    RSTRING_GETMEM(str2, ptr2, len2);
    termlen = rb_enc_mbminlen(enc);
    if (len1 > LONG_MAX - len2) {
        rb_raise(rb_eArgError, "string size too big");
    }
    str3 = str_enc_new(rb_cString, 0, len1+len2, enc);
    ptr3 = RSTRING_PTR(str3);
    memcpy(ptr3, ptr1, len1);
    memcpy(ptr3+len1, ptr2, len2);
    TERM_FILL(&ptr3[len1+len2], termlen);

    ENCODING_CODERANGE_SET(str3, rb_enc_to_index(enc),
                           ENC_CODERANGE_AND(ENC_CODERANGE(str1), ENC_CODERANGE(str2)));
    RB_GC_GUARD(str1);
    RB_GC_GUARD(str2);
    return str3;
}

+string → new_string or self 点击以切换源

如果 self 未冻结并且可以在不发出警告的情况下发生突变，则返回 self。

否则，返回未冻结的 self.dup。

static VALUE
str_uplus(VALUE str)
{
    if (OBJ_FROZEN(str) || CHILLED_STRING_P(str)) {
        return rb_str_dup(str);
    }
    else {
        return str;
    }
}

-string → frozen_string 点击以切换源

返回字符串的冻结的、可能预先存在的副本。

只要返回的 String 没有在其上设置任何实例变量并且不是 String 子类，就会对其进行重复数据删除。

请注意，-string 变体更方便用于定义常量

FILENAME = -'config/database.yml'

而 dedup 更适合在计算链中使用该方法

@url_list.concat(urls.map(&:dedup))

static VALUE
str_uminus(VALUE str)
{
    if (!BARE_STRING_P(str) && !rb_obj_frozen_p(str)) {
        str = rb_str_dup(str);
    }
    return rb_fstring(str);
}

也别名为：dedup

string << object → string 点击以切换源

将 object 连接到 self 并返回 self

s = 'foo'
s << 'bar' # => "foobar"
s          # => "foobar"

如果 object 是一个 Integer，则该值被视为代码点，并在连接之前转换为字符

s = 'foo'
s << 33 # => "foo!"

如果该代码点不能以 *string* 的编码表示，则会引发 RangeError。

s = 'foo'
s.encoding              # => <Encoding:UTF-8>
s << 0x00110000         # 1114112 out of char range (RangeError)
s = 'foo'.encode('EUC-JP')
s << 0x00800080         # invalid codepoint 0x800080 in EUC-JP (RangeError)

如果编码为 US-ASCII 且代码点为 0..0xff，则 *string* 会自动提升为 ASCII-8BIT。

s = 'foo'.encode('US-ASCII')
s << 0xff
s.encoding              # => #<Encoding:BINARY (ASCII-8BIT)>

相关：String#concat，它接受多个参数。

VALUE
rb_str_concat(VALUE str1, VALUE str2)
{
    unsigned int code;
    rb_encoding *enc = STR_ENC_GET(str1);
    int encidx;

    if (RB_INTEGER_TYPE_P(str2)) {
        if (rb_num_to_uint(str2, &code) == 0) {
        }
        else if (FIXNUM_P(str2)) {
            rb_raise(rb_eRangeError, "%ld out of char range", FIX2LONG(str2));
        }
        else {
            rb_raise(rb_eRangeError, "bignum out of char range");
        }
    }
    else {
        return rb_str_append(str1, str2);
    }

    encidx = rb_ascii8bit_appendable_encoding_index(enc, code);

    if (encidx >= 0) {
        rb_str_buf_cat_byte(str1, (unsigned char)code);
    }
    else {
        long pos = RSTRING_LEN(str1);
        int cr = ENC_CODERANGE(str1);
        int len;
        char *buf;

        switch (len = rb_enc_codelen(code, enc)) {
          case ONIGERR_INVALID_CODE_POINT_VALUE:
            rb_raise(rb_eRangeError, "invalid codepoint 0x%X in %s", code, rb_enc_name(enc));
            break;
          case ONIGERR_TOO_BIG_WIDE_CHAR_VALUE:
          case 0:
            rb_raise(rb_eRangeError, "%u out of char range", code);
            break;
        }
        buf = ALLOCA_N(char, len + 1);
        rb_enc_mbcput(code, buf, enc);
        if (rb_enc_precise_mbclen(buf, buf + len + 1, enc) != len) {
            rb_raise(rb_eRangeError, "invalid codepoint 0x%X in %s", code, rb_enc_name(enc));
        }
        rb_str_resize(str1, pos+len);
        memcpy(RSTRING_PTR(str1) + pos, buf, len);
        if (cr == ENC_CODERANGE_7BIT && code > 127) {
            cr = ENC_CODERANGE_VALID;
        }
        else if (cr == ENC_CODERANGE_BROKEN) {
            cr = ENC_CODERANGE_UNKNOWN;
        }
        ENC_CODERANGE_SET(str1, cr);
    }
    return str1;
}

string <=> other_string → -1, 0, 1, or nil 点击以切换源

比较 self 和 other_string，返回

如果 other_string 较大，则返回 -1。
如果两者相等，则返回 0。
如果 other_string 较小，则返回 1。
如果两者无法比较，则返回 nil。

示例

'foo' <=> 'foo' # => 0
'foo' <=> 'food' # => -1
'food' <=> 'foo' # => 1
'FOO' <=> 'foo' # => -1
'foo' <=> 'FOO' # => 1
'foo' <=> 1 # => nil

static VALUE
rb_str_cmp_m(VALUE str1, VALUE str2)
{
    int result;
    VALUE s = rb_check_string_type(str2);
    if (NIL_P(s)) {
        return rb_invcmp(str1, str2);
    }
    result = rb_str_cmp(str1, s);
    return INT2FIX(result);
}

string == object → true 或 false 点击切换源代码

如果 object 具有与 self 相同的长度和内容，则返回 true；否则返回 false。

s = 'foo'
s == 'foo' # => true
s == 'food' # => false
s == 'FOO' # => false

如果两个字符串的编码不兼容，则返回 false。

"\u{e4 f6 fc}".encode("ISO-8859-1") == ("\u{c4 d6 dc}") # => false

如果 object 不是 String 的实例，但响应 to_str，则使用 object.== 比较这两个字符串。

VALUE
rb_str_equal(VALUE str1, VALUE str2)
{
    if (str1 == str2) return Qtrue;
    if (!RB_TYPE_P(str2, T_STRING)) {
        if (!rb_respond_to(str2, idTo_str)) {
            return Qfalse;
        }
        return rb_equal(str2, str1);
    }
    return rb_str_eql_internal(str1, str2);
}

也别名为：===

string === object → true 或 false

如果 object 具有与 self 相同的长度和内容，则返回 true；否则返回 false。

s = 'foo'
s == 'foo' # => true
s == 'food' # => false
s == 'FOO' # => false

如果两个字符串的编码不兼容，则返回 false。

"\u{e4 f6 fc}".encode("ISO-8859-1") == ("\u{c4 d6 dc}") # => false

如果 object 不是 String 的实例，但响应 to_str，则使用 object.== 比较这两个字符串。

别名为：==

string =~ regexp → integer 或 nil 点击切换源代码

string =~ object → integer 或 nil

返回与给定 regexp 匹配的第一个子字符串的 Integer 索引，如果未找到匹配项，则返回 nil。

'foo' =~ /f/ # => 0
'foo' =~ /o/ # => 1
'foo' =~ /x/ # => nil

注意：还会更新 Regexp 的全局变量。

如果给定的 object 不是 Regexp，则返回 object =~ self 返回的值。

请注意，string =~ regexp 与 regexp =~ string 不同（请参阅 Regexp#=~）。

number= nil
"no. 9" =~ /(?<number>\d+)/
number # => nil (not assigned)
/(?<number>\d+)/ =~ "no. 9"
number #=> "9"

static VALUE
rb_str_match(VALUE x, VALUE y)
{
    switch (OBJ_BUILTIN_TYPE(y)) {
      case T_STRING:
        rb_raise(rb_eTypeError, "type mismatch: String given");

      case T_REGEXP:
        return rb_reg_match(y, x);

      default:
        return rb_funcall(y, idEqTilde, 1, x);
    }
}

string[index] → new_string 或 nil 点击切换源代码

string[start, length] → new_string 或 nil

string[range] → new_string 或 nil

string[regexp, capture = 0] → new_string 或 nil

string[substring] → new_string 或 nil

返回由参数指定的 self 的子字符串。请参阅字符串切片中的示例。

static VALUE
rb_str_aref_m(int argc, VALUE *argv, VALUE str)
{
    if (argc == 2) {
        if (RB_TYPE_P(argv[0], T_REGEXP)) {
            return rb_str_subpat(str, argv[0], argv[1]);
        }
        else {
            return rb_str_substr_two_fixnums(str, argv[0], argv[1], TRUE);
        }
    }
    rb_check_arity(argc, 1, 2);
    return rb_str_aref(str, argv[0]);
}

也别名为：slice

string[index] = new_string 点击切换源代码

string[start, length] = new_string

string[range] = new_string

string[regexp, capture = 0] = new_string

string[substring] = new_string

替换 self 的全部、部分或没有内容；返回 new_string。请参阅字符串切片。

一些示例

s = 'foo'
s[2] = 'rtune'     # => "rtune"
s                  # => "fortune"
s[1, 5] = 'init'   # => "init"
s                  # => "finite"
s[3..4] = 'al'     # => "al"
s                  # => "finale"
s[/e$/] = 'ly'     # => "ly"
s                  # => "finally"
s['lly'] = 'ncial' # => "ncial"
s                  # => "financial"

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]);
}

append_as_bytes(*objects) → string 点击切换源代码

将 objects 中的每个对象连接到 self 中，不进行任何编码验证或转换，并返回 self。

s = 'foo'
s.append_as_bytes(" \xE2\x82")  # => "foo \xE2\x82"
s.valid_encoding?               # => false
s.append_as_bytes("\xAC 12")
s.valid_encoding?               # => true

对于每个给定的对象 object，如果它是 Integer，则该值被视为一个字节。如果 Integer 大于一个字节，则只考虑低位字节，类似于 String#setbyte。

s = ""
s.append_as_bytes(0, 257)             # =>  "\u0000\u0001"

相关：String#<<，String#concat，它们进行编码感知连接。

VALUE
rb_str_append_as_bytes(int argc, VALUE *argv, VALUE str)
{
    long needed_capacity = 0;
    volatile VALUE t0;
    enum ruby_value_type *types = ALLOCV_N(enum ruby_value_type, t0, argc);

    for (int index = 0; index < argc; index++) {
        VALUE obj = argv[index];
        enum ruby_value_type type = types[index] = rb_type(obj);
        switch (type) {
          case T_FIXNUM:
          case T_BIGNUM:
            needed_capacity++;
            break;
          case T_STRING:
            needed_capacity += RSTRING_LEN(obj);
            break;
          default:
            rb_raise(
                rb_eTypeError,
                "wrong argument type %"PRIsVALUE" (expected String or Integer)",
                rb_obj_class(obj)
            );
            break;
        }
    }

    str_ensure_available_capa(str, needed_capacity);
    char *sptr = RSTRING_END(str);

    for (int index = 0; index < argc; index++) {
        VALUE obj = argv[index];
        enum ruby_value_type type = types[index];
        switch (type) {
          case T_FIXNUM:
          case T_BIGNUM: {
            argv[index] = obj = rb_int_and(obj, INT2FIX(0xff));
            char byte = (char)(NUM2INT(obj) & 0xFF);
            *sptr = byte;
            sptr++;
            break;
          }
          case T_STRING: {
            const char *ptr;
            long len;
            RSTRING_GETMEM(obj, ptr, len);
            memcpy(sptr, ptr, len);
            sptr += len;
            break;
          }
          default:
            rb_bug("append_as_bytes arguments should have been validated");
        }
    }

    STR_SET_LEN(str, RSTRING_LEN(str) + needed_capacity);
    TERM_FILL(sptr, TERM_LEN(str)); /* sentinel */

    int cr = ENC_CODERANGE(str);
    switch (cr) {
      case ENC_CODERANGE_7BIT: {
        for (int index = 0; index < argc; index++) {
            VALUE obj = argv[index];
            enum ruby_value_type type = types[index];
            switch (type) {
              case T_FIXNUM:
              case T_BIGNUM: {
                if (!ISASCII(NUM2INT(obj))) {
                    goto clear_cr;
                }
                break;
              }
              case T_STRING: {
                if (ENC_CODERANGE(obj) != ENC_CODERANGE_7BIT) {
                    goto clear_cr;
                }
                break;
              }
              default:
                rb_bug("append_as_bytes arguments should have been validated");
            }
        }
        break;
      }
      case ENC_CODERANGE_VALID:
        if (ENCODING_GET_INLINED(str) == ENCINDEX_ASCII_8BIT) {
            goto keep_cr;
        }
        else {
            goto clear_cr;
        }
        break;
      default:
        goto clear_cr;
        break;
    }

    RB_GC_GUARD(t0);

  clear_cr:
    // If no fast path was hit, we clear the coderange.
    // append_as_bytes is predominently meant to be used in
    // buffering situation, hence it's likely the coderange
    // will never be scanned, so it's not worth spending time
    // precomputing the coderange except for simple and common
    // situations.
    ENC_CODERANGE_CLEAR(str);
  keep_cr:
    return str;
}

ascii_only? → true 或 false 点击切换源代码

如果 self 仅包含 ASCII 字符，则返回 true，否则返回 false。

'abc'.ascii_only?         # => true
"abc\u{6666}".ascii_only? # => false

static VALUE
rb_str_is_ascii_only_p(VALUE str)
{
    int cr = rb_enc_str_coderange(str);

    return RBOOL(cr == ENC_CODERANGE_7BIT);
}

b → string 点击切换源代码

返回一个 self 的副本，该副本具有 ASCII-8BIT 编码；底层字节不会被修改。

s = "\x99"
s.encoding   # => #<Encoding:UTF-8>
t = s.b      # => "\x99"
t.encoding   # => #<Encoding:ASCII-8BIT>

s = "\u4095" # => "䂕"
s.encoding   # => #<Encoding:UTF-8>
s.bytes      # => [228, 130, 149]
t = s.b      # => "\xE4\x82\x95"
t.encoding   # => #<Encoding:ASCII-8BIT>
t.bytes      # => [228, 130, 149]

static VALUE
rb_str_b(VALUE str)
{
    VALUE str2;
    if (STR_EMBED_P(str)) {
        str2 = str_alloc_embed(rb_cString, RSTRING_LEN(str) + TERM_LEN(str));
    }
    else {
        str2 = str_alloc_heap(rb_cString);
    }
    str_replace_shared_without_enc(str2, str);

    if (rb_enc_asciicompat(STR_ENC_GET(str))) {
        // BINARY strings can never be broken; they're either 7-bit ASCII or VALID.
        // If we know the receiver's code range then we know the result's code range.
        int cr = ENC_CODERANGE(str);
        switch (cr) {
          case ENC_CODERANGE_7BIT:
            ENC_CODERANGE_SET(str2, ENC_CODERANGE_7BIT);
            break;
          case ENC_CODERANGE_BROKEN:
          case ENC_CODERANGE_VALID:
            ENC_CODERANGE_SET(str2, ENC_CODERANGE_VALID);
            break;
          default:
            ENC_CODERANGE_CLEAR(str2);
            break;
        }
    }

    return str2;
}

byteindex(substring, offset = 0) → integer 或 nil 点击切换源代码

byteindex(regexp, offset = 0) → integer 或 nil

返回给定 substring 的第一个出现的基于字节的 Integer 索引，如果未找到，则返回 nil。

'foo'.byteindex('f') # => 0
'foo'.byteindex('o') # => 1
'foo'.byteindex('oo') # => 1
'foo'.byteindex('ooo') # => nil

返回给定 Regexp regexp 的第一个匹配项的基于字节的 Integer 索引，如果未找到，则返回 nil。

'foo'.byteindex(/f/) # => 0
'foo'.byteindex(/o/) # => 1
'foo'.byteindex(/oo/) # => 1
'foo'.byteindex(/ooo/) # => nil

如果给定了 Integer 参数 offset，则它指定字符串中开始搜索的基于字节的位置。

'foo'.byteindex('o', 1) # => 1
'foo'.byteindex('o', 2) # => 2
'foo'.byteindex('o', 3) # => nil

如果 offset 为负数，则从 self 的末尾向后计数。

'foo'.byteindex('o', -1) # => 2
'foo'.byteindex('o', -2) # => 1
'foo'.byteindex('o', -3) # => 1
'foo'.byteindex('o', -4) # => nil

如果 offset 没有落在字符（代码点）边界上，则会引发 IndexError。

相关：String#index，String#byterindex。

static VALUE
rb_str_byteindex_m(int argc, VALUE *argv, VALUE str)
{
    VALUE sub;
    VALUE initpos;
    long pos;

    if (rb_scan_args(argc, argv, "11", &sub, &initpos) == 2) {
        long slen = RSTRING_LEN(str);
        pos = NUM2LONG(initpos);
        if (pos < 0 ? (pos += slen) < 0 : pos > slen) {
            if (RB_TYPE_P(sub, T_REGEXP)) {
                rb_backref_set(Qnil);
            }
            return Qnil;
        }
    }
    else {
        pos = 0;
    }

    str_ensure_byte_pos(str, pos);

    if (RB_TYPE_P(sub, T_REGEXP)) {
        if (rb_reg_search(sub, str, pos, 0) >= 0) {
            VALUE match = rb_backref_get();
            struct re_registers *regs = RMATCH_REGS(match);
            pos = BEG(0);
            return LONG2NUM(pos);
        }
    }
    else {
        StringValue(sub);
        pos = rb_str_byteindex(str, sub, pos);
        if (pos >= 0) return LONG2NUM(pos);
    }
    return Qnil;
}

byterindex(substring, offset = self.bytesize) → integer 或 nil 点击切换源代码

byterindex(regexp, offset = self.bytesize) → integer 或 nil

返回给定 substring 的 _最后_ 一次出现的基于字节的 Integer 索引，如果未找到，则返回 nil。

'foo'.byterindex('f') # => 0
'foo'.byterindex('o') # => 2
'foo'.byterindex('oo') # => 1
'foo'.byterindex('ooo') # => nil

返回给定 Regexp regexp 的 _最后_ 一次匹配项的基于字节的 Integer 索引，如果未找到，则返回 nil。

'foo'.byterindex(/f/) # => 0
'foo'.byterindex(/o/) # => 2
'foo'.byterindex(/oo/) # => 1
'foo'.byterindex(/ooo/) # => nil

_最后_ 一次匹配是指从可能的最后位置开始，而不是最长的匹配项的最后一次。

'foo'.byterindex(/o+/) # => 2
$~ #=> #<MatchData "o">

要获得最长的最后一次匹配，需要与负向后查找结合使用。

'foo'.byterindex(/(?<!o)o+/) # => 1
$~ #=> #<MatchData "oo">

或者使用 String#byteindex 和负向前查找。

'foo'.byteindex(/o+(?!.*o)/) # => 1
$~ #=> #<MatchData "oo">

如果给定且非负，Integer 参数 offset 指定字符串中 _结束_ 搜索的最大起始基于字节的位置。

'foo'.byterindex('o', 0) # => nil
'foo'.byterindex('o', 1) # => 1
'foo'.byterindex('o', 2) # => 2
'foo'.byterindex('o', 3) # => 2

如果 offset 是一个负数 Integer，则字符串中 _结束_ 搜索的最大起始位置是字符串的长度与 offset 的和。

'foo'.byterindex('o', -1) # => 2
'foo'.byterindex('o', -2) # => 1
'foo'.byterindex('o', -3) # => nil
'foo'.byterindex('o', -4) # => nil