FindSubString( )

Description

FindSubString() function is used to find a string within another string, or multi-line string.

Call Signature

int FindSubString ( string target_string, string sub_string [, int first_to_search] )

Return Value

int

-1 is returned if the substring is not found. Otherwise the return value is either an index within a string or a the line in a multi-line string where the sub_string is first found. See Remarks for details.

Arguments

string

target_string:

This can be either a simple string, or a multi line string (mstring).

string sub_string:

This is a string, to be searched for in the target_string.

[ int first_to_search ]:

An optional indication of what character or line the search should start on. The default is to start on the 1st.

Remarks

The FindSubString() function provides a very efficient method to search for substrings in single strings or string lists.

This is really two functions with significantly different operation -- one operating on a simple string and one on a multi-line string.

Simple String Expression:

If the target_string is a simple string expression, the return value will be the character at which sub_string first occurs in target_string. If a first_to_search argument is passed, the search starts at this character. The search is case insensitive.

Multi-line String Expression:

If the target_string is a multi-line string expression, the return value will be the line on which the sub_string is first found. If the first_to_search argument is passed, it defines the line within the multi-line string to start searching on. The search is case insensitive.

The sub_string can occur anywhere on the line that is found, and doesn't need to match the entire line.

There is no indication where in the found line the sub_string is located, though this could be ascertained through a single string FindSubString().

Example

Ingest a text file and report the line and character offset of all occurrences of the substring "PCIDSK" doing the search efficiently. Notice that we first identify what line the substring is on by searching the whole mstring variable "line_list" and then search within the individual line to find what character the string occurs at.

Because the while loop goes until -1 is returned, it is possible to find many occurrences of the substring on the same line and within the line list.

local mstring         line_list
local int             i, this_line, this_char

line_list = Text$Import("input.txt")

this_line = FindSubString(line_list,"PCIDSK")

while( this_line <> -1 )
	this_char = FindSubString(line_list[this_line],"PCIDSK")
	while( this_char <> -1 )
		printf "PCIDSK occurs at char %d of line %d\n", this_char, this_line

		this_char = FindSubString(line_list[this_line],"PCIDSK",this_char+1)
	endwhile

	this_line = FindSubString(line_list, "PCIDSK", this_line+1)
endwhile