Class TPriorityMap

Description

TPriorityMap class

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 itemAt, add, and remove. These functions can optionally take a priority parameter to allow access to specific priorities. TPriorityMap is functionally backward compatible with TMap.

To get the number of the items in the map, use getCount. TPriorityMap can also be used like a regular array as follows,

  1.  $map[$key]=$value// add a key-value pair
  2.  unset($map[$key])// remove the value with the specified key
  3.  if(isset($map[$key])) // if the map contains the key
  4.  foreach($map as $key=>$value// traverse the items in the map
  5.  $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 http://www.php.net/round.

  • author: Brad Anderson <javalizard@mac.com>
  • version: $Id: TPriorityMap.php 2817 2010-04-18 04:25:03Z javalizard $
  • since: 3.2a

Located in /Collections/TPriorityMap.php (line 60)

TComponent
   |
   --TMap
      |
      --TPriorityMap
Method Summary
TPriorityMap __construct ([map|array|Iterator|TPriorityMap $data = null], [boolean $readOnly = false], [numeric $defaultPriority = 10], [integer $precision = 8])
numeric add (mixed $key, mixed $value, [numeric|null $priority = null])
void clear ()
boolean contains (mixed $key)
void copyFrom (mixed $data)
integer count ()
integer getCount ()
numeric getDefaultPriority ()
Iterator getIterator ()
array getKeys ()
integer getPrecision ()
array getPriorities ()
integer getPriorityCount ([numeric $priority = null])
boolean getReadOnly ()
mixed itemAt (mixed $key, [mixed $priority = false])
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 priorityAt (integer $key)
numeric priorityOf (mixed $item)
mixed remove (mixed $key, [numeric|false|null $priority = false])
void setDefaultPriority (numeric $value)
void setPrecision (integer $value)
numeric setPriorityAt (mixed $key, [numeric|null $priority = null])
void setReadOnly (boolean $value)
void sortPriorities ()
array toArray ()
array toArrayAbovePriority (numeric $priority, [boolean $inclusive = true])
array toArrayBelowPriority (numeric $priority, [boolean $inclusive = false])
Methods
Constructor __construct (line 100)

Constructor.

Initializes the array with an array or an iterable object.

  • throws: TInvalidDataTypeException If data is not null and neither an array nor an iterator.
  • access: public
TPriorityMap __construct ([map|array|Iterator|TPriorityMap $data = null], [boolean $readOnly = false], [numeric $defaultPriority = 10], [integer $precision = 8])
  • map|array|Iterator|TPriorityMap $data: the intial data. Default is null, meaning no initialization.
  • 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:
TMap::__construct()
Constructor.
add (line 346)

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.

Note, if the specified key already exists, the old value will be overwritten. No duplicate keys are allowed regardless of priority.

  • return: priority at which the pair was added
  • throws: TInvalidOperationException if the map is read-only
  • access: public
numeric add (mixed $key, mixed $value, [numeric|null $priority = null])
  • mixed $key: key
  • mixed $value: value
  • numeric|null $priority: priority, default: null, filled in with default priority

Redefinition of:
TMap::add()
Adds an item into the map.
clear (line 440)

Removes all items in the map. remove is called on all items.

  • access: public
void clear ()

Redefinition of:
TMap::clear()
Removes all items in the map.
contains (line 451)
  • return: whether the map contains an item with the specified key
  • access: public
boolean contains (mixed $key)
  • mixed $key: the key

Redefinition of:
TMap::contains()
copyFrom (line 515)

Copies iterable data into the map.

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, object implementing Traversable, or a TPriorityMap

Redefinition of:
TMap::copyFrom()
Copies iterable data into the map.
count (line 200)

Returns the number of items in the map.

This method is required by Countable interface.

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

Redefinition of:
TMap::count()
Returns the number of items in the map.
flattenPriorities (line 184)

This flattens the priority map 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 208)
  • return: the number of items in the map
  • access: public
integer getCount ()

Redefinition of:
TMap::getCount()
getDefaultPriority (line 128)
  • return: gets the default priority of inserted items without a specified priority
  • access: public
numeric getDefaultPriority ()
getIterator (line 164)

Returns an iterator for traversing the items in the map.

This method is required by the interface IteratorAggregate.

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

Redefinition of:
TMap::getIterator()
Returns an iterator for traversing the items in the list.
getKeys (line 244)

Returns the keys within the map ordered through the priority of each key-value pair

  • return: the key list
  • access: public
array getKeys ()

Redefinition of:
TMap::getKeys()
getPrecision (line 145)
  • return: The precision of numeric priorities, defaults to 8
  • access: public
integer getPrecision ()
getPriorities (line 234)

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

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

Gets the number of items at a priority within the map.

  • return: the number of items in the map 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
getReadOnly (line 112)
  • return: whether this map is read-only or not. Defaults to false.
  • access: public
boolean getReadOnly ()

Redefinition of:
TMap::getReadOnly()
itemAt (line 257)

Returns the item with the specified key. If a priority is specified, only items

within that specific priority will be selected

  • return: the element at the offset, null if no element is found at the offset
  • access: public
mixed itemAt (mixed $key, [mixed $priority = false])
  • mixed $key: the key
  • mixed $priority: the priority. null is the default priority, false is any priority, and numeric is a specific priority. default: false, any priority.

Redefinition of:
TMap::itemAt()
Returns the item with the specified key.
itemsAtPriority (line 296)

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 545)

Merges iterable data into the map.

Existing data in the map will be kept and overwritten if the keys are the same.

  • 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, object implementing Traversable, or a TPriorityMap

Redefinition of:
TMap::mergeWith()
Merges iterable data into the map.
offsetExists (line 570)

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:
TMap::offsetExists()
Returns whether there is an element at the specified offset.
offsetGet (line 581)

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:
TMap::offsetGet()
Returns the element at the specified offset.
offsetSet (line 592)

Sets the element at the specified offset.

This method is required by the interface ArrayAccess.

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

Redefinition of:
TMap::offsetSet()
Sets the element at the specified offset.
offsetUnset (line 602)

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:
TMap::offsetUnset()
Unsets the element at the specified offset.
priorityAt (line 324)

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

  • return: priority of the item in the map
  • access: public
numeric priorityAt (integer $key)
  • integer $key: index of the item within the map
priorityOf (line 310)

Returns the priority of a particular item within the map. This searches the map for the item.

  • return: priority of the item in the map
  • access: public
numeric priorityOf (mixed $item)
  • mixed $item: item to look for within the map
remove (line 388)

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.

  • return: the removed value, null if no such key exists.
  • throws: TInvalidOperationException if the map is read-only
  • access: public
mixed remove (mixed $key, [numeric|false|null $priority = false])
  • mixed $key: the key of the item to be removed
  • numeric|false|null $priority: priority. False is any priority, null is the default priority, and numeric is a specific priority

Redefinition of:
TMap::remove()
Removes an item from the map by its key.
setDefaultPriority (line 137)

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 154)

This must be called internally or when instantiated.

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

This changes an item's priority. Specify the item and the new priority.

This method is exactly the same as offsetGet.

  • return: old priority of the item
  • access: public
numeric setPriorityAt (mixed $key, [numeric|null $priority = null])
  • mixed $key: the key
  • numeric|null $priority: the priority. default: null, filled in with the default priority numeric.
setReadOnly (line 120)
  • access: protected
void setReadOnly (boolean $value)
  • boolean $value: whether this list is read-only or not

Redefinition of:
TMap::setReadOnly()
sortPriorities (line 173)

Orders the priority list internally.

  • access: protected
void sortPriorities ()
toArray (line 463)

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.

  • return: the list of items in array
  • access: public
array toArray ()

Redefinition of:
TMap::toArray()
toArrayAbovePriority (line 495)

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 475)

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.

Inherited Methods

Inherited From TMap

TMap::__construct()
TMap::add()
TMap::clear()
TMap::contains()
TMap::copyFrom()
TMap::count()
TMap::getCount()
TMap::getIterator()
TMap::getKeys()
TMap::getReadOnly()
TMap::itemAt()
TMap::mergeWith()
TMap::offsetExists()
TMap::offsetGet()
TMap::offsetSet()
TMap::offsetUnset()
TMap::remove()
TMap::setReadOnly()
TMap::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:55 +0200 by phpDocumentor 1.4.3