<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Class Sequence - Class Sequence</title>
<link href="faldoc.css" rel="stylesheet" type="text/css"/>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
</head>
<body class="faldoc_body">
<div class="navitop">
<div class="tabs">
<ul>
<li><a href="./index.html"><span>Main</span></a></li>
<li><a href="./pages.html"><span>Related pages</span></a></li>
<li><a href="./groups.html"><span>Groups</span></a></li>
<li><a href="./funset.html"><span>Function sets</span></a></li>
<li><a href="./classes.html"><span>Classes</span></a></li>
<li><a href="./objects.html"><span>Objects</span></a></li>
<li><a href="./functions.html"><span>All functions</span></a></li>
<li><a href="./globals.html"><span>Globals</span></a></li>
</ul>
</div>
</div>
<hr/>
<h1 class="faldoc_title">Class Sequence</h1>
<p class="faldoc_brief">Base abstract class for VM assisted sequences. </p>
<p class="faldoc_funcdecl">
<b>class</b> Sequence
</p>
<p class="faldoc_brief"><a href="#more">more...</a></p>
<h2 class="faldoc_title">Summary</h2>
<table class="faldoc_list">
<tr><td><a href="#append">append()</a></td><td>Adds an item at the end of the sequence. </td></tr>
<tr><td><a href="#back">back()</a></td><td>Returns the last item in the Sequence. </td></tr>
<tr><td><a href="#clear">clear()</a></td><td>Removes all the items from the Sequence. </td></tr>
<tr><td><a href="#comp">comp()</a></td><td>Appends elements to this sequence through a filter. </td></tr>
<tr><td><a href="#empty">empty()</a></td><td>Checks if the Sequence is empty or not. </td></tr>
<tr><td><a href="#first">first()</a></td><td>Returns an iterator to the first element of the Sequence. </td></tr>
<tr><td><a href="#front">front()</a></td><td>Returns the first item in the Sequence. </td></tr>
<tr><td><a href="#last">last()</a></td><td>Returns an iterator to the last element of the Sequence. </td></tr>
<tr><td><a href="#mcomp">mcomp()</a></td><td>Appends elements to this sequence from multiple sources. </td></tr>
<tr><td><a href="#mfcomp">mfcomp()</a></td><td>Appends elements to this sequence from multiple sources through a filter. </td></tr>
<tr><td><a href="#prepend">prepend()</a></td><td>Adds an item in front of the sequence </td></tr>
</table>
<a name="more"><h2 class="faldoc_title">Detailed description</h2></a>
<p class="faldoc_funcdecl">
<b>class</b> Sequence
</p>
<table class="faldoc_function">
</table>
<br/>
<p class="item_brief">Base abstract class for VM assisted sequences. </p>
<p class="faldoc_text">This class is meant to provide common methods to VM-assisted (that is, language level) sequence classes. You can't derive directly from this class unless you're writing a native module, but you can derive from script-visible classes children of this one. </p>
<h2 class="faldoc_title">Methods</h2>
<h3 class="faldoc_funcname"><a name="append">append()</a></h3>
<p class="item_brief">Adds an item at the end of the sequence. </p>
<p class="faldoc_funcdecl">Sequence.append( item )</p>
<table class="faldoc_function">
<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"> If the sequence is sorted, the position at which the <b>item</b> is inserted is determined by the internal ordering; otherwise the <b>item</b> is appended at the end of the sequence. </p>
</p>
<h3 class="faldoc_funcname"><a name="back">back()</a></h3>
<p class="item_brief">Returns the last item in the Sequence. </p>
<p class="faldoc_funcdecl">Sequence.back( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The last item in the Sequence. </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 Sequence is empty. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This method overloads the BOM method <b>back</b>. If the Sequence is not empty, it returns the last element. </p>
</p>
<h3 class="faldoc_funcname"><a name="clear">clear()</a></h3>
<p class="item_brief">Removes all the items from the Sequence. </p>
<p class="faldoc_funcdecl">Sequence.clear( )</p>
<h3 class="faldoc_funcname"><a name="comp">comp()</a></h3>
<p class="item_brief">Appends elements to this sequence through a filter. </p>
<p class="faldoc_funcdecl">Sequence.comp( source, [filter] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">source</td><td class="faldoc_paramdesc">A sequence, a range or a callable generating items. </td></tr>
<tr><td class="faldoc_optparam">filter</td><td class="faldoc_optparamdesc">A filtering function receiving one item at a time. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">This sequence. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This method adds one item at a time to this Sequence. </p>
<p class="faldoc_text"> If <b>source</b> is a range, (must not be open), all the values generated by the range will be appended, considering range direction and step. </p>
<p class="faldoc_text"> If <b>source</b> is a sequence (array, dictionary, or any other object providing the sequence interface), all the values in the item will be appended to this Sequence. </p>
<p class="faldoc_text"> If <b>source</b> is a callable item, it is called repeatedly to generate the sequence. All the items it returns will be appended, until it declares being terminated by returning an oob(0). Continuation objects are also supported. </p>
<p class="faldoc_text"> If a <b>filter</b> callable is provided, all the items that should be appended are first passed to to it; the item returned by the callable will be used instead of the item provided in <b>source</b>. The <b>filter</b> may return an out of band 1 to skip the item from <b>source</b>, or an out of band 0 to stop the processing altogether. The <b>filter</b> callable receives also the forming sequence as the second parameter so that it account for it or manage it dynamically during the filter step. </p>
<p class="faldoc_text"> For example, the following comprehension creates a dictionary associating a letter of the alphabet to each element in the source sequence, discarding elements with spaces and terminating when a "<end>" mark is found. The <b>filter</b> function uses the second parameter to determine how many items have been added, and return a different element each time. </p>
<pre class="faldoc_code">
dict = [=>].comp(
// the source
.[ 'bananas' 'skip me' 'apples' 'oranges' '<end>' 'melons' ],
// the filter
{ element, dict =>
if " " in element: return oob(1)
if "<end>" == element: return oob(0)
return [ "A" / len(dict), element ] // (1)
}
)
// (1): "A" / number == chr( ord("A") + number )
</pre>
<p class="faldoc_text">This method actually adds each item in the comprehension to the sequence or sequence-compatible item in self. This means that comprehension needs not to be performed on a new, empty sequence; it may be also used to integrate more data in already existing sequences. </p>
</p>
<h3 class="faldoc_funcname"><a name="empty">empty()</a></h3>
<p class="item_brief">Checks if the Sequence is empty or not. </p>
<p class="faldoc_funcdecl">Sequence.empty( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">True if the Sequence is empty, false if contains some elements. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="first">first()</a></h3>
<p class="item_brief">Returns an iterator to the first element of the Sequence. </p>
<p class="faldoc_funcdecl">Sequence.first( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">An iterator. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Returns an iterator to the first element of the Sequence. If the Sequence is empty, an invalid iterator will be returned, but an insertion on that iterator will succeed and append an item to the Sequence. </p>
</p>
<h3 class="faldoc_funcname"><a name="front">front()</a></h3>
<p class="item_brief">Returns the first item in the Sequence. </p>
<p class="faldoc_funcdecl">Sequence.front( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The first item in the Sequence. </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 Sequence is empty. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This method overloads the BOM method <b>front</b>. If the Sequence is not empty, it returns the first element. </p>
</p>
<h3 class="faldoc_funcname"><a name="last">last()</a></h3>
<p class="item_brief">Returns an iterator to the last element of the Sequence. </p>
<p class="faldoc_funcdecl">Sequence.last( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">An iterator. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Returns an iterator to the last element of the Sequence. If the Sequence is empty, an invalid iterator will be returned, but an insertion on that iterator will succeed and append an item to the Sequence. </p>
</p>
<h3 class="faldoc_funcname"><a name="mcomp">mcomp()</a></h3>
<p class="item_brief">Appends elements to this sequence from multiple sources. </p>
<p class="faldoc_funcdecl">Sequence.mcomp( ... )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">...</td><td class="faldoc_paramdesc">One or more sequences, ranges or callables generating items. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">This sequence. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This method works as <a href="./class_Sequence.html#comp">Sequence.comp</a> but it's possible to specify more items and sequences. Each element in the result set is an array of items in which each element extracted from a source or returned by a generator is combined with all the others. </p>
<p class="faldoc_text">For example, the following operation: </p>
<pre class="faldoc_code">
[].mcomp( [1,2], [3,4] )
</pre>
<p class="faldoc_text">results in: </p>
<pre class="faldoc_code">
[ [1,3], [1,4], [2,3], [2,4] ]
</pre>
<p class="faldoc_text"> Generators are called repeatedly until they exhaust all the items they can generate, in the same order as they are declared in the <b>mcomp</b> call. </p>
<p class="faldoc_text">For example: </p>
<pre class="faldoc_code">
[].mcomp( alphagen, betagen )
</pre>
<p class="faldoc_text">will first call alphagen until it returns an oob(0), and then call betagen repeatedly. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> Calls in this context are not atomic. Suspension, sleep, I/O, and continuations are allowed and supported. </p>
<p class="faldoc_text">After all the generators are called, the collected data is mixed with static data coming from other sources. For example: </p>
<pre class="faldoc_code">
function make_gen( count, name )
i = 0
return {=>
if i == count: return oob(0)
> name, ": ", i
return i++
}
end
> [].mcomp( ["a","b"], make_gen(2, "first"), make_gen(2, "second") ).describe()
</pre>
<p class="faldoc_text">will generate the following output: </p>
<pre class="faldoc_code">
first: 0
first: 1
second: 0
second: 1
[ [ "a", 0, 0], [ "a", 0, 1], [ "a", 1, 0], [ "a", 1, 1],
[ "b", 0, 0], [ "b", 0, 1], [ "b", 1, 0], [ "b", 1, 1]]
</pre>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> The <a href="./class_Sequence.html#mfcomp">Sequence.mfcomp</a> provides a more flexible approach. </p>
</p>
<h3 class="faldoc_funcname"><a name="mfcomp">mfcomp()</a></h3>
<p class="item_brief">Appends elements to this sequence from multiple sources through a filter. </p>
<p class="faldoc_funcdecl">Sequence.mfcomp( filter, ... )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">filter</td><td class="faldoc_paramdesc">A filtering function receiving one item at a time. </td></tr><tr><td class="faldoc_param">...</td><td class="faldoc_paramdesc">One or more sequences, ranges or callables generating items. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">This sequence. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This function works exactly as <a href="./class_Sequence.html#mcomp">Sequence.mcomp</a>, with the difference that the elements generated are passed to a filter function for final delivery to the target sequence. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> The <b>filter</b> parameter is optional; if <b>nil</b> is passed to it, this method works exactly as <a href="./class_Sequence.html#mcomp">Sequence.mcomp</a>. </p>
<p class="faldoc_text">For example, the math set operation </p>
<pre class="faldoc_code">
{ x*y for x in 1,2,3 and y in 4,5,6 }
</pre>
<p class="faldoc_text">can be written using mfcomp like the following: </p>
<pre class="faldoc_code">
[].mfcomp( {x, y => x*y}, .[1 2 3], .[4 5 6] )
</pre>
<p class="faldoc_text">which results in </p>
<pre class="faldoc_code">
[ 4, 5, 6, 8, 10, 12, 12, 15, 18]
</pre>
<p class="faldoc_text"> The as for <a href="./class_Sequence.html#comp">Sequence.comp</a>, filter receives an extra parameter which is the sequence itself. For example, the following code: </p>
<pre class="faldoc_code">
> [].mfcomp( {x, y, seq =>
printl( "Seq is now long: " + seq.len() )
return [seq.len(), x*y]
},
.[1 2 3], .[4 5 6]
).describe()
</pre>
<p class="faldoc_text">generates this output: </p>
<pre class="faldoc_code">
Seq is now long: 0
Seq is now long: 1
Seq is now long: 2
Seq is now long: 3
Seq is now long: 4
Seq is now long: 5
Seq is now long: 6
Seq is now long: 7
Seq is now long: 8
[ [ 0, 4], [ 1, 5], [ 2, 6], [ 3, 8], [ 4, 10], [ 5, 12], [ 6, 12], [ 7, 15], [ 8, 18]]
</pre>
<p class="faldoc_text">Notice that it is possible to modify the sequence inside the filter, in case it's needed. </p>
<p class="faldoc_text">The filter may return an oob(1) to skip the value, and an oob(0) to terminate the operation. For example, the following code s </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> The call Sequence.mfcomp( filter, seq ) is equivalent to Sequence.comp( seq, filter ). </p>
</p>
<h3 class="faldoc_funcname"><a name="prepend">prepend()</a></h3>
<p class="item_brief">Adds an item in front of the sequence </p>
<p class="faldoc_funcdecl">Sequence.prepend( item )</p>
<table class="faldoc_function">
<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"> If the sequence is sorted, the position at which the <b>item</b> is inserted is determined by the internal ordering; otherwise the <b>item</b> is prepended in front of the sequence. </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>
