<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Class Stream - Class Stream</title>
<link href="faldoc.css" rel="stylesheet" type="text/css"/>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
</head>
<body class="faldoc_body">
<div class="navitop">
<div class="tabs">
<ul>
<li><a href="./index.html"><span>Main</span></a></li>
<li><a href="./pages.html"><span>Related pages</span></a></li>
<li><a href="./groups.html"><span>Groups</span></a></li>
<li><a href="./funset.html"><span>Function sets</span></a></li>
<li><a href="./classes.html"><span>Classes</span></a></li>
<li><a href="./objects.html"><span>Objects</span></a></li>
<li><a href="./functions.html"><span>All functions</span></a></li>
<li><a href="./globals.html"><span>Globals</span></a></li>
</ul>
</div>
</div>
<hr/>
<h1 class="faldoc_title">Class Stream</h1>
<p class="faldoc_brief">Stream oriented I/O class. </p>
<p class="faldoc_funcdecl">
<b>class</b> Stream
</p>
<p class="faldoc_brief"><a href="#more">more...</a></p>
<h2 class="faldoc_title">Summary</h2>
<table class="faldoc_list">
<tr><td><a href="#encoding">encoding</a></td><td>Name of the set encoding, if given, for text operations</td></tr>
<tr><td><a href="#eolMode">eolMode</a></td><td>Mode of EOL conversion in text operations.</td></tr>
<tr><td><a href="#clone">clone()</a></td><td>Clone the stream handle. </td></tr>
<tr><td><a href="#close">close()</a></td><td>Closes the stream. </td></tr>
<tr><td><a href="#eof">eof()</a></td><td>Checks if the last read operation hit the end of the file. </td></tr>
<tr><td><a href="#errorDescription">errorDescription()</a></td><td>Returns a system specific textual description of the last error. </td></tr>
<tr><td><a href="#flush">flush()</a></td><td>Flushes a stream. </td></tr>
<tr><td><a href="#getBuffering">getBuffering()</a></td><td>Returns the size of I/O buffering active on this stream. </td></tr>
<tr><td><a href="#grab">grab()</a></td><td>Grabs binary data from the stream. </td></tr>
<tr><td><a href="#grabLine">grabLine()</a></td><td>Grabs a line of text encoded data. </td></tr>
<tr><td><a href="#grabText">grabText()</a></td><td>Grabs text encoded data from the stream. </td></tr>
<tr><td><a href="#isOpen">isOpen()</a></td><td>Checks if the stream is currently open. </td></tr>
<tr><td><a href="#lastError">lastError()</a></td><td>Return the last system error. </td></tr>
<tr><td><a href="#lastMoved">lastMoved()</a></td><td>Return the amount of data moved by the last operation. </td></tr>
<tr><td><a href="#read">read()</a></td><td>Reads binary data from the stream. </td></tr>
<tr><td><a href="#readAvailable">readAvailable()</a></td><td>Checks if data can be read, or wait for available data. </td></tr>
<tr><td><a href="#readLine">readLine()</a></td><td>Reads a line of text encoded data. </td></tr>
<tr><td><a href="#readText">readText()</a></td><td>Reads text encoded data from the stream. </td></tr>
<tr><td><a href="#seek">seek()</a></td><td>Moves the file pointer on seekable streams. </td></tr>
<tr><td><a href="#seekCur">seekCur()</a></td><td>Moves the file pointer on seekable streams relative to current position. </td></tr>
<tr><td><a href="#seekEnd">seekEnd()</a></td><td>Moves the file pointer on seekable streams relative to end of file. </td></tr>
<tr><td><a href="#setBuffering">setBuffering()</a></td><td>Set the buffering state of this stream. </td></tr>
<tr><td><a href="#setEncoding">setEncoding()</a></td><td>Set the text encoding and EOL mode for text-based operations. </td></tr>
<tr><td><a href="#tell">tell()</a></td><td>Return the current position in a stream. </td></tr>
<tr><td><a href="#truncate">truncate()</a></td><td>Resizes a file. </td></tr>
<tr><td><a href="#write">write()</a></td><td>Write binary data to a stream. </td></tr>
<tr><td><a href="#writeAvailable">writeAvailable()</a></td><td>Checks if data can be written, or wait until it's possible to write. </td></tr>
<tr><td><a href="#writeText">writeText()</a></td><td>Write text data to a stream. </td></tr>
</table>
<a name="more"><h2 class="faldoc_title">Detailed description</h2></a>
<p class="faldoc_funcdecl">
<b>class</b> Stream
</p>
<table class="faldoc_function">
</table>
<br/>
<p class="item_brief">Stream oriented I/O class. </p>
<p class="faldoc_text">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. </p>
<p class="faldoc_text">Stream I/O is synchronous, but it's possible to wait for the operation to be nonblocking with the readAvailable() and writeAvailable() methods. </p>
<p class="faldoc_text">Generally, all the methods in the stream class raise an error in case of I/O failure. </p>
<p class="faldoc_text">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. </p>
<h2 class="faldoc_title">Properties</h2>
<h3 class="faldoc_funcname"><a name="encoding">encoding</a></h3>
<p class="item_brief">Name of the set encoding, if given, for text operations</p>
<h3 class="faldoc_funcname"><a name="eolMode">eolMode</a></h3>
<p class="item_brief">Mode of EOL conversion in text operations.</p>
<h2 class="faldoc_title">Methods</h2>
<h3 class="faldoc_funcname"><a name="clone">clone()</a></h3>
<p class="item_brief">Clone the stream handle. </p>
<p class="faldoc_funcdecl">Stream.clone( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A new copy of the stream handle. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_IoError.html">IoError</a></td><td class="faldoc_raisedesc">On stream error. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">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). </p>
<p class="faldoc_text">The underlying resource remains open until all the instances of the streams are closed. </p>
</p>
<h3 class="faldoc_funcname"><a name="close">close()</a></h3>
<p class="item_brief">Closes the stream. </p>
<p class="faldoc_funcdecl">Stream.close( )</p>
<p class="faldoc_text"><p class="faldoc_text">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. </p>
</p>
<h3 class="faldoc_funcname"><a name="eof">eof()</a></h3>
<p class="item_brief">Checks if the last read operation hit the end of the file. </p>
<p class="faldoc_funcdecl">Stream.eof( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">True if file pointer is at EOF. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Returns true if the last read operation hit the end of file. </p>
</p>
<h3 class="faldoc_funcname"><a name="errorDescription">errorDescription()</a></h3>
<p class="item_brief">Returns a system specific textual description of the last error. </p>
<p class="faldoc_funcdecl">Stream.errorDescription( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A string describing the system error. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Returns a system specific textual description of the last error occurred on the stream. </p>
</p>
<h3 class="faldoc_funcname"><a name="flush">flush()</a></h3>
<p class="item_brief">Flushes a stream. </p>
<p class="faldoc_funcdecl">Stream.flush( )</p>
<p class="faldoc_text"><p class="faldoc_text">Ensures that the operations on the stream are correctly flushed. </p>
</p>
<h3 class="faldoc_funcname"><a name="getBuffering">getBuffering()</a></h3>
<p class="item_brief">Returns the size of I/O buffering active on this stream. </p>
<p class="faldoc_funcdecl">Stream.getBuffering( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">0 if the stream is unbuffered or a positive number if it is buffered. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="grab">grab()</a></h3>
<p class="item_brief">Grabs binary data from the stream. </p>
<p class="faldoc_funcdecl">Stream.grab( size )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">size</td><td class="faldoc_paramdesc">Maximum size to be read. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A string containing binary data from the stream. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_IoError.html">IoError</a></td><td class="faldoc_raisedesc">on system errors. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This metod creates a string wide enough to read size bytes, and then tries to fill it with binary data coming from the stream. </p>
</p>
<h3 class="faldoc_funcname"><a name="grabLine">grabLine()</a></h3>
<p class="item_brief">Grabs a line of text encoded data. </p>
<p class="faldoc_funcdecl">Stream.grabLine( [size] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_optparam">size</td><td class="faldoc_optparamdesc">Maximum count of characters to be read before to return anyway. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A string containing the read line, or oob(0) when the file is over. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_IoError.html">IoError</a></td><td class="faldoc_raisedesc">on system errors. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This function works as <a href="./class_Stream.html#grabText">Stream.grabText</a>, but if a new line is encountered, the read terminates. Returned string does not contain the EOL sequence. </p>
<p class="faldoc_text">At EOF, the function returns an oob(0), which in normal tests is translated as "false", and that can be used to build sequences. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> 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. </p>
<p class="faldoc_text">For example, a normal loop may look like: </p>
<pre class="faldoc_code">
s = InputStream( "file.txt" )
while (l = s.grabLine()) != 0
> "LINE: ", l
end
s.close()
</pre>
<p class="faldoc_text">But it is possible to use the fuinction also in for/in loops: </p>
<pre class="faldoc_code">
s = InputStream( "file.txt" )
for line in s.grabLine: > "LINE: ", line
s.close()
</pre>
<p class="faldoc_text">Or even comprehensions: </p>
<pre class="faldoc_code">
s = InputStream( "file.txt" )
lines_in_file = List().comp( s.grabLine )
s.close()
</pre>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> As <a href="./class_Stream.html#readLine">Stream.readLine</a> 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. </p>
</p>
<h3 class="faldoc_funcname"><a name="grabText">grabText()</a></h3>
<p class="item_brief">Grabs text encoded data from the stream. </p>
<p class="faldoc_funcdecl">Stream.grabText( size )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">size</td><td class="faldoc_paramdesc">Optionally, a maximum size to be read. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A string containing the read text. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_IoError.html">IoError</a></td><td class="faldoc_raisedesc">on system errors. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This method reads a string from a stream, eventually parsing the input data through the given character encoding set by the <a href="./class_Stream.html#setEncoding">Stream.setEncoding</a> method, and returns it in a newly allocated string. </p>
<p class="faldoc_text"> If the function is successful, the buffer may contain <b>size</b> characters or less if the stream hadn't enough characters to read. </p>
<p class="faldoc_text">In case of failure, an IoError is raised. </p>
<p class="faldoc_text"> 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 <a href="./functions.html#transcodeFrom">transcodeFrom</a> calls should be used instead. </p>
</p>
<h3 class="faldoc_funcname"><a name="isOpen">isOpen()</a></h3>
<p class="item_brief">Checks if the stream is currently open. </p>
<p class="faldoc_funcdecl">Stream.isOpen( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">True if the file is open. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Return true if the stream is currently open. </p>
</p>
<h3 class="faldoc_funcname"><a name="lastError">lastError()</a></h3>
<p class="item_brief">Return the last system error. </p>
<p class="faldoc_funcdecl">Stream.lastError( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">An error code. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">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. </p>
</p>
<h3 class="faldoc_funcname"><a name="lastMoved">lastMoved()</a></h3>
<p class="item_brief">Return the amount of data moved by the last operation. </p>
<p class="faldoc_funcdecl">Stream.lastMoved( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">An amount of bytes. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">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. </p>
</p>
<h3 class="faldoc_funcname"><a name="read">read()</a></h3>
<p class="item_brief">Reads binary data from the stream. </p>
<p class="faldoc_funcdecl">Stream.read( buffer, [size] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">buffer</td><td class="faldoc_paramdesc">A string or MemBuf that will be filled with read data. </td></tr>
<tr><td class="faldoc_optparam">size</td><td class="faldoc_optparamdesc">Optionally, a maximum size to be read. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">Amount of data actually read. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_IoError.html">IoError</a></td><td class="faldoc_raisedesc">on system errors. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This method uses an already existing and pre-allocated string or Memory Buffer, filling it with at maximum <b>size</b> bytes. If <b>size</b> is not provided, the method tries to read enough data to fill the given buffer. A string may be pre-allocated with the <a href="./functions.html#strBuffer">strBuffer</a> function. </p>
<p class="faldoc_text"> If <b>size</b> 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. </p>
<p class="faldoc_text"> If the buffer is a string, each read fills the string from the beginning. If it is a MemBuffer, the space between <a href="./class_MemoryBuffer.html#limit">MemoryBuffer.limit</a> and <a href="./functions.html#len">len</a> is filled. This allow for partial reads in slow (i.e. network) streams. </p>
</p>
<h3 class="faldoc_funcname"><a name="readAvailable">readAvailable()</a></h3>
<p class="item_brief">Checks if data can be read, or wait for available data. </p>
<p class="faldoc_funcdecl">Stream.readAvailable( [seconds] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_optparam">seconds</td><td class="faldoc_optparamdesc">Maximum wait in seconds and fraction (defaults to infinite). </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">True if data is available, false otherwise. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_IoError.html">IoError</a></td><td class="faldoc_raisedesc">On stream error. </td></tr><tr><td class="faldoc_raiseitem"><a href="./class_InterruptedError.html">InterruptedError</a></td><td class="faldoc_raisedesc">if the Virtual Machine is asynchronously interrupted. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> 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 <b>seconds</b> 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. </p>
<p class="faldoc_text">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. </p>
<p class="faldoc_text"> This method complies with the <a href="./page_interrupt_protocol.html">Falcon Virtual Machine Preemptibility</a> of the Virtual Machine. </p>
</p>
<h3 class="faldoc_funcname"><a name="readLine">readLine()</a></h3>
<p class="item_brief">Reads a line of text encoded data. </p>
<p class="faldoc_funcdecl">Stream.readLine( buffer, [size] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">buffer</td><td class="faldoc_paramdesc">A string that will be filled with read data. </td></tr>
<tr><td class="faldoc_optparam">size</td><td class="faldoc_optparamdesc">Maximum count of characters to be read before to return anyway. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">True if a line was read, false otherwise. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_IoError.html">IoError</a></td><td class="faldoc_raisedesc">on system errors. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This function works as <a href="./class_Stream.html#readText">Stream.readText</a>, 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. </p>
<p class="faldoc_text">At EOF, the function returns false. Example: </p>
<pre class="faldoc_code">
s = InputStream( "file.txt" )
line = strBuffer(4096)
while s.readLine( line ): > "LINE: ", line
s.close()
</pre>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> It is possible to obtain a newly allocated line instead of having to provide a target buffer through the <a href="./class_Stream.html#grabLine">Stream.grabLine</a> method. </p>
</p>
<h3 class="faldoc_funcname"><a name="readText">readText()</a></h3>
<p class="item_brief">Reads text encoded data from the stream. </p>
<p class="faldoc_funcdecl">Stream.readText( buffer, [size] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">buffer</td><td class="faldoc_paramdesc">A string that will be filled with read data. </td></tr>
<tr><td class="faldoc_optparam">size</td><td class="faldoc_optparamdesc">Optionally, a maximum size to be read. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">Amount of data actually read. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_IoError.html">IoError</a></td><td class="faldoc_raisedesc">on system errors. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This method reads a string from a stream, eventually parsing the input data through the given character encoding set by the <a href="./class_Stream.html#setEncoding">Stream.setEncoding</a> method. The number of bytes actually read may vary depending on the decoding rules. </p>
<p class="faldoc_text"> If the size parameter is given, the function will try to read at maximum <b>size</b> 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. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> This differ from Stream.read, where the buffer is never grown, even when it is a string. </p>
<p class="faldoc_text"> If the function is successful, the buffer may contain <b>size</b> characters or less if the stream hadn't enough characters to read. </p>
<p class="faldoc_text">In case of failure, an IoError is raised. </p>
<p class="faldoc_text"> 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 <a href="./functions.html#transcodeFrom">transcodeFrom</a> calls should be used instead. </p>
</p>
<h3 class="faldoc_funcname"><a name="seek">seek()</a></h3>
<p class="item_brief">Moves the file pointer on seekable streams. </p>
<p class="faldoc_funcdecl">Stream.seek( position )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">position</td><td class="faldoc_paramdesc">Position in the stream to seek. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">Position in the stream after seek. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_IoError.html">IoError</a></td><td class="faldoc_raisedesc">on system errors. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">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. </p>
</p>
<h3 class="faldoc_funcname"><a name="seekCur">seekCur()</a></h3>
<p class="item_brief">Moves the file pointer on seekable streams relative to current position. </p>
<p class="faldoc_funcdecl">Stream.seekCur( position )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">position</td><td class="faldoc_paramdesc">Position in the stream to seek. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">Position in the stream after seek. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_IoError.html">IoError</a></td><td class="faldoc_raisedesc">on system errors. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">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. </p>
</p>
<h3 class="faldoc_funcname"><a name="seekEnd">seekEnd()</a></h3>
<p class="item_brief">Moves the file pointer on seekable streams relative to end of file. </p>
<p class="faldoc_funcdecl">Stream.seekEnd( position )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">position</td><td class="faldoc_paramdesc">Position in the stream to seek. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">Position in the stream after seek. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_IoError.html">IoError</a></td><td class="faldoc_raisedesc">on system errors. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">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. </p>
<p class="faldoc_text">On success, the function returns the position where the pointer has been moved. </p>
</p>
<h3 class="faldoc_funcname"><a name="setBuffering">setBuffering()</a></h3>
<p class="item_brief">Set the buffering state of this stream. </p>
<p class="faldoc_funcdecl">Stream.setBuffering( size )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">size</td><td class="faldoc_paramdesc">Buffering size; pass 0 to disable. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This method activates or disactivates I/O buffering on this stream. </p>
<p class="faldoc_text">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. </p>
<p class="faldoc_text">Seek operations invalidate the buffer, that is automatically flushed when necessary. </p>
<p class="faldoc_text">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). </p>
<p class="faldoc_text">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. </p>
</p>
<h3 class="faldoc_funcname"><a name="setEncoding">setEncoding()</a></h3>
<p class="item_brief">Set the text encoding and EOL mode for text-based operations. </p>
<p class="faldoc_funcdecl">Stream.setEncoding( encoding, [EOLMode] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">encoding</td><td class="faldoc_paramdesc">Name of the encoding that is used for the stream. </td></tr>
<tr><td class="faldoc_optparam">EOLMode</td><td class="faldoc_optparamdesc">How to treat end of line indicators. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This method sets an encoding that will affect readText() and writeText() methods. Provided encodings are: </p>
<ul>
<li>"utf-8" </li><li>"utf-16" </li><li>"utf-16BE" </li><li>"utf-16LE" </li><li>"iso8859-1" to "iso8859-15" </li><li>"gbk" (Chinese simplified) </li><li>"cp1252" </li><li>"C" (byte oriented – writes byte per byte) </li>
</ul>
<p class="faldoc_text">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: </p>
<ul>
<li>CR_TO_CR: CR and LF characters are untranslated </li><li>CR_TO_CRLF: When writing, CR ("\n") is translated into CRLF, when reading CRLF is translated into a single "\n" </li><li>SYSTEM_DETECT: use host system policy. </li>
</ul>
<p class="faldoc_text">If not provided, this parameter defaults to SYSTEM_DETECT. </p>
<p class="faldoc_text">If the given encoding is unknown, a ParamError is raised. </p>
</p>
<h3 class="faldoc_funcname"><a name="tell">tell()</a></h3>
<p class="item_brief">Return the current position in a stream. </p>
<p class="faldoc_funcdecl">Stream.tell( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">Position in the stream. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_IoError.html">IoError</a></td><td class="faldoc_raisedesc">on system errors. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Returns the current read/write position in the stream. If the underlying stream does not support seeking, the operation raises an IoError. </p>
</p>
<h3 class="faldoc_funcname"><a name="truncate">truncate()</a></h3>
<p class="item_brief">Resizes a file. </p>
<p class="faldoc_funcdecl">Stream.truncate( [position] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_optparam">position</td><td class="faldoc_optparamdesc">If given, truncate at given position. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">Position in the stream. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_IoError.html">IoError</a></td><td class="faldoc_raisedesc">on system errors. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">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. </p>
<p class="faldoc_text">If the underlying stream does not support seek operation, this function will raise an error. </p>
</p>
<h3 class="faldoc_funcname"><a name="write">write()</a></h3>
<p class="item_brief">Write binary data to a stream. </p>
<p class="faldoc_funcdecl">Stream.write( buffer, [size], [start] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">buffer</td><td class="faldoc_paramdesc">A string or a MemBuf containing the data to be written. </td></tr>
<tr><td class="faldoc_optparam">size</td><td class="faldoc_optparamdesc">Number of bytes to be written. </td></tr><tr><td class="faldoc_optparam">start</td><td class="faldoc_optparamdesc">A position from where to start writing. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">Amount of data actually written. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_IoError.html">IoError</a></td><td class="faldoc_raisedesc">on system errors. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">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. </p>
<p class="faldoc_text">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. </p>
<p class="faldoc_text"> MemBuf items can participate to stream binary writes through their internal position pointers. The buffer is written from <a href="./class_MemoryBuffer.html#position">MemoryBuffer.position</a> up to <a href="./class_MemoryBuffer.html#limit">MemoryBuffer.limit</a>, and upon completion <a href="./class_MemoryBuffer.html#position">MemoryBuffer.position</a> is advanced accordingly to the number of bytes effectively stored on the stream. When a MemBuf is used, <b>size</b> and <b>start</b> parameters are ignored. </p>
</p>
<h3 class="faldoc_funcname"><a name="writeAvailable">writeAvailable()</a></h3>
<p class="item_brief">Checks if data can be written, or wait until it's possible to write. </p>
<p class="faldoc_funcdecl">Stream.writeAvailable( [seconds] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_optparam">seconds</td><td class="faldoc_optparamdesc">Maximum wait in seconds and fraction (defaults to infinite). </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">True if data can be written, false otherwise. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_IoError.html">IoError</a></td><td class="faldoc_raisedesc">On stream error. </td></tr><tr><td class="faldoc_raiseitem"><a href="./class_InterruptedError.html">InterruptedError</a></td><td class="faldoc_raisedesc">if the Virtual Machine is asynchronously interrupted. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This function checks if the stream is available for immediate write, or if it becomes available during a determined time period. The <b>seconds</b> 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 <b>seconds</b> is not given, or if it's set to a negative value, the wait will be infinite. </p>
<p class="faldoc_text">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. </p>
<p class="faldoc_text"> This method complies with the <a href="./page_interrupt_protocol.html">Falcon Virtual Machine Preemptibility</a> of the Virtual Machine. </p>
</p>
<h3 class="faldoc_funcname"><a name="writeText">writeText()</a></h3>
<p class="item_brief">Write text data to a stream. </p>
<p class="faldoc_funcdecl">Stream.writeText( buffer, [start], [end] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">buffer</td><td class="faldoc_paramdesc">A string containing the text to be written. </td></tr>
<tr><td class="faldoc_optparam">start</td><td class="faldoc_optparamdesc">The character count from which to start writing data. </td></tr><tr><td class="faldoc_optparam">end</td><td class="faldoc_optparamdesc">The position of the last character to write. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_IoError.html">IoError</a></td><td class="faldoc_raisedesc">on system errors. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> Writes a string to a stream using the character encoding set with <a href="./class_Stream.html#setEncoding">Stream.setEncoding</a> 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. </p>
<p class="faldoc_text">In case of failure, an IoError is raised. </p>
</p>
<hr/>
<div class="navibottom">
<center>
<a href="./index.html">Main</a> - <a href="./pages.html">Related pages</a> - <a href="./groups.html">Groups</a> - <a href="./funset.html">Function sets</a> - <a href="./classes.html">Classes</a> - <a href="./objects.html">Objects</a> - <a href="./functions.html">All functions</a> - <a href="./globals.html">Globals</a>
</center>
</div>
</div>
<div class="faldoc_signature">Made with <a href="http://www.falconpl.org">faldoc 2.2.0</div>
</body>
</html>
