Core Function SubStr

SubStr( <expression>, <start>, <count>, <replacement> )

Description

Return part of a string

Parameters

expression

The expression to evaluate.

start

The character position to start. (0 = first character)

OR

If the start is a negative value the character position will work backwards from the length of the string.

count

Optional; The number of characters to extract. By default the entire remainder of the string.

If count is given and is negative, then that many characters will be omitted from the end of string (after the start position has been calculated when a start is negative). If start denotes the position of this truncation or beyond, empty string will be returned.

(Note - If you wish to extract from a start to a end position instead of from start to a number of characters you should see StrSub())

replacement

Optional; If you set this parameter the substring will be replaced instead of returned so you will receive a new string with the substring replaced with the replacement text.

If you use the ->> you can force the original string to be modified see example below.

If the replacement and the part to be replaced are the same size it wont even need to reconstruct the string it can just edit it directly in ram.

Return Value

Success: Returns the extracted string.

Failure: Returns an empty string.

Remarks

None.

Example

$var = Substr("I am a string", 2, 2);
MsgBox("2 chars extracted from position 2 are: $var");

Example using Start as a negative number

say substr("UberFoX", -3); // Prints FoX
say substr("UberFoX", -4, 2); // Prints rF

Using replacement and returning a new string

$str = "UberCat!";
print substr($str, 4, 3, "FoX");
# Prints
# UberFoX!

Using replacement and modifying the original string in place

# Normally when you do replacement on SubStr it returns the string
# with the changes made to it and leaves the original unchanged
# but when you use ->> you can force the original to be changed
# and have the replaced part returned instead example
$str = "UberCat!";
print "String: $str\n";
$rep = $str->>substr(4, 3, "FoX");
print "Replaced: $rep\n";
print "String: $str\n";
# String: UberCat!
# Replaced: Cat
# String: UberFoX!

Example of using an array as the second param

my $str = "the quick brown fox";
my $needle = "quick";
my $start = strpos($str, $needle);
my $len = strlen($needle);
my $arr = array($start, $len);
say substr($str, $arr); // Prints "quick"
 
# Slghtly better than doing substr($str, $arr[0], $arr[1]);