String Manipulation
The following string manipulation topics are described in this section:
- capitalize
- downcase
- gsub
- include?
- index
- insert
- join
- lines
- ljust
- lstrip
- lstrip
- pluralize
- reverse
- rindex
- rjust
- rstrip
- singularize
- split
- strip
- sub
- upcase
capitalize
Syntax
capitalize($string)
Description
Returns a string with the first letter of the string capitalized (if it is the first character), and the rest are lower-case.
Arguments
| Position | Possible Values | Required | Default Value |
|---|---|---|---|
| 1 | String value | Yes | None |
Result
String
Examples
$string = "hello"
capitalize($string) == "Hello"
$string = "HeLlO"
capitalize($string) == "Hello"
downcase
Syntax
downcase($string)
Description
Returns a string with all ASCII letters in string changed to lower-case.
See also: capitalize, upcase
Arguments
| Position | Possible Values | Required | Default Value |
|---|---|---|---|
| 1 | String value | Yes | None |
Result
String
Examples
$string = "HELLO"
downcase($string) == "hello"
$string = "HeLlO"
downcase($string) == "hello"
gsub
Syntax
gsub($string, $pattern, $replace)
See also: sub
Description
Returns a string with the all occurrences of pattern substituted for the replace argument. The pattern is typically a regular expression, but it can be a string.
Arguments
| Position | Possible Values | Required | Default Value |
|---|---|---|---|
| 1 | String value | Yes | None |
| 2 | String value -OR- Regex | Yes | None |
| 3 | String value | Yes | None |
Result
String
Examples
$string = "hello there howard"
gsub($string, "howard", "tom") == "hello there tom"
gsub($string, /e./, "!") == "h!lo th!!howard"
include?
Syntax
include?($string, $other_str)
Description
Returns true if string contains other_str.
Arguments
| Position | Possible Values | Required | Default Value |
|---|---|---|---|
| 1 | String value | Yes | None |
| 2 | String value | Yes | None |
Result
Boolean
Examples
$string = "hello"
capitalize($string) == "Hello"
$string = "HeLlO"
capitalize($string) == "Hello"
index
Syntax
index($string, $substr[, $offset])
Description
Returns the index of the first occurrence of substr in string. Returns null if not found. If the offset parameter is present, it specifies the position in string to begin the search (can be a negative number which will be relative to the end of the string).
See also: rindex
Arguments
| Position | Possible Values | Required | Default Value |
|---|---|---|---|
| 1 | String value | Yes | None |
| 2 | String value -OR- Regex | Yes | None |
| 3 | Number | No | 0 |
Result
Number or null
Examples
$string = "hello 123"
index($string, "he") == 0
index($string, "he", 2) == null
index($string, "23") == 7
index($string, /[1-9]/) == 6
insert
Syntax
insert($string, $index, $insertion_string)
Description
Returns a string with insertion_string inserted before the character at the given index of string. Negative indices count from the end of string, and insert after the given character. If a positive index is given past the end of string, insertion_string will be inserted at the end. If a negative index is given past the beginning of string, insertion_string will be inserted at the beginning.
Arguments
| Position | Possible Values | Required | Default Value | Comment |
|---|---|---|---|---|
| 1 | String value | Yes | None | |
| 2 | Number | Yes | None | The position at which to insert the new string |
| 3 | String value | Yes | None | The string value to insert |
Result
String
Examples
$string = "hello"
capitalize($string) == "Hello"
$string = "HeLlO"
capitalize($string) == "Hello"
join
Syntax
join($array[, $separator])
Description
Join elements of array into a single string using given separator if any.
See also: split
Arguments
| Position | Possible Values | Required | Default Value | Comment |
|---|---|---|---|---|
| 1 | String value | Yes | None | |
| 2 | String value | No | “” | Empty string by default |
Result
String
Examples
$values = ["some", "dash", "delimited", "string"]
join($values, "-") == "some-dash-delimited-string"
join($values) == "somedashdelimitedstring"
lines
Syntax
lines($string[, $separator])
Description
Returns an array of lines in string split using the supplied separator ($/ by default).
Arguments
| Position | Possible Values | Required | Default Value |
|---|---|---|---|
| 1 | String value | Yes | None |
| 2 | String value | No | $/ |
Result
Array
Examples
$string = "hello\nthere"
lines($string) == ["hello\n","there"]
lines($string, "e") == ["he", "llo\nthe", "re"]
ljust
Syntax
ljust($string, $padded_length[, $padding_value])
See also: rjust
Description
If padded_length is greater than the length of string, returns a string of length padded_length with string left justified and padded with padding_value; otherwise, returns string.
Arguments
| Position | Possible Values | Required | Default Value |
|---|---|---|---|
| 1 | String value | Yes | None |
| 2 | Number | Yes | None |
| 3 | String value | No | “ ” |
Result
String
Examples
$string = "hello"
ljust($string, 10) == "hello "
ljust($string, 3) == "hello"
ljust($string, "10", "end") == "helloenden"
lstrip
Syntax
lstrip($string)
Description
Returns a string with leading whitespace removed from string.
Arguments
| Position | Possible Values | Required | Default Value |
|---|---|---|---|
| 1 | String value | Yes | None |
Result
String
Examples
$string = " hello"
lstrip($string) == "hello"
pluralize
Syntax
pluralize($string)
Description
Returns the plural form of the word in the string. Currently only supports the English locale.
See also: singularize
Arguments
| Position | Possible Values | Required | Default Value |
|---|---|---|---|
| 1 | String value | Yes | None |
Result
String
Examples
$singular_type = "cloud"
pluralize($singular_type) == "clouds"
pluralize("ip_address") == "ip_addresses"
reverse
Syntax
reverse($string)
Description
Returns a string with the characters from string in reverse order.
Arguments
| Position | Possible Values | Required | Default Value |
|---|---|---|---|
| 1 | String value | Yes | None |
Result
String
Examples
$string = "hello"
reverse($string) == "olleh"
rindex
Syntax
rindex($string, $substr[, $offset])
Description
Returns the index of the last occurrence of substr in string. Returns null if not found. If the offset parameter is present, it specifies the position in string to end the search — characters beyond this point will not be considered (can be a negative number which will be relative to the end of the string).
See also: index
Arguments
| Position | Possible Values | Required | Default Value |
|---|---|---|---|
| 1 | String value | Yes | None |
| 2 | String value -OR- Regex | Yes | None |
| 3 | Number | No | None |
Result
Number or null
Examples
$string = "hello 123 123"
rindex($string, "3") == 12
rindex($string, "3", 11) == 8
rindex($string, /1./) == 10
rindex($string, "4") == null
rjust
Syntax
rjust($string, $padded_length[, $padding_value])
Description
If padded_length is greater than the length of string, returns a string of length padded_length with string right justified and padded with padding_value; otherwise, returns string.
See also: ljust
Arguments
| Position | Possible Values | Required | Default Value |
|---|---|---|---|
| 1 | String value | Yes | None |
| 2 | Number | Yes | None |
| 3 | String value | No | “ ” |
Result
String
Examples
$string = "hello"
rjust($string, 10) == " hello"
rjust($string, 3) == "hello"
rjust($string, "10", "end") == "endenhello"
rstrip
Syntax
rstrip($string)
Description
Returns a string with trailing whitespace removed from string.
Arguments
| Position | Possible Values | Required | Default Value |
|---|---|---|---|
| 1 | String value | Yes | None |
Result
String
Examples
$string = "hello "
rstrip($string) == "hello"
singularize
Syntax
singularize($string)
Description
The reverse of pluralize, returns the singular form of a word in a string. Currently only supports the English locale.
See also: pluralize
Arguments
| Position | Possible Values | Required | Default Value |
|---|---|---|---|
| 1 | String value | Yes | None |
Result
String
Examples
$plural_type = "clouds"
singularize($plural_type) == "cloud"
singularize("ip_addresses") == "ip_address"
split
Syntax
split($string, $separator_or_regexp)
Description
Split given string around matches of the given separator or regular expression.
See also: join
Arguments
| Position | Possible Values | Required | Default Value |
|---|---|---|---|
| 1 | String value | Yes | None |
| 2 | String value -OR- Regex | Yes | None |
Result
Array of strings
Examples
$text = "some-dash-delimited--string--"
$values = split($text, "/-+/") # ["some", "dash", "delimited", "string"]
strip
Syntax
strip($string)
Description
Returns a string with leading and trailing whitespace removed from string.
Arguments
| Position | Possible Values | Required | Default Value |
|---|---|---|---|
| 1 | String value | Yes | None |
Result
String
Examples
$string = " hello "
lstrip($string) == "hello"
sub
Syntax
sub($string, $pattern, $replace)
Description
Returns a string with the first occurrences of pattern substituted for the replace argument. The pattern is typically a regular expression, but it can be a string.
See also: gsub
Arguments
| Position | Possible Values | Required | Default Value |
|---|---|---|---|
| 1 | String value | Yes | None |
| 2 | String value -OR- Regex | Yes | None |
| 3 | String value | Yes | None |
Result
String
Examples
$string = "hello there howard"
gsub($string, "howard", "tom") == "hello there tom"
gsub($string, /e./, "!") == "h!lo th!!howard"
upcase
Syntax
upcase($string)
Description
Returns a string with all ASCII letters in string converted to upper-case.
See also: capitalize, downcase
Arguments
| Position | Possible Values | Required | Default Value |
|---|---|---|---|
| 1 | String value | Yes | None |
Result
String
Examples
$string = "hello"
upcase($string) == "HELLO"
$string = "HeLlO"
upcase($string) == "HELLO"