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.