class String

# File vendor/bundle/ruby/4.0.0/gems/json-2.21.2/lib/json/add/string.rb, line 11
def self.json_create(object)
  object["raw"].pack("C*")
end

Raw Strings are JSON Objects (the raw bytes are stored in an array for the key “raw”). The Ruby String can be created by this class method.

(?string source, ?encoding: encoding, ?capacity: int) → void

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 1039
def initialize: (?string source, ?encoding: encoding, ?capacity: int) -> void

Returns a new String object containing the given string.

The options are optional keyword options (see below).

With no argument given and keyword encoding also not given, returns an empty string with the Encoding ASCII-8BIT:

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

With argument string given and keyword option encoding not given, returns a new string with the same encoding as string:

s0 = 'foo'.encode(Encoding::UTF_16)
s1 = String.new(s0)
s1.encoding # => #<Encoding:UTF-16 (dummy)>

(Unlike String.new, a string literal like '' or a here document literal always has script encoding.)

With keyword option encoding given, returns a string with the specified encoding; the encoding may be an Encoding object, an encoding name, or an encoding name alias:

String.new(encoding: Encoding::US_ASCII).encoding        # => #<Encoding:US-ASCII>
String.new('', encoding: Encoding::US_ASCII).encoding    # => #<Encoding:US-ASCII>
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>

The given encoding need not be valid for the string’s content, and its validity is not checked:

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

But the given encoding itself is checked:

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

With keyword option capacity given, the given value is advisory only, and may or may not set the size of the internal buffer, which may in turn affect performance:

String.new('foo', capacity: 1)    # Buffer size is at least 4 (includes terminal null byte).
String.new('foo', capacity: 4096) # Buffer size is at least 4;
                                  # may be equal to, greater than, or less than 4096.

(String object) → String
(_ToStr object) → String
(untyped object) → String?

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 980
def self.try_convert: (String object) -> String # technically will return `object` unchanged.
                      | (_ToStr object) -> String
                      | (untyped object) -> String?

Attempts to convert the given object to a string.

If object is already a string, returns object, unmodified.

Otherwise if object responds to :to_str, calls object.to_str and returns the result.

Returns nil if object does not respond to :to_str.

Raises an exception unless object.to_str returns a string.

(array[untyped] positional_args) → String
(hash[Symbol, untyped] named_args) → String
(untyped arg) → String

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 1072
def %: (array[untyped] positional_args) -> String
       | (hash[Symbol, untyped] named_args) -> String
       | (untyped arg) -> String

Returns the result of formatting object into the format specifications contained in self (see Format Specifications):

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

If self contains multiple format specifications, object must be an array or hash containing the objects to be formatted:

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

Related: see Converting to New String.

(int amount) → String

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 1088
def *: (int amount) -> String

Returns a new string containing n copies of self:

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

Related: see Converting to New String.

(string other_string) → String

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 1101
def +: (string other_string) -> String

Returns a new string containing other_string concatenated to self:

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

Related: see Converting to New String.

() → self

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 1114
def +@: () -> self

Returns self if self is not frozen and can be mutated without warning issuance.

Otherwise returns self.dup, which is not frozen.

Related: see Freezing/Unfreezing.

() → self

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 1150
def -@: () -> self

Returns a frozen string equal to self.

The returned string is self if and only if all of the following are true:

• self is already frozen.

• self is an instance of String (rather than of a subclass of String)

• self has no instance variables set on it.

Otherwise, the returned string is a frozen copy of self.

Returning self, when possible, saves duplicating self; see Data deduplication.

It may also save duplicating other, already-existing, strings:

s0 = 'foo'
s1 = 'foo'
s0.object_id == s1.object_id       # => false
(-s0).object_id == (-s1).object_id # => true

Note that method -@ is convenient for defining a constant:

FileName = -'config/database.yml'

While its alias dedup is better suited for chaining:

'foo'.dedup.gsub!('o')

Related: see Freezing/Unfreezing.

(string | Integer str_or_codepoint) → self

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 1190
def <<: (string | Integer str_or_codepoint) -> self

Appends a string representation of object to self; returns self.

If object is a string, appends it to self:

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

If object is an integer, its value is considered a codepoint; converts the value to a character before concatenating:

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

Additionally, if the codepoint is in range 0..0xff and the encoding of self is Encoding::US_ASCII, changes the encoding to Encoding::ASCII_8BIT:

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

Raises RangeError if that codepoint is not representable in the encoding of self:

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

Related: see Modifying.

(string) → (-1 | 0 | 1)
(untyped) → (-1 | 0 | 1)?

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 1219
def <=>: (string) -> (-1 | 0 | 1)
         | (untyped) -> (-1 | 0 | 1)?

Compares self and other, evaluating their contents, not their lengths.

Returns:

• -1, if self is smaller.

• 0, if the two are equal.

• 1, if self is larger.

• nil, if the two are incomparable.

Examples:

'a'  <=> 'b'  # => -1
'a'  <=> 'ab' # => -1
'a'  <=> 'a'  # => 0
'b'  <=> 'a'  # => 1
'ab' <=> 'a'  # => 1
'a'  <=> :a   # => nil

Class String includes module Comparable, each of whose methods uses String#<=> for comparison.

Related: see Comparing.

(untyped other) → bool

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 1248
def ==: (untyped other) -> bool

Returns whether object is equal to self.

When object is a string, returns whether object has the same length and content as self:

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

Returns false if the two strings’ encodings are not compatible:

"\u{e4 f6 fc}".encode(Encoding::ISO_8859_1) == ("\u{c4 d6 dc}") # => false

When object is not a string:

• If object responds to method to_str, object == self is called and its return value is returned.

• If object does not respond to to_str, false is returned.

Related: Comparing.

(Regexp regex) → Integer?
[T] (_MatchAgainst[self, T] object) → T

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 1304
def =~: (Regexp regex) -> Integer?
        | [T] (_MatchAgainst[self, T] object) -> T

When object is a Regexp, returns the index of the first substring in self matched by object, or nil if no match is found; updates Regexp-related global variables:

'foo' =~ /f/ # => 0
$~           # => #<MatchData "f">
'foo' =~ /o/ # => 1
$~           # => #<MatchData "o">
'foo' =~ /x/ # => nil
$~           # => nil

Note that string =~ regexp is different from regexp =~ string (see Regexp#=~):

number = nil
'no. 9' =~ /(?<number>\d+)/ # => 4
number                      # => nil # Not assigned.
/(?<number>\d+)/ =~ 'no. 9' # => 4
number                      # => "9" # Assigned.

If object is not a Regexp, returns the value returned by object =~ self.

Related: see Querying.

(int start, ?int length) → String?
(range[int?] range) → String?
(Regexp regexp, ?MatchData::capture backref) → String?
(String substring) → String?

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 1416
def []: (int start, ?int length) -> String?
        | (range[int?] range) -> String?
        | (Regexp regexp, ?MatchData::capture backref) -> String?
        | (String substring) -> String?

Returns the substring of self specified by the arguments.

<strong>Form self[index]</strong>

With non-negative integer argument index given, returns the 1-character substring found in self at character offset index:

'hello'[0]    # => "h"
'hello'[4]    # => "o"
'hello'[5]    # => nil
'Привет'[2]   # => "и"
'こんにちは'[4] # => "は"

With negative integer argument index given, counts backward from the end of self:

'hello'[-1] # => "o"
'hello'[-5] # => "h"
'hello'[-6] # => nil

<strong>Form self[start, length]</strong>

With integer arguments start and length given, returns a substring of size length characters (as available) beginning at character offset specified by start.

If argument start is non-negative, the offset is start:

'hello'[0, 1]  # => "h"
'hello'[0, 5]  # => "hello"
'hello'[0, 6]  # => "hello"
'hello'[2, 3]  # => "llo"
'hello'[2, 0]  # => ""
'hello'[2, -1] # => nil

If argument start is negative, counts backward from the end of self:

'hello'[-1, 1] # => "o"
'hello'[-5, 5] # => "hello"
'hello'[-1, 0] # => ""
'hello'[-6, 5] # => nil

Special case: if start equals the length of self, returns a new empty string:

'hello'[5, 3]  # => ""

<strong>Form self[range]</strong>

With Range argument range given, forms substring self[range.start, range.size]:

'hello'[0..2]  # => "hel"
'hello'[0, 3]  # => "hel"

'hello'[0...2] # => "he"
'hello'[0, 2]  # => "he"

'hello'[0, 0]  # => ""
'hello'[0...0] # => ""

<strong>Form self[regexp, capture = 0]</strong>

With Regexp argument regexp given and capture as zero, searches for a matching substring in self; updates Regexp-related global variables:

'hello'[/ell/]     # => "ell"
'hello'[/l+/]      # => "ll"
'hello'[//]        # => ""
'hello'[/nosuch/]  # => nil

With capture as a positive integer n, returns the +n+th matched group:

'hello'[/(h)(e)(l+)(o)/]    # => "hello"
'hello'[/(h)(e)(l+)(o)/, 1] # => "h"
$1                          # => "h"
'hello'[/(h)(e)(l+)(o)/, 2] # => "e"
$2                          # => "e"
'hello'[/(h)(e)(l+)(o)/, 3] # => "ll"
'hello'[/(h)(e)(l+)(o)/, 4] # => "o"
'hello'[/(h)(e)(l+)(o)/, 5] # => nil

<strong>Form self[substring]</strong>

With string argument substring given, returns the matching substring of self, if found:

'hello'['ell']      # => "ell"
'hello'['']         # => ""
'hello'['nosuch']   # => nil
'Привет'['ив']      # => "ив"
'こんにちは'['んにち'] # => "んにち"

Related: see Converting to New String.

[T < _ToStr] (int index, T replacement) → T
[T < _ToStr] (int start, int length, T replacement) → T
[T < _ToStr] (range[int?] range, T replacement) → T
[T < _ToStr] (Regexp regexp, T replacement) → T
[T < _ToStr] (Regexp regexp, MatchData::capture backref, T replacement) → T
[T < _ToStr] (String substring, T replacement) → T

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 1611
def []=: [T < _ToStr] (int index, T replacement) -> T
         | [T < _ToStr] (int start, int length, T replacement) -> T
         | [T < _ToStr] (range[int?] range, T replacement) -> T
         | [T < _ToStr] (Regexp regexp, T replacement) -> T
         | [T < _ToStr] (Regexp regexp, MatchData::capture backref, T replacement) -> T
         | [T < _ToStr] (String substring, T replacement) -> T

Returns self with all, a substring, or none of its contents replaced; returns the argument other_string.

<strong>Form self[index] = other_string</strong>

With non-negative integer argument index given, searches for the 1-character substring found in self at character offset index:

s = 'hello'
s[0] = 'foo' # => "foo"
s            # => "fooello"

s = 'hello'
s[4] = 'foo' # => "foo"
s            # => "hellfoo"

s = 'hello'
s[5] = 'foo' # => "foo"
s            # => "hellofoo"

s = 'hello'
s[6] = 'foo' # Raises IndexError: index 6 out of string.

With negative integer argument index given, counts backward from the end of self:

s = 'hello'
s[-1] = 'foo'  # => "foo"
s              # => "hellfoo"

s = 'hello'
s[-5] = 'foo'  # => "foo"
s              # => "fooello"

s = 'hello'
s[-6] = 'foo'  # Raises IndexError: index -6 out of string.

<strong>Form self[start, length] = other_string</strong>

With integer arguments start and length given, searches for a substring of size length characters (as available) beginning at character offset specified by start.

If argument start is non-negative, the offset is start:

s = 'hello'
s[0, 1] = 'foo'  # => "foo"
s                # => "fooello"

s = 'hello'
s[0, 5] = 'foo'  # => "foo"
s                # => "foo"

s = 'hello'
s[0, 9] = 'foo'  # => "foo"
s                # => "foo"

s = 'hello'
s[2, 0] = 'foo'  # => "foo"
s                # => "hefoollo"

s = 'hello'
s[2, -1] = 'foo' # Raises IndexError: negative length -1.

If argument start is negative, counts backward from the end of self:

s = 'hello'
s[-1, 1] = 'foo' # => "foo"
s                # => "hellfoo"

s = 'hello'
s[-1, 9] = 'foo' # => "foo"
s                # => "hellfoo"

s = 'hello'
s[-5, 2] = 'foo' # => "foo"
s                # => "foollo"

s = 'hello'
s[-3, 0] = 'foo' # => "foo"
s                # => "hefoollo"

s = 'hello'
s[-6, 2] = 'foo' # Raises IndexError: index -6 out of string.

Special case: if start equals the length of self, the argument is appended to self:

s = 'hello'
s[5, 3] = 'foo' # => "foo"
s               # => "hellofoo"

<strong>Form self[range] = other_string</strong>

With Range argument range given, equivalent to self[range.start, range.size] = other_string:

s0 = 'hello'
s1 = 'hello'
s0[0..2] = 'foo' # => "foo"
s1[0, 3] = 'foo' # => "foo"
s0               # => "foolo"
s1               # => "foolo"

s = 'hello'
s[0...2] = 'foo' # => "foo"
s                # => "foollo"

s = 'hello'
s[0...0] = 'foo' # => "foo"
s                # => "foohello"

s = 'hello'
s[9..10] = 'foo' # Raises RangeError: 9..10 out of range

<strong>Form self[regexp, capture = 0] = other_string</strong>

With Regexp argument regexp given and capture as zero, searches for a matching substring in self; updates Regexp-related global variables:

s = 'hello'
s[/l/] = 'L'       # => "L"
[$`, $&, $']       # => ["he", "l", "lo"]
s[/eLlo/] = 'owdy' # => "owdy"
[$`, $&, $']       # => ["h", "eLlo", ""]
s[/eLlo/] = 'owdy' # Raises IndexError: regexp not matched.
[$`, $&, $']       # => [nil, nil, nil]

With capture as a positive integer n, searches for the +n+th matched group:

s = 'hello'
s[/(h)(e)(l+)(o)/] = 'foo'    # => "foo"
[$`, $&, $']                  # => ["", "hello", ""]

s = 'hello'
s[/(h)(e)(l+)(o)/, 1] = 'foo' # => "foo"
s                             # => "fooello"
[$`, $&, $']                  # => ["", "hello", ""]

s = 'hello'
s[/(h)(e)(l+)(o)/, 2] = 'foo' # => "foo"
s                             # => "hfoollo"
[$`, $&, $']                  # => ["", "hello", ""]

s = 'hello'
s[/(h)(e)(l+)(o)/, 4] = 'foo' # => "foo"
s                             # => "hellfoo"
[$`, $&, $']                  # => ["", "hello", ""]

s = 'hello'
# => "hello"
s[/(h)(e)(l+)(o)/, 5] = 'foo  # Raises IndexError: index 5 out of regexp.

s = 'hello'
s[/nosuch/] = 'foo'           # Raises IndexError: regexp not matched.

<strong>Form self[substring] = other_string</strong>

With string argument substring given:

s = 'hello'
s['l'] = 'foo'  # => "foo"
s  # => "hefoolo"

s = 'hello'
s['ll'] = 'foo'  # => "foo"
s  # => "hefooo"

s = 'Привет'
s['ив'] = 'foo'  # => "foo"
s  # => "Прfooет"

s = 'こんにちは'
s['んにち'] = 'foo'  # => "foo"
s  # => "こfooは"

s['nosuch'] = 'foo' # Raises IndexError: string not matched.

Related: see Modifying.

(*String | Integer) → String

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 1641
def append_as_bytes: (*String | Integer) -> String

Concatenates each object in objects into self; returns self; performs no encoding validation or conversion:

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

When a given object is an integer, the value is considered an 8-bit byte; if the integer occupies more than one byte (i.e,. is greater than 255), appends only the low-order byte (similar to String#setbyte):

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

Related: see Modifying.

() → bool

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 1654
def ascii_only?: () -> bool

Returns whether self contains only ASCII characters:

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

Related: see Querying.

() → String

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 1678
def b: () -> String

Returns a copy of self that has ASCII-8BIT encoding; the underlying bytes are not modified:

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]

Related: see Converting to New String.

(Regexp | string pattern, ?int offset) → Integer?

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 1745
def byteindex: (Regexp | string pattern, ?int offset) -> Integer?

Returns the 0-based integer index of a substring of self specified by object (a string or Regexp) and offset, or nil if there is no such substring; the returned index is the count of bytes (not characters).

When object is a string, returns the index of the first found substring equal to object:

s = 'foo'          # => "foo"
s.size             # => 3 # Three 1-byte characters.
s.bytesize         # => 3 # Three bytes.
s.byteindex('f')   # => 0
s.byteindex('o')   # => 1
s.byteindex('oo')  # => 1
s.byteindex('ooo') # => nil

When object is a Regexp, returns the index of the first found substring matching object; updates Regexp-related global variables:

s = 'foo'
s.byteindex(/f/)   # => 0
$~                 # => #<MatchData "f">
s.byteindex(/o/)   # => 1
s.byteindex(/oo/)  # => 1
s.byteindex(/ooo/) # => nil
$~                 # => nil

Integer argument offset, if given, specifies the 0-based index of the byte where searching is to begin.

When offset is non-negative, searching begins at byte position offset:

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

When offset is negative, counts backward from the end of self:

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

Raises IndexError if the byte at offset is not the first byte of a character:

s = "\uFFFF\uFFFF"       # => "\uFFFF\uFFFF"
s.size                   # => 2 # Two 3-byte characters.
s.bytesize               # => 6 # Six bytes.
s.byteindex("\uFFFF")    # => 0
s.byteindex("\uFFFF", 1) # Raises IndexError
s.byteindex("\uFFFF", 2) # Raises IndexError
s.byteindex("\uFFFF", 3) # => 3
s.byteindex("\uFFFF", 4) # Raises IndexError
s.byteindex("\uFFFF", 5) # Raises IndexError
s.byteindex("\uFFFF", 6) # => nil

Related: see Querying.

(Regexp | string pattern, ?int offset) → Integer?

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 1832
def byterindex: (Regexp | string pattern, ?int offset) -> Integer?

Returns the 0-based integer index of a substring of self that is the last match for the given object (a string or Regexp) and offset, or nil if there is no such substring; the returned index is the count of bytes (not characters).

When object is a string, returns the index of the last found substring equal to object:

s = 'foo'           # => "foo"
s.size              # => 3 # Three 1-byte characters.
s.bytesize          # => 3 # Three bytes.
s.byterindex('f')   # => 0
s.byterindex('o')   # => 2
s.byterindex('oo')  # => 1
s.byterindex('ooo') # => nil

When object is a Regexp, returns the index of the last found substring matching object; updates Regexp-related global variables:

s = 'foo'
s.byterindex(/f/)   # => 0
$~                  # => #<MatchData "f">
s.byterindex(/o/)   # => 2
s.byterindex(/oo/)  # => 1
s.byterindex(/ooo/) # => nil
$~                  # => nil

The last match means starting at the possible last position, not the last of the longest matches:

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

To get the last longest match, use a negative lookbehind:

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

Or use method byteindex with negative lookahead:

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

Integer argument offset, if given, specifies the 0-based index of the byte where searching is to end.

When offset is non-negative, searching ends at byte position offset:

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

When offset is negative, counts backward from the end of self:

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

Raises IndexError if the byte at offset is not the first byte of a character:

s = "\uFFFF\uFFFF"        # => "\uFFFF\uFFFF"
s.size                    # => 2 # Two 3-byte characters.
s.bytesize                # => 6 # Six bytes.
s.byterindex("\uFFFF")    # => 3
s.byterindex("\uFFFF", 1) # Raises IndexError
s.byterindex("\uFFFF", 2) # Raises IndexError
s.byterindex("\uFFFF", 3) # => 3
s.byterindex("\uFFFF", 4) # Raises IndexError
s.byterindex("\uFFFF", 5) # Raises IndexError
s.byterindex("\uFFFF", 6) # => nil

Related: see Querying.

() → Array[Integer]
() { (Integer byte) → void } → self

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 1848
def bytes: () -> Array[Integer]
           | () { (Integer byte) -> void } -> self

Returns an array of the bytes in self:

'hello'.bytes  # => [104, 101, 108, 108, 111]
'Привет'.bytes # => [208, 159, 209, 128, 208, 184, 208, 178, 208, 181, 209, 130]
'こんにちは'.bytes
# => [227, 129, 147, 227, 130, 147, 227, 129, 171, 227, 129, 161, 227, 129, 175]

Related: see Converting to Non-String.

() → Integer

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 1872
def bytesize: () -> Integer

Returns the count of bytes in self.

Note that the byte count may be different from the character count (returned by size):

s = 'foo'
s.bytesize # => 3
s.size     # => 3
s = 'Привет'
s.bytesize # => 12
s.size     # => 6
s = 'こんにちは'
s.bytesize # => 15
s.size     # => 5

Related: see Querying.

(int start, ?int length) → String?
(range[int?] range) → String?

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 1933
def byteslice: (int start, ?int length) -> String?
               | (range[int?] range) -> String?

Returns a substring of self, or nil if the substring cannot be constructed.

With integer arguments offset and length given, returns the substring beginning at the given offset and of the given length (as available):

s = '0123456789'   # => "0123456789"
s.byteslice(2)     # => "2"
s.byteslice(200)   # => nil
s.byteslice(4, 3)  # => "456"
s.byteslice(4, 30) # => "456789"

Returns nil if length is negative or offset falls outside of self:

s.byteslice(4, -1) # => nil
s.byteslice(40, 2) # => nil

Counts backwards from the end of self if offset is negative:

s = '0123456789'   # => "0123456789"
s.byteslice(-4)    # => "6"
s.byteslice(-4, 3) # => "678"

With Range argument range given, returns byteslice(range.begin, range.size):

s = '0123456789'    # => "0123456789"
s.byteslice(4..6)   # => "456"
s.byteslice(-6..-4) # => "456"
s.byteslice(5..2)   # => "" # range.size is zero.
s.byteslice(40..42) # => nil

The starting and ending offsets need not be on character boundaries:

s = 'こんにちは'
s.byteslice(0, 3) # => "こ"
s.byteslice(1, 3) # => "\x81\x93\xE3"

The encodings of self and the returned substring are always the same:

s.encoding                 # => #<Encoding:UTF-8>
s.byteslice(0, 3).encoding # => #<Encoding:UTF-8>
s.byteslice(1, 3).encoding # => #<Encoding:UTF-8>

But, depending on the character boundaries, the encoding of the returned substring may not be valid:

s.valid_encoding?                 # => true
s.byteslice(0, 3).valid_encoding? # => true
s.byteslice(1, 3).valid_encoding? # => false

Related: see Converting to New String.

(Integer start, int length, string str) → String
(int start, int length, string str, int str_start, int str_length) → String
(range[int?] range, string str, ?range[int?] str_range) → String

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 2006
def bytesplice: (Integer start, int length, string str) -> String
                | (int start, int length, string str, int str_start, int str_length) -> String
                | (range[int?] range, string str, ?range[int?] str_range) -> String

Replaces target bytes in self with source bytes from the given string str; returns self.

In the first form, arguments offset and length determine the target bytes, and the source bytes are all of the given str:

'0123456789'.bytesplice(0, 3, 'abc')  # => "abc3456789"
'0123456789'.bytesplice(3, 3, 'abc')  # => "012abc6789"
'0123456789'.bytesplice(0, 50, 'abc') # => "abc"
'0123456789'.bytesplice(50, 3, 'abc') # Raises IndexError.

The counts of the target bytes and source source bytes may be different:

'0123456789'.bytesplice(0, 6, 'abc') # => "abc6789"      # Shorter source.
'0123456789'.bytesplice(0, 1, 'abc') # => "abc123456789" # Shorter target.

And either count may be zero (i.e., specifying an empty string):

'0123456789'.bytesplice(0, 3, '')    # => "3456789"       # Empty source.
'0123456789'.bytesplice(0, 0, 'abc') # => "abc0123456789" # Empty target.

In the second form, just as in the first, arugments offset and length determine the target bytes; argument str contains the source bytes, and the additional arguments str_offset and str_length determine the actual source bytes:

'0123456789'.bytesplice(0, 3, 'abc', 0, 3) # => "abc3456789"
'0123456789'.bytesplice(0, 3, 'abc', 1, 1) # => "b3456789"      # Shorter source.
'0123456789'.bytesplice(0, 1, 'abc', 0, 3) # => "abc123456789"  # Shorter target.
'0123456789'.bytesplice(0, 3, 'abc', 1, 0) # => "3456789"       # Empty source.
'0123456789'.bytesplice(0, 0, 'abc', 0, 3) # => "abc0123456789" # Empty target.

In the third form, argument range determines the target bytes and the source bytes are all of the given str:

'0123456789'.bytesplice(0..2, 'abc')  # => "abc3456789"
'0123456789'.bytesplice(3..5, 'abc')  # => "012abc6789"
'0123456789'.bytesplice(0..5, 'abc')  # => "abc6789"       # Shorter source.
'0123456789'.bytesplice(0..0, 'abc')  # => "abc123456789"  # Shorter target.
'0123456789'.bytesplice(0..2, '')     # => "3456789"       # Empty source.
'0123456789'.bytesplice(0...0, 'abc') # => "abc0123456789" # Empty target.

In the fourth form, just as in the third, arugment range determines the target bytes; argument str contains the source bytes, and the additional argument str_range determines the actual source bytes:

'0123456789'.bytesplice(0..2, 'abc', 0..2)  # => "abc3456789"
'0123456789'.bytesplice(3..5, 'abc', 0..2)  # => "012abc6789"
'0123456789'.bytesplice(0..2, 'abc', 0..1)  # => "ab3456789"     # Shorter source.
'0123456789'.bytesplice(0..1, 'abc', 0..2)  # => "abc23456789"   # Shorter target.
'0123456789'.bytesplice(0..2, 'abc', 0...0) # => "3456789"       # Empty source.
'0123456789'.bytesplice(0...0, 'abc', 0..2) # => "abc0123456789" # Empty target.

In any of the forms, the beginnings and endings of both source and target must be on character boundaries.

In these examples, self has five 3-byte characters, and so has character boundaries at offsets 0, 3, 6, 9, 12, and 15.

'こんにちは'.bytesplice(0, 3, 'abc') # => "abcんにちは"
'こんにちは'.bytesplice(1, 3, 'abc') # Raises IndexError.
'こんにちは'.bytesplice(0, 2, 'abc') # Raises IndexError.

() → String
(:ascii | :lithuanian | :turkic) → String
(:lithuanian, :turkic) → String
(:turkic, :lithuanian) → String

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 2044
def capitalize: () -> String
                | (:ascii | :lithuanian | :turkic) -> String
                | (:lithuanian, :turkic) -> String
                | (:turkic, :lithuanian) -> String

Returns a string containing the characters in self, each with possibly changed case:

• The first character made uppercase.

• All other characters are made lowercase.

Examples:

'hello'.capitalize  # => "Hello"
'HELLO'.capitalize  # => "Hello"
'straße'.capitalize # => "Straße"  # Lowercase 'ß' not changed.
'STRAẞE'.capitalize # => "Straße"  # Uppercase 'ẞ' downcased to 'ß'.
'привет'.capitalize # => "Привет"
'ПРИВЕТ'.capitalize # => "Привет"

Some characters (and some character sets) do not have upcase and downcase versions; see Case Mapping:

s = '1, 2, 3, ...'
s.capitalize == s # => true
s = 'こんにちは'
s.capitalize == s # => true

The casing is affected by the given mapping, which may be :ascii, :fold, or :turkic; see Case Mappings.

Related: see Converting to New String.

() → self?
(:ascii | :lithuanian | :turkic) → self?
(:lithuanian, :turkic) → self?
(:turkic, :lithuanian) → self?

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 2060
def capitalize!: () -> self?
                 | (:ascii | :lithuanian | :turkic) -> self?
                 | (:lithuanian, :turkic) -> self?
                 | (:turkic, :lithuanian) -> self?

Like String#capitalize, except that:

• Changes character casings in self (not in a copy of self).

• Returns self if any changes are made, nil otherwise.

Related: See Modifying.

(string other) → (-1 | 0 | 1)
(untyped) → (-1 | 0 | 1)?

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 2092
def casecmp: (string other) -> (-1 | 0 | 1)
             | (untyped) -> (-1 | 0 | 1)?

Ignoring case, compares self and other_string; returns:

• -1 if self.downcase is smaller than other_string.downcase.

• 0 if the two are equal.

• 1 if self.downcase is larger than other_string.downcase.

• nil if the two are incomparable.

See Case Mapping.

Examples:

'foo'.casecmp('goo')  # => -1
'goo'.casecmp('foo')  # => 1
'foo'.casecmp('food') # => -1
'food'.casecmp('foo') # => 1
'FOO'.casecmp('foo')  # => 0
'foo'.casecmp('FOO')  # => 0
'foo'.casecmp(1)      # => nil

Related: see Comparing.

(string other) → bool
(untyped) → bool?

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 2116
def casecmp?: (string other) -> bool
              | (untyped) -> bool?

Returns true if self and other_string are equal after Unicode case folding, false if unequal, nil if incomparable.

See Case Mapping.

Examples:

'foo'.casecmp?('goo')  # => false
'goo'.casecmp?('foo')  # => false
'foo'.casecmp?('food') # => false
'food'.casecmp?('foo') # => false
'FOO'.casecmp?('foo')  # => true
'foo'.casecmp?('FOO')  # => true
'foo'.casecmp?(1)      # => nil

Related: see Comparing.

(int width, ?string pad_string) → String

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 2146
def center: (int width, ?string pad_string) -> String

Returns a centered copy of self.

If integer argument size is greater than the size (in characters) of self, returns a new string of length size that is a copy of self, centered and padded on one or both ends with pad_string:

'hello'.center(6)             # => "hello "               # Padded on one end.
'hello'.center(10)            # => "  hello   "           # Padded on both ends.
'hello'.center(20, '-|')      # => "-|-|-|-hello-|-|-|-|" # Some padding repeated.
'hello'.center(10, 'abcdefg') # => "abhelloabc"           # Some padding not used.
'  hello  '.center(13)        # => "    hello    "
'Привет'.center(10)           # => "  Привет  "
'こんにちは'.center(10)         # => "  こんにちは   "      # Multi-byte characters.

If size is less than or equal to the size of self, returns an unpadded copy of self:

'hello'.center(5)   # => "hello"
'hello'.center(-10) # => "hello"

Related: see Converting to New String.

() → Array[String]
() { (String char) → void } → self

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 2162
def chars: () -> Array[String]
           | () { (String char) -> void } -> self

Returns an array of the characters in self:

'hello'.chars     # => ["h", "e", "l", "l", "o"]
'Привет'.chars    # => ["П", "р", "и", "в", "е", "т"]
'こんにちは'.chars # => ["こ", "ん", "に", "ち", "は"]
''.chars          # => []

Related: see Converting to Non-String.

(?string? separator) → String

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 2204
def chomp: (?string? separator) -> String

Returns a new string copied from self, with trailing characters possibly removed:

When line_sep is "\n", removes the last one or two characters if they are "\r", "\n", or "\r\n" (but not "\n\r"):

$/                    # => "\n"
"abc\r".chomp         # => "abc"
"abc\n".chomp         # => "abc"
"abc\r\n".chomp       # => "abc"
"abc\n\r".chomp       # => "abc\n"
"тест\r\n".chomp      # => "тест"
"こんにちは\r\n".chomp  # => "こんにちは"

When line_sep is '' (an empty string), removes multiple trailing occurrences of "\n" or "\r\n" (but not "\r" or "\n\r"):

"abc\n\n\n".chomp('')           # => "abc"
"abc\r\n\r\n\r\n".chomp('')     # => "abc"
"abc\n\n\r\n\r\n\n\n".chomp('') # => "abc"
"abc\n\r\n\r\n\r".chomp('')     # => "abc\n\r\n\r\n\r"
"abc\r\r\r".chomp('')           # => "abc\r\r\r"

When line_sep is neither "\n" nor '', removes a single trailing line separator if there is one:

'abcd'.chomp('cd')   # => "ab"
'abcdcd'.chomp('cd') # => "abcd"
'abcd'.chomp('xx')   # => "abcd"

Related: see Converting to New String.

(nil) → nil
(?string? separator) → self?

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 2217
def chomp!: (nil) -> nil
          # | (?string separator) -> self? # https://github.com/ruby/rbs/pull/1672#discussion_r1423324796
            | (?string? separator) -> self?

Like String#chomp, except that:

• Removes trailing characters from self (not from a copy of self).

• Returns self if any characters are removed, nil otherwise.

Related: see Modifying.

() → String

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 2247
def chop: () -> String

Returns a new string copied from self, with trailing characters possibly removed.

Removes "\r\n" if those are the last two characters.

"abc\r\n".chop      # => "abc"
"тест\r\n".chop     # => "тест"
"こんにちは\r\n".chop # => "こんにちは"

Otherwise removes the last character if it exists.

'abcd'.chop     # => "abc"
'тест'.chop     # => "тес"
'こんにちは'.chop # => "こんにち"
''.chop         # => ""

If you only need to remove the newline separator at the end of the string, String#chomp is a better alternative.

Related: see Converting to New String.

() → self?

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 2260
def chop!: () -> self?

Like String#chop, except that:

• Removes trailing characters from self (not from a copy of self).

• Returns self if any characters are removed, nil otherwise.

Related: see Modifying.

() → String

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 2276
def chr: () -> String

Returns a string containing the first character of self:

'hello'.chr     # => "h"
'тест'.chr      # => "т"
'こんにちは'.chr # => "こ"
''.chr          # => ""

Related: see Converting to New String.

() → self

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 2290
def clear: () -> self

Removes the contents of self:

s = 'foo'
s.clear # => ""
s       # => ""

Related: see Modifying.

() → Array[Integer]
() { (Integer codepoint) → void } → self

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 2307
def codepoints: () -> Array[Integer]
                | () { (Integer codepoint) -> void } -> self

Returns an array of the codepoints in self; each codepoint is the integer value for a character:

'hello'.codepoints     # => [104, 101, 108, 108, 111]
'тест'.codepoints      # => [1090, 1077, 1089, 1090]
'こんにちは'.codepoints # => [12371, 12435, 12395, 12385, 12399]
''.codepoints          # => []

Related: see Converting to Non-String.

(*string | Integer string_or_codepoints) → self

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 2328
def concat: (*string | Integer string_or_codepoints) -> self

Concatenates each object in objects to self; returns self:

'foo'.concat('bar', 'baz') # => "foobarbaz"

For each given object object that is an integer, the value is considered a codepoint and converted to a character before concatenation:

'foo'.concat(32, 'bar', 32, 'baz') # => "foo bar baz" # Embeds spaces.
'те'.concat(1089, 1090)            # => "тест"
'こん'.concat(12395, 12385, 12399)  # => "こんにちは"

Related: see Converting to New String.

(selector selector_0, *selector more_selectors) → Integer

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 2416
def count: (selector selector_0, *selector more_selectors) -> Integer

Returns the total number of characters in self that are specified by the given selectors.

For one 1-character selector, returns the count of instances of that character:

s = 'abracadabra'
s.count('a') # => 5
s.count('b') # => 2
s.count('x') # => 0
s.count('')  # => 0

s = 'тест'
s.count('т')  # => 2
s.count('е')  # => 1

s = 'よろしくお願いします'
s.count('よ')  # => 1
s.count('し')  # => 2

For one multi-character selector, returns the count of instances for all specified characters:

s = 'abracadabra'
s.count('ab')     # => 7
s.count('abc')    # => 8
s.count('abcd')   # => 9
s.count('abcdr')  # => 11
s.count('abcdrx') # => 11

Order and repetition do not matter:

s.count('ba')   == s.count('ab') # => true
s.count('baab') == s.count('ab') # => true

For multiple selectors, forms a single selector that is the intersection of characters in all selectors and returns the count of instances for that selector:

s = 'abcdefg'
s.count('abcde', 'dcbfg') == s.count('bcd') # => true
s.count('abc', 'def')     == s.count('')    # => true

In a character selector, three characters get special treatment:

• A caret ('^') functions as a negation operator for the immediately following characters:

  s = 'abracadabra'
  s.count('^bc') # => 8  # Count of all except 'b' and 'c'.
  

• A hyphen ('-') between two other characters defines a range of characters:

  s = 'abracadabra'
  s.count('a-c') # => 8  # Count of all 'a', 'b', and 'c'.
  

• A backslash ('\') acts as an escape for a caret, a hyphen, or another backslash:

  s = 'abracadabra'
  s.count('\^bc')           # => 3  # Count of '^', 'b', and 'c'.
  s.count('a\-c')           # => 6  # Count of 'a', '-', and 'c'.
  'foo\bar\baz'.count('\\') # => 2  # Count of '\'.
  

These usages may be mixed:

s = 'abracadabra'
s.count('a-cq-t') # => 10  # Multiple ranges.
s.count('ac-d')   # => 7   # Range mixed with plain characters.
s.count('^a-c')   # => 3   # Range mixed with negation.

For multiple selectors, all forms may be used, including negations, ranges, and escapes.

s = 'abracadabra'
s.count('^abc', '^def') == s.count('^abcdef') # => true
s.count('a-e', 'c-g')   == s.count('cde')     # => true
s.count('^abc', 'c-g')  == s.count('defg')    # => true

Related: see Querying.

(string salt_str) → String

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 2472
def crypt: (string salt_str) -> String

Returns the string generated by calling crypt(3) standard library function with str and salt_str, in this order, as its arguments. Please do not use this method any longer. It is legacy; provided only for backward compatibility with ruby scripts in earlier days. It is bad to use in contemporary programs for several reasons:

• Behaviour of C's crypt(3) depends on the OS it is run. The generated string lacks data portability.

• On some OSes such as Mac OS, crypt(3) never fails (i.e. silently ends up in unexpected results).

• On some OSes such as Mac OS, crypt(3) is not thread safe.

• So-called "traditional" usage of crypt(3) is very very very weak. According to its manpage, Linux's traditional crypt(3) output has only 2**56 variations; too easy to brute force today. And this is the default behaviour.

• In order to make things robust some OSes implement so-called "modular" usage. To go through, you have to do a complex build-up of the salt_str parameter, by hand. Failure in generation of a proper salt string tends not to yield any errors; typos in parameters are normally not detectable.

  • For instance, in the following example, the second invocation of String#crypt is wrong; it has a typo in "round=" (lacks "s"). However the call does not fail and something unexpected is generated.

    "foo".crypt("$5$rounds=1000$salt$") # OK, proper usage
    "foo".crypt("$5$round=1000$salt$")  # Typo not detected
    

• Even in the "modular" mode, some hash functions are considered archaic and no longer recommended at all; for instance module $1$ is officially abandoned by its author: see phk.freebsd.dk/sagas/md5crypt_eol/ . For another instance module $3$ is considered completely broken: see the manpage of FreeBSD.

• On some OS such as Mac OS, there is no modular mode. Yet, as written above, crypt(3) on Mac OS never fails. This means even if you build up a proper salt string it generates a traditional DES hash anyways, and there is no way for you to be aware of.

  "foo".crypt("$5$rounds=1000$salt$") # => "$5fNPQMxC5j6."
  

If for some reason you cannot migrate to other secure contemporary password hashing algorithms, install the string-crypt gem and require 'string/crypt' to continue using it.

(selector selector_0, *selector more_selectors) → String

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 2594
def delete: (selector selector_0, *selector more_selectors) -> String

Returns a new string that is a copy of self with certain characters removed; the removed characters are all instances of those specified by the given string selectors.

For one 1-character selector, removes all instances of that character:

s = 'abracadabra'
s.delete('a') # => "brcdbr"
s.delete('b') # => "aracadara"
s.delete('x') # => "abracadabra"
s.delete('')  # => "abracadabra"

s = 'тест'
s.delete('т') # => "ес"
s.delete('е') # => "тст"

s = 'よろしくお願いします'
s.delete('よ') # => "ろしくお願いします"
s.delete('し') # => "よろくお願います"

For one multi-character selector, removes all instances of the specified characters:

s = 'abracadabra'
s.delete('ab')     # => "rcdr"
s.delete('abc')    # => "rdr"
s.delete('abcd')   # => "rr"
s.delete('abcdr')  # => ""
s.delete('abcdrx') # => ""

Order and repetition do not matter:

s.delete('ba')   == s.delete('ab') # => true
s.delete('baab') == s.delete('ab') # => true

For multiple selectors, forms a single selector that is the intersection of characters in all selectors and removes all instances of characters specified by that selector:

s = 'abcdefg'
s.delete('abcde', 'dcbfg') == s.delete('bcd') # => true
s.delete('abc', 'def')     == s.delete('')    # => true

In a character selector, three characters get special treatment:

• A caret ('^') functions as a negation operator for the immediately following characters:

  s = 'abracadabra'
  s.delete('^bc') # => "bcb"  # Deletes all except 'b' and 'c'.
  

• A hyphen ('-') between two other characters defines a range of characters:

  s = 'abracadabra'
  s.delete('a-c') # => "rdr"  # Deletes all 'a', 'b', and 'c'.
  

• A backslash ('\') acts as an escape for a caret, a hyphen, or another backslash:

  s = 'abracadabra'
  s.delete('\^bc')           # => "araadara"   # Deletes all '^', 'b', and 'c'.
  s.delete('a\-c')           # => "brdbr"      # Deletes all 'a', '-', and 'c'.
  'foo\bar\baz'.delete('\\') # => "foobarbaz"  # Deletes all '\'.
  

These usages may be mixed:

s = 'abracadabra'
s.delete('a-cq-t') # => "d"         # Multiple ranges.
s.delete('ac-d')   # => "brbr"      # Range mixed with plain characters.
s.delete('^a-c')   # => "abacaaba"  # Range mixed with negation.

For multiple selectors, all forms may be used, including negations, ranges, and escapes.

s = 'abracadabra'
s.delete('^abc', '^def') == s.delete('^abcdef') # => true
s.delete('a-e', 'c-g')   == s.delete('cde')     # => true
s.delete('^abc', 'c-g')  == s.delete('defg')    # => true

Related: see Converting to New String.

(selector selector_0, *selector more_selectors) → self?

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 2605
def delete!: (selector selector_0, *selector more_selectors) -> self?

Like String#delete, but modifies self in place; returns self if any characters were deleted, nil otherwise.

Related: see Modifying.

(string prefix) → String

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 2623
def delete_prefix: (string prefix) -> String

Returns a copy of self with leading substring prefix removed:

'oof'.delete_prefix('o')          # => "of"
'oof'.delete_prefix('oo')         # => "f"
'oof'.delete_prefix('oof')        # => ""
'oof'.delete_prefix('x')          # => "oof"
'тест'.delete_prefix('те')        # => "ст"
'こんにちは'.delete_prefix('こん')  # => "にちは"

Related: see Converting to New String.

(string prefix) → self?

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 2634
def delete_prefix!: (string prefix) -> self?

Like String#delete_prefix, except that self is modified in place; returns self if the prefix is removed, nil otherwise.

Related: see Modifying.

(string suffix) → String

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 2653
def delete_suffix: (string suffix) -> String

Returns a copy of self with trailing substring suffix removed:

'foo'.delete_suffix('o')           # => "fo"
'foo'.delete_suffix('oo')          # => "f"
'foo'.delete_suffix('foo')         # => ""
'foo'.delete_suffix('f')           # => "foo"
'foo'.delete_suffix('x')           # => "foo"
'тест'.delete_suffix('ст')         # => "те"
'こんにちは'.delete_suffix('ちは')  # => "こんに"

Related: see Converting to New String.

(string suffix) → self?

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 2664
def delete_suffix!: (string suffix) -> self?

Like String#delete_suffix, except that self is modified in place; returns self if the suffix is removed, nil otherwise.

Related: see Modifying.

() → String
(:ascii | :fold | :lithuanian | :turkic) → String
(:lithuanian, :turkic) → String
(:turkic, :lithuanian) → String

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 2692
def downcase: () -> String
              | (:ascii | :fold | :lithuanian | :turkic) -> String
              | (:lithuanian, :turkic) -> String
              | (:turkic, :lithuanian) -> String

Returns a new string containing the downcased characters in self:

'HELLO'.downcase        # => "hello"
'STRAẞE'.downcase       # => "straße"
'ПРИВЕТ'.downcase       # => "привет"
'RubyGems.org'.downcase # => "rubygems.org"

Some characters (and some character sets) do not have upcase and downcase versions; see Case Mapping:

s = '1, 2, 3, ...'
s.downcase == s # => true
s = 'こんにちは'
s.downcase == s # => true

The casing is affected by the given mapping, which may be :ascii, :fold, or :turkic; see Case Mappings.

Related: see Converting to New String.

() → self?
(:ascii | :fold | :lithuanian | :turkic) → self?
(:lithuanian, :turkic) → self?
(:turkic, :lithuanian) → self?

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 2708
def downcase!: () -> self?
               | (:ascii | :fold | :lithuanian | :turkic) -> self?
               | (:lithuanian, :turkic) -> self?
               | (:turkic, :lithuanian) -> self?

Like String#downcase, except that:

• Changes character casings in self (not in a copy of self).

• Returns self if any changes are made, nil otherwise.

Related: See Modifying.

() → String

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 2817
def dump: () -> String

For an ordinary string, this method, +String#dump+, returns a printable ASCII-only version of self, enclosed in double-quotes.

For a dumped string, method String#undump is the inverse of +String#dump+; it returns a “restored” version of self, where all the dumping changes have been undone.

In the simplest case, the dumped string contains the original string, enclosed in double-quotes; this example is done in irb (interactive Ruby), which uses method inspect to render the results:

s = 'hello'   # => "hello"
s.dump        # => "\"hello\""
s.dump.undump # => "hello"

Keep in mind that in the second line above:

• The outer double-quotes are put on by inspect, and are not part of the output of dump.

• The inner double-quotes are part of the output of dump, and are escaped by inspect because they are within the outer double-quotes.

To avoid confusion, we’ll use this helper method to omit the outer double-quotes:

def dump(s)
  print "String:   ", s, "\n"
  print "Dumped:   ", s.dump, "\n"
  print "Undumped: ", s.dump.undump, "\n"
end

So that for string 'hello', we’ll see:

String:    hello
Dumped:    "hello"
Undumped:  hello

In a dump, certain special characters are escaped:

String:    "
Dumped:    "\""
Undumped:  "

String:    \
Dumped:    "\\"
Undumped:  \

In a dump, unprintable characters are replaced by printable ones; the unprintable characters are the whitespace characters (other than space itself); here we see the ordinals for those characers, together with explanatory text:

h = {
   7 => 'Alert (BEL)',
   8 => 'Backspace (BS)',
   9 => 'Horizontal tab (HT)',
  10 => 'Linefeed (LF)',
  11 => 'Vertical tab (VT)',
  12 => 'Formfeed (FF)',
  13 => 'Carriage return (CR)'
}

In this example, the dumped output is printed by method inspect, and so contains both outer double-quotes and escaped inner double-quotes:

s = ''
h.keys.each {|i| s << i } # => [7, 8, 9, 10, 11, 12, 13]
s                         # => "\a\b\t\n\v\f\r"
s.dump                    # => "\"\\a\\b\\t\\n\\v\\f\\r\""

If self is encoded in UTF-8 and contains Unicode characters, each Unicode character is dumped as a Unicode escape sequence:

String:    тест
Dumped:    "\u0442\u0435\u0441\u0442"
Undumped:  тест

String:    こんにちは
Dumped:    "\u3053\u3093\u306B\u3061\u306F"
Undumped:  こんにちは

If the encoding of self is not ASCII-compatible (i.e., if self.encoding.ascii_compatible? returns false), each ASCII-compatible byte is dumped as an ASCII character, and all other bytes are dumped as hexadecimal; also appends .dup.force_encoding(\"encoding\"), where <encoding> is self.encoding.name:

String:    hello
Dumped:    "\xFE\xFF\x00h\x00e\x00l\x00l\x00o".dup.force_encoding("UTF-16")
Undumped:  hello

String:    тест
Dumped:    "\xFE\xFF\x04B\x045\x04A\x04B".dup.force_encoding("UTF-16")
Undumped:  тест

String:    こんにちは
Dumped:    "\xFE\xFF0S0\x930k0a0o".dup.force_encoding("UTF-16")
Undumped:  こんにちは

() → Enumerator[Integer, self]
() { (Integer byte) → void } → self

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 2841
def each_byte: () -> Enumerator[Integer, self]
               | () { (Integer byte) -> void } -> self

With a block given, calls the block with each successive byte from self; returns self:

a = []
'hello'.each_byte {|byte| a.push(byte) }     # Five 1-byte characters.
a # => [104, 101, 108, 108, 111]
a = []
'тест'.each_byte {|byte| a.push(byte) }      # Four 2-byte characters.
a # => [209, 130, 208, 181, 209, 129, 209, 130]
a = []
'こんにちは'.each_byte {|byte| a.push(byte) }  # Five 3-byte characters.
a # => [227, 129, 147, 227, 130, 147, 227, 129, 171, 227, 129, 161, 227, 129, 175]

With no block given, returns an enumerator.

Related: see Iterating.

() → Enumerator[String, self]
() { (String char) → void } → self

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 2872
def each_char: () -> Enumerator[String, self]
               | () { (String char) -> void } -> self

With a block given, calls the block with each successive character from self; returns self:

a = []
'hello'.each_char do |char|
  a.push(char)
end
a # => ["h", "e", "l", "l", "o"]
a = []
'тест'.each_char do |char|
  a.push(char)
end
a # => ["т", "е", "с", "т"]
a = []
'こんにちは'.each_char do |char|
  a.push(char)
end
a # => ["こ", "ん", "に", "ち", "は"]

With no block given, returns an enumerator.

Related: see Iterating.

() → Enumerator[Integer, self]
() { (Integer codepoint) → void } → self

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 2904
def each_codepoint: () -> Enumerator[Integer, self]
                    | () { (Integer codepoint) -> void } -> self

With a block given, calls the block with each successive codepoint from self; each codepoint is the integer value for a character; returns self:

a = []
'hello'.each_codepoint do |codepoint|
  a.push(codepoint)
end
a # => [104, 101, 108, 108, 111]
a = []
'тест'.each_codepoint do |codepoint|
  a.push(codepoint)
end
a # => [1090, 1077, 1089, 1090]
a = []
'こんにちは'.each_codepoint do |codepoint|
  a.push(codepoint)
end
a # => [12371, 12435, 12395, 12385, 12399]

With no block given, returns an enumerator.

Related: see Iterating.

() → Enumerator[String, self]
() { (String grapheme_cluter) → void } → self

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 2939
def each_grapheme_cluster: () -> Enumerator[String, self]
                           | () { (String grapheme_cluter) -> void } -> self

With a block given, calls the given block with each successive grapheme cluster from self (see Unicode Grapheme Cluster Boundaries ); returns self:

a = []
'hello'.each_grapheme_cluster do |grapheme_cluster|
  a.push(grapheme_cluster)
end
a  # => ["h", "e", "l", "l", "o"]

a = []
'тест'.each_grapheme_cluster do |grapheme_cluster|
  a.push(grapheme_cluster)
end
a # => ["т", "е", "с", "т"]

a = []
'こんにちは'.each_grapheme_cluster do |grapheme_cluster|
  a.push(grapheme_cluster)
end
a # => ["こ", "ん", "に", "ち", "は"]

With no block given, returns an enumerator.

Related: see Iterating.

(?string? separator, ?chomp: boolish) → Enumerator[String, self]
(?string? separator, ?chomp: boolish) { (String line) → void } → self

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 3012
def each_line: (?string? separator, ?chomp: boolish) -> Enumerator[String, self]
               | (?string? separator, ?chomp: boolish) { (String line) -> void } -> self

With a block given, forms the substrings (lines) that are the result of splitting self at each occurrence of the given record_separator; passes each line to the block; returns self.

With the default record_separator:

$/ # => "\n"
s = <<~EOT
This is the first line.
This is line two.

This is line four.
This is line five.
EOT
s.each_line {|line| p line }

Output:

"This is the first line.\n"
"This is line two.\n"
"\n"
"This is line four.\n"
"This is line five.\n"

With a different record_separator:

record_separator = ' is '
s.each_line(record_separator) {|line| p line }

Output:

"This is "
"the first line.\nThis is "
"line two.\n\nThis is "
"line four.\nThis is "
"line five.\n"

With chomp as true, removes the trailing record_separator from each line:

s.each_line(chomp: true) {|line| p line }

Output:

"This is the first line."
"This is line two."
""
"This is line four."
"This is line five."

With an empty string as record_separator, forms and passes “paragraphs” by splitting at each occurrence of two or more newlines:

record_separator = ''
s.each_line(record_separator) {|line| p line }

Output:

"This is the first line.\nThis is line two.\n\n"
"This is line four.\nThis is line five.\n"

With no block given, returns an enumerator.

Related: see Iterating.

() → bool

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 3027
def empty?: () -> bool

Returns whether the length of self is zero:

'hello'.empty? # => false
' '.empty? # => false
''.empty? # => true

Related: see Querying.

(?encoding source_encoding, ?encoding? from_encoding, ?invalid: :replace ?, ?undef: :replace ?, ?replace: string?, ?xml: (:text | :attr)?, ?newline: (:universal | :crlf | :cr | :lf)?, ?universal_newline: boolish, ?cr_newline: boolish, ?crlf_newline: boolish, ?lf_newline: boolish, ?fallback: ^(String) → string? | Method | _EncodeFallbackAref) → self

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.1.1/core/string.rbs, line 3086
def encode: (
    ?encoding source_encoding,
    ?encoding? from_encoding,
    ?invalid: :replace ?,
    ?undef: :replace ?,
    ?replace: string?,
    ?xml: (:text | :attr)?,
    ?newline: (:universal | :crlf | :cr | :lf)?,
    ?universal_newline: boolish,
    ?cr_newline: boolish,
    ?crlf_newline: boolish,
    ?lf_newline: boolish,
    ?fallback: ^(String) -> string? | Method | _EncodeFallbackAref
  ) -> self

Returns a copy of self transcoded as determined by dst_encoding; see Encodings.

By default, raises an exception if self contains an invalid byte or a character not defined in dst_encoding; that behavior may be modified by encoding options; see below.

With no arguments:

• Uses the same encoding if Encoding.default_internal is nil (the default):

  Encoding.default_internal # => nil
  s = "Ruby\x99".force_encoding('Windows-1252')
  s.encoding                # => #<Encoding:Windows-1252>
  s.bytes                   # => [82, 117, 98, 121, 153]
  t = s.encode              # => "Ruby\x99"
  t.encoding                # => #<Encoding:Windows-1252>
  t.bytes                   # => [82, 117, 98, 121, 226, 132, 162]
  

• Otherwise, uses the encoding Encoding.default_internal:

  Encoding.default_internal = 'UTF-8'
  t = s.encode              # => "Ruby™"
  t.encoding                # => #<Encoding:UTF-8>
  

With only argument dst_encoding given, uses that encoding:

s = "Ruby\x99".force_encoding('Windows-1252')
s.encoding            # => #<Encoding:Windows-1252>
t = s.encode('UTF-8') # => "Ruby™"
t.encoding            # => #<Encoding:UTF-8>

With arguments dst_encoding and src_encoding given, interprets self using src_encoding, encodes the new string using dst_encoding:

s = "Ruby\x99"
t = s.encode('UTF-8', 'Windows-1252') # => "Ruby™"
t.encoding                            # => #<Encoding:UTF-8>

Optional keyword arguments enc_opts specify encoding options; see Encoding Options.

Please note that, unless invalid: :replace option is given, conversion from an encoding enc to the same encoding enc (independent of whether enc is given explicitly or implicitly) is a no-op, i.e. the string is simply copied without any changes, and no exceptions are raised, even if there are invalid bytes.

Related: see Converting to New String.