Class: String

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.

Returns whether the length of self is zero:

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

Related: see Querying.

Returns true if self is encoded correctly, false otherwise:

"\xc2\xa1".force_encoding(Encoding::UTF_8).valid_encoding? # => true
"\xc2".force_encoding(Encoding::UTF_8).valid_encoding?     # => false
"\x80".force_encoding(Encoding::UTF_8).valid_encoding?     # => false

Returns a new string containing n copies of self:

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

Related: see Converting to New 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.

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.

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.

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.

Compares self and other_string, returning:

• -1 if other_string is larger.

• 0 if the two are equal.

• 1 if other_string is smaller.

• nil if the two are incomparable.

Examples:

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

Related: see Comparing.

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.

Alias for #==.

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.

Returns the substring of self specified by the arguments. See examples at String Slices.

Related: see Converting to New String.

Replaces all, some, or none of the contents of self; returns new_string. See String Slices.

A few examples:

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"

Related: see Modifying.

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 #setbyte):

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

Related: see Modifying.

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.

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.

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.

Returns an array of the bytes in self:

'hello'.bytes # => [104, 101, 108, 108, 111]
'тест'.bytes  # => [209, 130, 208, 181, 209, 129, 209, 130]
'こんにちは'.bytes
# => [227, 129, 147, 227, 130, 147, 227, 129, 171, 227, 129, 161, 227, 129, 175]

Related: see Converting to Non-String.

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 # => 8
s.size     # => 4
s = 'こんにちは'
s.bytesize # => 15
s.size     # => 5

Related: see Querying.

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.

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.

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

• The first character is upcased.

• All other characters are downcased.

Examples:

'hello world'.capitalize # => "Hello world"
'HELLO WORLD'.capitalize # => "Hello world"

Some characters do not have upcase and downcase, and so are not changed; see Case Mapping:

'1, 2, 3, ...'.capitalize # => "1, 2, 3, ..."

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

Related: see Converting to New String.

Like #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.

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.

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.

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.

Returns an array of the characters in self:

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

Related: see Converting to Non-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.

Like #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.

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, #chomp is a better alternative.

Related: see Converting to New String.

Like #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.

Returns a string containing the first character of self:

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

Related: see Converting to New String.

Removes the contents of self:

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

Related: see Modifying.

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.

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.

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.

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 <code>$3$</code> 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.

Alias for #-@.

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.

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

Related: see Modifying.

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.

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

Related: see Modifying.

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.

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

Related: see Modifying.

Returns a new string containing the downcased characters in self:

'Hello, World!'.downcase      # => "hello, world!"
'ТЕСТ'.downcase               # => "тест"
'よろしくお願いします'.downcase # => "よろしくお願いします"

Some characters do not have upcased and downcased versions.

The casing may be affected by the given mapping; see Case Mapping.

Related: see Converting to New String.

Like #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.

Returns a printable version of self, enclosed in double-quotes:

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

Certain special characters are rendered with escapes:

'"'.dump  # => "\"\\\"\""
'\\'.dump # => "\"\\\\\""

Non-printing characters are rendered with escapes:

s = ''
s << 7   # Alarm (bell).
s << 8   # Back space.
s << 9   # Horizontal tab.
s << 10  # Line feed.
s << 11  # Vertical tab.
s << 12  # Form feed.
s << 13  # Carriage return.
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, renders Unicode characters in Unicode escape sequence:

'тест'.dump     # => "\"\\u0442\\u0435\\u0441\\u0442\""
'こんにちは'.dump # => "\"\\u3053\\u3093\\u306B\\u3061\\u306F\""

If the encoding of self is not ASCII-compatible (i.e., self.encoding.ascii_compatible? returns false), renders all ASCII-compatible bytes as ASCII characters and all other bytes as hexadecimal. Appends .dup.force_encoding(\"encoding\"), where <encoding> is self.encoding.name:

s = 'hello'
s.encoding                # => #<Encoding:UTF-8>
s.dump                    # => "\"hello\""
s.encode('utf-16').dump   # => "\"\\xFE\\xFF\\x00h\\x00e\\x00l\\x00l\\x00o\".dup.force_encoding(\"UTF-16\")"
s.encode('utf-16le').dump # => "\"h\\x00e\\x00l\\x00l\\x00o\\x00\".dup.force_encoding(\"UTF-16LE\")"

s = 'тест'
s.encoding                # => #<Encoding:UTF-8>
s.dump                    # => "\"\\u0442\\u0435\\u0441\\u0442\""
s.encode('utf-16').dump   # => "\"\\xFE\\xFF\\x04B\\x045\\x04A\\x04B\".dup.force_encoding(\"UTF-16\")"
s.encode('utf-16le').dump # => "\"B\\x045\\x04A\\x04B\\x04\".dup.force_encoding(\"UTF-16LE\")"

s = 'こんにちは'
s.encoding                # => #<Encoding:UTF-8>
s.dump                    # => "\"\\u3053\\u3093\\u306B\\u3061\\u306F\""
s.encode('utf-16').dump   # => "\"\\xFE\\xFF0S0\\x930k0a0o\".dup.force_encoding(\"UTF-16\")"
s.encode('utf-16le').dump # => "\"S0\\x930k0a0o0\".dup.force_encoding(\"UTF-16LE\")"

Related: see Converting to New String.

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.

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.

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.

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.

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.

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.

Like #encode, but applies encoding changes to self; returns self.

Related: see Modifying.

Alias for Regexp#encoding.

Returns whether self ends with any of the given strings:

'foo'.end_with?('oo')         # => true
'foo'.end_with?('bar', 'oo')  # => true
'foo'.end_with?('bar', 'baz') # => false
'foo'.end_with?('')           # => true
'тест'.end_with?('т')         # => true
'こんにちは'.end_with?('は')   # => true

Related: see Querying.

Returns whether self and object have the same length and content:

s = 'foo'
s.eql?('foo')  # => true
s.eql?('food') # => false
s.eql?('FOO')  # => false

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

s0 = "äöü"                           # => "äöü"
s1 = s0.encode(Encoding::ISO_8859_1) # => "\xE4\xF6\xFC"
s0.encoding                          # => #<Encoding:UTF-8>
s1.encoding                          # => #<Encoding:ISO-8859-1>
s0.eql?(s1)                          # => false

See Encodings.

Related: see Querying.

Changes the encoding of self to the given #encoding, which may be a string encoding name or an ::Encoding object; does not change the underlying bytes; returns self:

s = 'łał'
s.bytes                   # => [197, 130, 97, 197, 130]
s.encoding                # => #<Encoding:UTF-8>
s.force_encoding('ascii') # => "\xC5\x82a\xC5\x82"
s.encoding                # => #<Encoding:US-ASCII>
s.valid_encoding?         # => true
s.bytes                   # => [197, 130, 97, 197, 130]

Makes the change even if the given #encoding is invalid for self (as is the change above):

s.valid_encoding?         # => false

See Encodings.

Related: see Modifying.

Returns the byte at zero-based #index as an integer:

s = 'foo'
s.getbyte(0)    # => 102
s.getbyte(1)    # => 111
s.getbyte(2)    # => 111

Counts backward from the end if #index is negative:

s.getbyte(-3) # => 102

Returns nil if #index is out of range:

s.getbyte(3)  # => nil
s.getbyte(-4) # => nil

More examples:

s = 'тест'
s.bytes      # => [209, 130, 208, 181, 209, 129, 209, 130]
s.getbyte(2) # => 208
s = 'こんにちは'
s.bytes      # => [227, 129, 147, 227, 130, 147, 227, 129, 171, 227, 129, 161, 227, 129, 175]
s.getbyte(2) # => 147

Related: see Converting to Non-String.

Returns an array of the grapheme clusters in self (see Unicode Grapheme Cluster Boundaries):

s = "ä-pqr-b̈-xyz-c̈"
s.size                   # => 16
s.bytesize               # => 19
s.grapheme_clusters.size # => 13
s.grapheme_clusters
# => ["ä", "-", "p", "q", "r", "-", "b̈", "-", "x", "y", "z", "-", "c̈"]

Details:

s = "ä"
s.grapheme_clusters             # => ["ä"]           # One grapheme cluster.
s.bytes                         # => [97, 204, 136]  # Three bytes.
s.chars                         # => ["a", "̈"]       # Two characters.
s.chars.map {|char| char.ord }  # => [97, 776]       # Their values.

Related: see Converting to Non-String.

Returns a copy of self with zero or more substrings replaced.

Argument pattern may be a string or a Regexp; argument replacement may be a string or a ::Hash. Varying types for the argument values makes this method very versatile.

Below are some simple examples; for many more examples, see Substitution Methods.

With arguments pattern and string replacement given, replaces each matching substring with the given replacement string:

s = 'abracadabra'
s.gsub('ab', 'AB')   # => "ABracadABra"
s.gsub(/[a-c]/, 'X') # => "XXrXXXdXXrX"

With arguments pattern and hash replacement given, replaces each matching substring with a value from the given replacement hash, or removes it:

h = {'a' => 'A', 'b' => 'B', 'c' => 'C'}
s.gsub(/[a-c]/, h) # => "ABrACAdABrA"  # 'a', 'b', 'c' replaced.
s.gsub(/[a-d]/, h) # => "ABrACAABrA"   # 'd' removed.

With argument pattern and a block given, calls the block with each matching substring; replaces that substring with the block’s return value:

s.gsub(/[a-d]/) {|substring| substring.upcase }
# => "ABrACADABrA"

With argument pattern and no block given, returns a new ::Enumerator.

Related: see Converting to New String.

Like #gsub, except that:

• Performs substitutions in self (not in a copy of self).

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

Related: see Modifying.

Returns the integer hash value for self.

Two String objects that have identical content and compatible encodings also have the same hash value; see Object#hash and Encodings:

s = 'foo'
h = s.hash       # => -569050784
h == 'foo'.hash  # => true
h == 'food'.hash # => false
h == 'FOO'.hash  # => false

s0 = "äöü"
s1 = s0.encode(Encoding::ISO_8859_1)
s0.encoding        # => #<Encoding:UTF-8>
s1.encoding        # => #<Encoding:ISO-8859-1>
s0.hash == s1.hash # => false

Related: see Querying.

Interprets the leading substring of self as hexadecimal; returns its integer value:

'0xFFFF'.hex     # => 65535
'FFzzzFF'.hex    # =>   255  # Hex ends at first non-hex character, 'z'.
'ffzzzFF'.hex    # =>   255  # Case does not matter.
'-FFzzzFF'.hex   # =>  -255  # May have leading '-'.
'0xFFzzzFF'.hex  # =>   255  # May have leading '0x'.
'-0xFFzzzFF'.hex # =>  -255  # May have leading '-0x'.

Returns zero if there is no such leading substring:

'zzz'.hex # => 0

Related: See Converting to Non-String.

Returns whether self contains other_string:

s = 'bar'
s.include?('ba')  # => true
s.include?('ar')  # => true
s.include?('bar') # => true
s.include?('a')   # => true
s.include?('')    # => true
s.include?('foo') # => false