Index  |  Related pages  |  Classes  |  Functions  |  Entities  |  Function Sets  |  Groups

ClassStream

class Stream

Stream oriented I/O class. more...


Member list

Properties
encoding Name of the set encoding, if given, for text operations
eolMode Mode of EOL conversion in text operations.
Methods
clone Clone the stream handle.
close Closes the stream.
eof Checks if the last read operation hit the end of the file.
errorDescription Returns a system specific textual description of the last error.
flush Flushes a stream.
isOpen Checks if the stream is currently open.
lastError Return the last system error.
lastMoved Return the amount of data moved by the last operation.
read Reads binary data from the stream.
readAvailable Checks if data can be read, or wait for available data.
readItem Deserializes an item from the stream.
readLine Reads a line of text encoded data.
readText Reads text encoded data from the stream.
seek Moves the file pointer on seekable streams.
seekCur Moves the file pointer on seekable streams relative to current position.
seekEnd Moves the file pointer on seekable streams relative to end of file.
setEncoding Set the text encoding and EOL mode for text-based operations.
tell Return the current position in a stream.
truncate Resizes a file.
write Write binary data to a stream.
writeAvailable Checks if data can be written, or wait until it's possible to write.
writeItem Serializes an item to the stream.
writeText Write text data to a stream.

Detailed description

Stream class is a common interface for I/O operations. The class itself is to be considered “abstract”. It should never be directly instantiated, as factory functions, subclasses and embedding applications will provide fully readied stream objects.

Stream I/O is synchronous, but it's possible to wait for the operation to be nonblocking with the readAvailable() and writeAvailable() methods.

Generally, all the methods in the stream class raise an error in case of I/O failure.

Streams provide also a character encoding layer; readText() and writeText() are meant to decode and encode falcon strings based on character encoding set with setEncoding(). Method as read() and write() are not affected, and seek operations works bytewise regardless the character conversion being used.


Class properties

encoding
Name of the set encoding, if given, for text operations

eolMode
Mode of EOL conversion in text operations.


Class methods

clone()

Clone the stream handle.

Stream.clone( )
Returns:

A new copy of the stream handle.

Raises:
IoError

On stream error.

The resulting stream is interchangeable with the original one. From this point on, write and read operations are not reflected on the cloned object, so two stream objects can be effectively used to read and write at different places in the same resource, unless the underlying stream is not seekable (in which case, reads are destructive).

The underlying resource remains open until all the instances of the streams are closed.

close()

Closes the stream.

Stream.close( )

All the operations are flushes and system resources are freed. This method is also called automatically at garbage collection, if it has not been called before.

eof()

Checks if the last read operation hit the end of the file.

Stream.eof( )
Returns:

True if file pointer is at EOF.

Returns true if the last read operation hit the end of file.

errorDescription()

Returns a system specific textual description of the last error.

Stream.errorDescription( )
Returns:

A string describing the system error.

Returns a system specific textual description of the last error occurred on the stream.

flush()

Flushes a stream.

Stream.flush( )

Ensures that the operations on the stream are correctly flushed.

isOpen()

Checks if the stream is currently open.

Stream.isOpen( )
Returns:

True if the file is open.

Return true if the stream is currently open.

lastError()

Return the last system error.

Stream.lastError( )
Returns:

An error code.

Returns a system specific low level error code for last failed I/O operation on this stream, or zero if the last operation was succesful.

lastMoved()

Return the amount of data moved by the last operation.

Stream.lastMoved( )
Returns:

An amount of bytes.

Returns the amount of bytes moved by the last write or read operation, in bytes. This may differ from the count of characters written or read by text-oriented functions.

read()

Reads binary data from the stream.

Stream.read( buffer, [size] )
buffer

A string or MemBuf that will be filled with read data.

size

Optionally, a maximum size to be read.

Returns:

Amount of data actually read (or a new string).

Raises:
IoError

on system errors.

Read at maximum size bytes and returns the count of bytes that have been actually read. This version uses an already existing string as the destination buffer. If the string has not enough internal storage, it is reallocated to fit the required size. If the size parameter is not given, the internal storage size of the string is used as maximum read size; this is usually equal to len(buffer), but functions as strBuffer can create strings that have an internal storage wider than their length.

The buffer parameter may be omitted; in that case, it is necessary to pass the size parameter. This method will then create a string wide enough to store the incoming data.

readAvailable()

Checks if data can be read, or wait for available data.

Stream.readAvailable( [seconds] )
seconds

Maximum wait in seconds and fraction (defaults to infinite).

Returns:

True if data is available, false otherwise.

Raises:
IoError

On stream error.

InterruptedError

if the Virtual Machine is asynchronously interrupted.

This function checks if data is available on a stream to be read immediately, or if it becomes available during a determined time period. The seconds parameter may be set to zero to perform just a check, or to a positive value to wait for incoming data. If the parameter is not given, or if it's set to a negative value, the wait will be infinite.

A read after readAvailable has returned succesfully is granted not to be blocking (unless another coroutine or thread reads data from the same stream in the meanwhile). Performing a read after that readAvailable has returned false will probably block for an undefined amount of time.

This method complies with the interrupt_protocol of the Virtual Machine.

readItem()

Deserializes an item from the stream.

Stream.readItem( )
Returns:

The deserialized item.

Raises:
IoError

on underlying stream error.

GenericError

If the data is correctly de-serialized, but it refers to external symbols non defined by this script.

ParseError

if the format of the input data is invalid.

Deerializes an item from the given stream. This method works as deserialize, but it works as a method of this stream instead of being considered a function.

readLine()

Reads a line of text encoded data.

Stream.readLine( buffer, [size] )
buffer

A string that will be filled with read data.

size

Maximum count of characters to be read before to return anyway.

Returns:

Amount of data actually read (or a new string).

Raises:
IoError

on system errors.

This function works as Stream.readText, but if a new line is encountered, the read terminates. Returned string does not contain the EOL sequence.

As for readText, this function may accept a numeric size as first parameter; in that case it will autonomously create a string wide enough to store the incoming data.

readText()

Reads text encoded data from the stream.

Stream.readText( buffer, [size] )
buffer

A string that will be filled with read data.

size

Optionally, a maximum size to be read.

Returns:

Amount of data actually read (or a new string).

Raises:
IoError

on system errors.

This method reads a string from a stream, eventually parsing the input data through the given character encoding set by the Stream.setEncoding method. The number of bytes actually read may vary depending on the decoding rules.

If the size parameter is given, the function will try to read at maximum size characters, enlarging the buffer if there isn't enough room for the operation. If it is not given, the current allocated memory of buffer will be used instead.

The buffer parameter may be omitted; in that case, it is necessary to pass the size parameter. This method will then create a string wide enough to store the incoming data.

If the function is successful, the buffer may contain size characters or less if the stream hadn't enough characters to read.

In case of failure, an IoError is raised.

Notice that this function is meant to be used on streams that are known to have available all the required data. For streams that may perform partial updates (i.e. network streams), a combination of binary reads and transcodeFrom calls should be used instead.

seek()

Moves the file pointer on seekable streams.

Stream.seek( position )
position

Position in the stream to seek.

Returns:

Position in the stream after seek.

Raises:
IoError

on system errors.

Changes the position in the stream from which the next read/write operation will be performed. The position is relative from the start of the stream. If the stream does not support seeking, an IoError is raised; if the position is greater than the stream size, the pointer is set to the end of the file. On success, it returns the actual position in the file.

seekCur()

Moves the file pointer on seekable streams relative to current position.

Stream.seekCur( position )
position

Position in the stream to seek.

Returns:

Position in the stream after seek.

Raises:
IoError

on system errors.

Changes the position in the stream from which the next read/write operation will be performed. The position is relative from the current position in the stream, a negative number meaning “backward”, and a positive meaning “forward”. If the stream does not support seeking, an IoError is raised. If the operation would move the pointer past the end of the file size, the pointer is set to the end; if it would move the pointer before the beginning, it is moved to the beginning. On success, the function returns the position where the pointer has been moved.

seekEnd()

Moves the file pointer on seekable streams relative to end of file.

Stream.seekEnd( position )
position

Position in the stream to seek.

Returns:

Position in the stream after seek.

Raises:
IoError

on system errors.

Changes the position in the stream from which the next read/write operation will be performed. The position is relative from the end of the stream. If the stream does not support seeking, an error is raised. If the operation would move the pointer before the beginning, the pointer is set to the file begin. On success, the function returns the position where the pointer has been moved. Use seekEnd( 0 ) to move the pointer to the end of the stream.

On success, the function returns the position where the pointer has been moved.

setEncoding()

Set the text encoding and EOL mode for text-based operations.

Stream.setEncoding( encoding, [EOLMode] )
encoding

Name of the encoding that is used for the stream.

EOLMode

How to treat end of line indicators.

This method sets an encoding that will affect readText() and writeText() methods. Provided encodings are:

As EOL manipulation is also part of the text operations, this function allows to chose how to deal with EOL characters stored in Falcon strings when writing data and how to parse incoming EOL. Available values are:

If not provided, this parameter defaults to SYSTEM_DETECT.

If the given encoding is unknown, a ParamError is raised.

tell()

Return the current position in a stream.

Stream.tell( )
Returns:

Position in the stream.

Raises:
IoError

on system errors.

Returns the current read/write position in the stream. If the underlying stream does not support seeking, the operation raises an IoError.

truncate()

Resizes a file.

Stream.truncate( [position] )
position

If given, truncate at given position.

Returns:

Position in the stream.

Raises:
IoError

on system errors.

Truncate stream at current position, or if a position parameter is given, truncate the file at given position relative from file start. To empty a file, open it and then truncate it, or pass 0 as parameter.

If the underlying stream does not support seek operation, this function will raise an error.

write()

Write binary data to a stream.

Stream.write( buffer, [size], [start] )
buffer

A string or a MemBuf containing the data to be written.

size

Number of bytes to be written.

start

A position from where to start writing.

Returns:

Amout of data actually written.

Raises:
IoError

on system errors.

Writes bytes from a buffer on the stream. The write operation is synchronous, and will block the VM until the stream has completed the write; however, the stream may complete only partially the operation. The number of bytes actually written on the stream is returned.

If a size parameter is not given, it defaults to len( buffer ).

A start position may optionally be given too; this allows to iterate through writes and send part of the data that couldent be send previously without extracting substrings or copying the memory buffers.

writeAvailable()

Checks if data can be written, or wait until it's possible to write.

Stream.writeAvailable( [seconds] )
seconds

Maximum wait in seconds and fraction (defaults to infinite).

Returns:

True if data can be written, false otherwise.

Raises:
IoError

On stream error.

InterruptedError

if the Virtual Machine is asynchronously interrupted.

This function checks if the stream is available for immediate write, or if it becomes available during a determined time period. The seconds parameter may be set to zero to perform just a check, or to a positive value to wait for the line being cleared. If the seconds is not given, or if it's set to a negative value, the wait will be infinite.

A write operation after writeAvailable has returned succesfully is granted not to be blocking (unless another coroutine or thread writes data to the same stream in the meanwhile). Performing a read after that readAvailable has returned false will probably block for an undefined amount of time.

This method complies with the interrupt_protocol of the Virtual Machine.

writeItem()

Serializes an item to the stream.

Stream.writeItem( item )
item

The item to be serialized.

Raises:
IoError

On stream error.

Serializes an item to the given stream. This method works as serialize, but it works as a method of this stream instead of being considered a function.

writeText()

Write text data to a stream.

Stream.writeText( buffer, [start], [end] )
buffer

A string containing the text to be written.

start

The character count from which to start writing data.

end

The position of the last character to write.

Returns:

Amout of characters actually written.

Raises:
IoError

on system errors.

Writes a string to a stream using the character encoding set with Stream.setEncoding method. The begin and end optional parameters can be provided to write a part of a wide string without having to create a temporary substring.

In case of failure, an IoError is raised.


Index  |  Related pages  |  Classes  |  Functions  |  Entities  |  Function Sets  |  Groups
Made with Faldoc 1.0.0