<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Falcon Core Module - All functions</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">All functions</h1>
<h3 class="faldoc_funcname"><a name="CurrentTime">CurrentTime()</a></h3>
<p class="item_brief">Returns the current system local time as a TimeStamp instance. </p>
<p class="faldoc_funcdecl">CurrentTime</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A new TimeStamp instance. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Returns the current system local time as a TimeStamp instance. The function can never fail. </p>
</p>
<h3 class="faldoc_funcname"><a name="IOStream">IOStream()</a></h3>
<p class="item_brief">Creates a stream for input and output. </p>
<p class="faldoc_funcdecl">IOStream( fileName, [createMode], [shareMode] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">fileName</td><td class="faldoc_paramdesc">A relative or absolute path to a file to be opened for input </td></tr>
<tr><td class="faldoc_optparam">createMode</td><td class="faldoc_optparamdesc">If given, the ownership of the created file. </td></tr><tr><td class="faldoc_optparam">shareMode</td><td class="faldoc_optparamdesc">If given, the share mode. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> A new valid <a href="./class_Stream.html">Stream</a> instance on success. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">If the function is successful, it creates the given fileName and returns a valid stream object by which the underlying file may be read. If an already existing file name is given, then the file is truncated and its access right are updated. Calling read methods on the returned object will fail, raising an error. </p>
<p class="faldoc_text">If the file can be created, its sharing mode can be controlled by providing a shareMode parameter. In case the shareMode is not given, then the maximum publicity is used. </p>
<p class="faldoc_text">If the file cannot be created, an error containing a valid fsError code is raised. </p>
<p class="faldoc_text"> See <a href="./funset_core_stream_factory.html">Stream factory functions</a> for a description of the shared modes. </p>
</p>
<h3 class="faldoc_funcname"><a name="InputStream">InputStream()</a></h3>
<p class="item_brief">Open a system file for reading. </p>
<p class="faldoc_funcdecl">InputStream( fileName, [shareMode] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">fileName</td><td class="faldoc_paramdesc">A relative or absolute path to a file to be opened for input </td></tr>
<tr><td class="faldoc_optparam">shareMode</td><td class="faldoc_optparamdesc">If given, the share mode. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> A new valid <a href="./class_Stream.html">Stream</a> instance on success. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">If the function is successful, it opens the given fileName and returns a valid stream object by which the underlying file may be read. Calling write methods on the returned object will fail, raising an error. </p>
<p class="faldoc_text">If the optional share parameter is not given, the maximum share publicity available on the system will be used. </p>
<p class="faldoc_text">If the file cannot be open, an error containing a valid fsError code is raised. </p>
<p class="faldoc_text"> See <a href="./funset_core_stream_factory.html">Stream factory functions</a> for a description of the shared modes. </p>
</p>
<h3 class="faldoc_funcname"><a name="MemBufFromPtr">MemBufFromPtr()</a></h3>
<p class="item_brief">Creates a memory buffer to store raw memory coming from external providers. </p>
<p class="faldoc_funcdecl">MemBufFromPtr( data, size, [wordSize] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">data</td><td class="faldoc_paramdesc">A pointer to the raw memory (as an integer value). </td></tr><tr><td class="faldoc_param">size</td><td class="faldoc_paramdesc">The maximum size of the memory. </td></tr>
<tr><td class="faldoc_optparam">wordSize</td><td class="faldoc_optparamdesc">Size of each word in bytes (1, 2, 3 or 4). </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Intentionally left undocumented. Don't use if you don't know what you're doing. </p>
</p>
<h3 class="faldoc_funcname"><a name="OutputStream">OutputStream()</a></h3>
<p class="item_brief">Creates a stream for output only. </p>
<p class="faldoc_funcdecl">OutputStream( fileName, [createMode], [shareMode] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">fileName</td><td class="faldoc_paramdesc">A relative or absolute path to a file to be opened for input </td></tr>
<tr><td class="faldoc_optparam">createMode</td><td class="faldoc_optparamdesc">If given, the ownership of the created file. </td></tr><tr><td class="faldoc_optparam">shareMode</td><td class="faldoc_optparamdesc">If given, the share mode. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> A new valid <a href="./class_Stream.html">Stream</a> instance on success. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">If the function is successful, it creates the given fileName and returns a valid stream object by which the underlying file may be read. If an already existing file name is given, then the file is truncated and its access right are updated. Calling read methods on the returned object will fail, raising an error. </p>
<p class="faldoc_text">If the file can be created, its sharing mode can be controlled by providing a shareMode parameter. In case the shareMode is not given, then the maximum publicity is used. </p>
<p class="faldoc_text">If the file cannot be created, an error containing a valid fsError code is raised. </p>
<p class="faldoc_text"> See <a href="./funset_core_stream_factory.html">Stream factory functions</a> for a description of the shared modes. </p>
</p>
<h3 class="faldoc_funcname"><a name="PageDict">PageDict()</a></h3>
<p class="item_brief">Creates a paged dictionary (which is internally represented as a B-Tree). </p>
<p class="faldoc_funcdecl">PageDict( pageSize )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">pageSize</td><td class="faldoc_paramdesc">size of pages expressed in maximum items. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A new dictionary. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The function returns a Falcon dictionary that can be handled exactly as a normal dictionary. The difference is only in the internal management of memory allocation and tree balance. Default Falcon dictionaries (the ones created with the "[=>]" operator) are internally represented as paired linear vectors of ordered entries. They are extremely efficient to store a relatively small set of data, whose size, and possibly key order, is known in advance. As this is exactly the condition under which source level dictionary are created, this way to store dictionary is the default in Falcon. The drawback is that if the data grows beyond a critical mass linear dictionary may become sluggishly slow and hang down the whole VM processing. </p>
<p class="faldoc_text">This function, which is actually a class factory function (this is the reason why its name begins in uppercase), returns an empty Falcon dictionary that is internally organized as a B-Tree structure. At a marginal cost in term of memory with respect to the mere storage of falcon items, which is used as spare and growth area, this structure offer high performances on medium to large amount of data to be ordered and searched. Empirical tests in Falcon language showed that this structure can scale up easily to several millions items. </p>
<p class="faldoc_text">In general, if a Falcon dictionary is meant to store large data, above five to ten thousands elements, or if the size of stored data is not known in advance, using this structure instead of the default Falcon dictionaries is highly advisable. </p>
</p>
<h3 class="faldoc_funcname"><a name="ParseRFC2822">ParseRFC2822()</a></h3>
<p class="item_brief">Parses a RFC2822 formatted date and returns a timestamp instance. </p>
<p class="faldoc_funcdecl">ParseRFC2822</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> A valid <a href="./class_TimeStamp.html">TimeStamp</a> instance or nil if the format is invalid. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="abs">abs()</a></h3>
<p class="item_brief">Returns the absolute value of a number. </p>
<p class="faldoc_funcdecl">abs( x )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">x</td><td class="faldoc_paramdesc">A number. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The absolute value of the parameter. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">If the argument is an integer, then an integer is returned, otherwise the return value will be a floating point number. </p>
</p>
<h3 class="faldoc_funcname"><a name="acos">acos()</a></h3>
<p class="item_brief">Returns the arc cosine of the argument. </p>
<p class="faldoc_funcdecl">acos( x )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">x</td><td class="faldoc_paramdesc">Argument. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The arc cosine of the argument. </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_MathError.html">MathError</a></td><td class="faldoc_raisedesc">If the argument is out of domain. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function computes the principal value of the arc cosine of its argument x. The value of x should be in the range [-1,1]. </p>
<p class="faldoc_text">The return value is expressed in radians. </p>
<p class="faldoc_text">The function may raise a Math error if the value cannot be computed because of domain or overflow errors. </p>
</p>
<h3 class="faldoc_funcname"><a name="all">all()</a></h3>
<p class="item_brief">Returns true if all the items in a given collection evaluate to true. </p>
<p class="faldoc_funcdecl">all( sequence )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">sequence</td><td class="faldoc_paramdesc">A sequence of arbitrary items. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">true if all the items are true, false otherwise </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> Items in <b>sequence</b> are evaluated in functional context for truth value. This means that, if they are sigmas, they get sigma-reduced and their return value is evaluated, otheriwise they are evaluated directly. </p>
<p class="faldoc_text">Truth value is determined using the standard Falcon truth check (nil is false, numerics are true if not zero, strings and collections are true if not empty, object and classes are always true). </p>
<p class="faldoc_text">The check is short circuited. This means that the processing of parameters is interrupted as an element is evaluated into false. </p>
<p class="faldoc_text">If the collection is empty, this function returns false. </p>
</p>
<h3 class="faldoc_funcname"><a name="allp">allp()</a></h3>
<p class="item_brief">Returns true if all the parameters evaluate to true. </p>
<p class="faldoc_funcdecl">allp( ... )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">...</td><td class="faldoc_paramdesc">An arbitrary list of items. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">true if all the items are true, false otherwise </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This function works like <a href="./functions.html#all">all</a>, but the collection may be specified directly in the parameters rather being given in a separate array. This make easier to write allp in callable arrays. For example, one may write </p>
<pre class="faldoc_code">
[allp, 1, k, n ...]
</pre>
<p class="faldoc_text">while using all one should write </p>
<pre class="faldoc_code">
[all, [1, k, n ...]]
</pre>
<p class="faldoc_text">Parameters are evaluated in functional context. This means that, if they are sigmas, they get sigma-reduced and their return value is evaluated, otheriwise they are evaluated directly. </p>
<p class="faldoc_text">Truth value is determined using the standard Falcon truth check (nil is false, numerics are true if not zero, strings and collections are true if not empty, object and classes are always true). </p>
<p class="faldoc_text">If called without parameters, this function returns false. </p>
</p>
<h3 class="faldoc_funcname"><a name="any">any()</a></h3>
<p class="item_brief">Returns true if any of the items in a given collection evaluate to true. </p>
<p class="faldoc_funcdecl">any( sequence )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">sequence</td><td class="faldoc_paramdesc">A sequence of arbitrary items. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">true at least one item in the collection is true, false otherwise. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> Items in <b>sequence</b> are evaluated in functional context for truth value. This means that, if they are sigmas, they get sigma-reduced and their return value is evaluated, otheriwise they are evaluated directly. </p>
<p class="faldoc_text">Truth value is determined using the standard Falcon truth check (nil is false, numerics are true if not zero, strings and collections are true if not empty, object and classes are always true). </p>
<p class="faldoc_text">The check is short circuited. This means that elements are evaluated until an element considered to be true (or sigma-reduced to a true value) is found. </p>
<p class="faldoc_text">If the collection is empty, this function returns false. </p>
</p>
<h3 class="faldoc_funcname"><a name="anyp">anyp()</a></h3>
<p class="item_brief">Returns true if any one of the parameters evaluate to true. </p>
<p class="faldoc_funcdecl">anyp( ... )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">...</td><td class="faldoc_paramdesc">A list of arbitrary items. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">true at least one parameter is true, false otherwise. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This function works like <a href="./functions.html#any">any</a>, but the sequence may be specified directly in the parameters rather being given in a separate array. This make easier to write anyp in callable arrays. For example, one may write </p>
<pre class="faldoc_code">
[anyp, 1, k, n ...]
</pre>
<p class="faldoc_text">while using any one should write </p>
<pre class="faldoc_code">
[any, [1, k, n ...]]
</pre>
<p class="faldoc_text">Parameters are evaluated in functional context. This means that, if they are sigmas, they get sigma-reduced and their return value is evaluated, otheriwise they are evaluated directly. </p>
<p class="faldoc_text">Truth value is determined using the standard Falcon truth check (nil is false, numerics are true if not zero, strings and collections are true if not empty, object and classes are always true). </p>
<p class="faldoc_text">If called without parameters, this function returns false. </p>
</p>
<h3 class="faldoc_funcname"><a name="argd">argd()</a></h3>
<p class="item_brief">Returns a dictionary containing all the parameters passed to the current function. </p>
<p class="faldoc_funcdecl">argd</p>
<p class="faldoc_text"><p class="faldoc_text">The dictionary contains the parameter names associated with the value passed by the caller. Parameters received beyond the officially declared ones aren't returned in this dictionary. </p>
<p class="faldoc_text">If the function doesn't declare any parameter, returns nil. </p>
</p>
<h3 class="faldoc_funcname"><a name="argv">argv()</a></h3>
<p class="item_brief">Returns all the parameters of the current function as a vector. </p>
<p class="faldoc_funcdecl">argv</p>
<p class="faldoc_text"><p class="faldoc_text">If the current function doesn't receive any parameter, it returns nil. </p>
</p>
<h3 class="faldoc_funcname"><a name="arrayAdd">arrayAdd()</a></h3>
<p class="item_brief">Adds an element to an array. </p>
<p class="faldoc_funcdecl">arrayAdd( array, item )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">array</td><td class="faldoc_paramdesc">The array where to add the new item. </td></tr><tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">The item to be added. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The element will be added at the end of the array, and its size will be increased by one. </p>
</p>
<h3 class="faldoc_funcname"><a name="arrayBuffer">arrayBuffer()</a></h3>
<p class="item_brief">Creates an array filled with nil items. </p>
<p class="faldoc_funcdecl">arrayBuffer( size, [defItem] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">size</td><td class="faldoc_paramdesc">The length of the returned array. </td></tr>
<tr><td class="faldoc_optparam">defItem</td><td class="faldoc_optparamdesc">The default item to be that will fill the array. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> An array filled with <b>size</b> nil elements. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function is useful when the caller knows the number of needed items. In this way, it is just necessary to set the various elements to their values, rather than adding them to the array. This will result in faster operations. </p>
<p class="faldoc_text"> If <b>defItem</b> is not given, the elements in the returned array will be set to nil, otherwise each element will be a flat copy of <b>item</b>. </p>
</p>
<h3 class="faldoc_funcname"><a name="arrayCompact">arrayCompact()</a></h3>
<p class="item_brief">Reduces the memory used by an array. </p>
<p class="faldoc_funcdecl">arrayCompact( array )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">array</td><td class="faldoc_paramdesc">The array itself. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">Itself </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Normally, array operations, as insertions, additions and so on cause the array to grow to accommodate items that may come in the future. also, reducing the size of an array doesn't automatically dispose of the memory held by the array to store its elements. </p>
<p class="faldoc_text">This function grants that the memory used by the array is strictly the memory needed to store its data. </p>
</p>
<h3 class="faldoc_funcname"><a name="arrayDel">arrayDel()</a></h3>
<p class="item_brief">Deletes the first element matching a given item. </p>
<p class="faldoc_funcdecl">arrayDel( array, item )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">array</td><td class="faldoc_paramdesc">The array that is to be changed. </td></tr><tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">The item that must be deleted. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">true if at least one item has been removed, false otherwise. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The function scans the array searching for an item that is considered equal to the given one. If such an item can be found, it is removed and the function returns true. If the item cannot be found, false is returned. </p>
<p class="faldoc_text">Only the first item matching the given one will be deleted. </p>
</p>
<h3 class="faldoc_funcname"><a name="arrayDelAll">arrayDelAll()</a></h3>
<p class="item_brief">Deletes all the occurrences of a given item in an array. </p>
<p class="faldoc_funcdecl">arrayDelAll( array, item )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">array</td><td class="faldoc_paramdesc">The array that is to be changed. </td></tr><tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">The item that must be deleted. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">true if at least one item has been removed, false otherwise. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function removes all the elements of the given array that are considered equivalent to the given item. If one or more elements have been found and deleted, the function will return true, else it will return false. </p>
</p>
<h3 class="faldoc_funcname"><a name="arrayFill">arrayFill()</a></h3>
<p class="item_brief">Fills the array with the given element. </p>
<p class="faldoc_funcdecl">arrayFill( array, item )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">array</td><td class="faldoc_paramdesc">The array where to add the new item. </td></tr><tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">The item to be replicated. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> The same <b>array</b> passed as parameter. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This method allows to clear a whole array, resetting all the elements to a default value. </p>
</p>
<h3 class="faldoc_funcname"><a name="arrayFind">arrayFind()</a></h3>
<p class="item_brief">Searches for a given item in an array. </p>
<p class="faldoc_funcdecl">arrayFind( array, item, [start], [end] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">array</td><td class="faldoc_paramdesc">The array that will be searched. </td></tr><tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">The array that will be searched. </td></tr>
<tr><td class="faldoc_optparam">start</td><td class="faldoc_optparamdesc">Optional first element to be searched. </td></tr><tr><td class="faldoc_optparam">end</td><td class="faldoc_optparamdesc">Optional last element +1 to be searched. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The position of the searched item in the array, or -1 if not found. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function searches the array for a given item (or for an item considered equivalent to the given one). If that item is found, the item position is returned, else -1 is returned. </p>
<p class="faldoc_text">An optional range may be specified to limit the search in the interval start included, end excluded. </p>
</p>
<h3 class="faldoc_funcname"><a name="arrayHead">arrayHead()</a></h3>
<p class="item_brief">Extracts the first element of an array and returns it. </p>
<p class="faldoc_funcdecl">arrayHead( array )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">array</td><td class="faldoc_paramdesc">The array that will be modified. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The extracted item. </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_AccessError.html">AccessError</a></td><td class="faldoc_raisedesc">if the array is empty. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function removes the first item of the array and returns it. If the original array is empty, AccessError is raised. </p>
</p>
<h3 class="faldoc_funcname"><a name="arrayIns">arrayIns()</a></h3>
<p class="item_brief">Inserts an item into an array. </p>
<p class="faldoc_funcdecl">arrayIns( array, itempos, item )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">array</td><td class="faldoc_paramdesc">The array where the item should be placed. </td></tr><tr><td class="faldoc_param">itempos</td><td class="faldoc_paramdesc">The position where the item should be placed. </td></tr><tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">The item to be inserted. The item is inserted before the given position. If pos is 0, the item is inserted in the very first position, while if it's equal to the array length, it is appended at the array tail. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="arrayMerge">arrayMerge()</a></h3>
<p class="item_brief">Merges two arrays. </p>
<p class="faldoc_funcdecl">arrayMerge( array1, array2, [insertPos], [start], [end] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">array1</td><td class="faldoc_paramdesc">Array containing the first half of the merge, that will be modified. </td></tr><tr><td class="faldoc_param">array2</td><td class="faldoc_paramdesc">Array containing the second half of the merge, read-only </td></tr>
<tr><td class="faldoc_optparam">insertPos</td><td class="faldoc_optparamdesc">Optional position of array 1 at which to place array2 </td></tr><tr><td class="faldoc_optparam">start</td><td class="faldoc_optparamdesc">First element of array2 to merge in array1 </td></tr><tr><td class="faldoc_optparam">end</td><td class="faldoc_optparamdesc">Last element – 1 of array2 to merge in array1 </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The items in array2 are appended to the end of array1, or in case an mergePos is specified, they are inserted at the given position. If mergePos is 0, they are inserted at beginning of array1, while if it's equal to array1 size they are appended at the end. An optional start parameter may be used to specify the first element in the array2 that must be copied in array1; if given, the parameter end will specify the last element that must be copied plus 1; that is elements are copied from array2 in array1 from start to end excluded. </p>
<p class="faldoc_text">The items are copied shallowly. This means that if an object is in array2 and it's modified thereafter, both array2 and array1 will grant access to the modified object. </p>
</p>
<h3 class="faldoc_funcname"><a name="arrayNM">arrayNM()</a></h3>
<p class="item_brief">Force an array to be non-method. </p>
<p class="faldoc_funcdecl">arrayNM( array )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">array</td><td class="faldoc_paramdesc">the array that should not be transformed into a method. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The same array passed as parameter. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Callable arrays stored in objects become methods when they are accessed. At times, this is not desirable. Suppose it is necessary to store a list of items, possibly functions, in an object, and that random access is needed. </p>
<p class="faldoc_text">In this case, an array is a good storage, but it's useful to tell Falcon that this array is never to be considered a method for the host object. Consider the following case: </p>
<pre class="faldoc_code">
class WithArrays( a )
asMethod = a
asArray= arrayNM( a.clone() ) // or a.clone().NM()
end
wa = WithArrays( [ printl, 'hello' ] )
// this is ok
for item in wa.asArray: > "Item in this array: ", item
// this will raise an error
for item in wa.asMethod: > "Item in this array: ", item
</pre>
<p class="faldoc_text">The array is cloned in this example as the function modifies the array itself, which becomes non-methodic, and returns it without copying it. So, if not copied, in this example also asMethod would have been non-methodic. </p>
</p>
<h3 class="faldoc_funcname"><a name="arrayRemove">arrayRemove()</a></h3>
<p class="item_brief">Removes one or more elements in the array. </p>
<p class="faldoc_funcdecl">arrayRemove( array, itemPos, [lastItemPos] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">array</td><td class="faldoc_paramdesc">The array from which items must be removed. </td></tr><tr><td class="faldoc_param">itemPos</td><td class="faldoc_paramdesc">The position of the item to be removed, or the first of the items to be removed. </td></tr>
<tr><td class="faldoc_optparam">lastItemPos</td><td class="faldoc_optparamdesc">The last item to be removed, in range semantic. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> Remove one item or a range of items. The size of the array is shortened accordingly. The semantic of <b>lastItemPos</b> is the same as ranged access to the array. </p>
</p>
<h3 class="faldoc_funcname"><a name="arrayResize">arrayResize()</a></h3>
<p class="item_brief">Changes the size of the array. </p>
<p class="faldoc_funcdecl">arrayResize( array, newSize )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">array</td><td class="faldoc_paramdesc">The array that will be resize. </td></tr><tr><td class="faldoc_param">newSize</td><td class="faldoc_paramdesc">The new size for the array. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">If the given size is smaller than the current size, the array is shortened. If it's larger, the array is grown up to the desired size, and the missing elements are filled by adding nil values. </p>
</p>
<h3 class="faldoc_funcname"><a name="arrayScan">arrayScan()</a></h3>
<p class="item_brief">Searches an array for an item satisfying arbitrary criteria. </p>
<p class="faldoc_funcdecl">arrayScan( array, func, [start], [end] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">array</td><td class="faldoc_paramdesc">The array that will be searched. </td></tr><tr><td class="faldoc_param">func</td><td class="faldoc_paramdesc">Function that verifies the criterion. </td></tr>
<tr><td class="faldoc_optparam">start</td><td class="faldoc_optparamdesc">Optional first element to be searched. </td></tr><tr><td class="faldoc_optparam">end</td><td class="faldoc_optparamdesc">Optional upper end of the range.. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The position of the searched item in the array, or -1 if not found. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">With this function, it is possible to specify an arbitrary search criterion. The items in the array are fed one after another as the single parameter to the provided scanFunc, which may be any Falcon callable item, including a method. If the scanFunc returns true, the scan is interrupted and the index of the item is returned. If the search is unsuccesful, -1 is returned. </p>
<p class="faldoc_text">An optional start parameter may be provided to begin searching from a certain point on. If also an end parameter is given, the search is taken between start included and end excluded (that is, the search terminates when at the element before the position indicated by end). </p>
<p class="faldoc_text">Scan function is called in atomic mode. The called function cannot be interrupted by external kind requests, and it cannot sleep or yield the execution to other coroutines. </p>
</p>
<h3 class="faldoc_funcname"><a name="arraySort">arraySort()</a></h3>
<p class="item_brief">Sorts an array, possibly using an arbitrary ordering criterion. </p>
<p class="faldoc_funcdecl">arraySort( array, [sortingFunc] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">array</td><td class="faldoc_paramdesc">The array that will be searched. </td></tr>
<tr><td class="faldoc_optparam">sortingFunc</td><td class="faldoc_optparamdesc">A function used to compare two items. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The function sorts the contents of the array so that the first element is the smaller one, and the last element is the bigger one. String sorting is performed lexicographically. To sort the data based on an arbitrary criterion, or to sort complex items, or objects, based on some of their contents, the caller may provide a sortFunc that will receive two parameters. The sortFunc must return -1 if the first parameter is to be considered smaller than the second, 0 if they are the same and 1 if the second parameter is considered greater. </p>
<p class="faldoc_text">Sort function is called in atomic mode. The called function cannot be interrupted by external kind requests, and it cannot sleep or yield the execution to other coroutines. </p>
</p>
<h3 class="faldoc_funcname"><a name="arrayTail">arrayTail()</a></h3>
<p class="item_brief">Extracts the last element of an array and returns it. </p>
<p class="faldoc_funcdecl">arrayTail( array )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">array</td><td class="faldoc_paramdesc">The array that will be modified. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The extracted item. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function removes the last item of the array and returns it. If the original array is empty, AccessError is raised. </p>
</p>
<h3 class="faldoc_funcname"><a name="asin">asin()</a></h3>
<p class="item_brief">Returns the arc sine of the argument. </p>
<p class="faldoc_funcdecl">asin( x )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">x</td><td class="faldoc_paramdesc">Argument. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The arc sine of the argument. </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_MathError.html">MathError</a></td><td class="faldoc_raisedesc">If the argument is out of domain. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The return value is expressed in radians. </p>
<p class="faldoc_text">The function may raise an error if the value cannot be computed because of domain or overflow errors. </p>
</p>
<h3 class="faldoc_funcname"><a name="assert">assert()</a></h3>
<p class="item_brief">Creates a message assertion on a certain message slot. </p>
<p class="faldoc_funcdecl">assert( msg, data )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">msg</td><td class="faldoc_paramdesc">The message to be asserted. </td></tr><tr><td class="faldoc_param">data</td><td class="faldoc_paramdesc">The value of the assertion. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">If there are already subscribed callbacks for this message a broadcast on them is performed now. </p>
</p>
<h3 class="faldoc_funcname"><a name="atan">atan()</a></h3>
<p class="item_brief">Returns the arc tangent of the argument. </p>
<p class="faldoc_funcdecl">atan( x )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">x</td><td class="faldoc_paramdesc">Argument. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The arc tangent of the argument. </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_MathError.html">MathError</a></td><td class="faldoc_raisedesc">If the argument is out of domain. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function computes the principal value of the arc tangent of its argument x. The value of x should be in the range [-1,1]. </p>
<p class="faldoc_text">The return value is expressed in radians. </p>
<p class="faldoc_text">The function may raise a Math error if the value cannot be computed because of domain or overflow errors. </p>
</p>
<h3 class="faldoc_funcname"><a name="atan2">atan2()</a></h3>
<p class="item_brief">Returns the arc tangent of x / y. </p>
<p class="faldoc_funcdecl">atan2( x, y )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">x</td><td class="faldoc_paramdesc">First argument. </td></tr><tr><td class="faldoc_param">y</td><td class="faldoc_paramdesc">Second argument. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The arc tangent of the x / y. </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_MathError.html">MathError</a></td><td class="faldoc_raisedesc">If the argument is out of domain. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function computes the principal value of the arc tangent of x/y, using the signs of both arguments to determine the quadrant of the return value. </p>
<p class="faldoc_text">The return value is expressed in radians. </p>
<p class="faldoc_text">The function may raise a Math error if the value cannot be computed because of domain or overflow errors. </p>
</p>
<h3 class="faldoc_funcname"><a name="attributes">attributes()</a></h3>
<p class="item_brief">Returns a dictionary containing annotation attributes of the current module. </p>
<p class="faldoc_funcdecl">attributes</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">Nil if the current module has no attributes, or a string-indexed dictionary. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="baseClass">baseClass()</a></h3>
<p class="item_brief">Returns the class item from which an object has been instantiated. </p>
<p class="faldoc_funcdecl">baseClass( item )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc"></td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A class item or nil. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">If applied on objects, returns the class item that has been used to instantiate an object. Calling the returned item is equivalent to call the class that instantiated this object. </p>
<p class="faldoc_text"> The returned item can be used to create another instance of the same class, or for comparisons on <b>select</b> branches. </p>
<p class="faldoc_text">If the item on which this method is applied is not an object, it returns nil. </p>
</p>
<h3 class="faldoc_funcname"><a name="beginCritical">beginCritical()</a></h3>
<p class="item_brief">Signals the VM that this coroutine must not be interrupted. </p>
<p class="faldoc_funcdecl">beginCritical</p>
<p class="faldoc_text"><p class="faldoc_text"> After this call the VM will abstain from swapping this coroutine out of the execution context. The coroutine can then alter a set of data that must be prepare and readied for other coroutines, and then call <a href="./functions.html#endCritical">endCritical</a> or <a href="./functions.html#yield">yield</a> to pass the control back to the other coroutines. </p>
<p class="faldoc_text"> This function is not recursive. Successive calls to <b>beginCritical</b> are not counted, and have actually no effect. The first call to <a href="./functions.html#yield">yield</a> will swap out the coroutine, and the first call to <a href="./functions.html#endCritical">endCritical</a> will signal the availability of the routine to be swapped out, no matter how many times <a href="./functions.html#beginCritical">beginCritical</a> has been called. </p>
</p>
<h3 class="faldoc_funcname"><a name="bless">bless()</a></h3>
<p class="item_brief">Blesses a dictionary, making it an OOP instance. </p>
<p class="faldoc_funcdecl">bless( dict, [mode] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">dict</td><td class="faldoc_paramdesc">A dictionary to be blessed. </td></tr>
<tr><td class="faldoc_optparam">mode</td><td class="faldoc_optparamdesc">True (default) to bless the dictionary, false to unbless it. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> The same dictonary passed as <b>dict</b>. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Blessed dictionaries become sensible to OOP operators: dot accessors and "provides" keyword behave as if the dictionary was an object instance, with its string entries being properties. </p>
</p>
<h3 class="faldoc_funcname"><a name="brigade">brigade()</a></h3>
<p class="item_brief">Process a list of functions passing the same parameters to them. </p>
<p class="faldoc_funcdecl">brigade( fl, ... )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">fl</td><td class="faldoc_paramdesc">The sequence of callable items to be called. </td></tr><tr><td class="faldoc_param">...</td><td class="faldoc_paramdesc">Arbitrary parameters used by the brigade functions. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The return value of the last function in fl. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function process a sequence of functions passing them the same set of parameters. The idea is that of a "brigate" of functions operating all on the same parameters so that it is possible to put common code into separate functions. </p>
<p class="faldoc_text">Items in the list are not functionally evaluated; they are simply called, passing to them the same parameters that the brigade group receives. Brigate is an ETA funcion, and this means that ongoing functional evaluation is interrupted as soon as a brigade is encountered. </p>
<pre class="faldoc_code">
function mean( array )
value = 0
for elem in array: value += elem
return value / len( array )
end
function dbl( array )
for i in [0:len(array)]: array[i] *= 2
end
doubleMean = .[ brigade .[
dbl
mean
]]
> "Mean: ", mean( [1,2,3] )
> "Double mean: ", doubleMean( [1,2,3] )
</pre>
<p class="faldoc_text">The above example brigades a "prefix" function to double the values in an array that must be processed by the main function. </p>
<p class="faldoc_text">Using out of band return values, the functions in the sequence can also control the parameters that the following functions will receive, terminate immediately the evaluation or restart it, forming a sort of iterative functional loop. An oob 0 causes the sequence to be interrutped (and return oob(0) itself), an out of band 1 will cause the first element of the sequence to be called again, and an out of band array will permanently change the parameters as seen by the functions. </p>
<p class="faldoc_text">The following brigate performs a first step using the given parameters, and another one using modified ones: </p>
<pre class="faldoc_code">
looper = .[brigade .[
{ val, text => printl( text, ": ", val ) } // do things
{ val, text => oob( [val+1, "Changed"] ) } // change params
{ val, text => val >= 10 ? oob(0) : oob(1)} // loop control
]]
looper( 1, "Original" )
</pre>
</p>
<h3 class="faldoc_funcname"><a name="broadcast">broadcast()</a></h3>
<p class="item_brief">Sends a message to every callable item subscribed to a message. </p>
<p class="faldoc_funcdecl">broadcast( msg, [...] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">msg</td><td class="faldoc_paramdesc">A message (string) to be broadcast. </td></tr>
<tr><td class="faldoc_optparam">...</td><td class="faldoc_optparamdesc">Zero or more data to be broadcaset. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> true if <b>msg</b> is found, false if it doesn't exist. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> Broadcast function implicitly searches for a Virtual Machine Message Slot (<a href="./class_VMSlot.html">VMSlot</a>) with the given <b>msg</b> name, and if it finds it, it emits a broadcast on that. </p>
<p class="faldoc_text">If the message is not found, the broadcast is silently dropped (no error is raised), but the function returns false. </p>
<p class="faldoc_text"> As calling this function requires a scan in the virtual machine message slot table, in case of repeated operations it is preferable to explicitly search for a slot with <a href="./functions.html#getSlot">getSlot</a>, or to create it as an <a href="./class_VMSlot.html">VMSlot</a> instance. On the other hand, if the reference to a VMSlot is not needed, this function allows to broadcast on the slot without adding the overhead required by the creation of the <a href="./class_VMSlot.html">VMSlot</a> wrapper. </p>
</p>
<h3 class="faldoc_funcname"><a name="cascade">cascade()</a></h3>
<p class="item_brief">Concatenate a set of callable items so to form a single execution unit. </p>
<p class="faldoc_funcdecl">cascade( callList, [...] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">callList</td><td class="faldoc_paramdesc">Sequence of callable items. </td></tr>
<tr><td class="faldoc_optparam">...</td><td class="faldoc_optparamdesc">Optional parameters to be passed to the first callable item. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The return value of the last callable item. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function executes a set of callable items passing the parameters it receives beyond the first one to the first item in the list; from there on, the return value of the previous call is fed as the sole parameter of the next call. In other words, </p>
<pre class="faldoc_code">
cascade( [F1, F2, ..., FN], p1, p2, ..., pn )
</pre>
<p class="faldoc_text">is equivalent to </p>
<pre class="faldoc_code">
FN( ... F2( F1( p1, p2, ..., pn ) ) ... )
</pre>
<p class="faldoc_text">A function may declare itself "uninterested" to insert its value in the cascade by returning an out-of-band item. In that case, the return value is ignored and the same parameter it received is passed on to the next calls and eventually returned. </p>
<p class="faldoc_text">Notice that the call list is not evaluated in functional context; it is just a list of callable items. To evaluate the list, or part of it, in functional context, use the eval() function. </p>
<p class="faldoc_text">A simple example usage is the following: </p>
<pre class="faldoc_code">
function square( a )
return a * a
end
function sqrt( a )
return a ** 0.5
end
cascade_abs = [cascade, [square, sqrt] ]
> cascade_abs( 2 ) // 2
> cascade_abs( -4 ) // 4
</pre>
<p class="faldoc_text">Thanks to the possibility to prevent insertion of the return value in the function call sequence, it is possible to program "interceptors" that will catch the progress of the sequence without interfering: </p>
<pre class="faldoc_code">
function showprog( v )
> "Result currently ", v
return oob(nil)
end
// define sqrt and square as before...
cascade_abs = [cascade, [square, showprog, sqrt, showprog] ]
> "First process: ", cascade_abs( 2 )
> "Second process: ", cascade_abs( -4 )
</pre>
<p class="faldoc_text">If the first function of the list declines processing by returning an oob item, the initial parameters are all passed to the second function, and so on till the last call. </p>
<p class="faldoc_text">For example: </p>
<pre class="faldoc_code">
function whichparams( a, b )
> "Called with ", a, " and ", b
return oob(nil)
end
csq = [cascade, [ whichparams, {a,b=> a*b} ]
> csq( 3, 4 )
</pre>
<p class="faldoc_text">Here, the first function in the list intercepts the parameters but, as it doesn't accepts them, they are both passed to the second in the list. </p>
</p>
<h3 class="faldoc_funcname"><a name="ceil">ceil()</a></h3>
<p class="item_brief">Returns the greatest integer near to the given value. </p>
<p class="faldoc_funcdecl">ceil( x )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">x</td><td class="faldoc_paramdesc">Argument. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The ceil value. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Ceil function returns the highest integer near to a given floating point number. For example, ceil of 1.1 is 2, and ceil of -1.1 is -1. If an integer number is given, then the function returns the same number. </p>
</p>
<h3 class="faldoc_funcname"><a name="choice">choice()</a></h3>
<p class="item_brief">Selects one of two alternatives depending on the evaluation of the first parameter. </p>
<p class="faldoc_funcdecl">choice( selector, whenTrue, [whenFalse], [...] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">selector</td><td class="faldoc_paramdesc">The item to be evaluated. </td></tr><tr><td class="faldoc_param">whenTrue</td><td class="faldoc_paramdesc">The item to return if selector evaluates to true. </td></tr>
<tr><td class="faldoc_optparam">whenFalse</td><td class="faldoc_optparamdesc">The item to be returned if selector evaluates to false </td></tr><tr><td class="faldoc_optparam">...</td><td class="faldoc_optparamdesc">Optional parameters to be passed to the first callable item. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The return value of the last callable item. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The selector parameter is evaluated in functional context. If it's a true atom or if it's a callable array which returns a true value, the ifTrue parameter is returned as-is, else the ifFalse parameter is returned. If the ifFalse parameter is not given and the selector evaluates to false, nil is returned. </p>
<p class="faldoc_text"> The choice function is equivalent to iff where each branch is passed through the <a href="./functions.html#lit">lit</a> function: </p>
<pre class="faldoc_code">
choice( selector, a, b ) == iff( selector, [lit, a], [lit, b] )
</pre>
<p class="faldoc_text">In case a literal value is needed, choice is more efficient than using iff and applying lit on the parameters. </p>
</p>
<h3 class="faldoc_funcname"><a name="chr">chr()</a></h3>
<p class="item_brief">Returns a string containing a single character that corresponds to the given number. </p>
<p class="faldoc_funcdecl">chr( number )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">number</td><td class="faldoc_paramdesc">Numeric code of the desired character </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">a single-char string. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function returns a single character string whose only character is the UNICODE equivalent for the given number. The number must be a valid UNICODE character, so it must be in range 0-0xFFFFFFFF. </p>
</p>
<h3 class="faldoc_funcname"><a name="className">className()</a></h3>
<p class="item_brief">Returns the name of the class an instance is instantiated from. </p>
<p class="faldoc_funcdecl">className( The )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">The</td><td class="faldoc_paramdesc">item to be checked. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The class name of an object (a string) or nil. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">If applied to objects, returns the name of the class of which the object is an instance. When applied to classes, it return the class symbolic name. In all other cases, return nil. </p>
</p>
<h3 class="faldoc_funcname"><a name="clone">clone()</a></h3>
<p class="item_brief">Performs a deep copy of the item. </p>
<p class="faldoc_funcdecl">clone( item )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">The item to be copied. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A copy of the item. </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_CloneError.html">CloneError</a></td><td class="faldoc_raisedesc">if the item is not cloneable. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> Returns an item equal to the <b>item</b>, but phisically separated. If the item is a sequence, only the first level of the item gets actually cloned: vectors and dictionaries gets cloned, but the items they store are just copied. This means that the new copy of the collection itself may change, and the older version will stay untouched, but if a deep item in the collection (as an object) is changed, its change will be reflected also in the original collection. </p>
<p class="faldoc_text">Cloning objects causes each of their properties to be cloned. If they store an internal user data which is provided by extension modules or embedding applications, that data is cloned too. Behavior of user data is beyond the control of the script, and the data may actually be just referenced or it may also refuse to be cloned. In that case, this method will raise a CloneError, which indicates that a deep user data provided by an external module or application doesn't provide a cloning feature. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> Cloning objects that stores other objects referencing themselves in their properties may cause an endless loop in this version. To provide a safe duplicate of objects that may be organized in circular hierarcies, overload the clone method so that it creates a new instance of the item and just performs a flat copy of the properties. </p>
</p>
<h3 class="faldoc_funcname"><a name="combinations">combinations()</a></h3>
<p class="item_brief">Returns the combination of the arguments. </p>
<p class="faldoc_funcdecl">combinations( x, y )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">x</td><td class="faldoc_paramdesc">First argument. </td></tr><tr><td class="faldoc_param">y</td><td class="faldoc_paramdesc">Second arguments. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The combination of the arguments. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The return value is expressed as a floating point value. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> For high values of <b>x</b>, the function may require exponential computational time and power. </p>
</p>
<h3 class="faldoc_funcname"><a name="compare">compare()</a></h3>
<p class="item_brief">Performs a lexicographical comparison. </p>
<p class="faldoc_funcdecl">compare( operand1, operand2 )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">operand1</td><td class="faldoc_paramdesc">The item to which this object must be compared. </td></tr><tr><td class="faldoc_param">operand2</td><td class="faldoc_paramdesc">The item to which this object must be compared. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">-1, 0 or 1 depending on the comparation result. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Performs a lexicographical comparison between the self item and the item passed as a parameter. If the item is found smaller than the parameter, it returns -1; if the item is greater than the parameter, it returns 1. If the two items are equal, it returns 0. </p>
<p class="faldoc_text">The compare method, if overloaded, is used by the Virtual Machine to perform tests on unknown types (i.e. objects), and to sort dictionary keys. </p>
<p class="faldoc_text"> Item different by type are ordered by their type ID, as indicated in the documentation of the <a href="./functions.html#typeOf">typeOf</a> core function. </p>
<p class="faldoc_text">By default, string comparison is performed in UNICODE character order, and objects, classes, vectors, and dictionaries are ordered by their internal pointer address. </p>
</p>
<h3 class="faldoc_funcname"><a name="consume">consume()</a></h3>
<p class="item_brief">Consumes currently being broadcasted signal. </p>
<p class="faldoc_funcdecl">consume</p>
<h3 class="faldoc_funcname"><a name="cos">cos()</a></h3>
<p class="item_brief">Returns the cosine of the argument. </p>
<p class="faldoc_funcdecl">cos( x )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">x</td><td class="faldoc_paramdesc">Argument. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The cosine of the argument. </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_MathError.html">MathError</a></td><td class="faldoc_raisedesc">If the argument is out of domain. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The return value is expressed in radians. </p>
<p class="faldoc_text">The function may raise an error if the value cannot be computed because of domain or overflow errors. </p>
</p>
<h3 class="faldoc_funcname"><a name="deg2rad">deg2rad()</a></h3>
<p class="item_brief">Converts an angle expressed in degrees into radians. </p>
<p class="faldoc_funcdecl">deg2rad( x )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">x</td><td class="faldoc_paramdesc">An angle expressed in degrees. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The angle converted in radians. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="deoob">deoob()</a></h3>
<p class="item_brief">Turns an out-of-band item in a normal item. </p>
<p class="faldoc_funcdecl">deoob( item )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">The out of band item to be turned into a normal item. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">An the non-out-of-band version version of the item. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> The function returns a flat copy of the item without the out-of-band status set. If the item was initially not OOB, then deoob() does nothing. See <a href="./functions.html#oob">oob</a> for a deeper explanation of OOB items. </p>
</p>
<h3 class="faldoc_funcname"><a name="derivedFrom">derivedFrom()</a></h3>
<p class="item_brief">Checks if this item has a given parent. </p>
<p class="faldoc_funcdecl">derivedFrom( item, cls )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">The item to be checked. </td></tr><tr><td class="faldoc_param">cls</td><td class="faldoc_paramdesc">A symbolic class name or a class instance. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">true if the given class is one of the ancestors of this item. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">If applied on objects, returns true if the given parameter is the name of the one of the classes that compose the class hierarchy of the object. </p>
<p class="faldoc_text">If applied on class instances, it returns true if the parameter is its name or the name of one of its ancestors. </p>
<p class="faldoc_text">In all the other cases, it return false. </p>
<p class="faldoc_text">It is also possible to use directly the class instance as a parameter, instead of a class name. In example: </p>
<pre class="faldoc_code">
object MyError from Error
//...
end
> "Is MyError derived from 'Error' (by name)?: ", \
derivedFrom( MyError, "Error" )
> "Is MyError derived from 'Error' (by class)?: ", \
derivedFrom( MyError, Error )
</pre>
</p>
<h3 class="faldoc_funcname"><a name="describe">describe()</a></h3>
<p class="item_brief">Returns the deep contents of an item on a string representation. </p>
<p class="faldoc_funcdecl">describe( item, [depth], [maxLen] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">The item to be inspected. </td></tr>
<tr><td class="faldoc_optparam">depth</td><td class="faldoc_optparamdesc">Maximum inspect depth. </td></tr><tr><td class="faldoc_optparam">maxLen</td><td class="faldoc_optparamdesc">Limit the display size of possibly very long items as i.e. strings or membufs. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function returns a string containing a representation of the given item. If the item is deep (an array, an instance, a dictionary) the contents are also passed through this function. </p>
<p class="faldoc_text">This function traverses arrays and items deeply; there isn't any protection against circular references, which may cause endless loop. However, the default maximum depth is 3, which is a good depth for debugging (goes deep, but doesn't dig beyond average interesting points). Set to -1 to have infinite depth. </p>
<p class="faldoc_text"> By default, only the first 60 characters of strings and elements of membufs are displayed. You may change this default by providing a <b>maxLen</b> parameter. </p>
<p class="faldoc_text">You may create personalized inspect functions using forward bindings, like the following: </p>
<pre class="faldoc_code">
compactDescribe = .[inspect depth|1 maxLen|15]
</pre>
</p>
<h3 class="faldoc_funcname"><a name="deserialize">deserialize()</a></h3>
<p class="item_brief">Deserialize an item from a stream. </p>
<p class="faldoc_funcdecl">deserialize( stream )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">stream</td><td class="faldoc_paramdesc">An instance of the Stream (or derived) class. </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 underlying stream error. </td></tr><tr><td class="faldoc_raiseitem"><a href="./class_GenericError.html">GenericError</a></td><td class="faldoc_raisedesc">If the data is correctly de-serialized, but it refers to external symbols non defined by this script. </td></tr><tr><td class="faldoc_raiseitem"><a href="./class_ParseError.html">ParseError</a></td><td class="faldoc_raisedesc">if the format of the input data is invalid. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The returned item is a new copy of the item that has been previously serialized on the given stream. After the read, the stream pointer is left ready for a new read, so that items that are serialized in sequence may be deserialized in the same order. </p>
<p class="faldoc_text">If the underlying stream read causes an i/o failure, an error is raised. </p>
<p class="faldoc_text">Also, an error is raised if the function cannot deserialize from the stream because the data format is invalid. </p>
</p>
<h3 class="faldoc_funcname"><a name="dictBack">dictBack()</a></h3>
<p class="item_brief">Returns the last item in the dictionary. </p>
<p class="faldoc_funcdecl">dictBack( dict, [remove], [key] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">dict</td><td class="faldoc_paramdesc">The dictionary on which to operate. </td></tr>
<tr><td class="faldoc_optparam">remove</td><td class="faldoc_optparamdesc">If true, remove the dictionary entry too. </td></tr><tr><td class="faldoc_optparam">key</td><td class="faldoc_optparamdesc">If true, return the key instead of the value. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The last value (or key) in the dictionary. </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_AccessError.html">AccessError</a></td><td class="faldoc_raisedesc">if the dictionary is empty </td></tr>
</table>
</td></tr>
</table>
<h3 class="faldoc_funcname"><a name="dictBest">dictBest()</a></h3>
<p class="item_brief">Returns an iterator set to a given key, or finds the best position for its insertion. </p>
<p class="faldoc_funcdecl">dictBest( dict, key )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">dict</td><td class="faldoc_paramdesc">The dictionary. </td></tr><tr><td class="faldoc_param">key</td><td class="faldoc_paramdesc">The key to be found. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">An iterator to the best possible position. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">If the key is found in the dictionary, an iterator pointing to that key is returned. It is then possible to change the value of the found item, insert one item after or before the returned iterator or eventually delete the key. If the key is not found, an iterator pointing to the first key greater than the searched one is returned. The position is so that an insertion there would place the key in the right order. If the key is not found, the returned iterator is marked as out-of-band (see oob() at page 14). </p>
<p class="faldoc_text">The method insert() of the Iterator class is optimized so that if the iterator is already in a valid position where to insert its key, the binary search is not performed again. Compare: </p>
<pre class="faldoc_code">
d = [ "a" => 1, "c"=>2 ]
// two searches
if "b" notin d
d["b"] = 0
else
d["b"]++
end
// one search
iter = dictBest( dict, "b" )
isoob(iter) ? iter.insert( "b", 0 ) : iter.value( iter.value() + 1 )
</pre>
<p class="faldoc_text">In the first case, the insertion of a special value in a dictionary where the value is still not present has required a first search then a second one at insertion or modify. In the second case, the iterator can use the position information it has stored to avoid a second search. </p>
<p class="faldoc_text">This function can also be used just to know what is the nearest key being present in the dictionary. The searched key is greater than the one that can be reached with Iterator.prev(), and less or equal than the one pointed. If Iterator.hasPrev() is false, then the searched key is smaller than any other in the collection, and if Iterator.hasCurrent() is false, then the key is greater than any other. </p>
</p>
<h3 class="faldoc_funcname"><a name="dictClear">dictClear()</a></h3>
<p class="item_brief">Removes all the items from a dictionary. </p>
<p class="faldoc_funcdecl">dictClear( dict )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">dict</td><td class="faldoc_paramdesc">The dictionary to be cleared. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="dictFill">dictFill()</a></h3>
<p class="item_brief">Fills the dictionary values with the given item. </p>
<p class="faldoc_funcdecl">dictFill( dict, item )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">dict</td><td class="faldoc_paramdesc">The array where to add the new item. </td></tr><tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">The item to be replicated. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> The same <b>dict</b> passed as parameter. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This method allows to clear all the values in this dictionary, resetting all the elements to a default value. </p>
</p>
<h3 class="faldoc_funcname"><a name="dictFind">dictFind()</a></h3>
<p class="item_brief">Returns an iterator set to a given key. </p>
<p class="faldoc_funcdecl">dictFind( dict, key )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">dict</td><td class="faldoc_paramdesc">The dictionary. </td></tr><tr><td class="faldoc_param">key</td><td class="faldoc_paramdesc">The key to be found. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">An iterator to the found item, or nil if not found. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">If the key is found in the dictionary, an iterator pointing to that key is returned. It is then possible to change the value of the found item, insert one item after or before the returned iterator or eventually delete the key. If the key is not found, the function returns nil. </p>
</p>
<h3 class="faldoc_funcname"><a name="dictFront">dictFront()</a></h3>
<p class="item_brief">Returns the first item in the dictionary. </p>
<p class="faldoc_funcdecl">dictFront( dict, [remove], [key] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">dict</td><td class="faldoc_paramdesc">The dictionary on which to operate. </td></tr>
<tr><td class="faldoc_optparam">remove</td><td class="faldoc_optparamdesc">If true, remove the dictionary entry too. </td></tr><tr><td class="faldoc_optparam">key</td><td class="faldoc_optparamdesc">If true, return the key instead of the value. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The first value (or key) in the dictionary. </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_AccessError.html">AccessError</a></td><td class="faldoc_raisedesc">if the dictionary is empty </td></tr>
</table>
</td></tr>
</table>
<h3 class="faldoc_funcname"><a name="dictGet">dictGet()</a></h3>
<p class="item_brief">Retreives a value associated with the given key </p>
<p class="faldoc_funcdecl">dictGet( dict, key )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">dict</td><td class="faldoc_paramdesc">A dictionary. </td></tr><tr><td class="faldoc_param">key</td><td class="faldoc_paramdesc">The key to be found. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The value associated with a key, or an out-of-band nil if not found. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Return the value associated with the key, if present, or one of the values if more than one key matching the given one is present. If not present, the value returned will be nil. Notice that nil may be also returned if the value associated with a given key is exactly nil. In case the key cannot be found, the returned value will be marked as OOB. </p>
</p>
<h3 class="faldoc_funcname"><a name="dictKeys">dictKeys()</a></h3>
<p class="item_brief">Returns an array containing all the keys in the dictionary. </p>
<p class="faldoc_funcdecl">dictKeys( dict )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">dict</td><td class="faldoc_paramdesc">A dictionary. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">An array containing all the keys. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The returned keyArray contains all the keys in the dictionary. The values in the returned array are not necessarily sorted; however, they respect the internal dictionary ordering, which depends on a hashing criterion. </p>
<p class="faldoc_text">If the dictionary is empty, then an empty array is returned. </p>
</p>
<h3 class="faldoc_funcname"><a name="dictMerge">dictMerge()</a></h3>
<p class="item_brief">Merges two dictionaries. </p>
<p class="faldoc_funcdecl">dictMerge( destDict, sourceDict )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">destDict</td><td class="faldoc_paramdesc">The dictionary where the merge will take place. </td></tr><tr><td class="faldoc_param">sourceDict</td><td class="faldoc_paramdesc">A dictionary that will be inserted in destDict </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The function allows to merge two dictionaries. </p>
</p>
<h3 class="faldoc_funcname"><a name="dictRemove">dictRemove()</a></h3>
<p class="item_brief">Removes a given key from the dictionary. </p>
<p class="faldoc_funcdecl">dictRemove( dict, key )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">dict</td><td class="faldoc_paramdesc">A dictionary. </td></tr><tr><td class="faldoc_param">key</td><td class="faldoc_paramdesc">The key to be removed </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">True if the key is found and removed, false otherwise. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">If the given key is found, it is removed from the dictionary, and the function returns true. If it's not found, it returns false. </p>
</p>
<h3 class="faldoc_funcname"><a name="dictSet">dictSet()</a></h3>
<p class="item_brief">Stores a value in a dictionary </p>
<p class="faldoc_funcdecl">dictSet( dict, key, value )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">dict</td><td class="faldoc_paramdesc">A dictionary. </td></tr><tr><td class="faldoc_param">key</td><td class="faldoc_paramdesc">The key to be found. </td></tr><tr><td class="faldoc_param">value</td><td class="faldoc_paramdesc">The key to be set. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">True if the value was overwritten, false if it has been inserted anew. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_note"><span class="faldoc_notetype">Note:</span> This method bypassess setIndex__ override in blessed (POOP) dictionaries. </p>
</p>
<h3 class="faldoc_funcname"><a name="dictValues">dictValues()</a></h3>
<p class="item_brief">Extracts all the values in the dictionary. </p>
<p class="faldoc_funcdecl">dictValues( dict )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">dict</td><td class="faldoc_paramdesc">A dictionary. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">An array containing all the values. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The returned array contains all the value in the dictionary, in the same order by which they can be accessed traversing the dictionary. </p>
<p class="faldoc_text">If the dictionary is empty, then an empty array is returned. </p>
</p>
<h3 class="faldoc_funcname"><a name="dirChange">dirChange()</a></h3>
<p class="item_brief">Changes the current working directory. </p>
<p class="faldoc_funcdecl">dirChange( newDir )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">newDir</td><td class="faldoc_paramdesc">The new working directory. </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 error. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">On success, the working directory is changed to the specified one. The path must be indicated in Falcon conventions (forward slashes separating directories). On failure, an IoError is raised. </p>
</p>
<h3 class="faldoc_funcname"><a name="dirCurrent">dirCurrent()</a></h3>
<p class="item_brief">Returns the current working directory. </p>
<p class="faldoc_funcdecl">dirCurrent</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A string representing the current working directory. </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 error. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">On success, a string containing the current working directory is returned. The path is in Falcon convention (forward slashes). If any system error occurs, an IoError is raised. </p>
</p>
<h3 class="faldoc_funcname"><a name="dirMake">dirMake()</a></h3>
<p class="item_brief">Creates a directory. </p>
<p class="faldoc_funcdecl">dirMake( dirname, [bFull] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">dirname</td><td class="faldoc_paramdesc">The name of the directory to be created. </td></tr>
<tr><td class="faldoc_optparam">bFull</td><td class="faldoc_optparamdesc">Create also the full pat to the given directory. </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 error. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">On success, this function creates the given directory with normal attributes. </p>
<p class="faldoc_text">It is possible to specify both a relative or absolute path; both the relative and absolute path can contain a subtree specification, that is, a set of directories separated by forward slashes, which lead to the directory that should be created. For example: </p>
<pre class="faldoc_code">
dirMake( "top/middle/bottom" )
</pre>
<p class="faldoc_text"> instructs <b>dirMake</b> to create the directory bottom in a subdirectory "middle", which should already exist. Passing <b>true</b> as second parameter, dirMake will also try to create directories leading to the final destination, if they are missing. </p>
</p>
<h3 class="faldoc_funcname"><a name="dirMakeLink">dirMakeLink()</a></h3>
<p class="item_brief">Creates a soft link to a file. </p>
<p class="faldoc_funcdecl">dirMakeLink( source, dest )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">source</td><td class="faldoc_paramdesc">The original file path. </td></tr><tr><td class="faldoc_param">dest</td><td class="faldoc_paramdesc">The path to the link file. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The path of both source and dest parameter is to be expressed in Falcon convention (forward slashes), and can be both relative to the working directory or absolute. </p>
<p class="faldoc_text">Currently, the function works only on UNIX systems; Windows platforms have recently added this functionality, but they are still not supported by this function at the moment. </p>
<p class="faldoc_text">On success, the function returns true. On failure, it returns false. In case the function is not supported, it just returns false. (Comments are welcome). </p>
</p>
<h3 class="faldoc_funcname"><a name="dirReadLink">dirReadLink()</a></h3>
<p class="item_brief">On systems supporting symbolic links, returns the linked file. </p>
<p class="faldoc_funcdecl">dirReadLink( linkPath )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">linkPath</td><td class="faldoc_paramdesc">A path to a symbolic link. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">If the target file in the linkPath parameter is a symbolic link and can be read, the return value will be a string containing the file the link is pointing to. Otherwise, the function will return nil. Function will return nil also on system where symbolic links are not supported. </p>
</p>
<h3 class="faldoc_funcname"><a name="dirRemove">dirRemove()</a></h3>
<p class="item_brief">Removes an empty directory. </p>
<p class="faldoc_funcdecl">dirRemove( dir )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">dir</td><td class="faldoc_paramdesc">The path to the directory to be removed. </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 error. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The function removes an empty directory. On failure an IoError with code 1012 will be raised. </p>
</p>
<h3 class="faldoc_funcname"><a name="dolist">dolist()</a></h3>
<p class="item_brief">Repeats an operation on a list of parameters. </p>
<p class="faldoc_funcdecl">dolist( processor, sequence, [...] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">processor</td><td class="faldoc_paramdesc">A callable item that will receive data coming from the sequence. </td></tr><tr><td class="faldoc_param">sequence</td><td class="faldoc_paramdesc">A list of items that will be fed in the processor one at a time. </td></tr>
<tr><td class="faldoc_optparam">...</td><td class="faldoc_optparamdesc">Optional parameters to be passed to the first callable item. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The return value of the last callable item. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> Every item in <b>sequence</b> is passed as parameter to the processor, which must be a callable item. Items are also functionally evaluated, one by one, but the parameter <b>sequence</b> is not functionally evaluated as a whole; to do that, use the explicit evaluation: </p>
<pre class="faldoc_code">
dolist( processor, eval(array) )
</pre>
<p class="faldoc_text"> This method is equivalent to <a href="./functions.html#xmap">xmap</a>, but it has the advantage that it doesn't create an array of evaluated results. So, when it is not necessary to transform a sequence in another through a mapping function, but just to run repeatedly over a collection, this function is to be preferred. </p>
</p>
<h3 class="faldoc_funcname"><a name="endCritical">endCritical()</a></h3>
<p class="item_brief">Signals the VM that this coroutine can be interrupted. </p>
<p class="faldoc_funcdecl">endCritical</p>
<p class="faldoc_text"><p class="faldoc_text">After this call, the coroutine may be swapped. This will happen only if/when the timeslice for this coroutine is over. </p>
<p class="faldoc_text"> This function is not recursive. Successive calls to <a href="./functions.html#beginCritical">beginCritical</a> are not counted, and have actually no effect. The first call to <a href="./functions.html#yield">yield</a> will swap out the coroutine, and the first call to <a href="./functions.html#endCritical">endCritical</a> will signal the availability of the routine to be swapped out, no matter how many times <a href="./functions.html#beginCritical">beginCritical</a> has been called. </p>
</p>
<h3 class="faldoc_funcname"><a name="eval">eval()</a></h3>
<p class="item_brief">Evaluates a sequence in functional context. </p>
<p class="faldoc_funcdecl">eval( sequence )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">sequence</td><td class="faldoc_paramdesc">A sequence to be evaluated. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The sigma-reduction (evaluation) result. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The parameter is evaluated in functional context; this means that if the parameter is a sequence starting with a callable item, that item gets called with the rest of the sequence passed as parameters, and the result it returns is considered the "evaluation result". This is performed recursively, inner-to-outer, on every element of the sequence before the call to the first element is actually performed. </p>
<p class="faldoc_text">The description of the functional evaluation algorithm is included in the heading of this section. </p>
</p>
<h3 class="faldoc_funcname"><a name="exit">exit()</a></h3>
<p class="item_brief">Requires immediate termination of the program. </p>
<p class="faldoc_funcdecl">exit( value )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">value</td><td class="faldoc_paramdesc">an item representing VM exit code. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The VM execution will be interrupted, with normal state, and the item will be passed in the A register of the VM, where embedding application expects to receive the exit value. Semantic of the exit value will vary depending on the embedding application. The Falcon command line tools (and so, stand alone scripts) will pass this return value to the system if it is an integer, else they will terminate passing 0 to the system. </p>
<p class="faldoc_text">This function terminates the VM also when there are more coroutines running. </p>
</p>
<h3 class="faldoc_funcname"><a name="exp">exp()</a></h3>
<p class="item_brief">Returns exponential (e^x) of the argument. </p>
<p class="faldoc_funcdecl">exp( x )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">x</td><td class="faldoc_paramdesc">Argument. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The exponential of the argument. </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_MathError.html">MathError</a></td><td class="faldoc_raisedesc">If the argument is out of domain. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The function may raise an error if the value cannot be computed because of domain or overflow errors. </p>
</p>
<h3 class="faldoc_funcname"><a name="factorial">factorial()</a></h3>
<p class="item_brief">Returns the factorial of the argument. </p>
<p class="faldoc_funcdecl">factorial( x )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">x</td><td class="faldoc_paramdesc">Argument. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The factorial of the argument. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The return value is expressed as a floating point value. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> For high values of <b>x</b>, the function may require exponential computational time and power. </p>
</p>
<h3 class="faldoc_funcname"><a name="fileChgroup">fileChgroup()</a></h3>
<p class="item_brief">Changes UNIX group to a directory entry. </p>
<p class="faldoc_funcdecl">fileChgroup( path, groupId )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">path</td><td class="faldoc_paramdesc">A file or otherwise valid directory entry. </td></tr><tr><td class="faldoc_param">groupId</td><td class="faldoc_paramdesc">The new group id. </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 error. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function changes the group ownership of the given file on POSIX systems. </p>
</p>
<h3 class="faldoc_funcname"><a name="fileChmod">fileChmod()</a></h3>
<p class="item_brief">Changes UNIX access right to a directory entry. </p>
<p class="faldoc_funcdecl">fileChmod( path, mode )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">path</td><td class="faldoc_paramdesc">A file or otherwise valid directory entry. </td></tr><tr><td class="faldoc_param">mode</td><td class="faldoc_paramdesc">The new access mode. </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 error. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function will work only on POSIX systems. The file access mode will be set along the octal access right defined by POSIX. See man 3 chmod for details. </p>
</p>
<h3 class="faldoc_funcname"><a name="fileChown">fileChown()</a></h3>
<p class="item_brief">Changes UNIX owner to a directory entry. </p>
<p class="faldoc_funcdecl">fileChown( path, ownerId )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">path</td><td class="faldoc_paramdesc">A file or otherwise valid directory entry. </td></tr><tr><td class="faldoc_param">ownerId</td><td class="faldoc_paramdesc">The new ownerId. </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 error. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function changes the user ownership of the given file on POSIX systems. </p>
</p>
<h3 class="faldoc_funcname"><a name="fileCopy">fileCopy()</a></h3>
<p class="item_brief">Copies a whole file from one position to another. </p>
<p class="faldoc_funcdecl">fileCopy( source, dest )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">source</td><td class="faldoc_paramdesc">Source file to be copied </td></tr><tr><td class="faldoc_param">dest</td><td class="faldoc_paramdesc">Destination file. </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 error. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function performs a file copy. The function is still experimental and needs addition of VM interruption protocol compliancy, as well as the possibility to preserve or change the system attributes in the target copy. </p>
</p>
<h3 class="faldoc_funcname"><a name="fileExt">fileExt()</a></h3>
<p class="item_brief">Return the extension in a complete filename. </p>
<p class="faldoc_funcdecl">fileExt( fullpath )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">fullpath</td><td class="faldoc_paramdesc">A string containing a path. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The extension part. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The function determines the element past a dot after the filename part. Filenames can start with a "."; they are not considered extensions. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> The filename should be in Falcon format (URI convention with forward slashes). </p>
</p>
<h3 class="faldoc_funcname"><a name="fileMove">fileMove()</a></h3>
<p class="item_brief">Renames a file locally. </p>
<p class="faldoc_funcdecl">fileMove( sourcePath, destPath )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">sourcePath</td><td class="faldoc_paramdesc">The path of the file to be moved. </td></tr><tr><td class="faldoc_param">destPath</td><td class="faldoc_paramdesc">The path of the destination file. </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 error. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function actually renames a file. Usually, it will file if the caller tries to move the file across filesystems (i.e. on different discs). </p>
<p class="faldoc_text">On failure, an IoError is raised. </p>
</p>
<h3 class="faldoc_funcname"><a name="fileName">fileName()</a></h3>
<p class="item_brief">Determines the name of a file in a complete path. </p>
<p class="faldoc_funcdecl">fileName( path )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">path</td><td class="faldoc_paramdesc">A string containing a path. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The filename part in the path. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The function determines the filename part of a complete path name. The returned filename includes the extension, if present. The filename does not need to represent a file actually existing in the system. If the filename part cannot be determined, an empty string is returned. </p>
</p>
<h3 class="faldoc_funcname"><a name="fileNameMerge">fileNameMerge()</a></h3>
<p class="item_brief">Merges a filename split up in four elements. </p>
<p class="faldoc_funcdecl">fileNameMerge( spec, path, filename, ext )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">spec</td><td class="faldoc_paramdesc">The disk or server specification, an array containing all the elements of the file path, or nil. </td></tr><tr><td class="faldoc_param">path</td><td class="faldoc_paramdesc">Path to the file, or nil. </td></tr><tr><td class="faldoc_param">filename</td><td class="faldoc_paramdesc">Filename, or nil. </td></tr><tr><td class="faldoc_param">ext</td><td class="faldoc_paramdesc">extension, or nil. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A complete absolute path. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The final path is composed by adding a colon after the disk/server specification, a slash after the path and a dot before the extension. </p>
<p class="faldoc_text"> It is also possible to pass all the four elements in an array, in place of the <b>spec</b> parameter. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> This function is an interal shortcut to the <a href="./class_Path.html">Path</a> class. </p>
</p>
<h3 class="faldoc_funcname"><a name="filePath">filePath()</a></h3>
<p class="item_brief">Return the path specification part in a complete filename. </p>
<p class="faldoc_funcdecl">filePath( fullpath )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">fullpath</td><td class="faldoc_paramdesc">A string containing a path. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The path part. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The function determines the filename part of a complete path name. The returned filename includes the host or disk specification, if present. The filename does not need to represent a file actually existing in the system. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> The filename should be in Falcon format (URI convention with forward slashes). </p>
</p>
<h3 class="faldoc_funcname"><a name="fileRemove">fileRemove()</a></h3>
<p class="item_brief">Removes a file from the system. </p>
<p class="faldoc_funcdecl">fileRemove( filename )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">filename</td><td class="faldoc_paramdesc">The name, relative or absolute path of the file to be removed. </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 error. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function tries to remove a file from the filesystem. If unsuccessful, an error with code 1015 is raised. </p>
</p>
<h3 class="faldoc_funcname"><a name="fileType">fileType()</a></h3>
<p class="item_brief">Deterimnes the type of a file. </p>
<p class="faldoc_funcdecl">fileType( filename )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">filename</td><td class="faldoc_paramdesc">Relative or absolute path to a file. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A valid file type or FileStat.NOTFOUND if not found. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function is useful to know what of what kind of system entry is a certain file, or if it exists at all, without paying the overhead for a full FileStat object being instantiated. </p>
<p class="faldoc_text">Returned values may be: </p>
<ul>
<li>FileStat.NORMAL </li><li>FileStat.DIR </li><li>FileStat.PIPE </li><li>FileStat.LINK </li><li>FileStat.DEVICE </li><li>FileStat.SOCKET </li><li>FileStat.UNKNOWN </li>
</ul>
<p class="faldoc_text">or FileStat.NOTFOUND if the file doesn't exist. </p>
</p>
<h3 class="faldoc_funcname"><a name="fileUnit">fileUnit()</a></h3>
<p class="item_brief">Return the unit specificator in a complete filename. </p>
<p class="faldoc_funcdecl">fileUnit( fullpath )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">fullpath</td><td class="faldoc_paramdesc">A string containing a path. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The unit specificator part. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Returns the unit specification in a complete path. </p>
</p>
<h3 class="faldoc_funcname"><a name="filter">filter()</a></h3>
<p class="item_brief">Filters sequence using a filter function. </p>
<p class="faldoc_funcdecl">filter( ffunc, sequence )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">ffunc</td><td class="faldoc_paramdesc">A callable item used to filter the array. </td></tr><tr><td class="faldoc_param">sequence</td><td class="faldoc_paramdesc">A sequence of arbitrary items. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The filtered sequence. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">ffunc is called iteratively for every item in the collection, which is passed as a parameter to it. If the call returns true, the item is added to the returned array; if it returns false, the item is not added. </p>
<p class="faldoc_text">Items in the collection are treated literally (not evaluated). </p>
</p>
<h3 class="faldoc_funcname"><a name="fint">fint()</a></h3>
<p class="item_brief">Returns the integer part of a floating point number as a floating point number. </p>
<p class="faldoc_funcdecl">fint( x )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">x</td><td class="faldoc_paramdesc">Argument. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A floating point number with fractional part zeroed. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> Fint function works like the core <a href="./functions.html#int">int</a> function, but it returns a floating point number. For example, <b>fint</b> applied on 3.58e200 will return the same number, while <a href="./functions.html#int">int</a> would raise a math error, as the number cannot be represented in a integer number that can store numbers up to +-2^63. </p>
</p>
<h3 class="faldoc_funcname"><a name="firstOf">firstOf()</a></h3>
<p class="item_brief">Returns the first non-false of its parameters. </p>
<p class="faldoc_funcdecl">firstOf( ... )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">...</td><td class="faldoc_paramdesc">Any number of arbitrary parameters. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The first non-false item. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This function scans the paraters one at a time. Sigma evaluation is stopped, or in other words, every parameters is considered as-is, as if <a href="./functions.html#lit">lit</a> was used on each of them. The function returns the first parameter being non-false in a standard Falcon truth check. Nonzero numeric values, non empty strings, arrays and dictionaries and any object is considered true. </p>
<p class="faldoc_text">If none of the parameters is true, of is none of the parameter is given, the function returns nil (which is considered false). </p>
</p>
<h3 class="faldoc_funcname"><a name="floop">floop()</a></h3>
<p class="item_brief">Repeats indefinitely a list of operations. </p>
<p class="faldoc_funcdecl">floop( sequence )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">sequence</td><td class="faldoc_paramdesc">A sequence of callable items that gets called one after another. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> Every item in <b>sequence</b> gets executed, one after another. When the last element is executed, the first one is called again, looping indefinitely. Any function in the sequence may interrupt the loop by returning an out-of-band 0; if a function returns an out of band 1, all the remaining items in the list are ignored and the loop starts again from the first item. </p>
<p class="faldoc_text">Items in the array are not functionally evaluated. </p>
</p>
<h3 class="faldoc_funcname"><a name="floor">floor()</a></h3>
<p class="item_brief">Returns the smallest integer near to the given value. </p>
<p class="faldoc_funcdecl">floor( x )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">x</td><td class="faldoc_paramdesc">Argument. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The smallest integer near to the given value. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> Floor function returns the smallest integer near to a given floating point number. For example, floor of 1.9 is 1, and floor of -1.9 is -2. If an integer number is given, then the function returns the same number. This is similar to fint(), but in case of negative numbers <a href="./functions.html#fint">fint</a> would return the integer part; in case of -1.9 it would return -1. </p>
</p>
<h3 class="faldoc_funcname"><a name="fract">fract()</a></h3>
<p class="item_brief">Returns the fractional part of a number. </p>
<p class="faldoc_funcdecl">fract( x )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">x</td><td class="faldoc_paramdesc">Argument. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The fractional part of a number. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function returns the non-integer part of a number. For example, </p>
<pre class="faldoc_code">
> fract( 1.234 )
</pre>
<p class="faldoc_text">would print 0.234. </p>
</p>
<h3 class="faldoc_funcname"><a name="getAssert">getAssert()</a></h3>
<p class="item_brief">Returns the given assertion, if it exists. </p>
<p class="faldoc_funcdecl">getAssert( msg, [default] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">msg</td><td class="faldoc_paramdesc">The message slot on which the assertion is to be ckeched. </td></tr>
<tr><td class="faldoc_optparam">default</td><td class="faldoc_optparamdesc">If given, instead of raising in case the assertion is not found, return this item. </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_MessageError.html">MessageError</a></td><td class="faldoc_raisedesc">if the given message is not asserted. </td></tr>
</table>
</td></tr>
</table>
<h3 class="faldoc_funcname"><a name="getEnviron">getEnviron()</a></h3>
<p class="item_brief">Return a dictionary containing all the environment variables. </p>
<p class="faldoc_funcdecl">getEnviron</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A dictionary where each key is an environment variable. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">() </p>
</p>
<h3 class="faldoc_funcname"><a name="getProperty">getProperty()</a></h3>
<p class="item_brief">Returns the value of a property in an object. </p>
<p class="faldoc_funcdecl">getProperty( obj, propName )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">obj</td><td class="faldoc_paramdesc">the source object, array or (blessed) dictionary. </td></tr><tr><td class="faldoc_param">propName</td><td class="faldoc_paramdesc">A string representing the name of a property or a method inside the object. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">the property </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_AccessError.html">AccessError</a></td><td class="faldoc_raisedesc">if the property can't be found. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">An item representing the property is returned. The returned value is actually a copy of the property; assigning a new value to it won't have any effect on the original object. </p>
<p class="faldoc_text">If the property is a method, a callable method item is returned. If the property is not found, an error of class RangeError is raised. </p>
</p>
<h3 class="faldoc_funcname"><a name="getSlot">getSlot()</a></h3>
<p class="item_brief">Retreives a MOP Message slot. </p>
<p class="faldoc_funcdecl">getSlot( msg, [make] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">msg</td><td class="faldoc_paramdesc">The message slot that must be taken or created. </td></tr>
<tr><td class="faldoc_optparam">make</td><td class="faldoc_optparamdesc">If true (default) create the slot if it doesn't exist. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The message slot coresponding with this name. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="getSystemEncoding">getSystemEncoding()</a></h3>
<p class="item_brief">Returns the "official" system encoding, if it matches with one known by Falcon. </p>
<p class="faldoc_funcdecl">getSystemEncoding</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The system encoding name. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function will return the name under which Falcon knows the default system encoding. Using returned value, the program is able to create encoders that should be able to parse the data provided by system functions as directory scanning, or that is probably used as the main encoding for system related text files (i.e. configuration files). </p>
</p>
<h3 class="faldoc_funcname"><a name="getenv">getenv()</a></h3>
<p class="item_brief">Get environment variable value. </p>
<p class="faldoc_funcdecl">getenv( varName )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">varName</td><td class="faldoc_paramdesc">Environment variable name (as a string) </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The value of the environment variable or nil if it is not present. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function returns a string containing the value set for the given environment variable by the operating system before starting the Falcon process or or by a previous call to setenv(). If the given variable name is not declared, the function will return nil. </p>
<p class="faldoc_text">On some systems (e.g. MS-Windows), setting a variable to an empty string is equivalent to unsetting it, so getenv() will never return an empty string. On other systems, environment variables may be set to empty strings, that may be returned by getenv(). </p>
</p>
<h3 class="faldoc_funcname"><a name="iff">iff()</a></h3>
<p class="item_brief">Performs a functional if; if the first parameter evaluates to true, the second parameter is evaluated and then returned, else the third one is evaluated and returned. </p>
<p class="faldoc_funcdecl">iff( cfr, whenTrue, [whenFalse] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">cfr</td><td class="faldoc_paramdesc">A condition or a callable item. </td></tr><tr><td class="faldoc_param">whenTrue</td><td class="faldoc_paramdesc">Value to be called and/or returned in case cfr evaluates to true. </td></tr>
<tr><td class="faldoc_optparam">whenFalse</td><td class="faldoc_optparamdesc">Value to be called and/or returned in case cfr evaluates to false. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The evaluation result of one of the two branches (or nil). </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Basically, this function is meant to return the second parameter or the third (or nil if not given), depending on the value of the first parameter; however, every item is evaluated in a functional context. This means that cfr may be a callable item, in which case its return value will be evaluated for truthfulness, and also the other parameters may. For example: </p>
<pre class="faldoc_code">
> iff( 0, "was true", "was false" ) // will print "was false"
iff( [{a=>a*2}, 1] , [printl, "ok!"] ) // will print "ok!" and return nil
</pre>
<p class="faldoc_text">In the last example, we are not interested in the return value (printl returns nil), but in executing that item only in case the first item is true. The first item is a callable item too, so iff will first execute the given block, finding a result of 2 (true), and then will decide which element to pick, and eventually execute. Notice that: </p>
<pre class="faldoc_code">
iff( 1 , printl( "ok!" ), printl( "no" ) )
</pre>
<p class="faldoc_text">This would have forced Falcon to execute the two printl calls before entering the iff function; still, iff would have returned printl return values (which is nil in both cases). </p>
</p>
<h3 class="faldoc_funcname"><a name="include">include()</a></h3>
<p class="item_brief">Dynamically loads a module as a plugin. </p>
<p class="faldoc_funcdecl">include( file, [inputEnc], [path], [symDict] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">file</td><td class="faldoc_paramdesc">The relative filename of the module. </td></tr>
<tr><td class="faldoc_optparam">inputEnc</td><td class="faldoc_optparamdesc">Input encoding. </td></tr><tr><td class="faldoc_optparam">path</td><td class="faldoc_optparamdesc">A string of ';' separated search paths. </td></tr><tr><td class="faldoc_optparam">symDict</td><td class="faldoc_optparamdesc">Symbols to be queried (or nil). </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">if the module cannot be found or loaded. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">A module indicated by filename is compiled, loaded and linked in the running Virtual Machine. The inclusion is relative to the current path, be it set in the script, in the current embedding application or in the falcon command line interpreter. It is possible to use a path relative to the current script path by using the scriptPath variable. </p>
<p class="faldoc_text"> If a dictionary of symbols to be queried is <b>not</b> provided, the module is loaded and its main code, if present, is executed. </p>
<p class="faldoc_text"> If <b>symDict</b> is provided, its keys are strings which refer to symbol names to be searched in the loaded module. If present, the entry are filled with symbols coming from the loaded module. When <b>symDict</b> is provided, the linked module won't have its main code executed (it is possible to execute it at a later time adding "__main__" to the searched symbols). If a symbol is not found, its entry in the dictionary will be set to nil. When loaded this way, the export requests in the loaded module are <b>not</b> honored (import/from semantic). </p>
<p class="faldoc_text"> The <b>compiler</b> Feather module provides a more complete interface to dynamic load and compilation, but this minimal dynamic load support is provided at base level for flexibility. </p>
</p>
<h3 class="faldoc_funcname"><a name="input">input()</a></h3>
<p class="item_brief">Get some text from the user (standard input stream). </p>
<p class="faldoc_funcdecl">input</p>
<p class="faldoc_text"><p class="faldoc_text">Reads a line from the standard input stream and returns a string containing the read data. This is mainly meant as a test/debugging function to provide the scripts with minimal console based user input support. When in need of reading lines from the standard input, prefer the readLine() method of the input stream object. </p>
<p class="faldoc_text">This function may also be overloaded by embedders to provide the scripts with a common general purpose input function, that returns a string that the user is queried for. </p>
</p>
<h3 class="faldoc_funcname"><a name="inspect">inspect()</a></h3>
<p class="item_brief">Displays the deep contents of an item. </p>
<p class="faldoc_funcdecl">inspect( item, [depth], [maxLen], [stream] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">The item to be inspected. </td></tr>
<tr><td class="faldoc_optparam">depth</td><td class="faldoc_optparamdesc">Maximum inspect depth. </td></tr><tr><td class="faldoc_optparam">maxLen</td><td class="faldoc_optparamdesc">Limit the display size of possibly very long items as i.e. strings or membufs. </td></tr><tr><td class="faldoc_optparam">stream</td><td class="faldoc_optparamdesc">Different stream where to send the dump. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This is mainly a debugging function that prints all the available informations on the item on the auxiliary stream. This function should not be used except for testing scripts and checking what they put in arrays, dictionaries, objects, classes or simple items. </p>
<p class="faldoc_text">Output is sent to the VM auxiliary stream; for stand-alone scripts, this translates into the "standard error stream". Embedders may provide simple debugging facilities by overloading and intercepting the VM auxiliary stream and provide separate output for that. </p>
<p class="faldoc_text">This function traverses arrays and items deeply; there isn't any protection against circular references, which may cause endless loop. However, the default maximum depth is 3, which is a good depth for debugging (goes deep, but doesn't dig beyond average interesting points). Set to -1 to have infinite depth. </p>
<p class="faldoc_text"> By default, only the first 60 characters of strings and elements of membufs are displayed. You may change this default by providing a <b>maxLen</b> parameter. </p>
<p class="faldoc_text">You may create personalized inspect functions using forward bindings, like the following: </p>
<pre class="faldoc_code">
compactInspect = .[inspect depth|1 maxLen|15]
</pre>
<p class="faldoc_text">And then, you may inspect a list of item with something like: </p>
<pre class="faldoc_code">
linsp = .[ dolist _compactInspect x ]
linsp( ["hello", "world"] )
</pre>
</p>
<h3 class="faldoc_funcname"><a name="int">int()</a></h3>
<p class="item_brief">Converts the given parameter to integer. </p>
<p class="faldoc_funcdecl">int( item )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">The item to be converted </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">An integer value. </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_ParseError.html">ParseError</a></td><td class="faldoc_raisedesc">in case the given string cannot be converted to an integer. </td></tr><tr><td class="faldoc_raiseitem"><a href="./class_MathError.html">MathError</a></td><td class="faldoc_raisedesc">if a given floating point value is too large to be converted to an integer. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Integer values are just copied. Floating point values are converted to long integer; in case they are too big to be represented a RangeError is raised. Strings are converted from base 10. If the string cannot be converted, or if the value is anything else, a MathError instance is raised. </p>
</p>
<h3 class="faldoc_funcname"><a name="isBound">isBound()</a></h3>
<p class="item_brief">Determines if an item is bound or not. </p>
<p class="faldoc_funcdecl">isBound( item )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc"></td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">True if the item is bound. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="isCallable">isCallable()</a></h3>
<p class="item_brief">Determines if an item is callable. </p>
<p class="faldoc_funcdecl">isCallable( item )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">The item to be converted </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">true if the item is callable, false otheriwse. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">If the function returns true, then the call operator can be applied. If it returns false, the item is not a callable one, and trying to call it would cause an error. </p>
</p>
<h3 class="faldoc_funcname"><a name="isoob">isoob()</a></h3>
<p class="item_brief">Checks for the out-of-band status of an item. </p>
<p class="faldoc_funcdecl">isoob( item )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">The item to be checked. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">True if the item is out of band, false otherwise. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function can be used to check if a certain item is an out of band item. </p>
</p>
<h3 class="faldoc_funcname"><a name="lbind">lbind()</a></h3>
<p class="item_brief">Creates a dynamic late binding symbol. </p>
<p class="faldoc_funcdecl">lbind( name, [value] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">name</td><td class="faldoc_paramdesc">A string representing a late binding name. </td></tr>
<tr><td class="faldoc_optparam">value</td><td class="faldoc_optparamdesc">A future binding value. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A newly created late binding name. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function create a late binding item which can be used in functional sequences as if the parameter was written in the source code prefixed with the amper '&' operator. </p>
<p class="faldoc_text">The following lines are equivalent: </p>
<pre class="faldoc_code">
bound = lbind( "count" )
ctx = &count
</pre>
<p class="faldoc_text">The return value of this function, both used directly or pre-cached, can be seamlessly merged with the & operator in functional sequences. </p>
<p class="faldoc_text">For example, it is possible to write the following loop: </p>
<pre class="faldoc_code">
eval( .[
.[ times 10 &count .[
.[eval .[ printl 'Counting...' .[lbind 'count'] ] ]
]
]] )
</pre>
<p class="faldoc_text">It is also possible cache the value and use it afterwards: </p>
<pre class="faldoc_code">
x = lbind( 'count' )
eval( .[
.[ times 10 &count .[
.[ printl 'Counting...' x]
]
]] )
</pre>
<p class="faldoc_text"> The <b>value</b> parameter initializes a future (forward) binding. Future bindings are bindings with a potential value, which is applied during function calls and symbol resolution to pre-existing symbolic entities. In practice, they allow calling fucntions with named parameters. </p>
<p class="faldoc_text">When mixing forward bindings and normal parameters, forward bindings are as placed directly at the position of the parameter they refer to, and they doesn't count during parameter expansion of non-named parameters. Also, they always overwrite the positional parameters, as they are considered after all the positional parameters have been placed on their spots. </p>
<pre class="faldoc_code">
function test( par1, par2, par3 )
>> "Par1: ", par1
>> ", Par2: ", par2
> ", Par3: ", par3
end
x = lbind( "par2", "Hello" )
test( x ) // nil->par1, "Hello"->par2, nil->par3
test( x, "Yo!" ) // "Yo!"->par1, "Hello"->par2, nil->par3
test( "Yo!", x ) // as above
test( "Yo!", "Yo! again", x ) // "Hello" overwrites "Yo again"
test( x, "Yo!", "Yo! again", "end" ) // "Yo!"->par1, "Hello"->par2, "end"->par3
</pre>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> lbind is <b>not</b> an ETA function. </p>
</p>
<h3 class="faldoc_funcname"><a name="len">len()</a></h3>
<p class="item_brief">Retrieves the length of a collection </p>
<p class="faldoc_funcdecl">len( item )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">an item of any kind </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">the count of items in the sequence, or 0. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The returned value represent the "size" of the item passed as a parameter. The number is consistent with the object type: in case of a string, it represents the count of characters, in case of arrays or dictionaries it represents the number of elements, in all the other cases the returned value is 0. </p>
</p>
<h3 class="faldoc_funcname"><a name="let">let()</a></h3>
<p class="item_brief">Assigns a value to another in a functional context. </p>
<p class="faldoc_funcdecl">let( dest, source )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">dest</td><td class="faldoc_paramdesc">Destination value (passed by reference). </td></tr><tr><td class="faldoc_param">source</td><td class="faldoc_paramdesc">Source value. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The assigned (source) value. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This function assigns a literal value given in <b>source</b> into <b>dest</b>, provided dest is a late binding or is passed by referece. </p>
<p class="faldoc_text"> This function is an ETA and prevents evaluation of its first parameter. In other words, the first parameter is treadted as if passed through <a href="./functions.html#lit">lit</a>. </p>
</p>
<h3 class="faldoc_funcname"><a name="lit">lit()</a></h3>
<p class="item_brief">Return its parameter as-is </p>
<p class="faldoc_funcdecl">lit( item )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">A condition or a callable item. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The parameter unevaluated. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function is meant to interrupt functional evaluation of lists. It has the same meaning of the single quote literal ' operator of the LISP language. </p>
<p class="faldoc_text">For example, the following code will return either a callable instance of printl, which prints a "prompt" before the parameter, or a callable instance of inspect: </p>
<pre class="faldoc_code">
iff( a > 0, [lit, [printl, "val: "] ], inspect)( param )
</pre>
<p class="faldoc_text">as inspect is a callable token, but not an evaluable one, it is already returned literally; however, [printl, "val:"] would be considered an evaluable item. To take its literal value and prevent evaluation in functional context, the lit construct must be used. </p>
</p>
<h3 class="faldoc_funcname"><a name="log">log()</a></h3>
<p class="item_brief">Returns the natural logarithm of the argument. </p>
<p class="faldoc_funcdecl">log( x )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">x</td><td class="faldoc_paramdesc">Argument. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The natural logarithm of the argument. </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_MathError.html">MathError</a></td><td class="faldoc_raisedesc">If the argument is out of domain. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The function may raise an error if the value cannot be computed because of domain or overflow errors. </p>
</p>
<h3 class="faldoc_funcname"><a name="map">map()</a></h3>
<p class="item_brief">Creates a new vector of items transforming each item in the original array through the mapping function. </p>
<p class="faldoc_funcdecl">map( mfunc, sequence )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">mfunc</td><td class="faldoc_paramdesc">A function or sigma used to map the array. </td></tr><tr><td class="faldoc_param">sequence</td><td class="faldoc_paramdesc">A sequence of arbitrary items. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The parameter unevaluated. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">mfunc is called iteratively for every item in the collection; its return value is added to the mapped array. In this way it is possible to apply an uniform transformation to all the item in a collection. </p>
<p class="faldoc_text">If mfunc returns an out of band nil item, map skips the given position in the target array, actually acting also as a filter function. </p>
<p class="faldoc_text">For example: </p>
<pre class="faldoc_code">
function mapper( item )
if item < 0: return oob(nil) // discard negative items
return item ** 0.5 // perform square root
end
inspect( map( mapper, [ 100, 4, -12, 9 ]) ) // returns [10, 2, 3]
</pre>
</p>
<h3 class="faldoc_funcname"><a name="max">max()</a></h3>
<p class="item_brief">Picks the maximum value among its parameters. </p>
<p class="faldoc_funcdecl">max( ... )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">...</td><td class="faldoc_paramdesc">The items to be checked. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The greatest item in the sequence. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function performs a lexicographic majority check on each element passed as a parameter, returning the greater of them. </p>
<p class="faldoc_text"> A standard VM comparation is performed, so the standard ordering rules apply. This also means that objects overloading the <a href="./class_BOM.html#compare">BOM.compare</a> method may provide specialized ordering rules. </p>
<p class="faldoc_text">If more than one item is found equal and greater than all the others, the first one is returned. </p>
<p class="faldoc_text"> If the function is called without parameters, it returns <b>nil</b>. </p>
</p>
<h3 class="faldoc_funcname"><a name="metaclass">metaclass()</a></h3>
<p class="item_brief">Returns the metaclass associated with the given item. </p>
<p class="faldoc_funcdecl">metaclass( item )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">The item of which the metaclass must be found. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The metaclass of this item. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="min">min()</a></h3>
<p class="item_brief">Picks the minimal value among its parameters. </p>
<p class="faldoc_funcdecl">min( ... )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">...</td><td class="faldoc_paramdesc">The items to be checked. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The smallest item in the sequence. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function performs a lexicographic minority check on each element passed as a parameter, returning the smallest of them. </p>
<p class="faldoc_text"> A standard VM comparation is performed, so the standard ordering rules apply. This also means that objects overloading the <a href="./class_BOM.html#compare">BOM.compare</a> method may provide specialized ordering rules. </p>
<p class="faldoc_text">If more than one item is found equal and lesser than all the others, the first one is returned. </p>
<p class="faldoc_text"> If the function is called without parameters, it returns <b>nil</b>. </p>
</p>
<h3 class="faldoc_funcname"><a name="numeric">numeric()</a></h3>
<p class="item_brief">Converts the given parameter to numeric. </p>
<p class="faldoc_funcdecl">numeric( item )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">The item to be converted </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A numeric value. </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_ParseError.html">ParseError</a></td><td class="faldoc_raisedesc">in case the given string cannot be converted to an integer. </td></tr><tr><td class="faldoc_raiseitem"><a href="./class_MathError.html">MathError</a></td><td class="faldoc_raisedesc">if a given floating point value is too large to be converted to an integer. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Floating point values are just copied. Integer values are converted to floating point; in case of very large integers, precision may be lost. Strings are converted from base 10. If the string cannot be converted, or if the value is anything else, a MathError instance is raised. </p>
</p>
<h3 class="faldoc_funcname"><a name="oob">oob()</a></h3>
<p class="item_brief">Generates an out-of-band item. </p>
<p class="faldoc_funcdecl">oob( [item] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_optparam">item</td><td class="faldoc_optparamdesc">The item to be declared out of band. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> An oob version of the item, or an oob <b>nil</b> if no item is given. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function returns an out-of-band nil item, or if a parameter is given, an out-of-band version of that item. </p>
</p>
<h3 class="faldoc_funcname"><a name="ord">ord()</a></h3>
<p class="item_brief">Returns the numeric UNICODE ID of a given character. </p>
<p class="faldoc_funcdecl">ord( string )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">The character for which the ID is requested. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">the UNICODE value of the first element in the string. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The first character in string is taken, and it's numeric ID is returned. </p>
</p>
<h3 class="faldoc_funcname"><a name="paramCount">paramCount()</a></h3>
<p class="item_brief">Returns number of parameter that have been passed to the current function or method. </p>
<p class="faldoc_funcdecl">paramCount</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The parameter count. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The return value is the minimum value between the formal parameters declared for the current function and the number of actual parameters the caller passed. Formal parameters which are declared in the function header, but for which the caller didn't provide actual parameters, are filled with nil. </p>
</p>
<h3 class="faldoc_funcname"><a name="paramIsRef">paramIsRef()</a></h3>
<p class="item_brief">Checks whether the nth parameter has been passed by reference or not. </p>
<p class="faldoc_funcdecl">paramIsRef( number )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">number</td><td class="faldoc_paramdesc">The paramter that must be checked (zero based) </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">true if the parameter has been passed by reference, 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_AccessError.html">AccessError</a></td><td class="faldoc_raisedesc"> if <b>number</b> is out of range. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Both assigning a value to a certain parameter and using the paramSet() function will change locally the value of the parameter, but this value won't be reflected in the actual parameter that was used to call the function, unless the parameter was explicitly passed by reference. In some contexts, it may be useful to know if this is the case. </p>
<p class="faldoc_text">If the given parameter number cannot be accessed, a AccessError is raised. </p>
</p>
<h3 class="faldoc_funcname"><a name="paramSet">paramSet()</a></h3>
<p class="item_brief">Changes the nth paramter if it has been passed by reference. </p>
<p class="faldoc_funcdecl">paramSet( number, value )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">number</td><td class="faldoc_paramdesc">the paramter to be changed (zero based) </td></tr><tr><td class="faldoc_param">value</td><td class="faldoc_paramdesc">the new value for the parameter </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_AccessError.html">AccessError</a></td><td class="faldoc_raisedesc">if </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><ol>
<li>is out of range. </li>
</ol>
<p class="faldoc_text">The function is equivalent to assigning the value directly to the required parameter; of course, in this way also optional parameter may be accessed. If the required parameter was passed by reference, also the original value in the caller is changed. </p>
<p class="faldoc_text">If the given parameter number cannot be accessed, an AccessError is raised. </p>
</p>
<h3 class="faldoc_funcname"><a name="parameter">parameter()</a></h3>
<p class="item_brief">Gets the Nth parameter </p>
<p class="faldoc_funcdecl">parameter( pnum )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">pnum</td><td class="faldoc_paramdesc">The ordinal number of the paremeter, zero based </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The nth paramter (zero based) or NIL if the parameter is not given. </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_AccessError.html">AccessError</a></td><td class="faldoc_raisedesc"> if <b>pnum</b> is out of range. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function returns the required parameter, being the first one passed to the function indicated as 0, the second as 1 and so on. Both formally declared parameters and optional parameters can be accessed this way. </p>
<p class="faldoc_text">If the given parameter number cannot be accessed, a AccessError is raised. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> This function used to be called "paramNumber", and has been renamed in version 0.8.10. The function is still aliased throught the old function name for compatibility reason, but its usage is deprecated. Use <b>parameter</b> instead. </p>
</p>
<h3 class="faldoc_funcname"><a name="passvp">passvp()</a></h3>
<p class="item_brief">Returns all the undeclared parameters, or passes them to a callable item </p>
<p class="faldoc_funcdecl">passvp( [citem] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_optparam">citem</td><td class="faldoc_optparamdesc">Callable item on which to pass the parameters. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">An array containing unnamed parameters, or the return value \b citem. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function returns all the parameters passed to this function but not declared in its prototype (variable parameters) in an array. </p>
<p class="faldoc_text">If the host function doesn't receive any extra parameter, this function returns an empty array. This is useful in case the array is immediately added to a direct call. For example: </p>
<pre class="faldoc_code">
function receiver( a, b )
> "A: ", a
> "B: ", b
> "Others: ", passvp().describe()
end
receiver( "one", "two", "three", "four" )
</pre>
<p class="faldoc_text"> If <b>citem</b> is specified, the function calls citem passing all the extra parameters to it. For example: </p>
<pre class="faldoc_code">
function promptPrint( prompt )
passvp( .[printl prompt] )
end
promptPrint( "The prompt: ", "arg1", " ", "arg2" )
</pre>
</p>
<h3 class="faldoc_funcname"><a name="permutations">permutations()</a></h3>
<p class="item_brief">Returns the permutation of the arguments. </p>
<p class="faldoc_funcdecl">permutations( x, y )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">x</td><td class="faldoc_paramdesc">First argument. </td></tr><tr><td class="faldoc_param">y</td><td class="faldoc_paramdesc">Second arguments. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The permutation of the arguments. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The return value is expressed as a floating point value. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> For high values of <b>x</b>, the function may require exponential computational time and power. </p>
</p>
<h3 class="faldoc_funcname"><a name="pow">pow()</a></h3>
<p class="item_brief">Returns the first argument elevated to the second one (x^y) </p>
<p class="faldoc_funcdecl">pow( x, y )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">x</td><td class="faldoc_paramdesc">Base. </td></tr><tr><td class="faldoc_param">y</td><td class="faldoc_paramdesc">Exponent. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">x^y </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_MathError.html">MathError</a></td><td class="faldoc_raisedesc">If the argument is out of domain. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The function may raise an error if the value cannot be computed because of domain or overflow errors. </p>
</p>
<h3 class="faldoc_funcname"><a name="print">print()</a></h3>
<p class="item_brief">Prints the contents of various items to the standard output stream. </p>
<p class="faldoc_funcdecl">print( ... )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">...</td><td class="faldoc_paramdesc">An arbitrary list of parameters. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function is the default way for a script to say something to the outer world. Scripts can expect print to do a consistent thing with respect to the environment they work in; stand alone scripts will have the printed data to be represented on the VM output stream. The stream can be overloaded to provide application supported output; by default it just passes any write to the process output stream. </p>
<p class="faldoc_text"> The items passed to print are just printed one after another, with no separation. After print return, the standard output stream is flushed and the cursor (if present) is moved past the last character printed. The function <a href="./functions.html#printl">printl</a> must be used, or a newline character must be explicitly placed among the output items. </p>
<p class="faldoc_text">The print function has no support for pretty print (i.e. numeric formatting, space padding and so on). Also, it does NOT automatically call the toString() method of objects. </p>
</p>
<h3 class="faldoc_funcname"><a name="printl">printl()</a></h3>
<p class="item_brief">Prints the contents of various items to the VM standard output stream, and adds a newline. </p>
<p class="faldoc_funcdecl">printl( ... )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">...</td><td class="faldoc_paramdesc">An arbitrary list of parameters. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This functions works exactly as <a href="./functions.html#print">print</a>, but it adds a textual "new line" after all the items are printed. The actual character sequence may vary depending on the underlying system. </p>
</p>
<h3 class="faldoc_funcname"><a name="properties">properties()</a></h3>
<p class="item_brief">Returns all the properties in the given item. </p>
<p class="faldoc_funcdecl">properties( item )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">An item that can be accessed via dot accessor. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">An array of strings representing property names. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function returns the properties offered by an item as a list of strings in an array. FBOM methods (item metaclass methods) are not returned; only explicitly declared properties are taken into account. </p>
<p class="faldoc_text">The item susceptible of returning an array of properties are: </p>
<ul>
<li> Objects (see <a href="./class_Object.html#properties">Object.properties</a>) </li><li> Dictionaries (if blessed, see <a href="./class_Dictionary.html#properties">Dictionary.properties</a>) </li><li> Arrays (see <a href="./class_Array.html#properties">Array.properties</a>) </li><li> Classes (see <a href="./class_Class.html#properties">Class.properties</a>) </li>
</ul>
<p class="faldoc_text"> This function, applied to any other item type, returns <b>nil</b>. </p>
</p>
<h3 class="faldoc_funcname"><a name="rad2deg">rad2deg()</a></h3>
<p class="item_brief">Converts an angle expressed in radians into degrees. </p>
<p class="faldoc_funcdecl">rad2deg( x )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">x</td><td class="faldoc_paramdesc">An angle expressed in radians. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The angle converted in degrees. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="random">random()</a></h3>
<p class="item_brief">Returns a pseudo random number. </p>
<p class="faldoc_funcdecl">random( ... )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">...</td><td class="faldoc_paramdesc">See below. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A pseudo random number or a random item picked from parameters. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function has actually several functionalities that are selected depending on the parameters. </p>
<p class="faldoc_text">Without parameters, the function returns a floating point number in the range [0,1). </p>
<p class="faldoc_text">With a signle numeric parameter, the function returns an integer between 0 and the number, included. The following functions are equivalent: </p>
<pre class="faldoc_code">
> random( x )
> int( random() * (x + 1) )
</pre>
<p class="faldoc_text">With two numeric parameters, the function returns an integer in the range [x, y]. The following functions are equivalent: </p>
<pre class="faldoc_code">
> random( x, y )
> int( x + (random() * (y + 1)) )
</pre>
<p class="faldoc_text">With more than two parameters, or when at least one of the first two parameters it not a number, one of the parameter is picked at random and then returned. </p>
<p class="faldoc_text"> The function <a href="./functions.html#randomChoice">randomChoice</a> returns unambiguously one of the parameters picked at random. </p>
</p>
<h3 class="faldoc_funcname"><a name="randomChoice">randomChoice()</a></h3>
<p class="item_brief">Selects one of the arguments at random and returns it. </p>
<p class="faldoc_funcdecl">randomChoice( ... )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">...</td><td class="faldoc_paramdesc">At least two items of any kind. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">One of the parameters, picked at random. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This function works as <a href="./functions.html#random">random</a> when it receives more than two parameters, but its usage is not ambiguous in case there are two items from which to choice. The function raises an error if less than two parameters are passed. </p>
</p>
<h3 class="faldoc_funcname"><a name="randomDice">randomDice()</a></h3>
<p class="item_brief">Performs a virtual dice set trow. </p>
<p class="faldoc_funcdecl">randomDice( dices, [sides] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">dices</td><td class="faldoc_paramdesc">Number of dices to be thrown. </td></tr>
<tr><td class="faldoc_optparam">sides</td><td class="faldoc_optparamdesc">Number of faces in the virtual dices. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A random value which is the sum of the virtual throws. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This function generates a series of successive <b>dices</b> throws, each one being integer value in the range [1, <b>sides</b>]. </p>
<p class="faldoc_text"> If <b>sides</b> is not given, 6 is assumed. </p>
<p class="faldoc_text">It would be easy to obtain the same result with simple instructions in Falcon, but this function spares several wasted VM cycles. </p>
<p class="faldoc_text"> The <b>dices</b> parameter must be greater than zero, and the and <b>sides</b> parameter must be greater than one. </p>
</p>
<h3 class="faldoc_funcname"><a name="randomGrab">randomGrab()</a></h3>
<p class="item_brief">Grabs repeatedly random elements from an array. </p>
<p class="faldoc_funcdecl">randomGrab( series, [size] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">series</td><td class="faldoc_paramdesc">An array from which items will be extracted. </td></tr>
<tr><td class="faldoc_optparam">size</td><td class="faldoc_optparamdesc">Count of extracted items. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">An array with some or all of the items grabbed from the original elements. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function extracts a desired amount of items from the elements array, putting them in a new array that will be returned. Items left in the elements array have a fair chance to be selected and removed at every step. If the size parameter is greater or equal than the size of the elements array, the array is eventually emptied and all the items are moved to the new array, actually performing a complete fair shuffling of the original. </p>
<p class="faldoc_text"> If <b>size</b> is not given, 1 is assumed; if it's zero or less than zero, then all the elements in the <b>series</b> array will be taken. </p>
<p class="faldoc_text">This function is suitable to emulate card shuffling or other random extraction events. </p>
</p>
<h3 class="faldoc_funcname"><a name="randomPick">randomPick()</a></h3>
<p class="item_brief">Grabs repeatedly random elements from an array. </p>
<p class="faldoc_funcdecl">randomPick( series )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">series</td><td class="faldoc_paramdesc">An array containing one or more items. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">One of the items in the array. </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_ParamError.html">ParamError</a></td><td class="faldoc_raisedesc"> if the <b>series</b> is empty. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This function choices one of the items contained in the <b>series</b> array at random. </p>
<p class="faldoc_text">If the array is empty, a ParamError error is raised. </p>
</p>
<h3 class="faldoc_funcname"><a name="randomSeed">randomSeed()</a></h3>
<p class="item_brief">Seeds the random number generator. </p>
<p class="faldoc_funcdecl">randomSeed( [seed] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_optparam">seed</td><td class="faldoc_optparamdesc">An integer number being used as random seed. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The random seed should be set once per program, possibly using a number that is likely to vary greatly among different executions. A good seed may be the return of the seconds() function, eventually multiplied by 1000 to make the milliseconds to take part in the seeding. If called without parameters, a number based on the current system timer value will be used. </p>
<p class="faldoc_text">Repeated calls to random(), and calls based on random function as randomChoice, randomPick and so on, will produce the same sequences if randomSeed() is called with the same seed. </p>
<p class="faldoc_text">Using a constant number as random seed may be a good strategy to produce predictable debug sequences. </p>
</p>
<h3 class="faldoc_funcname"><a name="randomWalk">randomWalk()</a></h3>
<p class="item_brief">Performs a random walk in an array. </p>
<p class="faldoc_funcdecl">randomWalk( series, [size] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">series</td><td class="faldoc_paramdesc">An array containing one or more items. </td></tr>
<tr><td class="faldoc_optparam">size</td><td class="faldoc_optparamdesc">Desire size of the walk. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">An array built from randomly picked items. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function picks one or more elements from the given array, and stores them in a new array without removing them from the old one. Elements can be picked up repeatedly, and the size of the target array may be larger than the size of the original one. </p>
<p class="faldoc_text">If the requested target size is zero, or if the original array is empty, an empty array is returned. </p>
<p class="faldoc_text"> If <b>size</b> is not given, 1 is assumed; if it's less than zero, then an the function will create an array of the same size of the <b>series</b> array, but the target array can contain multiple copies of the items in <b>series</b>, or it may be missing some of them. </p>
</p>
<h3 class="faldoc_funcname"><a name="readURI">readURI()</a></h3>
<p class="item_brief">Reads fully data from a given file or URI source. </p>
<p class="faldoc_funcdecl">readURI( uri, [encoding] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">uri</td><td class="faldoc_paramdesc">The item to be read (URI or string) </td></tr>
<tr><td class="faldoc_optparam">encoding</td><td class="faldoc_optparamdesc">The encoding. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A string containing the whole contents of the given file. </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">in case of read error. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function reads as efficiently as possible a file from the given source. If encoding isn't given, the file is read as binary data. </p>
<p class="faldoc_text">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_note"><span class="faldoc_notetype">Note:</span> The maximum size of the data that can be read is limited to 2 Gigabytes. </p>
</p>
<h3 class="faldoc_funcname"><a name="reduce">reduce()</a></h3>
<p class="item_brief">Uses the values in a given sequence and iteratively calls a reductor function to extract a single result. </p>
<p class="faldoc_funcdecl">reduce( reductor, sequence, [initial_value] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">reductor</td><td class="faldoc_paramdesc">A function or Sigma to reduce the array. </td></tr><tr><td class="faldoc_param">sequence</td><td class="faldoc_paramdesc">A sequence of arbitrary items. </td></tr>
<tr><td class="faldoc_optparam">initial_value</td><td class="faldoc_optparamdesc">Optional startup value for the reduction. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The reduced result. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The reductor is a function receiving two values as parameters. The first value is the previous value returned by the reductor, while the second one is an item iteratively taken from the origin array. If a startup value is given, the first time the reductor is called that value is provided as its first parameter, otherwise the first two items from the array are used in the first call. If the collection is empty, the initial_value is returned instead, and if is not given, nil is returned. If a startup value is not given and the collection contains only one element, that element is returned. </p>
<p class="faldoc_text">Some examples: </p>
<pre class="faldoc_code">
> reduce( {a,b=> a+b}, [1,2,3,4]) // sums 1 + 2 + 3 + 4 = 10
> reduce( {a,b=> a+b}, [1,2,3,4], -1 ) // sums -1 + 1 + 2 + 3 + 4 = 9
> reduce( {a,b=> a+b}, [1] ) // never calls lambda, returns 1
> reduce( {a,b=> a+b}, [], 0 ) // never calls lambda, returns 0
> reduce( {a,b=> a+b}, [] ) // never calls lambda, returns Nil
</pre>
<p class="faldoc_text">Items in the collection are treated literally (not evaluated). </p>
</p>
<h3 class="faldoc_funcname"><a name="retract">retract()</a></h3>
<p class="item_brief">Removes a previous assertion on a message. </p>
<p class="faldoc_funcdecl">retract( msg )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">msg</td><td class="faldoc_paramdesc">The message slot to be retracted. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="round">round()</a></h3>
<p class="item_brief">Rounds a floating point to the nearest integer. </p>
<p class="faldoc_funcdecl">round( x )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">x</td><td class="faldoc_paramdesc">Argument. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">Nearest integer to x. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Round returns the nearest integer value of a given floating point number. If the fractional part of the number is greater or equal to 0.5, the number is rounded up to the nearest biggest integer in absolute value, while if it's less than 0.5 the number is rounded down to the mere integer part. For example, 1.6 is rounded to 2, -1.6 is rounded to -2, 1.2 is rounded to 1 and -1.2 is rounded to -1. </p>
</p>
<h3 class="faldoc_funcname"><a name="seconds">seconds()</a></h3>
<p class="item_brief">Returns the number of seconds since the "epoch" as reported by the system. </p>
<p class="faldoc_funcdecl">seconds</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The number of seconds and fractions of seconds in a floating point value. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Actually, this function returns a floating point number which represents seconds and fraction of seconds elapse since a conventional time. This function is mainly meant to be used to take intervals of time inside the script, with a millisecond precision. </p>
</p>
<h3 class="faldoc_funcname"><a name="serialize">serialize()</a></h3>
<p class="item_brief">Serializes an item on a stream. </p>
<p class="faldoc_funcdecl">serialize( item, stream )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">The item to be serialized. </td></tr><tr><td class="faldoc_param">stream</td><td class="faldoc_paramdesc">An instance of the Stream (or derived) class. </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 underlying stream error. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The item is stored on the stream so that a deserialize() call on the same position in the stream where serialization took place will create an exact copy of the serialized item. </p>
<p class="faldoc_text">The application must ensure that the item does not contains circular references, or the serialization will enter an endless loop. </p>
<p class="faldoc_text">In case the underlying stream write causes an i/o failure, an error is raised. </p>
<p class="faldoc_text"> The BOM method <a href="./class_BOM.html#serialize">BOM.serialize</a> is available for all the Falcon items, and is equivalent to call this function. </p>
</p>
<h3 class="faldoc_funcname"><a name="set">set()</a></h3>
<p class="item_brief">Stores a value in a dictionary </p>
<p class="faldoc_funcdecl">set( key, value )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">key</td><td class="faldoc_paramdesc">The key to be found. </td></tr><tr><td class="faldoc_param">value</td><td class="faldoc_paramdesc">The key to be set. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">True if the value was overwritten, false if it has been inserted anew. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Dictionary </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> This method bypassess setIndex__ override in blessed (POOP) dictionaries. </p>
</p>
<h3 class="faldoc_funcname"><a name="setProperty">setProperty()</a></h3>
<p class="item_brief">Sets the value of a proprety in a given object </p>
<p class="faldoc_funcdecl">setProperty( obj, propName, value )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">obj</td><td class="faldoc_paramdesc">The source object. </td></tr><tr><td class="faldoc_param">propName</td><td class="faldoc_paramdesc">A string representing the name of a property or a method inside the object. </td></tr><tr><td class="faldoc_param">value</td><td class="faldoc_paramdesc">The property new value. </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_AccessError.html">AccessError</a></td><td class="faldoc_raisedesc">If the property can't be found. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Alters the value of the property in the given object. If the required property is not present, an AccessError is raised. </p>
</p>
<h3 class="faldoc_funcname"><a name="setenv">setenv()</a></h3>
<p class="item_brief">Set environment variable value. </p>
<p class="faldoc_funcdecl">setenv( varName, value )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">varName</td><td class="faldoc_paramdesc">Environment variable name (as a string) </td></tr><tr><td class="faldoc_param">value</td><td class="faldoc_paramdesc">a value for the given variable. </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 failure. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function sets the given value for the given environment variable. The varName parameter must be a string, while value may be any Falcon value. If the value is not a string, it will be converted using the toString() function. </p>
<p class="faldoc_text">If the variable was previously set to a different value, its value is changed; if it doesn't existed, it is created. </p>
<p class="faldoc_text">The function may fail if the system cannot perform the operation; this may happen if the space that the system reserves for environment variables is exhausted. In this case, the function raises an error. </p>
</p>
<h3 class="faldoc_funcname"><a name="sin">sin()</a></h3>
<p class="item_brief">Returns the sine of the argument. </p>
<p class="faldoc_funcdecl">sin( x )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">x</td><td class="faldoc_paramdesc">Argument. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The sine of the argument. </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_MathError.html">MathError</a></td><td class="faldoc_raisedesc">If the argument is out of domain. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The return value is expressed in radians. </p>
<p class="faldoc_text">The function may raise an error if the value cannot be computed because of domain or overflow errors. </p>
</p>
<h3 class="faldoc_funcname"><a name="sleep">sleep()</a></h3>
<p class="item_brief">Put the current coroutine at sleep for some time. </p>
<p class="faldoc_funcdecl">sleep( time )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">time</td><td class="faldoc_paramdesc">Time, in seconds and fractions, that the coroutine wishes to sleep. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">an item posted by the embedding application. </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_InterruptedError.html">InterruptedError</a></td><td class="faldoc_raisedesc">in case of asynchronous interruption. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function declares that the current coroutines is not willing to proceed at least for the given time. The VM will swap out the coroutine until the time has elapsed, and will make it eligible to run again after the given time lapse. </p>
<p class="faldoc_text">The parameter may be a floating point number if a pause shorter than a second is required. </p>
<p class="faldoc_text"> The <b>sleep</b>() function can be called also when the VM has not started any coroutine; this will make it to be idle for the required time. </p>
<p class="faldoc_text">In embedding applications, the Virtual Machine can be instructed to detect needed idle time and return to the calling application instead of performing a system request to sleep. In this way, embedding applications can use the idle time of the virtual machine to perform background operations. Single threaded applications may continue their execution and schedule continuation of the Virtual Machine at a later time, and multi-threaded applications can perform background message processing. </p>
<p class="faldoc_text"> This function complies with the interrupt protocol. The Virtual Machine may be asynchronously interrupted from the outside (i.e. from another thread). In this case, <b>sleep</b> will immediately raise an <a href="./class_InterruptedError.html">InterruptedError</a> instance. The script may just ignore this exception and let the VM to terminate immediately, or it may honor the request after a cleanup it provides in a <b>catch</b> block, or it may simply ignore the request and continue the execution by discarding the error through an appropriate <b>catch</b> block. </p>
</p>
<h3 class="faldoc_funcname"><a name="stdErr">stdErr()</a></h3>
<p class="item_brief">Creates an object mapped to the standard error of the Virtual Machine. </p>
<p class="faldoc_funcdecl">stdErr</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> A new valid <a href="./class_Stream.html">Stream</a> instance on success. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The returned stream maps output operations on the standard error stream of the virtual machine hosting the script. </p>
<p class="faldoc_text">The returned stream is a clone of the stream used by the Virtual Machine as standard error stream. This means that every transcoding applied by the VM is also available to the script, and that, when running in embedding applications, the stream will be handled by the embedder. </p>
<p class="faldoc_text">As a clone of this stream is held in the VM, closing it will have actually no effect, except that of invalidating the instance returned by this function. </p>
<p class="faldoc_text">Read operations will fail raising an I/O error. </p>
</p>
<h3 class="faldoc_funcname"><a name="stdErrRaw">stdErrRaw()</a></h3>
<p class="item_brief">Creates a stream that interfaces the standard error stream of the host process. </p>
<p class="faldoc_funcdecl">stdErrRaw</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> A new valid <a href="./class_Stream.html">Stream</a> instance on success. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> The returned stream maps output operations on the standard error stream of the process hosting the script. The returned stream is bound directly with the process error stream, without any automatic transcoding applied. <a href="./class_Stream.html#writeText">Stream.writeText</a> will write the text as stream of bytes to the stream, unless <a href="./class_Stream.html#setEncoding">Stream.setEncoding</a> is explicitly called on the returned instance. </p>
<p class="faldoc_text">Closing this stream has the effect to close the standard error stream of the process running the script (if the operation is allowed by the embedding application). Applications reading from the error stream of the script will be notified that the stream has been closed, and won't be left pending in reading this stream. </p>
<p class="faldoc_text">The stream is write only. Read operations will cause an I/O to be raised. </p>
</p>
<h3 class="faldoc_funcname"><a name="stdIn">stdIn()</a></h3>
<p class="item_brief">Creates an object mapped to the standard input of the Virtual Machine. </p>
<p class="faldoc_funcdecl">stdIn</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> A new valid <a href="./class_Stream.html">Stream</a> instance on success. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The returned read-only stream is mapped to the standard input of the virtual machine hosting the script. Read operations will return the characters from the input stream as they are available. The readAvailable() method of the returned stream will indicate if read operations may block. Calling the read() method will block until some character can be read, or will fill the given buffer up the amount of currently available characters. </p>
<p class="faldoc_text">The returned stream is a clone of the stream used by the Virtual Machine as standard input stream. This means that every transcoding applied by the VM is also available to the script, and that, when running in embedding applications, the stream will be handled by the embedder. </p>
<p class="faldoc_text">As a clone of this stream is held in the VM, closing it will have actually no effect, except that of invalidating the instance returned by this function. </p>
<p class="faldoc_text">Read operations will fail raising an I/O error. </p>
</p>
<h3 class="faldoc_funcname"><a name="stdInRaw">stdInRaw()</a></h3>
<p class="item_brief">Creates a stream that interfaces the standard input stream of the host process. </p>
<p class="faldoc_funcdecl">stdInRaw</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> A new valid <a href="./class_Stream.html">Stream</a> instance on success. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> The returned stream maps input operations on the standard input of the process hosting the script. The returned stream is bound directly with the process input stream, without any automatic transcoding applied. <a href="./class_Stream.html#readText">Stream.readText</a> will read the text as stream of binary data coming from the stream, unless <a href="./class_Stream.html#setEncoding">Stream.setEncoding</a> is explicitly called on the returned instance. </p>
<p class="faldoc_text">Closing this stream has the effect to close the standard input stream of the process running the script (if the operation is allowed by the embedding application). Applications trying to write data to the script process will be notified that the script has closed the stream and is not willing to receive data anymore. </p>
<p class="faldoc_text">The stream is read only. Write operations will cause an I/O to be raised. </p>
</p>
<h3 class="faldoc_funcname"><a name="stdOut">stdOut()</a></h3>
<p class="item_brief">Creates an object mapped to the standard output of the Virtual Machine. </p>
<p class="faldoc_funcdecl">stdOut</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> A new valid <a href="./class_Stream.html">Stream</a> instance on success. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The returned stream maps output operations on the standard output stream of the process hosting the script. </p>
<p class="faldoc_text">The returned stream is a clone of the stream used by the Virtual Machine as standard output stream. This means that every transcoding applied by the VM is also available to the script, and that, when running in embedding applications, the stream will be handled by the embedder. </p>
<p class="faldoc_text">As a clone of this stream is held in the VM, closing it will have actually no effect, except that of invalidating the instance returned by this function. </p>
<p class="faldoc_text">Read operations will fail raising an I/O error. </p>
</p>
<h3 class="faldoc_funcname"><a name="stdOutRaw">stdOutRaw()</a></h3>
<p class="item_brief">Creates a stream that interfaces the standard output stream of the host process. </p>
<p class="faldoc_funcdecl">stdOutRaw</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> A new valid <a href="./class_Stream.html">Stream</a> instance on success. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> The returned stream maps output operations on the standard output stream of the process hosting the script. The returned stream is bound directly with the process output, without any automatic transcoding applied. <a href="./class_Stream.html#writeText">Stream.writeText</a> will write the text as stream of bytes to the stream, unless <a href="./class_Stream.html#setEncoding">Stream.setEncoding</a> is explicitly called on the returned instance. </p>
<p class="faldoc_text">Closing this stream has the effect to close the standard output of the process running the script (if the operation is allowed by the embedding application). Print functions, fast print operations, default error reporting and so on will be unavailable from this point on. </p>
<p class="faldoc_text">Applications reading from the output stream of the process running the scripts, in example, piped applications, will recognize that the script has completed its output, and will disconnect immediately, while the script may continue to run. </p>
<p class="faldoc_text">The stream is write only. Read operations will cause an IoError to be raised. </p>
</p>
<h3 class="faldoc_funcname"><a name="strBack">strBack()</a></h3>
<p class="item_brief">Returns the last character(s) in a string. </p>
<p class="faldoc_funcdecl">strBack( str, [count], [remove], [numeric] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">str</td><td class="faldoc_paramdesc">The string on which to operate. </td></tr>
<tr><td class="faldoc_optparam">count</td><td class="faldoc_optparamdesc">Number of characters to be taken (defaults to 1). </td></tr><tr><td class="faldoc_optparam">remove</td><td class="faldoc_optparamdesc">If true, remove also the character. </td></tr><tr><td class="faldoc_optparam">numeric</td><td class="faldoc_optparamdesc">If true, returns a character value instead of a string. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The first element or nil if the string is empty. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This function returns a string containing one character from the end of <b>str</b>, or eventually more characters in case a number > 1 is specified in <b>count</b>. </p>
<p class="faldoc_text"> If <b>remove</b> is true, then the characters are removed and the string is shrinked. </p>
<p class="faldoc_text"> If <b>numeric</b> is true, the UNICODE value of the string character will be returned, otherwise the caller will receive a string containing the desired character. In this case, <b>count</b> parameter will be ignored and only one UNICODE value will be returned. </p>
</p>
<h3 class="faldoc_funcname"><a name="strBackFind">strBackFind()</a></h3>
<p class="item_brief">Finds a substring bakwards. </p>
<p class="faldoc_funcdecl">strBackFind( string, needle, [start], [end] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">String where the search will take place. </td></tr><tr><td class="faldoc_param">needle</td><td class="faldoc_paramdesc">Substring to search for. </td></tr>
<tr><td class="faldoc_optparam">start</td><td class="faldoc_optparamdesc">Optional position from which to start the search in string. </td></tr><tr><td class="faldoc_optparam">end</td><td class="faldoc_optparamdesc">Optional position at which to end the search in string. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The position where the substring is found, or -1. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> Works exactly as <a href="./functions.html#strFind">strFind</a>, except for the fact that the last match in the string (or in the specified interval) is returned. </p>
</p>
<h3 class="faldoc_funcname"><a name="strBackTrim">strBackTrim()</a></h3>
<p class="item_brief">Removes white spaces at both the beginning and the end of the string. </p>
<p class="faldoc_funcdecl">strBackTrim( string, [trimSet] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">The string to be trimmed. </td></tr>
<tr><td class="faldoc_optparam">trimSet</td><td class="faldoc_optparamdesc">A set of characters that must be removed. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The trimmed substring. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> A new string, which is a copy of the original one with all characters in <b>trimSet</b> at the beginning and at the end of the string removed, is returned. If <b>trimSet</b> is not supplied, it defaults to space, tabulation characters, new lines and carriage returns. The original string is unmodified. </p>
</p>
<h3 class="faldoc_funcname"><a name="strBuffer">strBuffer()</a></h3>
<p class="item_brief">Pre-allocates an empty string. </p>
<p class="faldoc_funcdecl">strBuffer( size )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">size</td><td class="faldoc_paramdesc">Size of the pre-allocated string. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The new string. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The returned string is an empty string, and equals to "". However, the required size is pre-allocated, and addition to this string (i.e. += operators) takes place in a fraction of the time otherwise required, up tho the filling of the pre-allocated buffer. Also, this string can be fed into file functions, the pre-allocation size being used as the input read size. </p>
</p>
<h3 class="faldoc_funcname"><a name="strCmpIgnoreCase">strCmpIgnoreCase()</a></h3>
<p class="item_brief">Performs a lexicographic comparation of two strings, ignoring character case. </p>
<p class="faldoc_funcdecl">strCmpIgnoreCase( string1, string2 )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string1</td><td class="faldoc_paramdesc">First string to be compared. </td></tr><tr><td class="faldoc_param">string2</td><td class="faldoc_paramdesc">Second string to be compared. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">-1, 0 or 1. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The two strings are compared ignoring the case of latin characters contained in the strings. </p>
<p class="faldoc_text">If the first string is greater than the second, the function returns a number less than 0. If it's smaller, it returns a positive number. If the two strings are the same, ignoring the case of the characters, 0 is returned. </p>
</p>
<h3 class="faldoc_funcname"><a name="strEndsWith">strEndsWith()</a></h3>
<p class="item_brief">Check if a strings ends with a substring. </p>
<p class="faldoc_funcdecl">strEndsWith( string, token, [icase] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">The string that is going to be tested for the given token. </td></tr><tr><td class="faldoc_param">token</td><td class="faldoc_paramdesc">The substring that will be compared with this string. </td></tr>
<tr><td class="faldoc_optparam">icase</td><td class="faldoc_optparamdesc">If true, pefroms a case neutral check </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> True if <b>token</b> matches the end of <b>string</b>, false otherwise. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This functioin performs a comparation check at the end of the <b>string</b>. If this string ends with <b>token</b>, the function returns true. If <b>token</b> is larger than the string, the function will always return false, and if <b>token</b> is an empty string, it will always match. </p>
<p class="faldoc_text"> The optional parameter <b>icase</b> can be provided as true to have this function to perform a case insensitive match. </p>
</p>
<h3 class="faldoc_funcname"><a name="strEscape">strEscape()</a></h3>
<p class="item_brief">Escape quotes and special characters in the string </p>
<p class="faldoc_funcdecl">strEscape( string, [full] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">the String to be escaped. </td></tr>
<tr><td class="faldoc_optparam">full</td><td class="faldoc_optparamdesc">If true, characters above UNICODE 127 are escaped as well. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A new escaped string. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="strEsq">strEsq()</a></h3>
<p class="item_brief">Escape quotes in the given string. </p>
<p class="faldoc_funcdecl">strEsq( string, [inplace] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">the String to be escaped. </td></tr>
<tr><td class="faldoc_optparam">inplace</td><td class="faldoc_optparamdesc">if true, the source string is modified, saving memory. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> A new escaped string, if <b>inplace</b> is not given, or the <b>string</b> parameter if <b>inplace</b> is true. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="strFill">strFill()</a></h3>
<p class="item_brief">Fills a string with a given character or substring. </p>
<p class="faldoc_funcdecl">strFill( string, chr )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">The string to be filled. </td></tr><tr><td class="faldoc_param">chr</td><td class="faldoc_paramdesc"> The character (unicode value) or substring used to refill the <b>string</b>. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The string itself. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function fills the physical storage of the given string with a single character or a repeated substring. This can be useful to clean a string used repeatedly as input buffer. </p>
<p class="faldoc_text">The function returns the same string that has been passed as the parameter. </p>
</p>
<h3 class="faldoc_funcname"><a name="strFind">strFind()</a></h3>
<p class="item_brief">Finds a substring. </p>
<p class="faldoc_funcdecl">strFind( string, needle, [start], [end] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">String where the search will take place. </td></tr><tr><td class="faldoc_param">needle</td><td class="faldoc_paramdesc">Substring to search for. </td></tr>
<tr><td class="faldoc_optparam">start</td><td class="faldoc_optparamdesc">Optional position from which to start the search in string. </td></tr><tr><td class="faldoc_optparam">end</td><td class="faldoc_optparamdesc">Optional position at which to end the search in string. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The position where the substring is found, or -1. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Returns the index in string were needle begins, or -1 if not present. Giving a start parameter will cause the search to start from the given position up to the end of the string; if a match can be made at start position, then the the returned value will be the same as start, so when repeating searches in a string for all the possible matches, repeat until the result is -1 by adding one to the returned value and using it as start position for the next search. </p>
<p class="faldoc_text">If an end position is given, it is used as upper limit for the search, so that the search is in the interval [start, end-1]. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> This function is equivalent to the fbom method String.find </p>
</p>
<h3 class="faldoc_funcname"><a name="strFromMemBuf">strFromMemBuf()</a></h3>
<p class="item_brief">Convets a MemBuf to a string. </p>
<p class="faldoc_funcdecl">strFromMemBuf( membuf )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">membuf</td><td class="faldoc_paramdesc">A MemBuf that will be converted to a string. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The resulting string. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This string takes each element of the membuf and converts it into a character in the final string. The contents of the buffer are not transcoded. It is appropriate to say that this function considers each element in the MemBuf as an Unicode value for the character in the final string. </p>
<p class="faldoc_text">To create a string from a buffer that may come from an encoded source (i.e. a file), use directly Transcode functions. </p>
</p>
<h3 class="faldoc_funcname"><a name="strFront">strFront()</a></h3>
<p class="item_brief">Returns the first character in a string. </p>
<p class="faldoc_funcdecl">strFront( str, [count], [remove], [numeric] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">str</td><td class="faldoc_paramdesc">The string on which to operate. </td></tr>
<tr><td class="faldoc_optparam">count</td><td class="faldoc_optparamdesc">Number of characters to be taken (defaults to 1). </td></tr><tr><td class="faldoc_optparam">remove</td><td class="faldoc_optparamdesc">If true, remove also the character. </td></tr><tr><td class="faldoc_optparam">numeric</td><td class="faldoc_optparamdesc">If true, returns a character value instead of a string. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The first element or nil if the string is empty. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This function returns a string containing one character from the beginning of <b>str</b>, or eventually more characters in case a number > 1 is specified in <b>count</b>. </p>
<p class="faldoc_text"> If <b>remove</b> is true, then the character is removed and the string is shrinked. </p>
<p class="faldoc_text"> If <b>numeric</b> is true, the UNICODE value of the string character will be returned, otherwise the caller will receive a string containing the desired character. In this case, <b>count</b> parameter will be ignored and only one UNICODE value will be returned. </p>
</p>
<h3 class="faldoc_funcname"><a name="strFrontTrim">strFrontTrim()</a></h3>
<p class="item_brief">Removes white spaces from the front of the string. </p>
<p class="faldoc_funcdecl">strFrontTrim( string, [trimSet] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">The string to be trimmed. </td></tr>
<tr><td class="faldoc_optparam">trimSet</td><td class="faldoc_optparamdesc">A set of characters that must be removed. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The trimmed substring. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> A new string, which is a copy of the original one with all characters in <b>trimSet</b> at the beginning of the string removed, is returned. If <b>trimSet</b> is not supplied, it defaults to space, tabulation characters, new lines and carriage returns. The original string is unmodified. </p>
</p>
<h3 class="faldoc_funcname"><a name="strLower">strLower()</a></h3>
<p class="item_brief">Returns a lowercase version of the given string. </p>
<p class="faldoc_funcdecl">strLower( string )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">String that must be lowercased. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The lowercased string. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">All the Latin characters in the string are turned lowercase. Other characters are left untouched. </p>
</p>
<h3 class="faldoc_funcname"><a name="strMerge">strMerge()</a></h3>
<p class="item_brief">Merges an array of strings into a string. </p>
<p class="faldoc_funcdecl">strMerge( array, [mergeStr], [count] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">array</td><td class="faldoc_paramdesc">An array of strings to be merged. </td></tr>
<tr><td class="faldoc_optparam">mergeStr</td><td class="faldoc_optparamdesc">A string placed between each merge. </td></tr><tr><td class="faldoc_optparam">count</td><td class="faldoc_optparamdesc">Maximum count of merges. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The merged string. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The function will return a new string containing the concatenation of the strings inside the array parameter. If the array is empty, an empty string is returned. If a mergeStr parameter is given, it is added to each pair of string merged; mergeStr is never added at the end of the new string. A count parameter may be specified to limit the number of elements merged in the array. </p>
<p class="faldoc_text">The function may be used in this way: </p>
<pre class="faldoc_code">
a = strMerge( [ "a", "string", "of", "words" ], " " )
printl( a ) // prints "a string of words"
</pre>
<p class="faldoc_text">If an element of the array is not a string, an error is raised. </p>
</p>
<h3 class="faldoc_funcname"><a name="strReplace">strReplace()</a></h3>
<p class="item_brief">Replaces the all the occurrences of a substring with another one. </p>
<p class="faldoc_funcdecl">strReplace( string, substr, repstr, [start], [end] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">The string where the replace will take place. </td></tr><tr><td class="faldoc_param">substr</td><td class="faldoc_paramdesc">The substring that will be replaced. </td></tr><tr><td class="faldoc_param">repstr</td><td class="faldoc_paramdesc">The string that will take the place of substr. </td></tr>
<tr><td class="faldoc_optparam">start</td><td class="faldoc_optparamdesc">Optional start position in the string. </td></tr><tr><td class="faldoc_optparam">end</td><td class="faldoc_optparamdesc">Optional end position in the string. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A copy of the string with the occourences of the searched substring replaced. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This is a flexible function that allows to alter a string by changing all the occurrences of a substring into another one. If the start parameter is given, the search and replacement will take place only starting at the specified position up to the end of the string, and if the end parameter is also provided, the search will take place in the interval [start, end-1]. </p>
</p>
<h3 class="faldoc_funcname"><a name="strReplicate">strReplicate()</a></h3>
<p class="item_brief">Returns a new string that is created by replicating the original one. </p>
<p class="faldoc_funcdecl">strReplicate( string, times )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">The string to be replicaeted. </td></tr><tr><td class="faldoc_param">times</td><td class="faldoc_paramdesc">Number of times the string must be replicated. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The new string. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">A nice shortcut. Also, this function performs the work efficiently, preallocating the needed space in one shot and avoiding the need to grow the string while replicating the original value. </p>
</p>
<h3 class="faldoc_funcname"><a name="strSplit">strSplit()</a></h3>
<p class="item_brief">Subdivides a string in an array of substrings given a token substring. </p>
<p class="faldoc_funcdecl">strSplit( string, token, [count] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">The string that must be splitted </td></tr><tr><td class="faldoc_param">token</td><td class="faldoc_paramdesc">The token by which the string should be splitted. </td></tr>
<tr><td class="faldoc_optparam">count</td><td class="faldoc_optparamdesc">Optional maximum split count. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">An array of strings containing the splitted string. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function returns an array of strings extracted from the given parameter. The array is filled with strings extracted from the first parameter, by dividing it based on the occurrences of the token substring. A count parameter may be provided to limit the splitting, so to take into consideration only the first relevant tokens. Adjacent matching tokens will cause the returned array to contains empty strings. If no matches are possible, the returned array contains at worst a single element containing a copy of the whole string passed as a parameter. </p>
<p class="faldoc_text">For example, the following may be useful to parse a INI file where keys are separated from values by "=" signs: </p>
<pre class="faldoc_code">
key, value = strSplit( string, "=", 2 )
</pre>
<p class="faldoc_text">This code would return an array of 2 items at maximum; if no "=" signs are found in string, the above code would throw an error because of unpacking size, a thing that may be desirable in a parsing code. If there are more than one "=" in the string, only the first starting from left is considered, while the others are returned in the second item, unparsed. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> This function is equivalent to the fbom method <a href="./class_String.html#split">String.split</a>. The above example can be rewritten as: </p>
<pre class="faldoc_code">
key, value = string.split( "=", 2 )
</pre>
</p>
<h3 class="faldoc_funcname"><a name="strSplitTrimmed">strSplitTrimmed()</a></h3>
<p class="item_brief">Subdivides a string in an array of substrings given a token substring. </p>
<p class="faldoc_funcdecl">strSplitTrimmed( string, token, [count] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">The string that must be splitted </td></tr><tr><td class="faldoc_param">token</td><td class="faldoc_paramdesc">The token by which the string should be splitted. </td></tr>
<tr><td class="faldoc_optparam">count</td><td class="faldoc_optparamdesc">Optional maximum split count. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">An array of strings containing the splitted string. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function returns an array of strings extracted from the given parameter. The array is filled with strings extracted from the first parameter, by dividing it based on the occurrences of the token substring. A count parameter may be provided to limit the splitting, so to take into consideration only the first relevant tokens. Adjacent matching tokens will be ignored. If no matches are possible, the returned array contains at worst a single element containing a copy of the whole string passed as a parameter. </p>
<p class="faldoc_text"> Contrarily to <a href="./functions.html#strSplit">strSplit</a>, this function will "eat up" adjacent tokens. While <a href="./functions.html#strSplit">strSplit</a> is more adequate to parse field-oriented strings (as i.e. colon separated fields in configuration files) this function is best employed in word extraction. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> this function is equivalent to the FBOM method String.splittr </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> See <a href="./class_Tokenizer.html">Tokenizer</a> for a more adequate function to scan extensively wide strings. </p>
</p>
<h3 class="faldoc_funcname"><a name="strStartsWith">strStartsWith()</a></h3>
<p class="item_brief">Check if a strings starts with a substring. </p>
<p class="faldoc_funcdecl">strStartsWith( string, token, [icase] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">The string that is going to be tested for the given token. </td></tr><tr><td class="faldoc_param">token</td><td class="faldoc_paramdesc">The substring that will be compared with this string. </td></tr>
<tr><td class="faldoc_optparam">icase</td><td class="faldoc_optparamdesc">If true, pefroms a case neutral check </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> True if <b>token</b> matches the beginning of <b>string</b>, false otherwise. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This functioin performs a comparation check at the beginning of the <b>string</b>. If this string starts with <b>token</b>, the function returns true. If <b>token</b> is larger than the string, the function will always return false, and if <b>token</b> is an empty string, it will always match. </p>
<p class="faldoc_text"> The optional parameter <b>icase</b> can be provided as true to have this function to perform a case insensitive match. </p>
</p>
<h3 class="faldoc_funcname"><a name="strToMemBuf">strToMemBuf()</a></h3>
<p class="item_brief">Convets a string into a Memory Buffer </p>
<p class="faldoc_funcdecl">strToMemBuf( string, [wordWidth] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">String to be converted in a membuf. </td></tr>
<tr><td class="faldoc_optparam">wordWidth</td><td class="faldoc_optparamdesc">The memory buffer word width (defaults to string character size). </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The resulting membuf. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function creates a membuf from a string. The resulting membuf has the same word width of the original string, which may be 1, 2 or 4 byte wide depending on the size needed to store its contents. It is possible to specify a different word width; in that case the function will be much less efficient (each character must be copied). </p>
<p class="faldoc_text">If wordWidth is set to zero, the resulting memory buffer will have 1 byte long elements, but the content of the string will be copied as-is, bytewise, regardless of its character size. </p>
</p>
<h3 class="faldoc_funcname"><a name="strTrim">strTrim()</a></h3>
<p class="item_brief">Removes the white spaces at the beginning and at the end of a string. </p>
<p class="faldoc_funcdecl">strTrim( string, [trimSet] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">The string to be trimmed. </td></tr>
<tr><td class="faldoc_optparam">trimSet</td><td class="faldoc_optparamdesc">A set of characters that must be removed. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The trimmed substring. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> A new string, which is a copy of the original one with all characters in <b>trimSet</b> at the end of the string removed, is returned. If <b>trimSet</b> is not supplied, it defaults to space, tabulation characters, new lines and carriage returns. The original string is unmodified. </p>
</p>
<h3 class="faldoc_funcname"><a name="strUnescape">strUnescape()</a></h3>
<p class="item_brief">Unescape quotes and special characters in the string </p>
<p class="faldoc_funcdecl">strUnescape( string, [inplace] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">the String to be escaped. </td></tr>
<tr><td class="faldoc_optparam">inplace</td><td class="faldoc_optparamdesc">if true, the source string is modified, saving memory. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> A new unescaped string, if <b>inplace</b> is not given, or the <b>string</b> parameter if <b>inplace</b> is true. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="strUnesq">strUnesq()</a></h3>
<p class="item_brief">Unescape the quotes in given string. </p>
<p class="faldoc_funcdecl">strUnesq( string, [inplace] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">the String to be unescaped. </td></tr>
<tr><td class="faldoc_optparam">inplace</td><td class="faldoc_optparamdesc">if true, the source string is modified, saving memory. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> A new unescaped string, if <b>inplace</b> is not given, or the <b>string</b> parameter if <b>inplace</b> is true. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function transforms all the occourences of '\\"' and '\\'' into a double or single quote, leaving all the other special escape sequences untouched. </p>
</p>
<h3 class="faldoc_funcname"><a name="strUpper">strUpper()</a></h3>
<p class="item_brief">Returns an upper case version of the string. </p>
<p class="faldoc_funcdecl">strUpper( string )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">String that must be uppercased. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The uppercased string. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">All the Latin characters in the string are turned uppercase. Other characters are left untouched. </p>
</p>
<h3 class="faldoc_funcname"><a name="strWildcardMatch">strWildcardMatch()</a></h3>
<p class="item_brief">Perform an old-style file-like jolly-based wildcard match. </p>
<p class="faldoc_funcdecl">strWildcardMatch( string, wildcard, [ignoreCase] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">String that must match the wildcard. </td></tr><tr><td class="faldoc_param">wildcard</td><td class="faldoc_paramdesc">A wildcard, possibly but not necessarily including a jolly character. </td></tr>
<tr><td class="faldoc_optparam">ignoreCase</td><td class="faldoc_optparamdesc">If true, the latin 26 base letters case is ignored in matches. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">True if the string matches, false otherwise. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function matches a wildcard that may contain jolly "*" or "?" characters against a string, eventually ignoring the case of the characters. This is a practical function to match file names against given patterns. A "?" in the wildcard represents any single character, while a "*" represents an arbitrary sequence of characters. </p>
<p class="faldoc_text">The wildcard must match completely the given string for the function to return true. </p>
<p class="faldoc_text">For example: </p>
<ul>
<li>"*" matches everything </li><li>"a?b" matches "aab", "adb" and so on </li><li>"a*b" matches "ab", "annnb" and so on </li>
</ul>
</p>
<h3 class="faldoc_funcname"><a name="subscribe">subscribe()</a></h3>
<p class="item_brief">Registers a callback to a message slot. </p>
<p class="faldoc_funcdecl">subscribe( msg, handler, [prio] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">msg</td><td class="faldoc_paramdesc">A string with the message name on which the item should be registered. </td></tr><tr><td class="faldoc_param">handler</td><td class="faldoc_paramdesc">A callable item or instance providing callback support. </td></tr>
<tr><td class="faldoc_optparam">prio</td><td class="faldoc_optparamdesc">Set to true to insert this subscription in front of the subscription list. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="systemErrorDescription">systemErrorDescription()</a></h3>
<p class="item_brief">Returns a system dependent message explaining an integer error code. </p>
<p class="faldoc_funcdecl">systemErrorDescription( errorCode )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">errorCode</td><td class="faldoc_paramdesc">A (possibly) numeric error code that some system function has returned. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A system-specific error description. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function is meant to provide the users (and the developers) with a minimal support to get an hint on why some system function failed, without having to consult the system manual pages. The fsError field of the Error class can be fed directly inside this function. </p>
</p>
<h3 class="faldoc_funcname"><a name="tan">tan()</a></h3>
<p class="item_brief">Returns the tangent of the argument. </p>
<p class="faldoc_funcdecl">tan( x )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">x</td><td class="faldoc_paramdesc">Argument. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The tangent of the argument. </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_MathError.html">MathError</a></td><td class="faldoc_raisedesc">If the argument is out of domain. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The return value is expressed in radians. </p>
<p class="faldoc_text">The function may raise an error if the value cannot be computed because of domain or overflow errors. </p>
</p>
<h3 class="faldoc_funcname"><a name="times">times()</a></h3>
<p class="item_brief">Repeats a sequence a determined number of times. </p>
<p class="faldoc_funcdecl">times( count, sequence )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">count</td><td class="faldoc_paramdesc">Count of times to be repeated or non-open range. </td></tr><tr><td class="faldoc_param">sequence</td><td class="faldoc_paramdesc">A function or a Sigma sequence. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">Last index processed. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This function is very similar to a functional for/in loop. It repeats a sequence of callable items in the <b>sequence</b> parameter a determined number of times. If the <b>sequence</b> parameter is a sequence, parametric evaluation is performed and the <b>&1</b> late binding is filled with the value of the index; if it's a function, then it is called with the counter value added as the last parameter. </p>
<p class="faldoc_text">If the evaluated parameter is a sequence, full deep sigma evaluation is performed at each loop. </p>
<p class="faldoc_text"> The loop index count will be given values from 0 to the required index-1 if <b>count</b> is numeric, or it will act as the for/in loop if <b>count</b> is a range. </p>
<p class="faldoc_text">For example: </p>
<pre class="faldoc_code">
function printParam( var )
> "Parameter is... ", var
end
// the followings are equivalent
times( 10, [printParam, &1] )
times( 10, printParam )
</pre>
<p class="faldoc_text">The following example prints a list of pair numbers between 2 and 10: </p>
<pre class="faldoc_code">
times( [2:11:2], // range 2 to 10+1, with step 2
.[ printl "Index is now..." &1 ]
)
</pre>
<p class="faldoc_text"> Exactly like <a href="./functions.html#floop">floop</a>, the flow of calls in <b>times</b> can be altered by the functions in sequence returning an out-of-band 0 or 1. If any function in the sequence returns an out-of-band 0, <b>times</b> terminates and return immediately (performing an operation similar to "break"). If a function returns an out-of-band 1, the rest of the items in <b>sequence</b> are ignored, and the loop is restarted with the index updated; this is equivalent to a functional "continue". For example: </p>
<pre class="faldoc_code">
times( 10,
// skip numbers less than 5
.[ .[(function(x); if x < 5: return oob(1); end) &1]
.[printl &1] // print the others
]
)
</pre>
<p class="faldoc_text"> The <b>times</b> function return the last generated value for the index. A natural termination of <b>times</b> can be detected thanks to the fact that the index is equal to the upper bound of the range, while an anticipated termination causes <b>times</b> to return a different index. For example, if <b>count</b> is 10, the generated index (possibly received by the items in <b>sequence</b>) will range from 0 to 9 included, and if the function terminates correctly, it will return 10. If a function in <b>sequence</b> returns an out-of-band 0, causing a premature termination of the loop, the value returned by times will be the loop index at which the out-of-band 0 was returned. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> Ranges [m:n] where m > n (down-ranges) terminate at n included; in that case, a succesful completion of <b>times</b> return one-past n. </p>
</p>
<h3 class="faldoc_funcname"><a name="toString">toString()</a></h3>
<p class="item_brief">Returns a string representation of the item. </p>
<p class="faldoc_funcdecl">toString( item, [format] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">The item to be converted to string. </td></tr>
<tr><td class="faldoc_optparam">format</td><td class="faldoc_optparamdesc">Specific object format. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">the string representation of the item. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function is useful to convert an unknown value in a string. The item may be any kind of Falcon item; the following rules apply: </p>
<ul>
<li>Nil items are represented as "<NIL>" </li><li>Integers are converted in base 10. </li><li>Floating point values are converted in base 10 with a default precision of 6; numprec may be specified to change the default precision. </li><li>Array and dictionaries are represented as "Array of 'n' elements" or "Dictionary of 'n' elements". </li><li>Strings are copied. </li><li>Objects are represented as "Object 'name of class'", but if a toString() method is provided by the object, that one is called instead. </li><li>Classes and other kind of opaque items are rendered with their names. </li>
</ul>
<p class="faldoc_text">This function is not meant to provide complex applications with pretty-print facilities, but just to provide simple scripts with a simple and consistent output facility. </p>
<p class="faldoc_text"> If a <b>format</b> parameter is given, the format will be passed unparsed to toString() methods of underlying items. </p>
</p>
<h3 class="faldoc_funcname"><a name="transcodeFrom">transcodeFrom()</a></h3>
<p class="item_brief">Returns a Falcon string created by parsing the given one as a binary sequence of bytes. </p>
<p class="faldoc_funcdecl">transcodeFrom( string, encoding )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">Falcon string or MemBuf to be encoded. </td></tr><tr><td class="faldoc_param">encoding</td><td class="faldoc_paramdesc">Name of the encoding (as a string). </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">On success, the transcoded string. </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_ParamError.html">ParamError</a></td><td class="faldoc_raisedesc">if the encoding is not known. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">In case the encoding name is not known, the function will raise a ParamError. The transcoding may also fail if the source data is not a valid sequence under the given encoding, and cannot be decoded. </p>
</p>
<h3 class="faldoc_funcname"><a name="transcodeTo">transcodeTo()</a></h3>
<p class="item_brief">Returns a binary buffer containing an encoded representation of a Falcon string. </p>
<p class="faldoc_funcdecl">transcodeTo( string, encoding )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">Falcon string to be encoded. </td></tr><tr><td class="faldoc_param">encoding</td><td class="faldoc_paramdesc">Name of the encoding (as a string). </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">On success, the transcoded string. </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_ParamError.html">ParamError</a></td><td class="faldoc_raisedesc">if the encoding is not known. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">In case the encoding name is not known, the function will raise a ParamError. </p>
</p>
<h3 class="faldoc_funcname"><a name="typeOf">typeOf()</a></h3>
<p class="item_brief">Returns an integer indicating the type of an item. </p>
<p class="faldoc_funcdecl">typeOf( item )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">An item of any kind. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A constant indicating the type of the item. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The typeId returned is an integer; the Falcon compiler is fed with a set of compile time constants that can be used to determine the type of an item. Those constants are always available at Falcon sources. </p>
<p class="faldoc_text">The value returned may be one of the following: </p>
<ul>
<li><b>NilType</b>- the item is NIL </li><li><b>BooleanType</b>- the item is true or false </li><li><b>NumericType</b>- the item is a number </li><li><b>RangeType</b>- the item is a range (a pair of two integers) </li><li><b>FunctionType</b>- the item is a function </li><li><b>StringType</b>- the item is a string </li><li><b>LBindType</b>- the item is a late binding symbol </li><li><b>MemBufType</b>- the item is a Memory Buffer Table </li><li><b>ArrayType</b>- the item is an array </li><li><b>DictionaryType</b>- the item is a dictionary </li><li><b>ObjectType</b>- the item is an object </li><li><b>ClassType</b>- the item is a class </li><li><b>MethodType</b>- the item is a method </li><li><b>ClassMethodType</b>- the item is a method inside a class </li>
</ul>
</p>
<h3 class="faldoc_funcname"><a name="unsetenv">unsetenv()</a></h3>
<p class="item_brief">Clear environment variable value. </p>
<p class="faldoc_funcdecl">unsetenv( varName )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">varName</td><td class="faldoc_paramdesc">Environment variable name (as a string) </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function removes a given variable setting, causing subsequents getenv( varName ) to return nil. </p>
</p>
<h3 class="faldoc_funcname"><a name="unsubscribe">unsubscribe()</a></h3>
<p class="item_brief">Unregisters a registered callback from a slot. </p>
<p class="faldoc_funcdecl">unsubscribe( msg, handler )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">msg</td><td class="faldoc_paramdesc">A string with the message name on which the item should be registered. </td></tr><tr><td class="faldoc_param">handler</td><td class="faldoc_paramdesc">A callable item or instance providing callback support. </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_CodeError.html">CodeError</a></td><td class="faldoc_raisedesc"> if the <b>handler</b> is not registered with this slot. </td></tr><tr><td class="faldoc_raiseitem"><a href="./class_AccessError.html">AccessError</a></td><td class="faldoc_raisedesc">if the named message slot doesn't exist. </td></tr>
</table>
</td></tr>
</table>
<h3 class="faldoc_funcname"><a name="valof">valof()</a></h3>
<p class="item_brief">Calls callable items or returns non callable ones. </p>
<p class="faldoc_funcdecl">valof( item )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">The item to be checked. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The item if it is not callable, or the call return value. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> The name function is a short for <i>extended</i><i>value</i>. It is meant to determine if the passed item is a non-callable value or if it should be called to determine a value. Performing this check at script level time consuming and often clumsy, and this function is easily used in functional sequences. </p>
</p>
<h3 class="faldoc_funcname"><a name="vmFalconPath">vmFalconPath()</a></h3>
<p class="item_brief">Returns default system path for Falcon load requests. </p>
<p class="faldoc_funcdecl">vmFalconPath</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The default compiled-in load path, or the value of the environemnt variable FALCON_LOAD_PATH if defined. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="vmIsMain">vmIsMain()</a></h3>
<p class="item_brief">Returns true if the calling module is the main module of the application. </p>
<p class="faldoc_funcdecl">vmIsMain</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">True if the calling module is the main module. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function checks if the current module has been added as the last one right before starting an explicit execution of the virtual machine from the outside. </p>
<p class="faldoc_text">This function is useful for those modules that have a main code which is meant to be executed at link time and a part that is menat to be executed only if the module is directly loaded and executed. </p>
<p class="faldoc_text">For example: </p>
<pre class="faldoc_code">
// executes this at link time
prtcode = printl
// executes this from another module on request
function testPrint()
prtcode( "Success." )
end
export testPrint
// performs a test if directly loaded
if vmIsMain()
> "Testing the testPrint function"
testPrint()
end
</pre>
</p>
<h3 class="faldoc_funcname"><a name="vmModuleName">vmModuleName()</a></h3>
<p class="item_brief">Returns the logical name of this module. </p>
<p class="faldoc_funcdecl">vmModuleName</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">Logical name of this module. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Every module has a logical name inside the application. There is a loose mapping between the underlying module providers and the logical name of the module, so knowing it may be helpful. </p>
</p>
<h3 class="faldoc_funcname"><a name="vmModuleVersionInfo">vmModuleVersionInfo()</a></h3>
<p class="item_brief">Returns an array containing current module version informations. </p>
<p class="faldoc_funcdecl">vmModuleVersionInfo</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">Major, minor and revision numbers of the curerntly being executed module, in a 3 elements array. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="vmSearchPath">vmSearchPath()</a></h3>
<p class="item_brief">Returns the application specific load path. </p>
<p class="faldoc_funcdecl">vmSearchPath</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A module search path as set by the application when creating the virtual machine. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This string is at disposal of the embeddign application (or of the Falcon command line interpreter) to communicate to scripts and underlying users the search path set at applicaiton level. It is used by internal services, the <a href="./functions.html#include">include</a> function, the compiler Feather module and similar facilities. </p>
</p>
<h3 class="faldoc_funcname"><a name="vmSystemType">vmSystemType()</a></h3>
<p class="item_brief">Returns a descriptive name of the overall system architecture. </p>
<p class="faldoc_funcdecl">vmSystemType</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A string containing a small descriptiuon of the system architecture. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Currently, it can be "WIN" on the various MS-Windows flavours and POSIX on Linux, BSD, Solaris, Mac-OSX and other *nix based systems. </p>
</p>
<h3 class="faldoc_funcname"><a name="vmVersionInfo">vmVersionInfo()</a></h3>
<p class="item_brief">Returns an array containing VM version informations. </p>
<p class="faldoc_funcdecl">vmVersionInfo</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">Major, minor and revision numbers of the running virtual machine in a 3 elements array. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="vmVersionName">vmVersionName()</a></h3>
<p class="item_brief">Returns the nickname for this VM version. </p>
<p class="faldoc_funcdecl">vmVersionName</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A string containing the symbolic name of this VM version. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="writeURI">writeURI()</a></h3>
<p class="item_brief">Writes fully data to a given file or URI source. </p>
<p class="faldoc_funcdecl">writeURI( uri, data, [encoding] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">uri</td><td class="faldoc_paramdesc">The item to be read (URI or string) </td></tr><tr><td class="faldoc_param">data</td><td class="faldoc_paramdesc">A string or membuf containing the data to be written. </td></tr>
<tr><td class="faldoc_optparam">encoding</td><td class="faldoc_optparamdesc">The encoding. </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">in case of write errors. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This function writes all the data contained in the string or memory buffer passed in the <b>data</b> parameter into the <b>uri</b> output resource. </p>
<p class="faldoc_text"> If <b>encoding</b> is not given, the data is treated as binary data and written as-is. </p>
<p class="faldoc_text">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>
<h3 class="faldoc_funcname"><a name="xmap">xmap()</a></h3>
<p class="item_brief">Creates a new vector of items transforming each item in the original array through the mapping function, applying also filtering on undesired items. </p>
<p class="faldoc_funcdecl">xmap( mfunc, sequence )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">mfunc</td><td class="faldoc_paramdesc">A function or sigma used to map the array. </td></tr><tr><td class="faldoc_param">sequence</td><td class="faldoc_paramdesc">A sequence to be mapped. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The mapped sequence. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"><b>mfunc</b> is called iteratively for every item in the collection; its return value is added to the mapped array. Moreover, each item in the collection is functionally evaluated before being passed to mfunc. </p>
<p class="faldoc_text">The filter function may return an out of band nil item to signal that the current item should not be added to the final collection. </p>
<p class="faldoc_text">For example: </p>
<pre class="faldoc_code">
mapper = { item => item < 0 ? oob(nil) : item ** 0.5 }
add = { a, b => a+b } // a block that will be evaluated
inspect( xmap( mapper, [ [add, 99, 1], 4, -12, 9 ]) ) // returns [10, 2, 3]
</pre>
</p>
<h3 class="faldoc_funcname"><a name="yield">yield()</a></h3>
<p class="item_brief">gives up the rest of the coroutine time slice. </p>
<p class="faldoc_funcdecl">yield</p>
<p class="faldoc_text"><p class="faldoc_text">This signals the VM that the current coroutine is temporarily done, and that another coroutine may be executed. If no other coroutines can be executed, current coroutine is resumed immediately (actually, it is never swapped out). </p>
</p>
<h3 class="faldoc_funcname"><a name="yieldOut">yieldOut()</a></h3>
<p class="item_brief">Terminates current coroutine. </p>
<p class="faldoc_funcdecl">yieldOut( retval )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">retval</td><td class="faldoc_paramdesc">a return value for the coroutine. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The current coroutine is terminated. If this is the last coroutine, the VM exits. Calling this function has the same effect of the END virtual machine PCODE. </p>
<p class="faldoc_text">In multithreading context, exiting from the last coroutine causes a clean termination of the current thread. </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>
