Class: SC.Set


Extends SC.Copyable, SC.Enumerable, SC.Freezable, SC.Observable.

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 gaurantee as to their order.

Whether or not property observing is enabled, sets offer very powerful notifications of items being added and removed, through the addSetObserver and removeSetObserver methods; this can be very useful, for instance, for filtering or mapping sets.

Note that SC.Set is a primitive object, like an array. It does implement limited key-value observing support, but it does not extend from SC.Object so you should not subclass it.

Creating a Set

You can create a set like you would most objects using SC.Set.create(). 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 SC.Set#clone().

// creates a new empty set
  var foundNames = SC.Set.create();

  // creates a set with four names in it.
  var names = SC.Set.create(["Charles", "Tom", "Juan", "Alex"]);

  // creates a copy of the names set.
  var namesCopy = SC.Set.create(names);

  // same as above.
  var anotherNamesCopy = names.clone();

Adding/Removing Objects

You generally add or remove objects from a set using add() or remove(). You can add any type of object including primitives such as numbers, strings, and booleans.

Note that objects can only exist one time in a set. If you call add() 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 that you cannot add/remove null or undefined to a set. Any attempt to do so will be ignored.

In addition to add/remove you can also call push()/pop(). Push behaves just like add() but pop(), unlike 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 SC.Set#contains(). This method tests for the object's hash, which is generally the same as the object's guid; however, if you implement the hash() method on the object, it will use the return value from that method instead.

Observing changes

When using SC.Set (rather than SC.CoreSet), you can observe the "[]" property to be alerted whenever the content changes.

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.

SC.Set and SC.CoreSet both offer another method of being observed: addSetObserver and removeSetObserver. These take a single parameter: an object which implements didAddItem(set, item) and didRemoveItem(set, item).

Whenever an item is added or removed from the set, all objects in the set (a SC.CoreSet, actually) of observing objects will be alerted appropriately.

BIG WARNING

SetObservers are not intended to be used "_creatively_"; for instance, do not expect to be alerted immediately to any changes. *While the notifications are currently sent out immediately, if we find a fast way to send them at end of run loop, we most likely will do so.*

Defined in: set.js

Since:
SproutCore 1.0

Field Summary

Fields borrowed from SC.Enumerable:
isEnumerable
Fields borrowed from SC.Observable:
isObservable
Fields borrowed from SC.Copyable:
isCopyable
Fields borrowed from SC.Freezable:
isFreezable, isFrozen

Instance Methods

Field Detail

isSet Boolean
Walk like a duck
length Number
This property will change as the number of objects in the set changes.

Instance Method Detail

add(obj)

Call this method to add an object. performs a basic add.

If the object is already in the set it will not be added again.

Parameters:
obj Object
the object to add
Returns:
SC.Set
receiver
addEach(objects)
Add all the items in the passed array or enumerable
Parameters:
objects Array
Returns:
SC.Set
receiver
addSetObserver(setObserver)

Adds a set observers. Set observers must implement two methods:

  • didAddItem(set, item)
  • didRemoveItem(set, item)

Set observers are, in fact, stored in another set (a CoreSet).

Parameters:
setObserver
clear()
Clears the set
Returns:
SC.Set
contains(obj)
Call this method to test for membership.
Parameters:
obj
Returns:
Boolean
copy()
Clones the set into a new set.
Returns:
SC.Set
new copy
create(items)

Creates a new set, with the optional array of items included in the return set.

Parameters:
items SC.Enumerable
items to add
Returns:
SC.Set
destroy()
Return a set to the pool for reallocation.
Returns:
SC.Set
receiver
firstObject()
Returns the first object in the set or null if the set is empty
isEqual(obj)

Returns YES if the passed object is also a set that contains the same objects as the receiver.

Parameters:
obj SC.Set
the other object
Returns:
Boolean
pop()
Removes an arbitrary object from the set and returns it.
Returns:
Object
an object from the set or null
remove(obj)

Removes the object from the set if it is found.

If the object is not in the set, nothing will be changed.

Parameters:
obj Object
the object to remove
Returns:
SC.Set
receiver
removeEach(objects)
Removes all the items in the passed array.
Parameters:
objects Array
Returns:
SC.Set
receiver
removeSetObserver(setObserver)
Removes a set observer.
Parameters:
setObserver
Documentation generated by JsDoc Toolkit 2.4.0 on Wed Apr 08 2015 10:02:21 GMT-0600 (CST)