IsMatch, Match, and MatchAll functions

Applies to: Canvas apps Cards Copilot Studio Model-driven apps Power Platform CLI Dataverse functions Power Pages

Tests for a match or extracts parts 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 submatches.

Use IsMatch to validate what a user typed in a Text input control. For example, confirm whether the user 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 fix the entry.

Use Match to extract the first text string that matches a pattern and MatchAll to extract all text strings that match. Extract submatches 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 use MatchAll to split a text string, consider using the Split function, which is simpler 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 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 that match 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 Match options for ways to modify this behavior.)

In the pattern language, the 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. For example, you can match the string "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 matches the letter "A" followed by one or more digits.

Power Apps uses a different definition for Match.EMail and Match.Hyphen. Evaluate Text( Match.Email ) to see the regular expression used by your host.

Regular expressions

The pattern they these functions use is called a regular expression. Power Fx's specific dialect of regular expressions is detailed in Regular expressions in Power Fx.

Regular expressions are powerful and serve a wide variety of purposes. They can also 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 online.

Regular expressions have a long history and are available in many programming languages. Every programming language has its own dialect of regular expressions, and there are few standards. We strive to ensure the same regular expression gives the same result across all Power Fx implementations. Compatibility isn't easy to accomplish as Power Fx runs on top of JavaScript and .NET which have significant differences. To accommodate running on different platforms, Power Fx regular expressions are limited to a subset of features that are widely supported across the industry.

As a result, some regular expressions that may work in other environments may be blocked or require a tweak in Power Fx. Authoring time errors are reported as unsupported features are encountered. This is one of the reasons that the regular expression and options must be an authoring time constant and not dynamic (for example, provided in a variable).

Here are some basic elements of regular expressions that build up complexity in parsing a number.

These examples only give a small taste of what regular expressions can do. They are commonly used to validate ID numbers, email addresses, phone numbers, dates and times, and to extract information from all kinds of text files. Continue your journey by reading Regular expressions in Power Fx, experiment, and use the web to learn more.

Match options

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

Using MatchAll is the same as 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 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. Options must be a constant formula without variables, data sources, or other dynamic references that change as the app runs.

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. Options must be a constant formula without any variables, data sources, or other dynamic references that change as the app runs.

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 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. Options must be a constant formula without variables, data sources, or other dynamic references that change as the app runs.

IsMatch examples

Ordinary characters

Imagine your app has a Text input control named TextInput1. Users enter values into this control to store them in a database.

Users type 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 submatches individually. To do this, 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.	{ FullMatch: "The", 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.
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.
MatchAll( pangram, "\b\wo\w\b" )	Finds all three-letter words with an "o" in the middle. "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", 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. To see all the words on one screen, resize the gallery's template and the label control.