UnicodePositionIn and UnicodePositionOf (Unicode functions)

The position of one string inside another (Unicode class)

These 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

%number	A numeric variable to receive the position of the first occurrence of the needle character string in the haystack string, starting at the implicit or explicit starting position. If needle is not found in haystack, %position is set to 0.
unicode	The method object string. Depending upon whether the UnicodePositionIn or UnicodePositionOf method is being used, unicode may be either the: search target needle, when called as UnicodePositionIn the search space haystack, when called as UnicodePositionOf
string	The argument string. Depending upon whether the UnicodePositionIn or UnicodePositionOf method is being used, string may be either the: search target needle, when called as UnicodePositionOf the search space haystack, when called as UnicodePositionIn
start	This optional, but name-required argument is a number specifying the position in the haystack string at which to start searching for the needle 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 (haystack plus one, minus the length of needle) returns a zero, because there are not enough characters in haystack to satisfy the search criteria.
• UnicodePositionIn / UnicodePositionOf do exactly the same thing. The only difference between them is the meaning assigned to the method object unicode and string arguments.
  • In UnicodePositionOf, the haystack is the method object and the needle is the argument string.
  • In UnicodePositionIn the method object unicode and first argument string meansings are reversed.

  Which method is preferable will depend on the application, and, in many cases, it will be quite arbitrary which one is used.

• UnicodePositionIn / UnicodePositionOf are analogous to the String intrinsics PositionIn and PositionOf.
• UnicodePositionIn / 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 an EBCDIC String. The Unicode trademark character has no valid translation to EBCDIC.

   %u is unicode initial('Model 204™':U) %posTM = %u:PositionOf('™':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

Float class String class Unicode class	List of Float methods List of String methods List of Unicode methods List of Intrinsic methods	Float methods syntax String methods syntax Unicode methods syntax
Notation conventions for methods