<doc>
  <legacy_id>1904</legacy_id>
  <name>matchChunk</name>
  <type>function</type>
  <syntax>
    <example>matchChunk(<i>string</i>,<i>regularExpression</i>[,<i>positionVarsList</i>])</example>
  </syntax>
  <library></library>
  <objects>
  </objects>
  <synonyms>
  </synonyms>
  <classification>
  </classification>
  <references>
    <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>matchChunk("Hello","Hel") <code><i>-- returns true</i></code></example>
    <example>matchChunk("Hello","o$") <code><i>-- also returns true</i></code></example>
    <example>matchChunk(the short name of this stack,"^rev") <code><i>-- starts with "rev"</i></code></example>
    <example>matchChunk(field "Title",myExpr,startMatch,endMatch)</example>
  </examples>
  <description>
    <p>Use the <b>matchChunk</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 <glossary tag="evaluate">evaluates</glossary> to a <glossary tag="regular expression">regular expression</glossary>.</p><p/><p>The optional <i>positionVarsList</i> consists of an even number of existing <glossary tag="variable">variables</glossary>, separated by commas.</p><p/><p><b>Value:</b></p><p>The <b>matchChunk</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 position of the substring matching the part of the <glossary tag="regular expression">regular expression</glossary> inside the parentheses is placed in the <glossary tag="variable">variables</glossary> in the <i>positionVarsList</i>. The number of the first <keyword tag="character">character</keyword> in the matching substring is placed in the first <glossary tag="variable">variable</glossary> in the <i>positionVarsList</i>, and the number of the last <keyword tag="character">character</keyword> is placed in the second <glossary tag="variable">variable</glossary>. Additional starting and ending positions, matching additional parenthetical expressions, are placed in additional pairs of <glossary tag="variable">variables</glossary> in the <i>positionVarsList</i>. If the <b>matchChunk</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>positionVarsList</i> are not changed.</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><code/><img src="202653"/> <b>Important!</b><code/> Variables in the <i>positionVarsList</i> must be created before the <b>matchChunk</b> <control_st tag="function">function</control_st> is <glossary tag="call">called</glossary>. The <b>matchChunk</b> <control_st tag="function">function</control_st>, unlike the <command tag="put">put</command> <glossary tag="command">command</glossary>, does not create them automatically.</p><p/><p>The <b>matchChunk</b> and <function tag="matchText">matchText</function> <glossary tag="function">functions</glossary> <constant tag="return">return</constant> 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>matchChunk</b> <control_st tag="function">function</control_st> records the positions of matched substrings in the optional <i>positionVarsList</i> variables, while the <function tag="matchText">matchText</function> <control_st tag="function">function</control_st> records the substrings themselves.</p><p/><p><code/><img src="202651"/> <b>Tip:</b><code/> 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>