Packageorg.as3collections.queues
Classpublic class PriorityQueue
InheritancePriorityQueue Inheritance SortedQueue Inheritance LinearQueue Inheritance AbstractQueue Inheritance AbstractArrayCollection Inheritance Object

This queue uses a org.as3coreaddendum.system.comparators.PriorityComparator object to sort the elements. All elements must implement the org.as3coreaddendum.system.IPriority interface, otherwise a org.as3coreaddendum.errors.ClassCastError is thrown.

This queue also adds an event listener on elements to org.as3coreaddendum.events.PriorityEvent (if elements implement flash.events.IEventDispatcher). Thus this queue keeps itself automatically sorted if its elements dispatch a org.as3coreaddendum.events.PriorityEvent when its priority changes.

View the examples

See also

org.as3coreaddendum.system.IPriority
org.as3coreaddendum.events.PriorityEvent


Public Properties
 PropertyDefined By
 InheritedallEquatable : Boolean
[read-only] Indicates whether all elements in this collection implement the interface org.as3coreaddendum.system.IEquatable.
AbstractArrayCollection
  comparator : IComparator
[override] PriorityQueue does not allow changing its comparator object.
PriorityQueue
  options : uint
[override] PriorityQueue does not allow changing its options.
PriorityQueue
Public Methods
 MethodDefined By
  
PriorityQueue(source:Array = null)
Constructor, creates a new PriorityQueue object.
PriorityQueue
  
add(element:*):Boolean
[override] Inserts the specified element into this queue if it is possible to do so immediately without violating restrictions.
PriorityQueue
 Inherited
addAll(collection:ICollection):Boolean
Adds all of the elements in the specified collection to this collection (optional operation).
AbstractArrayCollection
 Inherited
clear():void
[override] Removes all of the elements from this queue.
LinearQueue
  
clone():*
[override] Creates and return a new PriorityQueue object containing all elements in this queue (in the same order).
PriorityQueue
 Inherited
contains(o:*):Boolean
Returns true if this collection contains the specified object.
AbstractArrayCollection
 Inherited
containsAll(collection:ICollection):Boolean
Returns true if this collection contains all of the elements in the specified collection.
AbstractArrayCollection
 Inherited
Retrieves and removes the head of this queue.
AbstractQueue
 Inherited
Retrieves, but does not remove, the head of this queue.
AbstractQueue
 Inherited
equals(other:*):Boolean
[override] Performs an arbitrary, specific evaluation of equality between this object and the other object.
SortedQueue
 Inherited
isEmpty():Boolean
Returns true if this collection contains no elements.
AbstractArrayCollection
 Inherited
[override] Returns an iterator over a set of elements.
LinearQueue
  
offer(element:*):Boolean
[override] Inserts the specified element into this queue if it is possible to do so immediately without violating restrictions.
PriorityQueue
 Inherited
peek():*
[override] Retrieves, but does not remove, the head of this queue, or returns null if this queue is empty.
LinearQueue
 Inherited
poll():*
[override] Retrieves and removes the head of this queue, or returns null if this queue is empty.
SortedQueue
 Inherited
remove(o:*):Boolean
[override] Removes a single instance (only one occurrence) of the specified object from this queue, if it is present.
SortedQueue
 Inherited
removeAll(collection:ICollection):Boolean
[override] Removes all of this queue's elements that are also contained in the specified collection.
SortedQueue
 Inherited
retainAll(collection:ICollection):Boolean
Retains only the elements in this collection that are contained in the specified collection (optional operation).
AbstractArrayCollection
 Inherited
size():int
Returns the number of elements in this collection.
AbstractArrayCollection
 Inherited
sort(compare:Function = null, options:uint = 0):Array
Sorts the objects within this class.
SortedQueue
 Inherited
sortOn(fieldName:*, options:* = null):Array
Sorts the elements in an array according to one or more fields in the array.
SortedQueue
 Inherited
toArray():Array
Returns an array containing all of the elements in this collection.
AbstractArrayCollection
 Inherited
toString():String
Returns the string representation of this instance.
AbstractArrayCollection
Property Detail
comparatorproperty
comparator:IComparator[override]

PriorityQueue does not allow changing its comparator object.

PriorityQueue was designed to be used exclusively with its default comparator object. If you want to change the comparator object using this setter, consider using SortedQueue class instead.

If this setter is used an IllegalOperationError is thrown.


Implementation
    public function get comparator():IComparator
    public function set comparator(value:IComparator):void
optionsproperty 
options:uint[override]

PriorityQueue does not allow changing its options.

PriorityQueue was designed to be used exclusively with its default options. If you want to change the options using this setter, consider using SortedQueue class instead.

If this setter is used an IllegalOperationError is thrown.


Implementation
    public function get options():uint
    public function set options(value:uint):void
Constructor Detail
PriorityQueue()Constructor
public function PriorityQueue(source:Array = null)

Constructor, creates a new PriorityQueue object.

Parameters
source:Array (default = null) — an array to fill the queue.

Throws
org.as3coreaddendum.errors:ClassCastError — if one or more elements in the source argument do not implement the org.as3coreaddendum.system.IPriority interface.
Method Detail
add()method
override public function add(element:*):Boolean

Inserts the specified element into this queue if it is possible to do so immediately without violating restrictions. This method differs from offer only in that it throws an error if the element cannot be inserted.

This implementation returns the result of offer unless the element cannot be inserted.

This implementation only allow elements that implements the org.as3coreaddendum.system.IPriority interface. A org.as3coreaddendum.errors.ClassCastError is thrown if the element does not implements this interface.

Parameters

element:*

Returns
Booleantrue if this queue changed as a result of the call.

Throws
ArgumentError — if the specified element is null.
 
org.as3coreaddendum.errors:ClassCastError — if the element does not implements the org.as3coreaddendum.system.IPriority interface.
 
flash.errors:IllegalOperationError — if the specified element cannot be inserted.
clone()method 
override public function clone():*

Creates and return a new PriorityQueue object containing all elements in this queue (in the same order).

Returns
* — a new PriorityQueue object containing all elements in this queue (in the same order).
offer()method 
override public function offer(element:*):Boolean

Inserts the specified element into this queue if it is possible to do so immediately without violating restrictions. When using a restricted queue (like TypedQueue and UniqueQueue), this method is generally preferable to add, which can fail to insert an element only by throwing an error.

This implementation only allow elements that implements the org.as3coreaddendum.system.IPriority interface. If the element does not implements this interface the method returns false.

Before returning, the queue is reordered.

Parameters

element:* — the element to add.

Returns
Booleantrue if the element was added to this queue, else false.
Examples
     package test
     {
         import org.as3coreaddendum.system.IPriority;
     
         public class TestPriority extends EventDispatcher implements IPriority
         {
             private var _name:String;
             private var _priority:int;
     
             public function get priority(): int { return _priority; }
     
             public function set priority(value : int) : void
             {
                 _priority = value;
                 dispatchEvent(new PriorityEvent(PriorityEvent.CHANGED, _priority));
             }
     
             public function TestPriority(name:String, priority:int)
             {
                 _name = name;
                 _priority = priority;
             }
     
             public function toString(): String
             {
                 return "[TestPriority " + _name + "]";
             }
         }
     }
     
     import org.as3collections.ISortedQueue;
     import org.as3collections.queues.PriorityQueue;
     import test.TestPriority;
     
     var queue1:ISortedQueue = new PriorityQueue();
     
     var o1:TestPriority = new TestPriority("o1", 1);
     var o2:TestPriority = new TestPriority("o2", 2);
     var o3:TestPriority = new TestPriority("o3", 3);
     var o4:TestPriority = new TestPriority("o4", 4);
     
     queue1.offer(o2)            // true
     queue1                      // [[TestPriority o2]]
     queue1.size()               // 1
     
     queue1.offer(o3)            // true
     queue1                      // [[TestPriority o3],[TestPriority o2]]
     queue1.size()               // 2
     
     queue1.offer(o2)            // true
     queue1                      // [[TestPriority o3],[TestPriority o2],[TestPriority o2]]
     
     queue1.offer(o1)            // true
     queue1                      // [[TestPriority o3],[TestPriority o2],[TestPriority o2],[TestPriority o1]]
     
     queue1.offer(o4)            // true
     queue1                      // [[TestPriority o4],[TestPriority o3],[TestPriority o2],[TestPriority o2],[TestPriority o1]]
     
     queue1.offer(1)             // false
     queue1                      // [[TestPriority o4],[TestPriority o3],[TestPriority o2],[TestPriority o2],[TestPriority o1]]
     
     queue1.add(1)               // ClassCastError: The element must implement the 'org.as3coreaddendum.system.IPriority' interface. Type received: int