<doc>

<legacy_id>1136</legacy_id>

<name>find</name>

<type>command</type>

<syntax>

<example>find [<i>form</i>] <i>textToFind</i> [in <i>field</i>]</example>

<example>find empty</example>

</syntax>

<library></library>

<objects>

</objects>

<synonyms>

</synonyms>

<classification>

<category>Database Operations</category>

</classification>

<references>

<property tag="caseSensitive">caseSensitive Property</property>

<property tag="dontSearch">dontSearch Property</property>

<function tag="foundChunk">foundChunk Function</function>

<function tag="foundField">foundField Function</function>

<function tag="foundLine">foundLine Function</function>

<function tag="foundLoc">foundLoc Function</function>

<function tag="foundText">foundText Function</function>

<command tag="mark">mark Command</command>

<function tag="matchText">matchText Function</function>

<keyword tag="normal">normal Keyword</keyword>

<function tag="offset">offset Function</function>

<command tag="replace">replace Command</command>

<command tag="unmark">unmark Command</command>

<command tag="sort">sort Command</command>

<keyword tag="characters">characters Keyword</keyword>

<keyword tag="string">string Keyword</keyword>

<keyword tag="whole">whole Keyword</keyword>

<property tag="mark">mark Property</property>

</references>

<history>

<introduced version="1.0">Added.</introduced>

</history>

<platforms>

<mac/>

<windows/>

<linux/>

<ios/>

<android/>

</platforms>

<classes>

<desktop/>

<server/>

<web/>

<mobile/>

</classes>

<security>

</security>

<summary>Searches the <glossary tag="field">fields</glossary> of the <glossary tag="current stack">current stack</glossary>.</summary>

<examples>

<example>find "heart"</example>

<example>find string "beat must go on" in field "Quotes"</example>

</examples>

<description>

<p>Use the <b>find</b> <glossary tag="command">command</glossary> to search for text.</p><p/><p><b>Parameters:</b></p><p>The <i>form</i> is one of the following words:</p><p>* <code>normal</code></p><p>* <code>characters </code>or<code> character </code>(or<code> chars </code>or<code> char</code>)</p><p>* <code>words </code>or<code> word</code></p><p>* <code>string</code></p><p>* <code>whole</code></p><p>If no <i>form</i> is specified, the<code> find normal </code>form is used.</p><p/><p>The <i>textToFind</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>field</i> is any <glossary tag="expression">expression</glossary> that evaluates to a <href tag="reference/object_reference.rev">field reference</href>. If the <i>field</i> is not specified, the <b>find</b> <glossary tag="command">command</glossary> searches all the <glossary tag="field">fields</glossary> in the <glossary tag="current stack">current stack</glossary> (except <glossary tag="field">fields</glossary> whose <property tag="dontSearch">dontSearch</property> <glossary tag="property">property</glossary> is set to true).</p><p/><p><b>Comments:</b></p><p>The <b>find</b> <glossary tag="command">command</glossary> starts searching after the previously-found text (if there was a previous <b>find</b> <glossary tag="command">command</glossary>) or at the beginning of the first <keyword tag="field">field</keyword> on the <glossary tag="current card">current card</glossary> (if not).</p><p/><p>When the search is successful, the card containing the text appears and a box is drawn around the found text. If the text is not found in the stack, the <b>result</b> <control_st tag="function">function</control_st> <glossary tag="return">returns</glossary> "Not found".</p><p/><p>The six forms of the <b>find</b> command search in different ways. The<code> find normal</code>,<code> find chars</code>, and<code> find words </code>forms search for each word in the <i>textToFind</i>, but the <keyword tag="words">words</keyword> don't have to be together to be found; they only have to all appear on the same <keyword tag="card">card</keyword>. <keyword tag="the">The</keyword> <code>find words</code> and <code>find whole</code>forms look for complete words only. The<code> find string </code>and<code> find whole </code>forms search for the <i>textToFind</i> as a unit.</p><p/><p>The<code> find normal </code>form looks for each word in the <i>textToFind</i> at the beginning of a <keyword tag="word">word</keyword>. For example,<code> find "ring bell" </code>finds "<b><i>ring</i></b>ing" and "<b><i>bell</i></b>tower", but not "b<b><i>ring</i></b>" or "Camp<b><i>bell</i></b>". All the words you specify must be in <glossary tag="field">fields</glossary> on the <keyword tag="card">card</keyword>, but they don't need to be in the same order, or even in the same <keyword tag="field">field</keyword>.</p><p/><p>The<code> find chars </code>form looks for each word in the <i>textToFind</i>, in any part of a <keyword tag="word">word</keyword>. Unlike the<code> find normal </code>form, the<code> find chars </code>form doesn't require that the words in the <i>textToFind</i> be found at the start of a <keyword tag="word">word</keyword> on the <keyword tag="card">card</keyword>. For example,<code> find chars "ring bell" </code>finds "b<b><i>ring</i></b>", "<b><i>ring</i></b>ing", "<b><i>bell</i></b>tower", and "Camp<b><i>bell</i></b>". As with the<code> find normal </code>form, all the words must be somewhere on the <keyword tag="card">card</keyword>, but they don't need to be in the same order, or in the same <keyword tag="field">field</keyword>.</p><p/><p>The<code> find words </code>form looks for each word in the <i>textToFind</i>. All the <keyword tag="words">words</keyword> must be complete <keyword tag="words">words</keyword>, not parts of <keyword tag="words">words</keyword>. For example,<code> find words "ring bell" </code>finds "ring" and "bell", but not "<b><i>ring</i>i</b>ng", "b<b><i>ring</i></b>", "<b><i>bell</i></b>tower", or "Camp<b><i>bell</i></b>". As with the<code> find normal </code>and<code> find chars </code>forms, all the words must be somewhere on the <keyword tag="card">card</keyword>, but they don't need to be in the same order, or in the same <keyword tag="field">field</keyword>.</p><p/><p>The<code> find string </code>form looks for the entire <i>textToFind</i> as a unit. Unlike the<code> find normal</code>,<code> find chars</code>, and <code> find words </code> forms, the<code> find string </code>form requires that the <i>textToFind</i> be found exactly: the <keyword tag="words">words</keyword> must be in the same order and in the same <keyword tag="field">field</keyword>, and not separated by other <keyword tag="words">words</keyword>. For example,<code> find string "ring bell" </code>finds "ring bell" and "b<b><i>ring</i></b> <b><i>bell</i></b>tower", but not "<b><i>ring</i></b> the <b><i>bell</i></b>" (extra word between "ring" and "bell"), "<b><i>Ringbell</i></b> Street" (no space between "ring" and "bell"), or "<b><i>bell</i></b> <b><i>ring</i></b>er" (words are in the wrong order).</p><p/><p>The<code> find whole </code>form looks for the entire <i>textToFind</i> as a unit. Like the<code> find words </code>form (and unlike the<code> find string </code>form), the<code> find whole </code>form requires that each word in the <i>textToFind</i> be found as a whole <keyword tag="word">word</keyword>, not part of a <keyword tag="word">word</keyword>. For example,<code> find whole "ring bell" </code>finds "ring bell", but not "b<b><i>ring</i></b> <b><i>bell</i></b>tower" (the "ring" and "bell" are parts of <keyword tag="words">words</keyword>, not whole <keyword tag="words">words</keyword>), "<b><i>ring</i></b> the <b><i>bell</i></b>" (extra word between "ring" and "bell"), "<b><i>Ringbell</i></b> Street" (no space between "ring" and "bell"), or "<b><i>bell</i></b> <b><i>ring</i></b>er" (words are in the wrong order).</p><p/><p><code/><b>Note:</b><code/> Because the<code> find normal</code>,<code> find words</code>, and<code> find whole </code>forms search for words or portions of <keyword tag="words">words</keyword>, they cannot find a <keyword tag="string">string</keyword> containing a space. The<code> find string </code>form can find a string containing a space, but cannot find a <keyword tag="string">string</keyword> that contains a <constant tag="return">return</constant> <keyword tag="character">character</keyword>.</p><p/><p>The<code> find empty </code>form of the <b>find</b> <glossary tag="command">command</glossary> removes the box from the last <keyword tag="word">word</keyword> found and <glossary tag="reset">resets</glossary> the <b>find</b> <glossary tag="command">command</glossary>, so that the next search starts from the beginning of the <glossary tag="current card">current card</glossary>, rather than the location of the next find. Going to another <keyword tag="card">card</keyword> also <glossary tag="reset">resets</glossary> the <b>find</b> <glossary tag="command">command</glossary>.</p><p/><p>The setting of the <b>caseSensitive</b> <glossary tag="property">property</glossary> determines whether the search considers uppercase and lowercase characters to be equivalent.</p><p/><p><code/><b>Note:</b><code/> The search does not consider characters that differ by a diacritical mark to be equivalent. For example,<code> find "mére" </code>will not find the word "mere".</p><p/><p>Usually, the <b>offset</b> and <function tag="matchText">matchText</function> <glossary tag="function">functions</glossary> are faster than the <b>find</b> <glossary tag="command">command</glossary>. But unlike these <glossary tag="function">functions</glossary>, the <b>find</b> <glossary tag="command">command</glossary> can search all the <glossary tag="field">fields</glossary> of a <object tag="stack">stack</object> at once, instead of one <glossary tag="container">container</glossary> at a time.</p><p/><p><code/><img src="202651"/> <b>Tip:</b><code/> To perform a batch search, set the <command tag="mark">mark</command> <glossary tag="property">property</glossary> of all <glossary tag="card">cards</glossary> where a match is found by using the<code> mark cards by finding </code>form of the <b>mark</b> <glossary tag="command">command</glossary>.</p>

</description>

</doc>