Searches a string for the first occurrence of a specified sub-string.
Syntax
StringIndexOf( StringToSearch, SubstringToFind, SearchStartIndex, SearchLength );
Parameters
| Parameter Name | Type | Description | Optional? | Default Value |
|---|---|---|---|---|
| StringToSearch | String | The string to search. | No | n/a |
| SubstringToFind | String | The sub-string you want to find inside StringToSearch. | No | n/a |
| SearchStartIndex | Integer | The index location in StringToSearch where the function should start the search. If left as an empty string, the search will start from the first character. | Yes | "" |
| SearchLength | Integer | The number of characters to include in the search, including the starting character. If left as an empty string, the full string will be searched. | Yes | "" |
Output
If one instance of the specified sub-string is found, the function will return the index number of the sub-string's first character; otherwise, it will return a value of -1.
Use Case
Consider the following example string, which contains three instances of the word "beer":
"wheat beer light beer fruit beer"
If you used the StringIndexOf function to find the sub-string "beer" without using any of the optional parameters, the result would be the index of the letter "b" found in "wheat beer".
StringIndexOf( "wheat beer light beer fruit beer", "beer" );
= 6
We now know this instance of the word "beer" begins at index 6. As a result, if you include a SearchStartIndex argument higher than 6 with the above example, the instance of "beer" found using default arguments will not be found, because every character before SearchStartIndex is ignored.
If you use 8 as your SearchStartIndex, the function will effectively be looking at the following string:
"er light beer fruit beer"
In other words, if we use the following function:
StringIndexOf( "wheat beer light beer fruit beer", "beer", 8 );
= 17
This time, the instance of "beer" in "wheat beer" is not found. Instead, the following instance in "light beer" is found, at index 17.
Adding an argument for SearchLength will restrict the length of the string being examined. This is useful when examining larger strings if you want to limit your search to within a certain number of characters, avoiding unnecessary processing time.
In the beer example, we know that as long as the whole string contains at least one instance of "beer", an index will be returned as long as the search string length is long enough to encompass one instance. If you look at the diagram below, you will see that as long as your search string is at least 14 characters in length, you will return at least one instance of the word "beer", and an index as a result.
All search strings containing 14 or more characters will return at least one instance of the word "beer".
Conversely, if our search string length is less than the total length of the string being searched for, it will never find the whole word "beer", no matter what other arguments are used.
StringIndexOf( "wheat beer light beer fruit beer", "beer", 2, 3 );
= -1