data/TWiki/TWikiListIteratorDotPm.txt
changeset 0 414e01d06fd5
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/data/TWiki/TWikiListIteratorDotPm.txt	Sat Jan 26 15:50:53 2008 +0100
     1.3 @@ -0,0 +1,56 @@
     1.4 +---+ Package =TWiki::ListIterator=
     1.5 +
     1.6 +Iterator over a list
     1.7 +
     1.8 +
     1.9 +%TOC%
    1.10 +
    1.11 +---++ new(\@list)
    1.12 +
    1.13 +Create a new iterator over the given list. Designed primarily for operations
    1.14 +over fully defined lists of object references. The list is not damaged in
    1.15 +any way.
    1.16 +
    1.17 +
    1.18 +---++ hasNext() -> $boolean
    1.19 +
    1.20 +Returns false when the iterator is exhausted.
    1.21 +
    1.22 +<verbatim>
    1.23 +my $it = new TWiki::ListIterator(\@list);
    1.24 +while ($it->hasNext()) {
    1.25 +   ...
    1.26 +</verbatim>
    1.27 +
    1.28 +
    1.29 +---++ next() -> $data
    1.30 +
    1.31 +Return the next entry in the list.
    1.32 +
    1.33 +The iterator object can be customised to pre- and post-process entries from
    1.34 +the list before returning them. This is done by setting two fields in the
    1.35 +iterator object:
    1.36 +
    1.37 +   * ={filter}= can be defined to be a sub that filters each entry. The entry
    1.38 +     will be ignored (next() will not return it) if the filter returns false.
    1.39 +   * ={process}= can be defined to be a sub to process each entry before it
    1.40 +     is returned by next. The value returned from next is the value returned
    1.41 +     by the process function.
    1.42 +
    1.43 +For example,
    1.44 +<verbatim>
    1.45 +my @list = ( 1, 2, 3 );
    1.46 +
    1.47 +my $it = new TWiki::ListIterator(\@list);
    1.48 +$it->{filter} = sub { return $_[0] != 2 };
    1.49 +$it->{process} = sub { return $_[0] + 1 };
    1.50 +while ($it->hasNext()) {
    1.51 +    my $x = $it->next();
    1.52 +    print "$x, ";
    1.53 +}
    1.54 +</verbatim>
    1.55 +will print
    1.56 +<verbatim>
    1.57 +2, 4
    1.58 +</verbatim>
    1.59 +