An unordered collection of objects.
A Set works a bit like an array except that its items are not ordered. You can create a set to efficiently test for membership for an object. You can also iterate through a set just like an array, even accessing objects by index, however there is no guarantee as to their order.
All Sets are observable via the Enumerable Observer API - which works on any enumerable object including both Sets and Arrays.
Creating a Set
You can create a set like you would most objects using
new Ember.Set(). Most new sets you create will be empty, but you can
also initialize the set with some content by passing an array or other
enumerable of objects to the constructor.
Finally, you can pass in an existing set and the set will be copied. You
can also create a copy of a set by calling
1 2 3 4 5 6 7 8 9 10 11
// creates a new empty set var foundNames = new Ember.Set(); // creates a set with four names in it. var names = new Ember.Set(["Charles", "Tom", "Juan", "Alex"]); // :P // creates a copy of the names set. var namesCopy = new Ember.Set(names); // same as above. var anotherNamesCopy = names.copy();
You generally add or remove objects from a set using
remove(). You can add any type of object including primitives such as
numbers, strings, and booleans.
Unlike arrays, objects can only exist one time in a set. If you call
on a set with the same object multiple times, the object will only be added
once. Likewise, calling
remove() with the same object multiple times will
remove the object the first time and have no effect on future calls until
you add the object to the set again.
NOTE: You cannot add/remove
undefined to a set. Any attempt to do
so will be ignored.
In addition to add/remove you can also call
pop(). Push behaves
remove() will pick an arbitrary
object, remove it and return it. This is a good way to use a set as a job
queue when you don't care which order the jobs are executed in.
Testing for an Object
To test for an object's presence in a set you simply call
Ember.Set, you can observe the
"" property to be
alerted whenever the content changes. You can also add an enumerable
observer to the set to be notified of specific objects that are added and
removed from the set. See Ember.Enumerable
for more information on enumerables.
This is often unhelpful. If you are filtering sets of objects, for instance, it is very inefficient to re-filter all of the items each time the set changes. It would be better if you could just adjust the filtered set based on what was changed on the original set. The same issue applies to merging sets, as well.
Ember.Set primary implements other mixin APIs. For a complete reference
on the methods you will use with
Ember.Set, please consult these mixins.
The most useful ones will be
Ember.MutableEnumerable which implement most of the common iterator
methods you are used to on Array.
Note that you can also use the
Ember.Set as well. Once a set is frozen it can no longer be
modified. The benefit of this is that when you call
frozenCopy() on it,
Ember will avoid making copies of the set. This allows you to write
code that can know with certainty when the underlying set data will or
will not be modified.
No documented items