NAME

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

DESCRIPTION

This is an object class for Module::Generic::Iterator::Element objects as returned by various methods of Module::Generic::Iterator.

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.

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.

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.

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

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.

cpanm Module::Generic

perl -MCPAN -e shell
install Module::Generic