SubStr() [v1.0.46+]

Retrieves one or more characters from the specified position in a string.

NewStr := SubStr(String, StartingPos , Length)

Parameters

String

The string whose content is copied.

StartingPos

Specify 1 to start at the first character, 2 to start at the second, and so on. If StartingPos is beyond String's length, an empty string is returned.

If StartingPos is less than 1, it is considered to be an offset from the end of the string. For example, 0 extracts the last character and -1 extracts the two last characters. If StartingPos tries to go beyond the left end of the string, the extraction starts at the first character.

Length

If omitted, it defaults to "all characters". If blank, it defaults to 0. Otherwise, specify the maximum number of characters to retrieve (fewer than the maximum are retrieved whenever the remaining part of the string is too short).

You can also specify a negative Length to omit that many characters from the end of the returned string (an empty string is returned if all or too many characters are omitted).

Return Value

This function returns the requested substring of String.

Remarks

Functionally, the SubStr function is almost identical to the StringMid command. However, SubStr is recommended because it is more flexible and future-proof than StringMid.

RegExMatch(), StringMid, StringLeft/Right, StringTrimLeft/Right

Examples

Retrieves a substring with a length of 3 characters at position 4.

MsgBox % SubStr("123abc789", 4, 3) ; Returns abc

Retrieves a substring from the beginning and end of a string.

String := "The Quick Brown Fox Jumps Over the Lazy Dog"
MsgBox % SubStr(String, 1, 19)  ; Returns "The Quick Brown Fox"
MsgBox % SubStr(String, -7)  ; Returns "Lazy Dog"