<doc>
  <legacy_id>1781</legacy_id>
  <name>matchText</name>
  <type>function</type>
  <syntax>
    <example>matchText(<i>string</i>,<i>regularExpression</i>[,<i>foundTextVarsList</i>])</example>
  </syntax>
  <library></library>
  <objects>
  </objects>
  <synonyms>
  </synonyms>
  <classification>
  </classification>
  <references>
    <command tag="find">find Command</command>
    <command tag="filter">filter Command</command>
  </references>
  <history>
    <introduced version="1.0">Added.</introduced>
    <changed version="2.0"></changed>
  </history>
  <platforms>
    <mac/>
    <windows/>
    <linux/>
    <ios/>
    <android/>
  </platforms>
  <classes>
    <desktop/>
    <server/>
    <web/>
    <mobile/>
  </classes>
  <security>
  </security>
  <summary><glossary tag="return">Returns</glossary> true if a <glossary tag="regular expression">regular expression</glossary> is found in the specified <keyword tag="string">string</keyword>, false otherwise.</summary>
  <examples>
    <example>matchText("Goodbye","bye")</example>
    <example>matchText("Goodbye","^Good")</example>
    <example>matchText(phoneNumber,"([0-9]+)-([0-9]+-[0-9]+)",areaCode,phone)</example>
  </examples>
  <description>
    <p>Use the <b>matchText</b> <control_st tag="function">function</control_st> to check whether a <keyword tag="string">string</keyword> contains a specified pattern.</p><p/><p><b>Parameters:</b></p><p>The <i>string</i> is any <glossary tag="expression">expression</glossary> that <glossary tag="evaluate">evaluates</glossary> to a <keyword tag="string">string</keyword>.</p><p/><p>The <i>regularExpression</i> is any <glossary tag="expression">expression</glossary> that evaluates to a <glossary tag="regular expression">regular expression</glossary>.</p><p/><p>The optional <i>foundTextVarsList</i> consists of one or more names of existing <glossary tag="variable">variables</glossary>, separated by commas.</p><p/><p><b>Value:</b></p><p>The <b>matchText</b> <control_st tag="function">function</control_st> returns true or false.</p><p/><p><b>Comments:</b></p><p>If the <i>regularExpression</i> includes a pair of parentheses, the substring matching the part of the <glossary tag="regular expression">regular expression</glossary> inside the parentheses is placed in the first <glossary tag="variable">variable</glossary> in the <i>foundTextVarsList</i>. Additional substrings, matching additional parenthetical expressions within the <i>regularExpression</i>, are placed in additional <glossary tag="variable">variables</glossary> in the <i>foundTextVarsList</i>. The number of parenthetical expressions in the <i>regularExpression</i> should match the number of <glossary tag="variable">variables</glossary> in the <i>foundTextVarsList</i>.</p><p/><p>If the <b>matchText</b> <control_st tag="function">function</control_st> returns false, the <glossary tag="value">values</glossary> of the <glossary tag="variable">variables</glossary> in the <i>foundTextVarsList</i> are not changed.</p><p/><p>For example, the following <b>matchText</b> <glossary tag="function call">function call</glossary> extracts the user name and email address from a typical email "From" line:</p><p/><p>  matchText(myVar,"^From: (.*) &lt;(.+@.+)&gt;",userName,userAddress)</p><p/><p>There are two parenthetical expressions in the <i>regularExpression</i> above: "(.*)" and  "(.+@.+)". If the function returns true--that is, if the <keyword tag="string">string</keyword> 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.</p><p/><p>The <i>string</i> and <i>regularExpression</i> are always <href tag="../glossary/casedashsensitive.xml">case-sensitive</href>, regardless of the setting of the <property tag="caseSensitive">caseSensitive</property> <glossary tag="property">property</glossary>. (If you need to make a <href tag="../glossary/casedashinsensitive.xml">case-insensitive</href> comparison, use "(?i)" at the start of the <i>regularExpression</i> to make the match case-insensitive.)</p><p/><p><img src="202653"/> <b>Important!</b> It is no longer necessary to create the variables in the <i>foundTextVarsList </i>before the <b>matchText</b> function is called. These are now created by the compiler, and will appear in the <function tag="localNames">localNames</function> of the handler or function in which the <b>matchText</b> was called from.</p><p/><p>The <b>matchText</b> and <function tag="matchChunk">matchChunk</function> <glossary tag="function">functions</glossary> return the same <function tag="value">value</function>, given the same <i>string</i> and <i>regularExpression</i>. The difference between the two is that the <b>matchText</b> <control_st tag="function">function</control_st> records the text of matched substrings in the optional <i>foundTextVarsList</i>, which the <function tag="matchChunk">matchChunk</function> <control_st tag="function">function</control_st> records the character positions of the matched substrings.</p><p/><p><img src="202651"/> <b>Tip:</b> LiveCode implements <glossary tag="regular expression">regular expressions</glossary> compatible with the PCRE library. For detailed information about <glossary tag="regular expression">regular expression</glossary> elements you can use with this <control_st tag="function">function</control_st>, see the PCRE manual at &lt;<u>http://www.pcre.org/man.txt</u>&gt;.</p><p/><p><b>Changes:</b></p><p>The regular expression format changed in version 2.0 to use PCRE compatible syntax.</p>
  </description>
</doc>