StringGetPos

Retrieves the position of the specified substring within a string.

Deprecated: This command is not recommended for use in new scripts. Use the InStr function instead.

StringGetPos, OutputVar, InputVar, SearchText , Occurrence, Offset

Parameters

OutputVar

The name of the variable in which to store the retrieved position relative to the first character of InputVar. Position 0 is the first character for StringGetPos and position 1 is the first character for InStr().

InputVar

The name of the input variable, whose contents will be searched. Do not enclose the name in percent signs unless you want the contents of the variable to be used as the name.

SearchText

The string to search for. Matching is not case sensitive unless StringCaseSense has been turned on.

Occurrence

This affects which occurrence will be found if SearchText occurs more than once within InputVar. If this parameter is omitted, it defaults to L1 (meaning InputVar will be searched starting from the left for the first match). To change this behavior, specify one of the following options:

Ln: The search will start looking at the left side of InputVar and will continue rightward until the nth match is found.

Rn: The search will start looking at the right side of InputVar and will continue leftward until the nth match is found. If n is omitted (or if Occurrence is 1), it defaults to R1.

For example, to find the fourth occurrence from the right, specify R4. Note: If n is less than or equal to zero, no match will be found.

Offset

The number of characters on the leftmost or rightmost side (depending on the parameter above) to skip over. If omitted, the default is 0. For example, the following would start searching at the tenth character from the left: StringGetPos, OutputVar, InputVar, abc, , 9. This parameter can be an expression.

ErrorLevel

ErrorLevel is set to 1 if the specified occurrence of SearchText could not be found within InputVar, or 0 otherwise.

Remarks

Unlike StringMid and InStr(), 0 is defined as the position of the first character for StringGetPos.

The retrieved position is always relative to the first character of InputVar, regardless of whether Occurrence and/or Offset are specified. For example, if the string "abc" is found in 123abc789, its reported position will always be 3 regardless of the method by which it was found.

If the specified occurrence of SearchText does not exist within InputVar, OutputVar will be set to -1 and ErrorLevel will be set to 1.

Use SplitPath to more easily parse a file path into its directory, filename, and extension.

The built-in variables %A_Space% and %A_Tab% contain a single space and a single tab character, respectively. They are useful when searching for spaces and tabs alone or at the beginning or end of SearchText.

InStr(), RegExMatch(), IfInString, if var in/contains MatchList, StringCaseSense, StringReplace, SplitPath, StringLeft, StringRight, StringMid, StringTrimLeft, StringTrimRight, StringLen, StringLower, StringUpper, if var is type

Examples

Retrieves and analyzes the position of a substring.

Haystack := "abcdefghijklmnopqrs"
Needle := "def"
StringGetPos, pos, Haystack, %Needle%
if (pos >= 0)
    MsgBox, The string was found at position %pos%.

Divides up the full path name of a file into components. Note that it would be much easier to use StrSplit(), StringSplit or a parsing loop to do this, so the below is just for illustration.

FileSelectFile, file, , , Pick a filename in a deeply nested folder:
if (file != "")
{
    pos_prev := StrLen(file)
    pos_prev += 1 ; Adjust to be the position after the last char.
    Loop
    {
        ; Search from the right for the Nth occurrence:
        StringGetPos, pos, file, \, R%A_Index%
        if ErrorLevel
            break
        length := pos_prev - pos - 1
        pos_prev := pos
        pos += 2  ; Adjust for use with StringMid.
        StringMid, path_component, file, %pos%, %length%
        MsgBox Path component #%A_Index% (from the right) is:`n%path_component%
    }
}