ByteString Class

The ByteString class is a Primitive descendant that treats its value as a sequence of bytes instead of characters.

PSL is primarily character-oriented and does not consider the number of bytes used to represent a character. However, when (character) data is stored, exported, or imported, the code may have to deal with bytes rather than characters. The methods of the ByteString class provide the capabilities to deal with this.

There are two methods to instantiate a ByteString object.

1. Use the Number.byte() method to instantiate a single-byte byte string.

type ByteString SINGLBYT = 123.byte()

2. Use the String.toByteString() method to instantiate a multi-byte byte string.

type ByteString MULTIBYT = " Knäckebröd ".toByteString()

Because the ByteString class is a Primitive descendant, you can cast any other Primitive descendant as ByteString.

type ByteString objectName = {ByteString}value

On the other hand, casting a ByteString into any of the other Primitive descendants may result in a %GTM runtime exception. Therefore, you should never cast a ByteString into another Primitive descendant unless you are sure that the sequence of bytes constitutes a valid character string in the underlying implementation.

Even though the ByteString class encapsulates the character-to-bytes conversions, the class itself does rely on or presume a specific character representation. For example, methods of the ByteString class can deal with the GT.M character sets "M" and "UTF-8". Future versions may compile into code for a platform that uses a different character representation. For example, the Microsoft platforms and the java programming language use UTF-16 to represent characters. For this reason, application programs that need to be portable across multiple platforms shall not assume a specific character set encoding.

Example

//

// Despite the above warning to stay away from character set encodings,

// all examples of ByteString methods assume Runtime.charsetName = "UTF-8".

// This is exclusively for the sake of demonstrating the differences between

// character strings and byte strings, in particular with respect to

// "partial" characters.

//

// The following characters are used in the examples:

// character ä with byte sequence 195, 164 (decimal)

// character ö with byte sequence 195, 182 (decimal)

// character IJ with byte sequence 196, 178 (decimal)

// character ij with byte sequence 196, 179 (decimal)