BRL.Stream: Types Functions Source  


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

TStreamExceptionBase exception type thrown by streams
TStreamReadExceptionException type thrown by streams in the event of read errors
TStreamWriteExceptionException type thrown by streams in the event of write errors
TIOBase input/output type
TStreamData stream type
TStreamWrapperUtility stream wrapper type
TCStreamStandard C file stream type
TStreamFactoryBase stream factory type

Functions

OpenStreamOpen a stream for reading/writing
ReadStreamOpen a stream for reading
WriteStreamOpen a stream for writing
EofGet stream end of file status
StreamPosGet current position of seekable stream
StreamSizeGet current size of seekable stream
SeekStreamSet stream position of seekable stream
FlushStreamFlush a stream
CloseStreamClose a stream
ReadByteRead a Byte from a stream
ReadShortRead a Short from a stream
ReadIntRead an Int from a stream
ReadLongRead a Long from a stream
ReadFloatRead a Float from a stream
ReadDoubleRead a Double from a stream
WriteByteWrite a Byte to a stream
WriteShortWrite a Short to a stream
WriteIntWrite an Int to a stream
WriteLongWrite a Long to a stream
WriteFloatWrite a Float to a stream
WriteDoubleWrite a Double to a stream
ReadStringRead a String from a stream
WriteStringWrite a String to a stream
ReadLineRead a line of text from a stream
WriteLineWrite a line of text to a stream
LoadStringLoad a String from a stream
SaveStringSave a String to a stream
LoadByteArrayLoad a Byte array from a stream
SaveByteArraySave a Byte array to a stream
CopyStreamCopy stream contents to another stream
CopyBytesCopy bytes from one stream to another
CasedFileNameReturns a case sensitive filename if it exists from a case insensitive file path.

Function reference

Function OpenStream:TStream( url:Object,readable=True,writeable=True )
ReturnsA stream object
DescriptionOpen a stream for reading/writing
InformationAll streams created by OpenStream, ReadStream or WriteStream should eventually be closed using CloseStream.

Function ReadStream:TStream( url:Object )
ReturnsA stream object
DescriptionOpen a stream for reading
InformationAll streams created by OpenStream, ReadStream or WriteStream should eventually be closed using CloseStream.
Example
' readstream.bmx

' opens a read stream to the blitzbasic.com website and
' dumps the homepage to the console using readline and print

in=ReadStream("http::blitzbasic.com")

If Not in RuntimeError "Failed to open a ReadStream to file http::www.blitzbasic.com"

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

Function WriteStream:TStream( url:Object )
ReturnsA stream object
DescriptionOpen a stream for writing
InformationAll streams created by OpenStream, ReadStream or WriteStream should eventually be closed using CloseStream.
Example
' writestream.bmx

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

out=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 Eof( stream:TStream )
ReturnsTrue If stream is at end of file
DescriptionGet stream end of file status

Function StreamPos( stream:TStream )
ReturnsCurrent stream position, or -1 If stream is not seekable
DescriptionGet current position of seekable stream

Function StreamSize( stream:TStream )
ReturnsCurrent stream size in bytes, or -1 If stream is not seekable
DescriptionGet current size of seekable stream

Function SeekStream( stream:TStream,pos )
ReturnsNew stream position, or -1 If stream is not seekable
DescriptionSet stream position of seekable stream

Function FlushStream( stream:TStream )
DescriptionFlush a stream
InformationFlushStream writes any outstanding buffered data to stream.

Function CloseStream( stream:TStream )
DescriptionClose a stream
Information All streams should be closed when they are no longer required. Closing a stream also flushes the stream before it closes.

Function ReadByte( stream:TStream )
ReturnsA Byte value
DescriptionRead a Byte from a stream
InformationReadByte reads a single Byte from stream. A TStreamReadException is thrown If there is not enough data available.

Function ReadShort( stream:TStream )
ReturnsA Short value
DescriptionRead a Short from a stream
InformationReadShort reads 2 bytes from stream. A TStreamReadException is thrown If there is not enough data available.

Function ReadInt( stream:TStream )
ReturnsAn Int value
DescriptionRead an Int from a stream
InformationReadInt reads 4 bytes from stream. A TStreamReadException is thrown If there is not enough data available.

Function ReadLong:Long( stream:TStream )
ReturnsA Long value
DescriptionRead a Long from a stream
InformationReadLong reads 8 bytes from stream. A TStreamReadException is thrown If there is not enough data available.

Function ReadFloat#( stream:TStream )
ReturnsA Float value
DescriptionRead a Float from a stream
InformationReadFloat reads 4 bytes from stream. A TStreamReadException is thrown If there is not enough data available.

Function ReadDouble!( stream:TStream )
ReturnsA Double value
DescriptionRead a Double from a stream
InformationReadDouble reads 8 bytes from stream. A TStreamWriteException is thrown If there is not enough data available.

Function WriteByte( stream:TStream,n )
DescriptionWrite a Byte to a stream
InformationWriteByte writes a single Byte to stream. A TStreamWriteException is thrown If the Byte could Not be written

Function WriteShort( stream:TStream,n )
DescriptionWrite a Short to a stream
InformationWriteShort writes 2 bytes to stream. A TStreamWriteException is thrown if not all bytes could be written

Function WriteInt( stream:TStream,n )
DescriptionWrite an Int to a stream
InformationWriteInt writes 4 bytes to stream. A TStreamWriteException is thrown if not all bytes could be written

Function WriteLong( stream:TStream,n:Long )
DescriptionWrite a Long to a stream
InformationWriteLong writes 8 bytes to stream. A TStreamWriteException is thrown if not all bytes could be written

Function WriteFloat( stream:TStream,n# )
DescriptionWrite a Float to a stream
InformationWriteFloat writes 4 bytes to stream. A TStreamWriteException is thrown if not all bytes could be written

Function WriteDouble( stream:TStream,n! )
DescriptionWrite a Double to a stream
InformationWriteDouble writes 8 bytes to stream. A TStreamWriteException is thrown if not all bytes could be written

Function ReadString$( stream:TStream,length )
ReturnsA String of length length
DescriptionRead a String from a stream
Information A TStreamReadException is thrown if not all bytes could be read.

Function WriteString( stream:TStream,str$ )
DescriptionWrite a String to a stream
Information Each character in str is written to stream.

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

Function ReadLine$( stream:TStream )
ReturnsA string
DescriptionRead a line of text from a stream
Information 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.

Function WriteLine( stream:TStream,str$ )
ReturnsTrue if line successfully written, else False
DescriptionWrite a line of text to a stream
Information A sequence of bytes is written to the stream (one for each character in str) followed by the line terminating sequence "rn".

Function LoadString$( url:Object )
ReturnsA String
DescriptionLoad a String from a stream
Information 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.

Function SaveString( str$,url:Object )
DescriptionSave a String to a stream
Information 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 )
ReturnsA Byte array
DescriptionLoad a Byte array from a stream
Information The specified url is opened for reading, and each byte in the resultant stream (until eof of reached) is read into a byte array.

Function SaveByteArray( byteArray:Byte[],url:Object )
DescriptionSave a Byte array to a stream
Information 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=4096 )
DescriptionCopy stream contents to another stream
Information 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,bufSize=4096 )
DescriptionCopy bytes from one stream to another
Information 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$)
DescriptionReturns a case sensitive filename if it exists from a case insensitive file path.