UnicodePositionIn and UnicodePositionOf (Unicode functions): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
Line 15: Line 15:
<li>the search space "haystack," when called as <var>UnicodePositionOf</var></ul></td></tr>
<li>the search space "haystack," when called as <var>UnicodePositionOf</var></ul></td></tr>
<tr><th>haystack</th>
<tr><th>haystack</th>
<td>The search space <var>Unicode</var> string in which the search target <var class="term">needle</var> is to be located.</td></tr>
<td>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>The search target <var>Unicode</var> string to be located in the search space <var class="term">haystack</var> <var>Unicode</var> string.</td></tr>
<td>The search target <var>Unicode</var> string to be located in the search space <var class="term">haystack</var> <var>Unicode</var> string.</td></tr>

Revision as of 02:37, 9 March 2011

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 inside another (character case respected). The difference between the two methods is that for UnicodePositionIn, the method object string is located in the first argument string, whereas for UnicodePositionOf, the first argument string is located in the method object string. 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 string in the haystack string, starting at the implicit or explicit starting character position. If needle is not found in haystack, %position is set to 0.
unicode The method object Unicode string; either:
  • the search target "needle," when called as UnicodePositionIn
  • the search space "haystack," when called as UnicodePositionOf
haystack The search space Unicode string within which to look for the unicode method object (the "needle").
needle The search target Unicode string to be located in the search space haystack Unicode string.
Start An optional, but NameRequired, number specifying the character position in the search space haystack Unicode string at which to start searching for the search target needle Unicode string. Start defaults to 1, meaning that the search begins at the first character in 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 do exactly the same thing. The only difference between them is that in UnicodePositionOf, the haystack is the method object unicode and the needle is the first argument. In UnicodePositionIn, these roles are reversed: the needle is the method object unicode and the haystack is the first argument. Which method is preferable will depend on the application, and, in many cases, it will be quite arbitrary which one is used.
  • Available as of Sirius Mods Version 7.5, UnicodePositionIn and UnicodePositionOf are analogous to the PositionIn and PositionOf String methods.

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