String.Match(String, StringArray) Method

 Top 

Description

Returns the number of regular expression matches between the calling String and the specified String argument. In order to return a match, the String argument must match the entire string - this can be accomplished using regular expressions. A successful pattern match always returns >= 1, where multiple matches come from user specified groupings.

 

Regular Expressions

Description

.

Returns any character except \n (line feed), \r (carriage return)

|

Returns either the first or second item, can be strung together

{n}

Returns the previous item exactly n times; n>=1

{n,}

Returns the previous item at least n times, looks first for most matches possible; n>=0

{n,m}

Returns the previous item starting with m times before reducing repetition to n times; n>=0, m>=n

(...){n}

Matches group (...) if found {n} number of times, if n = 1, {n} is not needed

[...]

Matches a single character out of all possibilities offered, special characters will need an escape sequence

[ - ]

Hyphen indicates a range of characters, numbers to match; specifies a hyphen if immediately after [

[^ ]

Returns any character except those indicated within brackets

\

Indicates an escape sequence to suppress special characters

\Q...\E

Matches the characters between \Q and \E literally, suppressing the meaning of special characters

\d

Matches any decimal digits, can be used inside [...]

\w

Matches any word character, can be used inside [...]

\s

Matches any whitespace, can be used inside [...]

\D

Matches a character that is not a digit, can be used inside [...]

\W

Matches a character that is not a word character, can be used inside [...]

\S

Matches a character that is not a whitespace, can be used inside [...]

\n

Matches a line feed

\t

Matches a tab

*

0 or more of previous expression

+

1 or more of previous expression

?

0 or 1 of previous expression

 

 

Timing Precision Mode

This page describes functionality in nanosecond timing precision mode.

Click here to see the documentation for this object in millisecond timing precision mode.

 

Method Signature

String.Match(

String regularExpression,

StringArray stringArrayArgument)

 

 

Arguments

regularExpression

Description:

A regular expression that defines the pattern to match against.

 

 

stringArrayArgument

Description:

StringArray to hold the values of any groupings that match the regular expression.

 

 

 

Return Value

Type:

number

 

 

Returns the number of regular expression matches between the calling String and the regular expression specified by regularExpression.

 

Syntax

myVariable1 = myString1.Match(myString2, myStringArray1);

 

 

Example 1

This example demonstrates use of regular expression matching.

 

String testStr = "the test string";

StringArray matches;

// The StringArray matches will hold the value of any matches groups.

 

// The first run below does not produce a match because the spaces in the

// string are not being accounted for.  This is addressed by including \s

// in the second run.

 

Report testStr.Match("[a-z]*", matches), matches;

Report testStr.Match("[a-z,\s]*", matches), matches;

 

 

 

Output Report:

 

Input

testStr.Match("[a-z]*")

testStr.Match("[a-z,\s]*")

Output

0.000000000

1.000000000

matches

 

the test string

 

 

 

Example 2

This example demonstrates the use of a combination of regular expressions within one string

 

String testStr = "Apr 15 2011 09:50:02.000";

StringArray matches;

// The StringArray matches will hold the value of any matches groups.

 

// Matching a string with word, special character, and digit input for a

//common date format

 

Report testStr.Match("\w{3} \d{2} [0-9]{4} \d+:\d+:\d+\.\d{3}",matches),matches;

 

 

 

Output Report:

 

Input

testStr.Match("\w{3} \d{2} [0-9]{4} \d+:\d+:\d+\.\d{3}", matches)

Output

1.000000000

matches

Apr 15 2011 09:50:02.000

 

 

 

Example 3

This example demonstrates a more complex use of regular expression matching by matching words and spaces within a string.

 

String testStr = "the test string";

StringArray matches;

// The StringArray matches will hold the value of any matches groups.

 

// In this case, 4 matches are returned. Each grouping indicates one word in the string

// to be matched, defined by (), using the given regular expressions. The same match

// could also be found using the regular expression \w as in the second example.

// The output of '4' indicates that each grouping of letters was correctly matched

// (giving 3 matches) and then the entire string is a match.

 

Report testStr.Match("([a-z]*) ([a-z]*) ([a-z]*)", matches), matches;

Report testStr.Match("(\w*) (\w*) (\w*)", matches), matches;

 

 

 

Output Report:

 

Input

testStr.Match("([a-z]*) ([a-z]*) ([a-z]*)",matches)

Output

4.00000000

matches

{the test string, the, test, string}

 

 

 

Input

testStr.Match("(\w*) (\w*) (\w*)",matches)

Output

4.000000000

matches

{the test string, the, test, string}

 

 

 

See also

String Object

String.Match

Parsing Dates and Times

Parsing Arbitrary String Data

Parsing Arbitrary String Data