$ZWPACK and $ZWBPACK
Synopsis
$ZWPACK(string) $ZWBPACK(string)
Parameter
Argument | Description |
---|---|
string | A string consisting of two or more 8-bit characters. string must be an even number of characters. |
Description
The $ZWPACK function packs a string of 8-bit characters as a string of 16-bit wide characters in little-endian order. Two 8-bit characters are packed into a single 16-bit character.
$ZWBPACK performs the same task, but the 8-bit characters are stored in 16-bit wide characters in big-endian order.
Packing a string is a way to halve the character count of the string for storage and string manipulation. Unpacking restores the original 8-bit character string for display. These operations should not be used when Unicode characters are permitted in the data.
The input string has the following requirements:
-
string must consist of an even number of characters. The empty string is permitted, and returns the empty string. Specifying an odd number of characters results in a <FUNCTION> error.
-
string cannot contain any multibyte characters. You can use $ZISWIDE on string to check that it does not contain multibyte characters. If you use $ZWPACK or $ZWBPACK on a string containing multibyte characters, the system generates a <WIDE CHAR> error.
Examples
Note that the following examples require a Unicode installation of Caché.
The following example shows $ZWPACK packing four 8-bit characters into two 16-bit wide characters. Note the little-endian order of the bytes in the wide characters of the packed string: hexadecimal 4241 4443.
SET str=$CHAR(65,66,67,68)
WRITE !,$LENGTH(str)," characters: ",str
WRITE !,"$ZWPACK"
SET wstr=$ZWPACK(str)
WRITE !,$LENGTH(wstr)," packed characters: ",wstr
ZZDUMP wstr
WRITE !,"$ZWUNPACK"
SET nstr=$ZWUNPACK(wstr)
WRITE !,$LENGTH(nstr)," unpacked characters: ",nstr
The following example shows $ZWBPACK packing four 8-bit characters into two 16-bit wide characters. Note the big-endian order of the bytes in the wide characters of the packed string: hexadecimal 4142 4344.
SET str=$CHAR(65,66,67,68)
WRITE !,$LENGTH(str)," characters: ",str
WRITE !,"$ZWBPACK"
SET wstr=$ZWBPACK(str)
WRITE !,$LENGTH(wstr)," packed characters: ",wstr
ZZDUMP wstr
WRITE !,"$ZWBUNPACK"
SET nstr=$ZWBUNPACK(wstr)
WRITE !,$LENGTH(nstr)," unpacked characters: ",nstr
The following example validates string before packing it:
SET str=$CHAR(65,66,67,68)
IF $ZISWIDE(str) {
WRITE !,str," contains wide characters"
QUIT }
ELSEIF $LENGTH(str) # 2 {
WRITE !,str," contains an odd number of characters"
QUIT }
ELSE {
WRITE !,str," passes validation" }
WRITE !,$LENGTH(str)," characters: ",str
SET wstr=$ZWPACK(str)
WRITE !,$LENGTH(wstr)," packed characters: ",wstr
ZZDUMP wstr
See Also
-
$LENGTH function
-
$ZISWIDE function
-
$ZWUNPACK and $ZWBUNPACK functions