Skip to main content

$WFIND (ObjectScript)

Finds a substring by value and returns an integer specifying its end position in the string, recognizing surrogate pairs.

Synopsis

$WFIND(string,substring,position)
$WF(string,substring,position)

Arguments

Argument Description
string The target string that is to be searched. It can be a variable name, a numeric value, a string literal, or any valid ObjectScript expression that resolves to a string.
substring The substring that is to be searched for. It can be a variable name, a numeric value, a string literal, or any valid ObjectScript expression that resolves to a string.
position Optional — A position within the target string at which to start the search. It must be a positive integer.

Description

$WFIND returns an integer specifying the end position of a substring within a string. In calculating position, it counts each surrogate pair as a single character. $WFIND is functionally identical to $FIND, except that $WFIND recognizes surrogate pairs. It counts a surrogate pair as a single character. You can use the $WISWIDE function to determine if a string contains a surrogate pair.

A surrogate pair is a pair of 16-bit InterSystems IRIS character elements that together encode a single Unicode character. Surrogate pairs are used to represent certain ideographs which are used in Chinese, Japanese kanji, and Korean hanja. (Most commonly-used Chinese, kanji, and hanja characters are represented by standard 16-bit Unicode encodings.) Surrogate pairs provide InterSystems IRIS support for the Japanese JIS X0213:2004 (JIS2004) encoding standard and the Chinese GB18030 encoding standard.

A surrogate pair consists of high-order 16-bit character element in the hexadecimal range D800 through DBFF, and a low-order 16-bit character element in the hexadecimal range DC00 through DFFF.

The $WFIND function counts a surrogate pair as a single character. The $FIND function counts a surrogate pair as two characters. In all other aspects, $WFIND and $FIND are functionally identical. However, because $FIND is generally faster than $WFIND, $FIND is preferable for all cases where a surrogate pair is not likely to be encountered.

For further details on finding a substring, refer to the $FIND function.

Examples

The following example shows how $WFIND counts a surrogate pair as a single character in the return value:

  SET spair=$CHAR($ZHEX("D806"),$ZHEX("DC06"))
  SET str="ABC"_spair_"DEF"
  WRITE !,$FIND(str,"DE")," $FIND location in string"
  WRITE !,$WFIND(str,"DE")," $WFIND location in string"

The following example shows how $WFIND counts a surrogate pair as a single character in the position argument:

  SET spair=$CHAR($ZHEX("D806"),$ZHEX("DC06"))
  SET str="ABC"_spair_"DEF"
  WRITE !,$FIND(str,"DE",6)," $FIND location in string"
  WRITE !,$WFIND(str,"DE",6)," $WFIND location in string"

See Also

FeedbackOpens in a new tab