User Guide

266 Chapter 14 Using Regular Expressions in Functions
Returning Matched Subexpressions
The REFind and REFindNoCase functions allow you to get information about
matched subexpressions. If you set these functions’ fourth parameter,
ReturnSubExpression, to True, the function returns a CFML structure with two
arrays containing the positions and lengths of text strings that match the
subexpressions of the first instance of a matched regular expression pattern.
The returned structure has two keys,
pos and len. The pos array contains the
position of the subexpressions. The
len array has the length of each subexpression.
The first element of each array contains information about the complete matched
expression, and indices 2 onwards contain information about the parenthesized
elements. If there are no occurrences of the regular expression, the
pos and len
arrays each contain 1 element with a value of 0.
In the following example the first match for the expression ([A-Aa-z]+)[ ]+, is “is is”.
The expression [A-Za-z]+ is a subexpression of the complete regular expression.
<cfset subExprs=REFind("([A-Za-z]+)[ ]+\1",
"There is is a cat in in the kitchen",1,"True")>
When ColdFusion executes the ReFind function, subExprs.pos[1]=7,
subExprs.len[1]=5, subExprs.pos[2]=7, and subExprs.len[2]=2.
The entries subExprs.pos[1] and subExprs.len[1] refer to the entire matched
expression (“is is”), while subExprs.pos[2] and subExprs.len[2] refer to the first
parenthesized subexpression (“is”). Because
REFind returns information on the first
regular expression match only, the subExprs structure does not contain information
about the second match to the regular expression, "in in".
For a full discussion of subexpression usage, see the sections on REFind and
REFindNoCase in the ColdFusion Functions chapter of the CFML Reference.