Article Directory

Chapter 7 Caché Function Collection $CHAR Function
Outline
- parameter
description
parameter
- expression
Example
note

Chapter 7 Caché Function Collection $CHAR Function

Convert the integer value of the expression to the corresponding ASCII or Unicode character.

Outline

$CHAR(expression,...)
$C(expression,...)

parameter

expression The integer value to be converted.

description

$CHARReturns the character corresponding to the decimal (base 10) integer value specified by the expression. The character can be an 8-bit (ASCII) character or a 16-bit (Unicode) character. For 8-bit characters, the value in the expression must be a positive integer between 0 and 255. For 16-bit characters, please specify an integer between 256 and 65535 (hexadecimal FFFF). Values greater than 65535 will return an empty string. Values from 65536 (hexadecimal 10000) to 1114111 (hexadecimal 10FFFF) are used to represent Unicode surrogate pairs. These characters can be $WCHARreturned using . In an 8-bit Caché installation, $CHAR returns an empty string with an expression value greater than 255.

The expression can be specified as a comma-separated list, in which case the $CHARcorresponding character will be returned for each expression in the list.

$ASCIIFunction is $CHARthe inverse function.

parameter

expression

The expression can be an integer value, it can be the name of a variable containing 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 $ZHEXfunctions to specify characters using hexadecimal character codes instead of decimal (base 10) character codes. In the following example, both $CHARstatements return the Greek letter pi:

DHC-APP>WRITE $CHAR(960),!
π
 
DHC-APP> WRITE $CHAR($ZHEX("3C0"))
π

Example

The following example FORuses $CHARall ASCII characters in the range 65 to 90 to output in the loop . These are uppercase alphabetic characters.

/// d ##class(PHA.TEST.Function).Char()
ClassMethod Char()
{
    
    
	FOR i=65:1:90 {
    
    
		WRITE !,$CHAR(i) 
	}
}

DHC-APP>d ##class(PHA.TEST.Function).Char()
 
A
B
C
D
E
F
G
H
I
J
K
L
M
N
O
P
Q
R
S
T
U
V
W
X
Y
Z

The following example FORuses $CHARoutput Japanese hiragana characters in a loop :

/// d ##class(PHA.TEST.Function).Char1()
ClassMethod Char1()
{
    
    
	IF $SYSTEM.Version.IsUnicode()  {
    
    
		FOR i = 12353 : 1 : 12435 {
    
    
			WRITE !,$CHAR(i) 
		} 
	} ELSE {
    
    
		WRITE "此示例需要Caché的Unicode版本"
	}
}

DHC-APP>d ##class(PHA.TEST.Function).Char1()
ぁあぃいぅうぇえぉおかがきぎくぐけげこごさざしじすずせぜそぞただちぢっつづてでと                                        どなにぬねのはばぱひびぴふぶぷへべぺほぼぽまみむめもゃやゅゆょよらりるれろゎわゐ                                        ゑをん

The following two examples show the use of multiple expression values. The first one returns " AB", the second one returns" AaBbCcDdEeFfGgHhIiJjKk":

/// d ##class(PHA.TEST.Function).Char2()
ClassMethod Char2()
{
    
    
	WRITE $CHAR(65, 66),!
	FOR i = 65 : 1 : 75 {
    
     
		WRITE $CHAR(i, i + 32) 
	}
}

DHC-APP>d ##class(PHA.TEST.Function).Char2()
AB
AaBbCcDdEeFfGgHhIiJjKk

The following example shows the use of multibyte characters. The character corresponding to the integer 960 is the symbol of pi:

/// d ##class(PHA.TEST.Function).Char3()
ClassMethod Char3()
{
    
    
	IF $SYSTEM.Version.IsUnicode()  {
    
    
		WRITE $CHAR(960) 
	} ELSE {
    
    
		WRITE "此示例需要Caché的Unicode版本"
	}
}

DHC-APP>d ##class(PHA.TEST.Function).Char3()
π

note

`$CHAR`With `WRITE`command

When writing characters $CHARwith WRITEcommands, the output characters will reset the position of the special variables $Xand sum $Y. This is true even for “”NULL characters (ASCII 0) that are different from the empty string ( ). In general, you should use caution when writing non-printing characters $CHAR, as such characters may produce unpredictable cursor position and screen behavior.

`$CHAR`And `％List`structure

Because the ％Liststructure ( ％Library.List) is an encoded string using non-printing characters, certain $CHARvalues will cause the ％Liststructure to contain a single element. ％ListThe $CHARcombination of the returned structure is as follows:

$CHAR(1)Returns an empty $lb()list: .
$CHAR(1,1)Returns an empty list with two elements $lb(,).
$CHAR(2,1), $CHAR(2,2), Or $CHAR(2,12)returns a list containing an empty string: $lb("").
$CHAR(2,4) return $lb(0)
$CHAR(2,5)Return $lb(-1).
$CHAR(2,8)Or $CHAR(2,9)return $lb($double(0)).

A combination involving more than two characters and producing a single-element list $CHARhas 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 that specifies how the string should be represented. Valid flag values include 1, 2, 4, 5, 6, 7, 8, 9, 12, and 13. The interpretation of these flags has nothing to do with the normal ASCII interpretation of the non-printing character.

flag = 1, flag = 12And flag = 13return the literal string value as a list element.
flag = 2Only valid when count is an even number. It returns a list element, which contains one or more wide Unicode characters derived from the string, usually one or more Chinese characters.
flag = 4Returns the positive ASCII numeric code of the character as a list element. When count>10, flag = 4 cannot be used.
flag = 5Return a negative integer ASCII numeric code as a list element. When count>10, flag = 5 cannot be used.
flag = 6Return a positive integer derived from a string as a list element:
- $CHAR(3,6,n)Always return $lb(0).
- When count>3, it $CHAR(count,6,string)returns a (usually) large positive integer derived from the ASCII value. The number of trailing zeros corresponds to the ASCII value of the first character in the string, and the leading numeric value corresponds to the ASCII value of the second character in the string. For example, $CHAR(4,6,0,7)return $lb(7); $CHAR(4,6,3,7)return $lb(7000).
- When count>11, it cannot be used flag = 6.
flag = 7Return a negative integer derived from a string as a list element:
- $CHAR(3,7,n) Returns a negative number, the number of zeros corresponding to the value of n: 0 = –1, 1 = –10, 2 = –100, 3 = –1000, etc.
- When count>3, $CHAR(count,7,string)a (usually) large negative integer is returned. The number of trailing zeros corresponds to the ASCII value of the first character in the string.
- When count>11, flag=7 cannot be used.
flag = 8Return $DOUBLE（x）, where x is a decimal. When count>6, flag = 8 cannot be used.
flag = 9Return $DOUBLE（x）, where x is a large number. When count>10, flag = 9 cannot be used.

A character string is a number or character string counted as 2 characters. For example, a three-character string can be represented as $CHAR(5，FLAG，65，66，67)or $CHAR(5，FLAG)_“ABC”. The string value becomes a list element, and its value is flagrepresented by .

`$CHAR`Value in parameter

To use signed numeric values for expressions. Caché ignores negative numbers and only counts positive or unsigned numbers. In the following example, $CHARonly the first and third expressions are returned for signed integers , and the second expression is ignored, which is a negative integer.

DHC-APP>WRITE !,$CHAR(65,66,67)
 
ABC
DHC-APP> WRITE !,$CHAR(+65,-66,67)
 
AC

ABC
AC

You can use floating point values for expressions. Caché ignores the decimal part of the parameter and only considers the integer part. In the following example, $CHARthe decimal part of the number is ignored, and the character represented by the character code 65 (uppercase A) is generated.

DHC-APP>   WRITE $CHAR(65.5)
A

Unicode support

On Caché's Unicode installation, $CHARUnicode characters are supported when expressed in decimal (base 10) integers. On an 8-bit Caché installation, $CHARan empty string of integers greater than 255 is returned.

The Unicode value of a character is usually represented as a 4-digit number in hexadecimal notation using numbers 0-9 and letters AF. However, the standard functions in the ObjectScript language usually identify characters based on ASCII codes, which are decimal values, not hexadecimal.

Therefore, the $CHARfunction returns characters based on the input decimal Unicode value (rather than the more standard hexadecimal value), thus supporting Unicode encoding. You can use quoted $ZHEXfunctions to specify hexadecimal Unicode values as shown below $CHAR($ZHEX("hexnum")). May also be used without the quotes $ZHEXdecimal to hexadecimal numbers, as follows: hexnum = $ZHEX(decnum).

Surrogate pair

$CHARThe surrogate pair cannot be recognized. The surrogate pair is used to represent certain Chinese characters and supports the Japanese JIS2004 standard. You can use $WISWIDEfunctions to determine whether the string contains surrogate pairs. $WCHARThe function can identify and correctly parse the surrogate pair. $CHARAnd $WCHARotherwise the same. However, since it $CHARis usually $WCHARfaster, it is best to use it for all situations where surrogate pairs are unlikely to be encountered $CHAR.

Note: it should not be $WCHARand $ZWCHARconfused character who always come in pairs analysis.

And `$CHAR`related functions

$ASCIIFunction is $CHARthe inverse function. You can use it to convert characters to their equivalent numeric values. $ASCIIConvert all characters, including Unicode characters. In addition, all Caché platforms support related functions $ZLCHARand $ZWCHAR. They are similar $CHAR, but operate on a word (two bytes) or a long word (four bytes). You can use it to $ZISWIDEdetermine $CHARif there are any multibyte ("wide") characters in the expression.