BRL.Stream: Functions Types Modinfo Source  

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$)
DescriptionReturns a case sensitive filename if it exists from a case insensitive file path.

Function CloseStream( stream:TStream )
DescriptionClose a stream.
InformationAll 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 )
DescriptionCopy bytes from one stream to another.
InformationCopyBytes 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 )
DescriptionCopy stream contents to another stream.
InformationCopyStream 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 )
ReturnsTrue If stream is at end of file.
DescriptionGet stream end of file status.

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

Function LoadByteArray:Byte[]( url:Object )
ReturnsA Byte array.
DescriptionLoad a Byte array from a stream.
InformationThe 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 )
ReturnsA String.
DescriptionLoad a String from a stream.
InformationThe 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 )
ReturnsA stream object.
DescriptionOpen a stream for reading/writing.
InformationAll streams created by OpenStream, ReadStream or WriteStream should eventually be closed using CloseStream.

Function ReadByte( stream:TStream )
ReturnsA Byte value.
DescriptionRead a Byte from a stream.
InformationReadByte reads a single Byte from stream. A TStreamReadExcpetion 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 ReadFloat#( stream:TStream )
ReturnsA Float value.
DescriptionRead a Float from a stream.
InformationReadFloat reads 4 bytes from stream. A TStreamReadExcpetion 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 TStreamReadExcpetion is thrown If there is not enough data available.

Function ReadLine$( stream:TStream )
ReturnsA string.
DescriptionRead a line of text from a stream.
InformationBytes 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 )
ReturnsA Long value.
DescriptionRead a Long from a stream.
InformationReadLong reads 8 bytes from stream. A TStreamReadExcpetion 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 TStreamReadExcpetion is thrown If there is not enough data available.

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 ReadString$( stream:TStream,length )
ReturnsA String of length length.
DescriptionRead a String from a stream.
InformationA TStreamReadException is thrown if not all bytes could be read.

Function SaveByteArray( byteArray:Byte[],url:Object )
DescriptionSave a Byte array to a stream.
InformationThe 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 )
DescriptionSave a String to a stream.
InformationThe 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 )
ReturnsNew stream position, or -1 If stream is not seekable.
DescriptionSet stream position of seekable stream.

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 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 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 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 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 WriteLine( stream:TStream,str$ )
ReturnsTrue if line successfully written, else False.
DescriptionWrite a line of text to a stream.
InformationA 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 )
DescriptionWrite a Long to a stream.
InformationWriteLong writes 8 bytes to stream. A TStreamWriteException is thrown if not all bytes could 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 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 WriteString( stream:TStream,str$ )
DescriptionWrite a String to a stream.
InformationEach character in str is written to stream.

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

Types

Type TCStream Extends TStream
DescriptionStandard C file stream type.
Function CreateWithCStream:TCStream( cstream,mode )
DescriptionCreate a TCStream from a 'C' stream handle.
Function OpenFile:TCStream( path$,readable,writeable )
DescriptionCreate a TCStream from a 'C' filename.

Type TIO
DescriptionBase input/output type.
InformationTo 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()
DescriptionClose stream.
InformationCloses the stream after flushing any internal stream buffers.
Method Eof()
ReturnsTrue for end of file reached, otherwise False.
DescriptionGet stream end of file status.
InformationFor 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()
DescriptionFlush stream.
InformationFlushes any internal stream buffers.
Method Pos()
ReturnsStream position as a byte offset, or -1 if stream is not seekable.
DescriptionGet position of seekable stream.
Method Read( buf:Byte Ptr,count )
ReturnsNumber of bytes successfully read.
DescriptionRead at least 1 byte from a stream.
InformationThis 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 )
ReturnsNew stream position, or -1 if stream is not seekable.
DescriptionSeek to position in seekable stream.
Method Size()
ReturnsSize, in bytes, of seekable stream, or 0 if stream is not seekable.
DescriptionGet size of seekable stream.
Method Write( buf:Byte Ptr,count )
ReturnsNumber of bytes successfully written.
DescriptionWrite at least 1 byte to a stream.
InformationThis 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
DescriptionData stream type.
InformationTStream 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()
ReturnsThe read value.
DescriptionRead a byte from the stream.
InformationIf a value could not be read (possibly due to end of file), a TStreamReadException is thrown.
Method ReadBytes( buf:Byte Ptr,count )
DescriptionReads bytes from a stream.
InformationReadBytes 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!()
ReturnsThe read value.
DescriptionRead a double (eight bytes) from the stream.
InformationIf a value could not be read (possibly due to end of file), a TStreamReadException is thrown.
Method ReadFloat#()
ReturnsThe read value.
DescriptionRead a float (four bytes) from the stream.
InformationIf a value could not be read (possibly due to end of file), a TStreamReadException is thrown.
Method ReadInt()
ReturnsThe read value.
DescriptionRead an int (four bytes) from the stream.
InformationIf a value could not be read (possibly due to end of file), a TStreamReadException is thrown.
Method ReadLine$()
DescriptionRead a line of text from the stream.
InformationBytes 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()
ReturnsThe read value.
DescriptionRead a long (eight bytes) from the stream.
InformationIf a value could not be read (possibly due to end of file), a TStreamReadException is thrown.
Method ReadShort()
ReturnsThe read value.
DescriptionRead a short (two bytes) from the stream.
InformationIf a value could not be read (possibly due to end of file), a TStreamReadException is thrown.
Method ReadString$( length )
ReturnsA string composed of length bytes read from the stream.
DescriptionRead characters from the stream.
InformationA TStreamReadException is thrown if not all bytes could be read.
Method SkipBytes( count )
DescriptionSkip bytes in a stream.
InformationSkipBytes 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 )
DescriptionWrite a byte to the stream.
InformationIf the value could not be written (possibly due to end of file), a TStreamWriteExcpetion is thrown.
Method WriteBytes( buf:Byte Ptr,count )
DescriptionWrites bytes to a stream.
InformationWriteBytes 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! )
DescriptionWrite a double (eight bytes) to the stream.
InformationIf the value could not be written (possibly due to end of file), a TStreamWriteExcpetion is thrown.
Method WriteFloat( n# )
DescriptionWrite a float (four bytes) to the stream.
InformationIf the value could not be written (possibly due to end of file), a TStreamWriteExcpetion is thrown.
Method WriteInt( n )
DescriptionWrite an int (four bytes) to the stream.
InformationIf the value could not be written (possibly due to end of file), a TStreamWriteExcpetion is thrown.
Method WriteLine( str$ )
ReturnsTrue if line successfully written, else False.
DescriptionWrite a line of text to the stream.
InformationA 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 )
DescriptionWrite a long (eight bytes) to the stream.
InformationIf the value could not be written (possibly due to end of file), a TStreamWriteExcpetion is thrown.
Method WriteShort( n )
DescriptionWrite a short (two bytes) to the stream.
InformationIf the value could not be written (possibly due to end of file), a TStreamWriteExcpetion is thrown.
Method WriteString( str$ )
DescriptionWrite characters to the stream.
InformationA TStreamWriteException is thrown if not all bytes could be written.

Type TStreamException
DescriptionBase exception type thrown by streams.

Type TStreamFactory
DescriptionBase stream factory type.
InformationStream 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
DescriptionCreate a stream based on a url object.
InformationTypes 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
DescriptionException type thrown by streams in the event of read errors.
InformationTStreamReadException 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
DescriptionUtility stream wrapper type.
InformationTStreamWrapper '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 )
DescriptionSet underlying stream.
InformationSets the stream to be 'wrapped'. All calls to TIO methods of this stream will be redirected to stream.

Type TStreamWriteException Extends TStreamException
DescriptionException type thrown by streams in the event of write errors.
InformationTStreamWriteException 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

Version1.07
AuthorMark Sibly
LicenseBlitz Shared Source Code
CopyrightBlitz Research Ltd
ModserverBRL
History1.07 Release
HistoryOpenStream protocol:: now case insensitive
HistoryFixed ReadString with 0 length strings
HistoryRemoved LoadStream - use LoadByteArray instead
HistoryRemoved AddStreamFactory function
HistoryAdded url parameter to TStreamFactory CreateStream method
History1.06 Release
HistoryAdded checks to CStream for reading from write only stream and vice versa
History1.05 Release
HistoryFixed Eof bug
History1.04 Release
HistoryAdded LoadString
HistoryAdded LoadByteArray
HistoryCleaned up docs a bit