Class TPriorityList

Description

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 http://www.php.net/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 itemAt, add, insertAt, and remove. To get the number of the items in the list, use getCount. TPriorityList can also be used like a regular array as follows,

  1.  $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
  2.  $list[$index]=$item// $index must be between 0 and $list->Count-1.  This sets the element regardless of priority.  Priority stays the same.
  3.  $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.
  4.  unset($list[$index])// remove the item at $index
  5.  if(isset($list[$index])) // if the list has an item at $index
  6.  foreach($list as $index=>$item// traverse each item in the list in proper priority order and add/insert order
  7.  $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 insertAtIndexInPriority() and removeAtIndexInPriority() and then call the parent.

  • author: Brad Anderson <javalizard@gmail.com>
  • version: $Id: TPriorityList.php 2541 2008-10-21 15:05:13Z javalizard $
  • since: 3.2a

Located in /Collections/TPriorityList.php (line 50)

TComponent
   |
   --TList
      |
      --TPriorityList
Method Summary
TPriorityList __construct ([array|Iterator $data = null], [boolean $readOnly = false], [numeric $defaultPriority = 10], [integer $precision = 8])
int add (mixed $item, [numeric $priority = null])
void clear ()
boolean contains (mixed $item)
void copyFrom (mixed $data)
integer count ()
integer getCount ()
numeric getDefaultPriority ()
Iterator getIterator ()
integer getPrecision ()
array getPriorities ()
integer getPriorityCount ([numeric $priority = null])
integer indexOf (mixed $item)
integer insertAfter (mixed $indexitem, mixed $item)
void insertAt (integer $index, mixed $item)
void insertAtIndexInPriority (mixed $item, [integer $index = false], [numeric $priority = null], [boolean $preserveCache = false])
integer insertBefore (mixed $indexitem, mixed $item)
mixed itemAt (integer $index)
mixed itemAtIndexInPriority (integer $index, [numeric $priority = null])
array itemsAtPriority ([numeric $priority = null])
void mergeWith (mixed $data)
boolean offsetExists (mixed $offset)
mixed offsetGet (integer $offset)
void offsetSet (integer $offset, mixed $item)
void offsetUnset (mixed $offset)
numeric|array priorityAt (integer $index, [boolean $withindex = false])
numeric|array priorityOf (mixed $item, [boolean $withindex = false])
integer remove (mixed $item, [numeric $priority = false])
mixed removeAt (integer $index)
mixed removeAtIndexInPriority (integer $index, [numeric $priority = null])
void setDefaultPriority (numeric $value)
void setPrecision (integer $value)
void sortPriorities ()
array toArray ()
array toArrayAbovePriority (numeric $priority, [boolean $inclusive = true])
array toArrayBelowPriority (numeric $priority, [boolean $inclusive = false])
array toPriorityArray ()
Methods
Constructor __construct (line 86)

Constructor.

Initializes the list with an array or an iterable object.

  • throws: TInvalidDataTypeException If data is not null and is neither an array nor an iterator.
  • access: public
TPriorityList __construct ([array|Iterator $data = null], [boolean $readOnly = false], [numeric $defaultPriority = 10], [integer $precision = 8])
  • array|Iterator $data: the intial data. Default is null, meaning no initial data.
  • boolean $readOnly: whether the list is read-only
  • numeric $defaultPriority: the default priority of items without specified priorities.
  • integer $precision: the precision of the numeric priorities

Redefinition of:
TList::__construct()
Constructor.
add (line 267)

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.

  • return: the index within the flattened array
  • throws: TInvalidOperationException if the map is read-only
  • access: public
int add (mixed $item, [numeric $priority = null])
  • mixed $item: item to add into the list at priority
  • numeric $priority: priority blank or null for the default priority

Redefinition of:
TList::add()
Appends an item at the end of the list.
clear (line 446)

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

  • access: public
void clear ()

Redefinition of:
TList::clear()
Removes all items in the list.
contains (line 463)
  • return: whether the list contains the item
  • access: public
boolean contains (mixed $item)
  • mixed $item: item

Redefinition of:
TList::contains()
copyFrom (line 638)

Copies iterable data into the priority list.

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

  • throws: TInvalidDataTypeException If data is neither an array nor an iterator.
  • access: public
void copyFrom (mixed $data)
  • mixed $data: the data to be copied from, must be an array or object implementing Traversable

Redefinition of:
TList::copyFrom()
Copies iterable data into the list.
count (line 101)

Returns the number of items in the list.

This method is required by Countable interface.

  • return: number of items in the list.
  • access: public
integer count ()

Redefinition of:
TList::count()
Returns the number of items in the list.
flattenPriorities (line 200)

This flattens the priority list into a flat array [0,...,n-1]

  • return: array of items in the list in priority and index order
  • access: protected
array flattenPriorities ()
getCount (line 110)

Returns the total number of items in the list

  • return: the number of items in the list
  • access: public
integer getCount ()

Redefinition of:
TList::getCount()
getDefaultPriority (line 134)
  • return: gets the default priority of inserted items without a specified priority
  • access: public
numeric getDefaultPriority ()
getIterator (line 170)

Returns an iterator for traversing the items in the list.

This method is required by the interface IteratorAggregate.

  • return: an iterator for traversing the items in the list.
  • access: public
Iterator getIterator ()

Redefinition of:
TList::getIterator()
Returns an iterator for traversing the items in the list.
getPrecision (line 151)
  • return: The precision of numeric priorities, defaults to 8
  • access: public
integer getPrecision ()
getPriorities (line 179)

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

  • return: the array of priority numerics in decreasing priority order
  • access: public
array getPriorities ()
getPriorityCount (line 120)

Gets the number of items at a priority within the list

  • return: the number of items in the list at the specified priority
  • access: public
integer getPriorityCount ([numeric $priority = null])
  • numeric $priority: optional priority at which to count items. if no parameter, it will be set to the default getDefaultPriority
indexOf (line 472)
  • return: the index of the item in the flattened list (0 based), -1 if not found.
  • access: public
integer indexOf (mixed $item)
  • mixed $item: item

Redefinition of:
TList::indexOf()
insertAfter (line 561)

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.

  • return: where the item has been inserted in the flattened list
  • throws: TInvalidDataValueException If the item does not exist
  • access: public
integer insertAfter (mixed $indexitem, mixed $item)
  • mixed $indexitem: indexitem the item to index
  • mixed $item: the item to add after indexitem

Redefinition of:
TList::insertAfter()
Finds the base item. If found, the item is inserted after it.
insertAt (line 283)

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.

  • throws: TInvalidOperationException if the list is read-only
  • throws: TInvalidDataValueException If the index specified exceeds the bound
  • access: public
void insertAt (integer $index, mixed $item)
  • integer $index: the specified position in the flattened list.
  • mixed $item: new item to add

Redefinition of:
TList::insertAt()
Inserts an item at the specified position.
insertAtIndexInPriority (line 304)

Inserts an item at the specified index within a priority. Override and call this method to insert your own functionality.

  • throws: TInvalidOperationException if the list is read-only
  • throws: TInvalidDataValueException If the index specified exceeds the bound
  • access: public
void insertAtIndexInPriority (mixed $item, [integer $index = false], [numeric $priority = null], [boolean $preserveCache = false])
  • mixed $item: item to add within the list.
  • integer $index: index within the priority to add the item, defaults to false which appends the item at the priority
  • numeric $priority: priority priority of the item. defaults to null, which sets it to the default priority
  • boolean $preserveCache: preserveCache specifies if this is a special quick function or not. This defaults to false.
insertBefore (line 540)

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.

  • return: where the item has been inserted in the flattened list
  • throws: TInvalidDataValueException If the item does not exist
  • access: public
integer insertBefore (mixed $indexitem, mixed $item)
  • mixed $indexitem: indexitem the item to index
  • mixed $item: the item to add before indexitem

Redefinition of:
TList::insertBefore()
Finds the base item. If found, the item is inserted before it.
itemAt (line 219)

Returns the item at the index of a flattened priority list.

offsetGet calls this method.

  • return: the element at the offset
  • throws: TInvalidDataValueException Issued when the index is invalid
  • access: public
mixed itemAt (integer $index)
  • integer $index: the index of the item to get

Redefinition of:
TList::itemAt()
Returns the item at the specified offset.
itemAtIndexInPriority (line 248)

Returns the item at an index within a priority

  • return: the element at the offset, false if no element is found at the offset
  • access: public
mixed itemAtIndexInPriority (integer $index, [numeric $priority = null])
  • integer $index: the index into the list of items at priority
  • numeric $priority: the priority which to index. no parameter or null will result in the default priority
itemsAtPriority (line 233)

Gets all the items at a specific priority.

  • return: all items at priority in index order, null if there are no items at that priority
  • access: public
array itemsAtPriority ([numeric $priority = null])
  • numeric $priority: priority of the items to get. Defaults to null, filled in with the default priority, if left blank.
mergeWith (line 666)

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.

  • throws: TInvalidDataTypeException If data is neither an array nor an iterator.
  • access: public
void mergeWith (mixed $data)
  • mixed $data: the data to be merged with, must be an array or object implementing Traversable

Redefinition of:
TList::mergeWith()
Merges iterable data into the map.
offsetExists (line 692)

Returns whether there is an element at the specified offset.

This method is required by the interface ArrayAccess.

  • access: public
boolean offsetExists (mixed $offset)
  • mixed $offset: the offset to check on

Redefinition of:
TList::offsetExists()
Returns whether there is an item at the specified offset.
offsetGet (line 703)

Returns the element at the specified offset.

This method is required by the interface ArrayAccess.

  • return: the element at the offset, null if no element is found at the offset
  • access: public
mixed offsetGet (integer $offset)
  • integer $offset: the offset to retrieve element.

Redefinition of:
TList::offsetGet()
Returns the item at the specified offset.
offsetSet (line 720)

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.

  • access: public
void offsetSet (integer $offset, mixed $item)
  • integer $offset: the offset to set element
  • mixed $item: the element value

Redefinition of:
TList::offsetSet()
Sets the item at the specified offset.
offsetUnset (line 739)

Unsets the element at the specified offset.

This method is required by the interface ArrayAccess.

  • access: public
void offsetUnset (mixed $offset)
  • mixed $offset: the offset to unset element

Redefinition of:
TList::offsetUnset()
Unsets the item at the specified offset.
priorityAt (line 515)

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

  • return: 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]
  • access: public
numeric|array priorityAt (integer $index, [boolean $withindex = false])
  • integer $index: index of the item within the list
  • boolean $withindex: 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.
priorityOf (line 489)

Returns the priority of a particular item

  • return: 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]
  • access: public
numeric|array priorityOf (mixed $item, [boolean $withindex = false])
  • mixed $item: the item to look for within the list
  • boolean $withindex: 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.
remove (line 372)

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.

  • return: index within the flattened list at which the item is being removed
  • throws: TInvalidDataValueException If the item does not exist
  • access: public
integer remove (mixed $item, [numeric $priority = false])
  • mixed $item: item the item to be removed.
  • numeric $priority: 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.

Redefinition of:
TList::remove()
Removes an item from the list.
removeAt (line 401)

Removes an item at the specified index in the flattened list.

  • return: the removed item.
  • throws: TInvalidOperationException if the list is read-only
  • throws: TInvalidDataValueException If the index specified exceeds the bound
  • access: public
mixed removeAt (integer $index)
  • integer $index: index of the item to be removed.

Redefinition of:
TList::removeAt()
Removes an item at the specified position.
removeAtIndexInPriority (line 419)

Removes the item at a specific index within a priority. Override and call this method to insert your own functionality.

  • return: the removed item.
  • throws: TInvalidDataValueException If the item does not exist
  • access: public
mixed removeAtIndexInPriority (integer $index, [numeric $priority = null])
  • integer $index: index of item to remove within the priority.
  • numeric $priority: priority of the item to remove, defaults to null, or left blank, it is then set to the default priority
setDefaultPriority (line 143)

This must be called internally or when instantiated.

  • access: protected
void setDefaultPriority (numeric $value)
  • numeric $value: sets the default priority of inserted items without a specified priority
setPrecision (line 160)

This must be called internally or when instantiated.

  • access: protected
void setPrecision (integer $value)
  • integer $value: The precision of numeric priorities.
sortPriorities (line 189)

This orders the priority list internally.

  • access: protected
void sortPriorities ()
toArray (line 577)
  • return: the priority list of items in array
  • access: public
array toArray ()

Redefinition of:
TList::toArray()
toArrayAbovePriority (line 618)

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

  • return: 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.
  • access: public
array toArrayAbovePriority (numeric $priority, [boolean $inclusive = true])
  • numeric $priority: the cut-off priority. All items of priority greater than this are returned.
  • boolean $inclusive: whether or not the input cut-off priority is inclusive. Default: true, inclusive.
toArrayBelowPriority (line 598)

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

  • return: 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.
  • access: public
array toArrayBelowPriority (numeric $priority, [boolean $inclusive = false])
  • numeric $priority: the cut-off priority. All items of priority less than this are returned.
  • boolean $inclusive: whether or not the input cut-off priority is inclusive. Default: false, not inclusive.
toPriorityArray (line 585)
  • return: the array of priorities keys with values of arrays of items. The priorities are sorted so important priorities, lower numerics, are first.
  • access: public
array toPriorityArray ()

Inherited Methods

Inherited From TList

TList::__construct()
TList::add()
TList::clear()
TList::contains()
TList::copyFrom()
TList::count()
TList::getCount()
TList::getIterator()
TList::getReadOnly()
TList::indexOf()
TList::insertAfter()
TList::insertAt()
TList::insertBefore()
TList::itemAt()
TList::mergeWith()
TList::offsetExists()
TList::offsetGet()
TList::offsetSet()
TList::offsetUnset()
TList::remove()
TList::removeAt()
TList::setReadOnly()
TList::toArray()

Inherited From TComponent

TComponent::addParsedObject()
TComponent::attachEventHandler()
TComponent::canGetProperty()
TComponent::canSetProperty()
TComponent::createdOnTemplate()
TComponent::detachEventHandler()
TComponent::evaluateExpression()
TComponent::evaluateStatements()
TComponent::getEventHandlers()
TComponent::getSubProperty()
TComponent::hasEvent()
TComponent::hasEventHandler()
TComponent::hasProperty()
TComponent::raiseEvent()
TComponent::setSubProperty()
TComponent::__call()
TComponent::__get()
TComponent::__set()
TComponent::__sleep()
TComponent::__wakeup()

Documentation generated on Mon, 25 Jun 2012 14:38:54 +0200 by phpDocumentor 1.4.3