IsMatch, Match, and MatchAll functions

Applies to: Canvas apps Model-driven apps Power Platform CLI

Tests for a match or extracts portions of a text string based on a pattern.

Description

The IsMatch function tests whether a text string matches a pattern that can comprise ordinary characters, predefined patterns, or a regular expression. The Match and MatchAll functions return what was matched, including sub-matches.

Use IsMatch to validate what a user has typed in a Text input control. For example, you can confirm whether the user has entered a valid email address before the result is saved to your data source. If the entry doesn't match your criteria, add other controls that prompt the user to correct the entry.

Use Match to extract the first text string that matches a pattern and MatchAll to extract all text strings that match. You can also extract sub-matches to parse complex strings.

Match returns a record of information for the first match found, and MatchAll returns a table of records for every match found. The record or records contain:

These functions support MatchOptions. By default:

• These functions perform a case-sensitive match. Use MatchOptions.IgnoreCase to perform case-insensitive matches.
• IsMatch matches the entire text string (Complete MatchOption), while Match and MatchAll search for a match anywhere in the text string (Contains MatchOption). Use Complete, Contains, BeginsWith, or EndsWith as appropriate for your scenario.

IsMatch returns true if the text string matches the pattern or false if it doesn't. Match returns blank if no match is found that can be tested with the IsBlank function. MatchAll returns an empty table if no match is found that can be tested with the IsEmpty function.

If you're using MatchAll to split a text string, consider using the Split function, which is simpler to use and faster.

Patterns

The key to using these functions is in describing the pattern to match. You describe the pattern in a text string as a combination of:

• Ordinary characters, such as "abc" or "123".
• Predefined patterns, such as Letter, MultipleDigits, or Email. (The Match enum defines these patterns.)
• Regular-expression codes, such as "\d+\s+\d+" or "[a-z]+".

Combine these elements by using the string-concatenation operator &. For example, "abc" & Digit & "\s+" is a valid pattern that matches the characters "a", "b", and "c", followed by a digit from 0 to 9, followed by at least one whitespace character.

Ordinary characters

The simplest pattern is a sequence of ordinary characters to be matched exactly.

For example, when used with the IsMatch function, the string "Hello" matches the pattern "Hello" exactly. No more and no less. The string "hello!" doesn't match the pattern because of the exclamation point on the end and because the case is wrong for the letter "h". (See MatchOptions for ways to modify this behavior.)

In the pattern language, certain characters are reserved for special purposes. To use these characters, either prefix the character with a \ (backslash) to indicate that the character should be taken literally, or use one of the predefined patterns described later in this topic. This table lists the special characters:

For example, you can match "Hello?" by using the pattern "Hello\?" with a backslash before the question mark.

Predefined patterns

Predefined patterns provide a simple way to match either one of a set of characters or a sequence of multiple characters. Use the string-concatenation operator & to combine your own text strings with members of the Match enum:

For example, the pattern "A" & MultipleDigits will match the letter "A" followed by one or more digits.

Regular expressions

The pattern that these functions use is a regular expression. The ordinary characters and predefined patterns that are described earlier in this topic help build regular expressions.

Regular expressions are very powerful, available in many programming languages, and used for a wide variety of purposes. They can also often look like a random sequence of punctuation marks. This article doesn't describe all aspects of regular expressions, but a wealth of information, tutorials, and tools are available on the web.

Regular expressions come in different dialects, and Power Apps uses a variant of the JavaScript dialect. See regular-expression syntax for an introduction to the syntax. Named sub-matches (sometimes called named capture groups) are supported:

• Named sub-matches: (?<name> ...)
• Named backreferences: \k<name>

In the Match enum table earlier in this topic, each enum appears in the same row as its corresponding regular expression.

Match options

You can modify the behavior of these functions by specifying one or more options, which you can combine by using the string- concatenation operator (&).

Using MatchAll is equivalent to using the standard "g" modifier for regular expressions.

Syntax

IsMatch( Text, Pattern [, Options ] )

• Text – Required. The text string to test.
• Pattern – Required. The pattern to test as a text string. Concatenate predefined patterns that the Match enum defines, or provide a regular expression. Pattern must be a constant formula without any variables, data sources, or other dynamic references that change as the app runs.
• Options – Optional. A text-string combination of MatchOptions enum values. By default, MatchOptions.Complete is used.

Match( Text, Pattern [, Options ] )

• Text – Required. The text string to match.
• Pattern – Required. The pattern to match as a text string. Concatenate predefined patterns that the Match enum defines, or provide a regular expression. Pattern must be a constant formula without any variables, data sources, or other dynamic references that change as the app runs.
• Options – Optional. A text-string combination of MatchOptions enum values. By default, MatchOptions.Contains is used.

MatchAll( Text, Pattern [, Options ] )

• Text – Required. The text string to match.
• Pattern – Required. The pattern to match as a text string. Concatenate predefined patterns that the Match enum defines, or provide a regular expression. Pattern must be a constant formula without any variables, data sources, or other dynamic references that change as the app runs.
• Options – Optional. A text-string combination of MatchOptions enum values. By default, MatchOptions.Contains is used.

IsMatch examples

Ordinary characters

Imagine that your app contains a Text input control named TextInput1. The user enters values into this control to be stored in a database.

The user types Hello world into TextInput1.

Predefined patterns

Regular expressions

Match and MatchAll examples

Let's drill into that last example. If you wanted to convert this string to a date/time value using the Time function, you must pass in the named sub-matches individually. To do this, you can use the With function operating on the record that Match returns:

With(
    Match( "PT2H1M39S", "PT(?:(?<hours>\d+)H)?(?:(?<minutes>\d+)M)?(?:(?<seconds>\d+)S)?" ),
   Time( Value( hours ), Value( minutes ), Value( seconds ) )
)

For these examples, add a Button control, set its OnSelect property to this formula, and then select the button:

Set( pangram, "The quick brown fox jumps over the lazy dog." )

Formula	Description	Result
Match( pangram, "THE", IgnoreCase )	Find all matches of "THE" in the text string that the pangram variable contains. The string contains two matches, but only the first is returned because you're using Match and not MatchAll. The SubMatches column is empty because no sub-matches were defined.	{ FullMatch: "The", SubMatches: [ ], StartMatch: 32 }
MatchAll( pangram, "the" )	Find all matches of "the" in the text string that the pangram variable contains. The test is case sensitive, so only the second instance of "the" is found. The SubMatches column is empty because no sub-matches were defined.
MatchAll( pangram, "the", IgnoreCase )	Find all matches of "the" in the text string that the pangram variable contains. In this case, the test is case insensitive, so both instances of the word are found. The SubMatches column is empty because no sub-matches were defined.
MatchAll( pangram, "\b\wo\w\b" )	Finds all three-letter words with an "o" in the middle. Note that "brown" is excluded because it's not a three-letter word and, therefore, fails to match "\b" (word boundary).
Match( pangram, "\b\wo\w\b\s\*(?<between>\w.+\w)\s\*\b\wo\w\b" )	Matches all the characters between "fox" and "dog".	{ between: "jumps over the lazy", FullMatch: "fox jumps over the lazy dog", SubMatches: [ "jumps over the lazy" ], StartMatch: 17 }

To see the results of MatchAll in a gallery:

1. In an empty screen, insert a blank vertical Gallery control.

2. Set the gallery's Items property to MatchAll( pangram, "\w+" ) or MatchAll( pangram, MultipleLetters ).

   

3. Select "Add an item from the Insert tab" in the middle of the gallery control to select the template of the gallery.

4. Add a Label control to the gallery's template.

5. Set the label's Text property to ThisItem.FullMatch.

   The gallery is filled with each word in our example text. Resize the gallery's template and the label control in order to see all the words on one screen.