Iterate over elements in a specific priority.
$pl = new ElggPriorityList(); $pl->add('Element 0'); $pl->add('Element
10', 10); $pl->add('Element -10', -10);
foreach ($pl as $priority => $element) { var_dump("$priority =>
$element"); }
Yields:
0 => Element 0 10 => Element 10
Collisions on priority are handled by inserting the element at or as close to
the requested priority as possible:
$pl = new ElggPriorityList(); $pl->add('Element 5', 5);
$pl->add('Colliding element 5', 5); $pl->add('Another colliding element
5', 5);
foreach ($pl as $priority => $element) { var_dump("$priority =>
$element"); }
Yields: 5 => 'Element 5', 6 => 'Colliding element 5', 7 => 'Another
colliding element 5'
You can do priority lookups by element:
$pl = new ElggPriorityList(); $pl->add('Element 0'); $pl->add('Element
-5', -5); $pl->add('Element 10', 10); $pl->add('Element -10', -10);
$priority = $pl->getPriority('Element -5');
Or element lookups by priority. $element = $pl->getElement(-5);
To remove elements, pass the element. $pl->remove('Element -10');
To check if an element exists: $pl->contains('Element -5');
To move an element: $pl->move('Element -5', -3);
ElggPriorityList only tracks priority. No checking is done in
ElggPriorityList for duplicates or updating. If you need to track this use
objects and an external map:
function elgg_register_something($id, $display_name, $location, $priority =
500) { // $id => $element. static $map = array(); static $list;
if (!$list) { $list = new ElggPriorityList(); }
// update if already registered. if (isset($map[$id])) { $element =
$map[$id]; // move it first because we have to pass the original element. if
(!$list->move($element, $priority)) { return false; }
$element->display_name = $display_name; $element->location = $location; }
else { $element = new stdClass(); $element->display_name = $display_name;
$element->location = $location; if (!$list->add($element, $priority)) {
return false; } $map[$id] = $element; }
return true; }
Methods summary
public
|
#
__construct( array $elements = array() )
Create a new priority list.
Create a new priority list.
Parameters
- $elements
array
$elements An optional array of priorities => element
|
public
integer
|
#
add( mixed $element, mixed $priority = null, boolean $exact = false )
Adds an element to the list.
Adds an element to the list.
Parameters
- $element
mixed
$element The element to add to the list.- $priority
mixed
$priority Priority to add the element. In priority collisions, the original
element maintains its priority and the new element is to the next available
slot, taking into consideration all previously registered elements. Negative
elements are accepted.- $exact
boolean
$exact unused Returns
integer
The priority of the added element.
Warning
This returns the priority at which the element was added, which can be 0. Use
!== false to check for success.
|
public
boolean
|
#
remove( mixed $element, boolean $strict = false )
Removes an element from the list.
Removes an element from the list.
Parameters
- $element
mixed
$element The element to remove from the list- $strict
boolean
$strict Whether to check the type of the element match Returns
boolean
Warning
The element must have the same attributes / values. If using $strict, it must
have the same types. array(10) will fail in strict against array('10') (str vs
int).
|
public
boolean
|
#
move( mixed $element, integer $new_priority, boolean $strict = false )
Move an existing element to a new priority.
Move an existing element to a new priority.
Parameters
- $element
mixed
$element The element to move- $new_priority
integer
$new_priority The new priority for the element- $strict
boolean
$strict Whether to check the type of the element match Returns
boolean
|
public
array
|
|
public
boolean
|
#
sort( callable $callback = null )
Sort the elements optionally by a callback function.
Sort the elements optionally by a callback function.
If no user function is provided the elements are sorted by priority
registered.
The callback function should accept the array of elements as the first
argument and should return a sorted array.
This function can be called multiple times.
Parameters
- $callback
callable
$callback The callback for sorting. Numeric sorting is the default. Returns
boolean
|
public
integer
|
#
getNextPriority( integer $near = 0 )
Returns the next priority available.
Returns the next priority available.
Parameters
- $near
integer
$near Make the priority as close to $near as possible. Returns
integer
|
public
mixed
|
#
getPriority( mixed $element, boolean $strict = false )
Returns the priority of an element if it exists in the list.
Returns the priority of an element if it exists in the list.
Parameters
- $element
mixed
$element The element to check for.- $strict
boolean
$strict Use strict checking? Returns
mixed
False if the element doesn't exists, the priority if it does.
Warning
This can return 0 if the element's priority is 0.
|
public
mixed
|
#
getElement( integer $priority )
Returns the element at $priority.
Returns the element at $priority.
Parameters
- $priority
integer
$priority The priority Returns
mixed
The element or false on fail.
|
public
boolean
|
#
contains( mixed $element, boolean $strict = false )
Returns if the list contains $element.
Returns if the list contains $element.
Parameters
- $element
mixed
$element The element to check.- $strict
boolean
$strict Use strict checking? Returns
boolean
|
public
|
#
rewind( )
PHP Iterator Interface
See
Implementation of
|
public
mixed
|
#
current( )
PHP Iterator Interface
Returns
mixed
See
Implementation of
|
public
integer
|
#
key( )
PHP Iterator Interface
Returns
integer
See
Implementation of
|
public
mixed
|
#
next( )
PHP Iterator Interface
Returns
mixed
See
Implementation of
|
public
boolean
|
#
valid( )
PHP Iterator Interface
Returns
boolean
See
Implementation of
|
public
integer
|
#
count( )
Countable interface
Returns
integer
See
Implementation of
|