MatchText

Returns true if a regular expression is found in the specified string, false otherwise.

Built-in Function handler

Syntax:

matchText(<string>, <regularExpression> [, <foundTextVarsList>])

Examples:

matchText("Goodbye","bye")

matchText("Goodbye","^Good")

matchText(phoneNumber,"([0-9]+)-([0-9]+-[0-9]+)",areaCode,phone)

Use the matchText function to check whether a string contains a specified pattern.

If the regularExpression includes a pair of parentheses, the substring matching the part of the regular expression inside the parentheses is placed in the first variable in the foundTextVarsList. Additional substrings, matching additional parenthetical expressions within the regularExpression, are placed in additional variables in the foundTextVarsList. The number of parenthetical expressions in the regularExpression should match the number of variables in the foundTextVarsList.

If the matchText returns false, the values of the variables in the foundTextVarsList are not changed.

For example, the following matchText function call extracts the user name and email address from a typical email "From" line:

matchText(myVar,"^From: (.*) <(.+@.+)>",userName,userAddress)

There are two parenthetical expressions in the regularExpression above: "(.*)" and "(.+@.+)". If the function returns true--that is, if the string in myVar matches the regular expression--then the substring of myVar that matches the first of these parenthetical expressions is placed in the variable called userName; the second is placed in the variable userAddress.

The string and regularExpression are always case-sensitive, regardless of the setting of the caseSensitive property. (If you need to make a case-insensitive comparison, use "(?i)" at the start of the regularExpression to make the match case-insensitive.)

It is no longer necessary to create the variables in the foundTextVarsList before the matchText function is called. These are now created by the compiler, and will appear in the localNames of the handler or function in which the matchText was called from.

You can found all occurrences in a text using matchText and offset together, for examle let's create a list of all addresses in a email web page:

repeat while matchText(myText,  "mailto:(.*@.*?)" & quote , t2)      
      put t2 & comma after allEmailsAddresses
      put offset(t2,myText) into tnc
      put char ((the number of chars of t2) + tnc ) to -1 of myText into myText
   end repeat

Please not that the "?" char make the search not greedy, so only the smallest occurrence chunk is considered.

The matchText and matchChunk functions return the same value, given the same string and regularExpression. The difference between the two is that the matchText records the text of matched substrings in the optional foundTextVarsList, which the matchChunk records the character positions of the matched substrings.

Tip: LiveCode implements regular expressions compatible with the PCRE library. For detailed information about regular expression elements you can use with this function, see the PCRE manual at http://www.pcre.org.

Changes: The regular expression format changed in version 2.0 to use PCRE compatible syntax.

Parameters:

• string (string):
• regularExpression:Any expression that evaluates to a regular expression.
• foundTextVarsList: The optional foundTextVarsList consists of one or more names of existing variables, separated by commas.
• Returns (bool): The matchText function returns true or false.

See also: matchChunk (function), value (function), localNames (function), caseSensitive (property), offset, wordOffset (function), itemOffset (function), length (function), lineOffset (function), begins with