NAME
Array::Tour - Base class for Array Tours.
SYNOPSIS
#
# For a new package. Add extra methods and internal attributes afterwards.
#
package Array::Tour::NewTypeOfTour
use base qw(Array::Tour);
# (Code goes here).or
#
# Make use of the constants in the package.
#
use Array::Tour qw(:directions);
use Array::Tour qw(:status);or
#
# Use Array::Tour for its default 'typewriter' tour of the array.
#
use Array::Tour;
my $by_row = Array::Tour->new(dimensions => [24, 80, 1]);PREREQUISITES
Perl 5.8 or later. This is the version of perl under which this module was developed.
DESCRIPTION
Array::Tour is a base class for iterators that traverse the cells of an array. This class should provide most of the methods needed for any type of tour, whether it needs to visit each cell or not, and whether the tour needs to be a continuous path or not.
The iterator provides coordinates and directions. It does not define the array. This leaves the user of the tour object free to define the form of the array or the data structure behind it without restrictions from the tour object.
By itself without any subclassing or options, the Array::Tour class traverses a simple left-to-right, top-to-bottom typewriter path. There are options to change the direction or rotation of the path.
Tour Object Methods
new([<attribute> => value, ...])
Creates the object with its attributes.
Since attributes are set using the internal method _set(), it's recommended that subclasses do not override new(), but provide their own _set() method to handle their own attributes instead.
Four attributes start out available from the base class, dimensions, offset, position, and start.
These four attributes are automatically set before calling the _set() method:
- dimensions
-
Default value: [1, 1, 1]. Provide the size of the array:
my $spath1 = Array::Tour->new(dimensions => [16, 16, 1]);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:
my $spath1 = Array::Tour->new(dimensions => [16, 16]);This has the exact same effect as the code above it.
In fact the 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.
reset([<attribute> => value, ...])
Reset the object by returning its internal state to its original form. Optionally change some of the characteristics using the same parameters found in the new() method.
has_next()
Returns 1 if there is more to the tour, 0 if finished.
get_dimensions()
Returns an array of the dimensions.
direction()
Returns the current direction as found in the :directions EXPORT tag.
opposite_direction()
Return the direction opposite from the current direction.
say_direction
Return the name in English of the current direction.
direction_name
Return the name in English of the direction passed in.
print $tour->direction_name(NorthWest), " is ", NorthWest, "\n";get_position
Return a reference to an array of coordinates of the current position.
@absolute_pos = @{$self->get_position()};get_offset
Return a reference to an array of offsets to be added to the current position.
@offset = @{$self->get_offset()};adjusted_position
Return a reference to an array of coordinates that are created from the position plus the offset. Used by the next() method.
@current_pos = @{$self->adjusted_position()};next()
Returns an array reference to the next coordinates to use. Returns undef if the iterator is finished.
my $ctr = 1;
my $tour = Array::Tour->new(dimensions => 64);
while (my $cref = $tour->next())
{
my($x_coord, $y_coord, $z_coord) = @{$cref};
$grid[$y_coord, $x_coord] = isprime($ctr++);
}The above example would look like a completed Sieve of Eratothenes in the array @grid.
uses_array
Returns 0 or 1 depending upon whether there's an internal array to return.
get_array
Return a reference to the internally generated array.
$arrayref = $self->get_array()describe()
Returns as a hash the attributes of the tour object. The hash may be used to create a new object.
_set()
Take the parameters provided to new() and use them to set the attributes of the touring object.
_set_dimensions()
my @dims = Array::Tour->new(dimensions => [12, 16]);If the grid is going to be square, a single integer is sufficient:
my @dims = Array::Tour->new(dimensions => 16);In both cases, the dimensions attribute is set with a reference to a three dimensional array. The third dimension is set to 1 if no value is given for it.
Internal Tour Object Methods
Methods expected to be provided by the derived class.
These methods exist in the base class, but don't do much that is useful. The deriving class is expected to override these methods.
Subclassing
Array::Tour keeps track of its state through internal attributes that are sufficient for its purposes. Derived classes will probably need to add their own attributes.
- dimensions
-
Default value: [1, 1, 1]. Passed in via method new() using the dimensions key, which sets it through the set_dimensions() method.
- offset
-
Default value: [0, 0, 0]. The coordinate of the upper left corner. Calls to get_coordinates() will return the position adjusted by the value in
offset. - start
-
Default value: [0, 0, 0]. The starting position of the tour. Set automatically in this class.
- position
-
The current position of the iterator in the array.
There are also internal attributes that are used to control the behavior of an Array::Tour object. These have default values that you may override in your sub-class:
- odometer
-
Starting value: 0. The number of cells visited thus far.
- tourlength
-
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.
- tourstatus
-
Initially set to START. The remaining _tourstatus values (found with the export tag
:status) are TOURING and STOP. - array
-
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.
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:
There may be other tours under development. See the Changes file for more information.
EXPORT
The :directions EXPORT tag will let you use the constants that indicate direction. They are the directions North, NorthEast, East, SouthEast, South, SouthWest, West, and NorthWest.
The :status EXPORT tag has the values for the running state of the iterator.
See Also
AUTHOR
John M. Gamble may be found at <jgamble@cpan.org>