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
Show file Open project: pradosoft/prado Class Usage Examples

Public Methods

Method 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

Protected Methods

Method 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 method

Initializes the array with an array or an iterable object.
public __construct ( $data = null, $readOnly = false, $defaultPriority = 10, $precision = 8 )

add() public method

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
return numeric priority at which the pair was added

clear() public method

Removes all items in the map. {@link remove} is called on all items.
public clear ( )

contains() public method

public contains ( $key ) : boolean
return boolean whether the map contains an item with the specified key

copyFrom() public method

Note, existing data in the map will be cleared first.
public copyFrom ( $data )

count() public method

This method is required by \Countable interface.
public count ( ) : integer
return integer number of items in the map.

flattenPriorities() protected method

..,n-1]
protected flattenPriorities ( ) : array
return array array of items in the list in priority and index order

getCount() public method

public getCount ( ) : integer
return integer the number of items in the map

getDefaultPriority() public method

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

getIterator() public method

This method is required by the interface \IteratorAggregate.
public getIterator ( ) : Iterator
return Iterator an iterator for traversing the items in the map.

getKeys() public method

Returns the keys within the map ordered through the priority of each key-value pair
public getKeys ( ) : array
return array the key list

getPrecision() public method

public getPrecision ( ) : integer
return integer The precision of numeric priorities, defaults to 8

getPriorities() public method

This returns a list of the priorities within this map, ordered lowest to highest.
public getPriorities ( ) : array
return array the array of priority numerics in decreasing priority order

getPriorityCount() public method

Gets the number of items at a priority within the map.
public getPriorityCount ( $priority = null ) : integer
return integer the number of items in the map at the specified priority

getReadOnly() public method

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

itemAt() public method

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
return mixed the element at the offset, null if no element is found at the offset

itemsAtPriority() public method

Gets all the items at a specific priority.
public itemsAtPriority ( $priority = null ) : array
return array all items at priority in index order, null if there are no items at that priority

mergeWith() public method

Existing data in the map will be kept and overwritten if the keys are the same.
public mergeWith ( $data )

offsetExists() public method

This method is required by the interface \ArrayAccess.
public offsetExists ( $offset ) : boolean
return boolean

offsetGet() public method

This method is required by the interface \ArrayAccess.
public offsetGet ( $offset ) : mixed
return mixed the element at the offset, null if no element is found at the offset

offsetSet() public method

This method is required by the interface \ArrayAccess.
public offsetSet ( $offset, $item )

offsetUnset() public method

This method is required by the interface \ArrayAccess.
public offsetUnset ( $offset )

priorityAt() public method

Retutrns the priority of an item at a particular flattened index.
public priorityAt ( $key ) : numeric
return numeric priority of the item in the map

priorityOf() public method

Returns the priority of a particular item within the map. This searches the map for the item.
public priorityOf ( $item ) : numeric
return numeric priority of the item in the map

remove() public method

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
return mixed the removed value, null if no such key exists.

setDefaultPriority() protected method

This must be called internally or when instantiated.
protected setDefaultPriority ( $value )

setPrecision() protected method

This must be called internally or when instantiated.
protected setPrecision ( $value )

setPriorityAt() public method

This method is exactly the same as {@link offsetGet}.
public setPriorityAt ( $key, $priority = null ) : numeric
return numeric old priority of the item

setReadOnly() protected method

protected setReadOnly ( $value )

sortPriorities() protected method

Orders the priority list internally.
protected sortPriorities ( )

toArray() public method

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
return array the list of items in array

toArrayAbovePriority() public method

Combines the map elements which have a priority above the parameter value
public toArrayAbovePriority ( $priority, $inclusive = true ) : array
return 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 method

Combines the map elements which have a priority below the parameter value
public toArrayBelowPriority ( $priority, $inclusive = false ) : array
return 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.