$CHAR (ObjectScript)
Synopsis
$CHAR(expression,...)
$C(expression,...)
Argument
Argument | Description |
---|---|
expression | The integer value to be converted. |
Description
$CHAR returns the character that corresponds to the decimal (base-10) integer value specified by expression. This character can be an 8-bit (ASCII) character, or a 16-bit (Unicode) character. For 8-bit characters, the value in expression must evaluate to a positive integer in the range 0 to 255. For 16-bit characters, specify integers in the range 256 through 65535 (hex FFFF). Values larger than 65535 return an empty string. Values from 65536 (hex 10000) through 1114111 (hex 10FFFF) are used to represent Unicode surrogate pairs; these characters can be returned using $WCHAR.
You can specify expression as a comma-separated list, in which case $CHAR returns the corresponding character for each expression in the list.
The $ASCII function is the inverse of $CHAR.
Argument
expression
The expression can be an integer value, the name of a variable that contains an integer value, or any valid ObjectScript expression that evaluates to an integer value. To return characters for multiple integer values, specify a comma-separated list of expressions.
You can use the $ZHEX function to specify character using a hexadecimal character code, rather than a decimal (base-10) character code. In the following example, both $CHAR statements return the Greek letter pi:
WRITE $CHAR(960),!
WRITE $CHAR($ZHEX("3C0"))
Examples
The following example uses $CHAR in a FOR loop to output the characters for all ASCII codes in the range 65 to 90. These are the uppercase alphabetic characters.
FOR i=65:1:90 {
WRITE !,$CHAR(i) }
The following example uses $CHAR in a FOR loop to output the Japanese Hiragana characters:
FOR i=12353:1:12435 {
WRITE !,$CHAR(i) }
The following two examples show the use of multiple expression values. The first returns “AB” and the second returns “AaBbCcDdEeFfGgHhIiJjKk”:
WRITE $CHAR(65,66),!
FOR i=65:1:75 {
WRITE $CHAR(i,i+32) }
$CHAR and WRITE
When you use $CHAR to write characters with the WRITE command, the output characters reset the positions of the special variables $X and $Y. This is true even for the NULL character (ASCII 0), which is not the same as a null string (""). As a rule, you should use $CHAR with caution when writing nonprinting characters, because such characters may produce unpredictable cursor positioning and screen behavior.
$CHAR and %List Structures
Because a %List structure (%Library.ListOpens in a new tab) is an encoded string using non-printing characters, certain $CHAR values result in a %List structure containing a single element. The $CHAR combinations that return a %List structure are as follows:
-
$CHAR(1) returns an empty list: $lb().
-
$CHAR(1,1) returns a two-element empty list: $lb(,).
-
$CHAR(2,1), $CHAR(2,2), or $CHAR(2,12) returns a list containing the empty string: $lb("").
-
$CHAR(2,4) returns $lb(0).
-
$CHAR(2,5) returns $lb(-1).
-
$CHAR(2,8) or $CHAR(2,9) returns $lb($double(0)).
$CHAR combinations that involve more than two characters and result in a single-element list have the following syntax:
$CHAR(count,flag,string)
count is the total number of characters. For example, $CHAR(5,1,65,66,67) or $CHAR(5,1)_"ABC".
flag is an integer specifying how string should be represented. Valid flag values include 1, 2, 4, 5, 6, 7, 8, 9, 12, and 13. These flag interpretations have nothing to do with the usual ASCII interpretation of this non-print character.
-
flag=1, flag=12, and flag=13 return the literal string value as the list element.
-
flag=2 is only valid if count is an even number. It returns a list element containing one or more wide Unicode characters derived from string, often one or more Chinese characters.
-
flag=4 returns the positive ASCII numeric code for the character(s) as the list element. flag=4 cannot be used when count>10.
-
flag=5 returns a negative integer ASCII numeric code for the character(s) as the list element. flag=5 cannot be used when count>10.
-
flag=6 returns a positive integer derived from string as the list element:
-
$CHAR(3,6,n) always returns $lb(0).
-
$CHAR(count,6,string) when count > 3 returns a (usually) large positive integer derived from the ASCII numeric value. The number of trailing zeros corresponds to the ASCII value of the first character in string, the leading numeric value to the ASCII value of the second character in string. For example, $CHAR(4,6,0,7) returns $lb(7); $CHAR(4,6,3,7) returns $lb(7000).
flag=6 cannot be used when count>11.
-
-
flag=7 returns a negative integer derived from string as the list element:
-
$CHAR(3,7,n) returns a negative number with the number of zeros corresponding to the value of n: 0 = –1, 1 = –10, 2= –100, 3 = –1000, etc.
-
$CHAR(count,7,string) when count > 3 returns a (usually) large negative integer. The number of trailing zeros corresponds to the ASCII value of the first character in string.
flag=7 cannot be used when count>11.
-
-
flag=8 returns $DOUBLE(x) where x is a small number. flag=8 cannot be used when count>6.
-
flag=9 returns $DOUBLE(x) where x is a large number. flag=9 cannot be used when count>10.
string is a numeric or string of count – 2 characters. For example, a string of three characters can be represented as either $CHAR(5,flag,65,66,67) or $CHAR(5,flag)_"ABC". The string value becomes the list element, its value represented as specified by flag.
For further details, refer to $LISTBUILD and $LISTVALID.
Numeric Values in $CHAR Arguments
You can use signed numeric values for expression. InterSystems IRIS ignores negative numbers and only evaluates positive or unsigned numbers. In the following example, the $CHAR with signed integers returns only the first and third expression, ignoring the second expression, which is a negative integer.
WRITE !,$CHAR(65,66,67)
WRITE !,$CHAR(+65,-66,67)
ABC
AC
You can use floating point numeric values for expression. InterSystems IRIS ignores the fractional portion of the argument and only considers the integer portion. In the following example, $CHAR ignores the fractional portion of the number and produces the character represented by character code 65, an uppercase A.
WRITE $CHAR(65.5)
Unicode Support
$CHAR supports Unicode characters represented by decimal (base-10) integers.
The Unicode value for a character is usually expressed as a 4-digit number in hexadecimal notation, using the digits 0-9 and the letters A-F. However, standard functions in the ObjectScript language generally identify characters according to ASCII codes, which are decimal values, not hexadecimal.
Hence, the $CHAR function supports Unicode encoding by returning a character based on the decimal Unicode value that was input, not the more standard hexadecimal value. You can specify a hexadecimal Unicode value using the $ZHEX function using quotes, as follows $CHAR($ZHEX("hexnum")). You can also use $ZHEX without quotes to convert a decimal number to hexadecimal, as follows: hexnum = $ZHEX(decnum).
For further details refer to Unicode.
Surrogate Pairs
$CHAR does not recognize surrogate pairs. Surrogate pairs are used to represent some Chinese characters and to support the Japanese JIS2004 standard. You can use the $WISWIDE function to determine if a string contains a surrogate pair. The $WCHAR function recognizes and correctly parses surrogate pairs. $CHAR and $WCHAR are otherwise identical. However, because $CHAR is generally faster than $WCHAR, $CHAR is preferable for all cases where a surrogate pair is not likely to be encountered.
$WCHAR should not be confused with $ZWCHAR, which always parses characters in pairs.