class String

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

String 对象与 Symbol 对象不同，Symbol 对象旨在用作标识符，而不是文本或数据。

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

字符串字面量。
heredoc 字面量。

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

方法 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。

用于查询的方法¶ ↑

计数

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: 返回一个使用 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。

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

这些方法中的每一个都将 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 点击切换源代码

返回一个新的字符串，它是 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 点击切换源代码

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

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

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

除非 `object.to_str` 返回一个字符串对象，否则会引发异常。

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

返回一个新的字符串，其中包含 `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 点击切换源代码

返回一个新的字符串，其中包含 `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 点击切换源代码

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

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

只要返回的字符串没有设置任何实例变量，并且不是 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#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;
        ENC_CODERANGE_SET(str1, cr);
    }
    return str1;
}

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

比较 `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 或 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 {
            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 点击切换源代码

返回 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 or nil 点击切换源代码

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 的第一个匹配的字节索引，如果未找到，则返回 nil

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

如果给定 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 点击切换源代码

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 的最后一个匹配的字节索引，如果未找到，则返回 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">

如果给定 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 为负数，则字符串中结束搜索的最大起始位置为字符串长度与 offset 的和

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