PHP Class Prado\Collections\TPriorityList

TPriorityList implements a priority ordered list collection class. It allows you to specify any numeric for priorities down to a specific precision. The lower the numeric, the high the priority of the item in the list. Thus -10 has a higher priority than -5, 0, 10 (the default), 18, 10005, etc. Per {@link round}, precision may be negative and thus rounding can go by 10, 100, 1000, etc, instead of just .1, .01, .001, etc. The default precision allows for 8 decimal places. There is also a default priority of 10, if no different default priority is specified or no item specific priority is indicated. If you replace TList with this class it will work exactly the same with items inserted set to the default priority, until you start using different priorities than the default priority. As you access the PHP array features of this class, it flattens and caches the results. If at all possible, this will keep the cache fresh even when manipulated. If this is not possible the cache is cleared. When an array of items are needed and the cache is outdated, the cache is recreated from the items and their priorities You can access, append, insert, remove an item by using {@link itemAt}, {@link add}, {@link insertAt}, and {@link remove}. To get the number of the items in the list, use {@link getCount}. TPriorityList can also be used like a regular array as follows, $list[]=$item; // append with the default priority. It may not be the last item if other items in the list are prioritized after the default priority $list[$index]=$item; // $index must be between 0 and $list->Count-1. This sets the element regardless of priority. Priority stays the same. $list[$index]=$item; // $index is $list->Count. This appends the item to the end of the list with the same priority as the last item in the list. unset($list[$index]); // remove the item at $index if(isset($list[$index])) // if the list has an item at $index foreach($list as $index=>$item) // traverse each item in the list in proper priority order and add/insert order $n=count($list); // returns the number of items in the list To extend TPriorityList for doing your own operations with each addition or removal, override {@link insertAtIndexInPriority()} and {@link removeAtIndexInPriority()} and then call the parent.
Since: 3.2a
Author: Brad Anderson ([email protected])
Inheritance: extends TList
Mostrar archivo Open project: pradosoft/prado Class Usage Examples

Public Methods

Method Description
__construct ( $data = null, $readOnly = false, $defaultPriority = 10, $precision = 8 ) Constructor.
add ( $item, $priority = null ) : integer Appends an item into the list at the end of the specified priority. The position of the added item may not be at the end of the list.
clear ( ) Removes all items in the priority list by calling removeAtIndexInPriority from the last item to the first.
contains ( $item ) : boolean
copyFrom ( $data ) Copies iterable data into the priority list.
count ( ) : integer Returns the number of items in the list.
getCount ( ) : integer Returns the total number of items in the list
getDefaultPriority ( ) : numeric
getIterator ( ) : Iterator Returns an iterator for traversing the items in the list.
getPrecision ( ) : integer
getPriorities ( ) : array This returns a list of the priorities within this list, ordered lowest to highest.
getPriorityCount ( $priority = null ) : integer Gets the number of items at a priority within the list
indexOf ( $item ) : integer
insertAfter ( $indexitem, $item ) : integer This inserts an item after another item within the list. It uses the same priority as the found index item and places the new item after it.
insertAt ( $index, $item ) Inserts an item at an index. It reads the priority of the item at index within the flattened list and then inserts the item at that priority-index.
insertAtIndexInPriority ( $item, $index = false, $priority = null, $preserveCache = false ) Inserts an item at the specified index within a priority. Override and call this method to insert your own functionality.
insertBefore ( $indexitem, $item ) : integer This inserts an item before another item within the list. It uses the same priority as the found index item and places the new item before it.
itemAt ( $index ) : mixed Returns the item at the index of a flattened priority list.
itemAtIndexInPriority ( $index, $priority = null ) : mixed Returns the item at an index within a priority
itemsAtPriority ( $priority = null ) : array Gets all the items at a specific priority.
mergeWith ( $data ) Merges iterable data into the priority list.
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. This method is required by the interface \ArrayAccess.
offsetUnset ( $offset ) Unsets the element at the specified offset.
priorityAt ( $index, $withindex = false ) : numeric | array Retutrns the priority of an item at a particular flattened index.
priorityOf ( $item, $withindex = false ) : numeric | array Returns the priority of a particular item
remove ( $item, $priority = false ) : integer Removes an item from the priority list.
removeAt ( $index ) : mixed Removes an item at the specified index in the flattened list.
removeAtIndexInPriority ( $index, $priority = null ) : mixed Removes the item at a specific index within a priority. Override and call this method to insert your own functionality.
toArray ( ) : array
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
toPriorityArray ( ) : array

Protected Methods

Method Description
flattenPriorities ( ) : array This flattens the priority list 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.
sortPriorities ( ) This orders the priority list internally.

Method Details

__construct() public method

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

add() public method

Appends an item into the list at the end of the specified priority. The position of the added item may not be at the end of the list.
public add ( $item, $priority = null ) : integer
return integer the index within the flattened array

clear() public method

Removes all items in the priority list by calling removeAtIndexInPriority from the last item to the first.
public clear ( )

contains() public method

public contains ( $item ) : boolean
return boolean whether the list contains the item

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 list.

flattenPriorities() protected method

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

getCount() public method

Returns the total number of items in the list
public getCount ( ) : integer
return integer the number of items in the list

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 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 list, 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 list
public getPriorityCount ( $priority = null ) : integer
return integer the number of items in the list at the specified priority

indexOf() public method

public indexOf ( $item ) : integer
return integer the index of the item in the flattened list (0 based), -1 if not found.

insertAfter() public method

This inserts an item after another item within the list. It uses the same priority as the found index item and places the new item after it.
public insertAfter ( $indexitem, $item ) : integer
return integer where the item has been inserted in the flattened list

insertAt() public method

Inserts an item at an index. It reads the priority of the item at index within the flattened list and then inserts the item at that priority-index.
public insertAt ( $index, $item )

insertAtIndexInPriority() public method

Inserts an item at the specified index within a priority. Override and call this method to insert your own functionality.
public insertAtIndexInPriority ( $item, $index = false, $priority = null, $preserveCache = false )

insertBefore() public method

This inserts an item before another item within the list. It uses the same priority as the found index item and places the new item before it.
public insertBefore ( $indexitem, $item ) : integer
return integer where the item has been inserted in the flattened list

itemAt() public method

{@link offsetGet} calls this method.
public itemAt ( $index ) : mixed
return mixed the element at the offset

itemAtIndexInPriority() public method

Returns the item at an index within a priority
public itemAtIndexInPriority ( $index, $priority = null ) : mixed
return mixed the element at the offset, false 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

New data will be appended to the end of the existing data. If another TPriorityList is merged, the incoming parameter items will be appended at the priorities they are present. These items will be added to the end of the existing items with equal priorities, if there are any.
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

Setting elements in a priority list is not straight forword when appending and setting at the end boundary. When appending without an offset (a null offset), the item will be added at the default priority. The item may not be the last item in the list. When appending with an offset equal to the count of the list, the item will get be appended with the last items priority. All together, when setting the location of an item, the item stays in that location, but appending an item into a priority list doesn't mean the item is at the end of the list.
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 ( $index, $withindex = false ) : numeric | array
return numeric | array the priority of the item in the list, false if not found. if withindex is true, an array is returned of [0 => $priority, 1 => $priorityIndex, 2 => flattenedIndex, 'priority' => $priority, 'index' => $priorityIndex, 'absindex' => flattenedIndex]

priorityOf() public method

Returns the priority of a particular item
public priorityOf ( $item, $withindex = false ) : numeric | array
return numeric | array the priority of the item in the list, false if not found. if withindex is true, an array is returned of [0 => $priority, 1 => $priorityIndex, 2 => flattenedIndex, 'priority' => $priority, 'index' => $priorityIndex, 'absindex' => flattenedIndex]

remove() public method

The list will search for the item. The first matching item found will be removed from the list.
public remove ( $item, $priority = false ) : integer
return integer index within the flattened list at which the item is being removed

removeAt() public method

Removes an item at the specified index in the flattened list.
public removeAt ( $index ) : mixed
return mixed the removed item.

removeAtIndexInPriority() public method

Removes the item at a specific index within a priority. Override and call this method to insert your own functionality.
public removeAtIndexInPriority ( $index, $priority = null ) : mixed
return mixed the removed item.

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 )

sortPriorities() protected method

This orders the priority list internally.
protected sortPriorities ( )

toArray() public method

public toArray ( ) : array
return array the priority 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.

toPriorityArray() public method

public toPriorityArray ( ) : array
return array the array of priorities keys with values of arrays of items. The priorities are sorted so important priorities, lower numerics, are first.