RegExpr_MatchText

int RegExpr_MatchText (int regularExpressionHandle, const char *textToMatch, int textLength, int matchPolicy, int *matchLength);

Purpose

Determines if the specified text begins with a pattern that matches to the regular expression.

The regular expression must match from the beginning of the text. If you want to search for a regular expression match anywhere in the text, you must call this function iteratively, each time passing the address of the next character in the text.

See the Low–level class help for example source code showing how to use this function.

Parameters

Input
Name Type Description
regularExpressionHandle integer A handle returned from the RegExpr_Parse function.
textToMatch const char * The text to match to the regular expression.

The regular expression must match from the beginning of the text. If you want to search for a regular expression match anywhere in the text, you must call this function iteratively, each time passing the address of the next character in the text. See the Instrument Help for example source code. The function RegExpr_FindPatternInText performs this for you.
textLength integer The number of bytes in the text you want to be included to the attempt to match the regular expression.

If you pass a value less than zero, the text is assumed to be nul–terminated, and the full length is used.
matchPolicy integer Specifies whether the maximum or minimum number of characters are matched to the pattern.

Examples:

If the pattern is "a+" and the text to search is "aaaaab", the match could be of length 1 or 5. If you specify RegExpr_MatchLargestNumChars, the match length will be 5. Otherwise, it will be 1.

If the pattern is "a+b" and the text to search is "ababab", the match could be of length 2 or 6. If you specify RegExpr_MatchLargestNumChars, the match length will be 6. Otherwise, it will be 2.

Values:
RegExpr_MatchLargestNumChars 1 (Any non–zero value can be used)
RegExpr_MatchSmallestNumChars 0
Output
Name Type Description
matchLength integer * This parameter is set to the number of characters in the text that actually matched to the regular expression.

If there was no match, then the parameter is set to –1.

Return Value

Name Type Description
matchStatus integer Returns an indication of whether the regular expression matched the text.

Values:
1 matched
0 did not match
–1 did not match, and it was also determined that all attempts to find a match starting at subsequent bytes in the text will also fail.

The –2 return value is provided as an optimization. In some cases, the function can determine that it is useless to try to find a match anywhere in the text on or after the text address that was passed to the function. In that case, the function returns –2. If you are calling this function iteratively until you find a match, you can break out of your loop if the function returns –2. If you do not need to optimize, then you can treat –1 as the same.

Note   A return value of –1 does NOT necessarily indicate that there is a match later in the text.