BRL.Stream · BlitzMax

Streams are used to read or write data in a sequential manner.

BlitzMax supports many kinds of streams, including standard file streams (for reading and writing to files), bank streams (for reading and writing to banks) and endian streams (for swapping the byte order of stream data).

Streams are usually created using OpenStream, ReadStream or WriteStream. However, some kinds of streams provide their own methods for creating streams. For example, banks streams are created with the CreateBankStream command.

OpenStream, ReadStream and WriteStream all require a url parameter, which is used to 'locate' the stream. A url is usually a string value.

If the url contains the string "::", then a stream protocol is being specified. If not, then the url is assumed to be a simple filename.

External modules can add their own stream protocols to the system, allowing you to use streams for a wide variety of purposes. For example, the "incbin::" protocol allows you to read data from a binary file that has been embedded in an application using the Incbin command.

Other protocols include "http::" for reading and writing data over a network, and "littleendian::" and "bigendian::" for swapping the byte order of streams.

To write to a stream, use one of the 'Write' style commands, such as WriteByte.

To read from a stream, use one of the 'Read' style commands, such as ReadByte.

Some kinds of streams (for example, file streams and bank streams) support random access. This means that you can modify where in the stream the next read or write is to occur using the SeekStream command. You can also tell where you are in such streams using the StreamPos command.

When you are finished with a stream, you should always close it using CloseStream. Failure to do so may result in a resource leak, or prevent the stream from successfully opening in future.

Types

Type	Description
TStreamException	Base exception type thrown by streams
TStreamReadException	Exception type thrown by streams in the event of read errors
TStreamWriteException	Exception type thrown by streams in the event of write errors
TIO	Base input/output type
TStream	Data stream type
TStreamWrapper	Utility stream wrapper type
TCStream	Standard C file stream type
TStreamFactory	Base stream factory type

Functions

`Function OpenStream:TStream( url:Object,readable:Int=True,writeMode:Int=WRITE_MODE_OVERWRITE )`

Open a stream for reading/writing/appending

All streams created by OpenStream, ReadStream, WriteStream or AppendStream should eventually be closed using CloseStream.

Returns

A stream object

`Function ReadStream:TStream( url:Object )`

Open a stream for reading

All streams created by OpenStream, ReadStream or WriteStream should eventually be closed using CloseStream.

Returns

A stream object

Example

' readstream.bmx

' opens a read stream to the blitzmax.org website and
' dumps the content to the console using readline and print

SuperStrict

Local in:TStream = ReadStream("http::blitzmax.org")

If Not in RuntimeError "Failed to open a ReadStream to file http::blitzmax.org"

While Not Eof(in)
    Print ReadLine(in)
Wend
CloseStream in

`Function WriteStream:TStream( url:Object )`

Open a stream for writing

All streams created by OpenStream, ReadStream, WriteStream or AppendStream should eventually be closed using CloseStream.

Returns

A stream object

Example

' writestream.bmx

' opens a write stream to the file mygame.ini and
' outputs a simple text file using WriteLine

SuperStrict

Local out:TStream = WriteStream("mygame.ini")

If Not out RuntimeError "Failed to open a WriteStream to file mygame.ini"

WriteLine out,"[display]"
WriteLine out,"width=800"
WriteLine out,"height=600"
WriteLine out,"depth=32"
WriteLine out,""
WriteLine out,"[highscores]"
WriteLine out,"AXE=1000"
WriteLine out,"HAL=950"
WriteLine out,"MAK=920"

CloseStream out

Print "File mygame.ini created, bytes="+FileSize("mygame.ini")

`Function AppendStream:TStream( url:Object )`

Open a stream for appending

All streams created by OpenStream, ReadStream, WriteStream or AppendStream should eventually be closed using CloseStream.

Returns

A stream object

`Function Eof:Int( stream:TStream )`

Get stream end of file status

Returns

True If stream is at end of file

`Function StreamPos:Long( stream:TStream )`

Get current position of seekable stream

Returns

Current stream position, or -1 If stream is not seekable

`Function StreamSize:Long( stream:TStream )`

Get current size of seekable stream

Returns

Current stream size in bytes, or -1 If stream is not seekable

`Function SeekStream:Long( stream:TStream, pos:Long, whence:Int = SEEK_SET_ )`

Set stream position of seekable stream

Returns

New stream position, or -1 If stream is not seekable

`Function FlushStream( stream:TStream )`

Flush a stream

FlushStream writes any outstanding buffered data to stream.

`Function CloseStream( stream:TStream )`

Close a stream

All streams should be closed when they are no longer required. Closing a stream also flushes the stream before it closes.

`Function ReadByte:Int( stream:TStream )`

Read a Byte from a stream

ReadByte reads a single Byte from stream. A TStreamReadException is thrown If there is not enough data available.

Returns

A Byte value

`Function ReadShort:Int( stream:TStream )`

Read a Short from a stream

ReadShort reads 2 bytes from stream. A TStreamReadException is thrown If there is not enough data available.

Returns

A Short value

`Function ReadInt:Int( stream:TStream )`

Read an Int from a stream

ReadInt reads 4 bytes from stream. A TStreamReadException is thrown If there is not enough data available.

Returns

An Int value

`Function ReadLong:Long( stream:TStream )`

Read a Long from a stream

ReadLong reads 8 bytes from stream. A TStreamReadException is thrown If there is not enough data available.

Returns

A Long value

`Function ReadFloat#( stream:TStream )`

Read a Float from a stream

ReadFloat reads 4 bytes from stream. A TStreamReadException is thrown If there is not enough data available.

Returns

A Float value

`Function ReadDouble!( stream:TStream )`

Read a Double from a stream

ReadDouble reads 8 bytes from stream. A TStreamWriteException is thrown If there is not enough data available.

Returns

A Double value

`Function WriteByte( stream:TStream,n:Int )`

Write a Byte to a stream

WriteByte writes a single Byte to stream. A TStreamWriteException is thrown If the Byte could Not be written

`Function WriteShort( stream:TStream,n:Int )`

Write a Short to a stream

WriteShort writes 2 bytes to stream. A TStreamWriteException is thrown if not all bytes could be written

`Function WriteInt( stream:TStream,n:Int )`

Write an Int to a stream

WriteInt writes 4 bytes to stream. A TStreamWriteException is thrown if not all bytes could be written

`Function WriteLong( stream:TStream,n:Long )`

Write a Long to a stream

WriteLong writes 8 bytes to stream. A TStreamWriteException is thrown if not all bytes could be written

`Function WriteFloat( stream:TStream,n# )`

Write a Float to a stream

WriteFloat writes 4 bytes to stream. A TStreamWriteException is thrown if not all bytes could be written

`Function WriteDouble( stream:TStream,n! )`

Write a Double to a stream

WriteDouble writes 8 bytes to stream. A TStreamWriteException is thrown if not all bytes could be written

`Function ReadString$( stream:TStream,length:Int )`

Read a String from a stream

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

Returns

A String of length length

`Function WriteString( stream:TStream,str$ )`

Write a String to a stream

Each character in str is written to stream.

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

`Function ReadLine$( stream:TStream )`

Read a line of text from a stream

Bytes are read from stream until a newline character (ascii code 10) or null character (ascii code 0) is read, or end of file is detected.

Carriage Return characters (ascii code 13) are silently ignored.

The bytes read are returned in the form of a string, excluding any terminating newline or null character.

Returns

A string

`Function WriteLine:Int( stream:TStream,str$ )`

Write a line of text to a stream

A sequence of bytes is written to the stream (one for each character in str) followed by the line terminating sequence "rn".

Returns

True if line successfully written, else False

`Function LoadString$( url:Object )`

Load a String from a stream

The specified url is opened for reading, and each byte in the resultant stream (until eof of file is reached) is read into a string.

A TStreamReadException is thrown if the stream could not be read.

Returns

A String

`Function SaveString( str$,url:Object )`

Save a String to a stream

The specified url is opened For writing, and each character of str is written to the resultant stream.

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

`Function LoadByteArray:Byte[]( url:Object )`

Load a Byte array from a stream

The specified url is opened for reading, and each byte in the resultant stream (until eof of reached) is read into a byte array.

Returns

A Byte array

`Function SaveByteArray( byteArray:Byte[],url:Object )`

Save a Byte array to a stream

The specified url is opened For writing, and each element of byteArray is written to the resultant stream.

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

`Function CopyStream( fromStream:TStream,toStream:TStream,bufSize:Int=4096 )`

Copy stream contents to another stream

CopyStream copies bytes from fromStream to toStream Until fromStream reaches end of file.

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

`Function CopyBytes( fromStream:TStream,toStream:TStream,count:Int,bufSize:Int=4096 )`

Copy bytes from one stream to another

CopyBytes copies count bytes from fromStream to toStream.

A TStreamReadException is thrown if not all bytes could be read, and a TStreamWriteException is thrown if not all bytes could be written.

`Function CasedFileName$(path$)`

Returns a case sensitive filename if it exists from a case insensitive file path.

Consts

`Const WRITE_MODE_OVERWRITE:Int = 1`

Opens a file for output operations.

`Const WRITE_MODE_APPEND:Int = 2`

Opens a file for appending with all output operations writing data at the end of the file.

Repositioning operations such as Seek affects the next input operations, but output operations move the position back to the end of file.