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

TStreamException

Base exception type thrown by streams

TStreamReadException

Exception type thrown by streams in the event of read errors

TStreamReadException is usually thrown when a stream operation failed to read enough bytes. For example, if the stream ReadInt method fails to read 4 bytes, it will throw a TStreamReadException.

TStreamWriteException

Exception type thrown by streams in the event of write errors

TStreamWriteException is usually thrown when a stream operation failed to write enough bytes. For example, if the stream WriteInt method fails to write 4 bytes, it will throw a TStreamWriteException.

TIO

Base input/output type

To create your own stream types, you should extend TStream and implement at least these methods.

You should also make sure your stream can handle multiple calls to the Close method.

Methods

Eof
Pos
Size
Seek
Flush
Close
Read
Write

TIO: Methods

Eof

Method Eof()

Description: Get stream end of file status

Returns: True for end of file reached, otherwise False

Information: For seekable streams such as file streams, Eof generally returns True if the file position equals the file size. This means that no more bytes can be read from the stream. However, it may still be possible to write bytes, in which case the file will 'grow'.

For communication type streams such as socket streams, Eof returns True if the stream has been shut down for some reason - either locally or by the remote host. In this case, no more bytes can be read from or written to the stream.

Pos

Method Pos()

Description: Get position of seekable stream

Returns: Stream position as a byte offset, or -1 if stream is not seekable

Size

Method Size()

Description: Get size of seekable stream

Returns: Size, in bytes, of seekable stream, or 0 if stream is not seekable

Seek

Method Seek( pos )

Description: Seek to position in seekable stream

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

Flush

Method Flush()

Description: Flush stream

Information: Flushes any internal stream buffers.

Close

Method Close()

Description: Close stream

Information: Closes the stream after flushing any internal stream buffers.

Read

Method Read( buf:Byte Ptr,count )

Description: Read at least 1 byte from a stream

Returns: Number of bytes successfully read

Information: This method may 'block' if it is not possible to read at least one byte due to IO buffering.

If this method returns 0, the stream has reached end of file.

Write

Method Write( buf:Byte Ptr,count )

Description: Write at least 1 byte to a stream

Returns: Number of bytes successfully written

Information: This method may 'block' if it is not possible to write at least one byte due to IO buffering.

If this method returns 0, the stream has reached end of file.

TStream

Data stream type

TStream extends TIO to provide methods for reading and writing various types of values to and from a stream.

Note that methods dealing with strings - ReadLine, WriteLine, ReadString and WriteString - assume that strings are represented by bytes in the stream. In future, a more powerful TextStream type will be added capable of decoding text streams in multiple formats.

Methods

ReadBytes
WriteBytes
SkipBytes
ReadByte
WriteByte
ReadShort
WriteShort
ReadInt
WriteInt
ReadLong
WriteLong
ReadFloat
WriteFloat
ReadDouble
WriteDouble
ReadLine
WriteLine
ReadString
WriteString

TStream: Methods

ReadBytes

Method ReadBytes( buf:Byte Ptr,count )

Description: Reads bytes from a stream

Information: ReadBytes reads count bytes from the stream into the memory block specified by buf.

If count bytes were not successfully read, a TStreamReadException is thrown. This typically occurs due to end of file.

WriteBytes

Method WriteBytes( buf:Byte Ptr,count )

Description: Writes bytes to a stream

Information: WriteBytes writes count bytes from the memory block specified by buf to the stream.

If count bytes were not successfully written, a TStreamWriteException is thrown. This typically occurs due to end of file.

SkipBytes

Method SkipBytes( count )

Description: Skip bytes in a stream

Information: SkipBytes read count bytes from the stream and throws them away.

If count bytes were not successfully read, a TStreamReadException is thrown. This typically occurs due to end of file.

ReadByte

Method ReadByte()

Description: Read a byte from the stream

Returns: The read value

Information: If a value could not be read (possibly due to end of file), a TStreamReadException is thrown.

WriteByte

Method WriteByte( n )

Description: Write a byte to the stream

Information: If the value could not be written (possibly due to end of file), a TStreamWriteException is thrown.

ReadShort

Method ReadShort()

Description: Read a short (two bytes) from the stream

Returns: The read value

Information: If a value could not be read (possibly due to end of file), a TStreamReadException is thrown.

WriteShort

Method WriteShort( n )

Description: Write a short (two bytes) to the stream

Information: If the value could not be written (possibly due to end of file), a TStreamWriteException is thrown.

ReadInt

Method ReadInt()

Description: Read an int (four bytes) from the stream

Returns: The read value

Information: If a value could not be read (possibly due to end of file), a TStreamReadException is thrown.

WriteInt

Method WriteInt( n )

Description: Write an int (four bytes) to the stream

Information: If the value could not be written (possibly due to end of file), a TStreamWriteException is thrown.

ReadLong

Method ReadLong:Long()

Description: Read a long (eight bytes) from the stream

Returns: The read value

Information: If a value could not be read (possibly due to end of file), a TStreamReadException is thrown.

WriteLong

Method WriteLong( n:Long )

Description: Write a long (eight bytes) to the stream

Information: If the value could not be written (possibly due to end of file), a TStreamWriteException is thrown.

ReadFloat

Method ReadFloat#()

Description: Read a float (four bytes) from the stream

Returns: The read value

Information: If a value could not be read (possibly due to end of file), a TStreamReadException is thrown.

WriteFloat

Method WriteFloat( n# )

Description: Write a float (four bytes) to the stream

Information: If the value could not be written (possibly due to end of file), a TStreamWriteException is thrown.

ReadDouble

Method ReadDouble!()

Description: Read a double (eight bytes) from the stream

Returns: The read value

Information: If a value could not be read (possibly due to end of file), a TStreamReadException is thrown.

WriteDouble

Method WriteDouble( n! )

Description: Write a double (eight bytes) to the stream

Information: If the value could not be written (possibly due to end of file), a TStreamWriteException is thrown.

ReadLine

Method ReadLine$()

Description: Read a line of text from the stream

Information: Bytes are read from the 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.

WriteLine

Method WriteLine( str$ )

Description: Write a line of text to the stream

Returns: True if line successfully written, else False

Information: A sequence of bytes is written to the stream (one for each character in str) followed by the line terminating sequence "~r~n".

ReadString

Method ReadString$( length )

Description: Read characters from the stream

Returns: A string composed of length bytes read from the stream

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

WriteString

Method WriteString( str$ )

Description: Write characters to the stream

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

TStreamWrapper

Utility stream wrapper type

TStreamWrapper 'wraps' an existing stream, redirecting all TIO method calls to the wrapped stream.

This can be useful for writing stream 'filters' that modify the behaviour of existing streams.

Note that the Close method causes the underlying stream to be closed, which may not always be desirable. If necessary, you should override Close with a NOP version.

Methods

SetStream

TStreamWrapper: Methods

SetStream

Method SetStream( stream:TStream )

Description: Set underlying stream

Information: Sets the stream to be 'wrapped'. All calls to TIO methods of this stream will be redirected to stream.

TCStream

Standard C file stream type

Functions

OpenFile
CreateWithCStream

TCStream: Functions

OpenFile

Function OpenFile:TCStream( path$,readable,writeable )

Description: Create a TCStream from a 'C' filename

CreateWithCStream

Function CreateWithCStream:TCStream( cstream,mode )

Description: Create a TCStream from a 'C' stream handle

TStreamFactory

Base stream factory type

Stream factories are used by the OpenStream, ReadStream and WriteStream functions to create streams based on a 'url object'.

Url objects are usually strings, in which case the url is divided into 2 parts - a protocol and a path. These are separated by a double colon string - "::".

To create your own stream factories, you should extend the TStreamFactory type and implement the CreateStream method.

To install your stream factory, simply create an instance of it using 'New'.

Methods

CreateStream

TStreamFactory: Methods

CreateStream

Method CreateStream:TStream( url:Object,proto$,path$,readable,writeable )

Description: Create a stream based on a url object

Information: Types which extends TStreamFactory must implement this method.

url contains the original url object as supplied to OpenStream, ReadStream or WriteStream.

If url is a string, proto contains the url protocol - for example, the "incbin" part of "incbin::myfile".

If url is a string, path contains the remainder of the url - for example, the "myfile" part of "incbin::myfile".

If url is not a string, both proto and path will be Null.

Functions

OpenStream

Function OpenStream:TStream( url:Object,readable=True,writeable=True )

Description: Open a stream for reading/writing

Returns: A stream object

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

ReadStream

Function ReadStream:TStream( url:Object )

Description: Open a stream for reading

Returns: A stream object

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

WriteStream

Function WriteStream:TStream( url:Object )

Description: Open a stream for writing

Returns: A stream object

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

Eof

Function Eof( stream:TStream )

Description: Get stream end of file status

Returns: True If stream is at end of file

StreamPos

Function StreamPos( stream:TStream )

Description: Get current position of seekable stream

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

StreamSize

Function StreamSize( stream:TStream )

Description: Get current size of seekable stream

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

SeekStream

Function SeekStream( stream:TStream,pos )

Description: Set stream position of seekable stream

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

FlushStream

Function FlushStream( stream:TStream )

Description: Flush a stream

Information: FlushStream writes any outstanding buffered data to stream.

CloseStream

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.

ReadByte

Function ReadByte( stream:TStream )

Description: Read a Byte from a stream

Returns: A Byte value

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

ReadShort

Function ReadShort( stream:TStream )

Description: Read a Short from a stream

Returns: A Short value

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

ReadInt

Function ReadInt( stream:TStream )

Description: Read an Int from a stream

Returns: An Int value

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

ReadLong

Function ReadLong:Long( stream:TStream )

Description: Read a Long from a stream

Returns: A Long value

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

ReadFloat

Function ReadFloat#( stream:TStream )

Description: Read a Float from a stream

Returns: A Float value

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

ReadDouble

Function ReadDouble!( stream:TStream )

Description: Read a Double from a stream

Returns: A Double value

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

WriteByte

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

WriteShort

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

WriteInt

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

WriteLong

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

WriteFloat

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

WriteDouble

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

ReadString

Function ReadString$( stream:TStream,length )

Description: Read a String from a stream

Returns: A String of length length

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

WriteString

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.

ReadLine

Function ReadLine$( stream:TStream )

Description: Read a line of text from a stream

Returns: A string

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.

WriteLine

Function WriteLine( stream:TStream,str$ )

Description: Write a line of text to a stream

Returns: True if line successfully written, else False

Information: A sequence of bytes is written to the stream (one for each character in str) followed by the line terminating sequence "~r~n".

LoadString

Function LoadString$( url:Object )

Description: Load a String from a stream

Returns: A String

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.

SaveString

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.

LoadByteArray

Function LoadByteArray:Byte[]( url:Object )

Description: Load a Byte array from a stream

Returns: A Byte array

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.

SaveByteArray

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.

CopyStream

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.

CopyBytes

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.

CasedFileName

Function CasedFileName$(path$)

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