<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en" dir="ltr">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="../../../style.css">
<title>
Gambas Documentation - Enumeration Management
</title>
</head>
<table class="none" width="100%" cellpadding="0" cellspacing="0" border="0">
<tr><td align="left">
<font size="-1">
<a href="../../../help+en"><img class="flag" alt="Home" border="0" src="../../../img/lang/en.png" align="center"></a>&nbsp;
<a href="../cat+en">Up</a>&nbsp;
<a href="desc+en">Previous</a>&nbsp;
<a href="error+en">Next</a>&nbsp;
</td></tr></table>
<div class="notab">
<h1>
Enumeration Management
</h1>
<table class="table" border="0" bordercolor="#000000" cellpadding="4" cellspacing="0">
<tr class="dark"><td valign="top">
<tt><a href="../name/gb.getenum+en">GB.GetEnum</a></tt>
</td><td valign="top">
Returns the current enumeration state.
</td></tr>
<tr><td valign="top">
<tt><a href="../name/gb.listenum+en">GB.ListEnum</a></tt>
</td><td valign="top">
Lists all enumerators that enumerate a specified object.
</td></tr>
<tr class="dark"><td valign="top">
<tt><a href="../name/gb.nextenum+en">GB.NextEnum</a></tt>
</td><td valign="top">
Returns the next enumerator.
</td></tr>
<tr><td valign="top">
<tt><a href="../name/gb.stopallenum+en">GB.StopAllEnum</a></tt>
</td><td valign="top">
Stops all enumerators that enumerate a specified object.
</td></tr>
<tr class="dark"><td valign="top">
<tt><a href="../name/gb.stopenum+en">GB.StopEnum</a></tt>
</td><td valign="top">
Stops the current enumeration.
</td></tr>
</table>
<p>
<h2>Overview</h2>
<p>
Enumerations are managed in the <tt><a href="special/_next+en">_next</a></tt> special method.
<p>
This method is called at the start of the enumeration, and at each loop iteration, to
retrieve the first or the next element.
<p>
<h3>Enumeration State</h3>
<p>
<tt><a href="../name/gb.getenum+en">GB.GetEnum</a></tt> gives you a pointer to a enumeration buffer. Use this buffer to store the state of the enumeration. You can store up to 16 bytes into this buffer.
<p>
Note that the buffer is initialized with zeros at the beginning of the enumeration,
so that you can detect when <tt>_next</tt> is called at the start of the enumeration.
<p>
When the end of the enumeration is reached, use the <tt><a href="../name/gb.stopenum+en">GB.StopEnum</a></tt> function to warn the interpreter,
and returns immediately from the implementation function.
<p>
<h3>Updating Enumeration State</h3>
<p>
If you destroy one element of the enumeration, you must use <tt><a href="../name/gb.listenum+en">GB.ListEnum</a></tt> and <tt><a href="../name/gb.nextenum+en">GB.NextEnum</a></tt> to
update the state of current iterators.
<p>
If you entirely clear the enumerable object, then you must use <tt><a href="../name/gb.stopallenum+en">GB.StopAllEnum</a></tt> to stop
all current iterators.

</div>
</body>
</html>

