$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