@Matches (Formula Language)

Tests a string for a pattern string. Because the pattern string can contain a number of "wildcard" characters and logical symbols, you can test for complex character patterns.

Syntax

@Matches( string ; pattern )

Parameters

string

Text or text list. The string you want to scan in quotes. You can also enter the field name of a field that contains the string you want to scan; do not surround the field name in quotes.

pattern

Text or text list. The pattern you want to scan for in string surrounded by quotation marks. May contain wildcard characters and symbols (see the following table). The following symbols require a preceding backslash unless the pattern is enclosed in braces { } as a set: ?, *, &, !, |, \, +. The symbols require two preceding backslashes instead of one if the pattern is specified as a literal. This is because the backslash is an escape character in string literals, so "\?" passes "?" to the matching engine, where it is treated as a wildcard, while "\\?" passes "\?" to the matching engine, where it is treated as a question mark character.

Note: Simple characters in the pattern are not case-sensitive. Characters enclosed in braces must be matched exactly, and are case-sensitive. The character set {A-z} includes not just upper and lower case alphabet characters but also the backslash, underscore, and brackets characters.

Return value

flag

Boolean

  • Returns 1 (True) if the string contains the pattern
  • Returns 0 (False) if the string does not contain the pattern

The wildcard characters and symbols are as follows:

Symbol

Use

C

Where C is any character. Matches any single, non-special character C (or c)

?

Matches any single character

*

Matches any string (any number of characters)

{ABC}

Matches any character in set ABC

{A-FL-R}

Matches any character in the sets A...F and L...R

+C

Matches any number of occurrences of C (or c)

!

Complements logical meaning of the pattern (logical NOT)

|

Performs logical OR of two patterns

&

Performs logical AND of two patterns
Note: When specifying sets, be sure to enclose them in { } (curly braces). For example, the set A...F is represented as {A-F}.

Examples of pattern matching:

Pattern

Matches

ABC

The three-character string [a|A][b|B][c|C]

{ABC}{ABC}

Any two-character string composed of capital letters A, B, or C

A?C

Any three-character string that starts with a|A and ends with c|C

???

Any three-character string

+?

Any string, including the null string

+?{A-Z}

Any string that ends in a capital letter

+{!A-Z}

Any string that does not contain a capital letter

Usage

If the first or second parameter is a list, the function returns true if any element in the second parameter matches any element in the first parameter.

Examples

  1. This example returns 0. 
    @Matches("A big test";"a?test")
  2. This example returns 1.
    @Matches("A big test";"a?????test")
  3. This example converts the contents of the State field to lowercase, and returns 1 for any value in the field that contains "mont," for example Vermont or Montana. 
    @Matches(@Lowercase(State);"*mont*")
  4. This example is the default value formula for a field named SalesNumber. The formula returns the number 224 if the content of the Division field is either Central or Midwest. If the content of Division is anything else, the formula returns the number 124.
    @If(@Matches(Division;"Central | Midwest");224;124)
  5. This code, when added as the validation formula for a number field called input, displays the error message, "Value cannot be a letter" if the user enters any lowercase or uppercase letter between A and Z. 
    @If(@Matches(@Text(input);"+{!A-z}");@Success;@Failure("Value cannot be a letter"))
    Note: The validation error message is also triggered if the user enters a backslash, underscore, or brackets because specifying A-z, specifies all ASCII characters between the uppercase A and lowercase z. The backslash, underscore, and brackets are included in this set of characters.
  6. This code, when added as the validation formula for the US_State editable text field, displays the error message, "Entry must be a valid two-letter state abbreviation" if the user enters anything besides two upper-case letters. 
    @If(@Matches(US_State;"{A-Z}{A-Z}");@Success;@Failure("Entry must be a valid two-letter state abbreviation"))
  7. This example returns 0 because no item in the second list matches an item in the first list.
    @Text(@Matches("one" : "two" : "three"; "four" : "five" : "six"))
  8. This example returns 1 because one item in the second list matches an item in the first list.
    @Text(@Matches("one" : "two" : "three"; "three" : "four" : "five" : "six"))