View source for UnicodePositionIn and UnicodePositionOf (Unicode functions)

{{Template:Unicode:UnicodePositionIn and UnicodePositionOf subtitle}}

The <var>UnicodePositionIn</var> and <var>UnicodePositionOf</var> functions return the numeric position of the first occurrence of one character string (the "needle") inside another ("the haystack"). The search respects character case. The difference between the two methods is that for <var>UnicodePositionIn</var>, the method object string is the "needle" and the first argument is the "haystack," whereas for <var>UnicodePositionOf</var>, the first argument string is the "needle" and the method object string is the "haystack."  Which method is more convenient to use will be application dependent.

==Syntax==
{{Template:Unicode:UnicodePositionIn syntax}}
{{Template:Unicode:UnicodePositionOf syntax}}

===Syntax terms===
<table class="syntaxTable">
<tr><th>%position</th>
<td>A variable to receive the character position of the first occurrence of the "needle" <var>Unicode</var> string in the "haystack" <var>Unicode</var> string, starting at the implicit or explicit starting character position. If the "needle" is not found in the "haystack," <var class="term">%position</var> is set to 0. Whether the method object or the first argument is the "needle" or "haystack" depends on the method that is called.</td></tr>

<tr><th>unicode</th>
<td>The method object <var>Unicode</var> string; either:
<ul>
<li>the search target "needle," when called as <var>UnicodePositionIn</var>
<li>the search space "haystack," when called as <var>UnicodePositionOf</var>
</ul></td></tr>

<tr><th>haystack</th>
<td>In <var>UnicodePositionIn</var>, the search space <var>Unicode</var> string within which to look for the <var class="term">unicode</var> method object (the "needle").</td></tr>  

<tr><th>needle</th>
<td>In <var>UnicodePositionOf</var>, the search target <var>Unicode</var> string to be searched for within the <var class="term">unicode</var> method object (the "haystack").</td></tr>

<tr><th><var>Start</var></th>
<td>An optional, [[Notation conventions for methods#Named parameters|name required]], number specifying the character position in the "haystack" <var>Unicode</var> string at which to start searching for the "needle" <var>Unicode</var> string. <var>Start</var> defaults to 1, meaning that the search begins at the first character in the "haystack."</td></tr>
</table>

==Usage notes==
<ul>
<li>The <var>Start</var> position must be a positive number.  A zero or negative number results in request cancellation.  Specifying a <var>Start</var> position greater than the length of the "haystack" plus one, minus the length of <var class="term">needle</var> returns a zero, because there are not enough characters in the "haystack" to satisfy the search criteria.
<li><var>UnicodePositionIn</var> and <var>UnicodePositionOf</var> are available as of <var class="product">Sirius Mods</var> Version 7.5.
</ul>

==Examples==
<ol>
<li>
The following fragment contains three calls to <var>UnicodePositionOf</var>:
<p class="code">%s is unicode initial('This is a test')
[[PrintText statement|printText]] {%s:unicodePositionOf('is')}
printText {%s:unicodePositionOf('is', start=4)}
printText {%s:unicodePositionOf('is', start=7)}
</p>
The result is: 
<p class="output">3
6
0
</p>

<li>The following fragment contains three calls to <var>UnicodePositionIn</var>:
<p class="code">%s is unicode initial('spl')
printText {%s:unicodePositionIn('splish splash')}
printText {%s:unicodePositionIn('splish splash', start=4)}
printText {%s:unicodePositionIn('splish splash', start=9)}
</p>

The result is:
<p class="output">1
8
0
</p>

<li>The following sequence, which uses the [[U (String function)|U function]] to specify the Unicode trademark character (U+2122), produces a conversion error.  The second statement fails when the method attempts to implicitly convert the <var>Unicode</var> <var class="term">needle</var> character to EBCDIC. The Unicode trademark character has no valid translation to EBCDIC.
<p class="code">%u is unicode initial('Model 204&amp;#x2122;':[[U (String_function)|U]])
%posTM = %u:PositionOf('&amp;#x2122;':U)
print %posTM
</p>
However, given <code>%u</code> as defined above, here is an alternative solution that uses other [[Intrinsic classes|intrinsic]] methods to return the hex value of the trademark character:
<p class="code">%pos is float
%pos = %u:[[UnicodeUntranslatablePosition (Unicode function)|UnicodeUntranslatablePosition]]
printtext {~} is: {%u:[[UnicodeChar (Unicode function)|unicodeChar]](%pos):[[UnicodeToUtf16 (Unicode function)|unicodeToUtf16]]:[[StringToHex (String function)|stringToHex]]}
</p>

The result is:
<p class="output">%u:unicodeChar(%pos):unicodeToUtf16:stringToHex is: 2122
</p>
</ol>

==See also==
<ul>
<var>UnicodePositionIn</var> and <var>UnicodePositionOf</var> are analogous to the <var>[[PositionIn and PositionOf (String functions)|PositionIn]]</var> and <var>[[PositionIn and PositionOf (String functions)|PositionOf]]</var> <var>String</var> methods.
</ul>

{{Template:Unicode:UnicodePositionIn and UnicodePositionOf footer}}