Class Set
Class used for manipulation of arrays.
Copyright: Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
License: MIT License
Location: Cake/Utility/Set.php
Method Summary
-
_flatten() protected static
Flattens an array for sorting -
_map() protected static
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 static
Allows the application of a callback method to elements of an array extracted by a Set::extract() compatible path.
-
check() public static
Checks if a particular path is set in an array -
classicExtract() public static
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 static
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 static
Determines if one Set or array contains the exact keys and values of another. -
countDim() public static
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 static
Computes the difference between a Set and an array, two Sets, or two arrays -
enum() public static
Return a value from an array list if the key exists. -
expand() public static
Expand/unflattens an string to an array -
extract() public static
Implements partial support for XPath 2.0. If $path does not contain a '/' the call is delegated to Set::classicExtract(). Also the $path and $data arguments are reversible.
-
filter() public static
Filters empty elements out of a route array, excluding '0'. -
flatten() public static
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 static
Returns a series of values extracted from an array, formatted in a format string. -
get() public static
Return the value at the specified position -
insert() public static
Inserts $data into an array as defined by $path. -
map() public static
Maps the contents of the Set object to an object hierarchy. Maintains numeric keys as arrays of objects
-
matches() public static
This function can be used to see if a single item or a given xpath match certain conditions. -
merge() public static
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).
-
nest() public static
Takes in a flat array and returns a nested array -
normalize() public static
Normalizes a string or array list. -
numeric() public static
Checks to see if all the values in the array are numeric -
pushDiff() public static
Pushes the differences in $array2 onto the end of $array -
remove() public static
Removes an element from a Set or array as defined by $path. -
reverse() public static
Converts an object into an array. -
sort() public static
Sorts an array by any value, determined by a Set-compatible path
Method Detail
_flatten() protected static ¶
_flatten( array $results , string $key = null )
Flattens an array for sorting
Parameters
- array $results
- string $key optional null
Returns
_map() protected static ¶
_map( array $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
- array $array
- Array to map
- string $class
- Class name
- boolean $primary optional false
- whether to assign first array key as the name
Returns
Mapped object
apply() public static ¶
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
Link
check() public static ¶
check( string|array $data , string|array $path = null )
Checks if a particular path is set in an array
Parameters
- string|array $data
- Data to check on
- string|array $path optional null
- A dot-separated string.
Returns
true if path is found, false otherwise
Link
classicExtract() public static ¶
classicExtract( array $data , string|array $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
- string|array $path optional null
- As an array, or as a dot-separated string.
Returns
Extracted data or null when $data or $path are empty.
Link
combine() public static ¶
combine( array|object $data , string|array $path1 = null , string|array $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
- array|object $data
- Array or object from where to extract keys and values
- string|array $path1 optional null
- As an array, or as a dot-separated string.
- string|array $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
Link
contains() public static ¶
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
Link
countDim() public static ¶
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
Link
diff() public static ¶
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))
Link
enum() public static ¶
enum( string $select , array|string $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
- string $select
- Key in $list to return
- array|string $list optional null
- can be an array or a comma-separated list.
Returns
the value of the array key or null if no match
Link
expand() public static ¶
expand( array $data , string $separator = '.' )
Expand/unflattens an string to an array
For example, unflattens an array that was collapsed with Set::flatten()
into a multi-dimensional array. So, array('0.Foo.Bar' => 'Far') becomes
array(array('Foo' => array('Bar' => 'Far'))).
Parameters
- array $data
- Flattened array
- string $separator optional '.'
- The delimiter used
Returns
extract() public static ¶
extract( string $path , array $data = null , array $options = array() )
Implements partial support for XPath 2.0. If $path does not contain a '/' the call is delegated to Set::classicExtract(). Also the $path and $data arguments are reversible.
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
Link
filter() public static ¶
filter( array $var )
Filters empty elements out of a route array, excluding '0'.
Parameters
- array $var
- Either an array to filter, or value when in callback
Returns
Either filtered array, or true/false when in callback
Link
flatten() public static ¶
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
Link
format() public static ¶
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
Link
get() public static ¶
get( array $input , string|array $path = null )
Return the value at the specified position
Parameters
- array $input
- an array
- string|array $path optional null
- string or array of array keys
Returns
value at the specified position or null if it doesn't exist
insert() public static ¶
insert( array $list , string $path , array $data = null )
Inserts $data into an array as defined by $path.
Parameters
- array $list
- Where to insert into
- string $path
- A dot-separated string.
- array $data optional null
- Data to insert
Returns
Link
map() public static ¶
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
Link
matches() public static ¶
matches( string|array $conditions , array $data = array() , integer $i = null , integer $length = null )
This function can be used to see if a single item or a given xpath match certain conditions.
Parameters
- string|array $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.
- integer $length optional null
Returns
Link
merge() public static ¶
merge( array $data , array $merge = 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).
Since this method emulates array_merge, it will re-order numeric keys. When combined with out of
order numeric keys containing arrays, results can be lossy.
Note: This function will work with an unlimited amount of arguments and typecasts non-array parameters into arrays.
Parameters
- array $data
- Array to be merged
- array $merge optional null
- Array to merge with
Returns
Merged array
Link
nest() public static ¶
nest( mixed $data , array $options = array() )
Takes in a flat array and returns a nested array
Parameters
- mixed $data
- array $options optional array()
Options are: children - the key name to use in the resultset for children idPath - the path to a key that identifies each entry parentPath - the path to a key that identifies the parent of each entry root - the id of the desired top-most result
Returns
of results, nested
Link
normalize() public static ¶
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
Link
numeric() public static ¶
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
Link
pushDiff() public static ¶
pushDiff( array $array , array $array2 )
Pushes the differences in $array2 onto the end of $array
Parameters
- array $array
- Original array
- array $array2
- Differences to push
Returns
Combined array
Link
remove() public static ¶
remove( array $list , string $path = null )
Removes an element from a Set or array as defined by $path.
Parameters
- array $list
- From where to remove
- string $path optional null
- A dot-separated string.
Returns
Array with $path removed from its value
Link
reverse() public static ¶
reverse( object $object )
Converts an object into an array.
Parameters
- object $object
- Object to reverse
Returns
Array representation of given object
Link
sort() public static ¶
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