UnicodePositionIn and UnicodePositionOf (Unicode functions)

Position of first occurrence of one

These 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.

The UnicodePositionIn and UnicodePositionOf functions are available as of version 7.5 of the Sirius Mods.

Syntax

  %pos = needle:unicodePositionIn(haystack [, Start=spos])

  %pos = haystack:unicodePositionOf(needle [, Start=spos])

Syntax Terms

%pos

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, spos is set to 0.

needle

The character string to be located in the haystack string.

haystack

The character string in which needle is to be located.

Start=spos

This optional, name-required argument is a number that specifies the position in the haystack string at which to start searching for the needle string. spos defaults to 1, meaning that the search begins at the first character in haystack.

Usage Notes

• The starting position must be a positive number. A zero or negative number results in request cancellation. Specifying a starting 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.
• The UnicodePositionOf and UnicodePositionIn methods do exactly the same thing. The only difference between them is that in UnicodePositionOf, the haystack is the method object and the needle is the first argument. In UnicodePositionIn, the method object and first argument are reversed. Which method is preferable will depend on the application, and, in many cases, it will be quite arbitrary which one is used.
• The UnicodePositionOf and UnicodePositionIn methods are analogous to the String intrinsic PositionIn and PositionOf methods (??PositionIn and PositionOf).

Examples

Some examples follow. For information about the PrintText statement, see the list item ?? refid=intprnt..

• 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
  

• 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
  

• The following sequence, which uses the U function (??U) 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