view release on metacpan or  search on metacpan

lib/Array/Tour.pm  view on Meta::CPAN

=head3 _set()

=head3 _uses_array()

=head2 Attributes

Array::Tour keeps track of its state through internal attributes that are
sufficient for its purposes. Derived classes may alter these for their own
purposes and will likely need to add attributes of their own.

=over 4

=item dimensions

I<Default value: [1, 1, 1].>  Set in the method new() using the dimensions
key, which in turn sets it through the set_dimensions() method.

  my $spath1 = Array::Tour->new(dimensions => [16, 16, 1]);
or
  my $spath1 = Array::Tour->new(dimensions => [16, 16]);

The dimensions attribute represents a three-dimensional array, defined by rows,
columns, and levels.  If you are interested only in a two-dimensional array,
you don't need to specify the third dimension -- it will be added on for you.

In fact the C<dimensions> attribute is so forgiving that if you are only
interested in a simple square array, this will be sufficient:

  my $spath1 = Array::Tour->new(dimensions => 16);

The attribute will detect the single dimension, duplicate it, and add the
third dimension of 1.  You will have the same dimensions as the previous
examples.

=item offset

I<Default value: [0, 0, 0].> Set in the method new() using the offset
key, which in turn sets it through the _set_offset() method.

Sets the coordinate of the upper left corner of the tour array. Calls to
adjusted_position() (which in turn is called by the next() method) will return
the position adjusted by the value in C<offset>.

=item start

I<Default value: [0, 0, 0].> The starting position of the tour.  Set
automatically in this class.

=item position

The current position of the iterator in the array.

=item odometer

I<Starting value: 0.> The number of cells visited thus far.

=item tourlength

I<Default value: number of cells in the array.> The total number of cells
to visit. This is sometimes used to determine the endpoint of the tour.

=item tourstatus

Initially set to B<START>.  The remaining _tourstatus values (found with
the export tag C<:status>) are B<TOURING> and B<STOP>.

=item array

I<default value: undef.>  A reference to an internal array.  Some sub-classes
need an internal array for bookkeeping purposes.  This is where it will go.
The method _make_array() will create an internal array for a sub-class if it is
needed.

=back

=head2 Current Tours

This, the base class, performs a typewriter left-to-right tour of the array. If
the array has a third dimension, it will go to the next level after completing
the tour of the rows of the current level.

The subclasses that come with this package are:

L<Spiral|Array::Tour::Spiral>

L<Serpentine|Array::Tour::Serpentine>

L<RandomWalk|Array::Tour::RandomWalk>

There may be other tours under development. See the Changes file for more
information.

=head2 EXPORT

The :directions tag will let you use the constants that indicate
direction. They are the directions C<North>, C<NorthEast>, C<East>,
C<SouthEast>, C<South>, C<SouthWest>, C<West>, C<NorthWest>, C<Ceiling>,
C<Floor>, and C<SetPosition>, which indicates a directionless change in
position.

The :status tag has the values for the running state of the iterator.

=head2 See Also

L<Array::Iterator|Array::Iterator>

=head1 AUTHOR

John M. Gamble may be found at <jgamble@cpan.org>

=cut