Recipe 13.3. Looking for Pattern Matches

Problem

You want to search a string with a regex to find matches to the pattern.

Solution

Use the String.search( ) and String.match( ) methods.

Discussion

The String.search( ) and RegExp.test( ) methods behave similarly, as discussed in Recipe 13.2. The search( ) method works on a string object and takes a regular expression as a parameter. If the regex can be matched in the string, the starting position for the matching substring is returned. If the regex cannot be matched, -1 is returned:

var example:String = "ActionScript 3 Cookbook"; // Displays: 6 trace( example.search( /script/i ) ); // Displays: -1 trace( example.search( /script/ ) );

In the preceding code block, the search( ) method is first invoked by using a regex that matches the substring script in a case-insensitive manner. The matching substring Script is found at position 6. In the second call to search( ), the same regex is used, but this time without the ignoreCase flag being set. Because the verbatim substring script does not appear in the example string, -1 is returned.

The search( ) method does not respect the global flag or lastIndex property of the regex passed to it. It always begins its search from the beginning of the string.

// Create a global regular expression that matches three-letter words var regex:RegExp = /\b[a-z]{3}\b/g; var sentence:String = "This string has two three letter words."; /* Displays:   12   0   12 */ trace( sentence.search( regex ) ); trace( regex.lastIndex ); trace( sentence.search( regex ) );

When looking for a match with search( ), it is only ever possible to find the position of the first match, even if the regex is flagged as global. The lastIndex property is not automatically adjusted like it is with RegExp.exec( ) (see Recipe 13.2). Additionally, even if you set the lastIndex property by hand, it is not respected by the search( ) method:

// Force the last index to be past the first matching position regex.lastIndex = 13; /* Displays:   12   13 */ trace( sentence.search( regex ) ); trace( regex.lastIndex );

Because the search( ) method doesn't respect global regexes, it's only possible to determine if the string can match a given regexnot how many times a match can be made (just like the RegExp.test( ) method). For situations when you want to extract all of the substring matches to a regex pattern, use the String.match( ) method, which behaves similarly to the RegExp.exec( ) method (again, discussed in Recipe 13.2).

The match( ) method works on a string object and takes a regular expression as a parameter. It returns an array containing the substrings that were matched to the pattern. If the regex is not flagged as global, the array contains only one elementthe first matching substring found. If the regex is global, the array starts looking for matches at the beginning of the string and returns an array containing every match found in the string. If no match can be made, match( ) returns null.

// Create a global regular expression that matches three-letter words var regex:RegExp = /\b[a-z]{3}\b/g; var sentence:String = "This string has two three letter words."; var matches:Array = sentence.match( regex ); /* Displays:   has,two   2 */ trace( matches ); trace( matches.length );

See Also

Recipes 13.1 and 13.2