Skip to main content

$ZWUNPACK and $ZWBUNPACK (ObjectScript)

Unpacks a single 16-bit character to two 8-bit characters.

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

FeedbackOpens in a new tab