Module:...Iterator(3)

💅 Module::Generic::Iterator(3) — the array iterator that actually slaps

okay bestie, welcome to the User Contributed Perl Documentation for Module::Generic::Iterator(3), and ngl this one's a little icon. it's a whole vibe ✨

🌸 NAME 🌸

Module::Generic::Iterator — an Array Iterator Object Class. that's it, that's the name, she's serving exactly what it says on the tin 🎀

🦋 SYNOPSIS 🦋

here's the whole thing, verbatim, because you're gonna wanna copy-paste this:

    my $i = Module::Generic::Iterator->new( [qw( Joe John Mary )] );
    # or also:
    my $a = Module::Generic::Array->new( [qw( Joe John Mary )] );
    my $i = $a->iterator;
    while( $i->has_next )
    {
        my $elem = $i->next;
        my $value = $elem->value;
        # Get the next element relative to our element
        printf( "Next value is: %s at offset %d\n", $elem->next, $elem->next->pos  );
    }

    # Navigate to a specific element
    my $elem = $iter->find( "Jack" );
    print( "Found Jack at position: ", $elem->pos, "\n" );

    # Use element navigation
    my $first = $iter->first;
    my $next = $first->next; # Returns "Jack" as an element
    print( "Next after John: ", $next->value, "\n" );

⭐ VERSION ⭐

    v1.2.3

💖 DESCRIPTION 💖

so Module::Generic::Iterator gives you a generic iterator interface for strolling through a list of elements, like a lil tour guide for your array. it supports navigating the list with methods like next, prev, first, and last, and it lets you find specific elements with find. every single element in the iterator gets wrapped in a Module::Generic::Iterator::Element object, and that wrapper gives you contextual navigation (like next, prev) relative to its parent iterator. it's giving main character energy for each element, honestly 👑

this class is designed to be lightweight and flexible — it works with any array of values, whether those are scalars, references, or objects. no gatekeeping 💅

🎀 CONSTRUCTORS 🎀

new

creates a new iterator object, the birth of a star ✨ it takes an optional array reference or an Module::Generic::Array object of elements to iterate over, plus an optional hash or hash reference of parameters, and returns the newly instantiated object:

    my $iter = Module::Generic::Iterator->new( [1, 2, 3], debug => 3 );

supported parameters, bestie:

• debug — an integer to enable debugging. peep debug in Module::Generic if you wanna know more.

returns a new Module::Generic::Iterator object 🫶

🔥 METHODS 🔥

elements

returns the underlying array of elements as a Module::Generic::Array object. and each element? a Module::Generic::Iterator::Element object, no cap:

    my $elems = $iter->elements;
    print( $elems->length, "\n" ); # Number of elements

eof

returns true if the iterator is at the end of the list — meaning the current position is the last element or beyond, we've literally run out of road 💀 optionally it takes an element to check its position:

    if( $iter->eof )
    {
        print( "End of iterator\n" );
    }

find

finds an element by value and hands you back its corresponding Module::Generic::Iterator::Element object. if it's not found, you get undef in scalar context, or an empty list in list context — sad girl hours 😭:

    my $elem = $iter->find( "Jack" );
    print( $elem->value, "\n" ) if( $elem ); # "Jack"

for reference values, the comparison is done using refaddr in Scalar::Util. for scalar values, it's plain old string equality (eq). iykyk 🧚

first

moves the iterator to the first element and returns it as a Module::Generic::Iterator::Element object. firsties! 🥇

    my $first = $iter->first;
    print( $first->value, "\n" ); # First element

has_next

returns true if there's a next element in the iterator. the classic loop fuel:

    while( $iter->has_next )
    {
        my $elem = $iter->next;
        print( $elem->value, "\n" );
    }

has_prev

returns true if there's a previous element in the iterator — yes, we can go backwards, we're versatile like that 💅

    $iter->last;
    if( $iter->has_prev )
    {
        my $prev = $iter->prev;
        print( $prev->value, "\n" );
    }

last

moves the iterator to the last element and returns it as a Module::Generic::Iterator::Element object. saving the best for last, literally 💜

    my $last = $iter->last;
    print( $last->value, "\n" ); # Last element

length

returns the number of elements, starting from 1, as a Module::Generic::Number object. yes bestie, counting starts at 1 here, don't come for me 🍓

    print( $iter->length, "\n" ); # e.g., 5

next

moves the iterator to the next element and returns it as a Module::Generic::Iterator::Element object. optionally it takes an element to start from:

    while( my $elem = $iter->next )
    {
        print( $elem->value, "\n" );
    }

returns undef in scalar context, or an empty list in list context, if there are no more elements. the audacity 😭

pos

an lvalue method to get or set the current position in the iterator. returns the position as an integer:

    $iter->pos = 2; # Move to the third element
    my $pos = $iter->pos; # Returns the current position
    print( $iter->pos, "\n" ); # 2

⚠️ heads up: it warns if the position is not an integer. keep it whole, bestie, no decimals in the house 🚫

prev

moves the iterator to the previous element and returns it as a Module::Generic::Iterator::Element object. optionally it takes an element to start from:

    $iter->last;
    my $prev = $iter->prev;
    print( $prev->value, "\n" );

returns undef in scalar context, or an empty list in list context, if there are no previous elements. rewind culture 🌈

reset

resets the iterator position to the beginning (position 0). fresh start, new me 🦋

    $iter->last;
    $iter->reset;
    print( $iter->pos, "\n" ); # 0

returns the iterator object.

_find_pos

provided with an item, this returns its position in the array — or undef if it's not in the array. lowkey the little helper doing the heavy lifting 🙈

🧚 SERIALISATION 🧚

serialisation by CBOR, Sereal and Storable::Improved (or the legacy Storable) is supported by this package. to that effect, these subroutines are implemented: FREEZE, THAW, STORABLE_freeze and STORABLE_thaw. she can be packed up and unpacked, iconic behavior ✨

👑 THREAD-SAFETY 👑

Module::Generic::Iterator is thread-safe for all operations, because it operates on per-object state and does not modify shared resources at runtime. slay 🎀

key considerations for thread-safety:

• Shared Variables

there are no shared variables that are modified at runtime. the global $DEBUG variable (inherited from Module::Generic) is typically set before threads are created, and it is the user's responsibility to ensure thread-safety if it gets modified at runtime:

    use threads;
    local $Module::Generic::Iterator::DEBUG = 0; # Set before threads
    my @threads = map
    {
        threads->create(sub
        {
            my $iter = Module::Generic::Iterator->new( [1, 2, 3] );
            $iter->next; # Thread-safe
        });
    } 1..5;
    $_->join for( @threads );

• Object State

iterator data (e.g. elements, pos, value in Module::Generic::Iterator::Element) is stored per-object, ensuring thread isolation. everyone gets their own lil bubble 🫧

    use threads;
    my @threads = map
    {
        threads->create(sub
        {
            my $iter = Module::Generic::Iterator->new( [1, 2, 3] );
            while( my $elem = $iter->next )
            {
                print( $elem->value, "\n" ); # Thread-safe
            }
        });
    } 1..5;
    $_->join for( @threads );

• Serialisation

serialisation methods (FREEZE, THAW) operate on per-object state, making them thread-safe. periodt 💅

for debugging in threaded environments (depending on your Operating System):

    ls -l /proc/$$/fd  # List open file descriptors

🌈 SEE ALSO 🌈

Module::Generic::Iterator::Element, Module::Generic::Array — go give them a follow, they're the supporting cast and they ate 💖

🌸 AUTHOR 🌸

Jacques Deguest <jack@deguest.jp>

💜 COPYRIGHT & LICENSE 💜

Copyright (c) 2000-2024 DEGUEST Pte. Ltd.

you can use, copy, modify and redistribute this package and associated files under the same terms as Perl itself.

---

and that's the whole page, bestie 🎉 this lil time capsule is perl v5.42.2, dated 2026-02-15, and it's the Module:...Iterator(3) page from the User Contributed Perl Documentation. go forth and iterate, you've got this fr fr 🦋💖