#                Caches the first value of the iterator in %next_value_for.

##</code><code>##

    # Notes:         Keeps one forward-looking value for the iterator in
    #                   %next_value_for.  This is so we have something to
    #                   return when user's code throws Am_Now_Exhausted.

##</code><code>##

When you use an iterator in separate parts of your program, or as an argument to the various iterator functions, you do not get a copy of the iterator's stream of values.

In other words, if you grab a value from an iterator, then some other part of the program grabs a value from the same iterator, you will be getting different values.

This can be confusing if you're not expecting it. For example:

    my $it_one = Iterator->new ({something});
    my $it_two = some_iterator_transformation $it_one;
    my $value  = $it_two->value();
    my $whoops = $it_one->value;
Here, some_iterator_transformation takes an iterator as an argument, and returns an iterator as a result. When a value is fetched from $it_two, it internally grabs a value from $it_one (and presumably transforms it somehow). If you then grab a value from $it_one, you'll get its second value (or third, or whatever, depending on how many values $it_two grabbed), not the first.