PRADO Component Framework for PHP 5
  • Home
  • About
  • Testimonials
  • Demos
  • Download
  • Documentation
  • Forum
  • Development
  • Tutorials
  • Class Docs
  • API Manual
  • Wiki

Packages

  • None
  • System
    • Caching
    • Collections
    • Data
      • ActiveRecord
        • Relations
        • Scaffold
          • InputBuilder
      • Commom
        • Sqlite
      • Common
        • Mssql
        • Mysql
        • Oracle
        • Pgsql
        • Sqlite
      • DataGateway
      • SqlMap
        • Configuration
        • Statements
    • Exceptions
    • I18N
    • IO
    • Security
    • Util
    • Web
      • Javascripts
      • Services
      • UI
        • ActiveControls
        • WebControls
    • Xml
  • Wsat
    • pages
  • Overview
  • Package
  • Class
  • Tree
  • Deprecated
  • Todo

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;  // 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 TPriorityList::insertAtIndexInPriority() and TPriorityList::removeAtIndexInPriority() and then call the parent.

TComponent
Extended by TList implements IteratorAggregate, ArrayAccess, Countable
Extended by TPriorityList
Package: System\Collections
Copyright: Copyright © 2005-2014 PradoSoft
License: http://www.pradosoft.com/license/
Author: Brad Anderson <javalizard@gmail.com>
Since: 3.2a
Located at Collections/TPriorityList.php
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

TInvalidDataTypeException
If data is not null and is neither an array nor an iterator.

Overrides

TList::__construct()
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

TList::count()
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

TList::getCount()
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

$priority
numeric
optional priority at which to count items. if no parameter, it will be set to the default TPriorityList::getDefaultPriority()

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

TList::getIterator()
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.

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

TInvalidDataValueException
Issued when the index is invalid

Overrides

TList::itemAt()
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

TInvalidOperationException
if the map is read-only

Overrides

TList::add()
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

TInvalidDataValueException
If the index specified exceeds the bound
TInvalidOperationException
if the list is read-only

Overrides

TList::insertAt()
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

TInvalidDataValueException
If the index specified exceeds the bound
TInvalidOperationException
if the list is read-only
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

TInvalidDataValueException
If the item does not exist

Overrides

TList::remove()
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

TInvalidDataValueException
If the index specified exceeds the bound
TInvalidOperationException
if the list is read-only

Overrides

TList::removeAt()
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

TInvalidDataValueException
If the item does not exist
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

TInvalidOperationException
if the list is read-only

Overrides

TList::clear()
public boolean
# contains( mixed $item )

Parameters

$item
mixed
item

Returns

boolean
whether the list contains the item

Overrides

TList::contains()
public integer
# indexOf( mixed $item )

Parameters

$item
mixed
item

Returns

integer
the index of the item in the flattened list (0 based), -1 if not found.

Overrides

TList::indexOf()
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

TInvalidDataValueException
If the item does not exist

Overrides

TList::insertBefore()
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

TInvalidDataValueException
If the item does not exist

Overrides

TList::insertAfter()
public array
# toArray( )

Returns

array
the priority list of items in array

Overrides

TList::toArray()
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

TInvalidDataTypeException
If data is neither an array nor an iterator.

Overrides

TList::copyFrom()
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

TInvalidDataTypeException
If data is neither an array nor an iterator.

Overrides

TList::mergeWith()
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

TList::offsetExists()
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

TInvalidDataValueException
if the offset is invalid

Overrides

TList::offsetGet()
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

TList::offsetSet()
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

TList::offsetUnset()
Methods inherited from TList
getReadOnly(), setReadOnly()
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()
Constants inherited from TComponent
GLOBAL_RAISE_EVENT_LISTENER
Terms of Service | Contact Us
PRADO v3.2.4 API Manual API documentation generated by ApiGen 2.8.0
Copyright © 2006-2014 by the PRADO Group.
Powered by PRADO