Article Directory

Chapter One Caché Function Collection $ASCII Function
Outline
- parameter
description
parameter
- expression
- position
Example
note

Chapter One Caché Function Collection $ASCII Function

Convert characters to numeric codes.

Outline

$ASCII(expression,position)
$A(expression,position)

parameter

expression The character to be converted.
position Optional-the position of the character in the string, counting from 1. The default value is 1.

description

$ASCIIReturns the character code value of the single character specified in the expression. This character can be an 8-bit (extended ASCII) character or a 16-bit (Unicode) character. The return value is a positive integer.

The expression parameter can be evaluated as a single character or a string. If the expression is calculated as a string, you can include the optional position parameter to indicate the character to be converted.

parameter

expression

The result of this expression is a quoted string of one or more characters. The expression can be specified as a variable name, value, string literal, or any valid CachéObjectScript expression. If the string produced by expression exceeds one character, use position to select the desired character. If the position of the string is omitted, $ASCIIthe numeric code of the first character is returned. If the result of the expression is an empty string, $ASCII-1 is returned.

position

The position must be specified as a non-zero positive integer. It can be signed or unsigned. It is possible to use non-integer values in positions; however, Caché ignores the decimal part and only considers the integer part of the value. If the position is not included, $ASCIIthe value of the first character in the expression is returned. If the integer value of position is greater than the number of characters in the expression or less than 1, then $ASCII-1 is returned.

Example

The following example returns 87, which is Wthe ASCII value of the character .

DHC-APP>WRITE $ASCII("W")
87

The following example returns 960, which is pithe equivalent number of the Unicode character " ".

DHC-APP>WRITE $ASCII($CHAR(959+1))
960

The following example returns 84, which is Zthe ASCII equivalent of the first character in the variable .

DHC-APP>SET Z="TEST"
 
DHC-APP>WRITE $ASCII(Z)
84

The following example returns 83, which is Zthe ASCII numeric equivalent of the third character in the variable .

DHC-APP>SET Z="TEST"
 
DHC-APP>WRITE $ASCII(Z,3)
83

The following example returns -1 because the position specified by the second parameter is greater than the number of characters in the string.

DHC-APP>SET Z="TEST"
 
DHC-APP>WRITE $ASCII(Z,5)
-1

The following example FORuses in a loop to $ASCIIconvert xall characters in a variable to equivalent ASCII numbers. $ASCIIThe reference contains the position parameter, which is updated every time the loop is executed. When the number reached by position is greater than xthe number of characters in, $ASCIIthe value -1 will be returned, which will terminate the loop.

/// d ##class(PHA.TEST.Function).ASC2()
ClassMethod ASC2()
{
    
    
	SET x = "abcdefghijklmnopqrstuvwxyz"
	FOR i = 1 : 1 {
    
     
		QUIT:$ASCII(x, i)=-1 
		WRITE !, $ASCII(x, i) 
	}
	QUIT
}

DHC-APP>d ##class(PHA.TEST.Function).ASC2()
 
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

The following example Xgenerates a simple one for the string Checksum. When $CHAR（CS）concatenating with a string, the value of the new string is Checksumalways zero. Therefore, verification is simplified.

/// d ##class(PHA.TEST.Function).CXSUM()
ClassMethod CXSUM()
{
    
    
	SET x = "Now is the time for all good men to come to the aid of their party"
	SET CS = 0
	FOR i = 1 : 1 : $LENGTH(x) {
    
    
		SET CS = CS + $ASCII(x, i)
		WRITE !,"Checksum is:", CS
	}
	SET CS = 128 - CS # 128
	WRITE !,"Final checksum is:", CS
}

DHC-APP>d ##class(PHA.TEST.Function).CXSUM()
 
Checksum is:78
Checksum is:189
Checksum is:308
Checksum is:340
Checksum is:445
Checksum is:560
Checksum is:592
Checksum is:708
Checksum is:812
Checksum is:913
Checksum is:945
Checksum is:1061
Checksum is:1166
Checksum is:1275
Checksum is:1376
Checksum is:1408
Checksum is:1510
Checksum is:1621
Checksum is:1735
Checksum is:1767
Checksum is:1864
Checksum is:1972
Checksum is:2080
Checksum is:2112
Checksum is:2215
Checksum is:2326
Checksum is:2437
Checksum is:2537
Checksum is:2569
Checksum is:2678
Checksum is:2779
Checksum is:2889
Checksum is:2921
Checksum is:3037
Checksum is:3148
Checksum is:3180
Checksum is:3279
Checksum is:3390
Checksum is:3499
Checksum is:3600
Checksum is:3632
Checksum is:3748
Checksum is:3859
Checksum is:3891
Checksum is:4007
Checksum is:4111
Checksum is:4212
Checksum is:4244
Checksum is:4341
Checksum is:4446
Checksum is:4546
Checksum is:4578
Checksum is:4689
Checksum is:4791
Checksum is:4823
Checksum is:4939
Checksum is:5043
Checksum is:5144
Checksum is:5249
Checksum is:5363
Checksum is:5395
Checksum is:5507
Checksum is:5604
Checksum is:5718
Checksum is:5834
Checksum is:5955
Final checksum is:61

The following example converts a string of lowercase or mixed case letters to all uppercase letters.

/// d ##class(PHA.TEST.Function).ASCST()
ClassMethod ASCST()
{
    
    
ST  
	SET String = "ThIs Is a MiXeDCAse stRiNg"
	WRITE !,"Input: ",String
	SET Len = $LENGTH(String), Nstring=" " 
	FOR i = 1 : 1 : Len {
    
     DO CNVT }
	QUIT
CNVT  
	SET Char = $EXTRACT(String, i),Asc = $ASCII(Char)
	IF Asc > 96, Asc < 123 {
    
    
		SET Char = $CHAR(Asc - 32)
		SET Nstring = Nstring _ Char
	} ELSE {
    
    
		SET Nstring = Nstring _ Char
	}
	WRITE !,"Output: ",Nstring
	QUIT
}

DHC-APP>d ##class(PHA.TEST.Function).ASCST()
 
Input: ThIs Is a MiXeDCAse stRiNg
Output:  T
Output:  TH
Output:  THI
Output:  THIS
Output:  THIS
Output:  THIS I
Output:  THIS IS
Output:  THIS IS
Output:  THIS IS A
Output:  THIS IS A
Output:  THIS IS A M
Output:  THIS IS A MI
Output:  THIS IS A MIX
Output:  THIS IS A MIXE
Output:  THIS IS A MIXED
Output:  THIS IS A MIXEDC
Output:  THIS IS A MIXEDCA
Output:  THIS IS A MIXEDCAS
Output:  THIS IS A MIXEDCASE
Output:  THIS IS A MIXEDCASE
Output:  THIS IS A MIXEDCASE S
Output:  THIS IS A MIXEDCASE ST
Output:  THIS IS A MIXEDCASE STR
Output:  THIS IS A MIXEDCASE STRI
Output:  THIS IS A MIXEDCASE STRIN
Output:  THIS IS A MIXEDCASE STRING

Case difference 32

DHC-APP>w *70
F
DHC-APP>w *102
f

note

Support Unicode

$ASCIIThe function supports 8-bit and 16-bit characters. For 8-bit characters, it will return the numeric value 0 to 255. For 16-bit (Unicode) characters, it will return a numeric code up to 65535.

The Unicode value of a character is usually represented as 4 digits in hexadecimal, using numbers 0-9 and letters AF (10 to 15 respectively). However, the standard functions in the CachéObjectScript language usually identify characters based on ASCII numeric codes, which are decimal values in decimal not hexadecimal.

DHC-APP>w $ascii("姚鑫")
23002

DHC-APP>w $ascii("姚鑫",2)
37995

DHC-APP>w *23002
姚
DHC-APP>w *37995
鑫

Therefore, the $ASCIIfunction supports Unicode encoding by returning the decimal Unicode value of the input character instead of the hexadecimal value recommended by the Unicode standard. In this way, the function remains backward compatible while also supporting Unicode. To convert a decimal number to hexadecimal, use a $ZHEXfunction.

DHC-APP>w $zhex(23002)
59DA
DHC-APP>w $zhex(37995)
946B

\u59DA
\u946B

Surrogate pair

$ASCIIThe surrogate pair cannot be recognized. A surrogate pair is a pair of 16-bit Unicode characters, which together encode an ideographic character. 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. $WASCIIThe function can identify and correctly parse the surrogate pair. $ASCIIAnd $WASCIIotherwise the same. However, since it $ASCIIis usually $WASCIIfaster, it $ASCIIis desirable for all situations where it is unlikely to encounter a surrogate pair.

Note: $WASCIIshould not be $ZWASCIIconfused with, $ZWASCIIalways parse characters in pairs.

In UTF-16, it is encoded as a pair of 16-bit code elements (ie 32 bits, 4 bytes), called a surrogate pair,

related functions

$CHARFunction is $ASCIIthe inverse function. You can use it to convert integer codes to characters.

DHC-APP>w $char(23002)
姚
DHC-APP>w $char(37995)
鑫

$ASCIIConvert a single character to an integer. To convert a 16-bit (wide) character string to an integer, use $ZWASCII. To convert a 32-bit (long) string to an integer, use $ZLASCII. To convert a 64-bit (quaternary) string to an integer, please use $ZQASCII. To convert a 64-bit string to an IEEE floating point number ( $DOUBLEdata type), use $ZDASCII.

$ZWASCII Double byte

DHC-APP>w $ZWASCII("姚鑫")
50394
DHC-APP>w $ZWASCII("姚鑫",2)
-1

$ZWASCII Four bytes

DHC-APP>w $ZLASCII("姚鑫")
-1
DHC-APP>w $ZLASCII("姚鑫啊")
-1
DHC-APP>w $ZLASCII("姚鑫啊啊")
2682176730
DHC-APP>w $ZLASCII("姚鑫啊啊",2)
-1

$ZWASCII Eight bytes

DHC-APP>w $ZQASCII("姚鑫")
 
W $ZQASCII("姚鑫")
^
<FUNCTION>
DHC-APP>w $ZQASCII("姚鑫啊")
 
W $ZQASCII("姚鑫啊")
^
<FUNCTION>
DHC-APP>w $ZQASCII("姚鑫啊啊")
 
W $ZQASCII("姚鑫啊啊")
^
<FUNCTION>
DHC-APP>w $ZQASCII("姚鑫啊啊啊")
 
W $ZQASCII("姚鑫啊啊啊")
^
<FUNCTION>

DHC-APP>w $ZQASCII("姚鑫啊啊啊啊")
 
W $ZQASCII("姚鑫啊啊啊啊")
^
<FUNCTION>
DHC-APP>w $ZQASCII("姚鑫啊啊啊啊啊")
 
W $ZQASCII("姚鑫啊啊啊啊啊")
^
<FUNCTION>
DHC-APP>w $ZQASCII("姚鑫啊啊啊啊啊啊")
-6944656957523442470