Matches

The matches action returns a boolean which indicates if the supplied regex matches the entire input text.

It also supports an optional returntype which allows different checks, as detailed below.

Since v0.4, when using a Regex object, there are shortcut methods allowing a returntype to be suffixed onto the method name for cleaner syntax, e.g:

RegexObj.matches( Input , 'exact' )   => RegexObj.matchesExact( Input )
RegexObj.matches( Input , 'partial' ) => RegexObj.matchesPartial( Input )
RegexObj.matches( Input , 'start' )   => RegexObj.matchesStart( Input )
RegexObj.matches( Input , 'end' )     => RegexObj.matchesEnd( Input )
RegexObj.matches( Input , 'count' )   => RegexObj.matchesCount( Input )

Return Types

exact

Perform an exact match and returns true only if the regex exactly matches the entire text.

partial

Return true is the regex matches anywhere within the text.

start

Return true only if the regex match starts at the first character of the text.

end

Return true only if the regex match ends with the last character of the text.

count

Returns the number of times a partial match is found anywhere within the text.

Object

<cfset Input = "The quick fox jumps over the lazy brown dog." />
<cfset NineWordsRx = new Regex( '(?:\w+\W){9}' ) />
<cfset ThreeWordsRx = new Regex( '(?:\w+\W){3}' ) />
<cfset TtheRx = new Regex( '[Tt]he' ) />


<cfdump var=#NineWordsRx.matches( Input )# />


<cfdump var=#ThreeWordsRx.matches( Input )# />


<cfdump var=#ThreeWordsRx.matches( Input , 'partial' )# />


<cfdump var=#ThreeWordsRx.matches( Input , 'count' )# />


<cfdump var=#TtheRx.matches( Input , 'partial' )# />


<cfdump var=#TtheRx.matches( Input , 'count' )# />


<cfdump var=#TtheRx.matches( Input , 'start' )# />


<cfdump var=#TtheRx.matches( Input , 'end' )# />


<cfset DogRx = new Regex('dog\.') />
<cfdump var=#DogRx.matches( Input , 'end' )# />


<cfset TheRx = new Regex('the') />
<cfdump var=#TheRx.matches( Input , 'start' )# />


<cfset TheRx = new Regex('the','case_insensitive') />
<cfdump var=#TheRx.matches( Input , 'start' )# />

Tag

<cfset Input = "The quick fox jumps over the lazy brown dog." />

<cfregex matches variable="isExactMatch" text=#Input# >
    (?:\w+\W){9}
</cfregex>
<dump var=#isExactMatch#/>


<cfregex matches variable="isExactMatch" text=#Input# >
    (?:\w+\W){3}
</cfregex>
<dump var=#isExactMatch#/>


<cfregex matches variable="isPartialMatch" text=#Input# returntype="partial" >
    (?:\w+\W){3}
</cfregex>
<dump var=#isPartialMatch#/>


<cfregex matches variable="MatchCount" text=#Input# returntype="count" >
    (?:\w+\W){3}
</cfregex>
<dump var=#MatchCount#/>


<cfregex matches variable="isPartialMatch" text=#Input# returntype="partial" >
    [Tt]he
</cfregex>
<dump var=#isPartialMatch#/>


<cfregex matches variable="MatchCount" text=#Input# returntype="count" >
    [Tt]he
</cfregex>
<dump var=#MatchCount#/>


<cfregex matches variable="isStartMatch" text=#Input# returntype="start" >
    [Tt]he
</cfregex>
<dump var=#isStartMatch#/>


<cfregex matches variable="isEndMatch" text=#Input# returntype="start" >
    [Tt]he
</cfregex>
<dump var=#isEndMatch#/>


<cfregex matches variable="isEndMatch" text=#Input# returntype="start" >
    dog\.
</cfregex>
<dump var=#isEndMatch#/>


<cfregex matches variable="isStartMatch" text=#Input# returntype="start" >
    the
</cfregex>
<dump var=#isStartMatch#/>


<cfregex matches variable="isStartMatch" text=#Input# returntype="start" flags="case_insensitive" >
    the
</cfregex>
<dump var=#isStartMatch#/>

Function

<cfset Input = "The quick fox jumps over the lazy brown dog." />

<cfdump var=#RegexMatches( '(?:\w+\W){9}' , Input )# />


<cfdump var=#RegexMatches( '(?:\w+\W){3}' , Input )# />


<cfdump var=#RegexMatches( '(?:\w+\W){3}' , Input , 'partial' )# />


<cfdump var=#RegexMatches( '(?:\w+\W){3}' , Input , 'count' )# />


<cfdump var=#RegexMatches( '[Tt]he' , Input , 'partial' )# />


<cfdump var=#RegexMatches( '[Tt]he' , Input , 'count' )# />


<cfdump var=#RegexMatches( '[Tt]he' , Input , 'start' )# />


<cfdump var=#RegexMatches( '[Tt]he' , Input , 'end' )# />


<cfdump var=#RegexMatches( 'dog\.' , Input , 'end' )# />


<cfdump var=#RegexMatches( 'the' , Input , 'start' )# />


<cfdump var=#RegexMatches( 'the' , Input , 'start' , 'case_insensitive' )# />

Practical Examples

Example 1

Checking for a UK postcode:

<cfif NOT RegexMatches
    ( '[A-Z]{1,2}[0-9][A-Z]?[0-9]{1,2}[A-Z]{2}'
    , RegexReplace(Form.Postcode,'\s|-','')
    )>
    <cfset Error = "Unrecognised postcode." />
</cfif>

(This is a simplified regex, actual UK postcode validation is more complicated.)

Example 2

Validating that a password has enough non-alpha characters:

<cfif RegexMatches('\W',Form.Password,'count') LT 3>
    <cfset Error = "Passwords must contain at least three non-alphanumeric characters" />
</cfif>

Example 3

If you wanted to identify files which contained var-scoped variables, so that they can be converted to using the local scope, you might use:

<cfset FindVarRx = new Regex
    ( '<cfset\s+var\s+'
      & '|'
      & '<cfscript>[^<v]+(?:(?!</cfscript>).)*?(?<=\n\t{0,5})var\s+'
    , 'CASE_INSENSITIVE,DOTALL'
    ) />

<cfset VarFiles = StructNew() />
<cfset Total = 0 />
<cfdirectory name="Files" recurse directory="/codebase" filter="\*.cfm|\*.cfc" />

<cfloop query="Files">
    <cfif Files.Type NEQ 'FILE'><cfcontinue/></cfif>

    <cfset Found = FindVarRx.matches
        ( Text       : FileRead(Files.Directory & Files.Name)
        , ReturnType : 'count'
        ) />

    <cfif Found >
        <cfset VarFiles[Files.Directory & Files.Name] = Found />
        <cfset Total += Found />
    </cfif>
</cfloop>

<cfif Total >
    <cfoutput>Found #Total# Vars in #StructCount(VarFiles)# of #Files.RecordCount# files.</cfoutput>
    <cfdump var=#VarFiles# />
<cfelse>
    <cfoutput>No vars found in #Files.RecordCount# files.</cfoutput>
</cfif>

(note: this is to demonstrate how the method might be used; the regex itself may return false positives (e.g. vars inside comments or strings)

Example 4

The following example verifies that the start of a string matches one of five doctype definitions.

<cfregex
    action     = "matches"
    returntype = "start"
    variable   = "isSupportedDoctype"
    text       = #HtmlContent#
    >
    ## HTML5 DocType
        (?i:<!doctype\ html\s*>)

    |

    ## XHTML
        <!DOCTYPE\s+html\s+PUBLIC\s+"-//W3C//DTD\ XHTML\ 1\.
            (?:
                ## 1.0 Strict or Transitional
                0\ (Strict|Transitional)//EN"
                \s+
                "http://www\.w3\.org/TR/xhtml1/DTD/xhtml1-(?i:\1)
            |
                ## XHTML 1.1
                1//EN"
                \s+
                "http://www\.w3\.org/TR/xhtml11/DTD/xhtml11
            )
        \.dtd"\s*>

    |

    ## HTML 4 Strict
        <!DOCTYPE\s+HTML\s+PUBLIC\s+"-//W3C//DTD\ HTML\ 4\.01//EN"
        \s+
        "http://www\.w3\.org/TR/html4/strict\.dtd"
        \s*>
</cfregex>