Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.

For information on migrating to InterSystems IRIS, see the InterSystems IRIS Migration Guide and Migrating to InterSystems IRIS, both available on the WRC Distributions page (login required).

$WFIND

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)

Parameters

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 Caché 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 Caché 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:

  IF $SYSTEM.Version.IsUnicode()  {
  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"
  }
  ELSE {WRITE "This example requires a Unicode installation of Caché"} 
Copy code to clipboard

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

  IF $SYSTEM.Version.IsUnicode()  {
  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"
  }
  ELSE {WRITE "This example requires a Unicode installation of Caché"} 
Copy code to clipboard

See Also

Feedback