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.
Functions
Function CasedFileName$(path$) |
Description | Returns a case sensitive filename if it exists from a case insensitive file path. |
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 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 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 Eof( stream:TStream ) |
Returns | True If stream is at end of file. |
Description | Get stream end of file status. |
Function FlushStream( stream:TStream ) |
Description | Flush a stream. |
Information | FlushStream writes any outstanding buffered data to stream. |
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 End of file is reached) is read into a Byte array. |
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 End of file is reached) is read into a String. |
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 ReadByte( stream:TStream ) |
Returns | A Byte value. |
Description | Read a Byte from a stream. |
Information | ReadByte reads a single Byte from stream.
A TStreamReadExcpetion 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 ReadFloat#( stream:TStream ) |
Returns | A Float value. |
Description | Read a Float from a stream. |
Information | ReadFloat reads 4 bytes from stream.
A TStreamReadExcpetion 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 TStreamReadExcpetion is thrown If there is not enough data available. |
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 ReadLong:Long( stream:TStream ) |
Returns | A Long value. |
Description | Read a Long from a stream. |
Information | ReadLong reads 8 bytes from stream.
A TStreamReadExcpetion 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 TStreamReadExcpetion is thrown If there is not enough data available. |
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 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 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 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 SeekStream( stream:TStream,pos ) |
Returns | New stream position, or -1 If stream is not seekable. |
Description | Set stream position of seekable stream. |
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 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 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 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 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 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 "~r~n". |
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 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 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 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. |
Types
Type TCStream Extends TStream |
Description | Standard C file stream type. |
Function CreateWithCStream:TCStream( cstream,mode ) |
Description | Create a TCStream from a 'C' stream handle. |
Function OpenFile:TCStream( path$,readable,writeable ) |
Description | Create a TCStream from a 'C' filename. |
Type TIO |
Description | Base input/output type. |
Information | 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. |
Method Close() |
Description | Close stream. |
Information | Closes the stream after flushing any internal stream buffers. |
Method Eof() |
Returns | True for end of file reached, otherwise False. |
Description | Get stream end of file status. |
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. |
Method Flush() |
Description | Flush stream. |
Information | Flushes any internal stream buffers. |
Method Pos() |
Returns | Stream position as a byte offset, or -1 if stream is not seekable. |
Description | Get position of seekable stream. |
Method Read( buf:Byte Ptr,count ) |
Returns | Number of bytes successfully read. |
Description | Read at least 1 byte from a stream. |
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. |
Method Seek( pos ) |
Returns | New stream position, or -1 if stream is not seekable. |
Description | Seek to position in seekable stream. |
Method Size() |
Returns | Size, in bytes, of seekable stream, or 0 if stream is not seekable. |
Description | Get size of seekable stream. |
Method Write( buf:Byte Ptr,count ) |
Returns | Number of bytes successfully written. |
Description | Write at least 1 byte to a stream. |
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. |
Type TStream Extends TIO |
Description | Data stream type. |
Information | 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. |
Method ReadByte() |
Returns | The read value. |
Description | Read a byte from the stream. |
Information | If a value could not be read (possibly due to end of file), a TStreamReadException is thrown. |
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. |
Method ReadDouble!() |
Returns | The read value. |
Description | Read a double (eight bytes) from the stream. |
Information | If a value could not be read (possibly due to end of file), a TStreamReadException is thrown. |
Method ReadFloat#() |
Returns | The read value. |
Description | Read a float (four bytes) from the stream. |
Information | If a value could not be read (possibly due to end of file), a TStreamReadException is thrown. |
Method ReadInt() |
Returns | The read value. |
Description | Read an int (four bytes) from the stream. |
Information | If a value could not be read (possibly due to end of file), a TStreamReadException is thrown. |
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. |
Method ReadLong:Long() |
Returns | The read value. |
Description | Read a long (eight bytes) from the stream. |
Information | If a value could not be read (possibly due to end of file), a TStreamReadException is thrown. |
Method ReadShort() |
Returns | The read value. |
Description | Read a short (two bytes) from the stream. |
Information | If a value could not be read (possibly due to end of file), a TStreamReadException is thrown. |
Method ReadString$( length ) |
Returns | A string composed of length bytes read from the stream. |
Description | Read characters from the stream. |
Information | A TStreamReadException is thrown if not all bytes could be read. |
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. |
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 TStreamWriteExcpetion is thrown. |
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 TWriteStreamException is thrown. This typically
occurs due to end of file. |
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 TStreamWriteExcpetion is thrown. |
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 TStreamWriteExcpetion is thrown. |
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 TStreamWriteExcpetion is thrown. |
Method WriteLine( str$ ) |
Returns | True if line successfully written, else False. |
Description | Write a line of text to the stream. |
Information | A sequence of bytes is written to the stream (one for each character in str)
followed by the line terminating sequence "~r~n". |
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 TStreamWriteExcpetion is thrown. |
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 TStreamWriteExcpetion is thrown. |
Method WriteString( str$ ) |
Description | Write characters to the stream. |
Information | A TStreamWriteException is thrown if not all bytes could be written. |
Type TStreamException |
Description | Base exception type thrown by streams. |
Type TStreamFactory |
Description | Base stream factory type. |
Information | 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'. |
Method CreateStream:TStream( url:Object,proto$,path$,readable,writeable ) Abstract |
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. |
Type TStreamReadException Extends TStreamException |
Description | Exception type thrown by streams in the event of read errors. |
Information | 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. |
Type TStreamWrapper Extends TStream |
Description | Utility stream wrapper type. |
Information | 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. |
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. |
Type TStreamWriteException Extends TStreamException |
Description | Exception type thrown by streams in the event of write errors. |
Information | 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. |
Module Information
Version | 1.07 |
Author | Mark Sibly |
License | Blitz Shared Source Code |
Copyright | Blitz Research Ltd |
Modserver | BRL |
History | 1.07 Release |
History | OpenStream protocol:: now case insensitive |
History | Fixed ReadString with 0 length strings |
History | Removed LoadStream - use LoadByteArray instead |
History | Removed AddStreamFactory function |
History | Added url parameter to TStreamFactory CreateStream method |
History | 1.06 Release |
History | Added checks to CStream for reading from write only stream and vice versa |
History | 1.05 Release |
History | Fixed Eof bug |
History | 1.04 Release |
History | Added LoadString |
History | Added LoadByteArray |
History | Cleaned up docs a bit |