Description

Represents text as a series of 8-bit characters.

String provides methods for string manipulation, such as finding and extracting substrings, and pattern matching.

The base class of String is Object.

Constructor

String.new(String initial, Number capacity)

Constructs a new String, optionally with an initial value and capacity.

String.new()
String.new("string")
String.new("string", 35)
""
"string"
"string"

Static Methods

String char (Number values...)
Receives zero or more numbers. Returns a string with length equal to the number of arguments, in which each character has the internal numerical code equal to its corresponding argument.
String format (String format, Object values...)
Returns a formatted version of the variable number of arguments following the description given in the format argument.

Methods

Number % (Object value)
Compares value to the receiver string.
String + (Object value)
Returns new string containing value concatenated to receiver string.
String * (Number number)
Returns a new string containing number copies of the receiver.
Boolean < (Object value)
Returns true if receiver string is less than value.
Boolean <= (Object value)
Returns true if receiver string is less than or equal to value.
Boolean = (Object value)
Returns true if receiver string is equal to value.
Boolean > (Object value)
Returns true if receiver string is greater than value.
Boolean >= (Object value)
Returns true if receiver string is greater than or equal to value.
Boolean != (Object value)
Returns true if receiver string is not equal to value.
Number
String 		[] (Number index)
[] (Range range)
[] (String string)
References specified elements in receiver string.
Object []= (Number index, Object value)
Assigns index specified string element to value.
String append (Object value)
Appends value to the contents of receiver string.
Array byte (Number start, Number end)
Returns the internal numerical codes of characters optionally starting from index start, and ending at index end. The default value for start is 0; the default value for end is start.
Array bytes (Number start, Number end)
Returns the internal numerical codes of characters optionally starting from index start, and ending at index end. The default value for start is 0; the default value for end is the string length.
String clear ()
Clears the contents of receiver string.
String dequote ()
Dequotes copy of receiver string.
String dequote_self ()
Dequotes the receiver string.
String enquote ()
Enquotes copy of receiver string.
String enquote_self ()
Enquotes the receiver string.
Array find (String pattern, Number start, Boolean plain)
Looks for the first match of pattern in the receiver string.
Array gmatch (String pattern)
Looks for all matches of pattern in the receiver string.
Array gsub (String pattern, Object repl, Number max)
Returns an array with a copy of the receiver string in which all occurrences of the pattern have been replaced by a replacement string specified by repl, which may be a string, a table, or a method. gsub also returns, as its second array value, the total number of substitutions made.
Number gsub_self (String pattern, Object repl, Number max)
Modifies the receiver string in which all occurrences of the pattern have been replaced by a replacement string specified by repl, which may be a string, a table, or a method. gsub_self returns the total number of substitutions made.
Number hash ()
Returns hash of receiver string.
Number index (String string, Number offset)
Returns index of string in receiver string, optionally starting search at offset.
String insert (Object value, Number offset)
Inserts value into receiver string, optionally starting at offset.
Boolean is_empty ()
Tests if string has a length of zero.
Number length ()
Returns the number of bytes in the receiver string.
String lowercase ()
Returns a copy of the receiver string with all letters lowercased.
String lowercase_self ()
Lowercases the contents of receiver string.
Array match (String pattern, Number start)
Looks for the first match of pattern in the receiver string.
String next ()
Returns the next interval value of the receiver string.
String prepend (Object value)
Prepends value to receiver string.
String replace (String string)
Replaces contents of receiver string with string.
String reverse ()
Reverses bytes in copy of receiver string.
String reverse_self ()
Reverses bytes in receiver string.
String segment (Number length, Number offset)
Extracts length bytes from receiver string, optionally starting from offset.
String slice (Number index, Number number)
slice (Range range)
slice (String string)
Deletes the specified portion from string, and returns the portion deleted.
String sub (String string, String replace)
Performs simple substitution of string with replace in copy of receiver string.
String sub_self (String string, String replace)
Performs simple substitution of string with replace in receiver string.
String substring (Number start, Number end)
Returns the substring of the receiver string that starts at start and ends at end.
Array to_array ()
Returns array representation of receiver string.
Data to_data ()
Returns data representation of receiver string.
Number to_number ()
Returns number representation of receiver string.
String to_string ()
Returns receiver string.
String trim ()
Removes leading and trailing whitespace from copy of receiver string.
String trim_left ()
Removes leading whitespace from copy of receiver string.
String trim_left_self ()
Removes leading whitespace from receiver string.
String trim_right ()
Removes trailing whitespace from receiver string.
String trim_right_self ()
Removes trailing whitespace from copy of receiver string.
String trim_self ()
Removes leading and trailing whitespace from receiver string.
Array unpack (template)
Unpacks the contents of string into array of values according to the template directives.
String uppercase ()
Returns a copy of the string with all letters uppercased.
String uppercase_self ()
Uppercases the contents of the receiver string.

%

Number %(Object value)

Compares value to string. Returns -1 if string is less than, 0 if string is equal to, and +1 if string is greater than value.

Example

"hello" % "hello"
"123" % 123
"hello" % "world"
"world" % "hello"
0
0
-1
1

+

String +(Object value)

Returns string containing value concatenated to string.

Example

"hello" + " world"
"123" + 456
"hello world"
"123456"

*

String *(Number number)

Returns a new string containing number copies of the receiver.

Example

"abc" * 3
"abcabcabc"

<

Boolean <(Object value)

Returns true if string is less than value, otherwise false.

Example

"hello" < "world"
true

<=

Boolean <=(Object value)

Returns true if string is less than or equal to value, otherwise false.

Example

"hello" <= "hello"
true

=

Boolean =(Object value)

Returns true if string is equal to value, otherwise false.

Example

"hello" = "hello"
true

>

Boolean >(Object value)

Returns true if string is greater than value, otherwise false.

Example

"world" < "hello"
true

>=

Boolean >=(Object value)

Returns true if string is greater than or equal to value, otherwise false.

Example

"world" >= "world"
true

!=

Boolean !=(Object value)

Returns true if string is not equal to value, otherwise false.

Example

"hello" != "world"
true

[]

Number|String [](Number index)
Number|String [](Range range)
Number|String [](String string)

References elements specified by index, string, or range in receiver string.

Example

string = "hello"
string[0]
string[2..3]
string["ll"]
string["xx"]
"hello"
104
"ll"
"ll"
nil

[]=

Value !=(Object value)

Assigns index specified element in string to value.

Example

string = "hello"
string[0] = 72
string
"hello"
72
"Hello"

append

String append(Object value)

Appends value to the contents of string.

Example

"hello ".append("world")
"number ".append(123)
"hello world"
"number 123"

byte

Array bytes(Number start,
            Number end)

Returns the internal numerical codes of characters optionally starting from index start, and ending at index end. The default value for start is 0; the default value for end is start.

bytes

Array bytes(Number start,
            Number end)

Returns the internal numerical codes of characters optionally starting from index start, and ending at index end. The default value for start is 0; the default value for end is the string length.

char

static String char(Number values...)

Converts number to character.

Receives zero or more numbers. Returns a string with length equal to the number of arguments, in which each character has the internal numerical code equal to its corresponding argument.

clear

String clear()

Clears the contents of string.

Example

"abc".clear()
""

dequote

String dequote()

Dequotes copy of string.

Example

'"abcd"'.dequote()
abcd

dequote_self

String dequote_self()

Dequotes string.

Example

'"abcd"'.dequote_self()
abcd

enquote

String enquote()

Enquotes copy of string.

Example

'abcd'.enquote()
"abcd"

enquote_self

String enquote_self()

Enquotes string.

Example

'abcd'.enquote_self()
"abcd"

find

Array find(String pattern,
           Number start,
           Boolean plain)

Looks for the first match of pattern in string. If it finds a match, then find returns an array with the indices of string where this occurrence starts and ends; otherwise, it returns nil. A second, optional numerical argument start specifies where to start the search; its default value is 0 and may be negative. A value of true as a third, optional argument plain turns off the pattern matching facilities, so the function does a plain find substring operation, with no characters in pattern being considered magic. Note that if plain is given, then start must be given as well. If the pattern has captures, then in a successful match the captured values are also returned as an array, after the two indices.

format

static String format(String format,
                     Object values...)

Creates a formatted string.

Returns a formatted version of the variable number of arguments following the description given in the format argument. The format string follows the same rules as the printf family of standard C functions. The only differences are that the options/modifiers *, l, L, n, p, and h are not supported and that there is an extra option, q. The q option formats a string in a form suitable to be safely read back by the interpreter: the string is written between double quotes, and all double quotes, newlines, embedded zeros, and backslashes in the string are correctly escaped when written.

gmatch

Array gmatch(String pattern)

Looks for all matches of pattern in string. If it finds any, then gmatch returns an array of captures from the pattern for each match found; otherwise it returns nil. If pattern specifies no captures, then the whole match is returned.

gsub

Array gsub(String pattern,
           Object repl,
           Number max)

Returns an array with a copy of string in which all occurrences of the pattern have been replaced by a replacement string specified by repl, which may be a string, a table, or a method. gsub also returns, as its second array value, the total number of substitutions made.

If repl is a string, then its value is used for replacement. The character % works as an escape character: any sequence in repl of the form %n, with n between 1 and 9, stands for the value of the n-th captured substring (see below). The sequence %0 stands for the whole match. The sequence %% stands for a single %.

If repl is a table, then the table is queried for every match, using the first capture as the key; if the pattern specifies no captures, then the whole match is used as the key.

If repl is a method, then this function is called every time a match occurs, with all captured substrings passed as arguments, in order; if the pattern specifies no captures, then the whole match is passed as a sole argument.

If the value returned by the table query or by the method call is a string or a number, then it is used as the replacement string; otherwise, if it is false or nil, then there is no replacement (that is, the original match is kept in the string).

The optional last parameter max limits the maximum number of substitutions to occur. For instance, when max is 1 only the first occurrence of pattern is replaced.

gsub_self

Number gsub_self(String pattern,
                 Object repl,
                 Number max)

Replaces all occurrences of the pattern within string with the replacement string specified by repl, which may be a string, a table, or a method. gsub_self returns the total number of substitutions made.

If repl is a string, then its value is used for replacement. The character % works as an escape character: any sequence in repl of the form %n, with n between 1 and 9, stands for the value of the n-th captured substring (see below). The sequence %0 stands for the whole match. The sequence %% stands for a single %.

If repl is a table, then the table is queried for every match, using the first capture as the key; if the pattern specifies no captures, then the whole match is used as the key.

If repl is a method, then this function is called every time a match occurs, with all captured substrings passed as arguments, in order; if the pattern specifies no captures, then the whole match is passed as a sole argument.

If the value returned by the table query or by the method call is a string or a number, then it is used as the replacement string; otherwise, if it is false or nil, then there is no replacement (that is, the original match is kept in the string).

The optional last parameter max limits the maximum number of substitutions to occur. For instance, when max is 1 only the first occurrence of pattern is replaced.

hash

Number hash()

Returns the hash of string.

index

Number index(String string,
             Number offset)

Returns index of string in string, optionally starting search at offset.

Example

"abc abc".index("abc")
"abc abc".index("abc", 1)
0
4

insert

String insert(Object value,
              Number offset)

Inserts value into string, optionally starting at offset. The default offset is 0.

Example

"def".insert("abc")
"def".insert(123, 1)
"abcdef"
"d123ef"

is_empty

Boolean is_empty()

Tests if string has a length of zero.

Example

string = ""
string.is_empty()
""
true

length

Number length()

Returns the number of bytes in string.

lowercase

String lowercase()

Lowercases copy of string.

Example

"AbCd".lowercase()
"abcd"

lowercase_self

String lowercase_self()

Lowercases the contents of string.

Example

string = "AbCd"
string.lowercase_self()
string
"AbCd"
"abcd"
"abcd"

match

Array match(String pattern,
            Number start)

Looks for the first match of pattern in string. If it finds one, then match returns an array of captures from the pattern; otherwise it returns nil. If pattern specifies no captures, then the whole match is returned. A second, optional numerical argument start specifies where to start the search; its default value is 0 and may be negative.

next

String next()

Returns the next interval value of string.

Example

"abc".next()
"abz".next()
"abd"
"aca"

prepend

String prepend(Object value)

Prepends value to string.

Example

"def".prepend("abc")
"abcdef"

replace

String replace(String string)

Replaces contents of string with string.

Example

string = "puma"
string.replace("tiger")
string
"puma"
"tiger"
"tiger"

reverse

String reverse()

Reverses bytes in copy of string.

Example

"abc".reverse()
"cba"

reverse_self

String reverse_self()

Reverses bytes in string.

Example

"abc".reverse_self()
"cba"

seek

Number seek(String base,
            Number offset)

Sets and gets the current string position, measured from the beginning of the buffer, to the position given by offset plus the specified base, as follows:

Option Description
"b" base is position 0 (beginning of the buffer)
"c" base is current position
"e" base is end of buffer

In case of success, function seek returns the final string position, measured in bytes from the beginning of the buffer. If this function fails, it returns nil.

The default value for base is "c", and for offset is 0. Therefore, the call string.seek() returns the current string position, without changing it; the call string.seek("b") sets the position to the beginning of the buffer (and returns 0); and the call string.seek("e") sets the position to the end of the buffer, and returns its size.

segment

String segment(Number length,
               Number offset)

Extracts length bytes from string, optionally starting from offset. The default offset is 0.

Example

"elephant".segment(3)
"elephant".segment(3, 2)
"ele"
"pha"

slice

String slice(Number index, Number number)
String slice(Range range)
String slice(String string)

Deletes the specified portion from string, and returns the portion deleted.

Example

string = "elephant"
string.slice(1..3)
string
"elephant"
"lep"
"ehant"

sub

String sub(String string,
           String replace)

Performs simple substitution of string with replace in copy of string.

Example

"old is old".sub("old", "new")
"new is new"

sub_self

String sub_self(String string,
                String replace)

Performs simple substitution of string with replace in receiver string.

Example

"old is old".sub_self("old", "new")
"new is new"

substring

String substring(Number start,
                 Number end)

Returns the substring of string that starts at start and ends at end. If end is absent, then it is assumed to be equal to -1 (which is the same as the string length). In particular, the call string.substring(1, end) returns a prefix of string with length end, and string.substring(-start) returns a suffix of string with length start.

to_array

Array to_array()

Returns the array representation of string.

Example

"hello".to_array()
{104, 101, 108, 108, 111}

to_data

Data to_data()

Returns data representation of string.

to_number

Number to_number()

Returns the number representation of string.

Example

"123".to_number()
123

to_string

String to_string()

Returns string.

trim

String trim()

Removes leading and trailing whitespace from copy of receiver string.

trim_left

String trim_left()

Removes leading whitespace from copy of receiver string.

trim_left_self

String trim_left_self()

Removes leading whitespace from receiver string.

trim_right

String trim_right()

Removes trailing whitespace from copy of receiver string.

trim_right_self

String trim_right_self()

Removes trailing whitespace from receiver string.

trim_self

String trim_self()

Removes leading and trailing whitespace from receiver string.

unpack

Array unpack(String template)

Unpacks the contents of string into an array of values according to the template directives.

Packed strings are created using the Array method pack.

The template string may contain:

Directive Description
z Zero-terminated string
p String preceded by length byte
P String preceded by length word
a String preceded by length double word
A String
f Float
d Double
n Nexus number
c Character
b Byte
h 2 byte number
H Unsigned 2 byte number
i 4 byte number
I Unsigned 4 byte number
l 8 byte number
L Unsigned 8 byte number
< Little endian
> Big endian
= Native endian

Example

string = {1,2,3}.pack("bbb")
string.unpack("bbb")
string
{1,2,3}

uppercase

String uppercase()

Uppercases copy of string.

Example

"AbCd".uppercase()
"ABCD"

uppercase_self

String uppercase_self()

Uppercases the contents of string.

Example

"AbCd".str
str.uppercase_self()
str
"AbCd"
"ABCD"
"ABCD"