Packageorg.as3collections.queues
Classpublic class SortedQueue
InheritanceSortedQueue Inheritance LinearQueue Inheritance AbstractQueue Inheritance AbstractArrayCollection Inheritance Object
Implements ISortedQueue
Subclasses IndexQueue, PriorityIndexQueue, PriorityQueue

A queue that provides a total ordering on its elements. The queue is ordered according to the natural ordering of its elements, by a IComparator typically provided at sorted queue creation time, or by the arguments provided to the sort or sortOn methods.

For each change that occurs the queue is automatically ordered using the comparator and options. If none was provided the default behavior of the sort method is used.

The user of this queue may change their order at any time by calling the sort or sortOn method and imposing others arguments to change the sort behaviour.

It's possible to create unique sorted queues, typed sorted queues and even unique typed sorted queues. You just sends the SortedQueue object to the wrappers UniqueQueue or TypedQueue or uses the QueueUtil.getUniqueTypedQueue. But there's a problem here: the return type will be UniqueQueue or TypedQueue. Thus you will can no longer use the sort and sortOn methods directly. The wrapped SortedQueue will be only automatically ordered, with the provided comparator and options constructor's arguments. Check the examples at the bottom of the page.

View the examples


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
Defines the comparator object to be used automatically to sort.
SortedQueue
  options : uint
Defines the options to be used automatically to sort.
SortedQueue
Public Methods
 MethodDefined By
  
SortedQueue(source:Array = null, comparator:IComparator = null, options:uint = 0)
Constructor, creates a new SortedQueue object.
SortedQueue
 Inherited
add(element:*):Boolean
[override] Inserts the specified element into this queue if it is possible to do so immediately without violating restrictions.
AbstractQueue
 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 SortedQueue object containing all elements in this queue (in the same order).
SortedQueue
 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
dequeue():*
Retrieves and removes the head of this queue.
AbstractQueue
 Inherited
element():*
Retrieves, but does not remove, the head of this queue.
AbstractQueue
  
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
iterator():IIterator
[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.
SortedQueue
 Inherited
peek():*
[override] Retrieves, but does not remove, the head of this queue, or returns null if this queue is empty.
LinearQueue
  
poll():*
[override] Retrieves and removes the head of this queue, or returns null if this queue is empty.
SortedQueue
  
remove(o:*):Boolean
[override] Removes a single instance (only one occurrence) of the specified object from this queue, if it is present.
SortedQueue
  
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
  
sort(compare:Function = null, options:uint = 0):Array
Sorts the objects within this class.
SortedQueue
  
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

Defines the comparator object to be used automatically to sort.

If this value change the queue is automatically reordered with the new value.


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

Defines the options to be used automatically to sort.

If this value change the queue is automatically reordered with the new value.


Implementation
    public function get options():uint
    public function set options(value:uint):void
Constructor Detail
SortedQueue()Constructor
public function SortedQueue(source:Array = null, comparator:IComparator = null, options:uint = 0)

Constructor, creates a new SortedQueue object.

Parameters
source:Array (default = null) — an array to fill the queue.
 
comparator:IComparator (default = null) — the comparator object to be used internally to sort.
 
options:uint (default = 0) — the options to be used internally to sort.
Method Detail
clone()method
override public function clone():*

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

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

Performs an arbitrary, specific evaluation of equality between this object and the other object.

This implementation considers two differente objects equal if:

This implementation takes care of the order of the elements in the queue. So, for two queues are equal the order of elements returned by the iterator object must be equal.

Parameters

other:* — the object to be compared for equality.

Returns
Boolean — true if the arbitrary evaluation considers the objects equal.
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.

Before returning, the queue is reordered.

Parameters

element:* — the element to add.

Returns
Boolean — true if the element was added to this queue, else false.
poll()method 
override public function poll():*

Retrieves and removes the head of this queue, or returns null if this queue is empty.

Before returning, the queue is reordered.

Returns
* — the head of this queue, or null if this queue is empty.
remove()method 
override public function remove(o:*):Boolean

Removes a single instance (only one occurrence) of the specified object from this queue, if it is present.

Before returning, the queue is reordered.

Parameters

o:* — the object to be removed from this collection, if present.

Returns
Boolean — true if an object was removed as a result of this call.
removeAll()method 
override public function removeAll(collection:ICollection):Boolean

Removes all of this queue's elements that are also contained in the specified collection. After this call returns, this queue will contain no elements in common with the specified collection.

Before returning, the queue is reordered.

Parameters

collection:ICollection — the collection containing elements to be removed from this queue.

Returns
Boolean — true if this queue changed as a result of the call.
sort()method 
public function sort(compare:Function = null, options:uint = 0):Array

Sorts the objects within this class.

For more info see org.as3coreaddendum.system.ISortable.sort() in the link below.

Parameters

compare:Function (default = null)
 
options:uint (default = 0)

Returns
Array —
sortOn()method 
public function sortOn(fieldName:*, options:* = null):Array

Sorts the elements in an array according to one or more fields in the array.

Consult Array.sortOn in the ActionScript 3.0 Language Reference in the link below for more info.

Parameters

fieldName:*
 
options:* (default = null)

Returns
Array —

See also

http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/Array.html#sortOn()
Examples
     import org.as3collections.ISortedQueue;
     import org.as3collections.queues.SortedQueue;
     
     var queue1:ISortedQueue = new SortedQueue([3, 5, 1, 7], null, Array.NUMERIC | Array.DESCENDING);
     
     queue1                      // [7,5,3,1]
     queue1.size()               // 4
     
     queue1.add(-1)              // true
     queue1                      // [7,5,3,1,-1]
     queue1.size()               // 5
     
     queue1.add(4)               // true
     queue1                      // [7,5,4,3,1,-1]
     queue1.size()               // 6
     
     queue1.add(5)               // true
     queue1                      // [7,5,5,4,3,1,-1]
     queue1.size()               // 7
     
     queue1.poll()               // 7
     queue1                      // [5,5,4,3,1,-1]
     queue1.size()               // 6
     
     queue1.sort(null, Array.NUMERIC)
     queue1                      // [-1,1,3,4,5,5]
     
     queue1.poll()               // -1
     queue1                      // [5,5,4,3,1]
     queue1.size()               // 5
     
     queue1.add(2)               // true
     queue1                      // [5,5,4,3,2,1]
     queue1.size()               // 6
     
     queue1.add(10)              // true
     queue1                      // [10,5,5,4,3,2,1]



Copyright 2010-2011 Flavio Silva - http://flsilva.com

Tue Oct 4 2011, 01:49 PM -03:00