String.substr(startNum[, lengthNum])

---

String.substr(startNum[, lengthNum])

This operator allows extraction of a substring from a string attribute. The source string is not affected.

$MyString.substr(startN) 

returns the substring of $MyString beginning startNum characters from the beginning. The numbers for startN and lengthN are 0-based, i.e. zero is character position #1. A negative startNum value counts back from the end of the string .Negative values are 1-based, i.e. the -1 represents the last character in the string.

In the examples below assume $MyString's value is "Hello World". Examples:

$MyString = "abcde".substr(2); returns "cde"

$MyString = "abcde".substr(-2); returns "de"

$MyString = $MyString.substr(6); returns "World"

If the string does not contain at least startNum characters, the empty string is returned.

A second argument lengthNum specifies the length of the returned string. If unspecified, the entire remaining string is returned.

$MyString = "abcde".substr(2,2); returns "cd"

$MyString = "abcde".substr(-3,2); returns "cd"

$MyString = $MyString.substr(0,5); returns "Hello"

If the length of the substring is negative, it is treated as an offset from the end of the string.

$MyString = "Hello".substr(1,-1); → "ell"

Besides strings and string literals, this operator can also be used on other attribute data types that are string-like, URL, File, etc. Although the operator also works on lists/sets, the source data is all the values as a single semi-colon-joined string literal so there is less point in its use in this context.

This function respects existing rich text styling.

Incorrect argument values

From v9.7.2, if .substr() is asked to address parts of the string before its start or after its end, .substr() returns the empty string. This can arise through poor selection of input argument values. For instance, if $MyString is 5 characters long, $MyString.substr(0-7) is impossible, so this returns an empty string.

Trimming leading/trailing quotes

See String.trim().

Working with styled text

This operator is capable of worthing with StyledString operators: StyledString.bold, StyledString.fontSize(), StyledString.italic and StyledString.strike.