Caché ObjectScript Reference
$WFIND
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

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