Tinderbox v9 Icon

String.substr(startNum[, lengthNum])


Operator Type: 

Operator Scope of Action: 

Operator Purpose: 

Operator First Added: 

Operator Last Altered: 

Operator Has Optional Arguments: 

 Function  [other Function type actions]

 Item  [operators of similar scope]

 Data manipulation  [other Data manipulation operators]

 Baseline

 As at baseline

 [More on optional operator arguments]


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.

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.