Skip to content

Commit

Permalink
Fix #80942: Object iteration / Iterator: Replace duplicated examples …
Browse files Browse the repository at this point in the history 
…with direct links

* Object iteration / Iterator: Replace duplicated examples with direct links to the appropriate sections and add cross-links.

Closes GH-517.
  • Loading branch information
@AllenJB
AllenJB committed Apr 20, 2021
1 parent e994a8d commit 1fb0ef2
Show file tree
Hide file tree
Showing 4 changed files with 28 additions and 178 deletions.
10 changes: 10 additions & 0 deletions language/generators.xml
View file
Expand Up @@ -593,6 +593,16 @@ class LineIterator implements Iterator {
means that the same generator can't be iterated over multiple times: the
generator will need to be rebuilt by calling the generator function again.
</para>

<simplesect role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><link linkend="language.oop5.iterations">Object Iteration</link></member>
</simplelist>
</para>
</simplesect>

</sect1>
</chapter>

Expand Down
187 changes: 9 additions & 178 deletions language/oop5/iterations.xml
View file
Expand Up @@ -69,187 +69,18 @@ private => private var
<link linkend="language.oop5.visibility">visible</link> properties that could be
accessed.
</para>
<para>
To take it a step further, the <interfacename>Iterator</interfacename>
<link linkend="language.oop5.interfaces">interface</link> may be implemented.
This allows the object to dictate how it will be iterated and what values will
be available on each iteration.
</para>

<example>
<title>Object Iteration implementing Iterator</title>
<programlisting role="php">
<![CDATA[
<?php
class MyIterator implements Iterator
{
private $var = array();
public function __construct($array)
{
if (is_array($array)) {
$this->var = $array;
}
}
public function rewind()
{
echo "rewinding\n";
reset($this->var);
}
public function current()
{
$var = current($this->var);
echo "current: $var\n";
return $var;
}
public function key()
{
$var = key($this->var);
echo "key: $var\n";
return $var;
}
public function next()
{
$var = next($this->var);
echo "next: $var\n";
return $var;
}
public function valid()
{
$key = key($this->var);
$var = ($key !== NULL && $key !== FALSE);
echo "valid: $var\n";
return $var;
}
}
$values = array(1,2,3);
$it = new MyIterator($values);
foreach ($it as $a => $b) {
print "$a: $b\n";
}
?>
]]>
</programlisting>
&example.outputs;
<screen role="php">
<![CDATA[
rewinding
valid: 1
current: 1
key: 0
0: 1
next: 2
valid: 1
current: 2
key: 1
1: 2
next: 3
valid: 1
current: 3
key: 2
2: 3
next:
valid:
]]>
</screen>

</example>

<simplesect role="seealso">
&reftitle.seealso;
<para>
The <interfacename>IteratorAggregate</interfacename>
<link linkend="language.oop5.interfaces">interface</link>
can be used as an alternative to implementing all of the
<interfacename>Iterator</interfacename> methods.
<interfacename>IteratorAggregate</interfacename> only requires the
implementation of a single method,
<methodname>IteratorAggregate::getIterator</methodname>, which should return
an instance of a class implementing <interfacename>Iterator</interfacename>.
<simplelist>
<member><link linkend="language.generators">Generators</link></member>
<member><interfacename>Iterator</interfacename></member>
<member><interfacename>IteratorAggregate</interfacename> </member>
<member><link linkend="spl.iterators">SPL Iterators</link></member>
</simplelist>
</para>

<example>
<title>Object Iteration implementing IteratorAggregate</title>
<programlisting role="php">
<![CDATA[
<?php
class MyCollection implements IteratorAggregate
{
private $items = array();
private $count = 0;
// Required definition of interface IteratorAggregate
public function getIterator() {
return new MyIterator($this->items);
}
public function add($value) {
$this->items[$this->count++] = $value;
}
}
$coll = new MyCollection();
$coll->add('value 1');
$coll->add('value 2');
$coll->add('value 3');
foreach ($coll as $key => $val) {
echo "key/value: [$key -> $val]\n\n";
}
?>
]]>
</programlisting>
&example.outputs;
<screen role="php">
<![CDATA[
rewinding
current: value 1
valid: 1
current: value 1
key: 0
key/value: [0 -> value 1]
next: value 2
current: value 2
valid: 1
current: value 2
key: 1
key/value: [1 -> value 2]
next: value 3
current: value 3
valid: 1
current: value 3
key: 2
key/value: [2 -> value 3]
next:
current:
valid:
]]>
</screen>

</example>

<note>
<para>
For more examples of iterators, see the
<link linkend="spl.iterators">SPL Extension</link>.
</para>
</note>

<note>
<para>
<link linkend="language.generators">Generators</link> provide an
alternative way of defining iterators.
</para>
</note>
</simplesect>

</sect1>
<!-- Keep this comment at the end of the file
Expand Down
5 changes: 5 additions & 0 deletions language/predefined/generator.xml
View file
Expand Up @@ -52,6 +52,11 @@

</section>

<section xml:id="generator.seealso">
&reftitle.seealso;
<para>See also <link linkend="language.oop5.iterations">object iteration</link>.</para>
</section>

</partintro>

&language.predefined.generator.current;
Expand Down
4 changes: 4 additions & 0 deletions language/predefined/iterator.xml
View file
Expand Up @@ -142,6 +142,10 @@ string(17) "myIterator::valid"
</example><!-- }}} -->
</section>

<section xml:id="iterator.seealso">
&reftitle.seealso;
<para>See also <link linkend="language.oop5.iterations">object iteration</link>.</para>
</section>

</partintro>

Expand Down

0 comments on commit 1fb0ef2

Please sign in to comment.