Streams

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 commands. To read from a stream, use one of the read commands.

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 the CloseStream command. Failure to do so may result in a resource leak, or prevent the stream from successfully opening in future.

Function reference

OpenStream:TStream( url:Object,readable=True,writeable=True )   Open a stream for reading/writing

Returns: A stream object

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


ReadStream:TStream( url:Object )   Open a stream for reading

Returns: A stream object

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 WriteStream to file mypage.htmlhttp::www.blitzbasic.com"

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

WriteStream:TStream( url:Object )   Open a stream for writing

Returns: A stream object

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")

Eof( stream:TStream )   Get stream eof-of-file status

Returns: True if stream is at end-of-file.


StreamPos( stream:TStream )   Get stream position

Returns: Current stream position, or -1 if stream is not random access


StreamSize( stream:TStream )   Get stream size

Returns: Stream size in bytes, or -1 if stream is not random access


SeekStream( stream:TStream,pos )   Set stream position

Returns: New stream position, or -1 if stream is not random access


FlushStream( stream:TStream )   Flush a stream

FlushStream writes any outstanding buffered data to stream.


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.


ReadLine$( stream:TStream )   Read a line of text from a stream

Returns: A string

ReadLine reads a sequence of bytes from a stream until a newline character (ascii code 10) is read. Any carriage return characters encountered (ascii code 13) are ignored. The bytes read are returned in the form of a string, excluding the newline character.


WriteLine( stream:TStream,str$ )   Write a line of text to a stream

WriteLine writes a sequence of bytes (one for each character in str) to stream, followed by the line terminating sequence "~r~n". A TStreamWriteException is thrown if not all characters could be written


ReadString$( stream:TStream,length )   Read a string from a string

Returns: A string of length length. A TStreamReadExcpetion is thrown if there is not enough data available.


WriteString( stream:TSTream,str$ )   Write a string to stream

Each character in str is written to stream. A TStreamWriteException is thrown if not all characters could be written


ReadByte( stream:TStream )   Read a byte from a stream

Returns: A byte value

ReadByte reads a single byte from stream. A TStreamReadExcpetion is thrown if there is not enough data available.


ReadShort( stream:TStream )   Read a short from a stream

Returns: A short value

ReadShort reads 2 bytes from stream. A TStreamReadExcpetion is thrown if there is not enough data available.


Readint( stream:TStream )   Read an int from a stream

Returns: An int value

ReadInt reads 4 bytes from stream. A TStreamReadExcpetion is thrown if there is not enough data available.


ReadLong:Long( stream:TStream )   Read a long from a stream

Returns: A long value

ReadLong reads 8 bytes from stream. A TStreamReadExcpetion is thrown if there is not enough data available.


ReadFloat#( stream:TStream )   Read a float from a stream

Returns: A float value

ReadFloat reads 4 bytes from stream. A TStreamReadExcpetion is thrown if there is not enough data available.


ReadDouble!( stream:TStream )   Read a double from a stream

Returns: A double value

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


WriteByte( stream:TStream,n )   Write a byte to a stream

WriteByte writes a single byte to stream. A TStreamWriteException is thrown if the byte could not be written


WriteShort( stream:TStream,n )   Write a short to a stream

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


WriteInt( stream:TStream,n )   Write an int to a stream

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


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


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


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


LoadStream:Byte[]( url:Object )   Load stream contents into an array

Returns: A Byte array


CopyStream( from_stream:TStream,to_stream:TStream,buf_size=4096 )   Copy stream contents to another stream

Bytes are read from from_stream and written to to_stream until the source stream returns Eof.


CopyBytes( from_stream:TStream,to_stream:TStream,count,buf_size=4096 )   Copy bytes from one stream to another

Returns: Number of bytes actually copied


CasedFileName$(path$)   Returns a case sensitive filename if it exists from a case insensitive file path.

Module Information

Modulebrl.stream
Version 1.00
Author Mark Sibly
License Blitz Shared Source Code
Copyright Blitz Research Ltd
Modserver BRL