File Coverage

blib/lib/Array/Iterator/Circular.pm

Criterion	Covered	Total	%
statement	31	31	100.0
branch	2	2	100.0
condition			n/a
subroutine	12	12	100.0
pod	5	8	62.5
total	50	53	94.3

package Array::Iterator::Circular;

use strict;
use warnings;

use Array::Iterator;

# AUTHORITY
# DATE
# DIST

=head1 VERSION

Version 0.136

=cut

our $VERSION = '0.136';

our @ISA = qw(Array::Iterator);

=head1 SYNOPSIS

  use Array::Iterator::Circular;

  # create an instance with a
  # small array
  my $color_iterator = Array::Iterator::Circular->new(qw(red green blue orange));

  # this is a large list of
  # arbitrary items
  my @long_list_of_items = ( ... );

  # as we loop through the items ...
  foreach my $item (@long_list_of_items) {
      # we assign color from our color
      # iterator, which will keep dispensing
      # as it loops through its set
      $item->set_color($color_iterator->next());
  }

  # tell us how many times the set
  # was looped through
  print $color_iterator->get_loop_count();

=head1 DESCRIPTION

This iterator will loop continuosly as long as C or C is called. The C method will always return true (C<1>), since the list will always loop back. This is useful when you need a list to repeat itself, but don't want to (or care to) know that it is doing so.

=head1 METHODS

This is a subclass of Array::Iterator, only those methods that have been added or altered are documented here, refer to the Array::Iterator documentation for more information.

=over 4

=item B

Since we endlessly loop, this will always return true (C<1>).

=item B

This will return the next item in the array, and when it reaches the end of the array, it will loop back to the beginning again.

=item B

This method is now defined in terms of C, since neither will even stop dispensing items, there is no need to differentiate.

=item B

If at anytime during your looping, you want to know if you have arrived back at the start of you list, you can ask this method.

=item B

If at anytime during your looping, you want to know if you have gotten to the end of you list, you can ask this method.

=item B

This method will tell you how many times the iterator has looped back to its start.

=back

=cut

sub _init {
	my ($self, $length, @args) = @_;

	$self->{loop_counter} = 0;
	$self->SUPER::_init($length, @args);
}

# always return true, since
# we just keep looping
sub has_next { 1 }

sub next {
	my $self = $_[0];

	unless ($self->_current_index < $self->getLength()) {
		$self->_current_index = 0;
		$self->{loop_counter}++;
	}
	$self->_iterated = 1;
	return $self->_getItem($self->_iteratee(), $self->_current_index++);
}

# since neither of them will
# ever stop dispensing items
# they can just be aliases of
# one another.
*get_next = \&next;

sub is_start {
	my $self = $_[0];

	return ($self->_current_index() == 0);
}

sub isStart { my $self = shift; $self->is_start(@_) }

sub is_end {
	my $self = $_[0];

	return ($self->_current_index() == $self->getLength());
}

sub isEnd { my $self = shift; $self->is_end(@_) }

sub get_loop_count {
	my $self = $_[0];

	return $self->{loop_counter};
}

sub getLoopCount { my $self = shift; $self->get_loop_count(@_) }

1;


=head1 SEE ALSO

This is a subclass of B, please refer to it for more documentation.

=head1 MAINTAINER

Nigel Horne, C<<  >>

2025-2026

=head1 ORIGINAL AUTHOR

stevan little, [e-mail]

=head1 ORIGINAL COPYRIGHT AND LICENSE

Copyright 2004 by Infinity Interactive, Inc.

L

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

=cut