H. Klausing > Array-CompareAndFilter-v1.0.3 > Array::CompareAndFilter

Download:
Array-CompareAndFilter-v1.0.3.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  1
Open  0
View/Report Bugs
Module Version: v1.0.3   Source  

NAME ^

Array::CompareAndFilter - Basic functions to compare and filter arrays for different requirements.

SYNOPSIS ^

 use Array::CompareAndFilter qw(compareValue compareItem compareOrder intersection difference unscramble unique);
 # or use Array::CompareAndFilter qw(:all);
 
 # compare the content of two arrays
 if(compareValue([1,2,3,3], [1,2,3])) {
     say "Both arrays have same content.";                      # output
 } else {
     say "Arrays has different content.";
 }

 # compare the content of two arrays
 if(compareItem([1,2,3], [2,3,1])) {
     say "Both arrays have same content.";                      # output
 } else {
     say "Arrays are different.";
 }

 # compare the content and the order of two arrays
 if(compareOrder([1,2,3], [1,2,3])) {
     say "Both arrays have same content in the same order.";    # output
 } else {
     say "Arrays are different.";
 }

 # intersection gets equal items of two arrays
 my @inter = intersection([1,2,3], [2,3,4,2]);
 say "The intersection items (\@inter) are 2 & 3.";
 
 # substractItem substract ARR2 items from ARR1
 my @subItem = substractItem([3,1,2,3], [2,3]);
 say "The substractItem items (\@subItem) are 1 & 3";
 
 # substractValue substract ARR2 value from ARR1
 my @subValue = substractValue([3,1,2,3], [2,3]);
 say "The substractValue items (\@subValue) is 1";

 # difference gets items that are not part of the other aray
 my @diff = difference([1,2,3,4], [1,3,4,5]);
 say "The difference items (\@diff) are 2 & 5.";
 
 # union gets a list of items that part of all arrays
 my @unscramble = unscramble([1,2], [1,4,3]);
 say "The unscramble items (\@unscramble) are 1,2,3 & 4.";
 
 # unique gets a list of items of array1 that part are not in array2
 my @unique = unique([1,2,3,4,6], [1,2,3,5]);
 say "The unique items (@unique) are 4 & 6.";
 
 # singularize gets a list of singular items of array
 my @singularize = singularize([3,2,3,4,1]);
 say "The singularize items (\@singularize) are 1, 2, 3 & 4.";
 my @singularize = singularize([3,2,3,4,1],'b');
 say "The singularize items (\@singularize) are 3, 2, 4 & 1.";
 my @singularize = singularize([3,2,3,4,1],'e');
 say "The singularize items (\@singularize) are 2, 3, 4 & 1.";

DESCRIPTION ^

This module helps to solve easy tasks with arrays. Comparing of arrays or filtering array data are this kind of task that this module supports.

Functions

The following parameter names ARRAY, ARRAY1 and ARRAY2 are synonyms for array any kind of arrays. If these names are listed in square brackets it is a synonym of a reference. E.g. [ARRAY1] is a reference to the array ARRAY1.

Other parameter types will not excepted. If a given scalar value to the functions has not the reference type ARRAY the function exits with an error message. E.g. a call of compareValue([1,2,3], 3) will throw an error.

compareValue

compareValue([ARRAY1],[ARRAY2])

compareValue compares all values of two arrays. If each value of one array is found in the other array it will return true (1). The function returns false (0) if a difference in the content was found. The comparison is case sensitive. Value is defined as a data value of # an item.

If an item value is undefined it will be handled within the function like the text like '?undef?'. If an item value of ARRAY1 or ARRAY2 has the same value than the function returns a undef for this.

Examples for return value 1
 compareValue([1,2,3], [3,2,1]);            # returns 1
 compareValue([1,2,3], [3,2,1,2,3]);        # returns 1
Examples for return value 0
 compareValue([1,2,undef], [3,2,1,2,3]);    # returns 0
 compareValue([1,2,4], [3,2,1,2,3]);        # returns 0

compareItem

compareItem([ARRAY1],[ARRAY2])

compareItem compares all items of two arrays. If the size and the contents are equal this function will return 1. The function returns 0 if a difference in the size or in the content is found. The comparison is case sensitive.

If an item value is undefined it will be handled within the function like the text like '?undef?'. If an item value of ARRAY1 or ARRAY2 has the same value than the function returns a undef for this.

Examples for return value 1
 compareItem([1,2,3], [3,2,1]);             # returns 1
 compareItem([1,2,undef], [undef,2,1]);     # returns 1
Examples for return value 0
 compareItem([1,2,3], [3,2,1,2,3]);         # returns 0
 compareItem([1,2,3], [4,2,1]);             # returns 0

compareOrder

compareOrder([ARRAY1],[ARRAY2])

compareOrder compares all items of two arrays. If the size, content and the order of items are same it will return 1. The function returns 0 if a difference in size, content or order of items is found. The comparison is case sensitive.

If an item value is undefined it will be handled within the function like the text like '?undef?'. If an item value of ARRAY1 or ARRAY2 has the same value than the function returns a undef for this.

Examples for return value 1
 compareOrder([1,2,3], [1,2,3]);            # returns 1
 compareOrder([undef], [undef]);            # returns 1
 compareOrder([], []);                      # returns 1
Examples for return value 0
 compareOrder([1,2,3], [1,2,3,3]);          # returns 0
 compareOrder([1,2,3], [1,3,2]);            # returns 0

intersection

intersection([ARRAY1],[ARRAY2])

intersection returns all items that are listed in each of both arrays as a sorted list. If one array has no items or no item is listed in the other array this function returns an empty array. The comparison is case sensitive.

If an item value is undefined it will be handled within the function like the text like '?undef?'. If an item value of ARRAY1 or ARRAY2 has the same value than the function returns a undef for this.

Examples
 intersection([1,2,3], [1,2,3]);            # returns (1,2,3)
 intersection([undef], [undef]);            # returns (undef)
 intersection([], []);                      # returns ()
 intersection([1,2], [2,3]);                # returns (2)
 intersection([2,1,2], [3,1,2,2]);          # returns (1,2,2)

substractItem

substractItem([ARRAY1],[ARRAY2])

substractItem returns an array with a subtraction list of the operation ARRAY1 - ARRAY2. If an item value in ARRAY2 is listed in ARRAY1, than one item of ARRAY1 will be removed from the begin of the list. To remove multiple items, same amount of items have to be listed in ARRAY1. If no match between an item of ARRAY2 to ARRAY1 is found, no change will happen in ARRAY1.

The item order of ARRAY1 will be kept in the result list.

Examples
 substractItem([1,2,3,4], [1,2,3]);         # returns (4)
 substractItem([undef], [undef]);           # returns ()
 substractItem([1,2], [3]);                 # returns (1,2)
 substractItem([1,3,2,2], [2,1,2]);         # returns (3)

substractValue

substractValue([ARRAY1],[ARRAY2])

substractValue returns an array with a subtraction list of the operation ARRAY1 - ARRAY2. A value in ARRAY2 removes all items of ARRAY1 that have the same value. If no match between an item of ARRAY2 to ARRAY1 is found, no change will happen in ARRAY1.

The item order of ARRAY1 will be kept in the result list.

Examples
 substractValue([1,2,3,2,1], [1,2]);        # returns (3)
 substractValue([undef,undef], [undef]);    # returns ()
 substractValue([], [1,2]);                 # returns ()
 substractValue([1,2], [1,3]);              # returns (2)

difference

difference([ARRAY1],[ARRAY2])

difference returns a list of items that are not listed in the other array. The comparison is case sensitive.

If an item value is undefined it will be handled within the function like the text like '?undef?'. If an item value of ARRAY1 or ARRAY2 has the same value than the function returns a undef for this.

Examples
 difference([1,2,3,4], [1,3,4,5]);          # returns (2,5)
 difference([1], [2]);                      # returns (1,2)
 difference([undef,1], [2,3,1]);            # returns (2,3,undef)
 difference([2,1], [3,1,2]);                # returns (3)

unscramble

unscramble([ARRAY1],[ARRAY2])

unscramble returns a summary list of items. Each item value of both arrays will exist maximal one time.

If an item value is undefined it will be handled within the function like the text like '?undef?'. If an item value of ARRAY1 or ARRAY2 has the same value than the function returns a undef for this.

Examples
 unscramble([1,2], [1,4,3]);                # returns (1,2,3,4)
 unscramble([1,1], [2,3,3,1]);              # returns (1,2,3)
 unscramble([1,1], []);                     # returns (1)

unique

unique([ARRAY1],[ARRAY2])

unique checks all item values of ARRAY1 in the array of ARRAY2. It will return all items which were not found in ARRAY2.

If an item value is undefined it will be handled within the function like the text like '?undef?'. If an item value of ARRAY1 or ARRAY2 has the same value than the function returns a undef for this.

Examples
 unique([1,2,3], [2,1,4,3]);                # returns ()
 unique([1,2,3,4], [1,2,3,5]);              # returns (4)
 unique([1,2,3,5], [2,3,4]);                # returns (1,5)

singularize

singularize([ARRAY])

singularize removes all double items values of the given array list. By using an order argument the output can be selected for some different result variations.

'b' or 'B' scans the input array by the item values from the begin and returns a list were the first found position of each value is used. E.g. [1,2,1,3] -> (1,2,3)

'e' or 'E' scans the input array by the item values from the end and returns a list were the last found position of each value is used. E.g. [1,2,1,3] -> (2,1,3)

No order argument or other data then 'b|B' or 'e|B' will return a sorted list of singularize values.

If sorting is selected than following issue needes to be considered. If an item value is undefined it will be handled within the function like the text like '?undef?'. If an item value of ARRAY1 or ARRAY2 has the same value than the function returns a undef for this.

Examples
 singularize([qw(d b d b c a)]);            # returns ('a','b','c','d')
 singularize([3,2,3,4,1]);                  # returns (1,2,3,4)
 singularize([3,2,3,4,1],'s');              # returns (1,2,3,4)
 singularize([3,2,3,4,1],'b');              # returns (3,2,4,1)
 singularize([3,2,3,4,1],'e');              # returns (2,3,4,1)

VERSION ^

v1.0.3

AUTHOR ^

H. Klausing <h.klausing (at) gmx.de>

LICENSE ^

Copyright (c) 2012 H. Klausing, All Rights Reserved.

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

syntax highlighting: