Limit

In the core CFML RE functions, refind only matches once, rematch always 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 Limit 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 )[1] />

This is because ReMatch has to return all matches before the first one can be extracted, whilst 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.