BlitzMax/Modules/Streams/Text streams

From Wikibooks, open books for an open world
Jump to navigation Jump to search

The Text Stream module allows you to load and save text in a number of formats: LATIN1, UTF8 and UTF16.

The LATIN1 format uses a single byte to represent each character, and is therefore only capable of manipulating 256 distinct character values.

The UTF8 and UTF16 formats are capable of manipulating up to 1114112 character values, but will generally use greater storage space. In addition, many text processing applications are unable to handle UTF8 and UTF16 files.

Functions[edit | edit source]

LoadText[edit | edit source]

Function LoadText$( url:Object )

Description: Load text from a stream

Returns: A string containing the text

Information: LoadText loads LATIN1, UTF8 or UTF16 text from url.

The first bytes read from the stream control the format of the text:

&$fe $ff Text is big endian UTF16
&$ff $fe Text is little endian UTF16
&$ef $bb $bf Text is UTF8

If the first bytes don't match any of the above values, the stream is assumed to contain LATIN1 text.

A TStreamReadException is thrown if not all bytes could be read.

SaveText[edit | edit source]

Function SaveText( str$,url:Object )

Description: Save text to a stream

Information: SaveText saves the characters in str to url.

If str contains any characters with a character code greater than 255, then str is saved in UTF16 format. Otherwise, str is saved in LATIN1 format.

A TStreamWriteException is thrown if not all bytes could be written.