- NAME
- Features

- array_contain
- array_deeply_contain
- hash_contain
- hash_deeply_contain
- deeply_contain

- Synopsis
- Description
- Bugs and Caveats
- Author
- Copyright
- History

# NAME

ArrayHashSearch - Search utility for arrays and hashes in Perl.

# Features

## array_contain

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

## 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: <array reference> <scalar>
      returns 1 if an element with the given scalar value was found else 0

## hash_contain

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

## 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: <hash reference> <scalar>
      returns 1 if an element with the given scalar value was found else 0

## 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: <reference to an array or a hash> <scalar>
      returns 1 if an element with the given scalar value was found else 0

# Synopsis

      use ArrayHashSearch;
      my $dummyarrayref = [1,3,7,11,13,17,19,23];
      my $dummyarrayref2 = ['a','c','z',$dummyarrayref];

      if (array_contain($dummyarrayref,7))
      {
        print "Value 7 exists in the array!";
      }
      if (array_deeply_contain($dummyarrayref2,7))
      {
        print "Value 7 exists in the array!";
      }

      A more complex example:

      use strict;
      use warnings;
      use ArrayHashSearch;

      my $dummyarray1 = [1,2,3];
      my $dummyarray2 = [4,5,$dummyarray1];
      my $dummyarray3 = [7,$dummyarray2,9];
      my $dummyhash1 = {1=>'a',2=>'b',3=>'c'};
      my $dummyhash2 = {1=>$dummyhash1,2=>'d',3=>'e'};
      my $dummyhash3 = {1=>'f',2=>'g',3=>$dummyhash2};
      my $dummystructure1 = [1=>$dummyhash3,2=>$dummyarray3,3=>10];
      my $dummystructure2 = {1=>'h',2=>$dummystructure1,3=>'i'};

      print "ARRAY BINGO!\n" if array_deeply_contain($dummyarray3,5);
      print "HASH BINGO!\n" if hash_deeply_contain($dummyhash3,'a');
      print "ARRAY/HASH BINGO!\n" if deeply_contain($dummystructure1,5);
      print "HASH/ARRAY BINGO!\n" if deeply_contain($dummystructure2,'a');

# Description

      This module provides routines to search content of n-dimensional arrays and/or hashes for given values.
      These routines are useful for people who often test existence of specific values in complex data structures returned by other routines.
      Since there are currently no such built-in functions to search arrays/hashes, one can save time by using this module.

# Bugs and Caveats

      There no known bugs at this time, but this doesn't mean there are aren't any. Use it at your own risk.
      Note that there may be other bugs or limitations that the author is not aware of.

# Author

      Serge Tsafak <tsafserge2001@yahoo.fr>

# Copyright

      This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

# History

     Version 0.1: created; December 2007