$WFIND - Caché ObjectScript Reference - Caché & Ensemble 2018.1

docs.intersystems.com

Caché ObjectScript Reference

$WFIND

InterSystems: The power behind what matters

Caché Development References > Caché ObjectScript Reference > ObjectScript Functions > $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

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é"}

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é"}