3.6. String Functions

3.6.1. bindex()

Synopsis

Retrieves the byte position of a substring within a string.

Usage
bindex(string, substring [, start_position])
Example
$i = bindex("hello there", "the");

Table 3.87. Arguments and Return Values for bindex()

Argument Type

Return Type

Description

String, String, [Integer]

Integer

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.

Usage
brindex(string, substring, [position])
Example
$i = brindex("hello there", "the");

Table 3.88. Arguments and Return Values for brindex()

Argument Type

Return Type

Description

String, String, [Integer]

Integer

Returns the starting byte position of a string in another, starting from the end of the string, or from position if given. If position 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.

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

Table 3.89. 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; if the first argument is a variable reference, then the string is modified in place and the new string is also 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.

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

Table 3.90. Arguments and Return Values for chr()

Argument Type

Return Type

Description

Integer

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.

Usage
convert_encoding(string, new_encoding)
Example
$utf8_str = convert_encoding($iso_8859_1_str, "utf-8");

Table 3.91. 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.92. 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.

Usage
decode_url(url_string)
Example
$decoded_url = decode_url($encoded_url);

Table 3.93. Arguments and Return Values for decode_url()

Argument Type

Return Type

Description

url_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.

Usage
force_encoding(string, new_encoding)
Example
$utf8_str = force_encoding($bad_str, "utf-8");

Table 3.94. 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.

Usage
get_encoding(string)
Example
$enc = get_encoding($string);

Table 3.95. 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.

Usage
index(string, substring [, start_position])
Example
$i = index("hello there", "the");

Table 3.96. Arguments and Return Values for index()

Argument Type

Return Type

Description

String, String, [Integer]

Integer

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.

Usage
join(separator_string, list)
Example
$str = join(":", ("a", "b", "c")); # returns "a:b:c"

Table 3.97. Arguments and Return Values for join()

Argument Type

Return Type

Description

String, List

Srring

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().

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

Table 3.98. Arguments and Return Values for length()

Argument Type

Return Type

Description

String

Integer

Returns the length in characters for the string passed.


This function does not throw any exceptions.

3.6.12. ord()

Synopsis

Gives the numeric value of the first character in the string passed.

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

Table 3.99. Arguments and Return Values for ord()

Argument Type

Return Type

Description

String

Integer

Gives the numeric value of the first character in the string passed. Only works reliably with character encodings where each character is a single byte.


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.

Usage
regex(string, pattern_string, [options])
Example
$bool = regex("hello", "^hel"); # returns True

Table 3.100. Arguments and Return Values for regex()

Argument Type

Return Type

Description

String, String

Boolean

Returns True if string matches pattern, False if not. For valid options, see Regex Constants.


Table 3.101. 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.

Usage
regex_extract(string, pattern_string, [options])
Example
$list = regex_extract("hello:there", "(\\w+):(\\w+)");

Table 3.102. Arguments and Return Values for regex_extract()

Argument Type

Return Type

Description

String, String, [Integer]

String

Returns the result of string =~ s/pattern_string/[options]. For valid options, see Regex Constants


Table 3.103. 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.

Usage
regex_subst(string, pattern_string, target_string, [options])
Example
$str = regex_subst("hello there", "^there$", "you"); # returns "hello you"

Table 3.104. Arguments and Return Values for regex_subst()

Argument Type

Return Type

Description

String, String, String, [Integer]

String

Returns the result of string =~ s/pattern_string/target_string/[options]. For valid options, see Regex Constants


Table 3.105. 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.

Usage
replace(string, substring, new_substring)
Example
$str = replace("hello there", "there", "you"); # returns "hello you"

Table 3.106. Arguments and Return Values for replace()

Argument Type

Return Type

Description

String, String, String

String

Replaces all occurrances of a substring in a string with another 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.

Usage
rindex(string, substring, [position])
Example
$i = rindex("hello there", "the");

Table 3.107. Arguments and Return Values for rindex()

Argument Type

Return Type

Description

String, String, [Integer]

Integer

Returns the starting character position of a string in another, starting from the end of the string, or from position if given. If position 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.

Usage
split(pattern, string)
Example
$list = split(":", "some:text:here"); # returns ("some", "text", "here")

Table 3.108. Arguments and Return Values for split()

Argument Type

Return Type

Description

String, String

List

Returns a list of each component of a string separated by a separator string, with the separator removed.


This function does not throw any exceptions.

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().

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

Table 3.109. Arguments and Return Values for strlen()

Argument Type

Return Type

Description

String

Integer

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. 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.

Usage
substr(string, offset, [length])
Example
$str = substr("hello there", 6); # returns "there"

Table 3.110. Arguments and Return Values for substr()

Argument Type

Return Type

Description

String, Integer, [Integer]

String

Returns the substring according to the arguments. If integer_offset is negative, it designates an offset from the end of the string. If integer_length 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.21. tolower()

Synopsis

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

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

Table 3.111. 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.22. toupper()

Synopsis

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

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

Table 3.112. Arguments and Return Values for toupper()

Argument Type

Return Type

Description

Any

String

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


This function does not throw any exceptions.

3.6.23. 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 the following whitespace characters are removed: ' ', '\n', '\r', '\t', '\v' (vertical tab, ASCII 11), and '\0' (null character). To trim other character, pass a string as the second argument specifying the characters to be removed.

Usage
trim(string, [chars_to_trim])
Example
$line = trim("   hello  \n"); # returns "hello"

Table 3.113. Arguments and Return Values for trim()

Argument Type

Return Type

Description

String, [String]

String

Returns the new string with characters removed from the beginning and end of the string; if the first argument is a variable reference, then the string is modified in place and the new string is also returned.


This function does not throw any exceptions.