NAME

    Array::Circular - Provide an array data structure that can go around in
    circles.

 DESCRIPTION

    Circular array, tracks how many times it's been round.

 SYNOPSIS

        my $l = Array::Circular->new(qw/once upon a time there was/);
        my $current = $l->next;
        say "They are the same" if $current eq $l->current;
        my $first = $l->previous;
        say "Also the same" if $first eq $l->current;
        say "We went around the loop " . $l->loops . " times";

 METHODS

  new

        my $l = Array::Circular->new(qw/this is a test/);

  clone

        my $new = $l->clone;

  next

        my $element     = $l->next;
        my $two_forward = $l->next(2);
        my $two_back    = $l->next(-2);

  previous / prev

        my $element     = $l->previous;
        my $two_back    = $l->previous(2);
        my $two_forward = $l->previous(-2);

  current / curr

        my $element = $l->current;

  index

        my $idx = $l->index;
        $idx    = $l->index(3);

    Gets or sets the current index. Always returns the value of the current
    index. Does not reset the loop counter. No validation is performed.

  loops

        my $number_of_times_been_around = $l->loops
        $l->loops(-3);

    The loops method keeps track of how many times the array has been
    around. Looping forwards increases the loop count. Looping back
    decreases it. Sending in a number will set the counter but beware, no
    validation is performed on set operations.

  reset

        $l->reset

    Resets the current index and loop count to 0.

   me

        my $internal_store = $l->me

    This is the internal store that tracks the current state of the list.
    It's intended for internal use only.

   current_and_next / curr_and_next

    Convenience method to return current value then proceed next. Same
    interface as next.

   current_and_previous / curr_and_prev

    Convenience method to return current value then proceed previous. Same
    interface as previous.

   peek

    Peek n forward (defaults to 1). Take care if you're reliant on
    calculating the number of loops as part of this. This Returns the entry
    for each without updating the value of loops.

   size

    Returns the number of elements in the list.

 GOTCHAS

    Some array modification operations are supported. For example splice,
    push and pop operations are untested. If you mutate the array you may
    consider using reset, loops and index to fix up the effects of your
    mutation.

 IMPLEMENTATION NOTES

    This module is implemented as an inside out object.

 SEE ALSO

    Array::Iterator::Circular provides similar functionality but it does
    not support previous. Array::Iterator contains a survey of various
    similar modules.

 TODO

    Not thread safe. See implementation of Hash::MultiValue for
    implementation of thread safety. Alternatively use
    Hash::Util::FieldHash or Hash::Util::FieldHash::Compat.

 AUTHOR COPYRIGHT AND LICENSE

    Copyright 2018 Kieren Diment zarquon@cpan.org. This software can be
    redistributed under the same terms as perl itself.