Match Regular Expression function

Object information
Owning palette(s)	String palette
Type	Function
Requires	Basic Development Environment
Icon

The Match Regular Expression function searches for a regular expression in the input string beginning at the offset you enter. If the function finds a match, it splits the string into three substrings and any number of submatches. Resize the function to view any submatches found in the string.

Usage

Parameters

Data Type	Name	Required?	Description
	multiline?	No	multiline? specifies whether to treat the text in input string as a multiple-line string. This setting affects how the ^ and $ characters handle matches. If you set multiline? to FALSE (default), when you enter ^ at the beginning of a regular expression, the expression matches only the beginning of the string in input string. When you enter $ at the end of a regular expression, the expression matches only the end of the string in input string. If you set multiline? to TRUE, ^ matches the beginning of any line in input string and $ matches the end of any line in input string. Note The ^ character anchors the match to the beginning of a string when used as the first character of a pattern. If you add ^ to the beginning of a character class immediately after an open square bracket, the expression matches any character not in a given character class.
	ignore case?	No	ignore case? specifies whether the string search is case sensitive. If FALSE (default), the string search is case sensitive.
	input string	Yes	input string specifies the input string the function searches. This string cannot contain null characters.
	regular expression	Yes	regular expression specifies the pattern you want to search for in input string. If the function does not find a match, whole match and after match contain empty strings, before match contains the entire input string, offset past match returns –1, and all submatches outputs return empty strings. Place any substrings you want to search for in parentheses. The function returns any substring expressions it finds in substring 1..n. This string cannot contain null characters.
	offset	No	offset specifies the number of characters into input string at which the function starts searching for search string.
	error in	No	error in describes error conditions that occur before this node runs. This input provides standard error in functionality.
	before match	No	before match returns all the characters before the match.
	whole match	No	whole match returns all the characters that match the expression entered in regular expression. Any substring matches the function finds appear in the submatch outputs.
	after match	No	after match returns all the characters after the match.
	offset past match	No	offset past match returns the index in input string of the first character after the last match. If the VI does not find a match, offset past match returns –1.
	error out	No	error out contains error information. This output provides standard error out functionality.

Details

• This function is used to match one or more substrings in input string by evaluating a regular expression against it, where the regular expression ("regex") follows the standardized syntax defined by the Perl Compatible Regular Expression (PCRE) specification.
• Refer to the PCRE website at www.pcre.org for more detailed information about Perl Compatible Regular Expressions.
• From a cursory perspective, the Match Regular Expression node is functionally very similar to the Match Pattern function, but is much more powerful, arguably more versatile, and provides many additional options.
• The Match Regular Expression node executes much more slowly than the Match Pattern function. When executed relatively infrequently in an application, the difference is negligible, but when scaled and executed repeatedly, there is a noticeable performance penalty. Therefore, if the application does not require the power and complexity afforded by the Match Regular Expression function, the user may elect to use the Match Pattern function instead.
• Regular expression support is provided by the PCRE library package. Refer to <National Instruments>\_Legal Information directory for more information about the license under which the PCRE library package is redistributed.

Note The Match Regular Expression function does not support null characters (i.e. bytes with values of zero) in the input strings. If strings wired to this function include null characters, LabVIEW returns an error and the function may return unexpected results.

Grouping Patterns for Submatches

In straightforward use cases, the developer may simply rely on the value of the whole match terminal as the primary output of this function, as they would when using the Match Pattern function. For more complex use cases, multiple substrings from input string matching portions of the regular expression may be "captured," or returned separately from whole match as "submatches."

When captured groups are specified within the regex, the entirety of the match is predictably returned as the value of whole match, but smaller portions that are substrings of whole match are returned on separate output terminals.

In official PCRE parlance, these submatches are referred to as "captured groups." In the LabVIEW documentation for this function, the outputs for these captured groups are referred to as both "substrings" and "submatches" inconsistently.

The additional output terminals referred to as "Substring 1" .. "Substring n" are exposed by dragging the bottom of the function to expand it, similar to the behavior of the Scan From String function. These outputs are not depicted in the illustration at the top of this article.

Within the regular expression, the developer may specify that a portion of the match is to be captured and returned as a separate output by placing a subset of the regex within parentheses.

For example:

• Suppose Hello LabVIEW! is provided as the value of input string
• Also suppose that (el.)..(L..) is provided as the value of regular expression, wherein . may match any single character
• Upon execution of the Match Regular Expression function, the value of the whole match terminal is set to ello Lab
• Submatch 1 then has a value of ell
• Submatch 2 then has a value of Lab

If a captured group is nested within another captured group, the regular expression returns a submatch for the outer group before the inner group.

For example:

• Suppose again that Hello LabVIEW! is provided as the value of input string
• Also suppose that (.(el.).).(L..) is provided as the value of regular expression
• Upon execution of the Match Regular Expression function, the value of the whole match terminal is set to Hello Lab
• Submatch 1 then has a value of Hello
• Submatch 2 has a value of ell
• Submatch 3 has a value of Lab

In this example, Submatch 1 is Hello because the regular expression matches the outer character group before the inner group.

Avoiding Stack Overflow

Certain regular expressions that use repeated capturing groups (such as (.|\s)* or (a*)* ) require substantial resources to process when evaluated over large input strings, potentially leading to a stack overflow. Expressions involving captured groups that may cause excessive recursion are to be avoided for this reason. For example, evaluating the regular expression (.|\n)*A over a large input string may cause LabVIEW to crash. To avoid recursion, the regular expression (.|\n)*A may be rewritten as (?s).*A. The (?s) flag placed at the start of the regular expression instructs the compiler to include vertical white space characters when matching against the metacharacter, . (a period character in an expression). (.|\n)*A may also be rewritten as [^A]*A, which perhaps unintuitively includes vertical white space when matching characters other than "A" that precede "A".

As a general best practice, the developer may also wish to limit the allowable length of the input string to be evaluated by the regular expression.

It should also be noted that characters or expressions that form a group need not be captured as a submatch. To group characters as part of an expression without capturing them as output, they may form a non-capturing group. The syntactical difference is that a non-capturing group includes ?: after the opening (. For example, while (ABC) matches the string "ABC" and includes it as a submatch, (?:ABC) likewise groups the characters "ABC" together but does not return them as the value of a submatch output.

Tips and tricks

• Use back references to refer to previous partial matches in a regular expression. \1 refers to the first partial match, \2 to the second, and so on. For example, (cat|dog) \1 matches "cat cat" or "dog dog" but not "cat dog" or "dog cat".
• Commenting regular expressions is encouraged for readability. There are two methods by which to accomplish this, both native to PCRE's syntax and not specific to LabVIEW.
  1. Inline comments may be placed as in the following example: [A-Za-z\d]+(?#alphanumeric chars).+$ , where "alphanumeric chars" comprises the inline comment.
  2. More readable comments may be included by enabling commenting via the (?x) flag. The flag must be specified at the very start of the regular expression: Doing so causes the PCRE compiler to ignore both horizontal and vertical white space as well as comments at the ends of lines that begin with #. For example:

     (?x)       # Enable comments, ignore white space
     I Lab      # The literal characters "I lab"
     [WIEV]     # Any of {W, I, E, V}, case sensitive
     s\w        # literal "s" followed by \w, which is an alphanumeric char or _
     \hmuch     # horizontal white space (a tab or space) followed by "much"
     

     The reader should note that when the (?x) flag is in use, white space characters must be specified explicitly. e.g. \s \h \v \t \r \n etc.
• Unlike the expression syntax for the Match Pattern function, \s does not refer to a literal space character (ASCII 0x20).

White space characters are represented as follows:

White Space Characters

Escape	ASCII Value	Meaning
\t	0x09	Horizontal Tab (as from the tab key)
\n	0x0A	Line Feed
	0x0B	Vertical Tab (not commonly used)
\f	0x0C	Form Feed (not commonly used)
\r	0x0D	Carriage Return
	0x20	Space (as from the space bar)
\h	0x20 0x09	Space or Tab
\v	0x0A 0x0B 0x0C 0x0D	Line Feed, Vertical Tab, Form Feed, Carriage Return
\s	0x09 0x0A 0x0B 0x0C 0x0D 0x20	Union of characters included in \h and \v

XNode

This node is an example of how XNodes are used as a primitive node in LabVIEW. It utilizes the AdaptToInputs, Bounds, DisplayName, GenerateCode, GrowInfo, Help, Image, Initialize, Size, Terms, and UpdateStateWithRef abilities. The abilities used can be viewed after enabling the XNodeWizardMode INI flag. Many of the ability VIs are password protected.

If the user wishes to avoid using an XNode but retain the same functionality as the Match Regular Expression function, they may elect to substitute "Match Regular Expression_Execute.vi", which contains the core functionality used by the former. This VI is located in the directory, "/vi.lib/regexp/".

History

Version	Change(s)
	More info to come.

See also

• Match Pattern function
• XNodes

External links

• RegEx101 - A great resource for trying out your regular expression. Contains help, syntax highlighting, etc. Note LabVIEW uses PCRE, select this when using the website.
• Perl Compatible Regular Expressions (PCRE) website - The PCRE library is a set of functions that implement regular expression pattern matching using the same syntax and semantics as Perl 5.
• PCRE Pattern Manual Page - Detailed, official documentation of PCRE pattern syntax
• PCRE Syntax Manual Page - More abbreviated official documentation of PCRE pattern syntax
• Debuggex PCRE Cheat Sheet - A succinct reference for PCRE syntax