3.6. String Functions

3.6. String Functions
Prev	Chapter 3. Function Library	Next

3.6.1. bindex()

Synopsis

Retrieves the byte position of a substring within a string.

Prototype

intbindex(softstring$string, softstring$substring, softint$offset = 0)

intbindex() (RT_NOOP)

Example

$i = bindex("hello there", "the");

Table 3.102. Arguments and Return Values for bindex()

Argument Type	Return Type	Description
`softstring$string, softstring$substring, softint$offset = 0`	`int`	If the substring is found, returns the byte position of the substring within the string (starting at 0). If not found, returns -1. If an offset position is given, the search starts at the offset position. All values are byte positions, not character positions, which may differ for multi-byte character encodings.

This function does not throw any exceptions.

3.6.2. brindex()

Synopsis

Returns the starting byte position of a string in another, starting from the end of the string (-1 if not found) and takes an optional starting position.

Prototype

intbrindex(softstring$string, softstring$substring, softint$offset = -1)

intbrindex() (RT_NOOP)

Example

$i = brindex("hello there", "the");

Table 3.103. Arguments and Return Values for brindex()

Argument Type	Return Type	Description
`softstring$string, softstring$substring, softint$offset = -1`	`int`	Returns the starting byte position of a string in another, starting from the end of the string, or from `position` if given. If `$offset` is given, then the reverse search starts at that character position (searches always go from the end of the string toward the beginning). Returns -1 if the substring cannot be found. All values are byte positions, not character positions, which may differ for multi-byte character encodings.

This function does not throw any exceptions.

3.6.3. chomp()

Synopsis

Removes the trailing end-of-line indicator ('\n' or '\r\n') from a string and returns the new string (also see the chomp operator). If no EOL indicator is present in the string, this function simply returns the original string unmodified. This function accepts variable references, in which case it will modify the string in place and also return the modified string.

Prototype

stringchomp(string)

anychomp(reference)

Example

$line = chomp("hello\n"); # returns "hello"

Table 3.104. Arguments and Return Values for chomp()

Argument Type	Return Type	Description
`string`	`string`	Returns the new string with any end-of-line character(s) removed.
`reference`	`any`	If the first argument is a variable reference and points to a string, then the string is modified in place and the new string is also returned. Otherwise if the reference is any other type, no action is taken and no value is returned.

This function does not throw any exceptions.

3.6.4. chr()

Synopsis

Returns a string containing a single ASCII character represented by the numeric value passed.

Prototype

stringchr(softint)

stringchr(any) (NOOP)

nothingchr() (RT_NOOP)

Example

$i = chr(65); # returns "A"

Table 3.105. Arguments and Return Values for chr()

Argument Type	Return Type	Description
`softint`	`string`	Returns a string containing a single ASCII character represented by the numeric value passed.

This function does not throw any exceptions.

3.6.5. convert_encoding()

Synopsis

Performs explicit string character encoding conversions.

Prototype

stringconvert_encoding(string, string) (CONST)

nothingconvert_encoding() (RT_NOOP)

Example

$utf8_str = convert_encoding($iso_8859_1_str, "utf-8");

Table 3.106. Arguments and Return Values for convert_encoding()

Argument Type	Return Type	Description
`string, string`	`string`	Converts the string arguement to the encoding given and returns the new string.

Table 3.107. Exceptions Thrown by convert_encoding()

err	desc
`STRING-ENCODING-CONVERSION-ERROR`	There was an error converting to the target encoding (ex: conversion not supported, illegal character sequence, etc).

3.6.6. decode_url()

Synopsis

Decodes percent numeric codes in a URL string and returns the decoded string.

Prototype

stringdecode_url(string) (CONST)

nothingdecode_url() (RT_NOOP)

Example

$decoded_url = decode_url($encoded_url);

Table 3.108. Arguments and Return Values for decode_url()

Argument Type	Return Type	Description
`string`	`string`	Returns a string with numeric percent codes decoded to characters.

This function does not throw any exceptions.

3.6.7. force_encoding()

Synopsis

Returns the first string argument tagged with the character encoding given as the second argument; does not actually change the string data; use only in the case that a string is tagged with the wrong encoding, for example, if a string from a File object has a different encoding than the File object.

Prototype

stringforce_encoding(string, string) (CONST)

nothingforce_encoding() (RT_NOOP)

Example

$utf8_str = force_encoding($bad_str, "utf-8");

Table 3.109. Arguments and Return Values for convert_encoding()

Argument Type	Return Type	Description
`string, string`	`string`	Returns a string with identical byte data as the input string, but tagged with the new encoding.

This function does not throw any exceptions.

3.6.8. get_encoding()

Synopsis

Returns a string describing the character encoding of the string passed.

Prototype

stringget_encoding(string) (CONST)

nothingget_encoding() (RT_NOOP)

Example

$enc = get_encoding($string);

Table 3.110. Arguments and Return Values for get_encoding()

Argument Type	Return Type	Description
`string`	`string`	Returns a string describing the character encoding of the string passed (ex: "UTF-8", "ISO-8850-1", "KOI8-R").

This function does not throw any exceptions.

3.6.9. index()

Synopsis

Retrieves the character position of a substring within a string.

Prototype

intindex(softstring$string, softstring$substring, softint$offset = 0) (CONST)

intindex() (RT_NOOP)

Example

$i = index("hello there", "the");

Table 3.111. Arguments and Return Values for index()

Argument Type	Return Type	Description
`softstring$string, softstring$substring, softint$offset = 0`	`int`	If the substring is found, returns the position of the substring within the string (starting at 0). If not found, returns -1. If an offset position is given, the search starts at the offset position. All values are character positions, not byte positions, which may differ for multi-byte character encodings.

This function does not throw any exceptions.

3.6.10. join()

Synopsis

Creates a string from a list and separator string.

Prototype

stringjoin(string, list) (CONST)

stringjoin(string, ...) (CONST)

nothingjoin() (RT_NOOP)

Example

$str = join(":", ("a", "b", "c")); # returns "a:b:c"

Table 3.112. Arguments and Return Values for join()

Argument Type	Return Type	Description
`string, list or ...`	`string`	Returns a string with each element of the list separated by the separator string.

This function does not throw any exceptions.

3.6.11. length()

Synopsis

Returns the length in characters for the string passed. Note that the byte length may differ from the character length with multi-byte character encodings. For byte length of a string, see strlen().

Prototype

intlength(softstring) (CONST)

intlength(binary) (CONST)

intlength(any) (NOOP)

nothinglength() (RT_NOOP)

Example

$len = length("hello"); # returns 5

Table 3.113. Arguments and Return Values for length()

Argument Type	Return Type	Description
`softstring`	`int`	Returns the length in characters for the string passed.
`binary`	`int`	Returns the number of bytes in the binary data passed.

This function does not throw any exceptions.

3.6.12. ord()

Synopsis

Gives the numeric value of the given byte in the string passed (the first byte if no offset is passed); if no string is passed or the offset is after the end of the string, -1 is returned.

Prototype

intord(softstring$string, softint$offset = 0) (CONST)

nothingord() (RT_NOOP)

Example

$i = ord("A"); # returns 65

Table 3.114. Arguments and Return Values for ord()

Argument Type	Return Type	Description
`softstring$string, softint$offset = 0`	`int`	Gives the numeric value of the given byte in the string passed (the first byte if no offset is passed); if no string is passed or the offset is after the end of the string, -1 is returned.

This function does not throw any exceptions.

3.6.13. regex()

Synopsis

Returns True if the regular expression matches the string passed, otherwise returns False.

Prototype

boolregex(string$string, string$pattern, int$options = 0)

nothingregex() (RT_NOOP)

Example

$bool = regex("hello", "^hel"); # returns True

Table 3.115. Arguments and Return Values for regex()

Argument Type	Return Type	Description
`string$string, string$pattern, int$options = 0`	`bool`	Returns `True` if the first argument matches pattern as the second argument, `False` if not. The third argument can be passed to give regex options; for valid options, see Regex Constants.

Table 3.116. Exceptions Thrown by regex()

err	desc
`REGEX-COMPILATION-ERROR`	There was an error compiling the regular expression.

For more information on regular expression processing, see Regular Expressions.

3.6.14. regex_extract()

Synopsis

Returns a list of substrings in a string based on matching patterns defined by a regular expression.

Prototype

*listregex_extract(string$string, string$pattern, int$options = 0)

nothingregex_extract() (RT_NOOP)

Example

my *list $rv = regex_extract("hello:there", "(\\w+):(\\w+)");

Table 3.117. Arguments and Return Values for regex_extract()

Argument Type	Return Type	Description
`string$string, string$pattern, int$options = 0`	`*list`	Returns any patterns in parentheses in the second argument when applied tot he first argument as a `list`. If no matches are found, then NOTHING is returned. The third argument can be used to set regex options; for valid options, see Regex Constants

Table 3.118. Exceptions Thrown by regex_extract()

err	desc
`REGEX-OPTION-ERROR`	Invalid options were passed to the function.
`REGEX-COMPILATION-ERROR`	There was an error compiling the regular expression.

For more information on regular expression processing, see Regular Expressions.

3.6.15. regex_subst()

Synopsis

Returns a string with patterns substituted according to the arguments passed.

Prototype

stringregex_subst(string$string, string$pattern, string$new_string, int$options = 0)

nothingregex_subst() (RT_NOOP)

Example

$str = regex_subst("hello there", "^there$", "you"); # returns "hello you"

Table 3.119. Arguments and Return Values for regex_subst()

Argument Type	Return Type	Description
`string$string, string$pattern, string$new_string, int$options = 0`	`string`	Returns the result of applying the second argument as a pattern to the first argument, with the 3rd argument as the replacement string. The fourth argument can be used to set regex options; for valid options, see Regex Constants

Table 3.120. Exceptions Thrown by regex_subst()

err	desc
`REGEX-OPTION-ERROR`	Invalid options were passed to the function.
`REGEX-COMPILATION-ERROR`	There was an error compiling the regular expression.

For more information on regular expression processing, see Regular Expressions.

3.6.16. replace()

Synopsis

Replaces all occurrances of a substring in a string with another string.

Prototype

stringreplace(string$string, string$old, string$new)

nothingreplace() (RT_NOOP)

Example

$str = replace("hello there", "there", "you"); # returns "hello you"

Table 3.121. Arguments and Return Values for replace()

Argument Type	Return Type	Description
`string$string, string$old, string$new`	`string`	Replaces all occurrances of a the second string found in the first string with the third string and returns the new string.

This function does not throw any exceptions.

3.6.17. rindex()

Synopsis

Returns the starting character position of a string in another, starting from the end of the string (-1 if not found) and takes an optional starting position.

Prototype

intrindex(softstring$string, softstring$substring, softint$offset = -1) (CONST)

intrindex() (RT_NOOP)

Example

$i = rindex("hello there", "the");

Table 3.122. Arguments and Return Values for rindex()

Argument Type	Return Type	Description
`softstring$string, softstring$substring, softint$offset = -1`	`int`	Returns the starting character position of a string in another, starting from the end of the string, or from the third argument giving the character (not byte) position if given (negative values are offsets from the end of the string, -1 gives the last character of the string). If the thirs argument is given, then the reverse search starts at that character position (searches always go from the end of the string toward the beginning). Returns -1 if the substring cannot be found. All values are character positions, not byte positions, which may differ for multi-byte character encodings.

This function does not throw any exceptions.

3.6.18. split()

Synopsis

Splits a string into a list of components based on a separator string. If the separator string is not found in the string to split, then a list with only one element containing the entire string argument is returned.

Only the version that takes the third argument as a quote string can throw exceptions.

Prototype

listsplit(string$pattern, string$string, bool$with_pattern = False) (CONST)

listsplit(string$separator, string$string, string$quote) (RET_VALUE_ONLY)

listsplit(binary$separator, binary$bin) (CONST)

listsplit() (RT_NOOP)

Example

my list $list = split(":", "some:text:here"); # returns ("some", "text", "here")

Table 3.123. Arguments and Return Values for split()

Argument Type	Return Type	Description
`string$separator, string$string, bool$with_pattern = False`	`list of string`	Returns a list of each component of a string separated by a separator string, with the separator removed; the separator pattern will not be included in the elements of the list returned unless the third argument is `True`.
`string$separator, string$string, string$quote`	`list of string`	Returns a list of each component of a string separated by a separator string, with the separator removed; the quote character can appear as the first part of a field, in which case it is assumed to designate the entire field. If instances of the quote character are found in the field preceded by a backquote character (\), then these quote characters are ignored. Note that this variant of the function can throw exceptions if the quote character is found and not terminated, or if text other than the separator string follows an end quote. This is the only variant of split() that can throw exceptions.
`binary$separator, binary$bin`	`list of binary`	Returns a list of each component of thebinary object separated by the bytes identified by `$separator`, with the separator removed.

Table 3.124. Exceptions Thrown by split()

err	desc
`SPLIT-ERROR`	End quote character not found or excess text found following separator string.

3.6.19. strlen()

Synopsis

Returns the length in bytes of the string argument. Note that the byte length may differ from the character length with multi-byte character encodings. For the character length of a string, see length().

Prototype

intstrlen(softstring) (CONST)

intstrlen(any) (NOOP)

nothingstrlen() (RT_NOOP)

Example

$len = strlen("hello"); # returns 5

Table 3.125. Arguments and Return Values for strlen()

Argument Type	Return Type	Description
`softstring`	`int`	Returns the length of the string passed. If the argument is not a string, then it is converted to a string.

This function does not throw any exceptions.

3.6.20. strmul()

Synopsis

Returns new string with repeated original content with optionaly removed trailing characters.

Prototype

stringstrmul(softstring, int)

stringstrmul(softstring, int, int)

Example

my string $ret = strmul("hello", 2); # returns "hellohello"
my string $ret = strmul("%s,", 3, 1); # returns "%s,%s". See missing last ','

Table 3.126. Arguments and Return Values for strmul()

Argument Type	Return Type	Description
`softstring$original, int$multiplicator, [int$offset]`	`string`	Returns the `$multiplicator` times copied `$original`. If there `$offset` given the offset length is removed from end of the new string.

Table 3.127. Exceptions Thrown by strmul()

err	desc
`STRMUL-ERROR`	Offset argument has to be 0 or greater than 0.
`STRMUL-ERROR`	Multiple argument has to be greater than 0.

3.6.21. substr()

Synopsis

Returns a portion of a string starting from an integer offset, with an optional length. Arguments can be negative, giving offsets from the end of the string. All offsets are character positions, not byte positions.

Prototype

stringsubstr(softstring$string, softint$offset, softint$len) (CONST)

stringsubstr(softstring$string, softint$offset) (CONST)

nothingsubstr() (RT_NOOP)

Example

$str = substr("hello there", 6); # returns "there"

Table 3.128. Arguments and Return Values for substr()

Argument Type	Return Type	Description
`softstring$string, softint$offset, [softint$len]`	`string`	Returns the substring according to the arguments. If `$offset` is negative, it designates an offset from the end of the string. If `$len` is not present, all characters from the offset will be copied to the substring. If it is negative, the rest of the string without the trailing number characters given by the negative argument will be copied to the substring.

This function does not throw any exceptions.

3.6.22. tolower()

Synopsis

Converts the argument passed to a string value all in lower case.

Prototype

stringtolower(string) (CONST)

nothingtolower() (RT_NOOP)

Example

$str = tolower("HELLO"); # returns "hello"

Table 3.129. Arguments and Return Values for tolower()

Argument Type	Return Type	Description
`string`	`string`	Converts argument passed to a string value, all in lower case.

This function does not throw any exceptions.

3.6.23. toupper()

Synopsis

Converts the argument passed to a string value all in upper case.

Prototype

stringtoupper(string) (CONST)

nothingtoupper() (RT_NOOP)

Example

$str = toupper("hello"); # returns "HELLO"

Table 3.130. Arguments and Return Values for toupper()

Argument Type	Return Type	Description
`string`	`string`	Converts argument passed to a string value, all in upper case.

This function does not throw any exceptions.

3.6.24. trim()

Synopsis

Removes characters from the start and end of a string and returns the new string (also see the trim operator). This function accepts variable references, in which case it will modify the string in place and also return the modified string.

By default (if the second argument is omitted or passed as an empty string) the following whitespace characters are removed: ' ', '\n', '\r', '\t', '\v' (vertical tab, ASCII 11), and '\0' (null character). To trim other characters, pass a string as the second argument specifying the characters to be removed.

Prototype

stringtrim(string$string, string$chars = "") (CONST)

anytrim(reference$string_ref, string$chars = "")

nothingtrim() (RT_NOOP)

Example

$line = trim("   hello  \n"); # returns "hello"

Table 3.131. Arguments and Return Values for trim()

Argument Type	Return Type	Description
`string$string, string$chars = ""`	`string`	Returns the new string with characters removed from the beginning and end of the string; if the second argument is given then it defines the characters to be removed, otherwise whitespace is removed.
`reference$string_ref, string$chars = ""`	`any`	If the reference points to a string, the string is trimmed in place and the result is also returned; if the second argument is given then it defines the characters to be removed, otherwise whitespace is removed. If the reference is not a string then no value is returned.

This function does not throw any exceptions.

Prev	Up	Next
3.5. Environment Functions	Home	3.7. Operating System Functions