Monkey Documentation

Class Stream

Streams are used to read or write data in a sequential manner. More...

Extended by:
Properties:
Methods:

Detailed Discussion

Streams are used to read or write data in a sequential manner.

The low level Read and Write methods can be used to transfer data directly to/from databuffer objects. These methods return the number of bytes actually transferred, which may be less than requested if an IO error occurs or end-of-file is reached.

The higher level read and write methods will throw a StreamReadError or StreamWriteError exception if an IO error occurs or end-file-file is reached during processing.

The Eof method can be used detect end-of-file status when reading a stream. If this method returns a non-0 value, there is no data left to be read.

Some types of streams are also seekable, meaning they support an internal 'position' variable that controls where data is read/written and may be manually modified.

Property Documentation

Method Eof : Int () Property

Returns 1 if end-of-file has been reached, -1 if an IO error has occurred or 0 if the stream can be read.

Method Length : Int () Property

Returns the stream length if the stream is seekable, else 0.

Method Position : Int () Property

Returns the read/write position within the stream if the stream is seekable, else 0.

Method Documentation

Method Close : Void ()

Closes the stream and released any OS resources in use.

This method should always be used when you are finished with a stream.

Method Read : Int ( buffer:DataBuffer, offset:Int, count:Int )

Reads count bytes from the stream into databuffer, starting at address offset within the databuffer.

Returns the number of bytes actually read. This may be less than count if an IO error occurs or end-of-file has been reached.

If count is non-zero, this method will block until either at least 1 byte is available to be read, an IO error occurs or end-of-file has been reached.

Method ReadAll : Void ( buffer:DataBuffer, offset:int, count:int )

Reads count bytes from the stream into databuffer, starting at address offset within the databuffer.

If count is non-zero, this method will block until all bytes have been read.

A StreamReadError is thrown if not all bytes could be read.

Method ReadAll : DataBuffer ()

Reads all remaining bytes from the stream into a databuffer.

Method ReadByte : Int ()

Reads an 8 bit byte from the stream.

A StreamReadError will be thrown if a value could not be read.

Method ReadFloat : Float ()

Reads a 32 bit float value from the stream.

A StreamReadError will be thrown if a value could not be read.

Method ReadInt : Int ()

Reads a 32 bit int value from the stream.

A StreamReadError will be thrown if a value could not be read.

Method ReadShort : Int ()

Reads a 16 bit int value from the stream.

A StreamReadError will be thrown if a value could not be read.

Method ReadString : String ( count:Int, encoding:String="utf8" )

Reads count bytes from the stream and converts them to a string using the given encoding.

encoding should be utf8 or ascii.

Method ReadString : String ( encoding:String="utf8" )

Reads all bytes from the stream until end-of-file and converts them to a string using the given encoding.

encoding should be utf8 or ascii.

Method Seek : Int ( position:Int )

If the stream is seekable, adjusts the read/write position within the stream and returns the new read/write position.

Method Write : Int ( buffer:DataBuffer, offset:Int, count:Int )

Writes count bytes from databuffer to the stream, starting at address offset within the databuffer.

Returns the number of bytes actually written. This will be the same as count unless an IO error has occured.

This method may block if the underlying stream is full.

Method WriteAll : Void ( buffer:DataBuffer, offset:Int, count:Int )

Writes count bytes from databuffer to the stream, starting at address offset within the databuffer.

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

Method WriteByte : Void ( value:Int )

Writes an 8 bit byte to the stream.

A StreamWriteError will be thrown if value could not be written.

Method WriteFloat : Void ( value:Float )

Writes a 32 bit float value to the stream.

A StreamWriteError will be thrown if value could not be written.

Method WriteInt : Void ( value:Int )

Writes a 32 bit int value to the stream.

A StreamWriteError will be thrown if value could not be written.

Method WriteShort : Void ( value:Int )

Write a 16 bit int value to the stream.

A StreamWriteError will be thrown if value could not be written.

Method WriteString : Void ( value:String, encoding:String="utf8" )

Writes a string to the stream using the given encoding.

encoding should be utf8 or ascii.