Skip to main content

$WASCII

Returns the numeric code corresponding to a character, recognizing surrogate pairs.

Synopsis

$WASCII(expression,position)
$WA(expression,position)

Parameters

Argument Description
expression The character to be converted.
position Optional — The position of a character within a character string, counting from 1. The default is 1.

Description

$WASCII returns the character code value for a single character specified in expression. $WASCII recognizes a surrogate pair as a single character. The returned value is a positive integer.

The expression parameter may evaluate to a single character or to a string of characters. If expression evaluates to a string of characters, you can include the optional position parameter to indicate which character you want to convert. The position 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 $WASCII function recognizes a surrogate pair as a single character. The $ASCII function treats a surrogate pair as two characters. In all other aspects, $WASCII and $ASCII are functionally identical. However, because $ASCII is generally faster than $WASCII, $ASCII is preferable for all cases where a surrogate pair is not likely to be encountered. For further details on character to numeric code conversion, refer to the $ASCII function.

Examples

The following example shows $WASCII returning the Unicode value for a surrogate pair:

  IF $SYSTEM.Version.IsUnicode()  {
  SET hipart=$CHAR($ZHEX("D806"))
  SET lopart=$CHAR($ZHEX("DC06"))
  WRITE !,$ASCII(hipart)," = high-order value"
  WRITE !,$ASCII(lopart)," = low-order value"
  SET spair=hipart_lopart /* surrogate pair */
  SET xpair=hipart_hipart /* NOT a surrogate pair */
  WRITE !,$WASCII(spair)," = surrogate pair value"
  WRITE !,$WASCII(xpair)," = Not a surrogate pair"
  }
  ELSE {WRITE "This example requires a Unicode installation of Caché"}

The following example compares $WASCII and $ASCII return values for a surrogate pair:

  IF $SYSTEM.Version.IsUnicode()  {
  SET hipart=$CHAR($ZHEX("D806"))
  SET lopart=$CHAR($ZHEX("DC06"))
  WRITE !,$ASCII(hipart)," = high-order value"
  WRITE !,$ASCII(lopart)," = low-order value"
  SET spair=hipart_lopart /* surrogate pair */
  WRITE !,$ASCII(spair)," = $ASCII value for surrogate pair"
  WRITE !,$WASCII(spair)," = $WASCII value for surrogate pair"
  }
  ELSE {WRITE "This example requires a Unicode installation of Caché"}

The following example shows the effects on position counting of surrogate pairs. It returns both the $WASCII and $ASCII values for each position. $WASCII counts a surrogate pair as one position; $ASCII counts a surrogate pair as two positions:

  IF $SYSTEM.Version.IsUnicode()  {
  SET hipart=$CHAR($ZHEX("D806"))
  SET lopart=$CHAR($ZHEX("DC06"))
  WRITE !,$ASCII(hipart)," = high-order value"
  WRITE !,$ASCII(lopart)," = low-order value",!
  SET str="AB"_lopart_hipart_lopart_"CD"_hipart_lopart_"EF"
  FOR x=1:1:11 {
  WRITE !,"position ",x," $WASCII ",$WASCII(str,x)," $ASCII ",$ASCII(str,x) }
  }
  ELSE {WRITE "This example requires a Unicode installation of Caché"}

See Also

FeedbackOpens in a new tab