$ZWUNPACK and $ZWBUNPACK (ObjectScript)
Synopsis
$ZWUNPACK(string)
$ZWBUNPACK(string)
Argument
Argument | Description |
---|---|
string | A string consisting of one or more 16-bit characters. |
Description
$ZWUNPACK is a function that takes one or more two-byte wide characters and “unpacks” them, returning the corresponding pairs of single-byte characters in little endian order.
$ZWBUNPACK performs the same task, but the two-byte wide characters are unpacked 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 should consist entirely of 16-bit wide characters created using $ZWPACK or $ZWBPACK. The empty string is permitted, and returns the empty string. string should not contain any 16-bit Unicode characters, or any 8-bit characters.
You can use $ZISWIDE on string to check that it contains multibyte characters. However, you must use $ZISWIDE on each character to ensure that the string does not contain a mix of 16-bit and 8-bit characters. $ZISWIDE does not distinguish between Unicode and packed 16-bit characters.
You can use the IsBigEndian()Opens in a new tab class method to determine which bit ordering is used on your operating system platform: 1=big-endian bit order; 0=little-endian bit order.
WRITE $SYSTEM.Version.IsBigEndian()
Examples
The following example unpacks a string (“ABCD”) that was packed using $ZWPACK. It unpacks two 16-bit wide characters into four 8-bit 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 performs the same operation as the previous example, but uses big-endian order. 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 shows what happens when you “unpack” a string of 8-bit characters. Note that the unpacking operation assumes each character to be a 16-bit wide character, and thus supplies the missing eight bits as hexadecimal 00. This use of $ZWUNPACK is not recommended.
SET str=$CHAR(65,66,67)
WRITE !,$LENGTH(str)," characters: ",str
SET nstr=$ZWUNPACK(str)
WRITE !,$LENGTH(nstr)," unpacked characters:"
ZZDUMP nstr
The following example shows what happens when you “unpack” a string of 16-bit Unicode characters; in this case, lowercase Greek letters. This use of $ZWUNPACK is not recommended.
SET str=$CHAR(945,946,947)
WRITE !,$LENGTH(str)," characters: ",str
SET nstr=$ZWUNPACK(str)
WRITE !,$LENGTH(nstr)," unpacked characters: ",nstr
ZZDUMP nstr
See Also
-
$LENGTH function
-
$ZISWIDE function
-
$ZWPACK and $ZWBPACK functions