Module:...Element(3)

💖 NAME 💖

Okay so this is the Module:...Element(3) page from the User Contributed Perl Documentation, and it's giving “tiny iterator element object with main character energy.” The actual NAME situation is:

Module::Generic::Iterator::Element - An Array Iterator Element Object Class

---

✨ SYNOPSIS ✨

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  );
}

---

🌈 VERSION 🌈

v0.1.0 — cute, concise, iconic.

---

🦋 DESCRIPTION 🦋

This is an object class for Module::Generic::Iterator::Element objects as returned by various methods of Module::Generic::Iterator. So like, it's the little element object that shows up when you're doing iterator things. Bestie, it's literally the element wrapper. 💅

---

🧸 CONSTRUCTOR 🧸

✨ new ✨

Provided with an array value (whatever that may be) and an optional hash reference of parameters, and this will create a new iterator and return it.

Typical parameters are:

• parent — This is the Module::Generic::Iterator object and it is required. Required required, no cap. 🫶

---

🌸 METHODS 🌸

🌸 has_next 🌸

Returns true if there is a next element relative to this element:

my $first = $iter->first;
if( $first->has_next )
{
    print( "There is a next element\n" );
}

🎀 has_prev 🎀

Returns true if there is a previous element relative to this element:

my $last = $iter->last;
if( $last->has_prev )
{
    print( "There is a previous element\n" );
}

🔥 next 🔥

Returns the next element as a Module::Generic::Iterator::Element object when chaining. In scalar context, returns the element’s value:

my $first = $iter->first;
my $next = $first->next; # Next element
print( $next->value, "\n" ); # Value of next element
my $value = $first->next; # In scalar context, returns the value

Returns undef in scalar context, or an empty list in list context if there are no more element. That's the vibe check: no next element, no value. 💀

🦋 parent 🦋

Sets or gets a Module::Generic::Iterator object as the parent object for this array element.

my $elem = $iter->first;
my $parent = $elem->parent;
$parent->reset;

🌟 pos 🌟

Returns the position of the object in the iterator. This is read-only and returns an integer.

my $elem = $iter->find( "Jack" );
print( $elem->pos, "\n" ); # e.g., 1

💜 prev 💜

Returns the previous element as a Module::Generic::Iterator::Element object when chaining. In scalar context, returns the element’s value:

my $last = $iter->last;
my $prev = $last->prev; # Previous element's value
print( $last->prev->value, "\n" ); # Same (value of previous element)
my $value = $last->prev; # In scalar context, returns the value

Returns undef in scalar context, or an empty list in list context if there are no more element. Same energy as next, just going backwards. 🫶

🍓 value 🍓

Returns the raw value of the element object:

my $elem = $iter->first;
print( $elem->value, "\n" ); # e.g., "John"

---

🎀 SERIALISATION 🎀

Serialisation by CBOR, Sereal and Storable::Improved (or the legacy Storable) is supported by this package. To that effect, the following subroutines are implemented: FREEZE, THAW, STORABLE_freeze and STORABLE_thaw. Bestie, it freezes and thaws. Iconic. 🧚

---

👑 THREAD-SAFETY 👑

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

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 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:

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.

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

---

🫶 AUTHOR 🫶

Jacques Deguest <jack@deguest.jp>

---

💖 COPYRIGHT & LICENSE 💖

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

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

---

okay bye bestie 💅🫶 — this page is from perl v5.42.2, dated 2026-02-15, and lives under Module:...Element(3). ✨