Array::PAT - PHP Array Tools - Perl extension for array functions that are built into PHP.

NAME

Array::PAT - PHP Array Tools - Perl extension for array functions that are built into PHP.

SYNOPSIS

  use Array::PAT;

  @array = @array = qw(foo bar foo bar foo);
  $result = in_array("foo", @array);
  @duplicates_removed = array_unique(@array);
  @merged = array_merge(@array, @duplicates_removed);
  @foo = array_pad(17, 3, @array);
  @shuffled = shuffle(@foo);
  %result = array_count_values(@shuffled);
  ...

DESCRIPTION

This module is designed to give Perl the same array functionality that can be found in PHP. In PHP, hashes are called associative arrays and are treated similarly to numeric arrays. As is such, some of these functions will work with hashes or arrays. Just as The Beatles say:

"And in the end, the love you take,
is equal to the love you make" - "The End", John Lennon/Paul McCartney (1969)

This applies to all functions, unless otherwise noted. If you use pass by value, you will recieve a value back, but if you pass a reference to a hash or value, you will receive a reference back. This is to support backwards compatability, it might be removed in later releases.

FUNCTIONS

array_change_key_case()

%changed = array_change_key_case($case, %hash);
---OR---
$hash_ref = array_change_key_case($case, \%hash);

This function will take a hash and change all keys to either uppercase or lowercase. It will accept a hash or a hash reference. To make the keys uppercase, set $case to 1. To make the keys lowercase, set $case to 0. The function will leave number indices as is.

array_chunk()

@return = array_chunk($size, @array);
---OR---
$reference = array_chunk($size, \@array);

This function splits the array into several arrays with size values in them. You may also have an array with less values at the end. You get the arrays as members of a multidimensional array indexed with numbers starting from zero. This method will NOT preserve the keys like its PHP cousin.

array_combine()

$hash_ref = array_combine(\@keys, \@values);

This function returns a hash reference by using the values from the keys array as keys and the values from the values array as the corresponding values. Returns 0 if the number of elements for each array isn't equal or if the arrays are empty. This function will ONLY accept array references, do not use pass by value.

array_count_values()

%return = array_count_values(@array);

This function scans the given array and returns a hash with the keys as the unique elements of the array and the values are how many times each unique element is in the array.

array_diff()

@return = array_diff(@array1, @array2);
---OR---
$array_reference = array_diff(\@array1, \@array2);

This function returns an array containing all the values of array1 that are not present in any of the other arguments. Note that keys are NOT preserved.

array_diff_assoc()

%return = array_diff_assoc(\%hash1, \%hash2, $return);
---OR---
$hash_ref = array_diff_assoc(\%hash1, \%hash2);

Returns an array containing all the values from array1 that are not present in any of the other arguments. Note that the keys are used in the comparison unlike array_diff(). If you specify $return to be 1, it will return a hash. If $return is omitted or specified to be 0, you will recieve a hash reference.

array_diff_key()

%return = array_diff_key(\%hash1, \%hash2, $return);
---OR---
$hash_ref = array_diff_key(\%hash1, \%hash2);

Returns an array containing all the values of hash1 that have keys that are not present in any of the other arguments. Note that the associativity is preserved. This function is like array_diff() except the comparison is done on the keys instead of the values. Strict type check is executed so the string representation must be the same. If you specify $return to be 1, it will return a hash. If $return is omitted or specified to be 0, you will recieve a hash reference.

array_fill()

@array = array_fill($start, $num, $value, $return);
---OR---
$array_ref = array_fill($start, $num, $value);

Fills an array with num entries of the value of the value parameter, keys starting at the start_index parameter. Note that num must be a number greater than zero, or 0 will be returned. If you specify $return to be 1, it will return an array. If $return is omitted or specified to be 0, you will recieve an array reference.

array_flip()

%flipped = array_flip(%hash);
---OR---
$hash_ref = array_flip(\%hash);

Returns an array in flip order. The keys become the values and the values become the keys. If a value has several occurrences, the latest key will be used as its values, and all others will be lost.

array_interset()

@return = array_intersect(\@array1, \@array2, $return);
---OR---
$array_ref = array_intersect(\@array1, \@array2);

Returns an array containing all the values of array1 that are present in array2. Note that keys are NOT preserved. If you specify $return to be 1, it will return an array. If $return is omitted or specified to be 0, you will recieve an array reference.

array_intersect_assoc()

%return = array_intersect_assoc(\%hash1, \%hash2, $return);
---OR---
$hash_ref = array_intersect_assoc(\%hash1, \%hash2);

Returns a hash containing all the values of hash1 that are present in hash2. Note that the keys are used in the comparison unlike in array_intersect(). if you specify $return to be 1, it will return a hash. If $return is omitted or specified to be 0, you will recieve a hash reference.

array_intersect_key()

%return = array_intersect_key(\%hash1, \%hash2, $return);
---OR---
$hash_ref = array_intersect_key(\%hash1, \%hash2);

Returns a hash containing all the values of hash1 which have matching keys that are present in hash2. Strict type check is executed so the string representation must be the same. If you specify $return to be 1, it will return a hash. If $return is omitted or specified to be 0, you will recieve a hash reference.

array_key_exists()

$return = array_key_exists($key, 1, @array);
---OR---
$return = array_key_exists($key, 2, %hash);
---OR---
$return = array_key_exists($key, \@array);
---OR---
$return = array_key_exists($key, \%hash);

Returns 1 if the given key is in the array or hash. If you want to use pass by value, you MUST specify a 1 for an array or a 2 for a hash. If you are using pass by reference, you do not need to do this.

array_merge()

@array_merged = array_merge(@array1, @array2);
---OR---
@array_merged = array_merge(\@array1, \@array2);

This function merges the two given arrays together. It returns an array with all elements of array1 placed in the beginning of the merged array, followed by all the elements of array2.

array_pad()

@padded_array = array_pad($pad_size, $pad_value, @array);
---OR---
$array_ref = array_pad($pad_size, $pad_value, \@array);

This function returns a copy of the input padded to size specified by pad_size with value pad_value. If pad_size is positive then the array is padded on the right, if it's negative then on the left. If the absolute value of pad_size is less than or equal to the length of the input then no padding takes place. The pad_size must be an integer, but the pad_value may be of any type.

array_product()

$product = array_product(@array);
---OR---
$product = array_product(\@array);

Returns the product of values in an array as an integer or float.

array_rand()

@random = array_rand($number, 1, @array);
---OR---
@random = array_rand($number, 2, %hash);
---OR---
$array_ref = array_rand($number, \@array);
---OR---
$array_ref = array_rand($number, \%hash);

It takes an array/hash and a number which specifies how many entries you want to pick. It returns an array of keys for the random entries. This is done so that you can pick random keys as well as values out of the array. if you want to use pass by value, you MUST specify a 1 for an array or a 2 for a hash. If you are using pass by reference, you do not need to do this.

array_search()

$return = array_search($needle, @haystack);
---OR---
$return = array_search($needle, \@haystack);

Searches the given array for the value and will return the index if found. If it does not find the value, it will return -1.

array_slice()

@return = array_slice($offset, $length, @array);
---OR---
$array_ref = array_slice($offset, $length, \@array);

Returns the sequence of elements from the array as specified by the offset and length parameters. If offset is non-negative, the sequence will start at that offset in the array. If offset is negative, the sequence will start that far from the end of the array. if length is given and is positive, then the sequence will have that many elements in it. If length is given and is negative then the sequence will stop that many elements from the end of the array. If it is omitted, then the sequence will have everything from offset up until the end of the array.

array_sum()

$sum = array_sum(@array);
---OR---
$sum = array_sum(\@array);

Returns the sum of values in an array as an integer or float.

array_unique()

@duplicates_removed = array_unique(@array);
---OR---
$array_ref = array_unique(\@array);

This function returns an array with all of the duplicate entries of the given array removed.

in_array()

$return = in_array($needle, @haystack);
---OR---
$return = in_array($needle, \@haystack);

This function returns 1 if the the array contains the value, otherwise it will return 0.

range()

$array_ref = range($low, $high, $step);
---EXAMPLE---
$array_ref = range('a','m', 2);
---OR---
$array_ref = range(100, 2, 6);

Returns an array of elements from low to high, inclusive. If low > high, the sequence will be from high to low. If a step value is given, it will be used as the increment between elements in the sequence. step should be given as a positive number. If not specified, step will default to 1. The low and high may be integers or characters.

shuffle()

@shuffled = shuffle(@array);
---OR---
$array_ref = shuffle(\@array);

This function returns the passed array with its elements placed in a random order.

AUTHOR

Brian Shade

SEE ALSO

perl(1).