—

              
# -*- Perl -*-
#
# some utility subs for text patterns
package Game::TextPatterns::Util;
our $VERSION = '1.47';
use strict;
use warnings;
use constant { COL => 0, ROW => 1, };
require Exporter;
our @ISA       = qw(Exporter);
our @EXPORT_OK = qw(adj_4way adj_8way);
# NOTE the adj_* functions for speeds do not check if all points lie
# outside the given 0,0,mc,mr bounding box. this may change if this
# proves problematic in practice
sub adj_4way {
    my ($p, $max_col, $max_row) = @_;
    my @adj;
    push @adj, [ $p->[COL] - 1, $p->[ROW] ] unless $p->[COL] <= 0;
    push @adj, [ $p->[COL] + 1, $p->[ROW] ] unless $p->[COL] >= $max_col;
    push @adj, [ $p->[COL], $p->[ROW] - 1 ] unless $p->[ROW] <= 0;
    push @adj, [ $p->[COL], $p->[ROW] + 1 ] unless $p->[ROW] >= $max_row;
    return @adj;
}
sub adj_8way {
    my ($p, $max_col, $max_row) = @_;
    my @adj;
    push @adj, [ $p->[COL] - 1, $p->[ROW] ] unless $p->[COL] == 0;
    push @adj, [ $p->[COL] + 1, $p->[ROW] ] unless $p->[COL] == $max_col;
    push @adj, [ $p->[COL], $p->[ROW] - 1 ] unless $p->[ROW] == 0;
    push @adj, [ $p->[COL], $p->[ROW] + 1 ] unless $p->[ROW] == $max_row;
    push @adj, [ $p->[COL] - 1, $p->[ROW] - 1 ]
      unless $p->[COL] == 0
      or $p->[ROW] == 0;
    push @adj, [ $p->[COL] - 1, $p->[ROW] + 1 ]
      unless $p->[COL] == 0
      or $p->[ROW] == $max_row;
    push @adj, [ $p->[COL] + 1, $p->[ROW] - 1 ]
      unless $p->[COL] == $max_col
      or $p->[ROW] == 0;
    push @adj, [ $p->[COL] + 1, $p->[ROW] + 1 ]
      unless $p->[COL] == $max_col
      or $p->[ROW] == $max_row;
    return @adj;
}
1;
__END__
HideShow 50 lines of Pod
=head1 NAME
Game::TextPatterns::Util - utilities for text pattern generation
=head1 SYNOPSIS
  use Game::TextPatterns::Util qw(adj_4way adj_8way);
  my @adj   = adj_4way([1,1], 7, 7);
  my @diags = adj_8way([1,1], 7, 7);
=head1 DESCRIPTION
See L<Game::TextPatterns> which uses the provided utility
functions. The B<randomly> method might well use these functions
via a callback function.
=head1 FUNCTIONS
=over 4
=item B<adj_4way> I<point> I<max-col> I<max-row>
Given a I<point> that is an array reference C<column, row> (x,y) returns
the points adjancent by compass motion. Note that error checking is
limited in these routines as B<_fill> or such in theory will restrict
input points to lie within the bounding box.
Callers must not assume that the points will be returned in any
particular order; use C<shuffle> or C<rand> to pick from the points
randomly if necessary.
C<max-col, max-row> are array index values so must be C<7,7> for an
8x8 pattern.
=item B<adj_8way> I<point> I<max-col> I<max-row>
Same as B<adj_4way> only returning points by both compass and
diagonal motions.
=back
=head1 Known Issues
Humans are really good at mixing up the col,row (x,y) points with
other forms especially given the different orientation of the
internal pattern. Favor non-square patterns for tests to better
expose such mixups.
=cut