<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Class Iterator - Class Iterator</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 Iterator</h1>
<p class="faldoc_brief">Indirect pointer to sequences. </p>
<p class="faldoc_funcdecl">
<b>class</b> Iterator( collection, [atEnd] )
</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="#clone">clone()</a></td><td>Returns an instance of this iterator pointing to the same item. </td></tr>
<tr><td><a href="#equal">equal()</a></td><td>Check if this iterator is equal to the provided item. </td></tr>
<tr><td><a href="#erase">erase()</a></td><td>Erase current item in the underlying sequence. </td></tr>
<tr><td><a href="#find">find()</a></td><td>Moves this iterator on the searched item. </td></tr>
<tr><td><a href="#hasCurrent">hasCurrent()</a></td><td>Check if the iterator is valid and can be used to access the underlying collection. </td></tr>
<tr><td><a href="#hasNext">hasNext()</a></td><td> Check if the iterator is valid and a <a href="./class_Iterator.html#next">Iterator.next</a> operation would still leave it valid. </td></tr>
<tr><td><a href="#hasPrev">hasPrev()</a></td><td> Check if the iterator is valid and a <a href="./class_Iterator.html#prev">Iterator.prev</a> operation would still leave it valid. </td></tr>
<tr><td><a href="#insert">insert()</a></td><td>Insert an item, or a pair of key values, in an underlying sequence. </td></tr>
<tr><td><a href="#key">key()</a></td><td>Retreives the current key in the collection. </td></tr>
<tr><td><a href="#next">next()</a></td><td>Advance the iterator. </td></tr>
<tr><td><a href="#prev">prev()</a></td><td>Move the iterator back. </td></tr>
<tr><td><a href="#value">value()</a></td><td>Retreives the current item in the collection. </td></tr>
</table>
<a name="more"><h2 class="faldoc_title">Detailed description</h2></a>
<p class="faldoc_funcdecl">
<b>class</b> Iterator( collection, [atEnd] )
</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">collection</td><td class="faldoc_paramdesc">The collection on which to iterate. </td></tr>
<tr><td class="faldoc_optparam">atEnd</td><td class="faldoc_optparamdesc">Indicator for start position. </td></tr>
</table>
<br/>
<p class="item_brief">Indirect pointer to sequences. </p>
<p class="faldoc_text">An iterator is an object meant to point to a certain position in a collection (array, dictionary, string, or eventually user defined types), and to access iteratively the elements in that collection. </p>
<p class="faldoc_text">Iterators may be used to alter a collection by removing the item they are pointing to, or by changing its value. They can be stored to be used at a later moment, or they can be passed as parameters. Most notably, they hide the nature of the underlying collection, so that they can be used as an abstraction layer to access underlying data, one item at a time. </p>
<p class="faldoc_text">Altering the collection may cause an iterator to become invalid; only performing write operations through an iterator it is possible to guarantee that it will stay valid after the modify. A test for iterator validity is performed on each operation, and in case the iterator is not found valid anymore, an error is raised. </p>
<p class="faldoc_text">Iterators supports equality tests and provide an equal() method. Two iterators pointing to the same element in the same collection are considered equal; so it is possible to iterate through all the items between a start and an end. </p>
<a name="init"><h2 class="faldoc_section">Initialization </h2></a>
<p class="faldoc_text">The iterator is normally created at the begin of the sequence. If items in the collection can be directly accessed </p>
<p class="faldoc_text"> If <b>position</b> is given and true, the iterator starts from the end of the sequence (that is, pointing to the last valid element in the sequence), otherwise it points at the first valid element. </p>
<h2 class="faldoc_title">Methods</h2>
<h3 class="faldoc_funcname"><a name="clone">clone()</a></h3>
<p class="item_brief">Returns an instance of this iterator pointing to the same item. </p>
<p class="faldoc_funcdecl">Iterator.clone( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A new copy of this iterator. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Creates an iterator equivalent to this one. In this way, it is possible to record a previous position and use it later. Using a normal assignment wouldn't work, as the assignand would just be given the same iterator, and its value would change accordingly with the other image of the iterator. </p>
</p>
<h3 class="faldoc_funcname"><a name="equal">equal()</a></h3>
<p class="item_brief">Check if this iterator is equal to the provided item. </p>
<p class="faldoc_funcdecl">Iterator.equal( item )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">The item to which this iterator must be compared. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">True if the item matches this iterator. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This method overrides the FBOM equal method, and overloads the equality check of the VM. </p>
</p>
<h3 class="faldoc_funcname"><a name="erase">erase()</a></h3>
<p class="item_brief">Erase current item in the underlying sequence. </p>
<p class="faldoc_funcdecl">Iterator.erase( )</p>
<table class="faldoc_function">
<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 iterator is invalid. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">If the iterator is valid, this method removes current item. The iterator is moved to the very next item in the collection, and this may invalidate it if the removed element was the last one. To remove element while performing a scanning from the last element to the first one, remember to call the prev() method after every remove(); in forward scans, a successful remove() implies that the caller must not call next() to continue the scan. </p>
</p>
<h3 class="faldoc_funcname"><a name="find">find()</a></h3>
<p class="item_brief">Moves this iterator on the searched item. </p>
<p class="faldoc_funcdecl">Iterator.find( key )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">key</td><td class="faldoc_paramdesc">the key to be searched. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">true if the key was found, false otheriwse. </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 iterator is invalid or if the sequence doesn't provide keys. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This method searches for an key in the underlying sequence, provided it offers search keys support. This is the case of the various dictionaries. </p>
<p class="faldoc_text">This search is optimizied so that the subtree below the current position of the iterator is searched first. If the iterator is pointing to an item that matches the required key, this method returns immediately. </p>
<p class="faldoc_text">After a succesful search, the iterator is moved to the position of the searched item. </p>
<p class="faldoc_text">After a failed search, the iterator is moved to the smallest item in the sequence greater than the desired key; it's the best position for an insertion of the searched key. </p>
<p class="faldoc_text">For example, to traverse all the items in a dictionary starting with 'C', the following code can be used: </p>
<pre class="faldoc_code">
dict = [ "Alpha" => 1, "Beta" => 2, "Charlie" => 3, "Columbus" => 4, "Delta" => 5 ]
iter = Iterator( dict )
iter.find( "C" ) // we don't care if it succeeds
while iter.hasCurrent() and iter.key()[0] == "C"
> iter.key(), " => ", iter.value()
iter.next()
end
</pre>
<p class="faldoc_text">Also, a failed search gives anyhow a useful hint position for a subsequent insertion, which may avoid performing the search again. </p>
</p>
<h3 class="faldoc_funcname"><a name="hasCurrent">hasCurrent()</a></h3>
<p class="item_brief">Check if the iterator is valid and can be used to access the underlying collection. </p>
<p class="faldoc_funcdecl">Iterator.hasCurrent( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">true if the iterator is valid and can be used to access a current item. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="hasNext">hasNext()</a></h3>
<p class="item_brief"> Check if the iterator is valid and a <a href="./class_Iterator.html#next">Iterator.next</a> operation would still leave it valid. </p>
<p class="faldoc_funcdecl">Iterator.hasNext( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">true if there is an item past to the current one. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="hasPrev">hasPrev()</a></h3>
<p class="item_brief"> Check if the iterator is valid and a <a href="./class_Iterator.html#prev">Iterator.prev</a> operation would still leave it valid. </p>
<p class="faldoc_funcdecl">Iterator.hasPrev( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">true if there is an item before to the current one. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="insert">insert()</a></h3>
<p class="item_brief">Insert an item, or a pair of key values, in an underlying sequence. </p>
<p class="faldoc_funcdecl">Iterator.insert( key, [value] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">key</td><td class="faldoc_paramdesc">Item to be inserted (or key, if the underlying sequence is keyed). </td></tr>
<tr><td class="faldoc_optparam">value</td><td class="faldoc_optparamdesc">A value associated with the key. </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 iterator is invalid. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Inserts an item at current position. In case the underlying sequence is an ordered sequence of key-value pairs, a correct position for insertion is first searched, and then the iterator is moved to the position of the inserted key. </p>
<p class="faldoc_text">In this second case, if the iterator already points to a valid position for insertion of the given key, the search step is skipped. </p>
</p>
<h3 class="faldoc_funcname"><a name="key">key()</a></h3>
<p class="item_brief">Retreives the current key in the collection. </p>
<p class="faldoc_funcdecl">Iterator.key( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The current key. </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 iterator is not valid, or if the collection has not keys. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">If this iterator is valid and is pointing to a collection that provides key ordering (i.e. a dictionary), it returns the current key; otherwise, it raises an AccessError. </p>
</p>
<h3 class="faldoc_funcname"><a name="next">next()</a></h3>
<p class="item_brief">Advance the iterator. </p>
<p class="faldoc_funcdecl">Iterator.next( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">true if the iterator is still valid after next() has been completed. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Moves the iterator to the next item in the collection. If the iterator is not valid anymore, or if the current element was the last in the collection, the method returns false. If the iterator has successfully moved, it returns true. </p>
</p>
<h3 class="faldoc_funcname"><a name="prev">prev()</a></h3>
<p class="item_brief">Move the iterator back. </p>
<p class="faldoc_funcdecl">Iterator.prev( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">true if the iterator is still valid after prev() has been completed. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Moves the iterator to the previous item in the collection. If the iterator is not valid anymore, or if the current element was the first in the collection, the method returns false. If the iterator has successfully moved, it returns true. </p>
</p>
<h3 class="faldoc_funcname"><a name="value">value()</a></h3>
<p class="item_brief">Retreives the current item in the collection. </p>
<p class="faldoc_funcdecl">Iterator.value( [subst] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_optparam">subst</td><td class="faldoc_optparamdesc">New value for the current item. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The current 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 iterator is not valid. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">If the iterator is valid, the method returns the value of the item being currently pointed by the iterator. </p>
<p class="faldoc_text"> If a parameter <b>subst</b> is given, the current value in the sequence is changed to <b>substs</b>. </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>
