Original Author Paul Laughton, 2011
Page 68
De Re BASIC!
If you supply the qualifier, whether password or charset, it IS case-sensitive.
The source string is decoded to a byte stream according to the type. Then the byte stream is converted
to a BASIC! string (UTF-16) according to the character encoding (the charset parameter), which describes
how to interpret the byte stream. The charset is always UTF-8 for decryption, and defaults to UTF-8 for
the other types. The most common usage of this function is to omit the charset.
If the source string was encoded from binary data (with "ENCRYPT_RAW" or "BASE64"), the resulting
BASIC! string will be a buffer string. When a string is used as a buffer, one byte of data is written into the
lower 8 bits of each 16-bit character, and the upper 8 bits are 0. You can extract the binary data from
the string, one byte at a time, using the ASCII() or UCODE() functions.
If the source string cannot be decoded (or decrypted) with the specified charset (or password), the
function returns an empty string (""). You can call the GETERROR$() function to get an error message.
See the two-parameter form of ENCODE$(), below, for a partial list of valid charsets.
ENCODE$(<charset_sexp>, <source_sexp>)
Encodes the string <source_sexp> using the character encoding of the <charset_sexp> and returns the
result in a buffer string. When a string is used as a buffer, one byte of data is written into the lower 8
bits of each 16-bit character, and the upper 8 bits are 0.
The charset specifies the rules used to convert the source string into a byte stream. The stream is
written to a buffer string, one byte per character. The bytes are not reassembled into 16-bit characters.
The charsets "UTF-8", "UTF-16", "UTF-16BE", "UTF-16LE", "US-ASCII", and "ISO-8859-1" are always
available. Your device may have additional charsets. The charset names are case-sensitive, but the
standard charsets have aliases for convenience. For example, "utf8" is valid.
If the source string cannot be encoded with the specified charset, the function returns an empty string
(""). You can call the GETERROR$() function to get an error message.
If you create a buffer string with ENCODE$(), you can write the bytes to a file with Byte.write.buffer.
For encryption and URL- or Base64-encoding, see the three-parameter form of ENCODE$(), above.
DECODE$(<charset_sexp>, <buffer_sexp>)
Decodes the buffer string <buffer_sexp> that was encoded using the <charset_sexp> and returns the
result in a standard BASIC! string. A buffer string is a special use of the BASIC! string in which each 16-bit
character consists of one byte of 0 and one byte of data.
If the source string cannot be decoded with the specified charset, the function returns an empty string
(""). You can call the GETERROR$() function to get an error message.