String

The String class represents the arbitrary length of byte string.

Some methods for the String class which have the name ends with `!', modify the contents of the strings. The methods without `!' make copy of the string and modify them. So, they are more slower but safer. For example:

f = "string"
print f, f.sub("str", "ski"), f
       => string, skiing, string
print f, f.sub!("str", "ski"), f
       => skiing, skiing, skiing

SuperClass:

Object

Included Modules:

Comparable

Enumerable

Class Methods:

new(string)

Returns a newly created string object which has same contents to the string.

Methods:

self + other

Returns newly created concatenated string.

self * times

Reputation of the string. For example, "x" * 4 returns "xxxx".

self % args

Formats from the string. Works just like: sprintf(self, *args).

self == other

self > other

self >= other

self < other

self <= other

String comparison. If the value of the variable $= is not false, comparison done by case-insensitive.

self === other

Same as operator `=='. Used for case comparison.

self << other

Appends other's value to the string contents.

self =~ other

String match. Returns an index of the match if any, or nil. If the argument other is a string, it will be compiled into a regular expression.

~ self

Same as $_ =~ self.

self[nth]

Retrieves the nth character from a string.

self[start..last]

Returns a substring from start to last, including both ends.

self[start, length]

Returns a substring of length characters from start.

self[nth] = val

Changes the nth character of the string into val. If the strings is freezed, exception will occur.

self[start..last] = val

Replace the substring from start to last with val.

self[start, len] = val

Replace the substring length characters from start with val.

self <=> other

Returns -1, 0, or 1 depending on whether the left argument is less than, equal to, or greater than the right argument in the dictionary order.

<<(other)

concat(other)

Appends the contents of the other.

capitalize

capitalize!

Changes the first character in the string to uppercase character, if it is an alphabet.

capitalize! returns nil, if it does not modify the receiver.

chop

chop!

Chops off the last character of the string (2 characters if the last characters are "\r\n"). chop! modifies the receiver.

chop! returns nil, if it does not modify the receiver.

chomp([rs])

chomp!([rs])

Chops off the line ending of the string, which is specified by the rs. The default value of the rs is the value of the variable $/.

chomp! modifies the receiver, and returns nil, if it does not modify the receiver.

clone

dup

Returns a newly created string object which has the save value to the string. clone returns the complete copy of the original string including freeze status and instance variables. On the other hand, dup copies the string contents only.

crypt(salt)

Returns an encoded string using crypt(3). salt is the arbitrary string longer than 2 bytes.

delete(str)

delete!(str)

Deletes every characters included in str from the string. Deleting characters in str is in the form of tr(1). For example, `a-c' is the range from `a' to `c', `^' at the beginning means complement of the character set.

delete! returns nil, if it does not modify the receiver.

downcase

downcase!

Replaces all uppercase characters to lowercase characters. Little bit faster than tr("A-Z", "a-z").

downcase! returns nil, if it does not modify the receiver.

dump

Replaces all non-printable characters into backslash notations. The condition str == eval(str.dump) is guaranteed.

each_byte {|byte|...}

Iterates over each byte of the string.

each([rs]) {|line|...}

each_line([rs]) {|line|...}

Iterates over each line in the string. The value of the rsis the line separator, which default is the value of the variable $/.

empty?

Returns true, if the string is empty (i.e. 0 length string).

freeze

Prohibits modification of the string. Modification to the freezed string raises an exception.

frozen?

Returns true if the string is frozen.

gsub(pattern, replace)

gsub!(pattern, replace)

Replaces all matching substrings with the pattern to the replace. In replace, `&' and `\0' replaced to the matching substring, `\digit' replaced to the contents of the corresponding parenthesis. \`, \', and \+ replaced to pre-match, post-match substring, and contents of the last parenthesis respectively.

Notice: $<digits> are not available for the replace string, since it is evaluated before, match happens.

The method gsub! modifies the original string. If no match found gsub! returns nil. On the other hand, gsub modifies the copy of the string. If no match found, gsub returns the unmodified original string.

gsub(pattern) {...}

gsub!(pattern) {...}

If gsub and gsub! are called with the block, replace all matching substring to the value of the block. The matching substring will be given to the block.

hex

Interprets the string as a hexadecimal string and returns the corresponding integer value.

index(substr[, pos])

Returns the index of the substr in the string, or nil if not found. Optional second argument pos is given, start lookup from there.

intern

Returns unique integer corresponding the string. The string must not contain the null character ('\0').

length

size

Returns the length of the string in bytes.

ljust(width)

rjust(width)

center(width)

Returns left filled, right filled, centered string, respectively. If the string is longer than width, returns the string itself without modification.

oct

Interprets the string as a octal string and returns the corresponding integer value. Returns 0 if the string is not in octal. The octal string is the pattern of /^[0-7]+/.

reverse

reverse!

Returns the reversed string of the original string.

replace(other)

Copis the content of other into the string.

rindex(substr[, pos])

Returns the index of the last occurrence of the substr, or nil if not found. If optional second argument pos given, rindex returns the last occurrence at or before that position.

scan(pattern)

scan(pattern) {...}

Returns the array of arrays which contain subpatterns corresponding parentheses in the pattern. Match will be done repeatedly to the end of the string. When called with the block, subpatterns are passed to the block as parameters.

split([sep[, limit]])

Return an array containing the fields of the string, using the string or regexp sep as a separator. If sep is omitted, the value of the variable $; will be used as default. If the value of $; is nil, splits the string on whitespace (after skipping any leading whitespace). Anything matching sep is taken to be a delimiter separating the fields. (Note that the delimiter may be longer than one character.)

If limit is unspecified, trailing null fields are stripped (which potential users of pop() would do well to remember). If limit is specified and is not negative, splits into no more than that many fields (though it may split into fewer). If limit is negative, it is treated as if an arbitrarily large limit had been specified.

A pattern matching the null string (not to be confused with a null pattern //, which is just one member of the set of patterns matching a null string) will split the string into separate characters at each point it matches that way. For example:

print 'hi there'.split(/ */).join(':');

produces the output 'h:i:t:h:e:r:e'.

squeeze([str])

squeeze!([str])

Squeezes sequences of the same characters which is included in the str.

squeezes! returns nil, if it does not modify the receiver.

strip

strip!

Removes leading and trailing whitespace from the string.

strip! returns nil, if it does not modify the receiver.

sub(pattern, replace)

sub!(pattern, replace)

Replaces the first matching substrings with the pattern to the replace. In replace, `&' and `\0' replaced to the matching substring, `\digit' replaced to the contents of the corresponding parenthesis.

Notice: $<digits> are not available for the replace string, since it is evaluated before, match happens.

The method sub! modifies the original string. If no match found, sub! returns nil. On the other hand, sub modifies the copy of the string. If no match found, sub returns the unmodified original string.

sub(pattern) {...}

sub!(pattern) {...}

If gsub and gsub! are called with the block, replace the first matching substring to the value of the block. You can use $<digits> in the iterator block, for the block is evaluated after the match. The matching substring will be given to the block.

succ

succ!

Returns the succeeding string from self, which is like:

"aa".succ =>	"ab"
"99".succ =>	"100"
"a9".succ =>	"b0"
"Az".succ =>	"Ba"
"zz".succ =>	"aaa"

sum([bits])

Calculates bits-bit checksum of the string. Default is 16-bit checksum. For example, the following computes the same number as the System V sum program:

sum = 0
while gets
  sum += $_.sum
end
sum %= 65536

swapcase

swapcase!

Replaces all lowercase characters to uppercase characters, and all uppercase characters to lowercase characters.

swapcase! returns nil, if it does not modify the receiver.

to_f

Converts the string into Float.

to_i

Interprets the string as a decimal string and returns the corresponding integer value.

tr(search, replace)

tr!(search, replace)

Translates all occurrences of the characters found in search, with the corresponding character in replace. The first character in the search is `^', characters not in the search are translated.

tr! returns nil, if it does not modify the receiver.

tr_s(search, replace)

tr_s!(search, replace)

Translates all occurrences of the characters found in search, with the corresponding character in replace, then squeezes sequences of the same characters within the replaced characters. The first character in the search is `^', characters not in the search are translated.

tr_s! returns nil, if it does not modify the receiver.

unpack(template)

Unpacks packed string data (probably made by Array#pack), and expanded array value. The template has the same format as in the Array#pack, as follows this:

a

ASCII string(null padded)

A

ASCII string(space padded)

b

bit string(ascending bit order)

B

bit string(descending bit order)

h

hex string(low nibble first)

H

hex string(high nibble first)

c

char

C

unsigned char

s

short

S

unsigned short

i

int

I

unsigned int

l

long

L

unsigned long

m

string encoded in base64

n

short in "network" byte-order

N

long in "network" byte-order

v

short in "VAX" (little-endian) byte-order

V

long in "VAX" (little-endian) byte-order

f

single-precision float in the native format

d

A double-precision float in the native format

p

A pointer to a null-terminated string.

P

A pointer to a structure (fixed-length string).

u

uuencoded string

x

skip a byte

X

back up a byte

@

moves to absolute position

upcase

upcase!

Replaces all lowercase characters to downcase characters. Little bit faster than tr("a-z", "A-Z").

upcase! returns nil, if it does not modify the receiver.

upto(max) {...}

Iterates from self to max, giving the next string each time. (See succ) This method used internally in Range#each, that makes

     for i in "a" .. "ba"
       print i, "\n"
     end

print `a, b, c,...z,aa,...az, ba'.

matz@netlab.co.jp