|
Class TPriorityList
TPriorityList class
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 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 TPriorityList::itemAt() ,
TPriorityList::add() , TPriorityList::insertAt() , and TPriorityList::remove() . To get the number of the
items in the list, use TPriorityList::getCount() . TPriorityList can also be used like a
regular array as follows,
$list[]=$item;
$list[$index]=$item;
$list[$index]=$item;
unset($list[$index]);
if(isset($list[$index]))
foreach($list as $index=>$item)
$n=count($list);
To extend TPriorityList for doing your own operations with each addition or
removal, override TPriorityList::insertAtIndexInPriority() and TPriorityList::removeAtIndexInPriority() and then call the parent.
-
TComponent
-
TList
implements
IteratorAggregate,
ArrayAccess,
Countable
-
TPriorityList
Methods summary
public
|
#
__construct( array|Iterator $data = null, boolean $readOnly = false, numeric $defaultPriority = 10, integer $precision = 8 )
Constructor. Initializes the list with an array or an iterable object.
Constructor. Initializes the list with an array or an iterable object.
Parameters
- $data
array|Iterator the intial data. Default is null, meaning no initial data.
- $readOnly
boolean whether the list is read-only
- $defaultPriority
numeric the default priority of items without specified priorities.
- $precision
integer the precision of the numeric priorities
Throws
Overrides
|
public
integer
|
#
count( )
Returns the number of items in the list. This method is required by Countable
interface.
Returns the number of items in the list. This method is required by Countable
interface.
Returns
integer number of items in the list.
Overrides
|
public
integer
|
#
getCount( )
Returns the total number of items in the list
Returns the total number of items in the list
Returns
integer the number of items in the list
Overrides
|
public
integer
|
#
getPriorityCount( numeric $priority = null )
Gets the number of items at a priority within the list
Gets the number of items at a priority within the list
Parameters
Returns
integer the number of items in the list at the specified priority
|
public
numeric
|
#
getDefaultPriority( )
Returns
numeric gets the default priority of inserted items without a specified priority
|
protected
|
#
setDefaultPriority( numeric $value )
This must be called internally or when instantiated.
This must be called internally or when instantiated.
Parameters
- $value
numeric sets the default priority of inserted items without a specified priority
|
public
integer
|
#
getPrecision( )
Returns
integer The precision of numeric priorities, defaults to 8
|
protected
|
#
setPrecision( integer $value )
This must be called internally or when instantiated.
This must be called internally or when instantiated.
Parameters
- $value
integer The precision of numeric priorities.
|
public
Iterator
|
#
getIterator( )
Returns an iterator for traversing the items in the list. This method is
required by the interface IteratorAggregate.
Returns an iterator for traversing the items in the list. This method is
required by the interface IteratorAggregate.
Returns
Iterator an iterator for traversing the items in the list.
Overrides
|
public
array
|
#
getPriorities( )
This returns a list of the priorities within this list, ordered lowest to
highest.
This returns a list of the priorities within this list, ordered lowest to
highest.
Returns
array the array of priority numerics in decreasing priority order
|
protected
|
#
sortPriorities( )
This orders the priority list internally.
This orders the priority list internally.
|
protected
array
|
#
flattenPriorities( )
This flattens the priority list into a flat array [0,...,n-1]
This flattens the priority list into a flat array [0,...,n-1]
Returns
array array of items in the list in priority and index order
|
public
mixed
|
#
itemAt( integer $index )
Returns the item at the index of a flattened priority list. TPriorityList::offsetGet()
calls this method.
Parameters
- $index
integer the index of the item to get
Returns
mixed the element at the offset
Throws
Overrides
|
public
array
|
#
itemsAtPriority( numeric $priority = null )
Gets all the items at a specific priority.
Gets all the items at a specific priority.
Parameters
- $priority
numeric priority of the items to get. Defaults to null, filled in with the default
priority, if left blank.
Returns
array all items at priority in index order, null if there are no items at that
priority
|
public
mixed
|
#
itemAtIndexInPriority( integer $index, numeric $priority = null )
Returns the item at an index within a priority
Returns the item at an index within a priority
Parameters
- $index
integer the index into the list of items at priority
- $priority
numeric the priority which to index. no parameter or null will result in the default
priority
Returns
mixed the element at the offset, false if no element is found at the offset
|
public
integer
|
#
add( mixed $item, numeric $priority = null )
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.
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.
Parameters
- $item
mixed item to add into the list at priority
- $priority
numeric priority blank or null for the default priority
Returns
integer the index within the flattened array
Throws
Overrides
|
public
|
#
insertAt( integer $index, mixed $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.
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.
Parameters
- $index
integer the specified position in the flattened list.
- $item
mixed new item to add
Throws
Overrides
|
public
|
#
insertAtIndexInPriority( mixed $item, integer $index = false, numeric $priority = null, boolean $preserveCache = false )
Inserts an item at the specified index within a priority. Override and call
this method to insert your own functionality.
Inserts an item at the specified index within a priority. Override and call
this method to insert your own functionality.
Parameters
- $item
mixed item to add within the list.
- $index
integer index within the priority to add the item, defaults to false which appends the
item at the priority
- $priority
numeric priority priority of the item. defaults to null, which sets it to the default
priority
- $preserveCache
boolean preserveCache specifies if this is a special quick function or not. This
defaults to false.
Throws
|
public
integer
|
#
remove( mixed $item, numeric $priority = false )
Removes an item from the priority list. The list will search for the item.
The first matching item found will be removed from the list.
Removes an item from the priority list. The list will search for the item.
The first matching item found will be removed from the list.
Parameters
- $item
mixed item the item to be removed.
- $priority
numeric priority of item to remove. without this parameter it defaults to false. A value
of false means any priority. null will be filled in with the default priority.
Returns
integer index within the flattened list at which the item is being removed
Throws
Overrides
|
public
mixed
|
#
removeAt( integer $index )
Removes an item at the specified index in the flattened list.
Removes an item at the specified index in the flattened list.
Parameters
- $index
integer index of the item to be removed.
Returns
mixed the removed item.
Throws
Overrides
|
public
mixed
|
#
removeAtIndexInPriority( integer $index, numeric $priority = null )
Removes the item at a specific index within a priority. Override and call
this method to insert your own functionality.
Removes the item at a specific index within a priority. Override and call
this method to insert your own functionality.
Parameters
- $index
integer index of item to remove within the priority.
- $priority
numeric priority of the item to remove, defaults to null, or left blank, it is then set
to the default priority
Returns
mixed the removed item.
Throws
|
public
|
#
clear( )
Removes all items in the priority list by calling removeAtIndexInPriority
from the last item to the first.
Removes all items in the priority list by calling removeAtIndexInPriority
from the last item to the first.
Throws
Overrides
|
public
boolean
|
#
contains( mixed $item )
Parameters
Returns
boolean whether the list contains the item
Overrides
|
public
integer
|
#
indexOf( mixed $item )
Parameters
Returns
integer the index of the item in the flattened list (0 based), -1 if not found.
Overrides
|
public
numeric|array
|
#
priorityOf( mixed $item, boolean $withindex = false )
Returns the priority of a particular item
Returns the priority of a particular item
Parameters
- $item
mixed the item to look for within the list
- $withindex
boolean withindex this specifies if the full positional data of the item within the list
is returned. This defaults to false, if no parameter is provided, so only
provides the priority number of the item by default.
Returns
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]
|
public
numeric|array
|
#
priorityAt( integer $index, boolean $withindex = false )
Retutrns the priority of an item at a particular flattened index.
Retutrns the priority of an item at a particular flattened index.
Parameters
- $index
integer index of the item within the list
- $withindex
boolean withindex this specifies if the full positional data of the item within the list
is returned. This defaults to false, if no parameter is provided, so only
provides the priority number of the item by default.
Returns
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]
|
public
integer
|
#
insertBefore( mixed $indexitem, mixed $item )
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.
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.
Parameters
- $indexitem
mixed indexitem the item to index
- $item
mixed the item to add before indexitem
Returns
integer where the item has been inserted in the flattened list
Throws
Overrides
|
public
integer
|
#
insertAfter( mixed $indexitem, mixed $item )
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.
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.
Parameters
- $indexitem
mixed indexitem the item to index
- $item
mixed the item to add after indexitem
Returns
integer where the item has been inserted in the flattened list
Throws
Overrides
|
public
array
|
#
toArray( )
Returns
array the priority list of items in array
Overrides
|
public
array
|
#
toPriorityArray( )
Returns
array the array of priorities keys with values of arrays of items. The priorities are
sorted so important priorities, lower numerics, are first.
|
public
array
|
#
toArrayBelowPriority( numeric $priority, boolean $inclusive = false )
Combines the map elements which have a priority below the parameter value
Combines the map elements which have a priority below the parameter value
Parameters
- $priority
numeric the cut-off priority. All items of priority less than this are returned.
- $inclusive
boolean whether or not the input cut-off priority is inclusive. Default: false, not
inclusive.
Returns
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.
|
public
array
|
#
toArrayAbovePriority( numeric $priority, boolean $inclusive = true )
Combines the map elements which have a priority above the parameter value
Combines the map elements which have a priority above the parameter value
Parameters
- $priority
numeric the cut-off priority. All items of priority greater than this are returned.
- $inclusive
boolean whether or not the input cut-off priority is inclusive. Default: true,
inclusive.
Returns
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.
|
public
|
#
copyFrom( mixed $data )
Copies iterable data into the priority list. Note, existing data in the map
will be cleared first.
Copies iterable data into the priority list. Note, existing data in the map
will be cleared first.
Parameters
- $data
mixed the data to be copied from, must be an array or object implementing Traversable
Throws
Overrides
|
public
|
#
mergeWith( mixed $data )
Merges iterable data into the priority list. 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.
Merges iterable data into the priority list. 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.
Parameters
- $data
mixed the data to be merged with, must be an array or object implementing Traversable
Throws
Overrides
|
public
boolean
|
#
offsetExists( mixed $offset )
Returns whether there is an element at the specified offset. This method is
required by the interface ArrayAccess.
Returns whether there is an element at the specified offset. This method is
required by the interface ArrayAccess.
Parameters
- $offset
mixed the offset to check on
Returns
boolean
Overrides
|
public
mixed
|
#
offsetGet( integer $offset )
Returns the element at the specified offset. This method is required by the
interface ArrayAccess.
Returns the element at the specified offset. This method is required by the
interface ArrayAccess.
Parameters
- $offset
integer the offset to retrieve element.
Returns
mixed the element at the offset, null if no element is found at the offset
Throws
Overrides
|
public
|
#
offsetSet( integer $offset, mixed $item )
Sets the element at the specified offset. This method is required by the
interface ArrayAccess. 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.
Sets the element at the specified offset. This method is required by the
interface ArrayAccess. 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.
Parameters
- $offset
integer the offset to set element
- $item
mixed the element value
Overrides
|
public
|
#
offsetUnset( mixed $offset )
Unsets the element at the specified offset. This method is required by the
interface ArrayAccess.
Unsets the element at the specified offset. This method is required by the
interface ArrayAccess.
Parameters
- $offset
mixed the offset to unset element
Overrides
|
Methods inherited from TComponent
__call(),
__destruct(),
__get(),
__isset(),
__set(),
__sleep(),
__unset(),
__wakeup(),
addParsedObject(),
asa(),
attachBehavior(),
attachBehaviors(),
attachClassBehavior(),
attachEventHandler(),
canGetProperty(),
canSetProperty(),
clearBehaviors(),
createdOnTemplate(),
detachBehavior(),
detachBehaviors(),
detachClassBehavior(),
detachEventHandler(),
disableBehavior(),
disableBehaviors(),
enableBehavior(),
enableBehaviors(),
evaluateExpression(),
evaluateStatements(),
fxAttachClassBehavior(),
fxDetachClassBehavior(),
getAutoGlobalListen(),
getBehaviorsEnabled(),
getClassHierarchy(),
getEventHandlers(),
getListeningToGlobalEvents(),
getSubProperty(),
hasEvent(),
hasEventHandler(),
hasProperty(),
isa(),
listen(),
raiseEvent(),
setSubProperty(),
unlisten()
|
|