NAME

Role::TinyCommons::Iterator - A basic iterator

VERSION

This document describes version 0.001 of Role::TinyCommons::Iterator (from Perl distribution Role-TinyCommons-Iterator), released on 2021-04-18.

SYNOPSIS

In your class:

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

 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. For a bidirectional iterator, see Role::TinyCommons::Iterator::Bidirectional. For a resettable, see Role::TinyCommons::Iterator::Resettable.

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

Currently none.

HOMEPAGE

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

SOURCE

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

BUGS

Please report any bugs or feature requests on the bugtracker website https://github.com/perlancar/perl-Role-TinyCommons-Iterator/issues

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.

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. Both exception-based and undef-based signalling of out of items are provided for convenience. The "StopIteration" name comes from Python.

AUTHOR

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2021 by 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.

cpanm Role::TinyCommons::Iterator

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