1.4.1Class Stream

Stream oriented I/O class.

Class Stream

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.

Properties
encoding Name of the set encoding, if given, for text operations
eolMode Mode of EOL conversion in text operations.
Methods
cloneClone the stream handle.
closeCloses the stream.
eofChecks if the last read operation hit the end of the file.
errorDescriptionReturns a system specific textual description of the last error.
flushFlushes a stream.
getBufferingReturns the size of I/O buffering active on this stream.
grabGrabs binary data from the stream.
grabLineGrabs a line of text encoded data.
grabTextGrabs text encoded data from the stream.
isOpenChecks if the stream is currently open.
lastErrorReturn the last system error.
lastMovedReturn the amount of data moved by the last operation.
readReads binary data from the stream.
readAvailableChecks if data can be read, or wait for available data.
readLineReads a line of text encoded data.
readTextReads text encoded data from the stream.
seekMoves the file pointer on seekable streams.
seekCurMoves the file pointer on seekable streams relative to current position.
seekEndMoves the file pointer on seekable streams relative to end of file.
setBufferingSet the buffering state of this stream.
setEncodingSet the text encoding and EOL mode for text-based operations.
tellReturn the current position in a stream.
truncateResizes a file.
writeWrite binary data to a stream.
writeAvailableChecks if data can be written, or wait until it's possible to write.
writeTextWrite text data to a stream.

Properties

encoding

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

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

eolMode

Mode of EOL conversion in text operations.

Mode of EOL conversion in text operations.

Methods

clone

Clone the stream handle.

Stream.clone()
ReturnA new copy of the stream handle.
Raise
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()
ReturnTrue 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()
ReturnA 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.

getBuffering

Returns the size of I/O buffering active on this stream.

Stream.getBuffering()
Return0 if the stream is unbuffered or a positive number if it is buffered.

See also: Stream.

grab

Grabs binary data from the stream.

Stream.grab( size )
size Maximum size to be read.
ReturnA string containing binary data from the stream.
Raise
IoError on system errors.

This metod creates a string wide enough to read size bytes, and then tries to fill it with binary data coming from the stream.

grabLine

Grabs a line of text encoded data.

Stream.grabLine( [size] )
size Maximum count of characters to be read before to return anyway.
ReturnA string containing the read line, or oob(0) when the file is over.
Raise
IoError on system errors.

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

At EOF, the function returns an oob(0), which in normal tests is translated as "false", and that can be used to build sequences.

Note: An empty line is returned as an empty string. Please, notice that empty lines are returned as empty strings, and that empty strings, in Falcon, assume "false" value when logically evaluated. On loops where not checking for an explicit EOF to be hit in the stream, you will need to check for the returned value to be != 0, or not out of band.

For example, a normal loop may look like:


   s = InputStream( "file.txt" )
   while (l = s.grabLine()) != 0
      > "LINE: ", l
   end	
   s.close()

But it is possible to use the fuinction also in for/in loops:


   s = InputStream( "file.txt" )
   for line in s.grabLine: > "LINE: ", line
   s.close()

Or even comprehensions:


   s = InputStream( "file.txt" )
   lines_in_file = List().comp( s.grabLine )
   s.close()

Note: As Stream.readLine recycles a pre-allocated buffer provided as parameter it is more efficient than grabLine, unless you need to store each line for further processing later on.

grabText

Grabs text encoded data from the stream.

Stream.grabText( size )
size Optionally, a maximum size to be read.
ReturnA string containing the read text.
Raise
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, and returns it in a newly allocated string.

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.

isOpen

Checks if the stream is currently open.

Stream.isOpen()
ReturnTrue if the file is open.

Return true if the stream is currently open.

lastError

Return the last system error.

Stream.lastError()
ReturnAn 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()
ReturnAn 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.
ReturnAmount of data actually read.
Raise
IoError on system errors.

This method uses an already existing and pre-allocated string or Memory Buffer, filling it with at maximum size bytes. If size is not provided, the method tries to read enough data to fill the given buffer. A string may be pre-allocated with the strBuffer function.

If size is provided but it's larger than the available space in the given buffer, it is ignored. If there isn't any available space in the target buffer, a ParamError is raised.

If the buffer is a string, each read fills the string from the beginning. If it is a MemBuffer, the space between MemoryBuffer.limit and len is filled. This allow for partial reads in slow (i.e. network) streams.

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).
ReturnTrue if data is available, false otherwise.
Raise
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 Falcon Virtual Machine Preemptibility of the Virtual Machine.

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.
ReturnTrue if a line was read, false otherwise.
Raise
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. Also, the returned string may be empty if the line was empty.

At EOF, the function returns false. Example:


   s = InputStream( "file.txt" )
   line = strBuffer(4096)
   while s.readLine( line ): > "LINE: ", line
   s.close()

Note: It is possible to obtain a newly allocated line instead of having to provide a target buffer through the Stream.grabLine method.

See also: Stream.

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.
ReturnAmount of data actually read.
Raise
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 string if there isn't enough room for the operation. If it is not given, the current allocated memory of buffer will be used instead.

Note: This differ from Stream.read, where the buffer is never grown, even when it is a string.

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.
ReturnPosition in the stream after seek.
Raise
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.
ReturnPosition in the stream after seek.
Raise
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.
ReturnPosition in the stream after seek.
Raise
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.

setBuffering

Set the buffering state of this stream.

Stream.setBuffering( size )
size Buffering size; pass 0 to disable.

This method activates or disactivates I/O buffering on this stream.

When buffering is active, every read/write operation is first cached in memory, provided the size of the memory buffer is wide enough to store the data being written or to provide the data being read.

Seek operations invalidate the buffer, that is automatically flushed when necessary.

Local filesystem providers and standard I/O streams are buffered by default; other streams may be created with buffering enabled or not, buffered or not depending on their and common usage patterns (network streams are usually unbuffered).

You may want to disable buffering when preparing binary data in memory, or parsing big chunks of binary data at once via block (MemBuf) read/write operations. However, notice that buffering is always optimizing when chunk width is 1/4 of the buffer size or less, and causes only minor overhead in the other cases.

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()
ReturnPosition in the stream.
Raise
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.
ReturnPosition in the stream.
Raise
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.
ReturnAmount of data actually written.
Raise
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.

When the output buffer is a string, a size parameter can be given; otherwise the whole binary contents of the stream are written. A start position may optionally be given too; this allows to iterate through writes and send part of the data that coulden't be send previously without extracting substrings or copying the memory buffers.

MemBuf items can participate to stream binary writes through their internal position pointers. The buffer is written from MemoryBuffer.position up to MemoryBuffer.limit, and upon completion MemoryBuffer.position is advanced accordingly to the number of bytes effectively stored on the stream. When a MemBuf is used, size and start parameters are ignored.

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).
ReturnTrue if data can be written, false otherwise.
Raise
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 Falcon Virtual Machine Preemptibility of the Virtual Machine.

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.
Raise
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.

Made with http://www.falconpl.org