File Coverage

blib/lib/ArrayHashSearch.pm

Criterion	Covered	Total	%
statement	64	75	85.3
branch	34	50	68.0
condition	26	51	50.9
subroutine	7	8	87.5
pod	5	5	100.0
total	136	189	71.9

package ArrayHashSearch;

=head1 NAME

ArrayHashSearch - Search utility for arrays and hashes in Perl.

=cut

use warnings;
use strict;
use vars qw($VERSION @EXPORT @EXPORT_OK @ISA);
require Exporter;

@ISA = qw(Exporter);
$VERSION = '0.04';
@EXPORT = qw(array_contain array_deeply_contain hash_contain hash_deeply_contain deeply_contain);

=head1 Features

=head2 array_contain

  this routine searches the given array for the given scalar value and stops at the first value match found
  parameters:
  returns 1 if an element with the given scalar value was found else 0

=cut

sub array_contain
{
   my $sourcearrayref = shift @_;
   my $targetscalar = shift @_;
   die "\nBad arguments for subroutine 'array_contains': firstly an array reference and secondly a scalar are required!\n"
   unless ((ref $sourcearrayref eq "ARRAY") and (defined ($targetscalar) and not ref($targetscalar)));
   my $found = 0;
   #search for the given scalar in first dimension only
   foreach (sort @$sourcearrayref) #sort routine moves scalar elements to the beginning of array
   {
      if ($_ eq $targetscalar)
      {
         $found = 1;
         last;
      }
   }
   return $found;
}

=head2 array_deeply_contain

  this routine searches the given array and any hierarchy of referenced arrays for the given scalar value and stops at the first value match found
  parameters:
  returns 1 if an element with the given scalar value was found else 0

=cut

sub array_deeply_contain
{
   my $sourcearrayref = shift @_;
   my $targetscalar = shift @_;
   die "\nBad arguments for subroutine 'array_contains_recursive': firstly an array reference and secondly a scalar are required!\n"
   unless ((ref $sourcearrayref eq "ARRAY") and (defined ($targetscalar) and not ref($targetscalar)));
   my $found = 0;
   #search for the given scalar in first dimension
   foreach (sort @$sourcearrayref) #sort routine moves scalar elements to the beginning of array
   {
      if (not ref($_) and ($_ eq $targetscalar))
      {
         return 1;
      }
   }
   #if not found yet, search for other dimensions (pointed to by references)
   foreach (reverse sort @$sourcearrayref) #sort and reverse move references to the beginning of array
   {
      if (ref $_)
      {
         die "\nArrays with references to non arrays are not supported only 'pure' multi-dimensional arrays!\n"
         unless (ref $_ eq "ARRAY");
         $found = array_deeply_contain($_,$targetscalar);
         return 1 if ($found);
      }
   }
   return $found;
}

=head2 hash_contain

  this routine searches the given hash for the given scalar value and stops at the first value match found
  parameters:
  returns 1 if an element with the given scalar value was found else 0

=cut

sub hash_contain
{
   my $sourcehashref = shift @_;
   my $targetscalar = shift @_;
   die "\nBad arguments for subroutine 'hash_contains': firstly a hash reference and secondly a scalar are required!\n"
   unless ((ref $sourcehashref eq "HASH") and (defined ($targetscalar) and not ref($targetscalar)));
   my $found = 0;
   #search for the given scalar in first dimension only
   foreach (sort values %$sourcehashref) #sort routine moves scalar elements to the beginning of hash
   {
      if ($_ eq $targetscalar)
      {
         $found = 1;
         last;
      }
   }
   return $found;
}

=head2 hash_deeply_contain

  this routine searches the given hash and any hierarchy of referenced hashes for the given scalar value and stops at the first value match found
  parameters:
  returns 1 if an element with the given scalar value was found else 0

=cut

sub hash_deeply_contain
{
   my $sourcehashref = shift @_;
   my $targetscalar = shift @_;
   die "\nBad arguments for subroutine 'hash_contains_recursive': firstly a hash reference and secondly a scalar are required!\n"
   unless ((ref $sourcehashref eq "HASH") and (defined ($targetscalar) and not ref($targetscalar)));
   my $found = 0;
   #search for the given scalar in first dimension
   foreach (sort values %$sourcehashref) #sort routine moves scalar elements to the beginning of hash
   {
      if (not ref($_) and ($_ eq $targetscalar))
      {
         return 1;
      }
   }
   #if not found yet, search for other dimensions (pointed to by references)
   foreach (reverse sort values %$sourcehashref) #sort and reverse move references to the beginning of hash
   {
      if (ref $_)
      {
         die "\nHashes with references to non hashes are not supported only 'pure' multi-dimensional hashes!\n"
         unless (ref $_ eq "HASH");
         $found = hash_deeply_contain($_,$targetscalar);
         return 1 if ($found);
      }
   }
   return $found;
}

=head2 deeply_contain

  this routine searches the given hash/array and any hierarchy of referenced hashes/arrays for the given scalar value and stops at the first value match found
  this routine should be used for mixed data structures of arrays and hashes.
  parameters:
  returns 1 if an element with the given scalar value was found else 0

=cut

sub deeply_contain
{
   my $sourcestructureref = shift @_;
   my $targetscalar = shift @_;
   die "\nBad arguments for subroutine 'structure_contains_recursive': firstly a hash or array reference and secondly a scalar are required!\n"
   unless (((ref $sourcestructureref eq "HASH") or (ref $sourcestructureref eq "ARRAY")) and (defined ($targetscalar) and not ref($targetscalar)));
   my $found = 0;
   if (ref $sourcestructureref eq "HASH") #case of a hash
   {
      #search for the given scalar in first dimension
      foreach (sort values %$sourcestructureref) #sort routine moves scalar elements to the beginning of hash
      {
         if (not ref($_) and ($_ eq $targetscalar))
         {
            return 1;
         }
      }
      #if not found yet, search for other dimensions (pointed to by references)
      foreach (reverse sort values %$sourcestructureref) #sort and reverse move references to the beginning of hash
      {
         if (ref $_)
         {
            die "\nReferences to something else than hashes or arrays are invalid!\n"
            unless ((ref $_ eq "HASH") or (ref $_ eq "ARRAY"));
            $found = deeply_contain($_,$targetscalar);
            return 1 if ($found);
         }
      }
   }
   elsif (ref $sourcestructureref eq "ARRAY") #case of an array
   {
      #search for the given scalar in first dimension
      foreach (sort @$sourcestructureref) #sort routine moves scalar elements to the beginning of array
      {
         if (not ref($_) and ($_ eq $targetscalar))
         {
            return 1;
         }
      }
   #if not found yet, search for other dimensions (pointed to by references)
      foreach (reverse sort @$sourcestructureref) #sort and reverse move references to the beginning of array
      {
         if (ref $_)
         {
            die "\nReferences to something else than hashes or arrays are invalid!\n"
            unless ((ref $_ eq "HASH") or (ref $_ eq "ARRAY"));
            $found = deeply_contain($_,$targetscalar);
            return 1 if ($found);
         }

      }
   }
   return $found;
}

1;
__END__