$WFIND (ObjectScript)
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"
