UnicodePositionIn and UnicodePositionOf (Unicode functions): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
mNo edit summary
 
Line 6: Line 6:
{{Template:Unicode:UnicodePositionIn syntax}}
{{Template:Unicode:UnicodePositionIn syntax}}
{{Template:Unicode:UnicodePositionOf syntax}}
{{Template:Unicode:UnicodePositionOf syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%position</th>
<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>
<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>
<tr><th>unicode</th>
<td>The method object <var>Unicode</var> string; either:
<td>The method object <var>Unicode</var> string; either:
<ul><li>the search target "needle," when called as <var>UnicodePositionIn</var>
<ul>
<li>the search space "haystack," when called as <var>UnicodePositionOf</var></ul></td></tr>
<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>
<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>   
<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>
<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>
<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>
<tr><th><var>Start</var></th>
<td>An optional, but <var>[[Methods#Named parameters|NameRequired]]</var>, 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>
<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>
</table>


Line 25: Line 32:
<ul>
<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>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|Sirius Mods]]</var> Version 7.5.
<li><var>UnicodePositionIn</var> and <var>UnicodePositionOf</var> are available as of <var class="product">Sirius Mods</var> Version 7.5.
</ul>
</ul>


==Examples==
==Examples==
<ol><li>
<ol>
<li>
The following fragment contains three calls to <var>UnicodePositionOf</var>:
The following fragment contains three calls to <var>UnicodePositionOf</var>:
<p class="code">%s is unicode initial('This is a test')
<p class="code">%s is unicode initial('This is a test')
Line 41: Line 49:
0
0
</p>
</p>
<li>The following fragment contains three calls to <var>UnicodePositionIn</var>:
<li>The following fragment contains three calls to <var>UnicodePositionIn</var>:
<p class="code">%s is unicode initial('spl')
<p class="code">%s is unicode initial('spl')
Line 53: Line 62:
0
0
</p>
</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.
<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;amp;amp;#x2122;':[[U (String_function)|U]])
<p class="code">%u is unicode initial('Model 204&amp;#x2122;':[[U (String_function)|U]])
%posTM = %u:PositionOf('&amp;amp;amp;#x2122;':U)
%posTM = %u:PositionOf('&amp;#x2122;':U)
print %posTM
print %posTM
</p>
</p>
Line 61: Line 71:
<p class="code">%pos is float
<p class="code">%pos is float
%pos = %u:[[UnicodeUntranslatablePosition (Unicode function)|UnicodeUntranslatablePosition]]
%pos = %u:[[UnicodeUntranslatablePosition (Unicode function)|UnicodeUntranslatablePosition]]
printtext {~} is: -
printtext {~} is: {%u:[[UnicodeChar (Unicode function)|unicodeChar]](%pos):[[UnicodeToUtf16 (Unicode function)|unicodeToUtf16]]:[[StringToHex (String function)|stringToHex]]}
  {%u:[[UnicodeChar (Unicode function)|unicodeChar]](%pos):[[UnicodeToUtf16 (Unicode function)|unicodeToUtf16]]:[[StringToHex (String function)|stringToHex]]}
</p>
</p>


Line 71: Line 80:


==See also==
==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>
<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}}
{{Template:Unicode:UnicodePositionIn and UnicodePositionOf footer}}

Latest revision as of 17:28, 6 November 2012

The position of one string inside another (Unicode class)


The UnicodePositionIn and UnicodePositionOf 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 UnicodePositionIn, the method object string is the "needle" and the first argument is the "haystack," whereas for UnicodePositionOf, 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

%position = unicode:UnicodePositionIn( haystack, [Start= number])

%position = unicode:UnicodePositionOf( needle, [Start= number])

Syntax terms

%position A variable to receive the character position of the first occurrence of the "needle" Unicode string in the "haystack" Unicode string, starting at the implicit or explicit starting character position. If the "needle" is not found in the "haystack," %position is set to 0. Whether the method object or the first argument is the "needle" or "haystack" depends on the method that is called.
unicode The method object Unicode string; either:
  • the search target "needle," when called as UnicodePositionIn
  • the search space "haystack," when called as UnicodePositionOf
haystack In UnicodePositionIn, the search space Unicode string within which to look for the unicode method object (the "needle").
needle In UnicodePositionOf, the search target Unicode string to be searched for within the unicode method object (the "haystack").
Start An optional, name required, number specifying the character position in the "haystack" Unicode string at which to start searching for the "needle" Unicode string. Start defaults to 1, meaning that the search begins at the first character in the "haystack."

Usage notes

  • The Start position must be a positive number. A zero or negative number results in request cancellation. Specifying a Start position greater than the length of the "haystack" plus one, minus the length of needle returns a zero, because there are not enough characters in the "haystack" to satisfy the search criteria.
  • UnicodePositionIn and UnicodePositionOf are available as of Sirius Mods Version 7.5.

Examples

  1. The following fragment contains three calls to UnicodePositionOf:

    %s is unicode initial('This is a test') printText {%s:unicodePositionOf('is')} printText {%s:unicodePositionOf('is', start=4)} printText {%s:unicodePositionOf('is', start=7)}

    The result is:

    3 6 0

  2. The following fragment contains three calls to UnicodePositionIn:

    %s is unicode initial('spl') printText {%s:unicodePositionIn('splish splash')} printText {%s:unicodePositionIn('splish splash', start=4)} printText {%s:unicodePositionIn('splish splash', start=9)}

    The result is:

    1 8 0

  3. The following sequence, which uses the 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 Unicode needle character to EBCDIC. The Unicode trademark character has no valid translation to EBCDIC.

    %u is unicode initial('Model 204&#x2122;':U) %posTM = %u:PositionOf('&#x2122;':U) print %posTM

    However, given %u as defined above, here is an alternative solution that uses other intrinsic methods to return the hex value of the trademark character:

    %pos is float %pos = %u:UnicodeUntranslatablePosition printtext {~} is: {%u:unicodeChar(%pos):unicodeToUtf16:stringToHex}

    The result is:

    %u:unicodeChar(%pos):unicodeToUtf16:stringToHex is: 2122

See also

    UnicodePositionIn and UnicodePositionOf are analogous to the PositionIn and PositionOf String methods.