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
Functions
Function reference
Function OpenStream:TStream( url:Object,readable=True,writeable=True ) |
Returns | A stream object
|
Description | Open a stream for reading/writing |
Information | All streams created by OpenStream, ReadStream or WriteStream should eventually be
closed using CloseStream.
|
Function ReadStream:TStream( url:Object ) |
Returns | A stream object
|
Description | Open a stream for reading |
Information | All 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 ) |
Returns | A stream object
|
Description | Open a stream for writing |
Information | All 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 ) |
Returns | True If stream is at end of file
|
Description | Get stream end of file status |
Function StreamPos( stream:TStream ) |
Returns | Current stream position, or -1 If stream is not seekable
|
Description | Get current position of seekable stream |
Function StreamSize( stream:TStream ) |
Returns | Current stream size in bytes, or -1 If stream is not seekable
|
Description | Get current size of seekable stream |
Function SeekStream( stream:TStream,pos ) |
Returns | New stream position, or -1 If stream is not seekable
|
Description | Set stream position of seekable stream |
Function FlushStream( stream:TStream ) |
Description | Flush a stream |
Information | FlushStream writes any outstanding buffered data to stream.
|
Function CloseStream( stream:TStream ) |
Description | Close 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 ) |
Returns | A Byte value
|
Description | Read a Byte from a stream |
Information | ReadByte reads a single Byte from stream.
A TStreamReadException is thrown If there is not enough data available.
|
Function ReadShort( stream:TStream ) |
Returns | A Short value
|
Description | Read a Short from a stream |
Information | ReadShort reads 2 bytes from stream.
A TStreamReadException is thrown If there is not enough data available.
|
Function ReadInt( stream:TStream ) |
Returns | An Int value
|
Description | Read an Int from a stream |
Information | ReadInt reads 4 bytes from stream.
A TStreamReadException is thrown If there is not enough data available.
|
Function ReadLong:Long( stream:TStream ) |
Returns | A Long value
|
Description | Read a Long from a stream |
Information | ReadLong reads 8 bytes from stream.
A TStreamReadException is thrown If there is not enough data available.
|
Function ReadFloat#( stream:TStream ) |
Returns | A Float value
|
Description | Read a Float from a stream |
Information | ReadFloat reads 4 bytes from stream.
A TStreamReadException is thrown If there is not enough data available.
|
Function ReadDouble!( stream:TStream ) |
Returns | A Double value
|
Description | Read a Double from a stream |
Information | ReadDouble reads 8 bytes from stream.
A TStreamWriteException is thrown If there is not enough data available.
|
Function WriteByte( stream:TStream,n ) |
Description | Write a Byte to a stream |
Information | WriteByte writes a single Byte to stream.
A TStreamWriteException is thrown If the Byte could Not be written
|
Function WriteShort( stream:TStream,n ) |
Description | Write a Short to a stream |
Information | WriteShort writes 2 bytes to stream.
A TStreamWriteException is thrown if not all bytes could be written
|
Function WriteInt( stream:TStream,n ) |
Description | Write an Int to a stream |
Information | WriteInt writes 4 bytes to stream.
A TStreamWriteException is thrown if not all bytes could be written
|
Function WriteLong( stream:TStream,n:Long ) |
Description | Write a Long to a stream |
Information | WriteLong writes 8 bytes to stream.
A TStreamWriteException is thrown if not all bytes could be written
|
Function WriteFloat( stream:TStream,n# ) |
Description | Write a Float to a stream |
Information | WriteFloat writes 4 bytes to stream.
A TStreamWriteException is thrown if not all bytes could be written
|
Function WriteDouble( stream:TStream,n! ) |
Description | Write a Double to a stream |
Information | WriteDouble writes 8 bytes to stream.
A TStreamWriteException is thrown if not all bytes could be written
|
Function ReadString$( stream:TStream,length ) |
Returns | A String of length length
|
Description | Read a String from a stream |
Information |
A TStreamReadException is thrown if not all bytes could be read.
|
Function WriteString( stream:TStream,str$ ) |
Description | Write 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 ) |
Returns | A string
|
Description | Read 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$ ) |
Returns | True if line successfully written, else False
|
Description | Write 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 ) |
Returns | A String
|
Description | Load 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 ) |
Description | Save 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 ) |
Returns | A Byte array
|
Description | Load 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 ) |
Description | Save 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 ) |
Description | Copy 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 ) |
Description | Copy 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$) |
Description | Returns a case sensitive filename if it exists from a case insensitive file path. |