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.
Returns: A stream object
All streams created by OpenStream, ReadStream or WriteStream should eventually be closed
using CloseStream.
Returns: A stream object
All streams created by OpenStream, ReadStream or WriteStream should eventually be closed
using CloseStream.
Returns: A stream object
All streams created by OpenStream, ReadStream or WriteStream should eventually be closed
using CloseStream.
Returns: True if stream is at end-of-file.
Returns: Current stream position, or -1 if stream is not random access
Returns: Stream size in bytes, or -1 if stream is not random access
Returns: New stream position, or -1 if stream is not random access
FlushStream writes any outstanding buffered data to stream.
All streams should be closed when they are no longer required. Closing a stream also flushes the stream before it closes.
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 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
Returns: A string of length length. A TStreamReadExcpetion is thrown if there is not enough data available.
Each character in str is written to stream.
A TStreamWriteException is thrown if not all characters could be written
Returns: A byte value
ReadByte reads a single byte from stream.
A TStreamReadExcpetion is thrown if there is not enough data available.
Returns: A short value
ReadShort reads 2 bytes from stream.
A TStreamReadExcpetion is thrown if there is not enough data available.
Returns: An int value
ReadInt reads 4 bytes from stream.
A TStreamReadExcpetion is thrown if there is not enough data available.
Returns: A long value
ReadLong reads 8 bytes from stream.
A TStreamReadExcpetion is thrown if there is not enough data available.
Returns: A float value
ReadFloat reads 4 bytes from stream.
A TStreamReadExcpetion is thrown if there is not enough data available.
Returns: A double value
ReadDouble reads 8 bytes from stream.
A TStreamWriteException is thrown if there is not enough data available.
WriteByte writes a single byte to stream.
A TStreamWriteException is thrown if the byte could not be written
WriteShort writes 2 bytes to stream.
A TStreamWriteException is thrown if not all bytes could be written
WriteInt writes 4 bytes to stream.
A TStreamWriteException is thrown if not all bytes could be written
WriteLong writes 8 bytes to stream.
A TStreamWriteException is thrown if not all bytes could be written
WriteFloat writes 4 bytes to stream.
A TStreamWriteException is thrown if not all bytes could be written
WriteDouble writes 8 bytes to stream.
A TStreamWriteException is thrown if not all bytes could be written
Returns: A Byte array
Bytes are read from from_stream and written to to_stream until the source stream returns Eof.
Returns: Number of bytes actually copied
Module | brl.stream |
Version | 1.00 |
Author | Mark Sibly |
License | Blitz Shared Source Code |
Copyright | Blitz Research Ltd |
Modserver | BRL |