String

The string class. Can handle byte sequences of arbitrary lengths. See String Literals for details.

The String class itself behaves like a byte sequence. Use scan(/./), etc. to extract characters from a multibyte string one at a time.

Superclass

• Object

Included Modules

• Comparable
• Enumerable

Methods

self + other

Returns a new concatenated string.

self * times

Creates and returns a new string consisting of the string contents repeated times times.

self <=> other

Compares self with other by ASCII order; returns a positive integer if self is larger, 0 if the two are equal, and a negative integer if self is smaller.

self == other

Determines whether the strings are equal.

self[nth, len]

Returns a len-byte-long substring found at the nth byte. When nth is negative, counts from the end of the string.

If nth is out of range, returns nil.

self[regexp]

Returns the first substring matching regexp. Matching information can be configured in the built-in variable $~.

If there is no match to regexp, returns nil.

p "foobar"[/bar/]   # => "bar"

self[nth, len]=val

Replaces the len-byte-long substring found at the nth byte with the string val. When nth is negative, counts from the end of the string.

Returns val .

self[regexp]=val

Replaces the first substring matching the regular expression regexp with the string val.

If there is no match to the regular expression, throws an IndexError exception.

Returns val.

clone

dup

Returns a new string with the same contents as the original string. Using clone on a frozen string will return a similarly frozen string, but dup returns an unfrozen string with identical contents.

concat(other)

Appends the contents of the string other to self. Returns self.

downcase

downcase!

Replaces all uppercase characters with lowercase characters.

downcase creates and returns the modified string. downcase! modifies and returns self, but if no characters were replaced, returns nil.

See also upcase.

each {|line| ... }

each_line {|line| ... }

Iterates over each line in the string.

Returns self.

each_byte {|byte| ... }

Iterates over each byte of the string. Returns self.

empty?

Returns true if the string is empty (i.e., a zero-length string).

gsub(pattern) {|matched| .... }

gsub!(pattern) {|matched| .... }

Replaces all substrings matching pattern with the results of the block evaluation. The matching substring is passed to the block as an argument. The built-in variable $<digits> can be referenced within the block.

p 'abcabc'.gsub(/b/) {|s| s.upcase }    # => "aBcaBc"
p 'abcabc'.gsub(/b/) { $&.upcase }      # => "aBcaBc"
p 'abbbcd'.gsub(/a(b+)/) { $1 }         # => "bbbcd"

gsub creates and returns the post-replacement string. gsub! modifies and returns self, but if no characters were replaced, returns nil.

See also sub.

insert(nth, other)

Inserts the string other immediately before the character in the nth position. Returns self.

p "foobaz".insert(3, "bar")         # => "foobarbaz"

to_sym

Returns the symbol value (Symbol) corresponding to the string.

Use Symbol#id2name to obtain the string corresponding to a symbol.

p "foo".to_sym                      # => :foo
p "foo".to_sym.to_s == "foo"        # => true

length

size

Returns the length of the string in bytes.

scan(re)

scan(re) {|s| ... }

Repeatedly matches against self with the regular expression re and returns an array of matching substrings.

p "foobarbazfoobarbaz".scan(/ba./)
# => ["bar", "baz", "bar", "baz"]

p "abcde".scan(/./)
# => ["a", "b", "c", "d", "e"]

When called with a block specified, the matching substrings become the block's parameters. (If parentheses are included, an array of strings that match the patterns in parentheses becomes the block's parameter.) If a block is specified, returns self.

"foobarbazfoobarbaz".scan(/ba./) {|s| p s}
# => "bar"
     "baz"
     "bar"
     "baz"

slice(nth, len)

slice(regexp)

Identical to self[].

slice!(nth, len)

slice!(regexp)

Removes a specified range (see self[]) from a string and returns the removed substring.

If the argument is out of range, returns nil.

sub(pattern) {|matched| ... }

sub!(pattern) {|matched| ... }

Replaces the first substring matching pattern with the results of the block evaluation.

sub creates and returns the post-replacement string. sub! modifies and returns self, but if no characters were replaced, returns nil.

Identical to gsub, except that sub only matches once.

to_f

Interprets the string as a base-10 expression and converts it into a floating point integer (Float).

to_i([base])

Interprets the string as a numeric expression and converts it into an integer.

The default is base-10. By specifing base, you can perform base 2-36 conversions as well.

upcase

upcase!

Replaces all lowercase characters with uppercase characters.

downcase creates and returns the modified string. downcase! modifies and returns self, but if no characters were replaced, returns nil.

See also downcase.