Class Set

Class used for manipulation of arrays.

Package: Cake\Utility
Deprecated: 3.0.0 Will be removed in 3.0. Use Hash instead.
Copyright: Copyright (c) Cake Software Foundation, Inc. (https://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 a 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()source protected static

_flatten( array $results , string $key null )

Flattens an array for sorting

Parameters

array $results
Array to flatten.
string $key optional null
Key.

Returns

array

_map()source 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 Array to map
string $class
Class name
boolean $primary optional false
whether to assign first array key as the name

Returns

mixed
Mapped object

apply()source 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

mixed
Result of the callback when applied to extracted data

Link

https://book.cakephp.org/2.0/en/core-utility-libraries/set.html#Set::apply

check()source 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

boolean
true if path is found, false otherwise

Link

https://book.cakephp.org/2.0/en/core-utility-libraries/set.html#Set::check

classicExtract()source 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

mixed
An array of matched items or the content of a single selected item or null in any of these cases: $path or $data are null, no items found.

Link

https://book.cakephp.org/2.0/en/core-utility-libraries/set.html#Set::classicExtract

combine()source 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

array
Combined array

Link

https://book.cakephp.org/2.0/en/core-utility-libraries/set.html#Set::combine

contains()source 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

boolean
true if $val1 contains $val2, false otherwise

Link

https://book.cakephp.org/2.0/en/core-utility-libraries/set.html#Set::contains

countDim()source public static

countDim( array $array , 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
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

integer
The number of dimensions in $array

Link

https://book.cakephp.org/2.0/en/core-utility-libraries/set.html#Set::countDim

diff()source 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

array

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

https://book.cakephp.org/2.0/en/core-utility-libraries/set.html#Set::diff

enum()source 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

string
the value of the array key or null if no match

Link

https://book.cakephp.org/2.0/en/core-utility-libraries/set.html#Set::enum

expand()source public static

expand( array $data , string $separator '.' )

Expand/unflattens a 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

array

extract()source 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

mixed
An array of matched items or the content of a single selected item or null in any of these cases: $path or $data are null, no items found.

Link

https://book.cakephp.org/2.0/en/core-utility-libraries/set.html#Set::extract

filter()source 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

mixed
Either filtered array, or true/false when in callback

Link

https://book.cakephp.org/2.0/en/core-utility-libraries/set.html#Set::filter

flatten()source 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

array

Link

https://book.cakephp.org/2.0/en/core-utility-libraries/set.html#Set::flatten

format()source 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

array|null
An array of strings extracted from $keys and formatted with $format, otherwise null.

Link

https://book.cakephp.org/2.0/en/core-utility-libraries/set.html#Set::format

get()source 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

the
value at the specified position or null if it doesn't exist

insert()source 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

array

Link

https://book.cakephp.org/2.0/en/core-utility-libraries/set.html#Set::insert

map()source 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

object|null
Hierarchical object

Link

https://book.cakephp.org/2.0/en/core-utility-libraries/set.html#Set::map

matches()source 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
Length.

Returns

boolean

Link

https://book.cakephp.org/2.0/en/core-utility-libraries/set.html#Set::matches

merge()source 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

array
Merged array

Link

https://book.cakephp.org/2.0/en/core-utility-libraries/set.html#Set::merge

nest()source public static

nest( mixed $data , array $options array() )

Takes in a flat array and returns a nested array

Parameters

mixed $data
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

array
of results, nested

Link

normalize()source 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

array

Link

https://book.cakephp.org/2.0/en/core-utility-libraries/set.html#Set::normalize

numeric()source 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

boolean
true if values are numeric, false otherwise

Link

https://book.cakephp.org/2.0/en/core-utility-libraries/set.html#Set::numeric

pushDiff()source 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

array
Combined array

Link

https://book.cakephp.org/2.0/en/core-utility-libraries/set.html#Set::pushDiff

remove()source 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
Array with $path removed from its value

Link

https://book.cakephp.org/2.0/en/core-utility-libraries/set.html#Set::remove

reverse()source public static

reverse( object $object )

Converts an object into an array.

Parameters

object $object
Object to reverse

Returns

array
Array representation of given object

Link

https://book.cakephp.org/2.0/en/core-utility-libraries/set.html#Set::reverse

sort()source 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

array
Sorted array of data

Link

https://book.cakephp.org/2.0/en/core-utility-libraries/set.html#Set::sort

© 2005–2017 The Cake Software Foundation, Inc.
Licensed under the MIT License.
CakePHP is a registered trademark of Cake Software Foundation, Inc.
We are not endorsed by or affiliated with CakePHP.
https://api.cakephp.org/2.10/class-Set.html