NAME

Role::TinyCommons::Iterator::Basic - A basic iterator

VERSION

This document describes version 0.004 of Role::TinyCommons::Iterator::Basic (from Perl distribution RoleBundle-TinyCommons-Iterator), released on 2021-10-07.

SYNOPSIS

In your class:

package YourClass;
use Role::Tiny;
with 'Role::TinyCommons::Iterator::Basic';

sub new { ... }

# implement required methods
sub get_next_item { ... }
sub try_get_next_item { ... }
sub has_next_item { ... }

In your class user's code:

use YourClass;

my $obj = YourClass->new(...);

# iterate
my @items;
while ($obj->has_next_item) {
    push @items, $obj->get_next_item;
}

DESCRIPTION

This role provides a basic iterator that's unidirectional, non-resettable, and non-circular. For a bidirectional iterator, see Role::TinyCommons::Iterator::Bidirectional. For a resettable iterator, see Role::TinyCommons::Iterator::Resettable. For a circular iterator, see Role::TinyCommons::Iterator::Circular

REQUIRED METHODS

get_next_item

Usage:

while ($obj->has_next_item) {
    push @items, $obj->get_next_item;
}

Get the next item. Must throw an exception (string based, "StopIteration") if there is no more item to get. Usually used with "has_next_item" to check first if there is stil another item to get.

has_next_item

Usage:

while ($obj->has_next_item) {
    push @items, $obj->get_next_item;
}

Check whether iterator has another item.

get_iterator_pos

Usage:

my $pos = $obj->get_iterator_pos;

Return the iterator's current position, which is a non-negative integer. The first item has the position 0.

PROVIDED METHODS

get_coderef_iterator

Usage:

my $iterator = $obj->get_coderef_iterator($dies); # => coderef

Return a coderef that can be called repeatedly to get items. There are two kinds of coderef iterator that can be returned. If $dies is set to to true, will return a code that dies when there is no more item. If $dies is set to false (the default), will return a coderef that does not die but instead returns undef when there is no more item. If you have a collection that has an undef item, you will not be able to tell whether the undef that the coderef iterator returns is a sign of exhaustion of items or is an actual undef item.

Basically this method is just a shortcut for:

if ($dies) {
    return sub { $self->get_next_item };
} else {
    return sub { $self->has_next_item ? $self->get_next_item :
}

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/RoleBundle-TinyCommons-Iterator.

SOURCE

Source repository is at https://github.com/perlancar/perl-RoleBundle-TinyCommons-Iterator.

SEE ALSO

This role is loosely based on Array::Iterator, but the method names have been made with "verb"+"object" naming style to be more verbose and less likely clash with your other methods. The "StopIteration" name comes from Python.

AUTHOR

perlancar <perlancar@cpan.org>

CONTRIBUTING

To contribute, you can send patches by email/via RT, or send pull requests on GitHub.

Most of the time, you don't need to build the distribution yourself. You can simply modify the code, then test via:

% prove -l

If you want to build the distribution (e.g. to try to install it locally on your system), you can install Dist::Zilla, Dist::Zilla::PluginBundle::Author::PERLANCAR, and sometimes one or two other Dist::Zilla plugin and/or Pod::Weaver::Plugin. Any additional steps required beyond that are considered a bug and can be reported to me.

COPYRIGHT AND LICENSE

This software is copyright (c) 2021 by perlancar <perlancar@cpan.org>.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=RoleBundle-TinyCommons-Iterator

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

cpanm RoleBundle::TinyCommons::Iterator

perl -MCPAN -e shell
install RoleBundle::TinyCommons::Iterator