PHP Classes

PHP Array Helpers: Perform several array manipulation operations

Recommend this page to a friend!
  Info   View files Example   View files View files (11)   DownloadInstall with Composer Download .zip   Reputation   Support forum   Blog    
Ratings Unique User Downloads Download Rankings
StarStarStarStar 74%Total: 186 This week: 2All time: 8,635 This week: 94Up
Version License PHP version Categories
array-helpers 1.0.4GNU General Publi...5.5Algorithms, PHP 5, Data types
Description 

Author

This package can perform several array manipulation operations.

It can take a given array and performs several types of unusual array manipulation operations. Currently it can:

- Computing combinations of all the values contained in an array that has nested arrays
- Performing a cross-reference between an array containing keys and an associative array containing associative arrays using the same keys
- Merging two or more arrays together, using their array keys
- Sorting arrays of associative arrays containing the same keys, or arrays of objects having the same properties, providing multiple sort criterion
- Finding items in big arrays using dichotomic search
- Extracting ranges of values from arrays containing integer values
- Converting recursively array items to/from UTF8

Picture of Christian Vigh
  Performance   Level  
Name: Christian Vigh <contact>
Classes: 32 packages by
Country: France France
Age: 58
All time rank: 13810 in France France
Week rank: 10 Up1 in France France Up
Innovation award
Innovation award
Nominee: 20x

Winner: 3x

Example

<?php
   
/***********************************************************************************************************

        The following example demonstrates the use of the ArrayHelpers::CombinationsOf function.

     ***********************************************************************************************************/
   
require ( '../ArrayHelpers.phpclass' ) ;

    if (
php_sapi_name ( ) != 'cli' )
        echo (
"<pre>" ) ;

   
$array = [ [ 'a', 'b', 'c' ], 1, 2, [ 'x', 'y', 'z' ] ] ;

    echo
"********** Combinations of the following array :\n" ;
   
print_r ( $array ) ;
    echo
"---------- Result :\n" ;
   
print_r ( ArrayHelpers::CombinationsOf ( $array ) ) ;

    echo
"********** Combinations of an empty array :\n" ;
   
print_r ( ArrayHelpers::CombinationsOf ( [] ) ) ;

   
$array = [ 1, 2, 3, 4 ] ;

    echo
"********** Combinations of a flat array :\n" ;
   
print_r ( $array ) ;
    echo
"---------- Result :\n" ;
   
print_r ( ArrayHelpers::CombinationsOf ( $array ) ) ;


Details

INTRODUCTION

The ArrayHelpers class contains static methods that perform various and completely different operations on arrays. It is to be considered as some kind of swiss-knife and provides the following features :

  • Generating combinations of array elements
  • Merging array items in a way different from that of the array\_merge() and array\_merge\_recursive() functions
  • Performing fast lookups in a sorted array using a dichotomic search
  • Recursively encoding/decoding array items to/from UTF8
  • And more...

REFERENCE

ArrayHelpers::CombinationsOf ( $array, $max_results = 10000 ) ;

Takes an array containing values and nested arrays (no more than one level of nesting is authorized) and generates all the possible combinations, each nested array providing alternatives during the generation.

  

An example will be better than a long description ; suppose that you have the following array :

  
 	[ [ 'a', 'b' ], 1, 2, [ 'x', 'y', 'z' ] ]

You want to generate all the possible combinations given the above input, ie, a result such as this one :

	'a', 1, 2, 'x'
	'a', 1, 2, 'y',
	'a', 1, 2, 'z'
	'b', 1, 2, 'x',
	...
	'b', 1, 2, 'z'

The CombinationsOf method will do the work and will return you the following array :

  

[ [ 'a', 1, 2, 'x' ] [ 'b', 1, 2, 'x' ] [ 'a', 1, 2, 'y' ] [ 'b', 1, 2, 'y' ] [ 'a', 1, 2, 'z' ] [ 'b', 1, 2, 'z' ] ]

  

For example :

	$result 	=  ArrayHelpers::CombinationsOf ( [ [ 'a', 'b' ], 1, 2, [ 'x', 'y', 'z' ] ] ) ;
	print_r ( $result ) ;

Of course, if you array does not contain nested arrays, the return value will be an array containing only one element, the value you supplied for the $array parameter. For example :

	ArrayHelpers::CombinationsOf ( [ 1, 2, 3, 4 ] ) 

will return :

	[
		[ 1, 2, 3, 4 ]
     ]		

The $max\_results parameter is here to limit the number of items that will be returned by the function, just in case you provided array data which leads to exponential combinations.

Note that :

  • Results are computed from left to right
  • Currently, only one nesting level can be processed. For example, you cannot supply input values such as :

    [ [ 'a', [ 'b', 'c' ] ], 1, 2, [ 'x', 'y', 'z' ] ]

ArrayHelpers::CrossReference ( $keys, $array, &$missing = [], &$extra = [], $case_sensitive = true ) ;

Performs a cross-reference between two arrays. The first array contains key names, and the second one is either an associative array (with key names) or a regular array (with indexes).

The function checks that each element in $array (identified either by its key or its numeric index) has a correspondance in $keys.

On output :

  • $missing will contain the elements of $keys that are not contained in $array
  • $extra will contain the elements of $array that are not present in $keys

The $case\_sensitive parameter specifies if comparisons on array keys should be case-sensitive or not. This parameter is useless if the $array parameter is a non-associative array.

The function returns true if the contents of the $keys array are strictly the same as the array keys of the $array parameter, or false otherwise.

InArray ( $array, $value, $case_insensitive = true )

Checks that the specified value is in the specified array. By default, comparisons are not case-sensitive.

This function can be used if you do not have the extension tha contains the iin_array() function (however, I am unable to tell you what is the name of this extension...).

$result = ArrayHelpers::MergeAssoc ( $array [, ...] ) ;

The MergeAssoc()function can be considered as similar to the PHParray\_merge()* function ; however, it operates on array keys rather than on array values.

For example, the following :

print_r ( ArrayHelpers::MergeAssoc ( [ 17 = > 1	], [ 17 => 2, 18 => 3 ] ) ) ;

will produce the following output :

Array
(
    [17] => 2,
    [18] => 3
 )

while the array_merge() function will give :

Array
(
    [0] => 1
    [1] => 2
    [2] => 3
)

$result = ArrayHelpers::MergeAssocRecursive ( $array [, ...] ) ;

The MergeAssocRecursive() function is similar to the PHP array\_merge\_recursive() function. However, like the MergeAssoc() function, it operates on array keys rather than on array values.

For example, the following :

$array_1	=  [ 17 => 'value 17 version 1', 18 => [ 'a' => 'value a', 'b' => 'value b version 1' ] ] ;
$array_2	=  [ 17 => 'value 17 version 2', 18 => [ 'b' => 'value b version 2', 'c' => 'value c' ] ] ;
$array_3	=  [ 1 => 'value 1', 19 => 'value 19', 20 => 'value 20' ] ;
print_r ( ArrayHelpers::MergeAssocRecursive ( $array_1, $array_2, $array_3 ) ) ;

will give the following result :

Array
(
    [17] => value 17 version 2
    [18] => Array
        (
            [a] => value a
            [b] => value b version 2
            [c] => value c
        )

    [1] => value 1
    [19] => value 19
    [20] => value 20
)

while the array\_merge\_recursive() function will give :

Array
(
    [0] => value 17 version 1
    [1] => Array
        (
            [a] => value a
            [b] => value b version 1
        )

    [2] => value 17 version 2
    [3] => Array
        (
            [b] => value b version 2
            [c] => value c
        )

    [4] => value 1
    [5] => value 19
    [6] => value 20
)

ArrayHelpers::MultiSort ( &$array, $criterias, $case_sensitive = true ) ;

The MultiSort() function is intended to sort arrays whose values are associative arrays containing the same keys. It allows for specifying multiple sort criterias.

The $array parameter can either be an array of associative arrays, or an array of objects.

Each element in the $criteria array specifies a sort criteria, which must reference an array item key in the $array parameter (if array items are themselves associative arrays) or a property (if array items are objects).

Each value in the $criterias array must be a boolean value that indicates the sort direction for the associated array key or object property name : true for sorting in ascending order, false for descending order.

On output, the original contents of $array will be replaced with their sorted contents, while the function will return the number of comparisons performed.

The following examples sorts the $array parameter on two elements, 'prop1' (in ascending order) and 'prop2' (in descending order) :

$array	=
   [
	[ 'prop1' => 1 , 'prop2' => 2  , 'prop3' => 10 ],
	[ 'prop1' => 17, 'prop2' => 1  , 'prop3' => 11 ],
	[ 'prop1' => 1 , 'prop2' => 900, 'prop3' => 12 ],
	[ 'prop1' => 17, 'prop2' => 600, 'prop3' => 11 ],
	[ 'prop1' => 18, 'prop2' => 1  , 'prop3' => 11 ]
    ] ;

ArrayHelpers::MultiSort ( $array, [ 'prop1' => true, 'prop2' => false ] ) ;
print_r ( $array ) ;

It will output :

Array
(
    [0] => Array
        (
            [prop1] => 1
            [prop2] => 900
            [prop3] => 12
        )
    [1] => Array
        (
            [prop1] => 1
            [prop2] => 2
            [prop3] => 10
        )
    [2] => Array
        (
            [prop1] => 17
            [prop2] => 600
            [prop3] => 11
        )
    [3] => Array
        (
            [prop1] => 17
            [prop2] => 1
            [prop3] => 11
        )
    [4] => Array
        (
            [prop1] => 18
            [prop2] => 1
            [prop3] => 11
        )
)

This also works on arrays of objects, using the same value for the $criterias array :

class TestItem 
   {
	public		$prop1, $prop2, $prop3 ;

	public function  __construct ( $prop1, $prop2, $prop3 ) 
	   {
		$this -> prop1	=  $prop1 ;
		$this -> prop2	=  $prop2 ;
		$this -> prop3	=  $prop3 ;
	    }
    }

$array	=
   [
	new TestItem (  1,   2, 10 ),
	new TestItem ( 17,   1, 11 ),
	new TestItem (  1, 900, 12 ),
	new TestItem ( 17, 600, 11 ),
	new TestItem ( 18,   1, 11 )
    ] ;

ArrayHelpers::MultiSort ( $array, [ 'prop1' => true, 'prop2' => false ] ) ;

$index = ArrayHelpers::SortedFind ( $array, $value ) ;

Returns the index of the element in $array whose value is equal to the one specified for the $value parameter.

This function uses a dichotomic search and assumes that the supplied array is already sorted. The complexity of this function is thus O(log2(n)), where n is the number of elements contained in the array (for arrays containing 1 million elements, the number of comparisons will be log2(1000000), so at most 20 comparisons will be required to find the desired element).

It returns boolean false if the specified value was not found, or the index of the specified value in $array.

The following functions are also available :

  • SortedFindLE : Finds the first element in $array that is less or equal to $value.
  • SortedFindLT : Finds the first element in $array that is strictly less than $value.
  • SortedFindGE : Finds the first element in $array that is greater or equal to $value.
  • SortedFindGT : Finds the first element in $array that is strictly greater than $value.

$result = ToRanges ( $array ) ;

Extracts ranges of values from an array containing integer elements, and returns an array of 2-elements arrays, which contain in tur the low- and upper-bound of the range.

The following example :

$array	=  [ 1, 2, 3, 4, 5, 10, 11, 12, 20, 21 ] ;
print_r ( ArrayHelpers::ToRanges ( $array ) ) ;

will display :

Array
(
    [0] => Array
        (
            [0] => 1
            [1] => 5
        )

    [1] => Array
        (
            [0] => 10
            [1] => 12
        )

    [2] => Array
        (
            [0] => 20
            [1] => 21
        )

)

Note that the order of elements in $array has no importance ; you could specify as well :

$array	=  [ 1, 10, 4, 11, 3, 12, 20, 2, 21, 5 ] ;

$result = ToRangeString ( $array, $range_separator = '-', $item_separator = ', ' ) ;

Converts an array of integers to a string representing ranges. The following for example :

$a =  [ 1, 3, 4, 2, 6, 22, 21, 20, 12  ] ;
echo ( ArrayHelpers::ToRangeString ( $a ) ) ;

will display :

1-4, 6, 12, 20-22

The parameters are the following :

  • $array (array) : Array to be converted to a range list then to its string representation.
  • $range_separator (array) : tring to be used as a separator between the lower and upper limits of a range. Note that the separator will not be used if the lower and upper limits are equal (only one value will be inserted into the return value).
  • item_separator (string) : Separator string to be used between two ranges.

ArrayHelper::Utf8Encode ( &$array ) ; ArrayHelper::Utf8Decode ( &$array ) ;

Recursively encodes/decodes an array. Decoded data is put in the supplied $array argument.


  Files folder image Files  
File Role Description
Files folder imageexamples (7 files)
Plain text file ArrayHelpers.phpclass Class Class source
Accessible without login Plain text file LICENSE Lic. License text
Accessible without login Plain text file NOTICE Data Auxiliary data
Accessible without login Plain text file README.md Doc. Documentation

  Files folder image Files  /  examples  
File Role Description
  Accessible without login Plain text file CombinationsOf.php Example Example script
  Accessible without login Plain text file CrossReference.php Aux. Auxiliary script
  Accessible without login Plain text file MergeAssoc.php Example Example script
  Accessible without login Plain text file MergeAssocRecursive.php Example Example script
  Accessible without login Plain text file MultiSort.php Example Example script
  Accessible without login Plain text file SortedFind.php Example Example script
  Accessible without login Plain text file ToRanges.php Example Example script

 Version Control Unique User Downloads Download Rankings  
 100%
Total:186
This week:2
All time:8,635
This week:94Up
 User Ratings  
 
 All time
Utility:91%StarStarStarStarStar
Consistency:100%StarStarStarStarStarStar
Documentation:83%StarStarStarStarStar
Examples:100%StarStarStarStarStarStar
Tests:-
Videos:-
Overall:74%StarStarStarStar
Rank:104