Class Set
Class used for manipulation of arrays.
Copyright: Copyright 2005-2012, Cake Software Foundation, Inc. (http://cakefoundation.org)
License: License (http://www.opensource.org/licenses/mit-license.php)
Location: set.php
Method Summary
-
__array() public
Get the array value of $array. If $array is null, it will return the current array Set holds. If it is an object of type Set, it will return its value. If it is another object, its object variables. If it is anything else but an array, it will return an array whose first element is $array.
-
__flatten() public
Flattens an array for sorting -
__map() public
Maps the given value as an object. If $value is an object, it returns $value. Otherwise it maps $value as an object of type $class, and if primary assign name $key on first array. If $value is not empty, it will be used to set properties of returned object (recursively). If $key is numeric will maintain array structure
-
apply() public
Allows the application of a callback method to elements of an array extracted by a Set::extract() compatible path.
-
check() public
Checks if a particular path is set in an array -
classicExtract() public
Gets a value from an array or object that is contained in a given path using an array path syntax, i.e.: "{n}.Person.{[a-z]+}" - Where "{n}" represents a numeric key, "Person" represents a string literal, and "{[a-z]+}" (i.e. any string literal enclosed in brackets besides {n} and {s}) is interpreted as a regular expression.
-
combine() public
Creates an associative array using a $path1 as the path to build its keys, and optionally $path2 as path to get the values. If $path2 is not specified, all values will be initialized to null (useful for Set::merge). You can optionally group the values by what is obtained when following the path specified in $groupPath.
-
contains() public
Determines if one Set or array contains the exact keys and values of another. -
countDim() public
Counts the dimensions of an array. If $all is set to false (which is the default) it will only consider the dimension of the first element in the array.
-
diff() public
Computes the difference between a Set and an array, two Sets, or two arrays -
enum() public
Return a value from an array list if the key exists. -
extract() public
Implements partial support for XPath 2.0. If $path is an array or $data is empty it the call is delegated to Set::classicExtract.
-
filter() public
Filters empty elements out of a route array, excluding '0'. -
flatten() public
Collapses a multi-dimensional array into a single dimension, using a delimited array path for each array element's key, i.e. array(array('Foo' => array('Bar' => 'Far'))) becomes array('0.Foo.Bar' => 'Far').
-
format() public
Returns a series of values extracted from an array, formatted in a format string. -
insert() public
Inserts $data into an array as defined by $path. -
map() public
Maps the contents of the Set object to an object hierarchy. Maintains numeric keys as arrays of objects
-
matches() public
This function can be used to see if a single item or a given xpath match certain conditions. -
merge() public
This function can be thought of as a hybrid between PHP's array_merge and array_merge_recursive. The difference to the two is that if an array key contains another array then the function behaves recursive (unlike array_merge) but does not do if for keys containing strings (unlike array_merge_recursive). See the unit test for more information.
-
normalize() public
Normalizes a string or array list. -
numeric() public
Checks to see if all the values in the array are numeric -
pushDiff() public
Pushes the differences in $array2 onto the end of $array -
remove() public
Removes an element from a Set or array as defined by $path. -
reverse() public
Converts an object into an array. -
sort() public
Sorts an array by any value, determined by a Set-compatible path
Method Detail
__array() public ¶
__array( mixed $array )
Get the array value of $array. If $array is null, it will return the current array Set holds. If it is an object of type Set, it will return its value. If it is another object, its object variables. If it is anything else but an array, it will return an array whose first element is $array.
Parameters
- mixed $array
- Data from where to get the array.
Returns
Array from $array.
__flatten() public ¶
__flatten( array $results , string $key = null )
Flattens an array for sorting
Parameters
- array $results
- string $key optional null
Returns
__map() public ¶
__map( mixed $array , string $class , boolean $primary = false )
Maps the given value as an object. If $value is an object, it returns $value. Otherwise it maps $value as an object of type $class, and if primary assign name $key on first array. If $value is not empty, it will be used to set properties of returned object (recursively). If $key is numeric will maintain array structure
Parameters
- mixed $array
- $value Value to map
- string $class
- Class name
- boolean $primary optional false
- whether to assign first array key as the name
Returns
Mapped object
apply() public ¶
apply( mixed $path , array $data , mixed $callback , array $options = array() )
Allows the application of a callback method to elements of an array extracted by a Set::extract() compatible path.
Parameters
- mixed $path
- Set-compatible path to the array value
- array $data
- An array of data to extract from & then process with the $callback.
- mixed $callback
Callback method to be applied to extracted data. See http://ca2.php.net/manual/en/language.pseudo-types.php#language.types.callback for examples of callback formats.
- array $options optional array()
Options are: - type : can be pass, map, or reduce. Map will handoff the given callback to array_map, reduce will handoff to array_reduce, and pass will use call_user_func_array().
Returns
Result of the callback when applied to extracted data
check() public ¶
check( mixed $data , mixed $path = null )
Checks if a particular path is set in an array
Parameters
- mixed $data
- Data to check on
- mixed $path optional null
- A dot-separated string.
Returns
true if path is found, false otherwise
classicExtract() public ¶
classicExtract( array $data , mixed $path = null )
Gets a value from an array or object that is contained in a given path using an array path syntax, i.e.: "{n}.Person.{[a-z]+}" - Where "{n}" represents a numeric key, "Person" represents a string literal, and "{[a-z]+}" (i.e. any string literal enclosed in brackets besides {n} and {s}) is interpreted as a regular expression.
Parameters
- array $data
- Array from where to extract
- mixed $path optional null
- As an array, or as a dot-separated string.
Returns
Extracted data
combine() public ¶
combine( mixed $data , mixed $path1 = null , mixed $path2 = null , string $groupPath = null )
Creates an associative array using a $path1 as the path to build its keys, and optionally $path2 as path to get the values. If $path2 is not specified, all values will be initialized to null (useful for Set::merge). You can optionally group the values by what is obtained when following the path specified in $groupPath.
Parameters
- mixed $data
- Array or object from where to extract keys and values
- mixed $path1 optional null
- As an array, or as a dot-separated string.
- mixed $path2 optional null
- As an array, or as a dot-separated string.
- string $groupPath optional null
- As an array, or as a dot-separated string.
Returns
Combined array
contains() public ¶
contains( array $val1 , array $val2 = null )
Determines if one Set or array contains the exact keys and values of another.
Parameters
- array $val1
- First value
- array $val2 optional null
- Second value
Returns
true if $val1 contains $val2, false otherwise
countDim() public ¶
countDim( array $array = null , boolean $all = false , integer $count = 0 )
Counts the dimensions of an array. If $all is set to false (which is the default) it will only consider the dimension of the first element in the array.
Parameters
- array $array optional null
- Array to count dimensions on
- boolean $all optional false
- Set to true to count the dimension considering all elements in array
- integer $count optional 0
- Start the dimension count at this number
Returns
The number of dimensions in $array
diff() public ¶
diff( mixed $val1 , mixed $val2 = null )
Computes the difference between a Set and an array, two Sets, or two arrays
Parameters
- mixed $val1
- First value
- mixed $val2 optional null
- Second value
Returns
Returns the key => value pairs that are not common in $val1 and $val2 The expression for this function is ($val1 - $val2) + ($val2 - ($val1 - $val2))
enum() public ¶
enum( mixed $select , mixed $list = null )
Return a value from an array list if the key exists.
If a comma separated $list is passed arrays are numeric with the key of the first being 0 $list = 'no, yes' would translate to $list = array(0 => 'no', 1 => 'yes');
If an array is used, keys can be strings example: array('no' => 0, 'yes' => 1);
$list defaults to 0 = no 1 = yes if param is not passed
Parameters
- mixed $select
- Key in $list to return
- mixed $list optional null
- can be an array or a comma-separated list.
Returns
the value of the array key or null if no match
extract() public ¶
extract( string $path , array $data = null , array $options = array() )
Implements partial support for XPath 2.0. If $path is an array or $data is empty it the call is delegated to Set::classicExtract.
Currently implemented selectors:
- /User/id (similar to the classic {n}.User.id)
- /User[2]/name (selects the name of the second User)
- /User[id>2] (selects all Users with an id > 2)
- /User[id>2][<5] (selects all Users with an id > 2 but < 5)
- /Post/Comment[author_name=john]/../name (Selects the name of all Posts that have at least one Comment written by john)
- /Posts[name] (Selects all Posts that have a 'name' key)
- /Comment/.[1] (Selects the contents of the first comment)
- /Comment/.[:last] (Selects the last comment)
- /Comment/.[:first] (Selects the first comment)
- /Comment[text=/cakephp/i] (Selects the all comments that have a text matching the regex /cakephp/i)
- /Comment/@* (Selects the all key names of all comments)
Other limitations:
- Only absolute paths starting with a single '/' are supported right now
Warning: Even so it has plenty of unit tests the XPath support has not gone through a lot of real-world testing. Please report Bugs as you find them. Suggestions for additional features to implement are also very welcome!
Parameters
- string $path
- An absolute XPath 2.0 path
- array $data optional null
- An array of data to extract from
- array $options optional array()
- Currently only supports 'flatten' which can be disabled for higher XPath-ness
Returns
An array of matched items
filter() public ¶
filter( mixed $var , boolean $isArray = false )
Filters empty elements out of a route array, excluding '0'.
Parameters
- mixed $var
- Either an array to filter, or value when in callback
- boolean $isArray optional false
- Force to tell $var is an array when $var is empty
Returns
Either filtered array, or true/false when in callback
flatten() public ¶
flatten( array $data , string $separator = '.' )
Collapses a multi-dimensional array into a single dimension, using a delimited array path for each array element's key, i.e. array(array('Foo' => array('Bar' => 'Far'))) becomes array('0.Foo.Bar' => 'Far').
Parameters
- array $data
- Array to flatten
- string $separator optional '.'
- String used to separate array key elements in a path, defaults to '.'
Returns
format() public ¶
format( array $data , string $format , array $keys )
Returns a series of values extracted from an array, formatted in a format string.
Parameters
- array $data
- Source array from which to extract the data
- string $format
- Format string into which values will be inserted, see sprintf()
- array $keys
- An array containing one or more Set::extract()-style key paths
Returns
An array of strings extracted from $keys and formatted with $format
insert() public ¶
insert( mixed $list , mixed $path , mixed $data = null )
Inserts $data into an array as defined by $path.
Parameters
- mixed $list
- Where to insert into
- mixed $path
- A dot-separated string.
- mixed $data optional null
- Data to insert
Returns
map() public ¶
map( string $class = 'stdClass' , string $tmp = 'stdClass' )
Maps the contents of the Set object to an object hierarchy. Maintains numeric keys as arrays of objects
Parameters
- string $class optional 'stdClass'
- A class name of the type of object to map to
- string $tmp optional 'stdClass'
- A temporary class name used as $class if $class is an array
Returns
Hierarchical object
matches() public ¶
matches( mixed $conditions , array $data = array() , integer $i = null , $length = null )
This function can be used to see if a single item or a given xpath match certain conditions.
Parameters
- mixed $conditions
- An array of condition strings or an XPath expression
- array $data optional array()
- An array of data to execute the match on
- integer $i optional null
- Optional: The 'nth'-number of the item being matched.
- $length optional null
Returns
merge() public ¶
merge( array $arr1 , array $arr2 = null )
This function can be thought of as a hybrid between PHP's array_merge and array_merge_recursive. The difference to the two is that if an array key contains another array then the function behaves recursive (unlike array_merge) but does not do if for keys containing strings (unlike array_merge_recursive). See the unit test for more information.
Note: This function will work with an unlimited amount of arguments and typecasts non-array parameters into arrays.
Parameters
- array $arr1
- Array to be merged
- array $arr2 optional null
- Array to merge with
Returns
Merged array
normalize() public ¶
normalize( mixed $list , boolean $assoc = true , string $sep = ',' , boolean $trim = true )
Normalizes a string or array list.
Parameters
- mixed $list
- List to normalize
- boolean $assoc optional true
- If true, $list will be converted to an associative array
- string $sep optional ','
- If $list is a string, it will be split into an array with $sep
- boolean $trim optional true
- If true, separated strings will be trimmed
Returns
numeric() public ¶
numeric( array $array = null )
Checks to see if all the values in the array are numeric
Parameters
- array $array optional null
- The array to check. If null, the value of the current Set object
Returns
true if values are numeric, false otherwise
pushDiff() public ¶
pushDiff( mixed $array , mixed $array2 )
Pushes the differences in $array2 onto the end of $array
Parameters
- mixed $array
- Original array
- mixed $array2
- Differences to push
Returns
Combined array
remove() public ¶
remove( mixed $list , mixed $path = null )
Removes an element from a Set or array as defined by $path.
Parameters
- mixed $list
- From where to remove
- mixed $path optional null
- A dot-separated string.
Returns
Array with $path removed from its value
reverse() public ¶
reverse( object $object )
Converts an object into an array.
Parameters
- object $object
- Object to reverse
Returns
Array representation of given object
Public
sort() public ¶
sort( array $data , string $path , string $dir )
Sorts an array by any value, determined by a Set-compatible path
Parameters
- array $data
- An array of data to sort
- string $path
- A Set-compatible path to the array value
- string $dir
- Direction of sorting - either ascending (ASC), or descending (DESC)
Returns
Sorted array of data