Builds a String by creating a String::Builder with the given initial capacity, yielding it to the block and finally getting a String out of it. The String::Builder automatically resizes as needed.

str = String.build do |str|
  str << "hello "
  str << 1
end
str # => "hello 1"

Decodes the given slice UTF-16 sequence into a String.

Invalid values are encoded using the unicode replacement char with codepoint 0xfffd.

slice = Slice[104_u16, 105_u16, 32_u16, 55296_u16, 56485_u16]
String.from_utf16(slice) # => "hi 𐂥"

Implementation of string interpolation of a string and a char.

For example, this code will end up invoking this method:

char = '!'
"hello#{char}" # same as String.interpolation("hello", char)

In this case the implementation just does value + char.

NOTE there should never be a need to call this method instead of using string interpolation.

Implementation of string interpolation of a char and a string.

For example, this code will end up invoking this method:

char = '!'
"#{char}hello" # same as String.interpolation(char, "hello")

In this case the implementation just does char + value.

NOTE there should never be a need to call this method instead of using string interpolation.

Implementation of string interpolation of a single string.

For example, this code will end up invoking this method:

value = "hello"
"#{value}" # same as String.interpolation(value)

In this case the implementation just returns the same string.

NOTE there should never be a need to call this method instead of using string interpolation.

Implementation of string interpolation of a single non-string value.

For example, this code will end up invoking this method:

value = 123
"#{value}" # same as String.interpolation(value)

In this case the implementation just returns the result of calling value.to_s.

NOTE there should never be a need to call this method instead of using string interpolation.

Implementation of string interpolation of multiple string values.

For example, this code will end up invoking this method:

value1 = "hello"
value2 = "world"
"#{value1} #{value2}!" # same as String.interpolation(value1, " ", value2, "!")

In this case the implementation can pre-compute the needed string bytesize and so it's a bit more performant than interpolating non-string values.

NOTE there should never be a need to call this method instead of using string interpolation.

Implementation of string interpolation of multiple, possibly non-string values.

For example, this code will end up invoking this method:

value1 = "hello"
value2 = 123
"#{value1} #{value2}!" # same as String.interpolation(value1, " ", value2, "!")

In this case the implementation will call String.build with the given values.

NOTE there should never be a need to call this method instead of using string interpolation.

Creates a new String from the given bytes, which are encoded in the given encoding.

The invalid argument can be:

• nil: an exception is raised on invalid byte sequences
• :skip: invalid byte sequences are ignored

slice = Slice.new(2, 0_u8)
slice[0] = 186_u8
slice[1] = 195_u8
String.new(slice, "GB2312") # => "好"

Creates a new String from a pointer, indicating its bytesize count and, optionally, the UTF-8 codepoints count (size). Bytes will be copied from the pointer.

If the given size is zero, the amount of UTF-8 codepoints will be lazily computed when needed.

ptr = Pointer.malloc(4) { |i| ('a'.ord + i).to_u8 }
String.new(ptr, 2) # => "ab"

Creates a String from a pointer. Bytes will be copied from the pointer.

This method is unsafe: the pointer must point to data that eventually contains a zero byte that indicates the ends of the string. Otherwise, the result of this method is undefined and might cause a segmentation fault.

This method is typically used in C bindings, where you get a char* from a library and the library guarantees that this pointer eventually has an ending zero byte.

ptr = Pointer.malloc(5) { |i| i == 4 ? 0_u8 : ('a'.ord + i).to_u8 }
String.new(ptr) # => "abcd"

Creates a String from the given slice. Bytes will be copied from the slice.

This method is always safe to call, and the resulting string will have the contents and size of the slice.

slice = Slice.new(4) { |i| ('a'.ord + i).to_u8 }
String.new(slice) # => "abcd"

Creates a new String by allocating a buffer (Pointer(UInt8)) with the given capacity, then yielding that buffer. The block must return a tuple with the bytesize and size (UTF-8 codepoints count) of the String. If the returned size is zero, the UTF-8 codepoints count will be lazily computed.

The bytesize returned by the block must be less than or equal to the capacity given to this String, otherwise ArgumentError is raised.

If you need to build a String where the maximum capacity is unknown, use String#build.

str = String.new(4) do |buffer|
  buffer[0] = 'a'.ord.to_u8
  buffer[1] = 'b'.ord.to_u8
  {2, 2}
end
str # => "ab"

Decodes the given slice UTF-16 sequence into a String and returns the pointer after reading. The string ends when a zero value is found.

slice = Slice[104_u16, 105_u16, 0_u16, 55296_u16, 56485_u16, 0_u16]
String.from_utf16(slice) # => "hi\0000𐂥\u0000"
pointer = slice.to_unsafe
string, pointer = String.from_utf16(pointer)
string # => "hi"
string, pointer = String.from_utf16(pointer)
string # => "𐂥"

Invalid values are encoded using the unicode replacement char with codepoint 0xfffd.

Interpolates other into the string using top-level ::sprintf.

"I have %d apples" % 5                                             # => "I have 5 apples"
"%s, %s, %s, D" % ['A', 'B', 'C']                                  # => "A, B, C, D"
"sum: %{one} + %{two} = %{three}" % {one: 1, two: 2, three: 1 + 2} # => "sum: 1 + 2 = 3"
"I have %<apples>s apples" % {apples: 4}                           # => "I have 4 apples"

Makes a new String by adding str to itself times times.

"Developers! " * 4
# => "Developers! Developers! Developers! Developers! "

Concatenates str and other.

"abc" + "def" # => "abcdef"
"abc" + 'd'   # => "abcd"

Concatenates str and other.

"abc" + "def" # => "abcdef"
"abc" + 'd'   # => "abcd"

The comparison operator.

Compares this string with other, returning -1, 0 or 1 depending on whether this string is less, equal or greater than other.

Comparison is done byte-per-byte: if a byte is less than the other corresponding byte, -1 is returned and so on. This means two strings containing invalid UTF-8 byte sequences may compare unequal, even when they both produce the Unicode replacement character at the same string indices.

If the strings are of different lengths, and the strings are equal when compared up to the shortest length, then the longer string is considered greater than the shorter one.

"abcdef" <=> "abcde"   # => 1
"abcdef" <=> "abcdef"  # => 0
"abcdef" <=> "abcdefg" # => -1
"abcdef" <=> "ABCDEF"  # => 1

The comparison is case-sensitive. #compare is a case-insensitive alternative.

Returns true if this string is equal to `other.

Equality is checked byte-per-byte: if any byte is different from the corresponding byte, it returns false. This means two strings containing invalid UTF-8 byte sequences may compare unequal, even when they both produce the Unicode replacement character at the same string indices.

Thus equality is case-sensitive, as it is with the comparison operator (#<=>). #compare offers a case-insensitive alternative.

"abcdef" == "abcde"   # => false
"abcdef" == "abcdef"  # => true
"abcdef" == "abcdefg" # => false
"abcdef" == "ABCDEF"  # => false

"abcdef".compare("ABCDEF", case_insensitive: true) == 0 # => true

Tests whether str matches regex. If successful, it returns the position of the first match. If unsuccessful, it returns nil.

If the argument isn't a Regex, it returns nil.

"Haystack" =~ /ay/ # => 1
"Haystack" =~ /z/  # => nil

"Haystack" =~ 45 # => nil

Tests whether str matches regex. If successful, it returns the position of the first match. If unsuccessful, it returns nil.

If the argument isn't a Regex, it returns nil.

"Haystack" =~ /ay/ # => 1
"Haystack" =~ /z/  # => nil

"Haystack" =~ 45 # => nil

Returns a substring starting from the start character of size count.

Negative start is added to self.size, thus it's treated as a character index counting from the end, -1 designating the last character.

Raises IndexError if start index is out of bounds. Raises ArgumentError if count is negative.

Returns the Char at the given index.

Negative indices can be used to start counting from the end of the string.

Raises IndexError if the index is out of bounds.

"hello"[0]  # => 'h'
"hello"[1]  # => 'e'
"hello"[-1] # => 'o'
"hello"[-2] # => 'l'
"hello"[5]  # raises IndexError

Returns the substring indicated by range as span of character indices.

The substring ranges from self[range.begin] to self[range.end] (or self[range.end - 1] if the range is exclusive). It can be smaller than range.size if the end index is larger than self.size.

s = "abcde"
s[1..3] # => "bcd"
# range.end > s.size
s[3..7] # => "de"

Open ended ranges are clamped at the start and end of self, respectively.

# open ended ranges
s[2..] # => "cde"
s[..2] # => "abc"

Negative range values are added to self.size, thus they are treated as character indices counting from the end, -1 designating the last character.

# negative indices, both ranges are equivalent for `s`
s[1..3]   # => "bcd"
s[-4..-2] # => "bcd"
# Mixing negative and positive indices, both ranges are equivalent for `s`
s[1..-2] # => "bcd"
s[-4..3] # => "bcd"

Raises IndexError if the start index it out of range (range.begin > self.size || range.begin < -self.size). Ifrange.begin == self.sizean empty string is returned. Ifrange.begin > range.end`, an empty string is returned.

# range.begin > array.size
s[6..10] # raise IndexError
# range.begin == s.size
s[5..10] # => ""
# range.begin > range.end
s[3..1]   # => ""
s[-2..-4] # => ""
s[-2..1]  # => ""
s[3..-4]  # => ""

Returns str if str is found in this string.

"crystal"["cry"]  # => "cry"
"crystal"["ruby"] # raises NilAssertionError

Like #[](Int, Int) but returns nil if the start index is out of bounds.

Like #[](Range), but returns nil if range.begin is out of range.

"hello"[6..7]? # => nil
"hello"[6..]?  # => nil

Returns the character at index or nil if it's out of range.

Negative indices can be used to start counting from the end of the string.

See #[] for a raising alternative.

"hello"[0]?  # => 'h'
"hello"[1]?  # => 'e'
"hello"[-1]? # => 'o'
"hello"[-2]? # => 'l'
"hello"[5]?  # => nil

Returns str if str is found in this string, or nil otherwise.

"crystal"["cry"]?  # => "cry"
"crystal"["ruby"]? # => nil

Returns true if this String is comprised in its entirety by ASCII characters.

"hello".ascii_only? # => true
"你好".ascii_only?    # => false

Returns true if this string consists exclusively of unicode whitespace.

"".blank?        # => true
"   ".blank?     # => true
"   a   ".blank? # => false

Returns the byte at the given index.

Raises IndexError if the index is out of bounds.

"¥hello".byte_at(0)  # => 194
"¥hello".byte_at(1)  # => 165
"¥hello".byte_at(2)  # => 104
"¥hello".byte_at(-1) # => 111
"¥hello".byte_at(6)  # => 111
"¥hello".byte_at(7)  # raises IndexError

Returns the byte at the given index, or yields if out of bounds.

"¥hello".byte_at(6) { "OUT OF BOUNDS" } # => 111
"¥hello".byte_at(7) { "OUT OF BOUNDS" } # => "OUT OF BOUNDS"

Returns the byte at the given index, or nil if out of bounds.

"¥hello".byte_at?(0)  # => 194
"¥hello".byte_at?(1)  # => 165
"¥hello".byte_at?(2)  # => 104
"¥hello".byte_at?(-1) # => 111
"¥hello".byte_at?(6)  # => 111
"¥hello".byte_at?(7)  # => nil

Returns the index of the first occurrence of byte in the string, or nil if not present. If offset is present, it defines the position to start the search.

Negative offset can be used to start the search from the end of the string.

"Hello, World".byte_index(0x6f)             # => 4
"Hello, World".byte_index(0x5a)             # => nil
"Hello, World".byte_index(0x6f, 5)          # => 8
"💣".byte_index(0xA3)                        # => 3
"Dizzy Miss Lizzy".byte_index('z'.ord)      # => 2
"Dizzy Miss Lizzy".byte_index('z'.ord, 3)   # => 3
"Dizzy Miss Lizzy".byte_index('z'.ord, -4)  # => 13
"Dizzy Miss Lizzy".byte_index('z'.ord, -17) # => nil

Returns the index of the first occurrence of char in the string, or nil if not present. If offset is present, it defines the position to start the search.

Negative offset can be used to start the search from the end of the string.

"Hello, World".byte_index('o')          # => 4
"Hello, World".byte_index('Z')          # => nil
"Hello, World".byte_index('o', 5)       # => 8
"Hi, 💣".byte_index('💣')                 # => 4
"Dizzy Miss Lizzy".byte_index('z')      # => 2
"Dizzy Miss Lizzy".byte_index('z', 3)   # => 3
"Dizzy Miss Lizzy".byte_index('z', -4)  # => 13
"Dizzy Miss Lizzy".byte_index('z', -17) # => nil

Returns the byte index of search in the string, or nil if the string is not present. If offset is present, it defines the position to start the search.

Negative offset can be used to start the search from the end of the string.

"¥hello".byte_index("hello")              # => 2
"hello".byte_index("world")               # => nil
"Dizzy Miss Lizzy".byte_index("izzy")     # => 1
"Dizzy Miss Lizzy".byte_index("izzy", 2)  # => 12
"Dizzy Miss Lizzy".byte_index("izzy", -4) # => 12
"Dizzy Miss Lizzy".byte_index("izzy", -3) # => nil

Returns the char index of a byte index, or nil if out of bounds.

It is valid to pass #bytesize to index, and in this case the answer will be the size of this string.

Returns a new string built from count bytes starting at start byte.

start can be negative to start counting from the end of the string. If count is bigger than the number of bytes from start to #bytesize, only remaining bytes are returned.

This method should be avoided, unless the string is proven to be ASCII-only (for example #ascii_only?), or the byte positions are known to be at character boundaries. Otherwise, multi-byte characters may be split, leading to an invalid UTF-8 encoding.

Raises IndexError if the start index is out of bounds.

Raises ArgumentError if count is negative.

"hello".byte_slice(0, 2)   # => "he"
"hello".byte_slice(0, 100) # => "hello"
"hello".byte_slice(-2, 3)  # => "he"
"hello".byte_slice(-2, 5)  # => "he"
"hello".byte_slice(-2, 5)  # => "he"
"¥hello".byte_slice(0, 2)  # => "¥"
"¥hello".byte_slice(2, 2)  # => "he"
"¥hello".byte_slice(0, 1)  # => "\xC2" (invalid UTF-8 character)
"¥hello".byte_slice(1, 1)  # => "\xA5" (invalid UTF-8 character)
"¥hello".byte_slice(1, 2)  # => "\xA5h" (invalid UTF-8 character)
"hello".byte_slice(6, 2)   # raises IndexError
"hello".byte_slice(-6, 2)  # raises IndexError
"hello".byte_slice(0, -2)  # raises ArgumentError

Returns a new string built from byte in range.

Byte indices can be negative to start counting from the end of the string. If the end index is bigger than #bytesize, only remaining bytes are returned.

This method should be avoided, unless the string is proven to be ASCII-only (for example #ascii_only?), or the byte positions are known to be at character boundaries. Otherwise, multi-byte characters may be split, leading to an invalid UTF-8 encoding.

Raises IndexError if the range begin is out of bounds.

"hello".byte_slice(0..2)   # => "hel"
"hello".byte_slice(0..100) # => "hello"
"hello".byte_slice(-2..3)  # => "l"
"hello".byte_slice(-2..5)  # => "lo"
"¥hello".byte_slice(0...2) # => "¥"
"¥hello".byte_slice(2...4) # => "he"
"¥hello".byte_slice(0..0)  # => "\xC2" (invalid UTF-8 character)
"¥hello".byte_slice(1..1)  # => "\xA5" (invalid UTF-8 character)
"¥hello".byte_slice(1..2)  # => "\xA5h" (invalid UTF-8 character)
"hello".byte_slice(6..2)   # raises IndexError
"hello".byte_slice(-6..2)  # raises IndexError

Returns a substring starting from the start byte.

start can be negative to start counting from the end of the string.

This method should be avoided, unless the string is proven to be ASCII-only (for example #ascii_only?), or the byte positions are known to be at character boundaries. Otherwise, multi-byte characters may be split, leading to an invalid UTF-8 encoding.

Raises IndexError if start index is out of bounds.

"hello".byte_slice(0)  # => "hello"
"hello".byte_slice(2)  # => "llo"
"hello".byte_slice(-2) # => "lo"
"¥hello".byte_slice(2) # => "hello"
"¥hello".byte_slice(1) # => "\xA5hello" (invalid UTF-8 character)
"hello".byte_slice(6)  # raises IndexError
"hello".byte_slice(-6) # raises IndexError

Like #byte_slice(Int, Int) but returns Nil if the start index is out of bounds.

Raises ArgumentError if count is negative.

"hello".byte_slice?(0, 2)   # => "he"
"hello".byte_slice?(0, 100) # => "hello"
"hello".byte_slice?(6, 2)   # => nil
"hello".byte_slice?(-6, 2)  # => nil
"hello".byte_slice?(0, -2)  # raises ArgumentError

Like #byte_slice(Range) but returns Nil if range begin is out of bounds.

"hello".byte_slice?(0..2)   # => "hel"
"hello".byte_slice?(0..100) # => "hello"
"hello".byte_slice?(6..8)   # => nil
"hello".byte_slice?(-6..2)  # => nil

Returns a substring starting from the start byte.

start can be negative to start counting from the end of the string.

This method should be avoided, unless the string is proven to be ASCII-only (for example #ascii_only?), or the byte positions are known to be at character boundaries. Otherwise, multi-byte characters may be split, leading to an invalid UTF-8 encoding.

Returns nil if start index is out of bounds.

"hello".byte_slice?(0)  # => "hello"
"hello".byte_slice?(2)  # => "llo"
"hello".byte_slice?(-2) # => "lo"
"¥hello".byte_slice?(2) # => "hello"
"¥hello".byte_slice?(1) # => "\xA5hello" (invalid UTF-8 character)
"hello".byte_slice?(6)  # => nil
"hello".byte_slice?(-6) # => nil

Returns this string's bytes as an Array(UInt8).

"hello".bytes # => [104, 101, 108, 108, 111]
"你好".bytes    # => [228, 189, 160, 229, 165, 189]

Returns the number of bytes in this string.

"hello".bytesize # => 5
"你好".bytesize    # => 6

Writes an camelcased version of self to the given io.

If lower is true, lower camelcase will be written (the first letter is downcased).

io = IO::Memory.new
"eiffel_tower".camelcase io
io.to_s # => "EiffelTower"

Converts underscores to camelcase boundaries.

If lower is true, lower camelcase will be returned (the first letter is downcased).

"eiffel_tower".camelcase                                            # => "EiffelTower"
"empire_state_building".camelcase(lower: true)                      # => "empireStateBuilding"
"isolated_integer".camelcase(options: Unicode::CaseOptions::Turkic) # => "İsolatedİnteger"

Returns a new String with the first letter converted to uppercase and every subsequent letter converted to lowercase.

"hEllO".capitalize # => "Hello"

Writes a capitalized version of self to the given io.

io = IO::Memory.new
"hEllO".capitalize io
io.to_s # => "Hello"

Adds instances of char to left and right of the string until it is at least size of len.

"Purple".center(8)      # => " Purple "
"Purple".center(8, '-') # => "-Purple-"
"Purple".center(9, '-') # => "-Purple--"
"Aubergine".center(8)   # => "Aubergine"

Adds instances of char to left and right of the string until it is at least size of len, then appends the result to the given IO.

io = IO::Memory.new
"Purple".center(io, 9, '-')
io.to_s # => "-Purple--"

Returns the Char at the given index.

Negative indices can be used to start counting from the end of the string.

Raises IndexError if the index is out of bounds.

"hello".char_at(0)  # => 'h'
"hello".char_at(1)  # => 'e'
"hello".char_at(-1) # => 'o'
"hello".char_at(-2) # => 'l'
"hello".char_at(5)  # raises IndexError

Returns the Char at the given index, or result of running the given block if out of bounds.

Negative indices can be used to start counting from the end of the string.

"hello".char_at(4) { 'x' }  # => 'o'
"hello".char_at(5) { 'x' }  # => 'x'
"hello".char_at(-1) { 'x' } # => 'o'
"hello".char_at(-5) { 'x' } # => 'h'
"hello".char_at(-6) { 'x' } # => 'x'

Returns the byte index of a char index, or nil if out of bounds.

It is valid to pass #size to index, and in this case the answer will be the bytesize of this string.

"hello".char_index_to_byte_index(1) # => 1
"hello".char_index_to_byte_index(5) # => 5
"こんにちは".char_index_to_byte_index(1) # => 3
"こんにちは".char_index_to_byte_index(5) # => 15

Returns an Array of all characters in the string.

"ab☃".chars # => ['a', 'b', '☃']

Raises an ArgumentError if self has null bytes. Returns self otherwise.

This method should sometimes be called before passing a String to a C function.

Returns a new String with suffix removed from the end of the string. If suffix is '\n' then "\r\n" is also removed if the string ends with it.

"hello".chomp('o') # => "hell"
"hello".chomp('a') # => "hello"

Returns a new String with suffix removed from the end of the string. If suffix is "\n" then "\r\n" is also removed if the string ends with it.

"hello".chomp("llo") # => "he"
"hello".chomp("ol")  # => "hello"

Returns a new String with the last carriage return removed (that is, it will remove \n, \r, and \r\n).

"string\r\n".chomp # => "string"
"string\n\r".chomp # => "string\n"
"string\n".chomp   # => "string"
"string".chomp     # => "string"
"x".chomp.chomp    # => "x"

Returns self.

Returns the codepoint of the character at the given index.

Negative indices can be used to start counting from the end of the string.

Raises IndexError if the index is out of bounds.

See also: Char#ord.

"hello".codepoint_at(0)  # => 104
"hello".codepoint_at(-1) # => 111
"hello".codepoint_at(5)  # raises IndexError

Returns an Array of the codepoints that make the string.

"ab☃".codepoints # => [97, 98, 9731]

See also: Char#ord.

Compares this string with other, returning -1, 0 or 1 depending on whether this string is less, equal or greater than other, optionally in a case_insensitive manner.

Case-sensitive comparisons (case_insensitive == false) are equivalent to #<=> and are always done byte-per-byte.

"abcdef".compare("abcde")   # => 1
"abcdef".compare("abcdef")  # => 0
"abcdef".compare("abcdefg") # => -1
"abcdef".compare("ABCDEF")  # => 1

"abcdef".compare("ABCDEF", case_insensitive: true) # => 0
"abcdef".compare("ABCDEG", case_insensitive: true) # => -1

"heIIo".compare("heııo", case_insensitive: true, options: Unicode::CaseOptions::Turkic) # => 0
"Baffle".compare("baffle", case_insensitive: true, options: Unicode::CaseOptions::Fold)   # => 0

Case-sensitive only comparison is provided by the comparison operator #<=>.

Yields each char in this string to the block, returns the number of times the block returned a truthy value.

"aabbcc".count &.in?('a', 'b') # => 4

Counts the occurrences of other char in this string.

"aabbcc".count('a') # => 2

Sets should be a list of strings following the rules described at Char#in_set?. Returns the number of characters in this string that match the given set.

Yields each char in this string to the block. Returns a new String with all characters for which the block returned a truthy value removed.

"aabbcc".delete &.in?('a', 'b') # => "cc"

Returns a new String with all occurrences of char removed.

"aabbcc".delete('b') # => "aacc"

Sets should be a list of strings following the rules described at Char#in_set?. Returns a new String with all characters that match the given set removed.

"aabbccdd".delete("a-c") # => "dd"

Returns a new string that results from deleting count characters starting at start.

"abcdefg".delete_at(1, 3) # => "aefg"

Deleting more characters than those in the string is valid, and just results in deleting up to the last character:

"abcdefg".delete_at(3, 10) # => "abc"

A negative start counts from the end of the string:

"abcdefg".delete_at(-3, 2) # => "abcdg"

If count is negative, ArgumentError is raised.

If start is outside the bounds of the string, ArgumentError is raised.

However, start can be the position that is exactly the end of the string:

"abcd".delete_at(4, 3) # => "abcd"

Returns a new string that results from deleting characters at the given range.

"abcdef".delete_at(1..3) # => "aef"

Negative indices can be used to start counting from the end of the string:

"abcdef".delete_at(-3..-2) # => "abcf"

Raises IndexError if any index is outside the bounds of this string.

Returns a new string that results from deleting the character at the given index.

"abcde".delete_at(0) # => "bcde"
"abcde".delete_at(2) # => "abde"
"abcde".delete_at(4) # => "abcd"

A negative index counts from the end of the string:

"abcde".delete_at(-2) # => "abce"

If index is outside the bounds of the string, IndexError is raised.

Returns a new string that results from deleting count characters starting at start.

"abcdefg".delete_at(1, 3) # => "aefg"

Deleting more characters than those in the string is valid, and just results in deleting up to the last character:

"abcdefg".delete_at(3, 10) # => "abc"

A negative start counts from the end of the string:

"abcdefg".delete_at(-3, 2) # => "abcdg"

If count is negative, ArgumentError is raised.

If start is outside the bounds of the string, ArgumentError is raised.

However, start can be the position that is exactly the end of the string:

"abcd".delete_at(4, 3) # => "abcd"

DEPRECATED Use #delete_at(start, count) instead

Returns a new String with each uppercase letter replaced with its lowercase counterpart.

"hEllO".downcase # => "hello"

Writes a downcased version of self to the given io.

io = IO::Memory.new
"hEllO".downcase io
io.to_s # => "hello"

Returns a representation of self as an ASCII-compatible Crystal string literal, wrapped in double quotes.

Non-printable characters (see Char#printable?) and non-ASCII characters (codepoints larger U+007F) are escaped.

"\u{1f48e} - à la carte\n".dump # => %("\\u{1F48E} - \\u00E0 la carte\\n")

See Char#unicode_escape for the format used to escape characters without a special escape sequence.

• #dump_unquoted omits the delimiters.
• #inspect only escapes non-printable characters.

Returns a representation of self as an ASCII-compatible Crystal string literal, wrapped in double quotes.

Non-printable characters (see Char#printable?) and non-ASCII characters (codepoints larger U+007F) are escaped.

"\u{1f48e} - à la carte\n".dump # => %("\\u{1F48E} - \\u00E0 la carte\\n")

See Char#unicode_escape for the format used to escape characters without a special escape sequence.

• #dump_unquoted omits the delimiters.
• #inspect only escapes non-printable characters.

Returns a representation of self as the content of an ASCII-compatible Crystal string literal without delimiters.

Non-printable characters (see Char#printable?) and non-ASCII characters (codepoints larger U+007F) are escaped.

"\u{1f48e} - à la carte\n".dump_unquoted # => %(\\u{1F48E} - \\u00E0 la carte\\n)

See Char#unicode_escape for the format used to escape characters without a special escape sequence.

• #dump wraps the content in double quotes.
• #inspect_unquoted only escapes non-printable characters.

Returns self.

Yields each byte in the string to the block.

array = [] of UInt8
"ab☃".each_byte do |byte|
  array << byte
end
array # => [97, 98, 226, 152, 131]

Returns an Iterator over each byte in the string.

bytes = "ab☃".each_byte
bytes.next # => 97
bytes.next # => 98
bytes.next # => 226
bytes.next # => 152
bytes.next # => 131

Yields each character in the string to the block.

array = [] of Char
"ab☃".each_char do |char|
  array << char
end
array # => ['a', 'b', '☃']

Returns an Iterator over each character in the string.

chars = "ab☃".each_char
chars.next # => 'a'
chars.next # => 'b'
chars.next # => '☃'

Yields each character and its index in the string to the block.

array = [] of Tuple(Char, Int32)
"ab☃".each_char_with_index do |char, index|
  array << {char, index}
end
array # => [{'a', 0}, {'b', 1}, {'☃', 2}]

Accepts an optional offset parameter, which tells it to start counting from there.

Yields each codepoint to the block.

array = [] of Int32
"ab☃".each_codepoint do |codepoint|
  array << codepoint
end
array # => [97, 98, 9731]

See also: Char#ord.

Returns an Iterator for each codepoint.

codepoints = "ab☃".each_codepoint
codepoints.next # => 97
codepoints.next # => 98
codepoints.next # => 9731

See also: Char#ord.

Yields each Unicode extended grapheme cluster in this string.

Grapheme clusters correspond to "user-perceived characters" and are defined in Unicode Standard Annex #29. A cluster can consist of multiple code points which together form a single glyph.

"a👍🏼à".each_grapheme do |cluster|
  p! cluster
end

• #graphemes collects all grapheme clusters in an array

EXPERIMENTAL The grapheme API is still under development. Join the discussion at #11610.

Returns an iterator of this string split into Unicode extended grapheme clusters.

Grapheme clusters correspond to "user-perceived characters" and are defined in Unicode Standard Annex #29. A cluster can consist of multiple code points which together form a single glyph.

"a👍🏼à".each_grapheme.to_a # => [String::Grapheme('a'), String::Grapheme("👍🏼"), String::Grapheme("à")]

• #graphemes collects all grapheme clusters in an array

EXPERIMENTAL The grapheme API is still under development. Join the discussion at #11610.

Splits the string after each newline and yields each line to a block.

haiku = "the first cold shower
even the monkey seems to want
a little coat of straw"
haiku.each_line do |stanza|
  puts stanza
end
# output:
# the first cold shower
# even the monkey seems to want
# a little coat of straw

Returns an Iterator which yields each line of this string (see String#each_line).

Returns true if this is the empty string, "".

Returns a slice of bytes containing this string encoded in the given encoding.

The invalid argument can be:

• nil: an exception is raised on invalid byte sequences
• :skip: invalid byte sequences are ignored

"好".encode("GB2312") # => Bytes[186, 195]
"好".bytes            # => [229, 165, 189]

Returns true if this string ends with the given str.

"hello".ends_with?("o")  # => true
"hello".ends_with?("lo") # => true
"hello".ends_with?("ll") # => false

Returns true if this string ends with the given char.

"hello".ends_with?('o') # => true
"hello".ends_with?('l') # => false

Returns true if the regular expression re matches at the end of this string.

"22hello".ends_with?(/[0-9]/) # => false
"22hello".ends_with?(/[a-z]/) # => true
"22h".ends_with?(/[a-z]/)     # => true
"22h".ends_with?(/[A-Z]/)     # => false
"22h".ends_with?(/[a-z]{2}/)  # => false
"22hh".ends_with?(/[a-z]{2}/) # => true

Returns the number of Unicode extended graphemes clusters in this string.

• #each_grapheme iterates the grapheme clusters.

EXPERIMENTAL The grapheme API is still under development. Join the discussion at #11610.

Returns this string split into Unicode extended grapheme clusters.

Grapheme clusters correspond to "user-perceived characters" and are defined in Unicode Standard Annex #29. A cluster can consist of multiple code points which together form a single glyph.

"a👍🏼à".graphemes # => [String::Grapheme('a'), String::Grapheme("👍🏼"), String::Grapheme("à")]

• #each_grapheme iterates the grapheme clusters without allocating an array

EXPERIMENTAL The grapheme API is still under development. Join the discussion at #11610.

Returns a String where all occurrences of the given string are replaced with the block's value.

"hello yellow".gsub("ll") { "dd" } # => "heddo yeddow"

Returns a String where all occurrences of the given pattern are replaced by the block value's value.

"hello".gsub(/./) { |s| s[0].ord.to_s + ' ' } # => "104 101 108 108 111 "

Returns a String where each character yielded to the given block is replaced by the block's return value.

"hello".gsub { |char| char + 1 } # => "ifmmp"
"hello".gsub { "hi" }            # => "hihihihihi"

Returns a String where all occurrences of the given char are replaced with the given replacement.

"hello".gsub('l', "lo")      # => "heloloo"
"hello world".gsub('o', 'a') # => "hella warld"

Returns a String where all occurrences of the given pattern are replaced with a hash of replacements. If the hash contains the matched pattern, the corresponding value is used as a replacement. Otherwise the match is not included in the returned string.

# "he" and "l" are matched and replaced,
# but "o" is not and so is not included
"hello".gsub(/(he|l|o)/, {"he": "ha", "l": "la"}) # => "halala"

Returns a String where all occurrences of the given string are replaced with the given replacement.

"hello yellow".gsub("ll", "dd") # => "heddo yeddow"

Returns a String where all occurrences of the given pattern are replaced with the given replacement.

"hello".gsub(/[aeiou]/, '*') # => "h*ll*"

Within replacement, the special match variable $~ will not refer to the current match.

If backreferences is true (the default value), replacement can include backreferences:

"hello".gsub(/[aeiou]/, "(\\0)") # => "h(e)ll(o)"

When substitution is performed, any backreferences found in replacement will be replaced with the contents of the corresponding capture group in pattern. Backreferences to capture groups that were not present in pattern or that did not match will be skipped. See Regex for information about capture groups.

Backreferences are expressed in the form "\\d", where d is a group number, or "\\k<name>" where name is the name of a named capture group. A sequence of literal characters resembling a backreference can be expressed by placing "\\" before the sequence.

"foo".gsub(/o/, "x\\0x")                  # => "fxoxxox"
"foofoo".gsub(/(?<bar>oo)/, "|\\k<bar>|") # => "f|oo|f|oo|"
"foo".gsub(/o/, "\\\\0")                  # => "f\\0\\0"

Raises ArgumentError if an incomplete named back-reference is present in replacement.

Raises IndexError if a named group referenced in replacement is not present in pattern.

Returns a String where all chars in the given hash are replaced by the corresponding hash values.

"hello".gsub({'e' => 'a', 'l' => 'd'}) # => "haddo"

Returns a String where all chars in the given named tuple are replaced by the corresponding tuple values.

"hello".gsub({e: 'a', l: 'd'}) # => "haddo"

This returns true if this string has '\\' in it. It might not be a back reference, but '\\' is probably used for back references, so this check is faster than parsing the whole thing.

See Object#hash(hasher)

Interprets this string as containing a sequence of hexadecimal values and decodes it as a slice of bytes. Two consecutive bytes in the string represent a byte in the returned slice.

Raises ArgumentError if this string does not denote an hexstring.

"0102031aff".hexbytes  # => Bytes[1, 2, 3, 26, 255]
"1".hexbytes           # raises ArgumentError
"hello world".hexbytes # raises ArgumentError

Interprets this string as containing a sequence of hexadecimal values and decodes it as a slice of bytes. Two consecutive bytes in the string represent a byte in the returned slice.

Returns nil if this string does not denote an hexstring.

"0102031aff".hexbytes?  # => Bytes[1, 2, 3, 26, 255]
"1".hexbytes?           # => nil
"hello world".hexbytes? # => nil

Returns true if the string contains search.

"Team".includes?('i')            # => false
"Dysfunctional".includes?("fun") # => true

Returns the index of the first occurrence of search in the string, or nil if not present. If offset is present, it defines the position to start the search.

"Hello, World".index('o')    # => 4
"Hello, World".index('Z')    # => nil
"Hello, World".index("o", 5) # => 8
"Hello, World".index("H", 2) # => nil
"Hello, World".index(/[ ]+/) # => 6
"Hello, World".index(/\d+/)  # => nil

Returns the index of the first occurrence of search in the string, or nil if not present. If offset is present, it defines the position to start the search.

"Hello, World".index('o')    # => 4
"Hello, World".index('Z')    # => nil
"Hello, World".index("o", 5) # => 8
"Hello, World".index("H", 2) # => nil
"Hello, World".index(/[ ]+/) # => 6
"Hello, World".index(/\d+/)  # => nil

Returns the index of the first occurrence of search in the string, or nil if not present. If offset is present, it defines the position to start the search.

"Hello, World".index('o')    # => 4
"Hello, World".index('Z')    # => nil
"Hello, World".index("o", 5) # => 8
"Hello, World".index("H", 2) # => nil
"Hello, World".index(/[ ]+/) # => 6
"Hello, World".index(/\d+/)  # => nil

Returns the index of the first occurrence of search in the string, or nil if not present. If offset is present, it defines the position to start the search.

"Hello, World".index('o')    # => 4
"Hello, World".index('Z')    # => nil
"Hello, World".index("o", 5) # => 8
"Hello, World".index("H", 2) # => nil
"Hello, World".index(/[ ]+/) # => 6
"Hello, World".index(/\d+/)  # => nil

Raises Enumerable::NotFoundError if search does not occur in self.

Returns a new String that results of inserting other in self at index. Negative indices count from the end of the string, and insert after the given index.

Raises IndexError if the index is out of bounds.

"abcd".insert(0, 'X')  # => "Xabcd"
"abcd".insert(3, 'X')  # => "abcXd"
"abcd".insert(4, 'X')  # => "abcdX"
"abcd".insert(-3, 'X') # => "abXcd"
"abcd".insert(-1, 'X') # => "abcdX"

"abcd".insert(5, 'X')  # raises IndexError
"abcd".insert(-6, 'X') # raises IndexError

Returns a new String that results of inserting other in self at index. Negative indices count from the end of the string, and insert after the given index.

Raises IndexError if the index is out of bounds.

"abcd".insert(0, "FOO")  # => "FOOabcd"
"abcd".insert(3, "FOO")  # => "abcFOOd"
"abcd".insert(4, "FOO")  # => "abcdFOO"
"abcd".insert(-3, "FOO") # => "abFOOcd"
"abcd".insert(-1, "FOO") # => "abcdFOO"

"abcd".insert(5, "FOO")  # raises IndexError
"abcd".insert(-6, "FOO") # raises IndexError

Returns a representation of self as a Crystal string literal, wrapped in double quotes.

Non-printable characters (see Char#printable?) are escaped.

"\u{1f48e} - à la carte\n".inspect # => %("\u{1F48E} - à la carte\\n")

See Char#unicode_escape for the format used to escape characters without a special escape sequence.

• #inspect_unquoted omits the delimiters.
• #dump additionally escapes all non-ASCII characters.

Returns a representation of self as a Crystal string literal, wrapped in double quotes.

Non-printable characters (see Char#printable?) are escaped.

"\u{1f48e} - à la carte\n".inspect # => %("\u{1F48E} - à la carte\\n")

See Char#unicode_escape for the format used to escape characters without a special escape sequence.

• #inspect_unquoted omits the delimiters.
• #dump additionally escapes all non-ASCII characters.

Returns a representation of self as the content of a Crystal string literal without delimiters.

Non-printable characters (see Char#printable?) are escaped.

"\u{1f48e} - à la carte\n".inspect_unquoted # => %(\u{1F48E} - à la carte\\n)

See Char#unicode_escape for the format used to escape characters without a special escape sequence.

• #inspect wraps the content in double quotes.
• #dump_unquoted additionally escapes all non-ASCII characters.

Returns a representation of self as the content of a Crystal string literal without delimiters.

Non-printable characters (see Char#printable?) are escaped.

"\u{1f48e} - à la carte\n".inspect_unquoted # => %(\u{1F48E} - à la carte\\n)

See Char#unicode_escape for the format used to escape characters without a special escape sequence.

• #inspect wraps the content in double quotes.
• #dump_unquoted additionally escapes all non-ASCII characters.

Returns a new String with prefix removed from the beginning of the string.

"hello".lchop('h')   # => "ello"
"hello".lchop('g')   # => "hello"
"hello".lchop("hel") # => "lo"
"hello".lchop("eh")  # => "hello"

Returns a new String with the first char removed from it. Applying lchop to an empty string returns an empty string.

"hello".lchop # => "ello"
"".lchop      # => ""

Returns a new String with prefix removed from the beginning of the string if possible, else returns nil.

"hello".lchop?('h')   # => "ello"
"hello".lchop?('g')   # => nil
"hello".lchop?("hel") # => "lo"
"hello".lchop?("eh")  # => nil

Returns a new String with the first char removed from it if possible, else returns nil.

"hello".lchop? # => "ello"
"".lchop?      # => nil