class String

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

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

您可以使用以下方法显式创建字符串对象：

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

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

方法 String。

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

一般来说，如果存在 bang 和非 bang 版本的方法，bang! 会修改，非 bang! 不会。但是，没有 bang 的方法也可以修改，例如 String#replace。

替换方法¶ ↑

这些方法执行替换

String#sub: 一次替换（或不替换）；返回一个新的字符串。
String#sub!: 一次替换（或不替换）；返回 self。
String#gsub: 零次或多次替换；返回一个新的字符串。
String#gsub!: 零次或多次替换；返回 self。

这些方法中的每一个都接受以下参数：

第一个参数 pattern（字符串或正则表达式），指定要替换的子字符串。
以下任一参数：
- 第二个参数 replacement（字符串或哈希），确定替换字符串。
- 一个将确定替换字符串的代码块。

本节中的示例主要使用 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 是一个字符串时，它的所有字符都被视为普通字符（而不是正则表达式特殊字符）

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

字符串 replacement

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

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

字符串 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（空字符）："\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#slice）返回从 self 复制的切片。
String#[]= 返回 self 的副本，其中切片被替换。
String#slice! 返回 self，其中切片被移除。

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

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

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

string[index]

当给出非负整数参数 index 时，切片是在 self 中字符偏移量为 index 的位置找到的 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，则它应该是一个捕获组索引（整数）或一个捕获组名称（字符串或符号）；切片是指定的捕获（参见 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 类提供了对以下内容有用的方法：

创建字符串的方法¶ ↑

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

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

+@: 返回一个未冻结的字符串：如果未冻结，则为 self；否则为 self.dup。
-@: 返回一个冻结的字符串：如果已冻结，则为 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。

修改字符串的方法¶ ↑

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

插入

insert: 返回在给定偏移量处插入给定字符串的self。
<<: 返回self与给定字符串或整数连接的结果。

替换

sub!: 用给定的替换字符串替换与给定模式匹配的第一个子字符串；如果进行了任何更改，则返回self，否则返回nil。
gsub!: 用给定的替换字符串替换与给定模式匹配的每个子字符串；如果进行了任何更改，则返回self，否则返回nil。
succ!, next!: 返回修改后的self，使其成为自己的后继。
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。

转换为新字符串的方法¶ ↑

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

扩展

*: 返回self的多个副本的串联。
+: 返回self与给定其他字符串的串联。
center: 返回self的副本，在填充子字符串之间居中。
concat: 返回self与给定其他字符串的串联。
prepend: 返回给定其他字符串与self的串联。
ljust: 返回self的副本，长度为给定长度，右侧填充给定其他字符串。
rjust: 返回self的副本，长度为给定长度，左侧填充给定其他字符串。

编码

b: 返回self的副本，使用 ASCII-8BIT 编码。
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。

转换为非字符串的方法¶ ↑

这些方法中的每一个都将 self 的内容转换为非字符串。

字符、字节和集群

bytes: 返回 self 中字节的数组。
chars: 返回一个包含self中所有字符的数组。
codepoints: 返回一个包含self中所有整数序数值的数组。
getbyte: 返回由给定索引确定的整数字节。
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的副本，用双引号括起来，并对特殊字符进行转义。
to_sym, intern: 返回与self对应的符号。

用于迭代的方法¶ ↑

each_byte: 使用self中的每个连续字节调用给定的块。
each_char: 使用self中的每个连续字符调用给定的块。
each_codepoint: 使用self中的每个连续整数代码点调用给定的块。
each_grapheme_cluster: 对 self 中的每个连续的字形簇调用给定的代码块。
each_line: 对 self 中的每个连续行调用给定的代码块，由给定的记录分隔符确定。
upto: 对由连续调用 succ 返回的每个字符串值调用给定的代码块。

公共类方法

new(string = '', **opts) → new_string click to toggle source

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

如果没有参数，则返回具有 Encoding ASCII-8BIT 的空字符串。

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

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

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

(与 String.new 不同，字符串字面量（如 ''）或这里文档字面量始终具有脚本编码。)

如果有一个可选的关键字参数 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)

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)) { /* make noembed always */
                char *new_ptr = ALLOC_N(char, (size_t)capa + termlen);
                assert(RSTRING_LEN(str) + 1 <= str_embed_capa(str));
                memcpy(new_ptr, RSTRING(str)->as.embed.ary, RSTRING_LEN(str) + 1);
                RSTRING(str)->as.heap.ptr = new_ptr;
            }
            else if (FL_TEST(str, STR_SHARED|STR_NOFREE)) {
                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_t)capa + termlen);
                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 click to toggle source

如果 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 click to toggle source

返回将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 click to toggle source

返回一个新的字符串，其中包含integer个self的副本。

"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_new0(rb_cString, 0, len, termlen);
    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 click to toggle source

返回一个新的字符串，其中包含other_string连接到self。

"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_new0(rb_cString, 0, len1+len2, termlen);
    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 click to toggle source

如果self未冻结，则返回self。

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

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

-string → frozen_string click to toggle source

返回字符串的冻结副本，该副本可能已存在。

只要返回的字符串没有设置任何实例变量，并且不是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 click to toggle source

将object连接到self并返回self。

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

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

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

相关：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) {
        char buf[1];
        buf[0] = (char)code;
        rb_str_cat(str1, buf, 1);
        if (encidx != rb_enc_to_index(enc)) {
            rb_enc_associate_index(str1, encidx);
            ENC_CODERANGE_SET(str1, ENC_CODERANGE_VALID);
        }
    }
    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 click to toggle source

比较self和other_string，返回

-1 如果other_string更大。
0 如果两者相等。
1 如果other_string更小。
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 or false click to toggle source

如果 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 {
            long beg = NUM2LONG(argv[0]);
            long len = NUM2LONG(argv[1]);
            return rb_str_substr(str, beg, len);
        }
    }
    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]);
}

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 点击切换源代码

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

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 or nil click to toggle source

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

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

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

返回给定 Regexp regexp 的第一个匹配项的基于字节的索引，如果未找到则返回 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 or nil click to toggle source

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

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

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

返回给定 Regexp regexp 的最后一次匹配的基于字节的索引，如果未找到则返回 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 且为非负数，则指定字符串中开始搜索的最大基于字节的位置

string to _end_ the search:

 '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