Delicious Facebook Google Bookmarks Twitter

›Projects›AS3Commons Collections›Documentation
  1. Quick Overview
  2. Examples
  3. Differences to the Lite Collections Fx
  4. Getting started
  5. Resources
  6. Comments (9)
  7. Leave a Comment

Documentation

Welcome to the AS3Commons Collections framework – the successor of the Lite Collections Fx project.

Quick Overview

The framework currently contains 10 collections of wich 8 are available as well in a bindable (event dispatching) version. A bindable collection broadcasts change notifications after any modification of its content (add, remove, reorder, empty).

The collections can be classified by their access type (list = index, set = instance, map = key), by their order (unorderd, insertion order, sort order), by their permission of multiple entries of a single instance or by their realisation.

Collection Characteristics Realisation
Access Order Multiplicity
ArrayList index,
sequential		 insertion order multiple items Array
SortedList index,
sequential		 sort order multiple items Array
Set instance,
sequential		 unordered unique items Dictionary
LinkedSet instance,
sequential		 insertion order unique items Dictionary + LinkedList
SortedSet instance,
sequential		 sort order unique items,
multiple equal items		 Dictionary + Tree
Map key,
sequential		 unordered unique keys,
multiple items		 Dictionary
LinkedMap key,
sequential		 insertion order unique keys,
multiple items		 Dictionary + LinkedList
SortedMap key,
sequential		 sort order unique keys,
multiple items		 Dictionary + Tree
LinkedList sequential insertion order multiple items LinkedList
Treap instance,
sequential		 sort order unique items Tree

Each collection is equipped with a feature rich iterator that enables bidirectional navigation and insertion, replacement or removal within the iteration loop. The library further includes 5 special iterators:

  • ArrayIterator
  • CollectionFilterIterator
  • FilterIterator
  • RecursiveIterator
  • RecursiveFilterIterator

Note, all collections, iterators and interfaces are detailed described in the APIDoc.

Examples

The APIDoc consists of a large number of examples of all collections (bindable or not bindable). All those examples are also committed to the Git repository and can be found here: Browse examples.

SortedList example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
package {
  import org.as3commons.collections.SortedList;
  import org.as3commons.collections.framework.ICollectionIterator;
  import org.as3commons.collections.framework.IIterator;
  import org.as3commons.collections.framework.IListIterator;
  import org.as3commons.collections.utils.StringComparator;
  import flash.display.Sprite;

  public class SortedListExample extends Sprite {

    public function SortedListExample() {
      var list : SortedList = new SortedList(new StringComparator());
     
      // Add

      list.add("d");
      list.add("a");
      list.add("a");
      list.add("f");
      list.add("c");
      list.add("b");
      list.add("a");
      list.add("c");
      trace (list.toArray()); // a,a,a,b,c,c,d,f

      list.array = ["d", "a", "a", "f", "c", "b", "a", "c"];
      trace (list.toArray()); // a,a,a,b,c,c,d,f

      // Inspection

      trace (list.first); // a
      trace (list.last); // f

      trace (list.hasEqual("a")); // true
      trace (list.hasEqual("e")); // false
      trace (list.equalIndices("a")); // 0,1,2

      trace (list.lesserIndex("a")); // -1
      trace (list.lesserIndex("c")); // 3
     
      trace (list.higherIndex("c")); // 6
      trace (list.higherIndex("f")); // -1
      trace (list.higherIndex("x")); // -1

      // Iterator
     
      var iterator : IIterator = list.iterator();
      trace (iterator is IIterator); // true
      trace (iterator is ICollectionIterator); // true
      trace (iterator is IListIterator); // true
     
      while (iterator.hasNext()) {
        trace (iterator.next()); // a,a,a,b,c,c,d,f
      }
    }
  }
}

Filter iterator example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
package {
  import org.as3commons.collections.ArrayList;
  import org.as3commons.collections.framework.IIterator;
  import org.as3commons.collections.iterators.FilterIterator;
  import flash.display.Sprite;

  public class FilterIteratorExample extends Sprite {

    public function FilterIteratorExample() {
      var list : ArrayList = new ArrayList();
      var iterator : IIterator;

      list.array = [1, 2, 3, 4, 5, 6];
      iterator = new FilterIterator(list, evenFilter);
      while (iterator.hasNext()) {
        trace (iterator.next()); // 2, 4, 6
      }
    }

    private function evenFilter(item : *) : Boolean {
      // lets pass only even numbers
      return item % 2 == 0;
    }
  }
}

Bindable LinkedSet example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
package {
  import org.as3commons.collections.framework.ISetIterator;
  import org.as3commons.collections.fx.LinkedSetFx;
  import org.as3commons.collections.fx.events.CollectionEvent;
  import org.as3commons.collections.fx.events.SetEvent;
  import org.as3commons.collections.utils.NumericComparator;
  import flash.display.Sprite;

  public class LinkedSetFxExample extends Sprite {

    public function LinkedSetFxExample() {
      var theSet : LinkedSetFx = new LinkedSetFx();
      theSet.addEventListener(CollectionEvent.COLLECTION_CHANGED, changedHandler);
     
      theSet.add(1);
      theSet.add(3);
      theSet.add(2);
      theSet.add(2); // no event (2 already contained)
     
      theSet.addFirst(4);
      theSet.addLast(5);

      theSet.addBefore(2, 6);
      theSet.addAfter(2, 7);

      theSet.replace(3, 8);
      theSet.replace(1, 9);

      theSet.removeFirst();
      theSet.removeLast();
      theSet.remove(8);
      theSet.remove(6);
      theSet.remove(10); // no event (10 not contained)

      theSet.reverse();
      theSet.sort(new NumericComparator());

      theSet.clear();

      // [1] added                         [1]
      // [3] added after 1                 [1 3]
      // [2] added after 3                 [1 3 2]
      // [4] added before 1                [4 1 3 2]
      // [5] added after 2                 [4 1 3 2 5]
      // [6] added after 3 before 2        [4 1 3 6 2 5]
      // [7] added after 2 before 5        [4 1 3 6 2 7 5]
      // [8] replaced after 1 before 6     [4 1 8 6 2 7 5]
      // [9] replaced after 4 before 8     [4 9 8 6 2 7 5]
      // [4] removed before 9              [9 8 6 2 7 5]
      // [5] removed after 7               [9 8 6 2 7]
      // [8] removed after 9 before 6      [9 6 2 7]
      // [6] removed after 9 before 2      [9 2 7]
      // Reset                             [7 2 9]
      // Reset                             [2 7 9]
      // Reset                             []
    }

    private function changedHandler(e : SetEvent) : void {
      var info : String = "";
      var iterator : ISetIterator;
     
      switch (e.kind) {
        case CollectionEvent.ITEM_ADDED:
          info += "[" + e.item + "] added";

          iterator = e.iterator() as ISetIterator;
          if (iterator.previousItem !== undefined) info += " after " + iterator.previousItem;
          iterator.next();
          if (iterator.nextItem !== undefined) info += " before " + iterator.nextItem;
          break;

        case CollectionEvent.ITEM_REMOVED:
          info += "[" + e.item + "] removed";

          iterator = e.iterator() as ISetIterator;
          if (iterator.previousItem !== undefined) info += " after " + iterator.previousItem;
          if (iterator.nextItem !== undefined) info += " before " + iterator.nextItem;
          break;

        case CollectionEvent.ITEM_REPLACED:
          info += "[" + e.item + "] replaced";

          iterator = e.iterator() as ISetIterator;
          if (iterator.previousItem !== undefined) info += " after " + iterator.previousItem;
          iterator.next();
          if (iterator.nextItem !== undefined) info += " before " + iterator.nextItem;
          break;

        case CollectionEvent.RESET:
          info += ("Reset");
          break;
      }
     
      for (var i : uint = info.length; i < 34; i++) info += " ";
      info += "[" + e.set.toArray().join(" ") + "]";
      trace (info);
    }
  }
}

Differences to the Lite Collections Fx

Architectural changes

A list is now considered as a collection that provides (constant time) index access to its items. Therefore the LinkedList does not implement the IList interface any longer.

List, sets and maps are now considered as “random access collections” – providing a unique accessor to their items (index, item by instance, key). Therefore all lists, sets and maps have now a bindable version.

Performance increasement

The performance has been increased by a factor of 2 to 4 (partially even up to 20). A performance testing harness and all testing results will be released in the next time.

Iterator concept improvements

The iterators now have the ability to add or remove items during the iteration. The pointers (special iterators for linked collections) of the Lite Collections have been removed.

More concisely method names

All xxxItem() methods have lost their “item”. getItemAt() is now itemAt(), getFirstItem() is now simply first and so on.

Documentation

The APIDoc has been largely extended and contains all information that is necessary to work with the collections.

Getting started

There is not much to get the collections running.

  1. Download SWC, ZIP or clone the GitHub branch.
  2. Link or copy the sources into your project.
  3. Import the collection classes and write code.
  4. Examples.

Resources



9 Comments

  1. jason

    17. August 2010

    nice work, very useful for me, thanks

  2. Ruslan Lobachev

    15. November 2010

    Hello!
    First of all, i’m very appreciated your collections library.
    But why you aren’t based some of collection on Proxy class? I feel lack of [] operator, native for … in loops and delete.

  3. Jens Struwe

    15. November 2010

    It is not possible to feed a Proxy with complex keys:

    proxy[complexObj] = value

    I have been following an all-or-nothing-strategy, so neither
    of the collections is equipped with those short accessors.

  4. Ruslan Lobachev

    15. November 2010

    What do you mean by “complex keys”? Object keys same as in native Dictionary class? Proxy can support such keys, so you can implement Map based on Proxy, for example.

    Maybe I misunderstood you

  5. Jens Struwe

    15. November 2010

    Could you post example code or a link to further information?

  6. Ruslan Lobachev

    15. November 2010

    Sorry, my understanding of Proxy was bad.

    Yes, it can take object keys. But inside of Proxy any key stored as string obtained by keyObject.toString(). So two different proxy[new Object()] keys will be treated as the same key

  7. Ruslan Lobachev

    15. November 2010

    Now I completely agree with you :)

  8. Jens Struwe

    15. November 2010

    We would need a kind of hashing to be able to distinguish
    different object instances.

    proxy[object1.hashCode()] = object1

    Anyway, this might be a promising approach but it would
    add a lot of requirements to the use of the framework.
    And we are not building space shuttle software, we are
    poor frontend developers and we want to have it simple.

    ;-)

  9. ActionScript Community | Pearltrees

    17. März 2012

    [...] Documentation ‹ AS3Commons Collections ‹ Projects ‹ Russischer Bär Open Source Flash CollectionFilterIterator FilterIterator ArrayIterator RecursiveIterator [...]

Leave a Comment

You have a question or have experienced an issue? Please post it in the forum: http://sibirjak.tenderapp.com/ in order to make the discussion available at a more central place.