In the core CFML RE functions,
refind only matches once,
matches everything, and
rereplace can only replace once or everything, which
results in far less efficient code when doing anything other than these things.
In cfRegex, all Actions that have the ability to match multiple times will
match as many times as possible, by default, and they all accept the
parameter which can be used to control how many times the action occurs.
Using Match as an example:
<cfset FirstNumber = RegexMatch( Pattern = '\d+' , Text = LargeInput , Limit = 1 ) />
will always be more efficient than:
<cfset FirstNumber = ReMatch( reg_expression = '\d+' , string = LargeInput ) />
This is because
ReMatch has to return all matches before the first one can be
RegexMatch stops as soon as the limit is hit.
Limit accepts a positive integer; a limit of zero means "no limit" or unlimited.
It is important to understand, limit indicates the number of times the action occurs - for Split this means the resulting array will be one larger than the limit number, which is different to java.util.regex's native split limit, but consistent with the way limit works with the rest of cfRegex.
When a boolean callback function is used, if it returns
false the action
does not occur, so the match does not count towards the limit - only returning
true from the callback will count towards the limit.
Limit can be used with Find, Match, Replace, and Split actions.