PHP Class Prado\Collections\TPriorityMap

TPriorityMap implements a collection that takes key-value pairs with a priority to allow key-value pairs to be ordered. This ordering is important when flattening the map. When flattening the map, if some key-value pairs are required to be before or after others, use this class to keep order to your map. You can access, add or remove an item with a key by using {@link itemAt}, {@link add}, and {@link remove}. These functions can optionally take a priority parameter to allow access to specific priorities. TPriorityMap is functionally backward compatible with {@link TMap}. To get the number of the items in the map, use {@link getCount}. TPriorityMap can also be used like a regular array as follows,


$map[$key]=$value; // add a key-value pair
unset($map[$key]); // remove the value with the specified key
if(isset($map[$key])) // if the map contains the key
foreach($map as $key=>$value) // traverse the items in the map
$n=count($map);  // returns the number of items in the map

Using standard array access method like these will always use the default priority. An item that doesn't specify a priority will receive the default priority. The default priority is set during the instantiation of a new TPriorityMap. If no custom default priority is specified, the standard default priority of 10 is used. Priorities with significant digits below precision will be rounded. A priority may also be a numeric with decimals. This is set during the instantiation of a new TPriorityMap. The default is 8 decimal places for a priority. If a negative number is used, rounding occurs into the integer space rather than in the decimal space. See {@link round}.

Since: 3.2a

Author: Brad Anderson ([email protected])

Inheritance: extends TMap

Afficher le fichier Open project: pradosoft/prado Class Usage Examples

Méthodes publiques

Méthode	Description
__construct ( $data = null, $readOnly = false, $defaultPriority = 10, $precision = 8 )	Constructor.
add ( $key, $value, $priority = null ) : numeric	Adds an item into the map. A third parameter may be used to set the priority of the item within the map. Priority is primarily used during when flattening the map into an array where order may be and important factor of the key-value pairs within the array.
clear ( )	Removes all items in the map. {@link remove} is called on all items.
contains ( $key ) : boolean
copyFrom ( $data )	Copies iterable data into the map.
count ( ) : integer	Returns the number of items in the map.
getCount ( ) : integer
getDefaultPriority ( ) : numeric
getIterator ( ) : Iterator	Returns an iterator for traversing the items in the map.
getKeys ( ) : array	Returns the keys within the map ordered through the priority of each key-value pair
getPrecision ( ) : integer
getPriorities ( ) : array	This returns a list of the priorities within this map, ordered lowest to highest.
getPriorityCount ( $priority = null ) : integer	Gets the number of items at a priority within the map.
getReadOnly ( ) : boolean
itemAt ( $key, $priority = false ) : mixed	Returns the item with the specified key. If a priority is specified, only items within that specific priority will be selected
itemsAtPriority ( $priority = null ) : array	Gets all the items at a specific priority.
mergeWith ( $data )	Merges iterable data into the map.
offsetExists ( $offset ) : boolean	Returns whether there is an element at the specified offset.
offsetGet ( $offset ) : mixed	Returns the element at the specified offset.
offsetSet ( $offset, $item )	Sets the element at the specified offset.
offsetUnset ( $offset )	Unsets the element at the specified offset.
priorityAt ( $key ) : numeric	Retutrns the priority of an item at a particular flattened index.
priorityOf ( $item ) : numeric	Returns the priority of a particular item within the map. This searches the map for the item.
remove ( $key, $priority = false ) : mixed	Removes an item from the map by its key. If no priority, or false, is specified then priority is irrelevant. If null is used as a parameter for priority, then the priority will be the default priority. If a priority is specified, or the default priority is specified, only key-value pairs in that priority will be affected.
setPriorityAt ( $key, $priority = null ) : numeric	This changes an item's priority. Specify the item and the new priority.
toArray ( ) : array	When the map is flattened into an array, the priorities are taken into account and elements of the map are ordered in the array according to their priority.
toArrayAbovePriority ( $priority, $inclusive = true ) : array	Combines the map elements which have a priority above the parameter value
toArrayBelowPriority ( $priority, $inclusive = false ) : array	Combines the map elements which have a priority below the parameter value

Méthodes protégées

Méthode	Description
flattenPriorities ( ) : array	This flattens the priority map into a flat array [0,.
setDefaultPriority ( $value )	This must be called internally or when instantiated.
setPrecision ( $value )	This must be called internally or when instantiated.
setReadOnly ( $value )
sortPriorities ( )	Orders the priority list internally.

Method Details

__construct() public méthode

Initializes the array with an array or an iterable object.

public __construct ( $data = null, $readOnly = false, $defaultPriority = 10, $precision = 8 )

add() public méthode

Note, if the specified key already exists, the old value will be overwritten. No duplicate keys are allowed regardless of priority.

public add ( $key, $value, $priority = null ) : numeric
Résultat	numeric	priority at which the pair was added

clear() public méthode

Removes all items in the map. {@link remove} is called on all items.

public clear ( )

contains() public méthode

public contains ( $key ) : boolean
Résultat	boolean	whether the map contains an item with the specified key

copyFrom() public méthode

Note, existing data in the map will be cleared first.

public copyFrom ( $data )

count() public méthode

This method is required by \Countable interface.

public count ( ) : integer
Résultat	integer	number of items in the map.

flattenPriorities() protected méthode

..,n-1]

protected flattenPriorities ( ) : array
Résultat	array	array of items in the list in priority and index order

getCount() public méthode

public getCount ( ) : integer
Résultat	integer	the number of items in the map

getDefaultPriority() public méthode

public getDefaultPriority ( ) : numeric
Résultat	numeric	gets the default priority of inserted items without a specified priority

getIterator() public méthode

This method is required by the interface \IteratorAggregate.

public getIterator ( ) : Iterator
Résultat	Iterator	an iterator for traversing the items in the map.

getKeys() public méthode

Returns the keys within the map ordered through the priority of each key-value pair

public getKeys ( ) : array
Résultat	array	the key list

getPrecision() public méthode

public getPrecision ( ) : integer
Résultat	integer	The precision of numeric priorities, defaults to 8

getPriorities() public méthode

This returns a list of the priorities within this map, ordered lowest to highest.

public getPriorities ( ) : array
Résultat	array	the array of priority numerics in decreasing priority order

getPriorityCount() public méthode

Gets the number of items at a priority within the map.

public getPriorityCount ( $priority = null ) : integer
Résultat	integer	the number of items in the map at the specified priority

getReadOnly() public méthode

public getReadOnly ( ) : boolean
Résultat	boolean	whether this map is read-only or not. Defaults to false.

itemAt() public méthode

Returns the item with the specified key. If a priority is specified, only items within that specific priority will be selected

public itemAt ( $key, $priority = false ) : mixed
Résultat	mixed	the element at the offset, null if no element is found at the offset

itemsAtPriority() public méthode

Gets all the items at a specific priority.

public itemsAtPriority ( $priority = null ) : array
Résultat	array	all items at priority in index order, null if there are no items at that priority

mergeWith() public méthode

Existing data in the map will be kept and overwritten if the keys are the same.

public mergeWith ( $data )

offsetExists() public méthode

This method is required by the interface \ArrayAccess.

public offsetExists ( $offset ) : boolean
Résultat	boolean

offsetGet() public méthode

This method is required by the interface \ArrayAccess.

public offsetGet ( $offset ) : mixed
Résultat	mixed	the element at the offset, null if no element is found at the offset

offsetSet() public méthode

This method is required by the interface \ArrayAccess.

public offsetSet ( $offset, $item )

offsetUnset() public méthode

This method is required by the interface \ArrayAccess.

public offsetUnset ( $offset )

priorityAt() public méthode

Retutrns the priority of an item at a particular flattened index.

public priorityAt ( $key ) : numeric
Résultat	numeric	priority of the item in the map

priorityOf() public méthode

Returns the priority of a particular item within the map. This searches the map for the item.

public priorityOf ( $item ) : numeric
Résultat	numeric	priority of the item in the map

remove() public méthode

Removes an item from the map by its key. If no priority, or false, is specified then priority is irrelevant. If null is used as a parameter for priority, then the priority will be the default priority. If a priority is specified, or the default priority is specified, only key-value pairs in that priority will be affected.

public remove ( $key, $priority = false ) : mixed
Résultat	mixed	the removed value, null if no such key exists.

setDefaultPriority() protected méthode

This must be called internally or when instantiated.

protected setDefaultPriority ( $value )

setPrecision() protected méthode

This must be called internally or when instantiated.

protected setPrecision ( $value )

setPriorityAt() public méthode

This method is exactly the same as {@link offsetGet}.

public setPriorityAt ( $key, $priority = null ) : numeric
Résultat	numeric	old priority of the item

setReadOnly() protected méthode

protected setReadOnly ( $value )

sortPriorities() protected méthode

Orders the priority list internally.

protected sortPriorities ( )

toArray() public méthode

When the map is flattened into an array, the priorities are taken into account and elements of the map are ordered in the array according to their priority.

public toArray ( ) : array
Résultat	array	the list of items in array

toArrayAbovePriority() public méthode

Combines the map elements which have a priority above the parameter value

public toArrayAbovePriority ( $priority, $inclusive = true ) : array
Résultat	array	the array of priorities keys with values of arrays of items that are above a specified priority. The priorities are sorted so important priorities, lower numerics, are first.

toArrayBelowPriority() public méthode

Combines the map elements which have a priority below the parameter value

public toArrayBelowPriority ( $priority, $inclusive = false ) : array
Résultat	array	the array of priorities keys with values of arrays of items that are below a specified priority. The priorities are sorted so important priorities, lower numerics, are first.