Packageorg.as3collections.lists
Classpublic class SortedArrayList
InheritanceSortedArrayList Inheritance ArrayList Inheritance AbstractList Inheritance AbstractArrayCollection Inheritance Object
Implements ISortedList

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

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

The user of this list may change their order at any time using the setters comparator and options, or by calling sort or sortOn methods and imposing other arguments to change the sort behaviour.

It's possible to create unique sorted lists, typed sorted lists and even unique typed sorted lists. You just sends the SortedArrayList object to the wrappers UniqueSortedList or TypedSortedList or uses the ListUtil.getUniqueSortedList, ListUtil.getTypedSortedList or ListUtil.getUniqueTypedSortedList.

This documentation is partially based in the Java Collections Framework JavaDoc documentation. For further information see Java Collections Framework

View the examples

See also

ISortedList
ArrayList
TypedSortedList
UniqueSortedList
ListUtil.getUniqueSortedList()
ListUtil.getTypedSortedList()
ListUtil.getUniqueTypedSortedList()

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.
SortedArrayList
 InheritedmodCount : int
[read-only] The number of times this list has been structurally modified.
AbstractList
  options : uint
Defines the options to be used automatically to sort.
SortedArrayList
Public Methods
 MethodDefined By
  
SortedArrayList(source:Array = null, comparator:IComparator = null, options:uint = 0)
Constructor, creates a new SortedArrayList object.
SortedArrayList
 Inherited
add(element:*):Boolean
[override] Appends the specified element to the end of this list (optional operation).
AbstractList
 Inherited
addAll(collection:ICollection):Boolean
[override] Adds all of the elements in the specified collection to this list (optional operation).
AbstractList
 Inherited
addAllAt(index:int, collection:ICollection):Boolean
Inserts all of the elements in the specified collection into this list at the specified position (optional operation).
AbstractList
  
addAt(index:int, element:*):Boolean
[override] Inserts the specified element at the specified position in this list.
SortedArrayList
 Inherited
clear():void
[override] Removes all of the elements from this list.
ArrayList
  
clone():*
[override] Creates and return a new SortedArrayList object containing all elements in this list (in the same order).
SortedArrayList
 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
ensureCapacity(minCapacity:int):void
Increases the capacity of this ArrayList instance, if necessary, to ensure that it can hold at least the number of elements specified by the minCapacity argument.
ArrayList
  
equals(other:*):Boolean
[override] Performs an arbitrary, specific evaluation of equality between this object and the other object.
SortedArrayList
 Inherited
getAt(index:int):*
Returns the element at the specified position in this list.
AbstractList
 Inherited
indexOf(element:*, fromIndex:int = 0):int
Returns the index of the first occurrence of the specified element in this list, or -1 if this list does not contain the element.
AbstractList
 Inherited
isEmpty():Boolean
Returns true if this collection contains no elements.
AbstractArrayCollection
 Inherited
iterator():IIterator
[override] Returns an iterator over a set of elements.
ArrayList
 Inherited
lastIndexOf(element:*, fromIndex:int = 0x7fffffff):int
Returns the index of the last occurrence of the specified element in this list, or -1 if this list does not contain the element.
AbstractList
 Inherited
listIterator(index:int = 0):IListIterator
[override] Returns a list iterator of the elements in this list (in proper sequence), starting at the specified position in this list.
ArrayList
 Inherited
remove(o:*):Boolean
Removes a single instance (only one occurrence) of the specified object from this collection, if it is present (optional operation).
AbstractArrayCollection
 Inherited
removeAll(collection:ICollection):Boolean
Removes all of this collection's elements that are also contained in the specified collection (optional operation).
AbstractArrayCollection
 Inherited
removeAt(index:int):*
[override] Removes the element at the specified position in this list.
ArrayList
 Inherited
removeRange(fromIndex:int, toIndex:int):ICollection
[override] Removes all of the elements whose index is between fromIndex, inclusive, and toIndex, exclusive.
ArrayList
 Inherited
retainAll(collection:ICollection):Boolean
Retains only the elements in this collection that are contained in the specified collection (optional operation).
AbstractArrayCollection
  
reverse():void
[override] Reverses the list.
SortedArrayList
  
setAt(index:int, element:*):*
[override] Replaces the element at the specified position in this list with the specified element.
SortedArrayList
 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.
SortedArrayList
  
sortOn(fieldName:*, options:* = null):Array
Sorts the elements in an array according to one or more fields in the array.
SortedArrayList
  
subList(fromIndex:int, toIndex:int):IList
[override] Returns a new SortedArrayList that is a view of the portion of this SortedArrayList between the specified fromIndex, inclusive, and toIndex, exclusive.
SortedArrayList
 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 list 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 list is automatically reordered with the new value.


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

Constructor, creates a new SortedArrayList object.

Parameters
source:Array (default = null) — an array to fill the list.
 
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
addAt()method
override public function addAt(index:int, element:*):Boolean

Inserts the specified element at the specified position in this list. Shifts the element currently at that position (if any) and any subsequent elements to the right (adds one to their indices).

Before returning, the list is reordered, so there's no guarantee that the element remains in the inserted position.

Parameters

index:int — index at which the specified element is to be inserted.
 
element:* — the element to be added.

Returns
Boolean — true if this list changed as a result of the call.

Throws
IndexOutOfBoundsError — if the index is out of range (index < 0 || index > size()).
clone()method 
override public function clone():*

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

Returns
* — a new SortedArrayList object containing all elements in this list (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 list. So, for two lists 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.
reverse()method 
override public function reverse():void

Reverses the list. When this method is called, the list is reversed and an internal status reversed (true/false) is stored. When the list is automatically ordered by any change, if status is reversed = true, the list remains reversed. Thus, after any change it will remain sorted and reversed as it was before the change. A second call to reverse will reverse the list again and change the status to reversed = false. The default value is false. This condition is not used in the user call to sort or sortOn methods (i.e. even if status is reversed = true it will not be used automatically). So if is desirable to reverse the list after directly call sort or sortOn methods, reverse method should be explicitly called after that.

setAt()method 
override public function setAt(index:int, element:*):*

Replaces the element at the specified position in this list with the specified element.

Before returning, the list is reordered.

Parameters

index:int — index of the element to replace.
 
element:* — element to be stored at the specified position.

Returns
* — the element previously at the specified position.

Throws
IndexOutOfBoundsError — if the index is out of range (index < 0 || index >= size()).
sort()method 
public function sort(compare:Function = null, options:uint = 0):Array

Sorts the objects within this class.

Parameters

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

Returns
Array —

See also

org.as3coreaddendum.system.ISortable
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()
subList()method 
override public function subList(fromIndex:int, toIndex:int):IList

Returns a new SortedArrayList that is a view of the portion of this SortedArrayList between the specified fromIndex, inclusive, and toIndex, exclusive.

Modifications in the returned SortedArrayList object doesn't affect this list.

Parameters

fromIndex:int — the index to start retrieving elements (inclusive).
 
toIndex:int — the index to stop retrieving elements (exclusive).

Returns
IList — a new SortedArrayList that is a view of the specified range within this list.

Throws
IndexOutOfBoundsError — if fromIndex or toIndex is out of range (index < 0 || index > size()).
Examples
Example 1 
     import org.as3collections.ISortedList;
     import org.as3collections.lists.SortedArrayList;
     
     var list1:ISortedList = new SortedArrayList([3, 5, 1, 7], null, Array.NUMERIC | Array.DESCENDING);
     
     list1                       // [7,5,3,1]
     list1.size()                // 4
     
     list1.addAt(3, 8)           // true
     list1                       // [8,7,5,3,1]
     list1.size()                // 5
     
     list1.add(4)                // true
     list1                       // [8,7,5,4,3,1]
     list1.size()                // 6
     
     list1.add(5)                // true
     list1                       // [8,7,5,5,4,3,1]
     list1.size()                // 7
     
     list1.sort(null, Array.NUMERIC)
     list1                       // [1,3,4,5,5,7,8]
     
     list1.add(2)                // true
     list1                       // [8,7,5,5,4,3,2,1]
     list1.size()                // 8
     
     list1.reverse()
     list1                       // [1,2,3,4,5,5,7,8]
     
     list1.add(6)                // true
     list1                       // [1,2,3,4,5,5,6,7,8]
     
     list1.add(9)                // true
     list1                       // [1,2,3,4,5,5,6,7,8,9]
     
     list1.reverse()
     list1                       // [9,8,7,6,5,5,4,3,2,1]
     
     list1.add(10)               // true
     list1                       // [10,9,8,7,6,5,5,4,3,2,1]
     
     list1.add(-1)               // true
     list1                       // [10,9,8,7,6,5,5,4,3,2,1,-1]
     
     //list1.add("c")            // TypeError: Error #1034: Falha de coerção de tipo: não é possível converter "c" em Number.
Example 2 
     import org.as3collections.ISortedList;
     import org.as3collections.lists.SortedArrayList;
     import org.as3coreaddendum.system.comparators.AlphabeticComparator;
     
     var comparator:AlphabeticComparator = new AlphabeticComparator(false);
     var arr:Array = ["c", "a", "d", "b"];
     var list1:ISortedList = new SortedArrayList(arr, comparator);
     
     list1                              // [a,b,c,f]
     list1.size()                       // 4
     
     list1.addAt(1, "x")                // true
     list1                              // [a,b,c,f,x]
     list1.size()                       // 5
     
     list1.add("d")                     // true
     list1                              // [a,b,c,d,f,x]
     list1.size()                       // 6
     
     list1.add("d")                     // true
     list1                              // [a,b,c,d,d,f,x]
     list1.size()                       // 7
     
     list1.sort()
     list1                              // [a,b,c,d,d,f,x]
     
     list1.add(2)                       // true
     list1                              // [2,a,b,c,d,d,f,x]
     list1.size()                       // 8
Example 3 
     import org.as3collections.ISortedList;
     import org.as3collections.lists.SortedArrayList;
     
     var arr:Array = [5, 1, 100, 10, 99];
     var list1:ISortedList = new SortedArrayList(arr); // default behavior of the sort method
     
     list1                       // [1,10,100,5,99]
     list1.size()                // 5
     
     list1.add(50)               // true
     list1                       // [1,10,100,5,50,99]
     list1.size()                // 6
     
     list1.sort(null, Array.NUMERIC)
     list1                       // [1,5,10,50,99,100]
     
     list1.add(200)              // true
     list1                       // [1,10,100,200,5,50,99]
     list1.size()                // 7
Example 4 - Unique Sorted List 
     import org.as3collections.ISortedList;
     import org.as3collections.lists.SortedArrayList;
     import org.as3collections.utils.ListUtil;
     
     var arr:Array = [5, 1, 100, 10, 99, 5];
     
     var l1:ISortedList = new SortedArrayList(arr, null, Array.NUMERIC | Array.DESCENDING);
     
     var list1:ISortedList = ListUtil.getUniqueSortedList(l1);  // return type is UniqueSortedList
     
     list1                 // [100,99,10,5,1]
     list1.size()          // 5
     
     list1.add(50)         // true
     list1                 // [100,99,50,10,5,1]
     list1.size()          // 6
     
     list1.add(10)         // false
     list1                 // [100,99,50,10,5,1]
     list1.size()          // 6
Example 5 - Typed Sorted List 
     import org.as3collections.ISortedList;
     import org.as3collections.lists.SortedArrayList;
     import org.as3collections.utils.ListUtil;
     
     var arr:Array = [5, 1, 100, 10, 99, 5];
     
     var l1:ISortedList = new SortedArrayList(arr, null, Array.NUMERIC | Array.DESCENDING);
     
     var list1:ISortedList = ListUtil.getTypedSortedList(l1);  // return type is TypedSortedList
     
     list1                 // [100,99,10,5,5,1]
     list1.size()          // 6
     
     list1.add(50)         // true
     list1                 // [100,99,50,10,5,5,1]
     list1.size()          // 7
     
     list1.add(10)         // true
     list1                 // [100,99,50,10,10,5,5,1]
     list1.size()          // 8
     
     list1.add("a")        // ClassCastError: Invalid element type. element: a | type: String | expected type: int
Example 6 - Unique Typed Sorted List 
     import org.as3collections.ISortedList;
     import org.as3collections.lists.SortedArrayList;
     import org.as3collections.utils.ListUtil;
     
     var arr:Array = [5, 1, 100, 10, 99, 5];
     
     var l1:ISortedList = new SortedArrayList(arr, null, Array.NUMERIC | Array.DESCENDING);
     
     var list1:ISortedList = ListUtil.getUniqueTypedSortedList(l1);  // return type is TypedSortedList
     
     list1                 // [100,99,10,5,1]
     list1.size()          // 5
     
     list1.add(50)         // true
     list1                 // [100,99,50,10,5,1]
     list1.size()          // 6
     
     list1.add(10)         // false
     list1                 // [100,99,50,10,5,1]
     list1.size()          // 6
     
     list1.add("a")        // ClassCastError: Invalid element type. element: a | type: String | expected type: int



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

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