matchText

Typefunction
DictionaryLCS
LibraryLiveCode Script
Syntax
matchText(<string>, <regularExpression> [, <foundTextVarsList>])
Summary

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

Introduced1.0
Changes

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

OSmac, windows, linux, ios, android
Platformsdesktop, server, mobile
Parameters
NameTypeDescription
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.

Example
matchText("Goodbye","bye")
matchText("Goodbye","^Good")
matchText(phoneNumber,"([0-9]+)-([0-9]+-[0-9]+)",areaCode,phone)
Values
NameTypeDescription
return

The matchText function returns true or false.

RelatedKeyword: string
Property: caseSensitive
Command: find, filter
Function: matchChunk, value, localNames
Control Structure: function
Glossary: property, return, variable, value, function call, regular expression, case-sensitive, case-insensitive, function
Description

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 function 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: (.*) &lt;(.+@.+)&gt;",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.)

Important: 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.

The matchText and matchChunk functions return the same value, given the same string and regularExpression. The difference between the two is that the matchText function records the text of matched substrings in the optional foundTextVarsList, which the matchChunk function 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 pattern documentation at http://www.pcre.org/original/doc/html/pcrepattern.html.