StringTools

StringTools object provides several utility methods for encoding and decoding strings. For example, you can use a StringTools object to Base64-encode a chunk of data, or decode a UTF-8 encoded message header.

 

You can obtain a StringTools object using the DOpusFactory.StringTools method.

 

Method Name

Arguments

Return Type

Description

Decode

<Blob:source> or <string:source>

<string:format>

string or

Blob 

Decodes an encoded string or data.

You can provide either a Blob object or a string as the source to decode. Depending on the value of the format argument, either a string or a Blob is returned.

If format is specified as "base64" the source will be Base64-decoded, and a Blob is returned.

If format is specified as "quoted" the source will be Quoted-printable-decoded, and a Blob is returned.

If format is specified as "auto" or not supplied, special handling is invoked to decode a MIME-encoded email subject (e.g. one beginning with =?), and a string is returned. If "auto" is specified it will also detect UTF-8 or UTF-16 encoded data if it has a BOM at the beginning.

If format is specified as utf-8 the source will be converted from UTF-8 to a native string. Alternatively, if format is utf-16 or utf-16-le, the source will be converted from UTF-16 Little Endian to a native string. Or, if format is utf-16-be, the source will be converted from UTF-16 Big Endian to a native string.

If decoding UTF-8 or UTF-16 (via "auto" or "utf-8", etc.), any byte-order-mark (BOM) will be skipped if one exists at the beginning of the input data.

Otherwise, format must be set to a valid code-page name (e.g. "gb2312", "utf-8"), or a Windows code-page ID (e.g. 936, 65001). The source will be decoded using the specified code-page and a string is returned.

Encode

<Blob:source> or <string:source>

<string:format>

string or

Blob 

Encodes a string or data.

You can provide either a Blob object or a string as the source to decode. Depending on the value of the format argument, either a string or a Blob is returned.

If format is specified as "base64" the source will be Base64-encoded, and a string is returned.

If format is specified as "quoted" the source will be Quoted-printable-encoded, and a string is returned.

If format is specified as "utf-8 bom", the output data is encoded as UTF-8 with a byte-order-mark (BOM) at the start. Use "utf-8" if you want UTF-8 without the BOM.

If format is specified as "utf-16 bom" or "utf-16-le bom", the output data is encoded as UTF-16 Little Endian with a byte-order-mark (BOM) at the start. Use "utf-16" or "utf-16-le" if you do not want the BOM.

If format is specified as "utf-16-be bom", the output data is encoded as UTF-16 Big Endian with a byte-order-mark (BOM) at the start. Use "utf-16-be" if you do not want the BOM.

Otherwise, format must be set to a valid code-page name (e.g. "gb2312", "utf-8" etc.), or a Windows code-page ID (e.g. 936, 65001). The source will be encoded using the specified code-page and a Blob is returned.

IsASCII

<string:input>

bool

Tests the input string to see if it only contains characters that can be represented in ASCII.

If the result is false, the string is not safe to save into a text file unless you use a Unicode format such as UTF-8.

This check is not affected by locales or codepages. Instead, it tests whether the string consists of only 7-bit ASCII characters, such that no characters will be lost of modified if you save the string to a text file and then load it back on any other computer.