autodoc.git
/
traditional_manual
/
chapter_21.html
version
»
Context lines:
10
20
40
80
file
none
3
autodoc.git/traditional_manual/chapter_21.html:6856:
<p> Iterators are typically created to access a data set in some specific object, array, mapping, multiset or string. An object can have several iterators that access different data sets in it, or the same in different ways. E.g. strings have both an iterator for access char-by-char (<code>String.Iterator</code>), and another for access over splitted substrings (<code>String.SplitIterator</code>). <code>lfun::_get_iterator</code> may be defined in an object to get an instance of the canonical iterator type for it. It's used by e.g. <code>foreach</code> to iterate over objects conveniently.</p> <p> It's not an error to advance an iterator past the beginning or end
-
of the data set; <code>`!()</code> will only return true then, and <code>index</code>
-
and <code>value</code> will return <code>UNDEFINED</code>. An iterator in that state
+
of the data set; <code>`!()</code> will only return true then, and <code>
_iterator_
index</code>
+
and <code>
_iterator_
value</code> will return <code>UNDEFINED</code>. An iterator in that state
need not keep track of positions, so it's undefined what happens if it's "moved back" into the set of items.</p> <p> Backward movement for iterators is optional. It's supported if and only if <code>`-()</code> is defined, but even then it's undefined how far back the iterator can move. Therefore iterators may support only a limited amount of backward movement, e.g. when they access a stream through a limited buffer. If such an iterator is moved back past the limit then it'll behave as if it's pointing entirely outside the data set (see above).</p> <p> An iterator that doesn't support backward movement at all should
autodoc.git/traditional_manual/chapter_21.html:6879:
</dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>predef::get_iterator</code>, <code>lfun::_get_iterator</code>, <code>Array.Iterator</code>, <code>Mapping.Iterator</code>, <code>Multiset.Iterator</code>, <code>String.Iterator</code>, <code>String.SplitIterator</code>.</p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>_iterator_index</b></span>
+
</dt>
+
<dd><p><code><code class='datatype'>mixed</code> <b><span class='method'>_iterator_index</span>(</b><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Returns the current index, or <code>UNDEFINED</code> if the iterator
+
doesn't point to any item.</p>
+
<p> If there's no obvious index set then the index is the current
+
position in the data set, counting from <code class='expr'>0</code> (zero).</p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>_iterator_next</b></span>
+
</dt>
+
<dd><p><code><code class='datatype'>int</code> <b><span class='method'>_iterator_next</span>(</b><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>If this function is defined it should advance the iterator one
+
step, just like <code class='expr'><code>`+=</code>(1)</code> would do.</p>
+
</dd>
+
<dt class='head--doc'>Note</dt>
+
<dd class='body--doc'><p>This is the preferred way to advance the iterator, since it
+
reduces the overhead.</p>
+
</dd>
+
<dt class='head--doc'>Note</dt>
+
<dd class='body--doc'><p>This function was optional in Pike 7.6 and earlier.</p>
+
</dd>
+
<dt class='head--doc'>Returns</dt>
+
<dd class='body--doc'><p>Returns <tt>1</tt> if it succeeded in advancing, and
+
<tt>0</tt> (zero) if it has reached the end of the iterator.</p>
+
</dd>
+
<dt class='head--doc'>See also</dt>
+
<dd class='body--doc'><p><code>`+</code>, <code>`+=</code>, <code>`-</code></p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>_iterator_value</b></span>
+
</dt>
+
<dd><p><code><code class='datatype'>mixed</code> <b><span class='method'>_iterator_value</span>(</b><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Returns the current value, or <code>UNDEFINED</code> if the iterator
+
doesn't point to any item.</p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
<span class='homogen--name'><b>_random</b></span> </dt> <dd><p><code><code class='datatype'>void</code> <b><span class='method'>random</span>(</b> <span class='class'>Iterator</span> <span class='argument'>arg</span> <b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>If this function is defined then it sets the iterator to point to a random item in the accessible set. The random distribution should be rectangular within that set, and the pseudorandom sequence provided by <code>random</code> should be used.</p> </dd></dl>
autodoc.git/traditional_manual/chapter_21.html:6932:
</dt> <dd><p><code><code class='object unresolved'>Iterator</code> res = <code class='class'>Iterator()</code> + <code class='class'>steps</code></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Returns a clone of this iterator which is advanced the specified number of steps. The amount may be negative to move backwards. If the iterator doesn't support backward movement it should throw an exception in that case.</p> </dd> <dt class='head--doc'>See also</dt>
-
<dd class='body--doc'><p><code>next</code>, <code>`+=</code>, <code>`-</code></p>
+
<dd class='body--doc'><p><code>
_iterator_
next</code>, <code>`+=</code>, <code>`-</code></p>
</dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>`+=</b></span> </dt> <dd><p><code><code class='class'>Iterator()</code> += <code class='class'>steps</code></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Advance this iterator the specified number of steps and return it. The amount may be negative to move backwards. If the iterator doesn't support backward movement it should throw an exception in that case.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p><code>foreach</code> calls this function with a step value of <code class='expr'>1</code>
-
if <code>next()</code> doesn't exist for compatibility with Pike 7.6
+
if <code>
_iterator_
next()</code> doesn't exist for compatibility with Pike 7.6
and earlier.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p><code>foreach</code> will call this function even when the the iterator has more than one reference. If you want to loop over a copy of the iterator, you can create a copy by adding <code class='expr'>0</code> (zero) to it:</p> <pre><code>Iterator iterator<span class='delim'>;</span> ... <span class='lang'>foreach</span><span class='delim'>(</span>iterator<span class='delim'>+</span>0<span class='delim'>;</span> <span class='type'>mixed</span> index<span class='delim'>;</span> <span class='type'>mixed</span> value<span class='delim'>)</span> <span class='delim'>{</span> ... <span class='delim'>}</span> </code></pre> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>Even though this function is sufficient for <code>foreach</code> to
-
advance the iterator, <code>next()</code> is the preferred API.
-
<
code>next()<
/
code> has the additional advantage of not being an
-
lfun, so it is possible to advance the iterator by hand.</
p>
+
advance the iterator, <code>
_iterator_
next()</code> is the preferred API.</p>
</dd> <dt class='head--doc'>See also</dt>
-
<dd class='body--doc'><p><code>next</code>, <code>`+</code>, <code>`-</code></p>
+
<dd class='body--doc'><p><code>
_iterator_
next</code>, <code>`+</code>, <code>`-</code></p>
</dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>`-</b></span> </dt> <dd><p><code><code class='object unresolved'>Iterator</code> res = <code class='class'>Iterator()</code> - <code class='class'>steps</code></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>This lfun should be defined if and only if the iterator supports backward movement to some degree. It should back up the specified number of steps. The amount may be negative to move forward.</p> </dd> <dt class='head--doc'>See also</dt>
-
<dd class='body--doc'><p><code>next</code>, <code>`+</code>, <code>`+=</code></p>
+
<dd class='body--doc'><p><code>
_iterator_
next</code>, <code>`+</code>, <code>`+=</code></p>
</dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>create</b></span> </dt> <dd><p><code><span class='object'>Iterator</span> <span class='class'>Iterator</span><b>(</b><code class='datatype'>void</code>|<code class='datatype'>mixed</code> <code class='argument'>data</code><b>)</b></code></p></dd>
autodoc.git/traditional_manual/chapter_21.html:7040:
<dd class='body--doc'><p>It's not enough to set the iterator to the earliest accessible item. If the iterator doesn't support backing up to the original start position then this function should not be implemented.</p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
-
<span class='homogen--name'><b>index</b></span>
-
</dt>
-
<dd><p><code><code class='datatype'>mixed</code> <b><span class='method'>index</span>(</b><b>)</b></code></p></dd>
-
-
<dt class='head--doc'>Description</dt>
-
<dd class='body--doc'><p>Returns the current index, or <code>UNDEFINED</code> if the iterator
-
doesn't point to any item.</p>
-
<p> If there's no obvious index set then the index is the current
-
position in the data set, counting from <code class='expr'>0</code> (zero).</p>
-
</dd></dl>
-
-
-
<hr />
-
<dl class='group--doc'>
-
<dt class='head--type'><span class='homogen--type'>Method</span>
-
<span class='homogen--name'><b>next</b></span>
-
</dt>
-
<dd><p><code><code class='datatype'>int</code> <b><span class='method'>next</span>(</b><b>)</b></code></p></dd>
-
-
<dt class='head--doc'>Description</dt>
-
<dd class='body--doc'><p>If this function is defined it should advance the iterator one
-
step, just like <code class='expr'><code>`+=</code>(1)</code> would do.</p>
-
</dd>
-
<dt class='head--doc'>Note</dt>
-
<dd class='body--doc'><p>This is the preferred way to advance the iterator, since it
-
reduces the overhead.</p>
-
</dd>
-
<dt class='head--doc'>Note</dt>
-
<dd class='body--doc'><p>This function was optional in Pike 7.6 and earlier.</p>
-
</dd>
-
<dt class='head--doc'>Returns</dt>
-
<dd class='body--doc'><p>Returns <tt>1</tt> if it succeeded in advancing, and
-
<tt>0</tt> (zero) if it has reached the end of the iterator.</p>
-
</dd>
-
<dt class='head--doc'>See also</dt>
-
<dd class='body--doc'><p><code>`+</code>, <code>`+=</code>, <code>`-</code></p>
-
</dd></dl>
-
-
-
<hr />
-
<dl class='group--doc'>
-
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>set_index</b></span> </dt> <dd><p><code><code class='modifier'>optional</code> <code class='datatype'>void</code> <b><span class='method'>set_index</span>(</b><code class='datatype'>zero</code> <code class='argument'>index</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>If this function is defined it should set the iterator at the specified index.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>It should be possible to set the index at the end of the iterator.</p> </dd></dl>
-
-
-
<hr />
-
<dl class='group--doc'>
-
<dt class='head--type'><span class='homogen--type'>Method</span>
-
<span class='homogen--name'><b>value</b></span>
-
</dt>
-
<dd><p><code><code class='datatype'>mixed</code> <b><span class='method'>value</span>(</b><b>)</b></code></p></dd>
-
-
<dt class='head--doc'>Description</dt>
-
<dd class='body--doc'><p>Returns the current value, or <code>UNDEFINED</code> if the iterator
-
doesn't point to any item.</p>
-
</dd></dl>
+
</dd></dl><dl><dt><h2 class='header'>Class <b class='ms datatype'>MasterObject</b></h2> </dt><dd><dl class='group--doc'> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Master control program for Pike.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>predef::master()</code>, <code>predef::replace_master()</code></p> </dd></dl> <hr />